@zkp2p/pay-shared 4.0.0 → 5.0.0

package/dist/paymentRecovery.js

@@ -0,0 +1,27 @@
+/** Fiat payTo is a protocol hash; the saved quote owns the readable recipient. */
+export function paymentRecoveryRecipient(payment) {
+    const quote = payment.quote;
+    if (typeof quote === 'object' && quote !== null && 'maker' in quote) {
+        const maker = quote.maker;
+        if (typeof maker === 'object' && maker !== null && 'depositData' in maker) {
+            const data = maker.depositData;
+            if (typeof data === 'object' && data !== null && 'offchainId' in data) {
+                const recipient = data.offchainId;
+                if (typeof recipient === 'string' && recipient.trim() !== '')
+                    return recipient;
+            }
+        }
+    }
+    // Historical rows can lack maker data. Never present a bytes32 hash as a name.
+    return /^0x[\da-f]{64}$/i.test(payment.payTo) ? 'Recipient unavailable' : payment.payTo;
+}
+/** Old attempts without a snapshot have no reliable historical requested amount. */
+export function paymentRecoveryAmount(payment) {
+    if (payment.status === 'SETTLED')
+        return Number(payment.paymentAmount) > 0 ? payment.paymentAmount : null;
+    const quote = payment.quote;
+    if (typeof quote !== 'object' || quote === null || !('recoveryDisplayAmount' in quote))
+        return null;
+    const amount = quote.recoveryDisplayAmount;
+    return typeof amount === 'string' && /^\d+(\.\d+)?$/.test(amount) && Number(amount) > 0 ? amount : null;
+}

package/dist/rails.d.ts

