@agent-cards/sdk 0.23.19 → 0.23.21

package/dist/hold.d.ts

@@ -0,0 +1,180 @@
+/** One kind of card request the hold catches although no recogniser pays it. */
+export interface HoldOnlyRule {
+    /** The processor's name, for the record (`bolt`, `placeholder_card`). */
+    psp: string;
+    /** The card request's address. */
+    match: RegExp;
+    /** CDP Fetch url patterns that cover `match`, with an optional resource type. */
+    patterns: Array<{
+        urlPattern: string;
+        resourceType?: string;
+    }>;
+    /** When set, a request to `match` is a card request only if its body passes. */
+    body?: RegExp;
+    kind: 'tokenize' | 'store_card_post';
+    /** The processor's own wait for this request, in ms: the hold cancels before it. */
+    deadlineMs: number;
+    /** Methods that carry the card here. Default POST. */
+    methods?: string[];
+}
+/**
+ * Bolt's embedded card frame (connect.bolt.com credit-card-input): a POST of `{ payload, nonce, public_key }` JSON,
+ * the card boxed to Bolt's key, to `<base>/token` or `<base>/token/cvv`, with a 20 s timeout and retries.
+ */
+export declare const BOLT_HOLD_RULE: HoldOnlyRule;
+/** Each recogniser's own wait for its card request, where it was measured; any other gets HOLD_DEFAULT_DEADLINE_MS. */
+export declare const HOLD_DEADLINES_MS: Readonly<Record<string, number>>;
+export declare const HOLD_DEFAULT_DEADLINE_MS = 30000;
+/** How long before the processor's own wait the hold gives the request up. */
+export declare const HOLD_DEADLINE_MARGIN_MS = 2000;
+/**
+ * Any request whose body carries one of the placeholder card numbers, wherever it goes. It cannot see a card a
+ * processor's frame encrypts first (Bolt, Adyen): those need their own rule. Null without a usable number.
+ */
+export declare function placeholderHoldRule(numbers: readonly string[], deadlineMs?: number): HoldOnlyRule | null;
+/** The hold-only rule a request is a card request under, or null. */
+export declare function matchHoldOnlyRule(request: {
+    url: string;
+    method: string;
+    body: string | null;
+}, rules: readonly HoldOnlyRule[]): HoldOnlyRule | null;
+export interface HoldOptions {
+    /**
+     * The placeholder card numbers the vault gave this page. Any request whose body carries one is held too. Matched
+     * in this process only, never recorded or sent anywhere.
+     */
+    placeholderNumbers?: readonly string[];
+    /** Replaces every recogniser's deadline (tests). */
+    deadlineMs?: number;
+    /** How long before the processor's deadline the hold gives the request up. Default HOLD_DEADLINE_MARGIN_MS. */
+    deadlineMarginMs?: number;
+    /** Called once a card request is held. */
+    onHeld?: (held: HeldCardRequest) => void;
+}
+/** What the hold records of a held request: never its body or headers, which may carry the card. */
+export interface HeldCardRequest {
+    /** The processor, by the recogniser's name (`braintree`), `bolt`, or `placeholder_card`; null when unnamed. */
+    psp: string | null;
+    /** Origin and path only, with any credential a processor writes into the path masked (redactUrl). */
+    endpoint: string;
+    kind: 'tokenize' | 'store_card_post' | 'card_request';
+    /** Whether a release can answer it: a recogniser the SDK pays, never Bolt or a store's own card post. */
+    replayable: boolean;
+    heldAt: number;
+    deadlineMs: number;
+}
+export type HoldState = 'watching' | 'held' | 'released' | 'cancelled' | 'expired' | 'lost' | 'closed';
+export interface HoldReleaseInput {
+    /** The total the person confirmed, an integer in the currency's smallest unit. The approval is created at it. */
+    amount: number;
+    currency: string;
+    /**
+     * The total the page shows now, read by the caller (null when it reads none). Released only when it matches: equal
+     * to `amount` by default, or at most `amount` with `upTo` (an approval at a ceiling). Anything else cancels.
+     */
+    pageTotal: {
+        amount: number;
+        currency: string;
+    } | null;
+    /** `amount` is a ceiling the page total may stay under (a store that prices tax after the card). */
+    upTo?: boolean;
+    /**
+     * Sandbox only: a store's own card post held by the placeholder rule carries the documented test number only, and
+     * is sent on unchanged so the store can answer it (its Review Order). Refused on a live client.
+     */
+    continuePlaceholder?: boolean;
+}
+export interface HoldReleaseOutcome {
+    /**
+     * approved_not_charged: sandbox, the approval was approved and the request never sent on.
+     * authorized: live, the device's answer reached the page. continued: a placeholder post was sent on (sandbox).
+     */
+    outcome: 'approved_not_charged' | 'authorized' | 'continued' | 'declined' | 'expired' | 'failed';
+    authorizationId?: string | null;
+    detail?: string;
+}
+/** The hold of one attachment: `controller.hold`. */
+export interface CardRequestHold {
+    readonly state: HoldState;
+    readonly held: HeldCardRequest | null;
+    /** Card requests failed without being held: a second one, a retry, or one after a decision. */
+    readonly refused: number;
+    /** Resolves with the held request once one is held, or null after `timeoutMs` or once the hold is over. */
+    whenHeld(timeoutMs?: number): Promise<HeldCardRequest | null>;
+    release(input: HoldReleaseInput): Promise<HoldReleaseOutcome>;
+    /** Fail the held request in the page: nothing was created or sent. Every later card request fails at once. */
+    cancel(reason?: string): Promise<void>;
+}
+/** A hold ended without a release: the paused request fails, and every later card request fails at once. */
+export declare class HoldEndedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** A second card request while one is held: this request alone fails, the held one and the checkout are untouched. */
+export declare class HoldRefusedError extends Error {
+    constructor();
+}
+/** A sandbox release answered: the approval was created and read, and the request was never sent on. */
+export declare class HoldAnsweredError extends Error {
+    readonly outcome: HoldReleaseOutcome;
+    constructor(outcome: HoldReleaseOutcome);
+}
+/** What the transport does with a held request once the person answered. */
+export type HoldDecision = {
+    kind: 'release';
+    amount: number;
+    currency: string;
+    settle: (outcome: HoldReleaseOutcome) => void;
+} | {
+    kind: 'continue';
+    settle: (outcome: HoldReleaseOutcome) => void;
+};
+/**
+ * The hold's state, shared by the transport and the caller. The transport calls `hold` when a card request pauses
+ * and awaits the decision; the caller calls `release` or `cancel`. Not exported from the package: the caller sees
+ * the CardRequestHold face.
+ */
+export declare class HoldGate implements CardRequestHold {
+    private readonly options;
+    private readonly sandbox;
+    private readonly emit;
+    private _state;
+    private _held;
+    private _refused;
+    private timer;
+    private waiters;
+    private pending;
+    readonly rules: HoldOnlyRule[];
+    constructor(options: HoldOptions, sandbox: boolean, emit: (type: string, detail?: unknown) => void);
+    get state(): HoldState;
+    get held(): HeldCardRequest | null;
+    get refused(): number;
+    /** Fetch patterns the hold-only rules need beside the registry's. */
+    patterns(): Array<{
+        urlPattern: string;
+        resourceType?: string;
+    }>;
+    deadlineFor(psp: string | null, rule?: HoldOnlyRule): number;
+    /** A card request that may not be held now (a second one, or one after a decision): counted, and failed by the caller. */
+    refuse(psp: string | null, url: string): boolean;
+    /**
+     * Hold a card request: resolves with the person's decision, or rejects with HoldEndedError when the hold is
+     * cancelled, expires, loses its request or closes. The caller (the transport) answers or fails the request.
+     */
+    hold(input: {
+        psp: string | null;
+        url: string;
+        kind: HeldCardRequest['kind'];
+        replayable: boolean;
+        rule?: HoldOnlyRule;
+    }): Promise<HoldDecision>;
+    /** The page gave up the held request, or its frame went away: nothing was sent. */
+    lost(): void;
+    /** The attachment ended. */
+    close(): void;
+    private end;
+    whenHeld(timeoutMs?: number): Promise<HeldCardRequest | null>;
+    cancel(reason?: string): Promise<void>;
+    release(input: HoldReleaseInput): Promise<HoldReleaseOutcome>;
+    private decide;
+}

