@rhinestone/deposit-modal 0.12.2 → 0.14.0

package/dist/embed.d.cts

@@ -0,0 +1,183 @@
+import * as react from 'react';
+import { T as TargetChain } from './caip-D8aRWdEY.cjs';
+import { Y as OutputTokenRule, W as FiatMethodsConfig, d as AssetMigrationsConfig, P as DepositModalTheme, Q as DepositModalUIConfig } from './types-DP_3KwlD.cjs';
+import { WalletClient, PublicClient, Address } from 'viem';
+import { Transaction, Connection } from '@solana/web3.js';
+
+interface SolanaWalletProvider {
+    signAndSendTransaction(transaction: Transaction): Promise<string | {
+        signature?: string;
+        hash?: string;
+        txid?: string;
+        transactionId?: string;
+    }>;
+    signTransaction?(transaction: Transaction): Promise<Transaction>;
+    publicKey?: {
+        toBase58(): string;
+    };
+}
+
+/**
+ * The wallet the flow signs with, unifying EVM and Solana access behind one
+ * object. AppKit is one implementation (`useReownWalletSession`); a host that
+ * holds its own wallet supplies another. Nothing here may reference AppKit —
+ * that an implementation can be written without importing it is the point.
+ */
+interface WalletSession {
+    walletClient: WalletClient | undefined;
+    /**
+     * Whether this session can sign an EVM transaction right now. It is what the
+     * picker offers an EVM row on.
+     *
+     * Required, and answered by the implementation rather than inferred by the
+     * caller, because the caller can only infer it from whichever object it
+     * happens to check — and that has silently removed a connected user's wallet
+     * from the picker twice: once on `publicClient`, once on a resolvable viem
+     * chain. An implementation that has not thought about it now fails to
+     * compile.
+     *
+     * Distinct from `isReady`, which is about the provider having initialised.
+     *
+     * The invariant callers rely on: `true` means `walletClient` is defined, with
+     * an account and a chain bound.
+     */
+    canSignEvm: boolean;
+    /** Optional: every read falls back to `getPublicClient(chainId, rpcUrls)`,
+     *  so an implementation with no wallet-backed client omits it. */
+    publicClient: PublicClient | undefined;
+    address: Address | undefined;
+    caipAddress?: string;
+    isConnected: boolean;
+    isReady: boolean;
+    icon?: string;
+    isSolana: boolean;
+    solanaAddress?: string;
+    solanaProvider?: SolanaWalletProvider;
+    /** RPC connection managed by the connected Solana wallet session, used for
+     *  reads (blockhash, account info) instead of an app-configured RPC. */
+    solanaConnection?: Connection;
+    openConnect: () => void;
+    disconnect: () => void;
+    switchChain: (chainId: number) => Promise<void>;
+}
+
+/** A `window`, or anything shaped enough like one to hold the two globals. */
+type ChannelTarget = Record<string, unknown>;
+
+/**
+ * The message contract between the embed page and a native host.
+ *
+ * **This contract evolves; it is not frozen.** One URL serves every wrapper,
+ * and the handshake tells the page which protocol version and which
+ * capabilities the wrapper on the other side understands, so the page adapts
+ * at runtime. That puts the compatibility burden on the side we can actually
+ * update — a hosted page — rather than on app-store builds we cannot.
+ *
+ * The discipline that makes it safe:
+ *
+ * - an existing field never changes meaning, and never changes type;
+ * - new fields are optional, and a receiver ignores what it does not know;
+ * - an unknown event type is dropped, an unknown request method answers 4200;
+ * - behaviour that differs by wrapper version is gated on `HelloResult.protocol`
+ *   and `HelloResult.capabilities` — what the HOST speaks. The page's own
+ *   version tells it nothing it does not already know.
+ *
+ * A `/v1/` path exists only as an escape hatch for a break so fundamental the
+ * page cannot adapt to it. Reaching for it means every integrator ships an
+ * app-store release, so it is a last resort rather than a versioning scheme.
+ */
+
+type EmbedMode = "deposit" | "withdraw" | "claim";
+/**
+ * Every prop that survives a JSON hop. Names match the React props 1:1 on
+ * purpose — this is a transport, not a redesign, and a renamed field is a
+ * second thing to keep in sync forever.
+ *
+ * Config crosses the bridge and never the URL: a public URL taking a recipient
+ * and a backend URL is a phishing surface, and it would put keyed RPC
+ * endpoints into URL bars and logs.
+ */
+interface EmbedConfig {
+    mode: EmbedMode;
+    backendUrl: string;
+    recipient: string;
+    /** Never a viem `Chain`. This value is hashed into the account salt, so its
+     *  spelling is a deposit address. */
+    targetChain: TargetChain;
+    targetToken: string;
+    sourceChain?: number;
+    sourceToken?: string;
+    /** USD amount, or the case-insensitive sentinel `"max"`. */
+    defaultAmount?: string;
+    appBalanceUsd?: number;
+    outputTokenRules?: OutputTokenRule[];
+    rejectUnmapped?: boolean;
+    forceRegister?: boolean;
+    /**
+     * No `rpcUrls`. The web modal takes them so an integrator can route reads
+     * through their own endpoints, but those endpoints are usually keyed, and
+     * config crossing the bridge rather than the URL was to keep keyed endpoints
+     * out of logs — putting them in the handshake instead hands them to whatever
+     * the host logs, and to any frame that reaches an unscoped channel. The
+     * chain set already carries `publicRpcUrl`, so nothing is blocked without
+     * them, and a new optional field is the one change this contract makes
+     * cheaply: it can be added the day a client needs it, where removing it
+     * later could not.
+     */
+    enableWallet?: boolean;
+    enableFiatOnramp?: boolean;
+    enableQrTransfer?: boolean;
+    enableGaslessDeposit?: boolean;
+    enableExchangeConnect?: boolean;
+    /**
+     * Opt out of sending session analytics to Rhinestone. Default: on. The URL
+     * override the web props carry is deliberately absent — it exists for our own
+     * dev verification, and a bridge field can be added later but never removed.
+     */
+    enableAnalyticsIngest?: boolean;
+    fiatMethods?: FiatMethodsConfig;
+    assetMigrations?: AssetMigrationsConfig;
+    initialAssetMigration?: keyof AssetMigrationsConfig;
+    /**
+     * **The page never follows the OS on its own.** An absent `mode` is light,
+     * and `theme.mode: "system"` — protocol 2 — is what asks the page to read
+     * `prefers-color-scheme`. Following it silently would drop a dark funding
+     * sheet into a light single-appearance app the moment the user's phone
+     * switched, which is the host's call to make and not ours.
+     *
+     * **Appearance is not a mount-time value.** It can change while the sheet is
+     * open, so a host that tracks it re-sends its config over
+     * `session.configure`; the page repaints in place and the flow is not
+     * disturbed. This is why theming has to live in the bridge config rather
+     * than being handed over once at hello.
+     *
+     * **`"system"` does not mean the same thing on both platforms.** WKWebView
+     * reports the app's effective appearance. Android's WebView reports its
+     * theme's `isLightTheme`, which is *light* whenever the app never declares
+     * one — so an unthemed Android host reads light in OS dark mode, and reads
+     * it silently. A host that knows its own appearance should send `"light"` or
+     * `"dark"` and update it, which is also the only option for an app whose
+     * appearance is its own setting rather than the OS one.
+     */
+    theme?: DepositModalTheme;
+    uiConfig?: DepositModalUIConfig;
+    debug?: boolean;
+    /** Withdraw only. */
+    accountAddress?: string;
+    /** Claim only: prefills the lookup form. */
+    defaultTxHash?: string;
+    /** Claim only: seeds the refund destination, which the user can still edit.
+     *  Deliberately never defaulted to the deposit's sender — returning funds to
+     *  an exchange hot wallet can lose them. */
+    defaultDestination?: string;
+}
+
+interface DepositEmbedProps {
+    /** Where the injected channel lives. Defaults to this page's `window`. */
+    target?: ChannelTarget;
+    /** The handshake failed, so there is no session and no config to render. */
+    onFatal?: (error: unknown) => void;
+}
+declare function DepositEmbed({ target, onFatal }: DepositEmbedProps): react.JSX.Element | null;
+
+export { DepositEmbed, type DepositEmbedProps, type EmbedConfig, type WalletSession };

