@agent-cards/checkout 0.19.0 → 0.21.0

package/dist/lifecycle.js

@@ -1,395 +0,0 @@
-import { AdyenTestPlatformRefusedError, ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, CheckoutPreparationError, IntentNotConfirmableError, PaymentOutcomeUnknownError, ProcessorRefusedError } from './client.js';
-import { parseOwnedShopReceipt, OWNED_SHOP_SKU, OWNED_SHOP_AMOUNT_CENTS, OWNED_SHOP_CURRENCY } from './owned-shop.generated.js';
-/** How many times one approval's card-free Stripe confirmation may be checked before it is simply held. */
-export const MAX_STRIPE_CONTINUATION_CHECKS = 3;
-/** Shared by the raw CDP and Playwright transports. No browser ownership or payment execution lives here. */
-export class CheckoutLifecycle {
-    options;
-    state = { status: 'idle', authorizationId: null };
-    held = false;
-    active = false;
-    cancelled = false;
-    merchantAborted = false;
-    unboundStripeToken = false;
-    // The page's own confirmation paying with that token: see claimStripeContinuation.
-    stripeTokenPrepared = false;
-    stripeContinuation = 'none';
-    stripeContinuationChecks = 0;
-    ownedShopOrderId = null;
-    reconciliation = null;
-    preparationHandler;
-    preparationUsed = false;
-    abort = new AbortController();
-    constructor(options) {
-        this.options = options;
-    }
-    getState() {
-        return { ...this.state, ...(this.state.confirmation ? { confirmation: { ...this.state.confirmation } } : {}) };
-    }
-    setPreparationHandler(handler) { this.preparationHandler = handler; }
-    prepare(options) {
-        if (!this.preparationHandler)
-            return Promise.reject(new CheckoutPreparationError(null, 'transport_unavailable'));
-        return this.preparationHandler(options);
-    }
-    preparing() {
-        this.preparationUsed = true;
-        this.set({ status: 'awaiting_approval', authorizationId: null });
-    }
-    preparationCreated(preparationId) { this.set({ ...this.state, preparationId }); }
-    prepared(preparation) {
-        this.set({ status: 'ready_to_submit', authorizationId: null, preparationId: preparation.id });
-    }
-    preparationFailed(error) {
-        this.held = true;
-        if (this.cancelled)
-            return;
-        this.set({ ...this.state, status: error.reason === 'expired' ? 'timed_out' : error.reason === 'cancelled' ? 'cancelled' : 'failed', reason: error.reason });
-    }
-    isBlocked() { return this.held || this.cancelled; }
-    isCancelled() { return this.cancelled; }
-    begin() {
-        this.active = true;
-        this.set({ status: 'awaiting_approval', authorizationId: null, ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
-    }
-    end() { this.active = false; }
-    set(state) {
-        this.state = state;
-        // Application telemetry must never interrupt a paused payment after it reaches the processor.
-        try {
-            Promise.resolve(this.options.onStateChange?.(this.getState())).catch(() => { });
-        }
-        catch { /* observer only */ }
-    }
-    approvalCreated(authorizationId) {
-        this.set({ ...this.state, authorizationId });
-    }
-    approvalUrl(approvalUrl) {
-        this.notify({ reason: 'approval', authorizationId: this.state.authorizationId, approvalUrl });
-    }
-    notify(action) {
-        try {
-            Promise.resolve(this.options.onUserAction?.(action)).catch(() => { });
-        }
-        catch { /* observer only */ }
-    }
-    cancel() {
-        this.cancelled = true;
-        this.held = true;
-        this.abort.abort();
-        this.set({ ...this.state, status: this.active || this.state.authorizationId ? 'outcome_unknown' : 'cancelled', reason: 'local_cancel' });
-    }
-    /** The exact browser request is gone; a late approval cannot reopen it. */
-    merchantRequestAborted() {
-        this.merchantAborted = true;
-        this.held = true;
-        this.set({ ...this.state, status: 'outcome_unknown', reason: 'merchant_request_aborted' });
-    }
-    /**
-     * 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() {
-        this.set({ ...this.state, reason: 'merchant_request_lost' });
-    }
-    /**
-     * 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) {
-        this.set({ status: 'ready_to_submit', authorizationId, reason: 'awaiting_merchant_retry',
-            ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
-    }
-    /**
-     * 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) {
-        if (this.cancelled)
-            return;
-        this.set({ ...this.state, authorizationId, status: 'declined', reason: 'merchant_never_retried' });
-    }
-    /**
-     * 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') {
-        this.held = true;
-        if (this.state.authorizationId)
-            return; // do not hide an outstanding/completed payment behind a later unsupported request
-        this.set({ ...this.state, status: 'unsupported', reason });
-    }
-    /**
-     * 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() {
-        if (this.cancelled || this.state.authorizationId)
-            return;
-        this.set({ ...this.state, status: 'failed', reason: 'preparation_required' });
-    }
-    prepareHandoff(replay, requestUrl) {
-        if (replay.mode === 'token' && replay.executionMode === 'autopilot' && replay.shopOrderId) {
-            let receipt;
-            try {
-                receipt = parseOwnedShopReceipt(JSON.parse(replay.body), {
-                    order_id: replay.shopOrderId, sku: OWNED_SHOP_SKU, amount: OWNED_SHOP_AMOUNT_CENTS, currency: OWNED_SHOP_CURRENCY,
-                });
-            }
-            catch { /* An unrecognized response remains subject to the token continuation guard. */ }
-            if (receipt) {
-                this.ownedShopOrderId = receipt.order_id;
-                this.held = true;
-                return;
-            }
-        }
-        // A tokenization approval has no authoritative PaymentIntent or amount
-        // binding. Neither the first observed confirm nor the returned opaque
-        // token can supply one. Hold even in compatibility mode: this attachment
-        // must never turn that token into an unreviewed payment continuation.
-        if (!replay.mode || replay.mode === 'token') {
-            try {
-                const url = new URL(requestUrl);
-                if (url.origin === 'https://api.stripe.com' && ['/v1/payment_methods', '/v1/tokens', '/v1/sources', '/v1/confirmation_tokens'].includes(url.pathname)) {
-                    // Set before delivery: a lost browser acknowledgement must not reset
-                    // an already-issued token into a retryable authorization.
-                    this.unboundStripeToken = true;
-                    this.stripeTokenPrepared = true;
-                    this.held = true;
-                }
-            }
-            catch { /* unknown URL cannot establish a token binding */ }
-        }
-    }
-    /**
-     * 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() {
-        if (!this.stripeContinuationOpen() || this.stripeContinuation !== 'none'
-            || this.stripeContinuationChecks >= MAX_STRIPE_CONTINUATION_CHECKS)
-            return null;
-        this.stripeContinuation = 'checking';
-        this.stripeContinuationChecks++;
-        return this.state.authorizationId;
-    }
-    /**
-     * 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) {
-        if (this.stripeContinuation !== 'checking')
-            return false;
-        const proceed = allowed && this.stripeContinuationOpen();
-        this.stripeContinuation = proceed ? 'continued' : 'none';
-        if (proceed)
-            this.set({ ...this.state, reason: 'stripe_payment_continued' });
-        return proceed;
-    }
-    stripeContinuationOpen() {
-        return this.stripeTokenPrepared && !this.cancelled && !this.merchantAborted && !!this.state.authorizationId
-            && (this.state.status === 'awaiting_approval' || this.state.status === 'awaiting_merchant');
-    }
-    handedOff(replay) {
-        if (this.merchantAborted)
-            return;
-        if (this.ownedShopOrderId) {
-            this.held = true;
-            this.set({ status: 'completed', authorizationId: replay.authorizationId, mode: 'token', orderId: this.ownedShopOrderId });
-            return;
-        }
-        const mismatch = (!replay.mode || replay.mode === 'token') && replay.amountVerified === false;
-        this.held = !!this.options.requireMerchantResult || replay.mode === 'hosted_form' || mismatch || this.unboundStripeToken;
-        if (mismatch)
-            this.stripeTokenPrepared = false;
-        this.set({ status: 'awaiting_merchant', authorizationId: replay.authorizationId, mode: replay.mode ?? 'token',
-            ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}),
-            ...(mismatch ? { reason: 'charged_amount_mismatch' }
-                : this.stripeContinuation === 'continued' ? { reason: 'stripe_payment_continued' }
-                    : this.unboundStripeToken ? { reason: 'stripe_tokenization_unbound' } : {}) });
-    }
-    failed(error, handoffStarted = false) {
-        if (this.cancelled)
-            return;
-        if (this.merchantAborted) {
-            this.merchantRequestAborted();
-            return;
-        }
-        const authorizationId = error instanceof PaymentOutcomeUnknownError || error instanceof ProcessorRefusedError ? error.authorizationId : this.state.authorizationId;
-        if (!handoffStarted && error instanceof PaymentOutcomeUnknownError && error.reason === 'autopilot_action_required') {
-            this.held = true;
-            this.set({ ...this.state, authorizationId, status: 'requires_user_action', reason: 'other' });
-            this.notify({ reason: 'other', authorizationId });
-        }
-        else if (handoffStarted || error instanceof PaymentOutcomeUnknownError || error instanceof IntentNotConfirmableError) {
-            this.held = true;
-            this.set({ ...this.state, authorizationId, status: 'outcome_unknown', reason: error instanceof PaymentOutcomeUnknownError ? error.reason : error instanceof IntentNotConfirmableError ? 'intent_not_confirmable' : 'browser_handoff_failed' });
-        }
-        else if (error instanceof CheckoutCancelledError) {
-            this.cancel();
-        }
-        else if (error instanceof CheckoutPreparationError) {
-            this.preparationFailed(error);
-        }
-        else if (error instanceof ApprovalTimeoutError) {
-            this.set({ ...this.state, status: 'timed_out', reason: 'approval_expired' });
-        }
-        else if (error instanceof ProcessorRefusedError) {
-            // A rejected processor request is not proof that the merchant cannot
-            // collect this payment. Keep native retries held until the application
-            // checks the merchant and explicitly starts another attempt.
-            this.held = true;
-            this.set({ ...this.state, authorizationId, status: 'declined', reason: 'processor_refused' });
-        }
-        else if (error instanceof AdyenTestPlatformRefusedError) {
-            // Agentcard's own rule, not a person's answer: refused at create before
-            // anyone was asked, the checkout failed as it did before the error was
-            // typed; declined before the card was sent, the authorization is declined.
-            // Either way the reason names the rule.
-            this.set({ ...this.state, status: error.stage === 'create' ? 'failed' : 'declined', reason: error.code });
-        }
-        else if (error instanceof ApprovalDeclinedError) {
-            this.set({ ...this.state, status: 'declined', reason: 'approval_declined' });
-        }
-        else {
-            this.set({ ...this.state, status: 'failed', reason: 'checkout_failed' });
-        }
-    }
-    async requestUserAction(reason) {
-        if (this.state.status === 'completed')
-            return;
-        this.held = true;
-        this.set({ ...this.state, status: 'requires_user_action', reason });
-        // Hooks deliver a link/live view owned by the integrator; the SDK does not invent challenge URLs.
-        try {
-            await this.options.onUserAction?.({ reason, authorizationId: this.state.authorizationId });
-        }
-        catch { /* observer only */ }
-    }
-    reconcile() {
-        if (this.state.status === 'completed')
-            return Promise.resolve(this.getState());
-        if (this.reconciliation)
-            return this.reconciliation;
-        if (!this.options.resolveMerchantResult)
-            return Promise.resolve(this.getState());
-        if (this.active)
-            throw new Error('Wait for the paused request to finish before reconciling the merchant order.');
-        this.reconciliation = this.resolve().finally(() => { this.reconciliation = null; });
-        return this.reconciliation;
-    }
-    async resolve() {
-        let result;
-        try {
-            result = await this.options.resolveMerchantResult(this.getState());
-        }
-        catch {
-            result = { status: 'unknown' };
-        }
-        if (!result || typeof result !== 'object' || Array.isArray(result))
-            result = { status: 'unknown' };
-        // The resolver is trusted application code: it must check the original
-        // request, amount, currency, selected card and authoritative merchant
-        // result. The SDK binds its explicit confirmation to this authorization;
-        // it does not turn an HTTP response or a success URL into payment proof.
-        const orderConfirmed = result.status === 'completed' && result.confirmation === undefined
-            && typeof result.orderId === 'string' && result.orderId.length > 0;
-        const paymentConfirmed = result.status === 'completed' && result.orderId === undefined
-            && result.confirmation && typeof result.confirmation === 'object' && !Array.isArray(result.confirmation)
-            && result.confirmation.kind === 'merchant_payment'
-            && typeof this.state.authorizationId === 'string' && this.state.authorizationId.length > 0
-            && result.confirmation.authorizationId === this.state.authorizationId;
-        if (result.status === 'completed' && (orderConfirmed || paymentConfirmed)) {
-            this.held = true;
-            // Completion supersedes an earlier failure/challenge, while retaining
-            // preparation and authorization context. Never copy arbitrary evidence
-            // into public state or release the hold on additional payment requests.
-            const { reason: _previousReason, orderId: _previousOrder, confirmation: _previousConfirmation, ...context } = this.state;
-            this.set({ ...context, status: 'completed', ...(orderConfirmed
-                    ? { orderId: result.orderId }
-                    : { confirmation: { kind: 'merchant_payment', authorizationId: this.state.authorizationId } }) });
-        }
-        else if (result.status === 'failed') {
-            // Keep the guard armed until the application deliberately starts another attempt.
-            this.held = true;
-            this.set({ ...this.state, status: 'failed', reason: 'merchant_confirmed_failure' });
-        }
-        else if (result.status === 'requires_user_action') {
-            await this.requestUserAction(result.reason);
-        }
-        else {
-            this.held = true;
-            this.set({ ...this.state, status: result.status === 'pending' ? 'awaiting_merchant' : 'outcome_unknown', reason: 'merchant_not_confirmed' });
-        }
-        return this.getState();
-    }
-    retryAfterMerchantFailure(result) {
-        if (this.ownedShopOrderId)
-            throw new Error('This shop payment already has a receipt; another payment is not permitted.');
-        if (this.preparationUsed)
-            throw new Error('Prepared checkouts are single use. Reconcile this attempt and create a new attachment.');
-        if (this.active || this.reconciliation)
-            throw new Error('Cannot start another attempt while payment or reconciliation is in progress.');
-        if (this.cancelled)
-            throw new Error('This attachment was cancelled; attach again after reconciling the merchant order.');
-        if (result?.status !== 'failed')
-            throw new Error('A merchant-confirmed failure is required before retrying.');
-        if (this.state.status === 'completed')
-            throw new Error('This order is already complete. Use a new attachment for another order.');
-        if (this.unboundStripeToken)
-            throw new Error('This attachment delivered an unbound Stripe token; reconcile the merchant order and use a separately validated checkout flow.');
-        this.held = false;
-        this.merchantAborted = false;
-        this.set({ status: 'idle', authorizationId: null });
-    }
-}
-export function paymentEndpointGuards(input = []) {
-    const guards = input.map((guard) => {
-        const origin = new URL(guard.origin);
-        if (!['http:', 'https:'].includes(origin.protocol) || origin.origin !== guard.origin
-            || !guard.pathname.startsWith('/') || /[?#*]/.test(guard.pathname)) {
-            throw new Error('Payment endpoint guards require a canonical http(s) origin and an exact path without wildcards or query strings.');
-        }
-        const methods = (guard.methods ?? ['POST', 'PUT', 'PATCH']).map((method) => method.toUpperCase());
-        if (!methods.length || methods.some((method) => !['POST', 'PUT', 'PATCH', 'DELETE'].includes(method))) {
-            throw new Error('Payment endpoint guards can only block explicit mutation methods.');
-        }
-        return { ...guard, methods };
-    });
-    return {
-        patterns: guards.map((guard) => `${guard.origin}${guard.pathname}*`),
-        matches(raw, method) {
-            let url;
-            try {
-                url = new URL(raw);
-            }
-            catch {
-                return false;
-            }
-            return guards.some((guard) => url.origin === guard.origin && url.pathname === guard.pathname
-                && (method === undefined || guard.methods.includes(method.toUpperCase())));
-        },
-    };
-}

package/dist/mercado-checkout.d.ts

@@ -1,20 +0,0 @@
-import type { ReplayResponse } from './client.js';
-/** Capture only the native Checkout Pro configuration. A late configuration,
- * navigation or repeated token cannot replace the context of an issued token.
- * Final payment requests retain the attachment's existing payment guards.
- */
-export declare class MercadoCheckoutGate {
-    private context;
-    private started;
-    private stopped;
-    private sequence;
-    private associatedFlow;
-    private association;
-    matches(url: string): boolean;
-    requiresDocument(url: string, method: string): boolean;
-    invalidate(): void;
-    configuration(url: string, method: string, body: string, readDocument: () => Promise<string>): Promise<boolean>;
-    claimToken(url: string, method: string, documentUrl: string): unknown;
-    arm(replay: ReplayResponse, tokenUrl: string): Promise<void>;
-    associationBody(url: string, method: string, body: string, documentUrl: string): string | undefined;
-}

package/dist/mercado-checkout.generated.d.ts

@@ -1,52 +0,0 @@
-declare var MERCADO_CHECKOUT_ORIGIN: string;
-declare var MERCADO_CONFIGURATION_URL: string;
-declare var MERCADO_CHECKOUT_PATTERN: string;
-declare function mercadoCheckoutDocument(raw: any): {
-    flowId: string;
-    preferenceId: string | null;
-    query: string;
-};
-declare function parseMercadoCheckoutContext(value: any): any;
-declare function captureMercadoCheckoutContext(url: any, method: any, body: any, documentUrl: any): any;
-declare function isMercadoTokenRequest(url: any, method: any): boolean;
-declare function mercadoDigest(value: any): Promise<string>;
-declare function mercadoContextDigest(context: any, tokenUrl: any): Promise<string>;
-declare function prepareMercadoConfiguration(context: any, card: any): {
-    url: string;
-    body: string;
-};
-declare function parseMercadoConfiguration(value: any): {
-    paymentMethodId: any;
-    paymentTypeId: any;
-    paymentMethodName: any;
-    issuerId: string;
-    issuerName: any;
-};
-declare function createMercadoProcessorContext(configuration: any, context: any, tokenUrl: any, tokenBody: any): Promise<{
-    paymentMethodId: any;
-    paymentTypeId: any;
-    paymentMethodName: any;
-    issuerId: string;
-    issuerName: any;
-    version: number;
-    psp: string;
-    source: string;
-    contextDigest: string;
-    tokenDigest: string;
-}>;
-declare function validateMercadoProcessorContext(value: any, context: any, tokenUrl: any, tokenBody: any): Promise<any>;
-declare function createMercadoAssociationGate({ context, tokenUrl, tokenBody, processorContext }: {
-    context: any;
-    tokenUrl: any;
-    tokenBody: any;
-    processorContext: any;
-}): Promise<{
-    take({ url, method, body, documentUrl }: {
-        url: any;
-        method: any;
-        body: any;
-        documentUrl: any;
-    }): string;
-    readonly claimed: boolean;
-}>;
-export { MERCADO_CHECKOUT_ORIGIN, MERCADO_CHECKOUT_PATTERN, MERCADO_CONFIGURATION_URL, captureMercadoCheckoutContext, createMercadoAssociationGate, createMercadoProcessorContext, isMercadoTokenRequest, mercadoCheckoutDocument, mercadoContextDigest, mercadoDigest, parseMercadoCheckoutContext, parseMercadoConfiguration, prepareMercadoConfiguration, validateMercadoProcessorContext };