@agent-cards/sdk 0.23.23 → 0.23.24

package/dist/paddle-checkout-watch.js

@@ -0,0 +1,239 @@
+// Paddle's own checkout answers, recorded read-only in the agent's browser, for the create of a Paddle TokenEx /pay
+// (payment-core paddle-checkout-terms.js reads them, for the API). Paddle's checkout service answers the frame for
+// the checkout it is selling (POST /transaction-checkout, PATCH /transaction-checkout/<che_...>/, POST .../customer),
+// and each answer states what the checkout charges today and, for a free trial, the renewal's price, cycle and first
+// date. The /pay names none of that. So from attach on, the adapters tell this watch about every request to those
+// URLs, each answer's status, the moment each finishes and each body once it is read; the watch keeps each body cut
+// to the terms (projectPaddleCheckoutAnswer), never the customer, address or seller, and at a Billing /pay's pause
+// hands the client the newest few as `paddleCheckout`, which it sends with the create.
+//
+// The browser reads an answer's text after it reports the answer finished, so a pause can come between the two. The
+// pause then waits, up to PADDLE_CHECKOUT_READ_WAIT_MS, for the texts of the /pay's own checkout's answers that
+// finished before it. When one of them is still not read after that, or was still loading at the pause, the terms
+// the page had when the card left are not known, and no answers go: the API then reads no terms, never an older
+// answer's in place of the newest. Answers about another checkout, or on the other environment's host, neither wait
+// nor count; the create counts once its text names the /pay's checkout, since its URL names none.
+//
+// Each checkout keeps its own answers (PER_CHECKOUT, and each host's creates as one more such list), for the
+// CHECKOUTS asked about most recently, so another checkout's requests never push this checkout's answers out. When
+// the watch drops one of a checkout's answers, it remembers what that could hide, and a pause on that checkout sends
+// no answers when a dropped one was still loading or finished no earlier than the newest it would send.
+//
+// What this proves: the answers are what this browser saw. The API holds the agent's amount to today's total they
+// state, judges a renewal against the company's rules and admits a free trial's $0.00 only on them; an agent that
+// writes its own answers is not stopped, a risk Felipe accepted by name for Paddle trials (backend config
+// PADDLE_TRIAL_TERMS_RISK_ACCEPTED). Nothing here pauses, changes or answers a request.
+import { PADDLE_CHECKOUT_ANSWERS_MAX, PADDLE_CHECKOUT_ANSWER_LIMIT, paddleCheckoutAnswerTarget, paddleTokenexPayTarget, projectPaddleCheckoutAnswer, } from './paddle-tokenex.generated.js';
+/** How long a /pay's pause waits for the texts of Paddle's answers that finished before it. */
+export const PADDLE_CHECKOUT_READ_WAIT_MS = 1_000;
+const METHODS = ['GET', 'POST', 'PATCH', 'PUT'];
+const MAX = PADDLE_CHECKOUT_ANSWERS_MAX;
+const LIMIT = PADDLE_CHECKOUT_ANSWER_LIMIT;
+/** Requests the watch keeps for one checkout, or for one host's creates, the oldest sent dropped first. */
+const PER_CHECKOUT = 16;
+/** Checkouts (each host's creates counting as one) the watch keeps requests for, the one asked about least recently dropped whole. */
+const CHECKOUTS = 16;
+/** Checkouts whose dropped answers the watch remembers (Lost), the oldest forgotten first. */
+const LOST_KEPT = 64;
+export class PaddleCheckoutWatch {
+    exchanges = new Map();
+    /** Each checkout's request keys, oldest sent first; the checkout asked about least recently first. */
+    checkouts = new Map();
+    /** Each checkout's dropped answers, by `${environment}:${checkoutId}`. */
+    lost = new Map();
+    /**
+     * By environment, the latest finish of a create dropped after it finished and before its text was read: it may have
+     * been any checkout's on that host, and a create is its checkout's oldest answer.
+     */
+    lostCreateFinishedAt = new Map();
+    waiters = new Set();
+    now;
+    readWaitMs;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.readWaitMs = options.readWaitMs ?? PADDLE_CHECKOUT_READ_WAIT_MS;
+    }
+    /** Whether the request under `key` is one of Paddle's checkout answers whose text is still to be read. */
+    tracks(key) {
+        return this.exchanges.get(key)?.body === null;
+    }
+    /** A request left the page: kept when it asks Paddle's checkout service about the checkout. */
+    sent(key, request) {
+        const method = String(request.method).toUpperCase();
+        const target = METHODS.includes(method) ? paddleCheckoutAnswerTarget(request.url) : null;
+        if (!target)
+            return;
+        // A key the browser reports again (a redirect) starts over.
+        this.remove(key);
+        const checkout = `${target.environment}:${target.checkoutId ?? ''}`;
+        this.exchanges.set(key, { method, url: request.url, checkout, sentAt: this.now(), status: null, finishedAt: null, body: null });
+        const keys = this.checkouts.get(checkout) ?? new Set();
+        this.checkouts.delete(checkout);
+        this.checkouts.set(checkout, keys.add(key));
+        while (keys.size > PER_CHECKOUT) {
+            const oldest = keys.values().next().value;
+            this.drop(oldest);
+            keys.delete(oldest);
+        }
+        while (this.checkouts.size > CHECKOUTS) {
+            const [oldest, oldestKeys] = this.checkouts.entries().next().value;
+            for (const dropped of [...oldestKeys])
+                this.drop(dropped);
+            this.checkouts.delete(oldest);
+        }
+    }
+    /** Drops a kept request, noting what it was about (forget). */
+    drop(key) {
+        const exchange = this.remove(key);
+        if (exchange)
+            this.forget(exchange);
+    }
+    /** Takes a kept request out without a trace, and hands it back. */
+    remove(key) {
+        const exchange = this.exchanges.get(key);
+        if (!exchange)
+            return undefined;
+        this.exchanges.delete(key);
+        const keys = this.checkouts.get(exchange.checkout);
+        keys?.delete(key);
+        if (keys && keys.size === 0)
+            this.checkouts.delete(exchange.checkout);
+        return exchange;
+    }
+    /** Notes what a dropped answer was about, so a pause on its checkout knows what it can no longer see. */
+    forget(exchange) {
+        const target = paddleCheckoutAnswerTarget(exchange.url);
+        if (!target)
+            return;
+        const id = target.checkoutId ?? checkoutNamed(exchange.body);
+        if (id === null) {
+            // A create still loading is another checkout's (the /pay names an id only a finished create gives); one that
+            // finished unread may have been any checkout's on its host.
+            if (exchange.finishedAt !== null && exchange.body === null) {
+                this.lostCreateFinishedAt.set(target.environment, Math.max(this.lostCreateFinishedAt.get(target.environment) ?? -Infinity, exchange.finishedAt));
+            }
+            return;
+        }
+        const key = `${target.environment}:${id}`;
+        const lost = this.lost.get(key) ?? { loadingSentAt: Infinity, finishedAt: -Infinity };
+        if (exchange.finishedAt === null)
+            lost.loadingSentAt = Math.min(lost.loadingSentAt, exchange.sentAt);
+        else
+            lost.finishedAt = Math.max(lost.finishedAt, exchange.finishedAt);
+        this.lost.delete(key);
+        this.lost.set(key, lost);
+        if (this.lost.size > LOST_KEPT)
+            this.lost.delete(this.lost.keys().next().value);
+    }
+    /** Its answer's status arrived. */
+    answered(key, status) {
+        const exchange = this.exchanges.get(key);
+        if (exchange && typeof status === 'number')
+            exchange.status = status;
+    }
+    /** It finished loading: stamped the moment the browser says so, before its text is read, so a pause waits for that read. */
+    finished(key, completedAt) {
+        const exchange = this.exchanges.get(key);
+        if (exchange)
+            exchange.finishedAt ??= completedAt;
+    }
+    /**
+     * Its text was read (`text`, or null when it could not be). Kept cut to the terms; a body that is not a checkout
+     * answer, or whose projection is longer than the API takes, is kept as an empty one, so the reader knows a newer
+     * answer it cannot read came in.
+     */
+    read(key, text, completedAt) {
+        const exchange = this.exchanges.get(key);
+        if (!exchange || exchange.body !== null)
+            return;
+        exchange.finishedAt ??= completedAt;
+        const body = typeof text === 'string' ? projectPaddleCheckoutAnswer(text) : null;
+        exchange.body = typeof body === 'string' && body.length <= LIMIT ? body : '';
+        this.settle();
+    }
+    /**
+     * The request failed or was given up. One that never finished gave the page no answer and is forgotten; one that
+     * finished gave the page an answer this watch could not read, and is kept as one that cannot be read.
+     */
+    failed(key) {
+        const exchange = this.exchanges.get(key);
+        if (!exchange)
+            return;
+        if (exchange.finishedAt === null)
+            this.remove(key);
+        else
+            exchange.body ??= '';
+        this.settle();
+    }
+    settle() {
+        for (const wake of [...this.waiters])
+            wake();
+    }
+    /**
+     * The answers for a Billing /pay paused at `pausedAt`, newest last, or undefined when there are none to send: the
+     * card request is not a Billing /pay, nothing was recorded for its checkout, or the terms as of the pause are not
+     * known (see the header). Waits, up to the read bound or until `signal` aborts, for the texts of the checkout's
+     * answers that finished before the pause.
+     */
+    async capture(pausedAt, cardUrl, signal) {
+        if (paddleTokenexPayTarget(cardUrl)?.line !== 'billing')
+            return undefined;
+        // The /pay's own checkout, read as the answer URL that checkout has: its id and its environment's host.
+        const pay = paddleCheckoutAnswerTarget(cardUrl.replace(/\/pay$/, ''));
+        if (!pay || pay.checkoutId === null)
+            return undefined;
+        const own = `${pay.environment}:${pay.checkoutId}`;
+        const creates = `${pay.environment}:`;
+        const byId = (exchange) => exchange.checkout === own;
+        const create = (exchange) => exchange.checkout === creates;
+        const kept = (checkout) => [...(this.checkouts.get(checkout) ?? [])].map((key) => this.exchanges.get(key));
+        const asked = () => [...kept(own), ...kept(creates)].filter((exchange) => exchange.sentAt <= pausedAt);
+        const unread = (exchange) => exchange.finishedAt !== null && exchange.finishedAt <= pausedAt && exchange.body === null;
+        // The wait runs on the real clock, whatever clock stamps the requests.
+        const deadline = Date.now() + this.readWaitMs;
+        while (asked().some(unread) && !signal?.aborted) {
+            const left = deadline - Date.now();
+            if (left <= 0)
+                break;
+            await new Promise((resolve) => {
+                const wake = () => { clearTimeout(timer); this.waiters.delete(wake); signal?.removeEventListener('abort', wake); resolve(); };
+                const timer = setTimeout(wake, left);
+                this.waiters.add(wake);
+                signal?.addEventListener('abort', wake, { once: true });
+            });
+        }
+        // An answer about the checkout still loading at the pause, still unread, or answered with no status: the terms as
+        // of the pause are not known. So too when a dropped one was still loading by then.
+        const lost = this.lost.get(own);
+        if (lost && lost.loadingSentAt <= pausedAt)
+            return undefined;
+        const checkout = asked().filter(byId);
+        if (checkout.some((exchange) => exchange.finishedAt === null || exchange.finishedAt > pausedAt || exchange.body === null || exchange.status === null))
+            return undefined;
+        // A create counts once it finished, was read and names this checkout: one still loading is another checkout's,
+        // since the /pay names an id only a finished create gives.
+        const created = asked().filter((exchange) => create(exchange) && exchange.status !== null && exchange.finishedAt !== null
+            && exchange.finishedAt <= pausedAt && checkoutNamed(exchange.body) === pay.checkoutId);
+        const answers = [...checkout, ...created].sort((a, b) => a.finishedAt - b.finishedAt).slice(-MAX)
+            .map((exchange) => ({ method: exchange.method, url: exchange.url, status: exchange.status, completedAt: exchange.finishedAt, body: exchange.body }));
+        // A dropped answer that finished no earlier than the newest kept one may have held the newest terms, and one that
+        // finished after the pause was still loading at it; every kept answer finished by the pause, so one test holds both.
+        // A create dropped unread on this host counts the same way, as it may have been this checkout's.
+        const newest = answers.at(-1)?.completedAt ?? -Infinity;
+        if ((lost && lost.finishedAt >= newest) || (this.lostCreateFinishedAt.get(pay.environment) ?? -Infinity) >= newest)
+            return undefined;
+        return answers.length ? { pausedAt, answers } : undefined;
+    }
+}
+/** The checkout a kept projection answers about, or null when it names none. */
+function checkoutNamed(body) {
+    if (!body)
+        return null;
+    try {
+        const id = JSON.parse(body).data?.id;
+        return typeof id === 'string' ? id : null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -1,4 +1,32 @@
 declare function paddleVgsCardFactsAgree(facts: any, stored: any): boolean;
+declare var PADDLE_CHECKOUT_ANSWERS_MAX: number;
+declare var PADDLE_CHECKOUT_ANSWER_LIMIT: number;
+declare var PADDLE_CHECKOUT_TERMS_REFUSALS: readonly string[];
+declare function paddleMinorUnits(value: any, currency: any): number | null;
+declare function paddleCheckoutAnswerTarget(url: any): Readonly<{
+    environment: "production" | "sandbox";
+    checkoutId: string;
+    leg: string;
+}> | null;
+declare function projectPaddleCheckoutAnswer(text: any): string | null;
+declare function paddleCheckoutTerms(card: any, answers: any): Readonly<{
+    ok: false;
+    reason: any;
+}> | Readonly<{
+    ok: true;
+    checkoutId: string;
+    environment: "production" | "sandbox";
+    currency: any;
+    todayCents: number;
+    renews: boolean;
+    recurringCents: number | null;
+    trial: Readonly<{
+        renewalCents: number;
+        interval: any;
+        frequency: any;
+        startsAt: any;
+    }> | null;
+}>;
 declare var PADDLE_TOKENEX_PSP: string;
 declare var PADDLE_TOKENEX_CAPABILITY: string;
 declare var PADDLE_TOKENEX_OPERATION: string;
@@ -64,4 +92,4 @@ declare function paddleTokenexAnswerOutcome(status: any, text: any): {
     reason?: undefined;
     code?: undefined;
 };
-export { PADDLE_TOKENEX_CAPABILITY, PADDLE_TOKENEX_CARD_NETWORKS, PADDLE_TOKENEX_FACT_KEYS, PADDLE_TOKENEX_FIELDS, PADDLE_TOKENEX_OPERATION, PADDLE_TOKENEX_PSP, PADDLE_TOKENEX_REFUSAL_CODES, PADDLE_TOKENEX_SCHEME, encryptPaddleTokenexCard, isPaddleTokenexCardRequest, isPaddleTokenexCiphertext, isPaddleTokenexCiphertextUnderKey, paddleTokenexAnswerOutcome, paddleTokenexBodyVerdict, paddleVgsCardFactsAgree as paddleTokenexCardFactsAgree, paddleTokenexKeyUsable, paddleTokenexPayCarriesCard, paddleTokenexPayTarget, paddleTokenexRefusalCode, paddleTokenexRefusalMessage, paddleTokenexRequestRefusal, paddleTokenexStoredCardRefusal, paddleTokenexSubstitutionOf, paddleTokenexSubstitutionsRefusal, substitutePaddleTokenex };
+export { PADDLE_CHECKOUT_ANSWERS_MAX, PADDLE_CHECKOUT_ANSWER_LIMIT, PADDLE_CHECKOUT_TERMS_REFUSALS, PADDLE_TOKENEX_CAPABILITY, PADDLE_TOKENEX_CARD_NETWORKS, PADDLE_TOKENEX_FACT_KEYS, PADDLE_TOKENEX_FIELDS, PADDLE_TOKENEX_OPERATION, PADDLE_TOKENEX_PSP, PADDLE_TOKENEX_REFUSAL_CODES, PADDLE_TOKENEX_SCHEME, encryptPaddleTokenexCard, isPaddleTokenexCardRequest, isPaddleTokenexCiphertext, isPaddleTokenexCiphertextUnderKey, paddleCheckoutAnswerTarget, paddleCheckoutTerms, paddleMinorUnits, paddleTokenexAnswerOutcome, paddleTokenexBodyVerdict, paddleVgsCardFactsAgree as paddleTokenexCardFactsAgree, paddleTokenexKeyUsable, paddleTokenexPayCarriesCard, paddleTokenexPayTarget, paddleTokenexRefusalCode, paddleTokenexRefusalMessage, paddleTokenexRequestRefusal, paddleTokenexStoredCardRefusal, paddleTokenexSubstitutionOf, paddleTokenexSubstitutionsRefusal, projectPaddleCheckoutAnswer, substitutePaddleTokenex };

package/dist/paddle-tokenex.generated.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 // Generated from @agent-cards/payment-core. Do not edit.
-// artifact-sha256: 4289a22922e08251b579e9aadc396c8cff5d1a95b99ce35dd9a4618b43a33db5
+// artifact-sha256: cb62940ac92ca9f2a61b5168f362003d67998f12d045b18d8bd07ae352e0cb3e
 // src/sha256.js
 var K = /* @__PURE__ */ new Uint32Array([
     1116352408,
@@ -617,6 +617,155 @@ function swapMerchantHostedFields(body, spec, ciphertext = ADYEN_JWE) {
     }
     return JSON.stringify(out);
 }
+// src/paddle-checkout-terms.js
+var PADDLE_CHECKOUT_ANSWERS_MAX = 8;
+var PADDLE_CHECKOUT_ANSWER_LIMIT = 4096;
+var PADDLE_CHECKOUT_TERMS_REFUSALS = /* @__PURE__ */ Object.freeze([
+    "paddle_checkout_not_billing",
+    "paddle_checkout_answers_missing",
+    "paddle_checkout_answer_unreadable",
+    "paddle_checkout_total_unreadable",
+    "paddle_checkout_credit_unsupported"
+]);
+var ANSWER_URL = /^https:\/\/(sandbox-)?checkout-service\.paddle\.com\/transaction-checkout(?:\/([A-Za-z0-9_-]{1,64})(?:\/([a-z_]{1,32}))?)?\/?$/;
+var PAY_URL = /^https:\/\/(sandbox-)?checkout-service\.paddle\.com\/transaction-checkout\/([A-Za-z0-9_-]{1,64})\/pay$/;
+var NOT_ANSWERS = /* @__PURE__ */ new Set(["pay", "event"]);
+var METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PATCH", "PUT"]);
+var CURRENCY = /^[A-Z]{3}$/;
+var INTERVALS = /* @__PURE__ */ new Set(["day", "week", "month", "year"]);
+var INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})$/;
+var ZERO_DECIMAL = /* @__PURE__ */ new Set(["BIF", "CLP", "DJF", "GNF", "JPY", "KMF", "KRW", "MGA", "PYG", "RWF", "VND", "VUV", "XAF", "XOF", "XPF"]);
+var THREE_DECIMAL = /* @__PURE__ */ new Set(["BHD", "JOD", "KWD", "OMR", "TND"]);
+var record2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var refuse2 = (reason) => Object.freeze({ ok: false, reason });
+function paddleMinorUnits(value, currency) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || typeof currency !== "string" || !CURRENCY.test(currency))
+        return null;
+    const digits = ZERO_DECIMAL.has(currency) ? 0 : THREE_DECIMAL.has(currency) ? 3 : 2;
+    const match = /^(\d+)(?:\.(\d+))?$/.exec(String(value));
+    if (!match || (match[2] ?? "").length > digits)
+        return null;
+    const minor = Number(match[1] + (match[2] ?? "").padEnd(digits, "0"));
+    return Number.isSafeInteger(minor) ? minor : null;
+}
+function paddleCheckoutAnswerTarget(url) {
+    const match = typeof url === "string" ? ANSWER_URL.exec(url) : null;
+    if (!match || match[3] && NOT_ANSWERS.has(match[3]) || match[2] && NOT_ANSWERS.has(match[2]) && !match[3])
+        return null;
+    return Object.freeze({ environment: match[1] ? "sandbox" : "production", checkoutId: match[2] ?? null, leg: match[3] ?? null });
+}
+var pickNumbers = (value, keys) => {
+    if (!record2(value))
+        return void 0;
+    const out = {};
+    for (const key of keys)
+        if (typeof value[key] === "number")
+            out[key] = value[key];
+    return out;
+};
+var pickPhase = (phase) => record2(phase) ? {
+    type: typeof phase.type === "string" ? phase.type.slice(0, 32) : null,
+    billing_cycle: record2(phase.billing_cycle) ? { interval: typeof phase.billing_cycle.interval === "string" ? phase.billing_cycle.interval.slice(0, 16) : null, frequency: phase.billing_cycle.frequency } : null,
+    starts_at: typeof phase.starts_at === "string" ? phase.starts_at.slice(0, 40) : null,
+    ends_at: typeof phase.ends_at === "string" ? phase.ends_at.slice(0, 40) : null,
+    total: phase.total,
+    currency_code: typeof phase.currency_code === "string" ? phase.currency_code.slice(0, 3) : null
+} : null;
+function projectPaddleCheckoutAnswer(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const data = record2(value) ? value.data : null;
+    if (!record2(data) || typeof data.id !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(data.id))
+        return null;
+    const projected = {
+        id: data.id,
+        environment: typeof data.environment === "string" ? data.environment.slice(0, 16) : null,
+        currency_code: typeof data.currency_code === "string" ? data.currency_code.slice(0, 3) : null,
+        totals: pickNumbers(data.totals, ["total", "balance", "credit"]) ?? null,
+        recurring_totals: pickNumbers(data.recurring_totals, ["total"]) ?? null,
+        includes_negative_option: typeof data.includes_negative_option === "boolean" ? data.includes_negative_option : null,
+        payment_breakdown: Array.isArray(data.payment_breakdown) ? data.payment_breakdown.slice(0, 8).map(pickPhase) : null
+    };
+    return JSON.stringify({ data: projected });
+}
+function paddleCheckoutTerms(card, answers) {
+    const pay = record2(card) && typeof card.url === "string" ? PAY_URL.exec(card.url) : null;
+    if (!pay)
+        return refuse2("paddle_checkout_not_billing");
+    const environment = pay[1] ? "sandbox" : "production";
+    const checkoutId = pay[2];
+    const pausedAt = record2(card) && Number.isFinite(card.pausedAt) ? card.pausedAt : Infinity;
+    let newest = null;
+    for (const answer of Array.isArray(answers) ? answers.slice(-PADDLE_CHECKOUT_ANSWERS_MAX) : []) {
+        if (!record2(answer) || typeof answer.method !== "string" || !METHODS.has(answer.method.toUpperCase()))
+            continue;
+        const target = paddleCheckoutAnswerTarget(answer.url);
+        if (!target || target.environment !== environment || target.checkoutId !== null && target.checkoutId !== checkoutId)
+            continue;
+        if (!Number.isFinite(answer.completedAt) || answer.completedAt > pausedAt)
+            continue;
+        const readable = Number.isInteger(answer.status) && answer.status >= 200 && answer.status < 300 && typeof answer.body === "string" && answer.body.length <= PADDLE_CHECKOUT_ANSWER_LIMIT;
+        const projected = readable ? projectPaddleCheckoutAnswer(answer.body) : null;
+        const data2 = projected ? JSON.parse(projected).data : null;
+        if (target.checkoutId === null && !(data2 && data2.id === checkoutId))
+            continue;
+        if (newest && answer.completedAt < newest.completedAt)
+            continue;
+        newest = { completedAt: answer.completedAt, data: data2 && data2.id === checkoutId && data2.environment === environment ? data2 : null };
+    }
+    if (!newest)
+        return refuse2("paddle_checkout_answers_missing");
+    const data = newest.data;
+    if (!data || typeof data.currency_code !== "string" || !CURRENCY.test(data.currency_code) || !record2(data.totals))
+        return refuse2("paddle_checkout_answer_unreadable");
+    const currency = data.currency_code;
+    const todayCents = paddleMinorUnits(data.totals.total, currency);
+    const balanceCents = paddleMinorUnits(data.totals.balance, currency);
+    if (todayCents === null || balanceCents === null)
+        return refuse2("paddle_checkout_total_unreadable");
+    if (balanceCents !== todayCents || data.totals.credit !== void 0 && data.totals.credit !== 0)
+        return refuse2("paddle_checkout_credit_unsupported");
+    const phases = Array.isArray(data.payment_breakdown) ? data.payment_breakdown : [];
+    const oneTime = data.recurring_totals === null && data.includes_negative_option === false && phases.every((phase) => record2(phase) && phase.type === "due_now" && phase.billing_cycle === null);
+    const recurringCents = record2(data.recurring_totals) ? paddleMinorUnits(data.recurring_totals.total, currency) : null;
+    return Object.freeze({
+        ok: true,
+        checkoutId,
+        environment,
+        currency,
+        todayCents,
+        renews: !oneTime,
+        recurringCents: oneTime ? null : recurringCents,
+        trial: oneTime ? null : freeTrialOf(phases, currency, todayCents, recurringCents)
+    });
+}
+function freeTrialOf(phases, currency, todayCents, recurringCents) {
+    if (phases.length !== 2 || todayCents !== 0)
+        return null;
+    const [trial, renewal] = phases;
+    if (!record2(trial) || !record2(renewal) || trial.type !== "free_trial" || renewal.type !== "normal")
+        return null;
+    if (trial.currency_code !== currency || renewal.currency_code !== currency)
+        return null;
+    if (paddleMinorUnits(trial.total, currency) !== 0)
+        return null;
+    const renewalCents = paddleMinorUnits(renewal.total, currency);
+    if (renewalCents === null || renewalCents <= 0 || renewalCents !== recurringCents)
+        return null;
+    const cycle = renewal.billing_cycle;
+    if (!record2(cycle) || !INTERVALS.has(cycle.interval) || !Number.isInteger(cycle.frequency) || cycle.frequency < 1 || cycle.frequency > 999)
+        return null;
+    if (typeof renewal.starts_at !== "string" || !INSTANT.test(renewal.starts_at) || trial.ends_at !== renewal.starts_at)
+        return null;
+    if (!Number.isFinite(Date.parse(renewal.starts_at)))
+        return null;
+    return Object.freeze({ renewalCents, interval: cycle.interval, frequency: cycle.frequency, startsAt: renewal.starts_at });
+}
 // src/paddle-tokenex.js
 var PADDLE_TOKENEX_PSP = "paddle_tokenex";
 var PADDLE_TOKENEX_CAPABILITY = "paddle_tokenex_pay";
