@zkp2p/pay-shared 4.0.1 → 6.0.0

package/dist/fees.d.ts

@@ -24,4 +24,6 @@ export declare function resolveExactTokenGrossAmountUsdc(config: ReferralFeeConf
 export declare function resolveMaxFeeConfig(config: MaxFeeConfig, amountUsd: string): {
     maxFeePercentage: number;
 };
+/** Split endpoints use exactly the established merchant/buyer pricing paths. */
+export declare function resolveEffectiveFeePayer(feePayer: 'MERCHANT' | 'PAYEE' | 'SPLIT', buyerFeeShareBps: number): 'MERCHANT' | 'PAYEE' | 'SPLIT';
 export {};

package/dist/fees.js

@@ -193,3 +193,13 @@ export function resolveMaxFeeConfig(config, amountUsd) {
         maxFeePercentage: config.tranches[matchedTrancheIndex].value,
     };
 }
+/** Split endpoints use exactly the established merchant/buyer pricing paths. */
+export function resolveEffectiveFeePayer(feePayer, buyerFeeShareBps) {
+    if (feePayer !== 'SPLIT')
+        return feePayer;
+    if (buyerFeeShareBps === 0)
+        return 'MERCHANT';
+    if (buyerFeeShareBps === 10000)
+        return 'PAYEE';
+    return 'SPLIT';
+}

package/dist/fiatAmount.d.ts

