@agent-cards/checkout 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -1,22 +1,135 @@
-import { type Recognizer } from './registry.js';
+import { type CheckoutMode, type Recognizer } from './registry.js';
+import type { Substitutions } from './substitute.js';
 export interface PausedRequest {
     url: string;
     method: string;
     headers: Record<string, string>;
     body: string;
 }
-export interface ReplayResponse {
+/**
+ * The modes this SDK can finish. Asked for on syncRegistry (the API serves
+ * only recognizers in these modes, so a request this build cannot complete
+ * is never paused) and sent on every create.
+ */
+export declare const SUPPORTED_MODES: readonly CheckoutMode[];
+/**
+ * What the amount on an authorization IS: held to a Stripe PaymentIntent
+ * (read back at create and before the replay), the parked form's own sum
+ * (hosted_form: the bytes the device submits name the amount), or a display
+ * fact on a template that carries no amount.
+ */
+export type AmountAuthority = 'stripe_payment_intent' | 'hosted_form_sum' | 'display_only';
+/**
+ * The token flow: the cardholder's device called the processor itself, and
+ * this is the processor's answer to replay into the paused request.
+ */
+export interface TokenReplay {
+    /** Absent on older API versions; always 'token' here. */
+    mode?: 'token';
+    /** The approved authorization (`cauth_…`). */
+    authorizationId: string;
     status: number;
     headers: Record<string, string>;
     /** Body to hand back to the browser, verbatim. */
     body: string;
+    /**
+     * Post-replay reconciliation, when the API has it: whether the amount the
+     * processor reported charging equals the amount the user approved (null
+     * when there was nothing to compare, e.g. a tokenization request), and the
+     * charged pair itself. A `false` here means the approval stood (money had
+     * moved) and Agentcard also sent your server checkout_authorization.amount_mismatch.
+     */
+    amountVerified?: boolean | null;
+    chargedAmountCents?: number | null;
+    chargedCurrency?: string | null;
+    /**
+     * What `chargedAmountCents` is: 'captured' (the intent succeeded; this is
+     * amount_received), 'authorized' (requires_capture; amount_capturable, the
+     * merchant captures later), 'none' (a PaymentIntent was reported but
+     * nothing is collected yet: processing, requires_action), or null when no
+     * PaymentIntent was reported at all (a tokenization request).
+     */
+    chargedKind?: 'captured' | 'authorized' | 'none' | null;
+    /** 'stripe_payment_intent' when the amount was held to a Stripe intent; 'display_only' otherwise. */
+    amountAuthority?: AmountAuthority;
 }
+/**
+ * The cse flow (Adyen): the cardholder's device encrypted the card under the
+ * processor's public key and reported the ciphertext. Nothing was sent to the
+ * processor yet: write `substitutions` into the paused body
+ * (substituteEncryptedFields) and let the request CONTINUE from the browser
+ * that paused it, so its session data, risk data and cookies stay its own.
+ * The processor's answer then reaches the page as it normally would; the
+ * merchant's order state is where the outcome shows up.
+ */
+export interface CseReplay {
+    mode: 'cse';
+    authorizationId: string;
+    substitutions: Substitutions;
+    amountAuthority?: AmountAuthority;
+}
+/**
+ * The hosted_form flow (Tranzila): the cardholder's device rebuilt the
+ * processor's own form with the real card and submitted it itself, top-level,
+ * at `submittedAt`. The processor answered THE DEVICE, not the browser that
+ * paused the navigation, so there is no response to replay and no outcome
+ * here: resolve the paused navigation with hostedFormSubmittedPage() (the
+ * adapters do), never resubmit the form, and confirm the order with the
+ * merchant, which learns the outcome from the processor.
+ *
+ * THIS IS NOT AN APPROVED PAYMENT. `kind` and `outcome` say so in words so
+ * no caller mistakes it for one: the API finishes such an authorization as
+ * `submitted_on_device` (never `approved`) and sends your server
+ * `checkout_authorization.submitted` (never `.approved`). 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. Treat it as "the
+ * person paid, or tried to, on their own device" and confirm with the merchant.
+ */
+export interface HostedFormReplay {
+    mode: 'hosted_form';
+    /** What this resolution is: a device-attested submission, not a processor answer. */
+    kind: 'submitted_on_device';
+    /** Always 'unverified': no processor evidence exists for a hosted form. */
+    outcome: 'unverified';
+    authorizationId: string;
+    /** When the device reported the form left it (ISO 8601). */
+    submittedAt: string;
+    amountAuthority?: AmountAuthority;
+}
+/** What authorize() resolves with; branch on `mode` (absent means token). */
+export type ReplayResponse = TokenReplay | CseReplay | HostedFormReplay;
 export interface AuthorizeInput {
     /** Your identifier for the person whose card should pay. */
     user: string;
     /** Shown to the user on the approval screen. */
     merchant: string;
-    amount: string;
+    /**
+     * The display string the approval screen shows ("$23.06"). Optional when
+     * amountCents + currency are given, and IGNORED then: Agentcard derives the
+     * string from the number so every surface shows one amount.
+     */
+    amount?: string;
+    /**
+     * The amount as a number in the smallest currency unit (2306 for $23.06)
+     * with its ISO 4217 code ("usd"). On a Stripe PaymentIntent confirm this
+     * pair is BOUND to the intent: Agentcard reads the intent back from Stripe
+     * at create and again right before the cardholder's device replays, and a
+     * different amount is refused with nothing charged (an AmountMismatchError
+     * either way: `stage` says which check). After the replay the charge is
+     * reconciled against the approval (see ReplayResponse.amountVerified).
+     * Tokenization requests carry no amount, so there it is display-only.
+     * Both or neither: one without the other is refused.
+     */
+    amountCents?: number;
+    currency?: string;
+    /**
+     * WHICH stored card should pay — a vault card id from
+     * GET /api/v2/vault_cards. The approval page preselects it (the human can
+     * still override). Omitted: the page defaults to the most recently added
+     * card. An id that isn't in this user's vault fails the create with a 404
+     * `card_not_found`.
+     */
+    cardId?: string;
     request: PausedRequest;
     /** Abort if the user has not approved within this many ms. Default 15 min. */
     timeoutMs?: number;
@@ -27,12 +140,136 @@ export declare class CardEncryptedError extends Error {
     psp: string;
     constructor(psp: string);
 }
+/**
+ * The API approved an authorization in a mode this SDK build cannot finish.
+ * Unreachable by construction (syncRegistry asks only for SUPPORTED_MODES and
+ * every create names its mode), so it is treated as terminal: retrying the
+ * same page could only raise more prompts for the same dead end.
+ */
+export declare class UnsupportedModeError extends Error {
+    mode: string;
+    constructor(mode: string);
+}
 export declare class ApprovalTimeoutError extends Error {
     constructor(ms: number);
 }
 export declare class ApprovalDeclinedError extends Error {
     constructor(reason: string);
 }
+/**
+ * Agentcard refused the payment because the processor's amount did not match
+ * the amount the user was (or would have been) asked to approve. Nothing was
+ * charged. Two stages:
+ *   - 'create': the intent already disagreed when the request was parked. No
+ *     authorization exists (`authorizationId` is null). Per request, not per
+ *     page: the merchant can still update the intent before confirmation, so
+ *     the adapters keep intercepting and the next attempt is judged afresh.
+ *   - 'pre_replay': the intent moved between create and the moment the
+ *     cardholder's device would have sent the card. The authorization is
+ *     `declined` with reason `amount_mismatch`.
+ *
+ * A decline in every structural sense (the adapters abort the paused request
+ * and quiet the page's retry exactly as for a person's "no"), so it extends
+ * ApprovalDeclinedError: code that already handles declines keeps working,
+ * and code that wants the numbers reads them here or branches on `code`.
+ */
+export declare class AmountMismatchError extends ApprovalDeclinedError {
+    /** The declined authorization, or null for a create-time refusal (no row exists). */
+    authorizationId: string | null;
+    /** What the user was asked to approve, smallest currency unit. */
+    expectedCents: number;
+    /** What the processor reported at the last check. */
+    actualCents: number;
+    /** ISO 4217 of the approved amount. */
+    currency: string;
+    /** ISO 4217 the processor reported (differs only on a currency change). */
+    actualCurrency: string;
+    /** Which check refused it. */
+    stage: 'create' | 'pre_replay';
+    readonly code: "amount_mismatch";
+    constructor(
+    /** The declined authorization, or null for a create-time refusal (no row exists). */
+    authorizationId: string | null, 
+    /** What the user was asked to approve, smallest currency unit. */
+    expectedCents: number, 
+    /** What the processor reported at the last check. */
+    actualCents: number, 
+    /** ISO 4217 of the approved amount. */
+    currency: string, 
+    /** ISO 4217 the processor reported (differs only on a currency change). */
+    actualCurrency?: string, 
+    /** Which check refused it. */
+    stage?: 'create' | 'pre_replay');
+}
+/**
+ * The PaymentIntent behind this checkout can no longer be confirmed: it was
+ * already charged (succeeded), is being charged (processing), is authorized
+ * and on hold for the merchant to capture (requires_capture), or was
+ * canceled. Agentcard refused rather than replay a confirm at it; the
+ * authorization is `declined` with reason `intent_not_confirmable`.
+ * Deliberately NOT "nothing was charged": for three of those four, money has
+ * moved or is moving. Check the intent at Stripe before retrying.
+ */
+export declare class IntentNotConfirmableError extends ApprovalDeclinedError {
+    authorizationId: string;
+    readonly code: "intent_not_confirmable";
+    constructor(authorizationId: string);
+}
+/**
+ * The cardholder's device sent the card and the processor refused it
+ * outright (a card decline, a bad CVC, an invalid request). Nothing was
+ * charged; the authorization is `declined` with reason `processor_refused`
+ * and the processor's own code in `pspErrorCode` (Stripe's `card_declined`,
+ * `incorrect_cvc`, …). A decline like any other for the adapters: the paused
+ * request is aborted and the page's retry gets a fresh approval, where the
+ * person can pick another card.
+ */
+export declare class ProcessorRefusedError extends ApprovalDeclinedError {
+    authorizationId: string;
+    pspErrorCode: string | null;
+    readonly code: "processor_refused";
+    constructor(authorizationId: string, pspErrorCode: string | null);
+}
+/**
+ * A non-2xx from the Agentcard API, carrying the status so callers can tell a
+ * misconfiguration from a blip. The adapters use this to decide whether
+ * retrying is worth anything: a 404 `connection_not_found` will answer the same
+ * way forever, while a 429 or a 502 will not.
+ */
+export declare class CheckoutApiError extends Error {
+    status: number;
+    path: string;
+    bodyText: string;
+    /** The API's stable error code (`{ error: { code } }`), or null when the body carried none. */
+    readonly code: string | null;
+    /**
+     * The rest of the error envelope. A 409 `amount_mismatch` from create
+     * carries `expected_cents`, `actual_cents`, `currency`, `actual_currency`;
+     * an `amount_unverifiable` carries `reason`; an `intent_not_confirmable`
+     * carries `intent_status`.
+     */
+    readonly details: Record<string, unknown>;
+    constructor(status: number, path: string, bodyText: string);
+    /**
+     * True when repeating this exact call cannot succeed: a misconfiguration
+     * (4xx other than 429). NOT a 409 `amount_mismatch`: Stripe lets a merchant
+     * update an intent's amount until it is confirmed, so the next request on
+     * the same page may well agree. That one is a per-request failure, and
+     * authorize() surfaces it as AmountMismatchError before an adapter ever
+     * sees it here. NOT a 409 `duplicate_submission` either: the household
+     * already has, or already answered, the prompt for this submission, and
+     * once that prior authorization is declined or expired the same form is a
+     * new question. The adapters quiet the page's re-post the way they quiet a
+     * decline instead of latching the attachment.
+     */
+    get permanent(): boolean;
+}
+/**
+ * A URL as it may appear in an error message: origin + path only. A paused
+ * request's URL can carry a client secret in its query string, and error
+ * messages travel further than anyone intends (onEvent, logs, crash reports).
+ */
+export declare function redactUrl(raw: string): string;
 export interface VaultClientOptions {
     /**
      * Your Agentcard OAuth client credentials. The SDK exchanges them for a
@@ -49,24 +286,52 @@ export interface VaultClientOptions {
     registry?: Recognizer[];
     fetchImpl?: typeof fetch;
     pollIntervalMs?: number;
+    /**
+     * Waits before retrying a create the API answered 502 `amount_unverifiable`
+     * (Stripe did not answer the amount read-back) or 502 `cse_key_unavailable`
+     * (Adyen did not answer the public-key fetch). One retry per entry, then
+     * the error is thrown. Default [500, 1500]; [] disables retries.
+     */
+    unverifiableRetryDelaysMs?: number[];
 }
 export declare class VaultClient {
     private readonly opts;
     private readonly baseUrl;
     private readonly fetch;
     private readonly pollIntervalMs;
+    private readonly unverifiableRetryDelaysMs;
     private registry;
     constructor(opts: VaultClientOptions);
     /** Refresh recognizers from the API so new PSPs work without a redeploy. */
     syncRegistry(): Promise<void>;
     /** True when this request is a card tokenization we can take over. */
     isCardRequest(url: string, method?: string): boolean;
+    /**
+     * Glob url patterns covering every host the CURRENT registry can send a card
+     * to — what a raw CDP connection has to hand `Fetch.enable` before any card
+     * request can be paused. attachToCdp calls this for you.
+     *
+     * Call syncRegistry() FIRST: without it these cover only the built-in PSPs,
+     * and a request the API knows about is never paused at all. Deliberately
+     * WIDER than the recognizers themselves (a glob cannot express an anchored
+     * host regex); isCardRequest is the exact check and runs on every request
+     * these patterns pause.
+     */
+    cardUrlPatterns(): string[];
     /**
      * Hand us a paused tokenization request. We ask the cardholder to approve,
      * their device supplies the card and calls the merchant, and you get back the
      * response to replay into the browser. Your process never sees a card.
      */
     authorize(input: AuthorizeInput): Promise<ReplayResponse>;
+    /**
+     * POST the create, with two typed twists: a 502 `amount_unverifiable`
+     * (Stripe did not answer the read-back) is retried on a short backoff
+     * instead of being left to the page's own retry loop, and a 409
+     * `amount_mismatch` becomes an AmountMismatchError at stage 'create' so the
+     * adapters treat it as an answered request, not a dead page.
+     */
+    private createAuthorization;
     private token;
     private inflight;
     /**