@lunora/react-native 1.0.0-alpha.1 → 1.0.0-alpha.100

package/README.md

@@ -6,16 +6,19 @@
 
 </div>
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 ---
 
 The same live hooks you use on the web — `useQuery`, `useMutation`,
 `useSubscription`, `useAuth`, `usePresence`, … — running on your phone, plus the
 two seams a native app needs that a browser gives you for free: a durable offline
-queue backed by `AsyncStorage`, and credentialed requests (there is no cookie jar
-in React Native, so the session has to be attached explicitly).
+queue backed by `AsyncStorage`, and credentialed requests (the session is a
+bearer, attached explicitly).
 
-This package **re-exports the entire `@lunora/react` surface**, so you import
-your hooks and provider from here, and adds:
+This package **re-exports the whole `@lunora/react` surface** (see
+[below](#re-exported-lunorareact-surface)), so you import your hooks and
+provider from here, and adds:
 
 - `createLunoraClient(options)` — a `LunoraClient` factory tuned for React
   Native.
@@ -87,10 +90,9 @@ other clients write, and `send` is optimistic and offline-safe.
 
 ## Authentication (better-auth + Expo)
 
-React Native has no cookie jar, so the session is sent as a **bearer** token: the
-HTTP RPC carries it in the `Authorization` header and the live socket carries it
-in the `?token=` query param. A bearer avoids the `Cookie` header the runtime's
-CSRF guard rejects on an `Origin`-less native request (see [Why a bearer token](#why-a-bearer-token)).
+The session is sent as a **bearer** token: the HTTP RPC carries it in the
+`Authorization` header and the live socket carries it in the `?token=` query
+param (see [Why a bearer token](#why-a-bearer-token)).
 
 ```tsx
 // auth.ts
@@ -129,10 +131,24 @@ import { client } from "./lunora";
 function Root() {
     const { data: session } = authClient.useSession();
 
+    // `expoBearerToken` is async since better-auth 1.7.1, and an async function
+    // is not a valid effect cleanup return — so kick off a promise instead.
+    // `cancelled` is load-bearing: two session changes in quick succession leave
+    // two reads in flight, and without it the slower one reinstates the previous
+    // session's token.
     useEffect(() => {
-        const token = expoBearerToken(authClient);
-        client.setAuthToken(token); // HTTP `Authorization: Bearer …`
-        client.setWsToken(token ?? undefined); // WS `?token=…`
+        let cancelled = false;
+
+        void (async () => {
+            const token = await expoBearerToken(authClient);
+            if (cancelled) return;
+            client.setAuthToken(token); // HTTP `Authorization: Bearer …`
+            client.setWsToken(token ?? undefined); // WS `?token=…`
+        })();
+
+        return () => {
+            cancelled = true;
+        };
     }, [session]);
 
     // …render the app
@@ -165,11 +181,22 @@ import { expo } from "@better-auth/expo";
 
 Lunora's runtime enables a CSRF Origin-check by default — it rejects any
 state-changing HTTP request or WebSocket upgrade that carries a `Cookie` but no
-trusted `Origin`. React Native sends no `Origin`, so a cookie-based credential
-would be **rejected** once signed in. A bearer token carries no `Cookie`, so it's
-exempt — and it works identically on `react-native-web` (the browser lets you set
+trusted `Origin`. React Native sends no `Origin`, so a cookie-based credential is
+**rejected** once signed in. A bearer token is the credential instead, and it
+works identically on `react-native-web` (the browser lets you set
 `Authorization`, and the token rides `?token=` on the socket).
 
+Using a bearer does **not** by itself guarantee the absence of a `Cookie` header.
+React Native has a real cookie jar — `fetch` is backed by the platform HTTP stack
+(`NSURLSession` / `OkHttp`) and its shared cookie store — so the `Set-Cookie` a
+better-auth sign-in returns is kept and re-attached to later requests, and the
+guard then 403s every state-changing RPC with `FORBIDDEN_ORIGIN`. It is
+intermittent (it depends on whether the jar holds the cookie that launch), and
+`security.csrf.trustedOrigins` cannot fix it: the trust list is only consulted
+for an `Origin` that was actually received, and a missing one is rejected
+outright. `createLunoraClient` closes this by sending `credentials: "omit"` on
+every request; if you pass your own `fetch`, wrap it in `withoutAmbientCookies`.
+
 ### TanStack Query focus / online managers
 
 React Native doesn't fire the browser's `focus` / `online` events, so Query
@@ -197,6 +224,23 @@ Everything on `LunoraClientOptions` (`url`, `wsUrl`, `authBasePath`,
 An explicit `persistence`, `fetch`, or `WebSocket` always takes precedence over
 the convenience derived from `storage` / `getAuthHeaders`.
 
+### Re-exported `@lunora/react` surface
+
+Every hook, provider, and auth gate from [`@lunora/react`](../react) is
+re-exported here, wholesale — a new hook there lands on native with no edit to
+this package.
+
+The payment kit is **not** part of that surface: `CheckoutButton`,
+`CustomerPortalButton`, and `useCheckout` render a DOM `<button>` and navigate
+via `globalThis.location`, so they ship from the `@lunora/react/payment` subpath
+rather than the `@lunora/react` root, and nothing re-exports them here. Drive
+purchases through the platform's own flow (or a WebView pointed at the web
+checkout URL).
+
+`useVoiceAgent` is re-exported but its defaults are Web APIs (`getUserMedia`,
+Web Audio, `WebSocket`): on native, pass your own `createMicrophone` /
+`createSpeaker` implementations.
+
 ### `@lunora/react-native/auth`
 
 - `expoBearerToken(authClient)` — reads the better-auth Expo session token (from

package/dist/auth.d.mts

@@ -1,35 +1,51 @@
-export { expoClient, setupExpoFocusManager, setupExpoOnlineManager } from '@better-auth/expo/client';
+export {
 /**
-* Read the current better-auth session token from an Expo auth client, for use
-* as a **bearer** credential on the Lunora client — `client.setAuthToken(token)`
-* for HTTP RPC and `client.setWsToken(token ?? undefined)` for the live socket.
-*
-* The Expo plugin persists the session as a cookie in `SecureStore`;
-* `getCookie()` exposes it, and this pulls the `session_token` value out.
-* better-auth's `bearer` plugin accepts that value verbatim in the
-* `Authorization` header — so the native client authenticates WITHOUT sending a
-* `Cookie`, which the runtime's CSRF guard rejects on an `Origin`-less native
-* request (React Native sends no `Origin`). Returns `null` when signed out.
-*
-* Re-run it whenever the session changes and feed the result to the client (see
-* the package README):
-*
-* ```ts
-* const token = expoBearerToken(authClient);
-* client.setAuthToken(token);
-* client.setWsToken(token ?? undefined);
-* ```
-*/
-declare const expoBearerToken: (authClient: {
-  getCookie: () => string;
-}) => null | string;
+ * The slice of a key/value store the better-auth Expo plugin needs. Pass Expo
+ * `SecureStore` straight in.
+ *
+ * Re-exported from `@better-auth/expo/client` rather than restated here. This
+ * used to be a hand-written `SecureStorageLike` mirroring what upstream needed
+ * — two synchronous methods — and better-auth 1.7 moved the Expo storage
+ * integration to asynchronous `SecureStore` methods, so the real shape is now
+ * `getItem` + `getItemAsync` + `setItem` + `setItemAsync`. A hand-written
+ * mirror does not fail when upstream widens like that; it just silently
+ * describes a store the plugin will not accept. Re-exporting makes the
+ * compiler track it, which is the same lesson the `getCookie` shim taught in
+ * this file's history.
+ * @experimental
+ */
+type ExpoClientStorage, expoClient, setupExpoFocusManager, setupExpoOnlineManager } from '@better-auth/expo/client';
 /**
-* The slice of a key/value store the better-auth Expo plugin needs — the shape
-* of `expo-secure-store` (a synchronous `getItem`, plus `setItem`). Pass Expo
-* `SecureStore` straight in.
-*/
-interface SecureStorageLike {
-  getItem: (key: string) => null | string;
-  setItem: (key: string, value: string) => unknown;
-}
-export { SecureStorageLike, expoBearerToken };
+ * Read the current better-auth session token from an Expo auth client, for use
+ * as a **bearer** credential on the Lunora client — `client.setAuthToken(token)`
+ * for HTTP RPC and `client.setWsToken(token ?? undefined)` for the live socket.
+ *
+ * The Expo plugin persists the session as a cookie in `SecureStore`;
+ * `getCookie()` exposes it, and this pulls the `session_token` value out.
+ * better-auth's `bearer` plugin accepts that value verbatim in the
+ * `Authorization` header — so the native client authenticates WITHOUT sending a
+ * `Cookie`, which the runtime's CSRF guard rejects on an `Origin`-less native
+ * request (React Native sends no `Origin`). Resolves `null` when signed out.
+ *
+ * **Async since better-auth 1.7.1**, which changed `@better-auth/expo`'s
+ * `getCookie` from `() => string` to `() => Promise<string>` (it reads
+ * `SecureStore` asynchronously now). The awaited value is what gets matched:
+ * regexing the Promise itself would test `"[object Promise]"`, find no
+ * `session_token`, and return `null` on every call — a signed-in native app
+ * that silently behaves as anonymous, which is exactly the failure this
+ * signature change prevents by making callers await.
+ *
+ * Re-run it whenever the session changes and feed the result to the client (see
+ * the package README):
+ *
+ * ```ts
+ * const token = await expoBearerToken(authClient);
+ * client.setAuthToken(token);
+ * client.setWsToken(token ?? undefined);
+ * ```
+ * @experimental
+ */
+declare const expoBearerToken: (authClient: {
+  getCookie: () => Promise<string> | string;
+}) => Promise<null | string>;
+export { expoBearerToken };

package/dist/auth.d.ts

@@ -1,35 +1,51 @@
-export { expoClient, setupExpoFocusManager, setupExpoOnlineManager } from '@better-auth/expo/client';
+export {
 /**
-* Read the current better-auth session token from an Expo auth client, for use
-* as a **bearer** credential on the Lunora client — `client.setAuthToken(token)`
-* for HTTP RPC and `client.setWsToken(token ?? undefined)` for the live socket.
-*
-* The Expo plugin persists the session as a cookie in `SecureStore`;
-* `getCookie()` exposes it, and this pulls the `session_token` value out.
-* better-auth's `bearer` plugin accepts that value verbatim in the
-* `Authorization` header — so the native client authenticates WITHOUT sending a
-* `Cookie`, which the runtime's CSRF guard rejects on an `Origin`-less native
-* request (React Native sends no `Origin`). Returns `null` when signed out.
-*
-* Re-run it whenever the session changes and feed the result to the client (see
-* the package README):
-*
-* ```ts
-* const token = expoBearerToken(authClient);
-* client.setAuthToken(token);
-* client.setWsToken(token ?? undefined);
-* ```
-*/
-declare const expoBearerToken: (authClient: {
-  getCookie: () => string;
-}) => null | string;
+ * The slice of a key/value store the better-auth Expo plugin needs. Pass Expo
+ * `SecureStore` straight in.
+ *
+ * Re-exported from `@better-auth/expo/client` rather than restated here. This
+ * used to be a hand-written `SecureStorageLike` mirroring what upstream needed
+ * — two synchronous methods — and better-auth 1.7 moved the Expo storage
+ * integration to asynchronous `SecureStore` methods, so the real shape is now
+ * `getItem` + `getItemAsync` + `setItem` + `setItemAsync`. A hand-written
+ * mirror does not fail when upstream widens like that; it just silently
+ * describes a store the plugin will not accept. Re-exporting makes the
+ * compiler track it, which is the same lesson the `getCookie` shim taught in
+ * this file's history.
+ * @experimental
+ */
+type ExpoClientStorage, expoClient, setupExpoFocusManager, setupExpoOnlineManager } from '@better-auth/expo/client';
 /**
-* The slice of a key/value store the better-auth Expo plugin needs — the shape
-* of `expo-secure-store` (a synchronous `getItem`, plus `setItem`). Pass Expo
-* `SecureStore` straight in.
-*/
-interface SecureStorageLike {
-  getItem: (key: string) => null | string;
-  setItem: (key: string, value: string) => unknown;
-}
-export { SecureStorageLike, expoBearerToken };
+ * Read the current better-auth session token from an Expo auth client, for use
+ * as a **bearer** credential on the Lunora client — `client.setAuthToken(token)`
+ * for HTTP RPC and `client.setWsToken(token ?? undefined)` for the live socket.
+ *
+ * The Expo plugin persists the session as a cookie in `SecureStore`;
+ * `getCookie()` exposes it, and this pulls the `session_token` value out.
+ * better-auth's `bearer` plugin accepts that value verbatim in the
+ * `Authorization` header — so the native client authenticates WITHOUT sending a
+ * `Cookie`, which the runtime's CSRF guard rejects on an `Origin`-less native
+ * request (React Native sends no `Origin`). Resolves `null` when signed out.
+ *
+ * **Async since better-auth 1.7.1**, which changed `@better-auth/expo`'s
+ * `getCookie` from `() => string` to `() => Promise<string>` (it reads
+ * `SecureStore` asynchronously now). The awaited value is what gets matched:
+ * regexing the Promise itself would test `"[object Promise]"`, find no
+ * `session_token`, and return `null` on every call — a signed-in native app
+ * that silently behaves as anonymous, which is exactly the failure this
+ * signature change prevents by making callers await.
+ *
+ * Re-run it whenever the session changes and feed the result to the client (see
+ * the package README):
+ *
+ * ```ts
+ * const token = await expoBearerToken(authClient);
+ * client.setAuthToken(token);
+ * client.setWsToken(token ?? undefined);
+ * ```
+ * @experimental
+ */
+declare const expoBearerToken: (authClient: {
+  getCookie: () => Promise<string> | string;
+}) => Promise<null | string>;
+export { expoBearerToken };

package/dist/auth.mjs

@@ -1,2 +1 @@
-export { default as expoBearerToken } from './packem_shared/expoBearerToken-B0Zorz--.mjs';
-export { expoClient, setupExpoFocusManager, setupExpoOnlineManager } from '@better-auth/expo/client';
+import{default as p}from"./packem_shared/expoBearerToken-CA88JtQp.mjs";import{expoClient as a,setupExpoFocusManager as n,setupExpoOnlineManager as t}from"@better-auth/expo/client";export{p as expoBearerToken,a as expoClient,n as setupExpoFocusManager,t as setupExpoOnlineManager};

package/dist/index.d.mts

@@ -1,75 +1,140 @@
 import { AsyncStorageLike, LunoraClientOptions, LunoraClient } from '@lunora/client';
 export * from '@lunora/react';
 /**
-* A `() => headers` factory the React Native client threads onto every HTTP RPC
-* request *and* the WebSocket upgrade — a generic escape hatch for attaching a
-* **custom** credential header (an API-gateway key, a proxy token, …) that
-* React Native's missing cookie jar can't carry implicitly. Return `undefined`
-* (or an empty object) when there's nothing to attach.
-*
-* For better-auth Expo sessions, prefer a **bearer** token instead: read it with
-* `@lunora/react-native/auth`'s `expoBearerToken` and feed it to
-* `client.setAuthToken` / `setWsToken` (see the package README). A bearer avoids
-* the `Cookie` header the runtime's CSRF guard rejects on `Origin`-less native
-* requests.
-*/
+ * A `() => headers` factory the React Native client threads onto every HTTP RPC
+ * request *and* the WebSocket upgrade — a generic escape hatch for attaching a
+ * **custom** credential header (an API-gateway key, a proxy token, …). Return
+ * `undefined` (or an empty object) when there's nothing to attach.
+ *
+ * For better-auth Expo sessions, prefer a **bearer** token instead: read it with
+ * `@lunora/react-native/auth`'s `expoBearerToken` and feed it to
+ * `client.setAuthToken` / `setWsToken` (see the package README). Either way the
+ * client sends `credentials: "omit"`, so the platform cookie jar never attaches a
+ * session cookie the runtime's CSRF guard would reject on an `Origin`-less native
+ * request.
+ * @experimental
+ */
 type AuthHeadersFactory = () => Record<string, string> | undefined;
 /**
-* Options for `createLunoraClient` — the React Native / Expo counterpart to
-* constructing a `LunoraClient` directly. It is `LunoraClientOptions` with two
-* React-Native-shaped conveniences layered on. `storage` wires the
-* AsyncStorage-backed offline-queue persistence for you (the browser default
-* auto-probes IndexedDB, which React Native lacks, so without this the queue
-* stays in memory and is lost on reload). `getAuthHeaders` is a generic escape
-* hatch for a custom credential header on both the HTTP RPC path and the
-* WebSocket upgrade; for better-auth sessions prefer a bearer token
-* (`expoBearerToken` + the client's `setAuthToken` / `setWsToken`).
-*
-* The `persistence`, `fetch`, and `WebSocket` fields of `LunoraClientOptions`
-* are still accepted and take precedence when you need full control; the two
-* conveniences are sugar over exactly those seams.
-*/
+ * Options for `createLunoraClient` — the React Native / Expo counterpart to
+ * constructing a `LunoraClient` directly. It is `LunoraClientOptions` with two
+ * React-Native-shaped conveniences layered on. `storage` wires the
+ * AsyncStorage-backed offline-queue persistence for you (the browser default
+ * auto-probes IndexedDB, which React Native lacks, so without this the queue
+ * stays in memory and is lost on reload). `getAuthHeaders` is a generic escape
+ * hatch for a custom credential header on both the HTTP RPC path and the
+ * WebSocket upgrade; for better-auth sessions prefer a bearer token
+ * (`expoBearerToken` + the client's `setAuthToken` / `setWsToken`).
+ *
+ * The `persistence`, `fetch`, and `WebSocket` fields of `LunoraClientOptions`
+ * are still accepted and take precedence when you need full control; the two
+ * conveniences are sugar over exactly those seams.
+ * @experimental
+ */
 interface CreateLunoraClientOptions extends LunoraClientOptions {
   /**
-  * Attaches a credential to every HTTP RPC request and to the WebSocket
-  * upgrade request. See `AuthHeadersFactory`. When omitted, requests go out
-  * with only whatever `LunoraClient` already sets (its bearer token from
-  * `setAuthToken`, if any).
-  *
-  * Merged UNDER the client's own headers on the HTTP path (an explicit
-  * `setAuthToken` bearer wins over a same-named header here); applied to the
-  * WebSocket upgrade via a wrapping `WebSocket`, since the socket has no other
-  * way to carry credentials in React Native.
-  */
+   * Attaches a credential to every HTTP RPC request and to the WebSocket
+   * upgrade request. See `AuthHeadersFactory`. When omitted, requests go out
+   * with only whatever `LunoraClient` already sets (its bearer token from
+   * `setAuthToken`, if any).
+   *
+   * Merged UNDER the client's own headers on the HTTP path (an explicit
+   * `setAuthToken` bearer wins over a same-named header here); applied to the
+   * WebSocket upgrade via a wrapping `WebSocket`, since the socket has no other
+   * way to carry credentials in React Native.
+   */
   getAuthHeaders?: AuthHeadersFactory;
   /**
-  * React Native `AsyncStorage` (or any async key/value store with the same
-  * `getItem`/`setItem`/`removeItem` surface — Expo `SecureStore`, an in-memory
-  * map in tests). When supplied, the offline mutation queue is persisted here
-  * via `createAsyncStoragePersistence`, so writes made offline survive an app
-  * restart. Ignored when an explicit `persistence` is passed.
-  */
+   * React Native `AsyncStorage` (or any async key/value store with the same
+   * `getItem`/`setItem`/`removeItem` surface — Expo `SecureStore`, an in-memory
+   * map in tests). When supplied it backs two independent caches: the offline
+   * mutation queue (via `createAsyncStoragePersistence`, so writes made offline
+   * survive an app restart) and the durable query cache (via
+   * `createAsyncStorageQueryCache`, so reads repaint before the socket
+   * reconnects).
+   *
+   * Each is opted out of by its own option, not by the other: `persistence`
+   * overrides the queue and `queryCache` overrides the read cache, so
+   * `{ persistence: false, storage }` still writes query results to storage.
+   */
   storage?: AsyncStorageLike;
 }
 /**
-* Construct a `LunoraClient` tuned for React Native / Expo — a thin wrapper over
-* `new LunoraClient(options)` that fills in the two things a browser gets for
-* free but React Native does not.
-*
-* First, a durable offline queue: pass `storage` (React Native `AsyncStorage`,
-* or any async key/value store) and the offline mutation queue is persisted
-* through `createAsyncStoragePersistence` — the browser default auto-probes
-* IndexedDB, which React Native lacks, so without this the queue lives only in
-* memory and is lost on reload.
-*
-* Second, credentialed requests: pass `getAuthHeaders` and the returned headers
-* ride both the HTTP RPC path and the WebSocket upgrade, since React Native has
-* no cookie jar to attach a session implicitly.
-*
-* Everything on `LunoraClientOptions` is still accepted and passed through; an
-* explicit `persistence`, `fetch`, or `WebSocket` takes precedence over the
-* convenience derived from `storage` / `getAuthHeaders`. See the package README
-* for a full setup example.
-*/
+ * Wrap a `fetch` so no request carries the platform's ambient cookie credential.
+ *
+ * React Native **does** have a cookie jar — its `fetch` is backed by the
+ * platform HTTP stack (`NSURLSession` / `OkHttp`), which owns a shared,
+ * persistent cookie store — so a `Set-Cookie` from a better-auth sign-in is kept
+ * and re-attached to later requests automatically. The package's own docs used
+ * to assert the opposite, and the bearer design leaned on it: "there is no jar,
+ * therefore no `Cookie` header, therefore the runtime's CSRF guard never sees
+ * one".
+ *
+ * It does see one. The guard rejects an unsafe, cookie-bearing request whose
+ * `Origin` is missing or untrusted, and a native request sends no `Origin` — so
+ * every state-changing RPC 403s with `FORBIDDEN_ORIGIN` for as long as the jar
+ * holds that cookie. `security.csrf.trustedOrigins` cannot fix it: the trust list
+ * is only consulted for an `Origin` that was actually received, and a missing one
+ * is rejected outright. It is also intermittent — it depends on whether the jar
+ * happens to hold the session cookie that launch — which is what let it hide.
+ *
+ * `credentials: "omit"` is the fix, and it costs nothing on native: the session
+ * is a bearer there (`setAuthToken` / `setWsToken`), so the cookie was never the
+ * credential — only an accident of transport riding along. Wrapped INNERMOST by
+ * {@link createLunoraClient}, so it runs after every other layer and also
+ * overrides the `credentials: "include"` `@lunora/client` sends on its
+ * `get-session` probe.
+ *
+ * **Scope.** This covers `fetch`, which is the whole HTTP RPC/REST/storage
+ * surface. It does NOT cover the WebSocket upgrade — React Native attaches the
+ * same jar's cookie to the handshake and exposes no per-socket opt-out — nor
+ * `httpStream` imported standalone from `@lunora/client`, which resolves
+ * `globalThis.fetch` itself. Neither is a live 403 today: React Native sends an
+ * `Origin` equal to the server's on a WS handshake, and better-auth's `bearer`
+ * plugin overwrites the session cookie with the bearer rather than deferring to
+ * it. Both are noted so the guarantee is not read wider than it is.
+ *
+ * {@link createLunoraClient} applies it only on native — see
+ * {@link isNativeRuntime} — and only to the global `fetch`. Under
+ * `react-native-web` the jar is the browser's, `Origin` IS sent, the CSRF guard
+ * never fires, and a cookie session is a legitimate setup that this would
+ * silently sign out (`getCurrentUser` deliberately sends `credentials:
+ * "include"`). A caller-supplied `fetch` is never wrapped either, so a
+ * cookie-forwarding SSR transport keeps its credentials; apply this yourself if
+ * you want it.
+ */
+declare const withoutAmbientCookies: (fetchImpl: typeof fetch) => typeof fetch;
+/**
+ * Construct a `LunoraClient` tuned for React Native / Expo — a thin wrapper over
+ * `new LunoraClient(options)` that fills in the three things a browser gets for
+ * free but React Native does not.
+ *
+ * First, a durable offline queue: pass `storage` (React Native `AsyncStorage`,
+ * or any async key/value store) and the offline mutation queue is persisted
+ * through `createAsyncStoragePersistence` — the browser default auto-probes
+ * IndexedDB, which React Native lacks, so without this the queue lives only in
+ * memory and is lost on reload.
+ *
+ * Second, a durable read cache: the same `storage` also backs the query cache
+ * through `createAsyncStorageQueryCache`, so cached reads render immediately
+ * after a restart while the socket reconnects — mirroring the browser's
+ * IndexedDB-backed default.
+ *
+ * Third, credentialed requests: the session is a bearer on this platform, so the
+ * returned `fetch` is wrapped in {@link withoutAmbientCookies} (React Native's
+ * cookie jar is real, and a stray session cookie 403s every state-changing RPC —
+ * see there), and passing `getAuthHeaders` additionally rides its headers on both
+ * the HTTP RPC path and the WebSocket upgrade.
+ *
+ * Everything on `LunoraClientOptions` is still accepted and passed through; an
+ * explicit `persistence`, `queryCache`, `fetch`, or `WebSocket` replaces the
+ * transport derived from `storage`. A `getAuthHeaders` factory is layered over a
+ * caller-supplied `fetch` rather than ignored — the previous behaviour dropped
+ * the credential on HTTP while still injecting it on the WS upgrade. `persistence`
+ * and `queryCache` override independently — `storage` backs both, so opting out
+ * of one leaves the other wired. See the package README
+ * for a full setup example.
+ * @experimental
+ */
 declare const createLunoraClient: (options: CreateLunoraClientOptions) => LunoraClient;
-export { type AuthHeadersFactory, type CreateLunoraClientOptions, createLunoraClient };
+export { type AuthHeadersFactory, type CreateLunoraClientOptions, createLunoraClient, withoutAmbientCookies };

package/dist/index.d.ts

@@ -1,75 +1,140 @@
 import { AsyncStorageLike, LunoraClientOptions, LunoraClient } from '@lunora/client';
 export * from '@lunora/react';
 /**
-* A `() => headers` factory the React Native client threads onto every HTTP RPC
-* request *and* the WebSocket upgrade — a generic escape hatch for attaching a
-* **custom** credential header (an API-gateway key, a proxy token, …) that
-* React Native's missing cookie jar can't carry implicitly. Return `undefined`
-* (or an empty object) when there's nothing to attach.
-*
-* For better-auth Expo sessions, prefer a **bearer** token instead: read it with
-* `@lunora/react-native/auth`'s `expoBearerToken` and feed it to
-* `client.setAuthToken` / `setWsToken` (see the package README). A bearer avoids
-* the `Cookie` header the runtime's CSRF guard rejects on `Origin`-less native
-* requests.
-*/
+ * A `() => headers` factory the React Native client threads onto every HTTP RPC
+ * request *and* the WebSocket upgrade — a generic escape hatch for attaching a
+ * **custom** credential header (an API-gateway key, a proxy token, …). Return
+ * `undefined` (or an empty object) when there's nothing to attach.
+ *
+ * For better-auth Expo sessions, prefer a **bearer** token instead: read it with
+ * `@lunora/react-native/auth`'s `expoBearerToken` and feed it to
+ * `client.setAuthToken` / `setWsToken` (see the package README). Either way the
+ * client sends `credentials: "omit"`, so the platform cookie jar never attaches a
+ * session cookie the runtime's CSRF guard would reject on an `Origin`-less native
+ * request.
+ * @experimental
+ */
 type AuthHeadersFactory = () => Record<string, string> | undefined;
 /**
-* Options for `createLunoraClient` — the React Native / Expo counterpart to
-* constructing a `LunoraClient` directly. It is `LunoraClientOptions` with two
-* React-Native-shaped conveniences layered on. `storage` wires the
-* AsyncStorage-backed offline-queue persistence for you (the browser default
-* auto-probes IndexedDB, which React Native lacks, so without this the queue
-* stays in memory and is lost on reload). `getAuthHeaders` is a generic escape
-* hatch for a custom credential header on both the HTTP RPC path and the
-* WebSocket upgrade; for better-auth sessions prefer a bearer token
-* (`expoBearerToken` + the client's `setAuthToken` / `setWsToken`).
-*
-* The `persistence`, `fetch`, and `WebSocket` fields of `LunoraClientOptions`
-* are still accepted and take precedence when you need full control; the two
-* conveniences are sugar over exactly those seams.
-*/
+ * Options for `createLunoraClient` — the React Native / Expo counterpart to
+ * constructing a `LunoraClient` directly. It is `LunoraClientOptions` with two
+ * React-Native-shaped conveniences layered on. `storage` wires the
+ * AsyncStorage-backed offline-queue persistence for you (the browser default
+ * auto-probes IndexedDB, which React Native lacks, so without this the queue
+ * stays in memory and is lost on reload). `getAuthHeaders` is a generic escape
+ * hatch for a custom credential header on both the HTTP RPC path and the
+ * WebSocket upgrade; for better-auth sessions prefer a bearer token
+ * (`expoBearerToken` + the client's `setAuthToken` / `setWsToken`).
+ *
+ * The `persistence`, `fetch`, and `WebSocket` fields of `LunoraClientOptions`
+ * are still accepted and take precedence when you need full control; the two
+ * conveniences are sugar over exactly those seams.
+ * @experimental
+ */
 interface CreateLunoraClientOptions extends LunoraClientOptions {
   /**
-  * Attaches a credential to every HTTP RPC request and to the WebSocket
-  * upgrade request. See `AuthHeadersFactory`. When omitted, requests go out
-  * with only whatever `LunoraClient` already sets (its bearer token from
-  * `setAuthToken`, if any).
-  *
-  * Merged UNDER the client's own headers on the HTTP path (an explicit
-  * `setAuthToken` bearer wins over a same-named header here); applied to the
-  * WebSocket upgrade via a wrapping `WebSocket`, since the socket has no other
-  * way to carry credentials in React Native.
-  */
+   * Attaches a credential to every HTTP RPC request and to the WebSocket
+   * upgrade request. See `AuthHeadersFactory`. When omitted, requests go out
+   * with only whatever `LunoraClient` already sets (its bearer token from
+   * `setAuthToken`, if any).
+   *
+   * Merged UNDER the client's own headers on the HTTP path (an explicit
+   * `setAuthToken` bearer wins over a same-named header here); applied to the
+   * WebSocket upgrade via a wrapping `WebSocket`, since the socket has no other
+   * way to carry credentials in React Native.
+   */
   getAuthHeaders?: AuthHeadersFactory;
   /**
-  * React Native `AsyncStorage` (or any async key/value store with the same
-  * `getItem`/`setItem`/`removeItem` surface — Expo `SecureStore`, an in-memory
-  * map in tests). When supplied, the offline mutation queue is persisted here
-  * via `createAsyncStoragePersistence`, so writes made offline survive an app
-  * restart. Ignored when an explicit `persistence` is passed.
-  */
+   * React Native `AsyncStorage` (or any async key/value store with the same
+   * `getItem`/`setItem`/`removeItem` surface — Expo `SecureStore`, an in-memory
+   * map in tests). When supplied it backs two independent caches: the offline
+   * mutation queue (via `createAsyncStoragePersistence`, so writes made offline
+   * survive an app restart) and the durable query cache (via
+   * `createAsyncStorageQueryCache`, so reads repaint before the socket
+   * reconnects).
+   *
+   * Each is opted out of by its own option, not by the other: `persistence`
+   * overrides the queue and `queryCache` overrides the read cache, so
+   * `{ persistence: false, storage }` still writes query results to storage.
+   */
   storage?: AsyncStorageLike;
 }
 /**
-* Construct a `LunoraClient` tuned for React Native / Expo — a thin wrapper over
-* `new LunoraClient(options)` that fills in the two things a browser gets for
-* free but React Native does not.
-*
-* First, a durable offline queue: pass `storage` (React Native `AsyncStorage`,
-* or any async key/value store) and the offline mutation queue is persisted
-* through `createAsyncStoragePersistence` — the browser default auto-probes
-* IndexedDB, which React Native lacks, so without this the queue lives only in
-* memory and is lost on reload.
-*
-* Second, credentialed requests: pass `getAuthHeaders` and the returned headers
-* ride both the HTTP RPC path and the WebSocket upgrade, since React Native has
-* no cookie jar to attach a session implicitly.
-*
-* Everything on `LunoraClientOptions` is still accepted and passed through; an
-* explicit `persistence`, `fetch`, or `WebSocket` takes precedence over the
-* convenience derived from `storage` / `getAuthHeaders`. See the package README
-* for a full setup example.
-*/
+ * Wrap a `fetch` so no request carries the platform's ambient cookie credential.
+ *
+ * React Native **does** have a cookie jar — its `fetch` is backed by the
+ * platform HTTP stack (`NSURLSession` / `OkHttp`), which owns a shared,
+ * persistent cookie store — so a `Set-Cookie` from a better-auth sign-in is kept
+ * and re-attached to later requests automatically. The package's own docs used
+ * to assert the opposite, and the bearer design leaned on it: "there is no jar,
+ * therefore no `Cookie` header, therefore the runtime's CSRF guard never sees
+ * one".
+ *
+ * It does see one. The guard rejects an unsafe, cookie-bearing request whose
+ * `Origin` is missing or untrusted, and a native request sends no `Origin` — so
+ * every state-changing RPC 403s with `FORBIDDEN_ORIGIN` for as long as the jar
+ * holds that cookie. `security.csrf.trustedOrigins` cannot fix it: the trust list
+ * is only consulted for an `Origin` that was actually received, and a missing one
+ * is rejected outright. It is also intermittent — it depends on whether the jar
+ * happens to hold the session cookie that launch — which is what let it hide.
+ *
+ * `credentials: "omit"` is the fix, and it costs nothing on native: the session
+ * is a bearer there (`setAuthToken` / `setWsToken`), so the cookie was never the
+ * credential — only an accident of transport riding along. Wrapped INNERMOST by
+ * {@link createLunoraClient}, so it runs after every other layer and also
+ * overrides the `credentials: "include"` `@lunora/client` sends on its
+ * `get-session` probe.
+ *
+ * **Scope.** This covers `fetch`, which is the whole HTTP RPC/REST/storage
+ * surface. It does NOT cover the WebSocket upgrade — React Native attaches the
+ * same jar's cookie to the handshake and exposes no per-socket opt-out — nor
+ * `httpStream` imported standalone from `@lunora/client`, which resolves
+ * `globalThis.fetch` itself. Neither is a live 403 today: React Native sends an
+ * `Origin` equal to the server's on a WS handshake, and better-auth's `bearer`
+ * plugin overwrites the session cookie with the bearer rather than deferring to
+ * it. Both are noted so the guarantee is not read wider than it is.
+ *
+ * {@link createLunoraClient} applies it only on native — see
+ * {@link isNativeRuntime} — and only to the global `fetch`. Under
+ * `react-native-web` the jar is the browser's, `Origin` IS sent, the CSRF guard
+ * never fires, and a cookie session is a legitimate setup that this would
+ * silently sign out (`getCurrentUser` deliberately sends `credentials:
+ * "include"`). A caller-supplied `fetch` is never wrapped either, so a
+ * cookie-forwarding SSR transport keeps its credentials; apply this yourself if
+ * you want it.
+ */
+declare const withoutAmbientCookies: (fetchImpl: typeof fetch) => typeof fetch;
+/**
+ * Construct a `LunoraClient` tuned for React Native / Expo — a thin wrapper over
+ * `new LunoraClient(options)` that fills in the three things a browser gets for
+ * free but React Native does not.
+ *
+ * First, a durable offline queue: pass `storage` (React Native `AsyncStorage`,
+ * or any async key/value store) and the offline mutation queue is persisted
+ * through `createAsyncStoragePersistence` — the browser default auto-probes
+ * IndexedDB, which React Native lacks, so without this the queue lives only in
+ * memory and is lost on reload.
+ *
+ * Second, a durable read cache: the same `storage` also backs the query cache
+ * through `createAsyncStorageQueryCache`, so cached reads render immediately
+ * after a restart while the socket reconnects — mirroring the browser's
+ * IndexedDB-backed default.
+ *
+ * Third, credentialed requests: the session is a bearer on this platform, so the
+ * returned `fetch` is wrapped in {@link withoutAmbientCookies} (React Native's
+ * cookie jar is real, and a stray session cookie 403s every state-changing RPC —
+ * see there), and passing `getAuthHeaders` additionally rides its headers on both
+ * the HTTP RPC path and the WebSocket upgrade.
+ *
+ * Everything on `LunoraClientOptions` is still accepted and passed through; an
+ * explicit `persistence`, `queryCache`, `fetch`, or `WebSocket` replaces the
+ * transport derived from `storage`. A `getAuthHeaders` factory is layered over a
+ * caller-supplied `fetch` rather than ignored — the previous behaviour dropped
+ * the credential on HTTP while still injecting it on the WS upgrade. `persistence`
+ * and `queryCache` override independently — `storage` backs both, so opting out
+ * of one leaves the other wired. See the package README
+ * for a full setup example.
+ * @experimental
+ */
 declare const createLunoraClient: (options: CreateLunoraClientOptions) => LunoraClient;
-export { type AuthHeadersFactory, type CreateLunoraClientOptions, createLunoraClient };
+export { type AuthHeadersFactory, type CreateLunoraClientOptions, createLunoraClient, withoutAmbientCookies };

package/dist/index.mjs

@@ -1,2 +1 @@
-export { createLunoraClient } from './packem_shared/createLunoraClient-D9i-IKbc.mjs';
-export * from '@lunora/react';
+import{createLunoraClient as t,withoutAmbientCookies as r}from"./packem_shared/createLunoraClient-WOgHmG35.mjs";export*from"@lunora/react";export{t as createLunoraClient,r as withoutAmbientCookies};

package/dist/packem_shared/createLunoraClient-WOgHmG35.mjs

@@ -0,0 +1 @@
+import{LunoraClient as d,createAsyncStorageQueryCache as h,createAsyncStoragePersistence as i}from"@lunora/client";const u=()=>typeof document>"u",f=s=>(t,o)=>s(t,{...o,credentials:"omit"}),b=(s,t)=>(o,e)=>{const r=t();if(!r)return s(o,e);const c=new Headers(r);return e?.headers&&new Headers(e.headers).forEach((n,a)=>{c.set(a,n)}),s(o,{...e,headers:c})},S=(s,t)=>class extends s{constructor(e,r){const c=t();super(e,r,c?{headers:c}:void 0)}},y=s=>{const{getAuthHeaders:t,storage:o,...e}=s,r=e.fetch===void 0&&typeof fetch=="function"?fetch.bind(globalThis):void 0,c=e.fetch??(r&&u()?f(r):r),n=t&&c?b(c,t):c,a=t&&e.WebSocket===void 0&&typeof WebSocket=="function"?S(WebSocket,t):e.WebSocket;return new d({...e,persistence:e.persistence??(o?i({storage:o}):void 0),queryCache:e.queryCache??(o?h({storage:o}):void 0),fetch:n,WebSocket:a})};export{y as createLunoraClient,b as withAuthHeaders,S as withAuthWebSocket,f as withoutAmbientCookies};

package/dist/packem_shared/expoBearerToken-CA88JtQp.mjs

@@ -0,0 +1 @@
+const t=/(?:^|;)[^;=]*session_token=([^;]+)/,n=async e=>t.exec(await e.getCookie())?.[1]??null;export{n as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/react-native",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.100",
   "description": "React Native / Expo integration for Lunora: an AsyncStorage-backed client factory, the useQuery/useMutation/useSubscription hooks, and a one-call better-auth Expo client",
   "keywords": [
     "cloudflare",
@@ -50,13 +50,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.21",
-    "@lunora/react": "1.0.0-alpha.24"
+    "@lunora/client": "1.0.0-alpha.123",
+    "@lunora/react": "1.0.0-alpha.129"
   },
   "peerDependencies": {
-    "@better-auth/expo": "^1.6.23",
+    "@better-auth/expo": "^1.7.1",
     "@tanstack/react-query": "^5.101.0",
-    "better-auth": "^1.6.23",
+    "better-auth": "^1.7.1",
     "react": "^19.2.7"
   },
   "peerDependenciesMeta": {

package/dist/packem_shared/createLunoraClient-D9i-IKbc.mjs

@@ -1,36 +0,0 @@
-import { LunoraClient, createAsyncStoragePersistence } from '@lunora/client';
-
-const withAuthHeaders = (fetchImpl, getAuthHeaders) => (input, init) => {
-  const extra = getAuthHeaders();
-  if (!extra) {
-    return fetchImpl(input, init);
-  }
-  const merged = new Headers(extra);
-  if (init?.headers) {
-    new Headers(init.headers).forEach((value, key) => {
-      merged.set(key, value);
-    });
-  }
-  return fetchImpl(input, { ...init, headers: merged });
-};
-const withAuthWebSocket = (WebSocketImpl, getAuthHeaders) => class AuthWebSocket extends WebSocketImpl {
-  constructor(url, protocols) {
-    const headers = getAuthHeaders();
-    super(url, protocols, headers ? { headers } : void 0);
-  }
-};
-const createLunoraClient = (options) => {
-  const { getAuthHeaders, storage, ...rest } = options;
-  const authedFetch = getAuthHeaders && rest.fetch === void 0 && typeof fetch === "function" ? withAuthHeaders(fetch.bind(globalThis), getAuthHeaders) : rest.fetch;
-  const authedWebSocket = getAuthHeaders && rest.WebSocket === void 0 && typeof WebSocket === "function" ? withAuthWebSocket(WebSocket, getAuthHeaders) : rest.WebSocket;
-  return new LunoraClient({
-    ...rest,
-    // Auto-wire AsyncStorage persistence unless the caller passed an explicit
-    // `persistence` (including `false` to opt out).
-    persistence: rest.persistence ?? (storage ? createAsyncStoragePersistence({ storage }) : void 0),
-    fetch: authedFetch,
-    WebSocket: authedWebSocket
-  });
-};
-
-export { createLunoraClient, withAuthHeaders, withAuthWebSocket };

package/dist/packem_shared/expoBearerToken-B0Zorz--.mjs

@@ -1,7 +0,0 @@
-const SESSION_TOKEN_COOKIE = /(?:^|;)[^;=]*session_token=([^;]+)/;
-const expoBearerToken = (authClient) => {
-  const match = SESSION_TOKEN_COOKIE.exec(authClient.getCookie());
-  return match?.[1] ?? null;
-};
-
-export { expoBearerToken as default };