@pollar/core 0.7.1 → 0.8.0

package/dist/index.js

@@ -28,10 +28,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) => {
@@ -325,9 +325,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;
   }
@@ -900,14 +898,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;
 }
@@ -918,18 +920,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") {
@@ -951,22 +953,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 } = {}) {
@@ -1041,34 +1043,6 @@ function generateJti() {
   );
 }
 
-// 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]";
 function createMemoryAdapter() {
@@ -1156,6 +1130,57 @@ 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",
@@ -1166,6 +1191,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 {
@@ -1556,7 +1582,7 @@ async function authenticate(clientSessionId, deps, expectedWallet) {
   setAuthState({ step: "authenticating" });
   await streamUntilFound(api, clientSessionId, (data2) => data2?.status === "READY", 200, signal);
   const dpopJwk = await deps.getPublicJwk();
-  const { data, error } = await api.POST("/auth/login", {
+  const { data } = await api.POST("/auth/login", {
     body: {
       clientSessionId,
       dpopJwk,
@@ -1721,7 +1747,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 });
@@ -1758,6 +1784,7 @@ async function loginWallet(type, deps) {
 
 // src/client/client.ts
 var isBrowser = typeof window !== "undefined" && typeof localStorage !== "undefined";
+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.`
@@ -1785,6 +1812,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" };
@@ -1795,15 +1827,32 @@ 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.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._api = createApiClient(this.basePath);
     this._wireMiddlewares();
     this._networkState = { step: "connected", network: config.stellarNetwork ?? "testnet" };
@@ -1849,6 +1898,9 @@ 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() {
@@ -1858,6 +1910,11 @@ var PollarClient = class {
     }
     this._loginController?.abort();
     this._loginController = null;
+    this._clearRefreshTimer();
+    if (this._visibilityUnsubscribe) {
+      this._visibilityUnsubscribe();
+      this._visibilityUnsubscribe = null;
+    }
   }
   // ─── Middlewares (DPoP + auto-refresh) ────────────────────────────────────
   _wireMiddlewares() {
@@ -1865,6 +1922,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 {
@@ -1895,15 +1953,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);
       }
@@ -1928,14 +1993,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);
@@ -2006,6 +2079,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 ──────────────────────────────────────────────────────────────
@@ -2017,6 +2149,38 @@ 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;
@@ -2253,10 +2417,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(),
@@ -2270,40 +2440,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 ?? "",
@@ -2312,15 +2636,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 {
@@ -2408,7 +2846,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();
@@ -2422,6 +2875,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",
@@ -2443,6 +2906,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");
     }
@@ -2469,9 +2933,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;
@@ -2504,6 +2970,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