@agent-cards/sdk 0.23.11 → 0.23.13

package/dist/client.js

@@ -14,6 +14,7 @@ import { creditguardPageProcessUrl, creditguardPpDomainHost, creditguardPreparat
 import { CONVERGE_CAPABILITY } from './elavon-converge.js';
 import { SHIJI_STS_CAPABILITY, SHIJI_STS_PSP, isShijiStsServedCompanion, isShijiStsServedSubstitution } from './shiji-sts.js';
 import { AMADEUS_CHECKOUT_CAPABILITY, AMADEUS_CHECKOUT_PSP } from './amadeus-checkout.generated.js';
+import { PADDLE_VGS_CAPABILITY, PADDLE_VGS_PSP, paddleVgsCardFactsOf } from './paddle-vgs.generated.js';
 import { classifyStripeCheckoutRequest, encodeStripeCheckoutContext, hasStripeCheckoutMarker, parseStripeCheckoutContext, parseStripeCheckoutResponse, STRIPE_CHECKOUT_CONTEXT_HEADER, } from './stripe-checkout.generated.js';
 import { VoiceModule } from './voice.js';
 import { BuyModule } from './buy.js';
@@ -185,8 +186,16 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * the same terms: only to a build that lists it, for a company Agentcard turned
  * Moneris on for. A gated recognizer never sits in BUILTIN_REGISTRY, so it is paused
  * only after a sync.
+ *
+ * `paddle_vgs_cards`: the card request Paddle's checkout frame sends to its VGS card
+ * vault (vault.paddle.com/cards) on a checkout that names VGS, only through a prepared
+ * checkout: the frame aborts the request 10 seconds after Pay and sends it once more,
+ * and this build answers that second request from the same approval. The cardholder's
+ * device sends the card itself and the frame gets back the stored card's id alone.
+ * Served on the same terms: only to a build that lists it, for a company Agentcard
+ * turned Paddle on for.
  */
-export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CYBERSOURCE_FLEX_CAPABILITY, JUSPAY_CAPABILITY, DATATRANS_CAPABILITY, 'authorize_net_dpm_form', PELECARD_CAPABILITY, ACI_CAPABILITY, 'creditguard_pps_process', PRIMER_CAPABILITY, PAYRAILS_CAPABILITY, CONVERGE_CAPABILITY, EPROTECT_CAPABILITY, WSPAY_CAPABILITY, SHIJI_STS_CAPABILITY, AMADEUS_CHECKOUT_CAPABILITY, 'worldline_mycheckout_form', 'verifone_card_capture', 'ekashu_hosted_payment_page', SECURE_ACCEPTANCE_CAPABILITY, 'gravy_session_fields_put', 'moneris_hosted_tokenization'];
+export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CYBERSOURCE_FLEX_CAPABILITY, JUSPAY_CAPABILITY, DATATRANS_CAPABILITY, 'authorize_net_dpm_form', PELECARD_CAPABILITY, ACI_CAPABILITY, 'creditguard_pps_process', PRIMER_CAPABILITY, PAYRAILS_CAPABILITY, CONVERGE_CAPABILITY, EPROTECT_CAPABILITY, WSPAY_CAPABILITY, SHIJI_STS_CAPABILITY, AMADEUS_CHECKOUT_CAPABILITY, 'worldline_mycheckout_form', 'verifone_card_capture', 'ekashu_hosted_payment_page', SECURE_ACCEPTANCE_CAPABILITY, 'gravy_session_fields_put', 'moneris_hosted_tokenization', PADDLE_VGS_CAPABILITY];
 /**
  * Processors whose paused request names no amount at all, so the pair the
  * agent passes is the amount the cardholder approves: authorize() refuses one
@@ -207,13 +216,15 @@ export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CY
  * no more than that (the API's card rule). Moneris Hosted Tokenization's
  * request.php carries the card and no price: the merchant's server charges the
  * token later, so the agent's pair, above zero (MONERIS_PSP below), is the one
- * figure the approval shows.
+ * figure the approval shows. Paddle VGS's card request carries none either: Paddle
+ * charges the stored card at /pay for what the checkout says, so the agent's pair,
+ * which the prepared checkout carries, is the total the cardholder approves.
  */
 const MONERIS_PSP = 'moneris';
