@pollar/core 0.8.0 → 0.8.1

package/README.md

@@ -27,11 +27,37 @@ yarn add @pollar/core
 For React Native / Expo, also install one of the storage adapter peer deps:
 
 ```bash
-# Expo
+# Expo (react-native-quick-crypto is a native module → requires a dev build, not Expo Go)
 npx expo install expo-secure-store react-native-get-random-values
+npm i react-native-quick-crypto react-native-polyfill-globals
 
 # Bare React Native
-npm i react-native-keychain react-native-get-random-values
+npm i react-native-keychain react-native-get-random-values react-native-quick-crypto react-native-polyfill-globals
+```
+
+> **React Native runtime requirements.** The SDK builds a DPoP proof (RFC 9449) for **every** authenticated request.
+> That path uses four standard Web primitives that React Native / Hermes does **not** all ship by default. Register
+> them at the very top of your entry file, **before** any `@pollar/core` import. If any is missing, DPoP proof
+> construction fails and **no authenticated request works** — the SDK is not at fault, the runtime is.
+>
+> | Primitive | Used by | Polyfill |
+> | --- | --- | --- |
+> | `crypto.getRandomValues` | keypair generation (`NobleKeyManager`), DPoP `jti` | [`react-native-get-random-values`](https://github.com/LinusU/react-native-get-random-values) |
+> | `crypto.subtle.digest('SHA-256')` | `sha256` → API-key namespace, DPoP `ath`, `NobleKeyManager.sign()` | [`react-native-quick-crypto`](https://github.com/margelo/react-native-quick-crypto) ≥ 0.7 (native module → Expo **dev build**, not Expo Go) |
+> | `TextEncoder` / `TextDecoder` | DPoP proof encoding, base64url, JWK thumbprint | bundled in [`react-native-polyfill-globals`](https://github.com/acostalima/react-native-polyfill-globals) (or `text-encoding`) |
+> | `URL` (spec-compliant) | DPoP `htu` normalization (`new URL(request.url)` on every proof) | bundled in `react-native-polyfill-globals` (or [`react-native-url-polyfill`](https://github.com/charpeni/react-native-url-polyfill)) |
+>
+> `react-native-polyfill-globals/auto` is the pragmatic one-liner — it installs `TextEncoder`/`TextDecoder` **and**
+> `URL` together (plus base64 / fetch-streaming you don't strictly need). The SDK does **not** rely on `fetch` response
+> streaming on React Native: it polls the non-streaming `/auth/session/status/{id}/poll` endpoint instead, so you do
+> **not** need a fetch-streaming polyfill for auth — but you still need TextEncoder + URL from that same package.
+
+Entry-file setup (e.g. `index.js`), **before importing `@pollar/core`**:
+
+```ts
+import 'react-native-get-random-values'; // crypto.getRandomValues
+import 'react-native-polyfill-globals/auto'; // TextEncoder/TextDecoder + URL
+import 'react-native-quick-crypto'; // crypto.subtle.digest — register its global per the package's setup docs
 ```
 
 ## Overview
@@ -59,8 +85,10 @@ const client = new PollarClient({ apiKey: 'your-api-key' });
 ## React Native (Expo)
 
 ```ts
-// At your app entry — `crypto.getRandomValues` polyfill
-import 'react-native-get-random-values';
+// At your app entry, BEFORE importing @pollar/core — runtime polyfills (see table above):
+import 'react-native-get-random-values'; // crypto.getRandomValues
+import 'react-native-polyfill-globals/auto'; // TextEncoder/TextDecoder + URL
+import 'react-native-quick-crypto'; // crypto.subtle.digest — register its global per the package's setup docs
 
 import { PollarClient } from '@pollar/core';
 import { createSecureStoreAdapter } from '@pollar/core/adapters/expo';
@@ -78,7 +106,9 @@ const client = new PollarClient({ apiKey: 'your-api-key', storage });
 ## React Native (`react-native-keychain`)
 
 ```ts
-import 'react-native-get-random-values';
+import 'react-native-get-random-values'; // crypto.getRandomValues
+import 'react-native-polyfill-globals/auto'; // TextEncoder/TextDecoder + URL
+import 'react-native-quick-crypto'; // crypto.subtle.digest — register its global per the package's setup docs
 import { PollarClient } from '@pollar/core';
 import { createKeychainAdapter } from '@pollar/core/adapters/react-native-keychain';
 
@@ -86,6 +116,87 @@ const storage = await createKeychainAdapter();
 const client = new PollarClient({ apiKey: 'your-api-key', storage });
 ```
 
+## Framework integration
+
+`@pollar/core` is framework-agnostic: `PollarClient` is a plain class and the `on*StateChange` methods are
+callback subscriptions. To render reactively, bridge those callbacks into your framework's state primitive. The
+client instance should be a singleton (module scope, context, or DI) — never recreate it on every render.
+
+### React / Next.js
+
+`useSyncExternalStore` is the idiomatic bridge. In Next.js, only instantiate in Client Components (`'use client'`)
+— server-side, the SDK degrades to a no-op and warns.
+
+```tsx
+'use client';
+import { useSyncExternalStore } from 'react';
+import { PollarClient, type AuthState } from '@pollar/core';
+
+const client = new PollarClient({ apiKey: 'pk_...' }); // module scope = one instance
+
+export function useAuthState(): AuthState {
+  return useSyncExternalStore(
+    (cb) => client.onAuthStateChange(cb), // returns the unsubscribe fn
+    () => client.getAuthState(), // client snapshot
+    () => client.getAuthState(), // server snapshot (idle)
+  );
+}
+
+// const auth = useAuthState(); // re-renders on every auth transition
+```
+
+### Angular
+
+The SDK's callbacks fire **outside Angular's zone**, so wrap state updates in `NgZone.run()` (or use signals) or the
+view won't update. Expose the client through a service.
+
+```ts
+import { Injectable, NgZone, signal } from '@angular/core';
+import { PollarClient, type AuthState } from '@pollar/core';
+
+@Injectable({ providedIn: 'root' })
+export class PollarService {
+  private client = new PollarClient({ apiKey: 'pk_...' });
+  readonly authState = signal<AuthState>(this.client.getAuthState());
+
+  constructor(private zone: NgZone) {
+    this.client.onAuthStateChange((state) => {
+      this.zone.run(() => this.authState.set(state)); // re-enter Angular's zone
+    });
+  }
+
+  login = (email: string) => this.client.login({ provider: 'email', email });
+}
+```
+
+### Vue 3
+
+Assign the callback payload into a `ref` (or `shallowRef`) inside `onMounted`; unsubscribe in `onUnmounted`.
+
+```ts
+import { ref, shallowRef, onMounted, onUnmounted } from 'vue';
+import { PollarClient, type AuthState } from '@pollar/core';
+
+const client = new PollarClient({ apiKey: 'pk_...' });
+
+export function useAuth() {
+  const authState = shallowRef<AuthState>(client.getAuthState());
+  let unsub = () => {
+  };
+  onMounted(() => {
+    unsub = client.onAuthStateChange((s) => (authState.value = s)); // ref assign = reactive
+  });
+  onUnmounted(() => unsub());
+  return { authState, login: client.login.bind(client) };
+}
+```
+
+### React Native
+
+Same as React (`useSyncExternalStore`), plus the entry-file polyfills and injected adapters shown in the
+React Native sections above. OAuth and external-wallet logins require `openAuthUrl` / `walletAdapter` to be injected
+(the built-in popup/extension adapters are web-only).
+
 ## Preserved-on-disk storage shape
 
 0.7.0 persists exactly:
@@ -139,7 +250,7 @@ const sessions = await client.listSessions();
 ### `new PollarClient(config)`
 
 | Option             | Type                     | Required | Description                                                                                                 |
-| ------------------ | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------- |
+|--------------------|--------------------------|----------|-------------------------------------------------------------------------------------------------------------|
 | `apiKey`           | `string`                 | Yes      | Your Pollar API key                                                                                         |
 | `baseUrl`          | `string`                 | No       | Override the default API endpoint                                                                           |
 | `stellarNetwork`   | `'mainnet' \| 'testnet'` | No       | Target Stellar network (default: `testnet`)                                                                 |
@@ -167,6 +278,7 @@ client.login({ provider: 'email', email: 'user@example.com' });
 
 // Stellar wallet
 import { WalletType } from '@pollar/core';
+
 client.login({ provider: 'wallet', type: WalletType.FREIGHTER });
 client.login({ provider: 'wallet', type: WalletType.ALBEDO });
 ```

package/dist/adapters/react-native-appstate.d.mts

@@ -0,0 +1,10 @@
+import { V as VisibilityProvider } from '../types-84G_htcn.mjs';
+
+/**
+ * Create a `VisibilityProvider` backed by React Native's `AppState`.
+ *
+ * Throws (via the returned Promise) if `react-native` cannot be loaded.
+ */
+declare function createAppStateVisibilityProvider(): Promise<VisibilityProvider>;
+
+export { createAppStateVisibilityProvider };

package/dist/adapters/react-native-appstate.d.ts

@@ -0,0 +1,10 @@
+import { V as VisibilityProvider } from '../types-84G_htcn.js';
+
+/**
+ * Create a `VisibilityProvider` backed by React Native's `AppState`.
+ *
+ * Throws (via the returned Promise) if `react-native` cannot be loaded.
+ */
+declare function createAppStateVisibilityProvider(): Promise<VisibilityProvider>;
+
+export { createAppStateVisibilityProvider };

package/dist/adapters/react-native-appstate.js

@@ -0,0 +1,38 @@
+'use strict';
+
+// src/adapters/react-native-appstate.ts
+async function loadAppState() {
+  try {
+    const mod = await import('react-native');
+    const AppState = mod.AppState ?? mod.default?.AppState;
+    if (!AppState) {
+      throw new Error("'react-native' loaded but exposes no AppState export");
+    }
+    return AppState;
+  } catch (error) {
+    const message = `[PollarClient:visibility] Failed to load 'react-native' AppState. This adapter only runs inside a React Native app. Original error: ${error instanceof Error ? error.message : String(error)}`;
+    throw new Error(message);
+  }
+}
+async function createAppStateVisibilityProvider() {
+  const AppState = await loadAppState();
+  const isActive = (state) => state === "active";
+  return {
+    isVisible: () => isActive(AppState.currentState),
+    onChange: (cb) => {
+      let last = isActive(AppState.currentState);
+      const subscription = AppState.addEventListener("change", (state) => {
+        const next = isActive(state);
+        if (next !== last) {
+          last = next;
+          cb(next);
+        }
+      });
+      return () => subscription.remove();
+    }
+  };
+}
+
+exports.createAppStateVisibilityProvider = createAppStateVisibilityProvider;
+//# sourceMappingURL=react-native-appstate.js.map
+//# sourceMappingURL=react-native-appstate.js.map

package/dist/adapters/react-native-appstate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/react-native-appstate.ts"],"names":[],"mappings":";;;AA8BA,eAAe,YAAA,GAAqC;AAClD,EAAA,IAAI;AAGF,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,cAAc,CAAA;AACvC,IAAA,MAAM,QAAA,GAAY,GAAA,CAAmC,QAAA,IAAa,GAAA,CAAiD,OAAA,EAAS,QAAA;AAC5H,IAAA,IAAI,CAAC,QAAA,EAAU;AACb,MAAA,MAAM,IAAI,MAAM,sDAAsD,CAAA;AAAA,IACxE;AACA,IAAA,OAAO,QAAA;AAAA,EACT,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,OAAA,GACJ,uIAEmB,KAAA,YAAiB,KAAA,GAAQ,MAAM,OAAA,GAAU,MAAA,CAAO,KAAK,CAAC,CAAA,CAAA;AAC3E,IAAA,MAAM,IAAI,MAAM,OAAO,CAAA;AAAA,EACzB;AACF;AAOA,eAAsB,gCAAA,GAAgE;AACpF,EAAA,MAAM,QAAA,GAAW,MAAM,YAAA,EAAa;AAEpC,EAAA,MAAM,QAAA,GAAW,CAAC,KAAA,KAA2B,KAAA,KAAU,QAAA;AAEvD,EAAA,OAAO;AAAA,IACL,SAAA,EAAW,MAAM,QAAA,CAAS,QAAA,CAAS,YAAY,CAAA;AAAA,IAC/C,QAAA,EAAU,CAAC,EAAA,KAAO;AAIhB,MAAA,IAAI,IAAA,GAAO,QAAA,CAAS,QAAA,CAAS,YAAY,CAAA;AACzC,MAAA,MAAM,YAAA,GAAe,QAAA,CAAS,gBAAA,CAAiB,QAAA,EAAU,CAAC,KAAA,KAAU;AAClE,QAAA,MAAM,IAAA,GAAO,SAAS,KAAK,CAAA;AAC3B,QAAA,IAAI,SAAS,IAAA,EAAM;AACjB,UAAA,IAAA,GAAO,IAAA;AACP,UAAA,EAAA,CAAG,IAAI,CAAA;AAAA,QACT;AAAA,MACF,CAAC,CAAA;AACD,MAAA,OAAO,MAAM,aAAa,MAAA,EAAO;AAAA,IACnC;AAAA,GACF;AACF","file":"react-native-appstate.js","sourcesContent":["import type { VisibilityProvider } from '../visibility/types';\n\n/**\n * `AppState`-backed {@link VisibilityProvider} for React Native.\n *\n * Wire it into the silent-refresh scheduler so proactive token renewals are\n * skipped while the app is backgrounded and run the moment it returns to the\n * foreground — matching the web `visibilitychange` behavior and sidestepping\n * RN's aggressive background timer throttling.\n *\n * `react-native` is the consumer's framework (not a dependency of this SDK),\n * so the module is loaded lazily via dynamic `import('react-native')`. That\n * keeps web/Node bundles from ever resolving it. Because loading is async, the\n * factory is async too — mirror the `createSecureStoreAdapter` usage:\n *\n *   import { createAppStateVisibilityProvider } from '@pollar/core/adapters/react-native-appstate';\n *   const visibilityProvider = await createAppStateVisibilityProvider();\n *   new PollarClient({ apiKey, storage, visibilityProvider });\n */\n\n/**\n * Minimal structural type for the slice of `react-native`'s `AppState` we use.\n * Typed here instead of importing the package's types because `react-native`\n * is an optional peer the SDK is not type-checked against.\n */\ntype AppStateApi = {\n  currentState: string;\n  addEventListener: (type: 'change', handler: (state: string) => void) => { remove: () => void };\n};\n\nasync function loadAppState(): Promise<AppStateApi> {\n  try {\n    // @ts-expect-error -- optional peer dep; resolved at runtime in RN apps,\n    // absent when the SDK is built or run on web/Node.\n    const mod = await import('react-native');\n    const AppState = (mod as { AppState?: AppStateApi }).AppState ?? (mod as { default?: { AppState?: AppStateApi } }).default?.AppState;\n    if (!AppState) {\n      throw new Error(\"'react-native' loaded but exposes no AppState export\");\n    }\n    return AppState;\n  } catch (error) {\n    const message =\n      `[PollarClient:visibility] Failed to load 'react-native' AppState. ` +\n      `This adapter only runs inside a React Native app. ` +\n      `Original error: ${error instanceof Error ? error.message : String(error)}`;\n    throw new Error(message);\n  }\n}\n\n/**\n * Create a `VisibilityProvider` backed by React Native's `AppState`.\n *\n * Throws (via the returned Promise) if `react-native` cannot be loaded.\n */\nexport async function createAppStateVisibilityProvider(): Promise<VisibilityProvider> {\n  const AppState = await loadAppState();\n\n  const isActive = (state: string): boolean => state === 'active';\n\n  return {\n    isVisible: () => isActive(AppState.currentState),\n    onChange: (cb) => {\n      // Filter duplicate notifications — listeners only see real transitions,\n      // matching the web provider's contract. RN also emits 'inactive'\n      // (iOS transition state) which we collapse into \"not visible\".\n      let last = isActive(AppState.currentState);\n      const subscription = AppState.addEventListener('change', (state) => {\n        const next = isActive(state);\n        if (next !== last) {\n          last = next;\n          cb(next);\n        }\n      });\n      return () => subscription.remove();\n    },\n  };\n}\n"]}

package/dist/adapters/react-native-appstate.mjs

@@ -0,0 +1,36 @@
+// src/adapters/react-native-appstate.ts
+async function loadAppState() {
+  try {
+    const mod = await import('react-native');
+    const AppState = mod.AppState ?? mod.default?.AppState;
+    if (!AppState) {
+      throw new Error("'react-native' loaded but exposes no AppState export");
+    }
+    return AppState;
+  } catch (error) {
+    const message = `[PollarClient:visibility] Failed to load 'react-native' AppState. This adapter only runs inside a React Native app. Original error: ${error instanceof Error ? error.message : String(error)}`;
+    throw new Error(message);
+  }
+}
+async function createAppStateVisibilityProvider() {
+  const AppState = await loadAppState();
+  const isActive = (state) => state === "active";
+  return {
+    isVisible: () => isActive(AppState.currentState),
+    onChange: (cb) => {
+      let last = isActive(AppState.currentState);
+      const subscription = AppState.addEventListener("change", (state) => {
+        const next = isActive(state);
+        if (next !== last) {
+          last = next;
+          cb(next);
+        }
+      });
+      return () => subscription.remove();
+    }
+  };
+}
+
+export { createAppStateVisibilityProvider };
+//# sourceMappingURL=react-native-appstate.mjs.map
+//# sourceMappingURL=react-native-appstate.mjs.map

package/dist/adapters/react-native-appstate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/react-native-appstate.ts"],"names":[],"mappings":";AA8BA,eAAe,YAAA,GAAqC;AAClD,EAAA,IAAI;AAGF,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,cAAc,CAAA;AACvC,IAAA,MAAM,QAAA,GAAY,GAAA,CAAmC,QAAA,IAAa,GAAA,CAAiD,OAAA,EAAS,QAAA;AAC5H,IAAA,IAAI,CAAC,QAAA,EAAU;AACb,MAAA,MAAM,IAAI,MAAM,sDAAsD,CAAA;AAAA,IACxE;AACA,IAAA,OAAO,QAAA;AAAA,EACT,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,OAAA,GACJ,uIAEmB,KAAA,YAAiB,KAAA,GAAQ,MAAM,OAAA,GAAU,MAAA,CAAO,KAAK,CAAC,CAAA,CAAA;AAC3E,IAAA,MAAM,IAAI,MAAM,OAAO,CAAA;AAAA,EACzB;AACF;AAOA,eAAsB,gCAAA,GAAgE;AACpF,EAAA,MAAM,QAAA,GAAW,MAAM,YAAA,EAAa;AAEpC,EAAA,MAAM,QAAA,GAAW,CAAC,KAAA,KAA2B,KAAA,KAAU,QAAA;AAEvD,EAAA,OAAO;AAAA,IACL,SAAA,EAAW,MAAM,QAAA,CAAS,QAAA,CAAS,YAAY,CAAA;AAAA,IAC/C,QAAA,EAAU,CAAC,EAAA,KAAO;AAIhB,MAAA,IAAI,IAAA,GAAO,QAAA,CAAS,QAAA,CAAS,YAAY,CAAA;AACzC,MAAA,MAAM,YAAA,GAAe,QAAA,CAAS,gBAAA,CAAiB,QAAA,EAAU,CAAC,KAAA,KAAU;AAClE,QAAA,MAAM,IAAA,GAAO,SAAS,KAAK,CAAA;AAC3B,QAAA,IAAI,SAAS,IAAA,EAAM;AACjB,UAAA,IAAA,GAAO,IAAA;AACP,UAAA,EAAA,CAAG,IAAI,CAAA;AAAA,QACT;AAAA,MACF,CAAC,CAAA;AACD,MAAA,OAAO,MAAM,aAAa,MAAA,EAAO;AAAA,IACnC;AAAA,GACF;AACF","file":"react-native-appstate.mjs","sourcesContent":["import type { VisibilityProvider } from '../visibility/types';\n\n/**\n * `AppState`-backed {@link VisibilityProvider} for React Native.\n *\n * Wire it into the silent-refresh scheduler so proactive token renewals are\n * skipped while the app is backgrounded and run the moment it returns to the\n * foreground — matching the web `visibilitychange` behavior and sidestepping\n * RN's aggressive background timer throttling.\n *\n * `react-native` is the consumer's framework (not a dependency of this SDK),\n * so the module is loaded lazily via dynamic `import('react-native')`. That\n * keeps web/Node bundles from ever resolving it. Because loading is async, the\n * factory is async too — mirror the `createSecureStoreAdapter` usage:\n *\n *   import { createAppStateVisibilityProvider } from '@pollar/core/adapters/react-native-appstate';\n *   const visibilityProvider = await createAppStateVisibilityProvider();\n *   new PollarClient({ apiKey, storage, visibilityProvider });\n */\n\n/**\n * Minimal structural type for the slice of `react-native`'s `AppState` we use.\n * Typed here instead of importing the package's types because `react-native`\n * is an optional peer the SDK is not type-checked against.\n */\ntype AppStateApi = {\n  currentState: string;\n  addEventListener: (type: 'change', handler: (state: string) => void) => { remove: () => void };\n};\n\nasync function loadAppState(): Promise<AppStateApi> {\n  try {\n    // @ts-expect-error -- optional peer dep; resolved at runtime in RN apps,\n    // absent when the SDK is built or run on web/Node.\n    const mod = await import('react-native');\n    const AppState = (mod as { AppState?: AppStateApi }).AppState ?? (mod as { default?: { AppState?: AppStateApi } }).default?.AppState;\n    if (!AppState) {\n      throw new Error(\"'react-native' loaded but exposes no AppState export\");\n    }\n    return AppState;\n  } catch (error) {\n    const message =\n      `[PollarClient:visibility] Failed to load 'react-native' AppState. ` +\n      `This adapter only runs inside a React Native app. ` +\n      `Original error: ${error instanceof Error ? error.message : String(error)}`;\n    throw new Error(message);\n  }\n}\n\n/**\n * Create a `VisibilityProvider` backed by React Native's `AppState`.\n *\n * Throws (via the returned Promise) if `react-native` cannot be loaded.\n */\nexport async function createAppStateVisibilityProvider(): Promise<VisibilityProvider> {\n  const AppState = await loadAppState();\n\n  const isActive = (state: string): boolean => state === 'active';\n\n  return {\n    isVisible: () => isActive(AppState.currentState),\n    onChange: (cb) => {\n      // Filter duplicate notifications — listeners only see real transitions,\n      // matching the web provider's contract. RN also emits 'inactive'\n      // (iOS transition state) which we collapse into \"not visible\".\n      let last = isActive(AppState.currentState);\n      const subscription = AppState.addEventListener('change', (state) => {\n        const next = isActive(state);\n        if (next !== last) {\n          last = next;\n          cb(next);\n        }\n      });\n      return () => subscription.remove();\n    },\n  };\n}\n"]}

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { S as Storage, O as OnStorageDegrade } from './types-DqgJIJBl.mjs';
 export { a as StorageDegradeReason } from './types-DqgJIJBl.mjs';
+import { V as VisibilityProvider } from './types-84G_htcn.mjs';
 import * as openapi_fetch from 'openapi-fetch';
 
 type StellarNetwork = 'mainnet' | 'testnet';
@@ -75,43 +76,6 @@ interface KeyManager {
     sign(payload: Uint8Array): Promise<Uint8Array>;
 }
 
-/**
- * Pluggable "is the user looking at this app right now?" signal.
- *
- * Used by the silent-refresh scheduler so token renewals are skipped while
- * the tab is hidden / the app is backgrounded — both saves network and
- * works around aggressive `setTimeout` throttling that web browsers and RN
- * apply to non-foreground contexts.
- *
- * Default web implementation listens to `visibilitychange` plus
- * `pageshow`/`pagehide` (covers BFCache on iOS) and `focus`/`blur` (covers
- * the cases where `visibilitychange` lags). Default for non-browser
- * environments is a noop that always reports "visible".
- *
- * TODO(@pollar/react-native): when the dedicated RN package ships, it will
- * export an `AppState`-backed provider. Until then, RN consumers can wire
- * one inline:
- *
- *   import { AppState } from 'react-native';
- *   const rnVisibility = {
- *     isVisible: () => AppState.currentState === 'active',
- *     onChange: (cb) => {
- *       const sub = AppState.addEventListener('change', (s) => cb(s === 'active'));
- *       return () => sub.remove();
- *     },
- *   };
- *   new PollarClient({ apiKey, visibilityProvider: rnVisibility });
- */
-interface VisibilityProvider {
-    isVisible(): boolean;
-    /**
-     * Subscribe to visibility transitions. The callback receives the new
-     * visibility state (`true` = visible). Returns an unsubscribe function
-     * that must detach every listener registered by this call.
-     */
-    onChange(cb: (visible: boolean) => void): () => void;
-}
-
 declare enum WalletType {
     FREIGHTER = "freighter",
     ALBEDO = "albedo"
@@ -290,6 +254,47 @@ interface PollarClientConfig {
      * `undefined` = refresh forever as long as the app is visible.
      */
     maxIdleMs?: number;
+    /**
+     * Strategy for opening the hosted OAuth URL during
+     * `login({ provider: 'google' | 'github' })`. Defaults to a browser popup
+     * on web. React Native consumers MUST provide one (typically wrapping
+     * `expo-web-browser`'s `openAuthSessionAsync`), since `window.open` does
+     * not exist there. The SDK still drives the rest of the flow by polling the
+     * auth-session status, so the opener only needs to surface the URL — it does
+     * NOT need to capture the redirect payload.
+     */
+    openAuthUrl?: AuthUrlOpener;
+    /**
+     * Value sent to the backend as `redirect_uri` for hosted OAuth (where the
+     * provider returns the user afterwards). Defaults to `window.location.origin`
+     * on web. On React Native set this to your app's deep link / scheme — the
+     * same URL you pass to `WebBrowser.openAuthSessionAsync`.
+     */
+    oauthRedirectUri?: string;
+}
+/**
+ * Strategy for opening the hosted OAuth URL. The SDK mints the per-login auth
+ * session lazily inside `getUrl()` (call it once; the first call creates the
+ * `clientSessionId` and returns the full URL, or `null` if session creation
+ * failed). Open the resolved URL however the platform allows — a popup on web,
+ * `WebBrowser.openAuthSessionAsync(url, redirectUri)` on React Native — and
+ * resolve once the user-facing browser step is done or dismissed. You do NOT
+ * need to capture the redirect payload: the SDK polls the auth-session status
+ * until the backend marks it READY.
+ */
+type AuthUrlOpener = (ctx: AuthOpenContext) => void | Promise<void>;
+interface AuthOpenContext {
+    provider: 'google' | 'github';
+    /**
+     * Mints the auth session (once) and returns the full hosted-OAuth URL, or
+     * `null` if session creation failed. On web, call it AFTER reserving the
+     * popup window so popup blockers (which only honor `window.open` inside the
+     * original user-gesture tick) don't swallow it.
+     */
+    getUrl: () => Promise<string | null>;
+    /** The redirect target passed to the backend as `redirect_uri`. */
+    redirectUri: string;
+    signal: AbortSignal;
 }
 /**
  * One row in the active-sessions list (returned by `PollarClient.listSessions()`).
@@ -436,6 +441,8 @@ type SubmitOutcome = {
 };
 declare const AUTH_ERROR_CODES: {
     readonly SESSION_CREATE_FAILED: "SESSION_CREATE_FAILED";
+    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
+    readonly SESSION_INVALID: "SESSION_INVALID";
     readonly EMAIL_SEND_FAILED: "EMAIL_SEND_FAILED";
     readonly EMAIL_VERIFY_FAILED: "EMAIL_VERIFY_FAILED";
     readonly EMAIL_CODE_EXPIRED: "EMAIL_CODE_EXPIRED";
@@ -637,6 +644,10 @@ declare class PollarClient {
     private readonly _walletAdapterResolver;
     private readonly _walletResolverTimeoutMs;
     private _loginController;
+    /** Platform strategy for opening the hosted-OAuth URL (popup on web; injected on RN). */
+    private readonly _openAuthUrl;
+    /** `redirect_uri` sent to the backend for hosted OAuth. */
+    private readonly _oauthRedirectUri;
     constructor(config: PollarClientConfig);
     /** Awaitable handle for the initial keypair + session restore. */
     ready(): Promise<void>;
@@ -1123,6 +1134,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/auth/session/status/{clientSessionId}/poll": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Poll client session status (non-streaming)
+         * @description One-shot JSON variant of the SSE status stream, for clients without fetch response-body streaming (React Native). Returns the current `{status, user.ready}` immediately. Poll until `status` reaches a ready/consumed state.
+         */
+        get: operations["getAuthSessionStatusByClientSessionIdPoll"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/auth/google": {
         parameters: {
             query?: never;
@@ -1442,7 +1473,7 @@ interface paths {
         put?: never;
         /**
          * Submit a pre-signed XDR
-         * @description Submit step of the split build/sign/submit flow. Accepts a signed XDR produced by /tx/sign or by an external-wallet adapter. Goes through wallet-service /v1/tx/submit so the submission is policy-validated and idempotency-tracked.
+         * @description Submit step of the split build/sign/submit flow. Accepts a signed XDR produced by /tx/sign or signed client-side by an external wallet (Freighter/Albedo/SWK). Routing is custody-aware: EXTERNAL (user-controlled) wallets and adapter-signed wallets are broadcast directly via Soroban RPC, since wallet-service holds no record of them; custodial wallets go through wallet-service /v1/tx/submit so the submission is policy-validated and idempotency-tracked. The EXTERNAL signal is per-user, so apps mixing social login and wallet login submit each user correctly. All paths return the same PENDING | SUCCESS | FAILED outcome.
          */
         post: operations["postTxSubmit"];
         delete?: never;
@@ -1877,6 +1908,65 @@ interface operations {
             };
         };
     };
+    getAuthSessionStatusByClientSessionIdPoll: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                clientSessionId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Current session status */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        code: "SDK_SESSION_STATUS";
+                        /** @constant */
+                        success: true;
+                        content: {
+                            status: string;
+                            user: {
+                                ready: boolean;
+                            };
+                        };
+                    };
+                };
+            };
+            /** @description Not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        code: string;
+                    };
+                };
+            };
+            /** @description Gone (expired) */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        code: string;
+                    };
+                };
+            };
+        };
+    };
     getAuthGoogle: {
         parameters: {
             query: {
@@ -2172,6 +2262,19 @@ interface operations {
                     };
                 };
             };
+            /** @description Gone (expired) */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        code: string;
+                    };
+                };
+            };
         };
     };
     postAuthEmailVerifyCode: {
@@ -2259,6 +2362,19 @@ interface operations {
                     };
                 };
             };
