@agent-cards/sdk 0.23.12 → 0.23.14

package/dist/paddle-tokenex.js

@@ -0,0 +1,95 @@
+// Paddle TokenEx, the card leg of a Paddle checkout whose frame names the tokenization provider "tokenex",
+// as the SDK sees it (payment-core paddle-tokenex.js has the request's shape, the device encryption and the
+// substitution). Paddle's frame RSA-encrypts the card number and the CVV in the page itself, each on its
+// own, under the account-level TokenEx public key the checkout serves, and carries both inside one request:
+//   POST https://checkout-service.paddle.com/checkout/<id>/pay            (Paddle Classic)
+//   POST https://checkout-service.paddle.com/transaction-checkout/<id>/pay (Paddle Billing)
+// (sandbox-checkout-service.paddle.com in test). The agent's page encrypts a placeholder card, so the /pay
+// names the placeholder's ciphertexts and the placeholder's first six, last four, expiry and brand. This
+// build holds that /pay and writes over them the approved card's own: the two ciphertexts the cardholder's
+// device produced under the key payment-core pins (never a key from a row, a request or a page) and the
+// five metadata facts the device read from the real card. Every other byte goes as the frame wrote it
+// (mode cse), so the full card number never reaches the agent's runtime.
+//
+// The generic Adyen swap writes only the named ciphertext path, not the five metadata facts a sibling of
+// tokenex_card, so this lane is dispatched by psp to substitutePaddleTokenex instead, exactly as Shiji STS
+// is dispatched for its own body root. A production checkout-service refuses the Vault's cross-origin /pay
+// (403 at Cloudflare), so the device cannot send /pay itself and the lane rides in the agent's page.
+//
+// The registry entry ships dark (capability paddle_tokenex_pay). This build declares the capability on
+// syncRegistry, and the API serves the recognizer only to an org Agentcard enabled for paddle_tokenex, so
+// for every other org nothing here fires: isCardRequest never recognizes a TokenEx /pay and Paddle's
+// requests go through untouched. Autopilot never pays this processor: the API, the authority and the
+// enclave refuse it.
+import { PADDLE_TOKENEX_FIELDS, PADDLE_TOKENEX_FACT_KEYS, paddleTokenexPayTarget, substitutePaddleTokenex } from './paddle-tokenex.generated.js';
+/** The PSP id the API and the recognizer name this lane, re-exported so the client dispatches by it. */
+export { PADDLE_TOKENEX_PSP } from './paddle-tokenex.generated.js';
+/** The dark-launch capability a build declares when it fills a Paddle TokenEx /pay with the device's card. */
+export const PADDLE_TOKENEX_CAPABILITY = 'paddle_tokenex_pay';
+/** The holder the two ciphertexts are served at (the frame's tokenex_card), named once so both checks share it. */
+const SERVED_AT = 'data.payment_method_data.card.tokenex_card';
+const CIPHERTEXT_FIELDS = PADDLE_TOKENEX_FIELDS;
+const FACT_KEYS = PADDLE_TOKENEX_FACT_KEYS;
+const STRING_FACTS = ['card_first_six', 'card_last_four', 'card_brand'];
+const NUMBER_FACTS = ['expiry_month', 'expiry_year'];
+/**
+ * Whether an approved Paddle TokenEx authorization's served substitution is one this SDK can continue: JSON
+ * at the frame's tokenex_card holder, no sibling to remove, and exactly the two ciphertext fields, each a
+ * non-empty string and distinct from the other. substitutePaddleTokenex checks each against the pinned key
+ * for the /pay's environment; this is the shape gate the client runs before it acts.
+ */
+export function isPaddleTokenexServedSubstitution(sub) {
+    if (!sub || typeof sub !== 'object' || Array.isArray(sub))
+        return false;
+    const { encoding, at, fields, remove } = sub;
+    if (encoding !== 'json' || at !== SERVED_AT || !fields || typeof fields !== 'object' || Array.isArray(fields))
+        return false;
+    if (remove !== undefined && !(Array.isArray(remove) && remove.length === 0))
+        return false;
+    const named = fields;
+    const names = Object.keys(named);
+    if (names.length !== CIPHERTEXT_FIELDS.length || !CIPHERTEXT_FIELDS.every((name) => typeof named[name] === 'string' && named[name].length > 0))
+        return false;
+    return named.encrypted_card_number !== named.encrypted_cvv;
+}
+/**
+ * Whether the API's `paddle_tokenex_facts` beside an approved set is the five facts this SDK can write over
+ * the placeholder's: exactly the five keys, the three strings as strings and the two expiry parts as
+ * numbers. paddleTokenexSubstitutionOf checks the digits, range and network at the swap; this is the shape
+ * gate the client runs before it acts, so a malformed approval is refused before anything is written.
+ */
+export function isPaddleTokenexServedFacts(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const named = value;
+    const names = Object.keys(named);
+    if (names.length !== FACT_KEYS.length || !FACT_KEYS.every((name) => name in named))
+        return false;
+    return STRING_FACTS.every((name) => typeof named[name] === 'string' && named[name].length > 0)
+        && NUMBER_FACTS.every((name) => typeof named[name] === 'number' && Number.isInteger(named[name]));
+}
+/**
+ * The continuation of an approved Paddle TokenEx /pay: the paused body with the device's two ciphertexts
+ * written over the placeholder's at tokenex_card and the five facts over the placeholder's at metadata
+ * (payment-core substitutePaddleTokenex, which refuses a ciphertext that is not one under the pinned key
+ * for the /pay's environment, or one already in the paused body).
+ *
+ * Only into `approved`, the paused /pay the approval was created from: `url` and `body` must equal it byte
+ * for byte. The account-level TokenEx key is the same for every checkout of that seller, so the device's
+ * ciphertext could be decrypted in any later /pay of the same shape; binding it to the one request keeps
+ * this lane from ever submitting one checkout's ciphertext to another.
+ *
+ * Null when neither URL is a TokenEx /pay, so every other processor keeps the generic swap. Throws for any
+ * other body or URL, and for a substitution or facts the shape gates refuse, in each case before anything
+ * continues.
+ */
+export function paddleTokenexTokenContinuation(url, body, sub, facts, approved) {
+    if (paddleTokenexPayTarget(url) === null && paddleTokenexPayTarget(approved.url) === null)
+        return null;
+    if (url !== approved.url || body !== approved.body)
+        throw new Error('Refusing to substitute: the paused request is not the Paddle TokenEx /pay the cardholder approved.');
+    if (!isPaddleTokenexServedSubstitution(sub) || !isPaddleTokenexServedFacts(facts))
+        throw new Error('Refusing to substitute: the Paddle TokenEx approval is not two ciphertexts and five card facts.');
+    const substitution = { encrypted_card_number: sub.fields.encrypted_card_number, encrypted_cvv: sub.fields.encrypted_cvv, ...facts };
+    return { body: substitutePaddleTokenex(url, body, substitution) };
+}

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

