@archlast/client 0.0.1 → 0.1.0

package/README.md

@@ -1,50 +1,579 @@
 # @archlast/client
 
-Archlast client SDK for React hooks, auth helpers, storage utilities, and tRPC client access.
+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.
 
-## Install
+## 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 in your app):
+### Peer Dependencies
+
+Install required peer dependencies in your application:
 
 ```bash
 npm install react react-dom @tanstack/react-query
 ```
 
-## Usage
+### Optional Dependencies
+
+For tRPC support:
+
+```bash
+npm install @trpc/client @trpc/react-query
+```
+
+## Quick Start
+
+### 1. Create the Client
 
 ```ts
-import { ArchlastClient, ArchlastProvider, useQuery } from "@archlast/client";
-import { api } from "./_generated/api";
+import { ArchlastClient } from "@archlast/client";
+
+const client = new ArchlastClient(
+  "ws://localhost:4000/ws",  // WebSocket URL
+  "http://localhost:4000",   // HTTP URL
+  "web"                       // App ID
+);
+```
+
+### 2. Set Up the Provider
 
-const client = new ArchlastClient({ baseUrl: "http://localhost:4000" });
+```tsx
+import { ArchlastProvider } from "@archlast/client/react";
 
 function App() {
   return (
     <ArchlastProvider client={client}>
-      <TodoList />
+      <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, {});
-  return <pre>{JSON.stringify(tasks, null, 2)}</pre>;
+
+  // 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,
+    isLoading,
+    hasMore,
+    loadMore,
+    error
+  } = usePagination(api.tasks.listPaginated, {
+    limit: 20,
+    filter: { completed: false }
+  });
+
+  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>
+      )}
+    </div>
+  );
+}
+```
+
+**Server-side query must return:**
+
+```ts
+interface PaginatedResult<T> {
+  items: T[];
+  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.
+
+```ts
+import { useAuth } from "@archlast/client/react";
+
+function AuthButton() {
+  const {
+    signIn,
+    signOut,
+    isAuthenticated,
+    user,
+    isLoading
+  } = 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({ provider: "google" })}>
+      Sign in with Google
+    </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
+
+### Using the Auth Client
+
+```ts
+import { ArchlastAuthClient } from "@archlast/client/auth";
+
+const auth = new ArchlastAuthClient({
+  baseUrl: "http://localhost:4000"
+});
+
+// Email/password sign up
+await auth.signUp({
+  email: "user@example.com",
+  password: "secure_password",
+  name: "John Doe"
+});
+
+// Email/password sign in
+await auth.signIn({
+  email: "user@example.com",
+  password: "secure_password"
+});
+
+// OAuth sign in
+await auth.signIn({ provider: "google" });
+await auth.signIn({ provider: "github" });
+
+// Get current session
+const session = await auth.getSession();
+
+// Sign out
+await auth.signOut();
+```
+
+### 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;
 }
 ```
 
-## Subpath exports
+---
+
+## 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 to specific bucket
+const imageResult = await client.storage.upload(imageFile, "images");
+```
+
+### List Files
+
+```ts
+// List all files
+const files = await client.storage.list();
+
+// List files in bucket
+const images = await client.storage.list("images");
+
+// With pagination
+const page1 = await client.storage.list("images", { limit: 20 });
+const page2 = await client.storage.list("images", {
+  limit: 20,
+  cursor: page1.nextCursor
+});
+```
+
+### 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).
+
+```ts
+// Auth operations
+const profile = await client.admin.auth.getProfile();
+const users = await client.admin.auth.listUsers();
+await client.admin.auth.updateUser(userId, { role: "admin" });
+
+// API key management
+const keys = await client.admin.apiKeys.list();
+const newKey = await client.admin.apiKeys.create({ name: "CI/CD" });
+await client.admin.apiKeys.revoke(keyId);
+
+// Data operations
+const collections = await client.admin.data.listCollections();
+const docs = await client.admin.data.query("tasks", { limit: 100 });
+```
+
+---
+
+## tRPC Integration
 
-- `@archlast/client/react`
-- `@archlast/client/trpc`
-- `@archlast/client/auth`
-- `@archlast/client/storage`
-- `@archlast/client/admin`
+For type-safe RPC with full TypeScript inference.
 
-## tRPC client
+### Setup
 
 ```ts
 import { createArchlastTRPCClient } from "@archlast/client/trpc";
@@ -52,9 +581,246 @@ 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);
+  }
 });
 ```
 
-## Publishing (maintainers)
+### 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>
+  );
+}
+```
+
+---
+
+## Publishing (Maintainers)
 
 See `docs/npm-publishing.md` for release and publish steps.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@archlast/client",
-    "version": "0.0.1",
+    "version": "0.1.0",
     "description": "Archlast client SDK for React and API access",
     "license": "MIT",
     "repository": {