@rhinestone/deposit-modal 0.14.1 → 0.16.0

package/dist/{types-DP_3KwlD.d.cts → types-B9SbZQIG.d.ts}

@@ -1,5 +1,19 @@
+import { D as DisplayChainId, d as TargetChain } from './caip-BMi-9t09.js';
 import { TypedDataDefinition, Address, Hex, WalletClient, PublicClient, Chain } from 'viem';
-import { T as TargetChain } from './caip-D8aRWdEY.cjs';
+
+/**
+ * Consumer-supplied RPC URL overrides, scoped to a single modal instance (see
+ * {@link RpcUrlsProvider}). Threaded into every client the modal builds — EVM
+ * public clients (`public-client.ts`), the wallet adapter's transports
+ * (`reown.tsx`), and the Solana connection (`solana.ts`).
+ *
+ * Keyed by the same `number | "solana"` chain identifier the rest of the modal
+ * uses (see `core/constants.ts`), so a single `rpcUrls` prop covers every
+ * chain — EVM mainnets, Polygon (137, also feeds Polymarket reads), HyperEVM
+ * (999), and Solana.
+ */
+type ChainKey = number | "solana";
+type RpcUrlMap = Partial<Record<ChainKey, string>>;
 
 /**
  * Public config shape exposed on DepositModalProps. Each provider defaults to
@@ -39,8 +53,9 @@ interface SignRecoveryPayload {
      */
     signer: Address;
     /**
-     * The chain the deposit is on, and therefore the chain the signature is
-     * verified against.
+     * The chain the signature is verified against: the deposit's DESTINATION
+     * chain, where the recipient wallet lives. Not the source chain the refund
+     * pays out on — the processor verifies on the target and never falls back.
      *
      * Load-bearing for a smart account: ERC-1271 and ERC-6492 verification are
      * per-chain, so a signature produced against the wrong one is well formed,
@@ -70,21 +85,15 @@ type SignRecovery = (payload: SignRecoveryPayload) => Promise<Hex>;
 type RecoveryErrorCode = "DEPOSIT_NOT_RECOVERABLE" | "RECOVERY_UNSUPPORTED" | "SIGNATURE_INVALID" | "VERIFICATION_UNAVAILABLE" | "REFUND_RECONCILIATION_REQUIRED" | "REFUND_FAILED";
 
 /**
- * Consumer-supplied RPC URL overrides, scoped to a single modal instance (see
- * {@link RpcUrlsProvider}). Threaded into every client the modal builds — EVM
- * public clients (`public-client.ts`), the wallet adapter's transports
- * (`reown.tsx`), and the Solana connection (`solana.ts`).
- *
- * Keyed by the same `number | "solana"` chain identifier the rest of the modal
- * uses (see `core/constants.ts`), so a single `rpcUrls` prop covers every
- * chain — EVM mainnets, Polygon (137, also feeds Polymarket reads), HyperEVM
- * (999), and Solana.
+ * How a `GET /deposits` row reads on screen, and which rows are on screen at
+ * all. Shared rather than private to the history panel: the header's status dot
+ * derives from the same rows the panel lists, and a second copy of either
+ * answer would let the badge and the list disagree.
  */
-type ChainKey = number | "solana";
-type RpcUrlMap = Partial<Record<ChainKey, string>>;
+type HistoryStatus = "pending" | "processing" | "completed" | "failed" | "refunded" | "spam";
 
 type Caip2ChainId = `eip155:${number}` | `solana:${string}`;
