@zkp2p/pay-shared 1.0.0 → 3.0.0

package/dist/rails.js

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

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { PayCryptoTokenSymbol } from './crypto.js';
+import type { ProofMode } from './buyerTee.js';
 export declare const PaymentPlatform: {
     readonly VENMO: "venmo";
     readonly CASHAPP: "cashapp";
@@ -11,6 +12,11 @@ export declare const PaymentPlatform: {
     readonly CHIME: "chime";
 };
 export type PaymentPlatformType = typeof PaymentPlatform[keyof typeof PaymentPlatform];
+/**
+ * Type guard for PaymentPlatform values.
+ * Returns true if `value` is one of the known PaymentPlatform enum values.
+ */
+export declare function isPaymentPlatform(value: unknown): value is PaymentPlatformType;
 export declare const SupportedChains: Record<number, string>;
 export type SupportedChainId = keyof typeof SupportedChains;
 export declare const CheckoutMode: {
@@ -57,6 +63,13 @@ export declare const FeePayer: {
     readonly PAYEE: "PAYEE";
 };
 export type FeePayerType = typeof FeePayer[keyof typeof FeePayer];
+export declare const MerchantPaymentFlowMode: {
+    readonly EXCLUSIVE_SAR: "EXCLUSIVE_SAR";
+    readonly PREFER_SAR: "PREFER_SAR";
+    readonly PREFER_BUYER_TEE: "PREFER_BUYER_TEE";
+    readonly EXCLUSIVE_BUYER_TEE: "EXCLUSIVE_BUYER_TEE";
+};
+export type MerchantPaymentFlowModeType = typeof MerchantPaymentFlowMode[keyof typeof MerchantPaymentFlowMode];
 export declare const CheckoutOrderStatus: {
     readonly CREATED: "CREATED";
     readonly PARTIALLY_FULFILLED: "PARTIALLY_FULFILLED";
@@ -64,6 +77,12 @@ export declare const CheckoutOrderStatus: {
     readonly CANCELLED: "CANCELLED";
 };
 export type CheckoutOrderStatusType = typeof CheckoutOrderStatus[keyof typeof CheckoutOrderStatus];
+export declare const CheckoutOrderRefundStatus: {
+    readonly NONE: "NONE";
+    readonly PENDING: "PENDING";
+    readonly COMPLETED: "COMPLETED";
+};
+export type CheckoutOrderRefundStatusType = typeof CheckoutOrderRefundStatus[keyof typeof CheckoutOrderRefundStatus];
 export declare const CheckoutPaymentStatus: {
     readonly CREATED: "CREATED";
     readonly SETTLED: "SETTLED";
@@ -72,6 +91,12 @@ export declare const CheckoutPaymentStatus: {
     readonly FAILED: "FAILED";
 };
 export type CheckoutPaymentStatusType = typeof CheckoutPaymentStatus[keyof typeof CheckoutPaymentStatus];
+export declare const CheckoutPaymentMemoPolicy: {
+    readonly NONE: "NONE";
+    readonly REQUIRED: "REQUIRED";
+    readonly EMPTY: "EMPTY";
+};
+export type CheckoutPaymentMemoPolicyType = typeof CheckoutPaymentMemoPolicy[keyof typeof CheckoutPaymentMemoPolicy];
 export type ReferralFeeEntry = {
     recipient: string;
     feeBps: number;
@@ -87,6 +112,7 @@ type CreateOrderRequestBase = {
     destinationChainId?: number;
     feePayer?: FeePayerType;
     enabledRails?: string[];
+    dynamicOrdersEnabled?: boolean;
     successUrl?: string | null;
     cancelUrl?: string | null;
     notes?: Record<string, unknown> | null;
@@ -115,6 +141,7 @@ export type MerchantCheckoutTheme = {
     buttonTextColor?: string | null;
     defaultMaxFeePercentage?: number;
     payWithCryptoEnabled?: boolean;
+    currencySelectorEnabled?: boolean;
     [key: string]: unknown;
 };
 export type CheckoutMerchant = {
@@ -125,11 +152,19 @@ export type CheckoutMerchant = {
     disableBranding: boolean;
     checkoutTheme: MerchantCheckoutTheme | null;
     defaultPaymentCurrency?: string | null;
+    /** Whether the merchant has been verified by ZKP2P. */
+    verified: boolean;
 };
 export type CheckoutOrder = {
     id: string;
     merchantId: string;
     status: CheckoutOrderStatusType;
+    refundStatus: CheckoutOrderRefundStatusType;
+    refundAmountUsdc: string | null;
+    refundDepositId: string | null;
+    refundTransactionHash: string | null;
+    refundMetadata: unknown | null;
+    inPersonCheckout: boolean;
     requestedUsdcAmount: string;
     remainingUsdcAmount: string;
     destinationAddress: string;
@@ -141,6 +176,11 @@ export type CheckoutOrder = {
     cancelUrl: string | null;
     notes: unknown | null;
     metadata: unknown | null;
+    /** Merchant-requested fiat price; non-null only for pristine, un-resized fiat-input orders. */
+    requestedFiat?: {
+        amount: string;
+        currency: string;
+    } | null;
     bridgeInfo?: OrderBridgeInfo | null;
     referralSplitConfig: ReferralSplitConfig | null;
     cancelledAt: string | null;
@@ -156,6 +196,7 @@ export type CheckoutPaymentQuote = {
         amount: string;
         toAddress: string;
         escrowAddress?: string;
+        orchestratorAddress?: string;
         fiatCurrencyCode?: string;
         payeeDetails: string;
     };
@@ -163,6 +204,7 @@ export type CheckoutPaymentQuote = {
         depositData: Record<string, string>;
     };
     intentHash?: string;
+    sellerAutomatedReleaseAvailable?: boolean;
 };
 export type CheckoutQuote = {
     displayAmount: string;
@@ -172,21 +214,45 @@ export type CheckoutQuoteEntry = {
     platform: string;
     displayAmount: string;
     spreadPercentage: number;
+    sellerAutomatedReleaseAvailable?: boolean;
+};
+export type CheckoutNearbySuggestion = {
+    resizeAmountUsdc: string;
+    paymentAmount: string;
+    paymentCurrency: string;
+    tokenAmount: string;
+    percentDifference: string;
+    rail: string;
+};
+export type CheckoutNearbySuggestions = {
+    status: 'suggestions' | 'none' | 'ineligible' | 'unavailable';
+    below: CheckoutNearbySuggestion[];
+    above: CheckoutNearbySuggestion[];
 };
 export type CheckoutQuotes = {
     orderId: string;
     fiatCurrency: string;
     platforms: CheckoutQuoteEntry[];
+    nearbySuggestions?: CheckoutNearbySuggestions;
 };
 export type CheckoutPayment = {
     id: string;
     orderId: string;
     status: CheckoutPaymentStatusType;
     rail: string;
+    paymentMethodId: string | null;
+    proofMode: ProofMode;
+    attestation: {
+        serviceUrl: string;
+    };
     currency: string;
     payTo: string;
+    /** Recipient rating in the 1.0–5.0 range, rounded to one decimal. */
+    recipientRating: number;
     quote: CheckoutPaymentQuote;
     quoteExpiresAt: string;
+    memoPolicy: CheckoutPaymentMemoPolicyType;
+    suggestedMemo: string | null;
     paymentAmount: string;
     currencyPerUsdRate: string;
     netSettledUsdcAmount: string | null;
@@ -194,28 +260,33 @@ export type CheckoutPayment = {
     referralFees: SettlementReferralFeeEntry[] | null;
     railIdentifier: string | null;
     fulfillTransaction: string | null;
+    errorCode?: string | null;
+    errorMessage?: string | null;
     completedAt: string | null;
     createdAt: string;
     updatedAt: string | null;
 };
+export type CheckoutAggregatePayment = Omit<CheckoutPayment, 'paymentMethodId'> & {
+    paymentMethodId?: string | null;
+};
 export type CheckoutAggregate = {
     order: CheckoutOrder;
     merchant: CheckoutMerchant;
-    currentPayment: CheckoutPayment | null;
+    currentPayment: CheckoutAggregatePayment | null;
 };
 export type CreateOrderResponse = {
     order: CheckoutOrder;
     orderToken: string;
 };
-export type CreateCheckoutResponse = CreateOrderResponse;
-export type CheckoutCreateResponse = CreateOrderResponse;
 export type CreatePaymentRequest = {
     rail: string;
+    paymentMethodId?: string;
     fiatCurrency?: string;
     currency?: string;
     replacementPaymentId?: string;
     quoteLimit?: number;
     excludedPayToValues?: string[];
+    refundTo?: string;
 };
 export type CheckoutPaymentCreationResponse = CheckoutPayment & {
     relayerTransactionId?: string;
@@ -227,6 +298,7 @@ export type PaymentDeeplinkResponse = {
     url: string;
     proofSubmissionUrl: string;
     checkoutReturnUrl: string;
+    linkKind?: 'app_clip' | 'deeplink';
 };
 export type CheckoutDeeplinkResponse = PaymentDeeplinkResponse;
 export type MerchantConfig = {
@@ -240,17 +312,20 @@ export type MerchantConfig = {
     sweepEnabled: boolean;
     recipientOverrideEnabled: boolean;
     disableBranding: boolean;
+    dynamicOrdersEnabled: boolean;
     merchantCheckoutTheme: MerchantCheckoutTheme;
     platformReferralFeeConfig: ReferralFeeConfig | null;
     referralSplitConfig: ReferralSplitConfig | null;
+    flatFeePricing: boolean;
     createdAt: string;
     updatedAt: string | null;
 };
 export type MerchantUser = {
     id: string;
     email: string | null;
-    privyUserId: string;
-    role: 'OWNER' | 'MANAGER';
+    privyUserId: string | null;
+    v1PrivyUserId: string | null;
+    role: 'OWNER' | 'MANAGER' | 'CASHIER';
     merchantId: string | null;
     createdAt: string;
     updatedAt: string | null;
@@ -259,11 +334,19 @@ export type MerchantProfile = {
     id: string;
     name: string;
     logoUrl: string | null;
+    industryType: string | null;
+    industryOtherText: string | null;
+    integrationPath: MerchantIntegrationPathValue | null;
+    onboardingCompletedAt: string | null;
+    onboardingSkippedAt: string | null;
     apiKey: string;
     environment: MerchantEnvironmentType;
     sandboxMerchantId: string | null;
+    inPersonCheckoutEnabled: boolean;
     evmWalletAddress: string | null;
     solanaWalletAddress: string | null;
+    v1EvmWalletAddress: string | null;
+    v1SolanaWalletAddress: string | null;
     tier: 'FREE' | 'PRO';
     createdAt: string;
     updatedAt: string | null;
@@ -328,6 +411,8 @@ export type Merchant = {
     id: string;
     name: string;
     logoUrl?: string | null;
+    industryType?: string | null;
+    industryOtherText?: string | null;
     disableBranding?: boolean;
     apiKey: string;
     environment?: MerchantEnvironmentType;
@@ -475,6 +560,7 @@ type CreateSessionBaseRequest = {
     cancelUrl?: string;
     metadata?: Record<string, string>;
     enabledPaymentPlatforms?: PaymentPlatformType[];
+    dynamicOrdersEnabled?: boolean;
 };
 type CreateSessionExactTokenRequest = CreateSessionBaseRequest & {
     checkoutMode?: 'exact-token';
@@ -596,15 +682,48 @@ export interface OrderBridgeInfo {
     fallbackToOrigin?: boolean;
     failureMessage?: string | null;
 }
+export declare const MerchantIntegrationPath: {
+    readonly CUSTOM_API: "CUSTOM_API";
+    readonly WOOCOMMERCE: "WOOCOMMERCE";
+    readonly IN_PERSON: "IN_PERSON";
+    readonly TELEGRAM: "TELEGRAM";
+    readonly SHOPIFY: "SHOPIFY";
+};
+export type MerchantIntegrationPathValue = typeof MerchantIntegrationPath[keyof typeof MerchantIntegrationPath];
+export declare const OnboardingStepStatus: {
+    readonly DONE: "done";
+    readonly TODO: "todo";
+};
+export type OnboardingStepStatusValue = typeof OnboardingStepStatus[keyof typeof OnboardingStepStatus];
+export declare const OnboardingStepVerifiedBy: {
+    readonly AUTO: "auto";
+    readonly MANUAL: "manual";
+};
+export type OnboardingStepVerifiedByValue = typeof OnboardingStepVerifiedBy[keyof typeof OnboardingStepVerifiedBy];
+export type OnboardingStepState = {
+    id: string;
+    status: OnboardingStepStatusValue;
+    verifiedBy: OnboardingStepVerifiedByValue;
+};
+export type MerchantOnboardingResponse = {
+    path: MerchantIntegrationPathValue | null;
+    sandboxApiKey: string | null;
+    completedAt: string | null;
+    skippedAt: string | null;
+    steps: OnboardingStepState[];
+};
 export declare const WebhookEventType: {
     readonly ORDER_CREATED: "ORDER_CREATED";
     readonly ORDER_FULFILLED: "ORDER_FULFILLED";
     readonly ORDER_CANCELLED: "ORDER_CANCELLED";
+    readonly ORDER_RESIZED: "ORDER_RESIZED";
     readonly PAYMENT_CREATED: "PAYMENT_CREATED";
     readonly PAYMENT_SETTLED: "PAYMENT_SETTLED";
     readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
     readonly PAYMENT_EXPIRED: "PAYMENT_EXPIRED";
     readonly PAYMENT_FAILED: "PAYMENT_FAILED";
+    readonly REFUND_PENDING: "REFUND_PENDING";
+    readonly REFUND_COMPLETED: "REFUND_COMPLETED";
     readonly PAYMENT_BRIDGE_PENDING: "PAYMENT_BRIDGE_PENDING";
     readonly PAYMENT_BRIDGE_SUBMITTED: "PAYMENT_BRIDGE_SUBMITTED";
     readonly PAYMENT_BRIDGE_COMPLETED: "PAYMENT_BRIDGE_COMPLETED";
@@ -631,9 +750,6 @@ export type Webhook = {
     createdAt: string;
     updatedAt: string;
 };
-export type WebhookWithSecret = Webhook & {
-    secret: string;
-};
 export type WebhookDelivery = {
     id: string;
     webhookId: string;
@@ -653,7 +769,12 @@ export type WebhookPayload = {
     data: {
         order: CheckoutOrder | null;
         payment: CheckoutPayment | null;
+        refund: Record<string, unknown> | null;
         paymentBridge: Record<string, unknown> | null;
+        resize?: {
+            previousAmountUsdc: string;
+            newAmountUsdc: string;
+        };
     };
 };
 export type CreateWebhookRequest = {
@@ -661,7 +782,10 @@ export type CreateWebhookRequest = {
     events?: WebhookEventTypeValue[];
     customHeaders?: WebhookHeader[];
 };
-export type CreateWebhookResponse = WebhookWithSecret;
+export type CreateWebhookResponse = {
+    webhook: Webhook;
+    secret: string;
+};
 export type UpdateWebhookRequest = {
     url?: string;
     events?: WebhookEventTypeValue[];

package/dist/types.js

@@ -10,6 +10,14 @@ export const PaymentPlatform = {
     N26: 'n26',
     CHIME: 'chime',
 };
+const PAYMENT_PLATFORM_VALUES = new Set(Object.values(PaymentPlatform));
+/**
+ * Type guard for PaymentPlatform values.
+ * Returns true if `value` is one of the known PaymentPlatform enum values.
+ */
+export function isPaymentPlatform(value) {
+    return typeof value === 'string' && PAYMENT_PLATFORM_VALUES.has(value);
+}
 // Supported chains for USDC destination
 // Re-exported from chains.ts for backward compatibility
 export const SupportedChains = SupportedChainsMap;
@@ -53,12 +61,23 @@ export const FeePayer = {
     MERCHANT: 'MERCHANT',
     PAYEE: 'PAYEE',
 };
+export const MerchantPaymentFlowMode = {
+    EXCLUSIVE_SAR: 'EXCLUSIVE_SAR',
+    PREFER_SAR: 'PREFER_SAR',
+    PREFER_BUYER_TEE: 'PREFER_BUYER_TEE',
+    EXCLUSIVE_BUYER_TEE: 'EXCLUSIVE_BUYER_TEE',
+};
 export const CheckoutOrderStatus = {
     CREATED: 'CREATED',
     PARTIALLY_FULFILLED: 'PARTIALLY_FULFILLED',
     FULFILLED: 'FULFILLED',
     CANCELLED: 'CANCELLED',
 };
+export const CheckoutOrderRefundStatus = {
+    NONE: 'NONE',
+    PENDING: 'PENDING',
+    COMPLETED: 'COMPLETED',
+};
 export const CheckoutPaymentStatus = {
     CREATED: 'CREATED',
     SETTLED: 'SETTLED',
@@ -66,6 +85,11 @@ export const CheckoutPaymentStatus = {
     EXPIRED: 'EXPIRED',
     FAILED: 'FAILED',
 };
+export const CheckoutPaymentMemoPolicy = {
+    NONE: 'NONE',
+    REQUIRED: 'REQUIRED',
+    EMPTY: 'EMPTY',
+};
 // Structured error codes for Order failures
 export const OrderErrorCode = {
     // Proof verification errors
@@ -97,16 +121,35 @@ export const TrancheCurrency = {
     USD: 'USD',
     USDC: 'USDC',
 };
+// ============ Merchant Onboarding Types ============
+export const MerchantIntegrationPath = {
+    CUSTOM_API: 'CUSTOM_API',
+    WOOCOMMERCE: 'WOOCOMMERCE',
+    IN_PERSON: 'IN_PERSON',
+    TELEGRAM: 'TELEGRAM',
+    SHOPIFY: 'SHOPIFY',
+};
+export const OnboardingStepStatus = {
+    DONE: 'done',
+    TODO: 'todo',
+};
+export const OnboardingStepVerifiedBy = {
+    AUTO: 'auto',
+    MANUAL: 'manual',
+};
 // ============ Webhook Types ============
 export const WebhookEventType = {
     ORDER_CREATED: 'ORDER_CREATED',
     ORDER_FULFILLED: 'ORDER_FULFILLED',
     ORDER_CANCELLED: 'ORDER_CANCELLED',
+    ORDER_RESIZED: 'ORDER_RESIZED',
     PAYMENT_CREATED: 'PAYMENT_CREATED',
     PAYMENT_SETTLED: 'PAYMENT_SETTLED',
     PAYMENT_CANCELLED: 'PAYMENT_CANCELLED',
     PAYMENT_EXPIRED: 'PAYMENT_EXPIRED',
     PAYMENT_FAILED: 'PAYMENT_FAILED',
+    REFUND_PENDING: 'REFUND_PENDING',
+    REFUND_COMPLETED: 'REFUND_COMPLETED',
     PAYMENT_BRIDGE_PENDING: 'PAYMENT_BRIDGE_PENDING',
     PAYMENT_BRIDGE_SUBMITTED: 'PAYMENT_BRIDGE_SUBMITTED',
     PAYMENT_BRIDGE_COMPLETED: 'PAYMENT_BRIDGE_COMPLETED',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/pay-shared",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "description": "Shared TypeScript types, enums, and chain utilities used by ZKP2P Pay API, SDK, and frontend apps.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,11 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "lint": "eslint . --ext .ts,.tsx",
+    "test": "vitest run",
     "prepack": "npm run build",
     "prepublishOnly": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "vitest": "^1.6.1"
   }
 }