@@ -1,5 +1,6 @@
 export interface DisplayedFiatAmountInput {
-    readonly feePayer: 'MERCHANT' | 'PAYEE';
+    readonly buyerFiatAmount?: string | null;
+    readonly feePayer: 'MERCHANT' | 'PAYEE' | 'SPLIT';
     readonly signalIntentAmountBaseUnits: string | null;
     readonly conversionRateDecimal: string | null;
     readonly remainingUsdcAmount: string;
@@ -8,12 +9,16 @@ export interface DisplayedFiatAmountInput {
 }
 /**
  * The exact fiat amount the buyer is instructed to pay, as a decimal string.
- * BYTE-IDENTICAL to checkoutData.ts mapCheckoutPaymentToQuote (lines 336-351):
- *   quotedFiatAmount (PAYEE ceil-cents, else null)
- *     ?? (validRemaining&Rate ? (remaining*rate).toFixed(2) : paymentAmount)
+ * Shared by checkout rendering and seller verification:
+ *   PAYEE and SPLIT use the persisted quote, rounded upward to fiat cents.
+ *   MERCHANT: remaining amount at the FX peg, or the actual settled payment amount.
  * Always returns a string; the API caller passes it to fiatMinorUnitsFromDisplayedAmount,
  * which returns null for an unusable "0"/malformed value so the API fails SAR closed.
  */
 export declare function computeDisplayedFiatAmount(input: DisplayedFiatAmountInput): string;
 /** Parse a 2-decimal (or fewer) positive decimal string to integer minor units. Null if non-positive/malformed/>2dp. */
 export declare function fiatMinorUnitsFromDisplayedAmount(displayed: string): bigint | null;
+/** Buyer/merchant share of the difference between paid value and merchant net. */
+export declare function computeSplitFeeContribution(buyerValueUsd: string, netMerchantUsd: string, buyerFeeShareBps: number, quotedBridgeSpreadBps?: string): string;
+/** Reads the server-owned buyer amount from a persisted quote. */
+export declare function readQuoteBuyerFiatAmount(quote: unknown): string | undefined;

package/dist/fiatAmount.js

@@ -28,18 +28,29 @@ function centsToDecimalString(cents) {
 }
 /**
  * The exact fiat amount the buyer is instructed to pay, as a decimal string.
- * BYTE-IDENTICAL to checkoutData.ts mapCheckoutPaymentToQuote (lines 336-351):
- *   quotedFiatAmount (PAYEE ceil-cents, else null)
- *     ?? (validRemaining&Rate ? (remaining*rate).toFixed(2) : paymentAmount)
+ * Shared by checkout rendering and seller verification:
+ *   PAYEE and SPLIT use the persisted quote, rounded upward to fiat cents.
+ *   MERCHANT: remaining amount at the FX peg, or the actual settled payment amount.
  * Always returns a string; the API caller passes it to fiatMinorUnitsFromDisplayedAmount,
  * which returns null for an unusable "0"/malformed value so the API fails SAR closed.
  */
 export function computeDisplayedFiatAmount(input) {
-    const quotedCents = input.feePayer === 'PAYEE' && input.signalIntentAmountBaseUnits !== null && input.conversionRateDecimal !== null
+    if (input.buyerFiatAmount != null && input.feePayer !== 'MERCHANT') {
+        const cents = fiatMinorUnitsFromDisplayedAmount(input.buyerFiatAmount);
+        if (cents === null)
+            throw new Error('Buffered quote buyer amount must be positive fiat cents');
+        return centsToDecimalString(cents);
+    }
+    const quotedCents = input.feePayer !== 'MERCHANT' && input.signalIntentAmountBaseUnits !== null && input.conversionRateDecimal !== null
         ? ceilCentsFromSignalIntent(input.signalIntentAmountBaseUnits, input.conversionRateDecimal)
         : null;
     if (quotedCents !== null)
         return centsToDecimalString(quotedCents);
+    if (input.feePayer === 'SPLIT') {
+        if (Number(input.remainingUsdcAmount) <= 0)
+            return input.paymentAmountFallback;
+        throw new Error('Split pricing requires the persisted signal amount and conversion rate');
+    }
     const remainingUsdc = Number(input.remainingUsdcAmount);
     const rate = Number(input.currencyPerUsdRate);
     if (Number.isFinite(remainingUsdc) && Number.isFinite(rate) && remainingUsdc > 0 && rate > 0) {
@@ -56,3 +67,28 @@ export function fiatMinorUnitsFromDisplayedAmount(displayed) {
     const cents = BigInt(whole) * CENT_SCALE + BigInt(fraction.padEnd(2, '0'));
     return cents > 0n ? cents : null;
 }
+/** Buyer/merchant share of the difference between paid value and merchant net. */
+export function computeSplitFeeContribution(buyerValueUsd, netMerchantUsd, buyerFeeShareBps, quotedBridgeSpreadBps = '0') {
+    const paid = parseDecimalToScaledUnits(buyerValueUsd, 6);
+    const net = parseDecimalToScaledUnits(netMerchantUsd, 6);
+    if (paid === null || net === null)
+        throw new Error('Split fee contribution requires nonnegative decimal amounts');
+    const bridge = parseDecimalToScaledUnits(quotedBridgeSpreadBps, 18);
+    if (bridge === null)
+        throw new Error('Quoted bridge spread must be a nonnegative decimal');
+    const bridgeDenominator = 10000n * RATE_SCALE + bridge;
+    const units = (paid * BigInt(10000 - buyerFeeShareBps) * bridgeDenominator
+        + net * BigInt(buyerFeeShareBps) * 10000n * RATE_SCALE) / (10000n * bridgeDenominator);
+    return `${units / USDC_SCALE}.${(units % USDC_SCALE).toString().padStart(6, '0')}`;
+}
+/** Reads the server-owned buyer amount from a persisted quote. */
+export function readQuoteBuyerFiatAmount(quote) {
+    if (typeof quote !== 'object' || quote === null || !('amountAdjustment' in quote))
+        return undefined;
+    const adjustment = quote.amountAdjustment;
+    if (typeof adjustment !== 'object' || adjustment === null || !('buyerFiatAmount' in adjustment)
+        || typeof adjustment.buyerFiatAmount !== 'string') {
+        throw new Error('Buffered quote is missing its buyer fiat amount');
+    }
+    return adjustment.buyerFiatAmount;
+}

package/dist/index.d.ts

@@ -1,17 +1,23 @@
 export * from './types.js';
+export * from './paymentRecovery.js';
 export * from './chains.js';
 export * from './fees.js';
 export * from './crypto.js';
 export * from './rails.js';
+export * from './cashoutRails.js';
 export * from './buyerTee.js';
 export * from './bitcoin.js';
 export * from './addressValidators.js';
 export { doubleSha256, encodeBase58 } from './addressEncoding.js';
 export * from './fiatAmount.js';
+export * from './sandboxPricing.js';
 export * from './paypalSarPhase.js';
 export * from './paypalSarVerify.js';
 export * from './payeeFeeCap.js';
 export * from './onboarding.js';
 export * from './llmIntegration.js';
 export * from './tiers.js';
+export * from './masterMerchantSubMerchants.js';
 export * from './attribution.js';
+export * from './conciergeIntake.js';
+export * from './clientTelemetry.js';

package/dist/index.js

@@ -1,17 +1,23 @@
 export * from './types.js';
+export * from './paymentRecovery.js';
 export * from './chains.js';
 export * from './fees.js';
 export * from './crypto.js';
 export * from './rails.js';
+export * from './cashoutRails.js';
 export * from './buyerTee.js';
 export * from './bitcoin.js';
 export * from './addressValidators.js';
 export { doubleSha256, encodeBase58 } from './addressEncoding.js';
 export * from './fiatAmount.js';
+export * from './sandboxPricing.js';
 export * from './paypalSarPhase.js';
 export * from './paypalSarVerify.js';
 export * from './payeeFeeCap.js';
 export * from './onboarding.js';
 export * from './llmIntegration.js';
 export * from './tiers.js';
+export * from './masterMerchantSubMerchants.js';
 export * from './attribution.js';
+export * from './conciergeIntake.js';
+export * from './clientTelemetry.js';

package/dist/llmIntegration.d.ts

@@ -105,7 +105,3 @@ export type SandboxTestOrderResponse = {
     readonly status: string;
     readonly paymentId: string;
 };
-export type LlmIntegrationPromptResponse = {
-    readonly prompt: string;
-    readonly filename: string;
-};

package/dist/masterMerchantSubMerchants.d.ts

@@ -0,0 +1,74 @@
+/** The highest master merchant fee in bps, the referral-split schema's per-entry and total ceiling. */
+export declare const MASTER_MERCHANT_FEE_MAX_BPS = 5000;
+/** A Master Merchant Account sub merchant's ownership as its Master Merchant Account sees it. PR 5 reports only OWNED_BY_MASTER_MERCHANT; PR 6 fills the others. */
+export declare const SubMerchantTransferState: {
+    readonly OWNED_BY_MASTER_MERCHANT: "OWNED_BY_MASTER_MERCHANT";
+    readonly PENDING: "PENDING";
+    readonly TRANSFERRED: "TRANSFERRED";
+};
+export type SubMerchantTransferStateType = typeof SubMerchantTransferState[keyof typeof SubMerchantTransferState];
+export type SubMerchantTransfer = {
+    state: typeof SubMerchantTransferState.OWNED_BY_MASTER_MERCHANT;
+} | {
+    state: typeof SubMerchantTransferState.PENDING;
+    recipientEmail: string;
+    expiresAt: string;
+} | {
+    state: typeof SubMerchantTransferState.TRANSFERRED;
+    recipientEmail: string;
+    acceptedAt: string;
+};
+/** One row of GET /merchants/me/sub-merchants, also the POST response. */
+export type SubMerchantSummary = {
+    id: string;
+    name: string;
+    createdAt: string;
+    masterMerchantFeeBps: number;
+    ownerEmail: string;
+    transfer: SubMerchantTransfer;
+};
+export type SubMerchantListResponse = {
+    subMerchants: SubMerchantSummary[];
+};
+export type CreateSubMerchantRequest = {
+    name: string;
+    masterMerchantFeeBps: number;
+};
+export type SetMasterMerchantFeeRequest = {
+    masterMerchantFeeBps: number;
+};
+export type MasterMerchantFeeResult = {
+    subMerchantId: string;
+    masterMerchantFeeBps: number;
+};
+export type BpsRange = {
+    min: number;
+    max: number;
+};
+/** Configured fees for one enabled rail: Peer's platform fee across its tranches, and that plus the master merchant fee. */
+export type MasterMerchantFeePreviewRail = {
+    rail: string;
+    platformFeeBps: BpsRange;
+    totalFeeBps: BpsRange;
+};
+/** The first amount band (inclusive USD bounds; null max = open-ended) where configured fees exceed the max fee. */
+export type MasterMerchantMaxFeeViolation = {
+    rail: string;
+    minAmountUsd: string;
+    maxAmountUsd: string | null;
+    platformFeeBps: number;
+    splitFeeBps: number;
+    maxFeePercentage: number;
+};
+export type MasterMerchantFeePreviewResponse = {
+    masterMerchantFeeBps: number;
+    /** Null means no Master Merchant Account-specific cap. */
+    masterMerchantMaxFeeBps: number | null;
+    rails: MasterMerchantFeePreviewRail[];
+    maxFeeViolation: MasterMerchantMaxFeeViolation | null;
+};
+export declare const MASTER_MERCHANT_NOT_ENABLED_MESSAGE = "This merchant is not enabled as a Master Merchant Account";
+export declare const MASTER_MERCHANT_FEE_LOCKED_TRANSFERRED_MESSAGE = "This sub merchant now belongs to someone else; only an admin can change its master merchant fee";
+export declare const MASTER_MERCHANT_FEE_LOCKED_PENDING_MESSAGE = "Cancel the pending ownership transfer before changing the master merchant fee";
+export declare function formatMasterMerchantFeeExceedsCapMessage(masterMerchantFeeBps: number, masterMerchantMaxFeeBps: number): string;
+export declare function formatMasterMerchantMaxFeeViolationMessage(violation: MasterMerchantMaxFeeViolation): string;

package/dist/masterMerchantSubMerchants.js

@@ -0,0 +1,20 @@
+/** The highest master merchant fee in bps, the referral-split schema's per-entry and total ceiling. */
+export const MASTER_MERCHANT_FEE_MAX_BPS = 5000;
+/** A Master Merchant Account sub merchant's ownership as its Master Merchant Account sees it. PR 5 reports only OWNED_BY_MASTER_MERCHANT; PR 6 fills the others. */
+export const SubMerchantTransferState = {
+    OWNED_BY_MASTER_MERCHANT: 'OWNED_BY_MASTER_MERCHANT',
+    PENDING: 'PENDING',
+    TRANSFERRED: 'TRANSFERRED',
+};
+export const MASTER_MERCHANT_NOT_ENABLED_MESSAGE = 'This merchant is not enabled as a Master Merchant Account';
+export const MASTER_MERCHANT_FEE_LOCKED_TRANSFERRED_MESSAGE = 'This sub merchant now belongs to someone else; only an admin can change its master merchant fee';
+export const MASTER_MERCHANT_FEE_LOCKED_PENDING_MESSAGE = 'Cancel the pending ownership transfer before changing the master merchant fee';
+export function formatMasterMerchantFeeExceedsCapMessage(masterMerchantFeeBps, masterMerchantMaxFeeBps) {
+    return `Master merchant fee ${masterMerchantFeeBps} bps exceeds the ${masterMerchantMaxFeeBps} bps cap`;
+}
+export function formatMasterMerchantMaxFeeViolationMessage(violation) {
+    const band = violation.maxAmountUsd === null
+        ? `$${violation.minAmountUsd} and above`
+        : `$${violation.minAmountUsd}–$${violation.maxAmountUsd}`;
+    return `Configured fees on ${violation.rail} for orders of ${band} would be ${violation.platformFeeBps + violation.splitFeeBps} bps, above the ${violation.maxFeePercentage}% max fee`;
+}

package/dist/onboarding.js

@@ -70,10 +70,11 @@ export const ONBOARDING_STEP_REGISTRY = [
     {
         id: OnboardingStepId.RAILS,
         paths: 'ALL',
-        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        // Merchants start with default rails, so there is nothing to observe: the step is done once the
+        // merchant confirms their payment methods. The dashboard wizard acknowledges it after saving them.
+        verifiedBy: OnboardingStepVerifiedBy.MANUAL,
         inChecklist: false,
-        // This step is unconditionally satisfied and carries no information, so allowing
-        // it to imply earlier steps would mark every merchant's onboarding complete.
+        // Confirming payment methods says nothing about the profile or industry.
         impliesPrevious: false,
     },
     { id: OnboardingStepId.PATH, paths: 'ALL', verifiedBy: OnboardingStepVerifiedBy.AUTO, inChecklist: true, impliesPrevious: true },
@@ -158,11 +159,11 @@ export const ONBOARDING_STEP_REGISTRY = [
     },
 ];
 const autoStepPredicates = {
-    [OnboardingStepId.PROFILE]: (facts) => facts.hasName && facts.hasLogo,
+    // The logo is optional: the wizard acknowledges the profile once the merchant confirms a name.
+    [OnboardingStepId.PROFILE]: (facts) => facts.hasName && (facts.hasLogo || facts.manualSteps.includes(OnboardingStepId.PROFILE)),
     [OnboardingStepId.INDUSTRY]: (facts) => facts.hasIndustry,
     [OnboardingStepId.PLAN]: (facts) => facts.hasSelectedTier,
     [OnboardingStepId.PATH]: (facts) => facts.hasIntegrationPath,
-    [OnboardingStepId.RAILS]: () => true,
     [OnboardingStepId.INTEGRATION]: (facts) => facts.hasSandboxFulfilledOrder,
     [OnboardingStepId.WEBHOOK]: (facts) => facts.hasWebhook,
     [OnboardingStepId.TEST_ORDER]: (facts) => facts.hasSandboxFulfilledOrder,

package/dist/payeeFeeCap.d.ts

@@ -18,4 +18,14 @@ export declare function resolvePayeeReferralFeeCapacity(input: {
     readonly platformRecipient: string;
     readonly referralFees: readonly PayeeFeeEntry[];
 }): PayeeReferralFeeCapacityResult;
+export declare class QuoteAmountCapacityError extends RangeError {
+}
+/** Preserve the full-size quote's net settlement by reducing only Peer's fee. */
+export declare function resolveQuoteAmountFeeCapacity(input: {
+    readonly requestedSignalAmountRaw: string;
+    readonly grossSignalAmountRaw: string;
+    readonly quotedTokenOutputAmountRaw: string;
+    readonly platformRecipient: string;
+    readonly referralFees: readonly PayeeFeeEntry[];
+}): PayeeFeeEntry[];
 export declare function computeNetAfterPreciseFees(grossAmount: string, feeRates18dec: readonly string[]): string;

package/dist/payeeFeeCap.js

@@ -50,6 +50,26 @@ export function resolvePayeeReferralFeeCapacity(input) {
         requiredNetCovered,
     };
 }
+export class QuoteAmountCapacityError extends RangeError {
+}
+/** Preserve the full-size quote's net settlement by reducing only Peer's fee. */
+export function resolveQuoteAmountFeeCapacity(input) {
+    const requested = BigInt(input.requestedSignalAmountRaw);
+    const gross = BigInt(input.grossSignalAmountRaw);
+    const output = BigInt(input.quotedTokenOutputAmountRaw);
+    const nominalFees = input.referralFees.reduce((total, fee) => total + requested * BigInt(fee.feeBps) / BPS_DENOMINATOR, 0n);
+    const capacity = resolvePayeeReferralFeeCapacity({
+        grossSignalAmount: gross.toString(),
+        quotedTokenOutput: output.toString(),
+        requiredNetAmount: (output + requested - gross - nominalFees).toString(),
+        platformRecipient: input.platformRecipient,
+        referralFees: input.referralFees,
+    });
+    if (capacity.insufficientCapacity || !capacity.requiredNetCovered) {
+        throw new QuoteAmountCapacityError('Insufficient Peer fee capacity for quote amount shortfall');
+    }
+    return capacity.referralFees;
+}
 export function computeNetAfterPreciseFees(grossAmount, feeRates18dec) {
     const gross = parsePositiveUnits(grossAmount, 'gross amount');
     const totalFees = feeRates18dec.reduce((total, feeRate) => {

package/dist/paymentRecovery.d.ts

@@ -0,0 +1,26 @@
+/** Customer-safe history. No quote/proof payloads or executable payment instructions. */
+export type PaymentRecoveryAttempt = {
+    id: string;
+    rail: string;
+    currency: string;
+    amount: string | null;
+    recipient: string;
+    status: string;
+    createdAt: string;
+    expiresAt: string;
+};
+export type PaymentRecoveryHistory = {
+    attempts: PaymentRecoveryAttempt[];
+    nextCursor: string | null;
+};
+/** Fiat payTo is a protocol hash; the saved quote owns the readable recipient. */
+export declare function paymentRecoveryRecipient(payment: {
+    payTo: string;
+    quote: unknown;
+}): string;
+/** Old attempts without a snapshot have no reliable historical requested amount. */
+export declare function paymentRecoveryAmount(payment: {
+    status: string;
+    paymentAmount: string;
+    quote: unknown;
+}): string | null;

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;
+};