-type ChainId = number | "solana" | "hypercore" | Caip2ChainId;
+type ChainId = DisplayChainId | Caip2ChainId;
 interface DepositModalTheme {
     /**
      * Absent means light, unconditionally — never "follow the OS". `"system"` is
@@ -286,13 +295,39 @@ interface DepositModalProps {
      */
     enableExchangeConnect?: boolean;
     onRequestConnect?: () => void;
+    /**
+     * Signs a refund for a failed deposit the user recovers from its history
+     * row. Supply it to offer recovery; omit it and history behaves exactly as it
+     * does today — a failed row expands to its cause and details with no action.
+     *
+     * The processor verifies the signature against the deposit's `recipient`, on
+     * the deposit's DESTINATION chain, so return whatever that address's own
+     * verifier accepts there:
+     * - **embedded EOA** (Privy, Turnkey, Dynamic) — `signTypedData`, raw 65-byte
+     *   result.
+     * - **deployed smart account** — a signature valid under its ERC-1271
+     *   `isValidSignature`. A raw owner signature is usually not enough; a Safe,
+     *   for one, expects its own message wrapping, so go through your account SDK.
+     * - **undeployed smart account** — wrap per ERC-6492 so it can be verified
+     *   counterfactually. `SignatureErc6492.wrap` from `ox/erc6492` does this and
+     *   ships with viem already.
+     *
+     * Throwing (or returning nothing) is treated as the user declining, which is
+     * retryable.
+     */
+    signRecovery?: SignRecovery;
     theme?: DepositModalTheme;
     uiConfig?: DepositModalUIConfig;
     className?: string;
     onReady?: () => void;
     /** Discriminated stream of deposit lifecycle transitions. */
     onLifecycle?: (event: DepositLifecycleEvent) => void;
-    onEvent?: (event: DepositAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    /**
+     * Funnel telemetry. Also delivers `ClaimAnalyticsEvent`: a recovery started
+     * from history opens a claim session inside this modal, and a host that logs
+     * events would otherwise go blind exactly where funds are being recovered.
+     */
+    onEvent?: (event: DepositAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
     onError?: (data: ErrorEventData) => void;
     /**
      * Send session analytics to Rhinestone in addition to `onEvent`. Default:
@@ -370,7 +405,8 @@ interface WithdrawModalProps {
     onReady?: () => void;
     /** Discriminated stream of withdraw lifecycle transitions. */
     onLifecycle?: (event: WithdrawLifecycleEvent) => void;
-    onEvent?: (event: WithdrawAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
+    /** Claim events included, on the same terms as the deposit modal's. */
+    onEvent?: (event: WithdrawAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
     onError?: (data: ErrorEventData) => void;
     /**
      * Send session analytics to Rhinestone in addition to `onEvent`. Default:
@@ -379,80 +415,31 @@ interface WithdrawModalProps {
     enableAnalyticsIngest?: boolean;
     /** @internal Rhinestone's own dev verification. Not a supported prop. */
     analyticsIngestUrl?: string;
-    debug?: boolean;
-}
-/**
- * Self-service recovery modal. Returns a failed or rejected deposit's
- * source-chain funds to an address the user names. The deposit is looked up by
- * transaction hash.
- *
- * The user's own wallet authorizes it: the deposit's `recipient` — the in-app
- * wallet the funds were headed to — signs an EIP-712 struct naming the deposit and
- * the destination, and the processor verifies that signature against the same
- * `recipient` before moving anything. Your app needs no backend and no shared
- * secret; the request goes from the browser through your `deposit-widget-proxy`,
- * which adds only the project API key.
- *
- * Note the signer is the recipient, not the deposit account — deposit accounts are
- * service-owned and cannot sign for themselves.
- */
-interface ClaimModalProps {
     /**
-     * Signs the recovery authorization. Called with the exact typed data to sign and
-     * the `signer` address whose signature the processor will verify — the deposit's
-     * `recipient`.
+     * Signs a refund for a failed deposit the user recovers from a history row.
+     * Supply it to offer recovery; omit it and the panel is read-only — a failed
+     * row expands to its cause and details with no action.
+     *
+     * History here is the WITHDRAWAL DESTINATION's, so the signer is an address
+     * the user typed into the form rather than a wallet your app issued. Omit
+     * this prop unless your users can sign for the addresses they withdraw to.
      *
-     * Return whatever that address's own verifier accepts:
+     * The processor verifies the signature against the deposit's `recipient`, on
+     * the deposit's DESTINATION chain, so return whatever that address's own
+     * verifier accepts there:
      * - **embedded EOA** (Privy, Turnkey, Dynamic) — `signTypedData`, raw 65-byte
      *   result.
      * - **deployed smart account** — a signature valid under its ERC-1271
-     *   `isValidSignature`. A raw owner signature is usually not enough; a Safe, for
-     *   one, expects its own message wrapping, so go through your account SDK.
+     *   `isValidSignature`. A raw owner signature is usually not enough; a Safe,
+     *   for one, expects its own message wrapping, so go through your account SDK.
      * - **undeployed smart account** — wrap per ERC-6492 so it can be verified
      *   counterfactually. `SignatureErc6492.wrap` from `ox/erc6492` does this and
      *   ships with viem already.
      *
      * Throwing (or returning nothing) is treated as the user declining, which is
      * retryable.
-     *
-     * If your users can't sign — a lost embedded wallet, or a recipient your app
-     * controls rather than the user — use `createRefundHandler` from
-     * `@rhinestone/deposit-modal/server` against your own backend instead, and drive
-     * your own UI. That path authorizes on your say-so rather than a signature.
-     */
-    signRecovery: SignRecovery;
-    isOpen: boolean;
-    onClose: () => void;
-    inline?: boolean;
-    closeOnOverlayClick?: boolean;
-    backendUrl: string;
-    rpcUrls?: RpcUrlMap;
-    /** Optional prefills for the lookup form and destination. */
-    defaultTxHash?: string;
-    /**
-     * Prefills the refund destination. Left empty otherwise — the modal
-     * deliberately does NOT default to the deposit's sender, because returning
-     * funds to an exchange's hot wallet can lose them.
-     *
-     * Matches `refundDestination` on `RefundAuthorization` in `./server`, which
-     * is the authoritative version: this one only seeds the field and the user can
-     * edit it. Not related to the deposit's `recipient`.
      */
-    defaultRefundDestination?: Address;
-    theme?: DepositModalTheme;
-    uiConfig?: DepositModalUIConfig;
-    className?: string;
-    onReady?: () => void;
-    onLifecycle?: (event: ClaimLifecycleEvent) => void;
-    onEvent?: (event: ClaimAnalyticsEvent | AnalyticsIngestFailureEvent) => void;
-    onError?: (data: ErrorEventData) => void;
-    /**
-     * Sends claim session analytics to Rhinestone in addition to `onEvent`.
-     * Defaults to on; `false` turns collection off entirely.
-     */
-    enableAnalyticsIngest?: boolean;
-    /** @internal Rhinestone's own dev verification. Not a supported prop. */
-    analyticsIngestUrl?: string;
+    signRecovery?: SignRecovery;
     debug?: boolean;
 }
 interface AssetOption {
@@ -553,30 +540,6 @@ type WithdrawLifecycleEvent =
     txHash: Hex;
     error?: string;
 };
-type ClaimLifecycleEvent = {
-    type: "lookup";
-    txHash: string;
-    matches: number;
-} | {
-    type: "refund_requested";
-    account: Address;
-    /** Where the funds were asked to go, on the source chain. */
-    destination: Address;
-    chain: number;
-} | {
-    type: "complete";
-    txHash: string;
-    account: Address;
-    destination: Address;
-    chain: number;
-    token: string;
-    amount: string;
-} | {
-    type: "failed";
-    /** HTTP status from the refund endpoint; 0 if it was unreachable. */
-    status?: number;
-    error?: string;
-};
 type DepositFundingMethod = "wallet" | "transfer" | "fiat_onramp" | "exchange_connect" | "asset_migration";
 type DepositWalletIntegration = "modal_connected" | "host_supplied" | "none";
 interface DepositAnalyticsSessionProperties {
@@ -649,6 +612,57 @@ interface AnalyticsEventEnvelope<Modal extends "deposit" | "withdraw" | "claim",
     timestamp: string;
     session_properties: SessionProperties;
 }
+/**
+ * Which state the history entry point's dot was in when the panel was opened.
+ * `none` is the quiet state, reported as a value rather than by omission.
+ */
+type HistoryAnalyticsBadge = "needs_you" | "progress" | "none";
+/** Which of history's two entries a recovery attempt started from. */
+type HistoryClaimEntrySource = "history_row" | "history_fallback";
+/**
+ * The history surface reports on the session of the modal the user is in, under
+ * mirrored names — so a deposit and a withdraw visit are the same measurement
+ * of the same panel. Every event of one visit carries its `history_visit_id`;
+ * a close and reopen is a second visit with a different one.
+ *
+ * `deposit_id` is the join key into the claim stream. Amounts, tokens,
+ * recipients and searched transaction hashes are deliberately absent.
+ */
+type HistoryAnalyticsPayloads<Modal extends "deposit" | "withdraw", Step> = {
+    type: `${Modal}_modal_history_open`;
+    history_visit_id: string;
+    /** The host funnel step history was opened from; null before one opened. */
+    step: Step | null;
+    badge: HistoryAnalyticsBadge;
+    badge_count: number;
+}
+/** One per deposit per visit: a row expanded twice still counts once. */
+ | {
+    type: `${Modal}_modal_history_row_view`;
+    history_visit_id: string;
+    deposit_id: string;
+    status: HistoryStatus;
+    recoverable: boolean;
+    /** 0-based index in the list as displayed. */
+    position: number;
+} | {
+    type: `${Modal}_modal_history_load_more`;
+    history_visit_id: string;
+    /** 1-based press count within the visit. */
+    page: number;
+    /** Rows on screen before the press. */
+    loaded_rows: number;
+} | {
+    type: `${Modal}_modal_history_fallback_open`;
+    history_visit_id: string;
+    claim_attempt_id: string;
+} | {
+    type: `${Modal}_modal_history_recovery_start`;
+    history_visit_id: string;
+    claim_attempt_id: string;
+    entry_source: HistoryClaimEntrySource;
+    deposit_id: string;
+};
 type DepositAnalyticsSharedStep = "account_setup" | "funding_method_home";
 type DepositAnalyticsWalletStep = "wallet_connect" | "wallet_source_asset" | "wallet_source_token" | "wallet_amount" | "wallet_review" | "wallet_submit" | "wallet_processing";
 type DepositAnalyticsTransferStep = "transfer_source_selection" | "transfer_address_shown" | "transfer_copy" | "transfer_fee_amount" | "transfer_fee_review" | "transfer_tracking";
@@ -785,7 +799,7 @@ type DepositAnalyticsCommonEventPayload = {
     source: DepositAnalyticsCloseSource;
     step: DepositAnalyticsStep | null;
     after_handoff: boolean;
-};
+} | HistoryAnalyticsPayloads<"deposit", DepositAnalyticsStep>;
 /**
  * Method-aware deposit telemetry. UI outcomes describe only what the widget
  * observed and must not be treated as backend fulfilment truth.
@@ -869,7 +883,9 @@ type WithdrawAnalyticsEventPayload = {
     step: WithdrawAnalyticsStep | null;
     after_handoff: boolean;
     same_route?: boolean;
-};
+} | (HistoryAnalyticsPayloads<"withdraw", WithdrawAnalyticsStep> & {
+    same_route?: boolean;
+});
 type WithdrawAnalyticsEvent = WithdrawAnalyticsEventPayload & AnalyticsEventEnvelope<"withdraw", WithdrawAnalyticsSessionProperties>;
 /**
  * `submit` is the async boundary the review CTA opens rather than a screen of
@@ -879,8 +895,28 @@ type ClaimAnalyticsStep = "lookup" | "select" | "review" | "submit";
 /** Every reason has a call site in the claim flow; none is aspirational. */
 type ClaimAnalyticsFailureReason = RoutableAnalyticsReason<"lookup_transaction_hash_invalid" | "lookup_failed" | "lookup_no_deposits_found" | "lookup_no_eligible_deposits" | "refund_destination_invalid" | "recovery_deposit_data_incomplete" | "signature_rejected" | "signature_invalid" | "recovery_deposit_not_recoverable" | "recovery_unsupported" | "signature_verification_unavailable" | "refund_reconciliation_required" | "refund_failed" | "refund_service_unreachable" | "modal_close_refused_in_flight">;
 type ClaimAnalyticsAbandonmentReason = "back" | "modal_close";
-type ClaimAnalyticsCloseSource = "header_button" | "escape" | "overlay" | "host_controlled" | "success_done" | "failure_cancel";
+type ClaimAnalyticsCloseSource = "header_button" | "escape" | "overlay" | "host_controlled" | "success_done" | "failure_cancel"
+/** The labelled control back to the history list a recovery was started from. */
+ | "history_back";
 type ClaimAnalyticsUiOutcome = "completed" | "failed";
+/**
+ * Where a claim attempt was entered from. Present on every claim session, the
+ * standalone modal's included: segmenting on a value that is there keeps a
+ * standalone claim distinguishable from an older widget that reports nothing.
+ */
+type ClaimAnalyticsEntrySource = "standalone" | HistoryClaimEntrySource;
+/**
+ * What ties a claim attempt back to the history visit that produced it. Carried
+ * on every event of the attempt rather than in `session_properties`, which the
+ * ingest contract compares for equality across a session.
+ */
+interface ClaimAnalyticsCorrelation {
+    entry_source: ClaimAnalyticsEntrySource;
+    /** The deposit or withdraw session the attempt was started inside. */
+    source_session_id?: string;
+    history_visit_id?: string;
+    claim_attempt_id?: string;
+}
 /**
  * Claim funnel telemetry. Identities enter the stream only once a lookup has
  * matched a backend deposit row: the hash the user searched for, the refund
@@ -892,7 +928,8 @@ type ClaimAnalyticsUiOutcome = "completed" | "failed";
  * no hash, never an empty string: `deposit_id` is the join key, and a blank
  * identity would join to nothing while looking like one that does.
  */
-type ClaimAnalyticsEventPayload = {
+type ClaimAnalyticsEventPayload = ClaimAnalyticsEventDetail & Partial<ClaimAnalyticsCorrelation>;
+type ClaimAnalyticsEventDetail = {
     type: "claim_modal_open";
 } | {
     type: "claim_modal_step_open";
@@ -979,4 +1016,4 @@ interface AnalyticsIngestFailureEvent {
 }
 type ModalAnalyticsEvent = DepositAnalyticsEvent | WithdrawAnalyticsEvent | ClaimAnalyticsEvent | AnalyticsIngestFailureEvent;
 
-export type { WithdrawAnalyticsCloseSource as $, AnalyticsEventEnvelope as A, DepositAnalyticsStep as B, ChainId as C, DepositAnalyticsAbandonmentReason as D, DepositAnalyticsTransferStep as E, DepositAnalyticsUiOutcome as F, DepositAnalyticsWalletStep as G, DepositAssetMigrationMethodIdentifiers as H, DepositCompleteEventData as I, DepositExchangeConnectMethodIdentifiers as J, DepositFailedEventData as K, DepositFiatOnrampMethodIdentifiers as L, DepositFundingMethod as M, DepositLifecycleEvent as N, DepositModalProps as O, DepositModalTheme as P, DepositModalUIConfig as Q, DepositSubmittedEventData as R, DepositTransferHandoffIdentifiers as S, DepositWalletIntegration as T, DepositWalletMethodIdentifiers as U, ErrorEventData as V, FiatMethodsConfig as W, ModalAnalyticsEvent as X, OutputTokenRule as Y, RpcUrlMap as Z, WithdrawAnalyticsAbandonmentReason as _, AnalyticsIngestFailureEvent as a, WithdrawAnalyticsEvent as a0, WithdrawAnalyticsEventPayload as a1, WithdrawAnalyticsFailureReason as a2, WithdrawAnalyticsSessionProperties as a3, WithdrawAnalyticsStep as a4, WithdrawAnalyticsUiOutcome as a5, WithdrawCompleteEventData as a6, WithdrawFailedEventData as a7, WithdrawLifecycleEvent as a8, WithdrawModalProps as a9, WithdrawSubmittedEventData as aa, WithdrawTransferRequest as ab, RecoveryErrorCode as ac, SignRecovery as ad, SignRecoveryPayload as ae, AnalyticsIngestFailureReason as b, AnalyticsReasonFamily as c, AssetMigrationsConfig as d, AssetOption as e, ClaimAnalyticsAbandonmentReason as f, ClaimAnalyticsCloseSource as g, ClaimAnalyticsEvent as h, ClaimAnalyticsEventPayload as i, ClaimAnalyticsFailureReason as j, ClaimAnalyticsSessionProperties as k, ClaimAnalyticsStep as l, ClaimAnalyticsUiOutcome as m, ClaimLifecycleEvent as n, ClaimModalProps as o, ConnectedEventData as p, DepositAnalyticsCloseSource as q, DepositAnalyticsCorrelator as r, DepositAnalyticsEvent as s, DepositAnalyticsEventPayload as t, DepositAnalyticsExchangeStep as u, DepositAnalyticsFailureReason as v, DepositAnalyticsFiatStep as w, DepositAnalyticsMigrationStep as x, DepositAnalyticsSessionProperties as y, DepositAnalyticsSharedStep as z };
+export type { OutputTokenRule as $, AnalyticsEventEnvelope as A, DepositAnalyticsStep as B, ChainId as C, DepositAnalyticsAbandonmentReason as D, DepositAnalyticsTransferStep as E, DepositAnalyticsUiOutcome as F, DepositAnalyticsWalletStep as G, DepositAssetMigrationMethodIdentifiers as H, DepositCompleteEventData as I, DepositExchangeConnectMethodIdentifiers as J, DepositFailedEventData as K, DepositFiatOnrampMethodIdentifiers as L, DepositFundingMethod as M, DepositLifecycleEvent as N, DepositModalProps as O, DepositModalTheme as P, DepositModalUIConfig as Q, DepositSubmittedEventData as R, DepositTransferHandoffIdentifiers as S, DepositWalletIntegration as T, DepositWalletMethodIdentifiers as U, ErrorEventData as V, FiatMethodsConfig as W, HistoryAnalyticsBadge as X, HistoryClaimEntrySource as Y, HistoryStatus as Z, ModalAnalyticsEvent as _, AnalyticsIngestFailureEvent as a, RecoveryErrorCode as a0, RpcUrlMap as a1, SignRecovery as a2, SignRecoveryPayload as a3, WithdrawAnalyticsAbandonmentReason as a4, WithdrawAnalyticsCloseSource as a5, WithdrawAnalyticsEvent as a6, WithdrawAnalyticsEventPayload as a7, WithdrawAnalyticsFailureReason as a8, WithdrawAnalyticsSessionProperties as a9, WithdrawAnalyticsStep as aa, WithdrawAnalyticsUiOutcome as ab, WithdrawCompleteEventData as ac, WithdrawFailedEventData as ad, WithdrawLifecycleEvent as ae, WithdrawModalProps as af, WithdrawSubmittedEventData as ag, WithdrawTransferRequest as ah, AnalyticsIngestFailureReason as b, AnalyticsReasonFamily as c, AssetMigrationsConfig as d, AssetOption as e, ClaimAnalyticsAbandonmentReason as f, ClaimAnalyticsCloseSource as g, ClaimAnalyticsCorrelation as h, ClaimAnalyticsEntrySource as i, ClaimAnalyticsEvent as j, ClaimAnalyticsEventPayload as k, ClaimAnalyticsFailureReason as l, ClaimAnalyticsSessionProperties as m, ClaimAnalyticsStep as n, ClaimAnalyticsUiOutcome as o, ConnectedEventData as p, DepositAnalyticsCloseSource as q, DepositAnalyticsCorrelator as r, DepositAnalyticsEvent as s, DepositAnalyticsEventPayload as t, DepositAnalyticsExchangeStep as u, DepositAnalyticsFailureReason as v, DepositAnalyticsFiatStep as w, DepositAnalyticsMigrationStep as x, DepositAnalyticsSessionProperties as y, DepositAnalyticsSharedStep as z };