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

package/changelog.md

@@ -1,5 +1,39 @@
 # 1.3.4
 
+## 0.9.0-beta.1
+
+### Minor Changes
+
+Local-first startup, anonymous mode, and multiple users.
+
+- **Anonymous mode (default on):** the local database works without a
+  session — writes queue as ordinary ops in a local-only workspace (sync
+  status `local`) and merge into the account automatically on sign-in via
+  the normal bootstrap+flush path (deferred identity — no copy step). Set
+  `anonymous={false}` on the provider for classic sign-in-required behavior.
+- **Offline cold start fixed:** the engine opens the local keyspace with no
+  token and no network (`openLocal()`), so reloading offline serves all data
+  from the replica; the connection acquires tokens with retry on its own.
+  `reauth_required` now *pauses* the connection instead of stopping the
+  engine — local reads/writes keep working while the user re-authenticates.
+- **Multiple users:** several local users (anonymous or signed-in) side by
+  side with per-tab switching. New `useUsers()` hook
+  (`users`, `activeUser`, `switchUser`, `addUser`, `removeUser`), profile
+  registry in localStorage, per-user auth storage namespacing and isolated
+  sync keyspaces (`basic-sync:{project}:{userId}`). Existing single-user
+  sessions are adopted as the first profile automatically.
+- **Owner guard:** keyspaces are stamped with the account DID at bootstrap;
+  local data from one account can never merge into another (a mismatched
+  keyspace is wiped before bootstrap). Also fixes a latent leak where
+  unpushed ops could survive an account change.
+- **User-aware `useQuery`:** the active user id is appended to query deps
+  automatically so live queries re-attach on user switches; in-flight
+  queries hitting a closing store during the switch return undefined and
+  re-run.
+- `signOut()` now wipes the active user's data and falls through to the next
+  local user (or a fresh anonymous workspace); `useAuth()` exposes
+  `isAnonymous`; sync status gains `local`.
+
 ## 0.9.0-beta.0
 
 ### Major Changes (breaking)

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 import React from 'react';
 import Dexie, { Table } from 'dexie';
