@agent-cards/checkout 0.5.0 → 0.7.0

package/dist/client.d.ts

@@ -19,7 +19,16 @@ export declare const SUPPORTED_MODES: readonly CheckoutMode[];
  * (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';
+/**
+ * Who named the amount an authorization carries: `processor` (the paused
+ * request's own bytes, or the Stripe intent it names, read back by Agentcard),
+ * `agent` (the `amount` you passed), `page` (the total read off the checkout
+ * page), or `none` (nobody yet; the processor is read right before the card
+ * is sent).
+ */
+export type AmountAuthority = 'processor' | 'agent' | 'page' | 'none';
+/** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
+export declare function validAmountInput(amount: unknown): amount is number | string;
 /**
  * The token flow: the cardholder's device called the processor itself, and
  * this is the processor's answer to replay into the paused request.
@@ -41,17 +50,18 @@ export interface TokenReplay {
      * moved) and Agentcard also sent your server checkout_authorization.amount_mismatch.
      */
     amountVerified?: boolean | null;
-    chargedAmountCents?: number | null;
+    /** What the processor collected, an integer in the currency's smallest unit (Stripe's `amount`). */
+    chargedAmount?: number | null;
     chargedCurrency?: string | null;
     /**
-     * What `chargedAmountCents` is: 'captured' (the intent succeeded; this is
+     * What `chargedAmount` 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. */
+    /** Who named the amount the person approved. */
     amountAuthority?: AmountAuthority;
 }
 /**
@@ -102,13 +112,14 @@ export type ReplayResponse = TokenReplay | CseReplay | HostedFormReplay;
 export interface PrepareCheckoutOptions {
     psp: PreparationProcessor;
     /** The processor environment, independent of your Agentcard client's mode. */
-    environment: 'production' | 'sandbox';
+    environment: 'production' | 'sandbox' | 'shared';
     signal?: AbortSignal;
 }
 export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
     user: string;
     merchant: string;
-    amountCents: number;
+    /** An integer in the currency's smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06"). */
+    amount: number | string;
     currency: string;
     cardId?: string;
     merchantOrigin: string;
