@agent-cards/sdk 0.23.21 → 0.23.23

package/dist/payrexx.js

@@ -0,0 +1,141 @@
+/**
+ * Payrexx Pay's card frame after its card request (payment-core payrexx.js holds the rules; this SDK vendors them as
+ * payrexx.generated.ts).
+ *
+ * The frame, https://checkout.payrexx.com/?pspId=44&lang=<xx>, posts the card to its own URL. When Payrexx answers that
+ * card request by starting 3-D Secure (no token, a threeDSServerTransID), the merchant's page runs 3-D Secure and the
+ * frame posts the whole card again to the same URL for each step, with the step's own keys after the card request's
+ * fifteen:
+ *   - the authentication, after the ACS method: threeDSServerTransID, threeDSVersion when the first answer named one,
+ *     and ten authData values the page reads from the agent's browser;
+ *   - the post-authentication, after the bank's challenge: threeDSServerTransID and postAuth=true.
+ * On a page this SDK is attached to, that card is the agent's placeholder. One approval covers at most one of each, in
+ * that order, for the 3-D Secure run its own answer opened (payment-core payrexxFollowUpVerdict), so a run sends the
+ * card at most three times. What this module keeps of the approved card request (PayrexxFollowUps) is what the
+ * pre-claim gate reads to decide whether the cardholder's device sends a step, or the step fails in the browser.
+ * The card request itself, and a body with no card value at all (a wallet's own encryptedCard), are not 3-D Secure
+ * sends: the card-request arbiter pauses the one and continues the other (card-fields.js).
+ */
+import { PAYREXX_FOLLOW_UP_KINDS, isPayrexxFrameUrl, payrexxAnswerOutcome, payrexxBodyVerdict, payrexxFollowUpVerdict, payrexxGateVerdict, } from './payrexx.generated.js';
+export const PAYREXX_PSP = 'payrexx';
+/** The capability a build declares to be served Payrexx's recognizer (payment-core PAYREXX_CAPABILITY). */
+export const PAYREXX_CAPABILITY = 'payrexx_card_frame';
+/** The reason a checkout reads when a 3-D Secure send of the placeholder card fails in the browser. */
+export const PAYREXX_RESEND_REASON = 'unsupported_payrexx_card_resend';
+/**
+ * Whether a request is a POST to Payrexx's card frame URL whose body sends the card again for a 3-D Secure step
+ * (payment-core payrexxBodyVerdict: payrexx_three_ds_resend). `readBody` is called only for a POST to the frame URL,
+ * and a reader that throws, or a body nobody could read, reads as no 3-D Secure send.
+ */
+export function isPayrexxResend(url, method, readBody) {
+    if (String(method).toUpperCase() !== 'POST' || !isPayrexxFrameUrl(url))
+        return false;
+    let body;
+    try {
+        body = readBody();
+    }
+    catch {
+        body = null;
+    }
+    if (typeof body !== 'string')
+        return false;
+    const verdict = payrexxBodyVerdict(body);
+    return verdict.verdict === 'refuse' && verdict.code === 'payrexx_three_ds_resend';
+}
+/**
+ * A 3-D Secure send the cardholder's device did not answer with Payrexx's own answer. `reason` is the API's word for
+ * it: `not_picked_up` (no device started it in time: the Vault page was closed or asleep), `not_sent` (the device
+ * refused it before the card left), `no_answer`, `answer_withheld` (Payrexx's answer carried the card),
+ * `answer_refused`, `answer_late`, `response_expired`, or the API's refusal code when it did not take the send at all
+ * (`follow_up_refused`, `follow_up_not_covered`, `follow_up_window_closed`). `cardSent` says whether the card may
+ * have reached Payrexx: false only when the API confirmed it never left the device. Nothing in it names the request,
+ * the card or Payrexx's answer.
+ */
+export class PayrexxFollowUpError extends Error {
+    reason;
+    cardSent;
+    authorizationId;
+    constructor(reason, cardSent, authorizationId) {
+        super(cardSent
+            ? `This Payrexx 3-D Secure request under ${authorizationId} has no answer, and the cardholder's device may have sent it: ${reason}.`
+            : `The cardholder's device did not send this Payrexx 3-D Secure request under ${authorizationId}: ${reason}.`);
+        this.reason = reason;
+        this.cardSent = cardSent;
+        this.authorizationId = authorizationId;
+        this.name = 'PayrexxFollowUpError';
+    }
+}
+/**
+ * What one attachment keeps of its approved Payrexx card request: the request and Payrexx's answer as the page received
+ * them, until when the API said the approval covers sends after it, and the sends it claimed since, in order. Only a
+ * card request whose answer started 3-D Secure (payment-core payrexxAnswerOutcome: pending three_ds) and whose read
+ * named that window (`followUpsUntil`) is kept. Any later Payrexx card request handed over replaces it, a send the
+ * window has passed is never claimed, and once a send is refused or fails the attachment stops (stop()): nothing after
+ * it is claimed, a later approval included.
+ */
+export class PayrexxFollowUps {
+    parent = null;
+    sent = [];
+    stopped = false;
+    /** After a refused or failed send: no later request on this attachment is claimed. */
+    stop() { this.stopped = true; }
+    /**
+     * The approval the remembered card request went under, or null when none is remembered. The gate sends nothing
+     * unless the checkout's own state names this same approval.
+     */
+    get authorizationId() { return this.parent?.authorizationId ?? null; }
+    /**
+     * As the adapter hands an approved card request's answer to the page: before the answer lands, since the page may
+     * start 3-D Secure at once. Every Payrexx card request handed over clears what an earlier one left; only one whose
+     * answer started 3-D Secure, under a read that named the window, is kept.
+     */
+    remember(request, replay) {
+        if (payrexxGateVerdict(request.url, request.body).verdict !== 'card')
+            return;
+        this.parent = null;
+        this.sent = [];
+        const until = typeof replay.followUpsUntil === 'string' ? Date.parse(replay.followUpsUntil) : NaN;
+        if ((replay.mode ?? 'token') !== 'token' || !Number.isFinite(until))
+            return;
+        // No card: this browser only ever held the placeholder.
+        const outcome = payrexxAnswerOutcome(replay.status, replay.body, null);
+        if (outcome.outcome !== 'approved' || outcome.pending !== 'three_ds')
+            return;
+        this.parent = { authorizationId: replay.authorizationId, url: request.url, body: request.body, answer: { status: replay.status, text: replay.body }, until };
+    }
+    /**
+     * The claim for a paused 3-D Secure send the remembered approval covers, or null: no approval covers sends here, its
+     * window has passed, or payment-core's rule refuses the send against the sends already claimed. Synchronous, and it
+     * reserves the send, so two requests can never both be claimed as the next one.
+     */
+    claim(request, now = Date.now()) {
+        const parent = this.parent;
+        if (this.stopped || !parent || now >= parent.until || typeof request.body !== 'string')
+            return null;
+        const verdict = payrexxFollowUpVerdict({
+            parent: { url: parent.url, body: parent.body, answer: parent.answer }, sent: this.sent,
+            request: { url: request.url, method: request.method, body: request.body },
+        });
+        if (!verdict.ok || !PAYREXX_FOLLOW_UP_KINDS.includes(verdict.kind))
+            return null;
+        const entry = { kind: verdict.kind, state: 'pending' };
+        this.sent.push(entry);
+        const contentType = Object.entries(request.headers ?? {}).find(([name]) => /^content-type$/i.test(name))?.[1];
+        return {
+            authorizationId: parent.authorizationId, kind: verdict.kind, until: parent.until,
+            request: { url: request.url, method: 'POST', headers: { 'content-type': typeof contentType === 'string' ? contentType : 'application/x-www-form-urlencoded; charset=UTF-8' },
+                body: request.body },
+            settle(answer) {
+                if (entry.state !== 'pending')
+                    return;
+                // A copy of the answer as it was settled: a caller that changes its own object later changes no claim.
+                if (answer) {
+                    entry.state = 'answered';
+                    entry.answer = { status: answer.status, text: answer.text };
+                }
+                else
+                    entry.state = 'failed';
+            },
+        };
+    }
+}

