hydrousdb 2.0.3 → 3.0.1

package/README.md

@@ -1,1285 +1,1126 @@
-# HydrousDB SDK
+# HydrousDB JavaScript / TypeScript SDK
 
-Official JavaScript / TypeScript SDK for the **HydrousDB** platform.  
-Auth · Records · Analytics · Storage — one package, one client.
+<p align="center">
+  <strong>The official SDK for <a href="https://hydrousdb.com">HydrousDB</a> — records, auth, file storage, and analytics in one package.</strong>
+</p>
 
-```bash
-npm install hydrousdb
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/hydrousdb"><img src="https://img.shields.io/npm/v/hydrousdb.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/hydrousdb"><img src="https://img.shields.io/npm/dm/hydrousdb.svg" alt="npm downloads"></a>
+  <a href="https://github.com/hydrousdb/hydrousdb-js/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/hydrousdb.svg" alt="MIT License"></a>
+  <a href="https://hydrousdb.com"><img src="https://img.shields.io/badge/docs-hydrousdb.com-blue" alt="Documentation"></a>
+</p>
 
 ---
 
 ## Table of Contents
 
-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)
+- [What is HydrousDB?](#what-is-hydrousdb)
+- [Quick Start (5 minutes)](#quick-start-5-minutes)
+  - [Step 1 — Create your account](#step-1--create-your-account)
+  - [Step 2 — Create your first bucket](#step-2--create-your-first-bucket)
+  - [Step 3 — Grab your Security Key](#step-3--grab-your-security-key)
+  - [Step 4 — Install the SDK](#step-4--install-the-sdk)
+  - [Step 5 — Your first record](#step-5--your-first-record)
+- [Records](#records)
+  - [Create](#create-a-record)
+  - [Read](#read-a-record)
+  - [Update](#update-a-record)
+  - [Delete](#delete-a-record)
+  - [Query](#query-records)
+  - [Batch Operations](#batch-operations)
+  - [Version History](#version-history)
+- [Authentication](#authentication)
+  - [Sign Up](#sign-up-users)
+  - [Log In / Log Out](#log-in--log-out)
+  - [Session Management](#session-management)
+  - [Password Reset](#password-reset-flow)
+  - [Email Verification](#email-verification)
+  - [Admin Operations](#admin-operations)
+- [File Storage](#file-storage)
+  - [Simple Upload](#simple-upload)
+  - [Large File Upload (with progress)](#large-file-upload-with-progress)
+  - [Download](#download-files)
+  - [List Files](#list-files)
+  - [Scoped Storage](#scoped-storage)
+  - [Share & Visibility](#share--visibility)
+  - [File Operations](#file-operations)
+- [Analytics](#analytics)
+  - [Count](#count)
+  - [Distribution](#distribution)
+  - [Time Series](#time-series)
+  - [Top N](#top-n)
+  - [Field Stats](#field-stats)
+  - [Multi-Metric Dashboard](#multi-metric-dashboard)
+  - [Cross-Bucket Comparison](#cross-bucket-comparison)
+- [TypeScript Support](#typescript-support)
+- [Error Handling](#error-handling)
+- [Security Best Practices](#security-best-practices)
+- [API Reference](#api-reference)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
-## 1. Setup & Client Configuration
+## What is HydrousDB?
 
-Create **one** client and reuse it across your app.
+HydrousDB is a **backend-as-a-service** platform that gives your app a fully managed backend in minutes. Instead of spinning up servers, databases, and storage buckets yourself, you call an API.
 
-```ts
-import { createClient } from 'hydrousdb';
+| Feature | What it does |
+|---|---|
+| **Records** | Schemaless JSON document store. Create, read, update, delete and query records in named *buckets*. |
+| **Auth** | Full user authentication — signup, login, sessions, password reset, email verification, and admin controls. |
+| **Storage** | File uploads and downloads backed by Google Cloud Storage. Public and private files, signed share URLs. |
+| **Analytics** | BigQuery-powered aggregations — counts, distributions, time series, top-N, multi-metric dashboards, and cross-bucket comparisons. |
 
-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
-  },
-});
-```
+Everything is organised around two concepts:
 
-### Key types explained
+- **Security Key (`sk_...`)** — your master credential. Authenticate all API calls. Keep it secret.
+- **Bucket Key** — just the name of your bucket (e.g. `"blog-posts"`, `"app-users"`). Not a secret.
 
-| 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           |
+---
 
-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.
+## Quick Start (5 minutes)
 
-### Environment variables (recommended)
+### Step 1 — Create your account
 
-```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_…
-```
+Go to **[https://hydrousdb.com](https://hydrousdb.com)** and sign up for a free account.
 
-```ts
-// lib/db.ts  (server-side only — never expose secret keys to the browser)
-import { createClient } from 'hydrousdb';
+### Step 2 — Create your first bucket
 
-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!,
-  },
-});
-```
+1. Log in to your dashboard at **[https://hydrousdb.com/dashboard](https://hydrousdb.com/dashboard)**.
+2. Click **"New Bucket"**.
+3. Give it a name — use lowercase letters, numbers, hyphens, or underscores (e.g. `my-first-bucket`).
+4. Click **"Create"**.
 
----
+> 💡 **What is a bucket?** A bucket is a named collection of JSON records — similar to a table in SQL or a collection in MongoDB.
 
-## 2. Auth
+### Step 3 — Grab your Security Key
 
-### Sign Up
+1. In the dashboard, go to **Settings → API Keys**.
+2. Click **"Generate Security Key"**.
+3. Copy the key — it looks like `sk_live_xxxxxxxxxxxxxxxxxxxx`.
 
-```ts
-const { data, error } = await db.auth.signUp({
-  email:    'alice@example.com',
-  password: 'supersecret',
-  metadata: { plan: 'pro', referral: 'google' },
-});
+> ⚠️ **Your Security Key is your most important credential.** Treat it like a password. Never commit it to Git. Use environment variables.
+
+### Step 4 — Install the SDK
 
-if (error) console.error(error.message);
-if (data)  console.log('New user:', data.user.id);
+```bash
+npm install hydrousdb
+# or
+yarn add hydrousdb
+# or
+pnpm add hydrousdb
 ```
 