+            /** @description Gone (expired) */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        code: string;
+                    };
+                };
+            };
         };
     };
     postAuthWallet: {
@@ -2347,6 +2463,19 @@ interface operations {
                     };
                 };
             };
+            /** @description Gone (expired) */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        code: string;
+                    };
+                };
+            };
         };
     };
     postAuthLogin: {
@@ -2478,6 +2607,19 @@ interface operations {
                     };
                 };
             };
+            /** @description Gone (expired) */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        code: string;
+                    };
+                };
+            };
         };
     };
     postAuthRefresh: {
@@ -2568,6 +2710,19 @@ interface operations {
                     };
                 };
             };
+            /** @description Gone (expired) */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        success: false;
+                        code: string;
+                    };
+                };
+            };
         };
     };
     postAuthLogout: {
@@ -4842,4 +4997,4 @@ declare function listDistributionRules(api: PollarApiClient): Promise<Distributi
  */
 declare function claimDistributionRule(api: PollarApiClient, body: DistributionClaimBody): Promise<DistributionClaimContent>;
 
-export { AUTH_ERROR_CODES, type AdapterFn, AlbedoAdapter, type AuthErrorCode, type AuthState, type BuildOutcome, type BuildProofArgs, type ConnectWalletResponse, type DistributionClaimBody, type DistributionClaimContent, type DistributionRule, type DistributionRulesState, FreighterAdapter, type KeyManager, type KycFlow, type KycLevel, type KycProvider, type KycStartBody, type KycStartResponse, type KycStatus, type LocalStorageAdapterOptions, type NetworkState, OnStorageDegrade, type PaymentInstructions, type PollarAdapter, type PollarAdapters, type PollarApiClient, type PollarApplicationConfigContent, type PollarApplicationConfigResponse, PollarClient, type PollarClientConfig, PollarFlowError, type PollarLoginOptions, type PollarPersistedSession, type PollarUserProfile, type PublicEcJwk, type RampDirection, type RampQuote, type RampTxStatus, type RampsOfframpBody, type RampsOfframpResponse, type RampsOnrampBody, type RampsOnrampResponse, type RampsQuoteQuery, type RampsQuoteResponse, type RampsTransactionResponse, type RulePeriod, type SessionInfo, type SignAuthEntryOptions, type SignAuthEntryResponse, type SignOutcome, type SignTransactionOptions, type SignTransactionResponse, type StellarBalance, StellarClient, type StellarClientConfig, type StellarNetwork, Storage, type SubmitOutcome, type TransactionState, type TxBuildBody, type TxBuildContent, type TxBuildResponse, type TxBuildSignSubmitBody, type TxBuildSignSubmitContent, type TxBuildSignSubmitResponse, type TxErrorPhase, type TxHistoryContent, type TxHistoryParams, type TxHistoryRecord, type TxHistoryState, type TxSignAndSendBody, type TxSignBody, type TxSignContent, type TxSignResponse, type TxSignSendResponse, type TxSubmitSignedBody, type WalletAdapter, type WalletAdapterResolver, type WalletBalanceContent, type WalletBalanceRecord, type WalletBalanceState, type WalletId, WalletType, WebCryptoKeyManager, buildProof, canonicalEcJwk, claimDistributionRule, computeJwkThumbprint, createLocalStorageAdapter, createMemoryAdapter, createOffRamp, createOnRamp, defaultKeyManager, defaultStorage, getKycProviders, getKycStatus, getRampTransaction, getRampsQuote, isValidSession, listDistributionRules, normalizeHtu, pollKycStatus, pollRampTransaction, type paths as pollarPaths, resolveKyc, startKyc };
+export { AUTH_ERROR_CODES, type AdapterFn, AlbedoAdapter, type AuthErrorCode, type AuthOpenContext, type AuthState, type AuthUrlOpener, type BuildOutcome, type BuildProofArgs, type ConnectWalletResponse, type DistributionClaimBody, type DistributionClaimContent, type DistributionRule, type DistributionRulesState, FreighterAdapter, type KeyManager, type KycFlow, type KycLevel, type KycProvider, type KycStartBody, type KycStartResponse, type KycStatus, type LocalStorageAdapterOptions, type NetworkState, OnStorageDegrade, type PaymentInstructions, type PollarAdapter, type PollarAdapters, type PollarApiClient, type PollarApplicationConfigContent, type PollarApplicationConfigResponse, PollarClient, type PollarClientConfig, PollarFlowError, type PollarLoginOptions, type PollarPersistedSession, type PollarUserProfile, type PublicEcJwk, type RampDirection, type RampQuote, type RampTxStatus, type RampsOfframpBody, type RampsOfframpResponse, type RampsOnrampBody, type RampsOnrampResponse, type RampsQuoteQuery, type RampsQuoteResponse, type RampsTransactionResponse, type RulePeriod, type SessionInfo, type SignAuthEntryOptions, type SignAuthEntryResponse, type SignOutcome, type SignTransactionOptions, type SignTransactionResponse, type StellarBalance, StellarClient, type StellarClientConfig, type StellarNetwork, Storage, type SubmitOutcome, type TransactionState, type TxBuildBody, type TxBuildContent, type TxBuildResponse, type TxBuildSignSubmitBody, type TxBuildSignSubmitContent, type TxBuildSignSubmitResponse, type TxErrorPhase, type TxHistoryContent, type TxHistoryParams, type TxHistoryRecord, type TxHistoryState, type TxSignAndSendBody, type TxSignBody, type TxSignContent, type TxSignResponse, type TxSignSendResponse, type TxSubmitSignedBody, type WalletAdapter, type WalletAdapterResolver, type WalletBalanceContent, type WalletBalanceRecord, type WalletBalanceState, type WalletId, WalletType, WebCryptoKeyManager, buildProof, canonicalEcJwk, claimDistributionRule, computeJwkThumbprint, createLocalStorageAdapter, createMemoryAdapter, createOffRamp, createOnRamp, defaultKeyManager, defaultStorage, getKycProviders, getKycStatus, getRampTransaction, getRampsQuote, isValidSession, listDistributionRules, normalizeHtu, pollKycStatus, pollRampTransaction, type paths as pollarPaths, resolveKyc, startKyc };