@agent-cards/checkout 0.18.0 → 0.21.0

package/README.md

@@ -1,675 +1,12 @@
 # @agent-cards/checkout
 
-Let your browser agents pay with **the user's own card**, without your
-infrastructure ever touching card data.
-
-Your agent drives checkout normally. When the page tries to tokenize a card, we
-pause that one request, ask the cardholder to approve on their device, and their
-device supplies the card and calls the merchant. You get back the response to
-replay. A real card never enters your process, your logs, or your network.
-
-```
-your agent ──drives──> merchant checkout
-                            │ tokenization request
-                            ▼
-                    [ paused by this SDK ]
-                            │  template only, dummy card
-                            ▼
-                  Agentcard ──notify──> cardholder's device
-                                             │ decrypts card locally
-                                             ▼
-                                     merchant's card vault
-                            ┌────────token────────┘
-                            ▼
-                    [ request resumed ]  ──> order completes
-```
-
-## Install
-
-```bash
-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.
-
-To inspect a checkout before card entry with SDK `0.9.0` or later, read [Check checkout support](./PREFLIGHT.md).
-The read-only helper detects all 23 registered PSPs and reports processor support separately
-from an identified checkout flow. Kernel native coverage requires its own capability profile.
-
-## Use it
-
-Two lines against a CDP session you already have:
-
-```ts
-import { VaultClient, attachToCdp } from '@agent-cards/checkout';
-
-const vault = new VaultClient({
-  clientId: process.env.AGENTCARD_CLIENT_ID!,
-  clientSecret: process.env.AGENTCARD_CLIENT_SECRET!,
-});
-
-// Pull the current processor list. attachToCdp arms the browser from it, so
-// without this you only intercept the processors built into your installed
-// version. Safe to call on every run: a failed fetch keeps the built-ins.
-await vault.syncRegistry();
-
-await attachToCdp(cdp, pageSessionId, {
-  vault,
-  user: 'usr_123',                 // whose card should pay
-  merchant: 'vanman.shop',
-  amount: 583,                     // your hint, an integer in the currency's smallest unit (or a decimal string: '5.83')
-  currency: 'usd',                 // "$5.83" is derived for the approval screen
-  onApprovalUrl: (url) => sendToUser(url),   // SMS, push, email, iMessage: your call
-});
-```
-
-`amount` is your hint: an integer in the currency's smallest unit (583 for
-$5.83), or a decimal string in normal units ('5.83'), with `currency`. The
-processor's own amount is the higher authority: Agentcard reads it from the
-paused request where the processor puts it there, or from the Stripe intent
-the request names, right before the cardholder's device replays, and the
-company's caps are judged on it. A hint lets a bad purchase be refused the
-moment it opens; a hint more than one smallest unit away from the processor's
-amount is refused with nothing charged (`AmountMismatchError`), and after the
-replay the charge is reconciled against the approval
-(`ReplayResponse.amountVerified`, `chargedAmount`, and `chargedKind`:
-`captured` for a succeeded intent's `amount_received`, `authorized` for a
-manual-capture intent's `amount_capturable`, `none` when nothing is collected
-yet; plus the `checkout_authorization.amount_mismatch` webhook to your server
-when the charge disagreed). Every result carries `amountAuthority`:
-`processor`, `agent`, `page`, or `none`. A display string is never sent;
-Agentcard derives it.
-
-Then let your agent click "Pay" like it always does. `attachToCdp` pauses the
-request for approval. Merchant timeouts still apply to the request itself: Square's observed tokenization deadline
-is about 10 seconds, Braintree's native request timeout is 60 seconds, and Adyen Web's own request timeout abandons its Sessions payment call 60 seconds after Pay (observed on Adyen Web 6.41 and 6.44), each including approval and handoff. These are the processors' limits, not ones the SDK enforces: the SDK's own authorization wait stays 15 minutes.
-
-The approval outlives the page's own request. When the page's script gives up on its paused card request while the cardholder is still deciding, the SDK keeps the approval pending (state `awaiting_approval`, reason `merchant_request_lost`, event `merchant_request_lost`) and answers the page's next request for the same purchase from it: same endpoint, same method, same top-level document, same page total, and a body of the same shape carrying the same card placeholder and the same amount when the request names one. An amount has to be in evidence somewhere (your `amount` hint, a `pageAmount` reader, or the request's own bytes); with none, a retry is a new question and the approval is retired unused. Braintree's client re-issues its mutation on its own within a second; on other processors the agent clicks Pay again. If the approval lands before the page asks again, the controller reads `ready_to_submit` with reason `awaiting_merchant_retry` (event `approval_awaiting_merchant_retry`): click Pay once, and that request is answered with no second prompt on the phone. The wait for that request is bounded (`merchantRetryWaitMs`, two minutes by default, never past the approval window); when it ends with no request, the SDK retires the approval through the API with reason `merchant_never_retried`, the controller reads `declined` with that reason, nothing was charged, and the cardholder's approval page says so. This applies to `token` and `cse` checkouts; a hosted form, a prepared checkout and a native Stripe Checkout step keep the behaviour below. For human approval on a short-deadline processor, `controller.prepare()` before the first Pay action, shown below, still finishes the request inside its own deadline. For Adyen, `prepare()` moves the approval before Pay, so only the device-side encryption runs inside Adyen Web's minute.
-
-Playwright:
-
-```ts
-import { attachToPlaywright } from '@agent-cards/checkout/playwright';
-await attachToPlaywright(page, { vault, user, merchant, amount });
-```
-
-## Credentials
-
-Use your **OAuth client credentials**, not an `sk_` API key — those are retired,
-and the checkout endpoints reject them (`client_credentials_required`) because an
-authorization is bound to the confidential client that created it. The SDK does
-the `client_credentials` exchange for you, caches the token, and refreshes it
-once on a 401. Create a client from the dashboard Credentials page or with
-`agent-cards-admin oauth-clients create`.
-
-## Why you need the SDK and not just `Fetch.enable`
-
-Card fields render in **cross-origin iframes**, which are separate CDP targets.
-Enabling `Fetch` on the page session never sees the tokenization request. You
-need recursive `Target.setAutoAttach({ flatten: true })` on every nested target,
-then `Fetch.enable` on each, then `Runtime.runIfWaitingForDebugger` to unpause
-them. That, plus which headers a merchant requires you to replay verbatim, is
-what this package encapsulates.
-
-## What runs where
-
-| | Sees the real card |
-|---|---|
-| Your agent / browser | **no** — only a dummy PAN and a token |
-| Agentcard servers | **no** — a request template and a token |
-| Cardholder's device | yes — decrypts locally, calls the merchant directly |
-
-Because your process only ever handles a dummy card and an opaque token, this
-integration is designed to keep you out of PCI scope. Get your own QSA's read
-before you put that in writing.
-
-## Supported processors
-
-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 | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms read the intent's amount back from Stripe; a hint sent as `amount` + `currency` must agree with it. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
-| Braintree card tokenization | Prepared checkout supported; one live Haymarket Books ebook purchase with SDK `0.5.0` confirmed merchant fulfillment and SDK `completed` using a merchant receipt resolver. Independent processor capture/settlement, live 3DS and PayPal wallet flows remain unverified. |
-| Checkout.com | supported |
-| Mercado Pago | Card tokenization and prepared checkout are implemented. Guest Checkout Pro in Mexico also corrects the issuer for one native card association when the selected card has the same brand and type. One live MXN 40 Lotería Chida purchase with published SDK 0.10.0 completed automatically through Pay; the merchant confirmed paid status and PDF fulfillment. The historical SDK result remains unknown because the private receipt adapter rejected a relative download URL; a separate read with the corrected adapter confirms that same paid receipt. Independent processor capture/settlement and other country or integration paths remain unverified. |
-| 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. Sessions flow only: the paused request is `/checkoutshopper/v1/sessions/{id}/payments` on Adyen's own hosts; a merchant that posts the encrypted fields to its own server is not recognized, so nothing pauses there. Without a preparation, approval starts at Pay and must land before Adyen Web's own request timeout (observed at 60 seconds on Adyen Web 6.41 and 6.44; not enforced by the SDK); `prepare({ psp: 'adyen' })` moves the approval before Pay |
-| 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 |
-
-The recognizer list is fetched from the API at runtime (`vault.syncRegistry()`),
-so new processors work without you shipping a release. `attachToCdp` derives the
-`Fetch.enable` url patterns from that same list rather than a constant, which is
-why the sync call belongs before the attach. `vault.cardUrlPatterns()` returns
-those patterns if you arm a CDP connection yourself. Call
-`GET /v2/checkout/recognizers?modes=token,cse,hosted_form` for the list that is
-live right now.
-
-## Modes
-
-Each recognizer carries a `mode` (absent means `token`), and every authorization
-carries the mode it was handled in. The adapters do the right thing for all
-three; the difference matters if you drive `authorize()` yourself.
-`ReplayResponse` is a union, so branch on `mode`.
-
-- **`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. 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
-  (fetched by Agentcard from Adyen's host when the request is parked) and
-  `authorize()` resolves with `substitutions: { encoding: 'json', at, fields,
-  remove }`. Write them into the paused body with
-  `substituteEncryptedFields(body, substitutions)` and CONTINUE the request
-  from the same browser (`Fetch.continueRequest` with the rewritten
-  `postData`, or Playwright's `route.continue({ postData })`): its session
-  data, risk data and cookies must stay its own. Only the four encrypted
-  fields change, and the siblings named in `remove` are dropped (Adyen's
-  `brand`, which adyen-web derived from the dummy digits the agent typed:
-  left in place it names the wrong card and Adyen refuses the mismatch;
-  absent, Adyen reads the brand off the card it decrypts). A body that lacks
-  the fields throws `SubstitutionError`, which is not terminal. Adyen answers the browser,
-  so `charged_kind` is null on the approval and the merchant's order state is
-  the outcome to poll.
-- **`hosted_form`** (Tranzila). The processor's hosted card form submits the
-  card as a TOP-LEVEL form post, so the paused request is a page navigation
-  (the adapters arm `Fetch.enable` with no resource-type filter and attach the
-  processor's iframe, which is how a Document request on `direct.tranzila.com`
-  gets paused at all). The cardholder's device rebuilds that form with the
-  real card and submits it itself; the processor answers the device, and
-  `authorize()` resolves with `{ mode: 'hosted_form', kind:
-  'submitted_on_device', outcome: 'unverified', submittedAt }` once the
-  device reports the form left. **This is not an approved payment.** The
-  stamp is the cardholder's device attesting that the form left it;
-  Agentcard holds no processor evidence on this mode and cannot obtain any,
-  so the API finishes the authorization as `submitted_on_device` (never
-  `approved`) and sends your server `checkout_authorization.submitted`
-  (never `.approved`). Treat it as "the person paid, or tried to, on their
-  own device" and confirm the order with the merchant before you count it.
-  There is no response to replay: FULFIL the paused navigation with
-  `hostedFormSubmittedPage({ authorizationId, merchant, submittedAt })` (200,
-  `text/html`, `x-agentcard-checkout: submitted_on_device`, a `<meta
-  name="agentcard-checkout">` and an inert JSON block saying "submitted on
-  the cardholder's device, payment unverified, do not resubmit"), the way
-  the adapters do. Do not abort it: an aborted navigation renders nothing,
-  the iframe silently keeps its dummy-card form, and the agent's next move is
-  to click Pay again. Do not fake the processor's result page either: this
-  SDK does not know the outcome. The adapters emit `submitted_on_device` (not
-  `authorized`), refuse a byte-identical re-post of the same form for 15
-  minutes (`hostedFormRepeatQuietMs`), and the API answers a regenerated one
-  with `409 duplicate_submission`, which the adapters quiet the way they quiet
-  a decline (`approvalCooldownMs`): the page's immediate re-posts are refused
-  without a round trip, and once the prior authorization is declined or
-  expired the same form is a new question. Confirm the order with the
-  merchant, which learns the outcome from the processor.
-
-`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.
-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:
-'unverified'`; it is not an `authorized` event and must not be counted as
-one. `amountAuthority` on every replay is `stripe_payment_intent`,
-`hosted_form_sum` (the form's own amount) or `display_only`.
-
-## Errors worth handling
-
-- `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
-  `ApprovalDeclinedError` with `expectedCents`, `actualCents`, `currency`,
-  `code: 'amount_mismatch'` and `stage`: `'pre_replay'` (checked right before
-  the device would have sent the card; `authorizationId` names the declined
-  authorization) or `'create'` (the intent already disagreed when the request
-  was parked; no authorization exists, `authorizationId` is null). Per
-  request, not per page: a merchant can still update an intent's amount
-  until it is confirmed, so the adapters quiet the page's immediate retry
-  and judge the next request afresh instead of latching.
-- `IntentNotConfirmableError`: the PaymentIntent was already charged, is
-  processing, or is authorized and on hold (or canceled), so Agentcard
-  refused to replay a confirm at it. An `ApprovalDeclinedError` with
-  `code: 'intent_not_confirmable'`. Deliberately not "nothing was charged":
-  check the intent at Stripe before retrying.
-- `ProcessorRefusedError`: the cardholder's device reported a processor
-  request rejection. `pspErrorCode` carries the processor's code; optional
-  `processorError` carries bounded Razorpay reason, source, step and payment/order
-  identifiers when the API has them. A generic code such as `BAD_REQUEST_ERROR`
-  does not establish an issuer decline or prove no money moved. Reconcile the
-  merchant payment before retrying. This remains an `ApprovalDeclinedError`
-  with `code: 'processor_refused'` for compatibility.
-  The attachment records `status: 'declined', reason: 'processor_refused'`
-  and holds further card requests. After confirming merchant failure, call
-  `retryAfterMerchantFailure({ status: 'failed' })` to permit a deliberate new
-  attempt immediately, without waiting for the user-decline cooldown. Do not
-  automatically create a new attachment after this error;
-  the guard applies only within the existing attachment.
-- `CheckoutApiError` with `code === 'amount_unverifiable'`: Stripe could not
-  be asked (502; the SDK retries twice, 500ms then 1500ms, before throwing)
-  or the paused request lacked its client secret or publishable key (400).
-  `code === 'intent_not_confirmable'` at create (409) means the intent was
-  already used; the adapters stop intercepting for that page.
-  `code === 'cse_key_unavailable'` (502) means Adyen did not answer the
-  public-key fetch and is retried the same way; `cse_client_key_unknown`
-  (400) means Adyen does not know the merchant's `clientKey`, and
-  `cse_template_unsupported` (400) means the paused body carries no
-  encrypted card fields to fill (a stored card, a wallet, a single-blob
-  `encryptedCard`); both are terminal for that page.
-  `hosted_form_template_incomplete` (400) means the paused form lacks a
-  field the device fills or the processor requires, `hosted_form_gated`
-  (400) means it carries a live captcha token the device could never
-  re-submit, and `hosted_form_field_refused` (400, with `field` and a
-  `reason` of `stored_credential`, `not_a_sale` or `callback_host`) means
-  the form asks the processor for something other than one plain sale
-  reporting to the merchant you named (a reusable token in or out, a sale
-  mode that is not a sale, a callback URL off the merchant's host: name the
-  merchant by its hostname when the form carries callback URLs); all three
-  are terminal for that page. `duplicate_submission` (409,
-  with `prior_authorization_id` and `prior_status`) means this exact
-  submission already has, or already had, its prompt: the adapters quiet the
-  page's re-posts for `approvalCooldownMs` (no second notification for one
-  payment) and judge the next request afresh, since the prior authorization
-  declines or expires and the same form is then a new question.
-- `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 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.
-
-## Building this package
-
-It declares **no dependencies**, matching `packages/vault`, so the workspace
-lockfile needs no importer entry for it (a new package with its own deps cannot
-be installed here without regenerating the lockfile, and a full regen drifts
-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.
-
-Await attachment before clicking Pay. Both adapters stop waiting for browser
-setup after 30 seconds and throw `CheckoutAttachmentError` with
-`code: 'checkout_attachment_failed'` and `reason: 'timeout'`, `'closed'` or
-`'unavailable'`. Use `attachmentTimeoutMs` to choose a setup deadline from 1 to
-300000 milliseconds, separately from the approval's `timeoutMs`.
-Close the failed checkout page and create a fresh browser context before
-trying again. A late setup response cannot reopen the failed attachment or
-request approval; intercepted card requests remain blocked. A setup failure
-does not establish the status of any earlier purchase.
-
-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, amount, 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') await finishAgentTask(state);
-```
-
-`resolveMerchantResult` must verify the merchant's result for the original
-payment attempt. It returns one of:
-
-- `{ status: 'completed', orderId }`: merchant-confirmed success with a genuine order or receipt ID. Existing integrations keep this form.
-- `{ status: 'completed', confirmation: { kind: 'merchant_payment', authorizationId } }`: merchant-confirmed payment when no order or receipt ID is available. The ID must match the current checkout authorization.
-- `{ 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.
-
-For a merchant that confirms payment without returning an order ID, your
-resolver can return the explicit payment confirmation:
-
-```ts
-const checkout = await attachToPlaywright(page, {
-  vault, user, merchant, amount, currency,
-  requireMerchantResult: true,
-  resolveMerchantResult: async state => {
-    const payment = await readOriginalMerchantPayment(state);
-    if (!payment.confirmed || !state.authorizationId) return { status: 'unknown' };
-    return {
-      status: 'completed',
-      confirmation: {
-        kind: 'merchant_payment',
-        authorizationId: state.authorizationId,
-      },
-    };
-  },
-});
-```
-
-`readOriginalMerchantPayment` is your merchant-specific check. The check must
-match the original payment request, amount, currency and selected card, and
-verify authoritative merchant success for that attempt. HTTP 200 alone, a card
-token, a success URL or text that anyone can open does not establish payment.
-Copying `state.authorizationId` without checking the payment is insufficient.
-The SDK checks the authorization binding; it does not independently authenticate
-the merchant evidence supplied by your resolver.
-
-Return one completion form at a time. The payment-confirmation form leaves
-`state.orderId` absent and exposes `state.confirmation` with the exported
-`MerchantPaymentConfirmation` type. Your consumer should finish on
-`state.status === 'completed'` and treat `orderId` as optional. A missing or
-mismatched authorization, or `{ status: 'completed' }` without either completion
-form, leaves the outcome unknown. Confirmed completion clears stale failure or
-authentication reasons and continues to block further payment submissions.
-Never invent an order ID from a token or authorization ID.
-
-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.
-
-Native Stripe Checkout emits `checkout_blocked` before the existing `blocked`
-event when its local preparation rejects a request. Its
-`StripeCheckoutBlockedDetail` contains only fixed codes: `version: 1`,
-`processor: 'stripe'`, endpoint family, phase, stage, reason, optional validation code, gate state, and
-disposition. It contains no URLs, identifiers, request-derived field names or values, or exception text.
-
-| Field | Values |
-| --- | --- |
-| `endpoint_family` | `payment_methods`, `payment_page_confirm`, `other` |
-| `phase` | `tokenization`, `final`, `unknown` |
-| `stage` | `request_read`, `classification`, `claim`, `readiness`, `document`, `stub_response` |
-| `validation_code` | Shared-core `StripeCheckoutValidationCode`; present only for `request_validation_failed` |
-| `gate_state` | `fresh`, `stubbed`, `submitted`, `stopped` |
-| `disposition` | `active_claim_preserved`, `checkout_stopped` |
-
-`reason` is the exported `StripeCheckoutBlockReason` union. It identifies SDK
-claim and readiness failures, such as `duplicate_confirmation`, `document_changed`,
-or `attachment_not_ready`. A shared-core rejection reports
-`request_validation_failed` and a fixed `validation_code` identifying the failed
-check, or `unclassified` when no recognized code is available. Initial request
-classification uses phase `unknown`; a billing capture rejection uses
-`tokenization`, and a billing attachment rejection uses `final`.
-For example, `form_field_unknown` identifies an allowlist rejection without
-revealing the field name or value. Identifying that field requires a separate
-reviewed synthetic fixture; the code alone does not establish or fix a processor
-schema mismatch. `gate_state` records the state before the adapter handles
-the failure, though document validation may already have stopped the gate.
-
-`active_claim_preserved` means a valid duplicate was refused without invalidating
-the original request's claim. Do not cancel that checkout in response to the duplicate.
-`checkout_stopped` means the local preparation was retired; reconcile any existing
-authorization before another attempt. Neither disposition proves a payment outcome.
-
-With `requireMerchantResult`, subsequent card requests stay blocked after
-handoff. Stripe tokenization handoffs (`/v1/payment_methods`, `/v1/tokens`,
-`/v1/sources`, `/v1/confirmation_tokens`) 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, and the
-page cannot supply one. The SDK reports `awaiting_merchant` with reason
-`stripe_tokenization_unbound`, while ordinary browser traffic stays available.
-
-One follow-up can continue: the page's own card-free PaymentIntent confirm that
-pays with the approved token (`confirmCardPayment` with `payment_method: 'pm_...'`,
-`confirmPayment` with the confirmation token). The SDK asks the API, which reads
-the payment from Stripe and allows it only for the approved amount and
-currency, on the same Stripe account, paid with exactly the approved token.
-Allowed, the request continues untouched, the SDK emits `stripe_payment_continued`
-and the reason becomes `stripe_payment_continued`. One confirm continues per
-approval; every other follow-up, including an unrelated intent, a changed
-amount and a retry, stays blocked.
-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 `amount` 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.
-
-Worldpay, Bambora and Mercado Pago preparation requires SDK 0.6.0 or later and the matching API and Vault release.
-
-Prepare a Square, Braintree, Worldpay, Bambora or Mercado Pago checkout before the first Pay action so the cardholder can approve before the native card request starts. The API and Vault deployments must support the selected processor:
-
-```ts
-const checkout = await attachToPlaywright(page, {
-  vault, user: 'your-user-id', merchant: 'Example merchant',
-  amount: 100, currency: 'USD',
-  onApprovalUrl: deliverPrivatelyToCardholder,
-});
-const preparation = await checkout.prepare({
-  psp: 'braintree',
-  environment: 'production', // Square, Braintree and Worldpay: production or sandbox
-});
-// The cardholder has consented and unlocked the same approval document.
-// No processor request or payment has started.
-await page.getByRole('button', { name: 'Pay', exact: true }).click();
-```
-
-`prepare()` is available on both Playwright and raw CDP controllers. It requires `amount` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The approval page on the cardholder's device must stay open. Its selected card, merchant origin, declared merchant, amount, currency, processor and environment bind one fresh request. The amount's authority is `agent`; a card token does not enforce the merchant's eventual charge amount.
-
-| Processor | `environment` | Fresh native request |
-| --- | --- | --- |
-| Square | `production` or `sandbox` | Matching Square `/v2/card-nonce` host |
-| Braintree | `production` or `sandbox` | Matching Braintree GraphQL host and guest `TokenizeCreditCard` mutation |
-| Worldpay | `production` or `sandbox` | Matching Access Worldpay host and `/sessions/card` |
-| Checkout.com | `production` or `sandbox` | Fresh guest-card JSON POST to `/tokens` on the matching API or card-acquisition-gateway host |
-| Bambora | `shared` | `/scripts/tokenization/tokens` on `api.bam.shift4api.net` or `api.na.bambora.com` |
-| Mercado Pago | `shared` | `api.mercadopago.com/v1/card_tokens` with a fresh card body |
-| Recurly | `shared` | Form-encoded POST to `/js/v1/token` on `api.recurly.com` or `api.eu.recurly.com` |
-| Spreedly | `shared` | Native iframe JSON POST to `/v1/payment_methods/restricted.json` on `core.spreedly.com` |
-| Adyen | `production` or `sandbox` | The Sessions `/checkoutshopper/v1/sessions/{id}/payments` POST on the matching Adyen host family (`sandbox` is `checkoutshopper-test.adyen.com` with a `test_` client key; `production` is the live hosts with a `live_` key), carrying a fresh card's four encrypted fields |
-
-Use `environment: 'shared'` for Bambora, Mercado Pago, Recurly and Spreedly because the same endpoint serves test and live requests. Agentcard cannot establish the processor's test mode from that URL or a credential prefix. Configure test mode through the merchant's processor account when testing. Agentcard's own `sandbox` flag remains separate. Prepared Worldpay, Bambora, Mercado Pago and Recurly requests reject saved-card and recurring request bodies; a refused request retires the local preparation. Reconcile any existing merchant attempt before creating a new attachment.
-
-Prepare a Checkout.com checkout before the agent clicks Pay:
-
-```ts
-await controller.prepare({ psp: 'checkout_com', environment: 'production' });
-```
-
-Keep the phone approval page open, then click Pay once after readiness. Checkout.com Flow 1.228.0 gives its card iframe 12 seconds to return a token; approval before Pay leaves that interval for request binding and tokenization. Prepared requests must use an exact `/tokens` URL on `api.checkout.com` or `card-acquisition-gateway.checkout.com`, or the corresponding `.sandbox.checkout.com` host for `sandbox`. The request must describe a fresh card with a CVV and public-key authentication. Wallet, saved-card, reusable-token and recurring variants are refused. A native API fallback after the first CAG request cannot reuse approval. Match the actual merchant charge to the approved amount separately; a token does not enforce that amount.
-
-Prepare an Adyen Sessions checkout before the agent clicks Pay:
-
-```ts
-await controller.prepare({ psp: 'adyen', environment: 'production' }); // 'sandbox' for Adyen's test host
-```
-
-After approval, click Pay once. adyen-web encrypts the agent's placeholder digits and posts its Sessions `/payments` request; the SDK pauses it and binds it to the approval, the cardholder's device (still on the approval page) encrypts the approved card under the merchant's Adyen key, and the request continues from your browser with only the four encrypted fields swapped and `brand` dropped. Adyen answers your browser, so the merchant's order state is the outcome to poll. The bound request must be a fresh `scheme` card on the approved host family with a client key of that environment; a stored-card, single-blob or store-the-card request never uses the approval. Adyen Web's own 60-second request timeout then covers only the pause, the bind and the device's encryption.
-
-Prepare a Spreedly checkout before submitting the merchant's card form:
-
-```ts
-await controller.prepare({ psp: 'spreedly', environment: 'shared' });
-```
-
-After approval, submit the form once. The Vault replaces the card fields on your device and sends the native request through an encrypted connection to Spreedly. The merchant's environment and signed session stay unchanged. The API, Vault, relay and preparation migration must support Spreedly before you use this flow; the API refuses preparations while its relay rollout flag is disabled.
-
-Initial coverage includes the hosted iframe's new-card request. Saved-card CVV updates, Express, wallets, bank accounts and gateway purchase APIs require separate support. A returned card token does not confirm payment; wait for the merchant's result before reporting success. Autopilot is unavailable for Spreedly.
-
-Prepare Recurly before clicking the merchant's payment button:
-
-```ts
-await controller.prepare({ psp: 'recurly', environment: 'shared' });
-```
-
-After approval, submit the merchant's form once. Recurly's native request timer starts with that submission. The SDK preserves the captured US or EU endpoint and accepts a new-card form only. Legacy JSONP, saved tokens, bank accounts, alternative payments and proactive authentication requests require separate support. Prepared requests also refuse nonempty Worldpay or Cybersource risk results because those sessions can depend on the original card. A nonempty co-badged network preference is also refused until the selected card’s supported networks can be checked. A card token does not confirm a donation, subscription or purchase; confirm the merchant's result before reporting payment success.
-
-### Use Checkout Pro in Mexico
-
-Attach the SDK before entering card fields on `www.mercadopago.com.mx`, then prepare the guest card checkout:
+The older name of [`@agent-cards/sdk`](../checkout/README.md), Agentcard's SDK. This package re-exports every entry of `@agent-cards/sdk` (`.`, `./cdp`, `./playwright`, `./preflight`) for one release, so an import of `@agent-cards/checkout` keeps working while you rename it. The two JSON files under `./preflight/` are not re-exported: read them from `@agent-cards/sdk/preflight/catalog.json` and `@agent-cards/sdk/preflight/schemas.json`.
 
 ```ts
-await controller.prepare({ psp: 'mercado_pago', environment: 'shared' });
-```
-
-The Vault checks the selected card's issuer using the merchant's current checkout configuration. Your browser receives the processor's original card-token response, and the SDK replaces the issuer in one native card association. The card number, security code and eight-digit prefix stay out of your SDK process. The encrypted relay carries the configuration lookup between the approval device and Mercado Pago.
-
-The selected card must have the same brand and card type as the native form. Missing or ambiguous configuration, changed checkout details, and a repeated card association stop continuation. Start a fresh checkout and approval after resolving the mismatch. Final Pay and merchant confirmation still follow your existing checkout integration.
-
-Use the matching SDK, API, Vault and relay releases together. The issuer correction covers the observed guest Checkout Pro flow in Mexico. CardForm or Bricks on merchant websites, other countries, installment changes and Autopilot need separate validation. Successful tokenization and issuer association do not establish a paid order; keep `requireMerchantResult` and a merchant receipt resolver when validating a purchase.
-
-Braintree's native `ClientConfiguration` GraphQL query can run before, during or after preparation without using the approval. Only a single `TokenizeCreditCard` mutation can consume the prepared Braintree checkout. Prepared requests require guest card tokenization with explicit `options.validate: false`; omitted validation options, saved-card fields and `validate: true` are refused. Other GraphQL operations, batches and compound mutations are blocked. Braintree's legacy REST fallback cannot consume a prepared authorization.
-
-Readiness lasts up to 30 seconds (`preparation.expiresAt`) and appears as `ready_to_submit`, with `paymentStatus: 'not_started'`. Trigger the caller-owned Pay action immediately after the promise resolves. Expiry, navigation, cancellation, an early request or a changed checkout fails closed. A preparation and its attachment are single use; reconcile any bound authorization before creating a new attachment. The SDK never clicks Pay, reuses a stale request, changes native request deadlines, or automatically retries a failed prepared checkout.
-
-After Pay, the processor's native deadline still covers fresh authorization binding, device replay and token handoff. A disconnected or backgrounded cardholder device, or a slow transport, can still miss it. A subsequent SCA challenge has its own lifetime after token handoff. If the page's own script abandons an unprepared `token` or `cse` request while the cardholder decides, the approval survives and answers the page's next request for the same purchase (see "The approval outlives the page's own request" above). If the frame that sent the request is removed, the document moves to another URL, the page closes or crashes, or a prepared request is abandoned, the attachment blocks further requests and tries to retire the pre-replay authorization; a started replay or unconfirmed cancellation remains unknown. Without `prepare()`, approval loading and human interaction still share the native deadline, so a delayed approval finishes the page's retry rather than its first request.
-
-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
+// before
+import { VaultClient } from '@agent-cards/checkout';
+// after
+import { Agentcard } from '@agent-cards/sdk';
 ```
 
-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. These suites use an
-in-process Agentcard API fixture and loopback merchant pages. The preparation
-fixture denies all external traffic and waits beyond each modeled request deadline before any card request: eleven seconds for Square, sixty-one seconds for Braintree, and six and a half seconds for Worldpay, Bambora and Mercado Pago. Each fixture then checks one fresh request with an unchanged abort timer. The five-second timer matches the inspected Worldpay and Bambora source; the Mercado Pago timer is a test boundary, not a measured native deadline. The fixture exercises SDK ordering with native-shaped request bodies and synthetic responses, not processor acceptance. 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.
-### Autopilot execution metadata
-
-When the cardholder has enabled an eligible spending rule in their vault, the same authorization can run through autopilot. The SDK keeps polling the existing authorization and returns optional `executionMode: 'autopilot' | 'user_approval'` and `grantId` metadata. Older API responses remain supported.
-
-`authorize()` accepts optional `executionMode` and `grantId` routing hints, sent as `execution_mode` and `grant_id`. These never establish permission to spend; the protected payment service checks the cardholder's signed rule. Autopilot suppresses `onApprovalUrl` while it is executing. A definite fallback to user approval delivers the existing authorization's URL once. A lost outcome remains `PaymentOutcomeUnknownError`; it does not create or submit a second payment.
-
-Use `executionMode: 'user_approval'` to require the existing confirmation flow. Without a selected card or grant, the backend can use exactly one eligible rule; ambiguous card selection keeps confirmation. A `grantId` restricts selection to that rule. The initial executor supports only the configured controlled Stripe test flow, and production remains disabled.
-
-For controlled hosted Stripe Checkout, both attachment functions accept `stripeCheckout: { sessionId, publishableKey, environment? }`. The default is TEST, requiring `cs_test_` and `pk_test_`. LIVE requires explicit `environment: 'production'`, a `cs_live_` Session and its `pk_live_` key. Both modes require `executionMode: 'autopilot'`, an explicit `grantId`, and a positive numeric USD `amount` in cents. The top-level document must be that exact Session on `https://checkout.stripe.com`, at `/c/pay/{sessionId}`, `/pay/{sessionId}`, `/g/pay/{sessionId}`, or `/f/pay/{sessionId}`. The SDK validates the existing URL without rewriting or navigating it. Direct `authorize()` calls use `stripeCheckoutEnvironment: 'production'` for the same explicit LIVE opt-in; the attachment functions pass it automatically.
-
-The SDK answers dummy-card tokenization locally, then sends the browser's final native confirmation through the shared core and enclave. The local response is preparation only: it creates no authorization and makes no processor request. The final result includes `checkoutSessionId` only after the selected grant, restricted terminal response, and captured amount have been checked. Continue to confirm the merchant order through the checkout controller.
-
-When Agentcard reports `autopilot_status: action_required` for the same authorization and grant, the SDK stops waiting and calls `onUserAction` with `reason: 'other'` and the authorization ID. The checkout controller records `requires_user_action` and holds further card requests. A direct `VaultClient.authorize()` call rejects with `PaymentOutcomeUnknownError` and reason `autopilot_action_required`. The existing authorization and reservation remain held; the SDK does not cancel or create another payment, return a processor payload, or infer a 3DS challenge. Your application's `resolveMerchantResult` can report the authoritative outcome of this same payment through `reconcile()`. Challenge execution and automatic continuation are not provided by this status report.
-
-The shared core carries a validated billing email from that tokenization request into the final confirmation before authorization. The email stays bound to the same Session and local PaymentMethod reference. Missing email stays missing; duplicate or conflicting values are refused. The SDK does not fill an email from the Agentcard account or invent one for the merchant.
-
-This integration requires matching backend and measured executor releases. TEST and LIVE have separate admission controls. LIVE also requires a newly authorized production grant on the selected real card, a fixed merchant account/profile with exactly one complete fixed-price USD line item and an independently reviewed operation qualification reference; the SDK option supplies none of these. LIVE deployment remains unqualified and disabled until that evidence exists. Exact observed totals do not establish atomic amount enforcement by Stripe. Subscriptions, saved-card flows and authentication continuations remain excluded. An unavailable preparation or uncertain result is declined or held for reconciliation; it cannot switch to a competing human-approval payment.
-
-The adapters also send the observed top-level HTTPS `merchantOrigin`, such as `https://shop.example`, without a path, query or trailing slash. Direct `authorize()` callers can supply that origin explicitly. It is a routing hint; the protected adapter independently verifies the processor account, payee and amount. If a browser cannot provide its top-level URL, an explicit `merchantOrigin` option can supply the hint; otherwise the regular approval path remains available.
+`VaultClient` constructs the same client as `Agentcard` and stays for the same one release.