@provex/react 1.11.0 → 2.0.0

package/dist/{ProvexProvider-BAFqjyNz.d.ts → ProvexProvider-BG3DefVn.d.cts}

@@ -10,6 +10,7 @@ import { TokenInfo } from '@provex/utils/tokens';
 import { CaptureAdapter, ProvingState, CaptureCandidate } from '@provex/proving';
 import * as _provex_utils from '@provex/utils';
 import { WriteHookParams } from '@valve-tech/wallet-adapter';
+import { C as Clock } from './clock-BDtn-Itb.cjs';
 
 /**
  * @fileoverview Hook for fetching deposits that match a buyer's criteria.
@@ -439,31 +440,6 @@ interface PayeeDetails {
     platformName?: string;
     [key: string]: unknown;
 }
-/** Attestation request for zkTLS proof submission. */
-interface AttestationParams {
-    /** Payment platform (e.g. 'chase', 'venmo') */
-    platform: string;
-    /** Action type (e.g. 'transfer_zelle', 'transfer_venmo') */
-    actionType: string;
-    /** Reclaim proofs */
-    proofs: unknown[];
-    /** Chain ID for the attestation */
-    chainId: number;
-    /** Verifying contract address */
-    verifyingContract: Hex;
-    /** Intent data for the attestation */
-    intent: unknown;
-}
-/** Attestation response with signed payment proof. */
-interface AttestationResponse {
-    success: boolean;
-    message?: string;
-    statusCode?: number;
-    responseObject: {
-        paymentProof?: unknown;
-        [key: string]: unknown;
-    };
-}
 /**
  * Human-readable params for signaling an intent (buyer side).
  *
@@ -653,55 +629,114 @@ interface CreateDepositParams {
 }
 
 /**
- * @fileoverview React hook for the V3 intent signaling flow.
+ * @fileoverview React hook for the intent signaling flow (reserve a deposit).
  *
- * Thin state wrapper around ProveXClient.signalIntent() —
- * manages status, error messages, and loading state for the UI.
+ * A thin state wrapper around `ProveXClient.signalIntent()`. It manages the
+ * status, the message and the loading flag for the interface.
+ *
+ * The hook is headless. App-only concerns come in through options:
+ *   - `beginTransaction`: a pre-flight gate and a progress tracker, for
+ *     example a stuck-transaction check and a transaction strip.
+ *   - `isRejection` and `formatError`: the app's own error handling, for
+ *     example translated messages.
+ *   - `messages`: copy for the guard and success states.
+ *   - `chainId`, `indexer` and `apiUrl`: use these when the app has no
+ *     `ProvexProvider`. Each falls back to the provider value.
  */
 
 /** Status of the signal intent flow. */
 type SignalIntentStatus = 'input' | 'loading_payee' | 'loading_intent' | 'prompt_wallet_confirm' | 'writing_intent' | 'success' | 'error';
