@agent-cards/checkout 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.3.0
+
+### Browser checkout lifecycle
+
+- `attachToPlaywright` and `attachToCdp` now return a `CheckoutController` with state, cancellation, merchant reconciliation, user-action hooks and explicit retry after a merchant-confirmed failure. Existing callers may continue to ignore the return value.
+- `requireMerchantResult: true` holds further card requests after handoff until the application's merchant integration confirms the outcome. Approval or tokenization alone does not establish a successful order.
+- Stripe `/v1/payment_methods` and `/v1/tokens` handoffs hold further recognized card requests, even without `requireMerchantResult`. Tokenization does not bind a specific PaymentIntent, amount or currency, so automatic token-to-intent continuation is unsupported. Direct card-bearing PaymentIntent confirms retain their existing backend amount verification. Unknown merchant-server endpoints require explicit `paymentEndpoints` guards; server-side charges remain outside this browser guard.
+- Exact `paymentEndpoints` guards abort unsupported payment endpoints identified by the integrator. Unknown endpoints outside those guards remain untouched.
+- An existing-browser example covers the direct SDK connection used with Browserbase, Kernel or a compatible custom Chromium/CDP session. Cloud-provider sessions and real merchant/3DS flows still require separate validation; Kernel's native Vault integration is a separate path.
+
+### Migration from 0.2.x
+
+- Handle `PaymentOutcomeUnknownError` separately from decline or safe expiry. Lost create/poll responses, malformed post-create responses and local deadlines can leave an approval or payment outstanding. Reconcile the merchant order before starting another attempt; do not retry because a local timer elapsed.
+- `timeoutMs` now bounds authentication, authorization creation and polling together. `cancel()` stops this attachment locally; it does not revoke an approval link or cancel a processor payment. A cancelled attachment cannot restart.
+- An attachment that issued an unbound Stripe token cannot reset with `retryAfterMerchantFailure`, including when browser delivery is uncertain. Reconcile the merchant outcome and use a separately validated flow; do not reuse the token in a new attachment.
+- Hosted-form submissions remain blocked until an explicit merchant-confirmed failure permits retry. The short duplicate-request cooldown is not proof that retry is safe.
+- Initial raw-CDP interception setup errors now reject attachment. A child target that cannot be armed stays paused for operator recovery. Supply a browser-level, session-aware CDP connection for raw CDP; a page-scoped Playwright `CDPSession` is insufficient.
+- Playwright attachment rejects contexts with active service workers. Create checkout contexts with `serviceWorkers: 'block'`; checking an existing context cannot prevent later worker registration.
+- Observer callback failures no longer interrupt payment handoff. Event failure summaries omit processor/API response bodies and request query strings.
+
+### Verification
+
+Deterministic transport and lifecycle tests cover failure recovery and retry guards. Local Chromium fixtures cover nested cross-origin frames, same-page post-payment work, and blocking immediate Stripe payment-method-to-intent fetch chains for both adapters, including an unrelated first intent and changed amount/currency. All payment endpoints in those fixtures are local stubs; they do not establish production provider or processor coverage.

package/README.md

@@ -30,6 +30,9 @@ your agent ──drives──> merchant checkout
 npm i @agent-cards/checkout
 ```
 
+Upgrading from 0.2.x? Read the [0.3.0 migration notes](./CHANGELOG.md), especially
+the unknown-outcome, cancellation and browser-context requirements.
+
 ## Use it
 
 Two lines against a CDP session you already have:
@@ -118,12 +121,12 @@ before you put that in writing.
 
 ## Supported processors
 
-Merchants inherit their processor, so one entry covers every store on it.
+Coverage is specific to the processor request format, merchant setup, browser transport and follow-up flow. A recognized endpoint is not proof that every store using that processor completes checkout.
 
 | Processor | Status |
 |---|---|
 | Shopify | supported, verified end to end |
-| Stripe | supported, verified end to end |
+| Stripe | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms with `amountCents` + `currency` use backend amount verification. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
 | Braintree / PayPal | supported, verified end to end |
 | Checkout.com | supported |
 | VGS Collect (Very Good Security; Wolt) | not supported: VGS's proxy aliases only submissions from its own iframe, so a replay from the cardholder's device is refused by the merchant (verified on Wolt, 2026-09-03). Not recognized, so the agent's browser is not paused there |
@@ -213,8 +216,9 @@ three; the difference matters if you drive `authorize()` yourself.
 `syncRegistry()` asks the API for `SUPPORTED_MODES` only
 (`token,cse,hosted_form`), so a processor whose flow this build cannot finish
 is never paused; the API serves `hosted_form` entries only to callers that ask.
-An approval in some other mode throws `UnsupportedModeError`, which is
-terminal for that page (upgrade the SDK). The `authorized` event's detail names
+A registry mode this SDK cannot finish throws `UnsupportedModeError` before
+creation. An approval returned in an unexpected mode has an unknown outcome
+and holds the attachment for reconciliation. The `authorized` event's detail names
 the `mode`, the `authorizationId` and, for `cse`, the `fields` that were
 substituted; it never carries ciphertext. The `submitted_on_device` event's
 detail names the `authorizationId`, `submittedAt` and `outcome:
