@agent-cards/sdk 0.21.0 → 0.22.0

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/elavon-converge.d.ts

@@ -0,0 +1,37 @@
+export declare const CONVERGE_PSP = "elavon_converge";
+/** The dark-launch capability the API serves the elavon_converge recognizer behind. */
+export declare const CONVERGE_CAPABILITY = "converge_hpp_process";
+/**
+ * Why the SDK refuses an Elavon Converge payment before anything is claimed, created or prompted:
+ * payment-core's own codes (CONVERGE_REFUSAL_CODES), the ones the API answers a create with and
+ * the device refuses with, so an integrator reads one code whichever of them refused.
+ *   - A shape the Vault never pays: `converge_wallet_refused`, `converge_debit_card_refused`,
+ *     `converge_push_to_card_refused`, `converge_gift_card_refused`, `converge_payment_type_refused`,
+ *     `converge_captcha_refused`, `converge_service_fee_refused`, `converge_recurring_refused`,
+ *     `converge_card_saving_refused` (ssl_get_token or ssl_add_token), `converge_amount_add_on_refused`
+ *     (a tip or cash back) and `converge_currency_refused` (anything but US dollars).
+ *   - A follow-up after a step the Vault cannot complete: `converge_3ds_follow_up_refused` (3-D
+ *     Secure or Pay Defense) and `converge_surcharge_refused`.
+ *   - A body the cardholder has nothing to approve on: `converge_amount_missing` and
+ *     `converge_context_missing`.
+ *   - Not the page's own card request, which the device could never fill: `converge_body_malformed`,
+ *     `converge_credential_refused`, `converge_card_missing`, `converge_card_malformed`,
+ *     `converge_url_refused`, `converge_method_refused` and `converge_content_type_refused`.
+ */
+export declare const CONVERGE_REFUSAL_REASONS: readonly ["converge_body_malformed", "converge_payment_type_refused", "converge_debit_card_refused", "converge_push_to_card_refused", "converge_gift_card_refused", "converge_credential_refused", "converge_wallet_refused", "converge_captcha_refused", "converge_service_fee_refused", "converge_3ds_follow_up_refused", "converge_surcharge_refused", "converge_amount_add_on_refused", "converge_card_saving_refused", "converge_recurring_refused", "converge_currency_refused", "converge_amount_missing", "converge_context_missing", "converge_card_missing", "converge_card_malformed", "converge_url_refused", "converge_method_refused", "converge_content_type_refused"];
+export type ConvergeRefusalReason = typeof CONVERGE_REFUSAL_REASONS[number];
+/** True when the URL's host is one of Converge's two payment page hosts. */
+export declare function isConvergeHost(url: string): boolean;
+/**
+ * The pause decision for a card-carrying POST the registry recognized on a Converge host. Null
+ * when it is the page's own first credit card sale, which pauses for approval; otherwise the reason
+ * it is refused. It judges the whole request (the exact process URL, the page's JSON content type,
+ * and a body exactly as the page serializes it) with payment-core's convergeRequestRefusal, the
+ * check the API runs at create and the device runs before it writes a card. A code this build does
+ * not list reads as not the page's request, so a newer core can only refuse more.
+ */
+export declare function convergeRefusal(request: {
+    url: string;
+    headers: Record<string, string>;
+    body: string | null;
+}): ConvergeRefusalReason | null;

package/dist/elavon-converge.generated.d.ts

@@ -0,0 +1,49 @@
+declare var CONVERGE_HOSTS: readonly string[];
+declare var CONVERGE_DEMO_HOST: string;
+declare var CONVERGE_PROCESS_PATH: string;
+declare var CONVERGE_PROCESS_URLS: readonly string[];
+declare var CONVERGE_REFUSAL_CODES: readonly string[];
+declare function parseConvergeBody(body: any): any;
+declare function convergeAmountCents(value: any): number | null;
+declare function convergeBodyVerdict(body: any): Readonly<{
+    verdict: "refuse";
+    code: any;
+}> | Readonly<{
+    verdict: "continue";
+}> | Readonly<{
+    verdict: "card";
+}>;
+declare function convergeBodyRefusal(body: any): any;
+declare function isConvergeProcessUrl(url: any): boolean;
+declare function convergeRequestRefusal(request: any): any;
+declare function convergeRefusalMessage(code: any): any;
+declare function injectConvergeHppCard(templateBody: any, card: any): {
+    body: string;
+    where: string[];
+};
+declare function convergeAnswerKind(text: any): "unknown" | "approved" | "declined" | "step" | "session_timeout";
+declare function convergeFacts(text: any, template: any): {
+    kind: string;
+    final: boolean;
+    refusalCode: any;
+    txnId: string | null;
+    approvalCode: string | null;
+    amountCents: number | null;
+    tokenIssued: boolean;
+    chargedAboveRequest: boolean;
+};
+declare function convergeResponseOutcome(status: any, text: any): {
+    outcome: string;
+    reason: string;
+    code?: undefined;
+} | {
+    outcome: string;
+    reason?: undefined;
+    code?: undefined;
+} | {
+    outcome: string;
+    code: any;
+    reason?: undefined;
+};
+declare function sanitizeConvergeResponse(text: any): string;
+export { CONVERGE_DEMO_HOST, CONVERGE_HOSTS, CONVERGE_PROCESS_PATH, CONVERGE_PROCESS_URLS, CONVERGE_REFUSAL_CODES, convergeAmountCents, convergeAnswerKind, convergeBodyRefusal, convergeBodyVerdict, convergeFacts, convergeRefusalMessage, convergeRequestRefusal, convergeResponseOutcome, injectConvergeHppCard, isConvergeProcessUrl, parseConvergeBody, sanitizeConvergeResponse };