@@ -47,4 +47,32 @@ declare function paddleVgsAnswerOutcome(status: any, text: any, card: any): {
     reason?: undefined;
     code?: undefined;
 };
-export { PADDLE_VGS_CAPABILITY, PADDLE_VGS_CARDS_URLS, 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, paddleVgsCardRefusal, paddleVgsEnvironment, paddleVgsMerchantPin, paddleVgsMerchantRefusal, paddleVgsRefusalCode, paddleVgsRefusalMessage, paddleVgsRequestRefusal, paddleVgsSellerClaimsPinned, paddleVgsStoredCardRefusal, paddleVgsTypedCardRefusal };
+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 };

package/dist/paddle-vgs.generated.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 // Generated from @agent-cards/payment-core. Do not edit.
-// artifact-sha256: b33914c3bb882b868a28a7d7abb91d6cca450c0145dca0aa338474400b6f923e
+// artifact-sha256: f3437a15e11b72b9958179cc9610fdafb411cc5db76be536af62c08360a45575
 // src/paddle-vgs.js
 var PADDLE_VGS_PSP = "paddle_vgs";
 var PADDLE_VGS_CAPABILITY = "paddle_vgs_cards";
@@ -254,12 +254,12 @@ function readAnswer(text) {
         return null;
     }
 }
