@agent-cards/sdk 0.23.20 → 0.23.22

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/pre-claim.d.ts

@@ -2,6 +2,7 @@ import { StripeCheckoutGate } from './stripe-checkout.js';
 import { MercadoCheckoutGate } from './mercado-checkout.js';
 import { type JuspayCheckoutGate } from './juspay-gate.js';
 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 ShijiStsCompanions } from './shiji-sts.js';
@@ -15,6 +16,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. */
@@ -99,7 +101,7 @@ export interface PreClaimContext {
         verifoneProfileOf?(url: string): VerifoneProfile | null;
         cardOnFilePolicy?(url: string, method?: string): string | null;
         withoutCard?(url: string, body: string | null | undefined): 'continue' | 'refuse' | null;
-        /** VaultClient.recognizesProcessor: whether the synced registry serves this processor. */
+        /** VaultClient.recognizesProcessor: whether the synced registry serves this processor (ACI, EBANX, the TokenEx iframe). */
         recognizesProcessor?(psp: string): boolean;
         /** VaultClient.sendEbanxFollowUp: a send an approved EBANX token request covers, from the cardholder's device. */
         sendEbanxFollowUp?(authorizationId: string, request: {
@@ -115,6 +117,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;
@@ -188,6 +204,8 @@ export interface PreClaimContext {
     juspay?: JuspayCheckoutGate;
     /** The attachment's approved Datatrans answers (the repeat rule, datatrans.ts). Absent: none are kept. */
     datatrans?: DatatransRepeats;
+    /** The attachment's approved TokenEx iframe answers (the repeat rule, tokenex-iframe.ts). Absent: none are kept. */
+    tokenexIframe?: TokenexIframeRepeats;
     /** The adapter's identity for the request's frame (CDP frameId, Playwright Frame); undefined when unknown. */
     frame?: unknown;
     /**
@@ -223,6 +241,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
@@ -251,9 +275,13 @@ export declare const fiservPreClaim: PreClaimGate;
 export declare function isArmedCreditguardCall(vault: {
     recognizesProcessor?(psp: string): boolean;
 } | undefined, url: string): boolean;
+export declare const przelewy24PreClaim: PreClaimGate;
 export declare const ekashuPreClaim: PreClaimGate;
+export declare const transbankPreClaim: 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;
@@ -271,6 +299,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