@agent-cards/checkout 0.19.0 → 0.22.0

package/dist/fiserv.js

@@ -1,104 +0,0 @@
-/**
- * Fiserv Commerce Hub card capture, as this SDK reads it.
- *
- * Every rule lives in the internal payment core (payment-core src/fiserv.js), vendored
- * here as fiserv.generated.ts so the published package installs nothing else; the
- * backend and the Vault load the same rules. That artifact is untyped JavaScript, so
- * this module gives the adapters, the client and callers typed names for the parts the
- * SDK uses, the way substitute.ts types the shared substitution. It adds no rule.
- *
- * The request is the Secure Data Capture frame's POST to Commerce Hub's card-capture
- * endpoint. The frame encrypts the card the agent typed and posts the envelope as
- * source.encryptionData; the cardholder's device builds the same envelope around the
- * approved card under a key Agentcard pinned for the merchant, and the paused capture
- * continues from the agent's browser with the envelope's four members swapped.
- */
-import * as generated from './fiserv.generated.js';
-const core = generated;
-/** The card-capture endpoint per environment, exactly as the Secure Data Capture frame writes it. */
-export const FISERV_CARD_CAPTURE_ENDPOINTS = core.FISERV_CARD_CAPTURE_ENDPOINTS;
-const CAPTURE_HOSTS = new Set(Object.values(core.FISERV_CARD_CAPTURE_ENDPOINTS).map((endpoint) => new URL(endpoint).hostname));
-/**
- * Whether `url` is on one of the two card-capture hosts (connect.fiservapis.com and
- * connect-cert.fiservapis.com), whatever its path or query. The registry's Fiserv
- * recognizer lists exactly these hosts, so a card request on one of them is Fiserv's.
- */
-export function isFiservCaptureHost(url) {
-    try {
-        return CAPTURE_HOSTS.has(new URL(url).hostname);
-    }
-    catch {
-        return false;
-    }
-}
-/** The pinned key with this id, in either environment, or null. */
-export function fiservKeyPinById(id) {
-    return typeof id === 'string' ? core.FISERV_KEY_PINS.find((pin) => pin.id === id) ?? null : null;
-}
-/**
- * The id of the pin a paused capture's card may be sealed under (its envelope's key,
- * pinned for its endpoint's environment and for the merchant its body names), or null.
- */
-export function fiservCapturePinId(url, body) {
-    return core.fiservCapturePin({ url, body })?.id ?? null;
-}
-/** The card-capture endpoint a Fiserv preparation names for its environment. */
-export function fiservPreparationUrl(environment) {
-    return core.fiservPreparationUrl(environment);
-}
-/**
- * Whether the SDK pauses this capture body for the cardholder, or refuses it when no
- * preparation is ready: every body except the captures that carry no Vault card.
- * Fastlane (PaymentToken), ACH (PaymentCheck), gift and EBT captures share the endpoint
- * and continue untouched, each only in its exact source shape. A body not proven
- * card-free (one the adapter could not read, one over 64 KiB, one that is not JSON, a
- * PaymentCard with a plaintext card, a non-card type or category that also carries a card
- * member) is judged as a card capture, so the agent's placeholder never continues to
- * Fiserv on it.
- */
-export function isFiservPausableBody(body) {
-    return core.isFiservPausableBody(body);
-}
-/**
- * Whether this build pays the request only through a prepared checkout because it is
- * Fiserv's: a recognizer named fiserv, or a request on one of Fiserv's capture hosts.
- * The served entry says so too (preparationRequired); this build carries Fiserv's own
- * rules, so it requires the preparation whatever the served registry says, and a
- * registry that dropped the flag never opens an ordinary Fiserv authorization.
- */
-export function requiresFiservPreparation(psp, url) {
-    return psp === 'fiserv' || isFiservCaptureHost(url);
-}
-/**
- * Whether a paused request is the capture a Fiserv preparation for `environment`
- * consents to: that environment's endpoint exactly, the capture rules on the whole
- * request, headers included, and an envelope under a key pinned for that environment
- * and for the merchant the body names.
- */
-export function isPreparedFiservRequest(url, method, body, environment, headers) {
-    return core.isPreparedFiservRequest(url, method, body, environment, headers);
-}
-/**
- * Whether an approval's substitution is exactly Fiserv's envelope: `encoding` json,
- * `at` source.encryptionData, the four members keyId, encryptedKey, encryptionBlock and
- * aesIv in their exact shape under a pinned key, and nothing removed.
- */
-export function isFiservSubstitution(sub) {
-    if (!sub || typeof sub !== 'object' || Array.isArray(sub))
-        return false;
-    const value = sub;
-    return Object.keys(value).every((name) => ['encoding', 'at', 'fields', 'remove'].includes(name))
-        && value.encoding === 'json' && value.at === core.FISERV_SUBSTITUTION.at
-        && (value.remove === undefined || (Array.isArray(value.remove) && value.remove.length === 0))
-        && core.fiservSubstitutionFieldsRefusal(value.fields) === null;
-}
-/**
- * The paused Fiserv capture with the approval's envelope written over the four members
- * its source.encryptionData already carries, and every other byte the frame's own. It
- * throws, writing nothing, for a body that is not the capture Agentcard covers, for any
- * substitution but Fiserv's envelope, and for an envelope under another key than the one
- * the paused capture names. Run this on a Fiserv approval, never substituteEncryptedFields.
- */
-export function substituteFiservEnvelope(body, sub) {
-    return core.substituteFiservEnvelope(body, sub);
-}

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,18 +0,0 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, PreparationRequiredError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, AdyenTestPlatformRefusedError, MerchantTotalError, } from './client.js';
-export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, MerchantHostedReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, AdyenTestPlatformRefusal, MerchantTotalRefusal, 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 { classifyDeclaredMerchantRequest, classifyMerchantRequest, substituteMerchantHostedBody } from './merchant-hosted.js';
-export type { MerchantProfile, MerchantProfileStatus, MerchantRequestVerdict, MerchantHostedSubstitutions, MerchantHostedFact, JsonPathStep, SandboxMerchantDeclaration } from './merchant-hosted.js';
-export { MerchantExchangeLog, merchantAmountExchanges, merchantAmountFromResponses, merchantChargeReport, merchantProfilePricedBySource, merchantTotalAtRelease, MERCHANT_EXCHANGES_MAX, } from './merchant-total.js';
-export type { MerchantAmountCard, MerchantExchange, MerchantRequestSeen, MerchantTotalApproved, MerchantTotalCapture, MerchantTotalScope } from './merchant-total.js';
-export { substituteFiservEnvelope } from './fiserv.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,10 +0,0 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, PreparationRequiredError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, AdyenTestPlatformRefusedError, MerchantTotalError, } from './client.js';
-export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
-export { CheckoutAttachmentError } from './attachment.js';
-export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
-export { classifyDeclaredMerchantRequest, classifyMerchantRequest, substituteMerchantHostedBody } from './merchant-hosted.js';
-// The merchant's own total for a raw CDP runtime that intercepts on its own (merchant-total.ts).
-export { MerchantExchangeLog, merchantAmountExchanges, merchantAmountFromResponses, merchantChargeReport, merchantProfilePricedBySource, merchantTotalAtRelease, MERCHANT_EXCHANGES_MAX, } from './merchant-total.js';
-export { substituteFiservEnvelope } from './fiserv.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,179 +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;
-    /**
-     * A card request this SDK cannot pay was aborted. `reason`: an unrecognized
-     * declared payment endpoint (the default), a merchant profile Agentcard has not
-     * turned on (merchant_profile_observe), or a card request the profile cannot
-     * finish (merchant_request_unsupported).
-     */
-    unsupported(reason?: 'unrecognized_payment_endpoint' | 'merchant_profile_observe' | 'merchant_request_unsupported'): void;
-    /**
-     * A card request that only a prepared checkout pays (an Adyen merchant
-     * profile's, or a Fiserv card capture) arrived with no preparation on this
-     * attachment and was aborted before any pause, prompt or authorization.
-     * Nothing is outstanding, so nothing is held; prepare() stays refused here, as
-     * after any first card request.
-     */
-    preparationRequired(): 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;
-};