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

package/LICENSE.md

@@ -0,0 +1,111 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 anolilab and contributors
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or service
+that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software that
+   exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee using
+   the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to the
+infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN
+IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following will
+apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -1,45 +1,215 @@
+<div align="center">
+
 # @lunora/react-native
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+**React Native / Expo integration for [Lunora](https://lunora.sh).**
+
+</div>
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+---
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+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).
+
+This package **re-exports the entire `@lunora/react` surface**, so you import
+your hooks and provider from here, and adds:
+
+- `createLunoraClient(options)` — a `LunoraClient` factory tuned for React
+  Native.
+- `@lunora/react-native/auth` — a one-import bridge to the
+  [better-auth Expo](https://www.better-auth.com/docs/integrations/expo) plugin.
+
+## Install
+
+```sh
+pnpm add @lunora/react-native @lunora/react @tanstack/react-query react
+# offline-queue persistence:
+npx expo install @react-native-async-storage/async-storage
+# only if you use auth:
+npx expo install expo-secure-store expo-web-browser expo-linking expo-constants expo-network
+pnpm add better-auth @better-auth/expo
+```
+
+## Quick start
+
+```tsx
+// lunora.ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { createLunoraClient } from "@lunora/react-native";
+
+export const client = createLunoraClient({
+    url: process.env.EXPO_PUBLIC_LUNORA_URL!, // e.g. https://my-app.workers.dev
+    storage: AsyncStorage, // persists offline writes across app restarts
+});
+```
+
+```tsx
+// App.tsx
+import { LunoraProvider } from "@lunora/react-native";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { client } from "./lunora";
+import { Chat } from "./Chat";
+
+const queryClient = new QueryClient();
+
+export default function App() {
+    return (
+        <QueryClientProvider client={queryClient}>
+            <LunoraProvider client={client}>
+                <Chat />
+            </LunoraProvider>
+        </QueryClientProvider>
+    );
+}
+```
+
+```tsx
+// Chat.tsx
+import { useMutation, useQuery } from "@lunora/react-native";
+import { FlatList, Text } from "react-native";
+
+import { api } from "./lunora/_generated/api";
+
+export function Chat() {
+    const messages = useQuery(api.messages.list, {});
+    const { mutate: send } = useMutation(api.messages.send);
+
+    return <FlatList data={messages ?? []} keyExtractor={(m) => m._id} renderItem={({ item }) => <Text>{item.text}</Text>} />;
+}
+```
+
+`useQuery` opens a live WebSocket subscription — the list updates in place as
+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)).
+
+```tsx
+// auth.ts
+import { createAuthClient } from "better-auth/react";
+import { expoClient } from "@lunora/react-native/auth";
+import * as SecureStore from "expo-secure-store";
+
+export const authClient = createAuthClient({
+    baseURL: process.env.EXPO_PUBLIC_LUNORA_URL!,
+    plugins: [expoClient({ scheme: "myapp", storage: SecureStore })],
+});
+```
+
+```tsx
+// lunora.ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { createLunoraClient } from "@lunora/react-native";
+
+export const client = createLunoraClient({
+    url: process.env.EXPO_PUBLIC_LUNORA_URL!,
+    storage: AsyncStorage,
+});
+```
+
+Bridge the session into the client whenever it changes — `setAuthToken` for HTTP,
+`setWsToken` for the socket:
+
+```tsx
+// App.tsx
+import { useEffect } from "react";
+import { expoBearerToken } from "@lunora/react-native/auth";
+
+import { authClient } from "./auth";
+import { client } from "./lunora";
+
+function Root() {
+    const { data: session } = authClient.useSession();
+
+    useEffect(() => {
+        const token = expoBearerToken(authClient);
+        client.setAuthToken(token); // HTTP `Authorization: Bearer …`
+        client.setWsToken(token ?? undefined); // WS `?token=…`
+    }, [session]);
 
-## Purpose
+    // …render the app
+}
+```
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@lunora/react-native`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+On the **server**, add better-auth's `expo()` and `bearer()` plugins, and fold
+the socket's `?token=` into an `Authorization` header in `resolveIdentity` (see
+`@lunora/auth`):
 
-## What is OIDC Trusted Publishing?
+```ts
+import { bearer } from "@lunora/auth/plugins";
+import { expo } from "@better-auth/expo";
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+// authOptions.plugins: [expo(), bearer(), /* … */]
+// authOptions.trustedOrigins: ["myapp://"]
 
-## Setup Instructions
+// createWorker({
+//   resolveIdentity: async (request) => {
+//     const headers = new Headers(request.headers);
+//     const wsToken = new URL(request.url).searchParams.get("token");
+//     if (wsToken && !headers.has("authorization")) headers.set("authorization", `Bearer ${wsToken}`);
+//     const session = await auth.api.getSession({ headers });
+//     return session?.user?.id ? { userId: session.user.id } : null;
+//   },
+// });
+```
 
-To properly configure OIDC trusted publishing for this package:
+### Why a bearer token
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+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
+`Authorization`, and the token rides `?token=` on the socket).
 
-## DO NOT USE THIS PACKAGE
+### TanStack Query focus / online managers
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+React Native doesn't fire the browser's `focus` / `online` events, so Query
+won't auto-refetch on app resume unless you point its managers at Expo's signals:
 
-## More Information
+```ts
+import { setupExpoFocusManager, setupExpoOnlineManager } from "@lunora/react-native/auth";
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+setupExpoFocusManager();
+setupExpoOnlineManager();
+```
 
----
+## API
+
+### `createLunoraClient(options)`
+
+Everything on `LunoraClientOptions` (`url`, `wsUrl`, `authBasePath`,
+`persistenceVersion`, …) plus:
+
+| Option           | Description                                                                                                                                                                                                                                                                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `storage`        | React Native `AsyncStorage` (or any `getItem`/`setItem`/`removeItem` store). Wires `createAsyncStoragePersistence` for the offline queue.                                                                                                                                                                                           |
+| `getAuthHeaders` | `() => Record<string, string> \| undefined`. Generic escape hatch for a **custom** credential header (API-gateway key, proxy token) on every HTTP RPC + the WebSocket upgrade. For better-auth sessions prefer a bearer token (`expoBearerToken` + `setAuthToken`/`setWsToken`) — a `Cookie` header here would trip the CSRF guard. |
+
+An explicit `persistence`, `fetch`, or `WebSocket` always takes precedence over
+the convenience derived from `storage` / `getAuthHeaders`.
+
+### `@lunora/react-native/auth`
+
+- `expoBearerToken(authClient)` — reads the better-auth Expo session token (from
+  `getCookie()`) for use with `client.setAuthToken` / `setWsToken`; `null` when
+  signed out.
+- `expoClient`, `setupExpoFocusManager`, `setupExpoOnlineManager` — re-exported
+  from `@better-auth/expo/client`.
+
+## Example app
+
+A complete Expo chat app (auth + live messages + offline queue) lives at
+[`examples/expo`](../../examples/expo) in this repo.
+
+## License
 
-**Maintained for OIDC setup purposes only**
+FSL-1.1-Apache-2.0 — see [LICENSE.md](./LICENSE.md).