hydrousdb 2.0.1 → 2.0.3

package/README.md

@@ -1,682 +1,1237 @@
-# Hydrous SDK
+# HydrousDB SDK
 
-Official JavaScript / TypeScript SDK for the **Hydrous** platform.  
-One package — auth, records, analytics, and storage.
+Official JavaScript / TypeScript SDK for the **HydrousDB** platform.  
+Auth · Records · Analytics · Storage — one package, one client.
 
 ```bash
-npm install hydrous
+npm install hydrousdb
 ```
 
 ---
 
 ## Table of Contents
 
-1. [Quick Start](#1-quick-start)
-2. [Configuration](#2-configuration)
-3. [Auth](#3-auth)
-   - [Sign Up](#sign-up)
-   - [Sign In](#sign-in)
-   - [Sign Out](#sign-out)
-   - [Get Current User](#get-current-user)
-4. [Records](#4-records)
-   - [Insert](#insert)
-   - [Select / Query](#select--query)
-   - [Get by ID](#get-by-id)
-   - [Update](#update)
-   - [Delete](#delete)
-   - [Query Helpers](#query-helpers)
-5. [Analytics](#5-analytics)
-   - [Track an Event](#track-an-event)
-   - [Batch Track](#batch-track)
-   - [Query Events](#query-events)
-6. [Storage](#6-storage)
-   - [How Bucket Keys Work](#how-bucket-keys-work)
-   - [Upload a File](#upload-a-file)
-   - [Upload Raw Text / JSON](#upload-raw-text--json)
-   - [Track Upload Progress](#track-upload-progress)
-   - [Batch Upload](#batch-upload)
-   - [Download a File](#download-a-file)
-   - [Batch Download](#batch-download)
-   - [List Files & Folders](#list-files--folders)
-   - [File Metadata](#file-metadata)
-   - [Delete a File](#delete-a-file)
-   - [Delete a Folder](#delete-a-folder)
-   - [Create a Folder](#create-a-folder)
-   - [Move a File](#move-a-file)
-   - [Copy a File](#copy-a-file)
+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)
-   - [Bucket Stats](#bucket-stats)
-7. [Error Handling](#7-error-handling)
-8. [TypeScript Types Reference](#8-typescript-types-reference)
+   - [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)
 
 ---
 
-## 1. Quick Start
+## 1. Setup & Client Configuration
 
-```ts
-import { createClient } from 'hydrous';
+Create **one** client and reuse it across your app.
 
-const hydrous = createClient({
-  url:    'https://api.yourapp.hydrous.app',
-  apiKey: 'hk_live_…',
+```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
+  },
 });
-
-// Upload a file
-const { data, error } = await hydrous.storage.upload(
-  'ssk_my_bucket_key',       // ← bucket key always comes first
-  file,
-  {
-    path:       'avatars/alice.jpg',
-    onProgress: (p) => console.log(`${p.percent}%`),
-  }
-);
 ```
 
----
+### Key types explained
 
-## 2. Configuration
+| 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           |
 
-```ts
-import { HydrousClient } from 'hydrous';
+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.
 
-const hydrous = new HydrousClient({
-  url:     'https://api.yourapp.hydrous.app', // your project URL
-  apiKey:  'hk_live_…',                       // your project API key
-  timeout: 30_000,                             // optional — ms (default 30s)
-});
+### Environment variables (recommended)
+
+```bash
+# .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_…
 ```
 
-| Option    | Type     | Required | Description                          |
-|-----------|----------|----------|--------------------------------------|
-| `url`     | `string` | ✅       | Your Hydrous project base URL         |
-| `apiKey`  | `string` | ✅       | Your project API key                  |
-| `timeout` | `number` | ✗        | Request timeout in ms (default 30000) |
+```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!,
+  },
+});
+```
 
 ---
 
-## 3. Auth
+## 2. Auth
 
 ### Sign Up
 
 ```ts
-const { data, error } = await hydrous.auth.signUp({
-  email:    'user@example.com',
+const { data, error } = await db.auth.signUp({
+  email:    'alice@example.com',
   password: 'supersecret',
-  metadata: { plan: 'pro' },   // optional
+  metadata: { plan: 'pro', referral: 'google' },
 });
 
-if (data) {
-  console.log('New user:', data.user.id);
-  console.log('Access token:', data.accessToken);
-}
+if (error) console.error(error.message);
+if (data)  console.log('New user:', data.user.id);
 ```
 
 ### Sign In
 
 ```ts
-const { data, error } = await hydrous.auth.signIn({
-  email:    'user@example.com',
+const { data, error } = await db.auth.signIn({
+  email:    'alice@example.com',
   password: 'supersecret',
 });
 
 if (data) {
-  console.log('Welcome back,', data.user.email);
+  localStorage.setItem('token', data.accessToken);
 }
 ```
 
 ### Sign Out
 
 ```ts
-await hydrous.auth.signOut();
+await db.auth.signOut();
+localStorage.removeItem('token');
 ```
 
-### Get Current User
+### Get current user
 
 ```ts
-const { data: user } = await hydrous.auth.getUser();
+const { data: user } = await db.auth.getUser();
 console.log(user?.email);
 ```
 
-### Refresh Session
+### Refresh session
 
 ```ts
-const { data: session } = await hydrous.auth.refreshSession();
+const { data: session } = await db.auth.refreshSession();
 ```
 
 ---
 
-## 4. Records
+## 3. Records
 
 ### Insert
 
-Single record:
-
 ```ts
-const { data, error } = await hydrous.records.insert('users', {
-  name:  'Alice',
-  email: 'alice@example.com',
-  role:  'admin',
+// Single record
+const { data } = await db.records.insert('products', {
+  name:     'Widget Pro',
+  price:    49.99,
+  category: 'hardware',
+  inStock:  true,
 });
-```
-
-Bulk insert (array):
 
-```ts
-const { data } = await hydrous.records.insert('products', [
-  { name: 'Widget A', price: 9.99 },
-  { name: 'Widget B', price: 14.99 },
+// 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 ${data.length} products`);
+console.log(`Inserted ${count} products`);
 ```
 
-### Select / Query
+### Select (query)
 
 ```ts
-const { data, count } = await hydrous.records.select('users', {
-  where:   { field: 'role', operator: 'eq', value: 'admin' },
-  orderBy: { field: 'createdAt', direction: 'desc' },
+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', 'email'],   // optional column projection
+  select:  ['id', 'name', 'price'],  // return only these fields
 });
 ```
 
-Multiple filters:
+### Get one by ID
 
 ```ts
-import { eq, gt, inArray } from 'hydrous';
-
-const { data } = await hydrous.records.select('orders', {
-  where: [
-    eq('status',  'shipped'),
-    gt('total',   100),
-    inArray('tag', ['vip', 'priority']),
-  ],
-});
-```
-
-### Get by ID
-
-```ts
-const { data: user } = await hydrous.records.get('users', 'user_abc123');
+const { data: product } = await db.records.get('products', 'prod_abc123');
 ```
 
 ### Update
 
 ```ts
-const { data } = await hydrous.records.update('users', 'user_abc123', {
-  name: 'Alice Smith',
+const { data } = await db.records.update('products', 'prod_abc123', {
+  price:   59.99,
+  inStock: false,
 });
 ```
 
 ### Delete
 
 ```ts
-const { error } = await hydrous.records.delete('users', 'user_abc123');
-```
-
-### Query Helpers
-
-| Helper              | SQL equivalent          |
-|---------------------|------------------------|
-| `eq(field, val)`    | `field = val`          |
-| `neq(field, val)`   | `field != val`         |
-| `gt(field, val)`    | `field > val`          |
-| `lt(field, val)`    | `field < val`          |
-| `inArray(field, [])` | `field IN (…)`        |
-
-```ts
-import { eq, gt, inArray } from 'hydrous';
+const { error } = await db.records.delete('products', 'prod_abc123');
 ```
 
 ---
 
-## 5. Analytics
+## 4. Analytics
 
-### Track an Event
+### Track an event
 
 ```ts
-await hydrous.analytics.track({
-  event:      'page_view',
-  properties: { page: '/home', referrer: 'google.com' },
+await db.analytics.track({
+  event:      'purchase_completed',
   userId:     'user_abc123',
   sessionId:  'sess_xyz',
+  properties: {
+    orderId:   'ord_001',
+    total:     99.99,
+    currency:  'USD',
+    itemCount: 3,
+  },
 });
 ```
 
-### Batch Track
-
-More efficient than calling `track()` in a loop:
+### Track many events at once
 
 ```ts
-await hydrous.analytics.trackBatch([
-  { event: 'signup',    userId: 'u1' },
-  { event: 'onboarded', userId: 'u1', properties: { step: 'profile' } },
+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
+### Query events
 
 ```ts
-const { data, count } = await hydrous.analytics.query({
-  event:   'page_view',
-  from:    '2024-01-01',
-  to:      '2024-01-31',
-  limit:   500,
-  groupBy: 'properties.page',
+const { data } = await db.analytics.query({
+  event:  'purchase_completed',
+  from:   '2024-01-01',
+  to:     '2024-01-31',
+  limit:  500,
 });
 ```
 
 ---
 
-## 6. Storage
-
-The storage module handles all file operations. Every method takes a **bucket key** as its **first argument** — a string that begins with `ssk_`.
+## 5. Storage
 
-### How Bucket Keys Work
+### How storage keys work
 
-A bucket key (`ssk_…`) is a scoped credential that grants specific permissions (read / write / delete) to a bucket. You create them in the Hydrous dashboard.
+`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
 ```
-hydrous.storage.<method>(
-  'ssk_your_bucket_key',   // ← first, always a string
-  ...args
-)
+
+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/' });
 ```
 
 ---
 
-### Upload a File
+### Upload a file with progress
 
 ```ts
-const { data, error } = await hydrous.storage.upload(
-  'ssk_my_bucket_key',
-  file,                      // File | Blob | Uint8Array | ArrayBuffer
-  {
-    path:      'avatars/alice.jpg',  // destination path in your bucket
-    overwrite: true,                 // replace if exists (default: false)
-    onProgress: (progress) => {
-      console.log(progress.stage, progress.percent + '%');
-    },
-  }
-);
+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`);
+  },
+});
 
 if (data) {
-  console.log('Stored at:', data.path);
-  console.log('Space saved:', data.spaceSaved, 'bytes');
+  console.log('Path:', data.path);
+  console.log('Space saved by compression:', data.spaceSaved, 'bytes');
 }
 ```
 
----
+### Batch upload
 
-### Upload Raw Text / JSON
+```ts
+const files = Array.from(fileInput.files);
 
-No `File` object needed — pass any string directly.
+const { data } = await db.storage('documents').batchUpload(files, {
+  prefix:      'uploads/2024/',
+  overwrite:   false,
+  concurrency: 5,
 
-```ts
-// Upload a plain text file
-await hydrous.storage.uploadText(
-  'ssk_my_bucket_key',
-  'reports/summary.txt',
-  'Monthly report content…',
-  { mimeType: 'text/plain' }
-);
+  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}%`);
+  },
+});
 
-// Upload JSON
-await hydrous.storage.uploadText(
-  'ssk_my_bucket_key',
-  'data/config.json',
-  JSON.stringify({ theme: 'dark', lang: 'en' }),
-  { mimeType: 'application/json' }
-);
+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
 
-### Track Upload Progress
+```ts
+const { data: buffer, error } = await db.storage('documents').download('reports/q1.pdf');
 
-`onProgress` is called on every progress tick with a rich `UploadProgress` object.
+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
-await hydrous.storage.upload(
-  'ssk_my_bucket_key',
-  file,
-  {
-    onProgress: (p) => {
-      // p.stage          — 'pending' | 'compressing' | 'uploading' | 'done' | 'error'
-      // p.percent        — 0–100 integer
-      // p.bytesUploaded  — bytes sent so far
-      // p.totalBytes     — total bytes to send
-      // p.bytesPerSecond — current speed (null before first tick)
-      // p.eta            — estimated seconds remaining (null until speed is known)
-      // p.index          — file index (always 0 for single uploads)
-      // p.total          — total files (always 1 for single uploads)
-
-      switch (p.stage) {
-        case 'pending':
-          console.log('Queued');
-          break;
-        case 'compressing':
-          console.log('Compressing…');
-          break;
-        case 'uploading':
-          console.log(`Uploading ${p.percent}% — ${formatSpeed(p.bytesPerSecond)} — ETA ${p.eta}s`);
-          break;
-        case 'done':
-          console.log('✅ Done!', p.result);
-          break;
-        case 'error':
-          console.error('❌ Error:', p.error);
-          break;
-      }
-    },
-  }
-);
+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');
+}
 
-function formatSpeed(bps: number | null): string {
-  if (!bps) return '—';
-  if (bps > 1_000_000) return `${(bps / 1_000_000).toFixed(1)} MB/s`;
-  if (bps > 1_000)     return `${(bps / 1_000).toFixed(0)} KB/s`;
-  return `${bps} B/s`;
+// Paginate
+if (data!.pagination.hasNextPage) {
+  const page2 = await db.storage('documents').list({
+    prefix: 'invoices/',
+    cursor: data!.pagination.nextCursor!,
+  });
 }
 ```
 
-**Stage lifecycle:**
+### Delete, move, copy
 
-```
-pending → compressing → uploading → done
-                                  ↘ error
-```
+```ts
+// Delete a single file
+await db.storage('avatars').deleteFile('users/old-photo.jpg');
 
-> **Note:** In browsers, upload progress (bytes leaving the NIC) is tracked via
-> `XMLHttpRequest`. The final `done` stage fires only after the server confirms
-> the write to cloud storage — so `100%` means the file is truly saved.
+// 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');
 
-### Batch Upload
+// Copy a file (original kept)
+await db.storage('documents').copy('templates/invoice.pdf', 'invoices/inv-001.pdf');
+```
 
-Upload many files in one request. Progress fires per-file so you can render
-individual progress bars.
+### Signed URLs
 
 ```ts
-const inputFiles = Array.from(fileInput.files);  // FileList → array
-
-const { data, error } = await hydrous.storage.batchUpload(
-  'ssk_my_bucket_key',
-  inputFiles,
-  {
-    prefix:      'uploads/2024/',    // prepended to each filename
-    overwrite:   false,
-    concurrency: 5,                  // max parallel uploads on the server (1–10)
-    onProgress:  (p) => {
-      // p.index identifies WHICH file this event is for (0-based)
-      console.log(`File ${p.index} (${p.path}): ${p.stage} ${p.percent}%`);
-    },
-  }
+// Generate a link that expires in 10 minutes
+const { data } = await db.storage('documents').signedUrl(
+  'contracts/nda.pdf',
+  { expiresIn: 600 }
 );
 
-console.log('Succeeded:', data.succeeded.length);
-console.log('Failed:',    data.failed.length);
+console.log(data!.signedUrl);   // share this URL
+console.log(data!.expiresAt);   // ISO timestamp when it expires
 ```
 
-Per-file paths override:
+### Upload raw text / JSON
 
 ```ts
-await hydrous.storage.batchUpload('ssk_key', files, {
-  paths: [
-    'documents/report-q1.pdf',
-    'documents/report-q2.pdf',
-  ],
-});
+// 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' }
+);
 ```
 
-> All files are validated upfront before any uploads begin — if your quota
-> would be exceeded the entire batch is rejected cleanly with no partial writes.
+### 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);
+```
 
 ---
 
-### Download a File
+## 6. Error Handling
 
-Returns the file as an `ArrayBuffer`.
+Every method returns `{ data, error }`. `error` is `null` on success.
 
 ```ts
-const { data: buffer, error } = await hydrous.storage.download(
-  'ssk_my_bucket_key',
-  'avatars/alice.jpg'
-);
-
-if (buffer) {
-  // Browser: display image
-  const blob = new Blob([buffer], { type: 'image/jpeg' });
-  img.src    = URL.createObjectURL(blob);
+const { data, error } = await db.storage('avatars').upload(file);
 
-  // Node: write to disk
-  import { writeFileSync } from 'fs';
-  writeFileSync('alice.jpg', Buffer.from(buffer));
+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)
 }
 ```
 
----
-
-### Batch Download
+### Catching thrown errors
 
 ```ts
-const { data: files } = await hydrous.storage.batchDownload(
-  'ssk_my_bucket_key',
-  ['reports/jan.pdf', 'reports/feb.pdf', 'reports/mar.pdf'],
-  {
-    concurrency: 3,
-    autoSave:    true,          // browser: auto-triggers Save dialog per file
-    onProgress:  (p) => {
-      console.log(`${p.path}: ${p.status}`);   // 'pending' | 'success' | 'error'
-    },
-  }
-);
+import { isHydrousError } from 'hydrousdb';
 
-// files[n].content  — ArrayBuffer
-// files[n].mimeType — string
-// files[n].path     — original path
-// files[n].size     — bytes
+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    |
+
 ---
 
-### List Files & Folders
+## 7. Real-World Examples — Next.js
+
+### Shared client (lib/db.ts)
 
 ```ts
-const { data } = await hydrous.storage.list('ssk_my_bucket_key', {
-  prefix: 'avatars/',   // list inside a folder — omit for root
-  limit:  50,           // max items per page (1–100)
+// lib/db.ts
+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: {
+    avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
+    documents: process.env.HYDROUS_STORAGE_DOCS!,
+  },
 });
+```
 
-for (const item of data.items) {
-  if (item.type === 'folder') {
-    console.log('📁', item.path);
-  } else {
-    console.log('📄', item.path, item.size, 'bytes');
+---
+
+### 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>
+  );
 }
+```
 
-// Paginate
-if (data.pagination.hasNextPage) {
-  const page2 = await hydrous.storage.list('ssk_my_bucket_key', {
-    prefix: 'avatars/',
-    cursor: data.pagination.nextCursor,
+---
+
+### 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, 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}>
+          {p.name} — ${p.price}
+        </li>
+      ))}
+    </ul>
+  );
 }
 ```
 
 ---
 
-### File Metadata
+### Storage: Avatar upload with live progress bar
 
-```ts
-const { data: meta } = await hydrous.storage.metadata(
-  'ssk_my_bucket_key',
-  'avatars/alice.jpg'
-);
+```tsx
+// components/AvatarUploader.tsx
+'use client';
+import { useState } from 'react';
+import { db } from '@/lib/db';
+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; }
 
-console.log(meta.size);          // stored bytes
-console.log(meta.originalSize);  // bytes before compression
-console.log(meta.mimeType);
-console.log(meta.isCompressed);
-console.log(meta.updatedAt);
+    // Generate a signed URL to display the uploaded avatar
+    const { data: urlData } = await db.storage('avatars').signedUrl(
+      `users/${userId}/avatar.jpg`,
+      { expiresIn: 3600 }
+    );
+    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>
+  );
+}
 ```
 
 ---
 
-### Delete a File
+### Storage: Secure file download link (API route)
 
 ```ts
-const { error } = await hydrous.storage.deleteFile(
-  'ssk_my_bucket_key',
-  'avatars/old-photo.jpg'
-);
+// app/api/download/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+
+export async function GET(req: NextRequest) {
+  const filePath = req.nextUrl.searchParams.get('file');
+  if (!filePath) return NextResponse.json({ error: 'file param required' }, { status: 400 });
+
+  // Generate a short-lived signed URL (2 minutes)
+  const { data, error } = await db.storage('documents').signedUrl(filePath, {
+    expiresIn: 120,
+  });
+
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+
+  return NextResponse.json({ url: data!.signedUrl, expiresAt: data!.expiresAt });
+}
+```
+
+```tsx
+// Usage in a component:
+// const res  = await fetch(`/api/download?file=contracts/nda.pdf`);
+// const { url } = await res.json();
+// window.open(url, '_blank');
 ```
 
 ---
 
-### Delete a Folder
+### Analytics: Page-view tracking
+
+```tsx
+// components/Analytics.tsx
+'use client';
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { db } from '@/lib/db';
+
+export default function Analytics() {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    db.analytics.track({
+      event:      'page_view',
+      properties: {
+        path:      pathname,
+        referrer:  document.referrer,
+        userAgent: navigator.userAgent,
+      },
+    });
+  }, [pathname]);
+
+  return null;
+}
+```
 
-Recursively deletes the folder and everything inside it.
+```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>
+  );
+}
+```
+
+---
+
+### Records: Server Action — create a product
 
 ```ts
-await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
+// app/products/actions.ts
+'use server';
+import { db } from '@/lib/db';
+import { revalidatePath } from 'next/cache';
+
+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 { data, error } = await db.records.insert('products', {
+    name, price, category, inStock: true,
+  });
+
+  if (error) throw new Error(error.message);
+
+  revalidatePath('/products');
+  return data[0];
+}
 ```
 
 ---
 
-### Create a Folder
+## 8. Real-World Examples — Vue 3
+
+### Shared client (src/lib/db.ts)
 
 ```ts
-await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
+// src/lib/db.ts
+import { createClient } from 'hydrousdb';
+
+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,
+  },
+});
 ```
 
 ---
 
-### Move a File
+### Auth: Login composable
 
 ```ts
-await hydrous.storage.move(
-  'ssk_my_bucket_key',
-  'drafts/report.pdf',
-  'published/report.pdf'
-);
+// composables/useAuth.ts
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+import { db } from '@/lib/db';
+
+export function useAuth() {
+  const user    = ref(null);
+  const loading = ref(false);
+  const error   = ref<string | null>(null);
+  const router  = useRouter();
+
+  async function login(email: string, password: string) {
+    loading.value = true;
+    error.value   = null;
+
+    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');
+    }
+
+    loading.value = false;
+  }
+
+  async function logout() {
+    await db.auth.signOut();
+    user.value = null;
+    localStorage.removeItem('token');
+    router.push('/login');
+  }
+
+  return { user, loading, error, login, logout };
+}
 ```
 
 ---
 
-### Copy a File
+### Storage: File upload with progress
 
-```ts
-await hydrous.storage.copy(
-  'ssk_my_bucket_key',
-  'templates/invoice.pdf',
-  'invoices/invoice-001.pdf'
-);
+```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;
+    },
+  });
+
+  if (err) {
+    error.value = err.message;
+  } else {
+    done.value     = true;
+    progress.value = null;
+    console.log('Uploaded to', data!.path);
+  }
+}
+</script>
+
+<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>
 ```
 
 ---
 
-### Signed URLs
+### Records: Data table with pagination
 
-Generate a time-limited public URL for a private file.
+```vue
+<!-- components/ProductTable.vue -->
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import { db } from '@/lib/db';
+import { eq } from 'hydrousdb';
 
-```ts
-const { data } = await hydrous.storage.signedUrl(
-  'ssk_my_bucket_key',
-  'contracts/agreement.pdf',
-  { expiresIn: 300 }   // 5 minutes (default: 3600 = 1 hour)
-);
+type Product = { id: string; name: string; price: number; inStock: boolean };
+
+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,
+  });
 
-console.log(data.signedUrl);   // share this — expires at data.expiresAt
+  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>
 ```
 
 ---
 
-### Bucket Stats
+### Vue: Batch file upload with per-file progress
 
-```ts
-const { data: stats } = await hydrous.storage.stats('ssk_my_bucket_key');
+```vue
+<!-- components/BatchUploader.vue -->
+<script setup lang="ts">
+import { ref } from 'vue';
+import { db } from '@/lib/db';
+import type { UploadProgress } from 'hydrousdb';
+
+type FileState = { name: string; percent: number; stage: string; done: boolean; error?: string };
 
-console.log('Files:',         stats.totalFiles);
-console.log('Stored:',        stats.totalSizeBytes,   'bytes');
-console.log('Space saved:',   stats.spaceSavedBytes,  'bytes');
-console.log('Credits used:',  stats.creditsTotalUsed);
-console.log('Compression:',   stats.compressionRatio);
+const fileStates = ref<FileState[]>([]);
+
+async function onFilesChange(event: Event) {
+  const files = Array.from((event.target as HTMLInputElement).files ?? []);
+  if (!files.length) return;
+
+  fileStates.value = files.map(f => ({ name: f.name, percent: 0, stage: 'pending', done: false }));
+
+  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>
 ```
 
 ---
 
-## 7. Error Handling
+## 9. Real-World Examples — SvelteKit
 
-Every method returns `{ data, error }`. `error` is `null` on success.
+### Shared client
 
 ```ts
-const { data, error } = await hydrous.storage.upload('ssk_key', file);
+// 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,
+  },
+});
+```
 
-if (error) {
-  console.error(error.message);  // human-readable message
-  console.error(error.code);     // machine-readable code e.g. 'QUOTA_EXCEEDED'
-  console.error(error.status);   // HTTP status code (if applicable)
+### Server route — fetch records
+
+```ts
+// 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);
 }
 ```
 
-### Catching thrown errors
-
-If you prefer `try/catch`, import `isHydrousError`:
+### Page load — server-side
 
 ```ts
-import { isHydrousError } from 'hydrous';
+// 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' },
+  });
 
-try {
-  // ...
-} catch (err) {
-  if (isHydrousError(err)) {
-    console.error(err.code, err.message);
+  if (error) throw error;
+  return { products };
+};
+```
+
+### File upload component
+
+```svelte
+<!-- src/lib/components/Uploader.svelte -->
+<script lang="ts">
+  import { db } from '$lib/db';
+  import type { UploadProgress } from 'hydrousdb';
+
+  let progress: UploadProgress | null = null;
+  let uploadedPath = '';
+  let errorMsg = '';
+
+  async function handleFile(event: Event) {
+    const file = (event.target as HTMLInputElement).files?.[0];
+    if (!file) return;
+
+    errorMsg     = '';
+    uploadedPath = '';
+    progress     = null;
+
+    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>
+
+<input type="file" on:change={handleFile} />
+
+{#if progress}
+  <p>{progress.stage} — {progress.percent}%</p>
+  <progress value={progress.percent} max="100" />
+{/if}
+
+{#if uploadedPath}
+  <p>✓ Saved at: {uploadedPath}</p>
+{/if}
+
+{#if errorMsg}
+  <p style="color:red">{errorMsg}</p>
+{/if}
+```
+
+---
+
+## 10. Real-World Examples — Express / Node API
+
+### Setup
+
+```ts
+// 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!,
+  },
+});
+```
+
+### Upload from a file buffer (Node)
+
+```ts
+// routes/upload.ts
+import express from 'express';
+import multer  from 'multer';
+import { db }  from '../db';
+
+const router  = express.Router();
+const upload  = multer({ storage: multer.memoryStorage() });
+
+router.post('/upload', upload.single('file'), async (req, res) => {
+  if (!req.file) return res.status(400).json({ error: 'No file' });
+
+  const { data, error } = await db.storage('main').upload(
+    req.file.buffer,
+    {
+      path:     `uploads/${Date.now()}-${req.file.originalname}`,
+      overwrite: false,
+    }
+  );
+
+  if (error) return res.status(500).json({ error: error.message });
+  res.json({ path: data!.path, size: data!.storedSize });
+});
+
+export default router;
+```
+
+### Save JSON reports to storage
+
+```ts
+// jobs/generateReport.ts
+import { db } from '../db';
+
+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}`);
+
+  // 4. Track the event
+  await db.analytics.track({
+    event:      'report_generated',
+    properties: { month, totalOrders: report.totalOrders },
+  });
+
+  return data!.path;
 }
 ```
 
-### Common error codes
+### Batch delete old records
+
+```ts
+// 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();
+
+  // Fetch old sessions
+  const { data: old } = await db.records.select('sessions', {
+    where: lt('createdAt', cutoff),
+    limit: 500,
+  });
 
-| Code                | Meaning                                      |
-|---------------------|----------------------------------------------|
-| `HTTP_ERROR`        | Non-2xx HTTP response from the server        |
-| `NETWORK_ERROR`     | Failed to reach the server                   |
-| `QUOTA_EXCEEDED`    | Storage quota has been reached               |
-| `FILE_TOO_LARGE`    | File exceeds the per-file size limit (50 MB) |
-| `INVALID_MIME`      | MIME type not permitted                      |
-| `FILE_EXISTS`       | File already exists and `overwrite` is false |
-| `UPLOAD_ABORTED`    | Upload was cancelled by the client           |
-| `UPLOAD_TIMEOUT`    | Upload timed out                             |
-| `NO_SESSION`        | Auth operation requires a session            |
-| `UNKNOWN_ERROR`     | An unexpected error occurred                 |
+  if (!old.length) { console.log('Nothing to clean up'); return; }
+
+  // Delete each one
+  await Promise.all(old.map((s: any) => db.records.delete('sessions', s.id)));
+  console.log(`Deleted ${old.length} expired sessions`);
+}
+
+cleanupOldSessions();
+```
 
 ---
 
-## 8. TypeScript Types Reference
+## 11. TypeScript Types Reference
+
+### `HydrousConfig`
+
+```ts
+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
+}
+```
 
 ### `UploadProgress`
 
 ```ts
 interface UploadProgress {
-  index:          number;          // file index (0-based)
-  total:          number;          // total files in the operation
+  index:          number;          // 0-based file index
+  total:          number;          // total files in this operation
   path:           string;          // destination path
-  stage:          UploadStage;     // see below
+  stage:          UploadStage;     // 'pending'|'compressing'|'uploading'|'done'|'error'
   bytesUploaded:  number;
   totalBytes:     number;
   percent:        number;          // 0–100
-  bytesPerSecond: number | null;   // null before first tick
+  bytesPerSecond: number | null;   // null until speed is calculable
   eta:            number | null;   // seconds remaining, null until speed known
-  result?:        UploadResult;    // set when stage === 'done'
-  error?:         string;          // set when stage === 'error'
+  result?:        UploadResult;    // populated when stage === 'done'
+  error?:         string;          // populated when stage === 'error'
   code?:          string;
 }
-
-type UploadStage = 'pending' | 'compressing' | 'uploading' | 'done' | 'error';
 ```
 
 ### `UploadResult`
@@ -692,17 +1247,17 @@ interface UploadResult {
 }
 ```
 
-### `StorageItem` (from `list()`)
+### `StorageItem`
 
 ```ts
 interface StorageItem {
-  name:         string;
-  path:         string;
-  type:         'file' | 'folder';
-  size?:        number | null;
-  mimeType?:    string | null;
+  name:          string;
+  path:          string;
+  type:          'file' | 'folder';
+  size?:         number | null;
+  mimeType?:     string | null;
   isCompressed?: boolean;
-  updatedAt?:   string | null;
+  updatedAt?:    string | null;
 }
 ```
 
@@ -719,7 +1274,7 @@ interface StorageStats {
   creditsUsedUpload:      number;
   creditsUsedDownload:    number;
   creditsTotalUsed:       number;
-  compressionRatio:       string;  // e.g. "34.2%"
+  compressionRatio:       string;   // e.g. "34.2%"
 }
 ```
 
@@ -727,4 +1282,4 @@ interface StorageStats {
 
 ## License
 
-MIT © Hydrous
+MIT © HydrousDB