+/** The deposit to reserve. A `DepositInfo` fits this shape. */
+interface SignalIntentDeposit {
+    /** The escrow contract that holds the deposit. Required to send the order. */
+    escrow?: Hex | null;
+    /** The deposit id inside that escrow. Falls back to the order's `depositId`. */
+    localId?: bigint | null;
+}
+/** Progress callbacks for one signal-intent attempt. */
+interface SignalIntentTransaction {
+    /** The wallet is about to show a signature prompt. */
+    awaitingSignature: () => void;
+    /** The wallet sent the transaction and returned its hash. */
+    attach: (hash: Hex) => void;
+    /** The attempt failed or the user rejected it. */
+    failed: (error: unknown) => void;
+}
+/** Copy for the states the hook reports itself. */
+interface SignalIntentMessages {
+    clientOrDepositUnavailable: string;
+    noEscrowAddress: string;
+    success: string;
+}
+/** English defaults for {@link SignalIntentMessages}. */
+declare const DEFAULT_SIGNAL_INTENT_MESSAGES: SignalIntentMessages;
+/** Options for {@link useSignalIntent}. */
+interface UseSignalIntentOptions {
+    /** Wallet adapter for signing transactions. `null` until a wallet connects. */
+    wallet: WalletAdapter | null | undefined;
+    /**
+     * The chain to send on. Resolved through the shared chain table. When
+     * omitted, or unknown, the `ProvexProvider` chain is used.
+     */
+    chainId?: ChainId;
+    /** Indexer adapter. Defaults to the `ProvexProvider` adapter. */
+    indexer?: IndexerAdapter;
+    /** Backend API origin. Defaults to the `ProvexProvider` `apiUrl`. */
+    apiUrl?: string;
+    /** Called when the intent is signaled successfully. */
+    onSuccess: (intentHash: Hex) => void;
+    /** Called when the flow fails. A wallet rejection is not a failure. */
+    onFailure?: () => void;
+    /** The deposit to signal intent against. */
+    deposit: SignalIntentDeposit | null;
+    /** Called on failure to refresh deposit data. */
+    refetchDeposits?: () => void;
+    /**
+     * Pre-flight gate and progress tracker. It runs after the guards and
+     * before the wallet prompt. Resolve to `null` to stop silently (the user
+     * cancelled, or the gate handled the screen); the form stays at `input`.
+     */
+    beginTransaction?: () => Promise<SignalIntentTransaction | null>;
+    /** Whether an error is a wallet rejection. Defaults to the client's own flag. */
+    isRejection?: (error: unknown) => boolean;
+    /** Turns an error into the message a buyer reads. Defaults to English text. */
+    formatError?: (error: unknown) => string;
+    /** Overrides for the guard and success messages. */
+    messages?: Partial<SignalIntentMessages>;
+}
+/** One order to reserve. */
+interface StartOrderParams {
+    paymentMethod: Hex;
+    depositId: bigint;
+    tokenAmount: bigint;
+    toAddress: Hex;
+    fiatCurrencyCode: Hex;
+    conversionRate: bigint;
+    subProvider?: SubProviderKey;
+}
 /**
- * Hook for signaling intent to buy tokens via the V3 Orchestrator.
+ * Hook for signaling intent to buy tokens via the Orchestrator.
+ *
+ * Delegates to `ProveXClient.signalIntent()` for the full multi-step flow:
+ * 1. Fetch payee details from the indexer
+ * 2. Request a gating signature from the API
+ * 3. Simulate, submit, and parse the IntentSignaled event
  *
- * Delegates to ProveXClient.signalIntent() for the full multi-step flow:
- * 1. Fetch payee details from indexer
- * 2. Request gating signature from API
- * 3. Simulate, submit, and parse IntentSignaled event
+ * The client binds to `deposit.escrow`. Without that binding the client falls
+ * back to the v3 escrow, and a v4 reservation would go to the wrong
+ * orchestrator and revert at simulation.
  *
  * @example
  * ```ts
  * const { startOrder, status, message, isLoading } = useSignalIntent({
  *   wallet,
- *   chainId: 369,
  *   deposit: selectedDeposit,
  *   onSuccess: (intentHash) => navigate(`/verify/${intentHash}`),
  * })
  * ```
  */
