@agent-cards/sdk 0.21.0 → 0.23.0

package/dist/datatrans.generated.js

@@ -0,0 +1,426 @@
+// @ts-nocheck
+// Generated from @agent-cards/payment-core. Do not edit.
+// artifact-sha256: 0179250ba6f44c33967a08dc4ce3a891d8b73f0f7eb60e9cab34f801dc2a4c57
+// src/datatrans.js
+var DATATRANS_HOSTS = Object.freeze(["pay.datatrans.com", "pay.sandbox.datatrans.com"]);
+var DATATRANS_TOKENIZE_PATH = "/upp/payment/SecureFields/paymentField";
+var DATATRANS_REFUSAL_REASONS = Object.freeze(["unsupported", "card_on_file", "brand_mismatch", "unregistered_merchant"]);
+var DATATRANS_INVALID_REQUEST = "invalid_datatrans_request";
+var DATATRANS_CARD_ON_FILE_REFUSED = "datatrans_card_on_file_refused";
+var DATATRANS_REGISTRATION_POLICIES = Object.freeze(["refuse", "disclose", "agentcard_single_use"]);
+var DATATRANS_REGISTRATION_POLICY = "refuse";
+var DATATRANS_REVIEWED_MERCHANT_IDS = Object.freeze({
+    "pay.datatrans.com": Object.freeze([]),
+    "pay.sandbox.datatrans.com": Object.freeze(["1110022968", "1100007006"])
+});
+var DATATRANS_PAYMENT_METHODS = Object.freeze(["VIS", "ECA", "AMX", "DIN", "DIS", "JCB", "CUP", "MAU", "UAP", "DNK"]);
+var DATATRANS_TEST_PANS = Object.freeze([
+    "4242424242424242",
+    "4900000000000086",
+    "4900000000000003",
+    "5404000000000001",
+    "5200000000000007",
+    "5200000000000080",
+    "375811111111115",
+    "375000000000007",
+    "375811111111123",
+    "36168002586009",
+    "36167719110012",
+    "6011000000000004",
+    "3569990010030442",
+    "3569990010030400",
+    "6362970000457013",
+    "3841000000000007",
+    "6200104444444447",
+    "6210946888060008",
+    "6759000000000018",
+    "6759000000000026",
+    "4000001000000034",
+    "4000001000000018",
+    "4000001000000042",
+    "4000001000000026",
+    "5100001000000022",
+    "5100001000000048",
+    "5100001000000014",
+    "5100001000000030",
+    "340000100000024",
+    "340000100000040",
+    "340000100000016",
+    "340000100000032",
+    "36000010000022",
+    "3550998599961037"
+]);
+var UNSUPPORTED_REFUSAL = "Refusing to pay: unsupported Datatrans card request.";
+var CARD_ON_FILE_REFUSAL = "Refusing to pay: this Datatrans payment would let the merchant keep your card on file, which needs your consent first. Nothing was sent.";
+var BRAND_MISMATCH_REFUSAL = "Refusing to pay: this Datatrans payment names a card brand that is not your card's. Nothing was sent.";
+var UNREGISTERED_MERCHANT_REFUSAL = "Refusing to pay: this Datatrans payment goes to a merchant account Agentcard has not reviewed. Nothing was sent.";
+var FILL_REFUSAL = "Could not fill the card fields for Datatrans. Nothing was sent.";
+var BODY_LIMIT = 8192;
+var RESPONSE_LIMIT = 4096;
+var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var owns = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+var exact = (pattern, value) => typeof value === "string" && pattern.exec(value)?.[0] === value;
+var text = (value, max) => typeof value === "string" && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+var digits = (value, min, max) => typeof value === "string" && value.length >= min && value.length <= max && !/[^0-9]/.test(value);
+var panLike = (value) => (value.match(/\p{Nd}/gu) ?? []).length >= 12;
+var plain = (value, max) => text(value, max) && !panLike(value);
+function encodeDatatransFormValue(value) {
+    return encodeURIComponent(String(value)).replace(/%20/g, "+");
+}
+function decodeFormComponent(raw) {
+    try {
+        return decodeURIComponent(raw.replace(/\+/g, " "));
+    }
+    catch {
+        return null;
+    }
+}
+function parseDatatransForm(body) {
+    if (typeof body !== "string" || body === "" || body.length > BODY_LIMIT)
+        return null;
+    const pairs = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const chunk of body.split("&")) {
+        const eq = chunk.indexOf("=");
+        if (eq < 1)
+            return null;
+        const rawKey = chunk.slice(0, eq), raw = chunk.slice(eq + 1);
+        const key = decodeFormComponent(rawKey), value = decodeFormComponent(raw);
+        if (key === null || value === null || seen.has(key))
+            return null;
+        try {
+            if (encodeDatatransFormValue(key) !== rawKey || encodeDatatransFormValue(value) !== raw)
+                return null;
+        }
+        catch {
+            return null;
+        }
+        seen.add(key);
+        pairs.push({ key, value, rawKey, raw });
+    }
+    return pairs;
+}
+function serializeDatatransForm(pairs) {
+    return pairs.map(({ key, value }) => `${encodeDatatransFormValue(key)}=${encodeDatatransFormValue(value)}`).join("&");
+}
+function isDatatransTokenizeUrl(url, method = "POST") {
+    if (method !== "POST" || typeof url !== "string" || url.length > 256 || url.includes("?") || url.includes("#"))
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    return parsed.href === url && parsed.protocol === "https:" && !parsed.port && !parsed.username && !parsed.password && DATATRANS_HOSTS.includes(parsed.hostname) && parsed.pathname === DATATRANS_TOKENIZE_PATH;
+}
+function onPaymentFieldPath(url) {
+    if (typeof url !== "string" || url.length > 2048)
+        return false;
+    try {
+        const parsed = new URL(url);
+        return DATATRANS_HOSTS.includes(parsed.hostname.replace(/\.$/, "")) && parsed.pathname.toLowerCase() === DATATRANS_TOKENIZE_PATH.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+var KEYS = /* @__PURE__ */ new Set([
+    "mode",
+    "formId",
+    "cardNumber",
+    "cvv",
+    "iban",
+    "accountNumber",
+    "branchCode",
+    "paymentMethod",
+    "countryCode",
+    "merchantId",
+    "expy",
+    "expm",
+    "email",
+    "phoneNumber",
+    "usage",
+    "3D",
+    "browserUserAgent",
+    "browserJavaEnabled",
+    "browserLanguage",
+    "browserColorDepth",
+    "browserScreenHeight",
+    "browserScreenWidth",
+    "browserTZ"
+]);
+var REQUIRED = ["mode", "formId", "cardNumber", "paymentMethod", "merchantId", "expy", "expm"];
+var EMPTY_ONLY = /* @__PURE__ */ new Set(["iban", "accountNumber", "branchCode", "countryCode", "3D"]);
+var RULES = {
+    mode: (value) => value === "TOKENIZE",
+    formId: (value) => exact(/^[0-9]{18}$/, value),
+    cardNumber: (value) => digits(value, 12, 19),
+    cvv: (value) => value === "" || digits(value, 3, 4),
+    paymentMethod: (value) => DATATRANS_PAYMENT_METHODS.includes(value),
+    merchantId: (value) => exact(/^[0-9]{10}$/, value),
+    expm: (value) => exact(/^(?:0?[1-9]|1[0-2])$/, value),
+    expy: (value) => exact(/^(?:[0-9]{2}|20[0-9]{2})$/, value),
+    usage: (value) => value === "" || value === "SIMPLE" || value === "REGISTRATION",
+    email: (value) => value === "" || text(value, 254) && exact(/^[^\s@]{1,64}@[^\s@]{1,189}$/, value),
+    phoneNumber: (value) => value === "" || exact(/^\+?[0-9 ()./-]{1,32}$/, value),
+    browserUserAgent: (value) => value !== "" && text(value, 1024),
+    browserJavaEnabled: (value) => value === "true" || value === "false",
+    browserLanguage: (value) => value === "" || exact(/^[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8}){0,4}$/, value),
+    browserColorDepth: (value) => exact(/^[0-9]{1,3}$/, value),
+    browserScreenHeight: (value) => exact(/^[0-9]{1,5}$/, value),
+    browserScreenWidth: (value) => exact(/^[0-9]{1,5}$/, value),
+    browserTZ: (value) => exact(/^-?[0-9]{1,4}$/, value)
+};
+function judgeBody(body) {
+    const pairs = parseDatatransForm(body);
+    if (!pairs)
+        return null;
+    const fields = new Map(pairs.map(({ key, value }) => [key, value]));
+    for (const [key, value] of fields) {
+        if (!KEYS.has(key))
+            return null;
+        if (EMPTY_ONLY.has(key) ? value !== "" : !RULES[key](value))
+            return null;
+    }
+    if (!REQUIRED.every((key) => fields.has(key)))
+        return null;
+    return { pairs, fields, usage: fields.get("usage") ?? "" };
+}
+function datatransRegistrationRefusal(usage, card, policy = DATATRANS_REGISTRATION_POLICY) {
+    if (usage !== "REGISTRATION")
+        return null;
+    if (policy !== "disclose" && policy !== "agentcard_single_use")
+        return "card_on_file";
+    if (card === void 0)
+        return null;
+    if (!record(card) || card.cardOnFileConsent !== true)
+        return "card_on_file";
+    return policy === "agentcard_single_use" && card.agentcardSingleUse !== true ? "card_on_file" : null;
+}
+function datatransCardOnFileDisclosure(body, policy = DATATRANS_REGISTRATION_POLICY) {
+    const judged = judgeBody(body);
+    return judged !== null && judged.usage === "REGISTRATION" && (policy === "disclose" || policy === "agentcard_single_use");
+}
+function datatransBodyRefusal(body, card, policy = DATATRANS_REGISTRATION_POLICY) {
+    const judged = judgeBody(body);
+    if (!judged)
+        return "unsupported";
+    return datatransRegistrationRefusal(judged.usage, card, policy);
+}
+function datatransMerchantId(body) {
+    const judged = judgeBody(body);
+    return judged ? judged.fields.get("merchantId") : null;
+}
+function carriesCard(body) {
+    if (typeof body !== "string" || body === "")
+        return false;
+    for (const chunk of body.split("&")) {
+        const eq = chunk.indexOf("=");
+        if (eq <= 0 || eq === chunk.length - 1)
+            continue;
+        if (decodeFormComponent(chunk.slice(0, eq)) === "cardNumber")
+            return true;
+    }
+    return false;
+}
+var CONTENT_TYPE = /^application\/x-www-form-urlencoded(?:;\s*charset=utf-8)?$/i;
+function headersRefusal(headers) {
+    if (!record(headers))
+        return "unsupported";
+    const folded = /* @__PURE__ */ new Map();
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (folded.has(lower) || typeof value !== "string")
+            return "unsupported";
+        folded.set(lower, value);
+    }
+    return exact(CONTENT_TYPE, folded.get("content-type")) ? null : "unsupported";
+}
+function classifyDatatransRequest(url, method, body, headers, policy = DATATRANS_REGISTRATION_POLICY) {
+    if (method !== "POST" || !onPaymentFieldPath(url) || !carriesCard(body))
+        return null;
+    if (!isDatatransTokenizeUrl(url))
+        return "unsupported";
+    return headersRefusal(headers) ?? datatransBodyRefusal(body, void 0, policy) ?? "card";
+}
+function datatransTokenizeRefusal(request, card, policy = DATATRANS_REGISTRATION_POLICY) {
+    if (!record(request) || request.method !== "POST" || !isDatatransTokenizeUrl(request.url))
+        return "unsupported";
+    return headersRefusal(request.headers) ?? datatransBodyRefusal(request.body, card, policy);
+}
+function isDatatransTokenizeRequest(request, card) {
+    return datatransTokenizeRefusal(request, card) === null;
+}
+function datatransMerchantRefusal(url, body, merchants = DATATRANS_REVIEWED_MERCHANT_IDS) {
+    const merchantId = datatransMerchantId(body);
+    let host = "";
+    try {
+        host = new URL(url).hostname;
+    }
+    catch {
+        return "unregistered_merchant";
+    }
+    const listed = record(merchants) && owns(merchants, host) && Array.isArray(merchants[host]) ? merchants[host] : [];
+    return merchantId !== null && listed.includes(merchantId) ? null : "unregistered_merchant";
+}
+function datatransDeviceRefusal(request, card, policy = DATATRANS_REGISTRATION_POLICY, merchants = DATATRANS_REVIEWED_MERCHANT_IDS) {
+    const refusal = datatransTokenizeRefusal(request, card, policy);
+    if (refusal)
+        return refusal;
+    if (record(card) && digits(card.number, 12, 19) && datatransBrandRefusal(request.body, card) !== null)
+        return "brand_mismatch";
+    return datatransMerchantRefusal(request.url, request.body, merchants);
+}
+function datatransRefusalMessage(reason) {
+    if (reason === "card_on_file")
+        return CARD_ON_FILE_REFUSAL;
+    if (reason === "brand_mismatch")
+        return BRAND_MISMATCH_REFUSAL;
+    if (reason === "unregistered_merchant")
+        return UNREGISTERED_MERCHANT_REFUSAL;
+    return UNSUPPORTED_REFUSAL;
+}
+function datatransCardBrand(number) {
+    if (!digits(number, 12, 19))
+        return null;
+    const two = Number(number.slice(0, 2));
+    const four = Number(number.slice(0, 4));
+    if (number[0] === "4")
+        return "VIS";
+    if (two >= 51 && two <= 55 || four >= 2221 && four <= 2720)
+        return "ECA";
+    if (two === 34 || two === 37)
+        return "AMX";
+    return null;
+}
+function datatransBrandRefusal(body, card) {
+    const judged = judgeBody(body);
+    if (!judged)
+        return "unsupported";
+    const brand = datatransCardBrand(card && card.number);
+    return brand !== null && brand === judged.fields.get("paymentMethod") ? null : "brand_mismatch";
+}
+function injectDatatransCard(body, card, policy = DATATRANS_REGISTRATION_POLICY) {
+    const judged = judgeBody(body);
+    if (!judged)
+        throw new Error(UNSUPPORTED_REFUSAL);
+    if (datatransRegistrationRefusal(judged.usage, card ?? null, policy) !== null)
+        throw new Error(CARD_ON_FILE_REFUSAL);
+    const month = card && (Number.isInteger(card.month) || digits(card.month, 1, 2)) ? Number(card.month) : NaN;
+    const year = card && (Number.isInteger(card.year) || digits(card.year, 2, 4)) ? Number(card.year) : NaN;
+    if (!card || !digits(card.number, 12, 19) || !(month >= 1 && month <= 12) || !(year >= 0 && year <= 99 || year >= 2e3 && year <= 2099)) {
+        throw new Error(FILL_REFUSAL);
+    }
+    if (datatransBrandRefusal(body, card) !== null)
+        throw new Error(BRAND_MISMATCH_REFUSAL);
+    const fields = judged.fields;
+    if (!fields.get("cvv") || !digits(card.cvc, 3, 4))
+        throw new Error(FILL_REFUSAL);
+    const yy = String(year % 100).padStart(2, "0");
+    const values = {
+        cardNumber: card.number,
+        cvv: card.cvc,
+        expm: fields.get("expm").length === 2 ? String(month).padStart(2, "0") : String(month),
+        expy: fields.get("expy").length === 4 ? `20${yy}` : yy
+    };
+    const written = judged.pairs.map((pair) => owns(values, pair.key) ? `${pair.rawKey}=${encodeDatatransFormValue(values[pair.key])}` : `${pair.rawKey}=${pair.raw}`);
+    return { body: written.join("&"), where: ["cardNumber", "cvv", "expm", "expy"] };
+}
+var TRANSACTION_ID = /^[0-9]{18}$/;
+var CARD_WORD = /^[A-Za-z][A-Za-z _-]{0,31}$/;
+var COUNTRY = /^[A-Z]{2}$/;
+var CARD_INFO_KEYS = ["brand", "type", "usage", "country", "issuer", "coBrand"];
+var UNFOLLOWED_KEYS = ["tds2EnrollmentResult", "redirect", "dcc", "mcp"];
+var ERROR_CODES = [
+    [/^Invalid merchantId$/, "invalid_merchant_id"],
+    [/^Invalid merchant setup\b/, "invalid_merchant_setup"],
+    [/^Invalid field$/, "invalid_field"],
+    [/^Field .{1,64} not allowed for (?:alias version|mode) /, "field_not_allowed"],
+    [/^Invalid session$/, "invalid_session"],
+    [/^Too many requests$/, "too_many_requests"]
+];
+function readAnswer(body) {
+    if (typeof body !== "string" || body === "" || body.length > RESPONSE_LIMIT)
+        return null;
+    try {
+        const value = JSON.parse(body);
+        return record(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+var optionalText = (value, pattern) => value === null || exact(pattern, value);
+function rebuildCardInfo(info) {
+    if (!record(info) || !Object.keys(info).every((key) => CARD_INFO_KEYS.includes(key)) || !exact(CARD_WORD, info.brand))
+        return null;
+    if (owns(info, "type") && !optionalText(info.type, CARD_WORD) || owns(info, "usage") && !optionalText(info.usage, CARD_WORD) || owns(info, "country") && !optionalText(info.country, COUNTRY) || owns(info, "issuer") && info.issuer !== null && !plain(info.issuer, 128) || owns(info, "coBrand") && info.coBrand !== null && !plain(info.coBrand, 64))
+        return null;
+    const safe = {};
+    for (const key of CARD_INFO_KEYS)
+        if (owns(info, key))
+            safe[key] = info[key];
+    return safe;
+}
+function rebuildSuccess(value) {
+    if (Object.keys(value).length !== 2 || !exact(TRANSACTION_ID, value.transactionId))
+        return null;
+    const cardInfo = rebuildCardInfo(value.cardInfo);
+    return cardInfo ? { transactionId: value.transactionId, cardInfo } : null;
+}
+function rebuildError(value) {
+    return Object.keys(value).length === 1 && plain(value.error, 256) && value.error.trim() !== "" ? { error: value.error } : null;
+}
+function datatransErrorCode(message) {
+    for (const [pattern, code] of ERROR_CODES)
+        if (typeof message === "string" && pattern.test(message))
+            return code;
+    return "datatrans_error";
+}
+function datatransResponseOutcome(status, body, card) {
+    if (status === 408 || status === 429)
+        return { outcome: "unknown", reason: "datatrans_status_unconfirmed" };
+    if (status >= 400 && status < 500)
+        return { outcome: "refused", code: `http_${status}` };
+    if (status !== 200)
+        return { outcome: "unknown", reason: "datatrans_status_unconfirmed" };
+    const value = readAnswer(body);
+    if (!value)
+        return { outcome: "unknown", reason: "datatrans_unreadable" };
+    if (owns(value, "error")) {
+        const error = rebuildError(value);
+        if (!error)
+            return { outcome: "unknown", reason: "datatrans_unexpected_response" };
+        const code = datatransErrorCode(error.error);
+        return code === "too_many_requests" ? { outcome: "unknown", reason: "datatrans_repeat_request" } : { outcome: "refused", code };
+    }
+    if (UNFOLLOWED_KEYS.some((key) => owns(value, key)))
+        return { outcome: "unknown", reason: "datatrans_unsupported_flow" };
+    const safe = rebuildSuccess(value);
+    if (!safe)
+        return { outcome: "unknown", reason: "datatrans_unexpected_response" };
+    if (card && digits(card.number, 12, 19) && safe.transactionId.includes(card.number)) {
+        return { outcome: "unknown", reason: "datatrans_token_mismatch" };
+    }
+    return { outcome: "approved" };
+}
+function sanitizeDatatransTokenResponse(body) {
+    const value = readAnswer(body);
+    const fail = () => {
+        throw new Error("Invalid Datatrans tokenization response.");
+    };
+    if (!value)
+        return fail();
+    if (owns(value, "error"))
+        return JSON.stringify(rebuildError(value) ?? fail());
+    if (UNFOLLOWED_KEYS.some((key) => owns(value, key)))
+        return fail();
+    return JSON.stringify(rebuildSuccess(value) ?? fail());
+}
+function datatransFacts(status, body) {
+    const verdict = datatransResponseOutcome(status, body);
+    return { outcome: verdict.outcome, refusalCode: verdict.outcome === "refused" ? verdict.code : null };
+}
+export { DATATRANS_CARD_ON_FILE_REFUSED, DATATRANS_HOSTS, DATATRANS_INVALID_REQUEST, DATATRANS_PAYMENT_METHODS, DATATRANS_REFUSAL_REASONS, DATATRANS_REGISTRATION_POLICIES, DATATRANS_REGISTRATION_POLICY, DATATRANS_REVIEWED_MERCHANT_IDS, DATATRANS_TEST_PANS, DATATRANS_TOKENIZE_PATH, classifyDatatransRequest, datatransBodyRefusal, datatransBrandRefusal, datatransCardBrand, datatransCardOnFileDisclosure, datatransDeviceRefusal, datatransErrorCode, datatransFacts, datatransMerchantId, datatransMerchantRefusal, datatransRefusalMessage, datatransRegistrationRefusal, datatransResponseOutcome, datatransTokenizeRefusal, encodeDatatransFormValue, injectDatatransCard, isDatatransTokenizeRequest, isDatatransTokenizeUrl, parseDatatransForm, sanitizeDatatransTokenResponse, serializeDatatransForm };

package/dist/datatrans.js

@@ -0,0 +1,178 @@
+// Datatrans / PCI Proxy Secure Fields 2.0.0 in TOKENIZE mode (psp `datatrans`), on
+// pay.datatrans.com (live) and pay.sandbox.datatrans.com (sandbox): the card form British Airways's
+// Nexus checkout loads. Datatrans's card-number iframe reads the CVV from its same-origin CVV frame
+// and sends the whole card in one same-origin XHR, POST /upp/payment/SecureFields/paymentField,
+// form encoded. This module holds what the SDK decides about that iframe's requests. The rules
+// themselves are payment-core's (datatrans.generated.ts): the API applies the same ones at create,
+// and the cardholder's device applies them again before it writes a card. The one rule meant to
+// change after a build ships, the card-on-file policy, is never read from that copy: the API serves
+// the policy its create applies with the recognizer (Recognizer.cardOnFile), and this build follows
+// it at each sync.
+//
+// The processor ships dark. The API serves the datatrans recognizer only to a build that declares
+// the `datatrans_secure_fields_tokenize` capability (client.ts SUPPORTED_CAPABILITIES) and only to
+// an org Agentcard enabled for it, so an SDK the API never served it leaves every Datatrans request
+// alone.
+import { DATATRANS_CARD_ON_FILE_REFUSED, DATATRANS_HOSTS, DATATRANS_INVALID_REQUEST, DATATRANS_REGISTRATION_POLICIES, classifyDatatransRequest, datatransResponseOutcome, isDatatransTokenizeUrl, parseDatatransForm, } from './datatrans.generated.js';
+export const DATATRANS_PSP = 'datatrans';
+/** The dark-launch capability the API serves the datatrans recognizer behind. */
+export const DATATRANS_CAPABILITY = 'datatrans_secure_fields_tokenize';
+/** True when the URL's host is one of Datatrans's two pay hosts. */
+export function isDatatransHost(url) {
+    try {
+        return DATATRANS_HOSTS.includes(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The card-on-file policy this build applies to a Datatrans card post: the one the API served with
+ * the datatrans recognizer (Recognizer.cardOnFile, VaultClient.cardOnFilePolicy) when payment-core
+ * defines it (`refuse`, `disclose`, `agentcard_single_use`), and `refuse` for anything else, an entry
+ * that names none included. The decision is payment-core's DATATRANS_REGISTRATION_POLICY, which the
+ * API reads each time it serves the catalog and again at create, so a change to that one line
+ * reaches every build already published at its next syncRegistry(), with no SDK release.
+ */
+export function datatransCardOnFilePolicy(served) {
+    return typeof served === 'string' && DATATRANS_REGISTRATION_POLICIES.includes(served) ? served : 'refuse';
+}
+/**
+ * The pause decision for a POST the registry recognized on a Datatrans pay host, by payment-core's
+ * classifyDatatransRequest under the card-on-file policy the API served (datatransCardOnFilePolicy):
+ *   'card'  the exact card URL with jQuery's form type and a sound TOKENIZE card body: it pauses. A
+ *           usage=REGISTRATION post is one too once the served policy allows card on file, and the
+ *           API and the cardholder's device then apply that policy;
+ *   a DatatransRefusalReason: it is refused in the browser;
+ *   null    no card in the body (a wallet, bank-account or CVV-only post) or not the card path:
+ *           the SDK's ordinary handling decides, and such a post continues untouched.
+ */
+export function datatransPauseDecision(request, servedPolicy) {
+    const verdict = classifyDatatransRequest(request.url, 'POST', request.body ?? '', request.headers ?? {}, datatransCardOnFilePolicy(servedPolicy));
+    if (verdict === 'card')
+        return 'card';
+    if (verdict === 'card_on_file')
+        return DATATRANS_CARD_ON_FILE_REFUSED;
+    return verdict === null ? null : DATATRANS_INVALID_REQUEST;
+}
+// ── The repeat rule ─────────────────────────────────────────────────────────
+// British Airways's Nexus page tokenizes on blur, not on Pay: it submits the Secure Fields form
+// whenever a valid field loses focus, on autofill and whenever the expiry changes, and field.js
+// itself answers only a byte-identical submit from its cache. Without this rule each of those posts
+// would be a new approval on the cardholder's phone for a card the phone already tokenized into the
+// same form. So once an approved answer is handed to a card post, a later card post from the same
+// frame that differs from it only in the expiry (expm, expy) and the browser details (browser*) is
+// answered here, with that stored answer: no create, no prompt, no second replay. Those are the
+// fields the design lets a re-submit change: the device writes the Vault card's own expiry, and the
+// browser details describe the window, not the card. Every other field must match: the formId, the
+// merchantId, the placeholder card number and CVV, the brand, usage, and the traveller's email and
+// phone number, which Nexus sends for Amex and which reach Datatrans with the real card. A new
+// formId (the iframe reloaded), another placeholder, other contact data or another frame is a new
+// question. The answer also belongs to one approval's handoff: the gate in pre-claim.ts hands it
+// out only while that approval is the attachment's current one, so the order completing or failing,
+// a latched attachment and a new authorization all end it. The post names no amount and no order, so
+// once the answer reached the page the gate asks the application's merchant resolver before each
+// repeat and answers only while the order is still pending; an attachment with no resolver answers no
+// repeat after the handoff. The answer also ends once its form goes quiet (DATATRANS_REPEAT_IDLE_MS).
+/**
+ * How long an approved Datatrans answer is replayed to its own frame: the token's own lifetime
+ * (PCI Proxy keeps a tokenization readable for 30 minutes). Past it the stored transactionId names a
+ * token the merchant can no longer read, so a later post is a new question.
+ */
+export const DATATRANS_REPEAT_WINDOW_MS = 30 * 60_000;
+/**
+ * How long a stored answer waits for its form's next post. British Airways re-submits while the agent
+ * finishes the card form, right after the approved answer. A form that posts nothing for this long has
+ * moved on: the order was placed or abandoned, which the SDK cannot tell apart without reconcile(). Its
+ * next post is a new approval. Each answered re-submit restarts the wait, and the token's lifetime
+ * still ends every answer.
+ */
+export const DATATRANS_REPEAT_IDLE_MS = 5 * 60_000;
+/** The most answers one attachment keeps; the oldest goes first. */
+const MAX_REMEMBERED = 8;
+/** The fields a re-submit may change and still be the same question: the expiry and the browser details. */
+const REPEAT_FREE_FIELDS = new Set(['expm', 'expy', 'browserUserAgent', 'browserJavaEnabled',
+    'browserLanguage', 'browserColorDepth', 'browserScreenHeight', 'browserScreenWidth', 'browserTZ']);
+function repeatKey(url, body) {
+    if (!isDatatransTokenizeUrl(url) || typeof body !== 'string')
+        return null;
+    const pairs = parseDatatransForm(body);
+    if (!pairs)
+        return null;
+    const kept = pairs.filter(({ key }) => !REPEAT_FREE_FIELDS.has(key)).map(({ key, value }) => [key, value]);
+    const fields = new Map(kept);
+    if (!['formId', 'merchantId', 'cardNumber', 'paymentMethod'].every((name) => fields.get(name)))
+        return null;
+    return { url, fields: JSON.stringify(kept) };
+}
+function sameKey(a, b) {
+    return a.url === b.url && a.fields === b.fields;
+}
+/**
+ * The approved Datatrans answers one attachment handed to a card post, per frame. `frame` is the
+ * adapter's identity for the request's frame (the CDP frameId, the Playwright Frame); a request
+ * whose frame is unknown is never remembered and never answered. Only an answer payment-core reads
+ * as approved ({transactionId, cardInfo}) is kept: an error answer leaves the next post a new
+ * question, so the page can try again.
+ */
+export class DatatransRepeats {
+    windowMs;
+    now;
+    idleMs;
+    // `at`: when the approved answer reached the page; `seen`: when its form last posted and was answered.
+    remembered = [];
+    constructor(windowMs = DATATRANS_REPEAT_WINDOW_MS, now = Date.now, idleMs = DATATRANS_REPEAT_IDLE_MS) {
+        this.windowMs = windowMs;
+        this.now = now;
+        this.idleMs = idleMs;
+    }
+    /**
+     * Keep the answer a token replay handed to this card post, when Datatrans approved it. Called
+     * after the answer reached the browser, so it never throws: a failure here only leaves the
+     * page's next post a new question.
+     */
+    remember(frame, url, body, replay) {
+        try {
+            if (frame === undefined || frame === null || frame === '')
+                return;
+            if (replay.mode === 'cse' || replay.mode === 'hosted_form')
+                return;
+            const key = repeatKey(url, body);
+            if (!key || datatransResponseOutcome(replay.status, replay.body, undefined).outcome !== 'approved')
+                return;
+            this.prune();
+            this.remembered = this.remembered.filter((entry) => !(entry.frame === frame && sameKey(entry.key, key)));
+            const at = this.now();
+            this.remembered.push({ frame, key, authorizationId: replay.authorizationId, status: replay.status,
+                headers: { ...replay.headers }, body: replay.body, at, seen: at });
+            if (this.remembered.length > MAX_REMEMBERED)
+                this.remembered.shift();
+        }
+        catch { /* see above: the next post is a new question */ }
+    }
+    /**
+     * The stored answer for a repeat of an answered card post from the same frame, or null. Only an
+     * answer from `authorizationId`, the approval the attachment is handing off now, is handed out,
+     * and every answer from another approval is dropped: a later authorization ends the window of
+     * every earlier one. An answer whose form stayed quiet past the idle bound is dropped too, and
+     * handing one out restarts that bound.
+     */
+    answerFor(frame, url, body, authorizationId) {
+        if (frame === undefined || frame === null || frame === '' || !authorizationId)
+            return null;
+        const key = repeatKey(url, body);
+        if (!key)
+            return null;
+        this.prune();
+        this.remembered = this.remembered.filter((entry) => entry.authorizationId === authorizationId);
+        const entry = this.remembered.find((candidate) => candidate.frame === frame && sameKey(candidate.key, key));
+        if (!entry)
+            return null;
+        entry.seen = this.now();
+        return { authorizationId: entry.authorizationId, response: { status: entry.status, headers: { ...entry.headers }, body: entry.body } };
+    }
+    prune() {
+        const now = this.now();
+        this.remembered = this.remembered.filter((entry) => now - entry.at < this.windowMs && now - entry.seen < this.idleMs);
+    }
+}

package/dist/ekashu.d.ts

@@ -0,0 +1,35 @@
+/**
+ * NMI's Hosted Payment Page (formerly eKashu), as this SDK reads it.
+ *
+ * The merchant's page posts an entry form, top-level, to https://live.ekashu.com/ (test:
+ * test.ekashu.com), and NMI answers with its own card page. That entry carries no card, and it
+ * is the one request this SDK pauses: the cardholder's device repeats it over the end-to-end TLS
+ * relay and fills the card into the page NMI returns to it (payment-core processors/ekashu.js).
+ * Everything else the agent's browser posts to NMI carries a card the agent typed: the card page's
+ * own post (/index.php) and its 3-D Secure calls (ajax_3d_secure_v2_*.php). This SDK aborts every
+ * one of them, so a placeholder card never reaches NMI.
+ *
+ * The hosts are payment-core's EKASHU_HOSTS; payment-core.test.mjs pins the two lists together.
+ */
+export declare const EKASHU_PSP = "ekashu";
+export declare const EKASHU_HOSTS: readonly string[];
+/** Whether this URL is on one of NMI's hosted payment page hosts (https, standard port, no credentials). */
+export declare function isEkashuHost(url: string): boolean;
+/**
+ * The only request on NMI's hosts that is the merchant's entry: a POST to the host's root, with no
+ * query. The entry the SDK pauses; every other POST there carries a card and is aborted.
+ */
+export declare function isEkashuEntry(url: string, method: string): boolean;
+/** The entry URL on the same NMI host as this URL, the one the registry recognizes when this build is armed for NMI. */
+export declare function ekashuEntryUrl(url: string): string | null;
+/**
+ * Whether an adapter must hand this request to the pre-claim gates: it is on one of NMI's hosts
+ * and this build's registry serves that host's entry. The card page's own post and its 3-D Secure
+ * calls are not the entry, so the registry's card-request test (anchored to the entry) does not
+ * name them; the CDP adapter still pauses them through the recognizer's host-wide URL patterns,
+ * and attachToPlaywright's route predicate asks this, so both adapters show the gates every
+ * request to an armed NMI host.
+ */
+export declare function isArmedEkashuUrl(vault: {
+    isCardRequest(url: string, method?: string): boolean;
+}, url: string): boolean;