package/dist/hold.js

@@ -0,0 +1,270 @@
+// The card request hold (attachToCdp's `hold` mode; CARD-REQUEST-HOLD.md). A page's card request is paused in
+// the browser's network layer and HELD: no approval exists, nothing reaches the processor, and the request waits
+// for one of two answers.
+//
+//   release({ amount, currency, pageTotal })  the person confirmed this total, and the page shows it now: the
+//       approval is created only then, at that total. A live client answers the page with the device's replay; a
+//       sandbox client never sends the request on (the approval is created and read, nothing is charged).
+//   cancel(reason)                             the request fails in the page; nothing was created or sent.
+//
+// A held request that would outlive its processor's own wait (Braintree's client gives up after 60 s, Bolt's
+// tokenizer after 20 s) is cancelled first, so a hold never ends in an unknown state. One request is held at a
+// time; every other card request, and every one after a decision, fails at once.
+//
+// Beside the registry's recognisers, a hold also catches two kinds of request the SDK cannot pay:
+//   - Bolt's tokenizer: Bolt seals the card and its answer to a key pair made inside its own frame, so no device
+//     replay can answer it. Held, then only cancelled.
+//   - Any request whose body carries the placeholder card number (`placeholderNumbers`): a store's own card post or
+//     an unknown processor. The browser only ever holds the placeholder, so a body with its digits is a card request
+//     wherever it goes. In sandbox it may be released unchanged (it carries the documented test number only).
+// The hold records the processor and the endpoint (origin and path, any path credential masked), never a body or a
+// header.
+import { redactUrl } from './client.js';
+/**
+ * Bolt's embedded card frame (connect.bolt.com credit-card-input): a POST of `{ payload, nonce, public_key }` JSON,
+ * the card boxed to Bolt's key, to `<base>/token` or `<base>/token/cvv`, with a 20 s timeout and retries.
+ */
+export const BOLT_HOLD_RULE = {
+    psp: 'bolt',
+    match: /^[a-z]+:\/\/(?:(?:production|sandbox|staging)\.bolttk\.com|tokenizer(?:-sandbox|-staging)?\.bolt(?:app)?\.com)(?::\d+)?\/token(?:\/cvv)?(?:[?#]|$)/i,
+    patterns: [{ urlPattern: '*://*.bolttk.com*/token*' }, { urlPattern: '*://tokenizer*.bolt.com*/token*' }, { urlPattern: '*://tokenizer*.boltapp.com*/token*' }],
+    kind: 'tokenize',
+    deadlineMs: 20_000,
+};
+/** Each recogniser's own wait for its card request, where it was measured; any other gets HOLD_DEFAULT_DEADLINE_MS. */
+export const HOLD_DEADLINES_MS = { braintree: 60_000, adyen: 60_000, bolt: 20_000 };
+export const HOLD_DEFAULT_DEADLINE_MS = 30_000;
+/** How long before the processor's own wait the hold gives the request up. */
+export const HOLD_DEADLINE_MARGIN_MS = 2_000;
+/** The resource types a page can send a card in: XHR, fetch, a form post, and the rest. */
+const PLACEHOLDER_RESOURCE_TYPES = ['XHR', 'Fetch', 'Document', 'Other', 'Ping'];
+/**
+ * Any request whose body carries one of the placeholder card numbers, wherever it goes. It cannot see a card a
+ * processor's frame encrypts first (Bolt, Adyen): those need their own rule. Null without a usable number.
+ */
+export function placeholderHoldRule(numbers, deadlineMs = HOLD_DEFAULT_DEADLINE_MS) {
+    const digits = numbers.map((n) => String(n).replace(/\D/g, '')).filter((d) => d.length >= 12 && d.length <= 19);
+    if (!digits.length)
+        return null;
+    // The digits as a page may send them: plain, or grouped with spaces, dashes, '+' or '%20'.
+    const sep = '(?:\\s|-|\\+|%20)?';
+    const body = new RegExp(digits.map((d) => d.split('').join(sep)).join('|'));
+    return {
+        psp: 'placeholder_card', match: /^[a-z]+:\/\//i, body, kind: 'store_card_post', deadlineMs, methods: ['POST', 'PUT', 'PATCH'],
+        patterns: PLACEHOLDER_RESOURCE_TYPES.map((resourceType) => ({ urlPattern: '*', resourceType })),
+    };
+}
+/** The hold-only rule a request is a card request under, or null. */
+export function matchHoldOnlyRule(request, rules) {
+    for (const rule of rules) {
+        if (!(rule.methods ?? ['POST']).includes(String(request.method).toUpperCase()))
+            continue;
+        if (!rule.match.test(request.url))
+            continue;
+        if (rule.body && !rule.body.test(request.body ?? ''))
+            continue;
+        return rule;
+    }
+    return null;
+}
+/** A hold ended without a release: the paused request fails, and every later card request fails at once. */
+export class HoldEndedError extends Error {
+    reason;
+    constructor(reason) {
+        super(`card request hold ended: ${reason}`);
+        this.reason = reason;
+        this.name = 'HoldEndedError';
+    }
+}
+/** A second card request while one is held: this request alone fails, the held one and the checkout are untouched. */
+export class HoldRefusedError extends Error {
+    constructor() { super('another card request is held'); this.name = 'HoldRefusedError'; }
+}
+/** A sandbox release answered: the approval was created and read, and the request was never sent on. */
+export class HoldAnsweredError extends Error {
+    outcome;
+    constructor(outcome) {
+        super(`card request hold answered without sending: ${outcome.outcome}`);
+        this.outcome = outcome;
+        this.name = 'HoldAnsweredError';
+    }
+}
+/**
+ * A held request's origin and path as redactUrl reads them, so a credential a processor writes into the path (GoPay's
+ * card form token, a PayMongo session) never reaches an event or onHeld.
+ */
+function endpointOf(url) {
+    try {
+        new URL(url);
+    }
+    catch {
+        return redactUrl(String(url)).slice(0, 120);
+    }
+    return redactUrl(url);
+}
+function validTotal(t) {
+    const v = t;
+    return !!v && Number.isSafeInteger(v.amount) && v.amount > 0 && typeof v.currency === 'string' && /^[A-Za-z]{3}$/.test(v.currency);
+}
+/**
+ * The hold's state, shared by the transport and the caller. The transport calls `hold` when a card request pauses
+ * and awaits the decision; the caller calls `release` or `cancel`. Not exported from the package: the caller sees
+ * the CardRequestHold face.
+ */
+export class HoldGate {
+    options;
+    sandbox;
+    emit;
+    _state = 'watching';
+    _held = null;
+    _refused = 0;
+    timer = null;
+    waiters = [];
+    pending = null;
+    rules;
+    constructor(options, sandbox, emit) {
+        this.options = options;
+        this.sandbox = sandbox;
+        this.emit = emit;
+        const placeholder = options.placeholderNumbers?.length ? placeholderHoldRule(options.placeholderNumbers) : null;
+        this.rules = [BOLT_HOLD_RULE, ...(placeholder ? [placeholder] : [])];
+    }
+    get state() { return this._state; }
+    get held() { return this._held ? { ...this._held } : null; }
+    get refused() { return this._refused; }
+    /** Fetch patterns the hold-only rules need beside the registry's. */
+    patterns() { return this.rules.flatMap((r) => r.patterns); }
+    deadlineFor(psp, rule) {
+        return this.options.deadlineMs ?? rule?.deadlineMs ?? (psp ? HOLD_DEADLINES_MS[psp] : undefined) ?? HOLD_DEFAULT_DEADLINE_MS;
+    }
+    /** A card request that may not be held now (a second one, or one after a decision): counted, and failed by the caller. */
+    refuse(psp, url) {
+        if (this._state === 'watching')
+            return false;
+        this._refused++;
+        this.emit('card_request_refused', { psp, endpoint: endpointOf(url), state: this._state });
+        return true;
+    }
+    /**
+     * Hold a card request: resolves with the person's decision, or rejects with HoldEndedError when the hold is
+     * cancelled, expires, loses its request or closes. The caller (the transport) answers or fails the request.
+     */
+    hold(input) {
+        if (this._state !== 'watching')
+            return Promise.reject(new HoldEndedError(`not_watching:${this._state}`));
+        const deadlineMs = this.deadlineFor(input.psp, input.rule);
+        this._held = { psp: input.psp, endpoint: endpointOf(input.url), kind: input.kind, replayable: input.replayable, heldAt: Date.now(), deadlineMs };
+        this._state = 'held';
+        const decision = new Promise((resolve, reject) => { this.pending = { resolve, reject }; });
+        decision.catch(() => undefined);
+        const margin = this.options.deadlineMarginMs ?? HOLD_DEADLINE_MARGIN_MS;
+        this.timer = setTimeout(() => {
+            if (this._state !== 'held')
+                return;
+            this.end('expired', 'expired');
+            this.emit('card_request_expired', { endpoint: this._held?.endpoint, afterMs: Date.now() - (this._held?.heldAt ?? Date.now()) });
+        }, Math.max(0, deadlineMs - margin));
+        this.timer.unref?.();
+        const held = this.held;
+        this.emit('card_request_held', held);
+        try {
+            this.options.onHeld?.(held);
+        }
+        catch { /* observer only */ }
+        for (const w of this.waiters.splice(0))
+            w(held);
+        return decision;
+    }
+    /** The page gave up the held request, or its frame went away: nothing was sent. */
+    lost() {
+        if (this._state !== 'held')
+            return;
+        this.end('lost', 'request_lost');
+        this.emit('card_request_lost', { endpoint: this._held?.endpoint });
+    }
+    /** The attachment ended. */
+    close() {
+        if (this._state === 'held')
+            this.end('closed', 'closed');
+        else if (this._state === 'watching')
+            this._state = 'closed';
+        for (const w of this.waiters.splice(0))
+            w(null);
+    }
+    end(state, reason) {
+        this._state = state;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const p = this.pending;
+        this.pending = null;
+        p?.reject(new HoldEndedError(reason));
+        for (const w of this.waiters.splice(0))
+            w(null);
+    }
+    whenHeld(timeoutMs = 30_000) {
+        if (this._state === 'held')
+            return Promise.resolve(this.held);
+        if (this._state !== 'watching')
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            const t = setTimeout(() => resolve(null), timeoutMs);
+            t.unref?.();
+            this.waiters.push((h) => { clearTimeout(t); resolve(h); });
+        });
+    }
+    async cancel(reason = 'cancelled') {
+        if (this._state === 'watching') {
+            this._state = 'cancelled';
+            this.emit('card_request_hold_cancelled', { reason, held: false });
+            for (const w of this.waiters.splice(0))
+                w(null);
+            return;
+        }
+        if (this._state !== 'held')
+            return;
+        this.end('cancelled', reason);
+        this.emit('card_request_cancelled', { reason });
+    }
+    async release(input) {
+        if (this._state !== 'held' || !this.pending || !this._held)
+            return { outcome: 'failed', detail: `not_held:${this._state}` };
+        const fail = async (detail) => { await this.cancel(detail); return { outcome: 'failed', detail }; };
+        if (!validTotal(input))
+            return fail('invalid_amount');
+        // The exact total, or nothing: a page that moved (tax, shipping) after the person confirmed is not released.
+        const page = input.pageTotal;
+        if (!validTotal(page))
+            return fail('total_unread');
+        if (page.currency.toLowerCase() !== input.currency.toLowerCase())
+            return fail('total_changed');
+        if (input.upTo ? page.amount > input.amount : page.amount !== input.amount)
+            return fail(input.upTo ? 'total_over_ceiling' : 'total_changed');
+        const held = this._held;
+        let settle;
+        const settled = new Promise((resolve) => { settle = resolve; });
+        if (!held.replayable) {
+            if (held.kind === 'store_card_post' && input.continuePlaceholder && this.sandbox) {
+                this.decide({ kind: 'continue', settle });
+                this.emit('card_request_released', { psp: held.psp, continued: true, amount: input.amount, currency: input.currency.toLowerCase(), upTo: !!input.upTo });
+                return settled;
+            }
+            // Bolt's sealed tokenizer and a store's own card post have no device replay: the request is cancelled.
+            return fail(held.kind === 'store_card_post' ? (this.sandbox ? 'store_card_post_needs_continue' : 'store_card_post_unreviewed') : 'not_replayable');
+        }
+        this.decide({ kind: 'release', amount: input.amount, currency: input.currency.toLowerCase(), settle });
+        this.emit('card_request_released', { psp: held.psp, amount: input.amount, currency: input.currency.toLowerCase(), upTo: !!input.upTo });
+        return settled;
+    }
+    decide(decision) {
+        this._state = 'released';
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const p = this.pending;
+        this.pending = null;
+        p?.resolve(decision);
+    }
+}