@@ -631,17 +780,17 @@ var PADDLE_TOKENEX_REFUSAL_CODES = /* @__PURE__ */ Object.freeze([
     "paddle_tokenex_card_mismatch",
     "paddle_tokenex_key_unavailable"
 ]);
-var record2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var record3 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 var sameKeys = (value, keys) => {
     const own = Object.keys(value);
     return own.length === keys.length && own.every((key, at) => key === keys[at]);
 };
-var refuse2 = (code) => Object.freeze({ verdict: "refuse", code });
+var refuse3 = (code) => Object.freeze({ verdict: "refuse", code });
 var CARD = /* @__PURE__ */ Object.freeze({ verdict: "card" });
 var CONTINUE = /* @__PURE__ */ Object.freeze({ verdict: "continue" });
-var PAY_URL = /^https:\/\/(sandbox-)?checkout-service\.paddle\.com\/(checkout|transaction-checkout)\/[A-Za-z0-9_-]{1,64}\/pay$/;
+var PAY_URL2 = /^https:\/\/(sandbox-)?checkout-service\.paddle\.com\/(checkout|transaction-checkout)\/[A-Za-z0-9_-]{1,64}\/pay$/;
 function paddleTokenexPayTarget(url) {
-    const match = typeof url === "string" ? PAY_URL.exec(url) : null;
+    const match = typeof url === "string" ? PAY_URL2.exec(url) : null;
     return match ? Object.freeze({ environment: match[1] ? "sandbox" : "production", line: match[2] === "checkout" ? "classic" : "billing" }) : null;
 }
 function paddleTokenexPayCarriesCard(body) {
@@ -706,29 +855,29 @@ function readPay(body, line, environment) {
     let value;
     try {
         value = JSON.parse(body);
-        if (!record2(value) || JSON.stringify(value) !== body)
+        if (!record3(value) || JSON.stringify(value) !== body)
             return null;
     }
     catch {
         return null;
     }
     const data = value.data;
-    if (!sameKeys(value, ["data"]) || !record2(data) || !(sameKeys(data, PAY_DATA_KEYS) || sameKeys(data, [...PAY_DATA_KEYS, "checkout"])) || data.payment_method_type !== (line === "classic" ? "CARD" : "card"))
+    if (!sameKeys(value, ["data"]) || !record3(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 && !(record2(data.checkout) && sameKeys(data.checkout, ["frontend_host"]) && typeof data.checkout.frontend_host === "string" && FRONTEND_HOST.test(data.checkout.frontend_host)))
+    if (data.checkout !== void 0 && !(record3(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 = record2(method) && sameKeys(method, ["card"]) ? method.card : null;
-    if (!record2(card) || !(sameKeys(card, PAY_CARD_KEYS) || sameKeys(card, [...PAY_CARD_KEYS, "session_tracking"])))
+    const card = record3(method) && sameKeys(method, ["card"]) ? method.card : null;
+    if (!record3(card) || !(sameKeys(card, PAY_CARD_KEYS) || sameKeys(card, [...PAY_CARD_KEYS, "session_tracking"])))
         return null;
     const metadata = card.metadata;
-    if (!record2(metadata) || !sameKeys(metadata, METADATA_KEYS2) || 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_SIX2.test(metadata.card_first_six) || typeof metadata.card_last_four !== "string" || !LAST_FOUR2.test(metadata.card_last_four) || !expiryMonth2(metadata.expiry_month) || !expiryYear2(metadata.expiry_year) || !FRAME_BRANDS.includes(metadata.card_brand))
+    if (!record3(metadata) || !sameKeys(metadata, METADATA_KEYS2) || 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_SIX2.test(metadata.card_first_six) || typeof metadata.card_last_four !== "string" || !LAST_FOUR2.test(metadata.card_last_four) || !expiryMonth2(metadata.expiry_month) || !expiryYear2(metadata.expiry_year) || !FRAME_BRANDS.includes(metadata.card_brand))
         return null;
     const details = card.three_d_s;
-    if (!record2(details) || !sameKeys(details, ["browser_info"]) || typeof details.browser_info !== "string" || !BROWSER_INFO.test(details.browser_info))
+    if (!record3(details) || !sameKeys(details, ["browser_info"]) || typeof details.browser_info !== "string" || !BROWSER_INFO.test(details.browser_info))
         return null;
     const tokenex = card.tokenex_card;
-    if (!record2(tokenex) || !sameKeys(tokenex, CARD_KEYS))
+    if (!record3(tokenex) || !sameKeys(tokenex, CARD_KEYS))
         return null;
     for (const name of CARD_KEYS) {
         const blob = tokenex[name];
@@ -743,14 +892,14 @@ function readPay(body, line, environment) {
         return null;
     if (card.session_tracking !== void 0) {
         const tracking = card.session_tracking;
-        const radar = record2(tracking) && sameKeys(tracking, ["stripe_radar"]) ? tracking.stripe_radar : null;
-        if (!record2(radar) || !radarKeys(radar) || typeof radar.token !== "string" || !RADAR_TOKEN.test(radar.token) || typeof radar.country_code !== "string" || !COUNTRY_CODE.test(radar.country_code))
+        const radar = record3(tracking) && sameKeys(tracking, ["stripe_radar"]) ? tracking.stripe_radar : null;
+        if (!record3(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 paddleTokenexRequestRefusal(request, environment) {
-    if (!record2(request) || typeof request.method !== "string" || request.method.toUpperCase() !== "POST")
+    if (!record3(request) || typeof request.method !== "string" || request.method.toUpperCase() !== "POST")
         return "paddle_tokenex_pay_unsupported";
     const target = paddleTokenexPayTarget(request.url);
     if (!target || environment !== void 0 && target.environment !== environment)
@@ -758,7 +907,7 @@ function paddleTokenexRequestRefusal(request, environment) {
     return readPay(request.body, target.line, environment) === null ? "paddle_tokenex_pay_unsupported" : null;
 }
 function isPaddleTokenexCardRequest(request) {
-    return record2(request) && paddleTokenexPayCarriesCard(request.body) && paddleTokenexRequestRefusal(request) === null;
+    return record3(request) && paddleTokenexPayCarriesCard(request.body) && paddleTokenexRequestRefusal(request) === null;
 }
 function paddleTokenexBodyVerdict(body, line) {
     if (!paddleTokenexPayCarriesCard(body))
@@ -767,7 +916,7 @@ function paddleTokenexBodyVerdict(body, line) {
         if (readPay(body, candidate) !== null)
             return CARD;
     }
-    return refuse2("paddle_tokenex_pay_unsupported");
+    return refuse3("paddle_tokenex_pay_unsupported");
 }
 var REFUSAL_MESSAGES = /* @__PURE__ */ Object.freeze({
     paddle_tokenex_pay_unsupported: "Refusing to pay: this is not the card payment Paddle's checkout sends. Nothing was sent.",
@@ -824,7 +973,7 @@ function base64(bytes) {
     return btoa(binary);
 }
 function paddleTokenexSubstitutionOf(value, environment) {
-    if (!record2(value))
+    if (!record3(value))
         return null;
     const keys = Object.keys(value);
     const all = [...PADDLE_TOKENEX_FIELDS, ...PADDLE_TOKENEX_FACT_KEYS];
@@ -881,7 +1030,7 @@ function substitutePaddleTokenex(url, body, substitution) {
     return out;
 }
 function paddleTokenexKeyUsable(authorization) {
-    if (!record2(authorization) || !record2(authorization.cse))
+    if (!record3(authorization) || !record3(authorization.cse))
         return false;
     const cse = authorization.cse;
     if (cse.psp !== PADDLE_TOKENEX_PSP || cse.scheme !== PADDLE_TOKENEX_SCHEME)
@@ -895,7 +1044,7 @@ function paddleTokenexKeyUsable(authorization) {
 }
 function paddleTokenexSubstitutionsRefusal(template, substitution) {
     const refuseWith = (message) => ({ code: "invalid_substitutions", message });
-    if (!record2(template))
+    if (!record3(template))
         return refuseWith("This authorization is not a Paddle TokenEx /pay.");
     const target = paddleTokenexPayTarget(template.url);
     if (!target)
@@ -920,7 +1069,7 @@ function readAnswer(text) {
         return null;
     try {
         const value = JSON.parse(text);
-        return record2(value) ? value : null;
+        return record3(value) ? value : null;
     }
     catch {
         return null;
@@ -931,12 +1080,12 @@ function paddleTokenexRefusalCode(text) {
     const answer = readAnswer(text);
     if (!answer)
         return null;
-    const first = Array.isArray(answer.errors) && record2(answer.errors[0]) ? answer.errors[0] : null;
+    const first = Array.isArray(answer.errors) && record3(answer.errors[0]) ? answer.errors[0] : null;
     return boundedCode(first && first.error_code) ?? boundedCode(first && first.code) ?? boundedCode(answer.error_code) ?? boundedCode(answer.code);
 }
 function needs3ds(answer) {
-    const action = record2(answer) && record2(answer.data) ? answer.data.required_action : record2(answer) ? answer.required_action : null;
-    return record2(action) && typeof action.type === "string" && /(^|_)card$/.test(action.type);
+    const action = record3(answer) && record3(answer.data) ? answer.data.required_action : record3(answer) ? answer.required_action : null;
+    return record3(action) && typeof action.type === "string" && /(^|_)card$/.test(action.type);
 }
 function paddleTokenexAnswerOutcome(status, text) {
     if (!Number.isInteger(status))
@@ -952,4 +1101,4 @@ function paddleTokenexAnswerOutcome(status, text) {
         return { outcome: "unknown", reason: "paddle_tokenex_unconfirmed" };
     return needs3ds(answer) ? { outcome: "challenge" } : { outcome: "approved" };
 }
-export { PADDLE_TOKENEX_CAPABILITY, PADDLE_TOKENEX_CARD_NETWORKS, PADDLE_TOKENEX_FACT_KEYS, PADDLE_TOKENEX_FIELDS, PADDLE_TOKENEX_OPERATION, PADDLE_TOKENEX_PSP, PADDLE_TOKENEX_REFUSAL_CODES, PADDLE_TOKENEX_SCHEME, encryptPaddleTokenexCard, isPaddleTokenexCardRequest, isPaddleTokenexCiphertext, isPaddleTokenexCiphertextUnderKey, paddleTokenexAnswerOutcome, paddleTokenexBodyVerdict, paddleVgsCardFactsAgree as paddleTokenexCardFactsAgree, paddleTokenexKeyUsable, paddleTokenexPayCarriesCard, paddleTokenexPayTarget, paddleTokenexRefusalCode, paddleTokenexRefusalMessage, paddleTokenexRequestRefusal, paddleTokenexStoredCardRefusal, paddleTokenexSubstitutionOf, paddleTokenexSubstitutionsRefusal, substitutePaddleTokenex };
+export { PADDLE_CHECKOUT_ANSWERS_MAX, PADDLE_CHECKOUT_ANSWER_LIMIT, PADDLE_CHECKOUT_TERMS_REFUSALS, PADDLE_TOKENEX_CAPABILITY, PADDLE_TOKENEX_CARD_NETWORKS, PADDLE_TOKENEX_FACT_KEYS, PADDLE_TOKENEX_FIELDS, PADDLE_TOKENEX_OPERATION, PADDLE_TOKENEX_PSP, PADDLE_TOKENEX_REFUSAL_CODES, PADDLE_TOKENEX_SCHEME, encryptPaddleTokenexCard, isPaddleTokenexCardRequest, isPaddleTokenexCiphertext, isPaddleTokenexCiphertextUnderKey, paddleCheckoutAnswerTarget, paddleCheckoutTerms, paddleMinorUnits, paddleTokenexAnswerOutcome, paddleTokenexBodyVerdict, paddleVgsCardFactsAgree as paddleTokenexCardFactsAgree, paddleTokenexKeyUsable, paddleTokenexPayCarriesCard, paddleTokenexPayTarget, paddleTokenexRefusalCode, paddleTokenexRefusalMessage, paddleTokenexRequestRefusal, paddleTokenexStoredCardRefusal, paddleTokenexSubstitutionOf, paddleTokenexSubstitutionsRefusal, projectPaddleCheckoutAnswer, substitutePaddleTokenex };

package/dist/prepared-processor.d.ts

@@ -32,8 +32,13 @@
  * hipay: prepared only. The merchant's page gives HiPay's hosted fields 20 seconds after Pay, too soon for an
  * approval after Pay. Its environments are its two vault hosts: secure2-vault (production) and
  * stage-secure2-vault (sandbox).
+ *
+ * openpay_bbva: prepared only. openpay.js abandons its token create 40 seconds after Pay, too soon for an
+ * approval after Pay. Its environments are its API hosts: api.openpay.<mx|co|pe> (production) and
+ * sandbox-api.openpay.<mx|co|pe> (sandbox). The token URL names the merchant in its path, so no URL is
+ * prepared in advance: the claim binds the request by its host's environment and its shape, as ACI's.
  */
-export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago' | 'recurly' | 'spreedly' | 'adyen' | 'checkout_com' | 'paysafe' | 'fiserv' | 'cybersource_flex' | 'aci' | 'creditguard' | 'worldpay_eprotect' | 'amadeus_checkout' | 'verifone' | 'cybersource_secure_acceptance' | 'paddle_vgs' | 'wix_payments' | 'paygent' | 'hipay';
+export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago' | 'recurly' | 'spreedly' | 'adyen' | 'checkout_com' | 'paysafe' | 'fiserv' | 'cybersource_flex' | 'aci' | 'creditguard' | 'worldpay_eprotect' | 'amadeus_checkout' | 'verifone' | 'cybersource_secure_acceptance' | 'paddle_vgs' | 'wix_payments' | 'paygent' | 'hipay' | 'openpay_bbva';
 export type PreparationEnvironment = 'production' | 'sandbox' | 'shared';
 /**
  * How the approved card reaches the processor: the device's own request (token), or
@@ -71,7 +76,8 @@ export declare function preparedApprovalAnswersRetry(psp: string): boolean;
  * profile pins. CyberSource Secure Acceptance's are separate hosts too: secureacceptance is
  * live, testsecureacceptance is test. So are Paddle VGS's two card URLs: vault is live,
  * sandbox-vault is test. So are Paygent's two token hosts: token is live, sandbox is test. So are
- * HiPay's two vault hosts: secure2-vault is live, stage-secure2-vault is test.
+ * HiPay's two vault hosts: secure2-vault is live, stage-secure2-vault is test. So are Openpay's API
+ * hosts: api.openpay.<mx|co|pe> is live, sandbox-api.openpay.<mx|co|pe> is test.
  */
 export declare function validPreparationEnvironment(psp: string, environment: string): boolean;
 /**
@@ -83,8 +89,10 @@ export declare function validPreparationEnvironment(psp: string, environment: st
 export declare function aciPreparationUrl(environment: PreparationEnvironment): string;
 /**
  * A processor whose card request names an id the merchant mints only at Pay time (ACI's checkout
- * id), so no URL can be prepared in advance: whether the adapters can intercept it is asked of the
- * registry (VaultClient.recognizesProcessor), not of the prepared endpoint.
+ * id), or the merchant's own id (Openpay's token URL carries the merchant id in its path and the
+ * country in its host), so no URL can be prepared in advance: whether the adapters can intercept it
+ * is asked of the registry (VaultClient.recognizesProcessor), not of the prepared endpoint, which
+ * only names the preparation.
  */
 export declare function preparationBindsByShape(psp: string): boolean;
 /**