@agent-cards/checkout 0.2.1 → 0.3.1

package/dist/cdp.js

@@ -1,7 +1,8 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
-import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, UnsupportedModeError, redactUrl, } from './client.js';
+import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, UnsupportedModeError, redactUrl, } from './client.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
+import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
 // Every URL that leaves this module through onEvent is redacted to origin +
 // path first. A paused PaymentIntent confirm can carry the client secret in
 // its query string (Stripe.js puts it in the body; hand-rolled runtimes and
@@ -270,6 +271,35 @@ function headerEntries(headers) {
  * that drifts from the registry is exactly the bug this adapter used to have.
  */
 const FALLBACK_CARD_PATTERNS = cardUrlPatterns(BUILTIN_REGISTRY);
+/** Observer exceptions and server error envelopes must not interrupt or leak a processor handoff. */
+function safeOptions(opts) {
+    const observer = opts.onEvent;
+    return { ...opts, onEvent: (event) => { try {
+            Promise.resolve(observer?.(event)).catch(() => { });
+        }
+        catch { /* observer only */ } } };
+}
+function failureSummary(error) {
+    if (error instanceof CheckoutApiError)
+        return `${error.name}: ${error.code ?? `http_${error.status}`}`;
+    return error instanceof Error ? error.name : 'CheckoutError';
+}
+/** Separate from explicit cancellation: the client can drain a late create ID. */
+function merchantAttempt(lifecycle) {
+    const controller = new AbortController();
+    const error = () => new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'merchant_request_aborted');
+    return {
+        signal: controller.signal,
+        stop() {
+            if (controller.signal.aborted)
+                return;
+            lifecycle.merchantRequestAborted();
+            controller.abort(error());
+        },
+        assertLive() { if (controller.signal.aborted)
+            throw error(); },
+    };
+}
 /**
  * Take over card tokenization for a page.
  *
@@ -288,6 +318,9 @@ const FALLBACK_CARD_PATTERNS = cardUrlPatterns(BUILTIN_REGISTRY);
  * armed identically.
  */
 export async function attachToCdp(cdp, pageSessionId, opts) {
+    opts = safeOptions(opts);
+    const lifecycle = new CheckoutLifecycle(opts);
+    const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
     // Set once a failure proves that retrying cannot help; see isTerminal.
     let terminal = null;
@@ -296,45 +329,77 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let quietUntil = 0;
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
+    let activeRequest = null;
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
     const derived = typeof opts.vault?.cardUrlPatterns === 'function' ? opts.vault.cardUrlPatterns() : [];
-    const urlPatterns = derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS;
+    const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns])];
     opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
     const arm = async (sessionId) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
-        armed.add(key);
+        // Fetch's interception ID differs from Network's ID. Enable failure events
+        // before intercepting and bind each attempt to both its ID and CDP session.
+        await cdp.send('Network.enable', {}, sessionId);
+        await cdp.send('Page.enable', {}, sessionId).catch(() => { });
         await cdp.send('Fetch.enable', {
             patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
-        }, sessionId).catch(() => { });
+        }, sessionId);
         // Descend into this target's own children (iframes inside iframes).
         await cdp.send('Target.setAutoAttach', {
             autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
-        }, sessionId).catch(() => { });
+        }, sessionId);
+        armed.add(key);
     };
     cdp.on(async (method, params, sessionId) => {
+        if (method === 'Network.loadingFailed') {
+            if (activeRequest && activeRequest.networkId === params.requestId && activeRequest.sessionId === sessionId)
+                activeRequest.attempt.stop();
+            return;
+        }
+        if (method === 'Target.detachedFromTarget' || method === 'Inspector.detached' || method === 'Page.frameDetached') {
+            if (activeRequest && (method === 'Target.detachedFromTarget' ? activeRequest.sessionId === params.sessionId
+                : method === 'Inspector.detached' ? activeRequest.sessionId === sessionId
+                    : activeRequest.sessionId === sessionId && activeRequest.frameId === params.frameId))
+                activeRequest.attempt.stop();
+            return;
+        }
         if (method === 'Target.attachedToTarget') {
             const child = params.sessionId;
-            await arm(child);
+            try {
+                await arm(child);
+            }
+            catch {
+                terminal = new Error('browser_interception_unavailable');
+                lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'browser_interception_unavailable'));
+                opts.onEvent?.({ type: 'failed', detail: 'browser_interception_unavailable' });
+                // Leave this target paused: resuming an unarmed card frame would silently bypass the vault.
+                return;
+            }
             // Child targets start paused when waitForDebuggerOnStart is set.
             await cdp.send('Runtime.runIfWaitingForDebugger', {}, child).catch(() => { });
             return;
         }
         if (method !== 'Fetch.requestPaused')
             return;
