@agent-cards/checkout 0.17.0 → 0.19.0

package/dist/client.d.ts

@@ -1,5 +1,7 @@
 import { type CheckoutMode, type Recognizer } from './registry.js';
 import type { Substitutions } from './substitute.js';
+import { type MerchantHostedSubstitutions, type MerchantProfile, type SandboxMerchantDeclaration } from './merchant-hosted.js';
+import { type MerchantTotalApproved, type MerchantTotalCapture } from './merchant-total.js';
 import { type PreparationMode, type PreparationProcessor } from './prepared-processor.js';
 export interface PausedRequest {
     url: string;
@@ -15,6 +17,27 @@ export interface PausedRequest {
  * is never paused) and sent on every create.
  */
 export declare const SUPPORTED_MODES: readonly CheckoutMode[];
+/**
+ * Registry features this SDK honours, asked for on syncRegistry next to the
+ * modes. `card_fields`: it reads a recognizer's cardFields and claims only a
+ * request whose body carries the card, so the API may serve it recognizers
+ * whose endpoints also run without a card. `checkout_sessions`: it lets a
+ * request the recognizer marks as routine without a card (passWithoutCard)
+ * through ahead of its holds, so the API may serve Stripe's Checkout Session
+ * confirm, which hosted Checkout sends after an approval.
+ */
+export declare const SUPPORTED_REGISTRY_FEATURES: readonly string[];
+/**
+ * Dark-launch capabilities this build can finish. Sent on syncRegistry as
+ * ?capabilities= so the API also serves the recognizers gated behind one of
+ * these. `fiserv_card_capture`: Fiserv Commerce Hub's Secure Data Capture card
+ * capture, which this build pauses and pays only through a prepared checkout
+ * (pre-claim.ts, fiserv.ts). The API serves Fiserv's recognizer only to a build
+ * that lists it and only for a company Agentcard turned Fiserv on for, so an older
+ * SDK never pauses a capture it cannot finish and no SDK pauses one for a company
+ * Fiserv is off for; the API also refuses a Fiserv payment for every such company.
+ */
+export declare const SUPPORTED_CAPABILITIES: readonly string[];
 /**
  * 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
@@ -84,14 +107,52 @@ export interface TokenReplay extends ExecutionMetadata {
  * (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.
+ * merchant's order state is where the outcome shows up. A Fiserv card capture
+ * (a prepared checkout only) carries its envelope at `source.encryptionData`:
+ * write it with substituteFiservEnvelope, never substituteEncryptedFields.
  */
 export interface CseReplay extends ExecutionMetadata {
     mode: 'cse';
+    /** Absent on a processor-hosted cse approval; see MerchantHostedReplay. */
+    kind?: undefined;
     authorizationId: string;
     substitutions: Substitutions;
     amountAuthority?: AmountAuthority;
 }
+/**
+ * The cse flow at an Adyen merchant's OWN endpoint (a reviewed merchant
+ * profile, see merchant-hosted.ts): the cardholder's device encrypted the card
+ * under the key Agentcard reviewed for that merchant, and nothing was sent. The
+ * paused request continues from this browser with the ciphertext written where
+ * the profile holds it (substituteMerchantHostedBody), and only when the live
+ * body still hashes to `bodySha256`, the body the API checked at create. The
+ * merchant's server charges the card and answers its own page; its order state is
+ * the outcome. Only a prepared checkout pays one, never Autopilot.
+ */
+export interface MerchantHostedReplay extends ExecutionMetadata {
+    mode: 'cse';
+    kind: 'merchant_hosted';
+    authorizationId: string;
+    /** The reviewed merchant profile the approval pays. */
+    profile: string;
+    substitutions: MerchantHostedSubstitutions;
+    /** SHA-256 (lowercase hex) of the paused body the API checked at create. */
+    bodySha256: string;
+    /** When the API stops serving this ciphertext, if it said. */
+    substitutionsExpiresAt: string | null;
+    /** Present when the approval pays this client's own sandbox declaration (VaultClientOptions.sandboxMerchants). */
+    sandboxDeclaration?: Readonly<{
+        endpoint: string;
+        clientKey: string;
+    }>;
+    /**
+     * The merchant's own total this approval was created at, when its profile is priced by
+     * one: the adapters read it again at release (merchantTotalAtRelease) and hold the card
+     * request unless it is still this amount, then report what the merchant says it charged.
+     */
+    merchantTotal?: MerchantTotalApproved;
+    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,
@@ -121,11 +182,25 @@ export interface HostedFormReplay extends ExecutionMetadata {
     amountAuthority?: AmountAuthority;
 }
 /** What authorize() resolves with; branch on `mode` (absent means token). */
-export type ReplayResponse = TokenReplay | CseReplay | HostedFormReplay;
+export type ReplayResponse = TokenReplay | CseReplay | MerchantHostedReplay | HostedFormReplay;
 export interface PrepareCheckoutOptions {
     psp: PreparationProcessor;
     /** The processor environment, independent of your Agentcard client's mode. */
     environment: 'production' | 'sandbox' | 'shared';
+    /**
+     * An Adyen merchant that takes the card on its own server: the id of the
+     * profile Agentcard reviewed for it (psp 'adyen'; the environment is the
+     * profile's). The profile must be enabled on this client (syncRegistry); its
+     * card request is then the one request this preparation pays.
+     *
+     * A Fiserv checkout (psp 'fiserv'): the id of the key Agentcard pinned for the
+     * merchant, `agentcard_sandbox` in the sandbox environment. Required for Fiserv,
+     * and refused for every processor but Adyen and Fiserv. The cardholder is asked to
+     * approve a payment to the merchant that key belongs to, so the checkout's `merchant`
+     * must be that merchant's name (`Agentcard sandbox` for `agentcard_sandbox`), and the
+     * one card capture this preparation pays must carry an envelope under that key.
+     */
+    merchantProfile?: string;
     signal?: AbortSignal;
 }
 export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
@@ -161,6 +236,13 @@ export interface PreparedCheckout {
     readonly checkoutKey: string;
     readonly paymentStatus: 'not_started';
     readonly amountAuthority: 'agent';
+    /** The reviewed merchant profile this preparation pays, or the Fiserv key pin it pays under; absent for a processor-hosted checkout. */
+    readonly merchantProfile?: string;
+    /** The declared test endpoint and key this preparation pays instead of the profile's (VaultClientOptions.sandboxMerchants). */
+    readonly sandboxDeclaration?: Readonly<{
+        endpoint: string;
+        clientKey: string;
+    }>;
 }
 export declare class CheckoutPreparationError extends Error {
     preparationId: string | null;
@@ -199,6 +281,8 @@ export interface AuthorizeInput extends ExecutionMetadata {
         amount: number;
         currency: string;
     };
+    /** Milliseconds from the caller's pay click until the SDK caught the card request, measured on one clock. */
+    payToInterceptMs?: number;
     /**
      * WHICH stored card should pay — a vault card id from
      * GET /api/v2/vault_cards. The approval page preselects it (the human can
@@ -228,6 +312,13 @@ export interface AuthorizeInput extends ExecutionMetadata {
     onApprovalUrl?: (url: string) => void;
     /** One-use preparation returned by this client. Never resumes an older request. */
     preparation?: PreparedCheckout;
+    /**
+     * For a reviewed merchant profile priced by the merchant's own total: when the card
+     * request paused and the merchant responses this browser recorded (see
+     * merchant-total.ts). The adapters pass it; a runtime that intercepts on its own builds
+     * one from its network events, or the payment is refused before any create.
+     */
+    merchantTotal?: MerchantTotalCapture;
 }
 export declare class CardEncryptedError extends Error {
     psp: string;
@@ -242,6 +333,18 @@ export declare class UnsupportedModeError extends Error {
     mode: string;
     constructor(mode: string);
 }
+/**
+ * The recognizer says this processor is preparation-required, and no preparation
+ * was passed. Its card may be sent only after the cardholder approved a
+ * prepare(): call prepareCheckout() (or the adapters' preparation gate) before
+ * this request is intercepted. Thrown locally before any create or prompt, and
+ * terminal (retrying the same paused request without preparing fails the same
+ * way). The API answers 409 preparation_required for the same case.
+ */
+export declare class PreparationRequiredError extends Error {
+    psp: string;
+    constructor(psp: string);
+}
 export declare class ApprovalTimeoutError extends Error {
     constructor(ms: number);
 }
@@ -276,13 +379,20 @@ export declare class ApprovalDeclinedError extends Error {
  * 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`.
+ *
+ * A merchant-hosted checkout (an Adyen merchant whose own server charges the card)
+ * has no processor read-back: its agent amount is held to the merchant's own
+ * checkout total, as the agent's browser read it, at stage 'create'. The SDK refuses
+ * that before any create, and the API refuses the same with 409 `amount_mismatch`, so a
+ * caller catches this one class either way; `amountSource` says whose number
+ * `actualCents` is, and the message names it.
  */
 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. */
+    /** What the processor (or the merchant, see `amountSource`) reported at the last check. */
     actualCents: number;
     /** ISO 4217 of the approved amount. */
     currency: string;
@@ -290,20 +400,32 @@ export declare class AmountMismatchError extends ApprovalDeclinedError {
     actualCurrency: string;
     /** Which check refused it. */
     stage: 'create' | 'pre_replay';
+    /**
+     * Whose number `actualCents` is: the processor's ('processor'), a merchant-hosted
+     * merchant's own checkout total ('merchant_total'), or the amount its card request
+     * names ('merchant_request').
+     */
+    readonly amountSource: 'processor' | 'merchant_total' | 'merchant_request';
     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. */
+    /** What the processor (or the merchant, see `amountSource`) 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');
+    stage?: 'create' | 'pre_replay', 
+    /**
+     * Whose number `actualCents` is: the processor's ('processor'), a merchant-hosted
+     * merchant's own checkout total ('merchant_total'), or the amount its card request
+     * names ('merchant_request').
+     */
+    amountSource?: 'processor' | 'merchant_total' | 'merchant_request');
 }
 /**
  * The PaymentIntent behind this checkout can no longer be confirmed: it was
@@ -341,6 +463,55 @@ export declare class ProcessorRefusedError extends ApprovalDeclinedError {
     readonly processorError: RazorpayProcessorError | null;
     constructor(authorizationId: string, pspErrorCode: string | null, processorError?: RazorpayProcessorError | null);
 }
+/** Why Agentcard refused a payment on Adyen's TEST platform; see AdyenTestPlatformRefusedError. */
+export type AdyenTestPlatformRefusal = 'adyen_test_environment_refused' | 'adyen_test_platform_requires_documented_test_card';
+/**
+ * Agentcard refused a payment on Adyen's TEST platform, where a test account can
+ * read whatever is encrypted under its key. Nothing was encrypted and nothing was
+ * charged. `code` says which rule:
+ *   - 'adyen_test_environment_refused': a live checkout names Adyen's test host or
+ *     a `test_` client key. Stage 'create': the API refused it before anyone was
+ *     asked (`authorizationId` is null) and the page's next request is refused the
+ *     same way, so the adapters stop intercepting. Stage 'pre_replay': the
+ *     authorization was declined right before the card would have been encrypted.
+ *   - 'adyen_test_platform_requires_documented_test_card': a test-mode checkout on
+ *     Adyen's test platform, where the approval page encrypts only Adyen's
+ *     documented test cards and the cardholder's card is not one.
+ * A decline in every structural sense, so it extends ApprovalDeclinedError.
+ */
+export declare class AdyenTestPlatformRefusedError extends ApprovalDeclinedError {
+    readonly authorizationId: string | null;
+    readonly code: AdyenTestPlatformRefusal;
+    readonly stage: 'create' | 'pre_replay';
+    constructor(authorizationId: string | null, code: AdyenTestPlatformRefusal, stage: 'create' | 'pre_replay');
+}
+/** Why a merchant-hosted payment priced by the merchant's own total was refused; see MerchantTotalError. */
+export type MerchantTotalRefusal = 'merchant_total_required' | 'merchant_total_refused' | 'merchant_total_changed' | 'merchant_total_stale';
+/**
+ * A reviewed merchant's own checkout total could not stand behind this payment, so the
+ * card request was held and nothing was charged. The merchant's server picks what it
+ * charges, so a merchant-hosted payment is priced by the total the merchant's own
+ * checkout responses named in this browser (the profile's amount source), never by the
+ * agent's number alone. `code`:
+ *   - 'merchant_total_required': no total was sent (stage 'sdk': this runtime recorded no
+ *     merchant responses; stage 'create': the API got none);
+ *   - 'merchant_total_refused': the responses do not confirm one total for this order
+ *     (`reasonCode`: no_source when none was seen, stale, refused, unreadable,
+ *     mismatch, unbound, invalid); stage 'sdk' before any create, 'create' by the API;
+ *   - 'merchant_total_changed': stage 'release': between the approval and the moment the
+ *     card would have gone out, the merchant's total moved, or a request that could move
+ *     it had not answered. The approval is retired; the card never left this browser;
+ *   - 'merchant_total_stale': stage 'runtime': the approval came after the total was too
+ *     old for its profile, so the API withheld the card.
+ * A decline in every structural sense, so it extends ApprovalDeclinedError.
+ */
+export declare class MerchantTotalError extends ApprovalDeclinedError {
+    readonly authorizationId: string | null;
+    readonly code: MerchantTotalRefusal;
+    readonly stage: 'sdk' | 'create' | 'release' | 'runtime';
+    readonly reasonCode: string | null;
+    constructor(authorizationId: string | null, code: MerchantTotalRefusal, stage: 'sdk' | 'create' | 'release' | 'runtime', reasonCode: string | null, reason: string);
+}
 /**
  * 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
@@ -459,6 +630,11 @@ export interface VaultClientOptions {
     /** Override the PSP registry (tests, or pinning). Defaults to the hosted list. */
     registry?: Recognizer[];
     fetchImpl?: typeof fetch;
+    /** Receives contained reporting failures that do not change checkout behavior. */
+    onEvent?: (event: {
+        type: string;
+        detail?: unknown;
+    }) => void;
     pollIntervalMs?: number;
     /**
      * Waits before retrying a create the API answered 502 `amount_unverifiable`
@@ -467,6 +643,25 @@ export interface VaultClientOptions {
      * the error is thrown. Default [500, 1500]; [] disables retries.
      */
     unverifiableRetryDelaysMs?: number[];
+    /**
+     * Test mode only: run a merchant-hosted checkout against your own Adyen TEST
+     * account. Each entry arms your own endpoint as taking the card request of a
+     * profile Agentcard reviewed (its body rules), encrypted under your own Adyen
+     * TEST client key; prepare({ psp: 'adyen', environment: 'sandbox',
+     * merchantProfile: <that profile> }) then pays it. Declare them here, before any
+     * attach, so every adapter pauses the endpoint. The API accepts a declaration
+     * only from a test-mode client of an org Agentcard turned declarations on for,
+     * and the Vault encrypts only Adyen's documented test cards under a test_ key.
+     * Throws a TypeError at construction for a profile this build did not review, an
+     * endpoint the API would refuse (see declareSandboxMerchant) or a non-test key.
+     *
+     * On this client a declared profile id takes the place of the reviewed profile
+     * with that id: merchantProfile(id) and prepare({ merchantProfile: id }) name
+     * the declaration, so this client never prepares the reviewed merchant's own
+     * checkout. Nothing is lost on a test-mode client, which can never pay a
+     * reviewed profile on Adyen's live platform; use a separate client for that.
+     */
+    sandboxMerchants?: SandboxMerchantDeclaration[];
 }
 export declare class VaultClient {
     private readonly opts;
@@ -475,13 +670,49 @@ export declare class VaultClient {
     private readonly pollIntervalMs;
     private readonly unverifiableRetryDelaysMs;
     private registry;
+    /**
+     * The reviewed merchant profiles this client arms: every one this build reviewed,
+     * in 'observe' until a sync reads that the API enabled it (armServedProfiles).
+     */
+    private merchantProfiles;
+    /** This client's own sandbox declarations (sandboxMerchants), armed at construction, one per profile. */
+    private readonly declaredProfiles;
     private readonly preparations;
     private readonly usedPreparations;
     constructor(opts: VaultClientOptions);
     /** Refresh recognizers from the API so new PSPs work without a redeploy. */
     syncRegistry(): Promise<void>;
+    /**
+     * The reviewed Adyen merchant profile whose card endpoint (or a sibling of it,
+     * the same path under another query) this URL is, with its status on this
+     * client; null for any other URL. Every profile this build reviewed is armed,
+     * in 'observe' until a sync reads that the API enabled it. The adapters pause
+     * these requests and judge them with classifyMerchantRequest. A raw runtime
+     * that pauses one must never continue a card body there unless authorize()
+     * paid it.
+     */
+    merchantProfileOf(url: string): MerchantProfile | null;
+    /** The armed profile with this id, or null. A profile id this client declared (sandboxMerchants) names its declaration, in place of the reviewed profile. */
+    merchantProfile(id: string): MerchantProfile | null;
+    /**
+     * Fetch.enable globs for every armed merchant profile's endpoint and its
+     * siblings, for a raw CDP runtime to arm beside cardUrlPatterns(). Every profile
+     * this build reviewed is armed from the start, so these are the same before and
+     * after syncRegistry; a sync changes only a profile's status.
+     */
+    merchantProfileUrlPatterns(): string[];
     /** True when this request is a card tokenization we can take over. */
     isCardRequest(url: string, method?: string): boolean;
+    /**
+     * What happens to a card request (by URL) whose body carries no card: null
+     * when it carries one, so it is a card request as usual; 'continue' when the
+     * recognizer marks the endpoint as one where such requests are routine and
+     * never ours; 'refuse' otherwise, such as a Stripe confirmation paying with
+     * a method this checkout never approved. The adapters ask only after their
+     * holds, so a request that would reuse an approved token is refused there
+     * first. A body that could not be read is not judged here.
+     */
+    withoutCard(url: string, body: string | null | undefined): 'continue' | 'refuse' | null;
     /**
      * How the card would reach the processor on this request (`token`, `cse`
      * or `hosted_form`; absent on the entry means `token`), or null when the
@@ -506,6 +737,8 @@ export declare class VaultClient {
     prepareCheckout(input: PrepareCheckoutInput): Promise<PreparedCheckout>;
     /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */
     cancelPreparation(id: string): Promise<void>;
+    observePreparation(id: string, guidance: 'presented_not_filled' | 'not_presented', reason?: string): Promise<void>;
+    reportDuplicateGuard(authorizationId: string): Promise<void>;
     /**
      * 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
@@ -539,6 +772,53 @@ export declare class VaultClient {
         cancelled: true;
         processor_request_started: boolean;
     }>;
+    /**
+     * Ask whether the page may pay with the Stripe card token an approval
+     * produced: a PaymentIntent confirm that carries no card and pays with
+     * exactly the approved payment method, card token, confirmation token or
+     * source. The API reads the payment from Stripe and answers only for the
+     * approved amount and currency on the same Stripe account; any other answer
+     * rejects with a CheckoutApiError whose code says why (for example
+     * `continuation_not_bound`, `amount_mismatch`). Nothing is charged here:
+     * the adapters continue the page's own request once this resolves.
+     */
+    checkStripeContinuation(authorizationId: string, request: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    }): Promise<{
+        paymentIntentId: string;
+        amount: number;
+        currency: string;
+    }>;
+    /**
+     * After a merchant-hosted payment priced by the merchant's own total: what the merchant's
+     * confirmation says it charged (merchant-total.ts merchantChargeReport builds `report`
+     * from the responses this browser recorded after the card request). The API compares it
+     * with the approved amount and alerts Agentcard once when the merchant charged more, or
+     * in another currency. The adapters send it on their own; the verdict is 'equal',
+     * 'lower', 'higher', 'currency_mismatch', or 'unread' when no response read.
+     */
+    reportMerchantCharge(authorizationId: string, report: {
+        request: {
+            url: string;
+            method: string;
+            body: string;
+        };
+        responses: unknown[];
+    }): Promise<{
+        verdict: 'equal' | 'lower' | 'higher' | 'currency_mismatch' | 'unread';
+        alerted: boolean;
+    }>;
+    /**
+     * The merchant's own total for a paused card request whose reviewed profile is priced by
+     * one: the exchanges the adapter recorded (once every request that can move the total has
+     * answered), cut to what the profile's rules read, and the same reading the API makes.
+     * Refused with a MerchantTotalError before any create when nothing recorded them, one is
+     * still unanswered, or they do not confirm one total for this order.
+     */
+    private readMerchantTotal;
     /**
      * POST the create, with two typed twists: a 502 `amount_unverifiable`
      * (Stripe did not answer the read-back) is retried on a short backoff