@@ -224,8 +228,7 @@ one. `amountAuthority` on every replay is `stripe_payment_intent`,
 
 ## Errors worth handling
 
-- `ApprovalTimeoutError` — the user never approved. Default window is 15 minutes;
-  we have completed checkouts after a 5.5 minute approval delay.
+- `ApprovalTimeoutError` — the server confirms the authorization expired without a replay attempt. A local deadline is different: `PaymentOutcomeUnknownError` means the approval link may still be valid, so reconcile the merchant order before another attempt.
 - `ApprovalDeclinedError` — the user said no.
 - `AmountMismatchError`: the processor's amount did not match the amount the
   user was (or would have been) asked to approve. Nothing was charged. An
@@ -276,8 +279,9 @@ one. `amountAuthority` on every replay is `stripe_payment_intent`,
 - `CardEncryptedError`: this processor encrypts the card in-page and its
   registry entry does not (yet) say the vault can produce that ciphertext;
   route the purchase to an Agentcard-issued card instead.
-- `UnsupportedModeError`: the approval came back in a mode this build of the
-  SDK cannot finish. Terminal for the page; upgrade.
+- `UnsupportedModeError`: the registry requests a mode this SDK cannot finish
+  before an authorization exists. Upgrade. An unexpected approved mode instead
+  raises `PaymentOutcomeUnknownError` and requires reconciliation.
 - `SubstitutionError`: a `cse` approval could not be written into the paused
   body (the four encrypted fields were not there). The request is failed and
   the next one is judged afresh.
@@ -292,3 +296,167 @@ unrelated transitive versions). Build it with the workspace TypeScript:
 ```bash
 cd packages/checkout && pnpm build && pnpm test
 ```