-const AGENT_AMOUNT_PROCESSORS = [GMO_PSP, PELECARD_PSP, WSPAY_PSP, SECURE_ACCEPTANCE_PSP, MONERIS_PSP];
+const AGENT_AMOUNT_PROCESSORS = [GMO_PSP, PELECARD_PSP, WSPAY_PSP, SECURE_ACCEPTANCE_PSP, MONERIS_PSP, PADDLE_VGS_PSP];
 /** How AmountRequiredError names a processor. */
 const PROCESSOR_NAMES = { [GMO_PSP]: 'GMO', [PELECARD_PSP]: 'Pelecard', [WSPAY_PSP]: 'WSPay',
-    [SECURE_ACCEPTANCE_PSP]: 'CyberSource Secure Acceptance', [MONERIS_PSP]: 'Moneris' };
+    [SECURE_ACCEPTANCE_PSP]: 'CyberSource Secure Acceptance', [MONERIS_PSP]: 'Moneris', [PADDLE_VGS_PSP]: 'Paddle' };
 /**
  * Processors whose request and answer name no amount at all, so the total the
  * payment page shows (`pageAmount`) is the one figure that ties the agent's pair
@@ -949,6 +960,71 @@ function maskCreditguardTxId(path) {
 const PATH_SECRET_HOSTS = ['proxy.wspay.biz', 'proxy-test.wspay.biz', 'ipg.monri.com', 'ipgtest.monri.com'];
 /** The segment after a `payment` segment, in any case (the WSPay proxy is IIS) or after an escaped slash. */
 const PATH_SECRET = /(\/payment(?:\/|%2f))[^/]*/gi;
+/**
+ * Gravy (Gr4vy) gives every merchant hosts of its own under gr4vy.app, and Secure Fields sends the
+ * card to /checkout/sessions/<session id>/fields with no auth header, so the session id is that
+ * request's only credential (payment-core definitions.js): with it anyone can write card fields
+ * into the session until it expires. On those hosts the segment after /checkout/sessions/, in any
+ * case or after an escaped slash, reads {session}, as does any other id shaped like Gravy's UUID
+ * session ids.
+ */
+const GRAVY_HOST = /(?:^|\.)gr4vy\.app\.?$/i;
+const GRAVY_SESSION = /(\/checkout\/sessions(?:\/|%2f))[^/]*/gi;
+const GRAVY_SESSION_ID = /[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}/gi;
+function maskGravySession(path) {
+    return path.replace(GRAVY_SESSION, '$1{session}').replace(GRAVY_SESSION_ID, '{session}');
+}
+/**
+ * Rapyd's hosted pages send the card to api.rapyd.net (sandboxapi.rapyd.net in test) with no auth
+ * header: the page's own id in the path, checkout_<id> for a checkout page and hp_card_<id> for a
+ * card page, is the request's only credential (payment-core definitions.js), and with it anyone can
+ * read that page and post a card to it until it expires. On Rapyd's hosts every id of those shapes
+ * (hp_reuse_<id>, a payment link's, too) and the segment after /hosted/collect/card/, in any case or
+ * after an escaped slash, read {token}.
+ */
+const RAPYD_HOST = /(?:^|\.)rapyd\.net\.?$/i;
+const RAPYD_CARD_PAGE = /(\/hosted\/collect\/card(?:\/|%2f))[^/]*/gi;
+const RAPYD_PAGE_ID = /(?:checkout|hp_[a-z]+)_[a-z0-9]+/gi;
+function maskRapydToken(path) {
+    return path.replace(RAPYD_CARD_PAGE, '$1{token}').replace(RAPYD_PAGE_ID, '{token}');
+}
+/**
+ * Stripe Checkout's pages confirm a Checkout Session at /v1/payment_pages/<session id>/confirm on
+ * api.stripe.com with the merchant's publishable key, which is public, so the session id is what
+ * lets anyone confirm a payment on that checkout until it expires. There the segment after
+ * /payment_pages/, in any case or after an escaped slash, reads {session}. A PaymentIntent or
+ * SetupIntent id stays: confirming one also needs its client_secret, which rides in the body.
+ */
+const STRIPE_API_HOST = /^api\.stripe\.com\.?$/i;
+const STRIPE_PAYMENT_PAGE = /(\/payment_pages(?:\/|%2f))[^/]*/gi;
+function maskStripeSession(path) {
+    return path.replace(STRIPE_PAYMENT_PAGE, '$1{session}');
+}
+/**
+ * redactAciCheckoutId (aci.ts) takes the checkout id out of the paths ACI's widget sends. This rule
+ * takes any other copy of it out on ACI's hosts: a trailing dot on the host, an escaped or doubled
+ * slash, another case, a string that is not a URL. The segment after /v1/checkouts/ and any id of
+ * ACI's shape (<32 hex>.<cluster>-vm-tx<nn>) read {checkoutId}.
+ */
+const ACI_HOST = /^(?:eu-prod\.|eu-test\.|test\.)?oppwa\.com\.?$/i;
+const ACI_CHECKOUT = /(\/v1\/checkouts(?:\/|%2f))[^/]*/gi;
+const ACI_CHECKOUT_ID = /[0-9a-f]{32}\.[a-z0-9]{1,16}-vm-tx[0-9]{1,3}/gi;
+function maskAciCheckout(path) {
+    return path.replace(ACI_CHECKOUT, '$1{checkoutId}').replace(ACI_CHECKOUT_ID, '{checkoutId}');
+}
+/**
+ * The processors whose card request carries its own credential in the URL path, with the hosts
+ * that send it, the text that names those hosts in a string that is not a URL, and the mask. The
+ * guard in redact-url.test.mjs fails for a payment-core recognizer that no one has sorted into
+ * this list or out of it.
+ */
+const PATH_CREDENTIALS = [
+    { host: CREDITGUARD_HOST, named: /creditguard\.co\.il/i, mask: maskCreditguardTxId },
+    { host: GRAVY_HOST, named: /gr4vy\.app/i, mask: maskGravySession },
+    { host: RAPYD_HOST, named: /rapyd\.net/i, mask: maskRapydToken },
+    { host: STRIPE_API_HOST, named: /api\.stripe\.com/i, mask: maskStripeSession },
+    { host: ACI_HOST, named: /oppwa\.com/i, mask: maskAciCheckout },
+];
 /**
  * A URL as it may appear in an error message: origin + path only. A paused
  * request's URL can carry a client secret in its query string, and error
@@ -958,8 +1034,13 @@ const PATH_SECRET = /(\/payment(?:\/|%2f))[^/]*/gi;
  * so it reads {txId}, as does any other id-shaped segment there.
  * On the Monri and WSPay hosts the secret is a path segment, so it is replaced
  * with `{client_secret}`: https://proxy.wspay.biz/v2/payment/{client_secret}/confirm.
