@pylonsync/react 0.2.4

package/src/typed.ts

@@ -0,0 +1,149 @@
+/**
+ * Typed database client — narrow pylon's untyped `db` object using your
+ * generated `AppSchema` (from `pylon codegen client`).
+ *
+ * @example
+ * ```ts
+ * // src/pylon.client.ts (generated by `pylon codegen client`)
+ * export interface AppSchema {
+ *   entities: { Todo: Todo; User: User };
+ *   functions: {
+ *     placeBid: { input: { lotId: string; amount: number }; output: { accepted: boolean } };
+ *   };
+ *   queries: {};
+ * }
+ *
+ * // src/db.ts
+ * import { createTypedDb } from "@pylonsync/react";
+ * import type { AppSchema } from "./pylon.client";
+ * export const db = createTypedDb<AppSchema>();
+ *
+ * // Components get full type safety:
+ * const { data } = db.useQuery("Todo");         // data: Todo[]
+ * const { data: user } = db.useQueryOne("User", "u_1"); // user: User | null
+ * const bid = db.useMutation("placeBid");        // typed args + result
+ * await bid.mutate({ lotId: "x", amount: 150 }); // TS checks input type
+ * ```
+ */
+
+import type { Row } from "@pylonsync/sync";
+import { db as untypedDb } from "./db";
+import type {
+  QueryOptions,
+  UseQueryReturn,
+  UseQueryOneReturn,
+  UseMutationReturn,
+  UseInfiniteQueryReturn,
+} from "./hooks";
+
+// ---------------------------------------------------------------------------
+// Schema shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of the generated `AppSchema` interface.
+ *
+ * The CLI's `client_codegen` emits a type matching this shape. Consumers
+ * never construct `AppSchema` manually.
+ */
+export interface AgentDBSchema {
+  entities: Record<string, unknown>;
+  functions: Record<string, { input: unknown; output: unknown }>;
+  queries: Record<string, { input: unknown; output: unknown }>;
+}
+
+// ---------------------------------------------------------------------------
+// TypedDb — mirrors `db` but with generics keyed on the schema
+// ---------------------------------------------------------------------------
+
+export interface TypedDb<S extends AgentDBSchema> {
+  /** Live query with type inferred from the schema. */
+  useQuery<K extends keyof S["entities"]>(
+    entity: K,
+    options?: QueryOptions
+  ): UseQueryReturn<S["entities"][K]>;
+
+  /** Live single-row query. */
+  useQueryOne<K extends keyof S["entities"]>(
+    entity: K,
+    id: string
+  ): UseQueryOneReturn<S["entities"][K]>;
+
+  /** Server-side function call with typed input/output. */
+  useMutation<K extends keyof S["functions"]>(
+    fnName: K
+  ): UseMutationReturn<S["functions"][K]["input"], S["functions"][K]["output"]>;
+
+  /** Paginated live query. */
+  useInfiniteQuery<K extends keyof S["entities"]>(
+    entity: K,
+    options?: { pageSize?: number }
+  ): UseInfiniteQueryReturn<S["entities"][K]>;
+
+  /** Call a server-side function directly (outside React). */
+  fn<K extends keyof S["functions"]>(
+    name: K,
+    args: S["functions"][K]["input"]
+  ): Promise<S["functions"][K]["output"]>;
+
+  /** Insert a row (optimistic). */
+  insert<K extends keyof S["entities"]>(
+    entity: K,
+    data: Partial<S["entities"][K]>
+  ): unknown;
+
+  /** Update a row (optimistic). */
+  update<K extends keyof S["entities"]>(
+    entity: K,
+    id: string,
+    data: Partial<S["entities"][K]>
+  ): unknown;
+
+  /** Delete a row (optimistic). */
+  delete<K extends keyof S["entities"]>(entity: K, id: string): unknown;
+
+  /** Underlying untyped db (escape hatch). */
+  readonly untyped: typeof untypedDb;
+}
+
+/**
+ * Create a typed client from a generated `AppSchema`.
+ *
+ * At runtime this is literally the same object as `db`; types are narrowed
+ * at compile time via generics.
+ */
+export function createTypedDb<S extends AgentDBSchema>(): TypedDb<S> {
+  const d = untypedDb as unknown as {
+    useQuery: <T>(entity: string, options?: QueryOptions) => UseQueryReturn<T>;
+    useQueryOne: <T>(entity: string, id: string) => UseQueryOneReturn<T>;
+    useMutation: <A, R>(fn: string) => UseMutationReturn<A, R>;
+    useInfiniteQuery: <T>(
+      entity: string,
+      options?: { pageSize?: number }
+    ) => UseInfiniteQueryReturn<T>;
+    fn: <R>(name: string, args?: Record<string, unknown>) => Promise<R>;
+    insert: (entity: string, data: Row) => unknown;
+    update: (entity: string, id: string, data: Partial<Row>) => unknown;
+    delete: (entity: string, id: string) => unknown;
+  };
+
+  return {
+    useQuery: ((entity, options) =>
+      d.useQuery(entity as string, options)) as TypedDb<S>["useQuery"],
+    useQueryOne: ((entity, id) =>
+      d.useQueryOne(entity as string, id)) as TypedDb<S>["useQueryOne"],
+    useMutation: ((fnName) =>
+      d.useMutation(fnName as string)) as TypedDb<S>["useMutation"],
+    useInfiniteQuery: ((entity, options) =>
+      d.useInfiniteQuery(entity as string, options)) as TypedDb<S>["useInfiniteQuery"],
+    fn: ((name, args) =>
+      d.fn(name as string, args as Record<string, unknown>)) as TypedDb<S>["fn"],
+    insert: ((entity, data) =>
+      d.insert(entity as string, data as Row)) as TypedDb<S>["insert"],
+    update: ((entity, id, data) =>
+      d.update(entity as string, id, data as Partial<Row>)) as TypedDb<S>["update"],
+    delete: ((entity, id) =>
+      d.delete(entity as string, id)) as TypedDb<S>["delete"],
+    untyped: untypedDb,
+  };
+}

