@unifold/headless-react 0.1.70-beta.1 → 0.1.71-beta.1

package/README.md

@@ -71,13 +71,21 @@ function DepositUSDC({ externalUserId }: { externalUserId: string }) {
 }
 ```
 
-`useDeposit` drives an explicit status state machine:
+`useDeposit` drives an explicit **lifecycle** state machine:
 
 ```
-idle → creating_addresses → awaiting_funds → processing → succeeded | failed
+idle → creating_addresses → ready ⇄ processing
                           ↘ error (fatal: address creation / invalid recipient)
 ```
 
+`processing` is a live hint — “an execution is currently in flight” — and
+toggles back to `ready` when everything settles. **Outcomes never
+appear on the session status**: a session is an ongoing watcher that can
+observe many executions, so a session-level "succeeded"/"failed" would
+mislead the moment a second deposit arrives. Read outcomes from
+`executions`/`latestExecution` statuses, the `direct_execution.succeeded` /
+`.failed` events, or `waitForSuccess()`.
+
 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`.
@@ -108,9 +116,9 @@ 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
+// Generic primitive over the lifecycle state machine:
+await session.waitForStatus('processing');       // live activity detected
+await session.waitForStatus('ready');   // addresses ready / all settled
 
 // The 90% case — mirrors beginDeposit()'s promise contract
 // (resolve on success, reject on failure):

package/dist/index.js

@@ -77,6 +77,8 @@ function useDeposit(options) {
   (0, import_react2.useEffect)(() => {
     callbacksRef.current = options;
   });
+  const autoStartRef = (0, import_react2.useRef)(autoStart);
+  autoStartRef.current = autoStart;
   const [session, setSession] = (0, import_react2.useState)(null);
   const sessionKey = [
     publishableKey,
@@ -143,7 +145,7 @@ function useDeposit(options) {
       }
     });
     setSession(nextSession);