-import { useLiveQuery } from 'dexie-react-hooks';
 
 interface BasicStorage {
     get(key: string): Promise<string | null>;
@@ -76,6 +75,12 @@ type AuthManagerConfig = {
     pdsUrl: string;
     adminUrl: string;
     debug: boolean;
+    /**
+     * Identifies which local user profile this manager belongs to (multi-user).
+     * Cross-tab events are scoped to it so a tab active on another profile
+     * ignores them. Defaults to '' (single-user / legacy profile).
+     */
+    instanceKey?: string;
 };
 /**
  * Framework-agnostic auth manager. Holds token state, handles OAuth flow,
@@ -110,11 +115,14 @@ declare class AuthManager {
     private sessionCheckPromise;
     private lastSessionCheckAt;
     constructor(config: AuthManagerConfig, storage: BasicStorage, notify: () => void);
+    private get instanceKey();
     private initCrossTabSync;
     private broadcastTokenRefresh;
     private broadcastSignIn;
     private broadcastSignOut;
     private broadcastSessionInvalidated;
+    /** Release resources (cross-tab channel). Used when switching users. */
+    destroy(): void;
     /**
      * Bootstrap auth: handle OAuth callback (?code=), restore session
      * from refresh token, or load cached user for offline mode.
@@ -535,6 +543,17 @@ declare class SyncStore {
     private get allStores();
     getCursor(): Promise<number | null>;
     getChannel(): Promise<string | null>;
+    /**
+     * The account DID this keyspace's confirmed data belongs to. Absent for
+     * anonymous-era data (which may be merged into whichever account signs in).
+     */
+    getOwner(): Promise<string | null>;
+    setOwner(did: string): Promise<void>;
+    /**
+     * Clear everything (views, server state, pending, rejected, meta) without
+     * deleting the database — used when the keyspace changes owners.
+     */
+    wipeAll(): Promise<void>;
     /** All pending ops in creation order (used to warm the in-memory queue). */
     loadPending(): Promise<PendingRow[]>;
     listRejected(): Promise<RejectedRow[]>;
@@ -586,7 +605,7 @@ declare class SyncStore {
     private recomputeViewRecord;
 }
 
-type SyncStatus = 'idle' | 'connecting' | 'online' | 'offline' | 'auth_required' | 'revoked' | 'stopped';
+type SyncStatus = 'idle' | 'local' | 'connecting' | 'online' | 'offline' | 'auth_required' | 'revoked' | 'stopped';
 declare const OWN_SUB = "own";
 declare function shareSubKey(shareId: string): string;
 interface PendingEntry {
@@ -668,6 +687,19 @@ interface SyncEngineOptions {
     }) => Promise<Snapshot>;
     /** Prefix for IndexedDB database names. Default `basic-sync`. */
     dbNamePrefix?: string;
+    /**
+     * Keyspace segment appended to database names (multi-user: the local user
+     * id). `''`/unset = the legacy single-user keyspace.
+     */
+    keyspaceId?: string;
+    /**
+     * The account DID the current session belongs to, consulted at bootstrap
+     * for the owner guard: a keyspace stamped with a different DID is wiped
+     * before bootstrapping (never merge one account's local data into
+     * another); an unstamped keyspace (anonymous-era data) keeps its pending
+     * ops — that is the anonymous → signed-in migration path.
+     */
+    getOwnerDid?: () => string | null | Promise<string | null>;
     /**
      * App name included in `subscribe` messages. Production derives the channel
      * from the token and ignores this; the sync-playground conformance server
@@ -688,7 +720,11 @@ declare class SyncEngine {
     private readonly subs;
     private limits;
     private actor;
-    private started;
+    /** Own-sub store is open (local reads/writes work). */
+    private storesOpen;
+    /** A live connection is wanted (vs. local-only / paused). */
+    private connectIntended;
+    private openingLocal;
     private revokedInfo;
     private connectionStatus;
     private _status;
@@ -705,8 +741,28 @@ declare class SyncEngine {
     get pendingCount(): number;
     listRejected(subKey?: string): Promise<RejectedRow[]>;
     clearRejected(subKey?: string): Promise<void>;
-    /** Open the own-channel keyspace and connect. Idempotent. */
+    /**
+     * Open the own-channel keyspace for local reads/writes — no connection,
+     * no token needed. This is the anonymous / offline-cold-start entry point.
+     * Idempotent.
+     */
+    openLocal(): Promise<void>;
+    /**
+     * Open the keyspace (if needed) and start syncing. Idempotent.
+     * Note: a `CONNECTION_REVOKED` latch is NOT cleared here — reconnecting a
+     * revoked app connection requires a fresh consent flow. Call
+     * {@link clearRevoked} (or rebind the engine) after re-authorization.
+     */
+    connect(): Promise<void>;
+    /** Clear the revocation latch (after the user re-authorized the app). */
+    clearRevoked(): void;
+    /** @deprecated alias of {@link connect} */
     start(): Promise<void>;
+    /**
+     * Disconnect but keep stores open: local reads/writes keep working and
+     * ops queue for the next connect. Used on reauth_required.
+     */
+    pause(): void;
     /** Close the socket and stores; local data is kept. */
     stop(): void;
     /**
@@ -760,6 +816,8 @@ declare class SyncEngine {
     /** Push unsent pending ops, chunked to `limits.max_ops_per_push`. */
     private flush;
     private get dbPrefix();
+    /** Base database name for this keyspace (multi-user: includes the user id). */
+    private get baseDbName();
     private enqueue;
     private timer;
     private recomputeStatus;
@@ -819,14 +877,104 @@ declare class RestDb implements BasicDb {
 }
 
 /**
- * BasicClient — the framework-agnostic SDK core. Owns:
- * - AuthManager (OAuth/PKCE, tokens, cross-tab session)
- * - SyncEngine  (Sync/2 client: local store, pending queue, WS connection)
+ * User registry — multiple local users per project (anonymous or signed-in),
+ * one active at a time, switchable.
+ *
+ * - Profiles live in localStorage under `basic_users:{projectId}` and are
+ *   shared across tabs.
+ * - The *active* user id is per-tab (sessionStorage) so different tabs can be
+ *   on different users; it survives the OAuth redirect, so a sign-in resumes
+ *   on the profile that initiated it. Falls back to the most recently active
+ *   profile.
+ * - Each profile owns an isolated sync keyspace and a namespaced slice of
+ *   auth storage (refresh token, cached userinfo, PKCE state, ...) via
+ *   `PrefixedStorage`.
+ * - A pre-multi-user session (0.9.0-beta.0: bare `basic_refresh_token` +
+ *   `basic-sync:{projectId}` keyspace) is adopted as the first profile with
+ *   empty prefix/keyspace — no key or IndexedDB renames.
+ */
+
+type BasicUserKind = 'anon' | 'account';
+interface BasicUserProfile {
+    /** Local profile id (uuid). Stable across sign-in upgrades. */
+    id: string;
+    kind: BasicUserKind;
+    /** Account identity, set once signed in. */
+    did?: string | null;
+    handle?: string | null;
+    email?: string | null;
+    name?: string | null;
+    picture?: string | null;
+    /**
+     * Keyspace segment for sync data. `''` = the legacy pre-multi-user
+     * keyspace (`basic-sync:{projectId}`); otherwise db names append it.
+     */
+    keyspace: string;
+    /**
+     * Prefix for this profile's auth storage keys. `''` = legacy unprefixed
+     * keys; otherwise `u:{id}:`.
+     */
+    storagePrefix: string;
+    createdAt: number;
+    lastActiveAt: number;
+}
+/** Namespaces every key of an underlying BasicStorage adapter. */
+declare class PrefixedStorage implements BasicStorage {
+    private readonly inner;
+    readonly prefix: string;
+    constructor(inner: BasicStorage, prefix: string);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+declare class UserRegistry {
+    private readonly storage;
+    private readonly projectId;
+    constructor(storage: BasicStorage, projectId: string);
+    list(): Promise<BasicUserProfile[]>;
+    private save;
+    get(id: string): Promise<BasicUserProfile | null>;
+    createAnon(): Promise<BasicUserProfile>;
+    update(id: string, patch: Partial<Omit<BasicUserProfile, 'id' | 'keyspace' | 'storagePrefix'>>): Promise<BasicUserProfile | null>;
+    remove(id: string): Promise<void>;
+    /** The profile (if any) already bound to an account DID. */
+    findByDid(did: string): Promise<BasicUserProfile | null>;
+    private getActiveIdRaw;
+    setActiveId(id: string): void;
+    private clearActiveId;
+    /**
+     * Resolve the active profile for this tab: sessionStorage choice if it
+     * still exists, else the most recently active profile, else null.
+     */
+    resolveActive(): Promise<BasicUserProfile | null>;
+    touch(id: string): Promise<void>;
+    /**
+     * Adopt a pre-multi-user session as the first profile. Idempotent: runs
+     * only when the registry is empty and a bare refresh token exists. The
+     * adopted profile keeps the unprefixed storage keys and the legacy
+     * keyspace name, so nothing needs to move.
+     */
+    adoptLegacySession(): Promise<BasicUserProfile | null>;
+}
+
+/**
+ * BasicClient — the framework-agnostic SDK core. Owns, per active user:
+ * - AuthManager (OAuth/PKCE, tokens, cross-tab session; storage namespaced
+ *   per local user profile)
+ * - SyncEngine  (Sync/2 client on the profile's own keyspace)
  * - RestClient  (REST v2: snapshot/changes bootstrap, shares, CRUD)
  *
- * and orchestrates them: sync connects when a healthy session exists, stops
- * on reauth_required, and tears down local data on sign-out (no page reload).
- * The React layer (`BasicProvider` + hooks) is a thin subscriber.
+ * plus the multi-user registry: several local users (anonymous or signed-in)
+ * exist side by side, one active at a time per tab, switchable.
+ *
+ * Local-first rules:
+ * - The local keyspace opens with no token and no network (anonymous mode is
+ *   on by default; offline cold start works).
+ * - Anonymous writes are pending ops; sign-in upgrades the profile in place
+ *   and the normal bootstrap+flush merges them into the account.
+ * - `reauth_required` pauses the connection but keeps local reads/writes.
+ * - Sign-out wipes the profile's local data and falls through to the next
+ *   (or a fresh anonymous) user. No page reloads.
  */
 
 type BasicMode = 'sync' | 'rest';
@@ -853,6 +1001,11 @@ interface BasicClientConfig {
     debug?: boolean;
     /** 'sync' (offline-first local replica, default) or 'rest' (direct API). */
     mode?: BasicMode;
+    /**
+     * Anonymous/local-first usage (sync mode only, default true): the local db
+     * works without a session; data merges into the account on sign-in.
+     */
+    anonymous?: boolean;
     /** Node/testing: pass the `ws` constructor. */
     WebSocketImpl?: typeof WebSocket;
 }
@@ -881,36 +1034,64 @@ interface BasicClientSnapshot {
     syncEnabled: boolean;
     devInfo: BasicSchemaDevInfo | null;
     mode: BasicMode;
+    /** All local user profiles (anonymous and signed-in). */
+    users: BasicUserProfile[];
+    /** The profile active in this tab. */
+    activeUser: BasicUserProfile | null;
+    /** Active profile has no account yet (local-only workspace). */
+    isAnonymous: boolean;
 }
 interface ShareMountHandle {
     shareId: string;
     db: BasicDb;
 }
 declare class BasicClient {
-    readonly auth: AuthManager;
     readonly rest: RestClient;
-    readonly engine: SyncEngine | null;
     readonly mode: BasicMode;
     readonly config: BasicClientConfig;
     readonly projectId: string | undefined;
-    private readonly syncDb;
+    readonly users: UserRegistry | null;
+    private readonly rawStorage;
     private readonly restDb;
     private readonly debug;
+    private readonly anonymousEnabled;
+    private readonly authConfig;
+    private readonly syncUrl;
+    private binding;
+    private usersCache;
     private devInfo;
     private syncEnabled;
     private schemaChecked;
     private started;
-    private cleanupFns;
+    private signOutInProgress;
+    /** Serializes profile transitions (switch, dispose, sign-out fallthrough). */
+    private profileOps;
     private mounts;
     private listeners;
     private snapshot;
     constructor(config: BasicClientConfig);
-    /** The database handle: offline-first in sync mode, direct API in rest mode. */
+    get auth(): AuthManager;
+    get engine(): SyncEngine | null;
+    /** The database handle for the active user. Identity changes on switch. */
     get db(): BasicDb;
-    /** Bootstrap: version migrations, schema check, auth initialization. */
+    get activeUser(): BasicUserProfile | null;
+    /** Bootstrap: version migrations, profile resolution, schema check, auth init. */
     start(): Promise<void>;
-    /** Sign out: server-side revoke, local auth clear, sync teardown + purge. */
+    /**
+     * Sign out the active user: server-side revoke, wipe the profile's local
+     * data, drop the profile, and fall through to the next (or a fresh
+     * anonymous) user.
+     */
     signOut(): Promise<void>;
+    /** Switch this tab to another local user. */
+    switchUser(id: string): Promise<void>;
+    /** Create a fresh anonymous user and switch to it. */
+    addUser(): Promise<BasicUserProfile>;
+    /**
+     * Remove a local user: best-effort server-side revoke, wipe its keyspace
+     * and auth storage, drop the profile. Removing the active user signs out.
+     */
+    removeUser(id: string): Promise<void>;
     /** Stop connections and listeners; local data is kept. */
     stop(): void;
     /** Re-run the remote schema status check (dev toolbar). */
@@ -930,10 +1111,38 @@ declare class BasicClient {
     getMountedShare(shareId: string): ShareMountHandle | undefined;
     subscribe: (listener: () => void) => (() => void);
     getSnapshot: () => BasicClientSnapshot;
+    private createBinding;
+    /**
+     * Bind and boot a profile. Publishes the new binding first so React
+     * subscriptions re-attach to the new db, then tears the old binding down
+     * on the next tick (avoids in-flight live queries hitting a closed store).
+     */
+    private activateProfile;
+    private bindingMatches;
+    /** After sign-out/disposal: resume on the next profile or a fresh anon one. */
+    private activateNextProfileLocked;
+    /** Wipe a (non-active) profile's local footprint: keyspace dbs + auth keys. */
+    private disposeProfileData;
+    private deleteKeyspaceDatabases;
+    /** Previous auth status, for transition detection (revoked-latch clearing). */
+    private lastAuthStatus;
     private handleAuthChange;
-    private maybeStartSync;
-    private teardownLocalData;
-    private wireEngineEvents;
+    /**
+     * Drive the engine from auth + schema state:
+     * - local keyspace opens with no token (anonymous mode / offline cold start)
+     * - connect when a session exists (recovering counts — the connection
+     *   retries token acquisition itself)
+     * - reauth_required pauses the connection, keeps local data usable
+     */
+    private syncLifecycle;
+    /**
+     * After sign-in: bind the account identity to the active profile
+     * (anonymous → account upgrade) and dedupe against an existing profile
+     * for the same DID.
+     */
+    private maybeUpgradeProfile;
+    private refreshUsers;
+    private queueProfileOp;
     private checkSchema;
     private buildSnapshot;
     private publish;
@@ -954,6 +1163,12 @@ interface BasicProviderProps {
      * - 'rest': direct REST calls, no local persistence
      */
     mode?: BasicMode;
+    /**
+     * Anonymous/local-first usage (sync mode only, default true): the db works
+     * without a session and local data merges into the account on sign-in.
+     * Set false to require sign-in before any local data exists.
+     */
+    anonymous?: boolean;
     /** Show the floating dev toolbar (localhost / NODE_ENV=development / debug). */
     devToolbar?: boolean;
     /**
@@ -962,24 +1177,32 @@ interface BasicProviderProps {
      */
     renderWhileLoading?: boolean;
 }
-declare function BasicProvider({ children, schema, project_id, auth, storage, debug, mode, devToolbar, renderWhileLoading, }: BasicProviderProps): React.JSX.Element;
+declare function BasicProvider({ children, schema, project_id, auth, storage, debug, mode, anonymous, devToolbar, renderWhileLoading, }: BasicProviderProps): React.JSX.Element;
 
 /**
- * Reactive live queries against the local database (sync mode).
- * Re-export of dexie-react-hooks' `useLiveQuery` — any read through
- * `db.table(...)` (or its `ref` Dexie table) is observable.
+ * Reactive live queries against the local database (sync mode), built on
+ * dexie-react-hooks' `useLiveQuery`. Any read through `db.table(...)` (or
+ * its `ref` Dexie table) is observable.
  *
  * ```tsx
  * const todos = useQuery(() => db.table('todos').getAll())
  * ```
+ *
+ * User-aware: the active user's id is appended to `deps` automatically, so
+ * queries re-subscribe against the new user's database on `switchUser` /
+ * sign-in / sign-out — provided the query reads `db` from the current render
+ * (e.g. from `useBasic()`/`useDb()`). For closures created outside render,
+ * pass `[db]` in deps explicitly.
  */
-declare const useQuery: typeof useLiveQuery;
+declare function useQuery<T>(querier: () => T | Promise<T | undefined> | undefined, deps?: unknown[]): T | undefined;
 /** The BasicClient instance from the nearest provider. */
 declare function useBasicClient(): BasicClient;
 interface UseAuthResult {
     /** Auth bootstrap finished (a session may or may not exist). */
     isReady: boolean;
     isSignedIn: boolean;
+    /** Active user is a local-only (anonymous) workspace with no account. */
+    isAnonymous: boolean;
     status: AuthStatus;
     errorCode: string | null;
     user: User | null;
@@ -1035,15 +1258,34 @@ interface UseShareResult {
  * pending queue — never merged with your own data.
  */
 declare function useShare(shareId: string | null | undefined): UseShareResult;
+interface UseUsersResult {
+    /** All local user profiles (anonymous and signed-in), shared across tabs. */
+    users: BasicUserProfile[];
+    /** The profile active in this tab. */
+    activeUser: BasicUserProfile | null;
+    isAnonymous: boolean;
+    /** Switch this tab to another local user. */
+    switchUser: (id: string) => Promise<void>;
+    /** Create a fresh anonymous user and switch to it. */
+    addUser: () => Promise<BasicUserProfile>;
+    /** Remove a local user (wipes its local data; active user = sign out). */
+    removeUser: (id: string) => Promise<void>;
+}
+/** Multiple local users (anonymous or signed-in) with per-tab switching. */
+declare function useUsers(): UseUsersResult;
 interface UseBasicResult extends UseAuthResult {
     db: BasicDb;
     sync: UseSyncStatusResult;
+    /** All local user profiles. */
+    users: BasicUserProfile[];
+    /** The profile active in this tab. */
+    activeUser: BasicUserProfile | null;
     /** Local schema vs server status; null if no schema on the provider. */
     devInfo: BasicClientSnapshot['devInfo'];
     refreshSchemaStatus: () => Promise<void>;
     client: BasicClient;
 }
-/** Umbrella hook: auth + db + sync status. */
+/** Umbrella hook: auth + db + sync status + users. */
 declare function useBasic(): UseBasicResult;
 
 /**
@@ -1149,4 +1391,4 @@ type BasicDevToolbarProps = {
  */
 declare function BasicDevToolbar({ enabled, debug }: BasicDevToolbarProps): React.JSX.Element | null;
 
-export { AuthManager, type AuthResult, type AuthStatus, type BasicAuthConfig, BasicClient, type BasicClientConfig, type BasicClientSnapshot, type BasicDb, BasicDevToolbar, type BasicDevToolbarProps, type BasicMode, BasicProvider, type BasicProviderProps, type BasicRecord, type BasicSchemaDevInfo, type BasicStorage, type BasicTable, type ChangesPage, type ConnectionStatus, DEFAULT_LIMITS, type GetTokenOptions$1 as GetTokenOptions, LocalStorageAdapter, type LoggedOp, NotAuthenticatedError, OWN_SUB, type OpEnvelope, type OpType, PROTOCOL_VERSION, type PdsEndpoints, type PendingRow, type PushResult, type RejectedRow, type ResolvedDid, RestClient, type RestClientOptions, RestDb, RestError, type RestRecord, STORAGE_KEYS, type Share, type ShareMountHandle, type SharePermission, type ShareSelector, type Snapshot, type SubscriptionState, SyncConnection, SyncDb, SyncEngine, type SyncEngineEvents, type SyncEngineOptions, type SyncErrorCode, type SyncLimits, type SyncStatus, SyncStore, type SyncStoreSchema, type Token, type UseAuthResult, type UseBasicResult, type UseShareResult, type UseSharesResult, type UseSyncStatusResult, type User, applyOpToData, createBasicClient, isAuthError, isRebootstrapError, isRevocationError, isTerminalOpError, mintOpId, resolveDid, resolveDidWebUrl, resolveHandle, shareSubKey, useAuth, useBasic, useBasicClient, useDb, useQuery, useShare, useShares, useSyncStatus };
+export { AuthManager, type AuthResult, type AuthStatus, type BasicAuthConfig, BasicClient, type BasicClientConfig, type BasicClientSnapshot, type BasicDb, BasicDevToolbar, type BasicDevToolbarProps, type BasicMode, BasicProvider, type BasicProviderProps, type BasicRecord, type BasicSchemaDevInfo, type BasicStorage, type BasicTable, type BasicUserKind, type BasicUserProfile, type ChangesPage, type ConnectionStatus, DEFAULT_LIMITS, type GetTokenOptions$1 as GetTokenOptions, LocalStorageAdapter, type LoggedOp, NotAuthenticatedError, OWN_SUB, type OpEnvelope, type OpType, PROTOCOL_VERSION, type PdsEndpoints, type PendingRow, PrefixedStorage, type PushResult, type RejectedRow, type ResolvedDid, RestClient, type RestClientOptions, RestDb, RestError, type RestRecord, STORAGE_KEYS, type Share, type ShareMountHandle, type SharePermission, type ShareSelector, type Snapshot, type SubscriptionState, SyncConnection, SyncDb, SyncEngine, type SyncEngineEvents, type SyncEngineOptions, type SyncErrorCode, type SyncLimits, type SyncStatus, SyncStore, type SyncStoreSchema, type Token, type UseAuthResult, type UseBasicResult, type UseShareResult, type UseSharesResult, type UseSyncStatusResult, type UseUsersResult, type User, UserRegistry, applyOpToData, createBasicClient, isAuthError, isRebootstrapError, isRevocationError, isTerminalOpError, mintOpId, resolveDid, resolveDidWebUrl, resolveHandle, shareSubKey, useAuth, useBasic, useBasicClient, useDb, useQuery, useShare, useShares, useSyncStatus, useUsers };