@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/lifecycle.d.ts

@@ -1,6 +1,9 @@
 import { CheckoutPreparationError, type PrepareCheckoutOptions, type PreparedCheckout, type ReplayResponse } from './client.js';
 import type { CheckoutMode } from './registry.js';
+import type { PayrailsUnsupportedReason } from './payrails.js';
 import type { Substitutions } from './substitute.js';
+import type { GmoUnsupportedReason } from './gmo.js';
+import type { ShijiStsUnsupportedReason } from './shiji-sts.js';
 /** The application's resolver confirmed the payment for this checkout authorization. */
 export interface MerchantPaymentConfirmation {
     kind: 'merchant_payment';
@@ -27,7 +30,8 @@ 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;
+    /** How the card reached the merchant: a processor mode, or `card_endpoint` for a reviewed merchant's own card endpoint. */
+    mode?: CheckoutMode | 'card_endpoint';
     orderId?: string;
     confirmation?: MerchantPaymentConfirmation;
     /** Stable SDK category; never includes a request body, processor response, or approval link. */
@@ -115,6 +119,12 @@ export interface CheckoutController {
 }
 /** 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;
+/**
+ * How long a Datatrans re-submit waits for the merchant resolver (merchantOrderPending) while the
+ * page's card post stays paused. A resolver that has not answered by then reads as not pending, so
+ * the post becomes a new approval instead of hanging the checkout.
+ */
+export declare const MERCHANT_ORDER_READ_MS = 5000;
 /** 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;
@@ -127,7 +137,12 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private stripeTokenPrepared;
     private stripeContinuation;
     private stripeContinuationChecks;
+    /** The handoff in progress is WSPay's 3-D Secure step; see handedOff. */
+    private wspayChallenge;
+    private stripeContinuedReason;
+    private approvedPaymentMethod;
     private ownedShopOrderId;
+    private readonly handoffs;
     private reconciliation;
     private preparationHandler?;
     private preparationUsed;
@@ -146,6 +161,17 @@ export declare class CheckoutLifecycle implements CheckoutController {
     preparationFailed(error: CheckoutPreparationError): void;
     isBlocked(): boolean;
     isCancelled(): boolean;
+    /** Whether the application gave a merchant resolver, so reconcile() reads the merchant's own record. */
+    hasMerchantResolver(): boolean;
+    /**
+     * For a Datatrans re-submit once the approved answer reached the page (pre-claim.ts): whether the
+     * application's merchant resolver still reports this approval's order pending. A read only: no
+     * answer changes the state or the hold, so a pending order leaves the checkout exactly as it was.
+     * False with no resolver, while a request is in flight, once the checkout no longer awaits the
+     * merchant, when the resolver throws or answers anything but pending, and when it has not answered
+     * within `deadlineMs` (MERCHANT_ORDER_READ_MS): the paused card post never waits on it longer.
+     */
+    merchantOrderPending(deadlineMs?: number): Promise<boolean>;
     begin(): void;
     end(): void;
     private set;
@@ -183,10 +209,23 @@ export declare class CheckoutLifecycle implements CheckoutController {
     /**
      * 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).
+     * turned on (merchant_profile_observe), a card request the profile cannot
+     * finish (merchant_request_unsupported), a recognized processor's request in
+     * a form its gate refuses (GMO's unsupported_gmo_request and
+     * unsupported_gmo_token_v1), a CyberSource Flex request that is not a
+     * reviewed Microform v2 card field's (microform_unsupported,
+     * cybersource-flex.ts), a Juspay card request that is not the reviewed
+     * payment (juspay_request_unsupported, juspay-gate.ts), such as save card,
+     * EMI, a direct card or a sibling host, a reviewed merchant card endpoint
+     * this build does not pay (merchant_card_endpoint_not_enabled), a CreditGuard
+     * page that runs its own 3-D Secure (creditguard_three_d_secure), a
+     * recognized Primer request in a form its gate refuses (unsupported_primer_sdk,
+     * unsupported_primer_request), a Payrails request its gate refuses
+     * (`unsupported_payrails_card_payment` and the card-save refusal codes), or a
+     * Shiji STS request its gate refuses (shiji_sts_keep_on_file and the other
+     * shiji-sts.ts reasons).
      */
-    unsupported(reason?: 'unrecognized_payment_endpoint' | 'merchant_profile_observe' | 'merchant_request_unsupported'): void;
+    unsupported(reason?: 'unrecognized_payment_endpoint' | 'merchant_profile_observe' | 'merchant_request_unsupported' | GmoUnsupportedReason | 'microform_unsupported' | 'juspay_request_unsupported' | 'merchant_card_endpoint_not_enabled' | 'creditguard_three_d_secure' | 'unsupported_primer_sdk' | 'unsupported_primer_request' | PayrailsUnsupportedReason | ShijiStsUnsupportedReason): 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
@@ -196,6 +235,22 @@ export declare class CheckoutLifecycle implements CheckoutController {
      */
     preparationRequired(): void;
     prepareHandoff(replay: ReplayResponse, requestUrl: string): void;
+    /**
+     * The URLs of the requests this attachment has handed the card to, oldest
+     * first. Each is recorded before delivery, since the processor may already
+     * have minted a token from the card even if the browser never acknowledges
+     * it, and none is forgotten on a retry. The adapters pass them to
+     * VaultClient.withoutCard, which then refuses a Nuvei payment without a card.
+     */
+    cardHandoffs(): readonly string[];
+    /**
+     * The payment method a Stripe card save may pay with in place of the card
+     * it sends again (cdp.ts claimStripeContinuation): the one this
+     * attachment's approved `/v1/payment_methods` request returned, while its
+     * continuation is still open. Null for any other tokenization, and once the
+     * checkout was cancelled, aborted or reconciled.
+     */
+    approvedStripePaymentMethod(): string | null;
     /**
      * 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
@@ -210,9 +265,10 @@ export declare class CheckoutLifecycle implements CheckoutController {
      * 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.
+     * one will. `kind` names what it confirms: a payment (a PaymentIntent) or a
+     * card save (a SetupIntent), which the reason then says.
      */
-    stripeContinuationChecked(allowed: boolean): boolean;
+    stripeContinuationChecked(allowed: boolean, kind?: 'payment' | 'setup'): boolean;
     private stripeContinuationOpen;
     handedOff(replay: ReplayResponse): void;
     failed(error: unknown, handoffStarted?: boolean): void;

package/dist/lifecycle.js

@@ -1,7 +1,28 @@
 import { AdyenTestPlatformRefusedError, ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, CheckoutPreparationError, IntentNotConfirmableError, PaymentOutcomeUnknownError, ProcessorRefusedError } from './client.js';
+import { CardEndpointRefusedError } from './card-endpoint.js';
 import { parseOwnedShopReceipt, OWNED_SHOP_SKU, OWNED_SHOP_AMOUNT_CENTS, OWNED_SHOP_CURRENCY } from './owned-shop.generated.js';
+import { isWspayChallenge } from './wspay.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;
+/**
+ * How long a Datatrans re-submit waits for the merchant resolver (merchantOrderPending) while the
+ * page's card post stays paused. A resolver that has not answered by then reads as not pending, so
+ * the post becomes a new approval instead of hanging the checkout.
+ */
+export const MERCHANT_ORDER_READ_MS = 5_000;
+const STRIPE_PAYMENT_METHOD_ID = /^pm_[A-Za-z0-9]{1,250}$/;
+/** The `pm_` id in a Stripe `/v1/payment_methods` answer, or null for any other body. */
+function stripePaymentMethodId(body) {
+    if (typeof body !== 'string')
+        return null;
+    try {
+        const id = JSON.parse(body)?.id;
+        return typeof id === 'string' && STRIPE_PAYMENT_METHOD_ID.test(id) ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Shared by the raw CDP and Playwright transports. No browser ownership or payment execution lives here. */
 export class CheckoutLifecycle {
     options;
@@ -15,7 +36,15 @@ export class CheckoutLifecycle {
     stripeTokenPrepared = false;
     stripeContinuation = 'none';
     stripeContinuationChecks = 0;
+    /** The handoff in progress is WSPay's 3-D Secure step; see handedOff. */
+    wspayChallenge = false;
+    // What the continuation that went through confirmed: a payment, or a card save.
+    stripeContinuedReason = 'stripe_payment_continued';
+    // The payment method a Stripe /v1/payment_methods approval returned: see approvedStripePaymentMethod.
+    approvedPaymentMethod = null;
     ownedShopOrderId = null;
+    // Every request this attachment handed the card to: see cardHandoffs().
+    handoffs = [];
     reconciliation = null;
     preparationHandler;
     preparationUsed = false;
@@ -58,6 +87,30 @@ export class CheckoutLifecycle {
     }
     isBlocked() { return this.held || this.cancelled; }
     isCancelled() { return this.cancelled; }
+    /** Whether the application gave a merchant resolver, so reconcile() reads the merchant's own record. */
+    hasMerchantResolver() { return typeof this.options.resolveMerchantResult === 'function'; }
+    /**
+     * For a Datatrans re-submit once the approved answer reached the page (pre-claim.ts): whether the
+     * application's merchant resolver still reports this approval's order pending. A read only: no
+     * answer changes the state or the hold, so a pending order leaves the checkout exactly as it was.
+     * False with no resolver, while a request is in flight, once the checkout no longer awaits the
+     * merchant, when the resolver throws or answers anything but pending, and when it has not answered
+     * within `deadlineMs` (MERCHANT_ORDER_READ_MS): the paused card post never waits on it longer.
+     */
+    async merchantOrderPending(deadlineMs = MERCHANT_ORDER_READ_MS) {
+        const resolver = this.options.resolveMerchantResult;
+        if (!resolver || this.active || this.state.status !== 'awaiting_merchant')
+            return false;
+        let timer;
+        const expired = new Promise((resolve) => { timer = setTimeout(() => resolve(false), deadlineMs); });
+        const read = Promise.resolve().then(() => resolver(this.getState())).then((result) => !!result && typeof result === 'object' && !Array.isArray(result) && result.status === 'pending', () => false);
+        try {
+            return await Promise.race([read, expired]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     begin() {
         this.active = true;
         this.set({ status: 'awaiting_approval', authorizationId: null, ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
@@ -132,8 +185,21 @@ export class CheckoutLifecycle {
     /**
      * 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).
+     * turned on (merchant_profile_observe), a card request the profile cannot
+     * finish (merchant_request_unsupported), a recognized processor's request in
+     * a form its gate refuses (GMO's unsupported_gmo_request and
+     * unsupported_gmo_token_v1), a CyberSource Flex request that is not a
+     * reviewed Microform v2 card field's (microform_unsupported,
+     * cybersource-flex.ts), a Juspay card request that is not the reviewed
+     * payment (juspay_request_unsupported, juspay-gate.ts), such as save card,
+     * EMI, a direct card or a sibling host, a reviewed merchant card endpoint
+     * this build does not pay (merchant_card_endpoint_not_enabled), a CreditGuard
+     * page that runs its own 3-D Secure (creditguard_three_d_secure), a
+     * recognized Primer request in a form its gate refuses (unsupported_primer_sdk,
+     * unsupported_primer_request), a Payrails request its gate refuses
+     * (`unsupported_payrails_card_payment` and the card-save refusal codes), or a
+     * Shiji STS request its gate refuses (shiji_sts_keep_on_file and the other
+     * shiji-sts.ts reasons).
      */
     unsupported(reason = 'unrecognized_payment_endpoint') {
         this.held = true;
@@ -154,6 +220,8 @@ export class CheckoutLifecycle {
         this.set({ ...this.state, status: 'failed', reason: 'preparation_required' });
     }
     prepareHandoff(replay, requestUrl) {
+        this.wspayChallenge = isWspayChallenge(requestUrl, replay);
+        this.handoffs.push(requestUrl);
         if (replay.mode === 'token' && replay.executionMode === 'autopilot' && replay.shopOrderId) {
             let receipt;
             try {
@@ -181,11 +249,31 @@ export class CheckoutLifecycle {
                     this.unboundStripeToken = true;
                     this.stripeTokenPrepared = true;
                     this.held = true;
+                    if (url.pathname === '/v1/payment_methods')
+                        this.approvedPaymentMethod = stripePaymentMethodId(replay.body);
                 }
             }
             catch { /* unknown URL cannot establish a token binding */ }
         }
     }
+    /**
+     * The URLs of the requests this attachment has handed the card to, oldest
+     * first. Each is recorded before delivery, since the processor may already
+     * have minted a token from the card even if the browser never acknowledges
+     * it, and none is forgotten on a retry. The adapters pass them to
+     * VaultClient.withoutCard, which then refuses a Nuvei payment without a card.
+     */
+    cardHandoffs() { return [...this.handoffs]; }
+    /**
+     * The payment method a Stripe card save may pay with in place of the card
+     * it sends again (cdp.ts claimStripeContinuation): the one this
+     * attachment's approved `/v1/payment_methods` request returned, while its
+     * continuation is still open. Null for any other tokenization, and once the
+     * checkout was cancelled, aborted or reconciled.
+     */
+    approvedStripePaymentMethod() {
+        return this.stripeContinuationOpen() ? this.approvedPaymentMethod : null;
+    }
     /**
      * 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
@@ -207,15 +295,18 @@ export class CheckoutLifecycle {
      * 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.
+     * one will. `kind` names what it confirms: a payment (a PaymentIntent) or a
+     * card save (a SetupIntent), which the reason then says.
      */
-    stripeContinuationChecked(allowed) {
+    stripeContinuationChecked(allowed, kind = 'payment') {
         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' });
+        if (proceed) {
+            this.stripeContinuedReason = kind === 'setup' ? 'stripe_setup_continued' : 'stripe_payment_continued';
+            this.set({ ...this.state, reason: this.stripeContinuedReason });
+        }
         return proceed;
     }
     stripeContinuationOpen() {
@@ -230,14 +321,31 @@ export class CheckoutLifecycle {
             this.set({ status: 'completed', authorizationId: replay.authorizationId, mode: 'token', orderId: this.ownedShopOrderId });
             return;
         }
+        if (this.wspayChallenge) {
+            // WSPay answered with its 3-D Secure step, and the card frame now runs the
+            // bank's challenge in this browser. Nothing is charged until the cardholder
+            // completes it there, which the SDK cannot see, so this reads as
+            // requestUserAction('3ds') would, and holds until the merchant is reconciled.
+            // The step names no amount (amountVerified is null): WSPay then charges the
+            // amount the merchant's server set, and no answer Agentcard receives
+            // confirms it, so only the merchant's order can.
+            this.held = true;
+            this.set({ status: 'requires_user_action', authorizationId: replay.authorizationId, mode: 'token', reason: '3ds',
+                ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
+            this.notify({ reason: '3ds', authorizationId: replay.authorizationId });
+            return;
+        }
         const mismatch = (!replay.mode || replay.mode === 'token') && replay.amountVerified === false;
-        this.held = !!this.options.requireMerchantResult || replay.mode === 'hosted_form' || mismatch || this.unboundStripeToken;
+        // A card endpoint answer means the merchant already holds the card: its page's own
+        // retry, or a step-up that sends the card again, is refused until the application
+        // reconciles the order, exactly as for a hosted form the device submitted.
+        this.held = !!this.options.requireMerchantResult || replay.mode === 'hosted_form' || replay.mode === 'card_endpoint' || 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.stripeContinuation === 'continued' ? { reason: this.stripeContinuedReason }
                     : this.unboundStripeToken ? { reason: 'stripe_tokenization_unbound' } : {}) });
     }
     failed(error, handoffStarted = false) {
@@ -257,6 +365,13 @@ export class CheckoutLifecycle {
             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 CardEndpointRefusedError) {
+            // Refused before anything was created or sent. A refusal that every later request
+            // would meet holds the attachment; one about this request alone does not.
+            if (error.permanent)
+                this.held = true;
+            this.set({ ...this.state, status: error.reason === 'not_enabled' ? 'unsupported' : 'failed', reason: `merchant_card_endpoint_${error.reason}` });
+        }
         else if (error instanceof CheckoutCancelledError) {
             this.cancel();
         }

package/dist/merchant-card-endpoints.generated.d.ts

@@ -0,0 +1,63 @@
+declare var SubstitutionError: {
+    new (message: any): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+};
+declare var MERCHANT_CARD_ENDPOINT_PSP: string;
+declare var MERCHANT_CARD_ENDPOINT_MODE: string;
+declare var MERCHANT_CARD_ENDPOINT_PROFILES: any;
+declare var MERCHANT_CARD_ENDPOINT_RECOGNIZERS: any;
+declare var MERCHANT_CARD_ENDPOINT_CLIENT_TABLE: any;
+declare function merchantCardEndpointById(id: any): any;
+declare function trustedMerchantCardEndpoint(idOrEntry: any): any;
+declare function merchantCardEndpointRecognizerById(id: any): any;
+declare function merchantCardEndpointLive(idOrEntry: any): boolean;
+declare var MERCHANT_CARD_ENDPOINT_LIMITS: Readonly<{
+    bodyBytes: number;
+    answerBytes: number;
+    urlLength: 8192;
+    headerValueBytes: number;
+    headerBytes: number;
+    cookies: 64;
+}>;
+declare function merchantCardEndpointBodyRefusal(profile: any, body: any, contentType: any): string | null;
+declare function merchantCardEndpointAmount(profile: any, body: any, contentType: any): {
+    amountCents: null;
+    currency: any;
+} | {
+    amountCents: number;
+    currency: any;
+};
+declare function merchantCardEndpointMatches(profile: any, rawUrl: any, method: any, opts: any): boolean;
+declare function matchMerchantCardEndpoint(rawUrl: any, method: any, opts: any): any;
+declare function assertMerchantCardEndpoint(authorization: any): URL & {
+    profile: any;
+};
+declare function merchantCardEndpointSessionRefusal(profile: any, bundle: any): string | null;
+declare function substituteMerchantCardEndpoint(body: any, contentType: any, profile: any, card: any): any;
+declare function merchantEndpointRequest(profile: any, bundle: any, card: any): {
+    url: any;
+    method: any;
+    headers: {
+        "content-type": any;
+    };
+    body: any;
+};
+declare function responseCardLeak(card: any, response: any): "card_in_response" | "unreadable_in_response" | null;
+declare function merchantCardEndpointAnswer(profile: any, response: any, card: any): {
+    status: any;
+    withheld: string;
+    headers: {};
+    set_cookies: never[];
+    bodyText: null;
+} | {
+    status: any;
+    headers: {};
+    set_cookies: any[];
+    bodyText: any;
+    withheld?: undefined;
+};
+export { MERCHANT_CARD_ENDPOINT_CLIENT_TABLE, MERCHANT_CARD_ENDPOINT_LIMITS, MERCHANT_CARD_ENDPOINT_MODE, MERCHANT_CARD_ENDPOINT_PROFILES, MERCHANT_CARD_ENDPOINT_PSP, MERCHANT_CARD_ENDPOINT_RECOGNIZERS, SubstitutionError, assertMerchantCardEndpoint, matchMerchantCardEndpoint, merchantCardEndpointAmount, merchantCardEndpointAnswer, merchantCardEndpointBodyRefusal, merchantCardEndpointById, merchantCardEndpointLive, merchantCardEndpointMatches, merchantCardEndpointRecognizerById, merchantCardEndpointSessionRefusal, merchantEndpointRequest, responseCardLeak, substituteMerchantCardEndpoint, trustedMerchantCardEndpoint };