package/src/useRoom.ts

@@ -0,0 +1,231 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { getBaseUrl, getReactStorage, storageKey } from './index';
+
+// ---------------------------------------------------------------------------
+// Room types
+// ---------------------------------------------------------------------------
+
+export interface RoomPeer {
+  user_id: string;
+  data: any;
+  joined_at: string;
+}
+
+export interface RoomSnapshot {
+  room: string;
+  peers: RoomPeer[];
+}
+
+export interface UseRoomOptions {
+  /** Base URL of the pylon server. */
+  baseUrl?: string;
+  /** Auth token for API requests. */
+  token?: string;
+  /** Initial presence data sent on join. */
+  initialPresence?: Record<string, any>;
+  /** How often to poll for peer updates (ms). Defaults to 5 000. */
+  heartbeatInterval?: number;
+}
+
+export interface UseRoomReturn {
+  /** Current peers in the room (excluding self). */
+  peers: RoomPeer[];
+  /** Whether currently connected to the room. */
+  isConnected: boolean;
+  /** Update your presence data (e.g. cursor position, typing status). */
+  setPresence: (data: Record<string, any>) => void;
+  /** Broadcast a message to the room on a given topic. */
+  broadcast: (topic: string, data: any) => void;
+  /** Leave the room manually. */
+  leave: () => void;
+  /** Error message, if any. */
+  error: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to a real-time room. Joins on mount, leaves on unmount, and
+ * polls for peer updates on a configurable interval.
+ *
+ * ```tsx
+ * const { peers, isConnected, setPresence, broadcast, leave, error } = useRoom(
+ *   "project-42",
+ *   currentUser.id,
+ *   { baseUrl: "http://localhost:4321", token }
+ * );
+ * ```
+ */
+/**
+ * Read the current pylon token from the configured storage adapter
+ * (default: localStorage on web, AsyncStorage on RN, etc). Keeps the
+ * hook working even when the caller doesn't explicitly thread a token
+ * — otherwise every useRoom request hits the server as anonymous and
+ * 401s under any authenticated room policy.
+ */
+function readStoredToken(): string | undefined {
+  return getReactStorage().get(storageKey('token')) ?? undefined;
+}
+
+export function useRoom(
+  roomId: string,
+  userId: string,
+  options: UseRoomOptions = {},
+): UseRoomReturn {
+  const {
+    // Fall back to the globally configured baseUrl so room requests don't
+    // land on the Vite dev origin (localhost:5173) and 404 when the caller
+    // forgets to pass one.
+    baseUrl = getBaseUrl(),
+    token: explicitToken,
+    initialPresence = {},
+    heartbeatInterval = 5_000,
+  } = options;
+  // Resolve at render time rather than hook-creation time so the room
+  // reconnects with a fresh token after login.
+  const token = explicitToken ?? readStoredToken();
+
+  const [peers, setPeers] = useState<RoomPeer[]>([]);
+  const [isConnected, setIsConnected] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const presenceRef = useRef(initialPresence);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  // Stable header builder -- only changes when `token` changes.
+  const headers = useCallback((): Record<string, string> => {
+    const h: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (token) h['Authorization'] = `Bearer ${token}`;
+    return h;
+  }, [token]);
+
+  // ------- lifecycle: join / heartbeat / leave -------
+  //
+  // React StrictMode double-mounts every effect in dev: mount → unmount →
+  // re-mount. The `joined` ref tracks whether the join() call actually
+  // landed before the cleanup ran. If join hadn't completed yet, the
+  // cleanup skips leave entirely — there's nothing to leave on the
+  // server's side. If join did land, leave fires normally. Server-side
+  // leave is also idempotent now (200 with was_present:false on
+  // duplicate), so even a race on this can't error in the network tab.
+  useEffect(() => {
+    let mounted = true;
+    let joined = false;
+
+    const join = async () => {
+      try {
+        const res = await fetch(`${baseUrl}/api/rooms/join`, {
+          method: 'POST',
+          headers: headers(),
+          body: JSON.stringify({
+            room: roomId,
+            user_id: userId,
+            data: presenceRef.current,
+          }),
+        });
+        const body = await res.json();
+        if (!mounted) return;
+
+        if (res.ok) {
+          joined = true;
+          setIsConnected(true);
+          setError(null);
+          if (body.snapshot?.peers) {
+            setPeers(
+              (body.snapshot.peers as RoomPeer[]).filter(
+                (p) => p.user_id !== userId,
+              ),
+            );
+          }
+        } else {
+          setError(body.error?.message || 'Failed to join room');
+        }
+      } catch (e: any) {
+        if (mounted) setError(e.message);
+      }
+    };
+
+    join();
+
+    // Poll for peer list updates.
+    intervalRef.current = setInterval(async () => {
+      if (!mounted) return;
+      try {
+        const res = await fetch(
+          `${baseUrl}/api/rooms/${encodeURIComponent(roomId)}`,
+          { headers: headers() },
+        );
+        if (res.ok) {
+          const body = await res.json();
+          if (mounted) {
+            setPeers(
+              ((body.members ?? []) as RoomPeer[]).filter(
+                (p) => p.user_id !== userId,
+              ),
+            );
+          }
+        }
+      } catch {
+        // Swallow -- next heartbeat will retry.
+      }
+    }, heartbeatInterval);
+
+    return () => {
+      mounted = false;
+      if (intervalRef.current) clearInterval(intervalRef.current);
+
+      // Skip the leave call when join never completed — fixes the
+      // StrictMode double-mount race that produced spurious "user
+      // not in this room" errors. Server leave is also idempotent so
+      // a stray duplicate would 200 anyway, but we save the round trip.
+      if (joined) {
+        fetch(`${baseUrl}/api/rooms/leave`, {
+          method: 'POST',
+          headers: headers(),
+          body: JSON.stringify({ room: roomId, user_id: userId }),
+        }).catch(() => {});
+      }
+    };
+    // Re-run the entire lifecycle when identity or connection details change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [roomId, userId, baseUrl, token, heartbeatInterval]);
+
+  // ------- actions -------
+
+  const setPresence = useCallback(
+    (data: Record<string, any>) => {
+      presenceRef.current = data;
+      fetch(`${baseUrl}/api/rooms/presence`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ room: roomId, user_id: userId, data }),
+      }).catch(() => {});
+    },
+    [roomId, userId, baseUrl, headers],
+  );
+
+  const broadcast = useCallback(
+    (topic: string, data: any) => {
+      fetch(`${baseUrl}/api/rooms/broadcast`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify({ room: roomId, user_id: userId, topic, data }),
+      }).catch(() => {});
+    },
+    [roomId, userId, baseUrl, headers],
+  );
+
+  const leave = useCallback(() => {
+    fetch(`${baseUrl}/api/rooms/leave`, {
+      method: 'POST',
+      headers: headers(),
+      body: JSON.stringify({ room: roomId, user_id: userId }),
+    }).catch(() => {});
+    setIsConnected(false);
+    setPeers([]);
+  }, [roomId, userId, baseUrl, headers]);
+
+  return { peers, isConnected, setPresence, broadcast, leave, error };
+}