+ * On Gravy's hosts the checkout session id is the credential, so it reads
+ * `{session}`: https://api.<merchant>.gr4vy.app/checkout/sessions/{session}/fields.
+ * On Rapyd's hosts the hosted page's id reads `{token}`: https://api.rapyd.net/v1/checkout/{token}.
+ * On api.stripe.com a Checkout Session id reads `{session}`:
+ * https://api.stripe.com/v1/payment_pages/{session}/confirm.
  * A string that is not a URL keeps the part before any `?` or `#`, with the
- * same segment masked.
+ * same segments masked.
  */
 export function redactUrl(raw) {
     // An ACI checkout id is that checkout's only capability; it never rides on an event.
@@ -969,12 +1050,18 @@ export function redactUrl(raw) {
     try {
         const u = new URL(raw);
         // A trailing dot names the same host, so it cannot let the secret through.
-        const path = PATH_SECRET_HOSTS.includes(u.hostname.replace(/\.$/, '')) ? u.pathname.replace(PATH_SECRET, '$1{client_secret}') : u.pathname;
-        return `${u.origin}${CREDITGUARD_HOST.test(u.hostname) ? maskCreditguardTxId(path) : path}`;
+        let path = PATH_SECRET_HOSTS.includes(u.hostname.replace(/\.$/, '')) ? u.pathname.replace(PATH_SECRET, '$1{client_secret}') : u.pathname;
+        for (const rule of PATH_CREDENTIALS)
+            if (rule.host.test(u.hostname))
+                path = rule.mask(path);
+        return `${u.origin}${path}`;
     }
     catch {
-        const bare = raw.split(/[?#]/)[0].replace(PATH_SECRET, '$1{client_secret}');
-        return /creditguard\.co\.il/i.test(bare) ? maskCreditguardTxId(bare) : bare;
+        let bare = raw.split(/[?#]/)[0].replace(PATH_SECRET, '$1{client_secret}');
+        for (const rule of PATH_CREDENTIALS)
+            if (rule.named.test(bare))
+                bare = rule.mask(bare);
+        return bare;
     }
 }
 /**
@@ -1029,6 +1116,17 @@ const EPROTECT_PREPARATION_REFUSALS = ['merchant_profile_mismatch'];
 const SECURE_ACCEPTANCE_PREPARATION_REFUSALS = [
     'processor_unavailable', 'sandbox_host_on_live_row', 'live_host_on_sandbox_row', 'unsupported_checkout', 'merchant_profile_mismatch',
 ];
+/**
+ * The API's refusals of a Paddle VGS preparation, before any preparation exists, that prepareCheckout
+ * surfaces by name: the lane is held to Agentcard's own account (`processor_unavailable`), the environment
+ * is not the client's test or live mode, a live checkout's merchant is not the name the reviewed seller pin
+ * carries (`merchant_profile_mismatch`), and the locked card is on a network Paddle's card request is not
+ * paid on (`paddle_vgs_card_unsupported`). An unreviewed seller's page answers `unsupported_checkout`, which
+ * PREPARATION_REFUSALS names for every checkout. Only for a Paddle checkout.
+ */
+const PADDLE_VGS_PREPARATION_REFUSALS = [
+    'processor_unavailable', 'sandbox_host_on_live_row', 'live_host_on_sandbox_row', 'merchant_profile_mismatch', 'paddle_vgs_card_unsupported',
+];
 /**
  * The reason the cardholder's device declines a bound prepared row with, per processor, when its own
  * send boundary passed before the card left it (the Vault's sendWindow, 12 seconds after it last saw
@@ -1541,6 +1639,12 @@ export class VaultClient {
         const amadeus = input.psp === AMADEUS_CHECKOUT_PSP;
         if (amadeus && !input.cardId)
             throw fail('card_required');
+        // Paddle VGS: Paddle's /pay sends the expiry and the card network the agent typed into Paddle's form
+        // (placeholderCard) beside the card the device stores, so the preparation names that card, and the API
+        // approves no other; refusing here asks nobody to approve a preparation that could never bind.
+        const paddle = input.psp === PADDLE_VGS_PSP;
+        if (paddle && !input.cardId)
+            throw fail('card_required');
         // CyberSource Flex, tokenized before Pay: the loaded card field's capture context and fields,
         // verified here against the keys payment-core pins before anything is created (the API and the
         // cardholder's device verify them again).
@@ -1665,6 +1769,8 @@ export class VaultClient {
                         || (secureAcceptance && (state.secure_acceptance_profile_id !== secureAcceptanceProfileId || state.card_id !== input.cardId))
                         // Amadeus: the card the cardholder approved is the one whose expiry the agent typed.
                         || (amadeus && state.card_id !== input.cardId)
+                        // Paddle VGS: the card the cardholder approved is the one whose facts the agent typed.
+                        || (paddle && state.card_id !== input.cardId)
                         // The API says a preparation tokenizes before Pay exactly when this one carried a capture context.
                         || (state.tokenize_before_pay === true) !== !!flexContext)
                         throw fail('ready_unconfirmed', id);
@@ -1709,6 +1815,7 @@ export class VaultClient {
                 && ((error.status >= 400 && error.status < 500 && (PREPARATION_REFUSALS.includes(error.code)
                     || (input.psp === 'fiserv' && FISERV_PREPARATION_REFUSALS.includes(error.code))
                     || (input.psp === EPROTECT_PSP && EPROTECT_PREPARATION_REFUSALS.includes(error.code))
+                    || (input.psp === PADDLE_VGS_PSP && PADDLE_VGS_PREPARATION_REFUSALS.includes(error.code))
                     || (!!flexContext && CYBERSOURCE_FLEX_PREPARATION_REFUSALS.includes(error.code))))
                     || (input.psp === 'fiserv' && error.status === 502 && error.code === 'cse_key_unavailable')))
                 throw fail(error.code);
@@ -2138,9 +2245,12 @@ export class VaultClient {
         // A prepared CyberSource Secure Acceptance token create too, for 30 seconds:
         // the merchant's page asks its frame for the reply for 30 seconds from Save,
         // and the API names 500 ms as such a row's poll interval.
+        // A prepared Paddle VGS card request too, for 20 seconds: Paddle's frame aborts it 10 seconds after
+        // Pay and sends it once more, and the API names 500 ms as such a row's poll interval.
         const preparedFastPollUntil = preparation?.psp === 'mercado_pago' ? Date.now() + 10_000
-            : preparation?.psp === EPROTECT_PSP ? Date.now() + 15_000
-                : preparation?.psp === SECURE_ACCEPTANCE_PSP ? Date.now() + SECURE_ACCEPTANCE_FAST_POLL_MS : 0;
+            : preparation?.psp === PADDLE_VGS_PSP ? Date.now() + 20_000
+                : preparation?.psp === EPROTECT_PSP ? Date.now() + 15_000
+                    : preparation?.psp === SECURE_ACCEPTANCE_PSP ? Date.now() + SECURE_ACCEPTANCE_FAST_POLL_MS : 0;
         // A preparation that tokenized before Pay: the cardholder's device already holds CyberSource's
         // token and approves as soon as this bind reaches it, while the page may give createToken only
         // seconds (Alaska Airlines' flight checkout gives it three). Poll every 100 ms for 10 seconds,
@@ -2510,6 +2620,14 @@ export class VaultClient {
                             throw new PaymentOutcomeUnknownError(authorizationId, 'mercado_checkout_metadata_invalid');
                         }
                     }
+                    else if (rec?.psp === PADDLE_VGS_PSP) {
+                        // Paddle VGS: the approved card's details the phone read from the card it stored at VGS, which the
+                        // frame's /pay names in place of the placeholder's (paddle-vgs-pay.ts). Exactly those five, or the
+                        // stored card's id never reaches the frame.
+                        processorContext = paddleVgsCardFactsOf(s.processor_context) ?? undefined;
+                        if (!processorContext)
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'paddle_vgs_card_facts_unavailable');
+                    }
                     else if (s.processor_context !== undefined)
                         throw new PaymentOutcomeUnknownError(authorizationId, 'unexpected_processor_context');
                     return {
@@ -2686,11 +2804,12 @@ export class VaultClient {
      * approval produced: a SetupIntent confirm that carries no card and pays with
      * exactly the approved payment method (the page's own, or written by the
      * adapters in place of a card the confirm carries again).
-     * The API allows a card save only for a company Agentcard turned it on for,
-     * for an approval given on the Vault page, not by voice, with no amount, and
-     * a SetupIntent Stripe reports still confirmable on the same Stripe account;
-     * any other answer rejects with a CheckoutApiError whose code says why (for
-     * example `continuation_invalid` where it is off, `amount_mismatch`). Nothing
+     * The API allows a card save for any company, for an approval given on the
+     * Vault page, not by voice, with no amount, and a SetupIntent Stripe reports
+     * still confirmable on the same Stripe account; any other answer rejects with
+     * a CheckoutApiError whose code says why (for example `amount_mismatch`, or
+     * `continuation_invalid` for a confirm that is not a card-free SetupIntent
+     * confirm). Nothing
      * is charged: the adapters continue the page's request once this resolves.
      */
     async checkStripeSetupContinuation(authorizationId, request) {

package/dist/lifecycle.d.ts

@@ -4,6 +4,7 @@ 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';
+import type { PaddleVgsPayRefusal } from './paddle-vgs-pay.js';
 /** The application's resolver confirmed the payment for this checkout authorization. */
 export interface MerchantPaymentConfirmation {
     kind: 'merchant_payment';
@@ -91,6 +92,11 @@ export interface ResumeResult {
         headers: Record<string, string>;
         body: string;
     };
+    /**
+     * The read's `processor_context`, as the API serves it. A Paddle VGS read carries the approved card's
+     * details here, which the frame's /pay names; without them the stored card's id is never handed to the page.
+     */
+    processor_context?: unknown;
     substitutions?: Substitutions;
     submitted_at?: string;
     execution_mode?: string;
@@ -239,9 +245,12 @@ export declare class CheckoutLifecycle implements CheckoutController {
      * over (unsupported_paypal_hosted_fields, paypal-hosted-fields.ts), or a card
      * a merchant's page posts to CyberSource Secure Acceptance's Silent Order
      * POST, which no Vault mode takes over either
-     * (unsupported_cybersource_secure_acceptance, cybersource-secure-acceptance.ts).
+     * (unsupported_cybersource_secure_acceptance, cybersource-secure-acceptance.ts), or a
+     * Paddle /pay naming a stored card that its binding does not continue (the
+     * paddle-vgs-pay.ts reasons): once an approval exists the state keeps it, and only the
+     * hold changes.
      */
-    unsupported(reason?: 'unrecognized_payment_endpoint' | 'merchant_profile_observe' | 'merchant_request_unsupported' | GmoUnsupportedReason | 'microform_unsupported' | 'juspay_request_unsupported' | 'merchant_card_endpoint_not_enabled' | 'merchant_card_endpoint_resend_refused' | 'creditguard_three_d_secure' | 'unsupported_primer_sdk' | 'unsupported_primer_request' | PayrailsUnsupportedReason | ShijiStsUnsupportedReason | 'processor_card_page' | 'unsupported_paypal_hosted_fields' | 'unsupported_cybersource_secure_acceptance'): void;
+    unsupported(reason?: 'unrecognized_payment_endpoint' | 'merchant_profile_observe' | 'merchant_request_unsupported' | GmoUnsupportedReason | 'microform_unsupported' | 'juspay_request_unsupported' | 'merchant_card_endpoint_not_enabled' | 'merchant_card_endpoint_resend_refused' | 'creditguard_three_d_secure' | 'unsupported_primer_sdk' | 'unsupported_primer_request' | PayrailsUnsupportedReason | ShijiStsUnsupportedReason | 'processor_card_page' | 'unsupported_paypal_hosted_fields' | 'unsupported_cybersource_secure_acceptance' | PaddleVgsPayRefusal): 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

package/dist/lifecycle.js

@@ -238,7 +238,10 @@ export class CheckoutLifecycle {
      * over (unsupported_paypal_hosted_fields, paypal-hosted-fields.ts), or a card
      * a merchant's page posts to CyberSource Secure Acceptance's Silent Order
      * POST, which no Vault mode takes over either
-     * (unsupported_cybersource_secure_acceptance, cybersource-secure-acceptance.ts).
+     * (unsupported_cybersource_secure_acceptance, cybersource-secure-acceptance.ts), or a
+     * Paddle /pay naming a stored card that its binding does not continue (the
+     * paddle-vgs-pay.ts reasons): once an approval exists the state keeps it, and only the
+     * hold changes.
      */
     unsupported(reason = 'unrecognized_payment_endpoint') {
         this.held = true;

package/dist/paddle-vgs-pay.d.ts

@@ -0,0 +1,55 @@
+import type { ReplayResponse } from './client.js';
+/**
+ * Why a /pay naming a stored card was aborted, reported as the `reason` of the `unsupported_checkout` event:
+ *   paddle_vgs_pay_unbound        this attachment handed no stored card's id to the frame that sent it
+ *   paddle_vgs_pay_expired        it came more than a minute after the id reached the frame
+ *   paddle_vgs_pay_used           the one /pay for that id already went
+ *   paddle_vgs_pay_card_mismatch  it names another stored card, or the other environment's checkout service
+ *   paddle_vgs_pay_unsupported    anything else payment-core's rule refuses: another shape, a card saved at
+ *                                 Paddle for later, a network the frame chose from the typed card
+ */
+export type PaddleVgsPayRefusal = 'paddle_vgs_pay_unbound' | 'paddle_vgs_pay_expired' | 'paddle_vgs_pay_used' | 'paddle_vgs_pay_card_mismatch' | 'paddle_vgs_pay_unsupported';
+/** The patterns attachToCdp holds Paddle's two checkout services under, only for an attachment the API served Paddle VGS to. */
+export declare const PADDLE_VGS_PAY_PATTERNS: readonly string[];
+/** Whether `url` is on one of Paddle's two checkout services: what attachToPlaywright routes, once served. */
+export declare function isPaddleCheckoutService(url: string): boolean;
+/** Whether the synced registry serves Paddle VGS's card request: an org Agentcard turned Paddle on for. */
+export declare function recognizesPaddleVgs(vault: {
+    isCardRequest?: (url: string, method?: string) => boolean;
+} | null | undefined): boolean;
+/** The URL an event names for a /pay: its origin and path, with the checkout's id as {checkout}. */
+export declare function paddleVgsPayEventUrl(url: string): string;
+/**
+ * One attachment's /pay binding: at most one, to the stored card's id it last handed a Paddle frame. `arm` runs
+ * right before the id is handed over, `release` when the attachment is cancelled, and `judge` for every request
+ * to Paddle's checkout services. `served` says whether the synced registry serves Paddle VGS; it is asked only
+ * about a POST to /pay, so no other request reads the registry here.
+ */
+export declare class PaddleVgsPayGate {
+    private readonly served;
+    private readonly now;
+    private bound;
+    constructor(served: () => boolean, now?: () => number);
+    /** Whether the gate judges this request: a POST to /pay, on an attachment the API served Paddle VGS to. */
+    holds(url: string, method: string): boolean;
+    /**
+     * Bind the next /pay of `frame`, the frame about to receive `replay` for its card request to `cardsUrl`, to the
+     * stored card's id in the replay and the approved card's facts the API served beside it. Does nothing for a
+     * request to anything but Paddle's card vault. Throws when the frame is unknown, or the replay carries no id or
+     * no facts payment-core reads: the id must then not reach the frame, since its /pay could only carry the
+     * placeholder's facts.
+     */
+    arm(frame: unknown, cardsUrl: string, replay: ReplayResponse): void;
+    /** Drop the binding: no /pay continues with these facts after this. */
+    release(): void;
+    /**
+     * What becomes of a request to Paddle's checkout services: null when it is not a /pay naming a stored card (it
+     * continues untouched), the body to continue it with (payment-core paddleVgsPayVerdict), or why it is aborted.
+     * The binding answers one /pay: the first one from its frame continues or is refused, and either way ends it.
+     */
+    judge(frame: unknown, url: string, method: string, body: string | null): {
+        body: string;
+    } | {
+        reason: PaddleVgsPayRefusal;
+    } | null;
+}

package/dist/paddle-vgs-pay.js

@@ -0,0 +1,115 @@
+// Paddle's /pay, the request that charges the card the cardholder's phone stored at VGS, as the SDK sees it
+// (payment-core paddle-vgs.js has the request's shape and the rule).
+//
+// Once the SDK hands the stored card's id to Paddle's checkout frame, the frame posts /pay to its checkout
+// service with that id beside card facts it read from the number typed into its own form: on this lane the
+// agent's placeholder, so the placeholder's first six, last four and brand. This build holds that /pay and
+// writes over those five values the approved card's own, which the phone read from the card it sent to VGS and
+// the API served with the id (payment-core paddleVgsPayVerdict). Every other byte goes as the frame wrote it.
+//
+// The binding: the frame that received the stored card's id, the id, the vault's environment and the approved
+// card's facts, for PADDLE_VGS_CARD_ID_WINDOW_MS after the hand-over, for one /pay. A /pay naming a stored card
+// is aborted, so Paddle charges nothing, when this attachment handed no id to that frame
+// (paddle_vgs_pay_unbound), after the window (paddle_vgs_pay_expired), after the one /pay already went
+// (paddle_vgs_pay_used), or when payment-core's rule refuses it: another stored card or environment
+// (paddle_vgs_pay_card_mismatch), or any other shape (paddle_vgs_pay_unsupported). A /pay naming no stored card
+// (PayPal, a wallet) carries none of the cardholder's cards and continues untouched.
+//
+// Nothing is decided without the registry: an attachment the API did not serve Paddle VGS to never holds
+// Paddle's checkout service, so its /pay continues untouched, exactly as before.
+import { PADDLE_VGS_CARD_ID_WINDOW_MS, PADDLE_VGS_CARDS_URLS, paddleVgsCardFactsOf, paddleVgsEnvironment, paddleVgsPayCarriesStoredCard, paddleVgsPayTarget, paddleVgsPayVerdict, } from './paddle-vgs.generated.js';
+const CHECKOUT_SERVICES = ['https://checkout-service.paddle.com', 'https://sandbox-checkout-service.paddle.com'];
+/** The patterns attachToCdp holds Paddle's two checkout services under, only for an attachment the API served Paddle VGS to. */
+export const PADDLE_VGS_PAY_PATTERNS = CHECKOUT_SERVICES.map((origin) => `${origin}/*`);
+/** Whether `url` is on one of Paddle's two checkout services: what attachToPlaywright routes, once served. */
+export function isPaddleCheckoutService(url) {
+    try {
+        return CHECKOUT_SERVICES.includes(new URL(url).origin);
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether the synced registry serves Paddle VGS's card request: an org Agentcard turned Paddle on for. */
+export function recognizesPaddleVgs(vault) {
+    if (!vault || typeof vault.isCardRequest !== 'function')
+        return false;
+    try {
+        return vault.isCardRequest(PADDLE_VGS_CARDS_URLS.production, 'POST') || vault.isCardRequest(PADDLE_VGS_CARDS_URLS.sandbox, 'POST');
+    }
+    catch {
+        return false;
+    }
+}
+/** The URL an event names for a /pay: its origin and path, with the checkout's id as {checkout}. */
+export function paddleVgsPayEventUrl(url) {
+    return url.replace(/^(https:\/\/[^/]+\/(?:checkout|transaction-checkout)\/)[^/]+(\/pay)$/, '$1{checkout}$2');
+}
+const known = (frame) => frame !== undefined && frame !== null && frame !== '';
+/**
+ * One attachment's /pay binding: at most one, to the stored card's id it last handed a Paddle frame. `arm` runs
+ * right before the id is handed over, `release` when the attachment is cancelled, and `judge` for every request
+ * to Paddle's checkout services. `served` says whether the synced registry serves Paddle VGS; it is asked only
+ * about a POST to /pay, so no other request reads the registry here.
+ */
+export class PaddleVgsPayGate {
+    served;
+    now;
+    bound = null;
+    constructor(served, now = Date.now) {
+        this.served = served;
+        this.now = now;
+    }
+    /** Whether the gate judges this request: a POST to /pay, on an attachment the API served Paddle VGS to. */
+    holds(url, method) {
+        return String(method).toUpperCase() === 'POST' && paddleVgsPayTarget(url) !== null && this.served();
+    }
+    /**
+     * Bind the next /pay of `frame`, the frame about to receive `replay` for its card request to `cardsUrl`, to the
+     * stored card's id in the replay and the approved card's facts the API served beside it. Does nothing for a
+     * request to anything but Paddle's card vault. Throws when the frame is unknown, or the replay carries no id or
+     * no facts payment-core reads: the id must then not reach the frame, since its /pay could only carry the
+     * placeholder's facts.
+     */
+    arm(frame, cardsUrl, replay) {
+        const environment = paddleVgsEnvironment(cardsUrl);
+        if (environment === null)
+            return;
+        this.release();
+        const token = replay.mode === undefined || replay.mode === 'token' ? replay : null;
+        const facts = token ? paddleVgsCardFactsOf(token.processorContext) : null;
+        let cardId = null;
+        try {
+            cardId = token ? JSON.parse(token.body)?.data?.id : null;
+        }
+        catch {
+            cardId = null;
+        }
+        if (!known(frame) || !facts || typeof cardId !== 'string')
+            throw new Error('paddle_vgs_card_facts_unavailable');
+        this.bound = { frame, environment, cardId, facts, until: this.now() + PADDLE_VGS_CARD_ID_WINDOW_MS, used: false };
+    }
+    /** Drop the binding: no /pay continues with these facts after this. */
+    release() {
+        this.bound = null;
+    }
+    /**
+     * What becomes of a request to Paddle's checkout services: null when it is not a /pay naming a stored card (it
+     * continues untouched), the body to continue it with (payment-core paddleVgsPayVerdict), or why it is aborted.
+     * The binding answers one /pay: the first one from its frame continues or is refused, and either way ends it.
+     */
+    judge(frame, url, method, body) {
+        if (!this.holds(url, method) || !paddleVgsPayCarriesStoredCard(body))
+            return null;
+        const bound = this.bound;
+        if (!bound || !known(frame) || frame !== bound.frame)
+            return { reason: 'paddle_vgs_pay_unbound' };
+        if (bound.used)
+            return { reason: 'paddle_vgs_pay_used' };
+        bound.used = true;
+        if (this.now() > bound.until)
+            return { reason: 'paddle_vgs_pay_expired' };
+        const verdict = paddleVgsPayVerdict({ url, method, body }, { environment: bound.environment, cardId: bound.cardId, facts: bound.facts });
+        return verdict.verdict === 'continue' ? { body: verdict.body } : { reason: verdict.code };
+    }
+}

package/dist/paddle-vgs.generated.d.ts

@@ -0,0 +1,78 @@
+declare var PADDLE_VGS_PSP: string;
+declare var PADDLE_VGS_CAPABILITY: string;
+declare var PADDLE_VGS_OPERATION: string;
+declare var PADDLE_VGS_CONTENT_TYPE: string;
+declare var PADDLE_VGS_CARDS_URLS: Readonly<{
+    production: "https://vault.paddle.com/cards";
+    sandbox: "https://sandbox-vault.paddle.com/cards";
+}>;
+declare var PADDLE_VGS_REFUSAL_CODES: readonly string[];
+declare function paddleVgsEnvironment(url: any): "production" | "sandbox" | null;
+declare function isPaddleVgsCardsUrl(url: any): boolean;
+declare function paddleVgsBodyVerdict(body: any): Readonly<{
+    verdict: "refuse";
+    code: any;
+}> | Readonly<{
+    verdict: "card";
+}>;
+declare function paddleVgsRequestRefusal(request: any): any;
+declare function isPreparedPaddleVgsRequest(url: any, method: any, body: any, environment: any, headers: any): boolean;
+declare var PADDLE_VGS_MERCHANT_PINS: readonly any[];
+declare function paddleVgsMerchantPin(merchantOrigin: any, pins?: readonly any[]): any;
+declare function paddleVgsMerchantRefusal(environment: any, merchantOrigin: any, authorization: any, pins?: readonly any[]): "unsupported_environment" | "paddle_vgs_merchant_unreviewed" | "paddle_vgs_seller_unreviewed" | null;
+declare function paddleVgsSellerClaimsPinned(pins?: readonly any[]): boolean;
+declare function paddleVgsRefusalMessage(code: any): any;
+declare var PADDLE_VGS_CARD_NETWORKS: readonly string[];
+declare function paddleVgsCardRefusal(body: any, card: any): any;
+declare function paddleVgsStoredCardRefusal(brand: any): "paddle_vgs_card_unsupported" | null;
+declare function paddleVgsTypedCardRefusal(body: any, stored: any): any;
+declare function injectPaddleVgsCard(body: any, card: any): {
+    body: string;
+    where: string[];
+};
+declare function paddleVgsRefusalCode(text: any): string | null;
+declare function paddleVgsAnswerOutcome(status: any, text: any, card: any): {
+    outcome: string;
+    reason: string;
+    code?: undefined;
+    body?: undefined;
+} | {
+    outcome: string;
+    code: string;
+    reason?: undefined;
+    body?: undefined;
+} | {
+    outcome: string;
+    body: string;
+    reason?: undefined;
+    code?: undefined;
+};
+declare var PADDLE_VGS_CARD_ID_WINDOW_MS: number;
+declare function paddleVgsPayTarget(url: any): Readonly<{
+    environment: "production" | "sandbox";
+    line: "classic" | "billing";
+}> | null;
+declare function paddleVgsPayCarriesStoredCard(body: any): boolean;
+declare function paddleVgsCardFacts(card: any): Readonly<{
+    card_first_six: string;
+    card_last_four: string;
+    expiry_month: number;
+    expiry_year: number;
+    card_brand: "visa" | "master" | "american_express";
+}>;
+declare function paddleVgsCardFactsOf(value: any): Readonly<{
+    card_first_six: any;
+    card_last_four: string;
+    expiry_month: any;
+    expiry_year: any;
+    card_brand: any;
+}> | null;
+declare function paddleVgsCardFactsAgree(facts: any, stored: any): boolean;
+declare function paddleVgsPayVerdict(request: any, approved: any): Readonly<{
+    verdict: "refuse";
+    code: any;
+}> | Readonly<{
+    verdict: "continue";
+    body: string;
+}>;
+export { PADDLE_VGS_CAPABILITY, PADDLE_VGS_CARDS_URLS, PADDLE_VGS_CARD_ID_WINDOW_MS, PADDLE_VGS_CARD_NETWORKS, PADDLE_VGS_CONTENT_TYPE, PADDLE_VGS_MERCHANT_PINS, PADDLE_VGS_OPERATION, PADDLE_VGS_PSP, PADDLE_VGS_REFUSAL_CODES, injectPaddleVgsCard, isPaddleVgsCardsUrl, isPreparedPaddleVgsRequest, paddleVgsAnswerOutcome, paddleVgsBodyVerdict, paddleVgsCardFacts, paddleVgsCardFactsAgree, paddleVgsCardFactsOf, paddleVgsCardRefusal, paddleVgsEnvironment, paddleVgsMerchantPin, paddleVgsMerchantRefusal, paddleVgsPayCarriesStoredCard, paddleVgsPayTarget, paddleVgsPayVerdict, paddleVgsRefusalCode, paddleVgsRefusalMessage, paddleVgsRequestRefusal, paddleVgsSellerClaimsPinned, paddleVgsStoredCardRefusal, paddleVgsTypedCardRefusal };