@unifold/headless-react 0.1.70-beta.1

package/README.md

@@ -0,0 +1,198 @@
+# @unifold/headless-react
+
+Hooks-only (no UI) React SDK for Unifold crypto deposits. You own 100% of the
+rendering; the SDK owns the data flow, session lifecycle, polling, and events.
+
+- **Zero UI, zero CSS** — no components, no Tailwind, no portals.
+- **Layered like Stripe.js** — the flow logic lives in a framework-agnostic
+  `DepositSession` controller in `@unifold/core`; this package is a thin React
+  binding over it.
+- **Events first** — every state transition is observable as a typed event
+  using the same webhook-style envelope (`{ id, type, created, data: { object } }`)
+  as `@unifold/connect-react`'s `onEvent`. Callbacks (`onSuccess`, …) are sugar
+  over the event stream.
+
+> Already using `@unifold/connect-react` (the modal SDK)? Don't install this
+> package — import the same hooks from `@unifold/connect-react/headless`
+> instead. Install exactly one of the two packages.
+
+## Install
+
+```bash
+npm install @unifold/headless-react
+# or
+pnpm add @unifold/headless-react
+```
+
+## Setup
+
+Same provider as the modal SDK — the two SDKs can coexist in one app, sharing
+the provider and QueryClient:
+
+```tsx
+import { UnifoldProvider } from '@unifold/headless-react';
+
+function App() {
+  return (
+    <UnifoldProvider publishableKey="pk_live_...">
+      <YourApp />
+    </UnifoldProvider>
+  );
+}
+```
+
+## Quickstart — a custom deposit screen
+
+```tsx
+import { useDeposit } from '@unifold/headless-react';
+
+function DepositUSDC({ externalUserId }: { externalUserId: string }) {
+  const { status, getAddress, latestExecution } = useDeposit({
+    externalUserId,
+    destination: {
+      chainType: 'ethereum',
+      chainId: '8453',
+      tokenAddress: USDC_BASE,
+      recipientAddress: userTreasuryAddress,
+    },
+    onSuccess: (execution) => toast.success(`Received $${execution.destinationAmountUsd}`),
+  });
+
+  const eth = getAddress({ chainType: 'ethereum' });
+  if (!eth) return <Spinner />;
+
+  return (
+    <div>
+      <MyQrCode value={eth.address} />
+      <CopyField value={eth.address} />
+      {status === 'processing' && <MyProgress execution={latestExecution!} />}
+    </div>
+  );
+}
+```
+
+`useDeposit` drives an explicit status state machine:
+
+```
+idle → creating_addresses → awaiting_funds → processing → succeeded | failed
+                          ↘ error (fatal: address creation / invalid recipient)
+```
+
+The headless SDK is deliberately **not IP-aware** — `useDeposit` never geo-gates
+address creation. If you want the modal's region gate, opt in with
+`useAllowedCountry` and gate your own UI on `isAllowed`.
+
+### Manual confirmation + full event wiring
+
+```tsx
+const deposit = useDeposit({
+  externalUserId,
+  destination,
+  confirmationMode: 'manual',
+  onEvent: (event) => analytics.track(event.type, event),
+  onExecutionUpdated: (execution) => setTimeline((t) => [...t, execution]),
+  onError: (error) => {
+    if (error.code === 'POLLING_ERROR') showBanner('Connection hiccup — still watching');
+    else showFailure(error);
+  },
+});
+
+<Button onClick={deposit.confirmFundsSent} disabled={deposit.isCheckingDeposit}>
+  I've made the transfer
+</Button>;
+```
+
+### Promise waiters
+
+For imperative flows, the session exposes `await`-style sugar over the event
+stream (they only listen — neither starts nor stops the session):
+
+```ts
+// Generic primitive over the status state machine:
+await session.waitForStatus('processing');                 // deposit detected
+await session.waitForStatus(['succeeded', 'failed']);      // terminal outcome
+
+// The 90% case — mirrors beginDeposit()'s promise contract
+// (resolve on success, reject on failure):
+try {
+  const execution = await session.waitForSuccess();
+  creditUser(execution.destinationAmountUsd);
+} catch (error) {
+  // DepositSessionWaitError: DEPOSIT_FAILED | SESSION_ERROR | ABORTED | DESTROYED
+}
+```
+
+Both accept `{ signal }` — an `AbortSignal` cancels the *wait*, never the
+session (a deposit isn't cancelable: once the user sends funds, they arrive
+whether or not anyone is awaiting). For a deadline, compose the platform
+primitive — `waitForSuccess({ signal: AbortSignal.timeout(60_000) })` — and
+treat it as "outcome still unknown", not failure: keep the session (and your
+UI) watching. From `useDeposit`, reach the waiters via the `session` escape
+hatch.
+
+**One session, many executions.** Unlike quote-scoped models (e.g. Privy's,
+where one address maps to one order), a Unifold session can observe multiple
+executions — the user may send twice, or on two different chains, to the same
+universal addresses. `waitForSuccess` is one-shot **first-completion**
+detection; the session keeps polling afterwards, and every settlement fires
+its own `direct_execution.succeeded` event.
+
+**Live outcomes only.** The 60s lookback window exists to catch deposits sent
+moments before the session started — it only admits executions still
+*in-flight* at first sight (their settlement then fires live). An execution
+that already settled before the session began is history and never re-fires
+success/failure events, so reopening a deposit screen right after a success
+cannot double-credit. Render history with `useExecutions` instead. To credit each deposit, subscribe
+to events (dedupe on `execution.id`) or render `executions` from the hook:
+
+```ts
+session.on(DepositSessionEventType.EXECUTION_SUCCEEDED, ({ data }) => {
+  creditUser(data.object); // fires once per settled execution
+});
+```
+
+### Vanilla JS (no React)
+
+The controller is usable without React from `@unifold/core`:
+
+```ts
+import { createUnifoldClient } from '@unifold/core';
+
+const unifold = createUnifoldClient({ publishableKey: 'pk_live_...' });
+const session = unifold.createDepositSession({ externalUserId, destination });
+
+await session.start();
+renderQr(session.getSnapshot().addresses);
+
+const execution = await session.waitForSuccess();
+showSuccess(execution);
+session.destroy();
+```
+
+## Hooks
+
+| Hook | Purpose |
+| --- | --- |
+| `useDeposit` | Flagship flow hook: deposit addresses + execution detection + status state machine + events |
+| `useDepositAddresses` | Addresses without a live session (cached, idempotent create) |
+| `useSupportedDepositTokens` | Source token/chain list for custom pickers |
+| `useExecutions` | Deposit history (tracker screens) |
+| `useAllowedCountry` | Geo gate the modal uses; decide what to render when blocked |
+| `useAddressValidation` | Inline recipient validation (e.g. Algorand opt-in) |
+| `useUnifoldClient` | Escape hatch to the configured vanilla client |
+
+## Events
+
+`resource.action` names with webhook-mirroring envelopes; `direct_execution.succeeded`
+is byte-compatible with the modal SDK's `onEvent`:
+
+- `deposit_session.started` / `.addresses_created` / `.confirmation_started` / `.stopped` / `.errored`
+- `direct_execution.detected` / `.updated` / `.succeeded` / `.failed`
+
+When mixing the modal and headless surfaces, dedupe on `execution.id` (envelope
+`sevt_` ids are minted per emitter), and keep one active surface per flow at a
+time.
+
+## License
+
+Apache-2.0