-        const { requestId, request, resourceType } = params;
+        const { requestId, request, resourceType, networkId, frameId } = params;
         if (!opts.vault.isCardRequest(request.url, request.method)) {
+            if (guards.matches(request.url, request.method)) {
+                lifecycle.unsupported();
+                opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url), method: request.method } });
+                await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+                return;
+            }
             await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
             return;
         }
         // Same stop condition as the Playwright adapter: once a failure proves
         // retrying is pointless, fail the request without calling the API again.
-        if (terminal || awaitingApproval || Date.now() < quietUntil) {
-            const why = terminal ?? (awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
-            opts.onEvent?.({ type: 'blocked', detail: String(why) });
+        if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
+            const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+            opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
             return;
         }
@@ -342,6 +407,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         // requests can never both clear the check above and raise two prompts for
         // one checkout.
         awaitingApproval = true;
+        const attempt = merchantAttempt(lifecycle);
+        let handoffStarted = false;
         try {
             const body = pausedBody(request);
             if (body === null) {
@@ -361,15 +428,34 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 return;
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}) } });
+            lifecycle.begin();
+            if (typeof networkId !== 'string' || !networkId) {
+                attempt.stop();
+                attempt.assertLive();
+            }
+            activeRequest = { attempt, networkId, sessionId, frameId };
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
                 amountCents: opts.amountCents,
                 currency: opts.currency,
-                onApprovalUrl: opts.onApprovalUrl,
+                cardId: opts.cardId,
+                timeoutMs: opts.timeoutMs,
+                signal: lifecycle.abort.signal,
+                merchantSignal: attempt.signal,
+                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                onApprovalUrl: (url) => { if (!attempt.signal.aborted) {
+                    lifecycle.approvalUrl(url);
+                    return opts.onApprovalUrl?.(url);
+                } },
                 request: { url: request.url, method: request.method, headers: request.headers, body },
             });
+            attempt.assertLive();
+            if (lifecycle.isCancelled())
+                throw new Error('checkout cancelled locally after approval');
+            lifecycle.prepareHandoff(replay, request.url);
+            handoffStarted = replay.mode !== 'cse';
             if (replay.mode === 'hosted_form') {
                 // The device submitted the processor's own form; the processor
                 // answered the device. The paused NAVIGATION is fulfilled with a page
@@ -385,6 +471,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     responseHeaders: headerEntries(withCorsHeaders(page.headers, corsHeadersFor(request.url, request.headers))),
                     body: Buffer.from(page.body).toString('base64'),
                 }, sessionId);
+                attempt.assertLive();
                 lastSubmitted = { url: request.url, body, at: Date.now() };
                 // Named for what it is: a device-attested submission with no
                 // processor evidence, never an `authorized` event.
@@ -396,10 +483,13 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // and cookies, and only the four ciphertext fields swapped in. Only
                 // postData rides on the command: no header override, ever (see
                 // cseBody for why a recomputed Content-Length is refused by Chromium).
+                const postData = Buffer.from(cseBody(body, replay)).toString('base64');
+                handoffStarted = true;
                 await cdp.send('Fetch.continueRequest', {
                     requestId,
-                    postData: Buffer.from(cseBody(body, replay)).toString('base64'),
+                    postData,
                 }, sessionId);
+                attempt.assertLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
@@ -416,22 +506,32 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     responseHeaders: headerEntries(withCorsHeaders(replay.headers, cors.headers)),
                     body: Buffer.from(replay.body).toString('base64'),
                 }, sessionId);
+                attempt.assertLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
+            lifecycle.handedOff(replay);
         }
         catch (err) {
+            // Ignore the failure event caused by our own safe decline/error abort.
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
+            lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
             else if (isApprovalOutcome(err))
                 quietUntil = Date.now() + cooldownMs;
-            opts.onEvent?.({ type: 'failed', detail: String(err) });
+            opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
         }
         finally {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             awaitingApproval = false;
+            lifecycle.end();
         }
     });
     await arm(pageSessionId);
