@basictech/react 0.9.0-beta.1 → 0.11.0-beta.1

package/readme.md

@@ -1,467 +0,0 @@
-# @basictech/react
-
-React SDK for [Basic](https://basic.tech) — authentication and an offline-first, synced database for your React app.
-
-Basic gives every user their own personal datastore (a PDS). Your app authenticates with OAuth, gets its own sandboxed slice of the user's datastore, and this SDK keeps a local replica of that data in the browser — reads are instant and local, writes work offline, and everything syncs live across the user's devices over the Basic **Sync/2** protocol.
-
-> **Breaking change (0.9):** this version is a ground-up rewrite for the new Basic auth system and the Sync/2 sync engine. The 0.8.x sync client speaks a protocol the server no longer supports. See [Migrating from 0.8](#migrating-from-08).
-
----
-
-## Contents
-
-- [Installation](#installation)
-- [Quick start](#quick-start)
-- [How it works](#how-it-works)
-- [Anonymous & local-first](#anonymous--local-first)
-- [Multiple users](#multiple-users)
-- [Authentication](#authentication)
-- [Database](#database)
-- [Live queries](#live-queries)
-- [Sync status, offline behavior & errors](#sync-status-offline-behavior--errors)
-- [Shares (multiplayer)](#shares-multiplayer)
-- [Typed schemas](#typed-schemas)
-- [REST mode](#rest-mode)
-- [API reference](#api-reference)
-- [Advanced usage](#advanced-usage)
-- [Migrating from 0.8](#migrating-from-08)
-
----
-
-## Installation
-
-```bash
-npm install @basictech/react
-```
-
-Requires React 16.8+ (hooks). React 17, 18, and 19 are supported.
-
-## Quick start
-
-### 1. Define your schema
-
-Create a `basic.config.ts` with your project id (from [app.basic.tech](https://app.basic.tech)) and your tables:
-
-```typescript
-// basic.config.ts
-export const schema = {
-  project_id: "YOUR_PROJECT_ID",
-  version: 1,
-  tables: {
-    todos: {
-      type: "collection",
-      fields: {
-        title: { type: "string", indexed: true, required: true },
-        completed: { type: "boolean", indexed: true },
-      },
-    },
-  },
-};
-```
-
-Field types: `string`, `number`, `boolean`, `json`. Publish the schema from the Basic dashboard — sync is enabled once the published version matches your local one.
-
-### 2. Wrap your app
-
-```tsx
-// main.tsx
-import { BasicProvider } from "@basictech/react";
-import { schema } from "./basic.config";
-
-createRoot(document.getElementById("root")!).render(
-  <BasicProvider schema={schema} devToolbar>
-    <App />
-  </BasicProvider>,
-);
-```
-
-### 3. Sign in and use the database
-
-```tsx
-import { useBasic, useQuery } from "@basictech/react";
-
-function Todos() {
-  const { isSignedIn, signIn, signOut, user, db } = useBasic();
-  const todos = useQuery(() => db.table("todos").getAll());
-
-  if (!isSignedIn) {
-    return <button onClick={() => signIn()}>Sign in with Basic</button>;
-  }
-
-  return (
-    <div>
-      <p>hi {user?.email} <button onClick={() => signOut()}>sign out</button></p>
-
-      <button onClick={() => db.table("todos").create({ title: "hello", completed: false })}>
-        add todo
-      </button>
-
-      {todos?.map((todo) => (
-        <label key={todo.id}>
-          <input
-            type="checkbox"
-            checked={!!todo.completed}
-            onChange={() => db.table("todos").patch(todo.id, { completed: !todo.completed })}
-          />
-          {String(todo.title)}
-          <button onClick={() => db.table("todos").delete(todo.id)}>×</button>
-        </label>
-      ))}
-    </div>
-  );
-}
-```
-
-That's the whole loop — and note the app **works before sign-in too**: `db.table(...)` writes go to a local anonymous workspace and merge into the account automatically when the user signs in (see [Anonymous & local-first](#anonymous--local-first)). `useQuery` re-renders whenever local data changes — whether the change came from this tab, another device, or another user via a share.
-
-## How it works
-
-In the default `sync` mode, the SDK maintains a **local replica** of your app's slice of the user's datastore, in IndexedDB, and syncs it over one WebSocket:
-
-1. **Local first** — the local database opens immediately, with no session and no network. Reads and writes work from the first render, including offline cold starts.
-2. **Writes are ops** — every write is a `put` (create/replace), `patch` (shallow field merge), or `delete` operation with a client-minted unique id. Ops apply to the local view immediately (optimistic), queue in IndexedDB, and push to the server when online. Retries are always safe: the server deduplicates by op id.
-3. **Reads are local** — `get`/`getAll`/`find` read the local view: confirmed server state with your pending writes layered on top. No network round-trip.
-4. **Bootstrap on connect** — when a session exists, the SDK fetches a snapshot of the account's current state, layers your pending writes on top, then subscribes for live changes.
-5. **The server is the authority** — it orders all ops (last-writer-wins per record; `patch`es merge per field), validates them against your published schema, and echoes them to every connected device. If it rejects a write, the SDK rolls it back locally and surfaces it (see [rejected ops](#rejected-ops)).
-6. **Sign-out is clean** — the user's local data is wiped, the session is revoked server-side, and the app continues in a fresh anonymous workspace. No page reloads.
-
-## Anonymous & local-first
-
-Anonymous mode is **on by default**: users can use your app without signing in. Their data lives in a local-only workspace (sync status `local`), fully readable and writable, surviving reloads.
-
-When they sign in, the anonymous workspace **becomes** their account: every anonymous write is already a queued op, so the normal bootstrap-and-push flow merges them into the account — no copy step, no data loss, and live queries keep working through the transition.
-
-```tsx
-const { isAnonymous, isSignedIn, signIn, db } = useBasic();
-
-// works signed in or not:
-await db.table("todos").create({ title: "works offline & anonymous" });
-
-// prompt when you want the data to start syncing:
-{isAnonymous && <button onClick={() => signIn()}>Sign in to sync</button>}
-```
-
-Safety guarantees:
-
-- A keyspace is **stamped with the account DID** at first bootstrap. Local data from one account can never merge into another — if a different account signs in over it, the local cache is wiped first (it's server-backed; nothing is lost).
-- Signing out wipes that user's local data and drops into a fresh anonymous workspace (nothing readable is left behind on shared machines).
-
-Set `anonymous={false}` on the provider to require sign-in before any local data exists (classic behavior).
-
-## Multiple users
-
-Several local users — anonymous or signed-in — can exist side by side, one active at a time. The active user is **per tab** (two tabs can be on different users); the profiles themselves are shared across tabs. Each user has an isolated keyspace and session.
-
-```tsx
-const { users, activeUser, switchUser, addUser, removeUser } = useUsers();
-
-<select value={activeUser?.id} onChange={(e) => switchUser(e.target.value)}>
-  {users.map((u) => (
-    <option key={u.id} value={u.id}>
-      {u.kind === "anon" ? "Anonymous" : u.email || u.name || u.did}
-    </option>
-  ))}
-</select>
-<button onClick={() => addUser()}>Add user</button>
-```
-
-- `switchUser(id)` swaps the active session, database, and sync connection in place. Live queries via `useQuery` re-attach automatically.
-- `addUser()` creates a fresh anonymous user and switches to it (sign in from there to add an account).
-- `removeUser(id)` wipes that user's local data and revokes its session; removing the active user is the same as `signOut()`.
-- `signOut()` removes the active user and falls through to the next one (or a fresh anonymous workspace).
-
-## Authentication
-
-Basic is the OAuth provider. `signIn()` redirects to the user's Basic sign-in page; after consent the user lands back on your app with a code the SDK exchanges automatically (PKCE, rotating refresh tokens — all handled for you).
-
-```tsx
-const auth = useAuth(); // or grab the same fields from useBasic()
-
-auth.status;        // 'bootstrapping' | 'authenticated' | 'recovering' | 'reauth_required' | 'signed_out'
-auth.isSignedIn;    // boolean (stays true during reauth_required so you can show user info)
-auth.user;          // { sub, email, name, picture } | null
-auth.did;           // the user's decentralized id
-auth.scope;         // scopes granted to your app
-
-await auth.signIn();                       // redirect flow (current URL is the redirect URI)
-await auth.signIn("https://app.com/done"); // custom redirect URI
-await auth.signInWithHandle("alice.basic.id"); // federated: resolve the user's own PDS first
-await auth.signOut();                      // revokes server-side + clears local data
-```
-
-### Auth status lifecycle
-
-| Status | Meaning | What to render |
-| --- | --- | --- |
-| `bootstrapping` | SDK is initializing | splash / nothing (provider hides children by default) |
-| `authenticated` | Healthy session | your app |
-| `recovering` | Session likely exists but unconfirmed (offline, mid-refresh) | your app (data still works locally) |
-| `reauth_required` | Session definitively invalid — user must sign in again | your app (local reads/writes still work) + a re-sign-in prompt |
-| `signed_out` | No session — anonymous local workspace (default mode) | your app + a "sign in to sync" prompt (`isAnonymous` is true) |
-
-### Calling your own API
-
-`getToken()` returns a valid access token, refreshing it automatically (tokens are short-lived — never cache them yourself):
-
-```typescript
-const token = await auth.getToken();
-await fetch("https://your-api.example/thing", {
-  headers: { Authorization: `Bearer ${token}` },
-});
-// after a 401 from your API:
-await auth.getToken({ forceRefresh: true });
-```
-
-### Scopes
-
-Default requested scopes are `profile,email,app:admin`. Check what was actually granted:
-
-```typescript
-auth.hasScope("app:db:read"); // note: app:admin implies all app:db:* scopes
-auth.missingScopes();          // requested but not granted
-```
-
-## Database
-
-`db.table(name)` returns the table API (name must exist in your schema):
-
-```typescript
-const todos = db.table("todos");
-
-const created = await todos.create({ title: "buy milk" });
-// → { id: "0198…", title: "buy milk" } — id minted locally, works offline
-
-await todos.put(id, { title: "replace", completed: false });
-// create-or-replace the WHOLE record with these fields
-
-await todos.patch(id, { completed: true });
-// shallow-merge the given fields; returns null if the record doesn't exist
-
-await todos.delete(id);   // idempotent — deleting a missing record is fine
-
-await todos.get(id);      // record or null
-await todos.getAll();     // all records
-await todos.find((t) => !t.completed);
-```
-
-Semantics worth knowing:
-
-- **`put` replaces, `patch` merges.** Two devices patching *different* fields of the same record both win; patching the *same* field, the last write wins.
-- **`json` fields are atomic** — patching a `json` field replaces its whole value (no deep merge).
-- Writes are **validated locally** against your schema before queueing (same rules the server enforces), so typos fail fast with a thrown error instead of a round-trip.
-- In sync mode, `create` mints the id client-side — you get the full record back synchronously-ish, even offline.
-
-## Live queries
-
-`useQuery` re-runs your query and re-renders whenever the underlying data changes:
-
-```tsx
-const todos = useQuery(() => db.table("todos").getAll());               // undefined while loading
-const open  = useQuery(() => db.table("todos").find((t) => !t.completed));
-const one   = useQuery(() => db.table("todos").get(selectedId), [selectedId]); // deps like useEffect
-```
-
-For advanced queries, `table.ref` exposes the underlying [Dexie](https://dexie.org) table over the local view (sync mode only) — indexed fields from your schema are Dexie indexes:
-
-```tsx
-const recent = useQuery(() =>
-  db.table("todos").ref!.where("completed").equals(0).limit(10).toArray(),
-);
-```
-
-## Sync status, offline behavior & errors
-
-```tsx
-const sync = useSyncStatus();
-
-sync.status;        // 'idle' | 'local' | 'connecting' | 'online' | 'offline' | 'auth_required' | 'revoked' | 'stopped'
-sync.enabled;       // false when the schema is invalid/unpublished
-sync.pendingCount;  // local writes not yet confirmed by the server
-```
-
-`local` means the database is working without a connection — an anonymous workspace, an unpublished (version 0) schema during development, or a paused session.
-
-**Offline is not an error.** Writes keep working and queue in IndexedDB; reads serve the local view; everything pushes on reconnect (safe to retry — ops are idempotent). The queue survives page reloads — including offline cold starts: reloading with no network serves all data from the local replica.
-
-`revoked` means the user disconnected your app from their account — data access is gone until they sign in and consent again.
-
-### Rejected ops
-
-If the server terminally rejects a write (schema validation, permissions, payload too large), the SDK **rolls the record back**, parks the op in a rejected store, and will never retry it:
-
-```tsx
-const sync = useSyncStatus();
-const rejected = await sync.listRejected();
-// [{ op_id, op: { type, table, record_id, data }, error: 'SCHEMA_VALIDATION_FAILED', message, rejected_at }]
-await sync.clearRejected();
-```
-
-You can also listen live:
-
-```typescript
-const { client } = useBasic();
-useEffect(() => client.engine?.on("rejected", ({ rejection }) => {
-  toast.error(`write rejected: ${rejection.error}`);
-}), [client]);
-```
-
-## Shares (multiplayer)
-
-Users can grant other users access to a slice of their data — a whole table or specific records, read-only or read-write. Grants are created by the user on basic.id (apps can never share a user's data on their own); your app **lists** and **mounts** them:
-
-```tsx
-function SharedTodos() {
-  const { received } = useShares();          // shares other users granted to me
-  const share = received[0];
-  const { db: sharedDb, status } = useShare(share?.id); // 'mounting' | 'mounted' | 'error' | 'revoked'
-  const todos = useQuery(() => sharedDb?.table("todos").getAll(), [sharedDb]);
-
-  if (!share) return <p>nothing shared with you yet</p>;
-  if (status !== "mounted") return <p>{status}…</p>;
-
-  return (
-    <ul>
-      {todos?.map((t) => (
-        <li key={t.id} onClick={() => sharedDb!.table("todos").patch(t.id, { completed: true })}>
-          {String(t.title)}
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-Mounted shares live in their **own local keyspace** — separate replica, separate offline queue — and are never merged with the user's own data. Writes work when the share permission is `write` (the owner sees your changes attributed to the guest). When the owner revokes the share, the mount status flips to `revoked` and the local copy is purged.
-
-## Typed schemas
-
-`@basictech/schema` (a dependency of this package) can infer record types from your schema:
-
-```typescript
-import { defineSchema, type InferRecord } from "@basictech/schema";
-
-export const schema = defineSchema({
-  project_id: "…",
-  version: 1,
-  tables: {
-    todos: {
-      fields: {
-        title: { type: "string", required: true },
-        completed: { type: "boolean" },
-      },
-    },
-  },
-});
-
-type Todo = InferRecord<typeof schema, "todos">;
-// { id: string; title: string; completed?: boolean }
-
-const todos = db.table<Todo>("todos"); // fully typed CRUD
-```
-
-## REST mode
-
-Don't want a local replica? `mode="rest"` makes every table call a direct API request — no IndexedDB, no WebSocket, no offline support:
-
-```tsx
-<BasicProvider schema={schema} mode="rest">
-```
-
-The table API is identical, with REST semantics: `create` gets its id from the server, `put`/`patch`/`delete` on missing records return null/no-op, reads hit the network. `useQuery` won't live-update in this mode (re-run queries with deps).
-
-## API reference
-
-### `<BasicProvider>` props
-
-| Prop | Default | Description |
-| --- | --- | --- |
-| `schema` | — | Your Basic schema document (`project_id` is read from it) |
-| `mode` | `"sync"` | `"sync"` (local replica) or `"rest"` (direct API) |
-| `anonymous` | `true` | Local workspace without sign-in; merges into the account on sign-in |
-| `auth.scopes` | `"profile,email,app:admin"` | OAuth scopes to request |
-| `auth.pds_url` | `https://pds.basic.id` | The Basic server (auth + data + sync) |
-| `auth.sync_url` | `wss://<pds>/sync/` | Sync WebSocket URL (rarely needed) |
-| `storage` | `localStorage` | Custom `BasicStorage` adapter for auth state |
-| `debug` | `false` | Verbose console logging |
-| `devToolbar` | `false` | Floating status toolbar (dev environments only) |
-| `renderWhileLoading` | `false` | Render children before auth bootstrap finishes |
-
-### Hooks
-
-| Hook | Returns |
-| --- | --- |
-| `useBasic()` | Everything: auth fields + actions, `db`, `sync`, `users`, `activeUser`, `devInfo`, `client` |
-| `useAuth()` | `{ isReady, isSignedIn, isAnonymous, status, user, did, scope, hasScope, missingScopes, signIn, signInWithHandle, signInWithCode, signOut, getToken, getSignInUrl }` |
-| `useDb()` | The table API for the active user's own data |
-| `useQuery(fn, deps?)` | Live query result (`undefined` while loading); re-attaches automatically on user switch |
-| `useSyncStatus()` | `{ status, enabled, pendingCount, listRejected, clearRejected }` |
-| `useUsers()` | `{ users, activeUser, isAnonymous, switchUser, addUser, removeUser }` |
-| `useShares()` | `{ granted, received, isLoading, error, refresh }` |
-| `useShare(shareId)` | `{ db, status, error }` — a mounted share |
-
-Note on `useQuery` and user switching: the active user's identity is appended to your deps automatically, so queries that read `db` from the current render (via `useBasic()`/`useDb()`) re-attach to the new user's database on switch. If your query closure captures `db` from outside render, pass `[db]` in deps explicitly — or remount the subtree with `key={activeUser?.id}`.
-
-### Table API
-
-| Method | Sync mode | REST mode |
-| --- | --- | --- |
-| `create(data)` | client-minted id, offline-capable | server-minted id |
-| `put(id, data)` | create **or replace** | replace; throws if missing |
-| `patch(id, partial)` | merge; `null` if missing locally | merge; `null` if missing |
-| `delete(id)` | idempotent | no-op if missing |
-| `get(id)` / `getAll()` / `find(fn)` | local view | network |
-| `ref` | Dexie table (live queries, indexes) | `undefined` |
-
-## Advanced usage
-
-### Outside React
-
-Everything is available without React — `BasicClient` is the framework-agnostic core (`AuthManager` + `SyncEngine` + `RestClient`):
-
-```typescript
-import { createBasicClient } from "@basictech/react";
-
-const client = createBasicClient({ schema, debug: true });
-await client.start();
-client.subscribe(() => console.log(client.getSnapshot()));
-await client.db.table("todos").create({ title: "from anywhere" });
-```
-
-The Sync/2 protocol layer (`SyncEngine`, `SyncConnection`, `SyncStore`, and all wire types) is exported too, for building custom clients or other runtimes — pass a `WebSocketImpl` (e.g. the `ws` package) to run in Node.
-
-### Events
-
-```typescript
-const { client } = useBasic();
-client.engine?.on("status", (s) => {});                       // sync status changes
-client.engine?.on("change", ({ sub, tables }) => {});         // records changed
-client.engine?.on("rejected", ({ sub, rejection }) => {});    // terminal write rejection
-client.engine?.on("revoked", ({ code }) => {});               // app connection revoked
-```
-
-### Custom storage
-
-Auth state lives in `localStorage` by default. Provide any `{ get, set, remove }` async adapter via the `storage` prop (see `BasicStorage`). `STORAGE_KEYS` lists every key the SDK uses.
-
-## Migrating from 0.8
-
-0.9 is a breaking rewrite — the server's legacy sync endpoint was removed, so 0.8 sync no longer functions. Changes you'll make:
-
-| 0.8 | 0.9 |
-| --- | --- |
-| `db.collection("todos")` | `db.table("todos")` |
-| `.add(data)` | `.create(data)` |
-| `.update(id, partial)` | `.patch(id, partial)` |
-| `.put({ id, ...fields })` | `.put(id, fields)` |
-| `dbStatus` / `DBStatus` enum | `useSyncStatus().status` |
-| `dbMode="remote"` | `mode="rest"` |
-| `auth.ws_url` | `auth.sync_url` (you almost never need it) |
-| `signOut()` reloads the page | in-place teardown, no reload |
-
-Local data migrates by re-bootstrap: the old `basicdb` IndexedDB database is deleted automatically and 0.9 builds fresh replicas in `basic-sync:<project_id>` databases from the server (the server is the source of truth, so nothing is lost).
-
----
-
-## License
-
-ISC