@zkp2p/pay-shared 4.0.1 → 5.0.0

package/README.md

@@ -9,7 +9,7 @@ Shared TypeScript types, enums, and chain utilities used by ZKP2P Pay API, SDK,
 ## Install
 
 ```bash
-npm install @zkp2p/pay-shared@4.0.1
+npm install @zkp2p/pay-shared@5.0.0
 ```
 
 ## Published artifacts
@@ -115,5 +115,5 @@ Chain constants and helpers:
 ## Notes
 
 - Amount fields are strings to preserve precision across APIs and clients.
-- Canonical order/payment amounts are available on `CheckoutOrder` and `CheckoutPayment` (for example `requestedUsdcAmount`, `remainingUsdcAmount`, `netSettledUsdcAmount`).
+- Canonical order/payment amounts are available on `CheckoutOrder` and `CheckoutPayment` (for example `requestedUsdcAmount`, `remainingUsdcAmount`, `netSettledUsdcAmount`). `CheckoutPayment.penalties` lists attestation-applied reductions (`PaymentPenalty[]`, empty when none).
 - This package is ESM-only.

package/dist/addressValidators.d.ts

@@ -1,2 +1,4 @@
+/** NEAR Intents accepts mainnet transparent Zcash refund addresses only. */
+export declare function isValidZcashAddress(value: string): boolean;
 export declare function isValidSolanaAddress(value: string): boolean;
 export declare function isValidTronAddress(value: string): boolean;

package/dist/addressValidators.js

