@agent-cards/checkout 0.1.0 → 0.2.1

package/README.md

@@ -42,15 +42,40 @@ const vault = new VaultClient({
   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: '$5.83',
+  amountCents: 583,                // what the user approves, smallest currency unit
+  currency: 'usd',                 // "$5.83" is derived for the approval screen
   onApprovalUrl: (url) => sendToUser(url),   // iMessage, SMS, push, your call
 });
 ```
 
+`amount: '$5.83'` (a display string) still works on its own. Pass
+`amountCents` + `currency` when you want the amount enforced: on a Stripe
+PaymentIntent confirm, Agentcard reads the intent back from Stripe at create
+and again right before the cardholder's device replays, a different amount is
+refused with nothing charged, and after the replay the charge is reconciled
+against the approval (`ReplayResponse.amountVerified`, with
+`chargedAmountCents` 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 it
+disagrees). Amounts are Stripe minor units up to 2^53-1. `onEvent` payloads
+name URLs by origin and path only, so a client secret in a paused request's
+query string never reaches your telemetry. When you pass the pair, any
+`amount` string you also pass is
+ignored: Agentcard derives the display string from the number, following
+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.
 
@@ -101,18 +126,161 @@ Merchants inherit their processor, so one entry covers every store on it.
 | Stripe | supported, verified end to end |
 | Braintree / PayPal | supported, verified end to end |
 | Checkout.com | supported |
-| Adyen | not yet — the card is encrypted in-page, so a paused request carries a blob. Throws `CardEncryptedError` |
+| 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 |
 
 The recognizer list is fetched from the API at runtime (`vault.syncRegistry()`),
-so new processors work without you shipping a release.
+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.
+An approval in some other mode throws `UnsupportedModeError`, which is
+terminal for that page (upgrade the SDK). 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 user never approved. Default window is 15 minutes;
   we have completed checkouts after a 5.5 minute approval delay.
 - `ApprovalDeclinedError` — the user said no.
-- `CardEncryptedError` — this processor needs vault-side crypto; route the
-  purchase to an Agentcard-issued card instead.
+- `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 sent the card and the
+  processor refused it outright (`pspErrorCode` is the processor's own code,
+  such as Stripe's `card_declined`). Nothing was charged. An
+  `ApprovalDeclinedError` with `code: 'processor_refused'`; the page's next
+  attempt raises a fresh approval where the person can pick another card.
+- `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 approval came back in a mode this build of the
+  SDK cannot finish. Terminal for the page; upgrade.
+- `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
 
@@ -122,5 +290,5 @@ be installed here without regenerating the lockfile, and a full regen drifts
 unrelated transitive versions). Build it with the workspace TypeScript:
 
 ```bash
-pnpm --filter backend exec tsc -p packages/checkout/tsconfig.json
+cd packages/checkout && pnpm build && pnpm test
 ```

package/dist/cdp.d.ts

@@ -1,4 +1,67 @@
-import type { VaultClient } from './client.js';
+import { type VaultClient } from './client.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).
+ *
+ * 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>;
 /**
  * Minimal shape of a CDP connection. Works with a raw websocket client, a
  * Puppeteer CDPSession, or Playwright's CDPSession.
@@ -11,12 +74,25 @@ export interface AttachOptions {
     vault: VaultClient;
     user: string;
     merchant: string;
-    amount: string;
+    /** Display string for the approval screen. Optional when amountCents + currency are given. */
+    amount?: string;
+    /**
+     * The amount as a number (smallest currency unit) with its ISO 4217 code.
+     * See AuthorizeInput.amountCents: on a Stripe PaymentIntent confirm this
+     * binds the approval to the intent's amount, checked at create and again
+     * right before replay, so a larger charge is refused with nothing charged.
+     */
+    amountCents?: number;
+    currency?: string;
     onApprovalUrl?: (url: string) => void;
     onEvent?: (e: {
         type: string;
         detail?: unknown;
     }) => void;
+    /** Silence after a decline or timeout. Defaults to APPROVAL_COOLDOWN_MS. */
+    approvalCooldownMs?: number;
+    /** How long a hosted form the device already submitted stays refused on a re-post. Defaults to HOSTED_FORM_REPEAT_QUIET_MS. */
+    hostedFormRepeatQuietMs?: number;
 }
 /**
  * Take over card tokenization for a page.
@@ -25,6 +101,15 @@ export interface AttachOptions {
  * targets. Enabling Fetch on the page session alone will never see the
  * tokenization request. This attaches recursively so every nested target is
  * armed, which is the whole reason this adapter exists.
+ *
+ * The patterns armed here come from the REGISTRY, not from a constant, so a PSP
+ * the API knows about is paused without an SDK release — call
+ * `vault.syncRegistry()` before attaching and every recognizer the server
+ * serves is covered. They are a coarse pre-filter and are deliberately wider
+ * than the recognizers (see cardUrlPatterns): each paused request is re-checked
+ * with `isCardRequest` below and continued untouched unless it is an exact
+ * 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>;
 /**