@agent-cards/checkout 0.18.0 → 0.21.0

package/dist/hosted-form.d.ts

@@ -1,44 +0,0 @@
-/**
- * The hosted_form half of a replay: what the paused navigation is resolved
- * with once the cardholder's device has submitted the processor's own form.
- *
- * On a hosted-form processor (Tranzila) the paused request is a top-level
- * form navigation inside the processor's iframe, not an XHR. The cardholder's
- * device rebuilds that form with the real card and submits it itself, so the
- * processor's answer (approved, declined) is shown on the device and reaches
- * the merchant from the processor. The agent's browser never gets it.
- *
- * The paused navigation still has to resolve to SOMETHING. Aborting it is the
- * wrong something: an aborted navigation renders no error page, the iframe
- * silently stays on the dummy-card form, and the agent's natural next move is
- * to click Pay again. A fake copy of the processor's result page is wrong too:
- * this SDK does not know the outcome or the merchant's contract, so it must
- * not claim one. What it CAN say is exactly what happened: the cardholder
- * completed this payment on their own device, do not resubmit, confirm the
- * order with the merchant. This page says that, for a person and for an
- * agent, and nothing else.
- */
-export interface HostedFormSubmittedPageInput {
-    /** The approved authorization (`cauth_…`). */
-    authorizationId: string;
-    /** The merchant name the authorization was created with. */
-    merchant: string;
-    /** When the device reported the form left it (ISO 8601). */
-    submittedAt: string;
-}
-export interface SyntheticPage {
-    status: 200;
-    headers: Record<string, string>;
-    body: string;
-}
-/** The outcome word on the page, the header and the JSON: one spelling everywhere. */
-export declare const HOSTED_FORM_SUBMITTED_OUTCOME = "submitted_on_device";
-/**
- * A self-contained HTML document: no external resources, no script that runs
- * (the one `<script>` is `application/json`, inert by type), machine-readable
- * through the meta tag, the header and the JSON block, and human-readable in
- * one paragraph. `merchant` is integrator text and lands escaped; inside the
- * JSON every `<`, `>` and `&` is a \u escape (still valid JSON), so a merchant
- * name can never close the script block early or open a comment inside it.
- */
-export declare function hostedFormSubmittedPage(input: HostedFormSubmittedPageInput): SyntheticPage;

package/dist/hosted-form.js

@@ -1,78 +0,0 @@
-/**
- * The hosted_form half of a replay: what the paused navigation is resolved
- * with once the cardholder's device has submitted the processor's own form.
- *
- * On a hosted-form processor (Tranzila) the paused request is a top-level
- * form navigation inside the processor's iframe, not an XHR. The cardholder's
- * device rebuilds that form with the real card and submits it itself, so the
- * processor's answer (approved, declined) is shown on the device and reaches
- * the merchant from the processor. The agent's browser never gets it.
- *
- * The paused navigation still has to resolve to SOMETHING. Aborting it is the
- * wrong something: an aborted navigation renders no error page, the iframe
- * silently stays on the dummy-card form, and the agent's natural next move is
- * to click Pay again. A fake copy of the processor's result page is wrong too:
- * this SDK does not know the outcome or the merchant's contract, so it must
- * not claim one. What it CAN say is exactly what happened: the cardholder
- * completed this payment on their own device, do not resubmit, confirm the
- * order with the merchant. This page says that, for a person and for an
- * agent, and nothing else.
- */
-/** The outcome word on the page, the header and the JSON: one spelling everywhere. */
-export const HOSTED_FORM_SUBMITTED_OUTCOME = 'submitted_on_device';
-function escapeHtml(s) {
-    return String(s)
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
-/**
- * A self-contained HTML document: no external resources, no script that runs
- * (the one `<script>` is `application/json`, inert by type), machine-readable
- * through the meta tag, the header and the JSON block, and human-readable in
- * one paragraph. `merchant` is integrator text and lands escaped; inside the
- * JSON every `<`, `>` and `&` is a \u escape (still valid JSON), so a merchant
- * name can never close the script block early or open a comment inside it.
- */
-export function hostedFormSubmittedPage(input) {
-    const merchant = String(input.merchant ?? '');
-    const record = {
-        outcome: HOSTED_FORM_SUBMITTED_OUTCOME,
-        // In words, so an agent reading this block cannot take it for a receipt:
-        // the cardholder's device attested the form left it, nothing more.
-        payment: 'unverified',
-        attested_by: 'cardholder_device',
-        authorization_id: String(input.authorizationId),
-        merchant,
-        submitted_at: String(input.submittedAt),
-        next: "poll the merchant's order state; never resubmit",
-    };
-    const json = JSON.stringify(record).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026');
-    const body = [
-        '<!doctype html>',
-        '<html lang="en">',
-        '<head>',
-        '<meta charset="utf-8">',
-        `<meta name="agentcard-checkout" content="${HOSTED_FORM_SUBMITTED_OUTCOME}">`,
-        '<meta name="robots" content="noindex">',
-        '<title>Submitted on the cardholder\'s device</title>',
-        '</head>',
-        '<body>',
-        `<p>The cardholder submitted this payment from their own device. Agentcard holds no evidence of the processor's answer: this is not a receipt. Do not resubmit this form. Confirm the order with the merchant${merchant ? ` (${escapeHtml(merchant)})` : ''}.</p>`,
-        `<script type="application/json" id="agentcard-checkout">${json}</script>`,
-        '</body>',
-        '</html>',
-        '',
-    ].join('\n');
-    return {
-        status: 200,
-        headers: {
-            'content-type': 'text/html; charset=utf-8',
-            'cache-control': 'no-store',
-            'x-agentcard-checkout': HOSTED_FORM_SUBMITTED_OUTCOME,
-        },
-        body,
-    };
-}

package/dist/index.d.ts

@@ -1,13 +0,0 @@
-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, RuntimeCancelReason, ExecutionMetadata, } 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 type { StripeCheckoutOptions, StripeCheckoutBlockedDetail, StripeCheckoutBlockStage, StripeCheckoutBlockReason } from './stripe-checkout.js';
-export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
-export type { Substitutions } from './substitute.js';
-export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';
-export type { HostedFormSubmittedPageInput, SyntheticPage } from './hosted-form.js';
-export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';
-export type { Recognizer, CheckoutMode } from './registry.js';
-export type { CheckoutController, CheckoutState, MerchantResult, MerchantPaymentConfirmation, UserAction, LifecycleOptions, PaymentEndpointGuard } from './lifecycle.js';

