@unifold/core 0.1.74 → 0.1.76

package/dist/index.mjs

@@ -41,7 +41,7 @@ function generatePrefixedKSUID(prefix) {
 }
 
 // src/lib/client-headers.ts
-var SDK_VERSION = true ? "0.1.74" : "0.0.0-dev";
+var SDK_VERSION = true ? "0.1.76" : "0.0.0-dev";
 var CLIENT_VERSION_HEADER = "x-unifold-client-version";
 var CLIENT_USER_AGENT_HEADER = "x-unifold-client-user-agent";
 function detectRuntime() {
@@ -539,6 +539,7 @@ async function getDefaultOnrampToken(params, publishableKey) {
   const queryParams = new URLSearchParams();
   if (params.country_code) queryParams.append("country_code", params.country_code);
   if (params.subdivision_code) queryParams.append("subdivision_code", params.subdivision_code);
+  if (params.service_provider) queryParams.append("service_provider", params.service_provider);
   queryParams.append("token_address", params.token_address);
   queryParams.append("chain_id", params.chain_id);
   queryParams.append("chain_type", params.chain_type);
@@ -803,6 +804,25 @@ async function createExchangeSession(request, publishableKey) {
   }
   return response.json();
 }
+async function getOnrampSessionStatus(externalId, publishableKey, signal) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const response = await apiFetch(`${API_BASE_URL}/v1/public/onramps/sessions/status`, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "x-publishable-key": pk,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ external_id: externalId }),
+    signal
+  });
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ message: response.statusText }));
+    throw new Error(`Failed to get session status: ${error.message || response.statusText}`);
+  }
+  return response.json();
+}
 function getExchangeSessionStartUrl(request, publishableKey) {
   const params = new URLSearchParams();
   params.append("publishable_key", publishableKey);
@@ -821,24 +841,95 @@ function getExchangeSessionStartUrl(request, publishableKey) {
   if (request.source_amount) {
     params.append("source_amount", request.source_amount);
   }
+  if (request.country_code) {
+    params.append("country_code", request.country_code);
+  }
+  if (request.subdivision_code) {
+    params.append("subdivision_code", request.subdivision_code);
+  }
   params.append("external_id", request.external_id ?? generatePrefixedKSUID("exc"));
   return `${API_BASE_URL}/v1/public/onramps/exchanges/sessions/start?${params.toString()}`;
 }
-async function getIntegrationExchanges(publishableKey) {
+async function getIntegrationExchanges(publishableKey, query) {
   const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
   validatePublishableKey(pk);
-  const response = await apiFetch(`${API_BASE_URL}/v1/public/integrations/oauth/exchanges`, {
-    method: "GET",
+  const params = new URLSearchParams();
+  if (query?.country_code) params.append("country_code", query.country_code);
+  if (query?.subdivision_code) params.append("subdivision_code", query.subdivision_code);
+  const queryString = params.toString() ? `?${params.toString()}` : "";
+  const headers = {
+    accept: "application/json",
+    "x-publishable-key": pk
+  };
+  const response = await apiFetch(
+    `${API_BASE_URL}/v1/public/integrations/exchanges${queryString}`,
+    {
+      method: "GET",
+      headers
+    }
+  );
+  if (response.ok) {
+    return response.json();
+  }
+  if (response.status === 404) {
+    const legacyResponse = await apiFetch(
+      `${API_BASE_URL}/v1/public/integrations/oauth/exchanges${queryString}`,
+      {
+        method: "GET",
+        headers
+      }
+    );
+    if (legacyResponse.ok) {
+      return legacyResponse.json();
+    }
+    throw new Error(`Failed to fetch integration exchanges: ${legacyResponse.statusText}`);
+  }
+  throw new Error(`Failed to fetch integration exchanges: ${response.statusText}`);
+}
+async function createIntegrationExchangeSession(request, publishableKey) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const response = await apiFetch(`${API_BASE_URL}/v1/public/integrations/exchanges/sessions`, {
+    method: "POST",
     headers: {
       accept: "application/json",
-      "x-publishable-key": pk
-    }
+      "x-publishable-key": pk,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(request)
   });
   if (!response.ok) {
-    throw new Error(`Failed to fetch integration exchanges: ${response.statusText}`);
+    throw new Error(`Failed to create integration exchange session: ${response.statusText}`);
   }
   return response.json();
 }
+function getIntegrationExchangeSessionStartUrl(request, publishableKey) {
+  const params = new URLSearchParams();
+  params.append("publishable_key", publishableKey);
+  params.append("service_provider", request.service_provider);
+  params.append("chain_type", request.chain_type);
+  params.append("address", request.address);
+  if (request.preferred_destination_currency) {
+    params.append("preferred_destination_currency", request.preferred_destination_currency);
+  }
+  if (request.preferred_destination_network) {
+    params.append("preferred_destination_network", request.preferred_destination_network);
+  }
+  if (request.source_currency) {
+    params.append("source_currency", request.source_currency);
+  }
+  if (request.source_amount) {
+    params.append("source_amount", request.source_amount);
+  }
+  if (request.country_code) {
+    params.append("country_code", request.country_code);
+  }
+  if (request.subdivision_code) {
+    params.append("subdivision_code", request.subdivision_code);
+  }
+  params.append("external_id", request.external_id ?? generatePrefixedKSUID("exc"));
+  return `${API_BASE_URL}/v1/public/integrations/exchanges/sessions/start?${params.toString()}`;
+}
 async function startIntegrationOAuth(publishableKey) {
   const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
   validatePublishableKey(pk);
@@ -1732,10 +1823,17 @@ function createCoinbaseGooglePaySession(request, onrampToken, publishableKey, si
 }
 
 // src/lib/events.ts
+var DirectExecutionEventType = /* @__PURE__ */ ((DirectExecutionEventType2) => {
+  DirectExecutionEventType2["DETECTED"] = "direct_execution.detected";
+  DirectExecutionEventType2["UPDATED"] = "direct_execution.updated";
+  DirectExecutionEventType2["SUCCEEDED"] = "direct_execution.succeeded";
+  DirectExecutionEventType2["FAILED"] = "direct_execution.failed";
+  return DirectExecutionEventType2;
+})(DirectExecutionEventType || {});
 var DepositEventType = /* @__PURE__ */ ((DepositEventType2) => {
   DepositEventType2["ONRAMP_SESSION_CREATED"] = "onramp_session.created";
-  DepositEventType2["DIRECT_EXECUTION_SUCCEEDED"] = "direct_execution.succeeded";
-  DepositEventType2["DIRECT_EXECUTION_FAILED"] = "direct_execution.failed";
+  DepositEventType2["DIRECT_EXECUTION_SUCCEEDED"] = "direct_execution.succeeded" /* SUCCEEDED */;
+  DepositEventType2["DIRECT_EXECUTION_FAILED"] = "direct_execution.failed" /* FAILED */;
   DepositEventType2["METHOD_SELECTED"] = "deposit.method_selected";
   DepositEventType2["TOKEN_SELECTED"] = "deposit.token_selected";
   DepositEventType2["WALLET_SELECTED"] = "deposit.wallet_selected";
@@ -1755,8 +1853,8 @@ var DepositEventType = /* @__PURE__ */ ((DepositEventType2) => {
   return DepositEventType2;
 })(DepositEventType || {});
 var WithdrawEventType = /* @__PURE__ */ ((WithdrawEventType2) => {
-  WithdrawEventType2["DIRECT_EXECUTION_SUCCEEDED"] = "direct_execution.succeeded";
-  WithdrawEventType2["DIRECT_EXECUTION_FAILED"] = "direct_execution.failed";
+  WithdrawEventType2["DIRECT_EXECUTION_SUCCEEDED"] = "direct_execution.succeeded" /* SUCCEEDED */;
+  WithdrawEventType2["DIRECT_EXECUTION_FAILED"] = "direct_execution.failed" /* FAILED */;
   WithdrawEventType2["TOKEN_SELECTED"] = "withdraw.token_selected";
   WithdrawEventType2["FLOW_STARTED"] = "withdraw.flow_started";
   return WithdrawEventType2;
@@ -1855,6 +1953,52 @@ function mapDirectExecution(execution) {
     } : void 0
   };
 }
+function mapOnrampQuote(quote) {
+  return {
+    serviceProvider: quote.service_provider,
+    serviceProviderDisplayName: quote.service_provider_display_name,
+    paymentMethodType: quote.payment_method_type,
+    sourceCurrency: quote.source_currency,
+    countryCode: quote.country_code,
+    sourceAmount: quote.source_amount,
+    sourceAmountWithoutFees: quote.source_amount_without_fees,
+    totalFee: quote.total_fee,
+    networkFee: quote.network_fee,
+    transactionFee: quote.transaction_fee,
+    partnerFee: quote.partner_fee,
+    destinationAmount: quote.destination_amount,
+    destinationAmountWithoutFees: quote.destination_amount_without_fees,
+    destinationCurrency: quote.destination_currency,
+    destinationNetwork: quote.destination_network,
+    exchangeRate: quote.exchange_rate,
+    customerScore: quote.customer_score,
+    lowKyc: quote.low_kyc,
+    iconUrl: quote.icon_url,
+    iconUrls: quote.icon_urls,
+    institutionName: quote.institution_name
+  };
+}
+function mapDefaultOnrampToken(response) {
+  const metadata = response.destination_token_metadata;
+  return {
+    network: response.destination_network,
+    currency: response.destination_currency,
+    isStablecoin: response.is_stablecoin ?? false,
+    token: {
+      symbol: metadata.symbol,
+      name: metadata.name,
+      tokenAddress: metadata.token_address,
+      decimals: metadata.decimals,
+      chainId: metadata.chain_id,
+      chainType: metadata.chain_type,
+      chainName: metadata.chain_name,
+      iconUrl: metadata.icon_url,
+      iconUrls: metadata.icon_urls,
+      chainIconUrl: metadata.chain?.icon_url ?? ""
+    },
+    estimatedProcessingTimeSeconds: response.estimated_processing_time
+  };
+}
 
 // src/lib/deposit-session.ts
 var DETECTION_POLL_INTERVAL_MS = 2500;
@@ -1862,16 +2006,16 @@ 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) => {
+var DepositSessionEventType = ((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";
+  DepositSessionEventType2[DepositSessionEventType2["EXECUTION_DETECTED"] = "direct_execution.detected" /* DETECTED */] = "EXECUTION_DETECTED";
+  DepositSessionEventType2[DepositSessionEventType2["EXECUTION_UPDATED"] = "direct_execution.updated" /* UPDATED */] = "EXECUTION_UPDATED";
+  DepositSessionEventType2[DepositSessionEventType2["EXECUTION_SUCCEEDED"] = "direct_execution.succeeded" /* SUCCEEDED */] = "EXECUTION_SUCCEEDED";
+  DepositSessionEventType2[DepositSessionEventType2["EXECUTION_FAILED"] = "direct_execution.failed" /* FAILED */] = "EXECUTION_FAILED";
   return DepositSessionEventType2;
 })(DepositSessionEventType || {});
 var IN_PROGRESS_STATUSES = [
@@ -2094,17 +2238,17 @@ var DepositSession = class {
           }
           const offs = [
             this.on(
-              "direct_execution.succeeded" /* EXECUTION_SUCCEEDED */,
+              DepositSessionEventType.EXECUTION_SUCCEEDED,
               (event) => settle(() => resolve(event.data.object))
             ),
-            this.on("direct_execution.failed" /* EXECUTION_FAILED */, (event) => {
+            this.on(DepositSessionEventType.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 */, () => {
+            this.on(DepositSessionEventType.EXECUTION_UPDATED, () => {
               if (this.anyExecutionInFlight() || this.firstSuccess) return;
               const failed = this.snapshot.executions.find(
                 (execution) => FAILURE_STATUSES.includes(execution.status)
@@ -2394,18 +2538,18 @@ var DepositSession = class {
     this.commit();
     const eventCreated = this.executionEventTimestamp(wire);
     if (previousStatus === null) {
-      this.emitExecutionEvent("direct_execution.detected" /* EXECUTION_DETECTED */, execution, eventCreated);
+      this.emitExecutionEvent(DepositSessionEventType.EXECUTION_DETECTED, execution, eventCreated);
     } else {
       this.emitExecutionEvent(
-        "direct_execution.updated" /* EXECUTION_UPDATED */,
+        DepositSessionEventType.EXECUTION_UPDATED,
         { ...execution, previousStatus },
         eventCreated
       );
     }
     if (wire.status === "succeeded" /* SUCCEEDED */ && wasInProgressOrNew) {
-      this.emitExecutionEvent("direct_execution.succeeded" /* EXECUTION_SUCCEEDED */, execution, eventCreated);
+      this.emitExecutionEvent(DepositSessionEventType.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.emitExecutionEvent(DepositSessionEventType.EXECUTION_FAILED, execution, eventCreated);
     }
     this.notify();
   }
@@ -2508,22 +2652,1015 @@ var DepositSession = class {
   }
 };
 
-// src/lib/client.ts
-var UnifoldClient = class {
-  constructor(options) {
+// src/lib/onramp-session.ts
+var QUOTE_REFRESH_INTERVAL_MS = 6e4;
+var ADDRESS_CREATE_MAX_ATTEMPTS2 = 4;
+var OnrampSessionEventType = ((OnrampSessionEventType2) => {
+  OnrampSessionEventType2["SESSION_STARTED"] = "onramp_session.started";
+  OnrampSessionEventType2["ADDRESSES_CREATED"] = "onramp_session.addresses_created";
+  OnrampSessionEventType2["QUOTES_UPDATED"] = "onramp_session.quotes_updated";
+  OnrampSessionEventType2[OnrampSessionEventType2["CHECKOUT_CREATED"] = "onramp_session.created" /* ONRAMP_SESSION_CREATED */] = "CHECKOUT_CREATED";
+  OnrampSessionEventType2["SESSION_STOPPED"] = "onramp_session.stopped";
+  OnrampSessionEventType2["SESSION_ERRORED"] = "onramp_session.errored";
+  OnrampSessionEventType2[OnrampSessionEventType2["EXECUTION_DETECTED"] = "direct_execution.detected" /* DETECTED */] = "EXECUTION_DETECTED";
+  OnrampSessionEventType2[OnrampSessionEventType2["EXECUTION_UPDATED"] = "direct_execution.updated" /* UPDATED */] = "EXECUTION_UPDATED";
+  OnrampSessionEventType2[OnrampSessionEventType2["EXECUTION_SUCCEEDED"] = "direct_execution.succeeded" /* SUCCEEDED */] = "EXECUTION_SUCCEEDED";
+  OnrampSessionEventType2[OnrampSessionEventType2["EXECUTION_FAILED"] = "direct_execution.failed" /* FAILED */] = "EXECUTION_FAILED";
+  return OnrampSessionEventType2;
+})(OnrampSessionEventType || {});
+var FAILURE_STATUSES2 = ["failed" /* FAILED */, "refunded" /* REFUNDED */];
+var IN_PROGRESS_STATUSES2 = [
+  "pending" /* PENDING */,
+  "waiting" /* WAITING */,
+  "delayed" /* DELAYED */
+];
+var OnrampSessionWaitError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    __publicField(this, "code");
+    /** Failed execution (`DEPOSIT_FAILED`) or fatal {@link OnrampSessionError} (`SESSION_ERROR`). */
+    __publicField(this, "cause");
+    this.name = "OnrampSessionWaitError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var SessionCheckError2 = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+};
+var delay2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var OnrampSession = class {
+  constructor(config) {
+    /** Immutable id for correlation, `osess_<ksuid>`. Client-generated. */
+    __publicField(this, "id");
+    __publicField(this, "emitter", new TypedEmitter());
+    __publicField(this, "listeners", /* @__PURE__ */ new Set());
     __publicField(this, "publishableKey");
-    const { publishableKey } = options;
-    if (!publishableKey || publishableKey.trim() === "") {
-      throw new Error("Unifold: publishableKey is required");
+    __publicField(this, "externalUserId");
+    __publicField(this, "destination");
+    __publicField(this, "paymentMethodType");
+    __publicField(this, "email");
+    __publicField(this, "quoteRefreshIntervalMs");
+    __publicField(this, "method");
+    // Mutable quote request (updateQuoteRequest). Exactly one of
+    // sourceAmount / destinationAmount is truthy at a time (amount mode).
+    // Country/subdivision: host-supplied values win; when absent they are
+    // IP-detected during start() (see resolveCountry).
+    __publicField(this, "explicitCountryCode");
+    __publicField(this, "explicitSubdivisionCode");
+    __publicField(this, "detectedCountryCode", null);
+    __publicField(this, "detectedSubdivisionCode", null);
+    __publicField(this, "sourceAmount");
+    __publicField(this, "destinationAmount");
+    __publicField(this, "sourceCurrency");
+    // 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());
+    /** In-flight destination-token + quotes pipeline (see syncQuoteInputs). */
+    __publicField(this, "syncPromise", null);
+    /** A sync was asked for mid-pipeline; the loop owes it another pass. */
+    __publicField(this, "syncRequested", false);
+    /** Code of the non-fatal error already reported, so a streak emits once. */
+    __publicField(this, "nonFatalErrorLatch", null);
+    /** True once run() got past preparing — gates live quote-input syncing. */
+    __publicField(this, "prepared", false);
+    __publicField(this, "refreshTimer", null);
+    /** service_provider chosen via selectQuote(); sticky across quote refreshes. */
+    __publicField(this, "manualSelection", null);
+    /** First execution to succeed this run — waitForSuccess's one-shot answer. */
+    __publicField(this, "firstSuccess", null);
+    // Settlement watcher (composed DepositSession), created at createCheckout().
+    __publicField(this, "watcher", null);
+    __publicField(this, "watcherOffs", []);
+    // Snapshot state
+    __publicField(this, "status", "idle");
+    __publicField(this, "addresses", []);
+    __publicField(this, "destinationToken", null);
+    /** Geo `destinationToken` was resolved for; null while unresolved. */
+    __publicField(this, "destinationTokenGeoKey", null);
+    __publicField(this, "quotes", []);
+    __publicField(this, "selectedQuote", null);
+    __publicField(this, "isRefreshingQuotes", false);
+    __publicField(this, "quotesUpdatedAt", null);
+    __publicField(this, "checkout", null);
+    __publicField(this, "executions", []);
+    __publicField(this, "checkingDeposit", false);
+    __publicField(this, "error", null);
+    __publicField(this, "snapshot");
+    if (!config.publishableKey || config.publishableKey.trim() === "") {
+      throw new Error("OnrampSession: publishableKey is required");
     }
-    if (!publishableKey.startsWith("pk_test_") && !publishableKey.startsWith("pk_live_")) {
-      console.warn('Unifold: publishableKey should start with "pk_test_" or "pk_live_".');
+    if (!config.externalUserId) {
+      throw new Error("OnrampSession: externalUserId is required");
     }
-    this.publishableKey = publishableKey;
+    if (config.quoteRequest.sourceAmount && config.quoteRequest.destinationAmount) {
+      throw new Error(
+        "OnrampSession: provide exactly one of quoteRequest.sourceAmount / destinationAmount"
+      );
+    }
+    this.id = generatePrefixedKSUID("osess");
+    this.publishableKey = config.publishableKey;
+    this.externalUserId = config.externalUserId;
+    this.destination = config.destination;
+    this.paymentMethodType = config.paymentMethodType ?? "card";
+    this.email = config.email;
+    this.quoteRefreshIntervalMs = config.quoteRefreshIntervalMs ?? QUOTE_REFRESH_INTERVAL_MS;
+    this.method = this.paymentMethodType === "apple_pay" ? "apple_pay" : "card";
+    this.explicitCountryCode = config.quoteRequest.countryCode;
+    this.explicitSubdivisionCode = config.quoteRequest.subdivisionCode;
+    this.sourceAmount = config.quoteRequest.sourceAmount;
+    this.destinationAmount = config.quoteRequest.destinationAmount;
+    this.sourceCurrency = config.quoteRequest.sourceCurrency ?? "usd";
+    this.snapshot = this.buildSnapshot();
   }
-  /** Create a headless deposit-session flow controller. */
-  createDepositSession(params) {
-    return new DepositSession({ ...params, publishableKey: this.publishableKey });
+  // -- 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, resolves the onramp destination token (both
+   * with fail-fast recipient validation), and fetches the first quotes.
+   * Idempotent while running; callable again after stop() or a fatal error.
+   */
+  start() {
+    if (this.destroyed) {
+      return Promise.reject(new Error("OnrampSession has been destroyed"));
+    }
+    if (this.startPromise) return this.startPromise;
+    this.startPromise = this.run();
+    return this.startPromise;
+  }
+  /**
+   * Update the quote request (amount / currency / country) and refetch
+   * quotes. Debounce keystrokes host-side — every call that changes
+   * something hits the quotes API. No-op after createCheckout().
+   *
+   * Amount-mode switching: patching `sourceAmount` while in destination mode
+   * (or `destinationAmount` while in source mode) switches modes — the other
+   * amount is cleared. Patching BOTH to truthy values in one call throws
+   * (exactly one drives quoting).
+   */
+  updateQuoteRequest(patch) {
+    if (this.destroyed) return;
+    let nextSourceAmount = "sourceAmount" in patch ? patch.sourceAmount : this.sourceAmount;
+    let nextDestinationAmount = "destinationAmount" in patch ? patch.destinationAmount : this.destinationAmount;
+    if (nextSourceAmount && nextDestinationAmount) {
+      const sourcePatched = !!patch.sourceAmount;
+      const destinationPatched = !!patch.destinationAmount;
+      if (sourcePatched && destinationPatched) {
+        throw new Error(
+          "OnrampSession.updateQuoteRequest: provide exactly one of sourceAmount / destinationAmount"
+        );
+      }
+      if (destinationPatched) nextSourceAmount = void 0;
+      else nextDestinationAmount = void 0;
+    }
+    const next = {
+      countryCode: patch.countryCode ?? this.explicitCountryCode,
+      subdivisionCode: "subdivisionCode" in patch ? patch.subdivisionCode : this.explicitSubdivisionCode,
+      sourceAmount: nextSourceAmount,
+      destinationAmount: nextDestinationAmount,
+      sourceCurrency: patch.sourceCurrency ?? this.sourceCurrency
+    };
+    const changed = next.countryCode !== this.explicitCountryCode || next.subdivisionCode !== this.explicitSubdivisionCode || next.sourceAmount !== this.sourceAmount || next.destinationAmount !== this.destinationAmount || next.sourceCurrency !== this.sourceCurrency;
+    this.explicitCountryCode = next.countryCode;
+    this.explicitSubdivisionCode = next.subdivisionCode;
+    this.sourceAmount = next.sourceAmount;
+    this.destinationAmount = next.destinationAmount;
+    this.sourceCurrency = next.sourceCurrency;
+    if (!changed || this.checkout || !this.startPromise) return;
+    if (this.prepared) {
+      void this.syncQuoteInputs(this.runToken);
+    }
+  }
+  /** Refetch quotes with the current request. Resolves when the fetch settles. */
+  refreshQuotes() {
+    if (this.destroyed || !this.startPromise || this.checkout || !this.prepared) {
+      return Promise.resolve();
+    }
+    return this.syncQuoteInputs(this.runToken);
+  }
+  /**
+   * Pick a provider quote by `serviceProvider`. The selection is sticky
+   * across refreshes: while the provider keeps quoting it stays selected
+   * (with fresh pricing); if it drops out, selection falls back to the
+   * backend's top quote and auto-selection resumes.
+   *
+   * Returns the selected quote, or null when no quote matches.
+   */
+  selectQuote(serviceProvider) {
+    if (this.destroyed) return null;
+    const match = this.quotes.find((quote) => quote.serviceProvider === serviceProvider);
+    if (!match) return null;
+    this.manualSelection = serviceProvider;
+    this.selectedQuote = match;
+    this.commit();
+    this.notify();
+    return match;
+  }
+  /**
+   * Build the provider-hosted checkout and start watching the deposit
+   * addresses for the provider's on-chain settlement.
+   *
+   * Uses `snapshot.selectedQuote` (backend's top quote unless the host called
+   * selectQuote()). Hosts that manage their own selection UI can instead pass
+   * `options.serviceProvider` for a one-shot choice without mutating the
+   * sticky selection.
+   *
+   * Synchronous by design: the URL is assembled locally (single-use token
+   * exchange happens when it is opened), so hosts can `window.open()` the
+   * result inside the click handler without tripping popup blockers.
+   *
+   * Throws when the session is not ready (no matching quote / addresses or
+   * destination token missing) — gate your button on `status === 'ready'`
+   * and `selectedQuote`.
+   */
+  createCheckout(options = {}) {
+    if (this.destroyed) throw new Error("OnrampSession has been destroyed");
+    const quote = options.serviceProvider ? this.quotes.find((q) => q.serviceProvider === options.serviceProvider) : this.selectedQuote;
+    if (!quote) {
+      throw new Error(
+        options.serviceProvider ? `OnrampSession.createCheckout: no quote from '${options.serviceProvider}'` : "OnrampSession.createCheckout: no quote selected"
+      );
+    }
+    if (!this.destinationToken) {
+      throw new Error("OnrampSession.createCheckout: destination token not resolved yet");
+    }
+    const wallet = this.addresses.find(
+      (address) => address.chainType === this.destinationToken?.token.chainType
+    );
+    if (!wallet) {
+      throw new Error("OnrampSession.createCheckout: no deposit address for the onramp chain type");
+    }
+    const externalId = options.externalId ?? generatePrefixedKSUID("orsext");
+    const request = {
+      service_provider: quote.serviceProvider,
+      country_code: (quote.countryCode || this.effectiveCountryCode()).toUpperCase(),
+      source_currency: quote.sourceCurrency,
+      // Exactly one of source_amount / destination_amount — the session's
+      // current amount mode (quotes were fetched in the same mode, so the
+      // quoted providers all support it).
+      ...this.sourceAmount ? { source_amount: this.sourceAmount } : { destination_amount: this.destinationAmount },
+      destination_currency: quote.destinationCurrency,
+      destination_network: quote.destinationNetwork,
+      wallet_address: wallet.address,
+      subdivision_code: this.effectiveSubdivisionCode(),
+      external_id: externalId,
+      email: options.email ?? this.email,
+      payment_method_type: quote.paymentMethodType ?? this.paymentMethodType
+    };
+    const checkout = {
+      url: getOnrampSessionStartUrl(request, this.publishableKey),
+      externalId,
+      serviceProvider: quote.serviceProvider,
+      quote,
+      sourceAmount: this.sourceAmount ?? null,
+      destinationAmount: this.sourceAmount ? null : this.destinationAmount ?? null,
+      sourceCurrency: quote.sourceCurrency,
+      createdAt: Date.now()
+    };
+    this.checkout = checkout;
+    this.clearRefreshTimer();
+    this.setStatus("awaiting_payment");
+    this.commit();
+    this.emitSessionEvent(OnrampSessionEventType.CHECKOUT_CREATED, {
+      externalId,
+      sessionId: this.id,
+      url: checkout.url,
+      serviceProvider: quote.serviceProvider
+    });
+    this.notify();
+    this.startWatcher();
+    return checkout;
+  }
+  /**
+   * Stops quote refresh and settlement watching. The session can be
+   * restarted with start(), which resets quotes/checkout/executions
+   * (fresh run).
+   */
+  stop() {
+    const wasActive = this.startPromise !== null;
+    this.runToken += 1;
+    this.clearRefreshTimer();
+    this.teardownWatcher();
+    this.startPromise = null;
+    this.syncPromise = null;
+    this.isRefreshingQuotes = false;
+    this.checkingDeposit = false;
+    if (this.status !== "idle" && this.status !== "error") {
+      this.setStatus("idle");
+    }
+    if (wasActive && !this.destroyed) {
+      this.commit();
+      this.emitSessionEvent("onramp_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) — e.g. `waitForStatus('ready')` awaits quotes,
+   * `waitForStatus('processing')` awaits detection of the settlement.
+   * Statuses carry no outcomes; await those with {@link waitForSuccess}.
+   *
+   * Rejects with {@link OnrampSessionWaitError} 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 — same one-shot first-completion contract as
+   * {@link DepositSession.waitForSuccess}. A failure only rejects
+   * (`DEPOSIT_FAILED`) when no other observed execution is still in flight;
+   * fatal session errors reject with `SESSION_ERROR`. The session keeps
+   * watching after success — subscribe to `direct_execution.succeeded` to
+   * react to every settlement.
+   */
+  waitForSuccess(options = {}) {
+    return new Promise((resolve, reject) => {
+      this.installWaiter({
+        options,
+        reject,
+        subscribe: (settle) => {
+          const rejectFailure = (failed) => settle(
+            () => reject(new OnrampSessionWaitError("DEPOSIT_FAILED", "Deposit failed", failed))
+          );
+          if (this.firstSuccess) {
+            const first = this.firstSuccess;
+            settle(() => resolve(first));
+            return () => {
+            };
+          }
+          const alreadyFailed = this.executions.find(
+            (execution) => FAILURE_STATUSES2.includes(execution.status)
+          );
+          if (alreadyFailed && !this.anyExecutionInFlight()) {
+            rejectFailure(alreadyFailed);
+            return () => {
+            };
+          }
+          if (this.error?.fatal) {
+            const fatal = this.error;
+            settle(() => reject(new OnrampSessionWaitError("SESSION_ERROR", fatal.message, fatal)));
+            return () => {
+            };
+          }
+          const offs = [
+            this.on(
+              OnrampSessionEventType.EXECUTION_SUCCEEDED,
+              (event) => settle(() => resolve(event.data.object))
+            ),
+            this.on(OnrampSessionEventType.EXECUTION_FAILED, (event) => {
+              if (this.anyExecutionInFlight()) return;
+              rejectFailure(event.data.object);
+            }),
+            this.on(OnrampSessionEventType.EXECUTION_UPDATED, () => {
+              if (this.anyExecutionInFlight() || this.firstSuccess) return;
+              const failed = this.executions.find(
+                (execution) => FAILURE_STATUSES2.includes(execution.status)
+              );
+              if (failed) rejectFailure(failed);
+            }),
+            this.on("onramp_session.errored" /* SESSION_ERRORED */, (event) => {
+              if (!event.data.object.fatal) return;
+              settle(
+                () => reject(
+                  new OnrampSessionWaitError(
+                    "SESSION_ERROR",
+                    event.data.object.message,
+                    event.data.object
+                  )
+                )
+              );
+            })
+          ];
+          return () => offs.forEach((off) => off());
+        }
+      });
+    });
+  }
+  /** Shared waiter plumbing — AbortSignal / destroy() rejection with single settlement. */
+  installWaiter({
+    options,
+    reject,
+    subscribe
+  }) {
+    if (this.destroyed) {
+      reject(new OnrampSessionWaitError("DESTROYED", "OnrampSession has been destroyed"));
+      return;
+    }
+    if (options.signal?.aborted) {
+      reject(new OnrampSessionWaitError("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 OnrampSessionWaitError("ABORTED", "Wait aborted", options.signal?.reason))
+    );
+    const onDestroy = () => settle(
+      () => reject(
+        new OnrampSessionWaitError("DESTROYED", "OnrampSession 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.teardownWatcher();
+    this.prepared = false;
+    this.addresses = [];
+    this.destinationToken = null;
+    this.destinationTokenGeoKey = null;
+    this.quotes = [];
+    this.selectedQuote = null;
+    this.manualSelection = null;
+    this.quotesUpdatedAt = null;
+    this.nonFatalErrorLatch = null;
+    this.checkout = null;
+    this.executions = [];
+    this.firstSuccess = null;
+    this.checkingDeposit = false;
+    this.error = null;
+    this.setStatus("preparing");
+    this.commit();
+    this.emitSessionEvent("onramp_session.started" /* SESSION_STARTED */, { sessionId: this.id });
+    this.notify();
+    let wallets;
+    let destinationToken;
+    try {
+      [wallets, destinationToken] = await Promise.all([
+        this.createAddressesWithRetry(token),
+        this.resolveCountry().then(() => this.resolveDestinationToken()),
+        this.runStartChecks()
+      ]);
+    } catch (cause) {
+      if (token !== this.runToken) return;
+      const isCheck = cause instanceof SessionCheckError2;
+      this.failFatally(
+        isCheck ? cause.code : "ADDRESS_CREATION_FAILED",
+        isCheck ? cause.message : "Failed to prepare onramp session",
+        cause
+      );
+      return;
+    }
+    if (token !== this.runToken) return;
+    this.addresses = wallets.map(mapWalletToDepositAddress);
+    this.destinationToken = destinationToken.token;
+    this.destinationTokenGeoKey = destinationToken.geoKey;
+    this.prepared = true;
+    this.setStatus("quoting");
+    this.commit();
+    this.emitSessionEvent("onramp_session.addresses_created" /* ADDRESSES_CREATED */, {
+      sessionId: this.id,
+      addresses: this.addresses
+    });
+    this.notify();
+    if (token !== this.runToken) return;
+    await this.syncQuoteInputs(token);
+    if (token !== this.runToken) return;
+    if (this.quoteRefreshIntervalMs > 0) {
+      this.refreshTimer = setInterval(() => {
+        if (token !== this.runToken || this.checkout) return;
+        void this.syncQuoteInputs(token);
+      }, this.quoteRefreshIntervalMs);
+    }
+  }
+  failFatally(code, message, cause) {
+    this.clearRefreshTimer();
+    this.startPromise = null;
+    this.error = { code, message, fatal: true, cause };
+    this.setStatus("error");
+    this.commit();
+    this.emitSessionEvent("onramp_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_ATTEMPTS2; attempt++) {
+      if (attempt > 0) {
+        await delay2(Math.min(1e3 * 2 ** (attempt - 1), 1e4));
+        if (token !== this.runToken) throw new Error("OnrampSession 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;
+  }
+  /** Host-supplied geo wins; otherwise the IP-detected value; 'US' as a last resort. */
+  effectiveCountryCode() {
+    return this.explicitCountryCode || this.detectedCountryCode || "US";
+  }
+  /**
+   * Explicit subdivision wins. A detected subdivision applies only while the
+   * country is also detected — mixing a detected subdivision into an
+   * explicitly-set country would pin quotes to a region of the wrong country.
+   */
+  effectiveSubdivisionCode() {
+    if (this.explicitSubdivisionCode !== void 0) return this.explicitSubdivisionCode;
+    if (!this.explicitCountryCode && this.detectedCountryCode) {
+      return this.detectedSubdivisionCode ?? void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Auto-detect the payer's country from their IP when the host didn't
+   * supply one — so integrators don't need to build geo plumbing to render
+   * a buy screen. Never fatal: detection failure falls back to 'US' (modal
+   * parity — BuyWithCard quotes with `userIpInfo?.alpha2 || 'US'`). The
+   * detection result is cached for the session's lifetime (restarts reuse
+   * it); an explicit countryCode — at construction or via
+   * updateQuoteRequest — always overrides.
+   */
+  async resolveCountry() {
+    if (this.explicitCountryCode || this.detectedCountryCode) return;
+    try {
+      const info = await getIpAddress();
+      this.detectedCountryCode = info.alpha2 || "US";
+      this.detectedSubdivisionCode = info.subdivision_code ?? null;
+    } catch {
+      this.detectedCountryCode = "US";
+      this.detectedSubdivisionCode = null;
+    }
+  }
+  /** Identity of the geo a destination-token resolution was made for. */
+  geoKey() {
+    return `${this.effectiveCountryCode()}|${this.effectiveSubdivisionCode() ?? ""}`;
+  }
+  /**
+   * Resolve the provider-side network/currency the destination maps to. The
+   * geo it was resolved for travels with the result: routing is
+   * geo-dependent, so the caller has to know when a later country change
+   * invalidates it.
+   */
+  async resolveDestinationToken() {
+    const geoKey = this.geoKey();
+    try {
+      const response = await getDefaultOnrampToken(
+        {
+          country_code: this.effectiveCountryCode(),
+          subdivision_code: this.effectiveSubdivisionCode(),
+          token_address: this.destination.tokenAddress,
+          chain_id: this.destination.chainId,
+          chain_type: this.destination.chainType
+        },
+        this.publishableKey
+      );
+      return { token: mapDefaultOnrampToken(response), geoKey };
+    } catch {
+      throw new SessionCheckError2(
+        "DESTINATION_TOKEN_FAILED",
+        "No onramp route available for this destination token"
+      );
+    }
+  }
+  /**
+   * Fail-fast recipient validation — parity with DepositSession. Fails open
+   * on network errors (the backend still enforces at execution time), but a
+   * definitive negative result is fatal.
+   */
+  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 SessionCheckError2(
+        "INVALID_RECIPIENT",
+        "Recipient address cannot receive funds for this destination"
+      );
+    }
+  }
+  // -- Quotes ----------------------------------------------------------------
+  /**
+   * Bring the quote inputs and the destination token back in sync, then
+   * fetch quotes. Destination-token routing is geo-dependent (the modal
+   * re-runs its default-token effect whenever `userIpInfo` changes), so a
+   * payer-country change has to re-resolve it first — quoting on the network
+   * and currency routed for the previous geo would also carry into the
+   * checkout built from those quotes.
+   */
+  syncQuoteInputs(token) {
+    if (this.syncPromise) {
+      this.syncRequested = true;
+      return this.syncPromise;
+    }
+    this.syncPromise = Promise.resolve().then(() => this.syncQuoteInputsUntilFresh(token)).finally(() => {
+      this.syncPromise = null;
+    });
+    return this.syncPromise;
+  }
+  /** Loops until the session state matches the inputs it was built from. */
+  async syncQuoteInputsUntilFresh(token) {
+    while (token === this.runToken && !this.checkout) {
+      this.syncRequested = false;
+      if (!this.destinationToken || this.destinationTokenGeoKey !== this.geoKey()) {
+        if (!await this.resolveDestinationTokenForGeo(token) && !this.syncRequested) return;
+        continue;
+      }
+      if (!await this.fetchQuotesOnce(token) && !this.syncRequested) return;
+    }
+  }
+  /**
+   * Re-resolve the destination token for the current geo. Returns false when
+   * the run ended or the lookup failed.
+   */
+  async resolveDestinationTokenForGeo(token) {
+    this.destinationToken = null;
+    this.destinationTokenGeoKey = null;
+    this.quotes = [];
+    this.selectedQuote = null;
+    this.isRefreshingQuotes = true;
+    this.commit();
+    this.notify();
+    let resolved;
+    try {
+      resolved = await this.resolveDestinationToken();
+    } catch (cause) {
+      if (token !== this.runToken) return false;
+      this.isRefreshingQuotes = false;
+      this.raiseNonFatal(
+        "DESTINATION_TOKEN_FAILED",
+        "No onramp route available for this destination token",
+        cause
+      );
+      return false;
+    }
+    if (token !== this.runToken) return false;
+    this.destinationToken = resolved.token;
+    this.destinationTokenGeoKey = resolved.geoKey;
+    this.isRefreshingQuotes = false;
+    this.commit();
+    this.notify();
+    return true;
+  }
+  /** Returns true when the request inputs moved and quotes must be refetched. */
+  async fetchQuotesOnce(token) {
+    const destinationToken = this.destinationToken;
+    if (!destinationToken) return false;
+    if (this.destinationAmount && !destinationToken.isStablecoin) {
+      this.quotes = [];
+      this.selectedQuote = null;
+      if (this.status === "quoting") this.setStatus("ready");
+      this.raiseNonFatal(
+        "DESTINATION_AMOUNT_UNSUPPORTED",
+        "Buying a fixed destination amount is only supported for stablecoin destinations"
+      );
+      return false;
+    }
+    const activeAmount = this.sourceAmount || this.destinationAmount || "";
+    const amount = parseFloat(activeAmount);
+    if (!Number.isFinite(amount) || amount <= 0) {
+      this.quotes = [];
+      this.selectedQuote = null;
+      if (this.status === "quoting") this.setStatus("ready");
+      this.commit();
+      this.notify();
+      return false;
+    }
+    const requestSourceAmount = this.sourceAmount;
+    const requestDestinationAmount = this.destinationAmount;
+    const requestCurrency = this.sourceCurrency;
+    const requestCountry = this.effectiveCountryCode();
+    const requestSubdivision = this.effectiveSubdivisionCode();
+    this.isRefreshingQuotes = true;
+    this.commit();
+    this.notify();
+    try {
+      const response = await getOnrampQuotes(
+        {
+          country_code: requestCountry,
+          // Exactly one of source_amount / destination_amount (amount mode).
+          ...requestSourceAmount ? { source_amount: requestSourceAmount } : { destination_amount: requestDestinationAmount },
+          source_currency: requestCurrency.toLowerCase(),
+          destination_currency: destinationToken.currency,
+          destination_network: destinationToken.network,
+          subdivision_code: requestSubdivision
+        },
+        this.publishableKey
+      );
+      if (token !== this.runToken || this.checkout) return false;
+      const stale = requestSourceAmount !== this.sourceAmount || requestDestinationAmount !== this.destinationAmount || requestCurrency !== this.sourceCurrency || requestCountry !== this.effectiveCountryCode() || requestSubdivision !== this.effectiveSubdivisionCode();
+      if (!stale) {
+        this.quotes = response.data.map(mapOnrampQuote);
+        this.reconcileSelection();
+        this.quotesUpdatedAt = Date.now();
+        if (this.nonFatalErrorLatch) {
+          this.nonFatalErrorLatch = null;
+          if (this.error && !this.error.fatal) this.error = null;
+        }
+        this.commit();
+        this.emitSessionEvent("onramp_session.quotes_updated" /* QUOTES_UPDATED */, {
+          sessionId: this.id,
+          quotes: this.quotes,
+          selectedQuote: this.selectedQuote
+        });
+      }
+    } catch (cause) {
+      if (token !== this.runToken || this.checkout) return false;
+      console.error("[unifold] failed to fetch onramp quotes:", cause);
+      this.quotes = [];
+      this.selectedQuote = null;
+      this.raiseNonFatal("QUOTES_FAILED", "Failed to fetch onramp quotes", cause);
+    } finally {
+      if (token === this.runToken) {
+        this.isRefreshingQuotes = false;
+        if (this.status === "quoting") this.setStatus("ready");
+        this.commit();
+        this.notify();
+      }
+    }
+    return token === this.runToken && !this.checkout && this.startPromise !== null && (requestSourceAmount !== this.sourceAmount || requestDestinationAmount !== this.destinationAmount || requestCurrency !== this.sourceCurrency || requestCountry !== this.effectiveCountryCode() || requestSubdivision !== this.effectiveSubdivisionCode());
+  }
+  /**
+   * Record a non-fatal error and announce it once per streak — auto-refresh
+   * keeps retrying, and repeating the event every 60s would be noise.
+   */
+  raiseNonFatal(code, message, cause) {
+    const alreadyReported = this.nonFatalErrorLatch === code;
+    if (!alreadyReported) {
+      this.nonFatalErrorLatch = code;
+      this.error = { code, message, fatal: false, cause };
+    }
+    this.commit();
+    if (!alreadyReported) {
+      this.emitSessionEvent("onramp_session.errored" /* SESSION_ERRORED */, {
+        sessionId: this.id,
+        code,
+        message,
+        fatal: false
+      });
+    }
+    this.notify();
+  }
+  /** Sticky manual selection: keep the host's provider while it still quotes. */
+  reconcileSelection() {
+    if (this.manualSelection) {
+      const match = this.quotes.find((quote) => quote.serviceProvider === this.manualSelection);
+      if (match) {
+        this.selectedQuote = match;
+        return;
+      }
+      this.manualSelection = null;
+    }
+    this.selectedQuote = this.quotes[0] ?? null;
+  }
+  // -- Settlement watcher (composed DepositSession) ---------------------------
+  /**
+   * Start (once) the composed {@link DepositSession} that watches the deposit
+   * addresses for the provider's on-chain settlement. Its baseline starts at
+   * checkout time — correct for card rails, where funds can only arrive after
+   * the user pays at the provider. Detection polling, the backend scan nudge
+   * (auto-armed), the lookback window, and `direct_execution.*` semantics are
+   * all inherited rather than reimplemented.
+   */
+  startWatcher() {
+    if (this.watcher) return;
+    const watcher = new DepositSession({
+      publishableKey: this.publishableKey,
+      externalUserId: this.externalUserId,
+      destination: this.destination,
+      confirmationMode: "auto",
+      method: this.method
+    });
+    this.watcher = watcher;
+    const offEvents = watcher.on("*", (event) => {
+      switch (event.type) {
+        case DepositSessionEventType.EXECUTION_DETECTED:
+        case DepositSessionEventType.EXECUTION_UPDATED:
+        case DepositSessionEventType.EXECUTION_SUCCEEDED:
+        case DepositSessionEventType.EXECUTION_FAILED:
+          this.syncFromWatcher(watcher);
+          if (event.type === DepositSessionEventType.EXECUTION_SUCCEEDED && !this.firstSuccess) {
+            this.firstSuccess = event.data.object;
+          }
+          this.forwardExecutionEvent(event.type, event);
+          break;
+        case "deposit_session.errored" /* SESSION_ERRORED */: {
+          const { code, message, fatal } = event.data.object;
+          this.syncFromWatcher(watcher);
+          if (fatal) {
+            this.error = { code, message, fatal: true };
+            this.setStatus("error");
+            this.commit();
+          }
+          this.emitSessionEvent("onramp_session.errored" /* SESSION_ERRORED */, {
+            sessionId: this.id,
+            code,
+            message,
+            fatal
+          });
+          break;
+        }
+        default:
+          break;
+      }
+    });
+    const offSnapshot = watcher.subscribe(() => {
+      this.syncFromWatcher(watcher);
+      this.notify();
+    });
+    this.watcherOffs = [offEvents, offSnapshot];
+    void watcher.start().catch(() => {
+    });
+  }
+  syncFromWatcher(watcher) {
+    if (this.destroyed || this.watcher !== watcher) return;
+    const inner = watcher.getSnapshot();
+    this.executions = inner.executions;
+    this.checkingDeposit = inner.isCheckingDeposit;
+    if (this.status !== "error") {
+      if (inner.error && !inner.error.fatal) {
+        this.error = {
+          code: inner.error.code,
+          message: inner.error.message,
+          fatal: false,
+          cause: inner.error.cause
+        };
+      } else if (!inner.error && this.error && !this.error.fatal) {
+        this.error = null;
+      }
+      this.setStatus(inner.status === "processing" ? "processing" : "awaiting_payment");
+    }
+    this.commit();
+  }
+  forwardExecutionEvent(type, event) {
+    this.emitter.emit(
+      type,
+      {
+        id: event.id,
+        type,
+        created: event.created,
+        method: this.method,
+        data: event.data
+      }
+    );
+  }
+  teardownWatcher() {
+    this.watcherOffs.forEach((off) => off());
+    this.watcherOffs = [];
+    this.watcher?.destroy();
+    this.watcher = null;
+  }
+  // -- Internals --------------------------------------------------------------
+  anyExecutionInFlight() {
+    return this.executions.some((execution) => IN_PROGRESS_STATUSES2.includes(execution.status));
+  }
+  setStatus(status) {
+    this.status = status;
+  }
+  clearRefreshTimer() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+  buildSnapshot() {
+    return {
+      status: this.status,
+      countryCode: this.explicitCountryCode || this.detectedCountryCode || null,
+      addresses: this.addresses,
+      destinationToken: this.destinationToken,
+      quotes: this.quotes,
+      selectedQuote: this.selectedQuote,
+      isQuoteAutoSelected: this.manualSelection === null,
+      canSelectProvider: this.quotes.length > 1,
+      isRefreshingQuotes: this.isRefreshingQuotes,
+      quotesUpdatedAt: this.quotesUpdatedAt,
+      checkout: this.checkout,
+      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);
+      }
+    });
+  }
+  emitSessionEvent(type, object) {
+    this.emitter.emit(type, {
+      id: generatePrefixedKSUID("sevt"),
+      type,
+      created: Math.floor(Date.now() / 1e3),
+      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 a headless fiat-onramp flow controller (buy with card by default). */
+  createOnrampSession(params) {
+    return new OnrampSession({ ...params, publishableKey: this.publishableKey });
   }
   /**
    * Create (idempotently) and return the user's deposit addresses for a
@@ -2734,11 +3871,16 @@ export {
   DepositSession,
   DepositSessionEventType,
   DepositSessionWaitError,
+  DirectExecutionEventType,
   ExecutionStatus,
   IneligibilityReason,
   IntegrationProvider,
   IntegrationTransferError,
   LOOKBACK_MS,
+  OnrampSession,
+  OnrampSessionEventType,
+  OnrampSessionWaitError,
+  QUOTE_REFRESH_INTERVAL_MS,
   SCAN_NUDGE_INTERVAL_MS,
   SOLANA_USDC_ADDRESS,
   StripeApiResponseError,
@@ -2755,6 +3897,7 @@ export {
   createCoinbaseWalletPaySession,
   createDepositAddress,
   createExchangeSession,
+  createIntegrationExchangeSession,
   createIntegrationTransfer,
   createOnrampSession,
   createOnrampVerificationSession,
@@ -2787,12 +3930,14 @@ export {
   getGooglePayProviders,
   getIconUrl,
   getIconUrlWithCdn,
+  getIntegrationExchangeSessionStartUrl,
   getIntegrationExchanges,
   getIntegrationHoldings,
   getIntegrationTransferDefaultToken,
   getIpAddress,
   getOnrampQuotes,
   getOnrampSessionStartUrl,
+  getOnrampSessionStatus,
   getOnrampVerificationSession,
   getPreferredIconUrl,
   getProjectConfig,
@@ -2811,7 +3956,9 @@ export {
   isGooglePayLimitReached,
   isWalletPayLimitReached,
   listPaymentIntentExecutions,
+  mapDefaultOnrampToken,
   mapDirectExecution,
+  mapOnrampQuote,
   mapWalletToDepositAddress,
   pollDirectExecutions,
   queryExecutions,