hydrousdb 3.0.2 → 3.2.0

package/README.md

@@ -18,45 +18,64 @@
 
 - [What is HydrousDB?](#what-is-hydrousdb)
 - [How It Works](#how-it-works)
-- [Quick Start (5 minutes)](#quick-start-5-minutes)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Module Formats — ESM & CommonJS](#module-formats--esm--commonjs)
 - [Records](#records)
   - [Create](#create-a-record)
   - [Read](#read-a-record)
-  - [Update](#update-a-record)
+  - [Update — patch vs set](#update-a-record)
   - [Delete](#delete-a-record)
   - [Query](#query-records)
-  - [Batch Operations](#batch-operations)
+  - [Count](#count-records)
+  - [Batch Create](#batch-create)
+  - [Batch Delete](#batch-delete)
   - [Version History](#version-history)
+  - [Write-Filter Sentinels](#write-filter-sentinels)
+  - [Custom Record IDs](#custom-record-ids)
 - [Authentication](#authentication)
-  - [Sign Up](#sign-up-users)
+  - [Sign Up](#sign-up)
   - [Log In / Log Out](#log-in--log-out)
   - [Session Management](#session-management)
-  - [Password Reset](#password-reset-flow)
+  - [Validate a Session](#validate-a-session)
+  - [Update Profile](#update-profile)
+  - [Change Password](#change-password)
+  - [Password Reset Flow](#password-reset-flow)
   - [Email Verification](#email-verification)
-  - [Admin Operations](#admin-operations)
+  - [Admin — List Users](#admin--list-users)
+  - [Admin — Lock / Unlock](#admin--lock--unlock)
+  - [Admin — Delete Users](#admin--delete-users)
 - [File Storage](#file-storage)
   - [Simple Upload](#simple-upload)
-  - [Large File Upload (with progress)](#large-file-upload-with-progress)
-  - [Download](#download-files)
+  - [Upload Raw JSON or Text](#upload-raw-json-or-text)
+  - [Large File Upload with Progress](#large-file-upload-with-progress)
+  - [Batch Upload](#batch-upload)
+  - [Download](#download)
+  - [Batch Download](#batch-download)
   - [List Files](#list-files)
   - [Scoped Storage](#scoped-storage)
-  - [Share & Visibility](#share--visibility)
-  - [File Operations](#file-operations)
+  - [File Metadata](#file-metadata)
+  - [Signed Share URLs](#signed-share-urls)
+  - [Visibility](#visibility)
+  - [Move, Copy, Delete](#move-copy-delete)
+  - [Storage Stats](#storage-stats)
 - [Analytics](#analytics)
-  - [Count](#count)
+  - [Count](#count-1)
   - [Distribution](#distribution)
   - [Sum](#sum)
   - [Time Series](#time-series)
+  - [Field Time Series](#field-time-series)
   - [Top N](#top-n)
   - [Field Stats](#field-stats)
   - [Multi-Metric Dashboard](#multi-metric-dashboard)
-  - [Filtered Records](#filtered-records-bigquery)
+  - [Filtered Records via BigQuery](#filtered-records-via-bigquery)
   - [Cross-Bucket Comparison](#cross-bucket-comparison)
-  - [Storage Stats](#storage-stats)
-- [TypeScript Support](#typescript-support)
+  - [Storage Stats](#storage-stats-1)
+  - [Raw Query](#raw-query)
+- [TypeScript](#typescript)
 - [Error Handling](#error-handling)
 - [Security Best Practices](#security-best-practices)
-- [API Reference](#api-reference)
+- [Full API Reference](#full-api-reference)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -64,36 +83,33 @@
 
 ## What is HydrousDB?
 
-Traditional databases start choking when your JSON records get large. Postgres hits row-size limits. Firestore charges per field read. MongoDB Atlas buckles under millions of 500 KB+ documents. They were designed for structured rows and small payloads — not the kind of deeply nested, real-world JSON that modern applications actually produce.
-
-HydrousDB is built specifically for that problem. It stores every record as a compressed GCS blob, retrieves any record in a single network call (no index lookups — the storage path is computed directly from the record ID), and runs analytics at BigQuery scale without ETL. The bigger and messier your JSON, the more it outperforms traditional databases.
+Traditional databases start choking when your JSON records get large. Postgres hits row-size limits. Firestore charges per field read. MongoDB buckles under millions of 500 KB+ documents. They were built for structured rows and small payloads — not the deeply nested, real-world JSON that modern apps actually produce.
 
-**Systems that benefit immediately:**
+HydrousDB is built specifically for that problem. It stores every record as a compressed GCS blob, retrieves any record in a single network call (the storage path is computed directly from the record ID — no index lookups), and runs analytics at BigQuery scale without ETL. The bigger and messier your JSON, the more it outperforms traditional databases.
 
 | Domain | Example records | Why traditional DBs struggle |
 |---|---|---|
-| 🏥 **Hospital / EMR** | Full patient charts — vitals history, medication lists, clinical notes, imaging metadata | 850 KB+ per chart, millions of patients, strict audit trails |
-| 🎓 **School management** | Student portfolios — all grades, attendance, assessments, teacher notes across years | Deep nesting, bursty writes at term-end, long-term archival |
-| 🏭 **IoT / Industrial** | Sensor telemetry — time-stamped readings, device state, calibration metadata | Billions of records, append-heavy, rarely updated |
-| 🛒 **E-commerce** | Order records — line items, fulfilment events, return history, custom attributes | Highly variable shape, needs fast analytics across date ranges |
-| ⚖️ **Legal / compliance** | Case files — filings, correspondence, version history, linked documents | 1 MB+ records, immutable audit log, cross-case analytics |
-| 🎮 **Gaming** | Player save states — inventory, quest progress, achievement history, replay data | Large payloads, millions of concurrent users, burst writes |
-| 📡 **Logistics / tracking** | Shipment records — full event timeline, customs data, carrier metadata | Append-only events, heavy querying by date range and status |
+| 🏥 **Hospital / EMR** | Full patient charts — vitals, medications, notes, imaging | 850 KB+ per chart, millions of patients, strict audit trails |
+| 🎓 **School management** | Student portfolios — grades, assessments, teacher notes | Deep nesting, bursty writes at term-end, long-term archival |
+| 🏭 **IoT / Industrial** | Sensor telemetry — readings, device state, calibration | Billions of records, append-heavy, rarely updated |
+| 🛒 **E-commerce** | Orders — line items, fulfilment events, return history | Variable shape, fast analytics across date ranges |
+| ⚖️ **Legal / compliance** | Case files — filings, correspondence, version history | 1 MB+ records, immutable audit log, cross-case analytics |
+| 🎮 **Gaming** | Player save states — inventory, quest progress, replays | Large payloads, millions of users, burst writes |
 
 **What you get out of the box:**
 
 | Feature | What it does |
 |---|---|
-| **Records** | Schemaless JSON store. Billion-scale, gzip-compressed, date-encoded IDs for zero-lookup retrieval. Up to 1 MB per record. |
-| **Auth** | Full user authentication — signup, login, sessions, password reset, email verification, and admin controls. |
-| **Storage** | File uploads backed by Google Cloud Storage. Direct-to-GCS uploads, public/private visibility, signed share URLs. |
-| **Analytics** | BigQuery-powered aggregations — counts, distributions, time series, top-N, multi-metric dashboards, cross-bucket comparisons. Zero ETL. |
+| **Records** | Schemaless JSON store. Billion-scale, gzip-compressed, date-encoded IDs for zero-lookup retrieval. |
+| **Auth** | Full user system — signup, login, sessions, password reset, email verification, admin controls. |
+| **Storage** | File uploads to GCS. Direct uploads, public/private visibility, signed share URLs. |
+| **Analytics** | BigQuery-powered — counts, distributions, time series, top-N, cross-bucket. Zero ETL. |
 
 ---
 
 ## How It Works
 
-Every HydrousDB record ID encodes its creation date as a prefix (e.g. `260203-rec_01JA2XYZ`). This means the full storage path to any record can be computed in memory — no index lookup, no pointer chase. Just math.
+Every record ID encodes its creation date as a prefix (e.g. `260203-rec_01JA2XYZ`). This means the full GCS storage path to any record can be computed in memory — no index lookup needed.
 
 ```
 260203-rec_01JA2XYZ
@@ -105,201 +121,258 @@ projects/pid/buckets/bk/records/26/02/03/rec_01JA.json.gz
 0 index reads ✓
 ```
 
-Records are gzip-compressed on write (typically 60–80% size reduction). A full 850 KB hospital patient chart compresses to ~255 KB on disk — automatically, every time. Records age through storage tiers (Standard → Nearline → Coldline → Archive) as they get older, keeping historical data accessible without manual lifecycle management.
-
-This architecture means HydrousDB handles what breaks other databases:
-- **Huge records** — up to 1 MB per document, compressed
-- **Append-heavy workloads** — IoT telemetry, audit logs, event streams
-- **Date-range queries at scale** — the ID prefix enables efficient folder scans without a full table scan
-- **Long-term retention** — billions of records stay queryable via BigQuery without any migration
+Records are gzip-compressed on write (60–80% size reduction). An 850 KB hospital chart becomes ~255 KB on disk, automatically, every time.
 
 ---
 
-## Quick Start (5 minutes)
-
-### Step 1 — Create your account
+## Quick Start
 
-Go to **[https://hydrousdb.com](https://hydrousdb.com)** and sign up for a free account.
+### 1. Create your account
 
-### Step 2 — Create your first bucket
+Sign up at [https://hydrousdb.com](https://hydrousdb.com).
 
-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"**.
+### 2. Get your API keys
 
-> 💡 **What is a bucket?** A bucket is a named collection of JSON records — similar to a table in SQL or a collection in MongoDB.
-
-### Step 3 — Grab your API Keys
-
-HydrousDB uses three separate keys, each scoped to a service:
+From the dashboard → **Settings → API Keys**, create three key types:
 
 | Key | Prefix | Used for |
 |---|---|---|
-| **Auth Key** | `hk_auth_…` | All `/auth/*` routes — signup, login, sessions |
+| **Auth Key** | `hk_auth_…` | All auth routes — signup, login, sessions |
 | **Bucket Security Key** | `hk_bucket_…` | Records and analytics |
 | **Storage Key(s)** | `ssk_…` | File storage — one key per storage bucket |
 
-1. In the dashboard go to **Settings → API Keys**.
-2. Generate each key type you need.
-3. Copy them — you'll use all three when initialising the client.
-
-> ⚠️ **These keys are your credentials.** Treat them like passwords. Never commit them to Git. Use environment variables.
+> ⚠️ Never commit these to Git. Store them in environment variables.
 
-### Step 4 — Install the SDK
+### 3. Install
 
 ```bash
 npm install hydrousdb
-# or
-yarn add hydrousdb
-# or
-pnpm add hydrousdb
+# or: yarn add hydrousdb  /  pnpm add hydrousdb
 ```
 
 **Requirements:** Node.js 18+ (uses the native `fetch` API).
 
-### Step 5 — Your first record
+### 4. Create the client and write your first record
 
 ```typescript
 import { createClient } from 'hydrousdb';
 
-// Create the client once — reuse it everywhere
+// Create once — reuse everywhere in your app
 const db = createClient({
-  authKey:           process.env.HYDROUS_AUTH_KEY!,           // hk_auth_…
-  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,         // hk_bucket_…
+  authKey:           process.env.HYDROUS_AUTH_KEY!,
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
   storageKeys: {
-    main: process.env.HYDROUS_STORAGE_MAIN!,                  // ssk_…
+    main: process.env.HYDROUS_STORAGE_MAIN!,
   },
 });
 
-// Write a record to your bucket
-const post = await db.records('my-first-bucket').create({
+// Write
+const post = await db.records('my-bucket').create({
   title:     'Hello, HydrousDB!',
-  body:      'My first record.',
   published: false,
 });
 
 console.log(post.id);        // "260601-rec_01JA2XYZ"
 console.log(post.createdAt); // 1717200000000
 
-// Read it back — zero database reads, path computed from ID
-const fetched = await db.records('my-first-bucket').get(post.id);
-console.log(fetched.title);  // "Hello, HydrousDB!"
+// Read back — zero database reads, path computed from ID
+const fetched = await db.records('my-bucket').get(post.id);
+
+// Update
+await db.records('my-bucket').patch(post.id, { published: true });
+
+// Delete
+await db.records('my-bucket').delete(post.id);
+```
+
+---
+
+## Installation
+
+```bash
+npm install hydrousdb
+```
+
+### Module Formats — ESM & CommonJS
+
+The package ships both ESM (`.mjs`) and CommonJS (`.cjs`) builds. Your toolchain picks the right one automatically based on your `import` or `require` call.
 
-// Update it
-await db.records('my-first-bucket').patch(post.id, { published: true });
+```typescript
+// ESM — Next.js, Vite, modern Node, TypeScript
+import { createClient } from 'hydrousdb';
+```
 
-// Delete it
-await db.records('my-first-bucket').delete(post.id);
+```javascript
+// CommonJS — legacy Node, Jest without transform, older tooling
+const { createClient } = require('hydrousdb');
 ```
 
-🎉 **That's it.** You're live.
+Both exports are listed explicitly in `package.json` under the `exports` field:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import":  "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types":   "./dist/index.d.ts"
+    }
+  }
+}
+```
+
+**Using with Next.js?** If Next.js resolves the CJS build instead of ESM (common with the Pages Router or older Next configs), add this to `next.config.js`:
+
+```javascript
+const nextConfig = {
+  webpack(config) {
+    config.resolve.conditionNames = ['import', 'module', 'require', 'default'];
+    return config;
+  },
+};
+```
 
 ---
 
 ## Records
 
 Records are JSON objects stored in named buckets. Every record automatically gets:
-- `id` — date-prefixed unique identifier (e.g. `"260601-rec_01JA2XYZ"`) — encodes storage path
+
+- `id` — date-prefixed unique identifier (`"260601-rec_01JA2XYZ"`) — encodes the GCS path
 - `createdAt` — Unix timestamp in milliseconds
-- `updatedAt` — Unix timestamp in milliseconds (updated on every write)
+- `updatedAt` — Unix timestamp in milliseconds
 
-Records are gzip-compressed before storage. A 850 KB EMR chart becomes ~255 KB on disk. You never manage this — it's always on.
+```typescript
+const posts = db.records('blog-posts');
+// or typed:
+const orders = db.records<Order>('orders');
+```
 
 ### Create a Record
 
 ```typescript
-const products = db.records('products');
-
-const product = await products.create({
-  name:    'Wireless Headphones',
-  price:   79.99,
-  inStock: true,
-  tags:    ['audio', 'wireless'],
+const post = await posts.create({
+  title:  'My First Post',
+  body:   'Hello world.',
+  status: 'draft',
+  views:  0,
 });
 
-// product.id, product.createdAt, product.updatedAt are added automatically
+// post.id, post.createdAt, post.updatedAt are added automatically
+console.log(post.id); // "260601-rec_01JA2XYZ"
 ```
 
+**With queryable fields** — fields you want to filter on server-side must be declared at write time:
+
+```typescript
+const post = await posts.create(
+  {
+    title:    'My First Post',
+    status:   'draft',
+    authorId: 'usr_abc',
+  },
+  {
+    queryableFields: ['status', 'authorId'],   // index these for filtering
+    userEmail:       'alice@example.com',       // optional audit trail
+  },
+);
+```
+
+> 💡 **Why declare queryable fields?** HydrousDB stores records as compressed blobs. Fields you want to filter or sort by need to be registered in a lightweight index at write time. You only pay index overhead for the fields you actually query.
+
 ### Read a Record
 
 ```typescript
-// Get by ID — the storage path is derived from the ID in memory, no index read
-const product = await products.get('rec_abc123');
+// Path computed from the ID in memory — zero index reads
+const post = await posts.get('260601-rec_01JA2XYZ');
 
-// Throws HydrousError with code RECORD_NOT_FOUND if missing
+// Throws HydrousError (code: RECORD_NOT_FOUND) if the ID doesn't exist
 ```
 
 ### Update a Record
 
+**`patch(id, data)` — merge update.** Only the fields you provide are changed. All other fields on the record are left untouched.
+
 ```typescript
-// Patch (merge) — only the specified fields are changed
-const updated = await products.patch('rec_abc123', {
-  price:   69.99,
-  inStock: false,
+const updated = await posts.patch('260601-rec_01JA2XYZ', {
+  status: 'published',
+  views:  1,
 });
+```
 
-// 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'],
+**`set(id, data)` — full replace.** The entire record is replaced with the new data.
+
+```typescript
+const replaced = await posts.set('260601-rec_01JA2XYZ', {
+  title:  'Updated Title',
+  body:   'New content.',
+  status: 'published',
+  views:  42,
 });
 ```
 
+**Disable merge** (force field removal):
+
+```typescript
+// merge: false means fields not in `data` are removed
+await posts.patch('260601-rec_01JA2XYZ', { status: 'archived' }, { merge: false });
+```
+
 ### Delete a Record
 
 ```typescript
-await products.delete('rec_abc123');
+await posts.delete('260601-rec_01JA2XYZ');
 ```
 
 ### Query Records
 
 ```typescript
-// Get all records (up to 100 by default)
-const { records } = await products.query();
+// All records (up to 100 by default)
+const { records } = await posts.query();
 
 // With filters
-const { records: affordableStock } = await products.query({
+const { records: published } = await posts.query({
   filters: [
-    { field: 'inStock', op: '==', value: true },
-    { field: 'price',   op: '<',  value: 100  },
+    { field: 'status', op: '==', value: 'published' },
   ],
 });
 
-// Sort and paginate
-const { records, hasMore, nextCursor } = await products.query({
-  orderBy: 'price',
-  order:   'asc',
+// Multiple filters, sort, limit
+const { records, hasMore, nextCursor } = await posts.query({
+  filters: [
+    { field: 'status',   op: '==', value: 'published' },
+    { field: 'views',    op: '>',  value: 100          },
+  ],
+  orderBy: 'createdAt',
+  order:   'desc',
   limit:   20,
 });
 
 // Next page
 if (hasMore) {
-  const page2 = await products.query({
-    orderBy:    'price',
-    order:      'asc',
+  const page2 = await posts.query({
+    orderBy:    'createdAt',
+    order:      'desc',
     limit:      20,
     startAfter: nextCursor,
   });
 }
 
-// Select specific fields only
-const { records: lightRecords } = await products.query({
-  fields: 'name,price,inStock',
+// Select only specific fields (reduces payload size)
+const { records: light } = await posts.query({
+  fields: 'id,title,status,createdAt',
 });
 
-// Filter by date range
-const { records: recent } = await products.query({
+// Date range
+const { records: thisWeek } = await posts.query({
   dateRange: {
-    start: Date.now() - 7 * 24 * 60 * 60 * 1000, // 7 days ago
+    start: Date.now() - 7 * 24 * 60 * 60 * 1000,
     end:   Date.now(),
   },
 });
 ```
 
-**Available filter operators:**
+**Filter operators:**
 
 | Operator | Meaning |
 |---|---|
@@ -309,68 +382,162 @@ const { records: recent } = await products.query({
 | `<` | Less than |
 | `>=` | Greater than or equal |
 | `<=` | Less than or equal |
-| `CONTAINS` | String contains (case-sensitive) |
+| `CONTAINS` | String contains |
+
+> ⚠️ You can only filter on fields declared as `queryableFields` when the record was created. Filtering on an un-indexed field returns no results.
+
+### Count Records
+
+```typescript
+// Total records in the bucket
+const total = await posts.count();
+
+// Records matching filters
+const publishedCount = await posts.count([
+  { field: 'status', op: '==', value: 'published' },
+]);
+```
+
+### Batch Create
 
-### Batch Operations
+Up to 500 records per call.
 
 ```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  },
+const created = await posts.batchCreate(
+  [
+    { title: 'Post A', status: 'draft' },
+    { title: 'Post B', status: 'draft' },
+    { title: 'Post C', status: 'published' },
+  ],
+  {
+    queryableFields: ['status'],
+    userEmail:       'alice@example.com',
+  },
+);
+// → [{ id: '…', title: 'Post A', … }, { id: '…', title: 'Post B', … }, …]
+```
+
+Each record in the batch can optionally carry a `_customRecordId` for upsert behaviour:
+
+```typescript
+await posts.batchCreate([
+  { _customRecordId: '260601-post_welcome', title: 'Welcome', status: 'published' },
+  { title: 'Auto-ID post', status: 'draft' },
 ]);
-// → [{ id: '260601-rec_1', ... }, { id: '260601-rec_2', ... }, ...]
+```
+
+### Batch Delete
 
-// Count records
-const total   = await products.count();
-const inStock = await products.count([{ field: 'inStock', op: '==', value: true }]);
+Up to 500 records per call.
 
-// Get all records without filters (shortcut for query)
-const all = await products.getAll({ orderBy: 'price', order: 'asc' });
+```typescript
+const { deleted, failed } = await posts.batchDelete([
+  '260601-rec_01JA',
+  '260601-rec_02JB',
+  '260601-rec_03JC',
+]);
 
-// Delete multiple records
-const { deleted, failed } = await products.batchDelete(['rec_1', 'rec_2', 'rec_3']);
+console.log(`Deleted: ${deleted}, Failed: ${failed.length}`);
 ```
 
 ### Version History
 
-Every write to a record creates a new version, so you can travel back in time.
+Every write creates a new version — you can restore any record to any previous state.
+
+```typescript
+// Get the full history list (most recent first)
+const history = await posts.getHistory('260601-rec_01JA2XYZ');
+// [{ id, version: 3, createdAt, data }, { version: 2, … }, { version: 1, … }]
+
+// Restore to version 1 (the original)
+const restored = await posts.restoreVersion('260601-rec_01JA2XYZ', history[2]!.version);
+```
+
+### Write-Filter Sentinels
+
+For atomic server-side field operations — use these inside `patch()` to avoid race conditions.
+
+```typescript
+await posts.patch('260601-rec_01JA', {
+  // Increment / decrement a numeric field atomically
+  views:    { __op: 'increment', delta: 1 },
+  credits:  { __op: 'decrement', delta: 5 },
+
+  // Set a field only if it doesn't already have a value
+  slug:     { __op: 'setOnce', value: 'my-first-post' },
+
+  // Set a field only if a condition is met
+  discount: { __op: 'setIf', value: 10, cond: { op: '>=', value: 100 } },
+
+  // Add to an array (no duplicates)
+  tags:     { __op: 'appendUnique', item: 'featured' },
+
+  // Remove from an array
+  tags:     { __op: 'removeFromArray', item: 'draft' },
+
+  // Clamp a numeric value between min and max
+  rating:   { __op: 'clamp', value: 6, min: 0, max: 5 },
+
+  // Multiply a numeric field
+  price:    { __op: 'multiplyBy', factor: 1.1 },
+
+  // Flip a boolean
+  active:   { __op: 'toggleBool' },
+
+  // Set field to the server's current timestamp
+  lastSeen: { __op: 'serverTimestamp' },
+} as any);
+```
+
+### Custom Record IDs
+
+Provide your own ID instead of using an auto-generated one. If the ID already exists, the record is upserted.
 
 ```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.
+// Single record
+const post = await posts.create(
+  { title: 'Welcome', status: 'published' },
+  { customRecordId: '260601-post_welcome' },
+);
 
-// Restore to a specific version
-const restored = await products.restoreVersion('rec_abc123', history[2]!.version);
+// Batch — set _customRecordId on individual items
+await posts.batchCreate([
+  { _customRecordId: '260601-post_welcome', title: 'Welcome' },
+  { title: 'Auto-ID post' },
+]);
 ```
 
+Custom IDs must match `^[a-zA-Z_][a-zA-Z0-9_.\-]{0,200}$`.
+
 ---
 
 ## 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.
+HydrousDB has a complete user auth system. Your users live in a bucket you name (e.g. `"app-users"`). You get sessions, refresh tokens, password reset, email verification, and admin controls — all built in.
 
 ```typescript
 const auth = db.auth('app-users');
 ```
 
-### Sign Up Users
+### Sign Up
 
 ```typescript
 const { user, session } = await auth.signup({
   email:    'alice@example.com',
-  password: 'hunter2',         // min 8 characters, validated server-side
+  password: 'hunter2',          // validated server-side
   fullName: 'Alice Wonderland',
   // Any extra fields are stored on the user record:
   plan:     'pro',
   referral: 'friend123',
 });
 
-// user.id              → "usr_xxxxxxxxxx"
-// session.sessionId    → persist this in your app
-// session.refreshToken → persist this for long-lived sessions
+// Persist these in your app / session store:
+// session.sessionId
+// session.refreshToken
+// session.expiresAt
+
+console.log(user.id);             // "usr_xxxxxxxxxxxx"
+console.log(user.emailVerified);  // false — send a verification email
 ```
 
 ### Log In / Log Out
@@ -382,56 +549,61 @@ const { user, session } = await auth.login({
   password: 'hunter2',
 });
 
-// Log out (invalidates the session server-side)
+// Log out — invalidates the session server-side
 await auth.logout({ sessionId: session.sessionId });
+
+// Log out from all devices at once
+await auth.logout({ sessionId: session.sessionId, allDevices: true });
 ```
 
 ### Session Management
 
-Sessions expire after **24 hours**. Use the refresh token to get a new session — refresh tokens last **30 days**.
+Sessions expire after **24 hours**. Refresh tokens last **30 days**.
 
 ```typescript
-// Refresh the session before it expires
+// Refresh before expiry to get a new session
 const newSession = await auth.refreshSession({
   refreshToken: session.refreshToken,
 });
 // Store newSession.sessionId and newSession.refreshToken
 
-// Get the current user
+// Get a user by ID
 const user = await auth.getUser({ userId: session.userId });
 ```
 
-### Update User Profile
+### Validate a Session
+
+Use this on your backend to verify an incoming session is still active.
+
+```typescript
+const { user, session: activeSession } = await auth.validateSession({
+  sessionId: session.sessionId,
+});
+
+console.log(user.id);                  // "usr_xxxxxxxxxxxx"
+console.log(activeSession.expiresAt);  // timestamp
+```
+
+### Update Profile
 
 ```typescript
 const updated = await auth.updateUser({
   sessionId: session.sessionId,
   userId:    user.id,
-  data: {
+  updates: {
     fullName: 'Alice Smith',
     plan:     'enterprise',
+    // Any field on the user record can be updated here
     avatar:   'https://example.com/avatar.jpg',
   },
 });
 ```
 
-### Password Reset Flow
+> ⚠️ The `updates` key is required — it wraps the fields to change. Fields not included in `updates` are left untouched.
 
-```typescript
-// 1. User requests a reset (always returns success — prevents email enumeration)
-await auth.requestPasswordReset({ email: 'alice@example.com' });
+### Change Password
 
-// 2. User receives an email with a reset token
-
-// 3. User submits the new password
-await auth.confirmPasswordReset({
-  resetToken:  'tok_from_email',
-  newPassword: 'correcthorsebatterystaple',
-});
-// All existing sessions for this user are automatically revoked
-```
-
-### Change Password (authenticated)
+Requires an active session — so a stolen old password alone is not enough.
 
 ```typescript
 await auth.changePassword({
@@ -440,61 +612,112 @@ await auth.changePassword({
   currentPassword: 'hunter2',
   newPassword:     'correcthorsebatterystaple',
 });
+// All existing sessions for this user are automatically revoked
+```
+
+### Password Reset Flow
+
+```typescript
+// 1. User requests a reset — always returns success (prevents email enumeration)
+await auth.requestPasswordReset({ email: 'alice@example.com' });
+
+// 2. User receives the reset token via email (handled by your email provider)
+
+// 3. User submits the token + new password
+await auth.confirmPasswordReset({
+  resetToken:  'tok_from_email',
+  newPassword: 'correcthorsebatterystaple',
+});
+// All existing sessions are automatically revoked
 ```
 
 ### Email Verification
 
 ```typescript
-// 1. Send verification email
+// 1. Send the verification email
 await auth.requestEmailVerification({ userId: user.id });
 
-// 2. User clicks link in email, your app extracts the token
+// 2. User clicks link in their inbox — your app extracts the token from the URL
 
 // 3. Confirm the token
 await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
 ```
 
-### Admin Operations
+### Admin — List Users
 
 Admin operations require a valid session from a user with `role: 'admin'`.
 
 ```typescript
-// List all users
-const { users, total } = await auth.listUsers({
+// Paginated list — uses cursor-based pagination
+const { users, hasMore, nextCursor } = await auth.listUsers({
   sessionId: adminSession.sessionId,
   limit:     50,
-  offset:    0,
 });
 
+if (hasMore) {
+  const page2 = await auth.listUsers({
+    sessionId: adminSession.sessionId,
+    limit:     50,
+    cursor:    nextCursor!,
+  });
+}
+```
+
+Each user in the list includes:
+
+```typescript
+{
+  id:            'usr_xxxxxxxxxxxx',
+  email:         'alice@example.com',
+  fullName:      'Alice Wonderland',
+  emailVerified: true,
+  accountStatus: 'active',  // 'active' | 'locked' | 'suspended'
+  role:          'user',    // 'user' | 'admin'
+  createdAt:     1717200000000,
+  updatedAt:     1717200000000,
+  // ...any extra fields stored at signup
+}
+```
+
+### Admin — Lock / Unlock
+
+```typescript
 // Lock an account (prevents login)
-await auth.lockAccount({
+const { lockedUntil, unlockTime } = await auth.lockAccount({
   sessionId: adminSession.sessionId,
   userId:    'usr_abc123',
-  duration:  60 * 60 * 1000, // lock for 1 hour (default: 15 minutes)
+  duration:  60 * 60 * 1000, // 1 hour in ms (default: 15 minutes)
 });
 
-// Unlock an account
+console.log(`Account locked until ${unlockTime}`);
+
+// Unlock manually
 await auth.unlockAccount({
   sessionId: adminSession.sessionId,
   userId:    'usr_abc123',
 });
+```
 
-// Soft-delete a user (marks as deleted, keeps data)
+### Admin — Delete Users
+
+```typescript
+// Soft-delete — marks the account as deleted, keeps the data
 await auth.deleteUser({
   sessionId: adminSession.sessionId,
   userId:    'usr_abc123',
 });
 
-// Hard-delete a user (permanent — irreversible)
+// Hard-delete — permanent, irreversible
 await auth.hardDeleteUser({
   sessionId: adminSession.sessionId,
   userId:    'usr_abc123',
 });
 
-// Bulk delete multiple users
-const { deleted, failed } = await auth.bulkDeleteUsers({
+// Bulk delete — up to 500 users, soft or hard
+const { succeeded, failed } = await auth.bulkDeleteUsers({
   sessionId: adminSession.sessionId,
   userIds:   ['usr_a', 'usr_b', 'usr_c'],
+  hard:      false, // set true for permanent deletion
 });
 ```
 
@@ -502,66 +725,74 @@ const { deleted, failed } = await auth.bulkDeleteUsers({
 
 ## File Storage
 
-HydrousDB Storage is backed by Google Cloud Storage. Storage keys (`ssk_…`) are scoped per bucket, so you can give different parts of your app different levels of access.
+HydrousDB Storage is backed by Google Cloud Storage. Storage keys (`ssk_…`) are scoped per bucket — you can give different parts of your app different permissions.
 
 ```typescript
-// Pick a storage key by the name you gave it in storageKeys
-const files     = db.storage('main');
+const main      = db.storage('main');
 const avatars   = db.storage('avatars');
 const documents = db.storage('documents');
 ```
 
 ### Simple Upload
 
-For files up to **500 MB** when you don't need upload progress:
+Server-buffered upload for files up to **500 MB**. No progress bar — use [Large File Upload](#large-file-upload-with-progress) if you need one.
 
 ```typescript
-// Browser: upload from a file input
-const file = document.querySelector('input[type="file"]').files[0];
-
+// Browser — from a file input
+const file   = document.querySelector('input[type="file"]').files[0];
 const result = await db.storage('main').upload(file, `uploads/${file.name}`, {
-  isPublic:  true,   // publicly accessible without auth
-  overwrite: false,  // throw if the file already exists
+  isPublic:  true,   // publicly accessible without auth (default: false)
+  overwrite: false,  // throw if file already exists (default: false)
+  mimeType:  'image/jpeg', // optional — auto-detected from extension if omitted
 });
 
-console.log(result.publicUrl);   // CDN URL — usable anywhere
-console.log(result.downloadUrl); // null (it's public)
+console.log(result.publicUrl);   // CDN URL — use anywhere
+console.log(result.downloadUrl); // null when isPublic: true
 console.log(result.size);        // bytes
-console.log(result.mimeType);    // auto-detected from extension
+console.log(result.mimeType);    // 'image/jpeg'
 
-// Node.js: upload from a Buffer
+// Node.js — from a Buffer or file path
 import { readFileSync } from 'fs';
-const buffer = readFileSync('./report.pdf');
-const result = await db.storage('documents').upload(buffer, 'reports/q3.pdf');
-console.log(result.downloadUrl); // requires X-Storage-Key to access
+const buf    = readFileSync('./report.pdf');
+const result = await db.storage('documents').upload(buf, 'reports/q3.pdf');
+console.log(result.downloadUrl); // auth-required download URL
 ```
 
 ### Upload Raw JSON or Text
 
 ```typescript
+// Upload a JS object as JSON
 const result = await db.storage('main').uploadRaw(
-  { theme: 'dark', language: 'en' },
-  'user-config/alice.json',
+  { theme: 'dark', language: 'en', version: 3 },
+  'settings/alice.json',
   { isPublic: false },
 );
+
+// Upload a plain string
+await db.storage('main').uploadRaw(
+  '<html><body>Hello</body></html>',
+  'exports/page.html',
+  { mimeType: 'text/html', isPublic: true },
+);
 ```
 
-### Large File Upload (with progress)
+### Large File Upload with Progress
 
-For files over 10 MB or when you need a progress bar. The file goes directly to GCS — your server never buffers it.
+For files over ~10 MB or when you need a progress bar. The file goes **directly to GCS** — your server never buffers the bytes.
 
 ```typescript
 const storage = db.storage('main');
 
-// Step 1: Get a signed upload URL
+// Step 1 — Get a signed GCS upload URL
 const { uploadUrl, path } = await storage.getUploadUrl({
-  path:     'videos/product-demo.mp4',
-  mimeType: 'video/mp4',
-  size:     file.size,
-  isPublic: true,
+  path:            'videos/product-demo.mp4',
+  mimeType:        'video/mp4',
+  size:            file.size,
+  isPublic:        true,
+  expiresInSeconds: 900, // how long the signed URL is valid (default: 900 = 15 min)
 });
 
-// Step 2: Upload directly to GCS with progress tracking
+// Step 2 — Upload directly to GCS with real progress
 await storage.uploadToSignedUrl(
   uploadUrl,
   file,
@@ -572,54 +803,84 @@ await storage.uploadToSignedUrl(
   },
 );
 
-// Step 3: Confirm the upload (registers metadata server-side)
+// Step 3 — Confirm the upload (registers metadata on the server)
 const result = await storage.confirmUpload({
   path:     path,
   mimeType: 'video/mp4',
   isPublic: true,
 });
 
-console.log(result.publicUrl); // ready to use
+console.log(result.publicUrl); // live CDN URL
 ```
 
 ### Batch Upload
 
+Upload up to 50 files at once.
+
 ```typescript
 const storage = db.storage('main');
 
-// Get signed URLs for up to 50 files at once
+// Step 1 — Get signed URLs for all files
 const { files } = await storage.getBatchUploadUrls([
   { path: 'gallery/photo1.jpg', mimeType: 'image/jpeg', size: 204800, isPublic: true },
   { path: 'gallery/photo2.jpg', mimeType: 'image/jpeg', size: 153600, isPublic: true },
+  { path: 'gallery/photo3.png', mimeType: 'image/png',  size: 98304,  isPublic: true },
 ]);
 
-// Upload each one directly to GCS
+// Step 2 — Upload each directly to GCS
 for (const f of files) {
   await storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
 }
 
-// Confirm all at once
-const results = await storage.batchConfirmUploads(
+// Step 3 — Confirm all at once
+const { succeeded, failed } = await storage.batchConfirmUploads(
   files.map(f => ({ path: f.path, mimeType: f.mimeType, isPublic: true })),
 );
+
+console.log(`${succeeded.length} uploaded, ${failed.length} failed`);
+for (const f of succeeded) {
+  console.log(f.publicUrl);
+}
 ```
 
-### Download Files
+### Download
 
 ```typescript
 // Private files require authentication — returns ArrayBuffer
 const buffer = await db.storage('documents').download('reports/q3.pdf');
 const blob   = new Blob([buffer], { type: 'application/pdf' });
 
-// Trigger a browser download
+// Trigger browser download
 const url  = URL.createObjectURL(blob);
 const a    = document.createElement('a');
 a.href     = url;
 a.download = 'q3.pdf';
 a.click();
+```
+
+> 💡 **Public files:** Use `result.publicUrl` directly — no SDK call needed. `<img src={result.publicUrl} />` just works.
 
-// Public files: use publicUrl directly — no SDK needed
-// <img src={result.publicUrl} />
+### Batch Download
+
+Download up to 20 files in one call. Content is returned as base64 strings.
+
+```typescript
+const { succeeded, failed } = await db.storage('documents').batchDownload([
+  'reports/q1.pdf',
+  'reports/q2.pdf',
+  'reports/q3.pdf',
+]);
+
+for (const f of succeeded) {
+  console.log(f.path);     // 'reports/q1.pdf'
+  console.log(f.mimeType); // 'application/pdf'
+  console.log(f.size);     // bytes
+  const bytes = Buffer.from(f.content, 'base64');
+}
+
+for (const f of failed) {
+  console.error(`${f.path}: ${f.error}`);
+}
 ```
 
 ### List Files
@@ -628,22 +889,25 @@ a.click();
 const storage = db.storage('main');
 
 // List everything at the root
-const { files, folders } = await storage.list();
+const { files, folders, hasMore, nextCursor } = await storage.list();
 
 // List a specific folder
-const { files, folders, hasMore, nextCursor } = await storage.list({
-  prefix:    'gallery/',
-  limit:     50,
-  recursive: false,
+const result = await storage.list({
+  prefix: 'gallery/',
+  limit:  50,
 });
 
 // Paginate
-if (hasMore) {
-  const page2 = await storage.list({ prefix: 'gallery/', cursor: nextCursor });
+if (result.hasMore) {
+  const page2 = await storage.list({
+    prefix: 'gallery/',
+    cursor: result.nextCursor,
+  });
 }
 ```
 
-Each file entry includes:
+Each file entry:
+
 ```typescript
 {
   name:        'photo1.jpg',
@@ -651,7 +915,7 @@ Each file entry includes:
   size:        204800,
   mimeType:    'image/jpeg',
   isPublic:    true,
-  publicUrl:   'https://storage.googleapis.com/...',
+  publicUrl:   'https://storage.googleapis.com/…',
   downloadUrl: null,
   updatedAt:   '2025-06-01T12:00:00.000Z',
 }
@@ -659,88 +923,125 @@ Each file entry includes:
 
 ### Scoped Storage
 
-Working within a specific folder? Use `.scope()` to avoid repeating the prefix on every call.
+Pre-fix all operations to a folder — great for per-user isolation.
 
 ```typescript
-// All operations in the "user-avatars/" folder
-const avatars = db.storage('avatars').scope('user-avatars');
+const userDocs = db.storage('documents').scope(`users/${userId}/`);
 
-await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
-// → uploads to "user-avatars/{userId}.jpg"
+// Uploads to: users/{userId}/contract.pdf
+await userDocs.upload(pdfBuffer, 'contract.pdf');
 
-const { files } = await avatars.list();
-// → lists files under "user-avatars/"
+// Lists:      users/{userId}/
+const { files } = await userDocs.list();
 
-await avatars.deleteFile(`${userId}.jpg`);
-// → deletes "user-avatars/{userId}.jpg"
+// Deletes:    users/{userId}/contract.pdf
+await userDocs.deleteFile('contract.pdf');
 
 // Nest scopes
-const thumbnails = avatars.scope('thumbnails');
-// → all operations under "user-avatars/thumbnails/"
+const userThumbs = userDocs.scope('thumbnails/');
+// All ops under: users/{userId}/thumbnails/
 ```
 
-### Share & Visibility
+`ScopedStorage` has the same full API as `StorageManager` — every method listed in the reference is available.
+
+### File Metadata
 
 ```typescript
-const storage = db.storage('documents');
+const meta = await db.storage('documents').getMetadata('reports/q3.pdf');
+
+console.log(meta.size);        // bytes
+console.log(meta.mimeType);    // 'application/pdf'
+console.log(meta.isPublic);    // false
+console.log(meta.downloadUrl); // auth-required URL
+console.log(meta.createdAt);   // ISO string
+console.log(meta.updatedAt);   // ISO string
+```
 
-// Get file metadata (size, MIME type, URLs, visibility)
-const meta = await storage.getMetadata('reports/q3.pdf');
+### Signed Share URLs
 
-// Generate a time-limited share link for a private file
-// (no auth key needed to use the link)
-const { signedUrl, expiresAt } = await storage.getSignedUrl(
-  'reports/q3.pdf',
-  3600, // expires in 1 hour (default)
-);
+Generate a time-limited link for a private file — no `X-Storage-Key` required to use it.
+
+```typescript
+const { signedUrl, expiresAt, expiresIn } = await db.storage('documents')
+  .getSignedUrl('reports/q3.pdf', 3600); // expires in 1 hour (default)
 
-// Toggle visibility after upload
-await storage.setVisibility('reports/q3.pdf', true);  // make public
-await storage.setVisibility('reports/q3.pdf', false); // make private
+// Share signedUrl with the recipient — it expires automatically
+console.log(`Link valid until: ${new Date(expiresAt).toLocaleString()}`);
 ```
 
-### File Operations
+> ⚠️ Downloads via signed URLs bypass the server — **download stats are not tracked** for those requests. Use `downloadUrl` for tracked downloads.
+
+### Visibility
+
+```typescript
+// Make a private file public
+const result = await db.storage('main').setVisibility('docs/report.pdf', true);
+console.log(result.publicUrl); // now has a CDN URL
+
+// Make a public file private
+const result2 = await db.storage('main').setVisibility('docs/report.pdf', false);
+console.log(result2.downloadUrl); // now requires auth
+```
+
+### Move, Copy, Delete
 
 ```typescript
 const storage = db.storage('main');
 
-// Rename / move a file
+// Rename a file
 await storage.move('drafts/report.pdf', 'published/report-2025.pdf');
 
-// Copy a file
+// Move to a different folder
+await storage.move('inbox/data.csv', 'archive/2025/data.csv');
+
+// Copy
 await storage.copy('templates/invoice.html', 'invoices/inv-001.html');
 
-// Create a folder
+// Create a folder placeholder
 await storage.createFolder('archive/2025/');
 
-// Delete a file
+// Delete a single file
 await storage.deleteFile('temp/scratch.txt');
 
-// Delete a folder and all its contents
+// Delete a folder and all its contents recursively
 await storage.deleteFolder('temp/');
+```
 
-// Get key-level stats
-const stats = await storage.getStats();
-// → { totalFiles: 842, totalBytes: 1073741824, uploadCount: 1200, ... }
+### Storage Stats
+
+```typescript
+const stats = await db.storage('main').getStats();
+// {
+//   totalFiles:    842,
+//   totalBytes:    1073741824,
+//   uploadCount:   1200,
+//   downloadCount: 4830,
+//   deleteCount:   58,
+// }
+
+// Ping — no auth required
+const { ok, storageRoot } = await db.storage('main').info();
 ```
 
 ---
 
 ## Analytics
 
-HydrousDB Analytics runs queries directly against BigQuery on your GCS data — zero ETL, no data duplication, live results. Fast even on billions of records.
+HydrousDB Analytics runs directly against BigQuery on your GCS data — zero ETL, no duplication, live results. Fast even on billions of records.
 
 ```typescript
 const analytics = db.analytics('orders');
 ```
 
+All `dateRange` values are Unix timestamps in milliseconds: `{ start?: number, end?: number }`.
+
 ### Count
 
 ```typescript
 // Total records
 const { count } = await analytics.count();
 
-// Records in a date range
+// In a date range
 const { count: lastWeek } = await analytics.count({
   dateRange: {
     start: Date.now() - 7 * 24 * 60 * 60 * 1000,
@@ -754,8 +1055,12 @@ const { count: lastWeek } = await analytics.count({
 How many records have each unique value for a field?
 
 ```typescript
-const rows = await analytics.distribution({ field: 'status', limit: 10, order: 'desc' });
-// → [
+const rows = await analytics.distribution({
+  field: 'status',
+  limit: 10,
+  order: 'desc', // 'asc' | 'desc'
+});
+// [
 //   { value: 'completed', count: 8234 },
 //   { value: 'pending',   count: 1203 },
 //   { value: 'refunded',  count: 412  },
@@ -766,56 +1071,61 @@ const rows = await analytics.distribution({ field: 'status', limit: 10, order: '
 
 ```typescript
 // Total revenue
-const rows = await analytics.sum({ field: 'amount' });
-// → [{ sum: 198432.50 }]
+const [{ sum: total }] = await analytics.sum({ field: 'amount' });
 
-// Revenue grouped by country
+// Revenue by country
 const byCountry = await analytics.sum({
   field:   'amount',
   groupBy: 'country',
   limit:   10,
 });
-// → [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, ...]
+// [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, …]
 ```
 
 ### Time Series
 
-Record counts over time — ideal for activity and growth charts.
+Record counts bucketed over time — ideal for activity and growth charts.
 
 ```typescript
 const rows = await analytics.timeSeries({
-  granularity: 'day',  // 'hour' | 'day' | 'week' | 'month' | 'year'
+  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 }, ...]
+// [{ date: '2025-01-01', count: 42 }, { date: '2025-01-02', count: 67 }, …]
 ```
 
-Aggregate a numeric field over time:
+### Field Time Series
+
+Aggregate a numeric field over time.
 
 ```typescript
 const revenue = await analytics.fieldTimeSeries({
   field:       'amount',
-  aggregation: 'sum',  // 'sum' | 'avg' | 'min' | 'max' | 'count'
+  aggregation: 'sum',   // 'sum' | 'avg' | 'min' | 'max' | 'count'
   granularity: 'week',
+  dateRange: {
+    start: new Date('2025-01-01').getTime(),
+    end:   Date.now(),
+  },
 });
-// → [{ date: '2025-W01', value: 12340.50 }, ...]
+// [{ date: '2025-W01', value: 12340.50 }, { date: '2025-W02', value: 9872.00 }, …]
 ```
 
 ### Top N
 
-Most common values for a field:
+Most common values for a field.
 
 ```typescript
 const topProducts = await analytics.topN({
   field:      'productId',
-  labelField: 'productName', // optional: include a human-readable label
+  labelField: 'productName', // optional human-readable label alongside the value
   n:          5,
   order:      'desc',
 });
-// → [
+// [
 //   { value: 'prod_123', label: 'Widget Pro', count: 892 },
 //   { value: 'prod_456', label: 'Gizmo Plus', count: 743 },
 // ]
@@ -823,41 +1133,48 @@ const topProducts = await analytics.topN({
 
 ### Field Stats
 
-Statistical summary for any numeric field:
+Statistical summary for any numeric field.
 
 ```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
+// {
+//   min:    4.99,
+//   max:    9999.99,
+//   avg:    87.23,
+//   sum:    420948.27,
+//   count:  4823,
+//   stddev: 143.2,
 // }
 ```
 
 ### Multi-Metric Dashboard
 
-Calculate several aggregations in a single BigQuery query:
+Run several aggregations in a single BigQuery query — one network call.
 
 ```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' },
+    { field: 'amount',  name: 'totalRevenue',  aggregation: 'sum'   },
+    { field: 'amount',  name: 'avgOrderValue', aggregation: 'avg'   },
+    { field: 'amount',  name: 'maxOrder',      aggregation: 'max'   },
+    { field: 'userId',  name: 'uniqueOrders',  aggregation: 'count' },
   ],
-  dateRange: { start: new Date('2025-01-01').getTime(), end: Date.now() },
+  dateRange: {
+    start: new Date('2025-01-01').getTime(),
+    end:   Date.now(),
+  },
 });
-// → {
+// {
 //   totalRevenue:  198432.50,
 //   avgOrderValue: 87.23,
 //   maxOrder:      9999.99,
-//   totalOrders:   2275,
+//   uniqueOrders:  2275,
 // }
 ```
 
-### Filtered Records (BigQuery)
+### Filtered Records via BigQuery
 
-Query raw records at full BigQuery speed:
+Fetch raw records using the BigQuery engine — useful for large-scale filtered exports.
 
 ```typescript
 const records = await analytics.records({
@@ -866,15 +1183,20 @@ const records = await analytics.records({
     { field: 'amount', op: '>',  value: 100         },
   ],
   selectFields: ['orderId', 'amount', 'userId', 'createdAt'],
-  orderBy: 'amount',
-  order:   'desc',
-  limit:   50,
+  orderBy:      'amount',
+  order:        'desc',
+  limit:        50,
+  offset:       0,
+  dateRange: {
+    start: new Date('2025-01-01').getTime(),
+    end:   Date.now(),
+  },
 });
 ```
 
 ### Cross-Bucket Comparison
 
-Compare the same metric across multiple buckets in one query:
+Compare the same metric across multiple buckets in one query.
 
 ```typescript
 const comparison = await analytics.crossBucket({
@@ -882,32 +1204,87 @@ const comparison = await analytics.crossBucket({
   field:       'amount',
   aggregation: 'sum',
 });
-// → [
+// [
 //   { bucket: 'orders-us',   value: 120000 },
 //   { bucket: 'orders-eu',   value: 45000  },
 //   { bucket: 'orders-apac', value: 33000  },
 // ]
 ```
 
-> ⚠️ Your Bucket Security Key must have read access to **all** listed buckets.
+> ⚠️ Your Bucket Security Key must have read access to **every** bucket listed in `bucketKeys`.
 
 ### Storage Stats
 
 ```typescript
 const stats = await analytics.storageStats();
-// → { totalRecords: 48210, totalBytes: 921600000, avgBytes: 19112, minBytes: 128, maxBytes: 5242880 }
+// {
+//   totalRecords: 48210,
+//   totalBytes:   921600000,
+//   avgBytes:     19112,
+//   minBytes:     128,
+//   maxBytes:     5242880,
+// }
+```
+
+### Raw Query
+
+Use the `query()` method when none of the typed helpers cover your use case.
+
+```typescript
+import type { AnalyticsQuery } from 'hydrousdb';
+
+const result = await analytics.query<{ count: number }>({
+  queryType: 'count',
+  dateRange: { start: Date.now() - 86400000, end: Date.now() },
+});
+
+console.log(result.queryType); // 'count'
+console.log(result.data);      // { count: 142 }
 ```
 
 ---
 
-## TypeScript Support
+## TypeScript
 
-The SDK is written in TypeScript and ships with full type definitions. Use generic type parameters to get full autocomplete and compile-time safety throughout your app.
+The SDK is written entirely in TypeScript and ships full type definitions. Use generics for end-to-end type safety.
 
 ```typescript
 import { createClient } from 'hydrousdb';
+import type {
+  HydrousConfig,
+  RecordResult,
+  QueryFilter,
+  QueryOptions,
+  QueryResult,
+  CreateRecordOptions,
+  BatchCreateOptions,
+  UploadResult,
+  UploadUrlResult,
+  ListResult,
+  FileMetadata,
+  SignedUrlResult,
+  BatchDownloadResult,
+  StorageStats,
+  DateRange,
+  AnalyticsQuery,
+  AnalyticsResult,
+  CountResult,
+  DistributionRow,
+  SumRow,
+  TimeSeriesRow,
+  FieldTimeSeriesRow,
+  TopNRow,
+  FieldStats,
+  MultiMetricResult,
+  StorageStatsResult,
+  CrossBucketRow,
+  UserRecord,
+  Session,
+  AuthResult,
+  ListUsersResult,
+} from 'hydrousdb';
 
-// Define your data models as plain interfaces — no index signature needed
+// Define your domain models
 interface Order {
   customerId: string;
   items:      Array<{ productId: string; qty: number; price: number }>;
@@ -929,260 +1306,261 @@ const db = createClient({
   storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
 });
 
-// Fully typed clients
+// Fully typed — autocomplete, compile-time safety throughout
 const orders    = db.records<Order>('orders');
 const customers = db.records<Customer>('customers');
 
-// 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',
-});
+const order = await orders.create(
+  { customerId: 'cust_abc', items: [{ productId: 'prod_1', qty: 2, price: 29.99 }], total: 59.98, status: 'pending', country: 'US' },
+  { queryableFields: ['status', 'country', 'customerId'] },
+);
 
 // TypeScript catches mistakes at compile time:
-// order.nonExistentField   // ← TS error ✓
-// order.status = 'invalid' // ← TS error ✓
-```
-
-All exported types are available for import:
-
-```typescript
-import type {
-  HydrousConfig,
-  RecordResult,
-  QueryFilter,
-  QueryOptions,
-  UploadResult,
-  AnalyticsQuery,
-  DateRange,
-  // ... and many more
-} from 'hydrousdb';
+// order.nonExistentField    ← TS error ✓
+// orders.create({ bad: 1 }) ← TS error ✓
 ```
 
 ---
 
 ## Error Handling
 
-All errors thrown by the SDK extend `HydrousError`, which carries:
-
-| 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 |
+All SDK errors extend `HydrousError`. Specific sub-classes let you handle different failure modes precisely.
 
 ```typescript
-import { HydrousError, NetworkError, AuthError } from 'hydrousdb';
+import {
+  HydrousError,
+  AuthError,
+  RecordError,
+  StorageError,
+  AnalyticsError,
+  ValidationError,
+  NetworkError,
+} from 'hydrousdb';
 
 try {
-  const { user } = await auth.login({ email: 'a@b.com', password: 'wrong' });
+  const record = await db.records('orders').get('bad-id');
 } 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
-  } else if (err instanceof NetworkError) {
+  if (err instanceof NetworkError) {
     // No internet / server unreachable
-    console.error('Cannot reach HydrousDB — check your internet connection');
+    console.error('Cannot reach HydrousDB:', err.message);
+
+  } else if (err instanceof AuthError) {
+    // Bad key, expired session, insufficient permissions
+    console.error(`Auth failed [${err.code}]:`, err.message);
+    // err.code: INVALID_CREDENTIALS | ACCOUNT_LOCKED | INVALID_SESSION | FORBIDDEN | …
+
+  } else if (err instanceof ValidationError) {
+    // Invalid input — check details array
+    console.error('Validation failed:', err.details?.join(', '));
+
+  } else if (err instanceof RecordError) {
+    // Record-specific API error
+    console.error(`Record error [${err.code}]:`, err.message);
+
+  } else if (err instanceof StorageError) {
+    // Storage-specific error
+    console.error(`Storage error [${err.code}]:`, err.message);
+
   } else if (err instanceof HydrousError) {
     // Any other API error
-    console.error(`API error [${err.code}]: ${err.message}`);
-    console.error(`Request ID: ${err.requestId}`); // include in support tickets
+    console.error(`API error [${err.code}] ${err.status}:`, err.message);
+    console.error('Request ID:', err.requestId); // include in support tickets
   }
 }
 ```
 
+**Error properties:**
+
+| Property | Type | Description |
+|---|---|---|
+| `message` | `string` | Human-readable description |
+| `code` | `string` | Machine-readable error code |
+| `status` | `number` | HTTP status code |
+| `requestId` | `string \| undefined` | Server request ID — include in support tickets |
+| `details` | `string[] \| undefined` | Validation error details |
+
 **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` | Key not provided |
-| `INVALID_SECURITY_KEY` | 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 |
+| Code | Status | Meaning |
+|---|---|---|
+| `RECORD_NOT_FOUND` | 404 | The requested record ID does not exist |
+| `INVALID_CREDENTIALS` | 401 | Wrong email or password |
+| `ACCOUNT_LOCKED` | 403 | Account is temporarily locked |
+| `INVALID_SESSION` | 401 | Session expired or revoked — re-authenticate |
+| `MISSING_API_KEY` | 401 | Key not provided in headers |
+| `INVALID_SECURITY_KEY` | 401 | Key is wrong or has been revoked |
+| `FORBIDDEN` | 403 | Insufficient permissions for this operation |
+| `FILE_EXISTS` | 409 | File already exists — use `overwrite: true` |
+| `SYSTEM_BUCKET_FORBIDDEN` | 403 | Cannot query system buckets via analytics |
+| `CROSS_BUCKET_FORBIDDEN` | 403 | Key lacks read access to one of the requested buckets |
+| `VALIDATION_ERROR` | 400 | Invalid input — check `err.details` |
+| `NETWORK_ERROR` | — | Failed to reach the API |
 
 ---
 
 ## Security Best Practices
 
-1. **Never hard-code your keys.** Use environment variables:
+**1. Never hard-code keys — use environment variables.**
 
-   ```bash
-   # .env (add to .gitignore)
-   HYDROUS_AUTH_KEY=hk_auth_xxxxxxxxxxxxxxxxxxxx
-   HYDROUS_BUCKET_KEY=hk_bucket_xxxxxxxxxxxxxxxxxxxx
-   HYDROUS_STORAGE_MAIN=ssk_xxxxxxxxxxxxxxxxxxxx
-   ```
+```bash
+# .env  (add .env to your .gitignore)
+HYDROUS_AUTH_KEY=hk_auth_xxxxxxxxxxxxxxxxxxxx
+HYDROUS_BUCKET_KEY=hk_bucket_xxxxxxxxxxxxxxxxxxxx
+HYDROUS_STORAGE_MAIN=ssk_xxxxxxxxxxxxxxxxxxxx
+```
 
-   ```typescript
-   const db = createClient({
-     authKey:           process.env.HYDROUS_AUTH_KEY!,
-     bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
-     storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
-   });
-   ```
+```typescript
+const db = createClient({
+  authKey:           process.env.HYDROUS_AUTH_KEY!,
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+  storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
+});
+```
 
-2. **Never expose keys to browsers.** For browser-side apps, route requests through your own backend, or use per-user session tokens from `auth.login()`.
+**2. Never expose keys to browsers.** For browser-side apps, route requests through your own backend, or use per-user sessions from `auth.login()`.
 
-3. **Keys are sent via request headers — never in URLs.** The SDK enforces this automatically, so keys never appear in server logs or browser history.
+**3. Keys travel in headers — never in URLs.** The SDK enforces this automatically. Keys never appear in server access logs, GCP audit trails, or browser history.
 
-4. **Rotate keys periodically.** Revoke old keys from the dashboard after rotation.
+**4. Rotate keys periodically.** Revoke old keys from the dashboard after rotation.
 
-5. **Use scoped storage** (`db.storage('keyName').scope('prefix/')`) to isolate access by user or feature, reducing the blast radius of any misconfiguration.
+**5. Use scoped storage** (`db.storage('key').scope('prefix/')`) to isolate access per user or feature, reducing the blast radius of any misconfiguration.
 
-6. **Use `isPublic: false` (the default) for sensitive files.** Use signed URLs for time-limited sharing instead of making files permanently public.
+**6. Keep files private by default.** `isPublic` defaults to `false`. Use `getSignedUrl()` for time-limited external sharing rather than making files permanently public.
 
 ---
 
-## API Reference
+## Full API Reference
+
+### `createClient(config)` → `HydrousClient`
 
-### `createClient(config)`
+| Config field | Type | Required | Description |
+|---|---|---|---|
+| `authKey` | `string` | ✅ | `hk_auth_…` — used for all auth routes |
+| `bucketSecurityKey` | `string` | ✅ | `hk_bucket_…` — used for records & analytics |
+| `storageKeys` | `Record<string, string>` | ✅ | Named `ssk_…` keys — at least one entry |
+| `baseUrl` | `string` | — | Override the API endpoint (for self-hosting or testing) |
 
-Creates and returns a `HydrousClient` instance. Call this once and reuse it everywhere.
+---
+
+### `db.records<T>(bucketKey)` → `RecordsClient<T>`
+
+| Method | Signature | Description |
+|---|---|---|
+| `create` | `(data: T, opts?: CreateRecordOptions) → T & RecordResult` | Create a record. `opts.queryableFields` indexes fields for filtering. `opts.customRecordId` enables upsert. |
+| `get` | `(id: string) → T & RecordResult` | Fetch by ID. Zero index reads. |
+| `set` | `(id: string, data: T) → T & RecordResult` | Full replace. |
+| `patch` | `(id: string, data: Partial<T>, opts?) → T & RecordResult` | Partial update. `opts.merge` (default `true`) controls whether missing fields are removed. |
+| `delete` | `(id: string) → void` | Permanent delete. |
+| `query` | `(opts?: QueryOptions) → QueryResult<T>` | Filtered, sorted, paginated query. |
+| `getAll` | `(opts?) → (T & RecordResult)[]` | Query without filters — convenience shortcut. |
+| `count` | `(filters?) → number` | Count matching records. |
+| `batchCreate` | `(items: T[], opts?: BatchCreateOptions) → (T & RecordResult)[]` | Up to 500 records. |
+| `batchDelete` | `(ids: string[]) → { deleted, failed }` | Up to 500 records. |
+| `getHistory` | `(id: string) → RecordHistoryEntry[]` | Full version list, most recent first. |
+| `restoreVersion` | `(id: string, version: number) → T & RecordResult` | Roll back to any version. |
+
+**`QueryOptions`:**
 
 ```typescript
-const db = createClient({
-  authKey:           'hk_auth_…',    // Required — auth routes
-  bucketSecurityKey: 'hk_bucket_…',  // Required — records & analytics
-  storageKeys: {                     // Required — at least one entry
-    main:      'ssk_main_…',
-    avatars:   'ssk_avatars_…',
-    documents: 'ssk_docs_…',
-  },
-  baseUrl: 'https://...',            // Optional — defaults to official endpoint
-});
+{
+  filters?:    QueryFilter[];   // [{ field, op, value }, …]
+  fields?:     string;          // comma-separated field names
+  orderBy?:    string;
+  order?:      'asc' | 'desc';
+  limit?:      number;          // default 100, max 1000
+  offset?:     number;
+  startAfter?: string;          // cursor for next page
+  startAt?:    string;
+  endAt?:      string;
+  dateRange?:  DateRange;       // { start?: number, end?: number }
+}
 ```
 
-### `db.records<T>(bucketKey)`
+---
 
-Returns a `RecordsClient<T>` for the named bucket. Uses `bucketSecurityKey` automatically.
+### `db.auth(bucketKey)` → `AuthClient`
 
-| 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 previous version |
-
-### `db.auth(bucketKey)`
-
-Returns an `AuthClient` for the named user bucket. Uses `authKey` automatically.
-
-| Method | Description |
-|---|---|
-| `signup(opts)` | Register a new user |
-| `login(opts)` | Authenticate and create a session |
-| `logout({ sessionId })` | Invalidate a session |
-| `refreshSession({ refreshToken })` | Extend a session |
-| `getUser({ userId })` | Get user by ID |
-| `updateUser(opts)` | Update user fields |
-| `changePassword(opts)` | Change password (authenticated) |
-| `requestPasswordReset(opts)` | Send reset email |
-| `confirmPasswordReset(opts)` | Apply new password from reset token |
-| `requestEmailVerification(opts)` | Send verification email |
-| `confirmEmailVerification(opts)` | Verify email with token |
-| `listUsers(opts)` | List all users (admin) |
-| `lockAccount(opts)` | Lock a user account (admin) |
-| `unlockAccount(opts)` | Unlock a user account (admin) |
-| `deleteUser(opts)` | Soft-delete a user (admin) |
-| `hardDeleteUser(opts)` | Permanently delete a user (admin) |
-| `bulkDeleteUsers(opts)` | Bulk delete users (admin) |
-
-### `db.analytics(bucketKey)`
-
-Returns an `AnalyticsClient` for the named bucket. Uses `bucketSecurityKey` automatically.
-
-| Method | Description |
-|---|---|
-| `count(opts?)` | Count records |
-| `distribution(opts)` | Value distribution for a field |
-| `sum(opts)` | Sum with optional groupBy |
-| `timeSeries(opts?)` | Record counts over time |
-| `fieldTimeSeries(opts)` | Field aggregation over time |
-| `topN(opts)` | Top N values for a field |
-| `stats(opts)` | Statistical summary for a numeric field |
-| `records(opts?)` | Filtered raw records via BigQuery |
-| `multiMetric(opts)` | Multiple aggregations in one query |
-| `storageStats(opts?)` | Bucket storage statistics |
-| `crossBucket(opts)` | Compare a metric across multiple buckets |
-| `query(query)` | Raw analytics query |
-
-### `db.storage(keyName)`
-
-Returns a `StorageManager` for the named storage key. The name must match a key you defined in `storageKeys` when calling `createClient`. Uses the corresponding `ssk_…` key via `X-Storage-Key`.
+| Method | Signature | Description |
+|---|---|---|
+| `signup` | `(opts: SignupOptions) → AuthResult` | Register user + create session. Extra fields beyond `email/password/fullName` are stored on the user record. |
+| `login` | `(opts: LoginOptions) → AuthResult` | Authenticate + create session. |
+| `logout` | `({ sessionId, allDevices? }) → void` | Revoke one or all sessions. |
+| `refreshSession` | `({ refreshToken }) → Session` | Extend an expiring session. |
+| `validateSession` | `({ sessionId }) → { user, session }` | Check if a session is still active. |
+| `getUser` | `({ userId }) → UserRecord` | Fetch a user by ID. |
+| `updateUser` | `(opts: UpdateUserOptions) → UserRecord` | Update user fields — must wrap changes in `updates: { … }`. |
+| `changePassword` | `(opts: ChangePasswordOptions) → void` | Authenticated password change. Field is `currentPassword` in the SDK (maps to `oldPassword` on the wire). |
+| `requestPasswordReset` | `({ email }) → void` | Trigger reset email. |
+| `confirmPasswordReset` | `({ resetToken, newPassword }) → void` | Apply new password. |
+| `requestEmailVerification` | `({ userId }) → void` | Send verification email. |
+| `confirmEmailVerification` | `({ verifyToken }) → void` | Complete verification. |
+| `listUsers` | `(opts: ListUsersOptions) → ListUsersResult` | Paginated user list. Uses cursor-based pagination — `nextCursor` replaces `offset`. |
+| `lockAccount` | `({ sessionId, userId, duration? }) → { lockedUntil, unlockTime }` | Admin only. |
+| `unlockAccount` | `({ sessionId, userId }) → void` | Admin only. |
+| `deleteUser` | `({ sessionId, userId }) → void` | Soft delete. Admin required unless deleting own account. |
+| `hardDeleteUser` | `({ sessionId, userId }) → void` | Permanent. Admin required unless deleting own account. |
+| `bulkDeleteUsers` | `({ sessionId, userIds, hard? }) → { succeeded, failed }` | Up to 500 users. Admin only. |
 
-```typescript
-const storage = db.storage('avatars');
-const scoped  = db.storage('avatars').scope('user-uploads/');
-```
+---
 
-| Method | Description |
-|---|---|
-| `upload(data, path, opts?)` | Simple server-buffered upload (up to 500 MB) |
-| `uploadRaw(data, path, opts?)` | Upload JSON or text data |
-| `getUploadUrl(opts)` | Step 1: Get a signed GCS upload URL |
-| `uploadToSignedUrl(url, data, mime, onProgress?)` | Step 2: Upload directly to GCS |
-| `confirmUpload(opts)` | Step 3: Register upload metadata |
-| `getBatchUploadUrls(files)` | Get signed URLs for up to 50 files at once |
-| `batchConfirmUploads(items)` | Confirm multiple uploads at once |
-| `download(path)` | Download a private file as ArrayBuffer |
-| `batchDownload(paths)` | Download multiple files |
-| `list(opts?)` | List files and folders |
-| `getMetadata(path)` | Get file metadata |
-| `getSignedUrl(path, expiresIn?)` | Generate a 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 and all its contents |
-| `move(from, to)` | Move or rename a file |
-| `copy(from, to)` | Copy a file |
-| `getStats()` | Key-level storage statistics |
-| `info()` | Ping the storage service (no auth required) |
-| `scope(prefix)` | Get a `ScopedStorage` instance pre-fixed to a folder |
+### `db.storage(keyName)` → `StorageManager`
+
+| Method | Signature | Description |
+|---|---|---|
+| `upload` | `(data, path, opts?) → UploadResult` | Server-buffered upload. Up to 500 MB. |
+| `uploadRaw` | `(data, path, opts?) → UploadResult` | Upload a JS object or string as a file. |
+| `getUploadUrl` | `(opts) → UploadUrlResult` | Step 1 of direct upload. `expiresInSeconds` controls URL TTL. |
+| `uploadToSignedUrl` | `(signedUrl, data, mimeType, onProgress?) → void` | Step 2 — upload to GCS directly. `onProgress` callback fires with 0–100. |
+| `confirmUpload` | `(opts) → UploadResult` | Step 3 — register metadata. |
+| `getBatchUploadUrls` | `(files: BatchUploadItem[]) → BatchUploadUrlResult` | Up to 50 files. Returns `{ files: [...] }` — only succeeded items included. |
+| `batchConfirmUploads` | `(items) → { succeeded, failed }` | Confirm multiple uploads. Both arrays are returned. |
+| `download` | `(path) → ArrayBuffer` | Download private file. |
+| `batchDownload` | `(paths) → BatchDownloadResult` | Up to 20 files. Returns `{ succeeded, failed }` — content is base64. |
+| `list` | `(opts?) → ListResult` | Returns `{ files, folders, hasMore, nextCursor }`. |
+| `getMetadata` | `(path) → FileMetadata` | Size, MIME type, visibility, URLs. |
+| `getSignedUrl` | `(path, expiresIn?) → SignedUrlResult` | Time-limited share link. Default: 3600s. |
+| `setVisibility` | `(path, isPublic) → { path, isPublic, publicUrl, downloadUrl }` | Toggle public/private. |
+| `createFolder` | `(path) → { path }` | Create a GCS prefix placeholder. |
+| `deleteFile` | `(path) → void` | Delete a single file. |
+| `deleteFolder` | `(path) → void` | Delete folder + all contents. |
+| `move` | `(from, to) → { from, to }` | Move or rename. |
+| `copy` | `(from, to) → { from, to }` | Copy to a new path. |
+| `getStats` | `() → StorageStats` | Key-level totals: files, bytes, upload/download/delete counts. |
+| `info` | `() → { ok, storageRoot }` | Healthcheck — no auth required. |
+| `scope` | `(prefix) → ScopedStorage` | Create a path-prefixed sub-client with the full StorageManager API. |
 
 ---
 
-## Contributing
+### `db.analytics(bucketKey)` → `AnalyticsClient`
 
-We love contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+| Method | Signature | Description |
+|---|---|---|
+| `count` | `(opts?) → CountResult` | Total record count. |
+| `distribution` | `(opts) → DistributionRow[]` | Per-value counts for a field. |
+| `sum` | `(opts) → SumRow[]` | Sum of a numeric field, optional groupBy. |
+| `timeSeries` | `(opts?) → TimeSeriesRow[]` | Record counts over time. |
+| `fieldTimeSeries` | `(opts) → FieldTimeSeriesRow[]` | Field aggregation over time. |
+| `topN` | `(opts) → TopNRow[]` | Most frequent values. `labelField` adds a human-readable label. |
+| `stats` | `(opts) → FieldStats` | min / max / avg / sum / count / stddev for a numeric field. |
+| `records` | `(opts?) → (T & RecordResult)[]` | Filtered raw records via BigQuery. |
+| `multiMetric` | `(opts) → MultiMetricResult` | Multiple aggregations in one query. Each metric gets a named alias. |
+| `storageStats` | `(opts?) → StorageStatsResult` | Record count + byte totals for the bucket. |
+| `crossBucket` | `(opts) → CrossBucketRow[]` | Compare a metric across multiple buckets. |
+| `query` | `(query: AnalyticsQuery) → AnalyticsResult<T>` | Raw query — for cases not covered by the typed methods above. |
+
+---
+
+## Contributing
 
 ```bash
-# Clone the repo
 git clone https://github.com/hydrousdb/hydrousdb-js.git
 cd hydrousdb-js
 
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Build
-npm run build
-
-# Run tests in watch mode
-npm run test:watch
+npm install        # install dependencies
+npm run build      # compile ESM + CJS + type declarations
+npm test           # run the full test suite (68 tests)
+npm run test:watch # watch mode
+npm run lint       # TypeScript type check
 ```
 
 ---
@@ -1197,4 +1575,4 @@ MIT — see [LICENSE](./LICENSE) for details.
   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>
+</p>