package/src/useSession.ts

@@ -0,0 +1,71 @@
+import { SyncEngine, type ResolvedSession } from "@pylonsync/sync";
+import { useEffect, useSyncExternalStore } from "react";
+
+export type { ResolvedSession };
+
+export interface UseSessionReturn {
+  /** Server-resolved session. `userId=null` means anonymous. */
+  session: ResolvedSession;
+  /** Convenience accessors. */
+  userId: string | null;
+  tenantId: string | null;
+  isAdmin: boolean;
+  isAuthenticated: boolean;
+  /**
+   * Force a refresh of the cached session. Call after sign-in, sign-out,
+   * or `/api/auth/select-org` so the UI and sync engine pick up the
+   * change before the next pull/reconnect.
+   */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Subscribe to the server-resolved session held by the sync engine.
+ *
+ * The engine fetches `/api/auth/me` on start and on token flips, caches
+ * the result, and notifies the store on change — so this hook is
+ * purely a reader. Mutations (login/logout/select-org) are still the
+ * caller's responsibility; after them, invoke `refresh()` (or
+ * `engine.notifySessionChanged()`) to pull the new session immediately.
+ */
+export function useSession(sync: SyncEngine): UseSessionReturn {
+  const session = useSyncExternalStore(
+    (cb) => sync.store.subscribe(cb),
+    () => sync.resolvedSession(),
+    () => sync.resolvedSession(),
+  );
+
+  // Watch the localStorage token key. If another tab signs in/out, or the
+  // app writes a new token without going through `notifySessionChanged`,
+  // our cached session still matches the old identity until the next
+  // pull. A `storage` event covers the cross-tab case; a mount-time
+  // refresh covers the same-tab write-then-mount race.
+  useEffect(() => {
+    void sync.notifySessionChanged();
+    const onStorage = (e: StorageEvent) => {
+      // Only refresh when the key that actually changed looks like a
+      // pylon token. Skip unrelated keys so we don't generate an
+      // /api/auth/me flood from noisy apps.
+      if (!e.key) return;
+      if (e.key.startsWith("pylon_") || e.key.startsWith("pylon:")) {
+        if (e.key.endsWith("token") || e.key.endsWith(":token")) {
+          void sync.notifySessionChanged();
+        }
+      }
+    };
+    if (typeof window !== "undefined") {
+      window.addEventListener("storage", onStorage);
+      return () => window.removeEventListener("storage", onStorage);
+    }
+    return undefined;
+  }, [sync]);
+
+  return {
+    session,
+    userId: session.userId,
+    tenantId: session.tenantId,
+    isAdmin: session.isAdmin,
+    isAuthenticated: session.userId != null,
+    refresh: () => sync.notifySessionChanged(),
+  };
+}