hydrousdb 3.2.0 → 3.5.0

package/README.md

@@ -1,347 +1,68 @@
-# HydrousDB JavaScript / TypeScript SDK
+# HydrousDB JS/TS SDK
 
-<p align="center">
-  <strong>Store, retrieve, and query massive JSON records in milliseconds — with auth, file storage, and analytics built in.</strong><br><br>
-  <a href="https://hydrousdb.com/dashboard"><strong>→ Create a free account and run your first query in 5 minutes</strong></a>
-</p>
-
-<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
-
-- [What is HydrousDB?](#what-is-hydrousdb)
-- [How It Works](#how-it-works)
-- [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 — patch vs set](#update-a-record)
-  - [Delete](#delete-a-record)
-  - [Query](#query-records)
-  - [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)
-  - [Log In / Log Out](#log-in--log-out)
-  - [Session Management](#session-management)
-  - [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 — 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)
-  - [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)
-  - [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-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 via BigQuery](#filtered-records-via-bigquery)
-  - [Cross-Bucket Comparison](#cross-bucket-comparison)
-  - [Storage Stats](#storage-stats-1)
-  - [Raw Query](#raw-query)
-- [TypeScript](#typescript)
-- [Error Handling](#error-handling)
-- [Security Best Practices](#security-best-practices)
-- [Full API Reference](#full-api-reference)
-- [Contributing](#contributing)
-- [License](#license)
-
----
-
-## What is HydrousDB?
-
-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.
-
-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, 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. |
-| **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 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
-  ↓ parse date prefix
-YY=26  MM=02  DD=03
-  ↓ compute path in memory
-projects/pid/buckets/bk/records/26/02/03/rec_01JA.json.gz
-  ↓ fetch from GCS directly
-0 index reads ✓
-```
-
-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
-
-### 1. Create your account
-
-Sign up at [https://hydrousdb.com](https://hydrousdb.com).
-
-### 2. Get your API keys
-
-From the dashboard → **Settings → API Keys**, create three key types:
-
-| Key | Prefix | Used for |
-|---|---|---|
-| **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 |
-
-> ⚠️ Never commit these to Git. Store them in environment variables.
-
-### 3. Install
+**A database that doesn't choke on big JSON.** Store, query, and analyse massive records — with auth and file storage built in.
 
 ```bash
 npm install hydrousdb
-# or: yarn add hydrousdb  /  pnpm add hydrousdb
 ```
 
-**Requirements:** Node.js 18+ (uses the native `fetch` API).
+→ [Get your free API keys at hydrousdb.com](https://hydrousdb.com/dashboard)
 
-### 4. Create the client and write your first record
+---
 
-```typescript
+## Setup
+
+```ts
 import { createClient } from 'hydrousdb';
 
-// Create once — reuse everywhere in your app
 const db = createClient({
   authKey:           process.env.HYDROUS_AUTH_KEY!,
   bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
   storageKeys: {
-    main: process.env.HYDROUS_STORAGE_MAIN!,
+    main: process.env.HYDROUS_STORAGE_KEY!,
   },
 });
-
-// Write
-const post = await db.records('my-bucket').create({
-  title:     'Hello, HydrousDB!',
-  published: false,
-});
-
-console.log(post.id);        // "260601-rec_01JA2XYZ"
-console.log(post.createdAt); // 1717200000000
-
-// 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.
-
-```typescript
-// ESM — Next.js, Vite, modern Node, TypeScript
-import { createClient } from 'hydrousdb';
-```
+You get three key types from the dashboard — one for auth, one for records/analytics, one (or more) for file storage. Keep them in environment variables, never in your code.
 
-```javascript
-// CommonJS — legacy Node, Jest without transform, older tooling
-const { createClient } = require('hydrousdb');
-```
-
-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;
-  },
-};
-```
+Works in **React, Next.js, Vue, React Native, Node.js** — anywhere that runs modern JavaScript.
 
 ---
 
 ## Records
 
-Records are JSON objects stored in named buckets. Every record automatically gets:
-
-- `id` — date-prefixed unique identifier (`"260601-rec_01JA2XYZ"`) — encodes the GCS path
-- `createdAt` — Unix timestamp in milliseconds
-- `updatedAt` — Unix timestamp in milliseconds
+JSON objects stored in named buckets. Every record gets `id`, `createdAt`, and `updatedAt` automatically.
 
-```typescript
+```ts
 const posts = db.records('blog-posts');
-// or typed:
-const orders = db.records<Order>('orders');
-```
-
-### Create a Record
-
-```typescript
-const post = await posts.create({
-  title:  'My First Post',
-  body:   'Hello world.',
-  status: 'draft',
-  views:  0,
-});
-
-// 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
+// Create
 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
-  },
+  { title: 'Hello', status: 'draft', views: 0 },
+  { queryableFields: ['status'] },   // declare fields you want to filter on
 );
-```
-
-> 💡 **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
-// Path computed from the ID in memory — zero index reads
-const post = await posts.get('260601-rec_01JA2XYZ');
-
-// 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
-const updated = await posts.patch('260601-rec_01JA2XYZ', {
-  status: 'published',
-  views:  1,
-});
-```
-
-**`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):
+console.log(post.id); // "260601-rec_01JA2XYZ"
 
-```typescript
-// merge: false means fields not in `data` are removed
-await posts.patch('260601-rec_01JA2XYZ', { status: 'archived' }, { merge: false });
-```
+// Read  (path computed from ID — zero index lookups)
+const found = await posts.get(post.id);
 
-### Delete a Record
+// Update  (only the fields you pass are changed)
+await posts.patch(post.id, { status: 'published' });
 
-```typescript
-await posts.delete('260601-rec_01JA2XYZ');
+// Delete
+await posts.delete(post.id);
 ```
 
-### Query Records
+> **Why `queryableFields`?** Records are stored as compressed blobs. Fields you want to filter or sort by must be registered at write time. You only pay overhead for what you actually query.
 
-```typescript
-// All records (up to 100 by default)
-const { records } = await posts.query();
+### Query
 
-// With filters
-const { records: published } = await posts.query({
-  filters: [
-    { field: 'status', op: '==', value: 'published' },
-  ],
-});
-
-// Multiple filters, sort, limit
+```ts
 const { records, hasMore, nextCursor } = await posts.query({
   filters: [
-    { field: 'status',   op: '==', value: 'published' },
-    { field: 'views',    op: '>',  value: 100          },
+    { field: 'status', op: '==', value: 'published' },
+    { field: 'views',  op: '>',  value: 100 },
   ],
   orderBy: 'createdAt',
   order:   'desc',
@@ -350,374 +71,167 @@ const { records, hasMore, nextCursor } = await posts.query({
 
 // Next page
 if (hasMore) {
-  const page2 = await posts.query({
-    orderBy:    'createdAt',
-    order:      'desc',
-    limit:      20,
-    startAfter: nextCursor,
-  });
+  const page2 = await posts.query({ limit: 20, startAfter: nextCursor });
 }
-
-// Select only specific fields (reduces payload size)
-const { records: light } = await posts.query({
-  fields: 'id,title,status,createdAt',
-});
-
-// Date range
-const { records: thisWeek } = await posts.query({
-  dateRange: {
-    start: Date.now() - 7 * 24 * 60 * 60 * 1000,
-    end:   Date.now(),
-  },
-});
 ```
 
-**Filter operators:**
-
-| Operator | Meaning |
-|---|---|
-| `==` | Equal |
-| `!=` | Not equal |
-| `>` | Greater than |
-| `<` | Less than |
-| `>=` | Greater than or equal |
-| `<=` | Less than or equal |
-| `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.
+Filter operators: `==` `!=` `>` `<` `>=` `<=` `CONTAINS`
 
-### Count Records
+### Atomic field updates
 
-```typescript
-// Total records in the bucket
-const total = await posts.count();
+Avoid race conditions with server-side operations inside `patch()`:
 
-// Records matching filters
-const publishedCount = await posts.count([
-  { field: 'status', op: '==', value: 'published' },
-]);
+```ts
+await posts.patch(post.id, {
+  views:    { __op: 'increment',    delta: 1 },         // add 1
+  credits:  { __op: 'decrement',    delta: 5 },         // subtract 5
+  slug:     { __op: 'setOnce',      value: 'my-post' }, // set only if empty
+  tags:     { __op: 'appendUnique', item: 'featured' }, // add to array, no dupes
+  tags:     { __op: 'removeFromArray', item: 'draft' }, // remove from array
+  rating:   { __op: 'clamp',        value: 6, min: 0, max: 5 },
+  price:    { __op: 'multiplyBy',   factor: 1.1 },
+  active:   { __op: 'toggleBool' },
+  syncedAt: { __op: 'serverTimestamp' },
+} as any);
 ```
 
-### Batch Create
-
-Up to 500 records per call.
+### Batch operations
 
-```typescript
-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',
-  },
+```ts
+// Create up to 500 records at once
+const { results, errors } = await posts.batchCreate(
+  [{ title: 'A' }, { title: 'B' }],
+  { queryableFields: ['title'] },
 );
-// → [{ 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' },
-]);
-```
-
-### Batch Delete
-
-Up to 500 records per call.
 
-```typescript
-const { deleted, failed } = await posts.batchDelete([
-  '260601-rec_01JA',
-  '260601-rec_02JB',
-  '260601-rec_03JC',
+// Update up to 500 records at once
+await posts.batchUpdate([
+  { recordId: 'id1', values: { status: 'archived' } },
+  { recordId: 'id2', values: { status: 'archived' } },
 ]);
 
-console.log(`Deleted: ${deleted}, Failed: ${failed.length}`);
+// Delete up to 500 records at once
+const { successful, failed } = await posts.batchDelete(['id1', 'id2']);
 ```
 
-### Version History
+### Version history
 
-Every write creates a new version — you can restore any record to any previous state.
+Every write is automatically versioned.
 
-```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, … }]
+```ts
+const history = await posts.getHistory(post.id);
+// [{ generation, savedAt, savedBy, sizeBytes }, …]
 
-// Restore to version 1 (the original)
-const restored = await posts.restoreVersion('260601-rec_01JA2XYZ', history[2]!.version);
+// Read a specific past version
+const v1 = await posts.getVersion(post.id, history[0].generation!);
 ```
 
-### Write-Filter Sentinels
+### Custom record IDs
 
-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
-// Single record
+```ts
+// If the ID already exists, the record is upserted
 const post = await posts.create(
-  { title: 'Welcome', status: 'published' },
+  { title: 'Welcome' },
   { customRecordId: '260601-post_welcome' },
 );
-
-// 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
+## Auth
 
-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.
+A complete user system — signup, login, sessions, password reset, email verification, and admin controls.
 
-```typescript
-const auth = db.auth('app-users');
+```ts
+const auth = db.auth();
 ```
 
-### Sign Up
+### Sign up & log in
 
-```typescript
+```ts
+// Sign up — extra fields beyond email/password are stored on the user
 const { user, session } = await auth.signup({
   email:    'alice@example.com',
-  password: 'hunter2',          // validated server-side
-  fullName: 'Alice Wonderland',
-  // Any extra fields are stored on the user record:
-  plan:     'pro',
-  referral: 'friend123',
+  password: 'hunter2',
+  fullName: 'Alice Smith',
+  plan:     'pro',               // any custom fields you want
 });
 
-// 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
-
-```typescript
 // Log in
 const { user, session } = await auth.login({
   email:    'alice@example.com',
   password: 'hunter2',
 });
 
-// Log out — invalidates the session server-side
+// Log out (pass allDevices: true to log out everywhere)
 await auth.logout({ sessionId: session.sessionId });
-
-// Log out from all devices at once
-await auth.logout({ sessionId: session.sessionId, allDevices: true });
 ```
 
-### Session Management
+Store `session.sessionId` and `session.refreshToken` in your app. Sessions expire after **24 hours**, refresh tokens after **30 days**.
 
-Sessions expire after **24 hours**. Refresh tokens last **30 days**.
+### Session management
 
-```typescript
-// Refresh before expiry to get a new session
-const newSession = await auth.refreshSession({
-  refreshToken: session.refreshToken,
-});
-// Store newSession.sessionId and newSession.refreshToken
+```ts
+// Check if a session is still valid (use on your backend)
+const { user } = await auth.validateSession(session.sessionId);
 
-// Get a user by ID
-const user = await auth.getUser({ userId: session.userId });
+// Get a new session using the refresh token
+const newSession = await auth.refreshSession(session.refreshToken);
 ```
 
-### Validate a Session
+### User profile
 
-Use this on your backend to verify an incoming session is still active.
+```ts
+const user = await auth.getUser(session.userId);
 
-```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({
+await auth.updateUser({
   sessionId: session.sessionId,
   userId:    user.id,
-  updates: {
-    fullName: 'Alice Smith',
-    plan:     'enterprise',
-    // Any field on the user record can be updated here
-    avatar:   'https://example.com/avatar.jpg',
-  },
+  updates:   { fullName: 'Alice Johnson', plan: 'enterprise' },
 });
-```
-
-> ⚠️ The `updates` key is required — it wraps the fields to change. Fields not included in `updates` are left untouched.
 
-### Change Password
+await auth.deleteUser(session.sessionId, user.id);
+```
 
-Requires an active session — so a stolen old password alone is not enough.
+### Password & email
 
-```typescript
+```ts
+// Change password (requires active session)
 await auth.changePassword({
   sessionId:       session.sessionId,
   userId:          user.id,
   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)
+// Forgot password flow
+await auth.requestPasswordReset('alice@example.com');
+await auth.confirmPasswordReset(tokenFromEmail, 'newpassword123');
 
-// 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 the verification email
-await auth.requestEmailVerification({ userId: user.id });
-
-// 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' });
+// Email verification
+await auth.requestEmailVerification(user.id);
+await auth.confirmEmailVerification(tokenFromEmail);
 ```
 
-### Admin — List Users
+### Admin
 
-Admin operations require a valid session from a user with `role: 'admin'`.
-
-```typescript
-// Paginated list — uses cursor-based pagination
+```ts
+// List all users (paginated)
 const { users, hasMore, nextCursor } = await auth.listUsers({
   sessionId: adminSession.sessionId,
   limit:     50,
 });
 
-if (hasMore) {
-  const page2 = await auth.listUsers({
-    sessionId: adminSession.sessionId,
-    limit:     50,
-    cursor:    nextCursor!,
-  });
-}
-```
+// Lock / unlock an account
+await auth.lockAccount({ sessionId: adminSession.sessionId, userId: user.id });
+await auth.unlockAccount(adminSession.sessionId, user.id);
 
-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)
-const { lockedUntil, unlockTime } = await auth.lockAccount({
-  sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
-  duration:  60 * 60 * 1000, // 1 hour in ms (default: 15 minutes)
-});
-
-console.log(`Account locked until ${unlockTime}`);
-
-// Unlock manually
-await auth.unlockAccount({
-  sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
-});
-```
-
-### 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 — permanent, irreversible
-await auth.hardDeleteUser({
-  sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
-});
-
-// Bulk delete — up to 500 users, soft or hard
-const { succeeded, failed } = await auth.bulkDeleteUsers({
+// Delete users
+await auth.hardDeleteUser(adminSession.sessionId, user.id);
+await auth.bulkDeleteUsers({
   sessionId: adminSession.sessionId,
-  userIds:   ['usr_a', 'usr_b', 'usr_c'],
-  hard:      false, // set true for permanent deletion
+  userIds:   ['id1', 'id2'],
+  hard:      true,
 });
 ```
 
@@ -725,828 +239,318 @@ const { succeeded, failed } = await auth.bulkDeleteUsers({
 
 ## File Storage
 
-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
-const main      = db.storage('main');
-const avatars   = db.storage('avatars');
-const documents = db.storage('documents');
-```
-
-### Simple Upload
-
-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 — 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 (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 — use anywhere
-console.log(result.downloadUrl); // null when isPublic: true
-console.log(result.size);        // bytes
-console.log(result.mimeType);    // 'image/jpeg'
-
-// Node.js — from a Buffer or file path
-import { readFileSync } from 'fs';
-const buf    = readFileSync('./report.pdf');
-const result = await db.storage('documents').upload(buf, 'reports/q3.pdf');
-console.log(result.downloadUrl); // auth-required download URL
+```ts
+const storage = db.storage('main');
 ```
 
-### Upload Raw JSON or Text
+### Upload
 
-```typescript
-// Upload a JS object as JSON
-const result = await db.storage('main').uploadRaw(
-  { theme: 'dark', language: 'en', version: 3 },
-  'settings/alice.json',
-  { isPublic: false },
-);
+```ts
+// Simple upload (up to 500 MB)
+const result = await storage.upload(file, 'avatars/alice.jpg', { isPublic: true });
+console.log(result.publicUrl);    // permanent CDN URL
+console.log(result.downloadUrl);  // authenticated download URL (if private)
 
-// Upload a plain string
-await db.storage('main').uploadRaw(
-  '<html><body>Hello</body></html>',
-  'exports/page.html',
-  { mimeType: 'text/html', isPublic: true },
-);
+// Upload a JSON object or string directly
+await storage.uploadRaw({ theme: 'dark' }, 'config.json');
 ```
 
-### 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 the bytes.
-
-```typescript
-const storage = db.storage('main');
+**Large files with progress tracking** (recommended for anything > 10 MB):
 
-// Step 1 — Get a signed GCS upload URL
+```ts
+// Step 1 — get a signed upload URL
 const { uploadUrl, path } = await storage.getUploadUrl({
-  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 real progress
-await storage.uploadToSignedUrl(
-  uploadUrl,
-  file,
-  'video/mp4',
-  (percent) => {
-    progressBar.style.width = `${percent}%`;
-    console.log(`${percent}% uploaded`);
-  },
-);
-
-// Step 3 — Confirm the upload (registers metadata on the server)
-const result = await storage.confirmUpload({
-  path:     path,
+  path:     'videos/intro.mp4',
   mimeType: 'video/mp4',
+  size:     file.size,
   isPublic: true,
 });
 
-console.log(result.publicUrl); // live CDN URL
-```
-
-### Batch Upload
-
-Upload up to 50 files at once.
-
-```typescript
-const storage = db.storage('main');
-
-// 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 },
-]);
-
-// Step 2 — Upload each directly to GCS
-for (const f of files) {
-  await storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
-}
-
-// 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
-
-```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 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.
-
-### 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
-
-```typescript
-const storage = db.storage('main');
-
-// List everything at the root
-const { files, folders, hasMore, nextCursor } = await storage.list();
-
-// List a specific folder
-const result = await storage.list({
-  prefix: 'gallery/',
-  limit:  50,
+// Step 2 — upload directly to GCS (supports onProgress in browsers)
+await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => {
+  console.log(`${pct}% uploaded`);
 });
 
-// Paginate
-if (result.hasMore) {
-  const page2 = await storage.list({
-    prefix: 'gallery/',
-    cursor: result.nextCursor,
-  });
-}
-```
-
-Each file entry:
-
-```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',
-}
+// Step 3 — confirm and get the final result
+const result = await storage.confirmUpload({ path, mimeType: 'video/mp4', isPublic: true });
 ```
 
-### Scoped Storage
-
-Pre-fix all operations to a folder — great for per-user isolation.
+### Download, list, manage
 
-```typescript
-const userDocs = db.storage('documents').scope(`users/${userId}/`);
+```ts
+// Download a private file
+const buffer = await storage.download('private/doc.pdf');
 
-// Uploads to: users/{userId}/contract.pdf
-await userDocs.upload(pdfBuffer, 'contract.pdf');
+// List files
+const { files, folders, hasMore, nextCursor } = await storage.list({ prefix: 'avatars/' });
 
-// Lists:      users/{userId}/
-const { files } = await userDocs.list();
+// Get file metadata
+const meta = await storage.getMetadata('avatars/alice.jpg');
 
-// Deletes:    users/{userId}/contract.pdf
-await userDocs.deleteFile('contract.pdf');
+// Time-limited share link (no login needed to access)
+const { signedUrl } = await storage.getSignedUrl('private/report.pdf', 3600);
 
-// Nest scopes
-const userThumbs = userDocs.scope('thumbnails/');
-// All ops under: users/{userId}/thumbnails/
-```
-
-`ScopedStorage` has the same full API as `StorageManager` — every method listed in the reference is available.
-
-### File Metadata
-
-```typescript
-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
-```
-
-### Signed Share URLs
-
-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)
-
-// Share signedUrl with the recipient — it expires automatically
-console.log(`Link valid until: ${new Date(expiresAt).toLocaleString()}`);
-```
-
-> ⚠️ 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
+// Move, copy, delete
+await storage.move('old/path.jpg', 'new/path.jpg');
+await storage.copy('template.html', 'pages/home.html');
+await storage.deleteFile('avatars/old.jpg');
+await storage.deleteFolder('temp/');
 
-// Make a public file private
-const result2 = await db.storage('main').setVisibility('docs/report.pdf', false);
-console.log(result2.downloadUrl); // now requires auth
+// Change visibility after upload
+await storage.setVisibility('alice.jpg', false);  // make private
 ```
 
-### Move, Copy, Delete
-
-```typescript
-const storage = db.storage('main');
-
-// Rename a file
-await storage.move('drafts/report.pdf', 'published/report-2025.pdf');
-
-// Move to a different folder
-await storage.move('inbox/data.csv', 'archive/2025/data.csv');
+### Scoped storage
 
-// Copy
-await storage.copy('templates/invoice.html', 'invoices/inv-001.html');
+Automatically prefix every path — useful for per-user file isolation:
 
-// Create a folder placeholder
-await storage.createFolder('archive/2025/');
+```ts
+const userFiles = db.storage('main').scope(`users/${userId}/`);
 
-// Delete a single file
-await storage.deleteFile('temp/scratch.txt');
+await userFiles.upload(pdf, 'contract.pdf');      // → users/{userId}/contract.pdf
+const { files } = await userFiles.list();         // → only lists users/{userId}/
 
-// Delete a folder and all its contents recursively
-await storage.deleteFolder('temp/');
-```
-
-### 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();
+// Nest deeper
+const reports = userFiles.scope('reports/');      // → users/{userId}/reports/
 ```
 
 ---
 
 ## Analytics
 
-HydrousDB Analytics runs directly against BigQuery on your GCS data — zero ETL, no duplication, live results. Fast even on billions of records.
+BigQuery-powered aggregations. No ETL, no pipelines — just query.
 
-```typescript
+```ts
 const analytics = db.analytics('orders');
-```
 
-All `dateRange` values are Unix timestamps in milliseconds: `{ start?: number, end?: number }`.
-
-### Count
-
-```typescript
-// Total records
+// Total record count
 const { count } = await analytics.count();
 
-// In a date range
-const { count: lastWeek } = await analytics.count({
-  dateRange: {
-    start: Date.now() - 7 * 24 * 60 * 60 * 1000,
-    end:   Date.now(),
-  },
-});
-```
-
-### Distribution
-
-How many records have each unique value for a field?
-
-```typescript
-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  },
-// ]
-```
-
-### Sum
-
-```typescript
-// Total revenue
-const [{ sum: total }] = await analytics.sum({ field: 'amount' });
-
-// Revenue by country
-const byCountry = await analytics.sum({
-  field:   'amount',
-  groupBy: 'country',
-  limit:   10,
-});
-// [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, …]
-```
-
-### Time Series
-
-Record counts bucketed over time — ideal for activity and growth charts.
-
-```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 }, …]
-```
-
-### Field Time Series
-
-Aggregate a numeric field over time.
-
-```typescript
-const revenue = await analytics.fieldTimeSeries({
-  field:       'amount',
-  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-W02', value: 9872.00 }, …]
-```
+// How many records have each value of `status`
+const dist = await analytics.distribution({ field: 'status' });
 
-### Top N
+// Sum of `amount`, grouped by `region`
+const sums = await analytics.sum({ field: 'amount', groupBy: 'region' });
 
-Most common values for a field.
+// Records over time
+const daily = await analytics.timeSeries({ granularity: 'day' });
 
-```typescript
-const topProducts = await analytics.topN({
-  field:      'productId',
-  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 },
-// ]
-```
+// How `revenue` changes over time
+const trend = await analytics.fieldTimeSeries({ field: 'revenue', aggregation: 'sum' });
 
-### Field Stats
+// Top 10 countries by record count
+const top10 = await analytics.topN({ field: 'country', n: 10 });
 
-Statistical summary for any numeric field.
+// Min / max / avg / sum / stddev for a numeric field
+const stats = await analytics.stats({ field: 'price' });
 
-```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,
-// }
-```
-
-### Multi-Metric Dashboard
-
-Run several aggregations in a single BigQuery query — one network call.
-
-```typescript
+// Multiple aggregations in one round-trip
 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: 'uniqueOrders',  aggregation: 'count' },
+    { field: 'amount',   name: 'totalRevenue', aggregation: 'sum' },
+    { field: 'amount',   name: 'avgOrder',     aggregation: 'avg' },
+    { field: 'recordId', name: 'orderCount',   aggregation: 'count' },
   ],
-  dateRange: {
-    start: new Date('2025-01-01').getTime(),
-    end:   Date.now(),
-  },
 });
-// {
-//   totalRevenue:  198432.50,
-//   avgOrderValue: 87.23,
-//   maxOrder:      9999.99,
-//   uniqueOrders:  2275,
-// }
-```
-
-### Filtered Records via BigQuery
+// → { totalRevenue: 48200, avgOrder: 96.4, orderCount: 500 }
 
-Fetch raw records using the BigQuery engine — useful for large-scale filtered exports.
-
-```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,
-  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.
-
-```typescript
-const comparison = await analytics.crossBucket({
-  bucketKeys:  ['orders-us', 'orders-eu', 'orders-apac'],
+// Compare a metric across buckets
+const compare = await analytics.crossBucket({
+  bucketKeys:  ['orders-2024', 'orders-2025'],
   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 **every** bucket listed in `bucketKeys`.
-
-### Storage Stats
 
-```typescript
-const stats = await analytics.storageStats();
-// {
-//   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() },
+// All queries accept an optional date range
+const { count } = await analytics.count({
+  dateRange: { start: Date.now() - 7 * 24 * 60 * 60 * 1000, end: Date.now() },
 });
-
-console.log(result.queryType); // 'count'
-console.log(result.data);      // { count: 142 }
-```
-
----
-
-## TypeScript
-
-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 domain models
-interface Order {
-  customerId: string;
-  items:      Array<{ productId: string; qty: number; price: number }>;
-  total:      number;
-  status:     'pending' | 'processing' | 'completed' | 'refunded';
-  country:    string;
-}
-
-interface Customer {
-  name:    string;
-  email:   string;
-  tier:    'free' | 'pro' | 'enterprise';
-  credits: number;
-}
-
-const db = createClient({
-  authKey:           process.env.HYDROUS_AUTH_KEY!,
-  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
-  storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
-});
-
-// Fully typed — autocomplete, compile-time safety throughout
-const orders    = db.records<Order>('orders');
-const customers = db.records<Customer>('customers');
-
-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 ✓
-// orders.create({ bad: 1 }) ← TS error ✓
 ```
 
 ---
 
 ## Error Handling
 
-All SDK errors extend `HydrousError`. Specific sub-classes let you handle different failure modes precisely.
-
-```typescript
-import {
-  HydrousError,
-  AuthError,
-  RecordError,
-  StorageError,
-  AnalyticsError,
-  ValidationError,
-  NetworkError,
-} from 'hydrousdb';
+```ts
+import { HydrousError, NetworkError } from 'hydrousdb';
 
 try {
-  const record = await db.records('orders').get('bad-id');
+  await db.auth().login({ email: 'x@x.com', password: 'wrong' });
 } catch (err) {
+  if (err instanceof HydrousError) {
+    console.log(err.code);    // e.g. 'INVALID_CREDENTIALS'
+    console.log(err.status);  // e.g. 401
+    console.log(err.message); // human-readable
+  }
   if (err instanceof NetworkError) {
-    // No internet / server unreachable
-    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.status}:`, err.message);
-    console.error('Request ID:', err.requestId); // include in support tickets
+    console.log('No internet or server unreachable');
   }
 }
 ```
 
-**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 | 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 |
+| Error class | When it's thrown |
+|---|---|
+| `HydrousError` | Base class — all SDK errors extend this |
+| `AuthError` | Login failures, invalid sessions, permission denied |
+| `RecordError` | Record not found, validation failures |
+| `StorageError` | Upload/download failures, file not found |
+| `AnalyticsError` | Invalid query, bucket not found |
+| `NetworkError` | No network, request timed out |
+| `ValidationError` | Bad input caught client-side before the request is sent |
 
 ---
 
-## Security Best Practices
+## TypeScript
 
-**1. Never hard-code keys — use environment variables.**
+The SDK is written in TypeScript. Type your records for full autocomplete:
 
-```bash
-# .env  (add .env to your .gitignore)
-HYDROUS_AUTH_KEY=hk_auth_xxxxxxxxxxxxxxxxxxxx
-HYDROUS_BUCKET_KEY=hk_bucket_xxxxxxxxxxxxxxxxxxxx
-HYDROUS_STORAGE_MAIN=ssk_xxxxxxxxxxxxxxxxxxxx
-```
+```ts
+interface Order {
+  customerId: string;
+  amount:     number;
+  status:     'pending' | 'paid' | 'refunded';
+  items:      { sku: string; qty: number }[];
+}
 
-```typescript
-const db = createClient({
-  authKey:           process.env.HYDROUS_AUTH_KEY!,
-  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
-  storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
+const orders = db.records<Order>('orders');
+
+const order = await orders.create({
+  customerId: 'cust_123',
+  amount:     49.99,
+  status:     'pending',
+  items:      [{ sku: 'SHOE-42', qty: 1 }],
 });
+// order.status → 'pending' | 'paid' | 'refunded'  ✓
 ```
 
-**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 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.
-
-**5. Use scoped storage** (`db.storage('key').scope('prefix/')`) to isolate access per user or feature, reducing the blast radius of any misconfiguration.
-
-**6. Keep files private by default.** `isPublic` defaults to `false`. Use `getSignedUrl()` for time-limited external sharing rather than making files permanently public.
-
 ---
 
-## Full API Reference
-
-### `createClient(config)` → `HydrousClient`
+## Security
 
-| 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) |
+- **Never commit API keys.** Use environment variables (`process.env.…`).
+- **Never expose keys in the browser.** For client-side apps, proxy requests through your own backend.
+- **Keys travel in headers only** — the SDK enforces this. They never appear in URLs, access logs, or browser history.
+- **Files are private by default.** `isPublic` defaults to `false`. Use `getSignedUrl()` for temporary external sharing.
+- **Use scoped storage** (`storage.scope('prefix/')`) to isolate files per user.
 
 ---
 
-### `db.records<T>(bucketKey)` → `RecordsClient<T>`
+## Framework examples
 
-| 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
-{
-  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 }
+**Next.js (App Router)**
+```ts
+// lib/db.ts
+import { createClient } from 'hydrousdb';
+export const db = createClient({ … });
+
+// app/api/posts/route.ts
+import { db } from '@/lib/db';
+export async function GET() {
+  const { records } = await db.records('posts').query({ limit: 10 });
+  return Response.json(records);
 }
 ```
 
----
+**React (client-side via your own API)**
+```ts
+// Always go through your backend — never put keys in React components
+const res  = await fetch('/api/posts');
+const data = await res.json();
+```
 
-### `db.auth(bucketKey)` → `AuthClient`
+**Vue / Nuxt**
+```ts
+// composables/useDb.ts
+import { createClient } from 'hydrousdb';
+export const db = createClient({ … });
+```
 
-| 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. |
+**React Native**
+```ts
+import { createClient } from 'hydrousdb';
+// Works out of the box — uses the global fetch available in React Native
+const db = createClient({ … });
+```
 
 ---
 
-### `db.storage(keyName)` → `StorageManager`
+## API Reference
 
-| 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. |
+### `createClient(config)`
 
----
+| Field | Type | Description |
+|---|---|---|
+| `authKey` | `string` | `hk_auth_…` — for auth routes |
+| `bucketSecurityKey` | `string` | `hk_bucket_…` — for records & analytics |
+| `storageKeys` | `{ [name]: string }` | One or more `ssk_…` keys for storage |
+| `baseUrl` | `string` | Override the endpoint (optional) |
 
-### `db.analytics(bucketKey)` → `AnalyticsClient`
+### `db.records(bucket)` — key methods
 
-| 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. |
+| Method | What it does |
+|---|---|
+| `create(data, opts?)` | Create a record. Use `opts.queryableFields` to enable filtering. |
+| `get(id)` | Fetch by ID. |
+| `patch(id, data)` | Partial update — only the fields you pass are changed. |
+| `delete(id)` | Permanent delete. |
+| `query(opts?)` | Filter, sort, paginate. |
+| `batchCreate(items, opts?)` | Up to 500 at once. |
+| `batchUpdate(updates)` | Up to 500 at once. |
+| `batchDelete(ids)` | Up to 500 at once. |
+| `getHistory(id)` | Full version list. |
+| `getVersion(id, generation)` | Read a past version. |
+| `exists(id)` | Lightweight existence check (HEAD request). |
+
+### `db.auth()` — key methods
+
+| Method | What it does |
+|---|---|
+| `signup(opts)` | Register + create session. |
+| `login(opts)` | Authenticate + create session. |
+| `logout({ sessionId })` | Revoke session(s). |
+| `validateSession(sessionId)` | Check if a session is active. |
+| `refreshSession(refreshToken)` | Get a new session from a refresh token. |
+| `getUser(userId)` | Fetch a user by ID. |
+| `updateUser(opts)` | Update profile fields. |
+| `changePassword(opts)` | Authenticated password change. |
+| `requestPasswordReset(email)` | Trigger reset email. |
+| `confirmPasswordReset(token, newPw)` | Apply new password. |
+| `listUsers(opts)` | Paginated user list (admin). |
+| `lockAccount(opts)` / `unlockAccount(…)` | Admin account controls. |
+| `hardDeleteUser(sessionId, userId)` | Permanent delete (admin). |
+
+### `db.storage(keyName)` — key methods
+
+| Method | What it does |
+|---|---|
+| `upload(data, path, opts?)` | Server-buffered upload (up to 500 MB). |
+| `uploadRaw(data, path, opts?)` | Upload a JS object or string as a file. |
+| `getUploadUrl(opts)` | Step 1 of direct-to-GCS upload (for progress tracking). |
+| `uploadToSignedUrl(url, data, mime, onProgress?)` | Step 2 — upload directly to GCS. |
+| `confirmUpload(opts)` | Step 3 — register metadata. |
+| `download(path)` | Download a private file as ArrayBuffer. |
+| `list(opts?)` | List files and folders. |
+| `getMetadata(path)` | File size, MIME, visibility, URLs. |
+| `getSignedUrl(path, expiresIn?)` | Time-limited share link. |
+| `setVisibility(path, isPublic)` | Toggle public/private. |
+| `move(from, to)` / `copy(from, to)` | Move or copy files. |
+| `deleteFile(path)` / `deleteFolder(path)` | Delete files or folders. |
+| `scope(prefix)` | Get a path-prefixed sub-client. |
+
+### `db.analytics(bucket)` — key methods
+
+| Method | What it does |
+|---|---|
+| `count(opts?)` | Total record count. |
+| `distribution(opts)` | Per-value counts for a field. |
+| `sum(opts)` | Sum a numeric field, optional `groupBy`. |
+| `timeSeries(opts?)` | Record counts over time. |
+| `fieldTimeSeries(opts)` | Field aggregation over time. |
+| `topN(opts)` | Most frequent field values. |
+| `stats(opts)` | min / max / avg / sum / stddev. |
+| `multiMetric(opts)` | Multiple aggregations in one request. |
+| `crossBucket(opts)` | Compare a metric across buckets. |
+| `records(opts?)` | Filtered records via BigQuery. |
 
 ---
 
@@ -1555,24 +559,17 @@ const db = createClient({
 ```bash
 git clone https://github.com/hydrousdb/hydrousdb-js.git
 cd hydrousdb-js
-
-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
+npm install
+npm test        # run tests
+npm run build   # compile
 ```
 
----
-
 ## License
 
-MIT — see [LICENSE](./LICENSE) for details.
+MIT — [LICENSE](./LICENSE)
 
 ---
 
 <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>
+  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>