@@ -1,4 +1,7 @@
+export declare const ZCASH_RAIL = "near_intents_133701";
 export declare enum SupportedRail {
+    NEAR_INTENTS_ZCASH = "near_intents_133701",
+    APPLE_PAY = "apple_pay",
     VENMO = "venmo",
     CASHAPP = "cashapp",
     REVOLUT = "revolut",
@@ -14,6 +17,7 @@ export declare enum SupportedRail {
     RELAY_137 = "relay_137",
     RELAY_480 = "relay_480",
     RELAY_999 = "relay_999",
+    RELAY_5042 = "relay_5042",
     RELAY_8453 = "relay_8453",
     RELAY_42161 = "relay_42161",
     RELAY_8253038 = "relay_8253038",
@@ -33,6 +37,7 @@ export declare enum SupportedRelayRail {
     RELAY_137 = "relay_137",
     RELAY_480 = "relay_480",
     RELAY_999 = "relay_999",
+    RELAY_5042 = "relay_5042",
     RELAY_8453 = "relay_8453",
     RELAY_42161 = "relay_42161",
     RELAY_8253038 = "relay_8253038",
@@ -43,6 +48,16 @@ export declare const DEFAULT_FIAT_RAILS: readonly SupportedRail[];
 export declare const SUPPORTED_RAILS: readonly SupportedRail[];
 export declare const SUPPORTED_RELAY_RAILS: readonly SupportedRelayRail[];
 export declare const FIAT_SUPPORTED_RAILS: readonly ["venmo", "cashapp", "revolut", "wise", "zelle", "paypal", "monzo", "n26", "chime"];
+/**
+ * Coinbase Apple Pay. A third rail category: it is not a fiat rail (no fiat
+ * payment and no attestation) and not a crypto rail (the customer never sends
+ * crypto). Merchants enable it like any other method, but the resulting payment
+ * is recorded against the Relay rail it settles on, not against this key.
+ */
+export declare const APPLE_PAY_RAIL = SupportedRail.APPLE_PAY;
+export declare const APPLE_PAY_MAX_AMOUNT_USDC_BASE_UNITS = 2500000000n;
+export declare const APPLE_PAY_LIMIT_MESSAGE = "This order exceeds the Apple Pay limit. Choose another payment method.";
+export declare function isOnrampRail(rail: string | null | undefined): boolean;
 export type FiatSupportedRail = typeof FIAT_SUPPORTED_RAILS[number];
 export declare const PAYMENT_PLATFORM_LABELS: Record<string, string>;
 export declare const FIAT_RAIL_DISPLAY_NAMES: Record<FiatSupportedRail, string>;
@@ -82,9 +97,12 @@ export declare function setRuntimeDisabledFiatRails(rails: readonly string[]): v
 export declare function getRuntimeDisabledFiatRails(): string[];
 /** Returns true when the rail targets a crypto chain (legacy numeric or relay-prefixed format). */
 export declare function isCryptoRail(rail: string | null | undefined): boolean;
+/** A rail the customer pays on with fiat: excludes crypto rails and onramp
+ * rails such as Apple Pay, whose payments settle on a Relay rail instead. */
+export declare function isFiatPaymentRail(rail: string | null | undefined): boolean;
 /** Formats a chain id into the canonical relay rail string: `relay_<chainId>`. */
 export declare function formatRelayRail(chainId: number): string;
-/** Normalizes any crypto rail into canonical relay format (or null for non-crypto rails). */
+/** Normalizes a crypto rail into its canonical provider format (or null for non-crypto rails). */
 export declare function normalizeCryptoRail(rail: string | null | undefined): string | null;
 /** Returns the canonical base fiat rail for base rails and supported variants such as `zelle-chase`. */
 export declare function normalizeFiatRail(rail: string | null | undefined): string | null;
@@ -104,7 +122,7 @@ export declare function isSarSupportedFiatRail(rail: string | null | undefined):
  * 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 declare function filterRailsForExclusiveSar(rails: readonly string[]): string[];
+export declare function filterRailsForExclusiveSar<T extends string>(rails: readonly T[]): T[];
 /** Canonical Zelle paymentMethodId -> attestation-service actionType suffix. */
 export declare const ZELLE_METHOD_ACTION_SUFFIX: Record<string, string>;
 /** Strict create-boundary set for Zelle method ids and transitional variant rails. */

package/dist/rails.js

@@ -1,6 +1,10 @@
+import { ZCASH_CHAIN_ID } from './crypto.js';
 const RELAY_RAIL_PREFIX = 'relay_';
+export const ZCASH_RAIL = 'near_intents_133701';
 export var SupportedRail;
 (function (SupportedRail) {
+    SupportedRail["NEAR_INTENTS_ZCASH"] = "near_intents_133701";
+    SupportedRail["APPLE_PAY"] = "apple_pay";
     SupportedRail["VENMO"] = "venmo";
     SupportedRail["CASHAPP"] = "cashapp";
     SupportedRail["REVOLUT"] = "revolut";
@@ -16,6 +20,7 @@ export var SupportedRail;
     SupportedRail["RELAY_137"] = "relay_137";
     SupportedRail["RELAY_480"] = "relay_480";
     SupportedRail["RELAY_999"] = "relay_999";
+    SupportedRail["RELAY_5042"] = "relay_5042";
     SupportedRail["RELAY_8453"] = "relay_8453";
     SupportedRail["RELAY_42161"] = "relay_42161";
     SupportedRail["RELAY_8253038"] = "relay_8253038";
@@ -36,6 +41,7 @@ export var SupportedRelayRail;
     SupportedRelayRail["RELAY_137"] = "relay_137";
     SupportedRelayRail["RELAY_480"] = "relay_480";
     SupportedRelayRail["RELAY_999"] = "relay_999";
+    SupportedRelayRail["RELAY_5042"] = "relay_5042";
     SupportedRelayRail["RELAY_8453"] = "relay_8453";
     SupportedRelayRail["RELAY_42161"] = "relay_42161";
     SupportedRelayRail["RELAY_8253038"] = "relay_8253038";
@@ -68,6 +74,19 @@ export const FIAT_SUPPORTED_RAILS = [
     'n26',
     'chime',
 ];
+/**
+ * Coinbase Apple Pay. A third rail category: it is not a fiat rail (no fiat
+ * payment and no attestation) and not a crypto rail (the customer never sends
+ * crypto). Merchants enable it like any other method, but the resulting payment
+ * is recorded against the Relay rail it settles on, not against this key.
+ */
+export const APPLE_PAY_RAIL = SupportedRail.APPLE_PAY;
+// Peer Pay per-order ceiling, in USDC base units. Coinbase may allow less per buyer.
+export const APPLE_PAY_MAX_AMOUNT_USDC_BASE_UNITS = 2500000000n;
+export const APPLE_PAY_LIMIT_MESSAGE = 'This order exceeds the Apple Pay limit. Choose another payment method.';
+export function isOnrampRail(rail) {
+    return rail === APPLE_PAY_RAIL;
+}
 const PAYMENT_PLATFORM_LABEL_ENTRIES = {
     [SupportedRail.VENMO]: 'Venmo',
     [SupportedRail.CASHAPP]: 'Cash App',
@@ -79,7 +98,10 @@ const PAYMENT_PLATFORM_LABEL_ENTRIES = {
     [SupportedRail.N26]: 'N26',
     [SupportedRail.CHIME]: 'Chime',
 };
-export const PAYMENT_PLATFORM_LABELS = PAYMENT_PLATFORM_LABEL_ENTRIES;
+export const PAYMENT_PLATFORM_LABELS = {
+    ...PAYMENT_PLATFORM_LABEL_ENTRIES,
+    [SupportedRail.APPLE_PAY]: 'Apple Pay',
+};
 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;
@@ -100,6 +122,7 @@ export const RELAY_CHAIN_DISPLAY_NAMES = {
     137: 'Polygon',
     480: 'World Chain',
     999: 'Hyperliquid',
+    5042: 'Arc',
     8453: 'Base',
     42161: 'Arbitrum',
     8253038: 'Bitcoin',
@@ -107,6 +130,8 @@ export const RELAY_CHAIN_DISPLAY_NAMES = {
     792703809: 'Solana',
 };
 const CRYPTO_METHOD_ALIASES = [
+    'zcash',
+    'zec',
     'crypto',
     'usdc',
     'usdt',
@@ -134,20 +159,22 @@ export function parseCryptoRailChainId(rail) {
         return null;
     }
     const trimmed = rail.trim();
+    if (trimmed === ZCASH_RAIL)
+        return ZCASH_CHAIN_ID;
     if (trimmed === '') {
         return null;
     }
     const numericMatch = /^\d+$/.exec(trimmed);
     if (numericMatch !== null) {
         const parsed = Number(trimmed);
-        return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+        return Number.isSafeInteger(parsed) && parsed > 0 && parsed !== ZCASH_CHAIN_ID ? 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;
+    return Number.isSafeInteger(parsed) && parsed > 0 && parsed !== ZCASH_CHAIN_ID ? parsed : null;
 }
 export function isSupportedRail(rail) {
     return SUPPORTED_RAIL_SET.has(rail);
@@ -195,6 +222,11 @@ export function getRuntimeDisabledFiatRails() {
 export function isCryptoRail(rail) {
     return parseCryptoRailChainId(rail) !== null;
 }
+/** A rail the customer pays on with fiat: excludes crypto rails and onramp
+ * rails such as Apple Pay, whose payments settle on a Relay rail instead. */
+export function isFiatPaymentRail(rail) {
+    return !isCryptoRail(rail) && !isOnrampRail(rail);
+}
 /** Formats a chain id into the canonical relay rail string: `relay_<chainId>`. */
 export function formatRelayRail(chainId) {
     if (!Number.isSafeInteger(chainId) || chainId <= 0) {
@@ -202,8 +234,10 @@ export function formatRelayRail(chainId) {
     }
     return `${RELAY_RAIL_PREFIX}${chainId}`;
 }
-/** Normalizes any crypto rail into canonical relay format (or null for non-crypto rails). */
+/** Normalizes a crypto rail into its canonical provider format (or null for non-crypto rails). */
 export function normalizeCryptoRail(rail) {
+    if (rail?.trim() === ZCASH_RAIL)
+        return ZCASH_RAIL;
     const chainId = parseCryptoRailChainId(rail);
     return chainId === null ? null : formatRelayRail(chainId);
 }
@@ -307,7 +341,11 @@ export function getRailDisplayName(rail) {
     if (trimmed === '') {
         return 'Unknown';
     }
+    if (trimmed === ZCASH_RAIL)
+        return 'Zcash (NEAR Intents)';
     const normalized = trimmed.toLowerCase();
+    if (isOnrampRail(normalized))
+        return PAYMENT_PLATFORM_LABELS[APPLE_PAY_RAIL];
     if (isFiatSupportedRail(normalized)) {
         return FIAT_RAIL_DISPLAY_NAMES[normalized];
     }

package/dist/sandboxPricing.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Applies a deterministic per-rail spread (±3%) on top of the live fiat-per-USD
+ * rate so sandbox quotes vary by payment method. The spread is hashed from the
+ * rail identifier + currency so refreshes are stable and different merchants
+ * see consistent rates, without any rail getting an unrealistic 0% spread.
+ */
+export declare function applySandboxRailSpread(baseRate: number, rail: string, currency: string): number;
+/** Deterministic sandbox maker spread and fee-share sizing, shared with the CLI. */
+export declare function buildSandboxSplitFiatAmounts(input: {
+    principalUsd: string;
+    currencyPerUsdRate: string;
+    rail: string;
+    fiatCurrency: string;
+    buyerFeeShareBps: number;
+    totalReferralFeeBps: number;
+}): {
+    paymentAmount: string;
+    grossUsdcAmount: string;
+    conversionRate: string;
+    signalIntentAmountBaseUnits: string;
+};
+/** Preserve the saved signal for a full payment; scale a partial fiat payment at its saved maker rate. */
+export declare function settleSandboxSplitFiatAmounts(input: {
+    signalIntentAmountBaseUnits: string;
+    conversionRateDecimal: string;
+    paidFiatAmount?: string;
+}): {
+    paymentAmount: string;
+    grossUsdcAmount: string;
+};

package/dist/sandboxPricing.js

@@ -0,0 +1,53 @@
+import { computeDisplayedFiatAmount } from './fiatAmount.js';
+const MAX_RAIL_SPREAD = 0.03; // ±3% around the live FX rate
+const SPREAD_BUCKETS = 601; // integer granularity for the deterministic hash
+/**
+ * Applies a deterministic per-rail spread (±3%) on top of the live fiat-per-USD
+ * rate so sandbox quotes vary by payment method. The spread is hashed from the
+ * rail identifier + currency so refreshes are stable and different merchants
+ * see consistent rates, without any rail getting an unrealistic 0% spread.
+ */
+export function applySandboxRailSpread(baseRate, rail, currency) {
+    const seed = `${rail.trim().toLowerCase()}|${currency.trim().toUpperCase()}`;
+    let hash = 0;
+    for (let i = 0; i < seed.length; i += 1) {
+        hash = ((hash * 31) + seed.charCodeAt(i)) | 0;
+    }
+    const bucket = Math.abs(hash) % SPREAD_BUCKETS; // [0, 600]
+    const normalized = (bucket - (SPREAD_BUCKETS - 1) / 2) / ((SPREAD_BUCKETS - 1) / 2); // [-1, 1]
+    const spread = normalized * MAX_RAIL_SPREAD;
+    return baseRate * (1 + spread);
+}
+function decimalUnits(value, decimals) {
+    const [whole, fraction = ''] = value.split('.');
+    return BigInt(whole) * 10n ** BigInt(decimals) + BigInt(fraction.slice(0, decimals).padEnd(decimals, '0'));
+}
+function usdFromUnits(units) {
+    return `${units / 1000000n}.${(units % 1000000n).toString().padStart(6, '0')}`;
+}
+/** Deterministic sandbox maker spread and fee-share sizing, shared with the CLI. */
+export function buildSandboxSplitFiatAmounts(input) {
+    const rawRate = String(applySandboxRailSpread(Number(input.currencyPerUsdRate), input.rail, input.fiatCurrency));
+    const [whole, fraction = ''] = rawRate.split('.');
+    const conversionRate = fraction === '' ? whole : `${whole}.${fraction.slice(0, 6)}`;
+    const rate = decimalUnits(conversionRate, 18);
+    const peg = decimalUnits(input.currencyPerUsdRate, 18);
+    const share = BigInt(input.buyerFeeShareBps);
+    const denominator = (10000n - share) * rate * 10000n + share * (10000n - BigInt(input.totalReferralFeeBps)) * peg;
+    if (denominator <= 0n)
+        throw new Error('Split sandbox quote has no positive principal contribution');
+    const numerator = decimalUnits(input.principalUsd, 6) * 100000000n * peg;
+    const signalIntentAmountBaseUnits = ((numerator + denominator - 1n) / denominator).toString();
+    return { conversionRate, signalIntentAmountBaseUnits,
+        ...settleSandboxSplitFiatAmounts({ signalIntentAmountBaseUnits, conversionRateDecimal: conversionRate }) };
+}
+/** Preserve the saved signal for a full payment; scale a partial fiat payment at its saved maker rate. */
+export function settleSandboxSplitFiatAmounts(input) {
+    const paymentAmount = input.paidFiatAmount ?? computeDisplayedFiatAmount({
+        feePayer: 'SPLIT', signalIntentAmountBaseUnits: input.signalIntentAmountBaseUnits,
+        conversionRateDecimal: input.conversionRateDecimal, remainingUsdcAmount: '1', currencyPerUsdRate: '1', paymentAmountFallback: '0',
+    });
+    const grossUnits = input.paidFiatAmount === undefined ? BigInt(input.signalIntentAmountBaseUnits)
+        : decimalUnits(paymentAmount, 18) * 1000000n / decimalUnits(input.conversionRateDecimal, 18);
+    return { paymentAmount, grossUsdcAmount: usdFromUnits(grossUnits) };
+}

package/dist/tiers.d.ts

@@ -1,9 +1,11 @@
-import { type FeeTranche, type MerchantPaymentFlowModeType, type MerchantTierName } from './types.js';
+import { type FeeTranche, type MerchantEnvironmentType, type MerchantPaymentFlowModeType, type MerchantTierName } from './types.js';
 export type { MerchantTierName } from './types.js';
 export declare const TierChangeSource: {
     readonly SELF_SERVE: "SELF_SERVE";
     readonly ADMIN: "ADMIN";
     readonly MIGRATION: "MIGRATION";
+    /** A Master Merchant Account sub-merchant copied its Master Merchant Account's tier at creation. */
+    readonly SUB_MERCHANT: "SUB_MERCHANT";
 };
 export type TierChangeSourceType = typeof TierChangeSource[keyof typeof TierChangeSource];
 /**
@@ -51,7 +53,16 @@ export declare const TIER_DEFINITIONS: Readonly<Record<MerchantTierName, TierDef
 /** Server-side allowlist for self-serve tier selection — the only authority; `features` copy gates nothing. */
 export declare const SELF_SERVE_TIERS: readonly MerchantTierName[];
 /**
- * Formats a tier's monthly caps for display. `volumeUsdc` is a whole-USDC decimal string;
+ * Scan to Pay depends on seller automated release, which is available to Pro and Concierge merchants.
+ * Sandbox stays available so merchants can complete the no-value onboarding demo
+ * before choosing a live plan.
+ */
+export declare function canUseScanToPay(input: {
+    readonly tier: MerchantTierName | null | undefined;
+    readonly environment: MerchantEnvironmentType;
+}): boolean;
+/**
+ * Formats a tier's monthly caps for display; caps count fiat-paid orders only. `volumeUsdc` is a whole-USDC decimal string;
  * exact thousands render as `$10K`, anything else as `$2,500`.
  */
 export declare function formatTierMonthlyLimitsCopy(limits: TierMonthlyLimits | null): string;

package/dist/tiers.js

@@ -3,6 +3,8 @@ export const TierChangeSource = {
     SELF_SERVE: 'SELF_SERVE',
     ADMIN: 'ADMIN',
     MIGRATION: 'MIGRATION',
+    /** A Master Merchant Account sub-merchant copied its Master Merchant Account's tier at creation. */
+    SUB_MERCHANT: 'SUB_MERCHANT',
 };
 export const TIER_DEFINITIONS = {
     BASE: {
@@ -42,7 +44,15 @@ export const TIER_DEFINITIONS = {
 /** Server-side allowlist for self-serve tier selection — the only authority; `features` copy gates nothing. */
 export const SELF_SERVE_TIERS = ['BASE', 'PRO'];
 /**
- * Formats a tier's monthly caps for display. `volumeUsdc` is a whole-USDC decimal string;
+ * Scan to Pay depends on seller automated release, which is available to Pro and Concierge merchants.
+ * Sandbox stays available so merchants can complete the no-value onboarding demo
+ * before choosing a live plan.
+ */
+export function canUseScanToPay(input) {
+    return input.environment === 'SANDBOX' || input.tier === 'PRO' || input.tier === 'CONCIERGE';
+}
+/**
+ * Formats a tier's monthly caps for display; caps count fiat-paid orders only. `volumeUsdc` is a whole-USDC decimal string;
  * exact thousands render as `$10K`, anything else as `$2,500`.
  */
 export function formatTierMonthlyLimitsCopy(limits) {
@@ -53,5 +63,5 @@ export function formatTierMonthlyLimitsCopy(limits) {
     const volume = whole.length > 3 && /^\d+000$/.test(whole)
         ? `$${whole.slice(0, -3)}K`
         : `$${whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}`;
-    return `Up to ${volume} volume and ${limits.orderCount} orders per month`;
+    return `Up to ${volume} fiat volume and ${limits.orderCount} fiat orders per month`;
 }