@agent-cards/checkout 0.2.1 → 0.3.1

package/dist/lifecycle.js

@@ -0,0 +1,207 @@
+import { ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, 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;
+    state = { status: 'idle', authorizationId: null };
+    held = false;
+    active = false;
+    cancelled = false;
+    merchantAborted = false;
+    unboundStripeToken = false;
+    reconciliation = null;
+    abort = new AbortController();
+    constructor(options) {
+        this.options = options;
+    }
+    getState() { return { ...this.state }; }
+    isBlocked() { return this.held || this.cancelled; }
+    isCancelled() { return this.cancelled; }
+    begin() {
+        this.active = true;
+        this.set({ status: 'awaiting_approval', authorizationId: null });
+    }
+    end() { this.active = false; }
+    set(state) {
+        this.state = state;
+        // Application telemetry must never interrupt a paused payment after it reaches the processor.
+        try {
+            Promise.resolve(this.options.onStateChange?.(this.getState())).catch(() => { });
+        }
+        catch { /* observer only */ }
+    }
+    approvalCreated(authorizationId) {
+        this.set({ ...this.state, authorizationId });
+    }
+    approvalUrl(approvalUrl) {
+        this.notify({ reason: 'approval', authorizationId: this.state.authorizationId, approvalUrl });
+    }
+    notify(action) {
+        try {
+            Promise.resolve(this.options.onUserAction?.(action)).catch(() => { });
+        }
+        catch { /* observer only */ }
+    }
+    cancel() {
+        this.cancelled = true;
+        this.held = true;
+        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)
+            return; // do not hide an outstanding/completed payment behind a later unsupported request
+        this.set({ ...this.state, status: 'unsupported', reason: 'unrecognized_payment_endpoint' });
+    }
+    prepareHandoff(replay, requestUrl) {
+        // A tokenization approval has no authoritative PaymentIntent or amount
+        // binding. Neither the first observed confirm nor the returned opaque
+        // token can supply one. Hold even in compatibility mode: this attachment
+        // must never turn that token into an unreviewed payment continuation.
+        if (!replay.mode || replay.mode === 'token') {
+            try {
+                const url = new URL(requestUrl);
+                if (url.origin === 'https://api.stripe.com' && ['/v1/payment_methods', '/v1/tokens'].includes(url.pathname)) {
+                    // Set before delivery: a lost browser acknowledgement must not reset
+                    // an already-issued token into a retryable authorization.
+                    this.unboundStripeToken = true;
+                    this.held = true;
+                }
+            }
+            catch { /* unknown URL cannot establish a token binding */ }
+        }
+    }
+    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',
+            ...(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;
+            this.set({ ...this.state, authorizationId, status: 'outcome_unknown', reason: error instanceof PaymentOutcomeUnknownError ? error.reason : error instanceof IntentNotConfirmableError ? 'intent_not_confirmable' : 'browser_handoff_failed' });
+        }
+        else if (error instanceof CheckoutCancelledError) {
+            this.cancel();
+        }
+        else if (error instanceof ApprovalTimeoutError) {
+            this.set({ ...this.state, status: 'timed_out', reason: 'approval_expired' });
+        }
+        else if (error instanceof ApprovalDeclinedError) {
+            this.set({ ...this.state, status: 'declined', reason: 'approval_declined' });
+        }
+        else {
+            this.set({ ...this.state, status: 'failed', reason: 'checkout_failed' });
+        }
+    }
+    async requestUserAction(reason) {
+        if (this.state.status === 'completed')
+            return;
+        this.held = true;
+        this.set({ ...this.state, status: 'requires_user_action', reason });
+        // Hooks deliver a link/live view owned by the integrator; the SDK does not invent challenge URLs.
+        try {
+            await this.options.onUserAction?.({ reason, authorizationId: this.state.authorizationId });
+        }
+        catch { /* observer only */ }
+    }
+    reconcile() {
+        if (this.state.status === 'completed')
+            return Promise.resolve(this.getState());
+        if (this.reconciliation)
+            return this.reconciliation;
+        if (!this.options.resolveMerchantResult)
+            return Promise.resolve(this.getState());
+        if (this.active)
+            throw new Error('Wait for the paused request to finish before reconciling the merchant order.');
+        this.reconciliation = this.resolve().finally(() => { this.reconciliation = null; });
+        return this.reconciliation;
+    }
+    async resolve() {
+        let result;
+        try {
+            result = await this.options.resolveMerchantResult(this.getState());
+        }
+        catch {
+            result = { status: 'unknown' };
+        }
+        if (!result || typeof result !== 'object')
+            result = { status: 'unknown' };
+        if (result.status === 'completed' && typeof result.orderId === 'string' && result.orderId.length > 0) {
+            this.held = true;
+            this.set({ ...this.state, status: 'completed', orderId: result.orderId });
+        }
+        else if (result.status === 'failed') {
+            // Keep the guard armed until the application deliberately starts another attempt.
+            this.held = true;
+            this.set({ ...this.state, status: 'failed', reason: 'merchant_confirmed_failure' });
+        }
+        else if (result.status === 'requires_user_action') {
+            await this.requestUserAction(result.reason);
+        }
+        else {
+            this.held = true;
+            this.set({ ...this.state, status: result.status === 'pending' ? 'awaiting_merchant' : 'outcome_unknown', reason: 'merchant_not_confirmed' });
+        }
+        return this.getState();
+    }
+    retryAfterMerchantFailure(result) {
+        if (this.active || this.reconciliation)
+            throw new Error('Cannot start another attempt while payment or reconciliation is in progress.');
+        if (this.cancelled)
+            throw new Error('This attachment was cancelled; attach again after reconciling the merchant order.');
+        if (result?.status !== 'failed')
+            throw new Error('A merchant-confirmed failure is required before retrying.');
+        if (this.state.status === 'completed')
+            throw new Error('This order is already complete. Use a new attachment for another order.');
+        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 });
+    }
+}
+export function paymentEndpointGuards(input = []) {
+    const guards = input.map((guard) => {
+        const origin = new URL(guard.origin);
+        if (!['http:', 'https:'].includes(origin.protocol) || origin.origin !== guard.origin
+            || !guard.pathname.startsWith('/') || /[?#*]/.test(guard.pathname)) {
+            throw new Error('Payment endpoint guards require a canonical http(s) origin and an exact path without wildcards or query strings.');
+        }
+        const methods = (guard.methods ?? ['POST', 'PUT', 'PATCH']).map((method) => method.toUpperCase());
+        if (!methods.length || methods.some((method) => !['POST', 'PUT', 'PATCH', 'DELETE'].includes(method))) {
+            throw new Error('Payment endpoint guards can only block explicit mutation methods.');
+        }
+        return { ...guard, methods };
+    });
+    return {
+        patterns: guards.map((guard) => `${guard.origin}${guard.pathname}*`),
+        matches(raw, method) {
+            let url;
+            try {
+                url = new URL(raw);
+            }
+            catch {
+                return false;
+            }
+            return guards.some((guard) => url.origin === guard.origin && url.pathname === guard.pathname
+                && (method === undefined || guard.methods.includes(method.toUpperCase())));
+        },
+    };
+}

package/examples/existing-browser.mjs

@@ -0,0 +1,63 @@
+// Existing Kernel / Browserbase / custom Chromium session; does not create or close the provider's browser.
+// Run: CHECKOUT_DRIVER=/absolute/path/to/instinct-driver.mjs node examples/existing-browser.mjs
+// The driver owns the existing agent, its approved purchase and merchant-specific order verification.
+import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright-core';
+import { VaultClient, attachToPlaywright } from '../dist/index.js';
+
+const driverPath = process.env.CHECKOUT_DRIVER;
+if (!driverPath?.startsWith('/')) throw new Error('CHECKOUT_DRIVER must name an absolute path to your integration module.');
+const driver = await import(pathToFileURL(driverPath).href);
+for (const method of ['prepareCheckout', 'submitCheckout', 'resolveMerchantResult', 'onUserAction', 'finishAfterPayment']) {
+  if (typeof driver[method] !== 'function') throw new Error(`Your driver must implement ${method}.`);
+}
+if (!process.env.CHECKOUT_CDP_URL) throw new Error('Set CHECKOUT_CDP_URL to your existing session connection URL. Never log it.');
+for (const name of ['AGENTCARD_CLIENT_ID', 'AGENTCARD_CLIENT_SECRET']) {
+  if (!process.env[name]) throw new Error(`Set ${name} for your Agentcard organization.`);
+}
+const browser = await chromium.connectOverCDP(process.env.CHECKOUT_CDP_URL);
+try {
+const context = browser.contexts()[0];
+if (!context) throw new Error('The provider returned no default browser context.');
+const pages = context.pages();
+const index = Number(process.env.CHECKOUT_PAGE_INDEX ?? 0);
+const page = pages[index];
+if (!page) throw new Error('CHECKOUT_PAGE_INDEX must select the existing agent checkout tab.');
+
+const vault = new VaultClient({ clientId: process.env.AGENTCARD_CLIENT_ID, clientSecret: process.env.AGENTCARD_CLIENT_SECRET });
+await vault.syncRegistry();
+const checkout = await driver.prepareCheckout(page); // user, merchant, amountCents+currency, exact paymentEndpoints
+const controller = await attachToPlaywright(page, {
+  ...checkout,
+  vault,
+  requireMerchantResult: true,
+  onUserAction: action => driver.onUserAction(action, { page }),
+  resolveMerchantResult: state => driver.resolveMerchantResult({ page, state }),
+  // State has no PAN, replay body, approval capability, or provider connection URL.
+  onStateChange: state => console.log(JSON.stringify(state)),
+});
+
+// Must return after dispatching the click; do not block on a navigation that awaits user approval.
+await driver.submitCheckout(page);
+const deadline = Date.now() + 15 * 60_000;
+while (Date.now() < deadline) {
+  let state = controller.getState();
+  if (['awaiting_merchant', 'requires_user_action', 'outcome_unknown'].includes(state.status)) {
+    state = await controller.reconcile();
+  }
+  if (state.status === 'completed' && state.orderId) {
+    await driver.finishAfterPayment({ page, orderId: state.orderId });
+    break;
+  }
+  if (['declined', 'timed_out', 'cancelled', 'unsupported', 'failed'].includes(state.status)) break;
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+if (controller.getState().status !== 'completed') {
+  controller.cancel(); // local stop only; reconcile any still-valid approval before creating a new one
+  process.exitCode = 2;
+}
+} finally {
+  // Disconnect this CDP client. The existing agent retains ownership of its provider session.
+  // Do not call page.close(), context.close(), or a provider session-delete API here.
+  await browser.close();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "examples"
   ],
   "publishConfig": {
     "access": "public"
@@ -21,7 +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"
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs",
+    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs"
   },
   "keywords": [
     "payments",