+var isStoredCardId = (id) => typeof id === "string" && STORED_CARD_ID.test(id) && /[A-Za-z]/.test(id) && !PAN_LIKE.test(id);
 function storedCardId(answer) {
     const data = answer && answer.data;
-    if (!record(data) || data.type !== "cards" || typeof data.id !== "string")
+    if (!record(data) || data.type !== "cards")
         return null;
-    const id = data.id;
-    return STORED_CARD_ID.test(id) && /[A-Za-z]/.test(id) && !PAN_LIKE.test(id) ? id : null;
+    return isStoredCardId(data.id) ? data.id : null;
 }
 var boundedCode = (value) => typeof value === "string" && REFUSAL_CODE.test(value) && (value.match(/[0-9]/g) ?? []).length <= MAX_CODE_DIGITS ? value : null;
 function paddleVgsRefusalCode(text) {
@@ -286,4 +286,123 @@ function paddleVgsAnswerOutcome(status, text, card) {
         return { outcome: "unknown", reason: "paddle_vgs_unsafe_response" };
     return { outcome: "approved", body: JSON.stringify({ data: { type: "cards", id } }) };
 }
-export { PADDLE_VGS_CAPABILITY, PADDLE_VGS_CARDS_URLS, 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, paddleVgsCardRefusal, paddleVgsEnvironment, paddleVgsMerchantPin, paddleVgsMerchantRefusal, paddleVgsRefusalCode, paddleVgsRefusalMessage, paddleVgsRequestRefusal, paddleVgsSellerClaimsPinned, paddleVgsStoredCardRefusal, paddleVgsTypedCardRefusal };
+var PADDLE_VGS_CARD_ID_WINDOW_MS = 6e4;
+var PAY_URL = /^https:\/\/(sandbox-)?checkout-service\.paddle\.com\/(checkout|transaction-checkout)\/[A-Za-z0-9_-]{1,64}\/pay$/;
+function paddleVgsPayTarget(url) {
+    const match = typeof url === "string" ? PAY_URL.exec(url) : null;
+    return match ? Object.freeze({ environment: match[1] ? "sandbox" : "production", line: match[2] === "checkout" ? "classic" : "billing" }) : null;
+}
+function paddleVgsPayCarriesStoredCard(body) {
+    if (typeof body !== "string")
+        return true;
+    try {
+        return JSON.stringify(JSON.parse(body)).includes('"vgs_card"');
+    }
+    catch {
+        return true;
+    }
+}
+var FRAME_BRANDS = /* @__PURE__ */ Object.freeze(["visa", "master", "american_express", "discover", "diners_club", "jcb", "maestro", "dankort", "unionpay", "unknown"]);
+var PAY_BRANDS = /* @__PURE__ */ Object.freeze({ visa: "visa", mastercard: "master", amex: "american_express" });
+var FACT_KEYS = /* @__PURE__ */ Object.freeze(["card_first_six", "card_last_four", "expiry_month", "expiry_year", "card_brand"]);
+var FIRST_SIX = /^[0-9]{6}$/;
+var LAST_FOUR = /^[0-9]{4}$/;
+var fullYear = (year) => {
+    const value = Number(year);
+    return Number.isInteger(value) && value >= 0 && value <= 99 ? 2e3 + value : value;
+};
+var expiryMonth = (month) => Number.isInteger(month) && month >= 1 && month <= 12;
+var expiryYear = (year) => Number.isInteger(year) && year >= 2e3 && year <= 2099;
+function paddleVgsCardFacts(card) {
+    const number = card ? String(card.number) : "";
+    const network = cardNetwork(number);
+    const month = card ? Number(card.month) : NaN;
+    const year = card ? fullYear(card.year) : NaN;
+    if (network === null || !expiryMonth(month) || !expiryYear(year))
+        throw new Error("Could not read this card's details for Paddle. Nothing was sent.");
+    return Object.freeze({ card_first_six: number.slice(0, 6), card_last_four: number.slice(-4), expiry_month: month, expiry_year: year, card_brand: PAY_BRANDS[network] });
+}
+function paddleVgsCardFactsOf(value) {
+    if (!record(value))
+        return null;
+    const keys = Object.keys(value);
+    if (keys.length !== FACT_KEYS.length || !FACT_KEYS.every((key) => keys.includes(key)))
+        return null;
+    const { card_first_six: firstSix, card_last_four: lastFour, expiry_month: month, expiry_year: year, card_brand: brand } = value;
+    const network = typeof firstSix === "string" && FIRST_SIX.test(firstSix) ? cardNetwork(`${firstSix}000000`) : null;
+    if (network === null || PAY_BRANDS[network] !== brand || typeof lastFour !== "string" || !LAST_FOUR.test(lastFour) || !expiryMonth(month) || !expiryYear(year))
+        return null;
+    return Object.freeze({ card_first_six: firstSix, card_last_four: lastFour, expiry_month: month, expiry_year: year, card_brand: brand });
+}
+function paddleVgsCardFactsAgree(facts, stored) {
+    const read = paddleVgsCardFactsOf(facts);
+    if (!read)
+        return false;
+    const card = record(stored) ? stored : {};
+    const network = Object.keys(PAY_BRANDS).find((name) => PAY_BRANDS[name] === read.card_brand);
+    const brand = storedBrand(card.brand);
+    return !(typeof card.last4 === "string" && LAST_FOUR.test(card.last4) && card.last4 !== read.card_last_four) && (brand === null || brand === network) && !(Number.isInteger(card.expiryMonth) && card.expiryMonth !== read.expiry_month) && !(Number.isInteger(card.expiryYear) && card.expiryYear % 100 !== read.expiry_year % 100);
+}
+var PAY_BODY_LIMIT = 16384;
+var PAY_DATA_KEYS = /* @__PURE__ */ Object.freeze(["payment_method_type", "payment_method_data"]);
+var PAY_CARD_KEYS = /* @__PURE__ */ Object.freeze(["metadata", "three_d_s", "vgs_card"]);
+var METADATA_KEYS = /* @__PURE__ */ Object.freeze(["cardholder_name", ...FACT_KEYS]);
+var BROWSER_INFO = /^[A-Za-z0-9+/]{1,4096}={0,2}$/;
+var RADAR_TOKEN = /^[\x21-\x7e]{1,512}$/;
+var COUNTRY_CODE = /^[A-Za-z]{2}$/;
+var FRONTEND_HOST = /^https:\/\/[\x21-\x7e]{1,1024}$/;
+var radarKeys = (value) => sameKeys(value, ["token", "country_code"]) || sameKeys(value, ["country_code", "token"]);
+function readPay(body, line) {
+    if (typeof body !== "string" || body === "" || body.length > PAY_BODY_LIMIT)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(body);
+        if (!record(value) || JSON.stringify(value) !== body)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const data = value.data;
+    if (!sameKeys(value, ["data"]) || !record(data) || !(sameKeys(data, PAY_DATA_KEYS) || sameKeys(data, [...PAY_DATA_KEYS, "checkout"])) || data.payment_method_type !== (line === "classic" ? "CARD" : "card"))
+        return null;
+    if (data.checkout !== void 0 && !(record(data.checkout) && sameKeys(data.checkout, ["frontend_host"]) && typeof data.checkout.frontend_host === "string" && FRONTEND_HOST.test(data.checkout.frontend_host)))
+        return null;
+    const method = data.payment_method_data;
+    const card = record(method) && sameKeys(method, ["card"]) ? method.card : null;
+    if (!record(card) || !(sameKeys(card, PAY_CARD_KEYS) || sameKeys(card, [...PAY_CARD_KEYS, "session_tracking"])))
+        return null;
+    const metadata = card.metadata;
+    if (!record(metadata) || !sameKeys(metadata, METADATA_KEYS) || typeof metadata.cardholder_name !== "string" || metadata.cardholder_name.length > NAME_LIMIT || CONTROL.test(metadata.cardholder_name) || cardLikeName(metadata.cardholder_name) || typeof metadata.card_first_six !== "string" || !FIRST_SIX.test(metadata.card_first_six) || typeof metadata.card_last_four !== "string" || !LAST_FOUR.test(metadata.card_last_four) || !expiryMonth(metadata.expiry_month) || !expiryYear(metadata.expiry_year) || !FRAME_BRANDS.includes(metadata.card_brand))
+        return null;
+    const details = card.three_d_s;
+    if (!record(details) || !sameKeys(details, ["browser_info"]) || typeof details.browser_info !== "string" || !BROWSER_INFO.test(details.browser_info))
+        return null;
+    if (!record(card.vgs_card) || !sameKeys(card.vgs_card, ["card_id"]) || !isStoredCardId(card.vgs_card.card_id))
+        return null;
+    if (card.session_tracking !== void 0) {
+        const tracking = card.session_tracking;
+        const radar = record(tracking) && sameKeys(tracking, ["stripe_radar"]) ? tracking.stripe_radar : null;
+        if (!record(radar) || !radarKeys(radar) || typeof radar.token !== "string" || !RADAR_TOKEN.test(radar.token) || typeof radar.country_code !== "string" || !COUNTRY_CODE.test(radar.country_code))
+            return null;
+    }
+    return value;
+}
+function paddleVgsPayVerdict(request, approved) {
+    const facts = record(approved) ? paddleVgsCardFactsOf(approved.facts) : null;
+    if (!facts || !isStoredCardId(approved.cardId) || approved.environment !== "production" && approved.environment !== "sandbox") {
+        return refuse("paddle_vgs_pay_unbound");
+    }
+    const target = record(request) && typeof request.method === "string" && request.method.toUpperCase() === "POST" ? paddleVgsPayTarget(request.url) : null;
+    const value = target ? readPay(request.body, target.line) : null;
+    if (!value)
+        return refuse("paddle_vgs_pay_unsupported");
+    const card = value.data.payment_method_data.card;
+    if (target.environment !== approved.environment || card.vgs_card.card_id !== approved.cardId)
+        return refuse("paddle_vgs_pay_card_mismatch");
+    for (const key of FACT_KEYS)
+        card.metadata[key] = facts[key];
+    return Object.freeze({ verdict: "continue", body: JSON.stringify(value) });
+}
+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 };

