@agg-build/hooks 1.0.0 → 1.0.1

package/dist/withdraw.d.ts

@@ -0,0 +1,293 @@
+import * as _agg_build_sdk from '@agg-build/sdk';
+import { WsWithdrawalLifecycleStatus, WsWithdrawalLifecycleLeg, WithdrawManagedResponse, WithdrawManagedParams } from '@agg-build/sdk';
+import * as _tanstack_react_query from '@tanstack/react-query';
+export { U as UseDepositAddressesOptions, u as useDepositAddresses } from './use-deposit-addresses-B9ICS-3U.js';
+
+type WithdrawSelectOption = {
+    value: string;
+    label: string;
+};
+type WithdrawSummary = {
+    /**
+     * The amount the user submitted for withdrawal — NOT a confirmed payout
+     * figure. The API today returns `pricingStatus: "unquoted"` with no fee
+     * or net-output guarantee, so labeling this "received" was misleading.
+     * The label string is "Amount" until the multi-stable quote layer ships.
+     */
+    amountReceived: string;
+    network: string;
+    toWallet: string;
+    fees: string;
+};
+interface UseWithdrawFlowResult {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    withdrawFlow: {
+        balance: number;
+        balanceDisplay: string;
+        amount: string;
+        destinationWallet: string;
+        tokenOptions: WithdrawSelectOption[];
+        networkOptions: WithdrawSelectOption[];
+        selectedToken: string;
+        selectedNetwork: string;
+        purchaseSummary: WithdrawSummary;
+        /**
+         * The id returned by `POST /execution/withdraw-managed` once the user
+         * has submitted the flow — used by the success step to subscribe to
+         * `withdrawal_lifecycle` WS events. `null` until submission succeeds
+         * and reset to `null` when the modal closes.
+         */
+        withdrawalId: string | null;
+    };
+    onWithdrawDestinationChange: (address: string) => void;
+    onWithdrawAmountChange: (amount: string) => void;
+    onWithdrawTokenChange: (token: string) => void;
+    onWithdrawNetworkChange: (network: string) => void;
+    onMaxClick: () => void;
+    onSelectWithdrawProvider: (providerId: string) => Promise<void>;
+    onDoneWithdraw: () => void;
+}
+interface UseWithdrawFlowOptions {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+declare function useWithdrawFlow(options: UseWithdrawFlowOptions): UseWithdrawFlowResult;
+
+/**
+ * Latest lifecycle snapshot for a single withdrawal, materialized from the
+ * most recent `WsWithdrawalLifecycleEvent` whose `withdrawalId` matches.
+ *
+ * The wire format is intentionally additive (legs may arrive partial), so
+ * `legs` reflects the latest snapshot the server emitted — earlier per-leg
+ * deltas are not re-merged on the client. Consumers should treat `legs` as
+ * "last known truth" rather than a derived rollup.
+ */
+interface WithdrawalLifecycleState {
+    /** True until the first lifecycle event for this withdrawal arrives. */
+    pending: boolean;
+    /** Top-level status, or `null` until the first event arrives. */
+    status: WsWithdrawalLifecycleStatus | null;
+    /** Whether `status` is a terminal state (`completed` / `partial` / `failed`). */
+    terminal: boolean;
+    /** Last leg delta (the leg whose flip triggered the most recent event). */
+    lastLeg: WsWithdrawalLifecycleLeg | null;
+    /** All legs at the moment of the most recent event (server snapshot). */
+    legs: WsWithdrawalLifecycleLeg[];
+    /** Failure reason for terminal `failed` / `partial`. */
+    errorMessage: string | null;
+    /** Server timestamp (ms) of the most recent event. */
+    timestamp: number | null;
+}
+interface UseWithdrawalLifecycleResult {
+    /** Latest lifecycle snapshot for the watched `withdrawalId`. */
+    state: WithdrawalLifecycleState;
+    /** Reset to the initial pre-event state — call when the modal is closed or a new flow starts. */
+    reset: () => void;
+}
+/**
+ * Subscribes to `withdrawal_lifecycle` WS events for a single `withdrawalId`
+ * and exposes the latest snapshot. Returns a stable `pending` initial state
+ * until the first matching event arrives.
+ *
+ * Pass `null` for `withdrawalId` to disable the subscription (e.g. before
+ * the user has submitted a withdrawal). Switching the `withdrawalId` resets
+ * the state so a stale snapshot from a prior withdrawal can never bleed
+ * across.
+ *
+ * **Backfill behavior**: on mount with a non-null `withdrawalId`, and again
+ * whenever the WS connection re-opens, the hook calls
+ * `GET /execution/withdrawals/:id` to recover any lifecycle events that fired
+ * before the listener was attached or while the socket was disconnected. WS
+ * events always win over REST snapshots (REST stamps as `timestamp: 0`), so a
+ * race between the two never regresses to a stale state.
+ */
+declare function useWithdrawalLifecycle(withdrawalId: string | null): UseWithdrawalLifecycleResult;
+
+interface UseWithdrawManagedOptions {
+    onSuccess?: (data: WithdrawManagedResponse) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Mutation hook for withdrawing funds from managed wallets.
+ * On success, invalidates balances queries.
+ */
+declare function useWithdrawManaged(options?: UseWithdrawManagedOptions): _tanstack_react_query.UseMutationResult<WithdrawManagedResponse, Error, WithdrawManagedParams, unknown>;
+
+interface UseManagedBalancesOptions {
+    enabled?: boolean;
+}
+/**
+ * Query hook for fetching unified managed wallet balances across all chains.
+ */
+declare function useManagedBalances(options?: UseManagedBalancesOptions): {
+    balances: _agg_build_sdk.UnifiedBalanceResponse | undefined;
+    data: _agg_build_sdk.UnifiedBalanceResponse;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_agg_build_sdk.UnifiedBalanceResponse, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<_agg_build_sdk.UnifiedBalanceResponse>;
+} | {
+    balances: _agg_build_sdk.UnifiedBalanceResponse | undefined;
+    data: _agg_build_sdk.UnifiedBalanceResponse;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_agg_build_sdk.UnifiedBalanceResponse, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<_agg_build_sdk.UnifiedBalanceResponse>;
+} | {
+    balances: _agg_build_sdk.UnifiedBalanceResponse | undefined;
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_agg_build_sdk.UnifiedBalanceResponse, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<_agg_build_sdk.UnifiedBalanceResponse>;
+} | {
+    balances: _agg_build_sdk.UnifiedBalanceResponse | undefined;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_agg_build_sdk.UnifiedBalanceResponse, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<_agg_build_sdk.UnifiedBalanceResponse>;
+} | {
+    balances: _agg_build_sdk.UnifiedBalanceResponse | undefined;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_agg_build_sdk.UnifiedBalanceResponse, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<_agg_build_sdk.UnifiedBalanceResponse>;
+} | {
+    balances: _agg_build_sdk.UnifiedBalanceResponse | undefined;
+    data: _agg_build_sdk.UnifiedBalanceResponse;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_agg_build_sdk.UnifiedBalanceResponse, Error>>;
+    fetchStatus: _tanstack_react_query.FetchStatus;
+    promise: Promise<_agg_build_sdk.UnifiedBalanceResponse>;
+};
+
+export { type UseManagedBalancesOptions, type UseWithdrawFlowOptions, type UseWithdrawFlowResult, type UseWithdrawManagedOptions, type UseWithdrawalLifecycleResult, type WithdrawalLifecycleState, useManagedBalances, useWithdrawFlow, useWithdrawManaged, useWithdrawalLifecycle };