-### Sign In
+**Requirements:** Node.js 18+ (uses the native `fetch` API).
 
-```ts
-const { data, error } = await db.auth.signIn({
-  email:    'alice@example.com',
-  password: 'supersecret',
-});
+### Step 5 — Your first record
 
-if (data) {
-  localStorage.setItem('token', data.accessToken);
-}
-```
+```typescript
+import { createClient } from 'hydrousdb';
 
-### Sign Out
+// Create the client once — reuse it everywhere
+const db = createClient({
+  securityKey: process.env.HYDROUS_SECURITY_KEY!, // from Step 3
+});
 
-```ts
-await db.auth.signOut();
-localStorage.removeItem('token');
-```
+// Write a record to your bucket
+const post = await db.records('my-first-bucket').create({
+  title:     'Hello, HydrousDB!',
+  body:      'My first record.',
+  published: false,
+});
 
-### Get current user
+console.log(post.id);        // "rec_a1b2c3d4"
+console.log(post.createdAt); // 1717200000000
 
-```ts
-const { data: user } = await db.auth.getUser();
-console.log(user?.email);
-```
+// Read it back
+const fetched = await db.records('my-first-bucket').get(post.id);
+console.log(fetched.title);  // "Hello, HydrousDB!"
 
-### Refresh session
+// Update it
+const updated = await db.records('my-first-bucket').patch(post.id, { published: true });
 
-```ts
-const { data: session } = await db.auth.refreshSession();
+// Delete it
+await db.records('my-first-bucket').delete(post.id);
 ```
 
+🎉 **That's it!** You're live with zero configuration beyond your Security Key.
+
 ---
 
-## 3. Records
+## Records
+
+Records are JSON objects stored in named buckets. Every record automatically gets:
+- `id` — unique record identifier (e.g. `"rec_a1b2c3d4"`)
+- `createdAt` — Unix timestamp in milliseconds
+- `updatedAt` — Unix timestamp in milliseconds (updated on every write)
 
-### Insert
+### Create a Record
 
-```ts
-// Single record
-const { data } = await db.records.insert('products', {
-  name:     'Widget Pro',
-  price:    49.99,
-  category: 'hardware',
+```typescript
+const products = db.records('products');
+
+const product = await products.create({
+  name:     'Wireless Headphones',
+  price:    79.99,
   inStock:  true,
+  tags:     ['audio', 'wireless'],
 });
 
-// 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`);
+// product.id, product.createdAt, product.updatedAt are added automatically
 ```
 
-### Select (query)
+### Read a Record
 
-```ts
-import { eq, gt, inArray } from 'hydrousdb';
+```typescript
+// Get by ID
+const product = await products.get('rec_abc123');
 
-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
-});
+// product is null-safe: throws HydrousError with code RECORD_NOT_FOUND if missing
 ```
 
-### Get one by ID
+### Update a Record
 
-```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,
+```typescript
+// Patch (merge) — only the listed fields are changed
+const updated = await products.patch('rec_abc123', {
+  price:   69.99,
   inStock: false,
 });
+
+// Set (full replace) — the entire record is replaced
+const replaced = await products.set('rec_abc123', {
+  name:    'Wireless Headphones v2',
+  price:   89.99,
+  inStock: true,
+  tags:    ['audio', 'wireless', 'premium'],
+});
 ```
 
-### Delete
+### Delete a Record
 
-```ts
-const { error } = await db.records.delete('products', 'prod_abc123');
+```typescript
+await products.delete('rec_abc123');
 ```
 
----
-
-## 4. Analytics
+### Query Records
 
-### Track an event
+```typescript
+// Get all records (up to 100 by default)
+const { records } = await products.query();
 
-```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,
-  },
+// With filters
+const { records: affordableStock } = await products.query({
+  filters: [
+    { field: 'inStock', op: '==', value: true  },
+    { field: 'price',   op: '<',  value: 100   },
+  ],
 });
