@pollar/core 0.7.1 → 0.8.1

package/dist/index.mjs

@@ -26,10 +26,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // ../../node_modules/@stellar/freighter-api/build/index.min.js
 var require_index_min = __commonJS({
-  "../../node_modules/@stellar/freighter-api/build/index.min.js"(exports$1, module) {
+  "../../node_modules/@stellar/freighter-api/build/index.min.js"(exports, module) {
     !(function(e, r) {
-      "object" == typeof exports$1 && "object" == typeof module ? module.exports = r() : "function" == typeof define && define.amd ? define([], r) : "object" == typeof exports$1 ? exports$1.freighterApi = r() : e.freighterApi = r();
-    })(exports$1, (() => (() => {
+      "object" == typeof exports && "object" == typeof module ? module.exports = r() : "function" == typeof define && define.amd ? define([], r) : "object" == typeof exports ? exports.freighterApi = r() : e.freighterApi = r();
+    })(exports, (() => (() => {
       var e, r, E = { d: (e2, r2) => {
         for (var o2 in r2) E.o(r2, o2) && !E.o(e2, o2) && Object.defineProperty(e2, o2, { enumerable: true, get: r2[o2] });
       }, o: (e2, r2) => Object.prototype.hasOwnProperty.call(e2, r2), r: (e2) => {
@@ -323,9 +323,7 @@ var WebCryptoKeyManager = class {
      */
     this._initPromise = null;
     if (typeof globalThis.crypto === "undefined" || !globalThis.crypto.subtle) {
-      throw new Error(
-        "[PollarClient:keys] SubtleCrypto is unavailable. DPoP requires a secure context (HTTPS or localhost)."
-      );
+      throw new Error("[PollarClient:keys] SubtleCrypto is unavailable. DPoP requires a secure context (HTTPS or localhost).");
     }
     this.apiKey = apiKey;
   }
@@ -898,14 +896,18 @@ function createApiClient(baseUrl) {
 async function listDistributionRules(api) {
   const { data, error } = await api.GET("/distribution/rules");
   if (!data?.content || error) {
-    throw new Error(error?.error ?? "Failed to list distribution rules");
+    throw new Error(
+      error?.code ?? error?.error ?? "Failed to list distribution rules"
+    );
   }
   return data.content.rules;
 }
 async function claimDistributionRule(api, body) {
   const { data, error } = await api.POST("/distribution/claim", { body });
   if (!data?.content || error) {
-    throw new Error(error?.error ?? "Failed to claim distribution rule");
+    throw new Error(
+      error?.code ?? error?.error ?? "Failed to claim distribution rule"
+    );
   }
   return data.content;
 }
@@ -916,18 +918,18 @@ async function getKycStatus(api, providerId) {
     params: { query: providerId ? { providerId } : {} }
   });
   if (!data?.content || error) {
-    throw new Error(error?.error ?? "Failed to get KYC status");
+    throw new Error(error?.code ?? error?.error ?? "Failed to get KYC status");
   }
   return data.content;
 }
 async function getKycProviders(api, country) {
   const { data, error } = await api.GET("/kyc/providers", { params: { query: { country } } });
-  if (!data?.content || error) throw new Error(error?.error ?? "Failed to get KYC providers");
+  if (!data?.content || error) throw new Error(error?.code ?? error?.error ?? "Failed to get KYC providers");
   return data.content;
 }
 async function startKyc(api, body) {
   const { data, error } = await api.POST("/kyc/start", { body });
-  if (!data?.content || error) throw new Error(error?.error ?? "Failed to start KYC");
+  if (!data?.content || error) throw new Error(error?.code ?? error?.error ?? "Failed to start KYC");
   return data.content;
 }
 async function resolveKyc(api, providerId, level = "basic") {
@@ -949,22 +951,22 @@ async function pollKycStatus(api, providerId, { intervalMs = 3e3, timeoutMs = 3e
 // src/api/endpoints/ramps.ts
 async function getRampsQuote(api, query) {
   const { data, error } = await api.GET("/ramps/quote", { params: { query } });
-  if (!data?.content || error) throw new Error(error?.error ?? "Failed to get ramp quotes");
+  if (!data?.content || error) throw new Error(error?.code ?? error?.error ?? "Failed to get ramp quotes");
   return data.content;
 }
 async function createOnRamp(api, body) {
   const { data, error } = await api.POST("/ramps/onramp", { body });
-  if (!data?.content || error) throw new Error(error?.error ?? "Failed to create onramp");
+  if (!data?.content || error) throw new Error(error?.code ?? error?.error ?? "Failed to create onramp");
   return data.content;
 }
 async function createOffRamp(api, body) {
   const { data, error } = await api.POST("/ramps/offramp", { body });
-  if (!data?.content || error) throw new Error(error?.error ?? "Failed to create offramp");
+  if (!data?.content || error) throw new Error(error?.code ?? error?.error ?? "Failed to create offramp");
   return data.content;
 }
 async function getRampTransaction(api, txId) {
   const { data, error } = await api.GET("/ramps/transaction/{txId}", { params: { path: { txId } } });
-  if (!data?.content || error) throw new Error(error?.error ?? "Failed to get transaction");
+  if (!data?.content || error) throw new Error(error?.code ?? error?.error ?? "Failed to get transaction");
   return data.content;
 }
 async function pollRampTransaction(api, txId, { intervalMs = 5e3, timeoutMs = 6e5 } = {}) {
@@ -977,6 +979,26 @@ async function pollRampTransaction(api, txId, { intervalMs = 5e3, timeoutMs = 6e
   throw new Error("Ramp transaction polling timed out");
 }
 
+// src/lib/random-uuid.ts
+function randomUUID() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  if (c && typeof c.getRandomValues === "function") {
+    const bytes = new Uint8Array(16);
+    c.getRandomValues(bytes);
+    bytes[6] = bytes[6] & 15 | 64;
+    bytes[8] = bytes[8] & 63 | 128;
+    const hex = [];
+    for (let i = 0; i < 16; i++) hex.push(bytes[i].toString(16).padStart(2, "0"));
+    return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+  }
+  throw new Error(
+    "[PollarClient] No secure random source available (crypto.randomUUID / crypto.getRandomValues). DPoP requires a secure context (HTTPS) or, in React Native, the `react-native-get-random-values` polyfill."
+  );
+}
+
 // src/dpop.ts
 async function buildProof(args, keyManager) {
   const jwk = await keyManager.getPublicJwk();
@@ -986,7 +1008,7 @@ async function buildProof(args, keyManager) {
     jwk
   };
   const payload = {
-    jti: generateJti(),
+    jti: randomUUID(),
     htm: args.htm.toUpperCase(),
     htu: normalizeHtu(args.htu),
     iat: Math.floor(Date.now() / 1e3)
@@ -1020,52 +1042,6 @@ function normalizeHtu(rawUrl) {
   const portPart = port ? `:${port}` : "";
   return `${scheme}//${host}${portPart}${url.pathname}`;
 }
-function generateJti() {
-  const c = globalThis.crypto;
-  if (c && typeof c.randomUUID === "function") {
-    return c.randomUUID();
-  }
-  if (c && typeof c.getRandomValues === "function") {
-    const bytes = new Uint8Array(16);
-    c.getRandomValues(bytes);
-    bytes[6] = bytes[6] & 15 | 64;
-    bytes[8] = bytes[8] & 63 | 128;
-    const hex = [];
-    for (let i = 0; i < 16; i++) hex.push(bytes[i].toString(16).padStart(2, "0"));
-    return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
-  }
-  throw new Error(
-    "[PollarClient:dpop] No secure random source available (crypto.randomUUID / crypto.getRandomValues). DPoP requires a secure context (HTTPS) or, in React Native, the `react-native-get-random-values` polyfill."
-  );
-}
-
-// src/stellar/StellarClient.ts
-var HORIZON_URLS = {
-  mainnet: "https://horizon.stellar.org",
-  testnet: "https://horizon-testnet.stellar.org"
-};
-var StellarClient = class {
-  constructor(config) {
-    this.horizonUrl = typeof config === "string" ? HORIZON_URLS[config] : config.horizonUrl;
-  }
-  async submitTransaction(signedXdr) {
-    try {
-      const response = await fetch(`${this.horizonUrl}/transactions`, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: new URLSearchParams({ tx: signedXdr })
-      });
-      if (!response.ok) {
-        const body = await response.json().catch(() => ({}));
-        return { success: false, errorCode: body.extras?.result_codes?.transaction ?? "HORIZON_ERROR" };
-      }
-      const data = await response.json();
-      return { success: true, hash: data.hash };
-    } catch {
-      return { success: false, errorCode: "NETWORK_ERROR" };
-    }
-  }
-};
 
 // src/storage/web.ts
 var LOG_PREFIX = "[PollarClient:storage]";
@@ -1154,9 +1130,62 @@ function defaultStorage(options = {}) {
   return createLocalStorageAdapter(options);
 }
 
+// src/visibility/noop.ts
+function createNoopVisibilityProvider() {
+  return {
+    isVisible: () => true,
+    onChange: () => () => {
+    }
+  };
+}
+
+// src/visibility/web.ts
+function createWebVisibilityProvider() {
+  const isVisibleNow = () => typeof document === "undefined" || document.visibilityState === "visible";
+  return {
+    isVisible: isVisibleNow,
+    onChange: (cb) => {
+      if (typeof window === "undefined" || typeof document === "undefined") {
+        return () => {
+        };
+      }
+      let last = isVisibleNow();
+      const handler = () => {
+        const next = isVisibleNow();
+        if (next !== last) {
+          last = next;
+          cb(next);
+        }
+      };
+      document.addEventListener("visibilitychange", handler);
+      window.addEventListener("pageshow", handler);
+      window.addEventListener("pagehide", handler);
+      window.addEventListener("focus", handler);
+      window.addEventListener("blur", handler);
+      return () => {
+        document.removeEventListener("visibilitychange", handler);
+        window.removeEventListener("pageshow", handler);
+        window.removeEventListener("pagehide", handler);
+        window.removeEventListener("focus", handler);
+        window.removeEventListener("blur", handler);
+      };
+    }
+  };
+}
+
+// src/visibility/autodetect.ts
+function defaultVisibilityProvider() {
+  if (typeof document !== "undefined" && typeof window !== "undefined") {
+    return createWebVisibilityProvider();
+  }
+  return createNoopVisibilityProvider();
+}
+
 // src/types.ts
 var AUTH_ERROR_CODES = {
   SESSION_CREATE_FAILED: "SESSION_CREATE_FAILED",
+  SESSION_EXPIRED: "SESSION_EXPIRED",
+  SESSION_INVALID: "SESSION_INVALID",
   EMAIL_SEND_FAILED: "EMAIL_SEND_FAILED",
   EMAIL_VERIFY_FAILED: "EMAIL_VERIFY_FAILED",
   EMAIL_CODE_EXPIRED: "EMAIL_CODE_EXPIRED",
@@ -1164,6 +1193,7 @@ var AUTH_ERROR_CODES = {
   AUTH_FAILED: "AUTH_FAILED",
   WALLET_CONNECT_FAILED: "WALLET_CONNECT_FAILED",
   WALLET_AUTH_FAILED: "WALLET_AUTH_FAILED",
+  WALLET_RESOLVER_TIMEOUT: "WALLET_RESOLVER_TIMEOUT",
   UNEXPECTED_ERROR: "UNEXPECTED_ERROR"
 };
 var PollarFlowError = class extends Error {
@@ -1469,7 +1499,32 @@ async function readWalletType(storage, apiKeyHash) {
   return storage.get(walletTypeStorageKey(apiKeyHash));
 }
 
+// src/lib/abort.ts
+function abortError() {
+  if (typeof DOMException !== "undefined") {
+    return new DOMException("Aborted", "AbortError");
+  }
+  const err = new Error("Aborted");
+  err.name = "AbortError";
+  return err;
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError();
+}
+
 // src/client/stream.ts
+var SessionStatusError = class extends Error {
+  constructor(code) {
+    super(`[PollarClient] Session status terminal: ${code}`);
+    this.code = code;
+    this.name = "SessionStatusError";
+  }
+};
+function terminalStatusCode(parsed) {
+  const err = parsed?.error;
+  if (err === "INVALID_CLIENT_SESSION_ID" || err === "EXPIRED_CLIENT_ID") return err;
+  return null;
+}
 function abortableDelay(ms, signal) {
   return new Promise((resolve, reject) => {
     const t = setTimeout(resolve, ms);
@@ -1477,7 +1532,7 @@ function abortableDelay(ms, signal) {
       "abort",
       () => {
         clearTimeout(t);
-        reject(new DOMException("Aborted", "AbortError"));
+        reject(abortError());
       },
       { once: true }
     );
@@ -1492,7 +1547,7 @@ async function streamUntilFound(api, clientSessionId, check, retryDelayMs = 200,
     else await new Promise((r) => setTimeout(r, ms));
   };
   while (true) {
-    signal?.throwIfAborted();
+    throwIfAborted(signal);
     let data, error;
     try {
       ({ data, error } = await api.GET("/auth/session/status/{clientSessionId}", {
@@ -1515,7 +1570,7 @@ async function streamUntilFound(api, clientSessionId, check, retryDelayMs = 200,
     let sawAnyChunk = false;
     try {
       while (true) {
-        signal?.throwIfAborted();
+        throwIfAborted(signal);
         const { done, value } = await reader.read();
         if (done) {
           streamDone = true;
@@ -1526,17 +1581,22 @@ async function streamUntilFound(api, clientSessionId, check, retryDelayMs = 200,
         for (const message of chunk.split("\n\n").filter(Boolean)) {
           const dataLine = message.split("\n").find((l) => l.startsWith("data:"));
           if (!dataLine) continue;
+          let parsed;
           try {
-            const parsed = JSON.parse(dataLine.slice("data:".length).trim());
-            if (check(parsed)) {
-              return parsed;
-            }
+            parsed = JSON.parse(dataLine.slice("data:".length).trim());
           } catch {
+            continue;
+          }
+          const terminal = terminalStatusCode(parsed);
+          if (terminal) throw new SessionStatusError(terminal);
+          if (check(parsed)) {
+            return parsed;
           }
         }
       }
     } catch (e) {
       if (e instanceof Error && e.name === "AbortError") throw e;
+      if (e instanceof SessionStatusError) throw e;
       console.warn(e);
     } finally {
       reader.releaseLock();
@@ -1547,14 +1607,74 @@ async function streamUntilFound(api, clientSessionId, check, retryDelayMs = 200,
     if (delay) await sleep(delay);
   }
 }
+async function pollUntilFound(baseUrl, clientSessionId, check, intervalMs = 500, signal) {
+  const url = `${baseUrl}/auth/session/status/${encodeURIComponent(clientSessionId)}/poll`;
+  let backoff = intervalMs;
+  const sleep = async (ms) => {
+    if (ms <= 0) return;
+    if (signal) await abortableDelay(ms, signal);
+    else await new Promise((r) => setTimeout(r, ms));
+  };
+  while (true) {
+    throwIfAborted(signal);
+    let envelope = null;
+    let httpStatus = 0;
+    try {
+      const response = await fetch(url, { headers: { accept: "application/json" }, signal: signal ?? null });
+      httpStatus = response.status;
+      envelope = await response.json().catch(() => null);
+    } catch (e) {
+      if (e instanceof Error && e.name === "AbortError") throw e;
+      console.warn(e);
+    }
+    if (httpStatus === 404 || envelope?.code === "INVALID_CLIENT_SESSION_ID") {
+      throw new SessionStatusError("INVALID_CLIENT_SESSION_ID");
+    }
+    if (httpStatus === 410 || envelope?.code === "EXPIRED_CLIENT_ID") {
+      throw new SessionStatusError("EXPIRED_CLIENT_ID");
+    }
+    if (envelope?.success && envelope.content && check(envelope.content)) {
+      return envelope.content;
+    }
+    if (envelope) backoff = intervalMs;
+    else backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+    await sleep(backoff);
+  }
+}
+function waitForSessionReady(args) {
+  const { api, baseUrl, clientSessionId, check, useStreaming, retryDelayMs, signal } = args;
+  return useStreaming ? streamUntilFound(api, clientSessionId, check, retryDelayMs ?? 200, signal) : pollUntilFound(baseUrl, clientSessionId, check, retryDelayMs ?? 500, signal);
+}
 
 // src/client/auth/authenticate.ts
 async function authenticate(clientSessionId, deps, expectedWallet) {
-  const { api, signal, setAuthState, storeSession, clearSession } = deps;
+  const { api, basePath, useStreaming, signal, setAuthState, storeSession, clearSession } = deps;
   setAuthState({ step: "authenticating" });
-  await streamUntilFound(api, clientSessionId, (data2) => data2?.status === "READY", 200, signal);
+  try {
+    await waitForSessionReady({
+      api,
+      baseUrl: basePath,
+      clientSessionId,
+      check: (data2) => data2?.status === "READY",
+      useStreaming,
+      signal
+    });
+  } catch (err) {
+    if (err instanceof SessionStatusError) {
+      const expired = err.code === "EXPIRED_CLIENT_ID";
+      setAuthState({
+        step: "error",
+        previousStep: "authenticating",
+        message: expired ? "Login session expired \u2014 please try again" : "Login session is no longer valid \u2014 please try again",
+        errorCode: expired ? AUTH_ERROR_CODES.SESSION_EXPIRED : AUTH_ERROR_CODES.SESSION_INVALID
+      });
+      await clearSession();
+      return;
+    }
+    throw err;
+  }
   const dpopJwk = await deps.getPublicJwk();
-  const { data, error } = await api.POST("/auth/login", {
+  const { data } = await api.POST("/auth/login", {
     body: {
       clientSessionId,
       dpopJwk,
@@ -1676,26 +1796,36 @@ function severOpener(popup) {
   } catch {
   }
 }
-async function loginOAuth(provider, deps) {
-  const { setAuthState, basePath, apiKey } = deps;
-  const popup = window.open("about:blank", "_blank");
+var defaultWebOAuthOpener = async ({ getUrl }) => {
+  const popup = typeof window !== "undefined" ? window.open("about:blank", "_blank") : null;
   severOpener(popup);
-  const clientSessionId = await createAuthSession(deps);
-  if (!clientSessionId) {
+  const url = await getUrl();
+  if (!url) {
     popup?.close();
     return;
   }
-  setAuthState({ step: "opening_oauth", provider });
-  const url = new URL(`${basePath}/auth/${provider}`);
-  url.searchParams.set("api_key", apiKey);
-  url.searchParams.set("client_session_id", clientSessionId);
-  url.searchParams.set("redirect_uri", window.location.origin);
   if (popup) {
-    popup.location.href = url.toString();
+    popup.location.href = url;
     severOpener(popup);
-  } else {
-    window.open(url.toString(), "_blank", "noopener,noreferrer");
+  } else if (typeof window !== "undefined") {
+    window.open(url, "_blank", "noopener,noreferrer");
   }
+};
+async function loginOAuth(provider, deps) {
+  const { setAuthState, basePath, apiKey, openAuthUrl, redirectUri, signal } = deps;
+  let clientSessionId = null;
+  const getUrl = async () => {
+    clientSessionId = await createAuthSession(deps);
+    if (!clientSessionId) return null;
+    setAuthState({ step: "opening_oauth", provider });
+    const url = new URL(`${basePath}/auth/${provider}`);
+    url.searchParams.set("api_key", apiKey);
+    url.searchParams.set("client_session_id", clientSessionId);
+    url.searchParams.set("redirect_uri", redirectUri);
+    return url.toString();
+  };
+  await openAuthUrl({ provider, getUrl, redirectUri, signal });
+  if (!clientSessionId) return;
   await authenticate(clientSessionId, deps);
 }
 
@@ -1705,10 +1835,10 @@ function withSignal(promise, signal) {
     promise,
     new Promise((_, reject) => {
       if (signal.aborted) {
-        reject(new DOMException("Aborted", "AbortError"));
+        reject(abortError());
         return;
       }
-      signal.addEventListener("abort", () => reject(new DOMException("Aborted", "AbortError")), { once: true });
+      signal.addEventListener("abort", () => reject(abortError()), { once: true });
     })
   ]);
 }
@@ -1719,7 +1849,7 @@ async function loginWallet(type, deps) {
   let connectedWallet;
   try {
     setAuthState({ step: "connecting_wallet", walletType: type });
-    const adapter = await deps.resolveWalletAdapter(type);
+    const adapter = await withSignal(deps.resolveWalletAdapter(type), signal);
     const available = await withSignal(adapter.isAvailable(), signal);
     if (!available) {
       setAuthState({ step: "wallet_not_installed", walletType: type });
@@ -1756,6 +1886,9 @@ async function loginWallet(type, deps) {
 
 // src/client/client.ts
 var isBrowser = typeof window !== "undefined" && typeof localStorage !== "undefined";
+var isReactNative = typeof navigator !== "undefined" && navigator.product === "ReactNative";
+var isClientRuntime = isBrowser || isReactNative;
+var REFRESH_SKEW_SECONDS = 60;
 function warnServerSide(method) {
   console.warn(
     `[PollarClient] ${method}() called server-side \u2014 browser APIs unavailable. Use PollarClient only in Client Components.`
@@ -1783,6 +1916,11 @@ var PollarClient = class {
     /** Singleton in-flight refresh — concurrent 401s coalesce into one /auth/refresh call. */
     this._refreshPromise = null;
     this._storageEventHandler = null;
+    /** Updated by the request middleware. Read by the silent-refresh scheduler
+     *  to skip proactive refreshes after `maxIdleMs` of no HTTP activity. */
+    this._lastRequestAt = Date.now();
+    this._refreshTimer = null;
+    this._visibilityUnsubscribe = null;
     this._transactionState = null;
     this._transactionStateListeners = /* @__PURE__ */ new Set();
     this._txHistoryState = { step: "idle" };
@@ -1793,19 +1931,38 @@ var PollarClient = class {
     this._authStateListeners = /* @__PURE__ */ new Set();
     this._networkState = { step: "idle" };
     this._networkStateListeners = /* @__PURE__ */ new Set();
+    /**
+     * Latched once the storage adapter degrades. We dedupe (the adapter only
+     * fires once anyway) and use it to replay state to late-subscribers — same
+     * pattern as `onAuthStateChange` replaying `_authState` on subscribe.
+     * Only populated when the SDK constructed the default storage adapter; if
+     * the consumer passes `config.storage`, they own degradation notifications.
+     */
+    this._storageDegraded = null;
+    this._storageDegradeListeners = /* @__PURE__ */ new Set();
     this._walletAdapter = null;
     this._loginController = null;
     this.apiKey = config.apiKey;
-    this.id = crypto.randomUUID();
+    this.id = randomUUID();
     this.basePath = `${config.baseUrl || "https://sdk.api.pollar.xyz"}/v1`;
-    this._storage = config.storage ?? defaultStorage(config.onStorageDegrade ? { onDegrade: config.onStorageDegrade } : void 0);
+    this._storage = config.storage ?? defaultStorage({
+      onDegrade: (reason, error) => {
+        config.onStorageDegrade?.(reason, error);
+        this._dispatchStorageDegrade(reason, error);
+      }
+    });
     this._keyManager = config.keyManager ?? defaultKeyManager(this._storage, config.apiKey);
     this._walletAdapterResolver = config.walletAdapter ?? null;
+    this._walletResolverTimeoutMs = config.walletResolverTimeoutMs ?? 5e3;
     this._deviceLabel = config.deviceLabel;
+    this._visibilityProvider = config.visibilityProvider ?? defaultVisibilityProvider();
+    this._maxIdleMs = config.maxIdleMs;
+    this._openAuthUrl = config.openAuthUrl ?? defaultWebOAuthOpener;
+    this._oauthRedirectUri = config.oauthRedirectUri ?? (isBrowser ? window.location.origin : "");
     this._api = createApiClient(this.basePath);
     this._wireMiddlewares();
     this._networkState = { step: "connected", network: config.stellarNetwork ?? "testnet" };
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("constructor");
       this._initialized = Promise.resolve();
       return;
@@ -1831,7 +1988,7 @@ var PollarClient = class {
   // ─── Lifecycle ────────────────────────────────────────────────────────────
   async _initialize() {
     this._apiKeyHash = await hashApiKey(this.apiKey);
-    if (typeof window !== "undefined") {
+    if (isBrowser) {
       const sessionKey = sessionStorageKey(this._apiKeyHash);
       const handler = (e) => {
         if (e.key === sessionKey) {
@@ -1847,15 +2004,23 @@ var PollarClient = class {
       console.warn("[PollarClient] KeyManager init failed; DPoP unavailable for this session", err);
     }
     await this._restoreSession();
+    this._visibilityUnsubscribe = this._visibilityProvider.onChange((visible) => {
+      if (visible) void this._maybeProactiveRefresh();
+    });
   }
   /** Detach the cross-tab storage listener and abort any in-flight login. */
   destroy() {
-    if (this._storageEventHandler && typeof window !== "undefined") {
+    if (this._storageEventHandler && isBrowser) {
       window.removeEventListener("storage", this._storageEventHandler);
       this._storageEventHandler = null;
     }
     this._loginController?.abort();
     this._loginController = null;
+    this._clearRefreshTimer();
+    if (this._visibilityUnsubscribe) {
+      this._visibilityUnsubscribe();
+      this._visibilityUnsubscribe = null;
+    }
   }
   // ─── Middlewares (DPoP + auto-refresh) ────────────────────────────────────
   _wireMiddlewares() {
@@ -1863,6 +2028,7 @@ var PollarClient = class {
     this._api.use({
       onRequest: async ({ request }) => {
         request.headers.set("x-pollar-api-key", self.apiKey);
+        self._lastRequestAt = Date.now();
         await self._initialized;
         if (request.body !== null) {
           try {
@@ -1893,15 +2059,22 @@ var PollarClient = class {
         const newNonce = response.headers.get("DPoP-Nonce");
         if (newNonce) self._dpopNonce = newNonce;
         if (response.status !== 401) return response;
-        if (request.url.includes("/auth/refresh")) return response;
         const wwwAuth = response.headers.get("WWW-Authenticate") ?? "";
         const isNonceChallenge = wwwAuth.includes("use_dpop_nonce");
+        if (request.url.includes("/auth/refresh")) {
+          if (isNonceChallenge) return self._retryRequest(request);
+          return response;
+        }
         if (!isNonceChallenge) {
           try {
             await self.refresh();
           } catch {
             return response;
           }
+          const method = request.method.toUpperCase();
+          if (method !== "GET" && method !== "HEAD") {
+            return response;
+          }
         }
         return self._retryRequest(request);
       }
@@ -1926,14 +2099,22 @@ var PollarClient = class {
   }
   async _retryRequest(originalRequest) {
     const headers = new Headers(originalRequest.headers);
-    const accessToken = this._session?.token?.accessToken;
-    if (accessToken) {
-      const proof = await this._buildProofForRequest(originalRequest, accessToken);
-      if (proof) {
-        headers.set("Authorization", `DPoP ${accessToken}`);
-        headers.set("DPoP", proof);
-      } else {
-        headers.set("Authorization", `Bearer ${accessToken}`);
+    const isRefresh = originalRequest.url.includes("/auth/refresh");
+    if (isRefresh) {
+      const proof = await this._buildProofForRequest(originalRequest, void 0);
+      headers.delete("Authorization");
+      if (proof) headers.set("DPoP", proof);
+      else headers.delete("DPoP");
+    } else {
+      const accessToken = this._session?.token?.accessToken;
+      if (accessToken) {
+        const proof = await this._buildProofForRequest(originalRequest, accessToken);
+        if (proof) {
+          headers.set("Authorization", `DPoP ${accessToken}`);
+          headers.set("DPoP", proof);
+        } else {
+          headers.set("Authorization", `Bearer ${accessToken}`);
+        }
       }
     }
     const cachedBody = this._requestBodyCache.get(originalRequest);
@@ -2004,6 +2185,65 @@ var PollarClient = class {
       } catch (err) {
         console.error("[PollarClient] Failed to persist refreshed session", err);
       }
+      this._scheduleNextRefresh();
+    }
+  }
+  // ─── Silent refresh scheduler ────────────────────────────────────────────────
+  /**
+   * Arm a single setTimeout to fire shortly before the current access token
+   * expires. Idempotent — clearing any previous timer first. Safe to call
+   * from any session-write site (initial login, restore-from-storage, after
+   * a successful rotation). No-op if there's no session in memory.
+   *
+   * Browser/RN background-tab throttling makes long-running setTimeouts
+   * unreliable on their own; the `visibilitychange` listener compensates by
+   * re-invoking `_maybeProactiveRefresh` whenever the app comes back to the
+   * foreground, catching any timer that fired late or never fired at all.
+   */
+  _scheduleNextRefresh() {
+    this._clearRefreshTimer();
+    const expiresAt = this._session?.token?.expiresAt;
+    if (typeof expiresAt !== "number") return;
+    const dueInMs = Math.max(0, (expiresAt - Math.floor(Date.now() / 1e3) - REFRESH_SKEW_SECONDS) * 1e3);
+    this._refreshTimer = setTimeout(() => {
+      void this._maybeProactiveRefresh();
+    }, dueInMs);
+  }
+  /**
+   * Decide whether to actually run a refresh right now. Called both from the
+   * scheduler timer and from the visibility-change listener.
+   *
+   * Skip if:
+   *   - no session / no RT (nothing to refresh)
+   *   - app is hidden — wait for the visibility listener to re-trigger us
+   *   - `maxIdleMs` configured and no client request since that window — let
+   *     the next reactive 401-refresh handle it whenever the user comes back
+   *   - the AT still has more than `REFRESH_SKEW_SECONDS` of life — reschedule
+   *
+   * Otherwise call `refresh()`, which uses the existing in-flight singleton
+   * so we never collide with a reactive 401-triggered refresh. On failure,
+   * `_doRefresh` already calls `_clearSession`, so auth-state listeners see
+   * `step:'idle'` — no extra event dispatch needed here.
+   */
+  async _maybeProactiveRefresh() {
+    if (!this._session?.token?.refreshToken) return;
+    if (!this._visibilityProvider.isVisible()) return;
+    if (this._maxIdleMs !== void 0 && Date.now() - this._lastRequestAt > this._maxIdleMs) return;
+    const expiresAt = this._session.token.expiresAt;
+    if (Math.floor(Date.now() / 1e3) < expiresAt - REFRESH_SKEW_SECONDS) {
+      this._scheduleNextRefresh();
+      return;
+    }
+    try {
+      await this.refresh();
+    } catch (err) {
+      console.warn("[PollarClient] Proactive refresh failed; session cleared", err);
+    }
+  }
+  _clearRefreshTimer() {
+    if (this._refreshTimer !== null) {
+      clearTimeout(this._refreshTimer);
+      this._refreshTimer = null;
     }
   }
   // ─── Auth state ──────────────────────────────────────────────────────────────
@@ -2015,13 +2255,45 @@ var PollarClient = class {
     cb(this._authState);
     return () => this._authStateListeners.delete(cb);
   }
+  /**
+   * Subscribe to persistent-storage degradation (Safari private mode,
+   * sandboxed iframes, quota errors, etc.). The SDK keeps running off
+   * in-memory storage after degrade, but sessions won't survive reload — a
+   * host UI typically wants to show "your session won't be saved" so the
+   * user isn't blindsided after a refresh.
+   *
+   * Fires at most once per client lifetime (the underlying adapter dedupes).
+   * Late subscribers receive the latched state synchronously on subscribe.
+   *
+   * Only fires when the SDK constructs the default storage adapter. If you
+   * pass a custom `config.storage`, wire your own notification path through
+   * that adapter's API — the SDK has no hook into it.
+   */
+  onStorageDegrade(cb) {
+    this._storageDegradeListeners.add(cb);
+    if (this._storageDegraded) {
+      cb(this._storageDegraded.reason, this._storageDegraded.error);
+    }
+    return () => this._storageDegradeListeners.delete(cb);
+  }
+  _dispatchStorageDegrade(reason, error) {
+    if (this._storageDegraded) return;
+    this._storageDegraded = { reason, error };
+    for (const cb of this._storageDegradeListeners) {
+      try {
+        cb(reason, error);
+      } catch (err) {
+        console.error("[PollarClient] onStorageDegrade listener threw", err);
+      }
+    }
+  }
   /** PII (email, names, avatar, providers). Held in memory only — never persisted. */
   getUserProfile() {
     return this._profile;
   }
   // ─── Login (unified entry point) ─────────────────────────────────────────
   login(options) {
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("login");
       return;
     }
@@ -2032,7 +2304,9 @@ var PollarClient = class {
         loginOAuth(options.provider, {
           ...deps,
           basePath: this.basePath,
-          apiKey: this.apiKey
+          apiKey: this.apiKey,
+          openAuthUrl: this._openAuthUrl,
+          redirectUri: this._oauthRedirectUri
         }).catch((err) => this._handleFlowError(err));
       } else if (options.provider === "email") {
         const { email } = options;
@@ -2048,7 +2322,7 @@ var PollarClient = class {
   }
   // ─── Email OTP flow (3 steps) ─────────────────────────────────────────────
   beginEmailLogin() {
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("beginEmailLogin");
       return;
     }
@@ -2056,7 +2330,7 @@ var PollarClient = class {
     initEmailSession(this._flowDeps(controller.signal)).catch((err) => this._handleFlowError(err));
   }
   sendEmailCode(email) {
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("sendEmailCode");
       return;
     }
@@ -2068,7 +2342,7 @@ var PollarClient = class {
     sendEmailCode(email, clientSessionId, this._flowDeps(signal)).catch((err) => this._handleFlowError(err));
   }
   verifyEmailCode(code) {
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("verifyEmailCode");
       return;
     }
@@ -2086,7 +2360,7 @@ var PollarClient = class {
   }
   // ─── Wallet flow (single call) ────────────────────────────────────────────
   loginWallet(type) {
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("loginWallet");
       return;
     }
@@ -2112,7 +2386,7 @@ var PollarClient = class {
    * across all devices.
    */
   async logout(options = {}) {
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("logout");
       return;
     }
@@ -2142,7 +2416,7 @@ var PollarClient = class {
    * `current` flag identifies which entry corresponds to this client.
    */
   async listSessions() {
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("listSessions");
       return [];
     }
@@ -2161,7 +2435,7 @@ var PollarClient = class {
    * does NOT clear local state — call `logout()` for that case.
    */
   async revokeSession(familyId) {
-    if (!isBrowser) {
+    if (!isClientRuntime) {
       warnServerSide("revokeSession");
       return;
     }
@@ -2251,10 +2525,16 @@ var PollarClient = class {
     }
   }
   // ─── Transactions ─────────────────────────────────────────────────────────
+  /**
+   * Builds an unsigned XDR. Drives `_setTransactionState` for modal-style UIs
+   * AND returns a {@link BuildOutcome} so headless callers can `await` and
+   * inspect the result without subscribing to state changes.
+   */
   async buildTx(operation, params, options) {
     if (!this._session?.wallet?.publicKey) {
-      this._setTransactionState({ step: "error", details: "No wallet connected" });
-      return;
+      const details = "No wallet connected";
+      this._setTransactionState({ step: "error", phase: "building", details });
+      return { status: "error", details };
     }
     const body = {
       network: this.getNetwork(),
@@ -2268,40 +2548,194 @@ var PollarClient = class {
       const { data, error } = await this._api.POST("/tx/build", { body });
       if (!error && data?.success && data.content) {
         this._setTransactionState({ step: "built", buildData: data.content });
-      } else {
-        const details = error?.details;
-        this._setTransactionState({ step: "error", ...details && { details } });
+        return { status: "built", buildData: data.content };
       }
+      const details = error?.details;
+      this._setTransactionState({ step: "error", phase: "building", ...details && { details } });
+      return { status: "error", ...details && { details } };
     } catch (err) {
       console.error("[PollarClient] buildTx failed", err);
-      this._setTransactionState({ step: "error" });
+      this._setTransactionState({ step: "error", phase: "building" });
+      return { status: "error" };
     }
   }
   getWalletType() {
     return this._walletAdapter?.type ?? null;
   }
-  async signAndSubmitTx(unsignedXdr) {
-    const state = this._transactionState;
-    const buildData = state?.step === "built" ? state.buildData : state?.step === "error" ? state.buildData : void 0;
-    const stateExtra = buildData ? { buildData } : { external: true };
-    this._setTransactionState({ step: "signing", ...stateExtra });
-    const accountToSign = this._session?.wallet?.publicKey;
+  /**
+   * Signs the given unsigned XDR and returns the signed XDR.
+   *
+   * - External wallets: signs locally via the wallet adapter.
+   * - Custodial wallets: posts to `/tx/sign`. The backend signs (through
+   *   wallet-service or the app's customer-managed adapter) and returns the
+   *   signed XDR plus an `idempotencyKey` the caller should echo back to
+   *   `submitTx`.
+   *
+   * Drives `_setTransactionState`: emits `signing` while in flight and
+   * `signed` on success (or `error[phase: 'signing']` on failure). `buildData`
+   * is threaded through if the consumer previously called `buildTx`.
+   */
+  async signTx(unsignedXdr) {
+    const buildData = this._currentBuildData();
+    this._setTransactionState({ step: "signing", ...buildData && { buildData } });
     if (this._walletAdapter) {
+      const accountToSign = this._session?.wallet?.publicKey;
+      const signOpts = accountToSign ? { networkPassphrase: this._networkPassphrase(), accountToSign } : { networkPassphrase: this._networkPassphrase() };
       try {
-        const signOpts = accountToSign ? { networkPassphrase: this._networkPassphrase(), accountToSign } : { networkPassphrase: this._networkPassphrase() };
         const { signedTxXdr } = await this._walletAdapter.signTransaction(unsignedXdr, signOpts);
-        const stellarClient = new StellarClient(this.getNetwork());
-        const result = await stellarClient.submitTransaction(signedTxXdr);
-        if (result.success) {
-          this._setTransactionState({ step: "success", ...stateExtra, hash: result.hash });
-        } else {
-          this._setTransactionState({ step: "error", ...stateExtra, details: result.errorCode });
+        this._setTransactionState({
+          step: "signed",
+          signedXdr: signedTxXdr,
+          ...buildData && { buildData }
+        });
+        return { status: "signed", signedXdr: signedTxXdr };
+      } catch (err) {
+        const details = err instanceof Error ? err.message : void 0;
+        this._setTransactionState({
+          step: "error",
+          phase: "signing",
+          ...buildData && { buildData },
+          ...details && { details }
+        });
+        return { status: "error", ...details && { details } };
+      }
+    }
+    const publicKey = this._session?.wallet?.publicKey ?? "";
+    try {
+      const { data, error } = await this._api.POST("/tx/sign", {
+        body: { network: this.getNetwork(), publicKey, unsignedXdr }
+      });
+      if (!error && data?.success && data.content?.signedXdr) {
+        const { signedXdr, idempotencyKey } = data.content;
+        this._setTransactionState({
+          step: "signed",
+          signedXdr,
+          submissionToken: idempotencyKey,
+          ...buildData && { buildData }
+        });
+        return { status: "signed", signedXdr, submissionToken: idempotencyKey };
+      }
+      const details = error?.details;
+      this._setTransactionState({
+        step: "error",
+        phase: "signing",
+        ...buildData && { buildData },
+        ...details && { details }
+      });
+      return { status: "error", ...details && { details } };
+    } catch (err) {
+      const details = err instanceof Error ? err.message : void 0;
+      this._setTransactionState({
+        step: "error",
+        phase: "signing",
+        ...buildData && { buildData },
+        ...details && { details }
+      });
+      return { status: "error", ...details && { details } };
+    }
+  }
+  /**
+   * Submits a signed XDR via `/tx/submit` regardless of wallet type
+   * (custodial or external). Routing through sdk-api gives us:
+   *   - End-to-end tx_records persistence with full phase lifecycle so the
+   *     developer dashboard can show every tx (both custodial and external
+   *     wallet flows) at `/apps/:id/monitor/transactions`.
+   *   - Idempotency tracking via `submissionToken` (returned by `signTx`).
+   *   - A single response shape (SUCCESS / PENDING / FAILED) shared by both
+   *     flows — previously external wallets could only return SUCCESS or
+   *     error since the direct-to-Horizon path was synchronous.
+   *
+   * The extra hop adds ~50–150 ms vs. the legacy direct-Horizon path; the
+   * persistence + observability win is worth it.
+   *
+   * Drives `_setTransactionState`: emits `submitting` while in flight,
+   * `submitted` on Horizon ack (pending), `success` on ledger confirmation,
+   * or `error[phase: 'submitting']` on failure.
+   */
+  async submitTx(signedXdr, opts) {
+    const buildData = this._currentBuildData();
+    const outcomeExtra = buildData ? { buildData } : {};
+    this._setTransactionState({ step: "submitting", signedXdr, ...buildData && { buildData } });
+    const publicKey = this._session?.wallet?.publicKey ?? "";
+    try {
+      const { data, error } = await this._api.POST("/tx/submit", {
+        body: {
+          network: this.getNetwork(),
+          publicKey,
+          signedXdr,
+          ...opts?.submissionToken && { idempotencyKey: opts.submissionToken }
         }
-      } catch {
-        this._setTransactionState({ step: "error", ...stateExtra });
+      });
+      if (!error && data?.success && data.content) {
+        const { hash, status: backendStatus, resultCode } = data.content;
+        if (backendStatus === "SUCCESS") {
+          this._setTransactionState({ step: "success", hash, ...buildData && { buildData } });
+          return { status: "success", hash, ...outcomeExtra };
+        }
+        if (backendStatus === "PENDING") {
+          this._setTransactionState({ step: "submitted", hash, ...buildData && { buildData } });
+          return { status: "pending", hash, ...outcomeExtra };
+        }
+        this._setTransactionState({
+          step: "error",
+          phase: "submitting",
+          ...buildData && { buildData },
+          ...resultCode && { details: resultCode }
+        });
+        return {
+          status: "error",
+          hash,
+          ...outcomeExtra,
+          ...resultCode && { details: resultCode, resultCode }
+        };
       }
-      return;
+      const details = error?.details;
+      this._setTransactionState({
+        step: "error",
+        phase: "submitting",
+        ...buildData && { buildData },
+        ...details && { details }
+      });
+      return { status: "error", ...outcomeExtra, ...details && { details } };
+    } catch (err) {
+      const details = err instanceof Error ? err.message : void 0;
+      this._setTransactionState({
+        step: "error",
+        phase: "submitting",
+        ...buildData && { buildData },
+        ...details && { details }
+      });
+      return { status: "error", ...outcomeExtra, ...details && { details } };
     }
+  }
+  /**
+   * Signs and submits in one logical step. Returns a {@link SubmitOutcome}.
+   *
+   * - **External wallets**: composes `signTx` + `submitTx` client-side. State
+   *   machine sees the full granular sequence `signing → signed → submitting
+   *   → success` because the underlying methods each emit.
+   * - **Custodial wallets**: atomic `/tx/sign-and-send` round-trip. State
+   *   machine emits the compound `signing-submitting` step (the SDK can't
+   *   observe when one phase ends and the next begins inside that single
+   *   backend call) and then transitions to `submitted` (Horizon ack only) or
+   *   `success` (ledger-confirmed), or `error[phase: 'signing-submitting']`.
+   */
+  async signAndSubmitTx(unsignedXdr) {
+    if (this._walletAdapter) {
+      const signed = await this.signTx(unsignedXdr);
+      if (signed.status === "error") {
+        const buildData2 = this._currentBuildData();
+        return {
+          status: "error",
+          ...buildData2 && { buildData: buildData2 },
+          ...signed.details && { details: signed.details }
+        };
+      }
+      return this.submitTx(signed.signedXdr);
+    }
+    const buildData = this._currentBuildData();
+    const outcomeExtra = buildData ? { buildData } : {};
+    this._setTransactionState({ step: "signing-submitting", ...buildData && { buildData } });
     const body = {
       network: this.getNetwork(),
       publicKey: this._session?.wallet?.publicKey ?? "",
@@ -2310,15 +2744,129 @@ var PollarClient = class {
     try {
       const { data, error } = await this._api.POST("/tx/sign-and-send", { body });
       if (!error && data?.success && data.content?.hash) {
-        this._setTransactionState({ step: "success", ...stateExtra, hash: data.content.hash });
-      } else {
-        const details = error?.details;
-        this._setTransactionState({ step: "error", ...stateExtra, ...details && { details } });
+        const {
+          hash,
+          status: backendStatus,
+          resultCode
+        } = data.content;
+        if (backendStatus === "SUCCESS") {
+          this._setTransactionState({ step: "success", hash, ...buildData && { buildData } });
+          return { status: "success", hash, ...outcomeExtra };
+        }
+        if (backendStatus === "PENDING") {
+          this._setTransactionState({ step: "submitted", hash, ...buildData && { buildData } });
+          return { status: "pending", hash, ...outcomeExtra };
+        }
+        this._setTransactionState({
+          step: "error",
+          phase: "signing-submitting",
+          ...buildData && { buildData },
+          ...resultCode && { details: resultCode }
+        });
+        return {
+          status: "error",
+          hash,
+          ...outcomeExtra,
+          ...resultCode && { details: resultCode, resultCode }
+        };
       }
-    } catch {
-      this._setTransactionState({ step: "error", ...stateExtra });
+      const details = error?.details;
+      this._setTransactionState({
+        step: "error",
+        phase: "signing-submitting",
+        ...buildData && { buildData },
+        ...details && { details }
+      });
+      return { status: "error", ...outcomeExtra, ...details && { details } };
+    } catch (err) {
+      const details = err instanceof Error ? err.message : void 0;
+      this._setTransactionState({
+        step: "error",
+        phase: "signing-submitting",
+        ...buildData && { buildData },
+        ...details && { details }
+      });
+      return { status: "error", ...outcomeExtra, ...details && { details } };
     }
   }
+  /**
+   * One-shot: build → sign → submit, returning the final {@link SubmitOutcome}.
+   *
+   * - **External wallets**: composes `buildTx` + `signAndSubmitTx` client-side.
+   *   State machine sees the full granular sequence (`building → built →
+   *   signing → signed → submitting → success`) because each composed call
+   *   emits its own transitions.
+   * - **Custodial wallets**: single round-trip to `/tx/build-sign-submit`. The
+   *   signed XDR never leaves the backend. State machine emits the compound
+   *   `building-signing-submitting` step (the SDK can't observe individual
+   *   phase boundaries inside one atomic call) and then transitions to
+   *   `submitted` / `success` / `error[phase: 'building-signing-submitting']`.
+   *
+   * If you need granular UI feedback for custodial flows (separate
+   * "Building…", "Signing…", "Submitting…" indicators), call `buildTx`,
+   * `signTx`, and `submitTx` separately instead.
+   */
+  async buildAndSignAndSubmitTx(operation, params, options) {
+    if (this._walletAdapter) {
+      const built = await this.buildTx(operation, params, options);
+      if (built.status === "error") {
+        return { status: "error", ...built.details && { details: built.details } };
+      }
+      return this.signAndSubmitTx(built.buildData.unsignedXdr);
+    }
+    if (!this._session?.wallet?.publicKey) {
+      this._setTransactionState({ step: "error", phase: "building-signing-submitting", details: "No wallet connected" });
+      return { status: "error", details: "No wallet connected" };
+    }
+    this._setTransactionState({ step: "building-signing-submitting" });
+    try {
+      const { data, error } = await this._api.POST("/tx/build-sign-submit", {
+        body: {
+          network: this.getNetwork(),
+          publicKey: this._session.wallet.publicKey,
+          operation,
+          params,
+          options: options ?? {}
+        }
+      });
+      if (!error && data?.success && data.content) {
+        const { hash, status: backendStatus, resultCode } = data.content;
+        if (backendStatus === "SUCCESS") {
+          this._setTransactionState({ step: "success", hash });
+          return { status: "success", hash };
+        }
+        if (backendStatus === "PENDING") {
+          this._setTransactionState({ step: "submitted", hash });
+          return { status: "pending", hash };
+        }
+        this._setTransactionState({
+          step: "error",
+          phase: "building-signing-submitting",
+          ...resultCode && { details: resultCode }
+        });
+        return { status: "error", hash, ...resultCode && { details: resultCode, resultCode } };
+      }
+      const details = error?.details;
+      this._setTransactionState({
+        step: "error",
+        phase: "building-signing-submitting",
+        ...details && { details }
+      });
+      return { status: "error", ...details && { details } };
+    } catch (err) {
+      const details = err instanceof Error ? err.message : void 0;
+      this._setTransactionState({
+        step: "error",
+        phase: "building-signing-submitting",
+        ...details && { details }
+      });
+      return { status: "error", ...details && { details } };
+    }
+  }
+  /** Alias for {@link buildAndSignAndSubmitTx} — shorter "just do the thing" name. */
+  async runTx(operation, params, options) {
+    return this.buildAndSignAndSubmitTx(operation, params, options);
+  }
   // ─── App config ───────────────────────────────────────────────────────────
   async getAppConfig() {
     try {
@@ -2385,6 +2933,11 @@ var PollarClient = class {
   _flowDeps(signal) {
     return {
       api: this._api,
+      basePath: this.basePath,
+      // SSE status streaming works on web; React Native's `fetch` has no
+      // readable `response.body`, so those clients poll the non-streaming
+      // status endpoint instead. `isBrowser` is false in RN and SSR alike.
+      useStreaming: isBrowser,
       signal,
       setAuthState: this._setAuthState.bind(this),
       storeSession: this._storeSession.bind(this),
@@ -2406,7 +2959,22 @@ var PollarClient = class {
    */
   async _resolveWalletAdapter(id) {
     if (this._walletAdapterResolver) {
-      return Promise.resolve(this._walletAdapterResolver(id));
+      const timeoutMs = this._walletResolverTimeoutMs;
+      let timeoutHandle;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => {
+          reject(
+            Object.assign(new Error(`[PollarClient] Wallet adapter resolver for "${id}" timed out after ${timeoutMs}ms`), {
+              code: AUTH_ERROR_CODES.WALLET_RESOLVER_TIMEOUT
+            })
+          );
+        }, timeoutMs);
+      });
+      try {
+        return await Promise.race([Promise.resolve(this._walletAdapterResolver(id)), timeoutPromise]);
+      } finally {
+        if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+      }
     }
     if (id === "freighter" /* FREIGHTER */) return new FreighterAdapter();
     if (id === "albedo" /* ALBEDO */) return new AlbedoAdapter();
@@ -2420,6 +2988,16 @@ var PollarClient = class {
       this._setAuthState({ step: "idle" });
       return;
     }
+    if (error instanceof Error && error.code === AUTH_ERROR_CODES.WALLET_RESOLVER_TIMEOUT) {
+      console.error("[PollarClient]", error.message);
+      this._setAuthState({
+        step: "error",
+        previousStep: this._authState.step,
+        message: error.message,
+        errorCode: AUTH_ERROR_CODES.WALLET_RESOLVER_TIMEOUT
+      });
+      return;
+    }
     console.error("[PollarClient] Unexpected error in auth flow", error);
     this._setAuthState({
       step: "error",
@@ -2441,6 +3019,7 @@ var PollarClient = class {
       }
       console.info("[PollarClient] Session restored from storage");
       this._setAuthState({ step: "authenticated", session: this._session });
+      this._scheduleNextRefresh();
     } else {
       console.info("[PollarClient] No session in storage");
     }
@@ -2467,9 +3046,11 @@ var PollarClient = class {
     }
     await writeStorage(this._storage, this.apiKeyHash, persisted);
     this._setAuthState({ step: "authenticated", session: persisted });
+    this._scheduleNextRefresh();
   }
   async _clearSession() {
     console.info("[PollarClient] Session cleared");
+    this._clearRefreshTimer();
     this._session = null;
     this._profile = null;
     this._walletAdapter = null;
@@ -2502,6 +3083,46 @@ var PollarClient = class {
     console.info(`[PollarClient] transaction:${next.step}`);
     for (const cb of this._transactionStateListeners) cb(next);
   }
+  /**
+   * Threads `buildData` through state transitions. When the user has already
+   * called `buildTx`, every subsequent state (signing, signed, submitting,
+   * submitted, success, error) should carry the build summary so modal UIs
+   * can keep showing "Send 5 USDC to G..." through the whole flow.
+   */
+  _currentBuildData() {
+    const s = this._transactionState;
+    if (!s) return void 0;
+    if ("buildData" in s && s.buildData) return s.buildData;
+    return void 0;
+  }
+};
+
+// src/stellar/StellarClient.ts
+var HORIZON_URLS = {
+  mainnet: "https://horizon.stellar.org",
+  testnet: "https://horizon-testnet.stellar.org"
+};
+var StellarClient = class {
+  constructor(config) {
+    this.horizonUrl = typeof config === "string" ? HORIZON_URLS[config] : config.horizonUrl;
+  }
+  async submitTransaction(signedXdr) {
+    try {
+      const response = await fetch(`${this.horizonUrl}/transactions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ tx: signedXdr })
+      });
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({}));
+        return { success: false, errorCode: body.extras?.result_codes?.transaction ?? "HORIZON_ERROR" };
+      }
+      const data = await response.json();
+      return { success: true, hash: data.hash };
+    } catch {
+      return { success: false, errorCode: "NETWORK_ERROR" };
+    }
+  }
 };
 
 // src/index.ts