@agg-build/hooks 4.26.1 → 4.27.3

package/dist/index-CsP1jRMD.d.ts

@@ -0,0 +1,341 @@
+import "./index-D0fXU85a.js";
+import { WithdrawPreviewResponse, WsWithdrawalLifecycleLeg, WsWithdrawalLifecycleStatus } from "@agg-build/sdk";
+//#region src/execution/use-managed-balances.d.ts
+interface UseManagedBalancesOptions {
+  enabled?: boolean;
+  mode?: "live" | "paper";
+  /**
+   * `"self"` fetches the balances of the wallets linked to this account rather
+   * than the managed wallet. Its own query key, so both can be held at once.
+   */
+  custody?: "managed" | "self";
+}
+/**
+ * Query hook for fetching unified managed wallet balances across all chains.
+ */
+declare function useManagedBalances(options?: UseManagedBalancesOptions): {
+  balances: import("@agg-build/sdk").UnifiedBalanceResponse | undefined;
+  data: import("@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?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@agg-build/sdk").UnifiedBalanceResponse, Error>>;
+  fetchStatus: import("@tanstack/react-query").FetchStatus;
+  promise: Promise<import("@agg-build/sdk").UnifiedBalanceResponse>;
+} | {
+  balances: import("@agg-build/sdk").UnifiedBalanceResponse | undefined;
+  data: import("@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?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@agg-build/sdk").UnifiedBalanceResponse, Error>>;
+  fetchStatus: import("@tanstack/react-query").FetchStatus;
+  promise: Promise<import("@agg-build/sdk").UnifiedBalanceResponse>;
+} | {
+  balances: import("@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?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@agg-build/sdk").UnifiedBalanceResponse, Error>>;
+  fetchStatus: import("@tanstack/react-query").FetchStatus;
+  promise: Promise<import("@agg-build/sdk").UnifiedBalanceResponse>;
+} | {
+  balances: import("@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?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@agg-build/sdk").UnifiedBalanceResponse, Error>>;
+  fetchStatus: import("@tanstack/react-query").FetchStatus;
+  promise: Promise<import("@agg-build/sdk").UnifiedBalanceResponse>;
+} | {
+  balances: import("@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?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@agg-build/sdk").UnifiedBalanceResponse, Error>>;
+  fetchStatus: import("@tanstack/react-query").FetchStatus;
+  promise: Promise<import("@agg-build/sdk").UnifiedBalanceResponse>;
+} | {
+  balances: import("@agg-build/sdk").UnifiedBalanceResponse | undefined;
+  data: import("@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?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@agg-build/sdk").UnifiedBalanceResponse, Error>>;
+  fetchStatus: import("@tanstack/react-query").FetchStatus;
+  promise: Promise<import("@agg-build/sdk").UnifiedBalanceResponse>;
+};
+//#endregion
+//#region src/withdraw/use-withdraw-flow.d.ts
+type WithdrawSelectOption = {
+  value: string;
+  label: string;
+  disabled?: boolean;
+};
+type WithdrawSummary = {
+  /**
+   * The amount the user submitted for withdrawal — NOT a confirmed payout
+   * figure. A preflight quote can still fail or settle partially later, so
+   * labeling this "received" was misleading.
+   */
+  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;
+    /**
+     * True when the user clicked Max — the backend should apply its own cap
+     * rather than rejecting an over-balance request. Reset to false when the
+     * user manually edits the amount field afterward.
+     */
+    isMax: boolean;
+  };
+  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;
+//#endregion
+//#region src/withdraw/use-withdraw-estimate.d.ts
+interface WithdrawFeeEstimate {
+  estimatedFees: string;
+  networkReserve: string;
+  youReceive: string;
+}
+interface UseWithdrawEstimateParams {
+  amount: string;
+  selectedToken: string;
+  selectedNetwork: string;
+}
+/**
+ * Natively estimates withdrawal fees, network reserves, and the expected net
+ * amount to be received based on the selected token, destination network,
+ * and transfer amount.
+ */
+declare function useWithdrawEstimate({ amount, selectedToken, selectedNetwork }: UseWithdrawEstimateParams): WithdrawFeeEstimate | null;
+//#endregion
+//#region src/withdraw/use-withdrawal-lifecycle.d.ts
+/**
+ * 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;
+  /** Requested withdrawal amount in destination-token native decimals. */
+  requestedAmountRaw: string | null;
+  /** Terminal settled amount in destination-token native decimals. */
+  completedAmountRaw: string | null;
+  /** Realized platform fee in destination-token native decimals. Only present on terminal events; null until then. */
+  feeRaw: string | 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;
+//#endregion
+//#region src/withdraw/use-withdraw-preview.d.ts
+interface UseWithdrawPreviewParams {
+  amountRaw: string | null;
+  tokenSymbol: string | null;
+  destinationChainId: number | null;
+  destinationAddress: string | null;
+  /**
+   * When `true`, the backend caps the withdrawal to the maximum deliverable amount.
+   * Included in the query key so max vs non-max are distinct cache entries.
+   */
+  max?: boolean;
+}
+/**
+ * Live withdrawal preview backed by the API (`POST /execution/withdraw/preview`).
+ * Disabled until amount/token/chain/address are present and amount is non-zero.
+ * The backend caches identical previews for 15s; FE debounce keeps Relay calls
+ * bounded. Returns the real fee + receive amount, replacing the hardcoded
+ * `useWithdrawEstimate`.
+ */
+declare function useWithdrawPreview({ amountRaw, tokenSymbol, destinationChainId, destinationAddress, max }: UseWithdrawPreviewParams): import("@tanstack/react-query").UseQueryResult<WithdrawPreviewResponse, Error>;
+//#endregion
+export { useWithdrawalLifecycle as a, useWithdrawEstimate as c, useWithdrawFlow as d, UseManagedBalancesOptions as f, WithdrawalLifecycleState as i, UseWithdrawFlowOptions as l, useWithdrawPreview as n, UseWithdrawEstimateParams as o, useManagedBalances as p, UseWithdrawalLifecycleResult as r, WithdrawFeeEstimate as s, UseWithdrawPreviewParams as t, UseWithdrawFlowResult as u };
+//# sourceMappingURL=index-CsP1jRMD.d.ts.map