-```
 
-### Track many events at once
+// Sort and paginate
+const { records, hasMore, nextCursor } = await products.query({
+  orderBy: 'price',
+  order:   'asc',
+  limit:   20,
+});
 
-```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' } },
-]);
-```
+// Next page
+if (hasMore) {
+  const page2 = await products.query({
+    orderBy:    'price',
+    order:      'asc',
+    limit:      20,
+    startAfter: nextCursor,
+  });
+}
 
-### Query events
+// Select only specific fields
+const { records: lightRecords } = await products.query({
+  fields: 'name,price,inStock',
+});
 
-```ts
-const { data } = await db.analytics.query({
-  event:  'purchase_completed',
-  from:   '2024-01-01',
-  to:     '2024-01-31',
-  limit:  500,
+// Filter by date range
+const { records: recent } = await products.query({
+  dateRange: {
+    start: Date.now() - 7 * 24 * 60 * 60 * 1000, // 7 days ago
+    end:   Date.now(),
+  },
 });
 ```
 
----
-
-## 5. Storage
-
-### How storage keys work
+**Available filter operators:**
+
+| Operator | Meaning |
+|---|---|
+| `==` | Equal |
+| `!=` | Not equal |
+| `>` | Greater than |
+| `<` | Less than |
+| `>=` | Greater than or equal |
+| `<=` | Less than or equal |
+| `CONTAINS` | String contains (case-sensitive) |
+
+### Batch Operations
+
+```typescript
+// Create multiple records at once
+const created = await products.batchCreate([
+  { name: 'Item A', price: 10.00, inStock: true },
+  { name: 'Item B', price: 20.00, inStock: false },
+  { name: 'Item C', price: 30.00, inStock: true },
+]);
+// → [{ id: 'rec_1', ... }, { id: 'rec_2', ... }, { id: 'rec_3', ... }]
 
-`db.storage` is a function — call it with the **name** of the key you configured:
+// Count records
+const total = await products.count();
+const inStock = await products.count([{ field: 'inStock', op: '==', value: true }]);
 
-```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
+// Delete multiple records
+const { deleted, failed } = await products.batchDelete(['rec_1', 'rec_2', 'rec_3']);
 ```
 
-You can cache the result if you use the same bucket a lot:
+### Version History
 
-```ts
-const avatarStore   = db.storage('avatars');
-const documentStore = db.storage('documents');
+Every write to a record creates a new version stored in GCS, so you can travel back in time.
 
-await avatarStore.upload(file, { path: 'alice.jpg' });
-const list = await documentStore.list({ prefix: 'invoices/' });
+```typescript
+// Get the full version history of a record
+const history = await products.getHistory('rec_abc123');
+// history[0] is the latest version, history[1] is one write before, etc.
+
+// Restore to a specific version
+const restored = await products.restoreVersion('rec_abc123', history[2]!.version);
 ```
 
 ---
 
-### Upload a file with progress
+## Authentication
+
+HydrousDB has a built-in user auth system. Your users live in a bucket you create
+(e.g. `"app-users"`). You get sessions, refresh tokens, password reset, email
+verification, and admin controls out of the box.
 
-```ts
-const { data, error } = await db.storage('avatars').upload(file, {
-  path:      'users/alice.jpg',
-  overwrite: true,
+```typescript
+const auth = db.auth('app-users');
+```
 
-  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
+### Sign Up Users
 
-    console.log(`[${p.stage}] ${p.percent}% — ${p.bytesPerSecond} B/s — ETA ${p.eta}s`);
-  },
+```typescript
+const { user, session } = await auth.signup({
+  email:    'alice@example.com',
+  password: 'hunter2',           // min 8 characters, validated server-side
+  fullName: 'Alice Wonderland',
+  // Any extra fields are stored on the user record:
+  plan:     'pro',
+  referral: 'friend123',
 });
 
-if (data) {
-  console.log('Path:', data.path);
-  console.log('Space saved by compression:', data.spaceSaved, 'bytes');
-}
+// user.id          → "usr_xxxxxxxxxx"
+// session.sessionId → persist this in your app
+// session.refreshToken → persist this for long-lived sessions
 ```
 
-### Batch upload
-
-```ts
-const files = Array.from(fileInput.files);
-
-const { data } = await db.storage('documents').batchUpload(files, {
-  prefix:      'uploads/2024/',
-  overwrite:   false,
-  concurrency: 5,
+### Log In / Log Out
 
-  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}%`);
-  },
+```typescript
+// Log in
+const { user, session } = await auth.login({
+  email:    'alice@example.com',
+  password: 'hunter2',
 });
 
-console.log('Succeeded:', data!.succeeded.length);
-console.log('Failed:',    data!.failed.length);
-data!.failed.forEach(f => console.error(f.path, f.error));
+// Log out (invalidates the session server-side)
+await auth.logout({ sessionId: session.sessionId });
 ```
 
-### Download a file
+### Session Management
 
-```ts
-const { data: buffer, error } = await db.storage('documents').download('reports/q1.pdf');
+Sessions expire after **24 hours**. Use the refresh token to get a new session (refresh tokens last **30 days**).
 
-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);
+```typescript
+// Refresh the session before it expires
+const newSession = await auth.refreshSession({
+  refreshToken: session.refreshToken,
+});
+// Store newSession.sessionId and newSession.refreshToken
 
-  // In Node — write to disk
-  // import { writeFileSync } from 'fs';
-  // writeFileSync('q1.pdf', Buffer.from(buffer));
-}
+// Get the current user
+const user = await auth.getUser({ userId: session.userId });
 ```
 
-### List files
+### Update User Profile
 
-```ts
-const { data } = await db.storage('documents').list({
-  prefix: 'invoices/',
-  limit:  50,
+```typescript
+const updated = await auth.updateUser({
+  sessionId: session.sessionId,
+  userId:    user.id,
+  data: {
+    fullName: 'Alice Smith',
+    plan:     'enterprise',
+    avatar:   'https://example.com/avatar.jpg',
+  },
 });
-
-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
+### Password Reset Flow
 
-```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/');
+```typescript
+// 1. User requests a reset (always returns success — prevents email enumeration)
+await auth.requestPasswordReset({ email: 'alice@example.com' });
 
-// Move (rename) a file
-await db.storage('documents').move('drafts/report.pdf', 'published/report.pdf');
+// 2. User receives an email with a reset token (your app handles the email sending)
 
-// Copy a file (original kept)
-await db.storage('documents').copy('templates/invoice.pdf', 'invoices/inv-001.pdf');
+// 3. User submits the new password
+await auth.confirmPasswordReset({
+  resetToken:  'tok_from_email',
+  newPassword: 'correcthorsebatterystaple',
+});
+// All existing sessions for this user are automatically revoked
 ```
 
-### Signed URLs
-
-```ts
-// Generate a link that expires in 10 minutes
-const { data } = await db.storage('documents').signedUrl(
-  'contracts/nda.pdf',
-  { expiresIn: 600 }
-);
+### Change Password (authenticated)
 
-console.log(data!.signedUrl);   // share this URL
-console.log(data!.expiresAt);   // ISO timestamp when it expires
+```typescript
+await auth.changePassword({
+  sessionId:       session.sessionId,
+  userId:          user.id,
+  currentPassword: 'hunter2',
+  newPassword:     'correcthorsebatterystaple',
+});
 ```
 
-### Upload raw text / JSON
+### Email Verification
 
-```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' }
-);
-```
+```typescript
+// 1. Send verification email
+await auth.requestEmailVerification({ userId: user.id });
 
-### Stats
+// 2. User clicks link in email, your app extracts the token
 
-```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);
+// 3. Confirm the token
+await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
 ```
 
----
+### Admin Operations
 
-## 6. Error Handling
+Admin operations require a valid session from a user with `role: 'admin'`.
 
-Every method returns `{ data, error }`. `error` is `null` on success.
+```typescript
+// List all users
+const { users, total } = await auth.listUsers({
+  sessionId: adminSession.sessionId,
+  limit:     50,
+  offset:    0,
+});
 
-```ts
-const { data, error } = await db.storage('avatars').upload(file);
+// Lock an account (prevents login)
+await auth.lockAccount({
+  sessionId: adminSession.sessionId,
+  userId:    'usr_abc123',
+  duration:  60 * 60 * 1000, // lock for 1 hour (default: 15 minutes)
+});
 
-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)
-}
-```
+// Unlock an account
+await auth.unlockAccount({
+  sessionId: adminSession.sessionId,
+  userId:    'usr_abc123',
+});
 
-### Catching thrown errors
+// Soft-delete a user (marks as deleted, keeps data)
+await auth.deleteUser({
+  sessionId: adminSession.sessionId,
+  userId:    'usr_abc123',
+});
 
-```ts
-import { isHydrousError } from 'hydrousdb';
+// Hard-delete a user (permanent — irreversible)
+await auth.hardDeleteUser({
+  sessionId: adminSession.sessionId,
+  userId:    'usr_abc123',
+});
 