@@ -1,4 +1,15 @@
-import { decodeBase58, encodeBase58, hasBase58CheckChecksum, } from './addressEncoding.js';
+import { decodeBase58, doubleSha256, encodeBase58, hasBase58CheckChecksum, } from './addressEncoding.js';
+/** NEAR Intents accepts mainnet transparent Zcash refund addresses only. */
+export function isValidZcashAddress(value) {
+    if (!/^t[13][1-9A-HJ-NP-Za-km-z]{33}$/.test(value))
+        return false;
+    const decoded = decodeBase58(value);
+    if (decoded === null || decoded.length !== 26 || decoded[0] !== 0x1c
+        || (decoded[1] !== 0xb8 && decoded[1] !== 0xbd))
+        return false;
+    const checksum = doubleSha256(decoded.subarray(0, 22));
+    return decoded.subarray(22).every((byte, index) => byte === checksum[index]);
+}
 export function isValidSolanaAddress(value) {
     if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value)) {
         return false;

package/dist/chains.js

@@ -88,6 +88,15 @@ export const MAINNET_CHAINS = {
         isEvm: true,
         explorerUrl: 'https://hyperscan.xyz',
     },
+    5042: {
+        chainId: 5042,
+        name: 'Arc',
+        shortName: 'ARC',
+        usdcAddress: '0x3600000000000000000000000000000000000000',
+        isOriginChain: false,
+        isEvm: true,
+        explorerUrl: 'https://explorer.arc.io',
+    },
     // Non-EVM Destination chains
     [SOLANA_CHAIN_ID]: {
         chainId: SOLANA_CHAIN_ID,

package/dist/clientTelemetry.d.ts

@@ -0,0 +1,25 @@
+/** Shared, non-secret context for the Pay browser surfaces. */
+export type PayClientSurface = 'checkout' | 'merchant-dashboard' | 'support-dashboard';
+export declare function payClientContext(input: {
+    surface: PayClientSurface;
+    hostname: string;
+    productionBuild: boolean;
+    appVersion: string;
+    merchantId?: string;
+    environment?: 'LIVE' | 'SANDBOX';
+    qaRun: boolean;
+}): {
+    merchant_id?: string | undefined;
+    product: string;
+    surface: PayClientSurface;
+    hostname: string;
+    deployment_environment: string;
+    app_version: string;
+    environment: string;
+    is_qa: boolean;
+};
+/**
+ * Route templates only: never emit customer IDs, search parameters or fragments. The support
+ * dashboard templates its routes with `supportTelemetryRoute` from the support contracts.
+ */
+export declare function payClientRoute(surface: Exclude<PayClientSurface, 'support-dashboard'>, pathname: string): string;

package/dist/clientTelemetry.js

@@ -0,0 +1,30 @@
+const PRODUCTION_HOST = {
+    checkout: 'pay.peer.xyz',
+    'merchant-dashboard': 'merchant.pay.peer.xyz',
+    'support-dashboard': 'support.pay.peer.xyz',
+};
+export function payClientContext(input) {
+    const productionHost = PRODUCTION_HOST[input.surface];
+    return {
+        product: 'pay',
+        surface: input.surface,
+        hostname: input.hostname,
+        deployment_environment: input.productionBuild && input.hostname === productionHost
+            ? 'PRODUCTION' : input.productionBuild ? 'PREPROD' : 'DEVELOPMENT',
+        app_version: input.appVersion,
+        environment: input.environment ?? 'UNKNOWN',
+        is_qa: input.qaRun || input.merchantId === 'cmrunizzo02wf3ua8t6yx1mns',
+        ...(input.merchantId ? { merchant_id: input.merchantId } : {}),
+    };
+}
+/**
+ * Route templates only: never emit customer IDs, search parameters or fragments. The support
+ * dashboard templates its routes with `supportTelemetryRoute` from the support contracts.
+ */
+export function payClientRoute(surface, pathname) {
+    const path = pathname.split(/[?#]/, 1)[0];
+    if (surface === 'checkout')
+        return path === '/' ? '/' : '/:checkout';
+    return /^\/(?:login|onboarding|orders|staking|referrals|scan-to-pay|webhooks|faq|resources|settings(?:\/(?:account|payments|checkout|developer|billing|interface|tap-to-pay))?)?$/.test(path)
+        ? path : '/:unknown';
+}

package/dist/conciergeIntake.d.ts

@@ -0,0 +1,56 @@
+export declare const CONCIERGE_QUESTIONS: readonly [{
+    readonly id: "business";
+    readonly label: "What do you sell, and what industry are you in?";
+    readonly hint: "Your products or services and industry.";
+}, {
+    readonly id: "storefront";
+    readonly label: "Where do you sell?";
+    readonly hint: "Your website, plus what it runs on: Shopify, WooCommerce, custom site, Telegram, or in person.";
+}, {
+    readonly id: "volume";
+    readonly label: "How much volume do you process today?";
+    readonly hint: "Daily, weekly, or monthly volume, plus your average order size. Include the currency.";
+}, {
+    readonly id: "customers";
+    readonly label: "Where are your customers?";
+    readonly hint: "US, UK, EU, or elsewhere. This decides which payment apps we enable.";
+}, {
+    readonly id: "apps";
+    readonly label: "Which payment apps do you want your customers paying with?";
+    readonly hint: "Venmo, Cash App, Zelle, PayPal, Revolut, Wise, or others.";
+}, {
+    readonly id: "payments";
+    readonly label: "What do you use to accept payments today?";
+    readonly hint: "Your current payment providers or methods.";
+}, {
+    readonly id: "crypto";
+    readonly label: "Do you also want to accept crypto directly?";
+    readonly hint: "Customers can pay with any coin on any network and you still settle in USDC.";
+    readonly options: readonly ["Yes", "No", "Not sure yet"];
+}, {
+    readonly id: "feePayer";
+    readonly label: "Who pays the Peer Pay fee?";
+    readonly hint: "Your customer, you, or a split between both.";
+    readonly options: readonly ["Customer", "Merchant", "Split"];
+}, {
+    readonly id: "integrator";
+    readonly label: "Who is doing the integration on your side, you or a developer?";
+    readonly hint: "We will send the right guide and set up an API key if needed.";
+}];
+export type ConciergeQuestionId = typeof CONCIERGE_QUESTIONS[number]['id'];
+export type ConciergeQuestion = {
+    readonly id: ConciergeQuestionId;
+    readonly label: string;
+    readonly hint: string;
+    readonly options?: readonly string[];
+};
+export declare const CONCIERGE_QUESTION_IDS: readonly ConciergeQuestionId[];
+export type ConciergeAnswers = Partial<Record<ConciergeQuestionId, string>>;
+export type ConciergeInquiryInput = {
+    readonly contactEmail: string;
+    readonly businessName: string;
+    readonly telegramUsername: string;
+    readonly answers: ConciergeAnswers;
+    readonly message: string;
+};
+export declare function isCompleteConciergeAnswers(value: ConciergeAnswers): boolean;

package/dist/conciergeIntake.js

@@ -0,0 +1,15 @@
+export const CONCIERGE_QUESTIONS = [
+    { id: 'business', label: 'What do you sell, and what industry are you in?', hint: 'Your products or services and industry.' },
+    { id: 'storefront', label: 'Where do you sell?', hint: 'Your website, plus what it runs on: Shopify, WooCommerce, custom site, Telegram, or in person.' },
+    { id: 'volume', label: 'How much volume do you process today?', hint: 'Daily, weekly, or monthly volume, plus your average order size. Include the currency.' },
+    { id: 'customers', label: 'Where are your customers?', hint: 'US, UK, EU, or elsewhere. This decides which payment apps we enable.' },
+    { id: 'apps', label: 'Which payment apps do you want your customers paying with?', hint: 'Venmo, Cash App, Zelle, PayPal, Revolut, Wise, or others.' },
+    { id: 'payments', label: 'What do you use to accept payments today?', hint: 'Your current payment providers or methods.' },
+    { id: 'crypto', label: 'Do you also want to accept crypto directly?', hint: 'Customers can pay with any coin on any network and you still settle in USDC.', options: ['Yes', 'No', 'Not sure yet'] },
+    { id: 'feePayer', label: 'Who pays the Peer Pay fee?', hint: 'Your customer, you, or a split between both.', options: ['Customer', 'Merchant', 'Split'] },
+    { id: 'integrator', label: 'Who is doing the integration on your side, you or a developer?', hint: 'We will send the right guide and set up an API key if needed.' },
+];
+export const CONCIERGE_QUESTION_IDS = CONCIERGE_QUESTIONS.map(({ id }) => id);
+export function isCompleteConciergeAnswers(value) {
+    return CONCIERGE_QUESTION_IDS.every((id) => Boolean(value[id]?.trim()));
+}

package/dist/crypto.d.ts

@@ -1,5 +1,7 @@
 export declare const BITCOIN_CHAIN_ID = 8253038;
-export declare const PAY_CRYPTO_TOKEN_SYMBOLS: readonly ["BTC", "USDC", "USDT", "ETH", "PYUSD", "SOL", "BNB", "HYPE", "WBTC", "USDH"];
+export declare const ZCASH_CHAIN_ID = 133701;
+export declare const ZCASH_ASSET = "nep141:zec.omft.near";
+export declare const PAY_CRYPTO_TOKEN_SYMBOLS: readonly ["BTC", "USDC", "USDT", "ETH", "PYUSD", "SOL", "BNB", "HYPE", "WBTC", "USDH", "ZEC"];
 export type PayCryptoTokenSymbol = (typeof PAY_CRYPTO_TOKEN_SYMBOLS)[number];
 export declare const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS: PayCryptoTokenSymbol[];
 export declare const DEFAULT_ENABLED_DESTINATION_TOKENS: PayCryptoTokenSymbol[];
@@ -9,7 +11,7 @@ export declare const DEFAULT_ENABLED_DESTINATION_TOKENS: PayCryptoTokenSymbol[];
  * iteration order of PAY_CRYPTO_CHAIN_CONFIGS as a stable tiebreaker.
  */
 export declare const PAY_CRYPTO_CHAIN_DISPLAY_PRIORITY: readonly number[];
-export declare const STABLECOIN_SYMBOLS: Set<"USDC" | "USDT" | "ETH" | "BNB" | "SOL" | "BTC" | "PYUSD" | "HYPE" | "WBTC" | "USDH">;
+export declare const STABLECOIN_SYMBOLS: Set<"USDC" | "USDT" | "ETH" | "BNB" | "SOL" | "BTC" | "PYUSD" | "HYPE" | "WBTC" | "USDH" | "ZEC">;
 export interface SupportedCryptoTokenConfig {
     chainId: number;
     chainName: string;

package/dist/crypto.js

@@ -1,5 +1,8 @@
 import { MAINNET_CHAINS, BASE_CHAIN_ID, ETHEREUM_CHAIN_ID, SOLANA_CHAIN_ID, TRON_CHAIN_ID, getChainName, } from './chains.js';
 export const BITCOIN_CHAIN_ID = 8253038;
+// Synthetic network ID shared with the mobile and web NEAR Intents clients.
+export const ZCASH_CHAIN_ID = 133701;
+export const ZCASH_ASSET = 'nep141:zec.omft.near';
 export const PAY_CRYPTO_TOKEN_SYMBOLS = [
     'BTC', // Kept in symbols for DB compatibility with existing sessions
     'USDC',
@@ -11,6 +14,7 @@ export const PAY_CRYPTO_TOKEN_SYMBOLS = [
     'HYPE',
     'WBTC',
     'USDH',
+    'ZEC',
 ];
 export const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS = [
     'BTC',
@@ -23,6 +27,7 @@ export const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS = [
     'HYPE',
     'WBTC',
     'USDH',
+    'ZEC',
 ];
 export const DEFAULT_ENABLED_DESTINATION_TOKENS = [
     'USDC',
@@ -50,6 +55,7 @@ const NATIVE_SOL_ADDRESS = '11111111111111111111111111111111';
 const NATIVE_BTC_ADDRESS = 'bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8';
 const PAY_CRYPTO_CHAIN_CONFIGS = {
     ...MAINNET_CHAINS,
+    [ZCASH_CHAIN_ID]: { chainId: ZCASH_CHAIN_ID, name: 'Zcash', shortName: 'ZEC' },
     [BITCOIN_CHAIN_ID]: {
         chainId: BITCOIN_CHAIN_ID,
         name: 'Bitcoin',
@@ -57,6 +63,9 @@ const PAY_CRYPTO_CHAIN_CONFIGS = {
     },
 };
 const CHAIN_TOKEN_CONFIGS = {
+    [ZCASH_CHAIN_ID]: {
+        ZEC: { address: ZCASH_ASSET, decimals: 8, isNative: true },
+    },
     [BITCOIN_CHAIN_ID]: {
         BTC: { address: NATIVE_BTC_ADDRESS, decimals: 8, isNative: true },
     },
@@ -92,6 +101,10 @@ const CHAIN_TOKEN_CONFIGS = {
         USDC: { address: '0xb88339CB7199b77E23DB6E890353E22632Ba630f', decimals: 6, isNative: false },
         USDH: { address: '0x111111a1a0667d36bd57c0a9f569b98057111111', decimals: 6, isNative: false },
     },
+    5042: {
+        // Arc's ERC-20 USDC interface has 6 decimals; native gas uses 18.
+        USDC: { address: '0x3600000000000000000000000000000000000000', decimals: 6, isNative: false },
+    },
     8453: {
         ETH: { address: NATIVE_ETH_ADDRESS, decimals: 18, isNative: true },
         USDC: { address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', decimals: 6, isNative: false },

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,4 +1,5 @@
 export * from './types.js';
+export * from './paymentRecovery.js';
 export * from './chains.js';
 export * from './fees.js';
 export * from './crypto.js';
@@ -8,10 +9,14 @@ 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,4 +1,5 @@
 export * from './types.js';
+export * from './paymentRecovery.js';
 export * from './chains.js';
 export * from './fees.js';
 export * from './crypto.js';
@@ -8,10 +9,14 @@ 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;