@agent-cards/sdk 0.21.0 → 0.22.0

package/dist/prepared-processor.js

@@ -7,30 +7,81 @@ import { checkoutComPreparationUrl, isPreparedCheckoutComRequest } from './check
 import { classifyDeclaredMerchantRequest, classifyMerchantRequest } from './merchant-hosted.js';
 import { fiservCapturePinId, fiservPreparationUrl, isPreparedFiservRequest } from './fiserv.js';
 import { cybersourceFlexPreparationUrl, isPreparedCybersourceFlexRequest } from './cybersource-flex.generated.js';
+import { isPreparedAciRequest } from './aci.generated.js';
+import { CREDITGUARD_SANDBOX_HOST, creditguardPageProcessUrl, creditguardPreparationEnvironment, creditguardProcessRefusal, creditguardProcessTxId, } from './creditguard.generated.js';
+import { eprotectPreparationUrl, isPreparedEprotectRequest } from './eprotect.generated.js';
+import { amadeusEnvironment, amadeusPreparationUrls, amadeusRequestRefusal, isPreparedAmadeusRequest } from './amadeus-checkout.generated.js';
+import { isPreparedVerifoneRequest } from './verifone.js';
 export function preparationMode(psp) {
-    return psp === 'adyen' || psp === 'fiserv' ? 'cse' : 'token';
+    return psp === 'adyen' || psp === 'fiserv' || psp === 'verifone' ? 'cse' : 'token';
+}
+/** The method of the native card request a preparation binds: the registration GET for Worldpay eProtect, a POST for every other processor. */
+export function preparationRequestMethod(psp) {
+    return psp === 'worldpay_eprotect' ? 'GET' : 'POST';
 }
 /**
  * Shared endpoint processors cannot attest test/live mode from their URL or key prefix.
  * Adyen can: test and live are separate hosts and key prefixes. Fiserv's are separate
  * hosts too: connect (production) and connect-cert (sandbox). So are CyberSource
  * Flex's: flex.cybersource.com is live, testflex.cybersource.com is test, and each has
- * its own signing keys.
+ * its own signing keys. A Verifone preparation pays in the environment of the key its reviewed
+ * profile pins.
  */
 export function validPreparationEnvironment(psp, environment) {
     if (psp === 'bambora' || psp === 'mercado_pago' || psp === 'recurly' || psp === 'spreedly')
         return environment === 'shared';
-    return ['square', 'braintree', 'worldpay', 'adyen', 'checkout_com', 'paysafe', 'fiserv', 'cybersource_flex'].includes(psp) && ['production', 'sandbox'].includes(environment);
+    return ['square', 'braintree', 'worldpay', 'adyen', 'checkout_com', 'paysafe', 'fiserv', 'cybersource_flex', 'aci', 'creditguard', 'worldpay_eprotect', 'amadeus_checkout', 'verifone'].includes(psp) && ['production', 'sandbox'].includes(environment);
+}
+/**
+ * ACI's prepared endpoint, the literal the API names (backend checkout-prepared-processor.ts): its
+ * environment's primary widget host and a checkout id that can never be real, since the merchant
+ * mints the checkout only at Pay time. The bind matches the card-number request by host
+ * environment and shape instead (matchesPreparedRequest).
+ */
+export function aciPreparationUrl(environment) {
+    return `https://${environment === 'production' ? 'eu-prod' : 'eu-test'}.oppwa.com/v1/checkouts/prepared`;
+}
+/**
+ * A processor whose card request names an id the merchant mints only at Pay time (ACI's checkout
+ * id), so no URL can be prepared in advance: whether the adapters can intercept it is asked of the
+ * registry (VaultClient.recognizesProcessor), not of the prepared endpoint.
+ */
+export function preparationBindsByShape(psp) {
+    return psp === 'aci';
+}
+/**
+ * The endpoint a CreditGuard preparation stands for, per environment, as the API advertises it: the
+ * PPS card submit on pps (production) or ppsuat (sandbox) under the nil transaction id. It only
+ * proves the synced registry recognizes CreditGuard. A real submit names the txId of the page the
+ * preparation framed and may be on pps2, so it is matched by shape (matchesPreparedRequest), never
+ * by equality with this URL.
+ */
+export function creditguardPreparationUrl(environment) {
+    const host = environment === 'sandbox' ? CREDITGUARD_SANDBOX_HOST : 'pps.creditguard.co.il';
+    return `https://${host}/services/v1/txn/00000000-0000-0000-0000-000000000000/process`;
 }
 export function preparationEndpoint(psp, environment) {
     if (!validPreparationEnvironment(psp, environment))
         throw new Error('unsupported_preparation_processor');
     if (psp === 'cybersource_flex')
         return cybersourceFlexPreparationUrl(environment);
+    if (psp === 'creditguard')
+        return creditguardPreparationUrl(environment);
+    if (psp === 'worldpay_eprotect')
+        return eprotectPreparationUrl(environment);
+    // A Verifone endpoint is its reviewed profile's leg, never one per environment (verifone.ts).
+    if (psp === 'verifone')
+        throw new Error('unsupported_preparation_processor');
     if (psp === 'paysafe')
         return paysafePreparationUrl(environment);
     if (psp === 'fiserv')
         return fiservPreparationUrl(environment);
+    if (psp === 'aci')
+        return aciPreparationUrl(environment);
+    // The SDK's pay URL on the environment's first path, as the API names it. It only tells prepare()
+    // the processor is armed; the claim takes every exact card URL of that environment.
+    if (psp === 'amadeus_checkout')
+        return amadeusPreparationUrls(environment)[0];
     if (psp === 'checkout_com')
         return checkoutComPreparationUrl(environment);
     if (psp === 'adyen')
@@ -91,8 +142,57 @@ function freshCardBody(psp, body) {
         return false;
     return true;
 }
-/** Processor identity and environment are part of the device's prior consent. */
-export function matchesPreparedRequest(psp, environment, requestUrl, method, body, headers) {
+/**
+ * CreditGuard PPS: the host's environment (ppsuat sandbox, pps and pps2 production) is the
+ * preparation's, the submit is the /process URL of the page the preparation read, on that page's
+ * own host and for its txId, and the request is the page's own new-card submit exactly as the
+ * device will judge it, with ppDomain bound to the approved merchant page. A saved card, a wallet,
+ * a refused flag, another transaction or another PPS host never spends consent.
+ */
+function matchesPreparedCreditguard(environment, requestUrl, body, headers, binding) {
+    let hostname = '', merchantHost = '';
+    try {
+        hostname = new URL(requestUrl).hostname;
+        merchantHost = new URL(binding.merchantOrigin ?? '').hostname;
+    }
+    catch {
+        return false;
+    }
+    if (creditguardPreparationEnvironment(hostname) !== environment)
+        return false;
+    const page = typeof binding.paymentPageUrl === 'string' ? creditguardPageProcessUrl(binding.paymentPageUrl) : null;
+    const txId = creditguardProcessTxId(requestUrl);
+    if (page === null || txId === null || page !== requestUrl)
+        return false;
+    return creditguardProcessRefusal({ url: requestUrl, method: 'POST', headers, body: body ?? '' }, { merchantHost }) === null;
+}
+/**
+ * The approved merchant page's host, with its port if it has one: what the Amadeus SDK sends in its
+ * Amadeus-Checkout-Sdk-Host header (location.host). Null for anything but an http(s) origin. The
+ * API's twin (checkout-prepared-processor.ts) reads the same value.
+ */
+export function merchantHostOf(merchantOrigin) {
+    try {
+        const url = new URL(merchantOrigin ?? '');
+        return (url.protocol === 'https:' || url.protocol === 'http:') && url.host ? url.host.toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Processor identity and environment are part of the device's prior consent. `binding` carries what
+ * the preparation fixed beyond them (PreparedRequestBinding); Amadeus binds its SDK's Host header to
+ * `binding.merchantOrigin`, the origin the cardholder approved, and fails without one.
+ */
+export function matchesPreparedRequest(psp, environment, requestUrl, method, body, headers, binding = {}) {
+    // The one prepared GET: the registration itself, bodyless, on the approved environment's host,
+    // naming the paypageId the preparation carries (payment-core isPreparedEprotectRequest, the rule
+    // the API and the Vault bind with too). A preparation that carries none never matches.
+    if (psp === 'worldpay_eprotect') {
+        return validPreparationEnvironment(psp, environment)
+            && isPreparedEprotectRequest(requestUrl, method.toUpperCase(), body ?? '', environment, binding.paypageId ?? null);
+    }
     if (method.toUpperCase() !== 'POST' || !validPreparationEnvironment(psp, environment))
         return false;
     // CyberSource Flex: this environment's exact tokens URL, application/jwt with only the headers a
@@ -100,6 +200,11 @@ export function matchesPreparedRequest(psp, environment, requestUrl, method, bod
     // Flex gate verified the issuing field iframe's capture context against that JWE's key.
     if (psp === 'cybersource_flex')
         return isPreparedCybersourceFlexRequest(requestUrl, method.toUpperCase(), body ?? null, environment, headers);
+    if (psp === 'creditguard')
+        return matchesPreparedCreditguard(environment, requestUrl, body, headers, binding);
+    // A Verifone request is judged only through the profile its preparation names (matchesPreparation).
+    if (psp === 'verifone')
+        return false;
     if (psp === 'paysafe')
         return isPreparedPaysafeRequest(requestUrl, method, body ?? null, environment, headers);
     // Fiserv: that environment's card-capture endpoint exactly, the capture rules on the whole
@@ -107,6 +212,14 @@ export function matchesPreparedRequest(psp, environment, requestUrl, method, bod
     // and for the merchant the body names (payment-core isPreparedFiservRequest).
     if (psp === 'fiserv')
         return isPreparedFiservRequest(requestUrl, method.toUpperCase(), body ?? null, environment, headers);
+    // ACI binds the exact card-number request of a checkout on a host of the prepared environment
+    // (payment-core isPreparedAciRequest, the rule the API and the Vault bind with too).
+    if (psp === 'aci')
+        return isPreparedAciRequest({ url: requestUrl, method: method.toUpperCase(), body: body ?? null, headers }, environment);
+    if (psp === 'amadeus_checkout') {
+        const merchantHost = merchantHostOf(binding.merchantOrigin);
+        return merchantHost !== null && isPreparedAmadeusRequest(requestUrl, method, body ?? null, environment, headers, { merchantHost });
+    }
     if (psp === 'checkout_com')
         return isPreparedCheckoutComRequest(requestUrl, method, body ?? null, environment, headers);
     if (psp === 'adyen')
@@ -167,8 +280,18 @@ export function matchesPreparedMerchantRequest(profileId, requestUrl, method, bo
  * the one its envelope's key is pinned as for its endpoint and merchant, must be that
  * pin, as the API's bind requires. Two pins in one environment (a merchant's old and new
  * keys during a rotation) never spend each other's approval. No other processor names one.
+ * A CreditGuard preparation binds the merchant page it approved and the page it framed
+ * (merchantOrigin, paymentPageUrl), which matchesPreparedRequest holds the submit to.
+ * A Worldpay eProtect preparation names the paypageId its registration must carry.
+ * An Amadeus preparation binds its SDK's Host header to the page the cardholder approved
+ * (merchantOrigin), as the API does.
  */
 export function matchesPreparation(preparation, requestUrl, method, body, headers) {
+    // A Verifone preparation pays only its profile's reviewed leg, as payment-core pauses it.
+    if (preparation.psp === 'verifone') {
+        return typeof preparation.merchantProfile === 'string' && method.toUpperCase() === 'POST'
+            && isPreparedVerifoneRequest(requestUrl, 'POST', body ?? null, preparation.merchantProfile);
+    }
     if (preparation.psp === 'fiserv') {
         if (!matchesPreparedRequest(preparation.psp, preparation.environment, requestUrl, method, body, headers))
             return false;
@@ -178,5 +301,23 @@ export function matchesPreparation(preparation, requestUrl, method, body, header
         return preparation.psp === 'adyen'
             && matchesPreparedMerchantRequest(preparation.merchantProfile, requestUrl, method, body, preparation.sandboxDeclaration);
     }
-    return matchesPreparedRequest(preparation.psp, preparation.environment, requestUrl, method, body, headers);
+    return matchesPreparedRequest(preparation.psp, preparation.environment, requestUrl, method, body, headers, { merchantOrigin: preparation.merchantOrigin, paymentPageUrl: preparation.paymentPageUrl, paypageId: preparation.paypageId });
+}
+/**
+ * The reason a claim reports for a request its preparation does not match. An Amadeus preparation
+ * names what payment-core's Amadeus check refused on its own environment's card URL, as
+ * `amadeus_<reason>`: Air France's and KLM's add, whose expiry their own form keeps, is
+ * `amadeus_merchant_held_expiry`, every Data Collection Page store is
+ * `amadeus_dcp_field_config_unreviewed` until a merchant's field config is reviewed, and a Host
+ * header that does not name the approved page is `amadeus_header_binding`. Everything else, another
+ * processor's request or the other environment's host included, is `checkout_changed`.
+ */
+export function preparedRequestRefusal(psp, environment, requestUrl, body, headers, merchantOrigin) {
+    if (psp !== 'amadeus_checkout' || amadeusEnvironment(requestUrl) !== environment)
+        return 'checkout_changed';
+    const merchantHost = merchantHostOf(merchantOrigin);
+    if (merchantHost === null)
+        return 'amadeus_header_binding';
+    const reason = amadeusRequestRefusal({ url: requestUrl, method: 'POST', body: body ?? null, headers }, null, { merchantHost });
+    return typeof reason === 'string' ? `amadeus_${reason}` : 'checkout_changed';
 }

package/dist/primer.d.ts

@@ -0,0 +1,53 @@
+export declare const PRIMER_PSP = "primer";
+/** The dark-launch capability a build declares when it judges every Primer request with classifyPrimerRequest. */
+export declare const PRIMER_CAPABILITY = "primer_payment_instruments";
+/**
+ * Why a Primer request was aborted as an unsupported checkout, reported as the `reason` of the
+ * `unsupported_checkout` event and of the attachment's `unsupported` state:
+ *   unsupported_primer_sdk      a card request from Primer Checkout (primer-js), whose request gives
+ *                               up after 30 seconds, or any SDK that is not the legacy v2 controller
+ *   unsupported_primer_request  a card request the legacy v2 controller would not send: another URL
+ *                               spelling on the pci host, another header or body shape
+ */
+export type PrimerUnsupportedReason = 'unsupported_primer_sdk' | 'unsupported_primer_request';
+/**
+ * Why a single Primer request was aborted alone, reported as the detail of a `blocked` event; the
+ * attachment is not held, so the next request is judged again:
+ *   primer_keep_on_file          the body asks Primer to save the card for later charges
+ *   unreadable_primer_request    the adapter could not read the body
+ */
+export type PrimerBlockedReason = 'primer_keep_on_file' | 'unreadable_primer_request';
+/** What the pre-claim gate does with a request on a Primer pci host. */
+export type PrimerVerdict = {
+    kind: 'defer';
+} | {
+    kind: 'block';
+    reason: PrimerBlockedReason;
+} | {
+    kind: 'unsupported';
+    reason: PrimerUnsupportedReason;
+};
+/** True for a URL on one of Primer's two pci hosts, whatever its path. */
+export declare function isPrimerPciHost(rawUrl: string): boolean;
+/**
+ * The gate's verdict for a POST the registry recognized on a Primer pci host: defer (a new card,
+ * which the arbiter pauses, or a body with no card, which the card-field rule continues), block it
+ * alone, or abort it as an unsupported checkout. A decision that throws refuses.
+ */
+export declare function primerRequestVerdict(request: {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body: string | null;
+}): PrimerVerdict;
+/**
+ * The only answer the page may receive for an approved Primer request: status 200 or 201 and
+ * Primer's single-use card token rebuilt from payment-core's allow-list (sanitizePrimerResponse),
+ * under a JSON content type. Null for anything else: another status, a multi-use token or vaultData
+ * (the card was saved), a field out of bounds, a body that does not parse.
+ */
+export declare function primerTokenAnswer(status: number, body: string): {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+} | null;

package/dist/primer.generated.d.ts

@@ -0,0 +1,38 @@
+declare var PRIMER_PCI_HOSTS: readonly string[];
+declare var PRIMER_TOKENIZE_PATH: string;
+declare var PRIMER_REFUSAL_REASONS: readonly string[];
+declare var PRIMER_PROVABLE_NETWORKS: readonly string[];
+declare function isPrimerTokenizeUrl(url: any, method?: string): boolean;
+declare function primerBodyRefusal(body: any): "unsupported" | "keep_on_file" | null;
+declare function isPrimerNewCardBody(body: any): boolean;
+declare function primerKeepOnFileRequested(body: any): boolean | null;
+declare function classifyPrimerRequest(url: any, method: any, body: any, headers: any): "card" | "unsupported" | "keep_on_file" | "unsupported_sdk" | null;
+declare function primerTokenizeRefusal(request: any): "unsupported" | "keep_on_file" | "unsupported_sdk" | null;
+declare function isPrimerTokenizeRequest(request: any): boolean;
+declare function primerRefusalMessage(reason: any): string;
+declare function primerCardNetwork(number: any): "VISA" | "AMEX" | "MASTERCARD" | null;
+declare function primerNetworkRefusal(body: any, card: any): "unsupported" | "network_mismatch" | null;
+declare function injectPrimerCard(body: any, card: any): {
+    body: string;
+    where: string[];
+};
+declare function primerErrorId(body: any): any;
+declare function primerResponseOutcome(status: any, body: any, card: any): {
+    outcome: string;
+    code: any;
+    reason?: undefined;
+} | {
+    outcome: string;
+    reason: string;
+    code?: undefined;
+} | {
+    outcome: string;
+    code?: undefined;
+    reason?: undefined;
+};
+declare function sanitizePrimerResponse(body: any): string;
+declare function primerFacts(status: any, body: any): {
+    outcome: string;
+    refusalCode: any;
+};
+export { PRIMER_PCI_HOSTS, PRIMER_PROVABLE_NETWORKS, PRIMER_REFUSAL_REASONS, PRIMER_TOKENIZE_PATH, classifyPrimerRequest, injectPrimerCard, isPrimerNewCardBody, isPrimerTokenizeRequest, isPrimerTokenizeUrl, primerBodyRefusal, primerCardNetwork, primerErrorId, primerFacts, primerKeepOnFileRequested, primerNetworkRefusal, primerRefusalMessage, primerResponseOutcome, primerTokenizeRefusal, sanitizePrimerResponse };