package/dist/paysafe.generated.d.ts

@@ -1,12 +1,10 @@
 export type PaysafePreparationEnvironment = 'production' | 'sandbox';
 export declare function paysafePreparationUrl(environment: string): string;
-/** Exact strings refuse credentials, queries, fragments and URL normalization. */
+/** The environment of a reviewed build's card URL. Exact strings refuse credentials, queries, fragments and URL normalization. */
 export declare function paysafeEnvironment(url: string): PaysafePreparationEnvironment | undefined;
-/** Checkout 1.8.0 starts a 40-second XHR when Pay is pressed. Prior approval may
- * consume only its new-card request, including native clientInfo and headers.
- * Saved cards, alternate APIs and 3DS-only requests require separate review.
- * Source: hosted.paysafe.com/checkout/1.8.0/main.bundle.js, SHA-256
- * e9e111ff03073cc936a47674e8e7c5db4a6d1050e1b65bf5e20723116fd5080c.
- * The guard checks original bytes and never changes the request.
+/** A reviewed Checkout build (BUILDS) starts a 40-second XHR when Pay is pressed. Prior approval may
+ * consume only its new-card request, including native clientInfo and headers, on the card URL that
+ * build sends to in the approved environment. Saved cards, alternate APIs and 3DS-only requests
+ * require separate review. The guard checks original bytes and never changes the request.
  */
 export declare function isPreparedPaysafeRequest(url: string, method: string, body: string | null, environment: string, headers?: Record<string, string>): boolean;

