hydrousdb 2.0.0 → 2.0.3

package/README.md

@@ -1,774 +1,1282 @@
-# hydrousdb
+# HydrousDB SDK
 
-> **Official TypeScript SDK for [HydrousDB](https://db-api-82687684612.us-central1.run.app)**
-> — a cloud-native record store with built-in authentication, batch operations, analytics, and cursor-based pagination.
+Official JavaScript / TypeScript SDK for the **HydrousDB** platform.  
+Auth · Records · Analytics · Storage — one package, one client.
 
-[![npm version](https://img.shields.io/npm/v/hydrousdb)](https://npmjs.com/package/hydrousdb)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+```bash
+npm install hydrousdb
+```
 
 ---
 
 ## Table of Contents
 
-- [Features](#features)
-- [Installation](#installation)
-- [Key Concepts](#key-concepts)
-- [Quick Start](#quick-start)
-- [Framework Guides](#framework-guides)
-  - [Next.js (App Router)](#nextjs-app-router)
-  - [Next.js (Pages Router)](#nextjs-pages-router)
-  - [Vue 3 / Nuxt 3](#vue-3--nuxt-3)
-  - [React (Vite / CRA)](#react-vite--cra)
-  - [Node.js / Express](#nodejs--express)
-- [API Reference](#api-reference)
-  - [createClient](#createclient)
-  - [Records](#records)
-  - [Auth](#auth)
-  - [Analytics](#analytics)
-- [Error Handling](#error-handling)
-- [Pagination](#pagination)
-- [TypeScript](#typescript)
-- [Migration from v1](#migration-from-v1)
-- [Contributing](#contributing)
-- [License](#license)
+1. [Setup & Client Configuration](#1-setup--client-configuration)
+2. [Auth](#2-auth)
+3. [Records](#3-records)
+4. [Analytics](#4-analytics)
+5. [Storage](#5-storage)
+   - [How storage keys work](#how-storage-keys-work)
+   - [Upload a file with progress](#upload-a-file-with-progress)
+   - [Batch upload](#batch-upload)
+   - [Download a file](#download-a-file)
+   - [List files](#list-files)
+   - [Delete, move, copy](#delete-move-copy)
+   - [Signed URLs](#signed-urls)
+   - [Upload raw text / JSON](#upload-raw-text--json)
+   - [Stats](#stats)
+6. [Error Handling](#6-error-handling)
+7. [Real-World Examples — Next.js](#7-real-world-examples--nextjs)
+   - [Auth: Login page with session handling](#auth-login-page-with-session-handling)
+   - [Records: Product listing with filters](#records-product-listing-with-filters)
+   - [Storage: Avatar upload with live progress bar](#storage-avatar-upload-with-live-progress-bar)
+   - [Storage: Secure file download link](#storage-secure-file-download-link)
+   - [Analytics: Page-view tracking](#analytics-page-view-tracking)
+8. [Real-World Examples — Vue 3](#8-real-world-examples--vue-3)
+   - [Auth: Login composable](#auth-login-composable)
+   - [Storage: File upload with progress](#storage-file-upload-with-progress-1)
+   - [Records: Data table with pagination](#records-data-table-with-pagination)
+9. [Real-World Examples — SvelteKit](#9-real-world-examples--sveltekit)
+10. [Real-World Examples — Express / Node API](#10-real-world-examples--express--node-api)
+11. [TypeScript Types Reference](#11-typescript-types-reference)
 
 ---
 
-## Features
+## 1. Setup & Client Configuration
 
-- ✅ **Full TypeScript** — every method and response is fully typed
-- ✅ **Multi-bucket** — one client, any number of buckets; pass `bucketKey` per call
-- ✅ **Modular** — import only what you need (`hydrousdb/records`, `hydrousdb/auth`, `hydrousdb/analytics`)
-- ✅ **Tree-shakeable** — ships ESM + CJS with dual exports
-- ✅ **Auto-retry** — retries on transient 5xx / network errors with linear back-off
-- ✅ **Timeout control** — configurable per-client request timeout
-- ✅ **Cursor pagination helpers** — `queryAll()` / `listAllUsers()` handle cursor following for you
-- ✅ **Zero dependencies** — uses the native `fetch` API (Node 18+, all modern browsers)
+Create **one** client and reuse it across your app.
 
----
+```ts
+import { createClient } from 'hydrousdb';
+
+const db = createClient({
+  url:               'https://api.myapp.hydrous.app',  // your project URL
+  authKey:           'hk_auth_…',                      // auth service key
+  bucketSecurityKey: 'hk_bucket_…',                    // records + analytics key
+  storageKeys: {
+    main:      'ssk_main_…',        // your default storage bucket
+    avatars:   'ssk_avatars_…',     // a dedicated bucket for user avatars
+    documents: 'ssk_docs_…',        // a bucket for user documents
+    // …add as many as you need
+  },
+});
+```
+
+### Key types explained
+
+| Config field        | Used by                 | What it is                                               |
+|---------------------|-------------------------|----------------------------------------------------------|
+| `authKey`           | `db.auth.*`             | One key — controls all auth operations                   |
+| `bucketSecurityKey` | `db.records.*` `db.analytics.*` | One key — controls data and event access       |
+| `storageKeys`       | `db.storage('name').*`  | **Many keys** — one per storage bucket you use           |
 
-## Installation
+Because you can have many storage buckets (avatars, documents, exports, …),
+`storageKeys` is an object where **you choose the name**. When you call a
+storage method you pick which bucket to use by that name.
+
+### Environment variables (recommended)
 
 ```bash
-npm install hydrousdb
-# or
-pnpm add hydrousdb
-# or
-yarn add hydrousdb
+# .env.local
+NEXT_PUBLIC_HYDROUS_URL=https://api.myapp.hydrous.app
+HYDROUS_AUTH_KEY=hk_auth_…
+HYDROUS_BUCKET_KEY=hk_bucket_…
+HYDROUS_STORAGE_MAIN=ssk_main_…
+HYDROUS_STORAGE_AVATARS=ssk_avatars_…
+HYDROUS_STORAGE_DOCS=ssk_docs_…
 ```
 
-> **Node.js ≥ 18** is required (uses native `fetch`). For Node 16/17, polyfill `fetch` with `node-fetch` or `undici`.
+```ts
+// lib/db.ts  (server-side only — never expose secret keys to the browser)
+import { createClient } from 'hydrousdb';
+
+export const db = createClient({
+  url:               process.env.NEXT_PUBLIC_HYDROUS_URL!,
+  authKey:           process.env.HYDROUS_AUTH_KEY!,
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+  storageKeys: {
+    main:      process.env.HYDROUS_STORAGE_MAIN!,
+    avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
+    documents: process.env.HYDROUS_STORAGE_DOCS!,
+  },
+});
+```
 
 ---
 
-## Key Concepts
+## 2. Auth
 
-### Two keys, one client
+### Sign Up
 
-The SDK separates two distinct credentials:
+```ts
+const { data, error } = await db.auth.signUp({
+  email:    'alice@example.com',
+  password: 'supersecret',
+  metadata: { plan: 'pro', referral: 'google' },
+});
+
+if (error) console.error(error.message);
+if (data)  console.log('New user:', data.user.id);
+```
+
+### Sign In
+
+```ts
+const { data, error } = await db.auth.signIn({
+  email:    'alice@example.com',
+  password: 'supersecret',
+});
+
+if (data) {
+  localStorage.setItem('token', data.accessToken);
+}
+```
 
-| Key | Config field | Used for |
-|-----|-------------|----------|
-| Auth key | `authKey` | All `/auth` routes — sign up, sign in, session management |
-| Security key | `securityKey` | All records and analytics routes — data access credential |
+### Sign Out
 
-### Bucket per call
+```ts
+await db.auth.signOut();
+localStorage.removeItem('token');
+```
 
-Unlike v1, `bucketKey` is **not** set on the client — it's passed as an option on every records and analytics call. This means a **single client instance can read and write to any number of buckets** without re-initialising.
+### Get current user
 
 ```ts
-const db = createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
+const { data: user } = await db.auth.getUser();
+console.log(user?.email);
+```
+
+### Refresh session
 
-// Same client, different buckets
-await db.records.insert({ values: { name: 'Alice' } }, { bucketKey: 'users' });
-await db.records.insert({ values: { order: '#1001' } }, { bucketKey: 'orders' });
-await db.analytics.count({ bucketKey: 'users' });
-await db.analytics.count({ bucketKey: 'orders' });
+```ts
+const { data: session } = await db.auth.refreshSession();
 ```
 
 ---
 
-## Quick Start
+## 3. Records
+
+### Insert
 
 ```ts
-import { createClient } from 'hydrousdb';
+// Single record
+const { data } = await db.records.insert('products', {
+  name:     'Widget Pro',
+  price:    49.99,
+  category: 'hardware',
+  inStock:  true,
+});
 
-const db = createClient({
-  authKey:     'your-auth-key',
-  securityKey: 'your-security-key',
+// Bulk insert
+const { data, count } = await db.records.insert('products', [
+  { name: 'Widget A', price: 9.99  },
+  { name: 'Widget B', price: 19.99 },
+]);
+console.log(`Inserted ${count} products`);
+```
+
+### Select (query)
+
+```ts
+import { eq, gt, inArray } from 'hydrousdb';
+
+const { data, count } = await db.records.select('products', {
+  where:   [eq('category', 'hardware'), gt('price', 10)],
+  orderBy: { field: 'price', direction: 'asc' },
+  limit:   20,
+  offset:  0,
+  select:  ['id', 'name', 'price'],  // return only these fields
 });
+```
 
-// Insert a record into the 'users' bucket
-const { data, meta } = await db.records.insert(
-  { values: { name: 'Alice', score: 99 }, queryableFields: ['name'] },
-  { bucketKey: 'users' }
-);
-console.log('Created record:', meta.id);
+### Get one by ID
 
-// Query records from the 'users' bucket
-const { data: records } = await db.records.query({
-  bucketKey: 'users',
-  filters: [{ field: 'score', op: '>=', value: 90 }],
-  limit: 20,
+```ts
+const { data: product } = await db.records.get('products', 'prod_abc123');
+```
+
+### Update
+
+```ts
+const { data } = await db.records.update('products', 'prod_abc123', {
+  price:   59.99,
+  inStock: false,
 });
+```
+
+### Delete
+
+```ts
+const { error } = await db.records.delete('products', 'prod_abc123');
+```
 
-// Auth — no bucketKey needed
-const { data: user, session } = await db.auth.signIn({
-  email: 'alice@example.com',
-  password: 'Str0ng@Pass!',
+---
+
+## 4. Analytics
+
+### Track an event
+
+```ts
+await db.analytics.track({
+  event:      'purchase_completed',
+  userId:     'user_abc123',
+  sessionId:  'sess_xyz',
+  properties: {
+    orderId:   'ord_001',
+    total:     99.99,
+    currency:  'USD',
+    itemCount: 3,
+  },
 });
+```
 
-// Analytics
-const { data: stats } = await db.analytics.count({ bucketKey: 'users' });
-console.log(stats.count);
+### Track many events at once
+
+```ts
+await db.analytics.trackBatch([
+  { event: 'page_view',     userId: 'u1', properties: { page: '/home' } },
+  { event: 'button_click',  userId: 'u1', properties: { button: 'buy' } },
+  { event: 'add_to_cart',   userId: 'u1', properties: { product: 'prod_abc' } },
+]);
+```
+
+### Query events
+
+```ts
+const { data } = await db.analytics.query({
+  event:  'purchase_completed',
+  from:   '2024-01-01',
+  to:     '2024-01-31',
+  limit:  500,
+});
+```
+
+---
+
+## 5. Storage
+
+### How storage keys work
+
+`db.storage` is a function — call it with the **name** of the key you configured:
+
+```ts
+db.storage('avatars')    // returns a ScopedStorageClient for your avatars bucket
+db.storage('documents')  // returns one for your documents bucket
+db.storage('main')       // returns one for your main bucket
+```
+
+You can cache the result if you use the same bucket a lot:
+
+```ts
+const avatarStore   = db.storage('avatars');
+const documentStore = db.storage('documents');
+
+await avatarStore.upload(file, { path: 'alice.jpg' });
+const list = await documentStore.list({ prefix: 'invoices/' });
 ```
 
 ---
 
-## Framework Guides
+### Upload a file with progress
+
+```ts
+const { data, error } = await db.storage('avatars').upload(file, {
+  path:      'users/alice.jpg',
+  overwrite: true,
+
+  onProgress: (p) => {
+    // p.stage          — 'pending' | 'compressing' | 'uploading' | 'done' | 'error'
+    // p.percent        — 0–100 integer
+    // p.bytesUploaded  — bytes sent so far
+    // p.totalBytes     — total size
+    // p.bytesPerSecond — current speed (null until first tick)
+    // p.eta            — estimated seconds remaining
+
+    console.log(`[${p.stage}] ${p.percent}% — ${p.bytesPerSecond} B/s — ETA ${p.eta}s`);
+  },
+});
 
-### Next.js (App Router)
+if (data) {
+  console.log('Path:', data.path);
+  console.log('Space saved by compression:', data.spaceSaved, 'bytes');
+}
+```
 
-**1. Create a shared client singleton**
+### Batch upload
+
+```ts
+const files = Array.from(fileInput.files);
+
+const { data } = await db.storage('documents').batchUpload(files, {
+  prefix:      'uploads/2024/',
+  overwrite:   false,
+  concurrency: 5,
+
+  onProgress: (p) => {
+    // p.index identifies WHICH file (0-based, same order as files array)
+    console.log(`File ${p.index} "${p.path}": ${p.stage} ${p.percent}%`);
+  },
+});
+
+console.log('Succeeded:', data!.succeeded.length);
+console.log('Failed:',    data!.failed.length);
+data!.failed.forEach(f => console.error(f.path, f.error));
+```
+
+### Download a file
+
+```ts
+const { data: buffer, error } = await db.storage('documents').download('reports/q1.pdf');
+
+if (buffer) {
+  // In a browser — trigger Save dialog
+  const blob = new Blob([buffer], { type: 'application/pdf' });
+  const url  = URL.createObjectURL(blob);
+  const a    = document.createElement('a');
+  a.href     = url;
+  a.download = 'q1.pdf';
+  a.click();
+  URL.revokeObjectURL(url);
+
+  // In Node — write to disk
+  // import { writeFileSync } from 'fs';
+  // writeFileSync('q1.pdf', Buffer.from(buffer));
+}
+```
+
+### List files
+
+```ts
+const { data } = await db.storage('documents').list({
+  prefix: 'invoices/',
+  limit:  50,
+});
+
+for (const item of data!.items) {
+  if (item.type === 'folder') console.log('📁', item.path);
+  else                        console.log('📄', item.path, item.size, 'bytes');
+}
+
+// Paginate
+if (data!.pagination.hasNextPage) {
+  const page2 = await db.storage('documents').list({
+    prefix: 'invoices/',
+    cursor: data!.pagination.nextCursor!,
+  });
+}
+```
+
+### Delete, move, copy
+
+```ts
+// Delete a single file
+await db.storage('avatars').deleteFile('users/old-photo.jpg');
+
+// Recursively delete a folder
+await db.storage('temp').deleteFolder('uploads/draft/');
+
+// Create a folder
+await db.storage('documents').createFolder('reports/2025/');
+
+// Move (rename) a file
+await db.storage('documents').move('drafts/report.pdf', 'published/report.pdf');
+
+// Copy a file (original kept)
+await db.storage('documents').copy('templates/invoice.pdf', 'invoices/inv-001.pdf');
+```
+
+### Signed URLs
+
+```ts
+// Generate a link that expires in 10 minutes
+const { data } = await db.storage('documents').signedUrl(
+  'contracts/nda.pdf',
+  { expiresIn: 600 }
+);
+
+console.log(data!.signedUrl);   // share this URL
+console.log(data!.expiresAt);   // ISO timestamp when it expires
+```
+
+### Upload raw text / JSON
+
+```ts
+// Great for saving generated content, configs, or processed data
+await db.storage('configs').uploadText(
+  'settings/app.json',
+  JSON.stringify({ theme: 'dark', language: 'en' }, null, 2),
+  { mimeType: 'application/json' }
+);
+```
+
+### Stats
+
+```ts
+const { data: stats } = await db.storage('main').stats();
+console.log('Files:',    stats!.totalFiles);
+console.log('Stored:',   stats!.totalSizeBytes, 'bytes');
+console.log('Saved:',    stats!.spaceSavedBytes, 'bytes via compression');
+console.log('Credits:',  stats!.creditsTotalUsed);
+```
+
+---
+
+## 6. Error Handling
+
+Every method returns `{ data, error }`. `error` is `null` on success.
+
+```ts
+const { data, error } = await db.storage('avatars').upload(file);
+
+if (error) {
+  console.error(error.message);  // human-readable
+  console.error(error.code);     // machine-readable e.g. 'QUOTA_EXCEEDED'
+  console.error(error.status);   // HTTP status (if applicable)
+}
+```
+
+### Catching thrown errors
+
+```ts
+import { isHydrousError } from 'hydrousdb';
+
+try {
+  await db.storage('avatars').upload(file);
+} catch (err) {
+  if (isHydrousError(err)) {
+    console.error(err.code, err.message);
+  }
+}
+```
+
+### Common error codes
+
+| Code                  | Meaning                                        |
+|-----------------------|------------------------------------------------|
+| `HTTP_ERROR`          | Non-2xx response from the server               |
+| `NETWORK_ERROR`       | Could not reach the server                     |
+| `QUOTA_EXCEEDED`      | Storage quota reached                          |
+| `FILE_TOO_LARGE`      | File exceeds the 50 MB per-file limit          |
+| `FILE_EXISTS`         | File exists and `overwrite` is false           |
+| `UPLOAD_ABORTED`      | Upload cancelled                               |
+| `UPLOAD_TIMEOUT`      | Upload timed out                               |
+| `UNKNOWN_STORAGE_KEY` | Key name not in your `storageKeys` config      |
+| `NO_SESSION`          | Auth operation requires a signed-in session    |
+
+---
+
+## 7. Real-World Examples — Next.js
+
+### Shared client (lib/db.ts)
 
 ```ts
 // lib/db.ts
 import { createClient } from 'hydrousdb';
 
 export const db = createClient({
-  authKey:     process.env.HYDROUS_AUTH_KEY!,
-  securityKey: process.env.HYDROUS_SECURITY_KEY!,
+  url:               process.env.NEXT_PUBLIC_HYDROUS_URL!,
+  authKey:           process.env.HYDROUS_AUTH_KEY!,
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+  storageKeys: {
+    avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
+    documents: process.env.HYDROUS_STORAGE_DOCS!,
+  },
 });
 ```
 
-**2. Use in a Server Component**
+---
+
+### Auth: Login page with session handling
+
+```tsx
+// app/login/page.tsx
+'use client';
+import { useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { db } from '@/lib/db';
+
+export default function LoginPage() {
+  const router = useRouter();
+  const [email,    setEmail]    = useState('');
+  const [password, setPassword] = useState('');
+  const [error,    setError]    = useState<string | null>(null);
+  const [loading,  setLoading]  = useState(false);
+
+  async function handleLogin(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    setError(null);
+
+    const { data, error } = await db.auth.signIn({ email, password });
+
+    if (error) {
+      setError(error.message);
+      setLoading(false);
+      return;
+    }
+
+    // Persist session
+    localStorage.setItem('hydrous_token', data!.accessToken);
+    router.push('/dashboard');
+  }
+
+  return (
+    <form onSubmit={handleLogin}>
+      <input value={email}    onChange={e => setEmail(e.target.value)}
+             type="email"    placeholder="Email" required />
+      <input value={password} onChange={e => setPassword(e.target.value)}
+             type="password" placeholder="Password" required />
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+      <button type="submit" disabled={loading}>
+        {loading ? 'Signing in…' : 'Sign In'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+### Records: Product listing with filters
 
 ```tsx
 // app/products/page.tsx
 import { db } from '@/lib/db';
+import { eq } from 'hydrousdb';
+
+type Product = { id: string; name: string; price: number; inStock: boolean };
 
 export default async function ProductsPage() {
-  const { data: products } = await db.records.query({
-    bucketKey: 'products',
-    filters: [{ field: 'category', op: '==', value: 'shoes' }],
-    limit: 24,
-    sortOrder: 'desc',
+  const { data: products, error } = await db.records.select<Product>('products', {
+    where:   eq('inStock', true),
+    orderBy: { field: 'price', direction: 'asc' },
+    limit:   24,
   });
 
+  if (error) return <p>Error: {error.message}</p>;
+
   return (
     <ul>
       {products.map(p => (
-        <li key={p.id}>{String(p.name)}</li>
+        <li key={p.id}>
+          {p.name} — ${p.price}
+        </li>
       ))}
     </ul>
   );
 }
 ```
 
-**3. Use in a Route Handler**
+---
+
+### Storage: Avatar upload with live progress bar
 
-```ts
-// app/api/records/route.ts
-import { NextRequest, NextResponse } from 'next/server';
+```tsx
+// components/AvatarUploader.tsx
+'use client';
+import { useState } from 'react';
 import { db } from '@/lib/db';
-import { HydrousError } from 'hydrousdb';
-
-export async function POST(req: NextRequest) {
-  try {
-    const body = await req.json();
-    const result = await db.records.insert(
-      { values: body, queryableFields: ['email', 'name'] },
-      { bucketKey: 'users' }
+import type { UploadProgress } from 'hydrousdb';
+
+export default function AvatarUploader({ userId }: { userId: string }) {
+  const [progress,  setProgress]  = useState<UploadProgress | null>(null);
+  const [avatarUrl, setAvatarUrl] = useState<string | null>(null);
+  const [error,     setError]     = useState<string | null>(null);
+
+  async function handleFileChange(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0];
+    if (!file) return;
+
+    setError(null);
+    setProgress(null);
+
+    const { data, error } = await db.storage('avatars').upload(file, {
+      path:      `users/${userId}/avatar.jpg`,
+      overwrite: true,
+
+      onProgress: (p) => setProgress(p),
+    });
+
+    if (error) { setError(error.message); return; }
+
+    // Generate a signed URL to display the uploaded avatar
+    const { data: urlData } = await db.storage('avatars').signedUrl(
+      `users/${userId}/avatar.jpg`,
+      { expiresIn: 3600 }
     );
-    return NextResponse.json(result, { status: 201 });
-  } catch (err) {
-    if (err instanceof HydrousError) {
-      return NextResponse.json({ error: err.message }, { status: err.status });
-    }
-    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
+    setAvatarUrl(urlData?.signedUrl ?? null);
+    setProgress(null);
   }
+
+  return (
+    <div>
+      <input type="file" accept="image/*" onChange={handleFileChange} />
+
+      {progress && (
+        <div>
+          <p>{progress.stage} — {progress.percent}%</p>
+          <progress value={progress.percent} max={100} />
+          {progress.bytesPerSecond && (
+            <p>
+              {(progress.bytesPerSecond / 1024).toFixed(1)} KB/s
+              {progress.eta != null && ` · ${progress.eta}s remaining`}
+            </p>
+          )}
+        </div>
+      )}
+
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+      {avatarUrl && <img src={avatarUrl} alt="Avatar" width={100} />}
+    </div>
+  );
 }
 ```
 
-**4. Auth middleware example**
+---
+
+### Storage: Secure file download link (API route)
 
 ```ts
-// middleware.ts
+// app/api/download/route.ts
 import { NextRequest, NextResponse } from 'next/server';
 import { db } from '@/lib/db';
 
-export async function middleware(req: NextRequest) {
-  const sessionId = req.cookies.get('sessionId')?.value;
-  if (!sessionId) return NextResponse.redirect(new URL('/login', req.url));
+export async function GET(req: NextRequest) {
+  const filePath = req.nextUrl.searchParams.get('file');
+  if (!filePath) return NextResponse.json({ error: 'file param required' }, { status: 400 });
 
-  try {
-    await db.auth.validateSession(sessionId);
-    return NextResponse.next();
-  } catch {
-    return NextResponse.redirect(new URL('/login', req.url));
-  }
-}
+  // Generate a short-lived signed URL (2 minutes)
+  const { data, error } = await db.storage('documents').signedUrl(filePath, {
+    expiresIn: 120,
+  });
 
-export const config = { matcher: ['/dashboard/:path*'] };
-```
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
 
-**5. Environment variables**
+  return NextResponse.json({ url: data!.signedUrl, expiresAt: data!.expiresAt });
+}
+```
 
-```env
-# .env.local
-HYDROUS_AUTH_KEY=your-auth-key
-HYDROUS_SECURITY_KEY=your-security-key
+```tsx
+// Usage in a component:
+// const res  = await fetch(`/api/download?file=contracts/nda.pdf`);
+// const { url } = await res.json();
+// window.open(url, '_blank');
 ```
 
 ---
 
-### Next.js (Pages Router)
+### Analytics: Page-view tracking
 
-```ts
-// pages/api/records.ts
-import type { NextApiRequest, NextApiResponse } from 'next';
-import { createClient, HydrousError } from 'hydrousdb';
+```tsx
+// components/Analytics.tsx
+'use client';
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { db } from '@/lib/db';
 
-const db = createClient({
-  authKey:     process.env.HYDROUS_AUTH_KEY!,
-  securityKey: process.env.HYDROUS_SECURITY_KEY!,
-});
+export default function Analytics() {
+  const pathname = usePathname();
 
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  if (req.method === 'GET') {
-    try {
-      const result = await db.records.query({ bucketKey: 'orders', limit: 50 });
-      return res.status(200).json(result);
-    } catch (err) {
-      if (err instanceof HydrousError) return res.status(err.status).json({ error: err.message });
-      return res.status(500).json({ error: 'Internal Server Error' });
-    }
-  }
-  res.setHeader('Allow', ['GET']);
-  res.status(405).end();
+  useEffect(() => {
+    db.analytics.track({
+      event:      'page_view',
+      properties: {
+        path:      pathname,
+        referrer:  document.referrer,
+        userAgent: navigator.userAgent,
+      },
+    });
+  }, [pathname]);
+
+  return null;
 }
 ```
 
----
+```tsx
+// app/layout.tsx — add <Analytics /> inside <body>
+import Analytics from '@/components/Analytics';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <Analytics />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
 
-### Vue 3 / Nuxt 3
+---
 
-**Nuxt 3 — plugin**
+### Records: Server Action — create a product
 
 ```ts
-// plugins/hydrousdb.ts
-import { createClient } from 'hydrousdb';
+// app/products/actions.ts
+'use server';
+import { db } from '@/lib/db';
+import { revalidatePath } from 'next/cache';
 
-export default defineNuxtPlugin(() => {
-  const config = useRuntimeConfig();
+export async function createProduct(formData: FormData) {
+  const name     = formData.get('name')     as string;
+  const price    = Number(formData.get('price'));
+  const category = formData.get('category') as string;
 
-  const db = createClient({
-    authKey:     config.hydrousAuthKey as string,
-    securityKey: config.hydrousSecurityKey as string,
+  const { data, error } = await db.records.insert('products', {
+    name, price, category, inStock: true,
   });
 
-  return { provide: { db } };
-});
-```
+  if (error) throw new Error(error.message);
 
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  runtimeConfig: {
-    hydrousAuthKey:     '',  // NUXT_HYDROUS_AUTH_KEY
-    hydrousSecurityKey: '',  // NUXT_HYDROUS_SECURITY_KEY
-  },
-});
+  revalidatePath('/products');
+  return data[0];
+}
 ```
 
-**Usage in a component**
-
-```vue
-<script setup lang="ts">
-const { $db } = useNuxtApp();
-
-const { data: records, pending } = await useAsyncData('records', () =>
-  $db.records.query({ bucketKey: 'products', limit: 20 })
-);
-</script>
+---
 
-<template>
-  <div v-if="pending">Loading…</div>
-  <ul v-else>
-    <li v-for="r in records?.data" :key="r.id">{{ r.name }}</li>
-  </ul>
-</template>
-```
+## 8. Real-World Examples — Vue 3
 
-**Vue 3 standalone — composable**
+### Shared client (src/lib/db.ts)
 
 ```ts
-// composables/useHydrous.ts
+// src/lib/db.ts
 import { createClient } from 'hydrousdb';
 
-const db = createClient({
-  authKey:     import.meta.env.VITE_HYDROUS_AUTH_KEY,
-  securityKey: import.meta.env.VITE_HYDROUS_SECURITY_KEY,
+export const db = createClient({
+  url:               import.meta.env.VITE_HYDROUS_URL,
+  authKey:           import.meta.env.VITE_HYDROUS_AUTH_KEY,
+  bucketSecurityKey: import.meta.env.VITE_HYDROUS_BUCKET_KEY,
+  storageKeys: {
+    avatars:   import.meta.env.VITE_HYDROUS_STORAGE_AVATARS,
+    documents: import.meta.env.VITE_HYDROUS_STORAGE_DOCS,
+  },
 });
-
-export function useHydrous() {
-  return db;
-}
 ```
 
 ---
 
-### React (Vite / CRA)
+### Auth: Login composable
 
-```tsx
-// src/hooks/useRecords.ts
-import { useEffect, useState } from 'react';
-import { createClient, HydrousRecord, HydrousError } from 'hydrousdb';
+```ts
+// composables/useAuth.ts
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+import { db } from '@/lib/db';
 
-const db = createClient({
-  authKey:     import.meta.env.VITE_HYDROUS_AUTH_KEY,
-  securityKey: import.meta.env.VITE_HYDROUS_SECURITY_KEY,
-});
+export function useAuth() {
+  const user    = ref(null);
+  const loading = ref(false);
+  const error   = ref<string | null>(null);
+  const router  = useRouter();
 
-export function useRecords(bucketKey: string, limit = 20) {
-  const [records, setRecords] = useState<HydrousRecord[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError]     = useState<string | null>(null);
+  async function login(email: string, password: string) {
+    loading.value = true;
+    error.value   = null;
 
-  useEffect(() => {
-    const controller = new AbortController();
+    const { data, error: err } = await db.auth.signIn({ email, password });
+
+    if (err) {
+      error.value = err.message;
+    } else {
+      user.value = data!.user as any;
+      localStorage.setItem('token', data!.accessToken);
+      router.push('/dashboard');
+    }
 
-    db.records.query({ bucketKey, limit }, { signal: controller.signal })
-      .then(r  => setRecords(r.data))
-      .catch(e => { if (!(e instanceof DOMException)) setError(String(e)); })
-      .finally(() => setLoading(false));
+    loading.value = false;
+  }
 
-    return () => controller.abort();
-  }, [bucketKey, limit]);
+  async function logout() {
+    await db.auth.signOut();
+    user.value = null;
+    localStorage.removeItem('token');
+    router.push('/login');
+  }
 
-  return { records, loading, error };
+  return { user, loading, error, login, logout };
 }
 ```
 
 ---
 
-### Node.js / Express
+### Storage: File upload with progress
 
-```ts
-// server.ts
-import express from 'express';
-import { createClient, HydrousError } from 'hydrousdb';
+```vue
+<!-- components/FileUploader.vue -->
+<script setup lang="ts">
+import { ref } from 'vue';
+import { db } from '@/lib/db';
+import type { UploadProgress } from 'hydrousdb';
+
+const progress = ref<UploadProgress | null>(null);
+const done     = ref(false);
+const error    = ref<string | null>(null);
+
+async function onFileChange(event: Event) {
+  const file = (event.target as HTMLInputElement).files?.[0];
+  if (!file) return;
+
+  done.value     = false;
+  error.value    = null;
+  progress.value = null;
+
+  const { data, error: err } = await db.storage('documents').upload(file, {
+    path:      `uploads/${Date.now()}-${file.name}`,
+    overwrite: false,
+    onProgress: (p) => {
+      progress.value = p;
+    },
+  });
 
-const db  = createClient({
-  authKey:     process.env.HYDROUS_AUTH_KEY!,
-  securityKey: process.env.HYDROUS_SECURITY_KEY!,
-});
-const app = express();
-app.use(express.json());
-
-app.get('/orders', async (req, res) => {
-  try {
-    const result = await db.records.query({ bucketKey: 'orders', limit: 50 });
-    res.json(result);
-  } catch (err) {
-    if (err instanceof HydrousError) return res.status(err.status).json({ error: err.message });
-    res.status(500).json({ error: 'Internal Server Error' });
+  if (err) {
+    error.value = err.message;
+  } else {
+    done.value     = true;
+    progress.value = null;
+    console.log('Uploaded to', data!.path);
   }
-});
+}
+</script>
 
-app.listen(3000, () => console.log('Listening on :3000'));
+<template>
+  <div>
+    <input type="file" @change="onFileChange" />
+
+    <div v-if="progress">
+      <p>{{ progress.stage }} — {{ progress.percent }}%</p>
+      <div class="progress-bar">
+        <div class="fill" :style="{ width: progress.percent + '%' }" />
+      </div>
+      <p v-if="progress.bytesPerSecond">
+        {{ (progress.bytesPerSecond / 1024).toFixed(1) }} KB/s
+        <span v-if="progress.eta != null"> · {{ progress.eta }}s left</span>
+      </p>
+    </div>
+
+    <p v-if="done" style="color: green">✓ Upload complete!</p>
+    <p v-if="error" style="color: red">{{ error }}</p>
+  </div>
+</template>
 ```
 
 ---
 
-## API Reference
+### Records: Data table with pagination
 
-### `createClient`
+```vue
+<!-- components/ProductTable.vue -->
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import { db } from '@/lib/db';
+import { eq } from 'hydrousdb';
 
-```ts
-import { createClient } from 'hydrousdb';
+type Product = { id: string; name: string; price: number; inStock: boolean };
 
-const db = createClient({
-  authKey:     string,  // required — your HydrousDB auth key (for /auth routes)
-  securityKey: string,  // required — your HydrousDB security key (for records & analytics)
-  baseUrl?:    string,  // override API base URL
-  timeout?:    number,  // request timeout in ms (default: 30_000)
-  retries?:    number,  // retries on network/5xx errors (default: 2)
-});
-```
+const products = ref<Product[]>([]);
+const total    = ref(0);
+const page     = ref(1);
+const limit    = 10;
+
+async function loadPage(p: number) {
+  const { data, count, error } = await db.records.select<Product>('products', {
+    where:   eq('inStock', true),
+    orderBy: { field: 'name', direction: 'asc' },
+    limit,
+    offset:  (p - 1) * limit,
+  });
 
-> **Note:** `bucketKey` is no longer part of the client config. It is passed as an option on each individual records and analytics call.
+  if (error) { console.error(error.message); return; }
+  products.value = data;
+  total.value    = count;
+  page.value     = p;
+}
+
+onMounted(() => loadPage(1));
+</script>
+
+<template>
+  <table>
+    <tr v-for="p in products" :key="p.id">
+      <td>{{ p.name }}</td>
+      <td>${{ p.price }}</td>
+      <td>{{ p.inStock ? 'In Stock' : 'Out' }}</td>
+    </tr>
+  </table>
+
+  <div class="pagination">
+    <button :disabled="page === 1"   @click="loadPage(page - 1)">← Prev</button>
+    <span>Page {{ page }} of {{ Math.ceil(total / limit) }}</span>
+    <button :disabled="page * limit >= total" @click="loadPage(page + 1)">Next →</button>
+  </div>
+</template>
+```
 
 ---
 
-### Records
+### Vue: Batch file upload with per-file progress
 
-All methods live on `db.records`. Every method requires a `bucketKey` option.
+```vue
+<!-- components/BatchUploader.vue -->
+<script setup lang="ts">
+import { ref } from 'vue';
+import { db } from '@/lib/db';
+import type { UploadProgress } from 'hydrousdb';
 
-| Method | Description |
-|---|---|
-| `get(recordId, { bucketKey, ...opts })` | Fetch a single record |
-| `getSnapshot(recordId, generation, { bucketKey, ...opts })` | Fetch a historical version |
-| `query({ bucketKey, ...opts })` | Query a collection with filters / pagination |
-| `queryAll({ bucketKey, ...opts })` | Fetch all pages automatically |
-| `insert(payload, { bucketKey, ...opts })` | Create a new record |
-| `update(payload, { bucketKey, ...opts })` | Update an existing record |
-| `delete(recordId, { bucketKey, ...opts })` | Delete a record |
-| `exists(recordId, { bucketKey, ...opts })` | HEAD check — returns metadata or `null` |
-| `batchInsert(payload, { bucketKey, ...opts })` | Insert up to 500 records |
-| `batchUpdate(payload, { bucketKey, ...opts })` | Update up to 500 records |
-| `batchDelete(payload, { bucketKey, ...opts })` | Delete up to 500 records |
+type FileState = { name: string; percent: number; stage: string; done: boolean; error?: string };
 
-#### `db.records.get(recordId, options)`
+const fileStates = ref<FileState[]>([]);
 
-```ts
-const { data, history } = await db.records.get('rec_abc', {
-  bucketKey:   'users',
-  showHistory: true,
-});
-```
+async function onFilesChange(event: Event) {
+  const files = Array.from((event.target as HTMLInputElement).files ?? []);
+  if (!files.length) return;
 
-#### `db.records.query(options)`
+  fileStates.value = files.map(f => ({ name: f.name, percent: 0, stage: 'pending', done: false }));
 
-```ts
-const { data, meta } = await db.records.query({
-  bucketKey:  'orders',
-  filters:    [{ field: 'status', op: '==', value: 'active' }],
-  timeScope:  '30d',
-  sortOrder:  'desc',
-  limit:      50,
-  cursor:     meta.nextCursor ?? undefined,
-  fields:     'id,name,status',
-});
+  await db.storage('documents').batchUpload(files, {
+    prefix: 'batch-uploads/',
+
+    onProgress: (p: UploadProgress) => {
+      const s = fileStates.value[p.index];
+      if (!s) return;
+      s.percent = p.percent;
+      s.stage   = p.stage;
+      s.done    = p.stage === 'done';
+      s.error   = p.error;
+    },
+  });
+}
+</script>
+
+<template>
+  <input type="file" multiple @change="onFilesChange" />
+
+  <ul>
+    <li v-for="(f, i) in fileStates" :key="i">
+      <span>{{ f.name }}</span>
+      <progress :value="f.percent" max="100" />
+      <span :style="{ color: f.done ? 'green' : f.error ? 'red' : 'inherit' }">
+        {{ f.done ? '✓' : f.error ?? f.stage + ' ' + f.percent + '%' }}
+      </span>
+    </li>
+  </ul>
+</template>
 ```
 
-**Filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`  
-**Max 3 filters per query.**
+---
+
+## 9. Real-World Examples — SvelteKit
 
-#### `db.records.insert(payload, options)`
+### Shared client
 
 ```ts
-const { data, meta } = await db.records.insert(
-  {
-    values:          { name: 'Alice', role: 'admin', score: 100 },
-    queryableFields: ['name', 'role'],
-    userEmail:       'system@example.com',
+// src/lib/db.ts
+import { createClient } from 'hydrousdb';
+import {
+  PUBLIC_HYDROUS_URL,
+} from '$env/static/public';
+import {
+  HYDROUS_AUTH_KEY,
+  HYDROUS_BUCKET_KEY,
+  HYDROUS_STORAGE_AVATARS,
+  HYDROUS_STORAGE_DOCS,
+} from '$env/static/private';
+
+export const db = createClient({
+  url:               PUBLIC_HYDROUS_URL,
+  authKey:           HYDROUS_AUTH_KEY,
+  bucketSecurityKey: HYDROUS_BUCKET_KEY,
+  storageKeys: {
+    avatars:   HYDROUS_STORAGE_AVATARS,
+    documents: HYDROUS_STORAGE_DOCS,
   },
-  { bucketKey: 'users' }
-);
-// meta.id — the new record's ID
+});
 ```
 
-#### `db.records.update(payload, options)`
+### Server route — fetch records
 
 ```ts
-await db.records.update(
-  {
-    recordId:             'rec_abc',
-    values:               { score: 150 },
-    track_record_history: true,
-    reason:               'Manual score adjustment',
-  },
-  { bucketKey: 'users' }
-);
+// src/routes/api/products/+server.ts
+import { json } from '@sveltejs/kit';
+import { db } from '$lib/db';
+import { eq } from 'hydrousdb';
+
+export async function GET() {
+  const { data, error } = await db.records.select('products', {
+    where:   eq('inStock', true),
+    orderBy: { field: 'price', direction: 'asc' },
+    limit:   50,
+  });
+
+  if (error) return json({ error: error.message }, { status: 500 });
+  return json(data);
+}
 ```
 
-#### `db.records.batchInsert(payload, options)`
+### Page load — server-side
 
 ```ts
-const result = await db.records.batchInsert(
-  {
-    records:         [{ name: 'Alice', score: 99 }, { name: 'Bob', score: 82 }],
-    queryableFields: ['name'],
-    userEmail:       'import@example.com',
-  },
-  { bucketKey: 'users' }
-);
-// result.meta.failed — number of records that failed
+// src/routes/products/+page.server.ts
+import { db } from '$lib/db';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async () => {
+  const { data: products, error } = await db.records.select('products', {
+    limit: 24,
+    orderBy: { field: 'createdAt', direction: 'desc' },
+  });
+
+  if (error) throw error;
+  return { products };
+};
 ```
 
----
+### File upload component
 
-### Auth
-
-All methods live on `db.auth`. Auth routes use `authKey` and do **not** require a `bucketKey`.
-
-| Method | Description |
-|---|---|
-| `signUp(payload, opts?)` | Register a new user |
-| `signIn(payload, opts?)` | Authenticate with email + password |
-| `signOut(payload, opts?)` | Revoke session(s) |
-| `validateSession(sessionId, opts?)` | Verify a session is valid |
-| `refreshSession(refreshToken, opts?)` | Rotate session using refresh token |
-| `getUser(userId, opts?)` | Fetch user by ID |
-| `listUsers(opts?)` | Paginated user list |
-| `listAllUsers(opts?)` | All users (auto-paginates) |
-| `updateUser(payload, opts?)` | Update user profile |
-| `deleteUser(userId, opts?)` | Soft-delete a user |
-| `changePassword(payload, opts?)` | Change password (requires old password) |
-| `requestPasswordReset(payload, opts?)` | Trigger reset email |
-| `confirmPasswordReset(payload, opts?)` | Confirm reset with token |
-| `requestEmailVerification(payload, opts?)` | Trigger verification email |
-| `confirmEmailVerification(payload, opts?)` | Confirm email with token |
-| `lockAccount(payload, opts?)` | Lock account for a duration |
-| `unlockAccount(userId, opts?)` | Unlock account |
-
-#### Auth flow example
-
-```ts
-// 1. Sign up
-const { data: user, session } = await db.auth.signUp({
-  email:    'alice@example.com',
-  password: 'Str0ng@Pass!',
-  fullName: 'Alice Smith',
-});
+```svelte
+<!-- src/lib/components/Uploader.svelte -->
+<script lang="ts">
+  import { db } from '$lib/db';
+  import type { UploadProgress } from 'hydrousdb';
 
-// 2. Store session tokens
-const { sessionId, refreshToken, expiresAt } = session;
+  let progress: UploadProgress | null = null;
+  let uploadedPath = '';
+  let errorMsg = '';
 
-// 3. On each request, validate the session
-const { data: currentUser } = await db.auth.validateSession(sessionId);
+  async function handleFile(event: Event) {
+    const file = (event.target as HTMLInputElement).files?.[0];
+    if (!file) return;
 
-// 4. Before session expires, refresh it
-const { session: newSession } = await db.auth.refreshSession(refreshToken);
+    errorMsg     = '';
+    uploadedPath = '';
+    progress     = null;
 
-// 5. Sign out
-await db.auth.signOut({ sessionId });
-```
+    const { data, error } = await db.storage('documents').upload(file, {
+      path:       `uploads/${file.name}`,
+      onProgress: (p) => { progress = p; },
+    });
 
----
+    if (error) {
+      errorMsg = error.message;
+    } else {
+      uploadedPath = data!.path;
+      progress     = null;
+    }
+  }
+</script>
 
-### Analytics
+<input type="file" on:change={handleFile} />
 
-All methods live on `db.analytics`. Every method requires a `bucketKey` option.
+{#if progress}
+  <p>{progress.stage} — {progress.percent}%</p>
+  <progress value={progress.percent} max="100" />
+{/if}
 
-| Method | Server `queryType` | Description |
-|---|---|---|
-| `count({ bucketKey, ...opts })` | `"count"` | Total record count |
-| `distribution(field, { bucketKey, ...opts })` | `"distribution"` | Value histogram for a field |
-| `sum(field, { bucketKey, ...opts })` | `"sum"` | Sum a numeric field, with optional group-by |
-| `timeSeries({ bucketKey, ...opts })` | `"timeSeries"` | Record count over time |
-| `fieldTimeSeries(field, { bucketKey, ...opts })` | `"fieldTimeSeries"` | Numeric field aggregated over time |
-| `topN(field, n, { bucketKey, ...opts })` | `"topN"` | Top N field values by frequency |
-| `stats(field, { bucketKey, ...opts })` | `"stats"` | min/max/avg/stddev/p50/p90/p99 |
-| `records({ bucketKey, ...opts })` | `"records"` | Filtered + paginated raw records |
-| `multiMetric(metrics, { bucketKey, ...opts })` | `"multiMetric"` | Multiple aggregations in one call |
-| `storageStats({ bucketKey, ...opts })` | `"storageStats"` | Bucket storage usage |
-| `crossBucket({ bucketKey, bucketKeys, ...opts })` | `"crossBucket"` | Compare metric across buckets |
-| `query(payload, { bucketKey, ...opts })` | any | Raw query — full control |
+{#if uploadedPath}
+  <p>✓ Saved at: {uploadedPath}</p>
+{/if}
 
-#### Date ranges
+{#if errorMsg}
+  <p style="color:red">{errorMsg}</p>
+{/if}
+```
+
+---
 
-All analytics methods accept a `dateRange` option:
+## 10. Real-World Examples — Express / Node API
+
+### Setup
 
 ```ts
-const dateRange = { startDate: '2025-01-01', endDate: '2025-12-31' };
-// Or scope to a year / month
-const dateRange = { year: '2025', month: '03' };
+// src/db.ts
+import { createClient } from 'hydrousdb';
+import 'dotenv/config';
+
+export const db = createClient({
+  url:               process.env.HYDROUS_URL!,
+  authKey:           process.env.HYDROUS_AUTH_KEY!,
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+  storageKeys: {
+    main:      process.env.HYDROUS_STORAGE_MAIN!,
+    exports:   process.env.HYDROUS_STORAGE_EXPORTS!,
+  },
+});
 ```
 
-#### Examples
+### Upload from a file buffer (Node)
 
 ```ts
-// Total records
-const { data } = await db.analytics.count({ bucketKey: 'orders' });
-console.log(data.count);
+// routes/upload.ts
+import express from 'express';
+import multer  from 'multer';
+import { db }  from '../db';
 
-// Status breakdown
-const { data } = await db.analytics.distribution('status', { bucketKey: 'orders' });
-// [{ value: 'active', count: 80 }, { value: 'archived', count: 20 }]
+const router  = express.Router();
+const upload  = multer({ storage: multer.memoryStorage() });
 
-// Monthly revenue for Q1
-const { data } = await db.analytics.sum('amount', {
-  bucketKey:  'orders',
-  groupBy:    'region',
-  dateRange:  { startDate: '2025-01-01', endDate: '2025-03-31' },
-});
+router.post('/upload', upload.single('file'), async (req, res) => {
+  if (!req.file) return res.status(400).json({ error: 'No file' });
 
-// Daily signups this week
-const { data } = await db.analytics.timeSeries({
-  bucketKey:   'users',
-  granularity: 'day',
-  dateRange:   { startDate: '2025-03-01' },
-});
+  const { data, error } = await db.storage('main').upload(
+    req.file.buffer,
+    {
+      path:     `uploads/${Date.now()}-${req.file.originalname}`,
+      overwrite: false,
+    }
+  );
 
-// Score percentiles
-const { data } = await db.analytics.stats('score', { bucketKey: 'users' });
-console.log(data.avg, data.p90, data.p99);
-
-// Top 5 countries
-const { data } = await db.analytics.topN('country', 5, { bucketKey: 'users' });
-
-// Dashboard stats — one round-trip for multiple metrics
-const { data } = await db.analytics.multiMetric(
-  [
-    { name: 'totalRevenue', field: 'amount', aggregation: 'sum' },
-    { name: 'avgScore',     field: 'score',  aggregation: 'avg' },
-    { name: 'userCount',    field: 'userId', aggregation: 'count' },
-  ],
-  { bucketKey: 'orders' }
-);
-console.log(data.totalRevenue, data.avgScore);
-
-// Storage usage
-const { data } = await db.analytics.storageStats({ bucketKey: 'orders' });
-console.log(data.totalRecords, data.totalBytes);
-
-// Cross-bucket revenue comparison
-const { data } = await db.analytics.crossBucket({
-  bucketKey:   'sales-2025',
-  bucketKeys:  ['sales-2024', 'sales-2025'],
-  field:       'amount',
-  aggregation: 'sum',
+  if (error) return res.status(500).json({ error: error.message });
+  res.json({ path: data!.path, size: data!.storedSize });
 });
 
-// Raw records with filters
-const { data } = await db.analytics.records({
-  bucketKey:    'users',
-  filters:      [{ field: 'role', op: '==', value: 'admin' }],
-  selectFields: ['email', 'createdAt'],
-  limit:        50,
-});
-console.log(data.data, data.hasMore);
+export default router;
 ```
 
----
-
-## Error Handling
+### Save JSON reports to storage
 
 ```ts
-import { HydrousError, HydrousNetworkError, HydrousTimeoutError } from 'hydrousdb';
+// jobs/generateReport.ts
+import { db } from '../db';
 
-try {
-  await db.records.get('rec_does_not_exist', { bucketKey: 'users' });
-} catch (err) {
-  if (err instanceof HydrousError) {
-    console.error(err.message);   // human-readable message
-    console.error(err.status);    // HTTP status code (e.g. 404)
-    console.error(err.code);      // machine-readable code (e.g. 'NOT_FOUND')
-    console.error(err.details);   // validation error details array
-    console.error(err.requestId); // server request ID for support
-  } else if (err instanceof HydrousTimeoutError) {
-    console.error('Request timed out');
-  } else if (err instanceof HydrousNetworkError) {
-    console.error('Network failure:', err.cause);
-  }
-}
-```
+export async function generateMonthlyReport(month: string) {
+  // 1. Fetch data
+  const { data: orders } = await db.records.select('orders', {
+    where: { field: 'month', operator: 'eq', value: month },
+  });
 
----
+  // 2. Build report
+  const report = {
+    month,
+    generatedAt: new Date().toISOString(),
+    totalOrders: orders.length,
+    totalRevenue: orders.reduce((sum: number, o: any) => sum + o.total, 0),
+    orders,
+  };
+
+  // 3. Save to storage
+  const { data, error } = await db.storage('exports').uploadText(
+    `reports/${month}.json`,
+    JSON.stringify(report, null, 2),
+    { mimeType: 'application/json', overwrite: true }
+  );
+
+  if (error) throw new Error(`Failed to save report: ${error.message}`);
 
-## Pagination
+  // 4. Track the event
+  await db.analytics.track({
+    event:      'report_generated',
+    properties: { month, totalOrders: report.totalOrders },
+  });
+
+  return data!.path;
+}
+```
 
-HydrousDB uses opaque cursor strings for pagination.
+### Batch delete old records
 
 ```ts
-// Manual pagination
-let cursor: string | null = null;
+// scripts/cleanup.ts
+import { db } from '../db';
+import { lt } from 'hydrousdb';
+
+async function cleanupOldSessions() {
+  const cutoff = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
 
-do {
-  const { data, meta } = await db.records.query({
-    bucketKey: 'orders',
-    limit:     100,
-    cursor:    cursor ?? undefined,
+  // Fetch old sessions
+  const { data: old } = await db.records.select('sessions', {
+    where: lt('createdAt', cutoff),
+    limit: 500,
   });
 
-  processBatch(data);
-  cursor = meta.nextCursor;
-} while (cursor);
+  if (!old.length) { console.log('Nothing to clean up'); return; }
 
-// — OR — let the SDK handle it
-const allRecords = await db.records.queryAll({
-  bucketKey: 'orders',
-  filters:   [{ field: 'status', op: '==', value: 'active' }],
-});
+  // Delete each one
+  await Promise.all(old.map((s: any) => db.records.delete('sessions', s.id)));
+  console.log(`Deleted ${old.length} expired sessions`);
+}
+
+cleanupOldSessions();
 ```
 
 ---
 
-## TypeScript
+## 11. TypeScript Types Reference
 
-All types are exported from the root package:
+### `HydrousConfig`
 
 ```ts
-import type {
-  HydrousRecord,
-  QueryOptions,
-  InsertRecordPayload,
-  AuthUser,
-  SessionInfo,
-  HydrousConfig,
-  BucketOptions,
-  Filter,
-} from 'hydrousdb';
+interface HydrousConfig {
+  url:               string;
+  authKey:           string;       // one key for auth
+  bucketSecurityKey: string;       // one key for records + analytics
+  storageKeys:       Record<string, string>;  // many named keys for storage
+  timeout?:          number;       // ms, default 30000
+}
 ```
 
-Use the generic `query<T>` overload to type your records:
+### `UploadProgress`
 
 ```ts
-interface Product {
-  name:     string;
-  price:    number;
-  category: string;
+interface UploadProgress {
+  index:          number;          // 0-based file index
+  total:          number;          // total files in this operation
+  path:           string;          // destination path
+  stage:          UploadStage;     // 'pending'|'compressing'|'uploading'|'done'|'error'
+  bytesUploaded:  number;
+  totalBytes:     number;
+  percent:        number;          // 0–100
+  bytesPerSecond: number | null;   // null until speed is calculable
+  eta:            number | null;   // seconds remaining, null until speed known
+  result?:        UploadResult;    // populated when stage === 'done'
+  error?:         string;          // populated when stage === 'error'
+  code?:          string;
 }
-
-const { data } = await db.records.query<Product>({
-  bucketKey: 'products',
-  filters:   [{ field: 'category', op: '==', value: 'shoes' }],
-});
-
-// data is (Product & HydrousRecord)[]
-console.log(data[0].name, data[0].price);
 ```
 
----
-
-## Migration from v1
-
-v2 introduces two breaking changes:
-
-### 1. `bucketKey` moves from `createClient` to per-call options
+### `UploadResult`
 
 ```ts
-// v1
-const db = createClient({ authKey: 'ak_...', bucketKey: 'users' });
-await db.records.query({ limit: 50 });
-
-// v2
-const db = createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
-await db.records.query({ bucketKey: 'users', limit: 50 });
+interface UploadResult {
+  path:         string;
+  compressed:   boolean;
+  originalSize: number;
+  storedSize:   number;
+  spaceSaved:   number;
+  mimeType:     string;
+}
 ```
 
-### 2. `securityKey` replaces the implicit credential
-
-In v1 the SDK incorrectly used `bucketKey` as both the bucket identifier and the security credential in the URL. v2 adds an explicit `securityKey` that maps to the server's `:key` parameter.
+### `StorageItem`
 
 ```ts
-// v1 (broken — used bucketKey as both segments)
-createClient({ authKey: 'ak_...', bucketKey: 'users' });
-// → /api/users/users  ❌
-
-// v2 (correct)
-createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
-// → /api/users/sk_...  ✅  (bucketKey passed per-call)
+interface StorageItem {
+  name:          string;
+  path:          string;
+  type:          'file' | 'folder';
+  size?:         number | null;
+  mimeType?:     string | null;
+  isCompressed?: boolean;
+  updatedAt?:    string | null;
+}
 ```
 
-**Quick migration checklist:**
-1. Add `securityKey` to your `createClient` call
-2. Remove `bucketKey` from `createClient`
-3. Add `{ bucketKey: '...' }` to every `db.records.*` and `db.analytics.*` call
-4. Auth calls (`db.auth.*`) are unchanged
+### `StorageStats`
 
----
-
-## Contributing
-
-1. Fork the repo and clone it
-2. `npm install`
-3. `npm run dev` — TypeScript watch mode
-4. `npm test` — run the test suite
-5. Open a PR 🚀
+```ts
+interface StorageStats {
+  totalFiles:             number;
+  totalSizeBytes:         number;
+  totalOriginalSizeBytes: number;
+  spaceSavedBytes:        number;
+  uploadsCount:           number;
+  downloadsCount:         number;
+  creditsUsedUpload:      number;
+  creditsUsedDownload:    number;
+  creditsTotalUsed:       number;
+  compressionRatio:       string;   // e.g. "34.2%"
+}
+```
 
 ---