-try {
-  await db.storage('avatars').upload(file);
-} catch (err) {
-  if (isHydrousError(err)) {
-    console.error(err.code, err.message);
-  }
-}
+// Bulk delete multiple users
+const { deleted, failed } = await auth.bulkDeleteUsers({
+  sessionId: adminSession.sessionId,
+  userIds:   ['usr_a', 'usr_b', 'usr_c'],
+});
 ```
 
-### 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    |
+## File Storage
 
----
+HydrousDB Storage is backed by Google Cloud Storage. Your files live at:
+```
+hydrous-storage/{your-owner-id}/{your-path}
+```
+You never see or specify the owner prefix — the SDK handles it transparently.
 
-## 7. Real-World Examples — Next.js
+### Simple Upload
 
-### Shared client (lib/db.ts)
+For files up to **500 MB** when you don't need upload progress:
 
-```ts
-// lib/db.ts
-import { createClient } from 'hydrousdb';
+```typescript
+// Browser: upload from a file input
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
 
-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!,
-  },
+const result = await db.storage.upload(file, `uploads/${file.name}`, {
+  isPublic:  true,   // publicly accessible without auth
+  overwrite: false,  // throw if the file already exists
 });
-```
 
----
+console.log(result.publicUrl);   // CDN URL — usable anywhere
+console.log(result.downloadUrl); // null (it's public)
+console.log(result.size);        // bytes
+console.log(result.mimeType);    // auto-detected from extension
 
-### 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');
-  }
+// Node.js: upload from a Buffer
+import { readFileSync } from 'fs';
+const buffer = readFileSync('./report.pdf');
+const result = await db.storage.upload(buffer, 'reports/q3.pdf');
+console.log(result.downloadUrl); // requires X-Storage-Key to access
+```
 
-  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>
-  );
-}
+### Upload Raw JSON or Text
+
+```typescript
+const result = await db.storage.uploadRaw(
+  { theme: 'dark', language: 'en' },
+  'user-config/alice.json',
+  { isPublic: false },
+);
 ```
 
----
+### Large File Upload (with progress)
 
-### Records: Product listing with filters
+For files over 10 MB or when you need a progress bar. The file goes directly
+to GCS — your server never buffers it.
 
-```tsx
-// app/products/page.tsx
-import { db } from '@/lib/db';
-import { eq } from 'hydrousdb';
+```typescript
+// Step 1: Get a signed upload URL
+const { uploadUrl, path } = await db.storage.getUploadUrl({
+  path:     'videos/product-demo.mp4',
+  mimeType: 'video/mp4',
+  size:     file.size,
+  isPublic: true,
+});
 
-type Product = { id: string; name: string; price: number; inStock: boolean };
+// Step 2: Upload directly to GCS with progress
+await db.storage.uploadToSignedUrl(
+  uploadUrl,
+  file,
+  'video/mp4',
+  (percent) => {
+    progressBar.style.width = `${percent}%`;
+    console.log(`${percent}% uploaded`);
+  },
+);
 
-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,
-  });
+// Step 3: Confirm the upload (registers metadata)
+const result = await db.storage.confirmUpload({
+  path:     path,
+  mimeType: 'video/mp4',
+  isPublic: true,
+});
 
-  if (error) return <p>Error: {error.message}</p>;
-
-  return (
-    <ul>
-      {products.map(p => (
-        <li key={p.id}>
-          {p.name} — ${p.price}
-        </li>
-      ))}
-    </ul>
-  );
-}
+console.log(result.publicUrl); // ready to use
 ```
 
----
+### Batch Upload
 
-### Storage: Avatar upload with live progress bar
+```typescript
+// Get signed URLs for multiple files
+const { files } = await db.storage.getBatchUploadUrls([
+  { path: 'gallery/photo1.jpg', mimeType: 'image/jpeg', size: 204800, isPublic: true },
+  { path: 'gallery/photo2.jpg', mimeType: 'image/jpeg', size: 153600, isPublic: true },
+]);
 
-```tsx
-// components/AvatarUploader.tsx
-'use client';
-import { useState } from 'react';
-import { db } from '@/lib/db';
-import type { UploadProgress } from 'hydrousdb';
+// Upload each one
+for (const f of files) {
+  await db.storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
+}
 
-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);
+// Confirm all at once
+const results = await db.storage.batchConfirmUploads(
+  files.map(f => ({ path: f.path, mimeType: f.mimeType, isPublic: true }))
+);
+```
 
-  async function handleFileChange(e: React.ChangeEvent<HTMLInputElement>) {
-    const file = e.target.files?.[0];
-    if (!file) return;
+### Download Files
 
-    setError(null);
-    setProgress(null);
+```typescript
+// Private files require authentication — download as ArrayBuffer
+const buffer = await db.storage.download('reports/q3.pdf');
+const blob   = new Blob([buffer], { type: 'application/pdf' });
 
-    const { data, error } = await db.storage('avatars').upload(file, {
-      path:      `users/${userId}/avatar.jpg`,
-      overwrite: true,
+// In a browser: trigger a file download
+const url = URL.createObjectURL(blob);
+const a   = document.createElement('a');
+a.href    = url;
+a.download = 'q3.pdf';
+a.click();
 
-      onProgress: (p) => setProgress(p),
-    });
+// Public files: just use the publicUrl directly (no SDK needed)
+// <img src={result.publicUrl} />
+```
 
-    if (error) { setError(error.message); return; }
+### List Files
 
-    // 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);
-  }
+```typescript
+// List everything at the root
+const { files, folders } = await db.storage.list();
+
+// List a specific folder
+const { files, folders, hasMore, nextCursor } = await db.storage.list({
+  prefix:    'gallery/',
+  limit:     50,
+  recursive: false,
+});
 
