@archlast/client 0.1.1 → 0.1.3

package/README.md

@@ -1,960 +1,174 @@
-# @archlast/client
-
-The Archlast client SDK provides a complete solution for building reactive frontend applications with Archlast backends. It includes WebSocket-based real-time queries, React hooks with automatic cache management, authentication helpers, file storage utilities, admin APIs, and optional tRPC integration.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Client Configuration](#client-configuration)
-- [React Hooks](#react-hooks)
-  - [useQuery](#usequery)
-  - [useMutation](#usemutation)
-  - [usePagination](#usepagination)
-  - [useUpload](#useupload)
-  - [useAuth](#useauth)
-- [Direct Client Usage](#direct-client-usage)
-- [Authentication](#authentication)
-- [File Storage](#file-storage)
-- [Admin APIs](#admin-apis)
-- [tRPC Integration](#trpc-integration)
-- [Subpath Exports](#subpath-exports)
-- [TypeScript Support](#typescript-support)
-- [Error Handling](#error-handling)
-- [Advanced Patterns](#advanced-patterns)
-
-## Installation
-
-```bash
-npm install @archlast/client
-
-# Or with other package managers
-pnpm add @archlast/client
-yarn add @archlast/client
-bun add @archlast/client
-```
-
-### Peer Dependencies
-
-Install required peer dependencies in your application:
-
-```bash
-npm install react react-dom @tanstack/react-query
-```
-
-### Optional Dependencies
-
-For tRPC support:
-
-```bash
-npm install @trpc/client @trpc/react-query
-```
-
-## Quick Start
-
-### 1. Create the Client
-
-```ts
-import { ArchlastClient } from "@archlast/client";
-
-const client = new ArchlastClient(
-  "ws://localhost:4000/ws",  // WebSocket URL
-  "http://localhost:4000",   // HTTP URL
-  "web",                      // App ID
-  undefined,                  // Optional: auth URL (for same-origin proxy)
-  {
-    autoConnect: true,        // Auto-connect WebSocket (default: true)
-    isAdmin: false,           // Admin mode (default: false)
-    apiKey: "arch_key",       // Optional: Better-Auth API key
-    betterAuthCookies: {},    // Optional: Better-Auth session cookies
-  }
-);
-```
-
-### 2. Set Up the Provider
-
-```tsx
-import { ArchlastProvider } from "@archlast/client/react";
-
-function App() {
-  return (
-    <ArchlastProvider client={client}>
-      <YourApp />
-    </ArchlastProvider>
-  );
-}
-```
-
-### 3. Use Hooks in Components
-
-```tsx
-import { useQuery, useMutation } from "@archlast/client/react";
-import { api } from "./_generated/api";
-
-function TodoList() {
-  // Subscribe to live updates
-  const tasks = useQuery(api.tasks.list, {});
-
-  // Mutation with automatic cache invalidation
-  const createTask = useMutation(api.tasks.create);
-
-  const handleAdd = async () => {
-    await createTask({ text: "New task" });
-    // Cache automatically invalidated, UI updates reactively
-  };
-
-  if (!tasks) return <div>Loading...</div>;
-
-  return (
-    <div>
-      <ul>
-        {tasks.map(task => (
-          <li key={task._id}>{task.text}</li>
-        ))}
-      </ul>
-      <button onClick={handleAdd}>Add Task</button>
-    </div>
-  );
-}
-```
-
-> **Note:** The `api` object is auto-generated by the CLI in `_generated/api.ts`. Run `archlast dev` or `archlast build` to generate it.
-
----
-
-## Client Configuration
-
-### Constructor Signature
-
-```ts
-new ArchlastClient(wsUrl, httpUrl, appId, authUrl?, options?)
-```
-
-### Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `wsUrl` | `string` | WebSocket endpoint (e.g., `ws://localhost:4000/ws`) |
-| `httpUrl` | `string` | HTTP base URL (e.g., `http://localhost:4000`) |
-| `appId` | `string` | Application identifier (e.g., `"web"`, `"mobile"`) |
-| `authUrl` | `string?` | Optional custom auth URL (defaults to `httpUrl`) |
-| `options` | `object?` | Additional configuration options |
-
-### Options
-
-```ts
-interface ClientOptions {
-  // Auto-connect WebSocket on instantiation (default: true)
-  autoConnect?: boolean;
-
-  // API key for authentication (arch_ prefix)
-  apiKey?: string;
-
-  // Enable admin WebSocket subscriptions
-  isAdmin?: boolean;
-
-  // Better Auth session cookies for SSR
-  betterAuthCookies?: Record<string, string>;
-}
-```
-
-### Full Example
-
-```ts
-const client = new ArchlastClient(
-  "wss://api.myapp.com/ws",
-  "https://api.myapp.com",
-  "web",
-  "https://auth.myapp.com",  // Custom auth URL
-  {
-    autoConnect: true,
-    apiKey: "arch_your_api_key",
-    isAdmin: false,
-    betterAuthCookies: {
-      "better-auth.session": "session_token_here"
-    }
-  }
-);
-```
-
-### Runtime Credential Updates
-
-```ts
-// Rotate API key
-client.setApiKey("arch_new_api_key");
-
-// Update session cookies (for SSR)
-client.setBetterAuthCookies({
-  "better-auth.session": "new_session_token"
-});
-```
-
----
-
-## React Hooks
-
-### useQuery
-
-Subscribe to real-time query updates with automatic caching via TanStack Query.
-
-```ts
-import { useQuery } from "@archlast/client/react";
-import { api } from "./_generated/api";
-
-function TaskList() {
-  // Basic usage
-  const tasks = useQuery(api.tasks.list, {});
-
-  // With arguments
-  const task = useQuery(api.tasks.get, { id: "123" });
-
-  // With options
-  const { data, isLoading, error, refetch } = useQuery(
-    api.tasks.list,
-    { completed: false },
-    {
-      // TanStack Query options
-      staleTime: 5000,
-      refetchOnWindowFocus: true,
-    }
-  );
-
-  if (isLoading) return <Spinner />;
-  if (error) return <Error message={error.message} />;
-
-  return <TaskGrid tasks={data} />;
-}
-```
-
-### useMutation
-
-Execute mutations with automatic cache invalidation.
-
-```ts
-import { useMutation } from "@archlast/client/react";
-
-function CreateTaskForm() {
-  const createTask = useMutation(api.tasks.create);
-
-  const handleSubmit = async (e: FormEvent) => {
-    e.preventDefault();
-    const formData = new FormData(e.target as HTMLFormElement);
-
-    try {
-      const task = await createTask({
-        text: formData.get("text") as string,
-        priority: "medium"
-      });
-      console.log("Created:", task._id);
-    } catch (error) {
-      console.error("Failed:", error);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <input name="text" required />
-      <button type="submit">Create</button>
-    </form>
-  );
-}
-```
-
-### usePagination
-
-Handle cursor-based pagination with infinite scroll support.
-
-```ts
-import { usePagination } from "@archlast/client/react";
-
-function InfiniteTaskList() {
-  const {
-    items,           // Accumulated items across all pages
-    cursor,          // Current cursor for next page
-    isDone,          // Whether pagination is complete
-    hasMore,         // Convenience flag: !isDone && cursor exists
-    isLoading,       // Loading state
-    loadMore,        // Function to load next page
-    refresh,         // Function to reset and reload from first page
-    page,            // Optional: current page number (if server provides)
-    pageSize,        // Optional: page size (if server provides)
-    total,           // Optional: total count (if server provides)
-  } = usePagination(
-    api.tasks.listPaginated,
-    { completed: false }, // Base args (no cursor/limit)
-    { limit: 20 }         // Options
-  );
-
-  return (
-    <div>
-      <ul>
-        {items.map(task => (
-          <li key={task._id}>{task.text}</li>
-        ))}
-      </ul>
-
-      {hasMore && (
-        <button
-          onClick={loadMore}
-          disabled={isLoading}
-        >
-          {isLoading ? "Loading..." : "Load More"}
-        </button>
-      )}
-
-      <button onClick={refresh}>Refresh</button>
-    </div>
-  );
-}
-```
-
-**Server-side query must return:**
-
-```ts
-interface PaginatedResponse<T> {
-  items: T[];
-  continueCursor: string | null;
-  isDone: boolean;
-  page?: number;        // Optional
-  pageSize?: number;    // Optional
-  total?: number;       // Optional
-}
-  continueCursor: string | null;
-  isDone: boolean;
-}
-```
-
-### useUpload
-
-Upload files with progress tracking.
-
-```ts
-import { useUpload } from "@archlast/client/react";
-
-function FileUploader() {
-  const {
-    upload,
-    progress,
-    isUploading,
-    storageId,
-    error
-  } = useUpload();
-
-  const handleFileChange = async (e: ChangeEvent<HTMLInputElement>) => {
-    const file = e.target.files?.[0];
-    if (!file) return;
-
-    const id = await upload(file, "images");
-    console.log("Uploaded with ID:", id);
-  };
-
-  return (
-    <div>
-      <input type="file" onChange={handleFileChange} disabled={isUploading} />
-
-      {isUploading && (
-        <div>
-          <progress value={progress} max={100} />
-          <span>{progress}%</span>
-        </div>
-      )}
-
-      {storageId && <p>Uploaded: {storageId}</p>}
-      {error && <p className="error">{error.message}</p>}
-    </div>
-  );
-}
-```
-
-### useAuth
-
-Authentication state and actions via the `ArchlastAuthClient` wrapper.
-
-```ts
-import { useAuth } from "@archlast/client/react";
-
-function AuthButton() {
-  const {
-    isAuthenticated,
-    user,
-    isLoading,
-    signIn,
-    signOut
-  } = useAuth();
-
-  if (isLoading) return <Spinner />;
-
-  if (isAuthenticated) {
-    return (
-      <div>
-        <span>Welcome, {user?.name}</span>
-        <button onClick={() => signOut()}>
-          Sign Out
-        </button>
-      </div>
-    );
-  }
-
-  return (
-    <button onClick={() => signIn({ email: "user@example.com", password: "..." })}>
-      Sign In
-    </button>
-  );
-}
-```
-
-### Using Better-Auth React Hooks
-
-For full-featured auth in React, use Better-Auth's `useSession` hook:
-
-```tsx
-import { authClient } from "./lib/better-auth"; // Your Better-Auth client
-
-function AuthButton() {
-  const { data: session, isPending } = authClient.useSession();
-
-  if (isPending) return <Spinner />;
-
-  if (session?.user) {
-    return (
-      <div>
-        <span>Welcome, {session.user.name}</span>
-        <button onClick={() => authClient.signOut()}>
-          Sign Out
-        </button>
-      </div>
-    );
-  }
-
-  return (
-    <button onClick={() => authClient.signIn.email({ email, password })}>
-      Sign In
-    </button>
-  );
-}
-```
-
----
-
-## Direct Client Usage
-
-Use the client directly without React for Node.js, scripts, or non-React frameworks.
-
-### Fetch (Query)
-
-```ts
-// Fetch a single query
-const tasks = await client.fetch("tasks.list", {});
-
-// With arguments
-const task = await client.fetch("tasks.get", { id: "123" });
-```
-
-### Mutate
-
-```ts
-// Execute a mutation
-const created = await client.mutate("tasks.create", {
-  text: "New task",
-  priority: "high"
-});
-
-// Update
-await client.mutate("tasks.update", {
-  id: "123",
-  completed: true
-});
-
-// Delete
-await client.mutate("tasks.delete", { id: "123" });
-```
-
-### Subscribe
-
-```ts
-// Manual WebSocket subscription
-const unsubscribe = client.subscribe("tasks.list", {}, (data) => {
-  console.log("Tasks updated:", data);
-});
-
-// Later: unsubscribe
-unsubscribe();
-```
-
----
-
-## Authentication
-
-Archlast uses [Better-Auth](https://www.better-auth.com/) for authentication. The server exposes Better-Auth endpoints at `/api/auth/*`.
-
-### Using the Auth Client
-
-The `ArchlastAuthClient` provides a wrapper around Better-Auth endpoints:
-
-```ts
-import { ArchlastAuthClient } from "@archlast/client/auth";
-
-const auth = new ArchlastAuthClient({
-  baseUrl: "http://localhost:4000",
-  apiKey: "arch_your_api_key" // Optional: for programmatic access
-});
-
-// Sign up with email/password
-// POST /api/auth/sign-up/email
-await auth.signUp({
-  email: "user@example.com",
-  password: "secure_password",
-  name: "John Doe"
-});
-
-// Sign in with email/password
-// POST /api/auth/sign-in/email
-await auth.signIn({
-  email: "user@example.com",
-  password: "secure_password"
-});
-
-// Sign in with username (if username plugin enabled)
-await auth.signIn({
-  username: "johndoe",
-  password: "secure_password"
-});
-
-// Get current session
-// GET /api/auth/get-session
-const state = await auth.getState();
-console.log(state.isAuthenticated, state.user);
-
-// Sign out
-await auth.signOut();
-```
-
-### Using Better-Auth Client Directly
-
-For full Better-Auth features (OAuth, organization, admin), use the Better-Auth client directly:
-
-```ts
-import { createAuthClient } from "better-auth/react";
-import {
-  adminClient,
-  usernameClient,
-  organizationClient,
-  // Optional plugins (add as needed):
-  // anonymousClient,  // For guest users
-  // apiKeyClient,     // For API key management
-} from "better-auth/client/plugins";
-
-const authClient = createAuthClient({
-  baseURL: "http://localhost:4000/api/auth",
-  fetchOptions: { credentials: "include" },
-  plugins: [
-    adminClient(),
-    usernameClient(),
-    organizationClient(),
-  ],
-});
-
-// Email sign in (typical for user-facing apps)
-await authClient.signIn.email({
-  email: "user@example.com",
-  password: "secure_password",
-});
-
-// Username sign in (used by dashboard)
-await authClient.signIn.username({
-  username: "admin",
-  password: "secure_password",
-});
-
-// Session management
-const { data: session } = authClient.useSession();
-
-// Organization management
-await authClient.organization.create({ name: "My Team" });
-
-// Admin operations (requires admin role)
-await authClient.admin.listUsers({ limit: 10 });
-```
-
-### Auth State in Components
-
-```tsx
-import { useAuth } from "@archlast/client/react";
-
-function ProtectedRoute({ children }) {
-  const { isAuthenticated, isLoading } = useAuth();
-
-  if (isLoading) return <LoadingScreen />;
-  if (!isAuthenticated) return <Navigate to="/login" />;
-
-  return children;
-}
-```
-
----
-
-## File Storage
-
-### Storage Client
-
-```ts
-// Access via main client
-const storage = client.storage;
-
-// Or import directly
-import { StorageClient } from "@archlast/client/storage";
-const storage = new StorageClient(httpUrl, getAuthHeaders);
-```
-
-### Upload Files
-
-```ts
-const file = new File(["Hello, World!"], "hello.txt", { type: "text/plain" });
-
-// Basic upload
-const result = await client.storage.upload(file);
-console.log("Storage ID:", result.id);
-console.log("URL:", result.url);
-
-// Upload with explicit content type
-const blob = new Blob(["data"], { type: "application/octet-stream" });
-const binaryResult = await client.storage.upload(blob, "application/octet-stream");
-```
-
-### List Files
-
-### List Files
-
-```ts
-// List files with pagination
-const { items } = await client.storage.list(20, 0); // limit, offset
-
-// Next page
-const page2 = await client.storage.list(20, 20);
-
-// Items structure
-items.forEach(file => {
-  console.log(file.id);          // Storage ID
-  console.log(file.fileName);    // Original filename
-  console.log(file.contentType); // MIME type
-  console.log(file.size);        // Size in bytes
-  console.log(file.url);         // Public URL
-});
-```
-
-### Get Presigned URLs
-
-```ts
-// Get temporary signed URL for download
-const { url, expiresAt } = await client.storage.presign(storageId);
-
-// Use in img tag
-<img src={url} alt="Uploaded file" />
-```
-
-### Get Metadata
-
-```ts
-const metadata = await client.storage.getMetadata(storageId);
-console.log(metadata.filename);    // "hello.txt"
-console.log(metadata.contentType); // "text/plain"
-console.log(metadata.size);        // 13
-console.log(metadata.createdAt);   // Date
-```
-
----
-
-## Admin APIs
-
-Access admin functionality (requires admin privileges).
-
-### Admin Auth Client
-
-The `AdminClient` currently provides authentication management:
-
-```ts
-import { AdminClient } from "@archlast/client/admin";
-
-const admin = new AdminClient("http://localhost:4000", {
-  apiKey: "arch_your_api_key" // Optional: Better-Auth API key
-});
-
-// Admin authentication
-await admin.auth.signIn(email, password);
-const { user } = await admin.auth.getProfile();
-await admin.auth.signOut();
-
-// Session management
-const { sessions } = await admin.auth.getSessions();
-await admin.auth.revokeSession(sessionId);
-await admin.auth.signOutAll();
-```
-
-**Available Methods:**
-
-- `admin.auth.signIn(email, password)` - Admin sign in
-- `admin.auth.signOut()` - Sign out current session
-- `admin.auth.getProfile()` - Get admin profile
-- `admin.auth.getSessions()` - List all sessions
-- `admin.auth.revokeSession(sessionId)` - Revoke specific session
-- `admin.auth.signOutAll()` - Sign out from all sessions
-
-**Note:** Additional admin clients (users, data, API keys) may be added in future releases.
-
----
-
-## tRPC Integration
-
-For type-safe RPC with full TypeScript inference.
-
-### Setup
-
-```ts
-import { createArchlastTRPCClient } from "@archlast/client/trpc";
-import type { AppRouter } from "./_generated/rpc";
-
-const trpc = createArchlastTRPCClient<AppRouter>({
-  baseUrl: "http://localhost:4000",
-  apiKey: "arch_your_api_key"
-});
-```
-
-### Usage
-
-```ts
-// Queries
-const tasks = await trpc.tasks.list.query({});
-const task = await trpc.tasks.get.query({ id: "123" });
-
-// Mutations
-const created = await trpc.tasks.create.mutate({ text: "New task" });
-await trpc.tasks.update.mutate({ id: "123", completed: true });
-```
-
-### React Query Integration
-
-```tsx
-import { createTRPCReact } from "@trpc/react-query";
-import type { AppRouter } from "./_generated/rpc";
-
-export const trpc = createTRPCReact<AppRouter>();
-
-// In component
-function TaskList() {
-  const { data, isLoading } = trpc.tasks.list.useQuery({});
-  const createTask = trpc.tasks.create.useMutation();
-
-  // ...
-}
-```
-
----
-
-## Subpath Exports
-
-Import specific functionality to reduce bundle size:
-
-| Import | Description |
-|--------|-------------|
-| `@archlast/client` | Core `ArchlastClient` class |
-| `@archlast/client/react` | React hooks and provider |
-| `@archlast/client/auth` | Authentication client |
-| `@archlast/client/storage` | File storage client |
-| `@archlast/client/admin` | Admin API client |
-| `@archlast/client/trpc` | tRPC client factory |
-
-```ts
-// Minimal import for core functionality
-import { ArchlastClient } from "@archlast/client";
-
-// React-specific imports
-import {
-  ArchlastProvider,
-  useQuery,
-  useMutation,
-  usePagination,
-  useUpload,
-  useAuth
-} from "@archlast/client/react";
-
-// Auth-only import
-import { ArchlastAuthClient } from "@archlast/client/auth";
-```
-
----
-
-## TypeScript Support
-
-The client is fully typed. Types are generated by the CLI based on your schema.
-
-### Generated Types
-
-```ts
-// _generated/api.ts
-export const api = {
-  tasks: {
-    list: { _path: "tasks.list", _returnType: {} as Task[] },
-    get: { _path: "tasks.get", _returnType: {} as Task | null },
-    create: { _path: "tasks.create", _returnType: {} as Task },
-    // ...
-  }
-};
-```
-
-### Usage with Types
-
-```ts
-import { useQuery } from "@archlast/client/react";
-import { api } from "./_generated/api";
-
-// TypeScript knows `tasks` is Task[]
-const tasks = useQuery(api.tasks.list, {});
-
-// TypeScript knows `task` is Task | null
-const task = useQuery(api.tasks.get, { id: "123" });
-```
-
----
-
-## Error Handling
-
-### Query Errors
-
-```tsx
-function TaskList() {
-  const { data, error, isError } = useQuery(api.tasks.list, {});
-
-  if (isError) {
-    return (
-      <div className="error">
-        <h3>Failed to load tasks</h3>
-        <p>{error.message}</p>
-        <button onClick={() => refetch()}>Retry</button>
-      </div>
-    );
-  }
-
-  return <TaskGrid tasks={data} />;
-}
-```
-
-### Mutation Errors
-
-```ts
-const createTask = useMutation(api.tasks.create);
-
-try {
-  await createTask({ text: "" }); // Invalid
-} catch (error) {
-  if (error instanceof ValidationError) {
-    console.log("Validation failed:", error.issues);
-  } else if (error instanceof AuthenticationError) {
-    console.log("Not authenticated");
-  } else {
-    console.log("Unknown error:", error);
-  }
-}
-```
-
-### Global Error Boundary
-
-```tsx
-import { QueryErrorResetBoundary } from "@tanstack/react-query";
-import { ErrorBoundary } from "react-error-boundary";
-
-function App() {
-  return (
-    <QueryErrorResetBoundary>
-      {({ reset }) => (
-        <ErrorBoundary
-          onReset={reset}
-          fallbackRender={({ error, resetErrorBoundary }) => (
-            <div>
-              <p>Something went wrong: {error.message}</p>
-              <button onClick={resetErrorBoundary}>Try again</button>
-            </div>
-          )}
-        >
-          <ArchlastProvider client={client}>
-            <YourApp />
-          </ArchlastProvider>
-        </ErrorBoundary>
-      )}
-    </QueryErrorResetBoundary>
-  );
-}
-```
-
----
-
-## Advanced Patterns
-
-### Optimistic Updates
-
-```ts
-const queryClient = useQueryClient();
-
-const updateTask = useMutation(api.tasks.update, {
-  onMutate: async (newData) => {
-    // Cancel outgoing refetches
-    await queryClient.cancelQueries(["tasks.list"]);
-
-    // Snapshot previous value
-    const previous = queryClient.getQueryData(["tasks.list"]);
-
-    // Optimistically update
-    queryClient.setQueryData(["tasks.list"], (old: Task[]) =>
-      old.map(t => t._id === newData.id ? { ...t, ...newData } : t)
-    );
-
-    return { previous };
-  },
-  onError: (err, newData, context) => {
-    // Rollback on error
-    queryClient.setQueryData(["tasks.list"], context.previous);
-  }
-});
-```
-
-### SSR / Server Components
-
-```ts
-// For Next.js SSR
-const client = new ArchlastClient(
-  wsUrl,
-  httpUrl,
-  "web",
-  undefined,
-  {
-    autoConnect: false, // Don't connect on server
-    betterAuthCookies: cookies() // Pass request cookies
-  }
-);
-```
-
-### Multiple Clients
-
-```tsx
-const mainClient = new ArchlastClient(mainWsUrl, mainHttpUrl, "main");
-const analyticsClient = new ArchlastClient(analyticsWsUrl, analyticsHttpUrl, "analytics");
-
-function App() {
-  return (
-    <ArchlastProvider client={mainClient}>
-      <ArchlastProvider client={analyticsClient} contextKey="analytics">
-        <YourApp />
-      </ArchlastProvider>
-    </ArchlastProvider>
-  );
-}
-```
-
----
-
-## Keywords
-
-archlast, client, sdk, react, hooks, real-time, websocket, typescript, api
-
-## License
-
-MIT
+# @archlast/client
+
+The Archlast client SDK provides WebSocket-based queries and mutations, React
+hooks with cache integration, authentication helpers, storage utilities, admin
+APIs, and optional tRPC access.
+
+## Installation
+
+```bash
+npm install @archlast/client
+
+# Other package managers
+pnpm add @archlast/client
+yarn add @archlast/client
+bun add @archlast/client
+```
+
+Peer dependencies:
+
+```bash
+npm install react react-dom @tanstack/react-query
+```
+
+## Quick start
+
+```ts
+import { ArchlastClient } from "@archlast/client";
+import { ArchlastProvider, useQuery, useMutation } from "@archlast/client/react";
+import { api } from "./_generated/api";
+
+const client = new ArchlastClient(
+  "ws://localhost:4000/ws",
+  "http://localhost:4000",
+  "web"
+);
+
+function App() {
+  return (
+    <ArchlastProvider client={client}>
+      <TodoList />
+    </ArchlastProvider>
+  );
+}
+
+function TodoList() {
+  const tasks = useQuery(api.tasks.list, {});
+  const createTask = useMutation(api.tasks.create);
+
+  return (
+    <div>
+      <pre>{JSON.stringify(tasks, null, 2)}</pre>
+      <button onClick={() => createTask({ text: "New task" })}>
+        Add
+      </button>
+    </div>
+  );
+}
+```
+
+The `api` object is generated by the CLI in `_generated/api.ts`.
+
+## Client configuration
+
+Constructor signature:
+
+```ts
+new ArchlastClient(wsUrl, httpUrl?, appId?, authUrl?, options?)
+```
+
+Options:
+- `autoConnect` (default true)
+- `apiKey` Better Auth API key (`arch_` prefix)
+- `isAdmin` subscribe to admin streams
+- `betterAuthCookies` for session cookies
+
+```ts
+const client = new ArchlastClient(
+  "ws://localhost:4000/ws",
+  "http://localhost:4000",
+  "web",
+  undefined,
+  { apiKey: "arch_example" }
+);
+
+client.setApiKey("arch_new_key");
+client.setBetterAuthCookies({ "better-auth.session": "..." });
+```
+
+## React hooks
+
+Available from `@archlast/client/react`:
+
+- `useQuery` / `useMutation` for live queries and mutations
+- `usePagination` for cursor based queries
+- `useAuth` for Better Auth session state
+- `useUpload`, `useDownload` for storage
+- `useStorageList`, `useStorageMetadata`, `useStorageDeleteFile`
+
+Example:
+
+```ts
+const items = useQuery(api.items.list, { limit: 10 });
+const createItem = useMutation(api.items.create);
+```
+
+## Direct client usage
+
+```ts
+const data = await client.fetch("tasks.get", { id: "123" });
+const updated = await client.mutate("tasks.update", { id: "123", text: "Hi" });
+```
+
+## Authentication
+
+Auth uses Better Auth endpoints under `/api/auth/*`.
+
+```ts
+import { useAuth } from "@archlast/client/react";
+
+const { signIn, signOut, isAuthenticated } = useAuth();
+```
+
+Or use the auth client directly:
+
+```ts
+import { ArchlastAuthClient } from "@archlast/client/auth";
+
+const auth = new ArchlastAuthClient({ baseUrl: "http://localhost:4000" });
+```
+
+## Storage
+
+```ts
+const file = new File(["hello"], "hello.txt", { type: "text/plain" });
+const uploaded = await client.storage.upload(file);
+const list = await client.storage.list();
+const { url } = await client.storage.presign(uploaded.id);
+```
+
+## Admin APIs
+
+```ts
+const profile = await client.admin.auth.getProfile();
+```
+
+## tRPC integration
+
+```ts
+import { createArchlastTRPCClient } from "@archlast/client/trpc";
+import type { AppRouter } from "./_generated/rpc";
+
+const trpc = createArchlastTRPCClient<AppRouter>({
+  baseUrl: "http://localhost:4000",
+  apiKey: "arch_example"
+});
+```
+
+## Subpath exports
+
+- `@archlast/client/react`
+- `@archlast/client/trpc`
+- `@archlast/client/auth`
+- `@archlast/client/storage`
+- `@archlast/client/admin`
+
+## Troubleshooting
+
+- WebSocket errors: use `ws://<host>/ws` and confirm CORS settings.
+- Auth errors: ensure cookies or API key are configured.
+- Storage uploads: use `File` or `Blob` for browser uploads.
+
+## Publishing (maintainers)
+
+See `docs/npm-publishing.md` for release and publish steps.