Improve external CLI developer experience

Author: tehwave

CHANGELOG.md

@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Guarded raw Quickpay API access.
 - Human-readable output and sanitized machine-readable JSON.
 - Bounded, origin-validated, cycle-safe pagination.
+- Signed callback replay and foreground callback watching for local development.
 - Atomic credential storage with restrictive filesystem permissions.
-- Tracked PHAR distribution with complete source-integrity verification.
+- Generated PHAR release workflow with checksums and provenance attestations.
 - PHP 8.4 and 8.5 CI, PHPStan level 8, Pint, dependency audit, and a 90% coverage gate.

RELEASING.md

@@ -204,7 +204,7 @@ contact Quickpay without a key. After the public package is discoverable, also
 verify:
 
 ```bash
-skills add tehwave/quickpay-cli
+npx skills add tehwave/quickpay-cli
 ```
 
 ## 9. After publication

app/Commands/Api/ApiRequestCommand.php

@@ -20,13 +20,15 @@
  */
 class ApiRequestCommand extends AuthenticatedCommand
 {
-    protected $signature = 'api {method} {path}
-        {--query=*}
-        {--data=*}
-        {--data-json=}
-        {--header=*}
-        {--yes}
-        {--json}';
+    protected $signature = 'api
+        {method : GET, POST, PUT, PATCH, or DELETE}
+        {path : Relative Quickpay API path, for example /payments}
+        {--query=* : Query parameter as key=value; repeatable}
+        {--data=* : JSON request field as key=value; repeatable}
+        {--data-json= : JSON object request body}
+        {--header=* : Additional safe header as name:value; repeatable}
+        {--yes : Skip the interactive confirmation for mutations}
+        {--json : Write machine-readable JSON}';
 
     protected $description = 'Send a request to the Quickpay API';
 

app/Commands/Authentication/AuthCommand.php

@@ -3,6 +3,8 @@
 namespace App\Commands\Authentication;
 
 use App\Console\BaseCommand;
+use App\Console\Output\JsonOutput;
+use App\Credentials\ApiKey;
 use App\Credentials\ApiKeyResolver;
 use App\Credentials\Exceptions\CredentialException;
 use App\Quickpay\AuthenticatedQuickpayFactory;
@@ -11,7 +13,9 @@
 
 class AuthCommand extends BaseCommand
 {
-    protected $signature = 'auth';
+    protected $signature = 'auth
+        {--check : Exit non-zero when no active credential is configured}
+        {--json : Write machine-readable JSON}';
 
     protected $description = 'Show the active Quickpay authentication status';
 
@@ -23,15 +27,19 @@ public function handle(ApiKeyResolver $credentials, AuthenticatedQuickpayFactory
             return $this->failure($exception->getMessage());
         }
 
-        $this->line('Credential source: '.($apiKey?->source() ?? 'none'));
-        $this->line('API base URL: '.QuickpayClient::BASE_URL);
-        $this->line('API version: '.QuickpayClient::API_VERSION);
+        if (! $this->option('json')) {
+            $this->writeHumanStatusHeader($apiKey);
+        }
 
         if ($apiKey === null) {
-            $this->line('Scope: not authenticated');
-            $this->comment('Run quickpay login to store a merchant API key.');
+            if ($this->option('json')) {
+                $this->writeJsonStatus(null, null);
+            } else {
+                $this->line('Scope: not authenticated');
+                $this->comment('Run quickpay login to store a merchant API key.');
+            }
 
-            return self::SUCCESS;
+            return $this->option('check') ? self::FAILURE : self::SUCCESS;
         }
 
         try {
@@ -57,8 +65,30 @@ public function handle(ApiKeyResolver $credentials, AuthenticatedQuickpayFactory
             return $this->failure('Quickpay returned an invalid scope.');
         }
 
-        $this->line("Scope: {$scope}");
+        if ($this->option('json')) {
+            $this->writeJsonStatus($apiKey, $scope);
+        } else {
+            $this->line("Scope: {$scope}");
+        }
 
         return self::SUCCESS;
     }
+
+    private function writeHumanStatusHeader(?ApiKey $apiKey): void
+    {
+        $this->line('Credential source: '.($apiKey?->source() ?? 'none'));
+        $this->line('API base URL: '.QuickpayClient::BASE_URL);
+        $this->line('API version: '.QuickpayClient::API_VERSION);
+    }
+
+    private function writeJsonStatus(?ApiKey $apiKey, ?string $scope): void
+    {
+        $this->getOutput()->write(JsonOutput::value([
+            'authenticated' => $scope !== null,
+            'credential_source' => $apiKey?->source(),
+            'api_base_url' => QuickpayClient::BASE_URL,
+            'api_version' => QuickpayClient::API_VERSION,
+            'scope' => $scope,
+        ], ''));
+    }
 }

app/Commands/Payments/AbstractPaymentMutationCommand.php

@@ -98,12 +98,12 @@ private function writeMutationSummary(
             'Currency' => $payment['currency'] ?? null,
             'State' => $payment['state'] ?? null,
             'Accepted' => $payment['accepted'] ?? null,
-            'Balance' => $payment['balance'] ?? null,
+            'Balance (minor units)' => $payment['balance'] ?? null,
             'Operation' => $this->operation(),
         ];
 
         if ($amount !== null) {
-            $fields['Amount'] = $amount;
+            $fields['Amount (minor units)'] = $amount;
         }
 
         foreach ($fields as $label => $value) {

app/Commands/Payments/CancelPaymentCommand.php

@@ -4,7 +4,12 @@
 
 class CancelPaymentCommand extends AbstractPaymentMutationCommand
 {
-    protected $signature = 'payments:cancel {id} {--synchronized} {--callback-url= : Callback URL for Quickpay servers (not localhost)} {--yes} {--json}';
+    protected $signature = 'payments:cancel
+        {id : Quickpay payment ID}
+        {--synchronized : Request a synchronized Quickpay response}
+        {--callback-url= : Callback URL for Quickpay servers (not localhost)}
+        {--yes : Skip the interactive confirmation}
+        {--json : Write machine-readable JSON}';
 
     protected $description = 'Cancel a Quickpay payment';
 

app/Commands/Payments/CapturePaymentCommand.php

@@ -6,7 +6,13 @@
 
 class CapturePaymentCommand extends AbstractPaymentMutationCommand
 {
-    protected $signature = 'payments:capture {id} {amount} {--synchronized} {--callback-url= : Callback URL for Quickpay servers (not localhost)} {--yes} {--json}';
+    protected $signature = 'payments:capture
+        {id : Quickpay payment ID}
+        {amount : Capture amount as a positive integer in minor units}
+        {--synchronized : Request a synchronized Quickpay response}
+        {--callback-url= : Callback URL for Quickpay servers (not localhost)}
+        {--yes : Skip the interactive confirmation}
+        {--json : Write machine-readable JSON}';
 
     protected $description = 'Capture an authorized Quickpay payment';
 

app/Commands/Payments/CreatePaymentCommand.php

@@ -12,7 +12,11 @@
 
 class CreatePaymentCommand extends AuthenticatedCommand
 {
-    protected $signature = 'payments:create {order-id} {currency=DKK} {--field=*} {--json}';
+    protected $signature = 'payments:create
+        {order-id : Quickpay order ID containing 4-20 characters}
+        {currency=DKK : Three-letter currency code}
+        {--field=* : Additional request field as key=value; repeatable}
+        {--json : Write machine-readable JSON}';
 
     protected $description = 'Create a Quickpay payment';
 

app/Commands/Payments/CreatePaymentLinkCommand.php

@@ -22,15 +22,17 @@ class CreatePaymentLinkCommand extends AuthenticatedCommand
         'payment-methods' => 'payment_methods',
     ];
 
-    protected $signature = 'payments:link {id} {amount}
-        {--continue-url=}
-        {--cancel-url=}
+    protected $signature = 'payments:link
+        {id : Quickpay payment ID}
+        {amount : Link amount as a positive integer in minor units}
+        {--continue-url= : Browser destination after successful payment}
+        {--cancel-url= : Browser destination after cancelled payment}
         {--callback-url= : Callback URL for Quickpay servers (not localhost)}
-        {--language=}
-        {--payment-methods=}
-        {--auto-capture}
-        {--field=*}
-        {--json}';
+        {--language= : Payment-window language}
+        {--payment-methods= : Allowed payment methods}
+        {--auto-capture : Request automatic capture}
+        {--field=* : Additional request field as key=value; repeatable}
+        {--json : Write machine-readable JSON}';
 
     protected $description = 'Create a Quickpay payment link';
 

app/Commands/Payments/GetPaymentCommand.php

@@ -11,7 +11,10 @@
 
 class GetPaymentCommand extends AuthenticatedCommand
 {
-    protected $signature = 'payments:get {id} {--operations-size=} {--json}';
+    protected $signature = 'payments:get
+        {id : Quickpay payment ID}
+        {--operations-size= : Maximum operations included; use 0 to omit them}
+        {--json : Write machine-readable JSON}';
 
     protected $description = 'Get a Quickpay payment';
 
@@ -44,7 +47,7 @@ public function handle(AuthenticatedQuickpayFactory $quickpay, PaymentPresenter
                     $this->newLine();
                     $this->line('Operations');
                     $this->table(
-                        ['ID', 'Type', 'Amount', 'Pending', 'Quickpay status', 'Acquirer status', 'Callback', 'Created'],
+                        ['ID', 'Type', 'Amount (minor units)', 'Pending', 'Quickpay status', 'Acquirer status', 'Callback', 'Created'],
                         $presenter->operations($operations, $apiKey),
                     );
                 }