-  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>
-  );
+// Paginate
+if (hasMore) {
+  const page2 = await db.storage.list({ prefix: 'gallery/', cursor: nextCursor });
 }
 ```
 
----
+Each file entry includes:
+```typescript
+{
+  name:        'photo1.jpg',
+  path:        'gallery/photo1.jpg',
+  size:        204800,
+  mimeType:    'image/jpeg',
+  isPublic:    true,
+  publicUrl:   'https://storage.googleapis.com/...',
+  downloadUrl: null,
+  updatedAt:   '2025-06-01T12:00:00.000Z',
+}
+```
 
-### Storage: Secure file download link (API route)
+### Scoped Storage
 
-```ts
-// app/api/download/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { db } from '@/lib/db';
+Working within a specific folder? Use `.scope()` to avoid typing the prefix on every call.
 
-export async function GET(req: NextRequest) {
-  const filePath = req.nextUrl.searchParams.get('file');
-  if (!filePath) return NextResponse.json({ error: 'file param required' }, { status: 400 });
+```typescript
+// All operations in the "user-avatars/" folder
+const avatars = db.storage.scope('user-avatars');
 
-  // Generate a short-lived signed URL (2 minutes)
-  const { data, error } = await db.storage('documents').signedUrl(filePath, {
-    expiresIn: 120,
-  });
+await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
+// → uploads to "user-avatars/{userId}.jpg"
 
-  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+const { files } = await avatars.list();
+// → lists files under "user-avatars/"
 
-  return NextResponse.json({ url: data!.signedUrl, expiresAt: data!.expiresAt });
-}
-```
+await avatars.deleteFile(`${userId}.jpg`);
+// → deletes "user-avatars/{userId}.jpg"
 
-```tsx
-// Usage in a component:
-// const res  = await fetch(`/api/download?file=contracts/nda.pdf`);
-// const { url } = await res.json();
-// window.open(url, '_blank');
+// Nest scopes
+const thumbnails = avatars.scope('thumbnails');
+// → all operations under "user-avatars/thumbnails/"
 ```
 
----
+### Share & Visibility
 
-### 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;
-}
-```
+```typescript
+// Get file metadata (sizes, URLs, visibility)
+const meta = await db.storage.getMetadata('reports/q3.pdf');
 
-```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>
-  );
-}
+// Generate a time-limited share link for a private file
+// (no auth key needed to use the link)
+const { signedUrl, expiresAt } = await db.storage.getSignedUrl(
+  'reports/q3.pdf',
+  3600,  // expires in 1 hour (default)
+);
+// Share signedUrl with whoever needs it
+
+// Toggle visibility after upload
+const result = await db.storage.setVisibility('reports/q3.pdf', true);  // make public
+const result2 = await db.storage.setVisibility('reports/q3.pdf', false); // make private
 ```
 
----
+### File Operations
 
-### Records: Server Action — create a product
+```typescript
+// Rename / move a file
+await db.storage.move('drafts/report.pdf', 'published/report-2025.pdf');
 
-```ts
-// app/products/actions.ts
-'use server';
-import { db } from '@/lib/db';
-import { revalidatePath } from 'next/cache';
+// Copy a file
+await db.storage.copy('templates/invoice.html', 'invoices/inv-001.html');
 
-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;
+// Create a folder
+await db.storage.createFolder('archive/2025/');
 
-  const { data, error } = await db.records.insert('products', {
-    name, price, category, inStock: true,
-  });
+// Delete a file
+await db.storage.deleteFile('temp/scratch.txt');
 
-  if (error) throw new Error(error.message);
+// Delete a folder and all its contents
+await db.storage.deleteFolder('temp/');
 
-  revalidatePath('/products');
-  return data[0];
-}
+// Get key-level stats
+const stats = await db.storage.getStats();
+// → { totalFiles: 842, totalBytes: 1073741824, uploadCount: 1200, ... }
 ```
 
 ---
 
-## 8. Real-World Examples — Vue 3
+## Analytics
 
-### Shared client (src/lib/db.ts)
+HydrousDB Analytics runs your queries against BigQuery, so they're fast even
+on millions of records. All queries accept an optional `dateRange` filter.
 
-```ts
-// src/lib/db.ts
-import { createClient } from 'hydrousdb';
+```typescript
+const analytics = db.analytics('orders');
+```
+
+### Count
+
+```typescript
+// Total records
+const { count } = await analytics.count();
 
-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,
+// Records in a date range
+const { count: lastWeek } = await analytics.count({
+  dateRange: {
+    start: Date.now() - 7 * 24 * 60 * 60 * 1000,
+    end:   Date.now(),
   },
 });
 ```
 
----
-
-### Auth: Login composable
+### Distribution
 
-```ts
-// composables/useAuth.ts
-import { ref } from 'vue';
-import { useRouter } from 'vue-router';
-import { db } from '@/lib/db';
+How many records have each unique value for a field?
 
-export function useAuth() {
-  const user    = ref(null);
-  const loading = ref(false);
-  const error   = ref<string | null>(null);
-  const router  = useRouter();
+```typescript
+const rows = await analytics.distribution({ field: 'status', limit: 10, order: 'desc' });
+// → [
+//   { value: 'completed', count: 8234 },
+//   { value: 'pending',   count: 1203 },
+//   { value: 'refunded',  count: 412  },
+// ]
+```
 
-  async function login(email: string, password: string) {
-    loading.value = true;
-    error.value   = null;
+### Sum
 
-    const { data, error: err } = await db.auth.signIn({ email, password });
+```typescript
+// Total revenue
+const rows = await analytics.sum({ field: 'amount' });
+// → [{ sum: 198432.50 }]
 