-declare function useSignalIntent({ wallet, onSuccess, onFailure, deposit, refetchDeposits, }: {
-    /** Wallet adapter for signing transactions. */
-    wallet: WalletAdapter;
-    /** @deprecated Chain is resolved from ProvexProvider. Kept for API compat. */
-    chainId?: ChainId;
-    /** Called when the intent is signaled successfully. */
-    onSuccess: (intentHash: Hex) => void;
-    /** Called when the flow fails. */
-    onFailure?: () => void;
-    /** The deposit to signal intent against. */
-    deposit: DepositInfo | null;
-    /** Called on failure to refresh deposit data. */
-    refetchDeposits?: () => void;
-}): {
-    startOrder: ({ paymentMethod, depositId, tokenAmount, toAddress, fiatCurrencyCode, conversionRate, subProvider, }: {
-        paymentMethod: Hex;
-        depositId: bigint;
-        tokenAmount: bigint;
-        toAddress: Hex;
-        fiatCurrencyCode: Hex;
-        conversionRate: bigint;
-        subProvider?: SubProviderKey;
-    }) => Promise<void>;
+declare function useSignalIntent({ wallet, chainId, indexer, apiUrl, onSuccess, onFailure, deposit, refetchDeposits, beginTransaction, isRejection, formatError, messages, }: UseSignalIntentOptions): {
+    startOrder: ({ paymentMethod, depositId, tokenAmount, toAddress, fiatCurrencyCode, conversionRate, subProvider, }: StartOrderParams) => Promise<void>;
     status: SignalIntentStatus;
     message: string | null;
     isLoading: boolean;
@@ -710,10 +745,14 @@ declare function useSignalIntent({ wallet, onSuccess, onFailure, deposit, refetc
 /**
  * @fileoverview Hook for calculating reputation-based trading limits.
  *
- * Applies tier-based restrictions on transaction caps and cooldowns.
- * Pure computation -- no Ponder, no contract reads.
+ * Applies tier-based restrictions on order caps and cooldowns. Pure
+ * computation: no indexer query and no contract read.
  *
- * @see {@link useReputation} for fetching the user's tier
+ * The hook is headless. It reads no build-time environment value. The host
+ * app passes the kill switch as the `disabled` option, or sets
+ * `reputationDisabled` in the `ProvexProvider` config.
+ *
+ * @see {@link useUserReputation} for fetching the user's tier
  * @see {@link @provex/utils/reputation} for tier definitions
  */
 
@@ -725,30 +764,38 @@ interface ReputationLimitsParams {
     selectedPaymentMethod: ProviderKey;
     /** User's reputation tier */
     tier: TakerTier;
-    /** Settlement-token decimals — used to scale the tier cap into token
-     *  base units so the comparison against `amountInInt` is a direct
-     *  bigint compare. Pass `6` for USDC; future non-USDC tokens supply
-     *  their own decimals. */
+    /** Settlement-token decimals. Scales the tier cap into token base units
+     *  so the comparison against the order amount is a direct bigint compare.
+     *  Pass `6` for USDC; future tokens supply their own decimals. */
     decimals: number;
     /** The ORDER's token amount: what the buyer would receive from the matched
      *  seller (the intent amount), in settlement-token base units matching
      *  `decimals`. Not the typed fiat figure: the server checks the cap on the
      *  token amount, so 100 USDC allows 140,000 won at 1,400 won per USDC. Null
-     *  when no seller is matched, so nothing exceeds. (The name is kept for
-     *  compatibility with the published API.) */
+     *  when no seller is matched, so nothing exceeds. */
+    orderTokenAmount?: bigint | null;
+    /** @deprecated Use `orderTokenAmount`. Read only when `orderTokenAmount`
+     *  is absent. */
     amountInInt?: bigint | null;
-    /** When the user's cooldown ends (from useReputation) */
+    /** When the user's cooldown ends (from useUserReputation) */
     cooldownEndsAt?: Date | null;
+    /**
+     * Kill switch. When true the hook returns the no-limits result. Defaults
+     * to `ProvexProvider` `config.reputationDisabled`, then `false`.
+     */
+    disabled?: boolean;
+    /** Time source for the cooldown countdown. Defaults to the provider clock, then `systemClock`. */
+    clock?: Clock;
 }
 /** Result of the useReputationLimits hook. */
 interface ReputationLimits {
-    /** Whether reputation limits apply */
+    /** Whether reputation limits apply (false when the kill switch is on) */
     hasLimits: boolean;
     /** Alternative providers with no cooldown */
     noCooldownProviders: ProviderKey[];
     /** Cooldown hours for the selected payment method (category, not remaining) */
     selectedProviderCooldownHours: number;
-    /** Remaining cooldown time in formatted string (e.g., "5h 30m") - null if not on cooldown */
+    /** Remaining cooldown time as a string (e.g. "5h 30m"), null if not on cooldown */
     cooldownRemaining: string | null;
     /** Whether user is currently on cooldown for the selected payment method */
     isOnCooldown: boolean;
@@ -761,6 +808,18 @@ interface ReputationLimits {
     amountExceedsCap: boolean;
     /** Error message when cap is exceeded */
     capExceededMessage: string | null;
+    /**
+     * Display values for the cap math, so consumers can render a tooltip like
+     * "Entry: $100 x Revolut 5x = $500" without re-deriving the lookups.
+     * All five are `null` when limits do not apply (kill switch on) or when the
+     * platform is locked at the user's tier (`effectiveCap === null`). The
+     * numeric three are also `null` for the unlimited (president) cap.
+     */
+    tierName: string | null;
+    tierBaseCapUsd: number | null;
+    capMultiplier: number | null;
+    effectiveCapUsd: number | null;
+    providerName: string | null;
 }
 /**
  * Hook to calculate reputation-based limits for payment methods.
@@ -777,11 +836,12 @@ interface ReputationLimits {
  *   chainId,
  *   selectedPaymentMethod,
  *   tier: reputation.tier,
- *   amountInInt,
+ *   decimals: 6,
+ *   orderTokenAmount,
  * })
  * ```
  */
-declare function useReputationLimits({ chainId, selectedPaymentMethod, tier, decimals, amountInInt, cooldownEndsAt, }: ReputationLimitsParams): ReputationLimits;
+declare function useReputationLimits({ chainId, selectedPaymentMethod, tier, decimals, orderTokenAmount, amountInInt, cooldownEndsAt, disabled, clock, }: ReputationLimitsParams): ReputationLimits;
 
 /** Intent status values representing the lifecycle state. */
 declare const intentStatuses: {
@@ -843,6 +903,12 @@ interface ProvexConfig {
     apiUrl: string;
     /** The viem Chain object. Import from `viem/chains`. */
     chain: Chain;
+    /**
+     * Reputation kill switch. When true, `useUserReputation` reports the
+     * neutral default and `useReputationLimits` applies no cap or cooldown.
+     * A per-call `disabled` option overrides it.
+     */
+    reputationDisabled?: boolean;
     /** @deprecated Use `chain.id` — kept for backward compat during migration. */
     chainId?: ChainId;
 }
@@ -1043,6 +1109,8 @@ interface ProvexContextValue {
     publicClients: Record<number, PublicClient>;
     /** Optional wallet adapter for write operations. */
     wallet?: WalletAdapter;
+    /** Time source for polling and countdowns. Always set by ProvexProvider; `systemClock` unless overridden. */
+    clock?: Clock;
 }
 /** Props for the ProvexProvider component. */
 interface ProvexProviderProps {
@@ -1071,6 +1139,11 @@ interface ProvexProviderProps {
      * Omit for read-only apps.
      */
     wallet?: WalletAdapter;
+    /**
+     * Time source for polling loops and countdowns. Defaults to `systemClock`.
+     * Tests pass `createManualClock()` from `@provex/react/testing`.
+     */
+    clock?: Clock;
     /** Child components that consume the context. */
     children: React__default.ReactNode;
 }
@@ -1096,7 +1169,7 @@ interface ProvexProviderProps {
  * </ProvexProvider>
  * ```
  */
-declare function ProvexProvider({ config, indexer, queryClient, publicClient, publicClients, wallet, children, }: ProvexProviderProps): react_jsx_runtime.JSX.Element;
+declare function ProvexProvider({ config, indexer, queryClient, publicClient, publicClients, wallet, clock, children, }: ProvexProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * useProvex — access the Provex context (config, indexer, apiClient,
  * publicClients, wallet).
@@ -1123,5 +1196,10 @@ declare function useProvexWallet(): WalletAdapter | undefined;
  * Get the optional wallet adapter without requiring ProvexProvider.
  */
 declare function useOptionalProvexWallet(): WalletAdapter | undefined;
+/**
+ * Get the configured clock. Falls back to `systemClock` when no
+ * ProvexProvider is mounted or the provider has no clock.
+ */
+declare function useClock(): Clock;
 
-export { type SignalIntentStatus as $, type AttestationParams as A, type BuyProps as B, type CreateDepositRawParams as C, type DepositPaymentMethod as D, useDeposits as E, type FulfillIntentParams as F, getRate as G, usePayeeDetails as H, type IndexerAdapter as I, intentStatuses as J, useSignalIntent as K, useProvexPublicClient as L, type MakerRegistrationParams as M, useOptionalProvexPublicClient as N, useProvexWallet as O, type ProveXClientConfig as P, useOptionalProvexWallet as Q, type ReputationData as R, type SignalIntentParams as S, type TransactionResult as T, type UseProvexBuyOptions as U, type ReputationLimitsParams as V, type WritableMethod as W, type ReputationLimits as X, type DepositInfo as Y, type IntentStatus as Z, type PayeeInfo as _, type PaginationOptions as a, type IndexedVerifier as a0, type PaginatedResult as b, type IndexedDeposit as c, type IndexedIntent as d, type CreateDepositParams as e, type PreparedTransaction as f, type SignalIntentResult as g, type PayeeDetails as h, type AttestationResponse as i, type WalletAdapter as j, type UseProvexBuyReturn as k, type PhaseRenderProps as l, type ProvexConfig as m, type BuyPhase as n, type ProvexTheme as o, type PhaseComponentProps as p, ProvexProvider as q, type ProvexContextValue as r, type ProvexProviderProps as s, ProveXError as t, useProvex as u, type ProveXErrorCode as v, type SignalIntentRawParams as w, createApiClient as x, type ApiClient as y, useReputationLimits as z };
+export { type SignalIntentStatus as $, type ApiClient as A, type BuyProps as B, type CreateDepositRawParams as C, type DepositPaymentMethod as D, getRate as E, type FulfillIntentParams as F, usePayeeDetails as G, intentStatuses as H, type IndexerAdapter as I, useSignalIntent as J, DEFAULT_SIGNAL_INTENT_MESSAGES as K, useProvexPublicClient as L, type MakerRegistrationParams as M, useOptionalProvexPublicClient as N, useProvexWallet as O, type ProveXClientConfig as P, useOptionalProvexWallet as Q, type ReputationData as R, type SignalIntentParams as S, type TransactionResult as T, type UseProvexBuyOptions as U, type ReputationLimitsParams as V, type WritableMethod as W, type ReputationLimits as X, type DepositInfo as Y, type IntentStatus as Z, type PayeeInfo as _, type PaginationOptions as a, type SignalIntentDeposit as a0, type SignalIntentTransaction as a1, type SignalIntentMessages as a2, type UseSignalIntentOptions as a3, type StartOrderParams as a4, type IndexedVerifier as a5, type PaginatedResult as b, type IndexedDeposit as c, type IndexedIntent as d, type CreateDepositParams as e, type PreparedTransaction as f, type SignalIntentResult as g, type PayeeDetails as h, type WalletAdapter as i, type UseProvexBuyReturn as j, type PhaseRenderProps as k, type ProvexConfig as l, type BuyPhase as m, type ProvexTheme as n, type PhaseComponentProps as o, ProvexProvider as p, useClock as q, type ProvexContextValue as r, type ProvexProviderProps as s, ProveXError as t, useProvex as u, type ProveXErrorCode as v, type SignalIntentRawParams as w, createApiClient as x, useReputationLimits as y, useDeposits as z };