@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/pelecard.js

@@ -0,0 +1,42 @@
+// Pelecard Iframe/Redirect 2.0 (psp `pelecard`): the hosted payment page Uman tourist tax
+// (aumantax.com) loads in an iframe, served from gateway21.pelecard.biz (gateway20 on older
+// terminals). The page sends the card in one same-origin jQuery XHR, POST /PaymentGW/Transaction,
+// whose flat JSON body carries the card at CreditCardNumber, CreditCardDate (MMYY) and CvvNumber
+// and names no amount: the merchant's server bound the total, the currency and the action type
+// to the page's TransactionId when it created the payment. This module holds what the SDK
+// decides about that request. The rules themselves are payment-core's (pelecard.generated.ts):
+// the API applies the same ones at create, and the cardholder's device applies them again
+// before it writes a card.
+//
+// The processor ships dark. The API serves the pelecard recognizer only to a build that declares
+// the `pelecard_transaction` capability (client.ts SUPPORTED_CAPABILITIES), and only for an org
+// Agentcard enabled for Pelecard, so an SDK that has not synced, or that runs for any other org,
+// never recognizes a Pelecard host and leaves its requests alone.
+import { PELECARD_TRANSACTION_HOSTS, pelecardTransactionRefusal } from './pelecard.generated.js';
+export const PELECARD_PSP = 'pelecard';
+/** The dark-launch capability the API serves the pelecard recognizer behind. */
+export const PELECARD_CAPABILITY = 'pelecard_transaction';
+/** True when the URL's host is one of Pelecard's two payment page hosts. */
+export function isPelecardHost(url) {
+    try {
+        return PELECARD_TRANSACTION_HOSTS.includes(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The pause decision for a card-carrying POST the registry recognized on a Pelecard host. Null
+ * when it is the page's own one-time new-card submission, which pauses for approval; otherwise
+ * the reason it is refused. It judges the whole request (the exact URL, the page's JSON content
+ * type with Payment.js's own `charse0t` spelling, jQuery's X-Requested-With, and a body of the
+ * page's own keys) with payment-core's pelecardTransactionRefusal, the check the API runs at
+ * create and the device runs before it writes a card. It never passes keep-on-file consent:
+ * that waits for an approval that asks the cardholder.
+ */
+export function pelecardRefusal(request) {
+    const refusal = pelecardTransactionRefusal({ url: request.url, method: 'POST', headers: request.headers ?? {}, body: request.body ?? '' });
+    if (refusal === null)
+        return null;
+    return refusal === 'keep_on_file' ? 'pelecard_keep_on_file_unsupported' : 'invalid_pelecard_request';
+}

package/dist/pre-claim.d.ts

@@ -1,8 +1,17 @@
 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 { type AciGate } from './aci.js';
+import type { EprotectGate } from './eprotect.js';
+import { type ShijiStsCompanions } from './shiji-sts.js';
 import type { CheckoutLifecycle } from './lifecycle.js';
 import { type MerchantProfile } from './merchant-hosted.js';
 import type { MerchantHandoffWatch } from './merchant-handoff.js';
+import { type CybersourceFlexDecision, type CybersourceFlexPause, type FlexRequest } from './cybersource-flex.js';
+import { type CardEndpointProfile } from './card-endpoint.js';
+import { type PayrailsSessionCapture, type PayrailsSidecar } from './payrails.js';
+import { type VerifoneProfile } from './verifone.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. */
@@ -17,16 +26,22 @@ type PreClaimEvent = {
     detail?: unknown;
 };
 /** How the request was resolved. continue/answer/abort are already performed by the
- * time the decision is returned; only pause hands work back to the adapter. */
+ * time the decision is returned; only pause hands work back to the adapter, with the
+ * CyberSource Flex sidecar when the Flex gate paused it. */
 export type PreClaimDecision = {
     kind: 'continue';
 } | {
     kind: 'abort';
 } | {
     kind: 'answer';
-} | {
+}
+/** `payrails`: the session key a bound Payrails card save carries onto the create. */
+ | {
     kind: 'pause';
     stripeStep: StripeStep;
+    cybersourceFlex?: CybersourceFlexPause;
+    cardEndpoint?: CardEndpointProfile;
+    payrails?: PayrailsSidecar;
 };
 /** The adapter mechanics a gate performs. Each is awaited where the inline code
  * awaited it; none swallow their own transport failure (a gate adds a .catch
@@ -49,22 +64,45 @@ export interface PreClaimContext {
     /** The adapters expose headers and body as getters, read inside the gate that
      * needs them: Playwright's postData() can throw, and Mercado reads the body in
      * its own try, so that failure stops the native checkout instead of rejecting
-     * the route handler with the request neither aborted nor reported. */
+     * the route handler with the request neither aborted nor reported. `body` is ''
+     * for a request with no body, and null when the adapter knows the request carries
+     * a body it could not read (CDP: hasPostData with no bytes, a blob or a file).
+     * Playwright cannot tell those two apart (its postData() is null for both), so
+     * attachToPlaywright hands a gate that null for either, and '' for either at an
+     * armed Verifone merchant's origin. */
     request: {
         url: string;
         method: string;
         headers: Record<string, string>;
         body: string | null;
+        /** The request is a frame's navigation (CDP resourceType Document, Playwright isNavigationRequest). Only the ACI gate reads it. */
+        navigation?: boolean;
     };
+    /** cardOnFilePolicy: the policy the API served with the request's recognizer (VaultClient); absent reads as none.
+     * withoutCard is VaultClient's own (card-fields.js requestWithoutCard); optional so a test double may omit it. */
     vault: {
         isCardRequest(url: string, method?: string): boolean;
         merchantProfileOf?(url: string): MerchantProfile | null;
+        verifoneProfileOf?(url: string): VerifoneProfile | null;
+        cardOnFilePolicy?(url: string, method?: string): string | null;
+        withoutCard?(url: string, body: string | null | undefined): 'continue' | 'refuse' | null;
     };
     guards: {
         matches(url: string, method?: string): boolean;
     };
     mercado: MercadoCheckoutGate;
     stripe: StripeCheckoutGate;
+    /** ACI's split card; absent or inert until the registry serves ACI. */
+    aci?: AciGate;
+    /**
+     * Whether this browser sends the body the SDK replaced on a navigation, which removing the
+     * placeholder expiry from ACI's classic-mode /payment needs: true on the CDP adapter, which
+     * drives Chromium; the Playwright adapter asks the page's engine (aci.ts
+     * playwrightReplacesNavigationBody). Absent reads as no, so that /payment is refused.
+     */
+    replacesNavigationBody?: () => Promise<boolean>;
+    /** Worldpay eProtect's hosts; absent or inert until the registry serves eProtect. */
+    eprotect?: EprotectGate;
     readDocumentUrl: () => Promise<string>;
     lifecycle: CheckoutLifecycle;
     /** isEngaged and observeUnprepared are called only for an armed merchant profile's card request or a Fiserv card capture. */
@@ -90,10 +128,51 @@ export interface PreClaimContext {
     /** The paused request itself is gone (Playwright only); CDP returns false. */
     requestInactive: () => boolean;
     awaitingApproval: () => boolean;
+    /**
+     * The URLs of the frame that sent the request and of every frame above it, sender first, or
+     * undefined when the adapter cannot read them: Playwright walks the request's frame up through
+     * its parents, CDP reads the frame trees of the paused session and of each session above it.
+     * Read only for a Nuvei card request whose Origin or Referer does not already name PPS (see
+     * nuveiPreClaim), so no other request waits on it.
+     */
+    initiatorFrames?: () => readonly string[] | undefined | Promise<readonly string[] | undefined>;
     /** Set by the Stripe gate; read by the terminal arbiter and carried into a pause. */
     stripeStep: StripeStep;
     /** The merchant-hosted hand-off this attachment made, if any (merchant-handoff.ts). */
     merchantHandoff?: Pick<MerchantHandoffWatch, 'retried'>;
+    /**
+     * The adapter's reader of the Microform field iframe that sent a request (cybersource-flex.ts):
+     * CDP judges from the committed frame URLs it recorded, Playwright from request.frame().url().
+     * Absent, no CyberSource Flex request can pause: each one the registry recognizes is refused.
+     */
+    cybersourceFlex?: {
+        judge(request: FlexRequest): CybersourceFlexDecision | Promise<CybersourceFlexDecision>;
+    };
+    /**
+     * The attachment's Juspay gate (juspay-gate.ts). Absent, or off because the registry does not
+     * serve the Juspay recognizer, and every request to a Juspay host is judged as it was before.
+     */
+    juspay?: JuspayCheckoutGate;
+    /** The attachment's approved Datatrans answers (the repeat rule, datatrans.ts). Absent: none are kept. */
+    datatrans?: DatatransRepeats;
+    /** The adapter's identity for the request's frame (CDP frameId, Playwright Frame); undefined when unknown. */
+    frame?: unknown;
+    /**
+     * The Payrails sessions the adapter captured, or null (or absent) when it captures none: the
+     * synced registry does not pause Payrails' save, so the Payrails gate defers every request.
+     */
+    payrails?: PayrailsSessionCapture | null;
+    /**
+     * The attachment's Shiji STS getCvvId companion and the adapter's opaque id
+     * for the page or frame this request came from (shiji-sts.ts), read when the
+     * request is judged (attachToPlaywright reads the frame's document, so it
+     * answers asynchronously). Absent, a getCvvId has nothing to bind to and is
+     * refused.
+     */
+    shijiSts?: {
+        companions: ShijiStsCompanions;
+        page: () => string | Promise<string>;
+    };
 }
 /**
  * The URL an event may name for a request. For an armed merchant profile's
@@ -104,11 +183,13 @@ export interface PreClaimContext {
  */
 export declare function eventUrl(vault: {
     merchantProfileOf?(url: string): MerchantProfile | null;
+    verifoneProfileOf?(url: string): VerifoneProfile | null;
 } | undefined, url: string): string;
 /** A gate returns a decision when it handles the request, undefined to defer to
  * the next gate, or a promise of either when it must do I/O first. */
 export type PreClaimGate = (ctx: PreClaimContext) => PreClaimDecision | undefined | Promise<PreClaimDecision | undefined>;
 export declare const MERCHANT_BODY_UNREADABLE = "the paused request carries no body the SDK could read, so Agentcard cannot tell whether it carries a card";
+export declare const verifonePreClaim: PreClaimGate;
 export declare const fiservPreClaim: 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