clefbase 2.0.7 → 2.0.9

package/README.md

@@ -1,6 +1,6 @@
 # clefbase
 
-Firebase-style SDK and CLI for Clefbase / [Cleforyx](https://cleforyx.com). Database, auth, storage, and hosting in one package.
+Firebase-style SDK and CLI for Clefbase / [Cleforyx](https://cleforyx.com). Database, auth, storage, functions, AI, and hosting in one package.
 
 ## Install
 
@@ -12,7 +12,7 @@ npm install clefbase
 
 ## Quick Start
 
-### 1 — Initialise your project
+### 1 — Initialize your project
 
 ```bash
 npx clefbase init
@@ -23,15 +23,17 @@ The CLI will ask for your Project ID, API Key, and Admin Secret, let you pick wh
 ### 2 — Use the SDK
 
 ```ts
-import { initClefbase, getDatabase, getAuth, getStorage, getHosting } from "clefbase";
+import { initClefbase, getDatabase, getAuth, getStorage, getHosting, getFunctions, getAI } from "clefbase";
 import config from "./clefbase.json";
 
 const app = initClefbase(config);
 
-const db      = getDatabase(app);
-const auth    = getAuth(app);
-const storage = getStorage(app);
-const hosting = getHosting(app);  // requires adminSecret in config
+const db        = getDatabase(app);
+const auth      = getAuth(app);
+const storage   = getStorage(app);
+const hosting   = getHosting(app);  // requires adminSecret in config
+const functions = getFunctions(app);
+const ai        = getAI(app);
 ```
 
 ---
@@ -46,7 +48,7 @@ const post = await db.collection("posts").add({
   published: true,
   views: 0,
 });
-// post._id, post._createdAt, post._updatedAt are set by the server
+// post.id, post._createdAt, post._updatedAt are set by the server
 ```
 
 ### Get a document
@@ -107,6 +109,27 @@ await comments.add({ text: "Great post!", author: "Bob" });
 const all = await comments.getDocs();
 ```
 
+### Batch operations
+
+```ts
+const batch = db.batch();
+batch.set(db.collection("users").doc("user-1"), { name: "Alice" });
+batch.update(db.collection("users").doc("user-2"), { status: "active" });
+batch.delete(db.collection("logs").doc("log-1"));
+await batch.commit();
+```
+
+### Transactions
+
+```ts
+await db.runTransaction(async (tx) => {
+  const balance = await tx.collection("accounts").doc("acc-1").get();
+  const newBalance = (balance?.balance ?? 0) - 100;
+  tx.update(db.collection("accounts").doc("acc-1"), { balance: newBalance });
+  tx.set(db.collection("transactions").doc(), { amount: 100, type: "withdraw" });
+});
+```
+
 ### Convenience helpers
 
 ```ts
@@ -116,10 +139,24 @@ await db.updateDoc("users", "uid-123", { lastSeen: new Date().toISOString() });
 await db.deleteDoc("users", "uid-123");
 ```
 
+### FieldValue helpers
+
+```ts
+import { FieldValue } from "clefbase";
+
+await db.collection("posts").doc("p1").update({
+  views:       FieldValue.increment(1),
+  publishedAt: FieldValue.serverTimestamp(),
+  tags:        FieldValue.arrayUnion(["new-tag"]),
+});
+```
+
 ---
 
 ## Auth
 
+### Email / Password
+
 ```ts
 // Sign up
 const { user, token } = await auth.signUp("alice@example.com", "password123", {
@@ -127,76 +164,568 @@ const { user, token } = await auth.signUp("alice@example.com", "password123", {
   metadata: { role: "member" },
 });
 
-// Sign in / out
-const { user } = await auth.signIn("alice@example.com", "password123");
+// Sign in
+const { user, token } = await auth.signIn("alice@example.com", "password123");
+
+// Sign out
 await auth.signOut();
 
 // Current user
 const me = auth.currentUser; // AuthUser | null
+```
+
+### Auth state listener
 
-// Listen for auth state changes
+```ts
 const unsubscribe = auth.onAuthStateChanged((user) => {
   if (user) console.log("Signed in as", user.email);
   else      console.log("Signed out");
 });
+
+// Cleanup
 unsubscribe();
+```
 
+### Profile management
+
+```ts
 // Update profile
-await auth.updateProfile({ displayName: "Bob", metadata: { theme: "dark" } });
+await auth.updateProfile({ 
+  displayName: "Bob", 
+  metadata: { theme: "dark" } 
+});
+```
 
-// Password management
+### Password management
+
+```ts
+// Change password
 await auth.changePassword("oldPass", "newPass");
+
+// Send password reset email
 await auth.sendPasswordResetEmail("alice@example.com");
+
+// Confirm reset (call from link in email)
 await auth.confirmPasswordReset(resetToken, "newPassword");
+```
 
-// Email verification
+### Email verification
+
+```ts
+// Send verification email
 await auth.sendEmailVerification();
+
+// Verify email (call from link in email)
 await auth.verifyEmail("ABC123");
 ```
 
+### OAuth / Social login (Gateway)
+
+```ts
+// 1. Start sign-in with Google/GitHub/etc via gateway
+await auth.signInWithGateway("google");
+// Redirects to auth.cleforyx.com
+
+// 2. Handle callback on every app load (before rendering)
+const result = await auth.handleAuthCallback();
+if (result) {
+  console.log("Signed in:", result.user.email);
+  setAuthToken(app, result.token);
+}
+```
+
 ---
 
 ## Storage
 
+### Upload files
+
 ```ts
-// Upload (Node.js)
+// Node.js
 import fs from "fs";
 const meta = await storage.ref("avatars/user-123.jpg").upload(
   fs.readFileSync("./photo.jpg"),
   { contentType: "image/jpeg" }
 );
 
-// Upload (browser)
-const meta = await storage.ref(`uploads/${file.name}`).upload(file);
+// Browser
+const input = document.querySelector("input[type='file']");
+const meta = await storage.ref(`uploads/${input.files[0].name}`).upload(input.files[0]);
+
+console.log(meta.id, meta.sizeBytes, meta.md5);
+```
+
+### Download files
 
-// Download URL
+```ts
+// Get authenticated download URL
 const url = await storage.ref("avatars/user-123.jpg").getDownloadURL();
 
-// Metadata
+// Use directly in img tags or fetch
+const response = await fetch(url);
+const blob = await response.blob();
+```
+
+### File metadata
+
+```ts
 const meta = await storage.ref("avatars/user-123.jpg").getMetadata();
+console.log(meta.size, meta.mimeType, meta.uploadedAt);
+```
+
+### Delete files
 
-// Delete
+```ts
 await storage.ref("avatars/user-123.jpg").delete();
+```
 
-// List files
+### List files
+
+```ts
+// List root files
 const files = await storage.ref("avatars/").list({ limit: 20 });
 
-// Named bucket
-const ref = storage.bucket("user-uploads").ref("doc.pdf");
-await ref.upload(buffer, { contentType: "application/pdf" });
+// List with folder filtering
+const folderFiles = await storage.ref("avatars/2024/").list({ offset: 20 });
+```
+
+### Named buckets
+
+```ts
+const userBucket = storage.bucket("user-uploads");
+
+// Upload to bucket
+const file = await userBucket.ref("documents/resume.pdf").upload(buffer, {
+  contentType: "application/pdf"
+});
+
+// Download from bucket
+const url = await userBucket.ref("documents/resume.pdf").getDownloadURL();
+```
+
+### Set default bucket
+
+```ts
+storage.setDefaultBucket("media");
+// Now storage.ref() uses "media" instead of "default"
+```
+
+---
+
+## Functions
+
+### Deploy a function
+
+```ts
+await functions.deploy({
+  name:     "greetUser",
+  runtime:  "node",
+  trigger:  { type: "http" },
+  source:   `export async function handler(ctx) {
+    return { greeting: \`Hello, \${ctx.data.name}!\` };
+  }`,
+  timeoutMs: 30000,
+});
+```
+
+### Deploy from file (Node.js/CLI)
+
+```ts
+import { deployFromFile } from "clefbase";
+
+await deployFromFile(functions, {
+  name:     "analyzeImage",
+  runtime:  "python",
+  trigger:  { type: "http" },
+  filePath: "./functions/analyze_image.py",
+  env:      { API_KEY: process.env.API_KEY! },
+});
+```
+
+### Call HTTP-triggered functions
+
+```ts
+// One-shot call
+const { data, durationMs } = await functions.call("greetUser", { name: "Alice" });
+
+// Typed callable (recommended)
+const greet = httpsCallable<{ name: string }, { greeting: string }>(functions, "greetUser");
+const result = await greet({ name: "Bob" });
+```
+
+### Auth-aware function calls
+
+```ts
+import { setAuthToken } from "clefbase";
+
+const { token } = await auth.signIn("user@example.com", "password");
+setAuthToken(app, token);
+
+// ctx.auth.uid and ctx.auth.email available inside the function
+const { data } = await functions.call("getUserProfile");
+```
+
+### Scheduled functions (Cron)
+
+```ts
+await functions.deploy({
+  name:    "dailyReport",
+  runtime: "node",
+  trigger: { 
+    type: "cron",
+    cron: "0 9 * * *",  // Every day at 9 AM UTC
+  },
+  source: `export async function handler(ctx) {
+    // Generate daily report
+    return { status: "completed" };
+  }`,
+});
+```
+
+### List and manage functions
+
+```ts
+// List all functions
+const functions = await functions.list();
+
+// Get executions / call history
+const executions = await functions.executions("greetUser", 50);
+
+// Delete a function
+await functions.delete("greetUser");
+```
+
+---
+
+## AI
+
+### Text / Code generation
+
+```ts
+import { generateText } from "clefbase";
+
+const { content, inputTokens, outputTokens } = await ai.text({
+  model:        "claude-sonnet-4-5",
+  prompt:       "Write a bubble-sort in Python",
+  systemPrompt: "Return only code, no explanation.",
+  maxTokens:    512,
+  temperature:  0.3,
+});
+
+console.log(content);
+```
+
+### Vision / Multimodal text generation
+
+Send images (from URLs or base64) to text generation models for analysis, object detection, OCR, or image description. Supported by Claude 3+, Gemini 1.5+, and other vision-capable models.
+
+```ts
+// Single image from URL
+const { content } = await ai.text({
+  model:  "claude-sonnet-4-5",
+  prompt: "What objects are in this image? List them.",
+  images: [
+    { source: "https://example.com/photo.jpg" }
+  ],
+});
+
+// Multiple images with descriptions
+const { content } = await ai.text({
+  model:  "gemini-2.5-flash",
+  prompt: "Compare these two diagrams and describe the differences",
+  images: [
+    { 
+      source: "https://example.com/diagram-1.png",
+      description: "Original design" 
+    },
+    { 
+      source: "https://example.com/diagram-2.png",
+      description: "Updated design" 
+    },
+  ],
+});
+
+// Base64-encoded image (e.g., from canvas, screenshot, etc.)
+const { content } = await ai.text({
+  model:  "claude-sonnet-4-5",
+  prompt: "Extract and read all text from this screenshot",
+  images: [
+    { 
+      source: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEA...",
+      mediaType: "image/png"
+    }
+  ],
+});
+
+// Vision with system prompt and history
+const { content } = await ai.text({
+  model:        "claude-sonnet-4-5",
+  prompt:       "What color is the car in this image?",
+  systemPrompt: "You are a visual expert. Be precise and concise.",
+  images: [
+    { source: "https://example.com/car.jpg" }
+  ],
+  history: [
+    { role: "user", content: "Analyze this street scene" },
+    { role: "assistant", content: "I can see a busy urban street..." },
+  ],
+});
+```
+
+### File attachments for document and code analysis
+
+Pass documents, code files, spreadsheets, and other files to text models for analysis, summarization, and extraction. Supports PDFs, Word docs, spreadsheets, code files, JSON, CSV, video/audio transcription, and more.
+
+```ts
+// Summarize a PDF from a URL
+const { content } = await ai.text({
+  model:  "claude-sonnet-4-5",
+  prompt: "Summarize this document in 3 key points",
+  files: [
+    {
+      source:      "https://example.com/whitepaper.pdf",
+      mediaType:   "application/pdf",
+      filename:    "whitepaper.pdf",
+      description: "Technical whitepaper"
+    }
+  ],
+});
+
+// Extract data from a CSV (base64)
+const csvBase64 = "data:text/csv;base64,bmFtZSxhZ2UsY2l0eSpFdmlzLDM1LExvbmRvbg==";
+const { content } = await ai.text({
+  model:  "gemini-2.5-flash",
+  prompt: "Find all people over 30 and their cities",
+  files: [
+    {
+      source:      csvBase64,
+      mediaType:   "text/csv",
+      filename:    "users.csv",
+      description: "User database export"
+    }
+  ],
+});
+
+// Code review and security analysis
+const { content } = await ai.text({
+  model:  "claude-sonnet-4-5",
+  prompt: "Find security vulnerabilities and suggest fixes",
+  files: [
+    {
+      source:      "https://example.com/auth-handler.ts",
+      mediaType:   "text/typescript",
+      filename:    "auth.ts",
+      description: "Authentication handler"
+    }
+  ],
+});
+
+// Compare multiple documents
+const { content } = await ai.text({
+  model:  "claude-sonnet-4-5",
+  prompt: "Are these API schemas compatible? List differences.",
+  files: [
+    {
+      source:      "data:application/json;base64,eyJwcm9wc...",
+      mediaType:   "application/json",
+      filename:    "v1-schema.json",
+      description: "Original API schema"
+    },
+    {
+      source:      "data:application/json;base64,eyJwcm9wc...",
+      mediaType:   "application/json",
+      filename:    "v2-schema.json",
+      description: "New API schema"
+    }
+  ],
+});
+
+// Video/audio transcription and analysis
+const { content } = await ai.text({
+  model:  "claude-sonnet-4-5",
+  prompt: "Transcribe and summarize this podcast episode",
+  files: [
+    {
+      source:      "https://example.com/podcast.mp3",
+      mediaType:   "audio/mpeg",
+      filename:    "episode-42.mp3",
+      description: "Weekly podcast episode"
+    }
+  ],
+});
+```
+
+### Local AI models (Ollama)
+
+```ts
+// If Ollama is configured on your server, use local models
+const { content } = await ai.text({
+  model:  "ollama:mistral",
+  prompt: "Explain quantum computing",
+});
+```
+
+### Image generation
+
+**Text-to-Image:**
+```ts
+const { files } = await ai.image({
+  model:        "imagen-4.0-generate-001",
+  prompt:       "A futuristic city at sunset",
+  aspectRatio:  "16:9",
+  numberOfImages: 2,
+  outputFolder: "ai-generated", // saved to project storage
+});
+
+// Access generated images
+for (const file of files) {
+  console.log(file.fullPath); // e.g. "ai-generated/img_123.png"
+  const url = await storage.ref(file.fullPath).getDownloadURL();
+}
+```
+
+**Image-to-Image** (style transfer, upscaling, inpainting):
+```ts
+// Style transfer: apply Van Gogh style to a photo
+const { files } = await ai.image({
+  model: "imagen-4.0-generate-001",
+  prompt: "Repaint in the style of Van Gogh's Starry Night",
+  referenceImage: {
+    source: "https://example.com/portrait.jpg",
+    strength: 0.6, // 0–1: how much to preserve the reference
+  },
+  outputFolder: "styled",
+});
+
+// Upscaling: enhance and detail an existing image
+const { files: upscaled } = await ai.image({
+  model: "imagen-4.0-generate-001",
+  prompt: "Upscale with enhanced details, make it sharper and more vibrant",
+  referenceImage: {
+    source: "data:image/jpeg;base64,/9j/4AAQSkZJRg...", // base64 image
+    strength: 0.9, // high similarity to original
+  },
+});
+
+// Inpainting: modify objects in an image
+const { files: inpainted } = await ai.image({
+  model: "imagen-4.0-generate-001",
+  prompt: "Replace the sky with a dramatic sunset",
+  referenceImage: {
+    source: "https://example.com/landscape.jpg",
+    strength: 0.7,
+  },
+});
+```
+
+### Video generation (Veo 2)
+
+**Text-to-Video:**
+```ts
+// Async operation — waits for completion (1–5 minutes)
+const { status, files } = await ai.video({
+  model:           "veo-3.1-generate-preview",
+  prompt:          "A golden retriever on a sunny beach",
+  durationSeconds: 5,
+  aspectRatio:     "16:9",
+  outputFolder:    "videos",
+});
+
+const videoUrl = await storage.ref(files[0].fullPath).getDownloadURL();
+```
+
+**Image-to-Video** (animate photos, create camera movements):
+```ts
+// Animate a static photo
+const { files } = await ai.video({
+  model: "veo-3.1-generate-preview",
+  prompt: "The person starts walking toward the camera with a smile",
+  referenceImage: {
+    source: "https://example.com/portrait.jpg",
+    strength: 0.8, // strong visual consistency
+  },
+  durationSeconds: 4,
+  outputFolder: "animations",
+});
+
+// Cinematic camera movement
+const { files: cinematic } = await ai.video({
+  model: "veo-3.1-generate-preview",
+  prompt: "Smooth dolly-in camera movement, revealing more landscape detail",
+  referenceImage: {
+    source: "https://example.com/landscape.jpg",
+    strength: 0.7,
+  },
+  durationSeconds: 6,
+  aspectRatio: "16:9",
+});
+
+// Temporal extension (what happens next?)
+const { files: extended } = await ai.video({
+  model: "veo-3.1-generate-preview",
+  prompt: "The scene transitions to evening with golden hour lighting",
+  referenceImage: {
+    source: "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
+    strength: 0.6, // more creative freedom
+  },
+  durationSeconds: 5,
+});
+```
+
+### Embeddings
+
+```ts
+const { embeddings } = await ai.embedding({
+  model: "gemini-embedding-001",
+  input: ["apple", "orange", "banana"],
+});
+
+// embeddings[0] → vector for "apple"
+// embeddings[1] → vector for "orange"
+// etc.
+```
+
+### List available models
+
+```ts
+// All models
+const all = await ai.listModels();
+
+// Filter by category
+const textModels = await ai.listModels({ category: "text" });
+const imageModels = await ai.listModels({ category: "image" });
+
+// Filter by provider
+const googleModels = await ai.listModels({ provider: "google" });
+const anthropicModels = await ai.listModels({ provider: "anthropic" });
+```
+
+### Usage statistics
+
+```ts
+const stats = await ai.getStats();
+console.log(stats.totalRequests, stats.totalInputTokens, stats.totalMediaGenerated);
+
+// Get request log
+const records = await ai.getUsage({ limit: 20 });
+for (const r of records) {
+  console.log(r.model, r.status, r.createdAt);
+}
 ```
 
 ---
 
 ## Hosting
 
-### SDK
+### SDK: Deploy and manage sites
 
 ```ts
 import fs from "fs";
+import { getHosting } from "clefbase";
+
 const hosting = getHosting(app);
 
-// List sites
+// List all sites
 const sites = await hosting.listSites();
 
 // Create a site
@@ -217,51 +746,102 @@ console.log(`Live at: ${result.url}`);
 
 // Get active deploy
 const active = await hosting.site(site.id).getActiveDeploy();
+
+// List deploy history
+const deploys = await hosting.site(site.id).listDeploys({ limit: 10 });
 ```
 
-### CLI
+### CLI: Deploy from command line
 
 ```bash
 # First-time setup (interactive)
 clefbase init
 
-# Build then deploy in one step
+# Build then deploy
 npm run build && clefbase deploy
 
 # Deploy with options
 clefbase deploy --dir ./build --message "v2 release"
-clefbase deploy --site <siteId>     # override the linked site
+clefbase deploy --site <siteId>     # override linked site
 
-# Manage hosting
-clefbase hosting:init               # link/create a site
+# Manage sites
+clefbase hosting:init               # link or create a site
 clefbase hosting:status             # show current live deploy
 clefbase hosting:sites              # list all sites
+clefbase hosting:list-deploys       # show deployment history
 
 # Project info
-clefbase info                       # config + connectivity check
+clefbase info                       # show config and connectivity
+clefbase --version                  # show SDK version
+```
+
+### Custom domains
+
+```ts
+// Add custom domain to site
+await hosting.site(siteId).addCustomDomain("app.example.com");
+
+// Get custom domains
+const domains = await hosting.site(siteId).getCustomDomains();
+
+// Remove custom domain
+await hosting.site(siteId).removeCustomDomain("app.example.com");
 ```
 
 ---
 
-## CLI Reference
+## TypeScript
 
-| Command | Description |
-|---|---|
-| `clefbase init` | Interactive project setup |
-| `clefbase deploy` | Deploy your built site |
-| `clefbase deploy -d <dir>` | Deploy from a specific directory |
-| `clefbase deploy -m <msg>` | Deploy with a release note |
-| `clefbase deploy -s <siteId>` | Deploy to a specific site |
-| `clefbase hosting:init` | Link or create a hosted site |
-| `clefbase hosting:status` | Show current live deploy |
-| `clefbase hosting:sites` | List all sites |
-| `clefbase info` | Show config and connectivity |
+### Full type safety
+
+```ts
+import type { ClefbaseDocument } from "clefbase";
+
+interface Post extends ClefbaseDocument {
+  title:     string;
+  published: boolean;
+  views:     number;
+  tags:      string[];
+}
+
+const posts = db.collection<Post>("posts");
+const post = await posts.doc("p1").get();
+// post.views is number ✓, post.author doesn't exist ✗
+```
+
+### Function types
+
+```ts
+import { httpsCallable } from "clefbase";
+
+const add = httpsCallable<
+  { a: number; b: number },
+  { sum: number }
+>(functions, "add");
+
+const { data } = await add({ a: 3, b: 4 });
+console.log(data.sum); // ✓
+// console.log(data.product); // ✗ TypeScript error
+```
+
+### Auth types
+
+```ts
+import type { AuthUser } from "clefbase";
+
+const user: AuthUser | null = auth.currentUser;
+if (user) {
+  console.log(user.uid, user.email, user.displayName);
+}
+```
 
 ---
 
-## clefbase.json
+## Configuration
 
-Written by `clefbase init`. Never commit this file — it contains your secrets. The CLI adds it to `.gitignore` automatically.
+### clefbase.json
+
+Written by `clefbase init`. Never commit this file — add to `.gitignore` automatically.
 
 ```json
 {
@@ -272,8 +852,10 @@ Written by `clefbase init`. Never commit this file — it contains your secrets.
   "services": {
     "database": true,
     "auth":     true,
-    "storage":  false,
-    "hosting":  true
+    "storage":  true,
+    "hosting":  true,
+    "functions": true,
+    "ai":        true
   },
   "hosting": {
     "siteId":     "355f3976-89dc-...",
@@ -286,18 +868,129 @@ Written by `clefbase init`. Never commit this file — it contains your secrets.
 
 ---
 
-## TypeScript
+## Error Handling
 
-Full types with generics:
+### Database errors
 
 ```ts
-interface Post extends ClefbaseDocument {
-  title:     string;
-  published: boolean;
-  views:     number;
+import { ClefbaseError } from "clefbase";
+
+try {
+  await db.collection("users").doc("id").get();
+} catch (err) {
+  if (err instanceof ClefbaseError) {
+    console.error(err.message, err.code, err.status);
+  }
 }
+```
 
-const posts = db.collection<Post>("posts");
+### Functions errors
+
+```ts
+import { FunctionsError } from "clefbase";
+
+try {
+  await functions.call("myFunction");
+} catch (err) {
+  if (err instanceof FunctionsError) {
+    console.error(err.message, err.httpStatus);
+  }
+}
+```
+
+### AI errors
+
+```ts
+import { AIError } from "clefbase";
+
+try {
+  await ai.text({ model: "claude-sonnet-4-5", prompt: "Hi" });
+} catch (err) {
+  if (err instanceof AIError) {
+    console.error(err.message, err.httpStatus);
+  }
+}
+```
+
+---
+
+## Environment variables
+
+Create a `.env` file with:
+
+```bash
+CLEFORYX_SERVER_URL=https://api.cleforyx.com
+CLEFORYX_PROJECT_ID=your_project_id
+CLEFORYX_API_KEY=your_api_key
+CLEFORYX_ADMIN_SECRET=your_admin_secret
+```
+
+Or load into environment and use:
+
+```ts
+const app = initClefbase({
+  serverUrl:   process.env.CLEFORYX_SERVER_URL!,
+  projectId:   process.env.CLEFORYX_PROJECT_ID!,
+  apiKey:      process.env.CLEFORYX_API_KEY!,
+  adminSecret: process.env.CLEFORYX_ADMIN_SECRET,
+});
+```
+
+---
+
+## Advanced topics
+
+### Custom HTTP headers
+
+```ts
+import { HttpClient } from "clefbase";
+
+const client = new HttpClient(
+  "https://api.cleforyx.com/db",
+  { "x-cfx-key": "your-api-key" }
+);
+```
+
+### Offline-first patterns
+
+```ts
+// Store auth token locally
+localStorage.setItem("cfx_token", token);
+
+// On app load
+const saved = localStorage.getItem("cfx_token");
+if (saved) {
+  setAuthToken(app, saved);
+  const user = auth.currentUser;
+  // Use cached state while syncing in background
+}
+```
+
+### Server-side usage (Node.js)
+
+All SDK methods work on Node.js:
+
+```ts
+import { initClefbase, getDatabase } from "clefbase";
+
+const app = initClefbase({
+  serverUrl: "https://api.cleforyx.com",
+  projectId: "my_project",
+  apiKey: process.env.CLEFORYX_API_KEY!,
+});
+
+const db = getDatabase(app);
+const users = await db.collection("users").getDocs();
+```
+
+---
+
+## Support
+
+- **Docs**: https://cleforyx.com/docs
+- **GitHub**: https://github.com/cleforyx/clefbase
+- **Issues**: https://github.com/cleforyx/clefbase/issues
+- **Community**: https://discord.gg/cleforyx
 const post  = await posts.doc("abc").get();  // Post | null
 ```