@archlast/client 0.1.0 → 0.1.2

package/README.md

@@ -1,579 +1,149 @@
 # @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)
+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
 
-# Or with other package managers
+# Other package managers
 pnpm add @archlast/client
 yarn add @archlast/client
 bun add @archlast/client
 ```
 
-### Peer Dependencies
-
-Install required peer dependencies in your application:
+Peer dependencies:
 
 ```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
+## 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",  // WebSocket URL
-  "http://localhost:4000",   // HTTP URL
-  "web"                       // App ID
+  "ws://localhost:4000/ws",
+  "http://localhost:4000",
+  "web"
 );
-```
-
-### 2. Set Up the Provider
-
-```tsx
-import { ArchlastProvider } from "@archlast/client/react";
 
 function App() {
   return (
     <ArchlastProvider client={client}>
-      <YourApp />
+      <TodoList />
     </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>
+      <pre>{JSON.stringify(tasks, null, 2)}</pre>
+      <button onClick={() => createTask({ text: "New task" })}>
+        Add
+      </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.
+The `api` object is generated by the CLI in `_generated/api.ts`.
 
----
+## Client configuration
 
-## Client Configuration
-
-### Constructor Signature
+Constructor signature:
 
 ```ts
-new ArchlastClient(wsUrl, httpUrl, appId, authUrl?, options?)
+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
+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(
-  "wss://api.myapp.com/ws",
-  "https://api.myapp.com",
+  "ws://localhost:4000/ws",
+  "http://localhost:4000",
   "web",
-  "https://auth.myapp.com",  // Custom auth URL
-  {
-    autoConnect: true,
-    apiKey: "arch_your_api_key",
-    isAdmin: false,
-    betterAuthCookies: {
-      "better-auth.session": "session_token_here"
-    }
-  }
+  undefined,
+  { apiKey: "arch_example" }
 );
-```
 
-### 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"
-});
+client.setApiKey("arch_new_key");
+client.setBetterAuthCookies({ "better-auth.session": "..." });
 ```
 
----
+## React hooks
 
-## React Hooks
+Available from `@archlast/client/react`:
 
-### useQuery
+- `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`
 
-Subscribe to real-time query updates with automatic caching via TanStack Query.
+Example:
 
 ```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} />;
-}
+const items = useQuery(api.items.list, { limit: 10 });
+const createItem = useMutation(api.items.create);
 ```
 
-### useMutation
-
-Execute mutations with automatic cache invalidation.
+## Direct client usage
 
 ```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>
-  );
-}
+const data = await client.fetch("tasks.get", { id: "123" });
+const updated = await client.mutate("tasks.update", { id: "123", text: "Hi" });
 ```
 
-### 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
+Auth uses Better Auth endpoints under `/api/auth/*`.
 
 ```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;
-}
+const { signIn, signOut, isAuthenticated } = useAuth();
 ```
 
----
-
-## File Storage
-
-### Storage Client
+Or use the auth client directly:
 
 ```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);
+import { ArchlastAuthClient } from "@archlast/client/auth";
 
-// Use in img tag
-<img src={url} alt="Uploaded file" />
+const auth = new ArchlastAuthClient({ baseUrl: "http://localhost:4000" });
 ```
 
-### Get Metadata
+## Storage
 
 ```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
+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
 
-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
-
-For type-safe RPC with full TypeScript inference.
-
-### Setup
+## tRPC integration
 
 ```ts
 import { createArchlastTRPCClient } from "@archlast/client/trpc";
@@ -581,246 +151,24 @@ import type { AppRouter } from "./_generated/rpc";
 
 const trpc = createArchlastTRPCClient<AppRouter>({
   baseUrl: "http://localhost:4000",
-  apiKey: "arch_your_api_key"
+  apiKey: "arch_example"
 });
 ```
 
-### 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>
-  );
-}
-```
+## Subpath exports
 
----
+- `@archlast/client/react`
+- `@archlast/client/trpc`
+- `@archlast/client/auth`
+- `@archlast/client/storage`
+- `@archlast/client/admin`
 
-## Publishing (Maintainers)
+## Troubleshooting
 
-See `docs/npm-publishing.md` for release and publish steps.
+- 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.
 
-## License
+## Publishing (maintainers)
 
-MIT
+See `docs/npm-publishing.md` for release and publish steps.

package/package.json

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