package/dist/index.js

@@ -1,6 +0,0 @@
-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/lifecycle.d.ts

@@ -1,165 +0,0 @@
-import { CheckoutPreparationError, type PrepareCheckoutOptions, type PreparedCheckout, type ReplayResponse } from './client.js';
-import type { CheckoutMode } from './registry.js';
-/** The application's resolver confirmed the payment for this checkout authorization. */
-export interface MerchantPaymentConfirmation {
-    kind: 'merchant_payment';
-    authorizationId: string;
-}
-/** Only authoritative merchant evidence can confirm completion; a processor token is insufficient. */
-export type MerchantResult = {
-    status: 'completed';
-    orderId: string;
-    confirmation?: never;
-} | {
-    status: 'completed';
-    confirmation: MerchantPaymentConfirmation;
-    orderId?: never;
-} | {
-    status: 'failed';
-} | {
-    status: 'pending' | 'unknown';
-} | {
-    status: 'requires_user_action';
-    reason: '3ds' | 'redirect' | 'other';
-};
-export interface CheckoutState {
-    status: 'idle' | 'awaiting_approval' | 'ready_to_submit' | 'awaiting_merchant' | 'requires_user_action' | 'completed' | 'declined' | 'timed_out' | 'cancelled' | 'unsupported' | 'outcome_unknown' | 'failed';
-    authorizationId: string | null;
-    preparationId?: string;
-    mode?: CheckoutMode;
-    orderId?: string;
-    confirmation?: MerchantPaymentConfirmation;
-    /** Stable SDK category; never includes a request body, processor response, or approval link. */
-    reason?: string;
-}
-export interface UserAction {
-    reason: 'approval' | '3ds' | 'redirect' | 'other';
-    authorizationId: string | null;
-    /** Sensitive approval capability. Deliver privately; do not put this in ordinary telemetry. */
-    approvalUrl?: string;
-}
-export interface LifecycleOptions {
-    onStateChange?: (state: Readonly<CheckoutState>) => void;
-    onUserAction?: (action: UserAction) => void | Promise<void>;
-    /** Read authoritative merchant payment or order state; do not click Pay or initiate a new charge here. */
-    resolveMerchantResult?: (state: Readonly<CheckoutState>) => Promise<MerchantResult>;
-    /** Hold further card requests after handoff until the merchant result is reconciled. Default false for compatibility. */
-    requireMerchantResult?: boolean;
-}
-export interface CheckoutController {
-    getState(): Readonly<CheckoutState>;
-    /** Await device consent before the caller starts the first native Pay action. One use per attachment. */
-    prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
-    /** Stop locally and best-effort retire an unbound preparation. Does not cancel a processor payment. */
-    cancel(): void;
-    /** Ask the application's merchant resolver. A rejection records unknown; never automatically retries payment. */
-    reconcile(): Promise<Readonly<CheckoutState>>;
-    /** Signal an observed challenge; the SDK cannot detect every processor's 3DS UI. */
-    requestUserAction(reason: '3ds' | 'redirect' | 'other'): Promise<void>;
-    /** Start a new attempt after merchant-confirmed failure. Cancelled, completed and unbound Stripe-token attachments cannot reset. */
-    retryAfterMerchantFailure(result: {
-        status: 'failed';
-    }): void;
-}
-/** 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;
-/** Shared by the raw CDP and Playwright transports. No browser ownership or payment execution lives here. */
-export declare class CheckoutLifecycle implements CheckoutController {
-    private readonly options;
-    private state;
-    private held;
-    private active;
-    private cancelled;
-    private merchantAborted;
-    private unboundStripeToken;
-    private stripeTokenPrepared;
-    private stripeContinuation;
-    private stripeContinuationChecks;
-    private ownedShopOrderId;
-    private reconciliation;
-    private preparationHandler?;
-    private preparationUsed;
-    readonly abort: AbortController;
-    constructor(options: LifecycleOptions);
-    getState(): Readonly<CheckoutState>;
-    setPreparationHandler(handler: (options: PrepareCheckoutOptions) => Promise<PreparedCheckout>): void;
-    prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
-    preparing(): void;
-    preparationCreated(preparationId: string): void;
-    prepared(preparation: PreparedCheckout): void;
-    preparationFailed(error: CheckoutPreparationError): void;
-    isBlocked(): boolean;
-    isCancelled(): boolean;
-    begin(): void;
-    end(): void;
-    private set;
-    approvalCreated(authorizationId: string): void;
-    approvalUrl(approvalUrl: string): void;
-    private notify;
-    cancel(): void;
-    /** The exact browser request is gone; a late approval cannot reopen it. */
-    merchantRequestAborted(): void;
-    /**
-     * The page abandoned its card request (its own script timed out) while
-     * the cardholder is still deciding. The approval stays pending and the
-     * page's next matching request will be answered from it, so the status
-     * stays `awaiting_approval`; the reason says the page has to ask again.
-     * Not a hold: nothing is refused, and no card or token has moved.
-     */
-    merchantRequestLost(): void;
-    /**
-     * The cardholder approved, and there is no live page request to hand the
-     * answer to: the page gave up on its own request while they decided.
-     * `ready_to_submit` is the state a prepared checkout uses for "consent in
-     * hand, click Pay": the application's next Pay action produces the request
-     * this approval answers, with no second prompt on the phone.
-     */
-    awaitingMerchantRetry(authorizationId: string): void;
-    /**
-     * The page never asked again inside the retry wait and the API confirmed
-     * the approval is retired: `declined`, like any other approval that ended
-     * with nothing charged, and not held, because the next card request is a
-     * new question (the cardholder is told to ask their agent to try again).
-     * A retirement the API refused or did not confirm is an unknown outcome and
-     * is reported through failed() instead, which holds.
-     */
-    merchantNeverRetried(authorizationId: string | null): void;
-    unsupported(): void;
-    prepareHandoff(replay: ReplayResponse, requestUrl: string): void;
-    /**
-     * The approval a page's card-free Stripe confirmation may continue, or null.
-     * Only once a Stripe tokenization is being handed to the page, and while
-     * the checkout still awaits it (the page can send its confirmation before
-     * the browser acknowledges the delivery) or the merchant; for one check at
-     * a time and at most MAX_STRIPE_CONTINUATION_CHECKS checks. Reserves the check synchronously,
-     * so two confirmations can never both continue: the caller settles it with
-     * stripeContinuationChecked(). The hold stays on throughout.
-     */
-    claimStripeContinuation(): string | null;
-    /**
-     * Settle a claimed check. True only when the API allowed it and the checkout
-     * still awaits the merchant (nothing cancelled, aborted or reconciled it
-     * while the API answered): the page's confirmation continues, and no later
-     * one will.
-     */
-    stripeContinuationChecked(allowed: boolean): boolean;
-    private stripeContinuationOpen;
-    handedOff(replay: ReplayResponse): void;
-    failed(error: unknown, handoffStarted?: boolean): void;
-    requestUserAction(reason: '3ds' | 'redirect' | 'other'): Promise<void>;
-    reconcile(): Promise<Readonly<CheckoutState>>;
-    private resolve;
-    retryAfterMerchantFailure(result: {
-        status: 'failed';
-    }): void;
-}
-/** Exact origin and path, supplied by the integrator after observing a payment endpoint. No query/body matching. */
-export interface PaymentEndpointGuard {
-    origin: string;
-    pathname: string;
-    methods?: readonly string[];
-}
-export declare function paymentEndpointGuards(input?: readonly PaymentEndpointGuard[]): {
-    patterns: string[];
-    matches(url: string, method?: string): boolean;
-};