@@ -122,17 +133,19 @@ export interface PreparedCheckout {
     readonly id: string;
     readonly status: 'ready';
     readonly psp: PreparationProcessor;
-    readonly environment: 'production' | 'sandbox';
+    readonly environment: 'production' | 'sandbox' | 'shared';
     readonly expiresAt: string;
     readonly cardId: string;
     readonly user: string;
     readonly merchant: string;
-    readonly amountCents: number;
+    /** The approved amount, an integer in the currency's smallest unit, as the API confirmed it. */
+    readonly amount: number;
+    readonly amountDisplay: string | null;
     readonly currency: string;
     readonly merchantOrigin: string;
     readonly checkoutKey: string;
     readonly paymentStatus: 'not_started';
-    readonly amountAuthority: 'display_only';
+    readonly amountAuthority: 'agent';
 }
 export declare class CheckoutPreparationError extends Error {
     preparationId: string | null;
@@ -142,27 +155,31 @@ export declare class CheckoutPreparationError extends Error {
 export interface AuthorizeInput {
     /** Your identifier for the person whose card should pay. */
     user: string;
-    /** Shown to the user on the approval screen. */
+    /** Shown to the user on the approval screen. Judged by nothing: the merchant comes from the checkout page. */
     merchant: 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.
+     * Your hint at the amount: an integer in the currency's smallest unit (2306
+     * for $23.06), or a decimal string in normal units ("23.06"), with its ISO
+     * 4217 code ("usd"). Optional: the processor's own amount is the higher
+     * authority, read from the paused request or from the Stripe intent it
+     * names right before the cardholder's device replays, and the company's
+     * caps are judged on it. A hint lets a bad purchase be refused the moment
+     * you open it, and a hint that disagrees with the processor beyond one
+     * smallest unit is refused with nothing charged (an AmountMismatchError;
+     * `stage` says which check). Agentcard derives the display string; you
+     * never send one. Both or neither: one without the other is refused.
      */
-    amount?: string;
+    amount?: number | string;
+    currency?: 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.
+     * The total read off the checkout page, the lowest authority: used only
+     * when neither the processor's request nor your hint names an amount. The
+     * adapters fill it from `[data-agentcard-amount]` when a page carries one.
      */
-    amountCents?: number;
-    currency?: string;
+    pageAmount?: {
+        amount: 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
@@ -171,6 +188,14 @@ export interface AuthorizeInput {
      * `card_not_found`.
      */
     cardId?: string;
+    /**
+     * The origin of the checkout page the payment form was on
+     * (https://shop.example.com). The adapters read it from the page; pass it
+     * yourself when you run your own interception. With the processor identity
+     * in the paused request this is what names the merchant for the company's
+     * presets; `merchant` above is shown to the person and judged by nothing.
+     */
+    pageOrigin?: string;
     request: PausedRequest;
     /** Abort if the user has not approved within this many ms. Default 15 min. */
     timeoutMs?: number;
@@ -300,6 +325,69 @@ export declare class ProcessorRefusedError extends ApprovalDeclinedError {
  * retrying is worth anything: a 404 `connection_not_found` will answer the same
  * way forever, while a 429 or a 502 will not.
  */
+/**
+ * The company's preset refused the purchase. The company that runs this
+ * integration put rules on its users' Vault purchases (a merchant list, a
+ * currency, a spend cap, a time window); this purchase is outside them.
+ * Nothing was charged. Two stages:
+ *   - 'create': refused before any authorization existed (`authorizationId`
+ *     is null); nobody was asked to approve. Per purchase, not per page: the
+ *     next request on the same page is judged afresh.
+ *   - 'pre_replay': refused right before the cardholder's device would have
+ *     sent the card; the authorization is `declined` with `code` as reason.
+ * `code` is the rule's reason (merchant_denied, currency_denied,
+ * spend_rate_exceeded, time_window_denied, ...), `message` the rule's own
+ * statement with the company's next step, `preset` the version that judged
+ * it. When several presets refused the same purchase, `code`, `preset`,
+ * `rule` and `attachment` are the first, and `refusals` names every one. A
+ * decline in every structural sense (the adapters quiet the page's retry as
+ * for a person's "no"), so it extends ApprovalDeclinedError.
+ */
+export declare class PresetRefusedError extends ApprovalDeclinedError {
+    readonly authorizationId: string | null;
+    readonly code: string;
+    readonly detail: string | null;
+    readonly preset: {
+        id: string;
+        version: number;
+        name: string;
+    } | null;
+    readonly rule: string | null;
+    readonly stage: 'create' | 'pre_replay';
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    readonly attachment: PresetAttachment | null;
+    /** The preset's name. */
+    readonly presetName: string | null;
+    /** Every preset that refused, each with its attachment, rule, code and statement; one entry when one refused. */
+    readonly refusals: readonly PresetRefusal[];
+    constructor(authorizationId: string | null, code: string, detail: string | null, preset: {
+        id: string;
+        version: number;
+        name: string;
+    } | null, rule: string | null, stage: 'create' | 'pre_replay', 
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    attachment?: PresetAttachment | null, refusals?: readonly PresetRefusal[]);
+}
+/** The stored card a preset is attached to, with its last four digits. */
+export interface PresetAttachment {
+    kind: 'card';
+    targetId: string | null;
+    last4: string | null;
+}
+/** One preset's refusal of a purchase. */
+export interface PresetRefusal {
+    preset: {
+        id: string;
+        version: number;
+        name: string;
+    };
+    attachment: PresetAttachment | null;
+    rule: string | null;
+    code: string;
+    detail: string | null;
+}
+/** A decline reason only the company presets stamp (see PresetRefusedError). */
+export declare const PRESET_REFUSAL_REASONS: ReadonlySet<string>;
 export declare class CheckoutApiError extends Error {
     status: number;
     path: string;

package/dist/client.js

@@ -1,12 +1,18 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.js';
-import { matchesPreparedRequest } from './prepared-processor.js';
+import { matchesPreparedRequest, validPreparationEnvironment } from './prepared-processor.js';
 /**
  * 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 const SUPPORTED_MODES = ['token', 'cse', 'hosted_form'];
-const AMOUNT_AUTHORITIES = ['stripe_payment_intent', 'hosted_form_sum', 'display_only'];
+/** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
+export function validAmountInput(amount) {
+    if (typeof amount === 'number')
+        return Number.isSafeInteger(amount) && amount >= 0;
+    return typeof amount === 'string' && /^\d{1,15}\.\d{1,3}$/.test(amount.trim());
+}
+const AMOUNT_AUTHORITIES = ['processor', 'agent', 'page', 'none'];
 export class CheckoutPreparationError extends Error {
     preparationId;
     reason;
@@ -180,6 +186,94 @@ export class ProcessorRefusedError extends ApprovalDeclinedError {
  * retrying is worth anything: a 404 `connection_not_found` will answer the same
  * way forever, while a 429 or a 502 will not.
  */
+/**
+ * The company's preset refused the purchase. The company that runs this
+ * integration put rules on its users' Vault purchases (a merchant list, a
+ * currency, a spend cap, a time window); this purchase is outside them.
+ * Nothing was charged. Two stages:
+ *   - 'create': refused before any authorization existed (`authorizationId`
+ *     is null); nobody was asked to approve. Per purchase, not per page: the
+ *     next request on the same page is judged afresh.
+ *   - 'pre_replay': refused right before the cardholder's device would have
+ *     sent the card; the authorization is `declined` with `code` as reason.
+ * `code` is the rule's reason (merchant_denied, currency_denied,
+ * spend_rate_exceeded, time_window_denied, ...), `message` the rule's own
+ * statement with the company's next step, `preset` the version that judged
+ * it. When several presets refused the same purchase, `code`, `preset`,
+ * `rule` and `attachment` are the first, and `refusals` names every one. A
+ * decline in every structural sense (the adapters quiet the page's retry as
+ * for a person's "no"), so it extends ApprovalDeclinedError.
+ */
+export class PresetRefusedError extends ApprovalDeclinedError {
+    authorizationId;
+    code;
+    detail;
+    preset;
+    rule;
+    stage;
+    attachment;
+    /** The preset's name. */
+    presetName;
+    /** Every preset that refused, each with its attachment, rule, code and statement; one entry when one refused. */
+    refusals;
+    constructor(authorizationId, code, detail, preset, rule, stage, 
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    attachment = null, refusals = []) {
+        super(code);
+        this.authorizationId = authorizationId;
+        this.code = code;
+        this.detail = detail;
+        this.preset = preset;
+        this.rule = rule;
+        this.stage = stage;
+        this.attachment = attachment;
+        this.name = 'PresetRefusedError';
+        this.presetName = preset?.name ?? null;
+        this.refusals = refusals.length ? refusals : preset ? [{ preset, attachment, rule, code, detail }] : [];
+        const others = this.refusals.slice(1).map((r) => `"${r.preset.name}"`);
+        const also = others.length ? ` Also refused by ${others.length === 1 ? 'preset' : 'presets'} ${others.join(', ')}.` : '';
+        this.message = `refused by the company preset${preset ? ` "${preset.name}"` : ''} (${code}${stage === 'create' ? ', before any authorization was created' : ''}): ${detail ?? 'this purchase is outside the rules the company set'}${also}`;
+    }
+}
+/** A decline reason only the company presets stamp (see PresetRefusedError). */
+export const PRESET_REFUSAL_REASONS = new Set([
+    'spend_total_exceeded', 'spend_rate_exceeded', 'spend_rate_unknown',
+    'category_denied', 'category_unknown', 'merchant_denied', 'merchant_unknown',
+    'geo_denied', 'geo_unknown', 'currency_denied', 'currency_unknown',
+    'time_window_denied', 'surface_denied', 'surface_unknown',
+]);
+function presetOf(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const p = v;
+    if (typeof p.id !== 'string' || typeof p.version !== 'number' || typeof p.name !== 'string')
+        return null;
+    return { id: p.id, version: p.version, name: p.name };
+}
+function attachmentOf(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const a = v;
+    if (a.kind !== 'card')
+        return null;
+    return { kind: a.kind, targetId: typeof a.target_id === 'string' ? a.target_id : null, last4: typeof a.last4 === 'string' ? a.last4 : null };
+}
+/** The `refusals` list of a refusal envelope: every entry that names a preset. */
+function refusalsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const r = item;
+        const preset = presetOf(r.preset);
+        if (!preset || typeof r.reason !== 'string')
+            continue;
+        out.push({ preset, attachment: attachmentOf(r.attachment), rule: typeof r.rule === 'string' ? r.rule : null, code: r.reason, detail: typeof r.message === 'string' ? r.message : null });
+    }
+    return out;
+}
 export class CheckoutApiError extends Error {
     status;
     path;
@@ -218,6 +312,12 @@ export class CheckoutApiError extends Error {
     get permanent() {
         if (this.code === 'amount_mismatch' || this.code === 'duplicate_submission')
             return false;
+        // Nor a refusal by the company preset (a 403 carrying `preset` in the
+        // envelope): the company's rules refused THIS purchase, at this merchant,
+        // for this amount, at this hour. The next one on the same page may pass,
+        // so the page is quieted like a decline, never latched.
+        if (this.details.preset && typeof this.details.preset === 'object')
+            return false;
         return this.status >= 400 && this.status < 500 && this.status !== 429;
     }
 }
@@ -315,9 +415,9 @@ export class VaultClient {
     async prepareCheckout(input) {
         input = { ...input };
         const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
-        if (!['square', 'braintree'].includes(input.psp) || !['production', 'sandbox'].includes(input.environment))
+        if (!validPreparationEnvironment(input.psp, input.environment))
             throw fail('unsupported_processor');
-        if (!Number.isSafeInteger(input.amountCents) || input.amountCents <= 0 || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
+        if (!validAmountInput(input.amount) || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
             throw fail('amount_required');
         const origin = new URL(input.merchantOrigin);
         if (!(origin.protocol === 'https:' || (origin.protocol === 'http:' && origin.hostname === 'localhost')) || origin.origin !== input.merchantOrigin)
@@ -336,7 +436,7 @@ export class VaultClient {
             // Drain a sent creation even after caller cancellation to retire its ID.
             // The separate stop signal prevents dispatch after a slow OAuth exchange.
             const created = await this.post('/v2/checkout/preparations', {
-                user: input.user, merchant: input.merchant, amount_cents: input.amountCents, currency: input.currency.toLowerCase(),
+                user: input.user, merchant: input.merchant, amount: input.amount, currency: input.currency.toLowerCase(),
                 ...(input.cardId ? { card_id: input.cardId } : {}), psp: input.psp, mode: 'token',
                 environment: input.environment, checkout_key: input.checkoutKey, merchant_origin: input.merchantOrigin,
             }, AbortSignal.timeout(30_000), signal);
@@ -365,17 +465,18 @@ export class VaultClient {
                 if (state.status === 'ready') {
                     const expiry = Date.parse(state.ready_expires_at);
                     if (!Number.isFinite(expiry) || expiry <= Date.now() || typeof state.card_id !== 'string' || !state.card_id
-                        || state.payment_status !== 'not_started' || state.amount_authority !== 'display_only'
+                        || state.payment_status !== 'not_started' || state.amount_authority !== 'agent'
                         || state.user !== input.user || state.merchant !== input.merchant || state.merchant_origin !== input.merchantOrigin
-                        || state.amount_cents !== input.amountCents || state.currency !== input.currency.toLowerCase()
+                        || !Number.isSafeInteger(state.amount) || (typeof input.amount === 'number' && state.amount !== input.amount) || state.currency !== input.currency.toLowerCase()
                         || state.psp !== input.psp || state.mode !== 'token' || state.environment !== input.environment
                         || state.checkout_key !== input.checkoutKey)
                         throw fail('ready_unconfirmed', id);
                     const prepared = Object.freeze({
                         id: preparationId, status: 'ready', psp: input.psp, environment: input.environment, expiresAt: state.ready_expires_at,
-                        cardId: state.card_id, user: input.user, merchant: input.merchant, amountCents: input.amountCents,
+                        cardId: state.card_id, user: input.user, merchant: input.merchant, amount: state.amount,
+                        amountDisplay: typeof state.amount_display === 'string' ? state.amount_display : null,
                         currency: input.currency.toLowerCase(), merchantOrigin: input.merchantOrigin, checkoutKey: input.checkoutKey,
-                        paymentStatus: 'not_started', amountAuthority: 'display_only',
+                        paymentStatus: 'not_started', amountAuthority: 'agent',
                     });
                     this.preparations.add(prepared);
                     ready = true;
@@ -419,7 +520,7 @@ export class VaultClient {
             this.usedPreparations.add(preparation);
             if (Date.parse(preparation.expiresAt) <= Date.now())
                 throw new CheckoutPreparationError(preparation.id, 'expired');
-            if (input.user !== preparation.user || input.merchant !== preparation.merchant || input.amountCents !== preparation.amountCents
+            if (input.user !== preparation.user || input.merchant !== preparation.merchant || (typeof input.amount === 'number' && input.amount !== preparation.amount) || (typeof input.amount === 'string' && !validAmountInput(input.amount))
                 || input.currency?.toLowerCase() !== preparation.currency || input.cardId !== preparation.cardId
                 || !matchesPreparedRequest(preparation.psp, preparation.environment, input.request.url, input.request.method ?? 'POST', input.request.body))
                 throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
@@ -452,16 +553,16 @@ export class VaultClient {
             throw new Error(`checkout authorization is POST-only; got ${method} for ${redactUrl(input.request.url)}. ` +
                 'A non-POST tokenizer needs recognizer support before it can be intercepted.');
         }
-        // The amount travels as a display string, a number with its currency, or
-        // both. Refuse half a pair here, before a network call: the API would too,
-        // and a retry loop cannot fix a missing field.
-        const hasCents = input.amountCents != null;
+        // The amount is a hint: a pair or nothing. Refuse half a pair here, before
+        // a network call: the API would too, and a retry loop cannot fix a
+        // missing field. The processor's own amount is read by Agentcard.
+        const hasAmount = input.amount != null;
         const hasCurrency = typeof input.currency === 'string' && input.currency.length > 0;
-        if (hasCents !== hasCurrency) {
-            throw new Error('amountCents and currency go together: pass both or neither.');
+        if (hasAmount !== hasCurrency) {
+            throw new Error('amount and currency go together: pass both or neither.');
         }
-        if (!input.amount && !hasCents) {
-            throw new Error('authorize needs amount (a display string), or amountCents with currency.');
+        if (hasAmount && !validAmountInput(input.amount)) {
+            throw new Error('amount is an integer in the currency\'s smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06").');
         }
         const timeoutMs = input.timeoutMs ?? 15 * 60_000;
         if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
@@ -473,15 +574,18 @@ export class VaultClient {
         const payload = {
             user: input.user,
             merchant: input.merchant,
-            ...(input.amount ? { amount: input.amount } : {}),
             // snake_case on the wire; camelCase is this SDK's convention.
-            ...(hasCents ? { amount_cents: input.amountCents, currency: input.currency } : {}),
+            ...(hasAmount ? { amount: input.amount, currency: input.currency } : {}),
+            ...(input.pageAmount ? { page_amount: input.pageAmount.amount, page_currency: input.pageAmount.currency } : {}),
             psp: rec.psp,
             // The mode this request will be finished in. The API checks it against
             // the recognizer and refuses a disagreement before a row exists.
             mode,
             ...(input.cardId ? { cardId: input.cardId } : {}),
-            ...(preparation ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin } : {}),
+            // A prepared checkout already carries the page origin as merchant_origin.
+            ...(preparation
+                ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin }
+                : input.pageOrigin ? { checkout_origin: input.pageOrigin } : {}),
             request: {
                 url: input.request.url,
                 method: input.request.method,
@@ -621,7 +725,7 @@ export class VaultClient {
                         authorizationId,
                         ...response,
                         amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
-                        chargedAmountCents: typeof s.charged_amount_cents === 'number' ? s.charged_amount_cents : null,
+                        chargedAmount: typeof s.charged_amount === 'number' ? s.charged_amount : null,
                         chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
                         chargedKind: s.charged_kind === 'captured' || s.charged_kind === 'authorized' || s.charged_kind === 'none' ? s.charged_kind : null,
                         ...amountAuthority,
@@ -635,6 +739,9 @@ export class VaultClient {
                     }
                     if (s.reason === 'intent_not_confirmable')
                         throw new IntentNotConfirmableError(String(created.id));
+                    if (typeof s.reason === 'string' && PRESET_REFUSAL_REASONS.has(s.reason)) {
+                        throw new PresetRefusedError(String(created.id), s.reason, typeof s.message === 'string' ? s.message : null, presetOf(s.preset), typeof s.rule === 'string' ? s.rule : null, 'pre_replay', attachmentOf(s.attachment), refusalsOf(s.refusals));
+                    }
                     if (s.reason === 'processor_refused') {
                         throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null, s.psp === 'razorpay' ? parseProcessorError(s.processor_error) : null);
                     }
@@ -718,6 +825,11 @@ export class VaultClient {
                 return await this.post('/v2/checkout/authorizations', payload, signal, stopRetries);
             }
             catch (err) {
+                if (err instanceof CheckoutApiError && err.code && err.status === 403 && presetOf(err.details.preset)) {
+                    // A company preset refused this purchase before a row existed.
+                    const d = err.details;
+                    throw new PresetRefusedError(null, err.code, typeof d.message === 'string' ? d.message : null, presetOf(d.preset), typeof d.rule === 'string' ? d.rule : null, 'create', attachmentOf(d.attachment), refusalsOf(d.refusals));
+                }
                 if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
                     const d = err.details;
                     throw new AmountMismatchError(null, Number(d.expected_cents), Number(d.actual_cents), String(d.currency ?? currency ?? ''), d.actual_currency != null ? String(d.actual_currency) : undefined, 'create');

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
 export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, PrepareCheckoutOptions, PrepareCheckoutInput, PreparedCheckout, RazorpayProcessorError, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export { CheckoutAttachmentError } from './attachment.js';
 export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export type { Substitutions } from './substitute.js';

package/dist/index.js

@@ -1,5 +1,6 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export { CheckoutAttachmentError } from './attachment.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';

package/dist/preparation.js

@@ -1,5 +1,6 @@
 import { CheckoutPreparationError } from './client.js';
-import { matchesPreparedRequest, preparationEndpoint } from './prepared-processor.js';
+import { validAmountInput } from './client.js';
+import { matchesPreparedRequest, validPreparationEnvironment, preparationEndpoint } from './prepared-processor.js';
 /** A local, one-use rendezvous. It never starts or retries a merchant request. */
 export class PreparationGate {
     opts;
@@ -34,12 +35,12 @@ export class PreparationGate {
         const onAbort = () => this.invalidate('cancelled');
         signal.addEventListener('abort', onAbort, { once: true });
         try {
-            if (!options || !['square', 'braintree'].includes(options.psp) || !['production', 'sandbox'].includes(options.environment))
+            if (!options || !validPreparationEnvironment(options.psp, options.environment))
                 throw new CheckoutPreparationError(null, 'unsupported_processor');
             const tokenizer = preparationEndpoint(options.psp, options.environment);
             if (!this.opts.vault.isCardRequest(tokenizer, 'POST'))
                 throw new CheckoutPreparationError(null, 'processor_interception_unavailable');
-            if (!Number.isSafeInteger(this.opts.amountCents) || (this.opts.amountCents ?? 0) <= 0 || !/^[a-z]{3}$/i.test(this.opts.currency ?? ''))
+            if (!validAmountInput(this.opts.amount) || this.opts.amount === 0 || !/^[a-z]{3}$/i.test(this.opts.currency ?? ''))
                 throw new CheckoutPreparationError(null, 'amount_required');
             if (signal.aborted)
                 throw new CheckoutPreparationError(null, 'cancelled');
@@ -49,7 +50,7 @@ export class PreparationGate {
                 throw new CheckoutPreparationError(null, 'merchant_origin_invalid');
             const prepared = await this.opts.vault.prepareCheckout({
                 ...options, user: this.opts.user, merchant: this.opts.merchant,
-                amountCents: this.opts.amountCents, currency: this.opts.currency, cardId: this.opts.cardId,
+                amount: this.opts.amount, currency: this.opts.currency, cardId: this.opts.cardId,
                 merchantOrigin: page.origin, checkoutKey: crypto.randomUUID(), timeoutMs: this.opts.timeoutMs, signal,
                 onPreparationCreated: id => this.lifecycle.preparationCreated(id),
                 onApprovalUrl: url => {

package/dist/prepared-processor.d.ts

@@ -1,5 +1,7 @@
-export type PreparationProcessor = 'square' | 'braintree';
-export type PreparationEnvironment = 'production' | 'sandbox';
+export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago';
+export type PreparationEnvironment = 'production' | 'sandbox' | 'shared';
+/** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. */
+export declare function validPreparationEnvironment(psp: string, environment: string): boolean;
 export declare function preparationEndpoint(psp: PreparationProcessor, environment: PreparationEnvironment): string;
 /** Processor identity and environment are part of the device's prior consent. */
 export declare function matchesPreparedRequest(psp: PreparationProcessor, environment: PreparationEnvironment, requestUrl: string, method: string, body?: string | null): boolean;

package/dist/prepared-processor.js

@@ -1,23 +1,91 @@
-import { braintreeEnvironment, isPreparedBraintreeRequest } from './braintree.js';
+import { braintreeEnvironment, isPreparedBraintreeRequest, readTokenizationJson } from './braintree.js';
+/** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. */
+export function validPreparationEnvironment(psp, environment) {
+    if (psp === 'bambora' || psp === 'mercado_pago')
+        return environment === 'shared';
+    return ['square', 'braintree', 'worldpay'].includes(psp) && ['production', 'sandbox'].includes(environment);
+}
 export function preparationEndpoint(psp, environment) {
+    if (!validPreparationEnvironment(psp, environment))
+        throw new Error('unsupported_preparation_processor');
+    if (psp === 'bambora')
+        return 'https://api.bam.shift4api.net/scripts/tokenization/tokens';
+    if (psp === 'mercado_pago')
+        return 'https://api.mercadopago.com/v1/card_tokens';
+    if (psp === 'worldpay')
+        return environment === 'production'
+            ? 'https://access.worldpay.com/sessions/card' : 'https://try.access.worldpay.com/sessions/card';
     if (psp === 'braintree')
         return environment === 'production'
             ? 'https://payments.braintree-api.com/graphql' : 'https://payments.sandbox.braintree-api.com/graphql';
     return environment === 'production'
         ? 'https://pci-connect.squareup.com/v2/card-nonce' : 'https://pci-connect.squareupsandbox.com/v2/card-nonce';
 }
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+const keys = (value, allowed) => Object.keys(value).every(key => allowed.includes(key));
+const string = (value, max = 1024) => typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+const digits = (value, min, max) => typeof value === 'string' && value.length >= min && value.length <= max && !/[^0-9]/.test(value);
+const month = (value) => (typeof value === 'number' && Number.isInteger(value) || digits(value, 1, 2)) && Number(value) >= 1 && Number(value) <= 12;
+const year = (value) => (typeof value === 'number' && Number.isInteger(value) || digits(value, 2, 4)) && (Number(value) >= 0 && Number(value) <= 99 || Number(value) >= 2000 && Number(value) <= 9999);
+/** Native fresh-card shapes only. Saved-card, charge and recurring siblings never consume consent. */
+function freshCardBody(psp, body) {
+    const value = readTokenizationJson(body);
+    if (!value)
+        return false;
+    if (psp === 'worldpay')
+        return keys(value, ['identity', 'cardNumber', 'cardExpiryDate', 'cvc'])
+            && string(value.identity) && digits(value.cardNumber, 12, 19)
+            && record(value.cardExpiryDate) && keys(value.cardExpiryDate, ['month', 'year'])
+            && month(value.cardExpiryDate.month) && year(value.cardExpiryDate.year)
+            && (value.cvc === undefined || digits(value.cvc, 3, 4));
+    if (psp === 'bambora')
+        return keys(value, ['number', 'expiry_month', 'expiry_year', 'cvd'])
+            && digits(value.number, 12, 19) && month(value.expiry_month) && year(value.expiry_year)
+            && (value.cvd === undefined || digits(value.cvd, 3, 4));
+    if (psp !== 'mercado_pago' || !keys(value, ['card_number', 'expiration_month', 'expiration_year', 'security_code', 'cardholder', 'device'])
+        || !digits(value.card_number, 12, 19) || !month(value.expiration_month) || !year(value.expiration_year)
+        || (value.security_code !== undefined && value.security_code !== '' && !digits(value.security_code, 3, 4)) || !record(value.cardholder)
+        || !keys(value.cardholder, ['name', 'identification']))
+        return false;
+    const holder = value.cardholder;
+    if (holder.name !== undefined && holder.name !== '' && !string(holder.name))
+        return false;
+    if (holder.identification !== undefined && (!record(holder.identification) || !keys(holder.identification, ['type', 'number'])
+        || Object.values(holder.identification).some(v => v !== '' && !string(v))))
+        return false;
+    if (value.device !== undefined && (!record(value.device) || !keys(value.device, ['meli'])
+        || !record(value.device.meli) || !keys(value.device.meli, ['session_id']) || !string(value.device.meli.session_id, 4096)))
+        return false;
+    return true;
+}
 /** Processor identity and environment are part of the device's prior consent. */
 export function matchesPreparedRequest(psp, environment, requestUrl, method, body) {
-    if (method.toUpperCase() !== 'POST')
+    if (method.toUpperCase() !== 'POST' || !validPreparationEnvironment(psp, environment))
         return false;
-    if (psp === 'braintree') {
+    if (psp === 'braintree')
         return braintreeEnvironment(requestUrl) === environment && isPreparedBraintreeRequest(body ?? null);
-    }
-    if (psp !== 'square')
-        return false;
     try {
         const request = new URL(requestUrl), endpoint = new URL(preparationEndpoint(psp, environment));
-        return request.origin === endpoint.origin && request.pathname === endpoint.pathname && !request.username && !request.password;
+        if (request.username || request.password || request.hash)
+            return false;
+        if (psp === 'bambora') {
+            if (![endpoint.href, 'https://api.na.bambora.com/scripts/tokenization/tokens'].includes(requestUrl))
+                return false;
+        }
+        else if (psp === 'worldpay') {
+            if (requestUrl !== endpoint.href)
+                return false;
+        }
+        else if (request.origin !== endpoint.origin || request.pathname !== endpoint.pathname)
+            return false;
+        if (psp === 'mercado_pago') {
+            const names = [...request.searchParams.keys()];
+            if (new Set(names).size !== names.length || names.some(name => !['public_key', 'locale', 'js_version', 'referer'].includes(name)))
+                return false;
+        }
+        return psp === 'square' || freshCardBody(psp, body ?? null);
     }
     catch {
         return false;