package/dist/index.d.mts

@@ -0,0 +1,218 @@
+export { UnifoldConfig, UnifoldProvider, UnifoldProviderProps, useUnifold } from '@unifold/react-provider';
+import { UnifoldClient, ChainType, EvmContractCall, DepositMethod, DepositSessionEvent, DepositAddress, DirectExecution, ExecutionStatus, DepositSessionError, DepositSessionStatus, DepositSession, ActionType, ProductType, SupportedToken, AddressValidationFailureCode } from '@unifold/core';
+export { ActionType, ChainType, DepositAddress, DepositMethod, DepositSession, DepositSessionDestination, DepositSessionError, DepositSessionErrorCode, DepositSessionEvent, DepositSessionEventMap, DepositSessionEventType, DepositSessionParams, DepositSessionSnapshot, DepositSessionStatus, DepositSessionWaitError, DepositSessionWaitErrorCode, DepositSessionWaitOptions, DirectExecution, EvmContractCall, ExecutionStatus, SupportedChain, SupportedToken, UnifoldClient, UnifoldClientOptions, createUnifoldClient } from '@unifold/core';
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+/**
+ * Returns a memoized {@link UnifoldClient} configured with the publishable key
+ * from the surrounding `UnifoldProvider`.
+ *
+ * Escape hatch for imperative access to the headless API (resource calls,
+ * `createDepositSession`) outside the provided hooks.
+ */
+declare function useUnifoldClient(): UnifoldClient | null;
+
+interface UseDepositDestination {
+    chainType: ChainType;
+    chainId: string;
+    tokenAddress: string;
+    /** Address that receives the deposited funds. */
+    recipientAddress: string;
+    /** EVM-only post-delivery calls; same constraints as DepositConfig.contractCalls. */
+    contractCalls?: EvmContractCall[];
+}
+interface UseDepositOptions {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string | undefined;
+    /** Destination — what the deposit converts into and where it lands. */
+    destination: UseDepositDestination;
+    /**
+     * When the backend scan nudge is armed: 'auto' (default, after 5s) or
+     * 'manual' (host calls confirmFundsSent() from its own "I've sent it" button).
+     */
+    confirmationMode?: 'auto' | 'manual';
+    /** Rail hint stamped onto emitted events' `method`. @default 'transfer' */
+    method?: DepositMethod;
+    /**
+     * When true (default), start() is called automatically once externalUserId and the
+     * provider's publishable key are present. Set false to gate on your own UI
+     * (e.g. only start when the user opens your deposit sheet).
+     */
+    autoStart?: boolean;
+    /** Every lifecycle event ('*' subscription) — analytics/debug fan-out. */
+    onEvent?: (event: DepositSessionEvent) => void;
+    /** deposit_session.addresses_created */
+    onAddressesReady?: (addresses: DepositAddress[]) => void;
+    /** direct_execution.detected */
+    onExecutionDetected?: (execution: DirectExecution) => void;
+    /** direct_execution.updated */
+    onExecutionUpdated?: (execution: DirectExecution & {
+        previousStatus: ExecutionStatus | null;
+    }) => void;
+    /** direct_execution.succeeded */
+    onSuccess?: (execution: DirectExecution) => void;
+    /** direct_execution.failed + deposit_session.errored */
+    onError?: (error: DepositSessionError) => void;
+    /** Fired whenever snapshot.status changes. */
+    onStatusChange?: (status: DepositSessionStatus) => void;
+}
+interface UseDepositResult {
+    status: DepositSessionStatus;
+    /** Deposit addresses (one per chain type); empty until created. */
+    addresses: DepositAddress[];
+    /**
+     * Convenience: the deposit address matching the query. Takes an options
+     * object so future selectors (e.g. `addressType` when a chain type exposes
+     * multiple address formats) can be added without a breaking change.
+     */
+    getAddress: (query: {
+        chainType: ChainType;
+    }) => DepositAddress | undefined;
+    /** All executions observed this session, newest first. */
+    executions: DirectExecution[];
+    latestExecution: DirectExecution | null;
+    /** True while the backend is actively checking for the deposit (scan nudge armed). */
+    isCheckingDeposit: boolean;
+    error: DepositSessionError | null;
+    /** Start the session (relevant when autoStart: false, or to retry after error). */
+    start: () => Promise<void>;
+    /** Arm the backend scan nudge in 'manual' mode ("I've sent it" button). */
+    confirmFundsSent: () => void;
+    /** Stop all polling. */
+    stop: () => void;
+    /** stop() + fresh baseline + start(). */
+    restart: () => Promise<void>;
+    /** Escape hatch to the underlying session (e.g. extra event subscriptions). */
+    session: DepositSession | null;
+}
+/**
+ * Flagship headless deposit hook — the no-UI equivalent of
+ * `beginDeposit({ initialScreen: 'transfer' })`.
+ *
+ * Wraps a core {@link DepositSession}: creates it, subscribes via
+ * `useSyncExternalStore`, destroys it on unmount, and exposes the snapshot,
+ * imperative controls, and callback sugar. The host renders 100% of the UI.
+ *
+ * SSR-safe: the session is constructed in an effect; server renders see
+ * `status: 'idle'` and empty arrays.
+ */
+declare function useDeposit(options: UseDepositOptions): UseDepositResult;
+
+interface UseDepositAddressesOptions {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string | undefined;
+    destination?: {
+        chainType?: ChainType;
+        chainId?: string;
+        tokenAddress?: string;
+        recipientAddress?: string;
+        contractCalls?: EvmContractCall[];
+    };
+    /** Action type for the deposit address. @default server default ('deposit') */
+    actionType?: ActionType;
+    /** Whether the query should execute. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Fetch/create the user's deposit addresses with react-query caching.
+ *
+ * `POST /v1/public/deposit_addresses` is idempotent, so this is safe to cache
+ * (1h stale). For hosts that want addresses without a live deposit session
+ * (e.g. pre-rendering a receive screen). Shares its cache key with the modal
+ * SDK's internal hook, so mixing surfaces never double-fetches.
+ */
+declare function useDepositAddresses(options: UseDepositAddressesOptions): _tanstack_react_query.UseQueryResult<DepositAddress[], Error>;
+
+interface UseSupportedDepositTokensOptions {
+    /** All three destination fields must be provided together to filter. */
+    destination?: {
+        chainType: string;
+        chainId: string;
+        tokenAddress: string;
+    };
+    productType?: ProductType;
+    /** Whether the query should execute. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Source tokens/chains a user can deposit from — for building custom
+ * token/chain pickers. Cached 5 minutes; deduped with the modal SDK.
+ */
+declare function useSupportedDepositTokens(options?: UseSupportedDepositTokensOptions): _tanstack_react_query.UseQueryResult<SupportedToken[], Error>;
+
+interface UseExecutionsOptions {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string | undefined;
+    /**
+     * Polling interval in milliseconds; `false` (default) disables polling.
+     * Deposit detection should use `useDeposit` — this hook is for
+     * history/tracker screens.
+     */
+    refetchInterval?: number | false;
+    /** Whether the query should execute. Defaults to true. */
+    enabled?: boolean;
+    /** Filter by action type. Defaults to Deposit. */
+    actionType?: ActionType;
+}
+/**
+ * The user's executions (deposit history), mapped to camelCase
+ * {@link DirectExecution}. Shares its cache key with the modal SDK's tracker.
+ */
+declare function useExecutions(options: UseExecutionsOptions): _tanstack_react_query.UseQueryResult<DirectExecution[], Error>;
+
+interface AllowedCountryResult {
+    /** Whether the user is in an allowed country/subdivision. null while loading. */
+    isAllowed: boolean | null;
+    /** ISO 3166-1 alpha-2 country code (e.g. "US", "PT") */
+    alpha2: string | null;
+    /** Full country name (e.g. "United States") */
+    country: string | null;
+    /** ISO 3166-2 subdivision code (e.g. "NY"), null if unavailable */
+    subdivisionCode: string | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Whether the current user's region is allowed by the project's blocked
+ * countries configuration — the same geo gate the modal runs before showing
+ * deposit rails.
+ *
+ * The headless SDK is deliberately not IP-aware: `useDeposit` never runs this
+ * check. Hosts that want the modal's geo behavior opt in by rendering
+ * against this hook (and gating their deposit UI on `isAllowed`).
+ */
+declare function useAllowedCountry(): AllowedCountryResult;
+
+interface UseAddressValidationOptions {
+    /** Address that will receive the deposited funds. */
+    recipientAddress?: string;
+    destination?: {
+        chainType: ChainType;
+        chainId: string;
+        tokenAddress: string;
+    };
+    /** Whether to run validation. Defaults to true. */
+    enabled?: boolean;
+}
+interface AddressValidationResult {
+    /** Whether the address can receive funds. null while loading or when params are incomplete. */
+    isValid: boolean | null;
+    /** Standardized error code for i18n. */
+    failureCode: AddressValidationFailureCode | null;
+    /** Metadata for message interpolation. */
+    metadata: {
+        chain_name?: string;
+        token_symbol?: string;
+    } | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Validate that a recipient address can receive funds for a destination
+ * (primarily Algorand asset opt-in; typically valid=true elsewhere).
+ * `useDeposit` already fails fast on invalid recipients; use this hook for
+ * inline form validation before starting a session.
+ */
+declare function useAddressValidation(options: UseAddressValidationOptions): AddressValidationResult;
+
+export { type AddressValidationResult, type AllowedCountryResult, type UseAddressValidationOptions, type UseDepositAddressesOptions, type UseDepositDestination, type UseDepositOptions, type UseDepositResult, type UseExecutionsOptions, type UseSupportedDepositTokensOptions, useAddressValidation, useAllowedCountry, useDeposit, useDepositAddresses, useExecutions, useSupportedDepositTokens, useUnifoldClient };

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+export { UnifoldConfig, UnifoldProvider, UnifoldProviderProps, useUnifold } from '@unifold/react-provider';
+import { UnifoldClient, ChainType, EvmContractCall, DepositMethod, DepositSessionEvent, DepositAddress, DirectExecution, ExecutionStatus, DepositSessionError, DepositSessionStatus, DepositSession, ActionType, ProductType, SupportedToken, AddressValidationFailureCode } from '@unifold/core';
+export { ActionType, ChainType, DepositAddress, DepositMethod, DepositSession, DepositSessionDestination, DepositSessionError, DepositSessionErrorCode, DepositSessionEvent, DepositSessionEventMap, DepositSessionEventType, DepositSessionParams, DepositSessionSnapshot, DepositSessionStatus, DepositSessionWaitError, DepositSessionWaitErrorCode, DepositSessionWaitOptions, DirectExecution, EvmContractCall, ExecutionStatus, SupportedChain, SupportedToken, UnifoldClient, UnifoldClientOptions, createUnifoldClient } from '@unifold/core';
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+/**
+ * Returns a memoized {@link UnifoldClient} configured with the publishable key
+ * from the surrounding `UnifoldProvider`.
+ *
+ * Escape hatch for imperative access to the headless API (resource calls,
+ * `createDepositSession`) outside the provided hooks.
+ */
+declare function useUnifoldClient(): UnifoldClient | null;
+
+interface UseDepositDestination {
+    chainType: ChainType;
+    chainId: string;
+    tokenAddress: string;
+    /** Address that receives the deposited funds. */
+    recipientAddress: string;
+    /** EVM-only post-delivery calls; same constraints as DepositConfig.contractCalls. */
+    contractCalls?: EvmContractCall[];
+}
+interface UseDepositOptions {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string | undefined;
+    /** Destination — what the deposit converts into and where it lands. */
+    destination: UseDepositDestination;
+    /**
+     * When the backend scan nudge is armed: 'auto' (default, after 5s) or
+     * 'manual' (host calls confirmFundsSent() from its own "I've sent it" button).
+     */
+    confirmationMode?: 'auto' | 'manual';
+    /** Rail hint stamped onto emitted events' `method`. @default 'transfer' */
+    method?: DepositMethod;
+    /**
+     * When true (default), start() is called automatically once externalUserId and the
+     * provider's publishable key are present. Set false to gate on your own UI
+     * (e.g. only start when the user opens your deposit sheet).
+     */
+    autoStart?: boolean;
+    /** Every lifecycle event ('*' subscription) — analytics/debug fan-out. */
+    onEvent?: (event: DepositSessionEvent) => void;
+    /** deposit_session.addresses_created */
+    onAddressesReady?: (addresses: DepositAddress[]) => void;
+    /** direct_execution.detected */
+    onExecutionDetected?: (execution: DirectExecution) => void;
+    /** direct_execution.updated */
+    onExecutionUpdated?: (execution: DirectExecution & {
+        previousStatus: ExecutionStatus | null;
+    }) => void;
+    /** direct_execution.succeeded */
+    onSuccess?: (execution: DirectExecution) => void;
+    /** direct_execution.failed + deposit_session.errored */
+    onError?: (error: DepositSessionError) => void;
+    /** Fired whenever snapshot.status changes. */
+    onStatusChange?: (status: DepositSessionStatus) => void;
+}
+interface UseDepositResult {
+    status: DepositSessionStatus;
+    /** Deposit addresses (one per chain type); empty until created. */
+    addresses: DepositAddress[];
+    /**
+     * Convenience: the deposit address matching the query. Takes an options
+     * object so future selectors (e.g. `addressType` when a chain type exposes
+     * multiple address formats) can be added without a breaking change.
+     */
+    getAddress: (query: {
+        chainType: ChainType;
+    }) => DepositAddress | undefined;
+    /** All executions observed this session, newest first. */
+    executions: DirectExecution[];
+    latestExecution: DirectExecution | null;
+    /** True while the backend is actively checking for the deposit (scan nudge armed). */
+    isCheckingDeposit: boolean;
+    error: DepositSessionError | null;
+    /** Start the session (relevant when autoStart: false, or to retry after error). */
+    start: () => Promise<void>;
+    /** Arm the backend scan nudge in 'manual' mode ("I've sent it" button). */
+    confirmFundsSent: () => void;
+    /** Stop all polling. */
+    stop: () => void;
+    /** stop() + fresh baseline + start(). */
+    restart: () => Promise<void>;
+    /** Escape hatch to the underlying session (e.g. extra event subscriptions). */
+    session: DepositSession | null;
+}
+/**
+ * Flagship headless deposit hook — the no-UI equivalent of
+ * `beginDeposit({ initialScreen: 'transfer' })`.
+ *
+ * Wraps a core {@link DepositSession}: creates it, subscribes via
+ * `useSyncExternalStore`, destroys it on unmount, and exposes the snapshot,
+ * imperative controls, and callback sugar. The host renders 100% of the UI.
+ *
+ * SSR-safe: the session is constructed in an effect; server renders see
+ * `status: 'idle'` and empty arrays.
+ */
+declare function useDeposit(options: UseDepositOptions): UseDepositResult;
+
+interface UseDepositAddressesOptions {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string | undefined;
+    destination?: {
+        chainType?: ChainType;
+        chainId?: string;
+        tokenAddress?: string;
+        recipientAddress?: string;
+        contractCalls?: EvmContractCall[];
+    };
+    /** Action type for the deposit address. @default server default ('deposit') */
+    actionType?: ActionType;
+    /** Whether the query should execute. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Fetch/create the user's deposit addresses with react-query caching.
+ *
+ * `POST /v1/public/deposit_addresses` is idempotent, so this is safe to cache
+ * (1h stale). For hosts that want addresses without a live deposit session
+ * (e.g. pre-rendering a receive screen). Shares its cache key with the modal
+ * SDK's internal hook, so mixing surfaces never double-fetches.
+ */
+declare function useDepositAddresses(options: UseDepositAddressesOptions): _tanstack_react_query.UseQueryResult<DepositAddress[], Error>;
+
+interface UseSupportedDepositTokensOptions {
+    /** All three destination fields must be provided together to filter. */
+    destination?: {
+        chainType: string;
+        chainId: string;
+        tokenAddress: string;
+    };
+    productType?: ProductType;
+    /** Whether the query should execute. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Source tokens/chains a user can deposit from — for building custom
+ * token/chain pickers. Cached 5 minutes; deduped with the modal SDK.
+ */
+declare function useSupportedDepositTokens(options?: UseSupportedDepositTokensOptions): _tanstack_react_query.UseQueryResult<SupportedToken[], Error>;
+
+interface UseExecutionsOptions {
+    /** Host platform's stable user identifier (maps to external_user_id). */
+    externalUserId: string | undefined;
+    /**
+     * Polling interval in milliseconds; `false` (default) disables polling.
+     * Deposit detection should use `useDeposit` — this hook is for
+     * history/tracker screens.
+     */
+    refetchInterval?: number | false;
+    /** Whether the query should execute. Defaults to true. */
+    enabled?: boolean;
+    /** Filter by action type. Defaults to Deposit. */
+    actionType?: ActionType;
+}
+/**
+ * The user's executions (deposit history), mapped to camelCase
+ * {@link DirectExecution}. Shares its cache key with the modal SDK's tracker.
+ */
+declare function useExecutions(options: UseExecutionsOptions): _tanstack_react_query.UseQueryResult<DirectExecution[], Error>;
+
+interface AllowedCountryResult {
+    /** Whether the user is in an allowed country/subdivision. null while loading. */
+    isAllowed: boolean | null;
+    /** ISO 3166-1 alpha-2 country code (e.g. "US", "PT") */
+    alpha2: string | null;
+    /** Full country name (e.g. "United States") */
+    country: string | null;
+    /** ISO 3166-2 subdivision code (e.g. "NY"), null if unavailable */
+    subdivisionCode: string | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Whether the current user's region is allowed by the project's blocked
+ * countries configuration — the same geo gate the modal runs before showing
+ * deposit rails.
+ *
+ * The headless SDK is deliberately not IP-aware: `useDeposit` never runs this
+ * check. Hosts that want the modal's geo behavior opt in by rendering
+ * against this hook (and gating their deposit UI on `isAllowed`).
+ */
+declare function useAllowedCountry(): AllowedCountryResult;
+
+interface UseAddressValidationOptions {
+    /** Address that will receive the deposited funds. */
+    recipientAddress?: string;
+    destination?: {
+        chainType: ChainType;
+        chainId: string;
+        tokenAddress: string;
+    };
+    /** Whether to run validation. Defaults to true. */
+    enabled?: boolean;
+}
+interface AddressValidationResult {
+    /** Whether the address can receive funds. null while loading or when params are incomplete. */
+    isValid: boolean | null;
+    /** Standardized error code for i18n. */
+    failureCode: AddressValidationFailureCode | null;
+    /** Metadata for message interpolation. */
+    metadata: {
+        chain_name?: string;
+        token_symbol?: string;
+    } | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Validate that a recipient address can receive funds for a destination
+ * (primarily Algorand asset opt-in; typically valid=true elsewhere).
+ * `useDeposit` already fails fast on invalid recipients; use this hook for
+ * inline form validation before starting a session.
+ */
+declare function useAddressValidation(options: UseAddressValidationOptions): AddressValidationResult;
+
+export { type AddressValidationResult, type AllowedCountryResult, type UseAddressValidationOptions, type UseDepositAddressesOptions, type UseDepositDestination, type UseDepositOptions, type UseDepositResult, type UseExecutionsOptions, type UseSupportedDepositTokensOptions, useAddressValidation, useAllowedCountry, useDeposit, useDepositAddresses, useExecutions, useSupportedDepositTokens, useUnifoldClient };