package/dist/hosted-entry.d.ts

@@ -0,0 +1,4 @@
+/** Whether this processor's hosted page is entered with a GET this build reads exactly. */
+export declare function hasHostedGetEntry(psp: string): boolean;
+/** Whether `url` is exactly the GET entry of this processor's hosted page (false for a processor with none). */
+export declare function isHostedGetEntry(psp: string, url: string): boolean;

package/dist/hosted-entry.js

@@ -0,0 +1,32 @@
+/**
+ * Hosted payment pages whose entry is a plain GET: the processors whose merchant sends the buyer's browser to the
+ * processor's own page with a link (a redirect, or a page or frame location set by script) rather than a form post.
+ *
+ * Such an entry carries no card. The cardholder's device takes it over (mode hosted_form): it makes the processor's
+ * own calls for the payment the link names, and the paused navigation gets this SDK's submitted_on_device notice.
+ * A GET recognizer otherwise reads as a card request carried in the URL (Worldpay eProtect's registration), which
+ * this build completes only for a grammar it checks, so a hosted page joins this table with the exact link
+ * payment-core's resolveRecognizerForUrl admits for it, and nothing else: a URL the table does not admit is never
+ * paused, as the API would refuse it, and the page's own request goes on unchanged.
+ *
+ * Each rule is dark on its own: a processor is paused only once the API serves its recognizer, which it does only
+ * for a build that declares the processor's capability (client.ts SUPPORTED_CAPABILITIES) and a company Agentcard
+ * turned the processor on for. A rule listed here for a processor this build does not declare pauses nothing.
+ */
+import { PRZELEWY24_PSP, isPrzelewy24EntryUrl } from './przelewy24.js';
+import { COMGATE_PSP, isComgateEntryUrl } from './comgate.js';
+import { TRANSBANK_PSP, isTransbankEntryUrl } from './transbank.js';
+const HOSTED_GET_ENTRIES = new Map([
+    [PRZELEWY24_PSP, isPrzelewy24EntryUrl],
+    [COMGATE_PSP, isComgateEntryUrl],
+    [TRANSBANK_PSP, isTransbankEntryUrl],
+]);
+/** Whether this processor's hosted page is entered with a GET this build reads exactly. */
+export function hasHostedGetEntry(psp) {
+    return HOSTED_GET_ENTRIES.has(psp);
+}
+/** Whether `url` is exactly the GET entry of this processor's hosted page (false for a processor with none). */
+export function isHostedGetEntry(psp, url) {
+    const rule = HOSTED_GET_ENTRIES.get(psp);
+    return !!rule && typeof url === 'string' && rule(url) === true;
+}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { CheckoutAttachOptions } from './agentcard.js';
 export { CardEncryptedError, UnsupportedModeError, UnsupportedCapabilityError, PreparationRequiredError, AmountRequiredError, PageAmountRequiredError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, CheckoutAuthError, redactUrl, SUPPORTED_MODES, SUPPORTED_CAPABILITIES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, AdyenTestPlatformRefusedError, MerchantTotalError, PlaceholderCardError, } from './client.js';
 export type { GmoUnsupportedReason } from './gmo.js';
 export type { DatatransRefusalReason } from './datatrans.js';
