@agent-cards/checkout 0.2.0 → 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,14 +121,15 @@ 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 |
 | Adyen | supported (mode `cse`): the vault encrypts the card for Adyen on the cardholder's device and your browser sends it |
 | Tranzila | supported (mode `hosted_form`): the cardholder finishes on Tranzila's own page; the paused form navigation resolves to a synthetic page, and you poll the merchant's order state |
 
@@ -146,7 +150,20 @@ three; the difference matters if you drive `authorize()` yourself.
 
 - **`token`** (every processor but Adyen). The cardholder's device calls the
   processor and reports its answer; `authorize()` resolves with `status`,
-  `headers` and `body` to fulfill the paused request with.
+  `headers` and `body` to fulfill the paused request with. The browser checks
+  a fulfilled answer exactly as it checks a real one, so when the page called
+  the processor cross-origin (Stripe always does: Checkout on
+  `checkout.stripe.com` and Elements in the `js.stripe.com` frame both fetch
+  `api.stripe.com`) the answer must carry `access-control-allow-origin` for
+  the request's own `Origin`, or the page's fetch rejects and the checkout
+  reports a connection error even though the cardholder approved. The
+  adapters add those headers (`corsHeadersFor` + `withCorsHeaders`, exported
+  for a runtime that fulfills by hand, and `corsDecision` when you also want
+  the reason) and report the decision on the `authorized` event as `cors`:
+  `echoed`, `same_origin`, or `none` (no usable Origin on the request, so
+  the page could not read the answer). Only what a browser serializes is
+  echoed: one canonical http(s) origin, or the opaque `null`. Shopify's
+  card iframe posts to its own origin, so it never needed them.
 - **`cse`** (Adyen). Adyen's own page SDK encrypts the card before the request
   leaves the browser, so the paused body carries ciphertext. The cardholder's
   device produces the same ciphertext under the merchant's Adyen public key
@@ -199,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:
@@ -210,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
@@ -262,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.
@@ -278,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,13 +1,77 @@
 import { type VaultClient } from './client.js';
+import { type CheckoutController, type LifecycleOptions, type PaymentEndpointGuard } from './lifecycle.js';
 /**
- * Minimal shape of a CDP connection. Works with a raw websocket client, a
- * Puppeteer CDPSession, or Playwright's CDPSession.
+ * 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).
+ *
+ * The browser checks a fulfilled response exactly as it checks a real one. A
+ * page that fetches a processor on another origin therefore needs
+ * `access-control-allow-origin` on the synthetic answer, or its fetch rejects
+ * with "Failed to fetch" and the page never sees the processor's reply, even
+ * though the cardholder approved and the processor answered the vault.
+ * Shopify never hit this on its current host: the checkout.pci.shopifyinc.com
+ * card iframe posts to its own origin (its older deposit.<region>.shopifycs.com
+ * host is called from the checkout.shopifycs.com frame, cross-origin, and gets
+ * the answer like everyone else). Stripe hits it on every surface (Checkout on
+ * checkout.stripe.com or a merchant domain, and Elements in the js.stripe.com
+ * frame, all call api.stripe.com), and so does every other processor whose
+ * card frame calls a separate API host. Observed live on
+ * 2026-09-03: the vault replayed a Stripe PaymentMethod into a raw-CDP
+ * runtime, the browser refused the answer for want of this header, and
+ * Stripe Checkout showed "We are experiencing connection issues".
+ *
+ * The exact Origin is echoed rather than `*`: a credentialed request refuses
+ * `*`, the echo satisfies both. The processor's own value can never reach
+ * this adapter (a browser does not expose that header to the page that
+ * replayed the call), so whatever the replay carries under these names is
+ * replaced by the one value that is right for THIS request. Playwright adds
+ * the same headers inside route.fulfill when a cross-origin fulfill carries
+ * none (microsoft/playwright#12929), which is why attachToPlaywright never
+ * needed this; it writes them itself anyway, replacing a stale value, so both
+ * adapters answer the vault's replays identically.
+ *
+ * This widens nothing. A tokenization endpoint is built for anonymous
+ * browsers and answers every origin (`access-control-allow-origin: *` on
+ * Stripe's and Shopify's own replies), so the page that made the request
+ * could always read the processor's answer to it; the replay is made exactly
+ * as visible, to exactly that page. Whether a card goes anywhere at all is
+ * decided by the cardholder on the approval screen, never by this header.
+ *
+ * Only what a browser serializes is ever echoed: one canonical http(s)
+ * origin (`new URL(origin).origin === origin`), or the opaque `null` a
+ * sandboxed or data: document sends, which Chrome matches against
+ * `access-control-allow-origin: null` and which Playwright echoes too. That
+ * refuses userinfo, a path, an explicit default port, several origins in one
+ * value, or a control character that would break the fulfill after the
+ * cardholder already approved. Anything refused simply gets no CORS answer,
+ * which is what every fulfill got before this existed.
+ */
+export declare function corsHeadersFor(url: string, requestHeaders: Record<string, string> | undefined): Record<string, string> | null;
+/** How a fulfill was answered, reported on the `authorized` event so a silent CORS failure is diagnosable from events alone. */
+export type CorsOutcome = 'echoed' | 'same_origin' | 'none';
+/** The CORS answer and its reason: `none` when no usable Origin was sent (or the url is not http(s)), `same_origin` when no check applies. */
+export declare function corsDecision(url: string, requestHeaders: Record<string, string> | undefined): {
+    headers: Record<string, string> | null;
+    outcome: CorsOutcome;
+};
+/**
+ * `headers` with the CORS answer for this request written in; the object
+ * itself when none is needed. Any header the answer names is replaced
+ * whatever its case, so a name is never sent twice. The answer varies by
+ * Origin, and a `vary` the replay already carries is extended rather than
+ * replaced (or left alone when it already covers Origin or is `*`); a `vary`
+ * the answer itself names is taken as given.
+ */
+export declare function withCorsHeaders(headers: Record<string, string>, cors: Record<string, string> | null): Record<string, string>;
+/**
+ * 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;
@@ -21,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;
@@ -48,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.):
@@ -60,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>;