package/dist/paysafe.generated.js

@@ -1,10 +1,34 @@
 // Generated from @agent-cards/payment-core. Do not edit.
-// source-sha256: 24c7940ae8974c0d24e5a365144c1b07ccc46863ae3094eb92b3c54c8307e837
+// source-sha256: afa00cd57246e51361474c66c5ab4282bd5b39f0297fdf68616e164e19ed1741
 import { readTokenizationJson } from './braintree.js';
+/** The card URL a preparation names: Checkout 1.8.0's. The bind takes the exact URL of the build the request names (BUILDS). */
 const ENDPOINTS = {
     production: 'https://hosted.paysafe.com/checkout/api/v1/tokenize',
     sandbox: 'https://hosted.test.paysafe.com/checkout/api/v1/tokenize',
 };
+/**
+ * The Paysafe Checkout builds whose new-card request a prior approval may consume, each read from
+ * Paysafe's public bundle. A request binds only to the build its own clientInfo.version names, on
+ * that build's URL and headers, so a build Paysafe ships later is refused, and nothing is sent,
+ * until it is read and listed here. The request moved inside 1.x: 1.8.0 to 1.12.0 post to
+ * hosted.paysafe.com with a correlationId header, 1.16.1 to api.paysafe.com with three other
+ * headers, so a version range would hold one build's request to another build's rules.
+ *
+ * 1.8.0: hosted.paysafe.com/checkout/1.8.0/main.bundle.js, SHA-256
+ * e9e111ff03073cc936a47674e8e7c5db4a6d1050e1b65bf5e20723116fd5080c; LIVE/TEST select hosted[.test].
+ * 1.16.1: the checkout/v1/latest loader (SHA-256 5fac65c4f7a74b45388ad3ce7c02282f05e832226792bebc417cd9ff191be4f0)
+ * names it and frames checkout/v1/latest/index.html. Its main.js (SHA-256
+ * 328c6443da930f3648826248afa3c342cdd07d04e49a78b0878dda187772bf80) posts to environment +
+ * "checkout/api/v1/tokenize", and its vendor.js (SHA-256 7348275bd07256e295f4b83b292c7fe5115dd7ac35d1b1fe3d26eda3c37d2835)
+ * maps LIVE/TEST to api[.test].paysafe.com and sets X-Internal-Correlation-Id, X-Paysafe-Credentials,
+ * X-App-Version (the clientInfo version) and X-TransactionSource (CheckoutV1 for paysafe.checkout).
+ * The TEST host serves the same bytes (read 2026-10-15).
+ */
+const BUILDS = [
+    { version: '1.8.0', endpoints: ENDPOINTS, correlation: 'correlationid', fixed: {} },
+    { version: '1.16.1', correlation: 'x-internal-correlation-id', fixed: { 'x-app-version': '1.16.1', 'x-transactionsource': 'CheckoutV1' },
+        endpoints: { production: 'https://api.paysafe.com/checkout/api/v1/tokenize', sandbox: 'https://api.test.paysafe.com/checkout/api/v1/tokenize' } },
+];
 const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 const keys = (value, allowed) => record(value) && Object.keys(value).every(key => allowed.includes(key));
 const exact = (pattern, value) => typeof value === 'string' && pattern.exec(value)?.[0] === value;
