@agent-cards/sdk 0.21.0 → 0.23.0

package/dist/aci.js

@@ -0,0 +1,371 @@
+// ACI Worldwide COPYandPAY: the adapters' side of a split card.
+//
+// ACI's payment widget never sends a card in one request. Each of its PCI iframes posts only the
+// field it holds to POST https://<host>/v1/checkouts/<id> (the card number, the CVC and, in the
+// merchant's SAQ-A mode, the expiry and the holder), and once every one of those answered, the
+// merchant page's own form posts /v1/checkouts/<id>/payment from a hidden iframe. The rules that
+// judge each request (the leg classifier, the /payment continuation judge, the answer allow-list)
+// live in payment-core and reach this SDK as aci.generated.ts. This module holds what one
+// attachment decides from them:
+//   - the card-number request is the card request: the adapters pause it, the cardholder's device
+//     replays it with the real number, CVC and expiry, and the page gets ACI's rebuilt answer;
+//   - the page's own CVC and expiry requests carry the agent's placeholder values: they are held
+//     and answered with the card-number request's answer once it lands, never forwarded, and
+//     failed when it does not (or when no card-number request for their checkout ever begins);
+//   - the holder request carries nothing secret and continues;
+//   - a second card-number request on a checkout whose first one is running or was answered here
+//     is refused: that answer put the real card on the checkout and may already have let /payment
+//     through, and ACI warns that one checkout id reused can carry a second transaction;
+//   - the /payment submission continues only after its checkout's card-number request was
+//     answered, once, with the placeholder expiry a classic-mode page puts there removed, the
+//     brand held to the card number that request carried, and the return kept on the merchant.
+//     It continues only as a frame navigation, which is how the widget's form posts it into its
+//     hidden iframe, and a classic-mode body only on a browser shown to send the body the SDK
+//     replaced on a navigation (Chromium; see playwrightReplacesNavigationBody).
+import { aciBrandOfCardLeg as brandOfCardLeg, aciEndpoint, classifyAciRequest, prepareAciContinuation, sanitizeAciResponse, } from './aci.generated.js';
+const classifyLeg = classifyAciRequest;
+const judgePayment = prepareAciContinuation;
+/** The processor id, as the registry and the API name it. */
+export const ACI_PSP = 'aci';
+/** The dark-launch capability the API serves the ACI recognizer behind (payment-core definitions.js). */
+export const ACI_CAPABILITY = 'aci_split_card.v1';
+/**
+ * How long a sibling leg (the page's CVC or expiry request) waits for its checkout's card-number
+ * request to begin an approval. The widget fires every leg on one Pay click, milliseconds apart,
+ * so a sibling that still has no card-number request after this is one this SDK will never answer
+ * (a one-click stored-card CVC form, or a card-number request refused before it paused).
+ */
+export const ACI_SIBLING_WAIT_MS = 5_000;
+/** The /payment submission of a checkout whose card-number request was never answered here. */
+export const ACI_PAYMENT_UNAPPROVED = 'aci_payment_unapproved';
+/** A second /payment submission on a checkout that already continued one. */
+export const ACI_PAYMENT_REPEATED = 'aci_payment_repeated';
+/** A card-number request on a checkout whose card-number request is running or was answered here. */
+export const ACI_CHECKOUT_REUSED = 'aci_checkout_reused';
+/**
+ * How many failed checkouts one attachment keeps. A failed checkout only makes its later CVC and
+ * expiry requests fail at once instead of after ACI_SIBLING_WAIT_MS, so the oldest are dropped past
+ * this; a running or answered checkout is never dropped, since it is what refuses a second
+ * card-number request or /payment on that checkout.
+ */
+export const ACI_FAILED_CHECKOUTS_KEPT = 16;
+/**
+ * ACI's paymentBrand for the card number a card-number request carried, or null. That number is
+ * the agent's placeholder, typed in the approved card's network (a Mastercard-range placeholder for
+ * an Agentcard-issued card), and ACI's widget names the brand of the /payment submission from the
+ * same digits. The SDK is never told the approved card's own network: the widget's brand for the
+ * approved request is the one /payment may carry. The cardholder's device judges the placeholder
+ * with this same payment-core rule and refuses to send a card of another brand, which ACI would
+ * otherwise hold on the checkout before refusing /payment (100.100.700).
+ */
+export function aciBrandOfCardLeg(body) {
+    return brandOfCardLeg(body);
+}
+/**
+ * The answer a paused card-number request gets, or null when the stored answer is not one to hand
+ * the page: a 2xx carrying exactly ACI's rebuilt success answer (payment-core sanitizeAciResponse,
+ * the allow-list the API stored it through), under JSON. The widget only waits for every leg to
+ * resolve, so nothing else ACI said is ever needed, and the same answer serves the sibling legs.
+ */
+export function aciCardLegAnswer(response) {
+    if (!Number.isInteger(response?.status) || response.status < 200 || response.status > 299 || typeof response.body !== 'string')
+        return null;
+    let rebuilt;
+    try {
+        rebuilt = sanitizeAciResponse(response.body);
+    }
+    catch {
+        return null;
+    }
+    if (rebuilt !== response.body)
+        return null;
+    return { status: response.status, headers: { 'content-type': 'application/json' }, body: rebuilt };
+}
+/**
+ * The URL with an ACI checkout id taken out of its path, or null for a URL that is not on one of
+ * ACI's hosts under /v1/checkouts/. The id is the checkout's only capability: once the card-number
+ * request carried the real card, anyone holding it can post /payment against that card for the
+ * rest of the checkout's 30 minutes, so it never rides on an event.
+ */
+export function redactAciCheckoutId(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!['eu-prod.oppwa.com', 'oppwa.com', 'eu-test.oppwa.com', 'test.oppwa.com'].includes(url.hostname))
+        return null;
+    const path = /^\/v1\/checkouts\/[^/]+(\/.*)?$/.exec(url.pathname);
+    return path ? `${url.origin}/v1/checkouts/{checkoutId}${path[1] ?? ''}` : null;
+}
+/** How long the persistent-context engine probe (a CDP session opening) may take before it counts as no. */
+export const ACI_ENGINE_PROBE_MS = 5_000;
+/**
+ * Whether a Playwright page's browser sends the body the SDK replaced on a navigation. Removing the
+ * placeholder expiry from a classic-mode /payment needs it, because the widget's form posts
+ * /payment as its hidden iframe's navigation. The SDK's ACI browser test shows it on Chromium in
+ * both adapters (design gate G3), and CI installs only Chromium; a local WebKit 26.5 run sent the
+ * replaced body too, but nothing keeps that true, so every engine but Chromium is refused rather
+ * than trusted with the placeholder expiry. The engine is the page's browser type, or, for a
+ * persistent context that names no browser, whether a CDP session opens on the page, which only
+ * Chromium allows.
+ */
+export async function playwrightReplacesNavigationBody(page, probeMs = ACI_ENGINE_PROBE_MS) {
+    let context;
+    try {
+        context = page?.context?.();
+    }
+    catch {
+        return false;
+    }
+    let engine;
+    try {
+        engine = context?.browser?.()?.browserType?.()?.name?.();
+    }
+    catch {
+        engine = undefined;
+    }
+    if (typeof engine === 'string')
+        return engine === 'chromium';
+    if (typeof context?.newCDPSession !== 'function')
+        return false;
+    let opening;
+    try {
+        opening = Promise.resolve(context.newCDPSession(page));
+    }
+    catch {
+        return false;
+    }
+    let timer;
+    // A ref'd timer: the probe always settles within probeMs, even when nothing else keeps Node running.
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('expired'), probeMs);
+    });
+    try {
+        const session = await Promise.race([opening, expired]);
+        if (session === 'expired') {
+            // A session that opens after the probe gave up is closed then: the probe never keeps one.
+            opening.then((late) => late?.detach?.(), () => { }).catch(() => { });
+            return false;
+        }
+        try {
+            await session?.detach?.();
+        }
+        catch { /* the probe's own session; nothing depends on it */ }
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const groupKey = (leg) => `${leg.host}/${leg.checkoutId}`;
+/**
+ * One attachment's ACI state, keyed by checkout (host and checkout id). Every sibling and every
+ * /payment submission is matched against a card-number request this attachment itself paused and
+ * answered, never taken on the page's word. Inert (classify returns null) until the registry serves
+ * ACI, which a client reaches only by syncing with the capability, so a build or an API that never
+ * served it leaves every ACI request exactly as before.
+ */
+export class AciGate {
+    vault;
+    siblingWaitMs;
+    groups = new Map();
+    /** Siblings that arrived before their checkout's card-number request began, by checkout. */
+    early = new Map();
+    /** The checkout whose card-number request's approval is running. */
+    current = null;
+    constructor(vault, siblingWaitMs = ACI_SIBLING_WAIT_MS) {
+        this.vault = vault;
+        this.siblingWaitMs = siblingWaitMs;
+    }
+    served() {
+        return typeof this.vault?.recognizesProcessor === 'function' && this.vault.recognizesProcessor(ACI_PSP) === true;
+    }
+    /** What this request is, when the registry serves ACI and it is a POST to an ACI checkout; null leaves it to the other gates. */
+    classify(url, method, body) {
+        if (!this.served())
+            return null;
+        return classifyLeg({ url, method: typeof method === 'string' ? method.toUpperCase() : method, body });
+    }
+    /**
+     * Playwright's route predicate sees only the URL. The card-number, CVC, expiry and holder
+     * requests share the recognizer's URL; /payment and /registration do not, so they are routed
+     * here, and the rest of ACI's traffic (the widget script, /bins, /v1/collect) never is.
+     */
+    matches(url) {
+        return this.served() && aciEndpoint(url) !== null;
+    }
+    /**
+     * The card-number request of a checkout began its approval; its siblings wait for the outcome.
+     * False, with nothing changed, for a checkout whose card-number request is still running or was
+     * answered here: its group keeps its answer and its one /payment, so a second approval can never
+     * reopen that checkout for another /payment. The pre-claim gate refuses such a request first
+     * (reused, aci_checkout_reused), before it claims a preparation; the adapters fail it here too.
+     * A refused begin leaves the running approval it found running. A checkout whose card-number
+     * request failed begins again.
+     */
+    begin(url, method, body, merchantOrigin) {
+        const leg = classifyLeg({ url, method: typeof method === 'string' ? method.toUpperCase() : method, body });
+        if (leg?.leg !== 'card') {
+            this.current = null;
+            return true;
+        }
+        const key = groupKey(leg);
+        if (this.live(key))
+            return false;
+        const group = { state: 'running', answer: null, authorizationId: null, brand: aciBrandOfCardLeg(body),
+            merchantOrigin: merchantOrigin ?? null, paid: false, waiters: new Set() };
+        this.groups.set(key, group);
+        this.current = key;
+        const early = this.early.get(key);
+        this.early.delete(key);
+        for (const wake of early ?? [])
+            wake(group);
+        return true;
+    }
+    /** Whether this checkout's card-number request is running or was answered here: another one is refused. */
+    reused(leg) {
+        return this.live(groupKey(leg));
+    }
+    live(key) {
+        const group = this.groups.get(key);
+        return !!group && group.state !== 'failed';
+    }
+    /** Drops the oldest failed checkouts past ACI_FAILED_CHECKOUTS_KEPT; running and answered ones stay. */
+    prune() {
+        let failed = 0;
+        for (const group of this.groups.values())
+            if (group.state === 'failed')
+                failed++;
+        for (const [key, group] of this.groups) {
+            if (failed <= ACI_FAILED_CHECKOUTS_KEPT)
+                return;
+            if (group.state === 'failed') {
+                this.groups.delete(key);
+                failed--;
+            }
+        }
+    }
+    /** The card-number request's answer reached the page; its siblings get the same answer. */
+    answered(url, answer, authorizationId) {
+        const endpoint = aciEndpoint(url);
+        if (!endpoint || endpoint.kind !== 'leg' || this.current !== groupKey(endpoint))
+            return;
+        const group = this.groups.get(this.current);
+        if (!group || group.state !== 'running')
+            return;
+        group.state = 'answered';
+        group.answer = answer;
+        group.authorizationId = authorizationId;
+        for (const settle of group.waiters)
+            settle(answer);
+        group.waiters.clear();
+    }
+    /** The card-number request's approval ended, answered or not; unanswered siblings fail. */
+    end() {
+        const key = this.current;
+        this.current = null;
+        const group = key ? this.groups.get(key) : undefined;
+        if (!group || group.state !== 'running')
+            return;
+        group.state = 'failed';
+        for (const settle of group.waiters)
+            settle(null);
+        group.waiters.clear();
+        this.prune();
+    }
+    /**
+     * A request on this checkout was refused before any card-number request began (a card-number
+     * request that asks ACI to keep the card, a leg the widget never sends): the siblings waiting for
+     * one fail now, and so does every later sibling until a card-number request begins. A running or
+     * answered card-number request keeps its siblings.
+     */
+    refused(leg) {
+        const key = groupKey(leg);
+        const known = this.groups.get(key);
+        if (known && known.state !== 'failed')
+            return;
+        const failed = { state: 'failed', answer: null, authorizationId: null, brand: null, merchantOrigin: null, paid: false, waiters: new Set() };
+        // Deleted first, so the newest refusal is the last one pruned.
+        this.groups.delete(key);
+        this.groups.set(key, failed);
+        const early = this.early.get(key);
+        this.early.delete(key);
+        for (const wake of early ?? [])
+            wake(failed);
+        this.prune();
+    }
+    /**
+     * A sibling leg (the page's CVC or expiry request): the answer to hand it, once its checkout's
+     * card-number request was answered, or null when that request failed, never began within
+     * siblingWaitMs, or cannot be answered here. Never resolves to anything the page did not get.
+     */
+    hold(leg) {
+        const key = groupKey(leg);
+        const known = this.groups.get(key);
+        if (known?.state === 'answered')
+            return Promise.resolve(known.answer);
+        if (known?.state === 'failed')
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            const attach = (group) => {
+                if (group.state === 'answered')
+                    resolve(group.answer);
+                else if (group.state === 'failed')
+                    resolve(null);
+                else
+                    group.waiters.add(resolve);
+            };
+            if (known) {
+                attach(known);
+                return;
+            }
+            let waiting = this.early.get(key);
+            if (!waiting) {
+                waiting = new Set();
+                this.early.set(key, waiting);
+            }
+            const wake = (group) => { clearTimeout(timer); attach(group); };
+            // A ref'd timer: the page's request is answered within siblingWaitMs even when nothing else
+            // keeps Node running, never left pending while the process exits.
+            const timer = setTimeout(() => {
+                const set = this.early.get(key);
+                set?.delete(wake);
+                if (set && set.size === 0)
+                    this.early.delete(key);
+                resolve(null);
+            }, this.siblingWaitMs);
+            waiting.add(wake);
+        });
+    }
+    /**
+     * The page's /payment submission: continue it with the body to send, or refuse it. It continues
+     * only as a frame navigation (the widget's form posting into its hidden iframe; a script's fetch
+     * of the same URL is not the widget's and is refused before it can take the reservation), only
+     * for a checkout whose card-number request this attachment answered, only once, and only as
+     * payment-core's judge admits it for that card's brand and the merchant the cardholder approved.
+     * The reservation is taken before the answer, so two submissions can never both continue.
+     */
+    payment(url, method, body, request) {
+        const leg = classifyLeg({ url, method: typeof method === 'string' ? method.toUpperCase() : method, body });
+        if (leg?.leg !== 'continuation' || request?.navigation !== true)
+            return { outcome: 'refuse', code: 'aci_unsupported_request' };
+        const group = this.groups.get(groupKey(leg));
+        if (!group || group.state !== 'answered')
+            return { outcome: 'refuse', code: ACI_PAYMENT_UNAPPROVED };
+        if (group.paid)
+            return { outcome: 'refuse', code: ACI_PAYMENT_REPEATED };
+        const verdict = judgePayment({ url, method: 'POST', body }, { brand: group.brand, merchantOrigin: group.merchantOrigin });
+        if (verdict.outcome !== 'continue')
+            return { outcome: 'refuse', code: verdict.code };
+        if (verdict.host !== leg.host || verdict.checkoutId !== leg.checkoutId)
+            return { outcome: 'refuse', code: 'aci_unsupported_request' };
+        group.paid = true;
+        return { outcome: 'continue', body: verdict.body, stripped: verdict.stripped, authorizationId: group.authorizationId };
+    }
+}