-    if (err) {
-      error.value = err.message;
-    } else {
-      user.value = data!.user as any;
-      localStorage.setItem('token', data!.accessToken);
-      router.push('/dashboard');
-    }
+// Revenue by country
+const byCountry = await analytics.sum({
+  field:   'amount',
+  groupBy: 'country',
+  limit:   10,
+});
+// → [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, ...]
+```
 
-    loading.value = false;
-  }
+### Time Series
 
-  async function logout() {
-    await db.auth.signOut();
-    user.value = null;
-    localStorage.removeItem('token');
-    router.push('/login');
-  }
+Record counts over time — ideal for activity charts.
 
-  return { user, loading, error, login, logout };
-}
+```typescript
+const rows = await analytics.timeSeries({
+  granularity: 'day',       // 'hour' | 'day' | 'week' | 'month' | 'year'
+  dateRange: {
+    start: new Date('2025-01-01').getTime(),
+    end:   new Date('2025-06-01').getTime(),
+  },
+});
+// → [{ date: '2025-01-01', count: 42 }, { date: '2025-01-02', count: 67 }, ...]
 ```
 
----
+Aggregate a field over time:
 
-### Storage: File upload with progress
-
-```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>
+```typescript
+const revenue = await analytics.fieldTimeSeries({
+  field:       'amount',
+  aggregation: 'sum',   // 'sum' | 'avg' | 'min' | 'max' | 'count'
+  granularity: 'week',
+});
+// → [{ date: '2025-W01', value: 12340.50 }, ...]
 ```
 
----
+### Top N
+
+Most common values for a field:
 
-### Records: Data table with pagination
+```typescript
+const topProducts = await analytics.topN({
+  field:      'productId',
+  labelField: 'productName',  // optional: include a human-readable label
+  n:          5,
+  order:      'desc',
+});
+// → [
+//   { value: 'prod_123', label: 'Widget Pro', count: 892 },
+//   { value: 'prod_456', label: 'Gizmo Plus', count: 743 },
+// ]
+```
 
-```vue
-<!-- components/ProductTable.vue -->
-<script setup lang="ts">
-import { ref, onMounted } from 'vue';
-import { db } from '@/lib/db';
-import { eq } from 'hydrousdb';
+### Field Stats
 
-type Product = { id: string; name: string; price: number; inStock: boolean };
+Statistical summary for any numeric field:
 
-const products = ref<Product[]>([]);
-const total    = ref(0);
-const page     = ref(1);
-const limit    = 10;
+```typescript
+const stats = await analytics.stats({ field: 'orderValue' });
+// → {
+//   min: 4.99,  max: 9999.99, avg: 87.23,
+//   sum: 420948.27, count: 4823, stddev: 143.2
+// }
+```
 
-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,
-  });
+### Multi-Metric Dashboard
 
-  if (error) { console.error(error.message); return; }
-  products.value = data;
-  total.value    = count;
-  page.value     = p;
-}
+Calculate several aggregations in a single BigQuery query:
 
-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>
+```typescript
+const dashboard = await analytics.multiMetric({
+  metrics: [
+    { field: 'amount',   name: 'totalRevenue',    aggregation: 'sum'   },
+    { field: 'amount',   name: 'avgOrderValue',   aggregation: 'avg'   },
+    { field: 'amount',   name: 'maxOrder',        aggregation: 'max'   },
+    { field: 'userId',   name: 'totalOrders',     aggregation: 'count' },
+  ],
+  dateRange: { start: new Date('2025-01-01').getTime(), end: Date.now() },
+});
+// → {
+//   totalRevenue:  198432.50,
+//   avgOrderValue: 87.23,
+//   maxOrder:      9999.99,
+//   totalOrders:   2275,
+// }
 ```
 
----
+### Filtered Records (BigQuery)
 
-### Vue: Batch file upload with per-file progress
+Query raw records with full BigQuery speed:
 
-```vue
-<!-- components/BatchUploader.vue -->
-<script setup lang="ts">
-import { ref } from 'vue';
-import { db } from '@/lib/db';
-import type { UploadProgress } from 'hydrousdb';
+```typescript
+const records = await analytics.records({
+  filters: [
+    { field: 'status', op: '==', value: 'refunded' },
+    { field: 'amount', op: '>',  value: 100         },
+  ],
+  selectFields: ['orderId', 'amount', 'userId', 'createdAt'],
+  orderBy: 'amount',
+  order:   'desc',
+  limit:   50,
+});
+```
 
-type FileState = { name: string; percent: number; stage: string; done: boolean; error?: string };
+### Cross-Bucket Comparison
 
-const fileStates = ref<FileState[]>([]);
+Compare the same metric across multiple buckets in one query:
 
-async function onFilesChange(event: Event) {
-  const files = Array.from((event.target as HTMLInputElement).files ?? []);
-  if (!files.length) return;
+```typescript
+const comparison = await analytics.crossBucket({
+  bucketKeys:  ['orders-us', 'orders-eu', 'orders-apac'],
+  field:       'amount',
+  aggregation: 'sum',
+});
+// → [
+//   { bucket: 'orders-us',   value: 120000 },
+//   { bucket: 'orders-eu',   value: 45000  },
+//   { bucket: 'orders-apac', value: 33000  },
+// ]
+```
 
-  fileStates.value = files.map(f => ({ name: f.name, percent: 0, stage: 'pending', done: false }));
+> ⚠️ Your Security Key must have read access to **all** buckets in the list.
 
-  await db.storage('documents').batchUpload(files, {
-    prefix: 'batch-uploads/',
+### Storage Stats
 
-    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>
+```typescript
+const stats = await analytics.storageStats();
+// → { totalRecords: 48210, totalBytes: 921600000, avgBytes: 19112, minBytes: 128, maxBytes: 5242880 }
 ```
 
 ---
 
-## 9. Real-World Examples — SvelteKit
+## TypeScript Support
 
-### Shared client
+The SDK is written in TypeScript and ships with full type definitions. Use generic
+type parameters to describe the shape of your records and get autocomplete throughout.
 
-```ts
-// src/lib/db.ts
+```typescript
 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,
-  },
-});
-```
-
-### 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,
-  });
+// Define your data models
+interface Order {
+  customerId: string;
+  items:      Array<{ productId: string; qty: number; price: number }>;
+  total:      number;
+  status:     'pending' | 'processing' | 'completed' | 'refunded';
+  country:    string;
+}
 
-  if (error) return json({ error: error.message }, { status: 500 });
-  return json(data);
+interface Customer {
+  name:    string;
+  email:   string;
+  tier:    'free' | 'pro' | 'enterprise';
+  credits: number;
 }
-```
 
