@horus-wallet/sdk-react 0.1.0-beta.2 → 0.3.0-beta.1

package/dist/index.d.ts

@@ -3,12 +3,18 @@ import { ReactNode, ButtonHTMLAttributes } from 'react';
 /**
  * Public types for `@horus-wallet/sdk-react`.
  *
- * The React package targets the partner's BACKEND-PROXY pattern:
- * partner runs a thin proxy on their server (which holds the
- * `hk_sk_*` secret) and the React hooks call that proxy. Each hook's
- * `apiBase` defaults to `/api/horus` — partners can override via
- * provider config. v0.2 will add a publishable-key tier that lets
- * the React SDK call Horus directly without the partner-backend hop.
+ * The React package calls the Horus API directly from the browser
+ * using the partner's PUBLISHABLE app identifier (`app_*`). No
+ * partner backend is required. Auth is carried as `x-horus-key:
+ * <appId>` + `Authorization: Bearer <idToken>` headers on every
+ * request; the backend's per-app `allowedOrigins` allow-list is the
+ * security boundary, so partners MUST register the domains they'll
+ * serve the SDK from before shipping.
+ *
+ * Partners that need a server-side path (managed signing services,
+ * cron jobs, backoffice tools) use the sibling `@horus-wallet/sdk`
+ * package with an `hk_sk_*` secret — the publishable React surface
+ * intentionally has no awareness of secret keys.
  */
 /** Tokens returned from any successful auth flow. */
 interface AuthTokens {
@@ -24,6 +30,16 @@ interface AuthTokens {
     photoUrl?: string;
     providerId?: string;
 }
+/**
+ * Network type — Horus splits each chain into mainnet and testnet
+ * surfaces so partners don't mix them up at the API level.
+ */
+type NetworkType = 'MAINNET' | 'TESTNET';
+/** A chain selector — `(network, networkType)` pair. */
+interface ChainSelector {
+    network: string;
+    networkType: NetworkType;
+}
 /** Subset of the tokens that's safe to expose to consuming hooks. */
 interface User {
     uid: string;
@@ -56,25 +72,22 @@ interface HorusBranding {
 }
 /** Configuration for `<HorusProvider>`. */
 interface HorusProviderConfig {
-    /** Server-assigned id of the partner's app. Used by the popup for white-label policy lookup. */
+    /**
+     * Partner's publishable app identifier (`app_*`). Created via the
+     * Horus dashboard or admin API. Sent as `x-horus-key` on every
+     * request to identify which app the call belongs to. The host page's
+     * Origin must be on the app's `allowedOrigins` allow-list — this is
+     * the load-bearing security boundary for the publishable path.
+     */
     appId: string;
     /**
-     * URL prefix where the partner's backend exposes the Horus proxy
-     * routes. Defaults to `/api/horus`. The proxy routes the SDK
-     * expects:
-     *   - POST {apiBase}/auth/email/signin     → tokens
-     *   - POST {apiBase}/auth/email/signup     → tokens
-     *   - POST {apiBase}/auth/email-link/send  → ok
-     *   - POST {apiBase}/auth/email-link/verify → tokens
-     *   - POST {apiBase}/auth/oauth            → tokens (federate Google/Apple/etc.)
-     *   - POST {apiBase}/auth/refresh          → tokens
-     *   - GET  {apiBase}/wallets               → wallets list
-     *   - GET  {apiBase}/wallets/:network      → wallet details
-     *   - POST {apiBase}/sign-message          → signature
-     *   - POST {apiBase}/transfer/native       → tx hash
-     *   - POST {apiBase}/transfer/token        → tx hash
+     * Horus API base URL. Defaults to `https://api.horuswallet.com` (prod).
+     * Override for staging / dev:
      *
-     * The README shows a reference backend implementation in <50 lines.
+     *   <HorusProvider appId="app_xxx" apiBase="https://dev-api.horuswallet.com">
+     *
+     * Partners NEVER need to expose any path of their own — the SDK
+     * calls the Horus API directly.
      */
     apiBase?: string;
     /**
@@ -92,6 +105,35 @@ interface HorusProviderConfig {
      * Default true. Disable when you're handling expiry manually.
      */
     autoRefresh?: boolean;
+    /**
+     * Auto-create a wallet for the user on first sign-in if they don't
+     * already have one. Defaults to `{ network: 'EVM', networkType: 'MAINNET' }`
+     * to match Privy's behavior — new users land in your app with a
+     * wallet already provisioned, no extra round-trip required.
+     *
+     * Set to `false` to opt out (your app must call `useCreateWallet`
+     * explicitly to provision wallets).
+     *
+     * The provision is idempotent on the backend, runs once per user
+     * per session, and fails silently — a network blip will not block
+     * sign-in. Subsequent auto-provisions for the same user during the
+     * same session are skipped via a localStorage marker.
+     */
+    autoProvisionWallet?: false | {
+        network: string;
+        networkType: 'MAINNET' | 'TESTNET';
+    };
+    /**
+     * Initial active chain exposed via `useSwitchChain()` / `useChain()`.
+     * Defaults to `{ network: 'EVM', networkType: 'MAINNET' }`.
+     *
+     * Partners can read the current chain in their UI (e.g., to highlight
+     * the active network in a switcher) and pass it explicitly when
+     * calling `signMessage` / `sendTransaction` / etc. The active chain
+     * is a UI convenience — it is NOT implicitly used by the signing
+     * hooks unless the partner forwards it themselves.
+     */
+    defaultChain?: ChainSelector;
 }
 
 /**
@@ -185,8 +227,8 @@ declare function useHorusAuth(): UseHorusAuthResult;
 declare function useUser(): User | undefined;
 
 /**
- * `useWallets()` — fetches the signed-in user's wallets from the
- * partner's backend proxy. Refetches when auth state changes.
+ * `useWallets()` — fetches the signed-in user's wallets directly from
+ * the Horus API. Refetches when auth state changes.
  *
  * Mirror of Privy's `useWallets()` — partners coming from there get
  * a familiar `{ wallets, ready }` shape. Each wallet is a thin
@@ -212,6 +254,93 @@ interface UseWalletsResult {
 }
 declare function useWallets(): UseWalletsResult;
 
+/**
+ * `useCreateWallet()` — explicit wallet provisioning.
+ *
+ *   const { create, pending, error } = useCreateWallet();
+ *   await create({ network: 'EVM', networkType: 'MAINNET' });
+ *
+ * The backend's `/createWallet` is idempotent on `(user, network family)`,
+ * so calling this twice for the same network returns the existing wallet
+ * rather than duplicating. After a successful call the provider's
+ * `walletsVersion` counter is bumped, which triggers every active
+ * `useWallets()` to re-fetch — partners don't need to wire a manual
+ * `.refresh()` call.
+ *
+ * For most apps, you'll prefer the provider's `autoProvisionWallet`
+ * config (auto-fires on first sign-in). Reach for this hook when you
+ * need to provision an *additional* chain after the auto-provision,
+ * or for apps that opted out of auto-provision.
+ */
+interface CreateWalletInput {
+    /** Chain name — `'EVM' | 'BASE' | 'POLYGON' | 'BITCOIN' | 'ICP' | …` */
+    network: string;
+    /** `'MAINNET' | 'TESTNET'` */
+    networkType: 'MAINNET' | 'TESTNET';
+    /**
+     * Optional password — encrypts the wallet's private key at rest.
+     * Required for spending operations later if set. Recoverable only
+     * by the user.
+     */
+    password?: string;
+}
+interface CreateWalletResult {
+    /** Server response: nested by-network wallet record + a status message. */
+    wallets: unknown;
+    message: string;
+}
+interface UseCreateWalletResult {
+    /** Provision a new wallet. Resolves with the server response. */
+    create: (input: CreateWalletInput) => Promise<CreateWalletResult>;
+    /** True while a `create()` call is in flight. */
+    pending: boolean;
+    /** Last error, if any. Cleared on the next attempt. */
+    error: Error | undefined;
+}
+declare function useCreateWallet(): UseCreateWalletResult;
+
+/**
+ * `useSwitchChain()` — read and update the active chain selector.
+ *
+ *   const { chain, switchChain } = useSwitchChain();
+ *   <button onClick={() => switchChain({ network: 'BASE', networkType: 'MAINNET' })}>
+ *     Use Base
+ *   </button>
+ *
+ * Mirror of Privy's `useSwitchChain`. Pure UI state — partners forward
+ * `chain` explicitly into `signMessage` / `sendTransaction` / etc.
+ * calls. We deliberately don't auto-thread it through the signing
+ * hooks because an implicit "last switched chain" easily becomes a
+ * footgun (user switches to mainnet, dapp signs a testnet tx, etc).
+ *
+ * `supportedChains` is the static union of chain names the Horus
+ * backend supports today, listed in the order partners are most
+ * likely to want to surface them. Re-exported here so partners can
+ * render a chain picker without hardcoding the list themselves.
+ */
+
+/**
+ * Chain names the Horus backend supports today. Frozen tuple — typed
+ * as readonly so a partner who pins on a specific value gets a TS
+ * error when we drop a chain rather than a silent runtime miss.
+ */
+declare const SUPPORTED_CHAINS: readonly ["EVM", "ETHEREUM", "BASE", "POLYGON", "BSC", "ARBITRUM", "OPTIMISM", "BITCOIN", "ICP", "CASPER", "AETERNITY"];
+type SupportedChain = (typeof SUPPORTED_CHAINS)[number];
+interface UseSwitchChainResult {
+    /** Currently-active chain selector. */
+    chain: ChainSelector;
+    /** Set the active chain. Triggers a re-render in every consumer. */
+    switchChain: (chain: ChainSelector) => void;
+    /** Static list of chain names this SDK supports. */
+    supportedChains: readonly SupportedChain[];
+}
+declare function useSwitchChain(): UseSwitchChainResult;
+/**
+ * Alias for partners who prefer the "read-only" framing. Returns
+ * exactly the same shape as `useSwitchChain()`.
+ */
+declare const useChain: typeof useSwitchChain;
+
 /**
  * `useSignMessage()` — signs a UTF-8 message with the user's wallet.
  * EVM applies EIP-191 prefix server-side; Casper raw-signs; other
@@ -236,9 +365,113 @@ interface UseSignMessageResult {
 declare function useSignMessage(): UseSignMessageResult;
 
 /**
- * `useTransfer()` — native + token transfer helpers backed by the
- * partner's proxy. Each variant returns `{ pending, error }` so
- * forms can drive disabled-state without local plumbing.
+ * `useSignTypedData()` — EIP-712 typed-data signing.
+ *
+ *   const { signTypedData, pending, error } = useSignTypedData();
+ *
+ *   const sig = await signTypedData({
+ *     network: 'BASE',
+ *     networkType: 'MAINNET',
+ *     typedData: {
+ *       domain: { name: 'Acme', version: '1', chainId: 8453, verifyingContract: '0x…' },
+ *       types: {
+ *         Order: [
+ *           { name: 'buyer', type: 'address' },
+ *           { name: 'amount', type: 'uint256' },
+ *         ],
+ *       },
+ *       primaryType: 'Order',
+ *       message: { buyer: '0x…', amount: '1000000' },
+ *     },
+ *   });
+ *
+ * EVM-only. Non-EVM networks return a 400 (`HorusHttpError`). The
+ * `typedData` argument is forwarded verbatim — partners can pass the
+ * exact payload they'd hand to `eth_signTypedData_v4`, including a
+ * `EIP712Domain` entry in `types` (the backend strips it before
+ * hashing, matching MetaMask's behavior).
+ */
+
+interface Eip712TypedData {
+    domain: Record<string, unknown>;
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    /** Optional — the backend derives the primary type from the structure. */
+    primaryType?: string;
+    message: Record<string, unknown>;
+}
+interface SignTypedDataInput {
+    network: string;
+    networkType: NetworkType;
+    typedData: Eip712TypedData;
+    walletIndex?: number;
+    /** Wallet password if the user has one. */
+    password?: string;
+}
+interface UseSignTypedDataResult {
+    signTypedData: (input: SignTypedDataInput) => Promise<string>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useSignTypedData(): UseSignTypedDataResult;
+
+/**
+ * `useSendTransaction()` — generic EVM transaction sign + submit.
+ *
+ *   const { sendTransaction, pending, error } = useSendTransaction();
+ *
+ *   const { hash } = await sendTransaction({
+ *     network: 'BASE',
+ *     networkType: 'MAINNET',
+ *     to: '0xContractAddress',
+ *     data: '0xabcdef…',      // encoded contract call
+ *     value: '0',
+ *   });
+ *
+ * Use this when `useTransfer().native()` / `.token()` aren't enough —
+ * e.g., calling an arbitrary contract method, deploying a contract,
+ * setting an allowance, etc. The backend handles nonce + gas; partners
+ * only fill in what they want to override.
+ *
+ * Returns the broadcast tx hash. Confirmation polling is the caller's
+ * job (subscribe via your own RPC, or poll a block explorer).
+ *
+ * EVM-only. Non-EVM chains use their own submit primitives (`/withdraw`
+ * for ICP / Casper, etc.) which today aren't exposed through this hook.
+ */
+
+interface SendTransactionInput {
+    network: string;
+    networkType: NetworkType;
+    /** Recipient or contract address (`0x` + 40 hex chars). */
+    to: string;
+    /**
+     * Value in wei. Pass as a string (or bigint) — JS numbers lose bits
+     * above 2^53. Default: 0.
+     */
+    value?: string | bigint;
+    /** ABI-encoded calldata for contract calls. */
+    data?: string;
+    /** Explicit gas limit override. Omit to let the RPC estimate. */
+    gasLimit?: string | bigint;
+    walletIndex?: number;
+    password?: string;
+}
+interface UseSendTransactionResult {
+    sendTransaction: (input: SendTransactionInput) => Promise<{
+        hash: string;
+    }>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useSendTransaction(): UseSendTransactionResult;
+
+/**
+ * `useTransfer()` — native + token transfer helpers. Each variant
+ * returns `{ pending, error }` so forms can drive disabled-state
+ * without local plumbing. Calls Horus directly.
  */
 interface NativeTransferInput {
     network: string;
@@ -299,9 +532,194 @@ interface HorusLoginButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElem
 declare function HorusLoginButton({ flow, phone, onAuthenticated, onError, children, disabled, style, ...rest }: HorusLoginButtonProps): JSX.Element;
 
 /**
- * Fetch wrapper for calls to the partner's backend proxy. Handles
- * the auto-refresh-on-401 dance + JSON serialization + a typed
- * error so consuming hooks can branch on `err.status`.
+ * Shared helpers for building auth-page URLs. Reused by the popup
+ * (`openPopupFlow` in `useHorusAuth`) and the inline iframe modal
+ * (`<HorusAuthModal>`). Centralizing here keeps the wire shape
+ * exactly aligned across both — partners get identical behavior
+ * regardless of which presentation surface they pick.
+ *
+ * Not exported to partners; internal-only.
+ */
+
+type AuthFlow = 'google' | 'email_link' | 'phone';
+
+/**
+ * `<HorusAuthModal>` — inline auth flow.
+ *
+ * Renders an iframe pointed at `auth.horuswallet.com` with a backdrop
+ * + focus-trap shell. Partners use this as a drop-in alternative to
+ * `<HorusLoginButton>`'s popup model — matches Privy / Magic's inline
+ * modal UX.
+ *
+ *   const [open, setOpen] = useState(false);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => setOpen(true)}>Sign in</button>
+ *       <HorusAuthModal
+ *         flow="google"
+ *         open={open}
+ *         onClose={() => setOpen(false)}
+ *         onSuccess={(user) => { setOpen(false); console.log(user); }}
+ *       />
+ *     </>
+ *   );
+ *
+ * The component is controlled (partner owns `open`). On `success`, the
+ * provider's `signIn` is invoked under the hood — partners don't need
+ * to call it themselves — and the partner-supplied `onSuccess` fires
+ * with the resulting user. `onClose` is called for both user cancel
+ * and Escape-key dismissal.
+ *
+ * Requires the Horus auth page to be deployed with iframe-friendly
+ * CSP headers (frame-ancestors permitting the partner origin). The
+ * postMessage protocol is identical to the popup flow.
+ */
+
+interface HorusAuthModalProps {
+    /** Which sign-in flow to render in the iframe. */
+    flow: AuthFlow;
+    /** Optional phone-flow pre-fill. */
+    phone?: string;
+    /** Controlled open state — partner toggles to show/hide the modal. */
+    open: boolean;
+    /** Called when the modal is dismissed (user cancel, Escape, success). */
+    onClose: () => void;
+    /** Called after a successful sign-in — receives the new user object. */
+    onSuccess?: (user: User) => void;
+    /** Called when the iframe surfaces an error. */
+    onError?: (err: Error) => void;
+    /**
+     * Inline style override for the dialog. Default is a centered
+     * 480×640 panel with rounded corners — works for the canonical
+     * Horus auth-page; partners with strong design systems can override.
+     */
+    dialogStyle?: React.CSSProperties;
+    /** Style override for the backdrop. */
+    backdropStyle?: React.CSSProperties;
+}
+declare function HorusAuthModal(props: HorusAuthModalProps): JSX.Element | null;
+
+/**
+ * `<HorusRevealModal>` — iframe-based private-key reveal surface.
+ *
+ *   const { reveal } = useExportWallet();
+ *   const [revealToken, setRevealToken] = useState<string | null>(null);
+ *
+ *   <button
+ *     onClick={async () => {
+ *       const { revealToken } = await reveal({ network: 'EVM', networkType: 'MAINNET', password });
+ *       setRevealToken(revealToken);
+ *     }}
+ *   >Export private key</button>
+ *
+ *   <HorusRevealModal
+ *     revealToken={revealToken}
+ *     open={revealToken !== null}
+ *     onClose={() => setRevealToken(null)}
+ *   />
+ *
+ * The modal renders the auth-page's reveal flow inline. The iframe
+ * runs at `auth.horuswallet.com` — partner JS cannot read its DOM
+ * cross-origin, so the user's private key never enters the partner
+ * page's address space. The partner only receives a `reveal_complete`
+ * postMessage at the end carrying `{ viewed: boolean }` — useful for
+ * analytics, but no key material.
+ */
+interface HorusRevealModalProps {
+    /** Token obtained from `useExportWallet().reveal(...)`. */
+    revealToken: string | null;
+    /** Controlled open state. */
+    open: boolean;
+    /** Called when the modal is dismissed (user cancel, success, error, Escape). */
+    onClose: () => void;
+    /**
+     * Called when the iframe signals the reveal finished. `viewed` is
+     * true only if the user actually clicked through to see the key.
+     */
+    onComplete?: (viewed: boolean) => void;
+    /** Called on a flow-level error (network blip, bad token). */
+    onError?: (err: Error) => void;
+    dialogStyle?: React.CSSProperties;
+    backdropStyle?: React.CSSProperties;
+}
+declare function HorusRevealModal(props: HorusRevealModalProps): JSX.Element | null;
+
+/**
+ * `useExportWallet()` — initiate a private-key reveal flow.
+ *
+ *   const { reveal, pending, error } = useExportWallet();
+ *
+ *   // In a click handler:
+ *   const { revealToken } = await reveal({ network: 'EVM', networkType: 'MAINNET', password });
+ *   // Then mount <HorusRevealModal revealToken={revealToken} ... />
+ *
+ * Two-step flow (matches Privy's reveal model):
+ *
+ *   1. This hook calls `/exportWallet/grant` with the user's session
+ *      and wallet password. The backend validates and returns a
+ *      short-lived (60s) `revealToken`.
+ *   2. The partner page mounts `<HorusRevealModal>` with that token.
+ *      The modal opens an iframe at `auth.horuswallet.com?flow=reveal`,
+ *      the iframe re-prompts for the password, calls /redeem itself,
+ *      displays the key, and posts a "done" back. Partner JS never
+ *      sees the private key.
+ *
+ * Why the password is collected twice (once for grant, once in the
+ * iframe for redeem): the grant proves the user authorized the export
+ * AND that they know the password right now — without that step,
+ * a stolen session alone could trigger the reveal modal and bombard
+ * the user with a password prompt. The iframe re-prompt is the layer
+ * that proves the holder of the partner page is the same human who
+ * authorized the grant (the iframe never trusts partner JS for the
+ * password input).
+ */
+
+interface ExportWalletInput {
+    network: string;
+    networkType: NetworkType;
+    walletIndex?: number;
+    /**
+     * Wallet password. Pass `''` for password-less wallets — the backend
+     * uses the attempted decrypt as the proof of ownership, so an empty
+     * string against a password-less wallet succeeds where the same
+     * empty string against a password-protected wallet returns 401.
+     */
+    password: string;
+}
+interface ExportWalletResult {
+    /**
+     * Opaque token to hand to `<HorusRevealModal>`. Expires in 60s.
+     * Single-use: after the modal redeems it, a second redeem returns 409.
+     */
+    revealToken: string;
+    /** Seconds the token is valid for. */
+    expiresIn: number;
+}
+interface UseExportWalletResult {
+    reveal: (input: ExportWalletInput) => Promise<ExportWalletResult>;
+    pending: boolean;
+    error: Error | undefined;
+}
+declare function useExportWallet(): UseExportWalletResult;
+
+/**
+ * Fetch wrapper for browser-direct calls to the Horus API.
+ *
+ * Two headers are stamped on every request:
+ *   - `x-horus-key: <publishable appId>` — the partner's `app_*`
+ *     identifier. Tells Horus which app this call belongs to and
+ *     anchors the Origin allow-list check on the backend.
+ *   - `Authorization: Bearer <idToken>` — the end-user's session.
+ *     Skipped when `options.auth` is `false` (sign-in / refresh
+ *     endpoints that mint the token in the first place).
+ *
+ * On 401 we run a single refresh-then-retry. If refresh fails, the
+ * original 401 bubbles up so the provider can transition to the
+ * `unauthenticated` state.
+ *
+ * Returns the parsed JSON body on success, or throws a typed
+ * `HorusHttpError` so consumer hooks can branch on `err.status`.
  */
 
 declare class HorusHttpError extends Error {
@@ -311,4 +729,4 @@ declare class HorusHttpError extends Error {
     constructor(status: number, message: string, body: unknown, code?: string);
 }
 
-export { type AuthState, type AuthTokens, type HorusBranding, HorusHttpError, HorusLoginButton, type HorusLoginButtonProps, HorusProvider, type HorusProviderConfig, type HorusProviderProps, type NativeTransferInput, type SignMessageInput, type TokenTransferInput, type UseHorusAuthResult, type User, type WalletDescriptor, useHorusAuth, useSignMessage, useTransfer, useUser, useWallets };
+export { type AuthState, type AuthTokens, type ChainSelector, type CreateWalletInput, type CreateWalletResult, type Eip712TypedData, type ExportWalletInput, type ExportWalletResult, HorusAuthModal, type HorusAuthModalProps, type HorusBranding, HorusHttpError, HorusLoginButton, type HorusLoginButtonProps, HorusProvider, type HorusProviderConfig, type HorusProviderProps, HorusRevealModal, type HorusRevealModalProps, type NativeTransferInput, type NetworkType, SUPPORTED_CHAINS, type SendTransactionInput, type SignMessageInput, type SignTypedDataInput, type SupportedChain, type TokenTransferInput, type UseHorusAuthResult, type User, type WalletDescriptor, useChain, useCreateWallet, useExportWallet, useHorusAuth, useSendTransaction, useSignMessage, useSignTypedData, useSwitchChain, useTransfer, useUser, useWallets };