package/dist/paytrail.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Paytrail's card method (the Visa and Mastercard method on the payment wall most Finnish webshops send the buyer
+ * to), as this SDK reads it.
+ *
+ * The merchant's page, or Paytrail's own wall, posts a card-free entry top-level to
+ * https://services.paytrail.com/payments/<transaction>/click-to-pay/loading-and-redirect: seven fields Paytrail signed
+ * for the merchant, and no card and no amount. Paytrail answers with a loading page whose one form posts the same
+ * fields to .../click-to-pay/initialize-payment, which sends the browser to Payment Highway's card page
+ * (v1.api.paymenthighway.io, Paytrail's card platform) under a session of its own. The entry is the one request this
+ * SDK pauses: the cardholder's device repeats it over the end-to-end TLS relay and follows it to the card page
+ * (payment-core processors/paytrail.js). Everything after it in the agent's browser leads to the card the agent
+ * typed: the loading page's own post opens the card page, and on Payment Highway's host the card post (/card), the
+ * Click to Pay posts (/visa, /mastercard), the 3-D Secure step (/continue), the older card form's post and the card
+ * page's lookup of the typed card's first digits (GET .../acquirerData?bin=...). This SDK aborts every one of them,
+ * so a placeholder card never reaches Payment Highway.
+ *
+ * The hosts are payment-core's PAYTRAIL_HOSTS and PAYMENT_HIGHWAY_HOSTS; paytrail.test.mjs pins the lists together.
+ */
+export declare const PAYTRAIL_PSP = "paytrail";
+export declare const PAYTRAIL_HOSTS: readonly string[];
+export declare const PAYMENT_HIGHWAY_HOSTS: readonly string[];
+/** Whether this URL is on Paytrail's entry host (https, no credentials, any port, a trailing dot or not). */
+export declare function isPaytrailHost(url: string): boolean;
+/** Whether this URL is on Payment Highway's card page host (https, no credentials, any port, a trailing dot or not). */
+export declare function isPaymentHighwayHost(url: string): boolean;
+/**
+ * The only request that is the merchant's entry: a POST to the card method's loading-and-redirect route for one
+ * transaction, written exactly as the method's form action writes it, with the transaction in lowercase and no port,
+ * query, fragment or credentials (payment-core isPaytrailEntryUrl). The entry the SDK pauses; the gate aborts every
+ * other post of the card method.
+ */
+export declare function isPaytrailEntry(url: string, method: string): boolean;
+/**
+ * Whether a request on Paytrail's host belongs to the card method (a /click-to-pay/ route of a payment, in any letter
+ * case): the entry, the loading page's post to initialize-payment, which opens Payment Highway's card page for the
+ * transaction, and any other spelling of either. Another method's form (a bank's) is not.
+ */
+export declare function isPaytrailCardMethodUrl(url: string): boolean;
+/**
+ * The card page's card lookup: a GET on Payment Highway's host to .../acquirerData, which names the first digits of
+ * the card typed so far in its `bin` query. Any other GET there (the card page itself, its scripts and images) is not
+ * a card request.
+ */
+export declare function isPaymentHighwayCardLookup(url: string, method: string): boolean;
+/** Whether this build's registry serves Paytrail's entry, asked with an entry on a transaction no payment holds. */
+export declare function isPaytrailServed(vault: {
+    isCardRequest(url: string, method?: string): boolean;
+}): boolean;
+/**
+ * Whether an adapter must hand this request to the pre-claim gates: it is on Paytrail's host or Payment Highway's, and
+ * this build's registry serves Paytrail's entry. The loading page's post and Payment Highway's card requests are not
+ * the entry, so the registry's card-request test does not name them; the CDP adapter still pauses them through the
+ * recognizer's host and its abort host, and attachToPlaywright's route predicate asks this, so both adapters show the
+ * gates every request to either host once Paytrail is armed.
+ */
+export declare function isArmedPaytrailUrl(vault: {
+    isCardRequest(url: string, method?: string): boolean;
+}, url: string): boolean;

package/dist/paytrail.js

@@ -0,0 +1,98 @@
+/**
+ * Paytrail's card method (the Visa and Mastercard method on the payment wall most Finnish webshops send the buyer
+ * to), as this SDK reads it.
+ *
+ * The merchant's page, or Paytrail's own wall, posts a card-free entry top-level to
+ * https://services.paytrail.com/payments/<transaction>/click-to-pay/loading-and-redirect: seven fields Paytrail signed
+ * for the merchant, and no card and no amount. Paytrail answers with a loading page whose one form posts the same
+ * fields to .../click-to-pay/initialize-payment, which sends the browser to Payment Highway's card page
+ * (v1.api.paymenthighway.io, Paytrail's card platform) under a session of its own. The entry is the one request this
+ * SDK pauses: the cardholder's device repeats it over the end-to-end TLS relay and follows it to the card page
+ * (payment-core processors/paytrail.js). Everything after it in the agent's browser leads to the card the agent
+ * typed: the loading page's own post opens the card page, and on Payment Highway's host the card post (/card), the
+ * Click to Pay posts (/visa, /mastercard), the 3-D Secure step (/continue), the older card form's post and the card
+ * page's lookup of the typed card's first digits (GET .../acquirerData?bin=...). This SDK aborts every one of them,
+ * so a placeholder card never reaches Payment Highway.
+ *
+ * The hosts are payment-core's PAYTRAIL_HOSTS and PAYMENT_HIGHWAY_HOSTS; paytrail.test.mjs pins the lists together.
+ */
+export const PAYTRAIL_PSP = 'paytrail';
+export const PAYTRAIL_HOSTS = Object.freeze(['services.paytrail.com']);
+export const PAYMENT_HIGHWAY_HOSTS = Object.freeze(['v1.api.paymenthighway.io']);
+const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const ENTRY_PATH = new RegExp(`^/payments/${UUID}/click-to-pay/loading-and-redirect$`);
+// The card method's entry on a transaction no payment holds: the URL this build asks its registry about to learn
+// whether the API serves Paytrail's recognizer, which takes any transaction (payment-core isPaytrailEntryUrl).
+const ENTRY_PROBE = 'https://services.paytrail.com/payments/00000000-0000-4000-8000-000000000000/click-to-pay/loading-and-redirect';
+function onHosts(url, hosts) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    return parsed.protocol === 'https:' && !parsed.username && !parsed.password
+        && hosts.includes(parsed.hostname.toLowerCase().replace(/\.$/, '')) ? parsed : null;
+}
+/** Whether this URL is on Paytrail's entry host (https, no credentials, any port, a trailing dot or not). */
+export function isPaytrailHost(url) {
+    return onHosts(url, PAYTRAIL_HOSTS) !== null;
+}
+/** Whether this URL is on Payment Highway's card page host (https, no credentials, any port, a trailing dot or not). */
+export function isPaymentHighwayHost(url) {
+    return onHosts(url, PAYMENT_HIGHWAY_HOSTS) !== null;
+}
+/**
+ * The only request that is the merchant's entry: a POST to the card method's loading-and-redirect route for one
+ * transaction, written exactly as the method's form action writes it, with the transaction in lowercase and no port,
+ * query, fragment or credentials (payment-core isPaytrailEntryUrl). The entry the SDK pauses; the gate aborts every
+ * other post of the card method.
+ */
+export function isPaytrailEntry(url, method) {
+    if (String(method).toUpperCase() !== 'POST' || typeof url !== 'string')
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    return parsed.protocol === 'https:' && PAYTRAIL_HOSTS.includes(parsed.hostname) && ENTRY_PATH.test(parsed.pathname)
+        && !parsed.port && !parsed.username && !parsed.password && parsed.href === url && !/[?#]/.test(url);
+}
+/**
+ * Whether a request on Paytrail's host belongs to the card method (a /click-to-pay/ route of a payment, in any letter
+ * case): the entry, the loading page's post to initialize-payment, which opens Payment Highway's card page for the
+ * transaction, and any other spelling of either. Another method's form (a bank's) is not.
+ */
+export function isPaytrailCardMethodUrl(url) {
+    const parsed = onHosts(url, PAYTRAIL_HOSTS);
+    return parsed !== null && /^\/payments\/[^/]+\/click-to-pay(?:\/|$)/i.test(parsed.pathname);
+}
+/**
+ * The card page's card lookup: a GET on Payment Highway's host to .../acquirerData, which names the first digits of
+ * the card typed so far in its `bin` query. Any other GET there (the card page itself, its scripts and images) is not
+ * a card request.
+ */
+export function isPaymentHighwayCardLookup(url, method) {
+    if (String(method).toUpperCase() !== 'GET')
+        return false;
+    const parsed = onHosts(url, PAYMENT_HIGHWAY_HOSTS);
+    return parsed !== null && (/\/acquirerData\/?$/i.test(parsed.pathname) || parsed.searchParams.has('bin'));
+}
+/** Whether this build's registry serves Paytrail's entry, asked with an entry on a transaction no payment holds. */
+export function isPaytrailServed(vault) {
+    return vault.isCardRequest(ENTRY_PROBE, 'POST');
+}
+/**
+ * Whether an adapter must hand this request to the pre-claim gates: it is on Paytrail's host or Payment Highway's, and
+ * this build's registry serves Paytrail's entry. The loading page's post and Payment Highway's card requests are not
+ * the entry, so the registry's card-request test does not name them; the CDP adapter still pauses them through the
+ * recognizer's host and its abort host, and attachToPlaywright's route predicate asks this, so both adapters show the
+ * gates every request to either host once Paytrail is armed.
+ */
+export function isArmedPaytrailUrl(vault, url) {
+    return (isPaytrailHost(url) || isPaymentHighwayHost(url)) && isPaytrailServed(vault);
+}

package/dist/pre-claim.d.ts

@@ -5,6 +5,7 @@ import { DatatransRepeats } from './datatrans.js';
 import { TokenexIframeRepeats } from './tokenex-iframe.js';
 import { type AciGate } from './aci.js';
 import type { EprotectGate } from './eprotect.js';
+import type { SbpsGate } from './sbps.js';
 import { type ShijiStsCompanions } from './shiji-sts.js';
 import type { CheckoutLifecycle } from './lifecycle.js';
 import { type MerchantProfile } from './merchant-hosted.js';
@@ -16,6 +17,7 @@ import { type VerifoneProfile } from './verifone.js';
 import { type WorldlineMyCheckoutProducts } from './worldline-mycheckout.js';
 import { type PaddleVgsPayGate } from './paddle-vgs-pay.js';
 import { type EbanxFollowUps } from './ebanx.js';
+import { type PayrexxFollowUps } from './payrexx.js';
 /** The native Stripe step the gate claimed, or null when none was: exactly what StripeCheckoutGate.claim returns. */
 type StripeStep = ReturnType<StripeCheckoutGate['claim']>;
 /** A synthetic response a gate fulfills locally. The effect applies CORS and encoding. */
@@ -116,6 +118,20 @@ export interface PreClaimContext {
             headers: Record<string, string>;
             body: string;
         }>;
+        /** VaultClient.sendPayrexxFollowUp: a 3-D Secure send an approved Payrexx card request covers, from the cardholder's device. */
+        sendPayrexxFollowUp?(authorizationId: string, request: {
+            url: string;
+            method: 'POST';
+            headers: Record<string, string>;
+            body: string;
+        }, options?: {
+            signal?: AbortSignal;
+            until?: number;
+        }): Promise<{
+            status: number;
+            headers: Record<string, string>;
+            body: string;
+        }>;
     };
     guards: {
         matches(url: string, method?: string): boolean;
@@ -133,6 +149,8 @@ export interface PreClaimContext {
     replacesNavigationBody?: () => Promise<boolean>;
     /** Worldpay eProtect's hosts; absent or inert until the registry serves eProtect. */
     eprotect?: EprotectGate;
+    /** SB Payment Service's token hosts; absent or inert until the registry serves SBPS. */
+    sbps?: SbpsGate;
     readDocumentUrl: () => Promise<string>;
     lifecycle: CheckoutLifecycle;
     /**
@@ -226,6 +244,12 @@ export interface PreClaimContext {
      * is refused, as before the approval covered them.
      */
     ebanx?: EbanxFollowUps;
+    /**
+     * The attachment's approved Payrexx card request and the 3-D Secure sends claimed under it (payrexx.ts
+     * PayrexxFollowUps). Absent, or holding no approval whose answer started 3-D Secure, and every 3-D Secure send of the
+     * card frame is refused.
+     */
+    payrexx?: PayrexxFollowUps;
 }
 /**
  * The URL an event may name for a request. For an armed merchant profile's
@@ -257,9 +281,11 @@ export declare function isArmedCreditguardCall(vault: {
 export declare const przelewy24PreClaim: PreClaimGate;
 export declare const ekashuPreClaim: PreClaimGate;
 export declare const transbankPreClaim: PreClaimGate;
+export declare const paytrailPreClaim: PreClaimGate;
 export declare const redsysPreClaim: PreClaimGate;
 export declare const quickpayPreClaim: PreClaimGate;
 export declare const comgatePreClaim: PreClaimGate;
+export declare const eximbayPreClaim: PreClaimGate;
 export declare const paypalHostedFieldsPreClaim: PreClaimGate;
 export declare const paypalCardFormsPreClaim: PreClaimGate;
 export declare const cybersourceSecureAcceptancePreClaim: PreClaimGate;
@@ -277,6 +303,7 @@ export declare function routesHipayVault(vault: {
     recognizesProcessor?: (psp: string) => boolean;
 } | null | undefined, url: string): boolean;
 export declare const ebanxPreClaim: PreClaimGate;
+export declare const payrexxPreClaim: PreClaimGate;
 /** The processor gates, in order. A new family adds one entry here; the terminal
  * arbiter runs after all of them and is not part of this list. A gate appended
  * after Stripe is never offered a step Stripe claimed: Stripe answers, aborts or