hydrousdb 3.2.0 → 3.5.1

package/README.md

@@ -1,723 +1,486 @@
-# 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>
+**A database that doesn't choke on big JSON.** Store, query, and analyse massive records — with auth and file storage built in.
 
-<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>
+```bash
+npm install hydrousdb
+```
+
+→ [Get your free API keys at hydrousdb.com](https://hydrousdb.com/dashboard)
 
 ---
 
 ## 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)
+- [Setup](#setup)
 - [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)
+  - [Create, Read, Update, Delete](#create-read-update-delete)
+  - [Querying & Filtering](#querying--filtering)
+  - [Time Scope on Queries](#time-scope-on-queries)
+  - [Pagination](#pagination)
+  - [Atomic Field Updates](#atomic-field-updates)
+  - [Batch Operations](#batch-operations)
   - [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)
+  - [Existence Check](#existence-check)
+  - [Get All Records](#get-all-records)
+- [Auth](#auth)
+  - [Sign Up & Log In](#sign-up--log-in)
   - [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)
+  - [User Profile](#user-profile)
+  - [Password & Email](#password--email)
+  - [Admin Controls](#admin-controls)
 - [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)
+  - [Upload](#upload)
+  - [Large Files with Progress](#large-files-with-progress)
+  - [Batch Uploads](#batch-uploads)
   - [Download](#download)
   - [Batch Download](#batch-download)
-  - [List Files](#list-files)
-  - [Scoped Storage](#scoped-storage)
-  - [File Metadata](#file-metadata)
-  - [Signed Share URLs](#signed-share-urls)
+  - [List, Metadata & Signed URLs](#list-metadata--signed-urls)
+  - [Move, Copy & Delete](#move-copy--delete)
   - [Visibility](#visibility)
-  - [Move, Copy, Delete](#move-copy-delete)
+  - [Folders](#folders)
+  - [Scoped Storage](#scoped-storage)
   - [Storage Stats](#storage-stats)
 - [Analytics](#analytics)
-  - [Count](#count-1)
+  - [Date Range (Time Scope)](#date-range-time-scope)
+  - [Count](#count)
   - [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)
+  - [Stats](#stats)
+  - [Records via BigQuery](#records-via-bigquery)
+  - [Multi-Metric](#multi-metric)
   - [Storage Stats](#storage-stats-1)
+  - [Cross-Bucket](#cross-bucket)
   - [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.
+- [TypeScript](#typescript)
+- [Security](#security)
+- [Framework Examples](#framework-examples)
+- [API Reference](#api-reference)
 
 ---
 
-## 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
-
-```bash
-npm install hydrousdb
-# or: yarn add hydrousdb  /  pnpm add hydrousdb
-```
-
-**Requirements:** Node.js 18+ (uses the native `fetch` API).
-
-### 4. Create the client and write your first record
+## Setup
 
-```typescript
+```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!,
+  authKey:           process.env.HYDROUS_AUTH_KEY!,          // hk_auth_…
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,        // hk_bucket_…
   storageKeys: {
-    main: process.env.HYDROUS_STORAGE_MAIN!,
+    main: process.env.HYDROUS_STORAGE_KEY!,                  // ssk_…
+    // add more named storage keys as needed
   },
+  // baseUrl: 'https://custom-endpoint.example.com',         // optional override
 });
-
-// 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';
-```
-
-```javascript
-// CommonJS — legacy Node, Jest without transform, older tooling
-const { createClient } = require('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.
 
-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 automatically gets `id`, `createdAt`, and `updatedAt`.
 
-```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:
+### Create, Read, Update, Delete
 
-```typescript
+```ts
+// Create
 const post = await posts.create(
+  { title: 'Hello', status: 'draft', views: 0 },
   {
-    title:    'My First Post',
-    status:   'draft',
-    authorId: 'usr_abc',
-  },
-  {
-    queryableFields: ['status', 'authorId'],   // index these for filtering
-    userEmail:       'alice@example.com',       // optional audit trail
+    queryableFields: ['status', 'views'],  // declare fields you want to filter on
+    userEmail: 'alice@example.com',        // optional — for audit trails
   },
 );
-```
+console.log(post.id);        // "260601-rec_01JA2XYZ"
+console.log(post.createdAt); // Unix ms timestamp
 
-> 💡 **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 by ID
+const found = await posts.get(post.id);
 
-### Read a Record
+// Partial update — only the fields you pass are changed
+await posts.patch(post.id, { status: 'published' });
 
-```typescript
-// Path computed from the ID in memory — zero index reads
-const post = await posts.get('260601-rec_01JA2XYZ');
+// Merge mode — deeply merge nested objects instead of replacing them
+await posts.patch(post.id, { meta: { seo: true } }, { merge: true });
 
-// Throws HydrousError (code: RECORD_NOT_FOUND) if the ID doesn't exist
+// Delete permanently
+await posts.delete(post.id);
 ```
 
-### Update a Record
-
-**`patch(id, data)` — merge update.** Only the fields you provide are changed. All other fields on the record are left untouched.
+> **Why `queryableFields`?** Records are stored as compressed blobs. Fields you want to filter or sort by must be declared at write time. You only pay the indexing overhead for what you actually query.
 
-```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.
+### Querying & Filtering
 
-```typescript
-const replaced = await posts.set('260601-rec_01JA2XYZ', {
-  title:  'Updated Title',
-  body:   'New content.',
-  status: 'published',
-  views:  42,
+```ts
+const { records, hasMore, nextCursor } = await posts.query({
+  filters: [
+    { field: 'status', op: '==',       value: 'published' },
+    { field: 'views',  op: '>',        value: 100 },
+    { field: 'title',  op: 'contains', value: 'hello' },
+  ],
+  orderBy: 'createdAt',
+  order:   'desc',
+  limit:   20,
+  fields:  'id,title,status', // optional — return only these fields
 });
 ```
 
-**Disable merge** (force field removal):
+**Supported filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`
 
-```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 posts.delete('260601-rec_01JA2XYZ');
-```
+---
 
-### Query Records
+### Time Scope on Queries
 
-```typescript
-// All records (up to 100 by default)
-const { records } = await posts.query();
+Pass `timeScope` to restrict records to a specific **day, month, or year** using the record ID prefix convention. This is the fastest way to scope a query by time — no timestamp arithmetic needed.
 
-// With filters
-const { records: published } = await posts.query({
-  filters: [
-    { field: 'status', op: '==', value: 'published' },
-  ],
-});
+| Scope | Format | Example | Matches |
+|---|---|---|---|
+| Day | `_day_YYMMDD` | `_day_260305` | March 5, 2026 |
+| Month | `_month_YYMM` | `_month_2603` | March 2026 |
+| Year | `_year_YY` | `_year_26` | All of 2026 |
 
-// Multiple filters, sort, limit
+```ts
+// All records from March 2026
 const { records, hasMore, nextCursor } = await posts.query({
-  filters: [
-    { field: 'status',   op: '==', value: 'published' },
-    { field: 'views',    op: '>',  value: 100          },
-  ],
-  orderBy: 'createdAt',
-  order:   'desc',
-  limit:   20,
+  timeScope: '_month_2603',
+  order:     'desc',
+  limit:     50,
 });
 
-// Next page
+// Paginate through a time-scoped result set
 if (hasMore) {
   const page2 = await posts.query({
-    orderBy:    'createdAt',
-    order:      'desc',
-    limit:      20,
+    timeScope:  '_month_2603',
     startAfter: nextCursor,
   });
 }
 
-// Select only specific fields (reduces payload size)
-const { records: light } = await posts.query({
-  fields: 'id,title,status,createdAt',
+// A specific day
+const { records: dayRecords } = await posts.query({
+  timeScope: '_day_260305',   // March 5, 2026
+  order:     'asc',
 });
 
-// Date range
-const { records: thisWeek } = await posts.query({
-  dateRange: {
-    start: Date.now() - 7 * 24 * 60 * 60 * 1000,
-    end:   Date.now(),
-  },
+// An entire year
+const { records: yearRecords } = await posts.query({
+  timeScope: '_year_26',
+  orderBy:   'createdAt',
+  order:     'asc',
+  limit:     100,
 });
+
+// Fully composable with filters
+const { records: published } = await posts.query({
+  timeScope: '_month_2603',
+  filters:   [{ field: 'status', op: '==', value: 'published' }],
+  orderBy:   'createdAt',
+  order:     'desc',
+});
+
+// getAll() also respects timeScope
+const all = await posts.getAll({ timeScope: '_year_26' });
 ```
 
-**Filter operators:**
+---
 
-| Operator | Meaning |
-|---|---|
-| `==` | Equal |
-| `!=` | Not equal |
-| `>` | Greater than |
-| `<` | Less than |
-| `>=` | Greater than or equal |
-| `<=` | Less than or equal |
-| `CONTAINS` | String contains |
+### Pagination
 
-> ⚠️ You can only filter on fields declared as `queryableFields` when the record was created. Filtering on an un-indexed field returns no results.
+`query()` returns a cursor you can pass straight into the next call.
 
-### Count Records
+```ts
+// Page 1
+const page1 = await posts.query({ limit: 20, orderBy: 'createdAt', order: 'desc' });
 
-```typescript
-// Total records in the bucket
-const total = await posts.count();
+// Page 2
+if (page1.hasMore) {
+  const page2 = await posts.query({
+    limit:      20,
+    orderBy:    'createdAt',
+    order:      'desc',
+    startAfter: page1.nextCursor,   // cursor-based — no offset drift
+  });
+}
 
-// Records matching filters
-const publishedCount = await posts.count([
-  { field: 'status', op: '==', value: 'published' },
-]);
+// You can also use startAt / endAt for range-based cursor control
+const window = await posts.query({ startAt: cursorA, endAt: cursorB });
 ```
 
-### Batch Create
-
-Up to 500 records per call.
+---
 
-```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',
-  },
-);
-// → [{ id: '…', title: 'Post A', … }, { id: '…', title: 'Post B', … }, …]
+### Atomic Field Updates
+
+Avoid race conditions with server-side sentinels inside `patch()`:
+
+```ts
+await posts.patch(post.id, {
+  views:    { __op: 'increment',      delta: 1 },          // add N
+  credits:  { __op: 'decrement',      delta: 5 },          // subtract N
+  slug:     { __op: 'setOnce',        value: 'my-post' },  // set only if currently empty
+  tags:     { __op: 'appendUnique',   item: 'featured' },  // add to array, no duplicates
+  tags:     { __op: 'removeFromArray', item: 'draft' },    // remove from array
+  rating:   { __op: 'clamp',          value: 6, min: 0, max: 5 }, // clamp to range
+  price:    { __op: 'multiplyBy',     factor: 1.1 },       // multiply
+  active:   { __op: 'toggleBool' },                        // flip boolean
+  syncedAt: { __op: 'serverTimestamp' },                   // set to server time
+} as any);
 ```
 
-Each record in the batch can optionally carry a `_customRecordId` for upsert behaviour:
+Enable audit trails and history with extra `patch` options:
 
-```typescript
-await posts.batchCreate([
-  { _customRecordId: '260601-post_welcome', title: 'Welcome', status: 'published' },
-  { title: 'Auto-ID post', status: 'draft' },
-]);
+```ts
+await posts.patch(
+  post.id,
+  { status: 'published' },
+  { userEmail: 'alice@example.com', trackHistory: true },
+);
 ```
 
-### Batch Delete
+---
 
-Up to 500 records per call.
+### Batch Operations
 
-```typescript
-const { deleted, failed } = await posts.batchDelete([
-  '260601-rec_01JA',
-  '260601-rec_02JB',
-  '260601-rec_03JC',
-]);
+```ts
+// Create up to 500 records at once
+const { results, errors, successful, failed } = await posts.batchCreate(
+  [{ title: 'A', status: 'draft' }, { title: 'B', status: 'draft' }],
+  { queryableFields: ['title', 'status'], userEmail: 'alice@example.com' },
+);
 
-console.log(`Deleted: ${deleted}, Failed: ${failed.length}`);
+// Update up to 500 records at once
+const { successful, failed } = await posts.batchUpdate(
+  [
+    { recordId: 'id1', values: { status: 'archived' } },
+    { recordId: 'id2', values: { status: 'archived' } },
+  ],
+  'alice@example.com', // optional userEmail
+);
+
+// Delete up to 500 records at once
+const { successful, failed } = await posts.batchDelete(['id1', 'id2']);
 ```
 
-### Version History
+Batch upsert using custom IDs — include `_customRecordId` on each item:
 
-Every write creates a new version — you can restore any record to any previous state.
+```ts
+await posts.batchCreate([
+  { _customRecordId: '260601-post_hello', title: 'Hello' },
+  { _customRecordId: '260601-post_world', title: 'World' },
+] as any);
+```
 
-```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);
-```
+### Version History
 
-### Write-Filter Sentinels
+Every write is automatically versioned when `trackHistory` is enabled.
 
-For atomic server-side field operations — use these inside `patch()` to avoid race conditions.
+```ts
+// List all saved versions
+const history = await posts.getHistory(post.id);
+// → [{ generation, savedAt, savedBy, sizeBytes }, …]
 
-```typescript
-await posts.patch('260601-rec_01JA', {
-  // Increment / decrement a numeric field atomically
-  views:    { __op: 'increment', delta: 1 },
-  credits:  { __op: 'decrement', delta: 5 },
+// Retrieve a specific past version
+const v1 = await posts.getVersion(post.id, history[0].generation!);
+```
 
-  // 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 } },
+### Custom Record IDs
 
-  // Add to an array (no duplicates)
-  tags:     { __op: 'appendUnique', item: 'featured' },
+Supply your own ID at creation time — if it already exists the record is upserted in-place.
 
-  // Remove from an array
-  tags:     { __op: 'removeFromArray', item: 'draft' },
+```ts
+// Format: YYMMDD-segment1__segment2
+const post = await posts.create(
+  { title: 'Welcome' },
+  { customRecordId: '260601-post_welcome' },
+);
+```
 
-  // 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 },
+### Existence Check
 
-  // Flip a boolean
-  active:   { __op: 'toggleBool' },
+A lightweight HEAD request — much cheaper than fetching the full record:
 
-  // Set field to the server's current timestamp
-  lastSeen: { __op: 'serverTimestamp' },
-} as any);
+```ts
+const exists = await posts.exists(post.id); // true | false
 ```
 
-### Custom Record IDs
+---
 
-Provide your own ID instead of using an auto-generated one. If the ID already exists, the record is upserted.
+### Get All Records
 
-```typescript
-// Single record
-const post = await posts.create(
-  { title: 'Welcome', status: 'published' },
-  { customRecordId: '260601-post_welcome' },
-);
+Fetches every record matching the options without filter support. Use `query()` when you need filters.
 
-// Batch — set _customRecordId on individual items
-await posts.batchCreate([
-  { _customRecordId: '260601-post_welcome', title: 'Welcome' },
-  { title: 'Auto-ID post' },
-]);
+```ts
+const all = await posts.getAll({
+  orderBy: 'createdAt',
+  order:   'desc',
+  limit:   500,
+});
 ```
 
-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 this device
 await auth.logout({ sessionId: session.sessionId });
 
-// Log out from all devices at once
+// Log out everywhere
 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 last **30 days**.
+| Token | Lifetime |
+|---|---|
+| `sessionId` | 24 hours |
+| `refreshToken` | 30 days |
 
-```typescript
-// Refresh before expiry to get a new session
-const newSession = await auth.refreshSession({
-  refreshToken: session.refreshToken,
-});
-// Store newSession.sessionId and newSession.refreshToken
+---
 
-// Get a user by ID
-const user = await auth.getUser({ userId: session.userId });
-```
+### Session Management
 
-### Validate a Session
+```ts
+// Validate a session and get the current user (use on your backend)
+const { user, session } = await auth.validateSession(session.sessionId);
+// session → { sessionId, expiresAt }
 
-Use this on your backend to verify an incoming session is still active.
+// Get a brand-new session from a refresh token (before the old one expires)
+const newSession = await auth.refreshSession(session.refreshToken);
+```
 
-```typescript
-const { user, session: activeSession } = await auth.validateSession({
-  sessionId: session.sessionId,
-});
+---
 
-console.log(user.id);                  // "usr_xxxxxxxxxxxx"
-console.log(activeSession.expiresAt);  // timestamp
-```
+### User Profile
 
-### Update Profile
+```ts
+// Fetch a user by ID
+const user = await auth.getUser(session.userId);
 
-```typescript
-const updated = await auth.updateUser({
+// Update profile fields (users can update themselves; admins can update anyone)
+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' },
 });
+
+// Soft-delete (users can delete themselves; admins can delete anyone)
+await auth.deleteUser(session.sessionId, user.id);
 ```
 
-> ⚠️ The `updates` key is required — it wraps the fields to change. Fields not included in `updates` are left untouched.
+The `UserRecord` shape:
+
+```ts
+interface UserRecord {
+  id:             string;
+  email:          string;
+  fullName?:      string | null;
+  emailVerified:  boolean;
+  accountStatus:  'active' | 'locked' | 'suspended';
+  role:           'user' | 'admin';
+  createdAt:      number;   // Unix ms
+  updatedAt:      number;   // Unix ms
+  metadata?:      Record<string, unknown>;
+  [key: string]:  unknown;  // custom fields from signup
+}
+```
 
-### Change Password
+---
 
-Requires an active session — so a stolen old password alone is not enough.
+### Password & Email
 
-```typescript
+```ts
+// Change password — requires an active session AND the current password
 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' });
+// Forgot-password flow
+await auth.requestPasswordReset('alice@example.com');  // always succeeds (prevents enumeration)
+await auth.confirmPasswordReset(tokenFromEmail, 'newpassword123');
 
-// 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
+await auth.requestEmailVerification(user.id);
+await auth.confirmEmailVerification(tokenFromEmail);
 ```
 
-### 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' });
-```
+---
 
-### Admin — List Users
+### Admin Controls
 
-Admin operations require a valid session from a user with `role: 'admin'`.
+All admin methods require an active admin session.
 
-```typescript
-// Paginated list — uses cursor-based pagination
+```ts
+// Paginated user list
 const { users, hasMore, nextCursor } = await auth.listUsers({
   sessionId: adminSession.sessionId,
   limit:     50,
+  cursor:    previousNextCursor, // optional — for subsequent pages
 });
 
-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)
+// Lock an account (default: 15 minutes)
 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',
+  userId:    user.id,
+  duration:  60 * 60 * 1000, // optional ms — lock for 1 hour
 });
-```
 
-### Admin — Delete Users
+// Unlock an account
+await auth.unlockAccount(adminSession.sessionId, user.id);
 
-```typescript
-// Soft-delete — marks the account as deleted, keeps the data
-await auth.deleteUser({
-  sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
-});
+// Permanent (hard) delete — cannot be undone
+await auth.hardDeleteUser(adminSession.sessionId, user.id);
 
-// Hard-delete — permanent, irreversible
-await auth.hardDeleteUser({
-  sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
-});
-
-// Bulk delete — up to 500 users, soft or hard
+// Bulk delete — 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
+  userIds:   ['id1', 'id2', 'id3'],
+  hard:      true, // optional — defaults to soft delete
 });
 ```
 
@@ -725,323 +488,279 @@ 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.
+Files are **private by default** and scoped to your storage key server-side.
 
-```typescript
-const main      = db.storage('main');
-const avatars   = db.storage('avatars');
-const documents = db.storage('documents');
+```ts
+const storage = db.storage('main'); // 'main' matches a key in storageKeys config
 ```
 
-### Simple Upload
+### 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
+```ts
+// Simple upload — anything up to 500 MB
+const result = await storage.upload(file, 'avatars/alice.jpg', {
+  isPublic:        true,     // public CDN URL (default: false)
+  overwrite:       true,     // replace if the path exists (default: false)
+  mimeType:        'image/jpeg',  // optional — auto-detected from content if omitted
+  expiresInSeconds: 3600,    // optional — auto-delete after N seconds
 });
+console.log(result.publicUrl);   // permanent CDN URL (if isPublic: true)
+console.log(result.downloadUrl); // authenticated URL (if private)
+console.log(result.path);
+console.log(result.size);
+console.log(result.mimeType);
 
-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
+// Upload a JS object or string directly as a file
+await storage.uploadRaw({ theme: 'dark', lang: 'en' }, 'settings/config.json');
+await storage.uploadRaw('<html>…</html>', 'pages/home.html', { mimeType: 'text/html' });
 ```
 
-### Upload Raw JSON or Text
-
-```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 },
-);
-
-// 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
+---
 
-For files over ~10 MB or when you need a progress bar. The file goes **directly to GCS** — your server never buffers the bytes.
+### Large Files with Progress
 
-```typescript
-const storage = db.storage('main');
+Recommended for files > 10 MB or when you need a progress indicator (browsers only).
 
-// 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,
-  expiresInSeconds: 900, // how long the signed URL is valid (default: 900 = 15 min)
+```ts
+// Step 1 — get a signed GCS PUT URL
+const { uploadUrl, path, expiresAt, expiresIn } = await storage.getUploadUrl({
+  path:             'videos/intro.mp4',
+  mimeType:         'video/mp4',
+  size:             file.size,
+  isPublic:         true,
+  overwrite:        false,
+  expiresInSeconds: 3600, // URL lifetime
 });
 
-// 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 2 — upload directly to GCS with progress callback (browser XHR)
+await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', (percent) => {
+  console.log(`${percent}% uploaded`);
+});
 
-// Step 3 — Confirm the upload (registers metadata on the server)
+// Step 3 — confirm and register metadata server-side
 const result = await storage.confirmUpload({
-  path:     path,
+  path,
   mimeType: 'video/mp4',
   isPublic: true,
 });
-
-console.log(result.publicUrl); // live CDN URL
 ```
 
-### Batch Upload
+---
 
-Upload up to 50 files at once.
+### Batch Uploads
 
-```typescript
-const storage = db.storage('main');
+Get signed URLs for up to 50 files at once, upload them in parallel, then confirm in one call.
 
-// 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 },
+```ts
+// Step 1 — get signed URLs for multiple files
+const { files: urls } = await storage.getBatchUploadUrls([
+  { path: 'docs/a.pdf', mimeType: 'application/pdf', size: fileA.size, isPublic: false },
+  { path: 'docs/b.pdf', mimeType: 'application/pdf', size: fileB.size, isPublic: false },
 ]);
 
-// 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 })),
+// Step 2 — upload each file (run in parallel)
+await Promise.all(
+  urls.map(({ uploadUrl, path }, i) =>
+    storage.uploadToSignedUrl(uploadUrl, files[i], 'application/pdf'),
+  ),
 );
 
-console.log(`${succeeded.length} uploaded, ${failed.length} failed`);
-for (const f of succeeded) {
-  console.log(f.publicUrl);
-}
+// Step 3 — confirm all at once
+const { succeeded, failed } = await storage.batchConfirmUploads([
+  { path: 'docs/a.pdf', mimeType: 'application/pdf' },
+  { path: 'docs/b.pdf', mimeType: 'application/pdf' },
+]);
 ```
 
+---
+
 ### 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' });
+```ts
+// Download a private file as ArrayBuffer
+const buffer = await storage.download('private/report.pdf');
 
-// Trigger browser download
+// Convert to a Blob for use in the browser
+const blob = new Blob([buffer], { type: 'application/pdf' });
 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.
+For **public** files, just use the `publicUrl` directly — no SDK or authentication needed.
+
+---
 
 ### Batch Download
 
-Download up to 20 files in one call. Content is returned as base64 strings.
+Downloads up to 20 files at once. Content is returned as base64-encoded strings.
 
-```typescript
-const { succeeded, failed } = await db.storage('documents').batchDownload([
-  'reports/q1.pdf',
-  'reports/q2.pdf',
-  'reports/q3.pdf',
+```ts
+const { succeeded, failed } = await storage.batchDownload([
+  'docs/report.pdf',
+  'images/chart.png',
 ]);
 
-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 file of succeeded) {
+  console.log(file.path, file.mimeType, file.size);
+  // file.content is base64 — decode with atob() or Buffer.from(content, 'base64')
 }
 
-for (const f of failed) {
-  console.error(`${f.path}: ${f.error}`);
+for (const err of failed) {
+  console.error(err.path, err.error, err.code);
 }
 ```
 
-### List Files
-
-```typescript
-const storage = db.storage('main');
+---
 
-// List everything at the root
-const { files, folders, hasMore, nextCursor } = await storage.list();
+### List, Metadata & Signed URLs
 
-// List a specific folder
-const result = await storage.list({
-  prefix: 'gallery/',
-  limit:  50,
+```ts
+// List files and folders (paginated)
+const { files, folders, hasMore, nextCursor } = await storage.list({
+  prefix:    'avatars/',  // optional path prefix to list under
+  limit:     50,
+  cursor:    previousNextCursor,
+  recursive: true,  // include files in sub-folders (default: false)
 });
 
-// Paginate
-if (result.hasMore) {
-  const page2 = await storage.list({
-    prefix: 'gallery/',
-    cursor: result.nextCursor,
-  });
+// Page 2
+if (hasMore) {
+  const page2 = await storage.list({ prefix: 'avatars/', cursor: 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',
-}
+// Get file metadata
+const meta = await storage.getMetadata('avatars/alice.jpg');
+// → { path, size, mimeType, isPublic, publicUrl, downloadUrl, createdAt, updatedAt }
+
+// Generate a time-limited link — anyone with the URL can download (no key needed)
+// Note: downloads via signed URL bypass the server, so download stats are NOT tracked
+const { signedUrl, expiresAt, expiresIn } = await storage.getSignedUrl(
+  'private/report.pdf',
+  3600, // lifetime in seconds (default: 3600)
+);
 ```
 
-### Scoped Storage
+---
 
-Pre-fix all operations to a folder — great for per-user isolation.
+### Move, Copy & Delete
 
-```typescript
-const userDocs = db.storage('documents').scope(`users/${userId}/`);
+```ts
+await storage.move('old/path.jpg', 'new/path.jpg');
+await storage.copy('templates/base.html', 'pages/home.html');
+await storage.deleteFile('avatars/old.jpg');
+await storage.deleteFolder('temp/');  // recursively deletes all contents
+```
 
-// Uploads to: users/{userId}/contract.pdf
-await userDocs.upload(pdfBuffer, 'contract.pdf');
+---
 
-// Lists:      users/{userId}/
-const { files } = await userDocs.list();
+### Visibility
 
-// Deletes:    users/{userId}/contract.pdf
-await userDocs.deleteFile('contract.pdf');
+```ts
+// Make a private file public
+const result = await storage.setVisibility('reports/q1.pdf', true);
+console.log(result.publicUrl);
 
-// Nest scopes
-const userThumbs = userDocs.scope('thumbnails/');
-// All ops under: users/{userId}/thumbnails/
+// Make a public file private
+await storage.setVisibility('reports/q1.pdf', false);
 ```
 
-`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');
+### Folders
 
-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
+```ts
+// Create an explicit folder marker (usually not needed — folders are implicit)
+await storage.createFolder('projects/2025/');
 ```
 
-### Signed Share URLs
+---
 
-Generate a time-limited link for a private file — no `X-Storage-Key` required to use it.
+### Scoped Storage
 
-```typescript
-const { signedUrl, expiresAt, expiresIn } = await db.storage('documents')
-  .getSignedUrl('reports/q3.pdf', 3600); // expires in 1 hour (default)
+Automatically prefix every path — ideal for per-user file isolation.
 
-// Share signedUrl with the recipient — it expires automatically
-console.log(`Link valid until: ${new Date(expiresAt).toLocaleString()}`);
-```
+```ts
+const userFiles = db.storage('main').scope(`users/${userId}/`);
 
-> ⚠️ Downloads via signed URLs bypass the server — **download stats are not tracked** for those requests. Use `downloadUrl` for tracked downloads.
+await userFiles.upload(pdf, 'contract.pdf');      // → users/{userId}/contract.pdf
+await userFiles.uploadRaw({ key: 'val' }, 'prefs.json');
+const { files } = await userFiles.list();          // → only lists users/{userId}/
 
-### Visibility
+// Nest deeper
+const reports = userFiles.scope('reports/');       // → users/{userId}/reports/
+await reports.upload(file, 'q1.pdf');              // → users/{userId}/reports/q1.pdf
 
-```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
+// All StorageManager methods are available on ScopedStorage
+const meta        = await userFiles.getMetadata('contract.pdf');
+const { signedUrl } = await userFiles.getSignedUrl('contract.pdf', 900);
+await userFiles.move('old.pdf', 'new.pdf');
+await userFiles.deleteFile('contract.pdf');
+await userFiles.deleteFolder('reports/');
 ```
 
-### Move, Copy, Delete
+---
 
-```typescript
-const storage = db.storage('main');
+### Storage Stats
 
-// Rename a file
-await storage.move('drafts/report.pdf', 'published/report-2025.pdf');
+```ts
+// Stats for this storage key
+const stats = await storage.getStats();
+// → { totalFiles, totalBytes, uploadCount, downloadCount, deleteCount }
 
-// Move to a different folder
-await storage.move('inbox/data.csv', 'archive/2025/data.csv');
+// Server info (no auth required)
+const info = await storage.info();
+// → { ok: true, storageRoot: '…' }
+```
 
-// Copy
-await storage.copy('templates/invoice.html', 'invoices/inv-001.html');
+---
 
-// Create a folder placeholder
-await storage.createFolder('archive/2025/');
+## Analytics
 
-// Delete a single file
-await storage.deleteFile('temp/scratch.txt');
+BigQuery-powered aggregations. No ETL, no pipelines — just query.
 
-// Delete a folder and all its contents recursively
-await storage.deleteFolder('temp/');
+```ts
+const analytics = db.analytics('orders');
 ```
 
-### Storage Stats
+### Date Range (Time Scope)
 
-```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();
+Almost every analytics method accepts an optional `dateRange` to restrict results to a time window. Both `start` and `end` are Unix timestamps **in milliseconds** — the server converts them to ISO strings internally. Both fields are optional; omit either for an open-ended range.
+
+```ts
+interface DateRange {
+  start?: number;  // Unix ms — inclusive lower bound
+  end?:   number;  // Unix ms — inclusive upper bound
+}
 ```
 
----
+**Granularity options** (for time series methods):
 
-## Analytics
+| Value | Buckets results by |
+|---|---|
+| `'hour'` | Each hour |
+| `'day'` | Each calendar day |
+| `'week'` | Each week |
+| `'month'` | Each month |
+| `'year'` | Each year |
 
-HydrousDB Analytics runs directly against BigQuery on your GCS data — zero ETL, no duplication, live results. Fast even on billions of records.
+**Aggregation options** (for numeric field methods):
 
-```typescript
-const analytics = db.analytics('orders');
-```
+| Value | Meaning |
+|---|---|
+| `'sum'` | Total |
+| `'avg'` | Average |
+| `'min'` | Minimum |
+| `'max'` | Maximum |
+| `'count'` | Record count |
 
-All `dateRange` values are Unix timestamps in milliseconds: `{ start?: number, end?: number }`.
+---
 
 ### Count
 
-```typescript
-// Total records
+```ts
+// All-time total
 const { count } = await analytics.count();
 
-// In a date range
+// Within a time window
 const { count: lastWeek } = await analytics.count({
   dateRange: {
     start: Date.now() - 7 * 24 * 60 * 60 * 1000,
@@ -1050,283 +769,225 @@ const { count: lastWeek } = await analytics.count({
 });
 ```
 
+---
+
 ### Distribution
 
-How many records have each unique value for a field?
+How many records have each value of a field.
 
-```typescript
-const rows = await analytics.distribution({
-  field: 'status',
-  limit: 10,
-  order: 'desc', // 'asc' | 'desc'
+```ts
+const dist = await analytics.distribution({
+  field:     'status',
+  limit:     10,
+  order:     'desc', // 'asc' | 'desc'
+  dateRange: { start: new Date('2025-01-01').getTime() },
 });
-// [
-//   { value: 'completed', count: 8234 },
-//   { value: 'pending',   count: 1203 },
-//   { value: 'refunded',  count: 412  },
-// ]
+// → [{ value: 'published', count: 320 }, { value: 'draft', count: 80 }, …]
 ```
 
+---
+
 ### Sum
 
-```typescript
+Sum a numeric field, optionally grouped by another field.
+
+```ts
 // Total revenue
-const [{ sum: total }] = await analytics.sum({ field: 'amount' });
+const [{ sum: totalRevenue }] = await analytics.sum({ field: 'amount' });
 
-// Revenue by country
-const byCountry = await analytics.sum({
-  field:   'amount',
-  groupBy: 'country',
-  limit:   10,
+// Revenue by region, last quarter
+const sums = await analytics.sum({
+  field:     'amount',
+  groupBy:   'region',
+  limit:     20,
+  dateRange: {
+    start: new Date('2025-01-01').getTime(),
+    end:   new Date('2025-03-31').getTime(),
+  },
 });
-// [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, …]
+// → [{ group: 'Europe', sum: 18200 }, { group: 'Americas', sum: 29400 }, …]
 ```
 
+---
+
 ### Time Series
 
-Record counts bucketed over time — ideal for activity and growth charts.
+Count of records over time — useful for activity graphs.
 
-```typescript
-const rows = await analytics.timeSeries({
-  granularity: 'day',   // 'hour' | 'day' | 'week' | 'month' | 'year'
+```ts
+// Daily record counts, last 30 days
+const daily = await analytics.timeSeries({
+  granularity: 'day',
   dateRange: {
-    start: new Date('2025-01-01').getTime(),
-    end:   new Date('2025-06-01').getTime(),
+    start: Date.now() - 30 * 24 * 60 * 60 * 1000,
+    end:   Date.now(),
   },
 });
-// [{ date: '2025-01-01', count: 42 }, { date: '2025-01-02', count: 67 }, …]
+// → [{ date: '2025-03-01', count: 42 }, { date: '2025-03-02', count: 55 }, …]
+
+// Monthly, all time
+const monthly = await analytics.timeSeries({ granularity: 'month' });
 ```
 
+---
+
 ### Field Time Series
 
-Aggregate a numeric field over time.
+Aggregate a numeric field over time — useful for revenue, score, or usage trends.
 
-```typescript
-const revenue = await analytics.fieldTimeSeries({
+```ts
+// Daily sum of revenue, last 90 days
+const revTrend = await analytics.fieldTimeSeries({
   field:       'amount',
-  aggregation: 'sum',   // 'sum' | 'avg' | 'min' | 'max' | 'count'
-  granularity: 'week',
+  aggregation: 'sum',
+  granularity: 'day',
   dateRange: {
-    start: new Date('2025-01-01').getTime(),
+    start: Date.now() - 90 * 24 * 60 * 60 * 1000,
     end:   Date.now(),
   },
 });
-// [{ date: '2025-W01', value: 12340.50 }, { date: '2025-W02', value: 9872.00 }, …]
+// → [{ date: '2025-01-01', value: 4820.5 }, …]
+
+// Monthly average order value
+const avgTrend = await analytics.fieldTimeSeries({
+  field:       'amount',
+  aggregation: 'avg',
+  granularity: 'month',
+});
 ```
 
+---
+
 ### Top N
 
-Most common values for a field.
+Most frequent values for a field by record count.
 
-```typescript
-const topProducts = await analytics.topN({
-  field:      'productId',
-  labelField: 'productName', // optional human-readable label alongside the value
-  n:          5,
+```ts
+// Top 10 countries
+const top10 = await analytics.topN({
+  field:      'countryCode',
+  n:          10,
+  labelField: 'countryName', // optional — include a human-readable label alongside the value
   order:      'desc',
+  dateRange:  { start: new Date('2025-01-01').getTime() },
 });
-// [
-//   { value: 'prod_123', label: 'Widget Pro', count: 892 },
-//   { value: 'prod_456', label: 'Gizmo Plus', count: 743 },
-// ]
+// → [{ value: 'US', label: 'United States', count: 420 }, …]
 ```
 
-### Field Stats
-
-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,
-// }
-```
+---
 
-### Multi-Metric Dashboard
+### Stats
 
-Run several aggregations in a single BigQuery query — one network call.
+Statistical summary for a numeric field.
 
-```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: 'uniqueOrders',  aggregation: 'count' },
-  ],
-  dateRange: {
-    start: new Date('2025-01-01').getTime(),
-    end:   Date.now(),
-  },
+```ts
+const priceStats = await analytics.stats({
+  field:     'price',
+  dateRange: { start: new Date('2025-01-01').getTime() },
 });
-// {
-//   totalRevenue:  198432.50,
-//   avgOrderValue: 87.23,
-//   maxOrder:      9999.99,
-//   uniqueOrders:  2275,
-// }
+// → { min, max, avg, sum, count, stddev }
 ```
 
-### Filtered Records via BigQuery
+---
+
+### Records via BigQuery
 
-Fetch raw records using the BigQuery engine — useful for large-scale filtered exports.
+Fetch filtered records through the BigQuery engine instead of Firestore. Useful for large result sets or complex server-side filtering.
 
-```typescript
-const records = await analytics.records({
+```ts
+const records = await analytics.records<Order>({
   filters: [
-    { field: 'status', op: '==', value: 'refunded' },
-    { field: 'amount', op: '>',  value: 100         },
+    { field: 'status',  op: '==',       value: 'paid' },
+    { field: 'amount',  op: '>=',       value: 100 },
+    { field: 'country', op: 'CONTAINS', value: 'US' },
   ],
-  selectFields: ['orderId', 'amount', 'userId', 'createdAt'],
-  orderBy:      'amount',
+  selectFields: ['id', 'amount', 'country', 'createdAt'], // optional projection
+  orderBy:      'createdAt',
   order:        'desc',
-  limit:        50,
+  limit:        1000,
   offset:       0,
   dateRange: {
     start: new Date('2025-01-01').getTime(),
-    end:   Date.now(),
+    end:   new Date('2025-03-31').getTime(),
   },
 });
 ```
 
-### Cross-Bucket Comparison
+Analytics filter operators: `==` `!=` `>` `<` `>=` `<=` `CONTAINS`
 
-Compare the same metric across multiple buckets in one query.
-
-```typescript
-const comparison = await analytics.crossBucket({
-  bucketKeys:  ['orders-us', 'orders-eu', 'orders-apac'],
-  field:       'amount',
-  aggregation: 'sum',
-});
-// [
-//   { bucket: 'orders-us',   value: 120000 },
-//   { bucket: 'orders-eu',   value: 45000  },
-//   { bucket: 'orders-apac', value: 33000  },
-// ]
-```
+---
 
-> ⚠️ Your Bucket Security Key must have read access to **every** bucket listed in `bucketKeys`.
+### Multi-Metric
 
-### Storage Stats
+Compute multiple aggregations in a single round-trip — perfect for dashboards.
 
-```typescript
-const stats = await analytics.storageStats();
-// {
-//   totalRecords: 48210,
-//   totalBytes:   921600000,
-//   avgBytes:     19112,
-//   minBytes:     128,
-//   maxBytes:     5242880,
-// }
+```ts
+const dashboard = await analytics.multiMetric({
+  metrics: [
+    { field: 'amount',   name: 'totalRevenue', aggregation: 'sum' },
+    { field: 'amount',   name: 'avgOrder',     aggregation: 'avg' },
+    { field: 'amount',   name: 'maxOrder',     aggregation: 'max' },
+    { field: 'recordId', name: 'orderCount',   aggregation: 'count' },
+  ],
+  dateRange: { start: Date.now() - 30 * 24 * 60 * 60 * 1000 },
+});
+// → { totalRevenue: 48200, avgOrder: 96.4, maxOrder: 999, orderCount: 500 }
 ```
 
-### Raw Query
+---
 
-Use the `query()` method when none of the typed helpers cover your use case.
+### Storage Stats (Analytics)
 
-```typescript
-import type { AnalyticsQuery } from 'hydrousdb';
+Record count and byte statistics for the bucket.
 
-const result = await analytics.query<{ count: number }>({
-  queryType: 'count',
-  dateRange: { start: Date.now() - 86400000, end: Date.now() },
+```ts
+const storageInfo = await analytics.storageStats({
+  dateRange: { start: new Date('2025-01-01').getTime() },
 });
-
-console.log(result.queryType); // 'count'
-console.log(result.data);      // { count: 142 }
+// → { totalRecords, totalBytes, avgBytes, minBytes, maxBytes }
 ```
 
 ---
 
-## TypeScript
-
-The SDK is written entirely in TypeScript and ships full type definitions. Use generics for end-to-end type safety.
+### Cross-Bucket
 
-```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';
+Compare the same metric across multiple buckets in a single query. Your key must have read access to all listed buckets. System buckets are blocked.
 
-// 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;
-}
+```ts
+const compare = await analytics.crossBucket({
+  bucketKeys:  ['orders-2024', 'orders-2025'],
+  field:       'amount',
+  aggregation: 'sum',
+  dateRange:   { start: new Date('2025-01-01').getTime() },
+});
+// → [{ bucket: 'orders-2024', value: 38200 }, { bucket: 'orders-2025', value: 52100 }]
+```
 
-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! },
-});
+### Raw Query
 
-// Fully typed — autocomplete, compile-time safety throughout
-const orders    = db.records<Order>('orders');
-const customers = db.records<Customer>('customers');
+Escape hatch for query types not covered by the typed helpers.
 
-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'] },
-);
+```ts
+import type { AnalyticsQuery, AnalyticsResult } from 'hydrousdb';
 
-// TypeScript catches mistakes at compile time:
-// order.nonExistentField    ← TS error ✓
-// orders.create({ bad: 1 }) ← TS error ✓
+const result = await analytics.query<MyResultType>({
+  queryType:   'distribution',
+  field:       'category',
+  granularity: 'month',
+  filters:     [{ field: 'active', op: '==', value: true }],
+  dateRange:   { start: Date.now() - 30 * 24 * 60 * 60 * 1000 },
+  limit:       50,
+  order:       'desc',
+});
 ```
 
 ---
 
 ## Error Handling
 
-All SDK errors extend `HydrousError`. Specific sub-classes let you handle different failure modes precisely.
-
-```typescript
+```ts
 import {
   HydrousError,
   AuthError,
@@ -1338,215 +999,269 @@ import {
 } 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 AuthError) {
+    console.log(err.code);      // 'INVALID_CREDENTIALS'
+    console.log(err.status);    // 401
+    console.log(err.message);   // human-readable
+    console.log(err.requestId); // for support
+  }
+
+  if (err instanceof ValidationError) {
+    console.log(err.details);   // string[] of specific validation failures
+  }
+
   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');
+    console.log(err.cause);     // original error
   }
 }
 ```
 
-**Error properties:**
+| Error class | When it's thrown |
+|---|---|
+| `HydrousError` | Base class — all SDK errors extend this. Has `code`, `status`, `requestId`, `details`. |
+| `AuthError` | Login failures, invalid/expired sessions, permission denied |
+| `RecordError` | Record not found, write validation failures |
+| `StorageError` | Upload/download failures, file not found |
+| `AnalyticsError` | Invalid query, bucket not found |
+| `ValidationError` | Bad input caught client-side before the request is sent. Has `details: string[]`. |
+| `NetworkError` | No network, server unreachable, request timed out. Has `cause`. |
 
-| 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:**
+## TypeScript
 
-| 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 |
+The SDK is written in TypeScript. Type your records for full autocomplete and safety:
 
----
+```ts
+interface Order {
+  customerId: string;
+  amount:     number;
+  status:     'pending' | 'paid' | 'refunded';
+  items:      { sku: string; qty: number }[];
+}
 
-## Security Best Practices
+const orders = db.records<Order>('orders');
 
-**1. Never hard-code keys — use environment variables.**
+const order = await orders.create({
+  customerId: 'cust_123',
+  amount:     49.99,
+  status:     'pending',
+  items:      [{ sku: 'SHOE-42', qty: 1 }],
+});
+// order.status → 'pending' | 'paid' | 'refunded'  ✓
+// order.id, order.createdAt, order.updatedAt are automatically added ✓
 
-```bash
-# .env  (add .env to your .gitignore)
-HYDROUS_AUTH_KEY=hk_auth_xxxxxxxxxxxxxxxxxxxx
-HYDROUS_BUCKET_KEY=hk_bucket_xxxxxxxxxxxxxxxxxxxx
-HYDROUS_STORAGE_MAIN=ssk_xxxxxxxxxxxxxxxxxxxx
+const result = await orders.query({
+  filters: [{ field: 'status', op: '==', value: 'paid' }],
+});
+// result.records → (Order & RecordResult)[]  ✓
 ```
 
-```typescript
-const db = createClient({
+Key exported types:
+
+```ts
+import type {
+  HydrousConfig,
+  RecordData, RecordResult, QueryOptions, QueryFilter, QueryResult,
+  DateRange, Granularity, Aggregation, SortOrder,
+  AnalyticsQuery, AnalyticsResult, AnalyticsFilter,
+  UserRecord, AuthResult, Session,
+  UploadOptions, UploadResult,
+  ListOptions, ListResult, FileMetadata, SignedUrlResult,
+  StorageStats,
+} from 'hydrousdb';
+```
+
+---
+
+## Security
+
+- **Never commit API keys.** Use environment variables (`process.env.…`).
+- **Never expose keys in the browser.** For client-side apps, proxy all SDK calls through your own backend.
+- **Keys travel in headers only** — the SDK enforces this. They never appear in URLs, query strings, 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 and prevent path-traversal bugs.
+
+---
+
+## Framework Examples
+
+**Next.js (App Router)**
+```ts
+// lib/db.ts
+import { createClient } from 'hydrousdb';
+export const db = createClient({
   authKey:           process.env.HYDROUS_AUTH_KEY!,
   bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
-  storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
+  storageKeys:       { main: process.env.HYDROUS_STORAGE_KEY! },
 });
-```
 
-**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.
+// app/api/posts/route.ts
+import { db } from '@/lib/db';
+export async function GET() {
+  const { records } = await db.records('posts').query({
+    filters:  [{ field: 'status', op: '==', value: 'published' }],
+    orderBy:  'createdAt',
+    order:    'desc',
+    limit:    10,
+  });
+  return Response.json(records);
+}
+```
 
-**4. Rotate keys periodically.** Revoke old keys from the dashboard after rotation.
+**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();
+```
 
-**5. Use scoped storage** (`db.storage('key').scope('prefix/')`) to isolate access per user or feature, reducing the blast radius of any misconfiguration.
+**Vue / Nuxt**
+```ts
+// composables/useDb.ts
+import { createClient } from 'hydrousdb';
+export const db = createClient({
+  authKey:           import.meta.env.VITE_HYDROUS_AUTH_KEY,
+  bucketSecurityKey: import.meta.env.VITE_HYDROUS_BUCKET_KEY,
+  storageKeys:       { main: import.meta.env.VITE_HYDROUS_STORAGE_KEY },
+});
+```
 
-**6. Keep files private by default.** `isPublic` defaults to `false`. Use `getSignedUrl()` for time-limited external sharing rather than making files permanently public.
+**React Native**
+```ts
+import { createClient } from 'hydrousdb';
+// Works out of the box — uses the global fetch available in React Native
+const db = createClient({
+  authKey:           HYDROUS_AUTH_KEY,
+  bucketSecurityKey: HYDROUS_BUCKET_KEY,
+  storageKeys:       { main: HYDROUS_STORAGE_KEY },
+});
+```
 
 ---
 
-## Full API Reference
+## API Reference
 
-### `createClient(config)` → `HydrousClient`
+### `createClient(config)`
 
-| Config field | Type | Required | Description |
+| 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) |
+| `authKey` | `string` | ✓ | `hk_auth_…` — for auth routes |
+| `bucketSecurityKey` | `string` | ✓ | `hk_bucket_…` — for records & analytics |
+| `storageKeys` | `{ [name]: string }` | ✓ | One or more `ssk_…` keys for file storage |
+| `baseUrl` | `string` | — | Override the API endpoint (no trailing slash) |
 
 ---
 
-### `db.records<T>(bucketKey)` → `RecordsClient<T>`
+### `db.records<T>(bucket)` — all methods
 
-| Method | Signature | Description |
+| Method | Returns | 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 }
-}
-```
+| `create(data, opts?)` | `T & RecordResult` | Create a record. `opts.queryableFields` enables filtering. `opts.customRecordId` enables upsert. |
+| `get(id)` | `T & RecordResult` | Fetch a record by ID. |
+| `patch(id, data, opts?)` | `{ id, updatedAt? }` | Partial update. `opts.merge` for deep merge. `opts.trackHistory` to save a version. |
+| `delete(id)` | `void` | Permanently delete a record. |
+| `exists(id)` | `boolean` | Lightweight existence check (HEAD request). |
+| `query(opts?)` | `QueryResult<T>` | Filter, sort, paginate. Supports `dateRange`. |
+| `getAll(opts?)` | `(T & RecordResult)[]` | Fetch all records (no filter support — use `query` for filters). |
+| `batchCreate(items, opts?)` | `{ results, errors, successful, failed }` | Up to 500 records at once. |
+| `batchUpdate(updates, userEmail?)` | `{ successful, failed }` | Up to 500 records at once. |
+| `batchDelete(ids, userEmail?)` | `{ successful, failed }` | Up to 500 records at once. |
+| `getHistory(id)` | `RecordHistoryEntry[]` | List all saved versions. |
+| `getVersion(id, generation)` | `T & RecordResult` | Fetch a specific past version. |
+
+**`QueryOptions` fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `filters` | `QueryFilter[]` | Array of `{ field, op, value }` |
+| `fields` | `string` | Comma-separated list of fields to return |
+| `orderBy` | `string` | Field to sort by |
+| `order` | `'asc' \| 'desc'` | Sort direction |
+| `limit` | `number` | Max records to return |
+| `offset` | `number` | Skip N records |
+| `startAfter` | `string` | Cursor from `nextCursor` for next-page pagination |
+| `startAt` | `string` | Cursor — include the record at this cursor |
+| `endAt` | `string` | Cursor — stop at this cursor |
+| `dateRange` | `DateRange` | `{ start?, end? }` in Unix ms |
+| `timeScope` | `string` | Prefix-based time filter: `_day_YYMMDD`, `_month_YYMM`, or `_year_YY` |
 
 ---
 
-### `db.auth(bucketKey)` → `AuthClient`
+### `db.auth()` — all methods
 
-| 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. |
+| Method | Description |
+|---|---|
+| `signup(opts)` | Register + create session. Extra fields on `opts` are stored on the user. |
+| `login(opts)` | Authenticate + create session. |
+| `logout({ sessionId, allDevices? })` | Revoke one session or all sessions. |
+| `validateSession(sessionId)` | Check if a session is active; returns current user. |
+| `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 (requires current password). |
+| `requestPasswordReset(email)` | Send reset email (always succeeds to prevent enumeration). |
+| `confirmPasswordReset(token, newPw)` | Apply new password from reset token. |
+| `requestEmailVerification(userId)` | Send verification email. |
+| `confirmEmailVerification(token)` | Mark email verified from token. |
+| `getUser(userId)` | Fetch a user by ID. |
+| `listUsers(opts)` | Paginated user list. Admin only. |
+| `lockAccount(opts)` | Lock a user account. Admin only. |
+| `unlockAccount(sessionId, userId)` | Unlock a user account. Admin only. |
+| `hardDeleteUser(sessionId, userId)` | Permanent delete. Admin only. |
+| `bulkDeleteUsers(opts)` | Delete many users at once (soft or hard). Admin only. |
 
 ---
 
-### `db.storage(keyName)` → `StorageManager`
+### `db.storage(keyName)` — all methods
 
-| 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. |
+| Method | Description |
+|---|---|
+| `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 signed-URL upload — get a GCS PUT URL. |
+| `uploadToSignedUrl(url, data, mime, onProgress?)` | Step 2 — upload directly to GCS (supports progress in browsers). |
+| `confirmUpload(opts)` | Step 3 — register metadata server-side. |
+| `getBatchUploadUrls(files)` | Get signed URLs for up to 50 files at once. |
+| `batchConfirmUploads(items)` | Confirm multiple direct uploads at once. |
+| `download(path)` | Download a private file as `ArrayBuffer`. |
+| `batchDownload(paths, concurrency?)` | Download up to 20 files at once (base64 content). |
+| `list(opts?)` | List files and folders. Supports `prefix`, `limit`, `cursor`, `recursive`. |
+| `getMetadata(path)` | File size, MIME type, visibility, URLs. |
+| `getSignedUrl(path, expiresIn?)` | Time-limited share link (default 3600 s). |
+| `setVisibility(path, isPublic)` | Toggle a file between public and private. |
+| `createFolder(path)` | Create an explicit folder marker. |
+| `move(from, to)` | Move (rename) a file. |
+| `copy(from, to)` | Copy a file to a new path. |
+| `deleteFile(path)` | Permanently delete a file. |
+| `deleteFolder(path)` | Recursively delete a folder and all its contents. |
+| `getStats()` | Upload/download/delete counts and total bytes. |
+| `info()` | Server info — no auth required. |
+| `scope(prefix)` | Get a `ScopedStorage` that auto-prefixes all paths. |
+
+`ScopedStorage` exposes every method above (except `info`) plus `scope(subPrefix)` for nesting deeper.
 
 ---
 
-### `db.analytics(bucketKey)` → `AnalyticsClient`
+### `db.analytics(bucket)` — all methods
 
-| Method | Signature | Description |
+| Method | Returns | 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. |
+| `count(opts?)` | `{ count }` | Total record count, optionally within a `dateRange`. |
+| `distribution(opts)` | `DistributionRow[]` | Per-value counts for a field. |
+| `sum(opts)` | `SumRow[]` | Sum a numeric field, optional `groupBy`. |
+| `timeSeries(opts?)` | `TimeSeriesRow[]` | Record counts bucketed by `granularity`. |
+| `fieldTimeSeries(opts)` | `FieldTimeSeriesRow[]` | Numeric field aggregated over time. |
+| `topN(opts)` | `TopNRow[]` | Most frequent field values. |
+| `stats(opts)` | `FieldStats` | min / max / avg / sum / count / stddev. |
+| `records(opts?)` | `(T & RecordResult)[]` | Filtered records via BigQuery (good for large sets). |
+| `multiMetric(opts)` | `MultiMetricResult` | Multiple aggregations in one request. |
+| `storageStats(opts?)` | `StorageStatsResult` | Record count and byte stats for the bucket. |
+| `crossBucket(opts)` | `CrossBucketRow[]` | Compare a metric across multiple buckets. |
+| `query(query)` | `AnalyticsResult<T>` | Raw escape hatch for any `AnalyticsQuery`. |
 
 ---
 
@@ -1555,24 +1270,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>