@agent-cards/sdk 0.23.22 → 0.23.23

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';
@@ -148,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;
     /**
@@ -278,6 +281,7 @@ 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;

package/dist/pre-claim.js

@@ -80,6 +80,7 @@ import { cardEndpointCarriesCard, cardEndpointDetail, cardEndpointFor, cardEndpo
 import { cardEndpointStoppedPage, refusedNavigationOutcome } from './card-endpoint-page.js';
 import { PAYRAILS_HOLDING_REASONS, PAYRAILS_SESSION_MESSAGE, isPayrailsHost, isPayrailsPaymentUrl, isPayrailsStaticHost, payrailsKeyRefusal, payrailsPaymentRefusal, payrailsRequestKind, payrailsSaveRefusal, } from './payrails.js';
 import { classifyVerifoneProfileRequest, verifoneTemplatedUrl } from './verifone.js';
+import { isPaymentHighwayCardLookup, isPaymentHighwayHost, isPaytrailCardMethodUrl, isPaytrailEntry, isPaytrailServed } from './paytrail.js';
 import { ekashuEntryUrl, isEkashuEntry, isEkashuHost } from './ekashu.js';
 import { isArmedTransbankUrl } from './transbank.js';
 import { isRedsysEntry, isRedsysHost, redsysEntryUrl } from './redsys.js';
@@ -1509,6 +1510,23 @@ const eprotectPreClaim = (ctx) => {
         return eprotectFailoverAbort(ctx);
     return unsupportedAbort(ctx);
 };
+// SB Payment Service, once the registry serves it (a synced build that declares its capability, for
+// an org the API enabled); for every other client the gate defers on everything, so nothing changes.
+// On SBPS's token hosts:
+//   - the token request GET the recognizer admits defers to the arbiter, which pauses it for the vault
+//     claim flow; one the registry does not cover aborts as unsupported instead of reaching SBPS;
+//   - any other request on /token/generateToken (another method, query or spelling) aborts as an
+//     unsupported checkout, so the placeholder's ciphertext never leaves;
+//   - everything else there (the scripts, the 3-D Secure info request) continues.
+// Synchronous for a token request, so it pauses in the microtask it paused in.
+const sbpsPreClaim = (ctx) => {
+    const request = ctx.sbps?.classify(ctx.request.url, ctx.request.method);
+    if (!request || request.kind === 'sibling')
+        return undefined;
+    if (request.kind === 'token_request')
+        return ctx.vault.isCardRequest(ctx.request.url, ctx.request.method) ? undefined : unsupportedAbort(ctx);
+    return unsupportedAbort(ctx);
+};
 async function eprotectFailoverAbort(ctx) {
     ctx.onEvent?.({ type: 'blocked', detail: 'eprotect_failover_aborted' });
     await ctx.effects.abort();
@@ -1699,6 +1717,32 @@ export const transbankPreClaim = (ctx) => {
         return undefined;
     return processorPageAbort(ctx);
 };
+// Paytrail's card method (paytrail.ts). Once this build's registry serves Paytrail's entry (a capability the API serves
+// only to a company Agentcard turned Paytrail on for), every request to Paytrail's entry host and to Payment Highway's
+// card page host pauses, and this gate judges the card method's posts and the card page's card lookup:
+//   - the merchant's entry (the card method's loading-and-redirect route for one transaction, exactly) defers, and the
+//     terminal arbiter pauses it for the claim flow like any card request: the cardholder's device pays it;
+//   - every other post of the card method on Paytrail's host (the loading page's post to initialize-payment, which
+//     opens Payment Highway's card page, or the entry in another spelling) aborts as an unsupported checkout, and so do
+//     every POST to Payment Highway (the card post, the Click to Pay posts, the 3-D Secure step, the older card form's
+//     post) and the card page's GET that looks up the typed card's first digits, so Payment Highway never sees the card
+//     the agent typed. The agent's browser reaches Payment Highway only when the entry was not paused (an attachment
+//     made too late, say), and then only the cardholder's device can pay.
+// Any other request (another payment method's form, the card page itself, its scripts and images) is not this gate's
+// and continues. With Paytrail not served, the entry is no card request, the gate defers, and every request continues
+// as before. Synchronous until it must abort, like every gate. Exported for the gate registry's tests.
+export const paytrailPreClaim = (ctx) => {
+    const { url, method } = ctx.request;
+    const post = String(method).toUpperCase() === 'POST';
+    const paymentHighway = isPaymentHighwayHost(url) && (post || isPaymentHighwayCardLookup(url, method));
+    if (!paymentHighway && !(post && isPaytrailCardMethodUrl(url)))
+        return undefined;
+    if (!isPaytrailServed(ctx.vault))
+        return undefined;
+    if (isPaytrailEntry(url, method))
+        return undefined;
+    return processorPageAbort(ctx);
+};
 // Redsys's hosted payment page (redsys.ts). Once this build's registry serves Redsys's entry (a
 // capability the API serves only to a company Agentcard turned Redsys on for), every request to
 // Redsys's hosts pauses, and this gate judges the POSTs:
@@ -2438,8 +2482,8 @@ async function unsupportedContinue(ctx) {
  * 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
  * pauses each one itself. */
-export const PSP_PRE_CLAIM_GATES = [cardEndpointResendPreClaim, cardEndpointPreClaim, mercadoPreClaim, juspayPreClaim, braintreePreClaim, stripePreClaim, merchantHostedPreClaim, verifonePreClaim, fiservPreClaim, gmoPreClaim, cybersourceFlexPreClaim, datatransPreClaim, tokenexIframePreClaim, pelecardPreClaim, aciPreClaim, creditguardPreClaim, primerPreClaim, payrailsPreClaim, convergePreClaim, eprotectPreClaim, wspayPreClaim, shijiStsPreClaim, ekashuPreClaim, redsysPreClaim, quickpayPreClaim, comgatePreClaim, przelewy24PreClaim, transbankPreClaim, eximbayPreClaim, paypalHostedFieldsPreClaim,
-    paypalCardFormsPreClaim, cybersourceSecureAcceptancePreClaim, worldlineMyCheckoutPreClaim, paddleVgsPayPreClaim, ebanxPreClaim, payrexxPreClaim, hipayPreClaim];
+export const PSP_PRE_CLAIM_GATES = [cardEndpointResendPreClaim, cardEndpointPreClaim, mercadoPreClaim, juspayPreClaim, braintreePreClaim, stripePreClaim, merchantHostedPreClaim, verifonePreClaim, fiservPreClaim, gmoPreClaim, cybersourceFlexPreClaim, datatransPreClaim, tokenexIframePreClaim, pelecardPreClaim, aciPreClaim, creditguardPreClaim, primerPreClaim, payrailsPreClaim, convergePreClaim, eprotectPreClaim, sbpsPreClaim, wspayPreClaim, shijiStsPreClaim, ekashuPreClaim, redsysPreClaim, quickpayPreClaim, comgatePreClaim, przelewy24PreClaim, transbankPreClaim, eximbayPreClaim, paypalHostedFieldsPreClaim,
+    paypalCardFormsPreClaim, cybersourceSecureAcceptancePreClaim, worldlineMyCheckoutPreClaim, paddleVgsPayPreClaim, ebanxPreClaim, payrexxPreClaim, hipayPreClaim, paytrailPreClaim];
 /** Run each gate in order; the first to return a decision wins. If none does,
  * the terminal arbiter decides between continue, abort (unsupported) and pause.
  * Returns synchronously while every gate defers synchronously (an ordinary card