+export type { TokenexIframeRefusalReason } from './tokenex-iframe.js';
 export type { PelecardRefusalReason } from './pelecard.js';
 export type { PrimerUnsupportedReason, PrimerBlockedReason } from './primer.js';
 export { CONVERGE_REFUSAL_REASONS } from './elavon-converge.js';
@@ -13,6 +14,8 @@ export type { SecureAcceptanceCheckoutRefusal, SecureAcceptanceUnknownReason } f
 export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, MerchantHostedReplay, VerifoneReplay, HostedFormReplay, CardEndpointReplay, DeviceEncryptReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, AgentcardOptions, AdyenTestPlatformRefusal, MerchantTotalRefusal, PrepareCheckoutOptions, PrepareCheckoutInput, PreparedCheckout, RazorpayProcessorError, RuntimeCancelReason, ExecutionMetadata, PlaceholderCard, } from './client.js';
 export type { MicroformField, MicroformSidecar } from './cybersource-flex.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export { BOLT_HOLD_RULE, HOLD_DEADLINES_MS, HOLD_DEFAULT_DEADLINE_MS, HOLD_DEADLINE_MARGIN_MS, HoldAnsweredError, HoldEndedError, matchHoldOnlyRule, placeholderHoldRule } from './hold.js';
+export type { CardRequestHold, HeldCardRequest, HoldOnlyRule, HoldOptions, HoldReleaseInput, HoldReleaseOutcome, HoldState } from './hold.js';
 export { CheckoutAttachmentError } from './attachment.js';
 export { EbanxFollowUpError } from './ebanx.js';
 export { CardEndpointRefusedError, cardEndpointPatterns } from './card-endpoint.js';