package/dist/index-CsP1jRMD.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CsP1jRMD.d.ts","names":[],"sources":["../src/execution/use-managed-balances.ts","../src/withdraw/use-withdraw-flow.ts","../src/withdraw/use-withdraw-estimate.ts","../src/withdraw/use-withdrawal-lifecycle.ts","../src/withdraw/use-withdraw-preview.ts"],"mappings":";;;UAIiB;EACf;EACA;;;;;EAKA;;;;;iBAMc,mBAAmB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KCNxC;EAAyB;EAAe;EAAe;;KAKvD;;;;;;EAMH;EACA;EACA;EACA;;UAkDe;EACf;EACA,eAAe;EACf;IACE;IACA;IACA;IACA;IACA,cAAc;IACd,gBAAgB;IAChB;IACA;IACA,iBAAiB;;;;;;;IAOjB;;;;;;IAMA;;EAEF,8BAA8B;EAC9B,yBAAyB;EACzB,wBAAwB;EACxB,0BAA0B;EAC1B;EACA,2BAA2B,uBAAuB;EAClD;;UAGe;EACf;EACA,eAAe;;iBAoDD,gBAAgB,SAAS,yBAAyB;;;UCnKjD;EACf;EACA;EACA;;UAGe;EACf;EACA;EACA;;;;;;;iBAQc,sBACd,QACA,eACA,mBACC,4BAA4B;;;;;;;;;;;;UCGd;;EAEf;;EAEA,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;EAEA,SAAS;;EAET,MAAM;;EAEN;;EAEA;;UA4Fe;;EAEf,OAAO;;EAEP;;;;;;;;;;;;;;;;;;;iBAoBc,uBAAuB,8BAA8B;;;UC9JpD;EACf;EACA;EACA;EACA;;;;;EAKA;;;;;;;;;iBAUc,qBACd,WACA,aACA,oBACA,oBACA,OACC,2DAAwB,eAAA,yBAAA"}