@agent-cards/checkout 0.3.0 → 0.4.0

package/dist/lifecycle.js

@@ -1,4 +1,4 @@
-import { ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, IntentNotConfirmableError, PaymentOutcomeUnknownError } from './client.js';
+import { ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, CheckoutPreparationError, IntentNotConfirmableError, PaymentOutcomeUnknownError } from './client.js';
 /** Shared by the raw CDP and Playwright transports. No browser ownership or payment execution lives here. */
 export class CheckoutLifecycle {
     options;
@@ -6,18 +6,41 @@ export class CheckoutLifecycle {
     held = false;
     active = false;
     cancelled = false;
+    merchantAborted = false;
     unboundStripeToken = false;
     reconciliation = null;
+    preparationHandler;
+    preparationUsed = false;
     abort = new AbortController();
     constructor(options) {
         this.options = options;
     }
     getState() { return { ...this.state }; }
+    setPreparationHandler(handler) { this.preparationHandler = handler; }
+    prepare(options) {
+        if (!this.preparationHandler)
+            return Promise.reject(new CheckoutPreparationError(null, 'transport_unavailable'));
+        return this.preparationHandler(options);
+    }
+    preparing() {
+        this.preparationUsed = true;
+        this.set({ status: 'awaiting_approval', authorizationId: null });
+    }
+    preparationCreated(preparationId) { this.set({ ...this.state, preparationId }); }
+    prepared(preparation) {
+        this.set({ status: 'ready_to_submit', authorizationId: null, preparationId: preparation.id });
+    }
+    preparationFailed(error) {
+        this.held = true;
+        if (this.cancelled)
+            return;
+        this.set({ ...this.state, status: error.reason === 'expired' ? 'timed_out' : error.reason === 'cancelled' ? 'cancelled' : 'failed', reason: error.reason });
+    }
     isBlocked() { return this.held || this.cancelled; }
     isCancelled() { return this.cancelled; }
     begin() {
         this.active = true;
-        this.set({ status: 'awaiting_approval', authorizationId: null });
+        this.set({ status: 'awaiting_approval', authorizationId: null, ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
     }
     end() { this.active = false; }
     set(state) {
@@ -46,6 +69,12 @@ export class CheckoutLifecycle {
         this.abort.abort();
         this.set({ ...this.state, status: this.active || this.state.authorizationId ? 'outcome_unknown' : 'cancelled', reason: 'local_cancel' });
     }
+    /** The exact browser request is gone; a late approval cannot reopen it. */
+    merchantRequestAborted() {
+        this.merchantAborted = true;
+        this.held = true;
+        this.set({ ...this.state, status: 'outcome_unknown', reason: 'merchant_request_aborted' });
+    }
     unsupported() {
         this.held = true;
         if (this.state.authorizationId)
@@ -71,14 +100,21 @@ export class CheckoutLifecycle {
         }
     }
     handedOff(replay) {
+        if (this.merchantAborted)
+            return;
         const mismatch = (!replay.mode || replay.mode === 'token') && replay.amountVerified === false;
         this.held = !!this.options.requireMerchantResult || replay.mode === 'hosted_form' || mismatch || this.unboundStripeToken;
         this.set({ status: 'awaiting_merchant', authorizationId: replay.authorizationId, mode: replay.mode ?? 'token',
+            ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}),
             ...(mismatch ? { reason: 'charged_amount_mismatch' } : this.unboundStripeToken ? { reason: 'stripe_tokenization_unbound' } : {}) });
     }
     failed(error, handoffStarted = false) {
         if (this.cancelled)
             return;
+        if (this.merchantAborted) {
+            this.merchantRequestAborted();
+            return;
+        }
         const authorizationId = error instanceof PaymentOutcomeUnknownError ? error.authorizationId : this.state.authorizationId;
         if (handoffStarted || error instanceof PaymentOutcomeUnknownError || error instanceof IntentNotConfirmableError) {
             this.held = true;
@@ -87,6 +123,9 @@ export class CheckoutLifecycle {
         else if (error instanceof CheckoutCancelledError) {
             this.cancel();
         }
+        else if (error instanceof CheckoutPreparationError) {
+            this.preparationFailed(error);
+        }
         else if (error instanceof ApprovalTimeoutError) {
             this.set({ ...this.state, status: 'timed_out', reason: 'approval_expired' });
         }
@@ -149,6 +188,8 @@ export class CheckoutLifecycle {
         return this.getState();
     }
     retryAfterMerchantFailure(result) {
+        if (this.preparationUsed)
+            throw new Error('Prepared checkouts are single use. Reconcile this attempt and create a new attachment.');
         if (this.active || this.reconciliation)
             throw new Error('Cannot start another attempt while payment or reconciliation is in progress.');
         if (this.cancelled)
@@ -160,6 +201,7 @@ export class CheckoutLifecycle {
         if (this.unboundStripeToken)
             throw new Error('This attachment delivered an unbound Stripe token; reconcile the merchant order and use a separately validated checkout flow.');
         this.held = false;
+        this.merchantAborted = false;
         this.set({ status: 'idle', authorizationId: null });
     }
 }

package/dist/preparation.d.ts

@@ -0,0 +1,25 @@
+import { type PreparedCheckout } from './client.js';
+import type { AttachOptions } from './cdp.js';
+import type { CheckoutLifecycle } from './lifecycle.js';
+/** A local, one-use rendezvous. It never starts or retries a merchant request. */
+export declare class PreparationGate {
+    private readonly opts;
+    private readonly lifecycle;
+    private readonly readDocumentUrl;
+    private state;
+    private observedRequest;
+    private documentUrl;
+    private prepared?;
+    private stop;
+    private expiryTimer?;
+    constructor(opts: AttachOptions, lifecycle: CheckoutLifecycle, readDocumentUrl: () => Promise<string>);
+    private prepare;
+    /** Called for every recognized card mutation, before any await or local retry guard. */
+    claim(requestUrl: string): PreparedCheckout | undefined;
+    assertDocument(): Promise<void>;
+    private readDocument;
+    isEngaged(): boolean;
+    retireUnboundClaim(): void;
+    /** A bound native request has its own cancellation/unknown-outcome machinery. */
+    invalidate(reason: string): void;
+}

package/dist/preparation.js

@@ -0,0 +1,150 @@
+import { CheckoutPreparationError } from './client.js';
+/** A local, one-use rendezvous. It never starts or retries a merchant request. */
+export class PreparationGate {
+    opts;
+    lifecycle;
+    readDocumentUrl;
+    state = 'unused';
+    observedRequest = false;
+    documentUrl = '';
+    prepared;
+    stop = new AbortController();
+    expiryTimer;
+    constructor(opts, lifecycle, readDocumentUrl) {
+        this.opts = opts;
+        this.lifecycle = lifecycle;
+        this.readDocumentUrl = readDocumentUrl;
+        lifecycle.setPreparationHandler(options => this.prepare(options));
+        lifecycle.abort.signal.addEventListener('abort', () => this.invalidate('cancelled'), { once: true });
+    }
+    async prepare(options) {
+        options = { ...options };
+        if (this.state !== 'unused' || this.observedRequest || this.lifecycle.getState().status !== 'idle' || this.lifecycle.isBlocked()) {
+            // A late opt-in cannot turn the next native retry into ordinary approval.
+            // Preserve any existing authorization's state for reconciliation.
+            if (this.state === 'unused')
+                this.state = 'failed';
+            throw new CheckoutPreparationError(this.prepared?.id ?? null, 'must_prepare_before_first_request');
+        }
+        // Reserve synchronously, including while origin discovery/OAuth is pending.
+        this.state = 'preparing';
+        this.lifecycle.preparing();
+        const signal = AbortSignal.any([this.stop.signal, this.lifecycle.abort.signal, ...(options?.signal ? [options.signal] : [])]);
+        const onAbort = () => this.invalidate('cancelled');
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            if (!options || options.psp !== 'square' || !['production', 'sandbox'].includes(options.environment))
+                throw new CheckoutPreparationError(null, 'unsupported_processor');
+            const tokenizer = options.environment === 'production' ? 'https://pci-connect.squareup.com/v2/card-nonce' : 'https://pci-connect.squareupsandbox.com/v2/card-nonce';
+            if (!this.opts.vault.isCardRequest(tokenizer, 'POST'))
+                throw new CheckoutPreparationError(null, 'processor_interception_unavailable');
+            if (!Number.isSafeInteger(this.opts.amountCents) || (this.opts.amountCents ?? 0) <= 0 || !/^[a-z]{3}$/i.test(this.opts.currency ?? ''))
+                throw new CheckoutPreparationError(null, 'amount_required');
+            if (signal.aborted)
+                throw new CheckoutPreparationError(null, 'cancelled');
+            this.documentUrl = await this.readDocument();
+            const page = new URL(this.documentUrl);
+            if (!(page.protocol === 'https:' || (page.protocol === 'http:' && page.hostname === 'localhost')) || page.username || page.password)
+                throw new CheckoutPreparationError(null, 'merchant_origin_invalid');
+            const prepared = await this.opts.vault.prepareCheckout({
+                ...options, user: this.opts.user, merchant: this.opts.merchant,
+                amountCents: this.opts.amountCents, currency: this.opts.currency, cardId: this.opts.cardId,
+                merchantOrigin: page.origin, checkoutKey: crypto.randomUUID(), timeoutMs: this.opts.timeoutMs, signal,
+                onPreparationCreated: id => this.lifecycle.preparationCreated(id),
+                onApprovalUrl: url => {
+                    if (!signal.aborted) {
+                        this.lifecycle.approvalUrl(url);
+                        try {
+                            Promise.resolve(this.opts.onApprovalUrl?.(url)).catch(() => { });
+                        }
+                        catch { /* observer only */ }
+                    }
+                },
+            });
+            this.prepared = prepared;
+            if (signal.aborted || this.state !== 'preparing') {
+                void this.opts.vault.cancelPreparation(prepared.id).catch(() => { });
+                throw new CheckoutPreparationError(prepared.id, 'cancelled');
+            }
+            await this.assertDocument();
+            if (signal.aborted || this.state !== 'preparing')
+                throw new CheckoutPreparationError(prepared.id, 'cancelled');
+            const remaining = Date.parse(prepared.expiresAt) - Date.now();
+            if (!(remaining > 0))
+                throw new CheckoutPreparationError(prepared.id, 'expired');
+            this.state = 'ready';
+            this.expiryTimer = setTimeout(() => this.invalidate('expired'), remaining);
+            this.expiryTimer.unref?.();
+            this.lifecycle.prepared(prepared);
+            return prepared;
+        }
+        catch (error) {
+            const failure = error instanceof CheckoutPreparationError ? error : new CheckoutPreparationError(this.prepared?.id ?? null, 'preparation_unconfirmed');
+            this.invalidate(failure.reason);
+            throw failure;
+        }
+        // Keep the signal listener after ready: caller cancellation retires the handle too.
+    }
+    /** Called for every recognized card mutation, before any await or local retry guard. */
+    claim(requestUrl) {
+        this.observedRequest = true;
+        if (this.state === 'unused')
+            return undefined;
+        if (this.state !== 'ready' || !this.prepared) {
+            this.invalidate(this.state === 'preparing' ? 'submitted_before_ready' : 'already_used_or_unavailable');
+            throw new CheckoutPreparationError(this.prepared?.id ?? null, 'already_used_or_unavailable');
+        }
+        const prepared = this.prepared;
+        const request = new URL(requestUrl);
+        const origin = prepared.environment === 'production' ? 'https://pci-connect.squareup.com' : 'https://pci-connect.squareupsandbox.com';
+        if (Date.parse(prepared.expiresAt) <= Date.now() || request.origin !== origin || request.pathname !== '/v2/card-nonce' || request.username || request.password) {
+            const reason = Date.parse(prepared.expiresAt) <= Date.now() ? 'expired' : 'checkout_changed';
+            this.invalidate(reason);
+            throw new CheckoutPreparationError(prepared.id, reason);
+        }
+        this.state = 'consumed';
+        clearTimeout(this.expiryTimer);
+        return prepared;
+    }
+    async assertDocument() {
+        if (this.documentUrl && await this.readDocument() !== this.documentUrl)
+            throw new CheckoutPreparationError(this.prepared?.id ?? null, 'merchant_document_changed');
+    }
+    async readDocument() {
+        const signal = AbortSignal.any([this.stop.signal, this.lifecycle.abort.signal, AbortSignal.timeout(5_000)]);
+        const failure = () => new CheckoutPreparationError(this.prepared?.id ?? null, 'merchant_document_unavailable');
+        if (signal.aborted)
+            throw failure();
+        let aborted;
+        const stopped = new Promise((_, reject) => {
+            aborted = () => reject(failure());
+            signal.addEventListener('abort', aborted, { once: true });
+        });
+        try {
+            return await Promise.race([this.readDocumentUrl(), stopped]);
+        }
+        finally {
+            signal.removeEventListener('abort', aborted);
+        }
+    }
+    isEngaged() { return this.state !== 'unused'; }
+    retireUnboundClaim() {
+        if (this.state !== 'consumed' || !this.prepared || this.lifecycle.getState().authorizationId)
+            return;
+        void this.opts.vault.cancelPreparation(this.prepared.id).catch(() => { });
+        // No bound ID means the adapter must not leave a spent handle appearing ready.
+        if (this.lifecycle.getState().status === 'ready_to_submit')
+            this.lifecycle.preparationFailed(new CheckoutPreparationError(this.prepared.id, 'request_not_bound'));
+    }
+    /** A bound native request has its own cancellation/unknown-outcome machinery. */
+    invalidate(reason) {
+        if (this.state === 'unused' || this.state === 'consumed' || this.state === 'failed')
+            return;
+        this.state = 'failed';
+        clearTimeout(this.expiryTimer);
+        this.stop.abort();
+        if (this.prepared)
+            void this.opts.vault.cancelPreparation(this.prepared.id).catch(() => { });
+        this.lifecycle.preparationFailed(new CheckoutPreparationError(this.prepared?.id ?? null, reason));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,8 +23,8 @@
     "_comment_build": "TypeScript is fetched rather than declared as a devDependency ON PURPOSE. This package ships zero dependencies, which is why pnpm writes no importer for it in the workspace lockfile; adding any dep here creates one, and an importer the lockfile has not been regenerated for fails every Vercel build with ERR_PNPM_OUTDATED_LOCKFILE. Pinned so the published output is reproducible.",
     "build": "npx -y -p typescript@5.9.3 tsc",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs",
-    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs"
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs",
+    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs"
   },
   "keywords": [
     "payments",