@@ -16,27 +40,31 @@ export function paysafePreparationUrl(environment) {
         throw new Error('unsupported_preparation_environment');
     return ENDPOINTS[environment];
 }
-/** Exact strings refuse credentials, queries, fragments and URL normalization. */
+/** The environment of a reviewed build's card URL. Exact strings refuse credentials, queries, fragments and URL normalization. */
 export function paysafeEnvironment(url) {
-    return url === ENDPOINTS.production ? 'production' : url === ENDPOINTS.sandbox ? 'sandbox' : undefined;
+    const build = BUILDS.find(candidate => url === candidate.endpoints.production || url === candidate.endpoints.sandbox);
+    return !build ? undefined : url === build.endpoints.production ? 'production' : 'sandbox';
 }
 const ADDRESS_FIELDS = ['city', 'country', 'zip', 'street', 'street2', 'state'];
 function billing(value) {
     return keys(value, ADDRESS_FIELDS) && Object.values(value).every(value => text(value))
         && (!own(value, 'country') || exact(/^[A-Z]{2}$/, value.country));
 }
-function freshCard(value) {
+/** The reviewed build whose new-card body this is: never a saved card, a 3-D Secure request or another app's body. */
+function freshCardBuild(value) {
     if (!keys(value, ['card', 'clientInfo', 'billingAddress']) || !keys(value.card, ['cardNum', 'cardExpiry', 'cvv', 'holderName']))
-        return false;
+        return undefined;
     const card = value.card;
     if (!exact(/^[0-9]{12,19}$/, card.cardNum) || !exact(/^[0-9]{3,4}$/, card.cvv)
         || !keys(card.cardExpiry, ['month', 'year']) || !exact(/^(?:0[1-9]|1[0-2])$/, card.cardExpiry.month)
         || !exact(/^20[0-9]{2}$/, card.cardExpiry.year) || own(card, 'holderName') && !text(card.holderName)
         || own(value, 'billingAddress') && !billing(value.billingAddress))
-        return false;
+        return undefined;
     const info = value.clientInfo;
-    return keys(info, ['correlationId', 'invocationId', 'version', 'appName'])
-        && uuid(info.correlationId) && uuid(info.invocationId) && info.version === '1.8.0' && info.appName === 'paysafe.checkout';
+    if (!keys(info, ['correlationId', 'invocationId', 'version', 'appName'])
+        || !uuid(info.correlationId) || !uuid(info.invocationId) || info.appName !== 'paysafe.checkout')
+        return undefined;
+    return BUILDS.find(build => build.version === info.version);
 }
 const BROWSER_HEADERS = new Set(['accept', 'accept-language', 'accept-encoding', 'content-length', 'origin', 'referer',
     'user-agent', 'host', 'connection', 'cache-control', 'pragma', 'priority', 'dnt',
@@ -53,9 +81,11 @@ function singleUseCredential(value) {
         return false;
     }
 }
-function nativeHeaders(headers, correlationId) {
+/** The build's own headers, each once with its native value, and only headers a browser adds beside them. */
+function nativeHeaders(headers, correlationId, build) {
     if (!record(headers))
         return false;
+    const native = ['content-type', 'x-paysafe-credentials', build.correlation, ...Object.keys(build.fixed)];
     const parsed = new Map();
     let bytes = 0;
     for (const [name, value] of Object.entries(headers)) {
@@ -63,25 +93,27 @@ function nativeHeaders(headers, correlationId) {
         if (parsed.size >= 64 || parsed.has(lower) || !exact(/^[A-Za-z0-9-]+$/, name) || !text(value, 8192)
             || (bytes += name.length + value.length) > 32768)
             return false;
-        if (!['content-type', 'correlationid', 'x-paysafe-credentials'].includes(lower) && !BROWSER_HEADERS.has(lower)
+        if (!native.includes(lower) && !BROWSER_HEADERS.has(lower)
             && !exact(/^sec-ch-ua(?:-[a-z0-9-]+)?$/, lower))
             return false;
         parsed.set(lower, value);
     }
     return exact(/^application\/json(?:;\s*charset=utf-8)?$/i, parsed.get('content-type'))
-        && parsed.get('correlationid') === correlationId && singleUseCredential(parsed.get('x-paysafe-credentials'));
+        && parsed.get(build.correlation) === correlationId && singleUseCredential(parsed.get('x-paysafe-credentials'))
+        && Object.entries(build.fixed).every(([name, value]) => parsed.get(name) === value);
 }
-/** Checkout 1.8.0 starts a 40-second XHR when Pay is pressed. Prior approval may
- * consume only its new-card request, including native clientInfo and headers.
- * Saved cards, alternate APIs and 3DS-only requests require separate review.
- * Source: hosted.paysafe.com/checkout/1.8.0/main.bundle.js, SHA-256
- * e9e111ff03073cc936a47674e8e7c5db4a6d1050e1b65bf5e20723116fd5080c.
- * The guard checks original bytes and never changes the request.
+/** A reviewed Checkout build (BUILDS) starts a 40-second XHR when Pay is pressed. Prior approval may
+ * consume only its new-card request, including native clientInfo and headers, on the card URL that
+ * build sends to in the approved environment. Saved cards, alternate APIs and 3DS-only requests
+ * require separate review. The guard checks original bytes and never changes the request.
  */
 export function isPreparedPaysafeRequest(url, method, body, environment, headers) {
     if (method !== 'POST' || (environment !== 'production' && environment !== 'sandbox')
         || paysafeEnvironment(url) !== environment)
         return false;
     const value = readTokenizationJson(body);
-    return freshCard(value) && record(value.clientInfo) && nativeHeaders(headers, value.clientInfo.correlationId);
+    if (!value || !record(value.clientInfo))
+        return false;
+    const build = freshCardBuild(value);
+    return !!build && url === build.endpoints[environment] && nativeHeaders(headers, value.clientInfo.correlationId, build);
 }