-### Page load — server-side
+const db = createClient({ securityKey: process.env.HYDROUS_SECURITY_KEY! });
 
-```ts
-// src/routes/products/+page.server.ts
-import { db } from '$lib/db';
-import type { PageServerLoad } from './$types';
+// Fully typed clients
+const orders    = db.records<Order>('orders');
+const customers = db.records<Customer>('customers');
 
-export const load: PageServerLoad = async () => {
-  const { data: products, error } = await db.records.select('products', {
-    limit: 24,
-    orderBy: { field: 'createdAt', direction: 'desc' },
-  });
+// order.total, order.status, etc. are all type-safe
+const order = await orders.create({
+  customerId: 'cust_abc',
+  items:      [{ productId: 'prod_1', qty: 2, price: 29.99 }],
+  total:      59.98,
+  status:     'pending',
+  country:    'US',
+});
 
-  if (error) throw error;
-  return { products };
-};
+// TypeScript catches mistakes at compile time:
+// order.nonExistentField  // ← TS error ✓
+// order.status = 'invalid' // ← TS error ✓
 ```
 
-### 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}
+All exported types are available for import:
+
+```typescript
+import type {
+  HydrousConfig,
+  RecordResult,
+  QueryFilter,
+  QueryOptions,
+  UploadResult,
+  AnalyticsQuery,
+  DateRange,
+  // ... and many more
+} from 'hydrousdb';
 ```
 
 ---
 
-## 10. Real-World Examples — Express / Node API
-
-### Setup
+## Error Handling
 
-```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!,
-  },
-});
-```
+All errors thrown by the SDK extend `HydrousError`, which carries:
 
-### Upload from a file buffer (Node)
+| Property | Type | Description |
+|---|---|---|
+| `message` | `string` | Human-readable description |
+| `code` | `string` | Machine-readable error code (e.g. `"RECORD_NOT_FOUND"`) |
+| `status` | `number` | HTTP status code |
+| `requestId` | `string` | Server request ID (for support tracing) |
+| `details` | `string[]` | Validation error details |
 
-```ts
-// routes/upload.ts
-import express from 'express';
-import multer  from 'multer';
-import { db }  from '../db';
+```typescript
+import { HydrousError, NetworkError, AuthError } from 'hydrousdb';
 
-const router  = express.Router();
-const upload  = multer({ storage: multer.memoryStorage() });
+try {
+  const user = await auth.login({ email: 'a@b.com', password: 'wrong' });
+} catch (err) {
+  if (err instanceof AuthError) {
+    // Authentication-specific error
+    console.error(`Auth failed: ${err.code}`);
+    // err.code might be: INVALID_CREDENTIALS, ACCOUNT_LOCKED, EMAIL_NOT_VERIFIED, etc.
+  } else if (err instanceof NetworkError) {
+    // No internet / server unreachable
+    console.error('Cannot reach HydrousDB — check your internet connection');
+  } else if (err instanceof HydrousError) {
+    // Any other API error
+    console.error(`API error [${err.code}]: ${err.message}`);
+    console.error(`Request ID: ${err.requestId}`); // include this in support tickets
+  }
+}
+```
 
-router.post('/upload', upload.single('file'), async (req, res) => {
-  if (!req.file) return res.status(400).json({ error: 'No file' });
+**Common error codes:**
+
+| Code | Meaning |
+|---|---|
+| `RECORD_NOT_FOUND` | The requested record ID does not exist |
+| `INVALID_CREDENTIALS` | Wrong email or password |
+| `ACCOUNT_LOCKED` | The account is temporarily locked |
+| `INVALID_SESSION` | Session expired or revoked — re-authenticate |
+| `MISSING_API_KEY` | Security key not provided |
+| `INVALID_SECURITY_KEY` | Security key is wrong or revoked |
+| `FORBIDDEN` | Insufficient permissions |
+| `FILE_EXISTS` | File already exists at path (use `overwrite: true`) |
+| `LIMIT_EXCEEDED` | Storage quota or file size limit reached |
+| `SYSTEM_BUCKET_FORBIDDEN` | Cannot query system buckets via analytics |
+| `VALIDATION_ERROR` | Invalid input — check `err.details` |
+| `NETWORK_ERROR` | Failed to reach the API |
 
-  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 });
-});
+## Security Best Practices
 
-export default router;
-```
+1. **Never hard-code your Security Key.** Use environment variables:
 
-### Save JSON reports to storage
+   ```bash
+   # .env (add to .gitignore)
+   HYDROUS_SECURITY_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx
+   ```
 
-```ts
-// jobs/generateReport.ts
-import { db } from '../db';
+   ```typescript
+   const db = createClient({ securityKey: process.env.HYDROUS_SECURITY_KEY! });
+   ```
 
-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. **Never expose your Security Key to browsers.** For browser-side apps,
+   route requests through your own backend, or use per-user session tokens.
 
-  // 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 },
-  });
+3. **Your Security Key is sent via the `X-Api-Key` header — never in URLs.**
+   The SDK enforces this automatically, so keys never appear in server logs or
+   browser history.
 
-  return data!.path;
-}
-```
+4. **Rotate keys periodically.** Revoke old keys from the dashboard after rotation.
 
-### Batch delete old records
+5. **Use scoped storage** (`db.storage.scope(...)`) to isolate access by user or
+   feature, reducing the blast radius of any misconfiguration.
 
