@agent-cards/checkout 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.3.1
+
+- Detect a merchant request abort or owning frame/page closure while approval is pending. The attachment holds an unknown outcome and blocks automatic retries; an expired request is never reported as an authorized handoff.
+- Retire pending authorizations through the org-scoped cancellation endpoint when the merchant request disappears. Cancellation can win only before the processor-send boundary; started or completed replay remains unknown to this operation. A late creation response is drained so its authorization ID can be cancelled without exposing another approval link.
+- Square token mode uses the vault's verified browser TLS relay. The relay keeps TLS termination and card plaintext on the cardholder device and Square. SDK 0.2.1 can complete a prompt approval but does not contain the native-timeout lifecycle fixes; upgrade to 0.3.1 for Square checkout.
+- Square's native tokenization request still expires after about 10 seconds, including approval and token handoff. Delayed approval cannot complete that checkout; a later SCA challenge has its own lifetime after handoff. This release does not extend the deadline or retry a payment after timeout. Reconcile the merchant outcome and explicitly begin another checkout when required.
+
+## 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 [migration notes](./CHANGELOG.md), especially
+the unknown-outcome, cancellation and browser-context requirements.
+
 ## Use it
 
 Two lines against a CDP session you already have:
@@ -76,8 +79,11 @@ Stripe's minor units, so the approval screen, the notifications and every
 read show one amount. Tokenization requests carry no amount, so there the
 pair is shown and reported (`amountAuthority: 'display_only'`), not enforced.
 
-Then let your agent click "Pay" like it always does. `attachToCdp` holds the
-request open until the cardholder approves, so the checkout simply continues.
+Then let your agent click "Pay" like it always does. `attachToCdp` pauses the
+request for approval and resumes it only while the merchant request remains
+live. Merchant timeouts still apply: Square's observed tokenization deadline
+is about 10 seconds for approval and token handoff, so delayed approval cannot
+complete that checkout.
 
 Playwright:
 
@@ -118,12 +124,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 +219,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 +231,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 +282,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 +299,169 @@ 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.
+
+Square saved-card checkout requires SDK 0.3.1 for merchant-request lifetime handling. Its observed native tokenization request expires after about 10 seconds, including approval-page loading, unlocking, approval, relay and token handoff. An approval that exceeds this window cannot finish that checkout. A subsequent SCA challenge has its own lifetime after the token handoff. This SDK does not pause Square's timers or automatically retry an expired checkout. If the merchant request aborts or its frame closes, the attachment blocks further card requests and tries to retire a pre-replay approval. A started replay or unconfirmed cancellation remains unknown. General delayed human approval is not supported by this Square flow.
+
+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>;