package/dist/adyen-merchant-hosted.generated.d.ts

@@ -239,7 +239,7 @@ declare function merchantTotalFromResponses(profileId: any, input: any): {
         bodyAmount: string;
     };
 };
-declare function merchantProfileUrlRelation(profileId: any, rawUrl: any): "endpoint" | "sibling" | null;
+declare function merchantProfileUrlRelation(profileId: any, rawUrl: any): "sibling" | "endpoint" | "then" | "other" | null;
 declare function carriesAdyenCardCiphertext(body: any): any;
 declare function classifyMerchantBody(profileId: any, body: any): Readonly<{
     verdict: "pass";
@@ -257,7 +257,7 @@ declare function classifyMerchantRequest(profileId: any, rawUrl: any, method: an
 }> | Readonly<{
     verdict: "pause";
 }>;
-declare function declaredUrlRelation(endpoint: any, rawUrl: any): "endpoint" | "sibling" | null;
+declare function declaredUrlRelation(endpoint: any, rawUrl: any): "sibling" | "endpoint" | null;
 declare function classifyDeclaredMerchantRequest(profileId: any, endpoint: any, rawUrl: any, method: any, body: any): Readonly<{
     verdict: "pass";
 }> | Readonly<{
@@ -269,7 +269,7 @@ declare function classifyDeclaredMerchantRequest(profileId: any, endpoint: any,
 declare function declaredTemplatedUrl(endpoint: any): string;
 declare function merchantProfileTemplatedUrl(profileId: any, rawUrl: any): string;
 declare function merchantBodyKeyPathSha256(body: any): string | null;
-declare function merchantProfileUrlGlobs(profileId: any): unknown[];
+declare function merchantProfileUrlGlobs(profileId: any): any[];
 declare function declaredUrlGlobs(endpoint: any): string[];
 declare function merchantProfileRulesMatch(profileId: any, served: any): boolean;
 declare function merchantProfileEnvironment(profileId: any): "production" | "sandbox";