-```ts
-// scripts/cleanup.ts
-import { db } from '../db';
-import { lt } from 'hydrousdb';
+6. **Use `isPublic: false` (the default) for sensitive files.** Use signed URLs
+   for time-limited sharing instead of making files permanently public.
 
-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,
-  });
+## API Reference
 
-  if (!old.length) { console.log('Nothing to clean up'); return; }
+### `createClient(config)`
 
-  // Delete each one
-  await Promise.all(old.map((s: any) => db.records.delete('sessions', s.id)));
-  console.log(`Deleted ${old.length} expired sessions`);
-}
+Creates and returns a `HydrousClient` instance. Call this once and reuse the instance.
 
-cleanupOldSessions();
+```typescript
+const db = createClient({
+  securityKey: 'sk_live_...',   // Required — from https://hydrousdb.com/dashboard
+  baseUrl:     'https://...',   // Optional — defaults to official HydrousDB endpoint
+});
 ```
 
----
+### `db.records<T>(bucketKey)`
+
+Returns a `RecordsClient<T>` for the named bucket.
+
+| Method | Description |
+|---|---|
+| `create(data)` | Create a new record |
+| `get(id)` | Get a record by ID |
+| `set(id, data)` | Full replace |
+| `patch(id, data, opts?)` | Partial update (merge by default) |
+| `delete(id)` | Delete a record |
+| `query(opts?)` | Query with filters, sort, pagination |
+| `getAll(opts?)` | Shortcut for query without filters |
+| `count(filters?)` | Count matching records |
+| `batchCreate(items)` | Create multiple records |
+| `batchDelete(ids)` | Delete multiple records |
+| `getHistory(id)` | Get version history |
+| `restoreVersion(id, version)` | Restore to a version |
+
+### `db.auth(bucketKey)`
+
+Returns an `AuthClient` for the named user bucket.
+
+| Method | Description |
+|---|---|
+| `signup(opts)` | Register a new user |
+| `login(opts)` | Authenticate and create session |
+| `logout({ sessionId })` | Invalidate session |
+| `refreshSession({ refreshToken })` | Extend a session |
+| `getUser({ userId })` | Get user by ID |
+| `updateUser(opts)` | Update user fields |
+| `deleteUser(opts)` | Soft-delete a user |
+| `hardDeleteUser(opts)` | Permanently delete a user (admin) |
+| `listUsers(opts)` | List all users (admin) |
+| `bulkDeleteUsers(opts)` | Bulk delete (admin) |
+| `lockAccount(opts)` | Lock a user (admin) |
+| `unlockAccount(opts)` | Unlock a user (admin) |
+| `changePassword(opts)` | Change password (authenticated) |
+| `requestPasswordReset(opts)` | Send reset email |
+| `confirmPasswordReset(opts)` | Apply new password |
+| `requestEmailVerification(opts)` | Send verification email |
+| `confirmEmailVerification(opts)` | Verify email with token |
+
+### `db.analytics(bucketKey)`
+
+Returns an `AnalyticsClient` for the named bucket.
+
+| Method | Description |
+|---|---|
+| `count(opts?)` | Count records |
+| `distribution(opts)` | Value distribution for a field |
+| `sum(opts)` | Sum (with optional groupBy) |
+| `timeSeries(opts?)` | Records over time |
+| `fieldTimeSeries(opts)` | Field aggregation over time |
+| `topN(opts)` | Top N values for a field |
+| `stats(opts)` | Statistical summary for a field |
+| `records(opts?)` | Filtered raw records (BigQuery) |
+| `multiMetric(opts)` | Multiple aggregations in one query |
+| `storageStats(opts?)` | Bucket storage statistics |
+| `crossBucket(opts)` | Compare across multiple buckets |
+| `query(query)` | Raw analytics query |
+
+### `db.storage`
+
+The `StorageManager` instance. Also has `.scope(prefix)` for folder-scoped access.
+
+| Method | Description |
+|---|---|
+| `upload(data, path, opts?)` | Simple server-buffered upload |
+| `uploadRaw(data, path, opts?)` | Upload JSON/text data |
+| `getUploadUrl(opts)` | Step 1: Get signed GCS upload URL |
+| `uploadToSignedUrl(url, data, mime, onProgress?)` | Step 2: Upload to GCS directly |
+| `confirmUpload(opts)` | Step 3: Register upload metadata |
+| `getBatchUploadUrls(files)` | Batch signed upload URLs |
+| `batchConfirmUploads(items)` | Confirm batch uploads |
+| `download(path)` | Download private file |
+| `batchDownload(paths)` | Batch download |
+| `list(opts?)` | List files and folders |
+| `getMetadata(path)` | File metadata |
+| `getSignedUrl(path, expiresIn?)` | Time-limited share URL |
+| `setVisibility(path, isPublic)` | Toggle public/private |
+| `createFolder(path)` | Create a folder |
+| `deleteFile(path)` | Delete a file |
+| `deleteFolder(path)` | Delete a folder recursively |
+| `move(from, to)` | Move/rename |
+| `copy(from, to)` | Copy |
+| `getStats()` | Key-level stats |
+| `info()` | Server ping (no auth) |
+| `scope(prefix)` | Get a ScopedStorage instance |
 
-## 11. TypeScript Types Reference
+---
 
-### `HydrousConfig`
+## Contributing
 
-```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
-}
-```
+We love contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
-### `UploadProgress`
-
-```ts
-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;
-}
-```
+```bash
+# Clone the repo
+git clone https://github.com/hydrousdb/hydrousdb-js.git
+cd hydrousdb-js
 
-### `UploadResult`
+# Install dependencies
+npm install
 
-```ts
-interface UploadResult {
-  path:         string;
-  compressed:   boolean;
-  originalSize: number;
-  storedSize:   number;
-  spaceSaved:   number;
-  mimeType:     string;
-}
-```
+# Run tests
+npm test
 
-### `StorageItem`
-
-```ts
-interface StorageItem {
-  name:          string;
-  path:          string;
-  type:          'file' | 'folder';
-  size?:         number | null;
-  mimeType?:     string | null;
-  isCompressed?: boolean;
-  updatedAt?:    string | null;
-}
-```
+# Build
+npm run build
 
-### `StorageStats`
-
-```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%"
-}
+# Run tests in watch mode
+npm run test:watch
 ```
 
 ---
 
 ## License
 
-MIT © HydrousDB
+MIT — see [LICENSE](./LICENSE) for details.
+
+---
+
+<p align="center">
+  Built with ❤️ by the <a href="https://hydrousdb.com">HydrousDB</a> team.<br>
+  Questions? <a href="mailto:support@hydrousdb.com">support@hydrousdb.com</a> · 
+  <a href="https://github.com/hydrousdb/hydrousdb-js/issues">Open an issue</a>
+</p>