@agent-cards/sdk 0.20.0

package/dist/lifecycle.js

@@ -0,0 +1,405 @@
+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;
+    resumeHandler = null;
+    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);
+    }
+    /** The transport's hand while one request is paused for the business; null once it is answered. */
+    setResumeHandler(handler) { this.resumeHandler = handler; }
+    resume(result) {
+        if (!this.resumeHandler)
+            return Promise.reject(new Error('No card request is paused for the business to answer; attach with pauseOnly: true and wait for onPaused.'));
+        if (!result || typeof result !== 'object' || typeof result.status !== 'string')
+            return Promise.reject(new Error('resume takes the authorization as read: an object with a status.'));
+        return this.resumeHandler(result);
+    }
+    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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,52 @@
+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 };