@zkp2p/pay-shared 3.0.0 → 4.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@3.0.0
+npm install @zkp2p/pay-shared@4.0.0
 ```
 
 ## Published artifacts
@@ -58,6 +58,7 @@ console.log(CheckoutOrderStatus.CREATED); // "CREATED"
 ```ts
 import {
   BASE_CHAIN_ID,
+  TRON_CHAIN_ID,
   getSupportedChainIds,
   parseSupportedChainSelection,
   resolveDestinationTokenAddress,
@@ -67,8 +68,9 @@ import {
 const chainId = parseSupportedChainSelection('polygon'); // 137
 const usdc = resolveDestinationTokenAddress('USDC', 137); // Chain-specific USDC address
 const supportedAliases = getSupportedDestinationTokenAliasesForChain(BASE_CHAIN_ID); // ["USDC", "USDT"]
+const tronAliases = getSupportedDestinationTokenAliasesForChain(TRON_CHAIN_ID); // ["USDT"]
 
-console.log(getSupportedChainIds(), chainId, usdc, supportedAliases);
+console.log(getSupportedChainIds(), chainId, usdc, supportedAliases, tronAliases);
 ```
 
 ## Key Exports
@@ -100,6 +102,7 @@ Chain constants and helpers:
 - `BASE_CHAIN_ID`
 - `HYPEREVM_CHAIN_ID`
 - `SOLANA_CHAIN_ID`
+- `TRON_CHAIN_ID`
 - `SUPPORTED_DESTINATION_TOKEN_ALIASES`
 - `parseSupportedChainSelection(...)`
 - `resolveDestinationTokenAddress(...)`

package/dist/attribution.d.ts

@@ -0,0 +1,4 @@
+export declare enum IntentAttributionReferrer {
+    PAY = "zkp2p-pay",
+    SUPPORT = "zkp2p-pay-cs"
+}

package/dist/attribution.js

@@ -0,0 +1,5 @@
+export var IntentAttributionReferrer;
+(function (IntentAttributionReferrer) {
+    IntentAttributionReferrer["PAY"] = "zkp2p-pay";
+    IntentAttributionReferrer["SUPPORT"] = "zkp2p-pay-cs";
+})(IntentAttributionReferrer || (IntentAttributionReferrer = {}));

package/dist/chains.d.ts

@@ -1,13 +1,14 @@
 /**
  * Centralized chain configuration for ZKP2P Pay.
  *
- * All supported chains and their USDC addresses are defined here.
+ * All supported payout chains and their destination token addresses are defined here.
  * Import this module instead of duplicating chain configs in each app.
  */
 export declare const BASE_CHAIN_ID = 8453;
 export declare const ETHEREUM_CHAIN_ID = 1;
 export declare const HYPEREVM_CHAIN_ID = 999;
 export declare const SOLANA_CHAIN_ID = 792703809;
+export declare const TRON_CHAIN_ID = 728126428;
 export declare const SUPPORTED_DESTINATION_TOKEN_ALIASES: readonly ["USDC", "USDT"];
 export type DestinationTokenAlias = (typeof SUPPORTED_DESTINATION_TOKEN_ALIASES)[number];
 export declare const DEFAULT_DESTINATION_TOKEN_ALIAS: DestinationTokenAlias;
@@ -20,7 +21,7 @@ export interface ChainConfig {
     chainId: number;
     name: string;
     shortName: string;
-    usdcAddress: string;
+    usdcAddress: string | null;
     isOriginChain: boolean;
     isEvm: boolean;
     explorerUrl?: string;

package/dist/chains.js

@@ -1,7 +1,7 @@
 /**
  * Centralized chain configuration for ZKP2P Pay.
  *
- * All supported chains and their USDC addresses are defined here.
+ * All supported payout chains and their destination token addresses are defined here.
  * Import this module instead of duplicating chain configs in each app.
  */
 // Chain IDs
@@ -9,6 +9,7 @@ export const BASE_CHAIN_ID = 8453;
 export const ETHEREUM_CHAIN_ID = 1;
 export const HYPEREVM_CHAIN_ID = 999;
 export const SOLANA_CHAIN_ID = 792703809;
+export const TRON_CHAIN_ID = 728126428;
 export const SUPPORTED_DESTINATION_TOKEN_ALIASES = ['USDC', 'USDT'];
 export const DEFAULT_DESTINATION_TOKEN_ALIAS = 'USDC';
 // Mainnet chain configurations
@@ -97,6 +98,15 @@ export const MAINNET_CHAINS = {
         isEvm: false,
         explorerUrl: 'https://solscan.io',
     },
+    [TRON_CHAIN_ID]: {
+        chainId: TRON_CHAIN_ID,
+        name: 'Tron',
+        shortName: 'TRON',
+        usdcAddress: null,
+        isOriginChain: false,
+        isEvm: false,
+        explorerUrl: 'https://tronscan.org/#',
+    },
 };
 function normalizeChainSelectionKey(value) {
     return value.trim().toLowerCase().replace(/[^a-z0-9]/g, '');
@@ -123,6 +133,8 @@ const CHAIN_SELECTION_ALIASES = {
     hl: 999,
     solana: 792703809,
     sol: 792703809,
+    tron: TRON_CHAIN_ID,
+    trx: TRON_CHAIN_ID,
 };
 for (const chainId of SUPPORTED_CHAIN_IDS) {
     const chainConfig = MAINNET_CHAINS[chainId];
@@ -164,6 +176,10 @@ const DESTINATION_TOKEN_ADDRESSES = {
     999: {
         usdt: '0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb',
     },
+    // Tron
+    [TRON_CHAIN_ID]: {
+        usdt: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+    },
 };
 function isKnownDestinationTokenAlias(value) {
     return SUPPORTED_DESTINATION_TOKEN_ALIASES.includes(value);
@@ -245,7 +261,7 @@ export function getOriginChainId() {
  * Get USDC address for a chain.
  */
 export function getUsdcAddress(chainId) {
-    return getChainConfig(chainId)?.usdcAddress;
+    return getChainConfig(chainId)?.usdcAddress ?? undefined;
 }
 /**
  * Resolve destination token alias to chain-specific token address.

package/dist/crypto.d.ts

@@ -1,5 +1,4 @@
 export declare const BITCOIN_CHAIN_ID = 8253038;
-export declare const TRON_CHAIN_ID = 728126428;
 export declare const PAY_CRYPTO_TOKEN_SYMBOLS: readonly ["BTC", "USDC", "USDT", "ETH", "PYUSD", "SOL", "BNB", "HYPE", "WBTC", "USDH"];
 export type PayCryptoTokenSymbol = (typeof PAY_CRYPTO_TOKEN_SYMBOLS)[number];
 export declare const DEFAULT_ENABLED_PAY_CRYPTO_TOKENS: PayCryptoTokenSymbol[];
@@ -45,7 +44,7 @@ export declare function getSupportedPayCryptoChainIdsForToken(symbol: PayCryptoT
 /**
  * Returns the display name for a chain used by the "Pay with crypto"
  * flow. Resolves through PAY_CRYPTO_CHAIN_CONFIGS first so Bitcoin
- * and Tron (which are not in MAINNET_CHAINS) get the correct label.
+ * gets the correct label.
  * Falls back to getChainName for chains not registered here.
  */
 export declare function getPayCryptoChainName(chainId: number): string;

package/dist/crypto.js

@@ -1,6 +1,5 @@
-import { MAINNET_CHAINS, BASE_CHAIN_ID, ETHEREUM_CHAIN_ID, SOLANA_CHAIN_ID, getChainName, } from './chains.js';
+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;
-export const TRON_CHAIN_ID = 728126428;
 export const PAY_CRYPTO_TOKEN_SYMBOLS = [
     'BTC', // Kept in symbols for DB compatibility with existing sessions
     'USDC',
@@ -56,11 +55,6 @@ const PAY_CRYPTO_CHAIN_CONFIGS = {
         name: 'Bitcoin',
         shortName: 'BTC',
     },
-    [TRON_CHAIN_ID]: {
-        chainId: TRON_CHAIN_ID,
-        name: 'Tron',
-        shortName: 'TRON',
-    },
 };
 const CHAIN_TOKEN_CONFIGS = {
     [BITCOIN_CHAIN_ID]: {
@@ -219,7 +213,7 @@ export function getSupportedPayCryptoChainIdsForToken(symbol, enabledChainIds) {
 /**
  * Returns the display name for a chain used by the "Pay with crypto"
  * flow. Resolves through PAY_CRYPTO_CHAIN_CONFIGS first so Bitcoin
- * and Tron (which are not in MAINNET_CHAINS) get the correct label.
+ * gets the correct label.
  * Falls back to getChainName for chains not registered here.
  */
 export function getPayCryptoChainName(chainId) {

package/dist/index.d.ts

@@ -6,8 +6,12 @@ export * from './rails.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 './paypalSarPhase.js';
 export * from './paypalSarVerify.js';
 export * from './payeeFeeCap.js';
 export * from './onboarding.js';
+export * from './llmIntegration.js';
+export * from './tiers.js';
+export * from './attribution.js';

package/dist/index.js

@@ -6,8 +6,12 @@ export * from './rails.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 './paypalSarPhase.js';
 export * from './paypalSarVerify.js';
 export * from './payeeFeeCap.js';
 export * from './onboarding.js';
+export * from './llmIntegration.js';
+export * from './tiers.js';
+export * from './attribution.js';

package/dist/llmIntegration.d.ts

@@ -0,0 +1,111 @@
+import type { OnboardingStepIdValue } from './onboarding.js';
+import type { MerchantEnvironmentType, MerchantIntegrationPathValue, OnboardingStepStatusValue } from './types.js';
+export declare const IntegrationStepActor: {
+    readonly AGENT: "AGENT";
+    readonly MERCHANT: "MERCHANT";
+};
+export type IntegrationStepActorValue = typeof IntegrationStepActor[keyof typeof IntegrationStepActor];
+/**
+ * Which party can satisfy each onboarding step when a coding agent drives the
+ * integration. AGENT steps are reachable with an API key alone; MERCHANT steps
+ * need a Privy-authenticated dashboard session (tier selection), a human decision
+ * (industry, path), or physical action. An agent that retries a MERCHANT step
+ * gets 403 with no way to learn the wall is structural, so it is told up front.
+ */
+export declare const INTEGRATION_STEP_ACTORS: Readonly<Record<OnboardingStepIdValue, IntegrationStepActorValue>>;
+export type IntegrationDeliveryEvidence = {
+    /** WebhookDeliveryStatus. PENDING means queued but not yet attempted. */
+    readonly deliveryStatus: string;
+    readonly attempts: number;
+    readonly responseCode: number | null;
+    /**
+     * Locally generated transport failure reason — SSRF block, DNS timeout, fetch
+     * error. `null` whenever ANY HTTP response was received, including 401 and 500:
+     * webhook.service.ts records `responseBody: null` on every received response and
+     * never stores receiver body content. Diagnose received responses from
+     * `responseCode`; use this field only to explain why nothing was received.
+     */
+    readonly error: string | null;
+    readonly attemptedAt: string | null;
+};
+/**
+ * Webhooks are scoped per merchant row, and sandbox is its own row. An agent needs
+ * both: the sandbox registration is what a test order actually delivers to, and the
+ * live registration is what real payments deliver to (and what the onboarding step
+ * reads). Reporting only one hides half the integration.
+ */
+export type IntegrationWebhookEvidence = {
+    readonly webhookId: string | null;
+    readonly webhookUrl: string | null;
+    readonly subscribedEvents: readonly string[];
+    readonly lastDelivery: IntegrationDeliveryEvidence | null;
+};
+export type IntegrationStepEvidence = {
+    readonly sandboxOrderId?: string | null;
+    readonly sandboxOrderStatus?: string | null;
+    readonly liveOrderId?: string | null;
+    readonly canCreateLiveOrders?: boolean;
+    readonly sandboxWebhook?: IntegrationWebhookEvidence | null;
+    readonly liveWebhook?: IntegrationWebhookEvidence | null;
+    readonly tier?: string | null;
+    readonly missingFields?: readonly string[];
+};
+export type IntegrationStatusStep = {
+    readonly id: OnboardingStepIdValue;
+    readonly status: OnboardingStepStatusValue;
+    readonly actor: IntegrationStepActorValue;
+    readonly evidence: IntegrationStepEvidence;
+};
+export type IntegrationNextAction = {
+    readonly stepId: OnboardingStepIdValue;
+    readonly actor: IntegrationStepActorValue;
+    readonly instruction: string;
+    readonly docs: string;
+};
+export type IntegrationStatusResponse = {
+    readonly merchant: {
+        readonly id: string;
+        readonly name: string;
+        readonly integrationPath: MerchantIntegrationPathValue | null;
+    };
+    readonly environmentOfKey: MerchantEnvironmentType;
+    /** Onboarding checklist completion. See `verified` before trusting this. */
+    readonly complete: boolean;
+    /**
+     * True only when a sandbox ORDER_FULFILLED delivery has actually been accepted
+     * by the merchant's handler.
+     *
+     * Deliberately independent of `complete`. `GO_LIVE` carries
+     * `impliesPrevious: true`, so a single live order forces every earlier step —
+     * including `webhook` — to DONE, and `complete` would report a verified
+     * integration for a handler that has never successfully received anything.
+     * `verified` is the field the agent must gate on.
+     */
+    readonly verified: boolean;
+    /**
+     * True when the live merchant row has an active webhook subscribed to
+     * ORDER_FULFILLED. This is independent of the broader onboarding webhook step.
+     */
+    readonly liveWebhookReady: boolean;
+    readonly steps: readonly IntegrationStatusStep[];
+    readonly nextAction: IntegrationNextAction | null;
+    /**
+     * Missing agent work in dependency order: sandbox webhook, accepted sandbox
+     * delivery, then live webhook plus live order. Independent of registry order.
+     */
+    readonly nextAgentAction: IntegrationNextAction | null;
+};
+export type SandboxTestOrderRequest = {
+    readonly orderId?: string;
+    readonly requestedUsdcAmount?: string;
+    readonly rail?: string;
+};
+export type SandboxTestOrderResponse = {
+    readonly orderId: string;
+    readonly status: string;
+    readonly paymentId: string;
+};
+export type LlmIntegrationPromptResponse = {
+    readonly prompt: string;
+    readonly filename: string;
+};

package/dist/llmIntegration.js

@@ -0,0 +1,28 @@
+import { OnboardingStepId } from './onboarding.js';
+export const IntegrationStepActor = {
+    AGENT: 'AGENT',
+    MERCHANT: 'MERCHANT',
+};
+/**
+ * Which party can satisfy each onboarding step when a coding agent drives the
+ * integration. AGENT steps are reachable with an API key alone; MERCHANT steps
+ * need a Privy-authenticated dashboard session (tier selection), a human decision
+ * (industry, path), or physical action. An agent that retries a MERCHANT step
+ * gets 403 with no way to learn the wall is structural, so it is told up front.
+ */
+export const INTEGRATION_STEP_ACTORS = {
+    [OnboardingStepId.PROFILE]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.INDUSTRY]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.PLAN]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.PATH]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.RAILS]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.INTEGRATION]: IntegrationStepActor.AGENT,
+    [OnboardingStepId.WEBHOOK]: IntegrationStepActor.AGENT,
+    [OnboardingStepId.GO_LIVE]: IntegrationStepActor.AGENT,
+    [OnboardingStepId.DOWNLOAD_PLUGIN]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.PLUGIN_API_KEY]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.TEST_ORDER]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.FIRST_QR]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.LINK_BOT]: IntegrationStepActor.MERCHANT,
+    [OnboardingStepId.REQUEST_SETUP]: IntegrationStepActor.MERCHANT,
+};

package/dist/onboarding.d.ts

@@ -1,8 +1,10 @@
 import type { MerchantIntegrationPathValue, OnboardingStepState, OnboardingStepVerifiedByValue } from './types.js';
+import type { MerchantTierName } from './tiers.js';
 export type OnboardingFacts = {
     hasName: boolean;
     hasLogo: boolean;
     hasIndustry: boolean;
+    hasSelectedTier: boolean;
     hasIntegrationPath: boolean;
     hasWebhook: boolean;
     hasSandboxOrder: boolean;
@@ -14,6 +16,7 @@ export type OnboardingFacts = {
 export declare const OnboardingStepId: {
     readonly PROFILE: "profile";
     readonly INDUSTRY: "industry";
+    readonly PLAN: "plan";
     readonly PATH: "path";
     readonly RAILS: "rails";
     readonly INTEGRATION: "integration";
@@ -34,6 +37,21 @@ export type OnboardingStepRegistryEntry = {
     readonly inChecklist: boolean;
     readonly impliesPrevious: boolean;
 };
+export declare const TierCardAction: {
+    readonly SELECT: "select";
+    readonly REQUEST: "request";
+};
+export type TierCardActionValue = typeof TierCardAction[keyof typeof TierCardAction];
+export type SelfServeMerchantTier = Exclude<MerchantTierName, 'CONCIERGE'>;
+export type TierCopy = {
+    readonly displayLabel: string;
+    readonly kicker: string;
+    readonly price: string;
+    readonly features: readonly string[];
+    readonly cardAction: TierCardActionValue;
+};
+/** Shared copy and card behavior for every displayable merchant tier. */
+export declare const TIER_COPY: Readonly<Record<MerchantTierName, TierCopy>>;
 export declare const ONBOARDING_STEP_REGISTRY: readonly OnboardingStepRegistryEntry[];
 export declare function resolveOnboardingSteps(facts: OnboardingFacts, path: MerchantIntegrationPathValue | null): OnboardingStepState[];
 export declare function isOnboardingComplete(steps: readonly OnboardingStepState[]): boolean;

package/dist/onboarding.js

@@ -1,7 +1,9 @@
 import { MerchantIntegrationPath, OnboardingStepStatus, OnboardingStepVerifiedBy, } from './types.js';
+import { TIER_DEFINITIONS, formatTierMonthlyLimitsCopy } from './tiers.js';
 export const OnboardingStepId = {
     PROFILE: 'profile',
     INDUSTRY: 'industry',
+    PLAN: 'plan',
     PATH: 'path',
     RAILS: 'rails',
     INTEGRATION: 'integration',
@@ -14,6 +16,54 @@ export const OnboardingStepId = {
     LINK_BOT: 'linkBot',
     REQUEST_SETUP: 'requestSetup',
 };
+export const TierCardAction = {
+    SELECT: 'select',
+    REQUEST: 'request',
+};
+/** Shared copy and card behavior for every displayable merchant tier. */
+export const TIER_COPY = {
+    // features[0] is the plan's monthly cap, formatted from TIER_DEFINITIONS so
+    // copy always matches the enforced limits. Every surface leads with it (the
+    // landing's rate rows, the onboarding tier cards, billing).
+    BASE: {
+        displayLabel: 'Base',
+        kicker: 'Self-serve',
+        price: '2.95% fiat / 1% crypto per successful payment',
+        features: [
+            formatTierMonthlyLimitsCopy(TIER_DEFINITIONS.BASE.monthlyLimits),
+            'Every platform included; Venmo, Cash App, and PayPal require staking',
+            'Verify payments with the Peer app or extension',
+            'Instant settlement, merchant-funded refunds',
+        ],
+        cardAction: TierCardAction.SELECT,
+    },
+    PRO: {
+        displayLabel: 'Pro',
+        kicker: 'Self-serve',
+        price: '4.95% fiat / 1% crypto per successful payment',
+        features: [
+            formatTierMonthlyLimitsCopy(TIER_DEFINITIONS.PRO.monthlyLimits),
+            'Everything in Base',
+            'Seller Autopilot: customers pay with no Peer app or extension',
+            'Checkout branding and priority support',
+        ],
+        cardAction: TierCardAction.SELECT,
+    },
+    CONCIERGE: {
+        displayLabel: 'Concierge',
+        kicker: 'With our team',
+        price: 'Custom pricing',
+        features: [
+            formatTierMonthlyLimitsCopy(TIER_DEFINITIONS.CONCIERGE.monthlyLimits),
+            'No staking and no lockups',
+            'Negotiated rate or flat-fee invoicing',
+            'Full integration support',
+            'Named support in a dedicated group',
+            'Custom embedded checkout and integrations',
+        ],
+        cardAction: TierCardAction.REQUEST,
+    },
+};
 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 },
@@ -48,13 +98,6 @@ export const ONBOARDING_STEP_REGISTRY = [
         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],
@@ -76,13 +119,6 @@ export const ONBOARDING_STEP_REGISTRY = [
         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],
@@ -99,17 +135,39 @@ export const ONBOARDING_STEP_REGISTRY = [
         inChecklist: true,
         impliesPrevious: true,
     },
+    {
+        id: OnboardingStepId.PLAN,
+        paths: 'ALL',
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        // Deliberately the last ask before go-live: a tier is only required for LIVE
+        // orders, and it can also be selected out-of-band (billing page, admin), so a
+        // done plan step must not imply the integration steps that now precede it.
+        impliesPrevious: false,
+    },
+    {
+        id: OnboardingStepId.GO_LIVE,
+        paths: [
+            MerchantIntegrationPath.CUSTOM_API,
+            MerchantIntegrationPath.TELEGRAM,
+            MerchantIntegrationPath.WOOCOMMERCE,
+        ],
+        verifiedBy: OnboardingStepVerifiedBy.AUTO,
+        inChecklist: true,
+        impliesPrevious: true,
+    },
 ];
 const autoStepPredicates = {
     [OnboardingStepId.PROFILE]: (facts) => facts.hasName && facts.hasLogo,
     [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,
     [OnboardingStepId.LINK_BOT]: (facts) => facts.hasSandboxFulfilledOrder,
-    [OnboardingStepId.GO_LIVE]: (facts) => facts.hasLiveFulfilledOrder,
+    [OnboardingStepId.GO_LIVE]: (facts) => facts.hasLiveOrder,
     [OnboardingStepId.FIRST_QR]: (facts) => facts.hasSandboxOrder,
 };
 export function resolveOnboardingSteps(facts, path) {

package/dist/tiers.d.ts

@@ -0,0 +1,57 @@
+import { type FeeTranche, type MerchantPaymentFlowModeType, type MerchantTierName } from './types.js';
+export type { MerchantTierName } from './types.js';
+export declare const TierChangeSource: {
+    readonly SELF_SERVE: "SELF_SERVE";
+    readonly ADMIN: "ADMIN";
+    readonly MIGRATION: "MIGRATION";
+};
+export type TierChangeSourceType = typeof TierChangeSource[keyof typeof TierChangeSource];
+/**
+ * A fee config resolved to concrete numbers. `mode: 'default'` is deliberately
+ * unrepresentable — it would resolve against a mutable global at read time.
+ *
+ * `tranches` IS included: it is frozen data, just amount-parameterised. The bracket
+ * is chosen from the order amount at resolution time by `feeService`, so it cannot be
+ * flattened to a single `valueBps` at snapshot time.
+ */
+export type MaterializedFeeConfig = {
+    readonly mode: 'exempt';
+} | {
+    readonly mode: 'flat';
+    readonly currency: 'USDC';
+    readonly valueBps: number;
+} | {
+    readonly mode: 'tranches';
+    readonly currency: 'USDC';
+    readonly tranches: readonly FeeTranche[];
+};
+/** Monthly caps for a self-serve tier. `volumeUsdc` is a decimal string in whole USDC. */
+export type TierMonthlyLimits = {
+    readonly volumeUsdc: string;
+    readonly orderCount: number;
+};
+type TierFeeDefinition = {
+    readonly fiatFeeConfig: MaterializedFeeConfig;
+    readonly cryptoFeeConfig: MaterializedFeeConfig;
+} | {
+    /** Paired nulls mean commercial terms are admin-configured and must never be overwritten. */
+    readonly fiatFeeConfig: null;
+    readonly cryptoFeeConfig: null;
+};
+export type TierDefinition = TierFeeDefinition & {
+    readonly quotePreference: MerchantPaymentFlowModeType | null;
+    /** Policy-role name in the support dashboard. A string literal — SupportPolicyRole is a type alias, not a runtime enum. */
+    readonly supportPolicyRole: string;
+    /** Monthly order-volume / order-count caps enforced at order creation. null = unlimited. */
+    readonly monthlyLimits: TierMonthlyLimits | null;
+    /** Marketing/display copy only — render verbatim, never parse or branch on entries. */
+    readonly features: readonly string[];
+};
+export declare const TIER_DEFINITIONS: Readonly<Record<MerchantTierName, TierDefinition>>;
+/** Server-side allowlist for self-serve tier selection — the only authority; `features` copy gates nothing. */
+export declare const SELF_SERVE_TIERS: readonly MerchantTierName[];
+/**
+ * Formats a tier's monthly caps for display. `volumeUsdc` is a whole-USDC decimal string;
+ * exact thousands render as `$10K`, anything else as `$2,500`.
+ */
+export declare function formatTierMonthlyLimitsCopy(limits: TierMonthlyLimits | null): string;

package/dist/tiers.js

@@ -0,0 +1,57 @@
+import { MerchantPaymentFlowMode, } from './types.js';
+export const TierChangeSource = {
+    SELF_SERVE: 'SELF_SERVE',
+    ADMIN: 'ADMIN',
+    MIGRATION: 'MIGRATION',
+};
+export const TIER_DEFINITIONS = {
+    BASE: {
+        fiatFeeConfig: { mode: 'flat', currency: 'USDC', valueBps: 295 },
+        cryptoFeeConfig: { mode: 'flat', currency: 'USDC', valueBps: 100 },
+        quotePreference: MerchantPaymentFlowMode.PREFER_BUYER_TEE,
+        supportPolicyRole: 'BASIC_MERCHANT',
+        monthlyLimits: { volumeUsdc: '10000', orderCount: 50 },
+        features: [
+            '2.95% fiat / 1% crypto platform fees',
+            'Staking required before transacting on chargebackable rails',
+        ],
+    },
+    PRO: {
+        fiatFeeConfig: { mode: 'flat', currency: 'USDC', valueBps: 495 },
+        cryptoFeeConfig: { mode: 'flat', currency: 'USDC', valueBps: 100 },
+        quotePreference: MerchantPaymentFlowMode.PREFER_SAR,
+        supportPolicyRole: 'PRO_MERCHANT',
+        monthlyLimits: { volumeUsdc: '30000', orderCount: 100 },
+        features: [
+            '4.95% fiat / 1% crypto platform fees',
+            'Staking required before transacting on chargebackable rails',
+        ],
+    },
+    CONCIERGE: {
+        fiatFeeConfig: null,
+        cryptoFeeConfig: null,
+        quotePreference: null,
+        supportPolicyRole: 'CONCIERGE_MERCHANT',
+        monthlyLimits: null,
+        features: [
+            'Custom commercial terms',
+            'Flat-fee pricing available (admin-configured per merchant)',
+        ],
+    },
+};
+/** Server-side allowlist for self-serve tier selection — the only authority; `features` copy gates nothing. */
+export const SELF_SERVE_TIERS = ['BASE', 'PRO'];
+/**
+ * Formats a tier's monthly caps for display. `volumeUsdc` is a whole-USDC decimal string;
+ * exact thousands render as `$10K`, anything else as `$2,500`.
+ */
+export function formatTierMonthlyLimitsCopy(limits) {
+    if (limits === null) {
+        return 'Unlimited volume and orders';
+    }
+    const whole = limits.volumeUsdc.split('.')[0] ?? '0';
+    const volume = whole.length > 3 && /^\d+000$/.test(whole)
+        ? `$${whole.slice(0, -3)}K`
+        : `$${whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}`;
+    return `Up to ${volume} volume and ${limits.orderCount} orders per month`;
+}

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { PayCryptoTokenSymbol } from './crypto.js';
 import type { ProofMode } from './buyerTee.js';
+import type { OnboardingStepIdValue } from './onboarding.js';
 export declare const PaymentPlatform: {
     readonly VENMO: "venmo";
     readonly CASHAPP: "cashapp";
@@ -91,6 +92,46 @@ export declare const CheckoutPaymentStatus: {
     readonly FAILED: "FAILED";
 };
 export type CheckoutPaymentStatusType = typeof CheckoutPaymentStatus[keyof typeof CheckoutPaymentStatus];
+export declare const PaymentChargebackStatus: {
+    readonly NONE: "NONE";
+    readonly CHARGEBACKED: "CHARGEBACKED";
+};
+export type PaymentChargebackStatusType = typeof PaymentChargebackStatus[keyof typeof PaymentChargebackStatus];
+export declare const OrderChargebackStatus: {
+    readonly NONE: "NONE";
+    readonly PARTIALLY_CHARGEBACKED: "PARTIALLY_CHARGEBACKED";
+    readonly CHARGEBACKED: "CHARGEBACKED";
+};
+export type OrderChargebackStatusType = typeof OrderChargebackStatus[keyof typeof OrderChargebackStatus];
+export declare const ChargebackRefundOverlap: {
+    readonly NONE: "NONE";
+    readonly PENDING_HALTED: "PENDING_HALTED";
+    readonly SUBMITTING_OR_UNKNOWN: "SUBMITTING_OR_UNKNOWN";
+    readonly ALREADY_SUBMITTED: "ALREADY_SUBMITTED";
+    readonly ALREADY_REFUNDED: "ALREADY_REFUNDED";
+};
+export type ChargebackRefundOverlapType = typeof ChargebackRefundOverlap[keyof typeof ChargebackRefundOverlap];
+export declare const PaymentBridgeStatus: {
+    readonly PENDING: "PENDING";
+    readonly SUBMITTED: "SUBMITTED";
+    readonly COMPLETED: "COMPLETED";
+    readonly FAILED: "FAILED";
+};
+export type PaymentBridgeStatusType = typeof PaymentBridgeStatus[keyof typeof PaymentBridgeStatus];
+export type PaymentChargebackFact = {
+    paymentId: string;
+    intentHash: string;
+    disputeId: string;
+    status: typeof PaymentChargebackStatus.CHARGEBACKED;
+    compensatedUsdcAmount: string;
+    disputedAt: string;
+    disputeTxHash: string;
+    refundOverlap: ChargebackRefundOverlapType;
+    bridgeOrSweepOverlap: null | {
+        paymentBridgeId: string;
+        status: PaymentBridgeStatusType;
+    };
+};
 export declare const CheckoutPaymentMemoPolicy: {
     readonly NONE: "NONE";
     readonly REQUIRED: "REQUIRED";
@@ -159,6 +200,8 @@ export type CheckoutOrder = {
     id: string;
     merchantId: string;
     status: CheckoutOrderStatusType;
+    chargebackStatus: OrderChargebackStatusType;
+    chargebacks: PaymentChargebackFact[];
     refundStatus: CheckoutOrderRefundStatusType;
     refundAmountUsdc: string | null;
     refundDepositId: string | null;
@@ -229,6 +272,35 @@ export type CheckoutNearbySuggestions = {
     below: CheckoutNearbySuggestion[];
     above: CheckoutNearbySuggestion[];
 };
+export type QuoteAvailabilityRequest = {
+    amount: string;
+    quoteMode: CheckoutModeType;
+    fiatCurrency?: string;
+    destinationChainId: string | number;
+    destinationToken: string;
+    destinationAddress: string;
+    /** Max suggestions PER DIRECTION (1-10, API default 3). A response can carry up to 2x this. */
+    nearbyQuotesCount?: number;
+};
+export type QuoteAvailabilitySuggestion = {
+    suggestedAmount: string;
+    percentDifference: string;
+    rail: string;
+    paymentAmount: string;
+    paymentCurrency: string;
+    tokenAmount: string;
+    conversionRate: string;
+};
+export type QuoteAvailabilitySuggestions = {
+    below: QuoteAvailabilitySuggestion[];
+    above: QuoteAvailabilitySuggestion[];
+};
+/** `nearbySuggestions` is always null when `available` is true. */
+export type QuoteAvailability = {
+    available: boolean;
+    quoteCount: number;
+    nearbySuggestions: QuoteAvailabilitySuggestions | null;
+};
 export type CheckoutQuotes = {
     orderId: string;
     fiatCurrency: string;
@@ -239,6 +311,8 @@ export type CheckoutPayment = {
     id: string;
     orderId: string;
     status: CheckoutPaymentStatusType;
+    chargebackStatus: PaymentChargebackStatusType;
+    chargeback: PaymentChargebackFact | null;
     rail: string;
     paymentMethodId: string | null;
     proofMode: ProofMode;
@@ -290,6 +364,7 @@ export type CreatePaymentRequest = {
 };
 export type CheckoutPaymentCreationResponse = CheckoutPayment & {
     relayerTransactionId?: string;
+    recipientRecovery?: 'matched' | 'missed' | 'not_applicable';
 };
 export type PaymentDeeplinkResponse = {
     paymentId: string;
@@ -330,6 +405,7 @@ export type MerchantUser = {
     createdAt: string;
     updatedAt: string | null;
 };
+export type MerchantTierName = 'BASE' | 'PRO' | 'CONCIERGE';
 export type MerchantProfile = {
     id: string;
     name: string;
@@ -347,7 +423,7 @@ export type MerchantProfile = {
     solanaWalletAddress: string | null;
     v1EvmWalletAddress: string | null;
     v1SolanaWalletAddress: string | null;
-    tier: 'FREE' | 'PRO';
+    tier: MerchantTierName | null;
     createdAt: string;
     updatedAt: string | null;
     merchantConfig: MerchantConfig | null;
@@ -370,6 +446,12 @@ export declare const OrderErrorCode: {
     readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
 };
 export type OrderErrorCodeType = typeof OrderErrorCode[keyof typeof OrderErrorCode];
+export type PaymentSigningErrorCode = 'MERCHANT_WALLET_NOT_DELEGATED' | 'MERCHANT_SIGNER_WALLET_MISSING' | 'MERCHANT_SIGNING_UNAVAILABLE';
+export declare const SubmissionChannel: {
+    readonly OZ_RELAYER: "OZ_RELAYER";
+    readonly MERCHANT_PRIVY: "MERCHANT_PRIVY";
+};
+export type SubmissionChannelType = (typeof SubmissionChannel)[keyof typeof SubmissionChannel];
 export declare const MerchantEnvironment: {
     readonly LIVE: "LIVE";
     readonly SANDBOX: "SANDBOX";
@@ -672,7 +754,7 @@ export interface BridgeStatusResponse {
     failureMessage?: string;
 }
 export interface OrderBridgeInfo {
-    status: 'PENDING' | 'SUBMITTED' | 'COMPLETED' | 'FAILED';
+    status: PaymentBridgeStatusType;
     destinationChainId: string;
     outputAmount?: string;
     estimatedOutputAmount?: string;
@@ -701,7 +783,7 @@ export declare const OnboardingStepVerifiedBy: {
 };
 export type OnboardingStepVerifiedByValue = typeof OnboardingStepVerifiedBy[keyof typeof OnboardingStepVerifiedBy];
 export type OnboardingStepState = {
-    id: string;
+    id: OnboardingStepIdValue;
     status: OnboardingStepStatusValue;
     verifiedBy: OnboardingStepVerifiedByValue;
 };
@@ -728,6 +810,9 @@ export declare const WebhookEventType: {
     readonly PAYMENT_BRIDGE_SUBMITTED: "PAYMENT_BRIDGE_SUBMITTED";
     readonly PAYMENT_BRIDGE_COMPLETED: "PAYMENT_BRIDGE_COMPLETED";
     readonly PAYMENT_BRIDGE_FAILED: "PAYMENT_BRIDGE_FAILED";
+    readonly PAYMENT_CHARGEBACKED: "PAYMENT_CHARGEBACKED";
+    readonly ORDER_PARTIALLY_CHARGEBACKED: "ORDER_PARTIALLY_CHARGEBACKED";
+    readonly ORDER_CHARGEBACKED: "ORDER_CHARGEBACKED";
 };
 export type WebhookEventTypeValue = typeof WebhookEventType[keyof typeof WebhookEventType];
 export declare const WebhookDeliveryStatus: {
@@ -771,6 +856,13 @@ export type WebhookPayload = {
         payment: CheckoutPayment | null;
         refund: Record<string, unknown> | null;
         paymentBridge: Record<string, unknown> | null;
+        trigger?: {
+            type: 'CHARGEBACK_APPLIED';
+            chargeback: PaymentChargebackFact;
+        } | {
+            type: 'PAYMENT_SETTLED';
+            paymentId: string;
+        };
         resize?: {
             previousAmountUsdc: string;
             newAmountUsdc: string;

package/dist/types.js

@@ -85,6 +85,28 @@ export const CheckoutPaymentStatus = {
     EXPIRED: 'EXPIRED',
     FAILED: 'FAILED',
 };
+export const PaymentChargebackStatus = {
+    NONE: 'NONE',
+    CHARGEBACKED: 'CHARGEBACKED',
+};
+export const OrderChargebackStatus = {
+    NONE: 'NONE',
+    PARTIALLY_CHARGEBACKED: 'PARTIALLY_CHARGEBACKED',
+    CHARGEBACKED: 'CHARGEBACKED',
+};
+export const ChargebackRefundOverlap = {
+    NONE: 'NONE',
+    PENDING_HALTED: 'PENDING_HALTED',
+    SUBMITTING_OR_UNKNOWN: 'SUBMITTING_OR_UNKNOWN',
+    ALREADY_SUBMITTED: 'ALREADY_SUBMITTED',
+    ALREADY_REFUNDED: 'ALREADY_REFUNDED',
+};
+export const PaymentBridgeStatus = {
+    PENDING: 'PENDING',
+    SUBMITTED: 'SUBMITTED',
+    COMPLETED: 'COMPLETED',
+    FAILED: 'FAILED',
+};
 export const CheckoutPaymentMemoPolicy = {
     NONE: 'NONE',
     REQUIRED: 'REQUIRED',
@@ -113,6 +135,10 @@ export const OrderErrorCode = {
     SDK_ERROR: 'SDK_ERROR', // Unknown SDK error
     UNKNOWN_ERROR: 'UNKNOWN_ERROR', // Uncategorized error
 };
+export const SubmissionChannel = {
+    OZ_RELAYER: 'OZ_RELAYER',
+    MERCHANT_PRIVY: 'MERCHANT_PRIVY',
+};
 export const MerchantEnvironment = {
     LIVE: 'LIVE',
     SANDBOX: 'SANDBOX',
@@ -154,6 +180,9 @@ export const WebhookEventType = {
     PAYMENT_BRIDGE_SUBMITTED: 'PAYMENT_BRIDGE_SUBMITTED',
     PAYMENT_BRIDGE_COMPLETED: 'PAYMENT_BRIDGE_COMPLETED',
     PAYMENT_BRIDGE_FAILED: 'PAYMENT_BRIDGE_FAILED',
+    PAYMENT_CHARGEBACKED: 'PAYMENT_CHARGEBACKED',
+    ORDER_PARTIALLY_CHARGEBACKED: 'ORDER_PARTIALLY_CHARGEBACKED',
+    ORDER_CHARGEBACKED: 'ORDER_CHARGEBACKED',
 };
 export const WebhookDeliveryStatus = {
     PENDING: 'PENDING',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/pay-shared",
-  "version": "3.0.0",
+  "version": "4.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",