@zkp2p/pay-shared 0.0.2 → 2.0.0

package/dist/rails.js

@@ -0,0 +1,320 @@
+const RELAY_RAIL_PREFIX = 'relay_';
+export var SupportedRail;
+(function (SupportedRail) {
+    SupportedRail["VENMO"] = "venmo";
+    SupportedRail["CASHAPP"] = "cashapp";
+    SupportedRail["REVOLUT"] = "revolut";
+    SupportedRail["ZELLE"] = "zelle";
+    SupportedRail["PAYPAL"] = "paypal";
+    SupportedRail["WISE"] = "wise";
+    SupportedRail["MONZO"] = "monzo";
+    SupportedRail["N26"] = "n26";
+    SupportedRail["CHIME"] = "chime";
+    SupportedRail["RELAY_1"] = "relay_1";
+    SupportedRail["RELAY_10"] = "relay_10";
+    SupportedRail["RELAY_56"] = "relay_56";
+    SupportedRail["RELAY_137"] = "relay_137";
+    SupportedRail["RELAY_480"] = "relay_480";
+    SupportedRail["RELAY_999"] = "relay_999";
+    SupportedRail["RELAY_8453"] = "relay_8453";
+    SupportedRail["RELAY_42161"] = "relay_42161";
+    SupportedRail["RELAY_8253038"] = "relay_8253038";
+    SupportedRail["RELAY_728126428"] = "relay_728126428";
+    SupportedRail["RELAY_792703809"] = "relay_792703809";
+})(SupportedRail || (SupportedRail = {}));
+/**
+ * Canonical relay rails currently supported by zkp2p/pay.
+ *
+ * Chain id source reference:
+ * https://docs.relay.link/references/api/api_resources/supported-chains
+ */
+export var SupportedRelayRail;
+(function (SupportedRelayRail) {
+    SupportedRelayRail["RELAY_1"] = "relay_1";
+    SupportedRelayRail["RELAY_10"] = "relay_10";
+    SupportedRelayRail["RELAY_56"] = "relay_56";
+    SupportedRelayRail["RELAY_137"] = "relay_137";
+    SupportedRelayRail["RELAY_480"] = "relay_480";
+    SupportedRelayRail["RELAY_999"] = "relay_999";
+    SupportedRelayRail["RELAY_8453"] = "relay_8453";
+    SupportedRelayRail["RELAY_42161"] = "relay_42161";
+    SupportedRelayRail["RELAY_8253038"] = "relay_8253038";
+    SupportedRelayRail["RELAY_728126428"] = "relay_728126428";
+    SupportedRelayRail["RELAY_792703809"] = "relay_792703809";
+})(SupportedRelayRail || (SupportedRelayRail = {}));
+export const DEFAULT_FIAT_RAILS = [
+    SupportedRail.VENMO,
+    SupportedRail.CASHAPP,
+    SupportedRail.PAYPAL,
+    SupportedRail.WISE,
+];
+export const SUPPORTED_RAILS = Object.values(SupportedRail);
+export const SUPPORTED_RELAY_RAILS = Object.values(SupportedRelayRail);
+const SUPPORTED_RAIL_SET = new Set(SUPPORTED_RAILS);
+// Globally runtime-disabled fiat rails: removed from new offers/acceptance
+// everywhere isRailRuntimeEnabled / filterRuntimeEnabledRails are consumed,
+// while staying recognized for historical orders. Empty by default; the API
+// seeds this from the DISABLED_RAILS env at boot via setRuntimeDisabledFiatRails.
+// The frontend never sets it, so the browser bundle keeps an empty (no-op) set.
+let runtimeDisabledFiatRails = new Set();
+export const FIAT_SUPPORTED_RAILS = [
+    'venmo',
+    'cashapp',
+    'revolut',
+    'wise',
+    'zelle',
+    'paypal',
+    'monzo',
+    'n26',
+    'chime',
+];
+const PAYMENT_PLATFORM_LABEL_ENTRIES = {
+    [SupportedRail.VENMO]: 'Venmo',
+    [SupportedRail.CASHAPP]: 'Cash App',
+    [SupportedRail.REVOLUT]: 'Revolut',
+    [SupportedRail.WISE]: 'Wise',
+    [SupportedRail.ZELLE]: 'Zelle',
+    [SupportedRail.PAYPAL]: 'PayPal',
+    [SupportedRail.MONZO]: 'Monzo',
+    [SupportedRail.N26]: 'N26',
+    [SupportedRail.CHIME]: 'Chime',
+};
+export const PAYMENT_PLATFORM_LABELS = PAYMENT_PLATFORM_LABEL_ENTRIES;
+export const FIAT_RAIL_DISPLAY_NAMES = PAYMENT_PLATFORM_LABEL_ENTRIES;
+// Shared FE/BE minimum so queries too short for the pg_trgm trigram index are no-ops.
+export const ORDER_SEARCH_MIN_QUERY_LENGTH = 3;
+export function railKeysForQuery(query) {
+    const normalizedQuery = query.trim().toLowerCase();
+    if (normalizedQuery.length === 0) {
+        return [];
+    }
+    return Object.entries(PAYMENT_PLATFORM_LABELS)
+        .filter(([, label]) => label.toLowerCase().includes(normalizedQuery))
+        .map(([key]) => key);
+}
+const SUPPORTED_FIAT_RAILS = new Set(Object.keys(FIAT_RAIL_DISPLAY_NAMES));
+export const RELAY_CHAIN_DISPLAY_NAMES = {
+    1: 'Ethereum',
+    10: 'Optimism',
+    56: 'BNB Smart Chain',
+    137: 'Polygon',
+    480: 'World Chain',
+    999: 'Hyperliquid',
+    8453: 'Base',
+    42161: 'Arbitrum',
+    8253038: 'Bitcoin',
+    728126428: 'Tron',
+    792703809: 'Solana',
+};
+const CRYPTO_METHOD_ALIASES = [
+    'crypto',
+    'usdc',
+    'usdt',
+    ...Object.values(RELAY_CHAIN_DISPLAY_NAMES).map((name) => name.toLowerCase()),
+];
+/**
+ * Surfaces crypto-settled orders for token, chain, and "crypto" prefix queries.
+ */
+export function isCryptoMethodQuery(query) {
+    const normalizedQuery = query.trim().toLowerCase();
+    if (normalizedQuery.length === 0) {
+        return false;
+    }
+    return CRYPTO_METHOD_ALIASES.some((alias) => alias.startsWith(normalizedQuery));
+}
+/**
+ * Normalizes a rail string into a crypto chain id.
+ *
+ * Supports both:
+ * - legacy numeric format: "8453"
+ * - canonical relay format: "relay_8453"
+ */
+export function parseCryptoRailChainId(rail) {
+    if (typeof rail !== 'string') {
+        return null;
+    }
+    const trimmed = rail.trim();
+    if (trimmed === '') {
+        return null;
+    }
+    const numericMatch = /^\d+$/.exec(trimmed);
+    if (numericMatch !== null) {
+        const parsed = Number(trimmed);
+        return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+    }
+    const prefixedMatch = /^relay_(\d+)$/i.exec(trimmed);
+    if (prefixedMatch === null) {
+        return null;
+    }
+    const parsed = Number(prefixedMatch[1]);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+export function isSupportedRail(rail) {
+    return SUPPORTED_RAIL_SET.has(rail);
+}
+export function isFiatSupportedRail(rail) {
+    return FIAT_SUPPORTED_RAILS.includes(rail);
+}
+/** Returns false for rails that remain recognized but are disabled at runtime. */
+export function isRailRuntimeEnabled(rail) {
+    const normalizedFiatRail = normalizeFiatRail(rail);
+    return normalizedFiatRail === null || !runtimeDisabledFiatRails.has(normalizedFiatRail);
+}
+/** Filters out globally disabled runtime rails while preserving caller ordering. */
+export function filterRuntimeEnabledRails(rails) {
+    return rails.filter((rail) => isRailRuntimeEnabled(rail));
+}
+/**
+ * Replaces the set of globally runtime-disabled fiat rails. Only EXACT base
+ * fiat rails are honored (e.g. `venmo`, `paypal`, `zelle`); rail variants
+ * (e.g. `zelle-chase`, or an env typo like `paypal-test`), crypto/relay rails,
+ * and unknown strings are ignored so a malformed env value cannot silently
+ * disable a live rail. Disable is base-granular: disabling `zelle` also
+ * disables its variants at check time (isRailRuntimeEnabled normalizes the
+ * checked rail to its base). Backend-only: the API applies the `DISABLED_RAILS`
+ * env at boot; the frontend never calls this, so its disabled set stays empty.
+ */
+export function setRuntimeDisabledFiatRails(rails) {
+    const next = new Set();
+    for (const rail of rails) {
+        if (typeof rail !== 'string') {
+            continue;
+        }
+        const normalized = rail.trim().toLowerCase();
+        if (isFiatSupportedRail(normalized)) {
+            next.add(normalized);
+        }
+    }
+    runtimeDisabledFiatRails = next;
+}
+/** Returns the currently runtime-disabled fiat rails (canonical base rails). */
+export function getRuntimeDisabledFiatRails() {
+    return [...runtimeDisabledFiatRails];
+}
+/** Returns true when the rail targets a crypto chain (legacy numeric or relay-prefixed format). */
+export function isCryptoRail(rail) {
+    return parseCryptoRailChainId(rail) !== null;
+}
+/** Formats a chain id into the canonical relay rail string: `relay_<chainId>`. */
+export function formatRelayRail(chainId) {
+    if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+        throw new Error(`Invalid chain id for relay rail: ${chainId}`);
+    }
+    return `${RELAY_RAIL_PREFIX}${chainId}`;
+}
+/** Normalizes any crypto rail into canonical relay format (or null for non-crypto rails). */
+export function normalizeCryptoRail(rail) {
+    const chainId = parseCryptoRailChainId(rail);
+    return chainId === null ? null : formatRelayRail(chainId);
+}
+/** Returns the canonical base fiat rail for base rails and supported variants such as `zelle-chase`. */
+export function normalizeFiatRail(rail) {
+    if (typeof rail !== 'string') {
+        return null;
+    }
+    const trimmed = rail.trim().toLowerCase();
+    if (trimmed === '') {
+        return null;
+    }
+    if (SUPPORTED_FIAT_RAILS.has(trimmed)) {
+        return trimmed;
+    }
+    for (const baseRail of SUPPORTED_FIAT_RAILS) {
+        if (trimmed.startsWith(`${baseRail}-`)) {
+            return baseRail;
+        }
+    }
+    return null;
+}
+/**
+ * Fiat rails that support Seller Automated Release (SAR). Merchants in
+ * EXCLUSIVE_SAR mode may only offer these rails; every other fiat rail is
+ * force-disabled in the merchant and admin dashboards.
+ */
+export const SAR_SUPPORTED_FIAT_RAILS = ['venmo', 'cashapp', 'wise', 'paypal'];
+const SAR_SUPPORTED_FIAT_RAIL_SET = new Set(SAR_SUPPORTED_FIAT_RAILS);
+/** Returns true when the fiat rail (incl. variants like `zelle-chase`) supports SAR. */
+export function isSarSupportedFiatRail(rail) {
+    const normalized = normalizeFiatRail(rail);
+    return normalized !== null && SAR_SUPPORTED_FIAT_RAIL_SET.has(normalized);
+}
+/**
+ * Returns `rails` with non-SAR fiat rails removed, preserving crypto/relay rails,
+ * SAR-supported fiat rails, and original ordering. Used to keep an EXCLUSIVE_SAR
+ * merchant's `enabledRails` in sync with their quote preference: non-SAR fiat
+ * rails (e.g. `zelle`, `revolut`, incl. variants like `zelle-chase`) are dropped
+ * while crypto rails and SAR rails (venmo/cashapp/wise/paypal) are kept.
+ */
+export function filterRailsForExclusiveSar(rails) {
+    return rails.filter((rail) => {
+        const normalizedFiat = normalizeFiatRail(rail);
+        // Non-fiat (crypto/relay) or unrecognized rails are preserved verbatim.
+        if (normalizedFiat === null) {
+            return true;
+        }
+        // Recognized fiat rail: keep only if it supports SAR.
+        return SAR_SUPPORTED_FIAT_RAIL_SET.has(normalizedFiat);
+    });
+}
+/** Canonical Zelle paymentMethodId -> attestation-service actionType suffix. */
+export const ZELLE_METHOD_ACTION_SUFFIX = {
+    'zelle-bofa': 'bofa',
+    'zelle-chase': 'chase',
+    'zelle-citi': 'citi',
+};
+/** Strict create-boundary set for Zelle method ids and transitional variant rails. */
+export const ZELLE_PAYMENT_METHOD_IDS = new Set(Object.keys(ZELLE_METHOD_ACTION_SUFFIX));
+/** Bank-qualified buyer TEE action types accepted for generic Zelle proofs. */
+export const ZELLE_BUYER_TEE_ACTION_TYPES = new Set(Object.values(ZELLE_METHOD_ACTION_SUFFIX).map((suffix) => `transfer_zelle_${suffix}`));
+/**
+ * Resolves the attestation-service verifier route (`platform` + `actionType`)
+ * for a persisted `payment.rail` value.
+ *
+ * Zelle variants map to the new generic `zelle` platform with a bank-qualified
+ * actionType. Legacy bank-specific verifier routes are drain-only and should
+ * stay outside shared core. Non-Zelle fiat rails use the base rail as platform
+ * and `transfer_{rail}` as actionType. Unknown / crypto rails fall back to the
+ * raw trimmed rail so callers still surface a verifier mismatch via the
+ * attestation response rather than silently mis-routing.
+ */
+export function resolveAttestationRoute(rail) {
+    const trimmed = typeof rail === 'string' ? rail.trim().toLowerCase() : '';
+    // TRANSITIONAL: rail-variant fold, delete after drain window.
+    const zelleVariantSuffix = ZELLE_METHOD_ACTION_SUFFIX[trimmed];
+    if (zelleVariantSuffix !== undefined) {
+        return { platform: 'zelle', actionType: `transfer_zelle_${zelleVariantSuffix}` };
+    }
+    const baseRail = normalizeFiatRail(trimmed) ?? trimmed;
+    return { platform: baseRail, actionType: `transfer_${baseRail}` };
+}
+/** Canonical generic Zelle on-chain method hash: keccak256("zelle"), lowercase. */
+export const GENERIC_ZELLE_PAYMENT_METHOD_HASH = '0xf752c7d19698ecb0bb8988abf9b9a53a4c3657f3bc8850a6fb59fdf3e3ce8cd3';
+/** Case-insensitive check that a hash is the canonical generic Zelle on-chain method hash. */
+export function isGenericZellePaymentMethodHash(hash) {
+    return typeof hash === 'string'
+        && hash.trim().toLowerCase() === GENERIC_ZELLE_PAYMENT_METHOD_HASH;
+}
+/** True when the rail is Zelle (generic or a bank variant). */
+export function isZelleRail(rail) {
+    return normalizeFiatRail(rail) === 'zelle';
+}
+/** Formats a rail value for human-readable UI labels. */
+export function getRailDisplayName(rail) {
+    if (typeof rail !== 'string') {
+        return 'Unknown';
+    }
+    const trimmed = rail.trim();
+    if (trimmed === '') {
+        return 'Unknown';
+    }
+    const normalized = trimmed.toLowerCase();
+    if (isFiatSupportedRail(normalized)) {
+        return FIAT_RAIL_DISPLAY_NAMES[normalized];
+    }
+    const chainId = parseCryptoRailChainId(trimmed);
+    if (chainId !== null) {
+        const chainName = RELAY_CHAIN_DISPLAY_NAMES[chainId] ?? `Chain ${chainId}`;
+        return `Relay (${chainName})`;
+    }
+    return trimmed.toUpperCase();
+}