-    if (autoStart) {
+    if (autoStartRef.current) {
       void nextSession.start();
     }
     return () => {
@@ -151,7 +153,7 @@ function useDeposit(options) {
       offStatus();
       nextSession.destroy();
     };
-  }, [sessionKey, autoStart]);
+  }, [sessionKey]);
   const subscribe = (0, import_react2.useCallback)(
     (listener) => session ? session.subscribe(listener) : () => {
     },
@@ -226,7 +228,9 @@ function useDepositAddresses(options) {
       publishableKey
     ),
     select: (response) => response.data.map(import_core3.mapWalletToDepositAddress),
-    enabled: enabled && !!externalUserId && !!publishableKey,
+    // When a destination is supplied it must be complete — never issue a
+    // create call with a partially-filled destination.
+    enabled: enabled && !!externalUserId && !!publishableKey && (!destination || !!destination.chainType && !!destination.chainId && !!destination.tokenAddress && !!destination.recipientAddress),
     staleTime: 1e3 * 60 * 60,
     // 1 hour — wallets don't change once created
     gcTime: 1e3 * 60 * 60 * 24,
@@ -244,11 +248,12 @@ var import_react_provider4 = require("@unifold/react-provider");
 function useSupportedDepositTokens(options = {}) {
   const { publishableKey } = (0, import_react_provider4.useUnifold)();
   const { destination, productType, enabled = true } = options;
-  const apiOptions = destination || productType ? {
-    ...destination ? {
-      destination_token_address: destination.tokenAddress,
-      destination_chain_id: destination.chainId,
-      destination_chain_type: destination.chainType
+  const completeDestination = destination?.chainType && destination?.chainId && destination?.tokenAddress ? destination : void 0;
+  const apiOptions = completeDestination || productType ? {
+    ...completeDestination ? {
+      destination_token_address: completeDestination.tokenAddress,
+      destination_chain_id: completeDestination.chainId,
+      destination_chain_type: completeDestination.chainType
     } : {},
     ...productType ? { product_type: productType } : {}
   } : void 0;
@@ -279,7 +284,12 @@ var import_core5 = require("@unifold/core");
 var import_react_provider5 = require("@unifold/react-provider");
 function useExecutions(options) {
   const { publishableKey } = (0, import_react_provider5.useUnifold)();
-  const { externalUserId, refetchInterval = false, enabled = true, actionType = import_core5.ActionType.Deposit } = options;
+  const {
+    externalUserId,
+    refetchInterval = false,
+    enabled = true,
+    actionType = import_core5.ActionType.Deposit
+  } = options;
   return (0, import_react_query3.useQuery)({
     // Key parity with @unifold/ui-react's useExecutions.
     queryKey: ["unifold", "executions", actionType, externalUserId, publishableKey],
@@ -358,7 +368,8 @@ var import_react_provider7 = require("@unifold/react-provider");
 function useAddressValidation(options) {
   const { publishableKey } = (0, import_react_provider7.useUnifold)();
   const { recipientAddress, destination, enabled = true } = options;
-  const shouldValidate = enabled && !!publishableKey && !!recipientAddress && !!destination;
+  const hasCompleteDestination = !!destination?.chainType && !!destination?.chainId && !!destination?.tokenAddress;
+  const shouldValidate = enabled && !!publishableKey && !!recipientAddress && hasCompleteDestination;
   const { data, isLoading, error } = (0, import_react_query5.useQuery)({
     // Key parity with @unifold/ui-react's useAddressValidation.
     queryKey: [
@@ -379,11 +390,15 @@ function useAddressValidation(options) {
       publishableKey
     ),
     enabled: shouldValidate,
-    refetchOnMount: false,
-    refetchOnReconnect: false,
+    // Address validity is EXTERNAL state that can flip without the query key
+    // changing (e.g. an Algorand recipient opts in to the asset). Always
+    // revalidate on mount and never serve a stale verdict — otherwise a user
+    // who fixes the problem still sees "invalid" until a cache window expires.
+    refetchOnMount: "always",
+    refetchOnReconnect: true,
     refetchOnWindowFocus: false,
-    staleTime: 1e3 * 60 * 5,
-    gcTime: 1e3 * 60 * 30
+    staleTime: 0,
+    gcTime: 1e3 * 60 * 5
   });
   if (!shouldValidate) {
     return { isValid: null, failureCode: null, metadata: null, isLoading: false, error: null };

package/dist/index.mjs

@@ -41,6 +41,8 @@ function useDeposit(options) {
   useEffect(() => {
     callbacksRef.current = options;
   });
+  const autoStartRef = useRef(autoStart);
+  autoStartRef.current = autoStart;
   const [session, setSession] = useState(null);
   const sessionKey = [
     publishableKey,
@@ -107,7 +109,7 @@ function useDeposit(options) {
       }
     });
     setSession(nextSession);
-    if (autoStart) {
+    if (autoStartRef.current) {
       void nextSession.start();
     }
     return () => {
@@ -115,7 +117,7 @@ function useDeposit(options) {
       offStatus();
       nextSession.destroy();
     };
-  }, [sessionKey, autoStart]);
+  }, [sessionKey]);
   const subscribe = useCallback(
     (listener) => session ? session.subscribe(listener) : () => {
     },
@@ -193,7 +195,9 @@ function useDepositAddresses(options) {
       publishableKey
     ),
     select: (response) => response.data.map(mapWalletToDepositAddress),
-    enabled: enabled && !!externalUserId && !!publishableKey,
+    // When a destination is supplied it must be complete — never issue a
+    // create call with a partially-filled destination.
+    enabled: enabled && !!externalUserId && !!publishableKey && (!destination || !!destination.chainType && !!destination.chainId && !!destination.tokenAddress && !!destination.recipientAddress),
     staleTime: 1e3 * 60 * 60,
     // 1 hour — wallets don't change once created
     gcTime: 1e3 * 60 * 60 * 24,
@@ -213,11 +217,12 @@ import { useUnifold as useUnifold4 } from "@unifold/react-provider";
 function useSupportedDepositTokens(options = {}) {
   const { publishableKey } = useUnifold4();
   const { destination, productType, enabled = true } = options;
-  const apiOptions = destination || productType ? {
-    ...destination ? {
-      destination_token_address: destination.tokenAddress,
-      destination_chain_id: destination.chainId,
-      destination_chain_type: destination.chainType
+  const completeDestination = destination?.chainType && destination?.chainId && destination?.tokenAddress ? destination : void 0;
+  const apiOptions = completeDestination || productType ? {
+    ...completeDestination ? {
+      destination_token_address: completeDestination.tokenAddress,
+      destination_chain_id: completeDestination.chainId,
+      destination_chain_type: completeDestination.chainType
     } : {},
     ...productType ? { product_type: productType } : {}
   } : void 0;
@@ -252,7 +257,12 @@ import {
 import { useUnifold as useUnifold5 } from "@unifold/react-provider";
 function useExecutions(options) {
   const { publishableKey } = useUnifold5();
-  const { externalUserId, refetchInterval = false, enabled = true, actionType = ActionType.Deposit } = options;
+  const {
+    externalUserId,
+    refetchInterval = false,
+    enabled = true,
+    actionType = ActionType.Deposit
+  } = options;
   return useQuery3({
     // Key parity with @unifold/ui-react's useExecutions.
     queryKey: ["unifold", "executions", actionType, externalUserId, publishableKey],
@@ -333,7 +343,8 @@ import { useUnifold as useUnifold7 } from "@unifold/react-provider";
 function useAddressValidation(options) {
   const { publishableKey } = useUnifold7();
   const { recipientAddress, destination, enabled = true } = options;
-  const shouldValidate = enabled && !!publishableKey && !!recipientAddress && !!destination;
+  const hasCompleteDestination = !!destination?.chainType && !!destination?.chainId && !!destination?.tokenAddress;
+  const shouldValidate = enabled && !!publishableKey && !!recipientAddress && hasCompleteDestination;
   const { data, isLoading, error } = useQuery5({
     // Key parity with @unifold/ui-react's useAddressValidation.
     queryKey: [
@@ -354,11 +365,15 @@ function useAddressValidation(options) {
       publishableKey
     ),
     enabled: shouldValidate,
-    refetchOnMount: false,
-    refetchOnReconnect: false,
+    // Address validity is EXTERNAL state that can flip without the query key
+    // changing (e.g. an Algorand recipient opts in to the asset). Always
+    // revalidate on mount and never serve a stale verdict — otherwise a user
+    // who fixes the problem still sees "invalid" until a cache window expires.
+    refetchOnMount: "always",
+    refetchOnReconnect: true,
     refetchOnWindowFocus: false,
-    staleTime: 1e3 * 60 * 5,
-    gcTime: 1e3 * 60 * 30
+    staleTime: 0,
+    gcTime: 1e3 * 60 * 5
   });
   if (!shouldValidate) {
     return { isValid: null, failureCode: null, metadata: null, isLoading: false, error: null };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifold/headless-react",
-  "version": "0.1.70-beta.1",
+  "version": "0.1.71-beta.1",
   "description": "Unifold Headless React SDK - hooks-only (no UI) crypto deposit flows",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@tanstack/react-query": "^5.90.11",
-    "@unifold/core": "0.1.70-beta.1",
-    "@unifold/react-provider": "0.1.70-beta.1"
+    "@unifold/core": "0.1.71-beta.1",
+    "@unifold/react-provider": "0.1.71-beta.1"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",