+    return lifecycle;
 }
 /**
  * Playwright convenience wrapper — the path for cloud browsers that hand you a
@@ -445,6 +545,14 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
  * the note in the body for why a hand-rolled CDPSession does not work here.
  */
 export async function attachToPlaywright(page, opts) {
+    opts = safeOptions(opts);
+    // Routing cannot see requests owned by a service worker. Existing controlled
+    // contexts must be recreated with serviceWorkers: 'block' before checkout.
+    if (page.context?.().serviceWorkers?.().length) {
+        throw new Error('Service workers are active; use a checkout context created with serviceWorkers: "block".');
+    }
+    const lifecycle = new CheckoutLifecycle(opts);
+    const guards = paymentEndpointGuards(opts.paymentEndpoints);
     // Playwright's own routing, NOT a hand-rolled CDP session.
     //
     // A CDPSession from `newCDPSession(page)` is bound to the PAGE target and its
@@ -464,14 +572,30 @@ export async function attachToPlaywright(page, opts) {
     let quietUntil = 0;
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
+    let activeRequest = null;
+    page.on?.('requestfailed', (request) => {
+        if (activeRequest && activeRequest.request === request)
+            activeRequest.attempt.stop();
+    });
+    page.on?.('close', () => activeRequest?.attempt.stop());
+    page.on?.('crash', () => activeRequest?.attempt.stop());
+    page.on?.('framedetached', (frame) => {
+        if (activeRequest?.frames.includes(frame))
+            activeRequest.attempt.stop();
+    });
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
-    await page.route((url) => opts.vault.isCardRequest(url.toString()), async (route) => {
+    await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
         const request = route.request();
         // The matcher only sees the URL; a preflight or a GET must pass through
         // untouched or the browser's CORS check fails on our synthetic answer.
         if (!opts.vault.isCardRequest(request.url(), request.method())) {
+            if (guards.matches(request.url(), request.method())) {
+                lifecycle.unsupported();
+                opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
+                return route.abort('aborted');
+            }
             return route.fallback();
         }
         // Fail closed and stay quiet: no card may reach the PSP, but neither may
@@ -479,13 +603,26 @@ export async function attachToPlaywright(page, opts) {
         // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
         // CDP adapter's Fetch.failRequest uses, so a refused navigation
         // resolves identically whichever adapter is attached.
-        if (terminal || awaitingApproval || Date.now() < quietUntil) {
-            const why = terminal ?? (awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
-            opts.onEvent?.({ type: 'blocked', detail: String(why) });
+        if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
+            const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+            opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
             return route.abort('aborted');
         }
         // Reserved before anything that could yield, matching attachToCdp.
         awaitingApproval = true;
+        const attempt = merchantAttempt(lifecycle);
+        const frames = [];
+        try {
+            for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
+                frames.push(frame);
+        }
+        catch { /* requestfailed/page close still cover unavailable frame metadata */ }
+        const assertRequestLive = () => {
+            if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
+                attempt.stop();
+            attempt.assertLive();
+        };
+        let handoffStarted = false;
         try {
             const body = request.postData() ?? '';
             if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
@@ -493,21 +630,38 @@ export async function attachToPlaywright(page, opts) {
                 return await route.abort('aborted');
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
+            lifecycle.begin();
+            activeRequest = { request, frames, attempt };
+            assertRequestLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
                 amountCents: opts.amountCents,
                 currency: opts.currency,
-                onApprovalUrl: opts.onApprovalUrl,
+                cardId: opts.cardId,
+                timeoutMs: opts.timeoutMs,
+                signal: lifecycle.abort.signal,
+                merchantSignal: attempt.signal,
+                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                onApprovalUrl: (url) => { if (!attempt.signal.aborted) {
+                    lifecycle.approvalUrl(url);
+                    return opts.onApprovalUrl?.(url);
+                } },
                 request: { url: request.url(), method: request.method(), headers: request.headers(), body },
             });
+            assertRequestLive();
+            if (lifecycle.isCancelled())
+                throw new Error('checkout cancelled locally after approval');
+            lifecycle.prepareHandoff(replay, request.url());
+            handoffStarted = replay.mode !== 'cse';
             if (replay.mode === 'hosted_form') {
                 // Same as the CDP path: the paused navigation resolves to the
                 // synthetic page, and a re-post of this form is refused.
                 const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
                 // Inert on a navigation (never CORS-checked); one path for every fulfill.
                 await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
+                assertRequestLive();
                 lastSubmitted = { url: request.url(), body, at: Date.now() };
                 opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
             }
@@ -515,7 +669,10 @@ export async function attachToPlaywright(page, opts) {
                 // Same as the CDP path: the request continues from this browser
                 // with the ciphertext swapped in and no header override; Playwright
                 // recomputes the length itself.
-                await route.continue({ postData: cseBody(body, replay) });
+                const postData = cseBody(body, replay);
+                handoffStarted = true;
+                await route.continue({ postData });
+                assertRequestLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
@@ -524,19 +681,28 @@ export async function attachToPlaywright(page, opts) {
                 // cross-origin answer is the same whichever adapter ran.
                 const cors = corsDecision(request.url(), request.headers());
                 await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                assertRequestLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
+            lifecycle.handedOff(replay);
         }
         catch (err) {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
+            lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
             else if (isApprovalOutcome(err))
                 quietUntil = Date.now() + cooldownMs;
-            opts.onEvent?.({ type: 'failed', detail: String(err) });
-            await route.abort('aborted');
+            opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
+            await route.abort('aborted').catch(() => { });
         }
         finally {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             awaitingApproval = false;
+            lifecycle.end();
         }
     });
+    return lifecycle;
 }

package/dist/client.d.ts

@@ -133,6 +133,12 @@ export interface AuthorizeInput {
     request: PausedRequest;
     /** Abort if the user has not approved within this many ms. Default 15 min. */
     timeoutMs?: number;
+    /** Stops local polling; it does not revoke a pending approval or undo a payment. */
+    signal?: AbortSignal;
+    /** Adapter-owned merchant request lifetime. A failed request retires a pending approval before replay when possible. */
+    merchantSignal?: AbortSignal;
+    /** Called before onApprovalUrl; lets a runtime reconcile an interrupted authorization. */
+    onAuthorizationCreated?: (authorizationId: string) => void;
     /** Called once with the URL to surface to the user, if you deliver it yourself. */
     onApprovalUrl?: (url: string) => void;
 }
@@ -141,10 +147,9 @@ export declare class CardEncryptedError extends Error {
     constructor(psp: string);
 }
 /**
- * The API approved an authorization in a mode this SDK build cannot finish.
- * Unreachable by construction (syncRegistry asks only for SUPPORTED_MODES and
- * every create names its mode), so it is treated as terminal: retrying the
- * same page could only raise more prompts for the same dead end.
+ * The registry requests a mode this SDK build cannot finish, before creation.
+ * A response in an unexpected mode after creation has an unknown payment
+ * outcome instead and raises PaymentOutcomeUnknownError.
  */
 export declare class UnsupportedModeError extends Error {
     mode: string;
@@ -153,6 +158,15 @@ export declare class UnsupportedModeError extends Error {
 export declare class ApprovalTimeoutError extends Error {
     constructor(ms: number);
 }
+export declare class CheckoutCancelledError extends Error {
+    constructor();
+}
+/** The payment may have reached the processor. Reconcile the merchant order before any new attempt. */
+export declare class PaymentOutcomeUnknownError extends Error {
+    authorizationId: string | null;
+    reason: string;
+    constructor(authorizationId: string | null, reason: string);
+}
 export declare class ApprovalDeclinedError extends Error {
     constructor(reason: string);
 }
@@ -324,6 +338,14 @@ export declare class VaultClient {
      * response to replay into the browser. Your process never sees a card.
      */
     authorize(input: AuthorizeInput): Promise<ReplayResponse>;
+    /** Retire only a pre-replay authorization. A 409 or missing response remains unknown. */
+    cancelAuthorization(authorizationId: string): Promise<{
+        id: string;
+        status: 'declined';
+        reason: 'merchant_request_aborted';
+        cancelled: true;
+        processor_request_started: false;
+    }>;
     /**
      * POST the create, with two typed twists: a 502 `amount_unverifiable`
      * (Stripe did not answer the read-back) is retried on a short backoff