@waaskey/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+import { Waaskey, WaaskeyOptions, Chain, Balance, CreateWalletParams, CreateWalletOptions, Wallet, SendParams, SendResult, Signature, EmbeddedSession } from '@waaskey/sdk';
+export * from '@waaskey/sdk';
+import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
+
+/**
+ * Design tokens for the Waaskey widget kit (#17). One source for colours, radius and
+ * typography so every component (ConnectModal, WalletWidget, SignPrompt, FundWidget) and the
+ * React Native package share the same theme. White-label by passing a partial `theme` to the
+ * provider; light/dark are both first-class.
+ */
+interface WaasTheme {
+    /** Primary action / brand colour. */
+    accent: string;
+    /** Foreground on the accent (button text). */
+    accentForeground: string;
+    /** Surface/background. */
+    background: string;
+    /** Primary text. */
+    foreground: string;
+    /** Secondary/subtle text. */
+    muted: string;
+    /** Borders / dividers. */
+    border: string;
+    /** Error text. */
+    danger: string;
+    /** Corner radius (CSS length on web). */
+    radius: string;
+    /** Base font family. */
+    fontFamily: string;
+}
+declare const lightTheme: WaasTheme;
+declare const darkTheme: WaasTheme;
+declare const defaultTheme: WaasTheme;
+/** Merge a partial override onto a base theme (white-label). */
+declare function resolveTheme(override?: Partial<WaasTheme>, base?: WaasTheme): WaasTheme;
+
+/** Provide either a ready {@link Waaskey} client or the options to construct one, plus an optional theme. */
+type WaaskeyProviderProps = ({
+    client: Waaskey;
+} | {
+    options: WaaskeyOptions;
+}) & {
+    /** Partial theme override (white-label) merged onto the default light theme. */
+    theme?: Partial<WaasTheme>;
+    children?: ReactNode;
+};
+/**
+ * Makes a {@link Waaskey} client (and the kit {@link WaasTheme}) available to the hooks and
+ * components (`useWaaskey`/`useWaas`, `useTheme`, `<ConnectModal>`, `<WalletWidget>`, …).
+ * Pass a `client` you built, or `options` to construct one (memoized). SSR-safe (no browser
+ * APIs at construction). Written with `createElement` so the package needs no JSX build step.
+ */
+declare function WaaskeyProvider(props: WaaskeyProviderProps): ReactElement;
+/** Ergonomic alias of {@link WaaskeyProvider} — the documented kit entry point (`<WaasProvider>`). */
+declare const WaasProvider: typeof WaaskeyProvider;
+type WaasProviderProps = WaaskeyProviderProps;
+
+/** React context holding the configured {@link Waaskey} client. Provided by {@link WaaskeyProvider}. */
+declare const WaaskeyContext: react.Context<Waaskey | null>;
+
+/** Theme made available by {@link WaaskeyProvider} / `WaasProvider`. Defaults to the light theme. */
+declare const ThemeContext: react.Context<WaasTheme>;
+/** The active {@link WaasTheme} from context (falls back to the default light theme). */
+declare function useTheme(): WaasTheme;
+
+/** Loading/error/data triple for an async read — render all three states. */
+interface AsyncState<T> {
+    data?: T;
+    error?: Error;
+    loading: boolean;
+}
+/** The {@link Waaskey} client from context. Throws if used outside {@link WaaskeyProvider}. */
+declare function useWaaskey(): Waaskey;
+/**
+ * The unified kit surface (#12): the {@link Waaskey} client + active theme, plus the `auth`
+ * resource for convenience. Sugar over `useWaaskey()` + `useTheme()` for the Privy-style DX.
+ */
+declare function useWaas(): {
+    client: Waaskey;
+    theme: WaasTheme;
+    auth: Waaskey['auth'];
+};
+/** Imperatively create a wallet (non-custodial keygen). Returns the action + its async state. */
+declare function useCreateWallet(): {
+    create: (params: CreateWalletParams, options?: CreateWalletOptions) => Promise<Wallet>;
+    wallet?: Wallet;
+    error?: Error;
+    isPending: boolean;
+};
+/** Load a wallet by id (re-fetches when `id` changes); exposes `refresh`. */
+declare function useWallet(id: string | undefined): AsyncState<Wallet> & {
+    refresh: () => Promise<void>;
+};
+/** Read an address's native balance on a chain, client-side (no backend); exposes `refresh`. */
+declare function useBalance(chain: Chain | undefined, address: string | undefined): AsyncState<Balance> & {
+    refresh: () => Promise<void>;
+};
+/** Read an address's native balance across several chains at once; exposes `refresh`. */
+declare function useBalances(chains: Chain[], address: string | undefined): AsyncState<Balance[]> & {
+    refresh: () => Promise<void>;
+};
+/** Status of a {@link useSend} action. */
+type SendStatus = 'idle' | 'pending' | 'sent' | 'error';
+/**
+ * Imperatively send a transaction from a wallet, exposing an optimistic status
+ * (`idle → pending → sent | error`) the UI renders. The platform co-signs (MPC) and returns
+ * the **signed raw tx** (`result.signedTx`) — WaaS never broadcasts; the client submits it
+ * (e.g. `waaskey.broadcast(result.signedTx, { rpcUrl })` or your own node).
+ */
+declare function useSend(walletId: string | undefined): {
+    send: (params: SendParams) => Promise<SendResult>;
+    status: SendStatus;
+    result?: SendResult;
+    error?: Error;
+    reset: () => void;
+};
+/** Load a wallet's signing activity (newest first) — raw signs and send/sweep signed txs; exposes `refresh`. */
+declare function useSignatures(walletId: string | undefined): AsyncState<Signature[]> & {
+    refresh: () => Promise<void>;
+};
+
+/** Step of the email-OTP login flow. */
+type LoginStep = 'email' | 'code' | 'done';
+interface UseLogin {
+    step: LoginStep;
+    /** The email entered at the first step. */
+    email: string;
+    /** The session once login completes. */
+    session?: EmbeddedSession;
+    loading: boolean;
+    error?: Error;
+    /** Send a one-time code to `email` (→ `code` step). */
+    start: (email: string) => Promise<void>;
+    /** Verify the code (→ `done` step on success). */
+    verify: (code: string) => Promise<void>;
+    /** Back to the email step (clears error). */
+    reset: () => void;
+}
+/**
+ * Headless email-OTP login (#6/#13): drives `waaskey.auth.email.start` → `.verify`,
+ * tracking `step`/`loading`/`error` so a UI (e.g. `<ConnectModal>`) — or a custom one —
+ * can render all states. The established session is also held on `waaskey.auth`.
+ */
+declare function useLogin(): UseLogin;
+
+/**
+ * Render `text` to a QR-code data URL using `qrcode` (an optional peer dependency, lazy-loaded).
+ * Returns `undefined` until ready, or when `qrcode` isn't installed — callers should always also
+ * show the raw text (address) so receive works without the dependency.
+ */
+declare function useQrCode(text: string | undefined): string | undefined;
+
+/** Per-instance theme override for {@link ConnectModal} (merged onto the provider theme). */
+type ConnectModalTheme = Partial<WaasTheme>;
+interface ConnectModalProps {
+    /** Whether the modal is shown. */
+    open: boolean;
+    /** Close requested (backdrop / ✕ / after connect). */
+    onClose: () => void;
+    /** Called with the session once login completes. */
+    onConnect?: (session: EmbeddedSession) => void;
+    /** Heading copy. */
+    title?: string;
+    theme?: ConnectModalTheme;
+}
+/**
+ * Drop-in email-OTP login modal (#13). Runs `useLogin` (→ `waaskey.auth`), rendering the
+ * email → code → done steps with loading/error states; calls `onConnect` with the session.
+ * Themeable via inline tokens, accessible (labelled dialog, focus, Esc to close); written
+ * with `createElement` so the package needs no JSX build step.
+ */
+declare function ConnectModal({ open, onClose, onConnect, title, theme }: ConnectModalProps): ReactElement | null;
+
+/** Per-instance theme override for {@link WalletWidget} (merged onto the provider theme). */
+type WalletWidgetTheme = Partial<WaasTheme>;
+interface WalletWidgetProps {
+    /** Waaskey wallet id to render. */
+    walletId: string;
+    /** Chains to show native balances for (e.g. `['ethereum', 'base']`). */
+    chains: Chain[];
+    /** Backend chain id the Send tab submits to (e.g. `'evm:11155111'`). Defaults to `'evm:1'`. */
+    sendChainId?: string;
+    /** Decimals used to parse the human send amount into base units. Defaults to 18 (EVM native). */
+    sendDecimals?: number;
+    /** Called after a successful send. */
+    onSent?: (result: SendResult) => void;
+    theme?: WalletWidgetTheme;
+}
+/**
+ * Drop-in embedded-wallet panel (#14): balances/assets, receive (address + QR), send
+ * (amount + address with optimistic pending/sent/failed states), and activity (tx history).
+ * Built on the headless hooks (`useBalances`/`useSend`/`useSignatures`) — use those directly
+ * for a custom UI. `createElement`-only, so the package needs no JSX build step.
+ */
+declare function WalletWidget({ walletId, chains, sendChainId, sendDecimals, onSent, theme }: WalletWidgetProps): ReactElement;
+
+/** A signature/approval request the app raises for the user to confirm. */
+type SignRequest = {
+    kind: 'sign';
+    walletId: string;
+    digest: string;
+    title?: string;
+} | {
+    kind: 'send';
+    walletId: string;
+    tx: SendParams;
+    title?: string;
+};
+/** What a confirmed request resolves to — a signature hex (`sign`) or the broadcast result (`send`). */
+type SignOutcome = string | SendResult;
+/**
+ * Promise-based signing/approval prompt (#15) — the Privy "confirm transaction" modal.
+ *
+ * `requestSignature(req)` opens the prompt and resolves when the user approves (after the MPC
+ * sign/broadcast completes), or rejects when they cancel. Render the returned `prompt` element
+ * once near the app root. The approval drives the real action over the relay; an error is
+ * recoverable (retry/cancel), never an indefinite spinner.
+ */
+declare function useSignPrompt(): {
+    requestSignature: (req: SignRequest) => Promise<SignOutcome>;
+    prompt: ReactElement | null;
+};
+interface SignPromptProps {
+    request: SignRequest;
+    status: 'idle' | 'pending' | 'error';
+    error?: Error;
+    onApprove: () => void;
+    onReject: () => void;
+}
+/** The approval modal UI (used by {@link useSignPrompt}; exported for fully custom wiring). */
+declare function SignPrompt({ request, status, error, onApprove, onReject }: SignPromptProps): ReactElement;
+
+interface FundWidgetProps {
+    /** Wallet address the purchased crypto is delivered to. */
+    walletAddress: string;
+    /** Chain id, e.g. `evm:1`. */
+    chainId: string;
+    /** Crypto to buy. Defaults to `ETH`. */
+    cryptoCurrency?: string;
+    /** Fiat to pay with. */
+    fiatCurrency?: string;
+    /** Pre-fill the fiat amount. */
+    fiatAmount?: number;
+    /** Button copy. */
+    label?: string;
+    /** Called after the user returns from the on-ramp — a good place to refresh the balance. */
+    onComplete?: () => void;
+}
+/**
+ * Drop-in funding widget (#16) — buy crypto into the embedded wallet via a provider on-ramp
+ * (Transak, …). Fetches a provider widget URL from the API and opens it; on return the user
+ * confirms, firing `onComplete` so the host can refresh the balance. Themeable; the underlying
+ * `waaskey.onramp.widgetUrl(...)` works on web + React Native (only the open step is platform UI).
+ */
+declare function FundWidget({ walletAddress, chainId, cryptoCurrency, fiatCurrency, fiatAmount, label, onComplete }: FundWidgetProps): ReactElement;
+
+export { type AsyncState, ConnectModal, type ConnectModalProps, type ConnectModalTheme, FundWidget, type FundWidgetProps, type LoginStep, type SendStatus, type SignOutcome, SignPrompt, type SignPromptProps, type SignRequest, ThemeContext, type UseLogin, WaasProvider, type WaasProviderProps, type WaasTheme, WaaskeyContext, WaaskeyProvider, type WaaskeyProviderProps, WalletWidget, type WalletWidgetProps, type WalletWidgetTheme, darkTheme, defaultTheme, lightTheme, resolveTheme, useBalance, useBalances, useCreateWallet, useLogin, useQrCode, useSend, useSignPrompt, useSignatures, useTheme, useWaas, useWaaskey, useWallet };