@@ -42,7 +45,7 @@ export { VoiceModule, checkoutOriginOf, CANCEL_REASONS, bundleOf, streamAddress,
 export type { VoiceOptions, VoiceTransport } from './voice.js';
 export type { ApiTransport } from './api-module.js';
 export { BuyModule, BuyError, isBuyDeclined, isBuyNeedsApproval, isBuyVoiceUnsupported, BUY_TURN_TIMEOUT_MS, VOICE_EXECUTION_UNSUPPORTED } from './buy.js';
-export type { BuyStatus, BuyApproval, BuyVoiceDeclineCode, BuyCart, BuyCartLine, BuyDeliveryAddress, BuyPaymentSource, BuyOutcome, BuyPlacement, BuyCatalog, BuyUnmatched, BuyTurn, BuyDeclined, BuyNeedsApproval, BuyVoiceUnsupported, BuyVoiceTurn, BuyOrder, BuyLastCheckout, BuyConversation, BuyAskInput, BuyConfirmInput, BuyApproveByVoiceInput, BuyConversationInput, } from './buy.js';
+export type { BuyStatus, BuyApproval, BuyVoiceDeclineCode, BuyCart, BuyCartLine, BuyDeliveryAddress, BuyPaymentSource, BuyOutcome, BuyPlacement, BuyCatalog, BuyUnmatched, BuyTurn, BuyDeclined, BuyNeedsApproval, BuyVoiceUnsupported, BuyVoiceTurn, BuyOrder, BuyLastCheckout, BuyConversation, BuyAskInput, BuyConfirmInput, BuyApproveByVoiceInput, BuyConversationInput, BuyCheckoutHandoff, BuyOpenOffer, BuyBrowserCheckout, BuyApiAmount, } from './buy.js';
 export { Languages } from './languages.js';
 export type { Language, LanguageInfo } from './languages.js';
 export { verifyWebhook, signWebhook, parseWebhookEvent, parseSignatureHeader, isCheckoutAuthorizationEvent, isVaultEvent, CHECKOUT_AUTHORIZATION_EVENT_TYPES, VAULT_EVENT_TYPES } from './webhooks.js';

package/dist/index.js

@@ -4,6 +4,7 @@ export { Agentcard, Agentcard as VaultClient, CheckoutModule } from './agentcard
 export { CardEncryptedError, UnsupportedModeError, UnsupportedCapabilityError, PreparationRequiredError, AmountRequiredError, PageAmountRequiredError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, CheckoutAuthError, redactUrl, SUPPORTED_MODES, SUPPORTED_CAPABILITIES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, AdyenTestPlatformRefusedError, MerchantTotalError, PlaceholderCardError, } from './client.js';
 export { CONVERGE_REFUSAL_REASONS } from './elavon-converge.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export { BOLT_HOLD_RULE, HOLD_DEADLINES_MS, HOLD_DEFAULT_DEADLINE_MS, HOLD_DEADLINE_MARGIN_MS, HoldAnsweredError, HoldEndedError, matchHoldOnlyRule, placeholderHoldRule } from './hold.js';
 export { CheckoutAttachmentError } from './attachment.js';
 // EBANX after its card token: why a send an approved token request covers got no answer from the cardholder's device.
 export { EbanxFollowUpError } from './ebanx.js';

package/dist/lifecycle.d.ts

@@ -6,6 +6,7 @@ import type { GmoUnsupportedReason } from './gmo.js';
 import type { ShijiStsUnsupportedReason } from './shiji-sts.js';
 import type { PaddleVgsPayRefusal } from './paddle-vgs-pay.js';
 import type { PaypalCardFormReason } from './paypal-card-forms.js';
+import { type CardRequestHold, type HoldReleaseInput, type HoldReleaseOutcome } from './hold.js';
 /** The application's resolver confirmed the payment for this checkout authorization. */
 export interface MerchantPaymentConfirmation {
     kind: 'merchant_payment';
@@ -130,6 +131,10 @@ export interface CheckoutController {
     retryAfterMerchantFailure(result: {
         status: 'failed';
     }): void;
+    /** Hold mode (`attachToCdp(…, { hold: true })`): the held card request and its answers; null otherwise. */
+    readonly hold?: CardRequestHold | null;
+    /** Hold mode: `controller.hold.release(input)`. Rejects on an attachment without a hold. */
+    release?(input: HoldReleaseInput): Promise<HoldReleaseOutcome>;
 }
 /** How many times one approval's card-free Stripe confirmation may be checked before it is simply held. */
 export declare const MAX_STRIPE_CONTINUATION_CHECKS = 3;
@@ -167,11 +172,16 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private preparationHandler?;
     private preparationUsed;
     private resumeHandler;
+    private holdHandle;
     readonly abort: AbortController;
     constructor(options: LifecycleOptions);
     getState(): Readonly<CheckoutState>;
     setPreparationHandler(handler: (options: PrepareCheckoutOptions) => Promise<PreparedCheckout>): void;
     prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
+    /** Hold mode: the attachment's hold (hold.ts). */
+    setHold(hold: CardRequestHold): void;
+    get hold(): CardRequestHold | null;
+    release(input: HoldReleaseInput): Promise<HoldReleaseOutcome>;
     /** The transport's hand while one request is paused for the business; null once it is answered. */
     setResumeHandler(handler: ((result: ResumeResult) => Promise<void>) | null): void;
     resume(result: ResumeResult): Promise<void>;

package/dist/lifecycle.js

@@ -2,6 +2,7 @@ import { AdyenTestPlatformRefusedError, ApprovalDeclinedError, ApprovalTimeoutEr
 import { CardEndpointRefusedError } from './card-endpoint.js';
 import { parseOwnedShopReceipt, OWNED_SHOP_SKU, OWNED_SHOP_AMOUNT_CENTS, OWNED_SHOP_CURRENCY } from './owned-shop.generated.js';
 import { isWspayChallenge } from './wspay.js';
+import { HoldAnsweredError, HoldEndedError } from './hold.js';
 /**
  * The statuses that end an attempt: its outcome is known (`completed`, `declined`, `failed`,
  * `timed_out`, `unsupported`, `cancelled`), or the SDK already reported it unknown with its own
@@ -72,6 +73,7 @@ export class CheckoutLifecycle {
     preparationHandler;
     preparationUsed = false;
     resumeHandler = null;
+    holdHandle = null;
     abort = new AbortController();
     constructor(options) {
         this.options = options;
@@ -85,6 +87,14 @@ export class CheckoutLifecycle {
             return Promise.reject(new CheckoutPreparationError(null, 'transport_unavailable'));
         return this.preparationHandler(options);
     }
+    /** Hold mode: the attachment's hold (hold.ts). */
+    setHold(hold) { this.holdHandle = hold; }
+    get hold() { return this.holdHandle; }
+    release(input) {
+        if (!this.holdHandle)
+            return Promise.reject(new Error('No card request hold: attach with hold: true.'));
+        return this.holdHandle.release(input);
+    }
     /** The transport's hand while one request is paused for the business; null once it is answered. */
     setResumeHandler(handler) { this.resumeHandler = handler; }
     resume(result) {
@@ -450,6 +460,17 @@ export class CheckoutLifecycle {
                 this.held = true;
             this.set({ ...this.state, status: error.reason === 'not_enabled' ? 'unsupported' : 'failed', reason: `merchant_card_endpoint_${error.reason}` });
         }
+        else if (error instanceof HoldEndedError) {
+            // Nothing was created or sent; the hold refuses every later card request.
+            this.held = true;
+            this.set({ ...this.state, status: error.reason === 'expired' ? 'timed_out' : 'cancelled', reason: `hold_${error.reason}` });
+        }
+        else if (error instanceof HoldAnsweredError) {
+            // Sandbox: the approval was created and read, and the held request was never sent on.
+            const o = error.outcome.outcome;
+            this.held = true;
+            this.set({ ...this.state, status: o === 'declined' ? 'declined' : o === 'expired' ? 'timed_out' : o === 'approved_not_charged' ? 'cancelled' : 'failed', reason: `hold_${o}` });
+        }
         else if (error instanceof CheckoutCancelledError) {
             this.cancel();
         }