@bunbase-ae/react-sdk 1.0.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@bunbase-ae/react-sdk",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "React hooks for BunBase — caching, mutations, auth, realtime",
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19",
+    "@bunbase-ae/js": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Context.tsx

@@ -0,0 +1,106 @@
+import type { BunBaseClient } from "@bunbase-ae/js";
+import { createContext, type ReactNode, useContext, useEffect, useState } from "react";
+import { QueryCache, type QueryCacheStorage } from "./cache";
+
+interface BunBaseContextValue {
+  client: BunBaseClient;
+  cache: QueryCache;
+}
+
+const BunBaseContext = createContext<BunBaseContextValue | null>(null);
+
+export function BunBaseProvider({
+  client,
+  cacheStorage,
+  storagePrefix,
+  clearCacheOnLogout = false,
+  fallback = null,
+  children,
+}: {
+  client: BunBaseClient;
+  /**
+   * Optional persistent storage adapter. Pass `localStorageAdapter` for web,
+   * or an AsyncStorage-compatible adapter for React Native.
+   *
+   * When provided, the cache is hydrated from storage before children render,
+   * eliminating loading states on subsequent visits.
+   */
+  cacheStorage?: QueryCacheStorage;
+  /**
+   * Prefix for storage keys. Default: `"bb_cache:"`.
+   * Override to namespace multiple BunBase apps sharing the same storage.
+   */
+  storagePrefix?: string;
+  /**
+   * What to clear from the cache (memory + storage) when the user logs out.
+   *
+   * - `false` (default) — nothing is cleared; all cached data survives logout.
+   *   Use this when your app has public data you want to keep showing.
+   * - `true` — clears the entire cache on logout.
+   * - `string[]` — clears only entries whose cache key starts with one of
+   *   these prefixes. Use this to wipe user-specific collections while keeping
+   *   public ones cached.
+   *
+   * @example
+   * // Keep public horse listings, clear private orders on logout
+   * clearCacheOnLogout={["collection:orders", "collection:my-horses"]}
+   */
+  clearCacheOnLogout?: boolean | string[];
+  /**
+   * Rendered while the cache is hydrating from storage.
+   * Only relevant when `cacheStorage` is provided. Default: `null`.
+   */
+  fallback?: ReactNode;
+  children: ReactNode;
+}): ReactNode {
+  const [cache] = useState(() => new QueryCache({ storage: cacheStorage, storagePrefix }));
+  const [hydrated, setHydrated] = useState(!cacheStorage);
+
+  // Hydrate from storage before first render when a storage adapter is provided.
+  useEffect(() => {
+    if (!cacheStorage) return;
+    cache.hydrate().then(() => setHydrated(true));
+  }, [cache, cacheStorage]);
+
+  // Keep the realtime connection open whenever the user is authenticated so that
+  // server-pushed auth events (session_revoked, password_changed, etc.) are delivered
+  // immediately — even when no data subscriptions are active.
+  useEffect(() => {
+    // Connect now if a session is already present (e.g. restored from storage).
+    if (client.auth.isAuthenticated()) client.realtime.connect();
+
+    // Connect on login, disconnect on logout. Clear cache on logout if configured.
+    return client.auth.onAuthChange((session) => {
+      if (session) {
+        client.realtime.connect();
+      } else {
+        client.realtime.disconnect();
+        if (clearCacheOnLogout === true) {
+          cache.clear();
+        } else if (Array.isArray(clearCacheOnLogout)) {
+          for (const prefix of clearCacheOnLogout) cache.clear(prefix);
+        }
+      }
+    });
+  }, [client, cache, clearCacheOnLogout]);
+
+  // Refetch stale entries when the tab becomes visible again.
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    function onVisibility() {
+      if (document.visibilityState === "visible") cache.refetchStale();
+    }
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => document.removeEventListener("visibilitychange", onVisibility);
+  }, [cache]);
+
+  if (!hydrated) return <>{fallback}</>;
+
+  return <BunBaseContext.Provider value={{ client, cache }}>{children}</BunBaseContext.Provider>;
+}
+
+export function useBunBase(): BunBaseContextValue {
+  const ctx = useContext(BunBaseContext);
+  if (!ctx) throw new Error("useBunBase must be called inside <BunBaseProvider>.");
+  return ctx;
+}

package/src/cache.ts