package/dist/embed.d.ts

@@ -0,0 +1,183 @@
+import * as react from 'react';
+import { T as TargetChain } from './caip-D8aRWdEY.js';
+import { Y as OutputTokenRule, W as FiatMethodsConfig, d as AssetMigrationsConfig, P as DepositModalTheme, Q as DepositModalUIConfig } from './types-Bho4OA03.js';
+import { WalletClient, PublicClient, Address } from 'viem';
+import { Transaction, Connection } from '@solana/web3.js';
+
+interface SolanaWalletProvider {
+    signAndSendTransaction(transaction: Transaction): Promise<string | {
+        signature?: string;
+        hash?: string;
+        txid?: string;
+        transactionId?: string;
+    }>;
+    signTransaction?(transaction: Transaction): Promise<Transaction>;
+    publicKey?: {
+        toBase58(): string;
+    };
+}
+
+/**
+ * The wallet the flow signs with, unifying EVM and Solana access behind one
+ * object. AppKit is one implementation (`useReownWalletSession`); a host that
+ * holds its own wallet supplies another. Nothing here may reference AppKit —
+ * that an implementation can be written without importing it is the point.
+ */
+interface WalletSession {
+    walletClient: WalletClient | undefined;
+    /**
+     * Whether this session can sign an EVM transaction right now. It is what the
+     * picker offers an EVM row on.
+     *
+     * Required, and answered by the implementation rather than inferred by the
+     * caller, because the caller can only infer it from whichever object it
+     * happens to check — and that has silently removed a connected user's wallet
+     * from the picker twice: once on `publicClient`, once on a resolvable viem
+     * chain. An implementation that has not thought about it now fails to
+     * compile.
+     *
+     * Distinct from `isReady`, which is about the provider having initialised.
+     *
+     * The invariant callers rely on: `true` means `walletClient` is defined, with
+     * an account and a chain bound.
+     */
+    canSignEvm: boolean;
+    /** Optional: every read falls back to `getPublicClient(chainId, rpcUrls)`,
+     *  so an implementation with no wallet-backed client omits it. */
+    publicClient: PublicClient | undefined;
+    address: Address | undefined;
+    caipAddress?: string;
+    isConnected: boolean;
+    isReady: boolean;
+    icon?: string;
+    isSolana: boolean;
+    solanaAddress?: string;
+    solanaProvider?: SolanaWalletProvider;
+    /** RPC connection managed by the connected Solana wallet session, used for
+     *  reads (blockhash, account info) instead of an app-configured RPC. */
+    solanaConnection?: Connection;
+    openConnect: () => void;
+    disconnect: () => void;
+    switchChain: (chainId: number) => Promise<void>;
+}
+
+/** A `window`, or anything shaped enough like one to hold the two globals. */
+type ChannelTarget = Record<string, unknown>;
+
+/**
+ * The message contract between the embed page and a native host.
+ *
+ * **This contract evolves; it is not frozen.** One URL serves every wrapper,
+ * and the handshake tells the page which protocol version and which
+ * capabilities the wrapper on the other side understands, so the page adapts
+ * at runtime. That puts the compatibility burden on the side we can actually
+ * update — a hosted page — rather than on app-store builds we cannot.
+ *
+ * The discipline that makes it safe:
+ *
+ * - an existing field never changes meaning, and never changes type;
+ * - new fields are optional, and a receiver ignores what it does not know;
+ * - an unknown event type is dropped, an unknown request method answers 4200;
+ * - behaviour that differs by wrapper version is gated on `HelloResult.protocol`
+ *   and `HelloResult.capabilities` — what the HOST speaks. The page's own
+ *   version tells it nothing it does not already know.
+ *
+ * A `/v1/` path exists only as an escape hatch for a break so fundamental the
+ * page cannot adapt to it. Reaching for it means every integrator ships an
+ * app-store release, so it is a last resort rather than a versioning scheme.
+ */
+
+type EmbedMode = "deposit" | "withdraw" | "claim";
+/**
+ * Every prop that survives a JSON hop. Names match the React props 1:1 on
+ * purpose — this is a transport, not a redesign, and a renamed field is a
+ * second thing to keep in sync forever.
+ *
+ * Config crosses the bridge and never the URL: a public URL taking a recipient
+ * and a backend URL is a phishing surface, and it would put keyed RPC
+ * endpoints into URL bars and logs.
+ */
+interface EmbedConfig {
+    mode: EmbedMode;
+    backendUrl: string;
+    recipient: string;
+    /** Never a viem `Chain`. This value is hashed into the account salt, so its
+     *  spelling is a deposit address. */
+    targetChain: TargetChain;
+    targetToken: string;
+    sourceChain?: number;
+    sourceToken?: string;
+    /** USD amount, or the case-insensitive sentinel `"max"`. */
+    defaultAmount?: string;
+    appBalanceUsd?: number;
+    outputTokenRules?: OutputTokenRule[];
+    rejectUnmapped?: boolean;
+    forceRegister?: boolean;
+    /**
+     * No `rpcUrls`. The web modal takes them so an integrator can route reads
+     * through their own endpoints, but those endpoints are usually keyed, and
+     * config crossing the bridge rather than the URL was to keep keyed endpoints
+     * out of logs — putting them in the handshake instead hands them to whatever
+     * the host logs, and to any frame that reaches an unscoped channel. The
+     * chain set already carries `publicRpcUrl`, so nothing is blocked without
+     * them, and a new optional field is the one change this contract makes
+     * cheaply: it can be added the day a client needs it, where removing it
+     * later could not.
+     */
+    enableWallet?: boolean;
+    enableFiatOnramp?: boolean;
+    enableQrTransfer?: boolean;
+    enableGaslessDeposit?: boolean;
+    enableExchangeConnect?: boolean;
+    /**
+     * Opt out of sending session analytics to Rhinestone. Default: on. The URL
+     * override the web props carry is deliberately absent — it exists for our own
+     * dev verification, and a bridge field can be added later but never removed.
+     */
+    enableAnalyticsIngest?: boolean;
+    fiatMethods?: FiatMethodsConfig;
+    assetMigrations?: AssetMigrationsConfig;
+    initialAssetMigration?: keyof AssetMigrationsConfig;
+    /**
+     * **The page never follows the OS on its own.** An absent `mode` is light,
+     * and `theme.mode: "system"` — protocol 2 — is what asks the page to read
+     * `prefers-color-scheme`. Following it silently would drop a dark funding
+     * sheet into a light single-appearance app the moment the user's phone
+     * switched, which is the host's call to make and not ours.
+     *
+     * **Appearance is not a mount-time value.** It can change while the sheet is
+     * open, so a host that tracks it re-sends its config over
+     * `session.configure`; the page repaints in place and the flow is not
+     * disturbed. This is why theming has to live in the bridge config rather
+     * than being handed over once at hello.
+     *
+     * **`"system"` does not mean the same thing on both platforms.** WKWebView
+     * reports the app's effective appearance. Android's WebView reports its
+     * theme's `isLightTheme`, which is *light* whenever the app never declares
+     * one — so an unthemed Android host reads light in OS dark mode, and reads
+     * it silently. A host that knows its own appearance should send `"light"` or
+     * `"dark"` and update it, which is also the only option for an app whose
+     * appearance is its own setting rather than the OS one.
+     */
+    theme?: DepositModalTheme;
+    uiConfig?: DepositModalUIConfig;
+    debug?: boolean;
+    /** Withdraw only. */
+    accountAddress?: string;
+    /** Claim only: prefills the lookup form. */
+    defaultTxHash?: string;
+    /** Claim only: seeds the refund destination, which the user can still edit.
+     *  Deliberately never defaulted to the deposit's sender — returning funds to
+     *  an exchange hot wallet can lose them. */
+    defaultDestination?: string;
+}
+
+interface DepositEmbedProps {
+    /** Where the injected channel lives. Defaults to this page's `window`. */
+    target?: ChannelTarget;
+    /** The handshake failed, so there is no session and no config to render. */
+    onFatal?: (error: unknown) => void;
+}
+declare function DepositEmbed({ target, onFatal }: DepositEmbedProps): react.JSX.Element | null;
+
+export { DepositEmbed, type DepositEmbedProps, type EmbedConfig, type WalletSession };