+
+
+## Browser integration and merchant outcomes
+
+`attachToPlaywright` works with an existing Chromium page reached through
+`chromium.connectOverCDP`. Browserbase supplies `session.connectUrl`; Kernel
+supplies `browser.cdp_ws_url`; a custom browser must expose a compatible CDP
+endpoint. This is Agentcard's **direct SDK** path. Kernel's native Vault alias
+integration is a separate provider adapter with its own coverage and lifecycle;
+do not install both interceptors on the same checkout without validating how
+those routes interact.
+
+The local browser suite validates Chromium and nested cross-origin frames over
+both Playwright routing and a raw, session-aware CDP connection. It does not
+establish live Browserbase, Kernel, 3DS or merchant coverage. A raw page-scoped
+Playwright `CDPSession` is not the `CdpLike` interface. Raw CDP must preserve the
+`sessionId` on every command/event and allow recursive target attachment.
+Initial arming errors reject `attachToCdp`; a child that cannot be armed remains
+paused and reports `browser_interception_unavailable` for operator recovery.
+
+Use a checkout context created with `serviceWorkers: 'block'`. Playwright cannot
+route requests intercepted by a service worker. The SDK rejects already active
+service workers, but that check cannot prevent a site from registering one
+later in an existing context configured to allow them. Attach before entering
+card fields; keep the existing checkout tab. Separate popup tabs need their own
+attachment. A page route does not cover a popup's first navigation; a popup
+which submits payment on that navigation requires a separately validated
+context/browser-level integration. Existing `page.route` handlers must call
+`route.fallback()` when they do not handle a request; later routes have priority.
+
+Both adapters now return a controller; existing code that ignores the return
+value continues to work. Choose `requireMerchantResult: true` for a pilot:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault, user, merchant, amountCents, currency,
+  requireMerchantResult: true,
+  onStateChange: state => recordState(state),
+  onUserAction: action => deliverPrivatelyToUser(action),
+  resolveMerchantResult: async state => readMerchantOrder(state),
+  paymentEndpoints: [
+    { origin: 'https://payments.example.com', pathname: '/submit', methods: ['POST'] },
+  ],
+});
+
+// Your existing agent dispatches checkout. Later, once the paused request resumes:
+const state = await checkout.reconcile();
+if (state.status === 'completed' && state.orderId) await finishAgentTask(state.orderId);
+```
+
+`resolveMerchantResult` must read an authoritative merchant order/receipt tied
+to this attempt. It returns one of:
+
+- `{ status: 'completed', orderId }`: merchant-confirmed success.
+- `{ status: 'failed' }`: merchant confirmed the attempt failed; no successful payment/order exists.
+- `{ status: 'pending' }` or `{ status: 'unknown' }`: keep waiting or reconcile; never click Pay again.
+- `{ status: 'requires_user_action', reason: '3ds' | 'redirect' | 'other' }`: deliver your own browser live view or supported challenge UI to the user.
+
+The SDK does not infer order success from `authorized` or a tokenization reply,
+and does not claim to detect or solve arbitrary 3DS challenges. Your merchant
+resolver (or `checkout.requestUserAction('3ds')` when your browser observes it)
+drives that hook. Deliver `onUserAction` approval URLs privately: they are
+capabilities and never belong in general telemetry. Observer exceptions are
+isolated from the payment handoff.
+
+With `requireMerchantResult`, subsequent card requests stay blocked after
+handoff. Stripe `/v1/payment_methods` and `/v1/tokens` handoffs always hold further
+recognized card requests, even when that option is false. A tokenization approval has no
+authoritative binding to a specific PaymentIntent, amount or currency. The first
+observed confirm cannot supply that binding. The SDK therefore blocks every
+follow-up confirm on that attachment, including the same token, an unrelated
+intent, changed amounts and retries. It reports `awaiting_merchant` with reason
+`stripe_tokenization_unbound`, while ordinary browser traffic stays available.
+There is no automatic token-to-intent continuation or merchant-continuation hook.
+Unrecognized merchant-server endpoints remain outside this guard unless listed
+in `paymentEndpoints`; this is not a guarantee against a merchant charging a
+saved token on its own server.
+A direct card-bearing PaymentIntent confirm remains supported with the backend's
+existing amount verification when `amountCents` and `currency` are supplied.
+
+Hosted-form submissions also always stay blocked because their payment outcome
+is unverified. `reconcile()` calls the resolver once, coalescing concurrent calls.
+After an explicit merchant-confirmed failure, the application may call
+`checkout.retryAfterMerchantFailure({ status: 'failed' })` to permit another
+attempt where the attachment permits recovery. This is an assertion from your
+merchant integration, not a timeout or a best guess. Completed orders, cancelled
+attachments and attachments that issued an unbound Stripe token cannot reset
+this way, including when the token's browser delivery acknowledgement was lost.
+Reconcile the merchant outcome and use a separately validated checkout flow;
+do not reuse that token in a new attachment as a workaround. Configuration and
+unsupported-mode failures require fixing the integration. Bank flows requiring
+another confirmation and other stored-token chains remain unverified.
+
+Lost authorization polling, local approval timeouts, or interrupted browser
+handoffs produce `outcome_unknown` and block automatic retry. The thrown
+`PaymentOutcomeUnknownError` carries `authorizationId` when creation was
+acknowledged. `checkout.cancel()` stops the local attachment and polling; it
+does not revoke a pending approval link or undo a processor payment. Cancellation
+after an attempt starts is therefore unknown until reconciled. A cancelled
+attachment cannot restart.
+
+### Unsupported endpoints
+
+`paymentEndpoints` is an explicit list supplied by the integrator after observing
+the site's payment requests. Each guard uses a canonical origin, exact path and
+mutation methods; it never examines or logs card bodies. If a guarded endpoint
+is not recognized, the SDK aborts it and reports `unsupported_checkout` /
+`unsupported` without creating an approval. Preflights and ordinary page traffic
+continue. There is no wildcard or intercept-all fallback, and no automatic
+conversion to an issued card. Unknown endpoints absent from these guards remain
+untouched; the SDK cannot identify every payment request from its URL.
+
+### Runnable integration and local verification
+
+`examples/existing-browser.mjs` runs against an existing provider session, using
+an application-owned driver module for the agent's actions, user communication
+and merchant-result resolver. Set `CHECKOUT_DRIVER` to that module's absolute
+path and `CHECKOUT_CDP_URL` to the provider connection URL; optionally select the
+existing tab with `CHECKOUT_PAGE_INDEX`. The module must export
+`prepareCheckout(page)`, `submitCheckout(page)`, `resolveMerchantResult({page,
+state})`, `onUserAction(action, {page})`, and `finishAfterPayment({page, orderId})`.
+`prepareCheckout` returns the checkout options above. `submitCheckout` dispatches
+the existing agent's approved purchase and returns without waiting for approval.
+Install `playwright-core` in the example's host project. The SDK itself keeps no
+runtime dependencies. The example is integration scaffolding, not a universal
+merchant driver and not evidence of a live provider checkout.
+
+```sh
+pnpm build
+pnpm test
+# Uses installed playwright-core, falling back to the monorepo backend dependency.
+# Set CHECKOUT_CHROME_PATH if Chromium is not installed in Playwright's cache.
+pnpm test:browser
+```
+
+The browser fixtures never contact a payment service. The general suite uses
+`psp.invalid`; the Stripe continuation suite forces `api.stripe.com` through an
+allowlisted loopback proxy and a temporary self-signed TLS stub (requires the
+`openssl` CLI). All other proxy destinations are rejected. Both suites use an
+in-process Agentcard API fixture and loopback merchant pages. It proves nested-frame pause/resume, agent control during approval,
+post-payment tasks in the same page, decline/expiry/cancel, unknown-outcome retry
+blocking, explicit unsupported endpoint behavior, and blocking an immediate real-browser
+Stripe token-to-intent fetch chain, including unrelated first intents, changed
+amounts/currencies and delayed CDP acknowledgement. It does not test card
+cryptography, real bank authorization or a cloud-provider deployment.
+
+Provider/API references checked for this integration:
+[Playwright CDP](https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp),
+[Playwright routing limitations](https://playwright.dev/docs/api/class-page#page-route),
+[Browserbase Playwright quickstart](https://docs.browserbase.com/welcome/quickstarts/playwright),
+[Kernel native Agentcard integration](https://www.kernel.sh/docs/integrations/payments/agentcard).
+
+
+The authenticated `GET /v2/checkout/coverage` endpoint describes direct-SDK
+processor modes, limitations and verification levels. Use
+`POST /v2/checkout/coverage/assess` with up to 1,000 uniquely identified cases:
+`{ cases: [{ id, request_url, method: "POST", scenario: "one_time", weight: 1,
+requires_3ds: false }] }`. Scenarios also include `save_card`,
+`subscription_initial` and `subscription_renewal`. The endpoint assesses request
+recognition, not purchases: `recognized`, `unsupported` and `unverified` are
+coverage classifications, `recognized_traffic_share` is traffic-weighted, and
+`purchase_success_rate` stays null without observed merchant outcomes. Do not
+substitute the assessor for a browser/merchant validation run or use native
+Kernel adapter coverage as evidence for this SDK's coverage.

package/dist/cdp.d.ts

@@ -1,4 +1,5 @@
 import { type VaultClient } from './client.js';
+import { type CheckoutController, type LifecycleOptions, type PaymentEndpointGuard } from './lifecycle.js';
 /**
  * The CORS headers a fulfilled CROSS-ORIGIN request needs, or null when the
  * request is same-origin (or carries no Origin, so no CORS check applies).
@@ -63,14 +64,14 @@ export declare function corsDecision(url: string, requestHeaders: Record<string,
  */
 export declare function withCorsHeaders(headers: Record<string, string>, cors: Record<string, string> | null): Record<string, string>;
 /**
- * Minimal shape of a CDP connection. Works with a raw websocket client, a
- * Puppeteer CDPSession, or Playwright's CDPSession.
+ * Browser-level, session-aware CDP connection. A page-scoped Playwright or
+ * Puppeteer CDPSession is NOT this interface; use attachToPlaywright for those.
  */
 export interface CdpLike {
     send(method: string, params?: any, sessionId?: string): Promise<any>;
     on(handler: (method: string, params: any, sessionId?: string) => void): void;
 }
-export interface AttachOptions {
+export interface AttachOptions extends LifecycleOptions {
     vault: VaultClient;
     user: string;
     merchant: string;
@@ -84,6 +85,10 @@ export interface AttachOptions {
      */
     amountCents?: number;
     currency?: string;
+    cardId?: string;
+    timeoutMs?: number;
+    /** Explicit payment endpoints to block if the registry cannot handle their method/format. Unlisted traffic is untouched. */
+    paymentEndpoints?: readonly PaymentEndpointGuard[];
     onApprovalUrl?: (url: string) => void;
     onEvent?: (e: {
         type: string;
@@ -111,7 +116,7 @@ export interface AttachOptions {
  * match. Patterns are resolved once, at attach, so every nested target ends up
  * armed identically.
  */
-export declare function attachToCdp(cdp: CdpLike, pageSessionId: string, opts: AttachOptions): Promise<void>;
+export declare function attachToCdp(cdp: CdpLike, pageSessionId: string, opts: AttachOptions): Promise<CheckoutController>;
 /**
  * Playwright convenience wrapper — the path for cloud browsers that hand you a
  * CDP websocket (Kernel's `cdp_ws_url`, Browserbase, etc.):
@@ -123,4 +128,4 @@ export declare function attachToCdp(cdp: CdpLike, pageSessionId: string, opts: A
  * Uses Playwright's own request routing, which already spans subframes — see
  * the note in the body for why a hand-rolled CDPSession does not work here.
  */
-export declare function attachToPlaywright(page: any, opts: AttachOptions): Promise<void>;
+export declare function attachToPlaywright(page: any, opts: AttachOptions): Promise<CheckoutController>;

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,19 @@ 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';
+}
 /**
  * Take over card tokenization for a page.
  *
@@ -288,6 +302,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;
@@ -300,25 +317,34 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     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);
         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 === '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;
@@ -327,14 +353,20 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return;
         const { requestId, request, resourceType } = 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 +374,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         // requests can never both clear the check above and raise two prompts for
         // one checkout.
         awaitingApproval = true;
+        let handoffStarted = false;
         try {
             const body = pausedBody(request);
             if (body === null) {
@@ -361,15 +394,24 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 return;
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}) } });
+            lifecycle.begin();
             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,
+                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                onApprovalUrl: (url) => { lifecycle.approvalUrl(url); return opts.onApprovalUrl?.(url); },
                 request: { url: request.url, method: request.method, headers: request.headers, body },
             });
+            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
@@ -396,9 +438,11 @@ 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);
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
@@ -418,20 +462,24 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 }, sessionId);
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
+            lifecycle.handedOff(replay);
         }
         catch (err) {
+            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 {
             awaitingApproval = false;
+            lifecycle.end();
         }
     });
     await arm(pageSessionId);
+    return lifecycle;
 }
 /**
  * Playwright convenience wrapper — the path for cloud browsers that hand you a
@@ -445,6 +493,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
@@ -467,11 +523,16 @@ export async function attachToPlaywright(page, opts) {
     // 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 +540,14 @@ 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;
+        let handoffStarted = false;
         try {
             const body = request.postData() ?? '';
             if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
@@ -493,15 +555,24 @@ export async function attachToPlaywright(page, opts) {
                 return await route.abort('aborted');
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
+            lifecycle.begin();
             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,
+                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                onApprovalUrl: (url) => { lifecycle.approvalUrl(url); return opts.onApprovalUrl?.(url); },
                 request: { url: request.url(), method: request.method(), headers: request.headers(), body },
             });
+            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.
@@ -515,7 +586,9 @@ 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 });
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
@@ -526,17 +599,21 @@ export async function attachToPlaywright(page, opts) {
                 await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
+            lifecycle.handedOff(replay);
         }
         catch (err) {
+            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 route.abort('aborted');
         }
         finally {
             awaitingApproval = false;
+            lifecycle.end();
         }
     });
+    return lifecycle;
 }

package/dist/client.d.ts

@@ -133,6 +133,10 @@ 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;
+    /** 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 +145,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 +156,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);
 }