@@ -0,0 +1,403 @@
+// QueryCache — stale-while-revalidate cache for BunBase React hooks.
+//
+// Semantics:
+//   - First fetch:   loading → success/error, subscribers notified.
+//   - Stale refetch: show stale data immediately, refetch in background, notify when done.
+//   - Deduplication: concurrent fetches for the same key share one in-flight Promise.
+//   - Invalidation:  clear matching keys and notify subscribers to trigger re-fetch.
+//   - Shallow equal: background refetch results are compared shallowly to existing data;
+//                    if nothing changed, subscribers are NOT notified (no re-render).
+//   - Storage:       optional persistent storage adapter (localStorage, AsyncStorage, etc.)
+//                    Entries are hydrated on init and flushed on every write.
+
+type Notify = () => void;
+
+export interface CacheEntry {
+  data: unknown;
+  error: Error | null;
+  /** "loading" = no data yet. "success"/"error" = settled (may be stale). */
+  status: "loading" | "success" | "error";
+  /** Timestamp (ms) when data becomes stale. 0 = already stale. */
+  staleAt: number;
+  /** In-flight Promise — used for deduplication. */
+  promise: Promise<void> | null;
+  /** Stored so focus-triggered refetch can re-run without external reference. */
+  fetcher: (() => Promise<unknown>) | null;
+  staleTime: number;
+}
+
+// ─── Storage adapter ─────────────────────────────────────────────────────────
+
+/**
+ * Pluggable storage adapter for persisting the query cache across sessions.
+ *
+ * Both `localStorage` (via `localStorageAdapter`) and React Native's
+ * `AsyncStorage` fit this interface — all methods may return a Promise or a
+ * plain value.
+ */
+export interface QueryCacheStorage {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+  /** Return all keys currently in storage (used for hydration and prefix invalidation). */
+  getAllKeys(): string[] | Promise<string[]>;
+}
+
+/** Ready-to-use adapter for the browser `localStorage` API. */
+export const localStorageAdapter: QueryCacheStorage = {
+  getItem: (key) => localStorage.getItem(key),
+  setItem: (key, value) => localStorage.setItem(key, value),
+  removeItem: (key) => localStorage.removeItem(key),
+  getAllKeys: () => Object.keys(localStorage),
+};
+
+// What gets written to storage — excludes non-serialisable fields.
+type StoredEntry = { data: unknown; staleAt: number; staleTime: number };
+
+// ─── Shallow equality ────────────────────────────────────────────────────────
+//
+// Compares two values one level deep.
+//   - Primitives: strict equality.
+//   - Arrays: same length + each element ===.
+//   - Objects: same keys + each value ===.
+// Good enough for flat records and ListResult shapes. Deep nesting (expand,
+// nested objects) will still trigger a re-render, which is the safe default.
+
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== "object" || typeof b !== "object") return false;
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  }
+
+  if (Array.isArray(a) || Array.isArray(b)) return false;
+
+  const aObj = a as Record<string, unknown>;
+  const bObj = b as Record<string, unknown>;
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!(key in bObj) || aObj[key] !== bObj[key]) return false;
+  }
+  return true;
+}
+
+// ─── QueryCache ───────────────────────────────────────────────────────────────
+
+export interface QueryCacheOptions {
+  storage?: QueryCacheStorage;
+  /**
+   * Prefix applied to every storage key to avoid collisions with other data
+   * in the same storage. Default: `"bb_cache:"`.
+   */
+  storagePrefix?: string;
+}
+
+export class QueryCache {
+  private readonly entries = new Map<string, CacheEntry>();
+  private readonly subs = new Map<string, Set<Notify>>();
+  private readonly focusSubs = new Set<Notify>();
+  private readonly storage: QueryCacheStorage | undefined;
+  private readonly prefix: string;
+
+  constructor(options: QueryCacheOptions = {}) {
+    this.storage = options.storage;
+    this.prefix = options.storagePrefix ?? "bb_cache:";
+  }
+
+  // ─── Storage helpers ──────────────────────────────────────────────────────
+
+  private storageKey(key: string): string {
+    return `${this.prefix}${key}`;
+  }
+
+  private persist(key: string, entry: CacheEntry): void {
+    if (!this.storage) return;
+    const stored: StoredEntry = {
+      data: entry.data,
+      staleAt: entry.staleAt,
+      staleTime: entry.staleTime,
+    };
+    // Fire-and-forget — storage writes must not block the in-memory cache.
+    Promise.resolve(this.storage.setItem(this.storageKey(key), JSON.stringify(stored))).catch(
+      () => {},
+    );
+  }
+
+  /**
+   * Hydrate the in-memory cache from storage.
+   * Call this once before rendering and await it — entries will be available
+   * immediately so hooks show data on the very first render without a loading state.
+   * Stale entries are hydrated too; hooks will background-refetch them as usual.
+   */
+  async hydrate(): Promise<void> {
+    if (!this.storage) return;
+    try {
+      const allKeys = await this.storage.getAllKeys();
+      const cacheKeys = allKeys.filter((k) => k.startsWith(this.prefix));
+      await Promise.all(
+        cacheKeys.map(async (storageKey) => {
+          try {
+            const raw = await this.storage?.getItem(storageKey);
+            if (!raw) return;
+            const stored = JSON.parse(raw) as StoredEntry;
+            const internalKey = storageKey.slice(this.prefix.length);
+            // Don't overwrite entries that may have been set before hydration.
+            if (this.entries.has(internalKey)) return;
+            this.entries.set(internalKey, {
+              data: stored.data,
+              error: null,
+              status: "success",
+              staleAt: stored.staleAt,
+              promise: null,
+              fetcher: null,
+              staleTime: stored.staleTime,
+            });
+          } catch {
+            // Corrupt entry — skip silently.
+          }
+        }),
+      );
+    } catch {
+      // Storage unavailable (e.g. privacy mode) — start with empty cache.
+    }
+  }
+
+  // ─── Subscriptions ──────────────────────────────────────────────────────────
+
+  subscribe(key: string, fn: Notify): () => void {
+    let set = this.subs.get(key);
+    if (!set) {
+      set = new Set();
+      this.subs.set(key, set);
+    }
+    set.add(fn);
+    return () => {
+      const s = this.subs.get(key);
+      if (!s) return;
+      s.delete(fn);
+      if (s.size === 0) this.subs.delete(key);
+    };
+  }
+
+  /** Register a callback that fires when the window regains focus. */
+  onFocus(fn: Notify): () => void {
+    this.focusSubs.add(fn);
+    return () => this.focusSubs.delete(fn);
+  }
+
+  /** Called by BunBaseProvider on visibilitychange. */
+  triggerFocus(): void {
+    for (const fn of this.focusSubs) fn();
+  }
+
+  private notify(key: string): void {
+    const set = this.subs.get(key);
+    if (!set) return;
+    for (const fn of set) fn();
+  }
+
+  // ─── Read ───────────────────────────────────────────────────────────────────
+
+  get(key: string): CacheEntry | undefined {
+    return this.entries.get(key);
+  }
+
+  isStale(key: string): boolean {
+    const e = this.entries.get(key);
+    if (!e || e.status !== "success") return true;
+    return Date.now() >= e.staleAt;
+  }
+
+  // ─── Fetch ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Fetch data for `key` using `fetcher`.
+   *
+   * - If data is fresh: no-op (returns immediately).
+   * - If stale or missing: fetches in background; shows stale data while fetching (SWR).
+   * - If already in flight: deduplicates (does nothing).
+   * - If new data is shallowly equal to existing: updates staleAt but skips notify.
+   */
+  fetch(key: string, fetcher: () => Promise<unknown>, staleTime: number): void {
+    const existing = this.entries.get(key);
+
+    // Deduplicate concurrent fetches.
+    if (existing?.promise) return;
+
+    // Data is fresh — nothing to do.
+    if (existing?.status === "success" && Date.now() < existing.staleAt) return;
+
+    // Keep existing data visible while refetching (SWR).
+    const entry: CacheEntry = {
+      data: existing?.data,
+      error: null,
+      status: existing?.data !== undefined ? "success" : "loading",
+      staleAt: existing?.staleAt ?? 0,
+      promise: null,
+      fetcher,
+      staleTime,
+    };
+
+    const promise: Promise<void> = fetcher().then(
+      (data) => {
+        if (this.entries.get(key)?.promise !== promise) return; // superseded
+        const prev = this.entries.get(key);
+        const changed = !shallowEqual(prev?.data, data);
+        const next: CacheEntry = {
+          data,
+          error: null,
+          status: "success",
+          staleAt: Date.now() + staleTime,
+          promise: null,
+          fetcher,
+          staleTime,
+        };
+        this.entries.set(key, next);
+        this.persist(key, next);
+        // Skip re-render if data is identical.
+        if (changed) this.notify(key);
+      },
+      (err: unknown) => {
+        const current = this.entries.get(key);
+        if (current?.promise !== promise) return;
+        this.entries.set(key, {
+          data: current?.data,
+          error: err instanceof Error ? err : new Error(String(err)),
+          status: "error",
+          staleAt: 0,
+          promise: null,
+          fetcher,
+          staleTime,
+        });
+        this.notify(key);
+      },
+    );
+
+    entry.promise = promise;
+    this.entries.set(key, entry);
+
+    // Only notify for loading state when there's no cached data to show yet.
+    if (existing?.data === undefined) this.notify(key);
+  }
+
+  /** Force a re-fetch regardless of freshness. */
+  refetch(key: string): void {
+    const entry = this.entries.get(key);
+    if (!entry?.fetcher) return;
+    this.entries.set(key, { ...entry, staleAt: 0, promise: null });
+    this.fetch(key, entry.fetcher, entry.staleTime);
+  }
+
+  // ─── Invalidation ────────────────────────────────────────────────────────────
+
+  /**
+   * Mark all entries whose key starts with `prefix` as stale and notify subscribers.
+   *
+   * Data is KEPT so components remain in a loaded state (not loading) while the
+   * background re-fetch runs. Subscribers should call `cache.fetch()` when they
+   * receive a notification and find the entry is stale.
+   */
+  invalidate(prefix: string): void {
+    const toNotify: string[] = [];
+    for (const [key, entry] of this.entries) {
+      if (key.startsWith(prefix)) {
+        this.entries.set(key, { ...entry, staleAt: 0, promise: null });
+        toNotify.push(key);
+      }
+    }
+    for (const key of toNotify) this.notify(key);
+  }
+
+  /**
+   * Write data only if the key has no existing entry.
+   * Used to pre-populate record caches from list results without
+   * overwriting fresher data from a direct fetch or realtime event.
+   */
+  setDataIfMissing(key: string, data: unknown, staleTime: number): void {
+    if (this.entries.has(key)) return;
+    const entry: CacheEntry = {
+      data,
+      error: null,
+      status: "success",
+      staleAt: Date.now() + staleTime,
+      promise: null,
+      fetcher: null,
+      staleTime,
+    };
+    this.entries.set(key, entry);
+    this.persist(key, entry);
+    this.notify(key);
+  }
+
+  /** Manually set cache data (optimistic updates, mutation results, realtime events). */
+  setData(key: string, data: unknown): void {
+    const existing = this.entries.get(key);
+    // Skip notify if data hasn't changed — still bump staleAt.
+    if (shallowEqual(existing?.data, data)) {
+      if (existing) existing.staleAt = Date.now() + existing.staleTime;
+      return;
+    }
+    const staleTime = existing?.staleTime ?? 30_000;
+    const entry: CacheEntry = {
+      data,
+      error: null,
+      status: "success",
+      staleAt: Date.now() + staleTime,
+      promise: null,
+      fetcher: existing?.fetcher ?? null,
+      staleTime,
+    };
+    this.entries.set(key, entry);
+    this.persist(key, entry);
+    this.notify(key);
+  }
+
+  /**
+   * Remove entries from memory and persistent storage.
+   *
+   * @param prefix - If provided, only entries whose key starts with this string
+   *   are removed. Omit to clear everything.
+   *
+   * Subscribers are notified so components transition back to a loading state.
+   * Fire-and-forget for storage — the in-memory cache is always updated synchronously.
+   *
+   * @example
+   * // Clear everything (e.g. full sign-out)
+   * cache.clear();
+   *
+   * // Clear only user-specific collections (keep public data)
+   * cache.clear("collection:orders");
+   */
+  clear(prefix?: string): void {
+    const toDelete: string[] = [];
+    for (const key of this.entries.keys()) {
+      if (!prefix || key.startsWith(prefix)) toDelete.push(key);
+    }
+    for (const key of toDelete) {
+      this.entries.delete(key);
+      if (this.storage) {
+        Promise.resolve(this.storage.removeItem(this.storageKey(key))).catch(() => {});
+      }
+      this.notify(key);
+    }
+  }
+
+  /** Re-fetch all stale or errored entries. Called on window focus. */
+  refetchStale(): void {
+    for (const [key, entry] of this.entries) {
+      if (!entry.fetcher) continue;
+      const isStale = entry.status === "error" || Date.now() >= entry.staleAt;
+      if (isStale && !entry.promise) {
+        this.fetch(key, entry.fetcher, entry.staleTime);
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+// @bunbase/react — React hooks for BunBase
+//
+// Usage:
+//   import { BunBaseProvider, useList, useCreate, useAuth } from "@bunbase-ae/react-sdk;
+//
+//   const client = new BunBaseClient({ url: "https://api.example.com" });
+//
+//   function App() {
+//     return (
+//       <BunBaseProvider client={client}>
+//         <Posts />
+//       </BunBaseProvider>
+//     );
+//   }
+//
+//   function Posts() {
+//     const { data, loading, error } = useList("posts", { sort: "-_created_at" });
+//     const create = useCreate("posts");
+//     // ...
+//   }
+
+export type { WithExpand } from "@bunbase-ae/js";
+export { BunBaseProvider, useBunBase } from "./Context";
+export type { CacheEntry, QueryCacheOptions, QueryCacheStorage } from "./cache";
+export { localStorageAdapter, QueryCache } from "./cache";
+export type { UploadOptions } from "./types";
+export type { UseAuthResult } from "./useAuth";
+export { useAuth } from "./useAuth";
+export type { UseListOptions, UseListResult } from "./useList";
+export { useList } from "./useList";
+export type { MutationResult } from "./useMutation";
+export { useCreate, useDelete, useUpdate } from "./useMutation";
+export type { UsePresenceResult, UseRealtimeOptions, UseRealtimeResult } from "./useRealtime";
+export {
+  useCollectionEvents,
+  usePresence,
+  useRealtime,
+  useRecordEvents,
+} from "./useRealtime";
+export type { UseRecordOptions, UseRecordResult } from "./useRecord";
+export { useRecord } from "./useRecord";
+export type { UseUploadResult } from "./useUpload";
+export { useUpload } from "./useUpload";

package/src/types.ts

@@ -0,0 +1 @@
+export type { SignedUploadResult, UploadOptions } from "@bunbase-ae/js";

package/src/useAuth.ts

@@ -0,0 +1,174 @@
+// useAuth — reactive auth state with optional selector to prevent extra re-renders.
+//
+// Basic usage (re-renders on any auth state change):
+//   const { user, isAuthenticated, login, logout } = useAuth();
+//
+// Selector usage (re-renders ONLY when the selected value changes):
+//   const user = useAuth(s => s.user);
+//   const isAuth = useAuth(s => s.isAuthenticated);
+//   const { user, loading } = useAuth(s => ({ user: s.user, loading: s.loading }));
+//
+// Shallow equality is used for selector results — objects are compared by their
+// own enumerable properties so { user, loading } won't trigger a re-render when
+// neither value changed.
+
+import type { AuthUser, LoginResult } from "@bunbase-ae/js";
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { useBunBase } from "./Context";
+
+export interface UseAuthResult {
+  user: AuthUser | null;
+  /** True while the initial auth check is running. */
+  loading: boolean;
+  error: Error | null;
+  isAuthenticated: boolean;
+  login: (email: string, password: string) => Promise<LoginResult>;
+  register: (email: string, password: string) => Promise<void>;
+  logout: () => Promise<void>;
+  clearError: () => void;
+}
+
+// Shallow equality — primitives by identity, objects by own property identity.
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+  const ka = Object.keys(a as object);
+  const kb = Object.keys(b as object);
+  if (ka.length !== kb.length) return false;
+  for (const k of ka) {
+    if ((a as Record<string, unknown>)[k] !== (b as Record<string, unknown>)[k]) return false;
+  }
+  return true;
+}
+
+export function useAuth(): UseAuthResult;
+export function useAuth<T>(selector: (s: UseAuthResult) => T): T;
+export function useAuth<T>(selector?: (s: UseAuthResult) => T): UseAuthResult | T {
+  const { client } = useBunBase();
+
+  // ─── Actions ─────────────────────────────────────────────────────────────────
+
+  const login = useCallback(
+    async (email: string, password: string): Promise<LoginResult> => {
+      client.auth.patchSnapshot({ error: null });
+      try {
+        return await client.auth.login({ email, password });
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        client.auth.patchSnapshot({ error: e });
+        throw e;
+      }
+    },
+    [client],
+  );
+
+  const register = useCallback(
+    async (email: string, password: string): Promise<void> => {
+      client.auth.patchSnapshot({ error: null });
+      try {
+        await client.auth.register({ email, password });
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        client.auth.patchSnapshot({ error: e });
+        throw e;
+      }
+    },
+    [client],
+  );
+
+  const logout = useCallback(async (): Promise<void> => {
+    client.auth.patchSnapshot({ error: null });
+    try {
+      await client.auth.logout();
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      client.auth.patchSnapshot({ error: e });
+      throw e;
+    }
+  }, [client]);
+
+  const clearError = useCallback(() => {
+    client.auth.patchSnapshot({ error: null });
+  }, [client]);
+
+  // ─── External store subscription ─────────────────────────────────────────────
+
+  // Stable refs — updated every render so the getSnapshot closure always sees the
+  // latest selector/actions without needing to be in the useCallback deps array.
+  const actionsRef = useRef({ login, register, logout, clearError });
+  actionsRef.current = { login, register, logout, clearError };
+
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  // Tracks the last returned value so we can return the same reference when
+  // shallowly equal — this is what causes useSyncExternalStore to bail out.
+  const prevRef = useRef<UseAuthResult | T | undefined>(undefined);
+
+  // getSnapshot is called by useSyncExternalStore on every store notification.
+  // It returns a stable reference when nothing the caller cares about changed.
+  const getSnapshot = useCallback((): UseAuthResult | T => {
+    const snap = client.auth.getSnapshot();
+    const full: UseAuthResult = {
+      ...snap,
+      isAuthenticated: snap.user !== null,
+      ...actionsRef.current,
+    };
+
+    if (!selectorRef.current) {
+      // No selector: compare full object with previous — actions are stable
+      // useCallbacks so this mainly changes when user/loading/error change.
+      if (shallowEqual(full, prevRef.current)) return prevRef.current as UseAuthResult;
+      prevRef.current = full;
+      return full;
+    }
+
+    const selected = selectorRef.current(full);
+    if (shallowEqual(selected, prevRef.current)) return prevRef.current as T;
+    prevRef.current = selected;
+    return selected;
+  }, [client]);
+
+  // ─── Session validation on mount ─────────────────────────────────────────────
+
+  // Silently validate/refresh the session. If a cached user already exists the
+  // UI shows it immediately and this just confirms it in the background.
+  useEffect(() => {
+    if (!client.auth.isAuthenticated()) return;
+    if (!client.auth.getCachedUser()) {
+      client.auth.patchSnapshot({ loading: true });
+    }
+    client.auth.me().then(
+      () => client.auth.patchSnapshot({ loading: false }),
+      () => client.auth.patchSnapshot({ user: null, loading: false }),
+    );
+  }, [client]);
+
+  // ─── Token change listener ────────────────────────────────────────────────────
+
+  // Fires on login, logout, silent refresh, and server-pushed session revocation.
+  useEffect(() => {
+    return client.auth.onAuthChange((session) => {
+      if (!session) {
+        // user: null is already handled by AuthClient's onTokenChange listener,
+        // but be explicit here too in case this fires before that listener runs.
+        client.auth.patchSnapshot({ user: null, loading: false });
+      } else {
+        // user is already in the snapshot (set by login/register/etc before this fires).
+        // Call me() anyway to get a fresh validated user object from the server.
+        if (!client.auth.getCachedUser()) {
+          client.auth.patchSnapshot({ loading: true });
+        }
+        client.auth.me().then(
+          () => client.auth.patchSnapshot({ loading: false }),
+          () => client.auth.patchSnapshot({ user: null, loading: false }),
+        );
+      }
+    });
+  }, [client]);
+
+  return useSyncExternalStore(
+    useCallback((fn) => client.auth.subscribeSnapshot(fn), [client]),
+    getSnapshot,
+  ) as UseAuthResult | T;
+}

package/src/useList.ts

@@ -0,0 +1,157 @@
+// useList — fetch and cache a collection list with SWR semantics.
+
+import type { BunBaseRecord, ListQuery, ListResult, WithExpand } from "@bunbase-ae/js";
+import { useCallback, useEffect, useReducer, useRef } from "react";
+import { useBunBase } from "./Context";
+import type { CacheEntry } from "./cache";
+
+// Stable JSON — sorts keys so query object identity doesn't matter.
+function stableKey(value: unknown): string {
+  return (
+    JSON.stringify(value, (_, v) =>
+      v !== null && typeof v === "object" && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort())
+        : (v as unknown),
+    ) ?? "{}"
+  );
+}
+
+export interface UseListResult<T, TExpand extends Record<string, unknown> = Record<string, never>> {
+  data: ListResult<WithExpand<T & BunBaseRecord, TExpand>> | undefined;
+  /** True while the very first fetch is in flight (no cached data yet). */
+  loading: boolean;
+  /** True while a background refetch is running with stale data still visible. */
+  isRefetching: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+export interface UseListOptions {
+  /** ms before cached data is considered stale. Default: 30 000. */
+  staleTime?: number;
+  /** ms between automatic background re-fetches. Default: none. */
+  refetchInterval?: number;
+  /** Set false to skip fetching entirely. Default: true. */
+  enabled?: boolean;
+  /** Subscribe to realtime collection events and auto-invalidate. Default: false. */
+  realtime?: boolean;
+}
+
+export function useList<
+  T extends Record<string, unknown> = Record<string, unknown>,
+  TExpand extends Record<string, unknown> = Record<string, never>,
+>(
+  collection: string,
+  query: ListQuery<T> = {},
+  options: UseListOptions = {},
+): UseListResult<T, TExpand> {
+  const { client, cache } = useBunBase();
+  const staleTime = options.staleTime ?? 30_000;
+  const enabled = options.enabled !== false;
+  const cacheKey = `${collection}:list:${stableKey(query)}`;
+
+  // Always points at the latest fetcher — avoids stale-closure bugs.
+  const fetcherRef = useRef<() => Promise<unknown>>(() => Promise.resolve(null));
+  // Update every render so the closure captures the latest query.
+  useEffect(() => {
+    fetcherRef.current = () => client.collection<T>(collection).list(query);
+  });
+
+  // Stable refs so the subscribe callback below doesn't need to re-register
+  // when staleTime or enabled change.
+  const staleTimeRef = useRef(staleTime);
+  const enabledRef = useRef(enabled);
+  useEffect(() => {
+    staleTimeRef.current = staleTime;
+    enabledRef.current = enabled;
+  });
+
+  const [, rerender] = useReducer((n: number) => n + 1, 0);
+
+  // Re-render whenever this cache key updates. Also triggers a background
+  // re-fetch immediately when the notification arrives and the entry is stale
+  // (e.g. after cache.invalidate() from a realtime event or mutation).
+  useEffect(
+    () =>
+      cache.subscribe(cacheKey, () => {
+        if (enabledRef.current && cache.isStale(cacheKey)) {
+          cache.fetch(cacheKey, () => fetcherRef.current(), staleTimeRef.current);
+        }
+        rerender();
+      }),
+    [cache, cacheKey],
+  );
+
+  // Fetch when the key or enabled flag changes.
+  useEffect(() => {
+    if (!enabled) return;
+    cache.fetch(cacheKey, () => fetcherRef.current(), staleTime);
+  }, [cache, cacheKey, staleTime, enabled]);
+
+  // Refetch on window focus when data is stale.
+  useEffect(() => {
+    if (!enabled) return;
+    return cache.onFocus(() => {
+      if (cache.isStale(cacheKey)) {
+        cache.fetch(cacheKey, () => fetcherRef.current(), staleTime);
+      }
+    });
+  }, [cache, cacheKey, staleTime, enabled]);
+
+  // Periodic background refetch.
+  useEffect(() => {
+    if (!options.refetchInterval || !enabled) return;
+    const id = setInterval(() => {
+      cache.invalidate(cacheKey);
+      cache.fetch(cacheKey, () => fetcherRef.current(), staleTime);
+    }, options.refetchInterval);
+    return () => clearInterval(id);
+  }, [cache, cacheKey, staleTime, options.refetchInterval, enabled]);
+
+  // Realtime: smart cache sync on any collection change.
+  //   update → write directly to get cache (instant) + invalidate list
+  //   delete → remove get cache entry + invalidate list
+  //   create → invalidate list only (can't safely insert into sorted/filtered list)
+  useEffect(() => {
+    if (!options.realtime || !enabled) return;
+    return client.realtime.subscribe(`collection:${collection}`, (event) => {
+      const id = event.record.id;
+      if (event.event === "update") {
+        cache.setData(`${collection}:get:${id}`, event.record);
+        cache.invalidate(`${collection}:list`);
+      } else if (event.event === "delete") {
+        cache.invalidate(`${collection}:get:${id}`);
+        cache.invalidate(`${collection}:list`);
+      } else {
+        cache.invalidate(`${collection}:list`);
+      }
+    });
+  }, [client, collection, cache, options.realtime, enabled]);
+
+  const entry = cache.get(cacheKey);
+
+  // Populate individual record caches from list results so that navigating
+  // to a detail page loads instantly without a round-trip.
+  // Uses setDataIfMissing so fresher data (realtime events, direct fetches) is never overwritten.
+  const lastEntryRef = useRef<CacheEntry | undefined>(undefined);
+  useEffect(() => {
+    if (entry === lastEntryRef.current) return;
+    lastEntryRef.current = entry;
+    if (entry?.status !== "success" || !entry.data) return;
+    const result = entry.data as ListResult<WithExpand<T & BunBaseRecord, TExpand>>;
+    for (const item of result.items) {
+      cache.setDataIfMissing(`${collection}:get:${item.id}`, item, staleTime);
+    }
+  }, [entry, cache, collection, staleTime]);
+
+  return {
+    data: entry?.data as ListResult<WithExpand<T & BunBaseRecord, TExpand>> | undefined,
+    loading: !entry || entry.status === "loading",
+    isRefetching: !!(entry?.data !== undefined && entry.promise),
+    error: entry?.error ?? null,
+    refetch: useCallback(() => {
+      cache.invalidate(cacheKey);
+      cache.fetch(cacheKey, () => fetcherRef.current(), staleTime);
+    }, [cache, cacheKey, staleTime]),
+  };
+}

package/src/useMutation.ts

@@ -0,0 +1,141 @@
+// Mutation hooks — create, update, delete with automatic cache invalidation.
+
+import type { BunBaseRecord } from "@bunbase-ae/js";
+import { useCallback, useState } from "react";
+import { useBunBase } from "./Context";
+
+export interface MutationResult<TData, TArgs extends unknown[]> {
+  mutate: (...args: TArgs) => Promise<TData>;
+  loading: boolean;
+  error: Error | null;
+  data: TData | undefined;
+  reset: () => void;
+}
+
+function useError() {
+  const [error, setError] = useState<Error | null>(null);
+  // stable ref — setError from useState is always stable, so no deps needed.
+  const capture = useCallback((err: unknown): Error => {
+    const e = err instanceof Error ? err : new Error(String(err));
+    setError(e);
+    return e;
+  }, []);
+  return { error, setError, capture };
+}
+
+// ─── useCreate ───────────────────────────────────────────────────────────────
+
+export function useCreate<T extends Record<string, unknown> = Record<string, unknown>>(
+  collection: string,
+): MutationResult<T & BunBaseRecord, [Partial<T>]> {
+  const { client, cache } = useBunBase();
+  const [loading, setLoading] = useState(false);
+  const [data, setData] = useState<(T & BunBaseRecord) | undefined>(undefined);
+  const { error, setError, capture } = useError();
+
+  const mutate = useCallback(
+    async (payload: Partial<T>): Promise<T & BunBaseRecord> => {
+      setLoading(true);
+      setError(null);
+      try {
+        const record = await client.collection<T>(collection).create(payload);
+        setData(record);
+        // Invalidate all list queries for this collection so they re-fetch.
+        cache.invalidate(`${collection}:list`);
+        return record;
+      } catch (err) {
+        throw capture(err);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client, collection, cache, setError, capture],
+  );
+
+  return {
+    mutate,
+    loading,
+    error,
+    data,
+    reset: useCallback(() => {
+      setData(undefined);
+      setError(null);
+    }, [setError]),
+  };
+}
+
+// ─── useUpdate ───────────────────────────────────────────────────────────────
+
+export function useUpdate<T extends Record<string, unknown> = Record<string, unknown>>(
+  collection: string,
+): MutationResult<T & BunBaseRecord, [string, Partial<T>]> {
+  const { client, cache } = useBunBase();
+  const [loading, setLoading] = useState(false);
+  const [data, setData] = useState<(T & BunBaseRecord) | undefined>(undefined);
+  const { error, setError, capture } = useError();
+
+  const mutate = useCallback(
+    async (id: string, patch: Partial<T>): Promise<T & BunBaseRecord> => {
+      setLoading(true);
+      setError(null);
+      try {
+        const record = await client.collection<T>(collection).update(id, patch);
+        setData(record);
+        // Write the updated record into the single-record cache immediately.
+        cache.setData(`${collection}:get:${id}`, record);
+        // Invalidate list queries so any ordering/filter changes are reflected.
+        cache.invalidate(`${collection}:list`);
+        return record;
+      } catch (err) {
+        throw capture(err);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client, collection, cache, setError, capture],
+  );
+
+  return {
+    mutate,
+    loading,
+    error,
+    data,
+    reset: useCallback(() => {
+      setData(undefined);
+      setError(null);
+    }, [setError]),
+  };
+}
+
+// ─── useDelete ───────────────────────────────────────────────────────────────
+
+export function useDelete(collection: string): MutationResult<void, [string]> {
+  const { client, cache } = useBunBase();
+  const [loading, setLoading] = useState(false);
+  const { error, setError, capture } = useError();
+
+  const mutate = useCallback(
+    async (id: string): Promise<void> => {
+      setLoading(true);
+      setError(null);
+      try {
+        await client.collection(collection).delete(id);
+        // Wipe all cached data for this collection (list + single-record).
+        cache.invalidate(`${collection}:`);
+      } catch (err) {
+        throw capture(err);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client, collection, cache, setError, capture],
+  );
+
+  return {
+    mutate,
+    loading,
+    error,
+    data: undefined,
+    reset: useCallback(() => setError(null), [setError]),
+  };
+}

package/src/useRealtime.ts

@@ -0,0 +1,126 @@
+// useRealtime — subscribe to collection or record changes.
+//
+// All hooks auto-reconnect (handled by RealtimeClient) and unsubscribe on unmount.
+
+import type { RealtimeEvent, SubscribeOptions } from "@bunbase-ae/js";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useBunBase } from "./Context";
+
+// ─── useRealtime ─────────────────────────────────────────────────────────────
+
+export interface UseRealtimeOptions extends SubscribeOptions {
+  /**
+   * When true, invalidate all cache entries for the event's collection on every
+   * incoming change. Pairs well with useList / useRecord for live-updating UIs.
+   */
+  invalidateCache?: boolean;
+}
+
+export interface UseRealtimeResult {
+  /** True once the WebSocket connection is open. */
+  connected: boolean;
+}
+
+export function useRealtime<T extends Record<string, unknown> = Record<string, unknown>>(
+  channel: string,
+  callback?: (event: RealtimeEvent<T>) => void,
+  options: UseRealtimeOptions = {},
+): UseRealtimeResult {
+  const { client, cache } = useBunBase();
+  const [connected, setConnected] = useState(false);
+
+  // Always call the latest callback without re-subscribing.
+  const cbRef = useRef(callback);
+  cbRef.current = callback;
+
+  // Stable ref for subscribe options so effect doesn't re-run on object identity changes.
+  const optsRef = useRef(options);
+  optsRef.current = options;
+
+  useEffect(() => {
+    if (!channel) return;
+
+    const { events, filter, ids } = optsRef.current;
+
+    const unsub = client.realtime.subscribe<T>(
+      channel,
+      (event) => {
+        cbRef.current?.(event);
+        if (optsRef.current.invalidateCache) {
+          const col = event.collection;
+          const id = event.record.id;
+          if (event.event === "update") {
+            // Write updated record directly to get cache — instant UI, no round-trip.
+            cache.setData(`${col}:get:${id}`, event.record);
+            // Invalidate list cache so any ordering/filter changes are reflected.
+            cache.invalidate(`${col}:list`);
+          } else if (event.event === "delete") {
+            cache.invalidate(`${col}:get:${id}`);
+            cache.invalidate(`${col}:list`);
+          } else {
+            // create — can't safely insert into sorted/filtered lists.
+            cache.invalidate(`${col}:list`);
+          }
+        }
+      },
+      { events, filter, ids },
+    );
+
+    const unconnect = client.realtime.onConnect(() => setConnected(true));
+
+    return () => {
+      unsub();
+      unconnect();
+    };
+  }, [client, channel, cache]);
+
+  return { connected };
+}
+
+// ─── useCollectionEvents ─────────────────────────────────────────────────────
+
+/** Subscribe to all changes in a collection. */
+export function useCollectionEvents<T extends Record<string, unknown> = Record<string, unknown>>(
+  collection: string,
+  callback?: (event: RealtimeEvent<T>) => void,
+  options: UseRealtimeOptions = {},
+): UseRealtimeResult {
+  return useRealtime<T>(`collection:${collection}`, callback, options);
+}
+
+// ─── useRecordEvents ─────────────────────────────────────────────────────────
+
+/** Subscribe to changes on a specific record. Pass null/undefined to skip. */
+export function useRecordEvents<T extends Record<string, unknown> = Record<string, unknown>>(
+  collection: string,
+  id: string | null | undefined,
+  callback?: (event: RealtimeEvent<T>) => void,
+): UseRealtimeResult {
+  return useRealtime<T>(id ? `record:${collection}:${id}` : "", callback);
+}
+
+// ─── usePresence ─────────────────────────────────────────────────────────────
+
+export interface UsePresenceResult {
+  users: string[];
+  refresh: () => void;
+}
+
+/** Query which users are present on a channel. Refreshes on mount. */
+export function usePresence(channel: string): UsePresenceResult {
+  const { client } = useBunBase();
+  const [users, setUsers] = useState<string[]>([]);
+
+  const refresh = useCallback(() => {
+    client.realtime
+      .presence(channel)
+      .then(setUsers)
+      .catch(() => {});
+  }, [client, channel]);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  return { users, refresh };
+}

package/src/useRecord.ts

@@ -0,0 +1,95 @@
+// useRecord — fetch and cache a single collection record.
+
+import type { BunBaseRecord, GetQuery, WithExpand } from "@bunbase-ae/js";
+import { useCallback, useEffect, useReducer, useRef } from "react";
+import { useBunBase } from "./Context";
+
+export interface UseRecordResult<
+  T,
+  TExpand extends Record<string, unknown> = Record<string, never>,
+> {
+  data: WithExpand<T & BunBaseRecord, TExpand> | undefined;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+export interface UseRecordOptions extends GetQuery {
+  staleTime?: number;
+}
+
+export function useRecord<
+  T extends Record<string, unknown> = Record<string, unknown>,
+  TExpand extends Record<string, unknown> = Record<string, never>,
+>(
+  collection: string,
+  /** Pass null or undefined to skip fetching (e.g. while id is loading). */
+  id: string | null | undefined,
+  options: UseRecordOptions = {},
+): UseRecordResult<T, TExpand> {
+  const { client, cache } = useBunBase();
+  const staleTime = options.staleTime ?? 30_000;
+  // Null id = no fetch.
+  const cacheKey = id ? `${collection}:get:${id}` : null;
+
+  const fetcherRef = useRef<() => Promise<unknown>>(null as unknown as () => Promise<unknown>);
+  if (id) {
+    fetcherRef.current = () => client.collection<T>(collection).get(id, { expand: options.expand });
+  }
+
+  const staleTimeRef = useRef(staleTime);
+  useEffect(() => {
+    staleTimeRef.current = staleTime;
+  });
+
+  const [, rerender] = useReducer((n: number) => n + 1, 0);
+
+  useEffect(() => {
+    if (!cacheKey) return;
+    return cache.subscribe(cacheKey, () => {
+      if (cacheKey && cache.isStale(cacheKey)) {
+        cache.fetch(cacheKey, () => fetcherRef.current(), staleTimeRef.current);
+      }
+      rerender();
+    });
+  }, [cache, cacheKey]);
+
+  useEffect(() => {
+    if (!cacheKey) return;
+    cache.fetch(cacheKey, () => fetcherRef.current(), staleTime);
+  }, [cache, cacheKey, staleTime]);
+
+  useEffect(() => {
+    if (!cacheKey) return;
+    return cache.onFocus(() => {
+      if (cacheKey && cache.isStale(cacheKey)) {
+        cache.fetch(cacheKey, () => fetcherRef.current(), staleTime);
+      }
+    });
+  }, [cache, cacheKey, staleTime]);
+
+  // Realtime: update single-record cache when the record changes.
+  useEffect(() => {
+    if (!id || !cacheKey) return;
+    return client.realtime.subscribe(`record:${collection}:${id}`, (event) => {
+      if (event.event === "delete") {
+        cache.invalidate(cacheKey);
+      } else {
+        cache.setData(cacheKey, event.record);
+      }
+    });
+  }, [client, collection, id, cache, cacheKey]);
+
+  const entry = cacheKey ? cache.get(cacheKey) : undefined;
+
+  return {
+    data: entry?.data as WithExpand<T & BunBaseRecord, TExpand> | undefined,
+    loading: !!cacheKey && (!entry || entry.status === "loading"),
+    error: entry?.error ?? null,
+    refetch: useCallback(() => {
+      if (!cacheKey) return;
+      cache.invalidate(cacheKey);
+      cache.fetch(cacheKey, () => fetcherRef.current(), staleTime);
+    }, [cache, cacheKey, staleTime]),
+  };
+}

package/src/useUpload.ts

@@ -0,0 +1,65 @@
+// useUpload — file upload with progress tracking.
+
+import type { FileRecord } from "@bunbase-ae/js";
+import { useCallback, useState } from "react";
+import { useBunBase } from "./Context";
+import type { UploadOptions } from "./types";
+
+export interface UseUploadResult {
+  upload: (file: File | Blob, options?: Omit<UploadOptions, "onProgress">) => Promise<FileRecord>;
+  /** True while upload is in progress. */
+  loading: boolean;
+  /** Upload progress from 0 to 1. Resets to 0 on each new upload. */
+  progress: number;
+  error: Error | null;
+  /** The uploaded FileRecord. Set after a successful upload. */
+  data: FileRecord | undefined;
+  reset: () => void;
+}
+
+export function useUpload(): UseUploadResult {
+  const { client } = useBunBase();
+  const [loading, setLoading] = useState(false);
+  const [progress, setProgress] = useState(0);
+  const [error, setError] = useState<Error | null>(null);
+  const [data, setData] = useState<FileRecord | undefined>(undefined);
+
+  const upload = useCallback(
+    async (
+      file: File | Blob,
+      options: Omit<UploadOptions, "onProgress"> = {},
+    ): Promise<FileRecord> => {
+      setLoading(true);
+      setProgress(0);
+      setError(null);
+      try {
+        const record = await client.storage.upload(file, {
+          ...options,
+          onProgress: (p) => setProgress(p),
+        });
+        setData(record);
+        return record;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client],
+  );
+
+  return {
+    upload,
+    loading,
+    progress,
+    error,
+    data,
+    reset: useCallback(() => {
+      setError(null);
+      setData(undefined);
+      setProgress(0);
+    }, []),
+  };
+}