@unifold/core 0.1.69 → 0.1.70

package/dist/index.mjs

@@ -1,3 +1,7 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
 // src/lib/utils.ts
 function formatStablecoinAmount(baseUnits, decimals) {
   const raw = Number(baseUnits) / 10 ** decimals;
@@ -94,6 +98,16 @@ var ActionType = /* @__PURE__ */ ((ActionType2) => {
   ActionType2["Withdraw"] = "withdraw";
   return ActionType2;
 })(ActionType || {});
+var DepositAddressValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    __publicField(this, "isDepositAddressValidationError", true);
+    this.name = "DepositAddressValidationError";
+  }
+};
+function isDepositAddressValidationError(error) {
+  return error instanceof Error && error.isDepositAddressValidationError === true;
+}
 async function createDepositAddress(overrides, publishableKey) {
   if (!overrides?.external_user_id) {
     throw new Error("external_user_id is required");
@@ -121,6 +135,13 @@ async function createDepositAddress(overrides, publishableKey) {
     body: JSON.stringify(payload)
   });
   if (!response.ok) {
+    if (response.status === 400) {
+      const body = await response.json().catch(() => null);
+      if (body?.error_type === "validation_error") {
+        const firstError = Array.isArray(body.details?.errors) ? body.details?.errors[0] : void 0;
+        throw new DepositAddressValidationError(firstError ?? "Invalid recipient address");
+      }
+    }
     throw new Error(`Failed to create EOA: ${response.statusText}`);
   }
   return response.json();
@@ -400,6 +421,9 @@ function getOnrampSessionStartUrl(request, publishableKey) {
   if (request.email) {
     params.append("email", request.email);
   }
+  if (request.payment_method_type) {
+    params.append("payment_method_type", request.payment_method_type);
+  }
   if (request.payment_method) {
     params.append("payment_method", request.payment_method);
   }
@@ -477,6 +501,21 @@ async function getProjectConfig(publishableKey, options) {
   const data = await response.json();
   return data;
 }
+async function getPublicIncident(publishableKey) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const response = await fetch(`${API_BASE_URL}/v1/public/projects/incident`, {
+    method: "GET",
+    headers: {
+      accept: "application/json",
+      "x-publishable-key": pk
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch public incident: ${response.statusText}`);
+  }
+  return response.json();
+}
 async function getIpAddress() {
   const response = await fetch(`${API_BASE_URL}/v1/public/ip_address`, {
     method: "GET",
@@ -532,7 +571,7 @@ async function getExternalWallets(publishableKey) {
   const data = await response.json();
   return data;
 }
-async function getWalletMobileDeepLink(wallet, depositAddresses, publishableKey) {
+async function getWalletMobileDeepLink(wallet, depositAddresses, publishableKey, amountUsd) {
   const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
   validatePublishableKey(pk);
   const response = await fetch(`${API_BASE_URL}/v1/public/external_wallets/mobile_deeplink`, {
@@ -542,7 +581,11 @@ async function getWalletMobileDeepLink(wallet, depositAddresses, publishableKey)
       accept: "application/json",
       "x-publishable-key": pk
     },
-    body: JSON.stringify({ wallet, deposit_addresses: depositAddresses })
+    body: JSON.stringify({
+      wallet,
+      deposit_addresses: depositAddresses,
+      ...amountUsd ? { amount_usd: amountUsd } : {}
+    })
   });
   if (!response.ok) {
     throw new Error(`Failed to generate wallet deep link: ${response.statusText}`);
@@ -587,6 +630,15 @@ async function verifyRecipientAddress(request, publishableKey) {
     body: JSON.stringify(request)
   });
   if (!response.ok) {
+    const body = await response.json().catch(() => null);
+    if (response.status === 400 && body?.error_type === "validation_error") {
+      const firstError = Array.isArray(body.details?.errors) ? body.details?.errors[0] : void 0;
+      return {
+        valid: false,
+        failure_code: "validation_error",
+        message: firstError ?? "Invalid recipient address"
+      };
+    }
     throw new Error(`Failed to verify recipient address: ${response.statusText}`);
   }
   return response.json();
@@ -1029,11 +1081,12 @@ async function stripeGetDefaultToken(params, publishableKey) {
 }
 var HEADLESS_STRIPE_BASE = "/v1/public/onramps/headless/stripe";
 var StripeApiResponseError = class extends Error {
-  constructor(message, statusCode, stripeCode, errorType) {
+  constructor(message, statusCode, stripeCode, errorType, stripeMessage) {
     super(message);
     this.statusCode = statusCode;
     this.stripeCode = stripeCode;
     this.errorType = errorType;
+    this.stripeMessage = stripeMessage;
     this.name = "StripeApiResponseError";
   }
 };
@@ -1044,7 +1097,8 @@ function throwStripeError(prefix, response, error) {
     `${prefix}: ${detailMessage}`,
     response.status,
     stripeError?.code,
-    error.error_type
+    error.error_type,
+    stripeError?.message
   );
 }
 async function stripeGetConfig(publishableKey) {
@@ -1536,6 +1590,825 @@ var CheckoutEventType = /* @__PURE__ */ ((CheckoutEventType2) => {
   return CheckoutEventType2;
 })(CheckoutEventType || {});
 
+// src/lib/emitter.ts
+var TypedEmitter = class {
+  constructor() {
+    __publicField(this, "handlers", /* @__PURE__ */ new Map());
+  }
+  on(type, handler) {
+    let set = this.handlers.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(type, set);
+    }
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+    };
+  }
+  emit(type, event) {
+    const dispatch = (handler) => {
+      try {
+        handler(event);
+      } catch (error) {
+        console.error("[unifold] event handler threw", error);
+      }
+    };
+    this.handlers.get(type)?.forEach(dispatch);
+    this.handlers.get("*")?.forEach(dispatch);
+  }
+  removeAllListeners() {
+    this.handlers.clear();
+  }
+};
+
+// src/lib/mappers.ts
+function mapWalletToDepositAddress(wallet) {
+  return {
+    id: wallet.id,
+    chainType: wallet.chain_type,
+    addressType: wallet.address_type,
+    address: wallet.address,
+    destinationChainType: wallet.destination_chain_type,
+    destinationChainId: wallet.destination_chain_id,
+    destinationTokenAddress: wallet.destination_token_address,
+    recipientAddress: wallet.recipient_address,
+    isPrimary: wallet.is_primary
+  };
+}
+function mapDirectExecution(execution) {
+  return {
+    id: execution.id,
+    transactionHash: execution.transaction_hash,
+    recipientAddress: execution.recipient_address,
+    depositAddress: execution.deposit_wallet?.address,
+    sourceChainType: execution.source_chain_type,
+    sourceChainId: execution.source_chain_id,
+    sourceTokenAddress: execution.source_token_address,
+    destinationChainType: execution.destination_chain_type,
+    destinationChainId: execution.destination_chain_id,
+    destinationTokenAddress: execution.destination_token_address,
+    sourceAmountBaseUnit: execution.source_amount_base_unit,
+    sourceAmountUsd: execution.source_amount_usd,
+    destinationAmountBaseUnit: execution.destination_amount_base_unit,
+    destinationAmountUsd: execution.destination_amount_usd,
+    destinationTransactionHashes: execution.destination_transaction_hashes,
+    status: execution.status,
+    failureReason: execution.failure_reason,
+    createdAt: execution.created_at,
+    updatedAt: execution.updated_at,
+    explorerUrl: execution.explorer_url,
+    destinationExplorerUrl: execution.destination_explorer_url,
+    sourceTokenMetadata: execution.source_token_metadata ? {
+      iconUrl: execution.source_token_metadata.icon_url,
+      iconUrls: execution.source_token_metadata.icon_urls,
+      decimals: execution.source_token_metadata.decimals
+    } : void 0,
+    destinationTokenMetadata: execution.destination_token_metadata ? {
+      iconUrl: execution.destination_token_metadata.icon_url,
+      iconUrls: execution.destination_token_metadata.icon_urls,
+      decimals: execution.destination_token_metadata.decimals
+    } : void 0
+  };
+}
+
+// src/lib/deposit-session.ts
+var DETECTION_POLL_INTERVAL_MS = 2500;
+var SCAN_NUDGE_INTERVAL_MS = 5e3;
+var DETECTION_ARM_DELAY_MS = 5e3;
+var LOOKBACK_MS = 6e4;
+var ADDRESS_CREATE_MAX_ATTEMPTS = 4;
+var DepositSessionEventType = /* @__PURE__ */ ((DepositSessionEventType2) => {
+  DepositSessionEventType2["SESSION_STARTED"] = "deposit_session.started";
+  DepositSessionEventType2["ADDRESSES_CREATED"] = "deposit_session.addresses_created";
+  DepositSessionEventType2["CONFIRMATION_STARTED"] = "deposit_session.confirmation_started";
+  DepositSessionEventType2["SESSION_STOPPED"] = "deposit_session.stopped";
+  DepositSessionEventType2["SESSION_ERRORED"] = "deposit_session.errored";
+  DepositSessionEventType2["EXECUTION_DETECTED"] = "direct_execution.detected";
+  DepositSessionEventType2["EXECUTION_UPDATED"] = "direct_execution.updated";
+  DepositSessionEventType2["EXECUTION_SUCCEEDED"] = "direct_execution.succeeded";
+  DepositSessionEventType2["EXECUTION_FAILED"] = "direct_execution.failed";
+  return DepositSessionEventType2;
+})(DepositSessionEventType || {});
+var IN_PROGRESS_STATUSES = [
+  "pending" /* PENDING */,
+  "waiting" /* WAITING */,
+  "delayed" /* DELAYED */
+];
+var FAILURE_STATUSES = ["failed" /* FAILED */, "refunded" /* REFUNDED */];
+var DepositSessionWaitError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    __publicField(this, "code");
+    /** Failed execution (`DEPOSIT_FAILED`) or fatal {@link DepositSessionError} (`SESSION_ERROR`). */
+    __publicField(this, "cause");
+    this.name = "DepositSessionWaitError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var SessionCheckError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+};
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var DepositSession = class {
+  constructor(config) {
+    /** Immutable id for correlation, `dsess_<ksuid>`. Client-generated. */
+    __publicField(this, "id");
+    __publicField(this, "emitter", new TypedEmitter());
+    __publicField(this, "listeners", /* @__PURE__ */ new Set());
+    __publicField(this, "publishableKey");
+    __publicField(this, "externalUserId");
+    __publicField(this, "destination");
+    __publicField(this, "confirmationMode");
+    __publicField(this, "method");
+    // Run state. runToken invalidates in-flight async work across stop()/restart.
+    __publicField(this, "runToken", 0);
+    __publicField(this, "startPromise", null);
+    __publicField(this, "destroyed", false);
+    /** Pending waiter rejections, invoked by destroy() so waiters never hang. */
+    __publicField(this, "waiterDestroyCallbacks", /* @__PURE__ */ new Set());
+    __publicField(this, "baselineMs", 0);
+    __publicField(this, "tracked", /* @__PURE__ */ new Map());
+    __publicField(this, "pollErrorLatched", false);
+    __publicField(this, "pollInFlight", false);
+    /** First execution to succeed this run — waitForSuccess's one-shot answer. */
+    __publicField(this, "firstSuccess", null);
+    __publicField(this, "detectionTimer", null);
+    __publicField(this, "nudgeTimer", null);
+    __publicField(this, "armTimer", null);
+    // Snapshot state
+    __publicField(this, "status", "idle");
+    __publicField(this, "addresses", []);
+    __publicField(this, "addressIds", []);
+    __publicField(this, "executions", []);
+    __publicField(this, "checkingDeposit", false);
+    __publicField(this, "error", null);
+    __publicField(this, "snapshot");
+    if (!config.publishableKey || config.publishableKey.trim() === "") {
+      throw new Error("DepositSession: publishableKey is required");
+    }
+    if (!config.externalUserId) {
+      throw new Error("DepositSession: externalUserId is required");
+    }
+    this.id = generatePrefixedKSUID("dsess");
+    this.publishableKey = config.publishableKey;
+    this.externalUserId = config.externalUserId;
+    this.destination = config.destination;
+    this.confirmationMode = config.confirmationMode ?? "auto";
+    this.method = config.method ?? "transfer";
+    this.snapshot = this.buildSnapshot();
+  }
+  // -- Public surface -------------------------------------------------------
+  /** Synchronous snapshot; the reference is stable until state changes. */
+  getSnapshot() {
+    return this.snapshot;
+  }
+  /**
+   * Subscribe to snapshot changes (external-store contract; drives
+   * `useSyncExternalStore` in the React binding). Returns an unsubscribe fn.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  on(type, handler) {
+    return this.emitter.on(type, handler);
+  }
+  /**
+   * Creates/fetches addresses (with a fail-fast recipient check) and starts
+   * detection polling. Idempotent while running; callable again after stop()
+   * or a fatal error (fresh baseline).
+   */
+  start() {
+    if (this.destroyed) {
+      return Promise.reject(new Error("DepositSession has been destroyed"));
+    }
+    if (this.startPromise) return this.startPromise;
+    this.startPromise = this.run();
+    return this.startPromise;
+  }
+  /** Arms the backend scan nudge in 'manual' mode. No-op if already armed. */
+  confirmFundsSent() {
+    if (this.destroyed || !this.startPromise) return;
+    this.armConfirmation("manual");
+  }
+  /**
+   * Stops all polling. The session can be restarted with start(), which
+   * resets the baseline and tracked executions (fresh run).
+   */
+  stop() {
+    const wasActive = this.startPromise !== null;
+    this.runToken += 1;
+    this.clearTimers();
+    this.startPromise = null;
+    this.checkingDeposit = false;
+    if (this.status !== "idle" && this.status !== "error") {
+      this.setStatus("idle");
+    }
+    if (wasActive && !this.destroyed) {
+      this.commit();
+      this.emitSessionEvent("deposit_session.stopped" /* SESSION_STOPPED */, {
+        sessionId: this.id
+      });
+      this.notify();
+    }
+  }
+  /** stop() + release all listeners. Terminal — start() rejects afterwards. */
+  destroy() {
+    this.stop();
+    this.destroyed = true;
+    Array.from(this.waiterDestroyCallbacks).forEach((callback) => callback());
+    this.waiterDestroyCallbacks.clear();
+    this.emitter.removeAllListeners();
+    this.listeners.clear();
+  }
+  // -- Promise waiters (subscription sugar over the event stream) ------------
+  /**
+   * Resolve when the session reaches one of the given statuses (immediately
+   * if it's already there). Generic primitive over the lifecycle state
+   * machine — e.g. `waitForStatus('processing')` awaits detection of live
+   * activity, `waitForStatus('ready')` awaits readiness. Statuses
+   * carry no outcomes; await those with {@link waitForSuccess} or the
+   * `direct_execution.*` events.
+   *
+   * Rejects with {@link DepositSessionWaitError} on abort or destroy().
+   * Does not start or stop the session — it only listens.
+   */
+  waitForStatus(status, options = {}) {
+    const statuses = Array.isArray(status) ? status : [status];
+    return new Promise((resolve, reject) => {
+      this.installWaiter({
+        options,
+        reject,
+        subscribe: (settle) => {
+          const check = () => {
+            if (statuses.includes(this.snapshot.status)) settle(() => resolve(this.snapshot));
+          };
+          check();
+          return this.subscribe(check);
+        }
+      });
+    });
+  }
+  /**
+   * Resolve with the **first** succeeded {@link DirectExecution} observed by
+   * this session — the one-liner for the 90% case. Mirrors `beginDeposit()`'s
+   * promise contract: resolve on success, reject on failure.
+   *
+   * Multi-execution semantics (unlike quote-scoped models such as Privy's,
+   * one session can observe many executions — a user may send twice, or on
+   * two chains): this waiter is one-shot "first completion" detection. If an
+   * execution has already succeeded this run, it resolves immediately with
+   * the FIRST one that did (not the newest). The session keeps polling after
+   * success — to react to every settlement, subscribe to
+   * `direct_execution.succeeded` events or read `snapshot.executions`.
+   *
+   * Rejects with {@link DepositSessionWaitError}:
+   * - `DEPOSIT_FAILED` (cause: the failed execution) when a deposit fails and
+   *   NO other observed execution is still in flight — a failure while
+   *   another deposit is pending keeps waiting (that one may still succeed),
+   * - `SESSION_ERROR` (cause: the fatal {@link DepositSessionError}) on fatal
+   *   session errors (e.g. address creation failed),
+   * - `ABORTED` / `DESTROYED` per the wait options and session lifecycle.
+   */
+  waitForSuccess(options = {}) {
+    return new Promise((resolve, reject) => {
+      this.installWaiter({
+        options,
+        reject,
+        subscribe: (settle) => {
+          const rejectFailure = (failed) => settle(
+            () => reject(new DepositSessionWaitError("DEPOSIT_FAILED", "Deposit failed", failed))
+          );
+          const { executions, error } = this.snapshot;
+          if (this.firstSuccess) {
+            const first = this.firstSuccess;
+            settle(() => resolve(first));
+            return () => {
+            };
+          }
+          const alreadyFailed = executions.find(
+            (execution) => FAILURE_STATUSES.includes(execution.status)
+          );
+          if (alreadyFailed && !this.anyExecutionInFlight()) {
+            rejectFailure(alreadyFailed);
+            return () => {
+            };
+          }
+          if (error?.fatal) {
+            settle(
+              () => reject(new DepositSessionWaitError("SESSION_ERROR", error.message, error))
+            );
+            return () => {
+            };
+          }
+          const offs = [
+            this.on(
+              "direct_execution.succeeded" /* EXECUTION_SUCCEEDED */,
+              (event) => settle(() => resolve(event.data.object))
+            ),
+            this.on("direct_execution.failed" /* EXECUTION_FAILED */, (event) => {
+              if (this.anyExecutionInFlight()) return;
+              rejectFailure(event.data.object);
+            }),
+            // A previously-failed wait condition can become settleable when
+            // the last in-flight execution also fails (updated → failed is
+            // covered above; updated → refunded transitions re-check here).
+            this.on("direct_execution.updated" /* EXECUTION_UPDATED */, () => {
+              if (this.anyExecutionInFlight() || this.firstSuccess) return;
+              const failed = this.snapshot.executions.find(
+                (execution) => FAILURE_STATUSES.includes(execution.status)
+              );
+              if (failed) rejectFailure(failed);
+            }),
+            this.on("deposit_session.errored" /* SESSION_ERRORED */, (event) => {
+              if (!event.data.object.fatal) return;
+              settle(
+                () => reject(
+                  new DepositSessionWaitError(
+                    "SESSION_ERROR",
+                    event.data.object.message,
+                    event.data.object
+                  )
+                )
+              );
+            })
+          ];
+          return () => offs.forEach((off) => off());
+        }
+      });
+    });
+  }
+  /**
+   * Shared waiter plumbing: AbortSignal and destroy() rejection, with
+   * single-settlement and cleanup. `subscribe` installs the wait condition
+   * and returns its unsubscribe fn; it settles via `settle(fn)`.
+   */
+  installWaiter({
+    options,
+    reject,
+    subscribe
+  }) {
+    if (this.destroyed) {
+      reject(new DepositSessionWaitError("DESTROYED", "DepositSession has been destroyed"));
+      return;
+    }
+    if (options.signal?.aborted) {
+      reject(new DepositSessionWaitError("ABORTED", "Wait aborted", options.signal.reason));
+      return;
+    }
+    let settled = false;
+    let unsubscribe = null;
+    const cleanup = () => {
+      unsubscribe?.();
+      options.signal?.removeEventListener("abort", onAbort);
+      this.waiterDestroyCallbacks.delete(onDestroy);
+    };
+    const settle = (finish) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      finish();
+    };
+    const onAbort = () => settle(
+      () => reject(new DepositSessionWaitError("ABORTED", "Wait aborted", options.signal?.reason))
+    );
+    const onDestroy = () => settle(
+      () => reject(
+        new DepositSessionWaitError("DESTROYED", "DepositSession was destroyed while waiting")
+      )
+    );
+    this.waiterDestroyCallbacks.add(onDestroy);
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    unsubscribe = subscribe(settle);
+    if (settled) cleanup();
+  }
+  // -- Run lifecycle ---------------------------------------------------------
+  async run() {
+    const token = ++this.runToken;
+    this.baselineMs = Date.now();
+    this.tracked.clear();
+    this.pollErrorLatched = false;
+    this.executions = [];
+    this.firstSuccess = null;
+    this.error = null;
+    this.checkingDeposit = false;
+    this.addresses = [];
+    this.addressIds = [];
+    this.setStatus("creating_addresses");
+    this.commit();
+    this.emitSessionEvent("deposit_session.started" /* SESSION_STARTED */, {
+      sessionId: this.id
+    });
+    this.notify();
+    let wallets;
+    try {
+      [wallets] = await Promise.all([this.createAddressesWithRetry(token), this.runStartChecks()]);
+    } catch (cause) {
+      if (token !== this.runToken) return;
+      const isCheck = cause instanceof SessionCheckError;
+      this.failFatally(
+        isCheck ? cause.code : "ADDRESS_CREATION_FAILED",
+        isCheck ? cause.message : "Failed to create deposit addresses",
+        cause
+      );
+      return;
+    }
+    if (token !== this.runToken) return;
+    this.addresses = wallets.map(mapWalletToDepositAddress);
+    this.addressIds = wallets.map((w) => w.id).filter(Boolean);
+    this.setStatus("ready");
+    this.commit();
+    this.emitSessionEvent("deposit_session.addresses_created" /* ADDRESSES_CREATED */, {
+      sessionId: this.id,
+      addresses: this.addresses
+    });
+    this.notify();
+    if (token !== this.runToken) return;
+    this.startDetectionLoop(token);
+    if (this.confirmationMode === "auto") {
+      this.armTimer = setTimeout(() => {
+        if (token === this.runToken) this.armConfirmation("auto");
+      }, DETECTION_ARM_DELAY_MS);
+    }
+  }
+  failFatally(code, message, cause) {
+    this.clearTimers();
+    this.startPromise = null;
+    this.error = { code, message, fatal: true, cause };
+    this.setStatus("error");
+    this.commit();
+    this.emitSessionEvent("deposit_session.errored" /* SESSION_ERRORED */, {
+      sessionId: this.id,
+      code,
+      message,
+      fatal: true
+    });
+    this.notify();
+  }
+  async createAddressesWithRetry(token) {
+    let lastError;
+    for (let attempt = 0; attempt < ADDRESS_CREATE_MAX_ATTEMPTS; attempt++) {
+      if (attempt > 0) {
+        await delay(Math.min(1e3 * 2 ** (attempt - 1), 1e4));
+        if (token !== this.runToken) throw new Error("DepositSession stopped");
+      }
+      try {
+        const response = await createDepositAddress(
+          {
+            external_user_id: this.externalUserId,
+            destination_chain_type: this.destination.chainType,
+            destination_chain_id: this.destination.chainId,
+            destination_token_address: this.destination.tokenAddress,
+            recipient_address: this.destination.recipientAddress,
+            contract_calls: this.destination.contractCalls
+          },
+          this.publishableKey
+        );
+        return response.data;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Fail-fast recipient validation (e.g. Algorand asset opt-in). Fails open
+   * on network errors — the backend still enforces at execution time — but a
+   * definitive negative result is fatal.
+   *
+   * Deliberately NOT IP/geo-aware: generating deposit addresses headless
+   * carries no region gate. Hosts that want the modal's geo behavior render
+   * against the opt-in `useAllowedCountry` hook instead.
+   */
+  async runStartChecks() {
+    const recipientValid = await verifyRecipientAddress(
+      {
+        chain_type: this.destination.chainType,
+        chain_id: this.destination.chainId,
+        token_address: this.destination.tokenAddress,
+        recipient_address: this.destination.recipientAddress
+      },
+      this.publishableKey
+    ).then((result) => result.valid).catch(() => null);
+    if (recipientValid === false) {
+      throw new SessionCheckError(
+        "INVALID_RECIPIENT",
+        "Recipient address cannot receive funds for this destination"
+      );
+    }
+  }
+  // -- Detection polling (port of useDepositPolling Effect 2) ----------------
+  startDetectionLoop(token) {
+    const poll = () => {
+      if (token !== this.runToken) {
+        if (this.detectionTimer) {
+          clearInterval(this.detectionTimer);
+          this.detectionTimer = null;
+        }
+        return;
+      }
+      void this.pollExecutions(token);
+    };
+    poll();
+    this.detectionTimer = setInterval(poll, DETECTION_POLL_INTERVAL_MS);
+  }
+  async pollExecutions(token) {
+    if (this.pollInFlight) return;
+    this.pollInFlight = true;
+    try {
+      await this.pollExecutionsOnce(token);
+    } finally {
+      this.pollInFlight = false;
+    }
+  }
+  async pollExecutionsOnce(token) {
+    try {
+      const response = await queryExecutions(
+        this.externalUserId,
+        this.publishableKey,
+        "deposit" /* Deposit */
+      );
+      if (token !== this.runToken) return;
+      if (this.pollErrorLatched) {
+        this.pollErrorLatched = false;
+        if (this.error && !this.error.fatal) {
+          this.error = null;
+          this.commit();
+          this.notify();
+        }
+      }
+      const cutoffMs = this.baselineMs - LOOKBACK_MS;
+      const sorted = [...response.data].sort((a, b) => {
+        const timeA = a.created_at ? new Date(a.created_at).getTime() : 0;
+        const timeB = b.created_at ? new Date(b.created_at).getTime() : 0;
+        return timeB - timeA;
+      });
+      let candidate = null;
+      for (const execution of sorted) {
+        const createdMs = execution.created_at ? new Date(execution.created_at).getTime() : NaN;
+        if (!Number.isFinite(createdMs) || createdMs < cutoffMs) continue;
+        const trackedStatus = this.tracked.get(execution.id);
+        const isTerminal = execution.status === "succeeded" /* SUCCEEDED */ || FAILURE_STATUSES.includes(execution.status);
+        if (trackedStatus === void 0 && createdMs < this.baselineMs && isTerminal) {
+          continue;
+        }
+        if (trackedStatus === void 0 || trackedStatus !== execution.status) {
+          candidate = execution;
+          break;
+        }
+      }
+      if (!candidate) return;
+      this.processExecutionChange(candidate);
+    } catch (error) {
+      if (token !== this.runToken) return;
+      console.error("[unifold] failed to fetch executions:", error);
+      if (!this.pollErrorLatched) {
+        this.pollErrorLatched = true;
+        this.error = {
+          code: "POLLING_ERROR",
+          message: "Failed to fetch deposit status",
+          fatal: false,
+          cause: error
+        };
+        this.commit();
+        this.emitSessionEvent("deposit_session.errored" /* SESSION_ERRORED */, {
+          sessionId: this.id,
+          code: "POLLING_ERROR",
+          message: "Failed to fetch deposit status",
+          fatal: false
+        });
+        this.notify();
+      }
+    }
+  }
+  processExecutionChange(wire) {
+    const previousStatus = this.tracked.get(wire.id) ?? null;
+    this.tracked.set(wire.id, wire.status);
+    const execution = mapDirectExecution(wire);
+    const existingIndex = this.executions.findIndex((e) => e.id === execution.id);
+    if (existingIndex >= 0) {
+      this.executions = this.executions.map((e, i) => i === existingIndex ? execution : e);
+    } else {
+      this.executions = [...this.executions, execution].sort((a, b) => {
+        const timeA = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+        const timeB = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+        return timeB - timeA;
+      });
+    }
+    this.setStatus(this.anyExecutionInFlight() ? "processing" : "ready");
+    const wasInProgressOrNew = previousStatus === null || IN_PROGRESS_STATUSES.includes(previousStatus);
+    if (wire.status === "succeeded" /* SUCCEEDED */ && wasInProgressOrNew && !this.firstSuccess) {
+      this.firstSuccess = execution;
+    }
+    this.commit();
+    const eventCreated = this.executionEventTimestamp(wire);
+    if (previousStatus === null) {
+      this.emitExecutionEvent("direct_execution.detected" /* EXECUTION_DETECTED */, execution, eventCreated);
+    } else {
+      this.emitExecutionEvent(
+        "direct_execution.updated" /* EXECUTION_UPDATED */,
+        { ...execution, previousStatus },
+        eventCreated
+      );
+    }
+    if (wire.status === "succeeded" /* SUCCEEDED */ && wasInProgressOrNew) {
+      this.emitExecutionEvent("direct_execution.succeeded" /* EXECUTION_SUCCEEDED */, execution, eventCreated);
+    } else if (FAILURE_STATUSES.includes(wire.status) && (previousStatus === null || !FAILURE_STATUSES.includes(previousStatus))) {
+      this.emitExecutionEvent("direct_execution.failed" /* EXECUTION_FAILED */, execution, eventCreated);
+    }
+    this.notify();
+  }
+  // -- Scan nudge (port of useDepositPolling Effects 1 + 3) ------------------
+  armConfirmation(trigger) {
+    if (this.checkingDeposit || this.destroyed) return;
+    if (this.addressIds.length === 0) return;
+    if (this.armTimer) {
+      clearTimeout(this.armTimer);
+      this.armTimer = null;
+    }
+    this.checkingDeposit = true;
+    this.commit();
+    this.emitSessionEvent("deposit_session.confirmation_started" /* CONFIRMATION_STARTED */, {
+      sessionId: this.id,
+      trigger
+    });
+    this.notify();
+    const token = this.runToken;
+    const nudge = () => {
+      if (token !== this.runToken) return;
+      void Promise.all(
+        this.addressIds.map(
+          (id) => pollDirectExecutions({ deposit_wallet_id: id }, this.publishableKey).catch(() => {
+          })
+        )
+      );
+    };
+    nudge();
+    this.nudgeTimer = setInterval(nudge, SCAN_NUDGE_INTERVAL_MS);
+  }
+  // -- Internals --------------------------------------------------------------
+  anyExecutionInFlight() {
+    return Array.from(this.tracked.values()).some(
+      (status) => IN_PROGRESS_STATUSES.includes(status)
+    );
+  }
+  setStatus(status) {
+    this.status = status;
+  }
+  clearTimers() {
+    if (this.detectionTimer) {
+      clearInterval(this.detectionTimer);
+      this.detectionTimer = null;
+    }
+    if (this.nudgeTimer) {
+      clearInterval(this.nudgeTimer);
+      this.nudgeTimer = null;
+    }
+    if (this.armTimer) {
+      clearTimeout(this.armTimer);
+      this.armTimer = null;
+    }
+  }
+  buildSnapshot() {
+    return {
+      status: this.status,
+      addresses: this.addresses,
+      executions: this.executions,
+      latestExecution: this.executions[0] ?? null,
+      isCheckingDeposit: this.checkingDeposit,
+      error: this.error
+    };
+  }
+  /** Rebuild the snapshot so getSnapshot() reflects current state. */
+  commit() {
+    this.snapshot = this.buildSnapshot();
+  }
+  notify() {
+    this.listeners.forEach((listener) => {
+      try {
+        listener();
+      } catch (error) {
+        console.error("[unifold] snapshot listener threw", error);
+      }
+    });
+  }
+  executionEventTimestamp(wire) {
+    if (wire.updated_at) return Math.floor(new Date(wire.updated_at).getTime() / 1e3);
+    if (wire.created_at) return Math.floor(new Date(wire.created_at).getTime() / 1e3);
+    return Math.floor(Date.now() / 1e3);
+  }
+  emitSessionEvent(type, object) {
+    this.emitter.emit(type, {
+      id: generatePrefixedKSUID("sevt"),
+      type,
+      created: Math.floor(Date.now() / 1e3),
+      method: this.method,
+      data: { object }
+    });
+  }
+  emitExecutionEvent(type, object, created) {
+    this.emitter.emit(type, {
+      id: generatePrefixedKSUID("sevt"),
+      type,
+      created,
+      method: this.method,
+      data: { object }
+    });
+  }
+};
+
+// src/lib/client.ts
+var UnifoldClient = class {
+  constructor(options) {
+    __publicField(this, "publishableKey");
+    const { publishableKey } = options;
+    if (!publishableKey || publishableKey.trim() === "") {
+      throw new Error("Unifold: publishableKey is required");
+    }
+    if (!publishableKey.startsWith("pk_test_") && !publishableKey.startsWith("pk_live_")) {
+      console.warn('Unifold: publishableKey should start with "pk_test_" or "pk_live_".');
+    }
+    this.publishableKey = publishableKey;
+  }
+  /** Create a headless deposit-session flow controller. */
+  createDepositSession(params) {
+    return new DepositSession({ ...params, publishableKey: this.publishableKey });
+  }
+  /**
+   * Create (idempotently) and return the user's deposit addresses for a
+   * destination — `POST /v1/public/deposit_addresses`.
+   */
+  async getDepositAddresses(params) {
+    const response = await createDepositAddress(
+      {
+        external_user_id: params.externalUserId,
+        destination_chain_type: params.destination.chainType,
+        destination_chain_id: params.destination.chainId,
+        destination_token_address: params.destination.tokenAddress,
+        recipient_address: params.destination.recipientAddress,
+        contract_calls: params.destination.contractCalls
+      },
+      this.publishableKey
+    );
+    return response.data.map(mapWalletToDepositAddress);
+  }
+  /** List the user's executions — `POST /v1/public/direct_executions/query`. */
+  async listExecutions(params) {
+    const response = await queryExecutions(
+      params.externalUserId,
+      this.publishableKey,
+      params.actionType ?? "deposit" /* Deposit */
+    );
+    return response.data.map(mapDirectExecution);
+  }
+  /** Source tokens/chains a user can deposit from for a destination. */
+  async getSupportedDepositTokens(params) {
+    const response = await getSupportedDepositTokens(
+      this.publishableKey,
+      params?.destination || params?.productType ? {
+        ...params.destination ? {
+          destination_chain_type: params.destination.chainType,
+          destination_chain_id: params.destination.chainId,
+          destination_token_address: params.destination.tokenAddress
+        } : {},
+        ...params.productType ? { product_type: params.productType } : {}
+      } : void 0
+    );
+    return response.data;
+  }
+  /** Validate a recipient address for a destination (e.g. Algorand opt-in). */
+  async verifyAddress(params) {
+    const response = await verifyRecipientAddress(
+      {
+        chain_type: params.chainType,
+        chain_id: params.chainId,
+        token_address: params.tokenAddress,
+        recipient_address: params.recipientAddress
+      },
+      this.publishableKey
+    );
+    return {
+      valid: response.valid,
+      failureCode: response.failure_code ?? null,
+      metadata: response.metadata ?? null
+    };
+  }
+  /** Project-level configuration (feature flags, blocked countries, ...). */
+  getProjectConfig(options) {
+    return getProjectConfig(this.publishableKey, options);
+  }
+};
+function createUnifoldClient(options) {
+  return new UnifoldClient(options);
+}
+
 // src/hooks/use-user-ip.ts
 import { useQuery } from "@tanstack/react-query";
 function useUserIp() {
@@ -1670,12 +2543,21 @@ var i18n = en_default;
 export {
   ActionType,
   CheckoutEventType,
+  DETECTION_ARM_DELAY_MS,
+  DETECTION_POLL_INTERVAL_MS,
+  DepositAddressValidationError,
   DepositEventType,
+  DepositSession,
+  DepositSessionEventType,
+  DepositSessionWaitError,
   ExecutionStatus,
   IneligibilityReason,
   IntegrationProvider,
+  LOOKBACK_MS,
+  SCAN_NUDGE_INTERVAL_MS,
   SOLANA_USDC_ADDRESS,
   StripeApiResponseError,
+  UnifoldClient,
   WithdrawEventType,
   authenticateIntegrationOAuth,
   buildHypercoreTransaction,
@@ -1689,6 +2571,7 @@ export {
   createIntegrationTransfer,
   createOnrampSession,
   createOnrampVerificationSession,
+  createUnifoldClient,
   exchangeOnrampVerificationToken,
   formatStablecoinAmount,
   generateKSUID,
@@ -1723,6 +2606,7 @@ export {
   getOnrampVerificationSession,
   getPreferredIconUrl,
   getProjectConfig,
+  getPublicIncident,
   getSupportedDepositTokens,
   getSupportedDestinationTokens,
   getTokenChains,
@@ -1731,7 +2615,10 @@ export {
   getWalletMobileDeepLink,
   i18n,
   isApplePayLimitReached,
+  isDepositAddressValidationError,
   listPaymentIntentExecutions,
+  mapDirectExecution,
+  mapWalletToDepositAddress,
   pollDirectExecutions,
   queryExecutions,
   refreshIntegrationToken,