@zkp2p/pay-shared 1.0.0 → 3.0.0

package/dist/onboarding.js

@@ -0,0 +1,150 @@
+import { MerchantIntegrationPath, OnboardingStepStatus, OnboardingStepVerifiedBy, } from './types.js';
+export const OnboardingStepId = {
+    PROFILE: 'profile',
+    INDUSTRY: 'industry',
+    PATH: 'path',
+    RAILS: 'rails',
+    INTEGRATION: 'integration',
+    WEBHOOK: 'webhook',
+    GO_LIVE: 'goLive',
+    DOWNLOAD_PLUGIN: 'downloadPlugin',
+    PLUGIN_API_KEY: 'pluginApiKey',
+    TEST_ORDER: 'testOrder',
+    FIRST_QR: 'firstQr',
+    LINK_BOT: 'linkBot',
+    REQUEST_SETUP: 'requestSetup',
+};
+export const ONBOARDING_STEP_REGISTRY = [
+    { id: OnboardingStepId.PROFILE, paths: 'ALL', verifiedBy: OnboardingStepVerifiedBy.AUTO, inChecklist: true, impliesPrevious: true },
+    { id: OnboardingStepId.INDUSTRY, paths: 'ALL', verifiedBy: OnboardingStepVerifiedBy.AUTO, inChecklist: true, impliesPrevious: true },
+    {
+        id: OnboardingStepId.RAILS,
+        paths: 'ALL',
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        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.
+        impliesPrevious: false,
+    },
+    { id: OnboardingStepId.PATH, paths: 'ALL', verifiedBy: OnboardingStepVerifiedBy.AUTO, inChecklist: true, impliesPrevious: true },
+    {
+        id: OnboardingStepId.INTEGRATION,
+        paths: [MerchantIntegrationPath.CUSTOM_API],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.WEBHOOK,
+        paths: [MerchantIntegrationPath.CUSTOM_API],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: false,
+    },
+    {
+        id: OnboardingStepId.LINK_BOT,
+        paths: [MerchantIntegrationPath.TELEGRAM],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.GO_LIVE,
+        paths: [MerchantIntegrationPath.CUSTOM_API, MerchantIntegrationPath.TELEGRAM],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.DOWNLOAD_PLUGIN,
+        paths: [MerchantIntegrationPath.WOOCOMMERCE],
+        verifiedBy: OnboardingStepVerifiedBy.MANUAL,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.PLUGIN_API_KEY,
+        paths: [MerchantIntegrationPath.WOOCOMMERCE],
+        verifiedBy: OnboardingStepVerifiedBy.MANUAL,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.TEST_ORDER,
+        paths: [MerchantIntegrationPath.WOOCOMMERCE],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.GO_LIVE,
+        paths: [MerchantIntegrationPath.WOOCOMMERCE],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.FIRST_QR,
+        paths: [MerchantIntegrationPath.IN_PERSON],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        // In-person merchants only need to show a Scan to Pay QR. Waiting for a real
+        // customer payment would leave unopened shops stuck in onboarding.
+        impliesPrevious: true,
+    },
+    {
+        id: OnboardingStepId.REQUEST_SETUP,
+        paths: [MerchantIntegrationPath.SHOPIFY],
+        verifiedBy: OnboardingStepVerifiedBy.MANUAL,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
+];
+const autoStepPredicates = {
+    [OnboardingStepId.PROFILE]: (facts) => facts.hasName && facts.hasLogo,
+    [OnboardingStepId.INDUSTRY]: (facts) => facts.hasIndustry,
+    [OnboardingStepId.PATH]: (facts) => facts.hasIntegrationPath,
+    [OnboardingStepId.RAILS]: () => true,
+    [OnboardingStepId.INTEGRATION]: (facts) => facts.hasSandboxFulfilledOrder,
+    [OnboardingStepId.WEBHOOK]: (facts) => facts.hasWebhook,
+    [OnboardingStepId.TEST_ORDER]: (facts) => facts.hasSandboxFulfilledOrder,
+    [OnboardingStepId.LINK_BOT]: (facts) => facts.hasSandboxFulfilledOrder,
+    [OnboardingStepId.GO_LIVE]: (facts) => facts.hasLiveFulfilledOrder,
+    [OnboardingStepId.FIRST_QR]: (facts) => facts.hasSandboxOrder,
+};
+export function resolveOnboardingSteps(facts, path) {
+    const entries = ONBOARDING_STEP_REGISTRY.filter((entry) => entry.paths === 'ALL' || (path !== null && entry.paths.includes(path)));
+    // Load-bearing override: merchants already taking payments must remain free of
+    // the onboarding checklist, even when they have no selected integration path.
+    if (facts.hasLiveFulfilledOrder) {
+        return entries.map((entry) => ({
+            id: entry.id,
+            status: OnboardingStepStatus.DONE,
+            verifiedBy: entry.verifiedBy,
+        }));
+    }
+    const steps = entries.map((entry) => {
+        const isDone = entry.verifiedBy === OnboardingStepVerifiedBy.MANUAL
+            ? facts.manualSteps.includes(entry.id)
+            : autoStepPredicates[entry.id]?.(facts) ?? false;
+        return {
+            id: entry.id,
+            status: isDone ? OnboardingStepStatus.DONE : OnboardingStepStatus.TODO,
+            verifiedBy: entry.verifiedBy,
+        };
+    });
+    let laterStepIsDone = false;
+    for (let index = steps.length - 1; index >= 0; index -= 1) {
+        if (laterStepIsDone) {
+            steps[index] = { ...steps[index], status: OnboardingStepStatus.DONE };
+        }
+        else if (steps[index].status === OnboardingStepStatus.DONE
+            && entries[index].impliesPrevious) {
+            laterStepIsDone = true;
+        }
+    }
+    return steps;
+}
+export function isOnboardingComplete(steps) {
+    return steps.every((step) => step.status === OnboardingStepStatus.DONE);
+}

package/dist/payeeFeeCap.d.ts

@@ -0,0 +1,21 @@
+export type PayeeFeeEntry = {
+    readonly recipient: string;
+    readonly feeBps: number;
+};
+export type PayeeReferralFeeCapacityResult = {
+    readonly referralFees: PayeeFeeEntry[];
+    readonly configuredPlatformReferralFeeBps: number;
+    readonly adjustedPlatformReferralFeeBps: number;
+    readonly otherReferralFeeAmount: string;
+    readonly platformFeeCapacityAmount: string;
+    readonly insufficientCapacity: boolean;
+    readonly requiredNetCovered: boolean;
+};
+export declare function resolvePayeeReferralFeeCapacity(input: {
+    readonly grossSignalAmount: string;
+    readonly quotedTokenOutput: string;
+    readonly requiredNetAmount: string;
+    readonly platformRecipient: string;
+    readonly referralFees: readonly PayeeFeeEntry[];
+}): PayeeReferralFeeCapacityResult;
+export declare function computeNetAfterPreciseFees(grossAmount: string, feeRates18dec: readonly string[]): string;

package/dist/payeeFeeCap.js

@@ -0,0 +1,105 @@
+const BPS_DENOMINATOR = 10000n;
+const PRECISE_FEE_DENOMINATOR = 10n ** 18n;
+const UNSIGNED_INTEGER_PATTERN = /^\d+$/;
+export function resolvePayeeReferralFeeCapacity(input) {
+    const grossSignalAmount = parsePositiveUnits(input.grossSignalAmount, 'gross signal amount');
+    const quotedTokenOutput = parsePositiveUnits(input.quotedTokenOutput, 'quoted token output');
+    const requiredNetAmount = parsePositiveUnits(input.requiredNetAmount, 'required net amount');
+    if (quotedTokenOutput > grossSignalAmount) {
+        throw new RangeError('Quoted token output cannot exceed gross signal amount');
+    }
+    const platformRecipient = input.platformRecipient.trim().toLowerCase();
+    if (platformRecipient === '') {
+        throw new RangeError('Platform recipient is required');
+    }
+    const platformEntries = input.referralFees.filter((entry) => entry.recipient.trim().toLowerCase() === platformRecipient);
+    if (platformEntries.length > 1) {
+        throw new RangeError('Duplicate platform referral fee entries');
+    }
+    input.referralFees.forEach(validateFeeEntry);
+    const configuredPlatformReferralFeeBps = platformEntries[0]?.feeBps ?? 0;
+    const otherReferralFeeAmount = input.referralFees.reduce((total, entry) => {
+        if (entry.recipient.trim().toLowerCase() === platformRecipient) {
+            return total;
+        }
+        return total + computeBpsFee(grossSignalAmount, entry.feeBps);
+    }, 0n);
+    const platformFeeCapacityAmount = quotedTokenOutput - requiredNetAmount - otherReferralFeeAmount;
+    const insufficientCapacity = platformFeeCapacityAmount < 0n;
+    const adjustedPlatformReferralFeeBps = insufficientCapacity
+        ? 0
+        : findLargestFittingBps(grossSignalAmount, platformFeeCapacityAmount, configuredPlatformReferralFeeBps);
+    const adjustedPlatformFeeAmount = computeBpsFee(grossSignalAmount, adjustedPlatformReferralFeeBps);
+    const requiredNetCovered = quotedTokenOutput
+        - otherReferralFeeAmount
+        - adjustedPlatformFeeAmount >= requiredNetAmount;
+    return {
+        referralFees: input.referralFees.flatMap((entry) => {
+            if (entry.recipient.trim().toLowerCase() !== platformRecipient) {
+                return [{ ...entry }];
+            }
+            return adjustedPlatformReferralFeeBps === 0
+                ? []
+                : [{ ...entry, feeBps: adjustedPlatformReferralFeeBps }];
+        }),
+        configuredPlatformReferralFeeBps,
+        adjustedPlatformReferralFeeBps,
+        otherReferralFeeAmount: otherReferralFeeAmount.toString(),
+        platformFeeCapacityAmount: platformFeeCapacityAmount.toString(),
+        insufficientCapacity,
+        requiredNetCovered,
+    };
+}
+export function computeNetAfterPreciseFees(grossAmount, feeRates18dec) {
+    const gross = parsePositiveUnits(grossAmount, 'gross amount');
+    const totalFees = feeRates18dec.reduce((total, feeRate) => {
+        const rate = parseUnsignedUnits(feeRate, 'precise fee rate');
+        if (rate > PRECISE_FEE_DENOMINATOR) {
+            throw new RangeError('Precise fee rate cannot exceed 100%');
+        }
+        return total + (gross * rate / PRECISE_FEE_DENOMINATOR);
+    }, 0n);
+    if (totalFees > gross) {
+        throw new RangeError('Precise fees exceed gross amount');
+    }
+    return (gross - totalFees).toString();
+}
+function findLargestFittingBps(grossAmount, capacity, configuredBps) {
+    let low = 0;
+    let high = configuredBps;
+    while (low < high) {
+        const candidate = Math.ceil((low + high) / 2);
+        if (computeBpsFee(grossAmount, candidate) <= capacity) {
+            low = candidate;
+        }
+        else {
+            high = candidate - 1;
+        }
+    }
+    return low;
+}
+function computeBpsFee(grossAmount, feeBps) {
+    return grossAmount * BigInt(feeBps) / BPS_DENOMINATOR;
+}
+function validateFeeEntry(entry) {
+    if (entry.recipient.trim() === '') {
+        throw new RangeError('Referral fee recipient is required');
+    }
+    if (!Number.isInteger(entry.feeBps) || entry.feeBps < 0 || entry.feeBps > 10000) {
+        throw new RangeError(`Invalid referral fee bps: ${entry.feeBps}`);
+    }
+}
+function parsePositiveUnits(value, label) {
+    const parsed = parseUnsignedUnits(value, label);
+    if (parsed <= 0n) {
+        throw new RangeError(`${label} must be positive`);
+    }
+    return parsed;
+}
+function parseUnsignedUnits(value, label) {
+    const normalized = value.trim();
+    if (!UNSIGNED_INTEGER_PATTERN.test(normalized)) {
+        throw new RangeError(`${label} must be an unsigned integer`);
+    }
+    return BigInt(normalized);
+}

package/dist/paypalSarPhase.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether a name-mode SAR verify poll outcome is worth retrying. Only a "no receipt found yet" (404)
+ * may resolve on a later poll; every other terminal status is deterministic and must fail fast.
+ */
+export declare function isRetryableSarPollStatus(statusCode: number): boolean;

package/dist/paypalSarPhase.js

@@ -0,0 +1,8 @@
+const NO_RECEIPT_STATUS = 404; // SELLER_TXID_NOT_FOUND — the only status worth re-polling
+/**
+ * Whether a name-mode SAR verify poll outcome is worth retrying. Only a "no receipt found yet" (404)
+ * may resolve on a later poll; every other terminal status is deterministic and must fail fast.
+ */
+export function isRetryableSarPollStatus(statusCode) {
+    return statusCode === NO_RECEIPT_STATUS;
+}

package/dist/paypalSarVerify.d.ts

@@ -0,0 +1,41 @@
+export type SarAttemptOutcome = {
+    kind: 'success';
+    proofAttemptId: string;
+} | {
+    kind: 'unavailable';
+} | {
+    kind: 'error';
+    errorCode: string;
+    errorMessage: string;
+    statusCode: number;
+};
+export type SarVerifyResult = {
+    kind: 'success';
+    proofAttemptId: string;
+} | {
+    kind: 'unavailable';
+} | {
+    kind: 'error';
+    errorCode: string;
+    errorMessage: string;
+} | {
+    kind: 'aborted';
+};
+export interface RunPaypalSarNameVerifyDeps {
+    /** POST a name-mode attempt. attemptNumber is 1-based and increments per name poll. */
+    submitNameAttempt: (attemptNumber: number) => Promise<SarAttemptOutcome>;
+    sleep: (ms: number) => Promise<void>;
+    /** Re-checked after every await; returning false short-circuits to { kind: 'aborted' }. */
+    isMounted: () => boolean;
+    now: () => number;
+    retryIntervalMs: number;
+    retryDurationMs: number;
+}
+/**
+ * Name-only PayPal SAR verification.
+ * Polls name-mode verify (retrying only on retryable poll statuses until the deadline). Terminal
+ * name failures surface directly. Success / unavailable short-circuit. The caller maps the returned
+ * result to its own UI side effects; 'aborted' means the component unmounted and the caller should
+ * do nothing.
+ */
+export declare function runPaypalSarNameVerify(deps: RunPaypalSarNameVerifyDeps): Promise<SarVerifyResult>;

package/dist/paypalSarVerify.js

@@ -0,0 +1,31 @@
+import { isRetryableSarPollStatus } from './paypalSarPhase.js';
+/**
+ * Name-only PayPal SAR verification.
+ * Polls name-mode verify (retrying only on retryable poll statuses until the deadline). Terminal
+ * name failures surface directly. Success / unavailable short-circuit. The caller maps the returned
+ * result to its own UI side effects; 'aborted' means the component unmounted and the caller should
+ * do nothing.
+ */
+export async function runPaypalSarNameVerify(deps) {
+    const { submitNameAttempt, sleep, isMounted, now, retryIntervalMs, retryDurationMs } = deps;
+    const deadline = now() + retryDurationMs;
+    let attemptNumber = 1;
+    while (true) {
+        const outcome = await submitNameAttempt(attemptNumber);
+        if (!isMounted())
+            return { kind: 'aborted' };
+        if (outcome.kind === 'success')
+            return { kind: 'success', proofAttemptId: outcome.proofAttemptId };
+        if (outcome.kind === 'unavailable')
+            return { kind: 'unavailable' };
+        const deadlineReached = now() + retryIntervalMs > deadline;
+        if (isRetryableSarPollStatus(outcome.statusCode) && !deadlineReached) {
+            await sleep(retryIntervalMs);
+            if (!isMounted())
+                return { kind: 'aborted' };
+            attemptNumber += 1;
+            continue;
+        }
+        return { kind: 'error', errorCode: outcome.errorCode, errorMessage: outcome.errorMessage };
+    }
+}

package/dist/rails.d.ts

@@ -42,6 +42,17 @@ export declare enum SupportedRelayRail {
 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"];
+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>;
+export declare const ORDER_SEARCH_MIN_QUERY_LENGTH = 3;
+export declare function railKeysForQuery(query: string): string[];
+export declare const RELAY_CHAIN_DISPLAY_NAMES: Record<number, string>;
+/**
+ * Surfaces crypto-settled orders for token, chain, and "crypto" prefix queries.
+ */
+export declare function isCryptoMethodQuery(query: string): boolean;
 /**
  * Normalizes a rail string into a crypto chain id.
  *
@@ -51,11 +62,76 @@ export declare const SUPPORTED_RELAY_RAILS: readonly SupportedRelayRail[];
  */
 export declare function parseCryptoRailChainId(rail: string | null | undefined): number | null;
 export declare function isSupportedRail(rail: string): rail is SupportedRail;
+export declare function isFiatSupportedRail(rail: string): rail is FiatSupportedRail;
+/** Returns false for rails that remain recognized but are disabled at runtime. */
+export declare function isRailRuntimeEnabled(rail: string | null | undefined): boolean;
+/** Filters out globally disabled runtime rails while preserving caller ordering. */
+export declare function filterRuntimeEnabledRails<T extends string>(rails: readonly T[]): T[];
+/**
+ * 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 declare function setRuntimeDisabledFiatRails(rails: readonly string[]): void;
+/** Returns the currently runtime-disabled fiat rails (canonical base rails). */
+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;
 /** 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). */
 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;
+/**
+ * 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 declare const SAR_SUPPORTED_FIAT_RAILS: readonly ["venmo", "cashapp", "wise", "paypal"];
+export type SarSupportedFiatRail = typeof SAR_SUPPORTED_FIAT_RAILS[number];
+/** Returns true when the fiat rail (incl. variants like `zelle-chase`) supports SAR. */
+export declare function isSarSupportedFiatRail(rail: string | null | undefined): boolean;
+/**
+ * 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 declare function filterRailsForExclusiveSar(rails: readonly string[]): string[];
+/** 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. */
+export declare const ZELLE_PAYMENT_METHOD_IDS: ReadonlySet<string>;
+/** Bank-qualified buyer TEE action types accepted for generic Zelle proofs. */
+export declare const ZELLE_BUYER_TEE_ACTION_TYPES: ReadonlySet<string>;
+export type AttestationRoute = {
+    readonly platform: string;
+    readonly actionType: string;
+};
+/**
+ * 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 declare function resolveAttestationRoute(rail: string | null | undefined): AttestationRoute;
+/** Canonical generic Zelle on-chain method hash: keccak256("zelle"), lowercase. */
+export declare const GENERIC_ZELLE_PAYMENT_METHOD_HASH = "0xf752c7d19698ecb0bb8988abf9b9a53a4c3657f3bc8850a6fb59fdf3e3ce8cd3";
+/** Case-insensitive check that a hash is the canonical generic Zelle on-chain method hash. */
+export declare function isGenericZellePaymentMethodHash(hash: string | null | undefined): boolean;
+/** True when the rail is Zelle (generic or a bank variant). */
+export declare function isZelleRail(rail: string | null | undefined): boolean;
 /** Formats a rail value for human-readable UI labels. */
 export declare function getRailDisplayName(rail: string | null | undefined): string;