hydrousdb 3.0.2 → 3.5.0

package/README.md

@@ -1,500 +1,237 @@
-# 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 (5 minutes)](#quick-start-5-minutes)
-- [Records](#records)
-  - [Create](#create-a-record)
-  - [Read](#read-a-record)
-  - [Update](#update-a-record)
-  - [Delete](#delete-a-record)
-  - [Query](#query-records)
-  - [Batch Operations](#batch-operations)
-  - [Version History](#version-history)
-- [Authentication](#authentication)
-  - [Sign Up](#sign-up-users)
-  - [Log In / Log Out](#log-in--log-out)
-  - [Session Management](#session-management)
-  - [Password Reset](#password-reset-flow)
-  - [Email Verification](#email-verification)
-  - [Admin Operations](#admin-operations)
-- [File Storage](#file-storage)
-  - [Simple Upload](#simple-upload)
-  - [Large File Upload (with progress)](#large-file-upload-with-progress)
-  - [Download](#download-files)
-  - [List Files](#list-files)
-  - [Scoped Storage](#scoped-storage)
-  - [Share & Visibility](#share--visibility)
-  - [File Operations](#file-operations)
-- [Analytics](#analytics)
-  - [Count](#count)
-  - [Distribution](#distribution)
-  - [Sum](#sum)
-  - [Time Series](#time-series)
-  - [Top N](#top-n)
-  - [Field Stats](#field-stats)
-  - [Multi-Metric Dashboard](#multi-metric-dashboard)
-  - [Filtered Records](#filtered-records-bigquery)
-  - [Cross-Bucket Comparison](#cross-bucket-comparison)
-  - [Storage Stats](#storage-stats)
-- [TypeScript Support](#typescript-support)
-- [Error Handling](#error-handling)
-- [Security Best Practices](#security-best-practices)
-- [API Reference](#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 Atlas buckles under millions of 500 KB+ documents. They were designed for structured rows and small payloads — not the kind of deeply nested, real-world JSON that modern applications actually produce.
-
-HydrousDB is built specifically for that problem. It stores every record as a compressed GCS blob, retrieves any record in a single network call (no index lookups — the storage path is computed directly from the record ID), and runs analytics at BigQuery scale without ETL. The bigger and messier your JSON, the more it outperforms traditional databases.
-
-**Systems that benefit immediately:**
-
-| Domain | Example records | Why traditional DBs struggle |
-|---|---|---|
-| 🏥 **Hospital / EMR** | Full patient charts — vitals history, medication lists, clinical notes, imaging metadata | 850 KB+ per chart, millions of patients, strict audit trails |
-| 🎓 **School management** | Student portfolios — all grades, attendance, assessments, teacher notes across years | Deep nesting, bursty writes at term-end, long-term archival |
-| 🏭 **IoT / Industrial** | Sensor telemetry — time-stamped readings, device state, calibration metadata | Billions of records, append-heavy, rarely updated |
-| 🛒 **E-commerce** | Order records — line items, fulfilment events, return history, custom attributes | Highly variable shape, needs fast analytics across date ranges |
-| ⚖️ **Legal / compliance** | Case files — filings, correspondence, version history, linked documents | 1 MB+ records, immutable audit log, cross-case analytics |
-| 🎮 **Gaming** | Player save states — inventory, quest progress, achievement history, replay data | Large payloads, millions of concurrent users, burst writes |
-| 📡 **Logistics / tracking** | Shipment records — full event timeline, customs data, carrier metadata | Append-only events, heavy querying by date range and status |
-
-**What you get out of the box:**
-
-| Feature | What it does |
-|---|---|
-| **Records** | Schemaless JSON store. Billion-scale, gzip-compressed, date-encoded IDs for zero-lookup retrieval. Up to 1 MB per record. |
-| **Auth** | Full user authentication — signup, login, sessions, password reset, email verification, and admin controls. |
-| **Storage** | File uploads backed by Google Cloud Storage. Direct-to-GCS uploads, public/private visibility, signed share URLs. |
-| **Analytics** | BigQuery-powered aggregations — counts, distributions, time series, top-N, multi-metric dashboards, cross-bucket comparisons. Zero ETL. |
-
----
-
-## How It Works
-
-Every HydrousDB record ID encodes its creation date as a prefix (e.g. `260203-rec_01JA2XYZ`). This means the full storage path to any record can be computed in memory — no index lookup, no pointer chase. Just math.
-
-```
-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 (typically 60–80% size reduction). A full 850 KB hospital patient chart compresses to ~255 KB on disk — automatically, every time. Records age through storage tiers (Standard → Nearline → Coldline → Archive) as they get older, keeping historical data accessible without manual lifecycle management.
-
-This architecture means HydrousDB handles what breaks other databases:
-- **Huge records** — up to 1 MB per document, compressed
-- **Append-heavy workloads** — IoT telemetry, audit logs, event streams
-- **Date-range queries at scale** — the ID prefix enables efficient folder scans without a full table scan
-- **Long-term retention** — billions of records stay queryable via BigQuery without any migration
-
----
-
-## Quick Start (5 minutes)
-
-### Step 1 — Create your account
-
-Go to **[https://hydrousdb.com](https://hydrousdb.com)** and sign up for a free account.
-
-### Step 2 — Create your first bucket
-
-1. Log in to your dashboard at **[https://hydrousdb.com/dashboard](https://hydrousdb.com/dashboard)**.
-2. Click **"New Bucket"**.
-3. Give it a name — use lowercase letters, numbers, hyphens, or underscores (e.g. `my-first-bucket`).
-4. Click **"Create"**.
-
-> 💡 **What is a bucket?** A bucket is a named collection of JSON records — similar to a table in SQL or a collection in MongoDB.
-
-### Step 3 — Grab your API Keys
-
-HydrousDB uses three separate keys, each scoped to a service:
-
-| 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 |
-
-1. In the dashboard go to **Settings → API Keys**.
-2. Generate each key type you need.
-3. Copy them — you'll use all three when initialising the client.
-
-> ⚠️ **These keys are your credentials.** Treat them like passwords. Never commit them to Git. Use environment variables.
-
-### Step 4 — Install the SDK
+**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
-# or
-pnpm add hydrousdb
 ```
 
-**Requirements:** Node.js 18+ (uses the native `fetch` API).
+→ [Get your free API keys at hydrousdb.com](https://hydrousdb.com/dashboard)
+
+---
 
-### Step 5 — Your first record
+## Setup
 
-```typescript
+```ts
 import { createClient } from 'hydrousdb';
 
-// Create the client once — reuse it everywhere
 const db = createClient({
-  authKey:           process.env.HYDROUS_AUTH_KEY!,           // hk_auth_…
-  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,         // hk_bucket_…
+  authKey:           process.env.HYDROUS_AUTH_KEY!,
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
   storageKeys: {
-    main: process.env.HYDROUS_STORAGE_MAIN!,                  // ssk_…
+    main: process.env.HYDROUS_STORAGE_KEY!,
   },
 });
-
-// Write a record to your bucket
-const post = await db.records('my-first-bucket').create({
-  title:     'Hello, HydrousDB!',
-  body:      'My first record.',
-  published: false,
-});
-
-console.log(post.id);        // "260601-rec_01JA2XYZ"
-console.log(post.createdAt); // 1717200000000
-
-// Read it back — zero database reads, path computed from ID
-const fetched = await db.records('my-first-bucket').get(post.id);
-console.log(fetched.title);  // "Hello, HydrousDB!"
-
-// Update it
-await db.records('my-first-bucket').patch(post.id, { published: true });
-
-// Delete it
-await db.records('my-first-bucket').delete(post.id);
 ```
 
-🎉 **That's it.** You're live.
+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.
+
+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 (e.g. `"260601-rec_01JA2XYZ"`) — encodes storage path
-- `createdAt` — Unix timestamp in milliseconds
-- `updatedAt` — Unix timestamp in milliseconds (updated on every write)
-
-Records are gzip-compressed before storage. A 850 KB EMR chart becomes ~255 KB on disk. You never manage this — it's always on.
-
-### Create a Record
-
-```typescript
-const products = db.records('products');
-
-const product = await products.create({
-  name:    'Wireless Headphones',
-  price:   79.99,
-  inStock: true,
-  tags:    ['audio', 'wireless'],
-});
-
-// product.id, product.createdAt, product.updatedAt are added automatically
-```
-
-### Read a Record
+JSON objects stored in named buckets. Every record gets `id`, `createdAt`, and `updatedAt` automatically.
 
-```typescript
-// Get by ID — the storage path is derived from the ID in memory, no index read
-const product = await products.get('rec_abc123');
+```ts
+const posts = db.records('blog-posts');
 
-// Throws HydrousError with code RECORD_NOT_FOUND if missing
-```
-
-### Update a Record
-
-```typescript
-// Patch (merge) — only the specified fields are changed
-const updated = await products.patch('rec_abc123', {
-  price:   69.99,
-  inStock: false,
-});
+// Create
+const post = await posts.create(
+  { title: 'Hello', status: 'draft', views: 0 },
+  { queryableFields: ['status'] },   // declare fields you want to filter on
+);
+console.log(post.id); // "260601-rec_01JA2XYZ"
 
-// Set (full replace) — the entire record is replaced
-const replaced = await products.set('rec_abc123', {
-  name:    'Wireless Headphones v2',
-  price:   89.99,
-  inStock: true,
-  tags:    ['audio', 'wireless', 'premium'],
-});
-```
+// 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 products.delete('rec_abc123');
+// 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
-// Get all records (up to 100 by default)
-const { records } = await products.query();
+### Query
 
-// With filters
-const { records: affordableStock } = await products.query({
+```ts
+const { records, hasMore, nextCursor } = await posts.query({
   filters: [
-    { field: 'inStock', op: '==', value: true },
-    { field: 'price',   op: '<',  value: 100  },
+    { field: 'status', op: '==', value: 'published' },
+    { field: 'views',  op: '>',  value: 100 },
   ],
-});
-
-// Sort and paginate
-const { records, hasMore, nextCursor } = await products.query({
-  orderBy: 'price',
-  order:   'asc',
+  orderBy: 'createdAt',
+  order:   'desc',
   limit:   20,
 });
 
 // Next page
 if (hasMore) {
-  const page2 = await products.query({
-    orderBy:    'price',
-    order:      'asc',
-    limit:      20,
-    startAfter: nextCursor,
-  });
+  const page2 = await posts.query({ limit: 20, startAfter: nextCursor });
 }
+```
 
-// Select specific fields only
-const { records: lightRecords } = await products.query({
-  fields: 'name,price,inStock',
-});
+Filter operators: `==` `!=` `>` `<` `>=` `<=` `CONTAINS`
 
-// Filter by date range
-const { records: recent } = await products.query({
-  dateRange: {
-    start: Date.now() - 7 * 24 * 60 * 60 * 1000, // 7 days ago
-    end:   Date.now(),
-  },
-});
+### Atomic field updates
+
+Avoid race conditions with server-side operations inside `patch()`:
+
+```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);
 ```
 
-**Available filter operators:**
+### Batch operations
 
-| Operator | Meaning |
-|---|---|
-| `==` | Equal |
-| `!=` | Not equal |
-| `>` | Greater than |
-| `<` | Less than |
-| `>=` | Greater than or equal |
-| `<=` | Less than or equal |
-| `CONTAINS` | String contains (case-sensitive) |
-
-### Batch Operations
-
-```typescript
-// Create multiple records at once
-const created = await products.batchCreate([
-  { name: 'Item A', price: 10.00, inStock: true  },
-  { name: 'Item B', price: 20.00, inStock: false },
-  { name: 'Item C', price: 30.00, inStock: true  },
+```ts
+// Create up to 500 records at once
+const { results, errors } = await posts.batchCreate(
+  [{ title: 'A' }, { title: 'B' }],
+  { queryableFields: ['title'] },
+);
+
+// Update up to 500 records at once
+await posts.batchUpdate([
+  { recordId: 'id1', values: { status: 'archived' } },
+  { recordId: 'id2', values: { status: 'archived' } },
 ]);
-// → [{ id: '260601-rec_1', ... }, { id: '260601-rec_2', ... }, ...]
 
-// Count records
-const total   = await products.count();
-const inStock = await products.count([{ field: 'inStock', op: '==', value: true }]);
+// Delete up to 500 records at once
+const { successful, failed } = await posts.batchDelete(['id1', 'id2']);
+```
 
-// Get all records without filters (shortcut for query)
-const all = await products.getAll({ orderBy: 'price', order: 'asc' });
+### Version history
 
-// Delete multiple records
-const { deleted, failed } = await products.batchDelete(['rec_1', 'rec_2', 'rec_3']);
-```
+Every write is automatically versioned.
 
-### Version History
+```ts
+const history = await posts.getHistory(post.id);
+// [{ generation, savedAt, savedBy, sizeBytes }, …]
 
-Every write to a record creates a new version, so you can travel back in time.
+// Read a specific past version
+const v1 = await posts.getVersion(post.id, history[0].generation!);
+```
 
-```typescript
-// Get the full version history of a record
-const history = await products.getHistory('rec_abc123');
-// history[0] is the latest version, history[1] is one write before, etc.
+### Custom record IDs
 
-// Restore to a specific version
-const restored = await products.restoreVersion('rec_abc123', history[2]!.version);
+```ts
+// If the ID already exists, the record is upserted
+const post = await posts.create(
+  { title: 'Welcome' },
+  { customRecordId: '260601-post_welcome' },
+);
 ```
 
 ---
 
-## Authentication
+## Auth
 
-HydrousDB has a built-in user auth system. Your users live in a bucket you create (e.g. `"app-users"`). You get sessions, refresh tokens, password reset, email verification, and admin controls out of the box.
+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 Users
+### 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',         // min 8 characters, 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
 });
 
-// user.id              → "usr_xxxxxxxxxx"
-// session.sessionId    → persist this in your app
-// session.refreshToken → persist this for long-lived sessions
-```
-
-### 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 });
 ```
 
-### 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**. Use the refresh token to get a new session — refresh tokens last **30 days**.
+### Session management
 
-```typescript
-// Refresh the session before it expires
-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 the current user
-const user = await auth.getUser({ userId: session.userId });
+// Get a new session using the refresh token
+const newSession = await auth.refreshSession(session.refreshToken);
 ```
 
-### Update User Profile
+### User profile
+
+```ts
+const user = await auth.getUser(session.userId);
 
-```typescript
-const updated = await auth.updateUser({
+await auth.updateUser({
   sessionId: session.sessionId,
   userId:    user.id,
-  data: {
-    fullName: 'Alice Smith',
-    plan:     'enterprise',
-    avatar:   'https://example.com/avatar.jpg',
-  },
+  updates:   { fullName: 'Alice Johnson', plan: 'enterprise' },
 });
-```
 
-### 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 an email with a reset token
-
-// 3. User submits the new password
-await auth.confirmPasswordReset({
-  resetToken:  'tok_from_email',
-  newPassword: 'correcthorsebatterystaple',
-});
-// All existing sessions for this user are automatically revoked
+await auth.deleteUser(session.sessionId, user.id);
 ```
 
-### Change Password (authenticated)
+### Password & email
 
-```typescript
+```ts
+// Change password (requires active session)
 await auth.changePassword({
   sessionId:       session.sessionId,
   userId:          user.id,
   currentPassword: 'hunter2',
   newPassword:     'correcthorsebatterystaple',
 });
-```
-
-### Email Verification
 
-```typescript
-// 1. Send verification email
-await auth.requestEmailVerification({ userId: user.id });
+// Forgot password flow
+await auth.requestPasswordReset('alice@example.com');
+await auth.confirmPasswordReset(tokenFromEmail, 'newpassword123');
 
-// 2. User clicks link in email, your app extracts the token
-
-// 3. Confirm the token
-await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
+// Email verification
+await auth.requestEmailVerification(user.id);
+await auth.confirmEmailVerification(tokenFromEmail);
 ```
 
-### Admin Operations
-
-Admin operations require a valid session from a user with `role: 'admin'`.
+### Admin
 
-```typescript
-// List all users
-const { users, total } = await auth.listUsers({
+```ts
+// List all users (paginated)
+const { users, hasMore, nextCursor } = await auth.listUsers({
   sessionId: adminSession.sessionId,
   limit:     50,
-  offset:    0,
-});
-
-// Lock an account (prevents login)
-await auth.lockAccount({
-  sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
-  duration:  60 * 60 * 1000, // lock for 1 hour (default: 15 minutes)
-});
-
-// Unlock an account
-await auth.unlockAccount({
-  sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
 });
 
-// Soft-delete a user (marks as deleted, keeps data)
-await auth.deleteUser({
-  sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
-});
+// Lock / unlock an account
+await auth.lockAccount({ sessionId: adminSession.sessionId, userId: user.id });
+await auth.unlockAccount(adminSession.sessionId, user.id);
 
-// Hard-delete a user (permanent — irreversible)
-await auth.hardDeleteUser({
+// Delete users
+await auth.hardDeleteUser(adminSession.sessionId, user.id);
+await auth.bulkDeleteUsers({
   sessionId: adminSession.sessionId,
-  userId:    'usr_abc123',
-});
-
-// Bulk delete multiple users
-const { deleted, failed } = await auth.bulkDeleteUsers({
-  sessionId: adminSession.sessionId,
-  userIds:   ['usr_a', 'usr_b', 'usr_c'],
+  userIds:   ['id1', 'id2'],
+  hard:      true,
 });
 ```
 
@@ -502,548 +239,238 @@ const { deleted, failed } = await auth.bulkDeleteUsers({
 
 ## File Storage
 
-HydrousDB Storage is backed by Google Cloud Storage. Storage keys (`ssk_…`) are scoped per bucket, so you can give different parts of your app different levels of access.
-
-```typescript
-// Pick a storage key by the name you gave it in storageKeys
-const files     = db.storage('main');
-const avatars   = db.storage('avatars');
-const documents = db.storage('documents');
+```ts
+const storage = db.storage('main');
 ```
 
-### Simple Upload
+### Upload
 
-For files up to **500 MB** when you don't need upload progress:
+```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)
 
-```typescript
-// Browser: upload from a file input
-const file = document.querySelector('input[type="file"]').files[0];
-
-const result = await db.storage('main').upload(file, `uploads/${file.name}`, {
-  isPublic:  true,   // publicly accessible without auth
-  overwrite: false,  // throw if the file already exists
-});
-
-console.log(result.publicUrl);   // CDN URL — usable anywhere
-console.log(result.downloadUrl); // null (it's public)
-console.log(result.size);        // bytes
-console.log(result.mimeType);    // auto-detected from extension
-
-// Node.js: upload from a Buffer
-import { readFileSync } from 'fs';
-const buffer = readFileSync('./report.pdf');
-const result = await db.storage('documents').upload(buffer, 'reports/q3.pdf');
-console.log(result.downloadUrl); // requires X-Storage-Key to access
+// Upload a JSON object or string directly
+await storage.uploadRaw({ theme: 'dark' }, 'config.json');
 ```
 
-### Upload Raw JSON or Text
-
-```typescript
-const result = await db.storage('main').uploadRaw(
-  { theme: 'dark', language: 'en' },
-  'user-config/alice.json',
-  { isPublic: false },
-);
-```
-
-### Large File Upload (with progress)
-
-For files over 10 MB or when you need a progress bar. The file goes directly to GCS — your server never buffers it.
+**Large files with progress tracking** (recommended for anything > 10 MB):
 
-```typescript
-const storage = db.storage('main');
-
-// Step 1: Get a signed upload URL
+```ts
+// Step 1 — get a signed upload URL
 const { uploadUrl, path } = await storage.getUploadUrl({
-  path:     'videos/product-demo.mp4',
+  path:     'videos/intro.mp4',
   mimeType: 'video/mp4',
   size:     file.size,
   isPublic: true,
 });
 
-// Step 2: Upload directly to GCS with progress tracking
-await storage.uploadToSignedUrl(
-  uploadUrl,
-  file,
-  'video/mp4',
-  (percent) => {
-    progressBar.style.width = `${percent}%`;
-    console.log(`${percent}% uploaded`);
-  },
-);
-
-// Step 3: Confirm the upload (registers metadata server-side)
-const result = await storage.confirmUpload({
-  path:     path,
-  mimeType: 'video/mp4',
-  isPublic: true,
+// Step 2 — upload directly to GCS (supports onProgress in browsers)
+await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => {
+  console.log(`${pct}% uploaded`);
 });
 
-console.log(result.publicUrl); // ready to use
+// Step 3 — confirm and get the final result
+const result = await storage.confirmUpload({ path, mimeType: 'video/mp4', isPublic: true });
 ```
 
-### Batch Upload
+### Download, list, manage
 
-```typescript
-const storage = db.storage('main');
+```ts
+// Download a private file
+const buffer = await storage.download('private/doc.pdf');
 
-// Get signed URLs for up to 50 files at once
-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 },
-]);
+// List files
+const { files, folders, hasMore, nextCursor } = await storage.list({ prefix: 'avatars/' });
 
-// Upload each one directly to GCS
-for (const f of files) {
-  await storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
-}
-
-// Confirm all at once
-const results = await storage.batchConfirmUploads(
-  files.map(f => ({ path: f.path, mimeType: f.mimeType, isPublic: true })),
-);
-```
+// Get file metadata
+const meta = await storage.getMetadata('avatars/alice.jpg');
 
-### Download Files
-
-```typescript
-// Private files require authentication — returns ArrayBuffer
-const buffer = await db.storage('documents').download('reports/q3.pdf');
-const blob   = new Blob([buffer], { type: 'application/pdf' });
-
-// Trigger a browser download
-const url  = URL.createObjectURL(blob);
-const a    = document.createElement('a');
-a.href     = url;
-a.download = 'q3.pdf';
-a.click();
-
-// Public files: use publicUrl directly — no SDK needed
-// <img src={result.publicUrl} />
-```
+// Time-limited share link (no login needed to access)
+const { signedUrl } = await storage.getSignedUrl('private/report.pdf', 3600);
 
-### List Files
-
-```typescript
-const storage = db.storage('main');
-
-// List everything at the root
-const { files, folders } = await storage.list();
-
-// List a specific folder
-const { files, folders, hasMore, nextCursor } = await storage.list({
-  prefix:    'gallery/',
-  limit:     50,
-  recursive: false,
-});
-
-// Paginate
-if (hasMore) {
-  const page2 = await storage.list({ prefix: 'gallery/', cursor: nextCursor });
-}
-```
-
-Each file entry includes:
-```typescript
-{
-  name:        'photo1.jpg',
-  path:        'gallery/photo1.jpg',
-  size:        204800,
-  mimeType:    'image/jpeg',
-  isPublic:    true,
-  publicUrl:   'https://storage.googleapis.com/...',
-  downloadUrl: null,
-  updatedAt:   '2025-06-01T12:00:00.000Z',
-}
-```
-
-### Scoped Storage
-
-Working within a specific folder? Use `.scope()` to avoid repeating the prefix on every call.
-
-```typescript
-// All operations in the "user-avatars/" folder
-const avatars = db.storage('avatars').scope('user-avatars');
-
-await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
-// → uploads to "user-avatars/{userId}.jpg"
-
-const { files } = await avatars.list();
-// → lists files under "user-avatars/"
-
-await avatars.deleteFile(`${userId}.jpg`);
-// → deletes "user-avatars/{userId}.jpg"
+// 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/');
 
-// Nest scopes
-const thumbnails = avatars.scope('thumbnails');
-// → all operations under "user-avatars/thumbnails/"
+// Change visibility after upload
+await storage.setVisibility('alice.jpg', false);  // make private
 ```
 
-### Share & Visibility
+### Scoped storage
 
-```typescript
-const storage = db.storage('documents');
+Automatically prefix every path — useful for per-user file isolation:
 
-// Get file metadata (size, MIME type, URLs, visibility)
-const meta = await storage.getMetadata('reports/q3.pdf');
+```ts
+const userFiles = db.storage('main').scope(`users/${userId}/`);
 
-// Generate a time-limited share link for a private file
-// (no auth key needed to use the link)
-const { signedUrl, expiresAt } = await storage.getSignedUrl(
-  'reports/q3.pdf',
-  3600, // expires in 1 hour (default)
-);
+await userFiles.upload(pdf, 'contract.pdf');      // → users/{userId}/contract.pdf
+const { files } = await userFiles.list();         // → only lists users/{userId}/
 
-// Toggle visibility after upload
-await storage.setVisibility('reports/q3.pdf', true);  // make public
-await storage.setVisibility('reports/q3.pdf', false); // make private
-```
-
-### File Operations
-
-```typescript
-const storage = db.storage('main');
-
-// Rename / move a file
-await storage.move('drafts/report.pdf', 'published/report-2025.pdf');
-
-// Copy a file
-await storage.copy('templates/invoice.html', 'invoices/inv-001.html');
-
-// Create a folder
-await storage.createFolder('archive/2025/');
-
-// Delete a file
-await storage.deleteFile('temp/scratch.txt');
-
-// Delete a folder and all its contents
-await storage.deleteFolder('temp/');
-
-// Get key-level stats
-const stats = await storage.getStats();
-// → { totalFiles: 842, totalBytes: 1073741824, uploadCount: 1200, ... }
+// Nest deeper
+const reports = userFiles.scope('reports/');      // → users/{userId}/reports/
 ```
 
 ---
 
 ## Analytics
 
-HydrousDB Analytics runs queries directly against BigQuery on your GCS data — zero ETL, no data duplication, live results. Fast even on billions of records.
+BigQuery-powered aggregations. No ETL, no pipelines — just query.
 
-```typescript
+```ts
 const analytics = db.analytics('orders');
-```
 
-### Count
-
-```typescript
-// Total records
+// Total record count
 const { count } = await analytics.count();
 
-// Records 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' });
-// → [
-//   { value: 'completed', count: 8234 },
-//   { value: 'pending',   count: 1203 },
-//   { value: 'refunded',  count: 412  },
-// ]
-```
-
-### Sum
-
-```typescript
-// Total revenue
-const rows = await analytics.sum({ field: 'amount' });
-// → [{ sum: 198432.50 }]
-
-// Revenue grouped by country
-const byCountry = await analytics.sum({
-  field:   'amount',
-  groupBy: 'country',
-  limit:   10,
-});
-// → [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, ...]
-```
+// How many records have each value of `status`
+const dist = await analytics.distribution({ field: 'status' });
 
-### Time Series
+// Sum of `amount`, grouped by `region`
+const sums = await analytics.sum({ field: 'amount', groupBy: 'region' });
 
-Record counts over time — ideal for activity and growth charts.
+// Records over time
+const daily = await analytics.timeSeries({ granularity: 'day' });
 
-```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 }, ...]
-```
+// How `revenue` changes over time
+const trend = await analytics.fieldTimeSeries({ field: 'revenue', aggregation: 'sum' });
 
-Aggregate a numeric field over time:
-
-```typescript
-const revenue = await analytics.fieldTimeSeries({
-  field:       'amount',
-  aggregation: 'sum',  // 'sum' | 'avg' | 'min' | 'max' | 'count'
-  granularity: 'week',
-});
-// → [{ date: '2025-W01', value: 12340.50 }, ...]
-```
+// Top 10 countries by record count
+const top10 = await analytics.topN({ field: 'country', n: 10 });
 
-### Top N
+// Min / max / avg / sum / stddev for a numeric field
+const stats = await analytics.stats({ field: 'price' });
 
-Most common values for a field:
-
-```typescript
-const topProducts = await analytics.topN({
-  field:      'productId',
-  labelField: 'productName', // optional: include a human-readable label
-  n:          5,
-  order:      'desc',
-});
-// → [
-//   { value: 'prod_123', label: 'Widget Pro', count: 892 },
-//   { value: 'prod_456', label: 'Gizmo Plus', count: 743 },
-// ]
-```
-
-### 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
-
-Calculate several aggregations in a single BigQuery query:
-
-```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: 'totalOrders',   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,
-//   totalOrders:   2275,
-// }
-```
-
-### Filtered Records (BigQuery)
-
-Query raw records at full BigQuery speed:
+// → { totalRevenue: 48200, avgOrder: 96.4, orderCount: 500 }
 
-```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,
-});
-```
-
-### 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  },
-// ]
+
+// All queries accept an optional date range
+const { count } = await analytics.count({
+  dateRange: { start: Date.now() - 7 * 24 * 60 * 60 * 1000, end: Date.now() },
+});
 ```
 
-> ⚠️ Your Bucket Security Key must have read access to **all** listed buckets.
+---
+
+## Error Handling
 
-### Storage Stats
+```ts
+import { HydrousError, NetworkError } from 'hydrousdb';
 
-```typescript
-const stats = await analytics.storageStats();
-// → { totalRecords: 48210, totalBytes: 921600000, avgBytes: 19112, minBytes: 128, maxBytes: 5242880 }
+try {
+  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) {
+    console.log('No internet or server unreachable');
+  }
+}
 ```
 
----
+| 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 |
 
-## TypeScript Support
+---
 
-The SDK is written in TypeScript and ships with full type definitions. Use generic type parameters to get full autocomplete and compile-time safety throughout your app.
+## TypeScript
 
-```typescript
-import { createClient } from 'hydrousdb';
+The SDK is written in TypeScript. Type your records for full autocomplete:
 
-// Define your data models as plain interfaces — no index signature needed
+```ts
 interface Order {
   customerId: string;
-  items:      Array<{ productId: string; qty: number; price: number }>;
-  total:      number;
-  status:     'pending' | 'processing' | 'completed' | 'refunded';
-  country:    string;
+  amount:     number;
+  status:     'pending' | 'paid' | 'refunded';
+  items:      { sku: string; qty: number }[];
 }
 
-interface Customer {
-  name:    string;
-  email:   string;
-  tier:    'free' | 'pro' | 'enterprise';
-  credits: number;
-}
+const orders = db.records<Order>('orders');
 
-const db = createClient({
-  authKey:           process.env.HYDROUS_AUTH_KEY!,
-  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
-  storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
-});
-
-// Fully typed clients
-const orders    = db.records<Order>('orders');
-const customers = db.records<Customer>('customers');
-
-// order.total, order.status, etc. are all type-safe
 const order = await orders.create({
-  customerId: 'cust_abc',
-  items:      [{ productId: 'prod_1', qty: 2, price: 29.99 }],
-  total:      59.98,
+  customerId: 'cust_123',
+  amount:     49.99,
   status:     'pending',
-  country:    'US',
+  items:      [{ sku: 'SHOE-42', qty: 1 }],
 });
-
-// TypeScript catches mistakes at compile time:
-// order.nonExistentField   // ← TS error ✓
-// order.status = 'invalid' // ← TS error ✓
-```
-
-All exported types are available for import:
-
-```typescript
-import type {
-  HydrousConfig,
-  RecordResult,
-  QueryFilter,
-  QueryOptions,
-  UploadResult,
-  AnalyticsQuery,
-  DateRange,
-  // ... and many more
-} from 'hydrousdb';
+// order.status → 'pending' | 'paid' | 'refunded'  ✓
 ```
 
 ---
 
-## Error Handling
-
-All errors thrown by the SDK extend `HydrousError`, which carries:
-
-| Property | Type | Description |
-|---|---|---|
-| `message` | `string` | Human-readable description |
-| `code` | `string` | Machine-readable error code (e.g. `"RECORD_NOT_FOUND"`) |
-| `status` | `number` | HTTP status code |
-| `requestId` | `string` | Server request ID (for support tracing) |
-| `details` | `string[]` | Validation error details |
+## Security
 
-```typescript
-import { HydrousError, NetworkError, AuthError } from 'hydrousdb';
-
-try {
-  const { user } = await auth.login({ email: 'a@b.com', password: 'wrong' });
-} catch (err) {
-  if (err instanceof AuthError) {
-    // Authentication-specific error
-    console.error(`Auth failed: ${err.code}`);
-    // err.code might be: INVALID_CREDENTIALS, ACCOUNT_LOCKED, EMAIL_NOT_VERIFIED
-  } else if (err instanceof NetworkError) {
-    // No internet / server unreachable
-    console.error('Cannot reach HydrousDB — check your internet connection');
-  } else if (err instanceof HydrousError) {
-    // Any other API error
-    console.error(`API error [${err.code}]: ${err.message}`);
-    console.error(`Request ID: ${err.requestId}`); // include in support tickets
-  }
-}
-```
-
-**Common error codes:**
-
-| Code | Meaning |
-|---|---|
-| `RECORD_NOT_FOUND` | The requested record ID does not exist |
-| `INVALID_CREDENTIALS` | Wrong email or password |
-| `ACCOUNT_LOCKED` | The account is temporarily locked |
-| `INVALID_SESSION` | Session expired or revoked — re-authenticate |
-| `MISSING_API_KEY` | Key not provided |
-| `INVALID_SECURITY_KEY` | Key is wrong or revoked |
-| `FORBIDDEN` | Insufficient permissions |
-| `FILE_EXISTS` | File already exists at path (use `overwrite: true`) |
-| `LIMIT_EXCEEDED` | Storage quota or file size limit reached |
-| `SYSTEM_BUCKET_FORBIDDEN` | Cannot query system buckets via analytics |
-| `VALIDATION_ERROR` | Invalid input — check `err.details` |
-| `NETWORK_ERROR` | Failed to reach the API |
+- **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.
 
 ---
 
-## Security Best Practices
-
-1. **Never hard-code your keys.** Use environment variables:
-
-   ```bash
-   # .env (add to .gitignore)
-   HYDROUS_AUTH_KEY=hk_auth_xxxxxxxxxxxxxxxxxxxx
-   HYDROUS_BUCKET_KEY=hk_bucket_xxxxxxxxxxxxxxxxxxxx
-   HYDROUS_STORAGE_MAIN=ssk_xxxxxxxxxxxxxxxxxxxx
-   ```
-
-   ```typescript
-   const db = createClient({
-     authKey:           process.env.HYDROUS_AUTH_KEY!,
-     bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
-     storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
-   });
-   ```
+## Framework examples
 
-2. **Never expose keys to browsers.** For browser-side apps, route requests through your own backend, or use per-user session tokens from `auth.login()`.
+**Next.js (App Router)**
+```ts
+// lib/db.ts
+import { createClient } from 'hydrousdb';
+export const db = createClient({ … });
 
-3. **Keys are sent via request headers — never in URLs.** The SDK enforces this automatically, so keys never appear in server logs or browser history.
+// 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);
+}
+```
 
-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('keyName').scope('prefix/')`) to isolate access by user or feature, reducing the blast radius of any misconfiguration.
+**Vue / Nuxt**
+```ts
+// composables/useDb.ts
+import { createClient } from 'hydrousdb';
+export const db = createClient({ … });
+```
 
-6. **Use `isPublic: false` (the default) for sensitive files.** Use signed URLs for time-limited sharing instead of 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({ … });
+```
 
 ---
 
@@ -1051,150 +478,98 @@ try {
 
 ### `createClient(config)`
 
-Creates and returns a `HydrousClient` instance. Call this once and reuse it everywhere.
-
-```typescript
-const db = createClient({
-  authKey:           'hk_auth_…',    // Required — auth routes
-  bucketSecurityKey: 'hk_bucket_…',  // Required — records & analytics
-  storageKeys: {                     // Required — at least one entry
-    main:      'ssk_main_…',
-    avatars:   'ssk_avatars_…',
-    documents: 'ssk_docs_…',
-  },
-  baseUrl: 'https://...',            // Optional — defaults to official endpoint
-});
-```
-
-### `db.records<T>(bucketKey)`
+| 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) |
 
-Returns a `RecordsClient<T>` for the named bucket. Uses `bucketSecurityKey` automatically.
+### `db.records(bucket)` — key methods
 
-| Method | Description |
+| Method | What it does |
 |---|---|
-| `create(data)` | Create a new record |
-| `get(id)` | Get a record by ID |
-| `set(id, data)` | Full replace |
-| `patch(id, data, opts?)` | Partial update (merge by default) |
-| `delete(id)` | Delete a record |
-| `query(opts?)` | Query with filters, sort, pagination |
-| `getAll(opts?)` | Shortcut for query without filters |
-| `count(filters?)` | Count matching records |
-| `batchCreate(items)` | Create multiple records |
-| `batchDelete(ids)` | Delete multiple records |
-| `getHistory(id)` | Get version history |
-| `restoreVersion(id, version)` | Restore to a previous version |
-
-### `db.auth(bucketKey)`
-
-Returns an `AuthClient` for the named user bucket. Uses `authKey` automatically.
-
-| Method | Description |
+| `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 a new user |
-| `login(opts)` | Authenticate and create a session |
-| `logout({ sessionId })` | Invalidate a session |
-| `refreshSession({ refreshToken })` | Extend a session |
-| `getUser({ userId })` | Get user by ID |
-| `updateUser(opts)` | Update user fields |
-| `changePassword(opts)` | Change password (authenticated) |
-| `requestPasswordReset(opts)` | Send reset email |
-| `confirmPasswordReset(opts)` | Apply new password from reset token |
-| `requestEmailVerification(opts)` | Send verification email |
-| `confirmEmailVerification(opts)` | Verify email with token |
-| `listUsers(opts)` | List all users (admin) |
-| `lockAccount(opts)` | Lock a user account (admin) |
-| `unlockAccount(opts)` | Unlock a user account (admin) |
-| `deleteUser(opts)` | Soft-delete a user (admin) |
-| `hardDeleteUser(opts)` | Permanently delete a user (admin) |
-| `bulkDeleteUsers(opts)` | Bulk delete users (admin) |
-
-### `db.analytics(bucketKey)`
-
-Returns an `AnalyticsClient` for the named bucket. Uses `bucketSecurityKey` automatically.
-
-| Method | Description |
+| `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 |
 |---|---|
-| `count(opts?)` | Count records |
-| `distribution(opts)` | Value distribution for a field |
-| `sum(opts)` | Sum with optional groupBy |
-| `timeSeries(opts?)` | Record counts over time |
-| `fieldTimeSeries(opts)` | Field aggregation over time |
-| `topN(opts)` | Top N values for a field |
-| `stats(opts)` | Statistical summary for a numeric field |
-| `records(opts?)` | Filtered raw records via BigQuery |
-| `multiMetric(opts)` | Multiple aggregations in one query |
-| `storageStats(opts?)` | Bucket storage statistics |
-| `crossBucket(opts)` | Compare a metric across multiple buckets |
-| `query(query)` | Raw analytics query |
-
-### `db.storage(keyName)`
-
-Returns a `StorageManager` for the named storage key. The name must match a key you defined in `storageKeys` when calling `createClient`. Uses the corresponding `ssk_…` key via `X-Storage-Key`.
-
-```typescript
-const storage = db.storage('avatars');
-const scoped  = db.storage('avatars').scope('user-uploads/');
-```
-
-| 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 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 |
 |---|---|
-| `upload(data, path, opts?)` | Simple server-buffered upload (up to 500 MB) |
-| `uploadRaw(data, path, opts?)` | Upload JSON or text data |
-| `getUploadUrl(opts)` | Step 1: Get a signed GCS upload URL |
-| `uploadToSignedUrl(url, data, mime, onProgress?)` | Step 2: Upload directly to GCS |
-| `confirmUpload(opts)` | Step 3: Register upload metadata |
-| `getBatchUploadUrls(files)` | Get signed URLs for up to 50 files at once |
-| `batchConfirmUploads(items)` | Confirm multiple uploads at once |
-| `download(path)` | Download a private file as ArrayBuffer |
-| `batchDownload(paths)` | Download multiple files |
-| `list(opts?)` | List files and folders |
-| `getMetadata(path)` | Get file metadata |
-| `getSignedUrl(path, expiresIn?)` | Generate a time-limited share URL |
-| `setVisibility(path, isPublic)` | Toggle public / private |
-| `createFolder(path)` | Create a folder |
-| `deleteFile(path)` | Delete a file |
-| `deleteFolder(path)` | Delete a folder and all its contents |
-| `move(from, to)` | Move or rename a file |
-| `copy(from, to)` | Copy a file |
-| `getStats()` | Key-level storage statistics |
-| `info()` | Ping the storage service (no auth required) |
-| `scope(prefix)` | Get a `ScopedStorage` instance pre-fixed to a folder |
+| `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. |
 
 ---
 
 ## Contributing
 
-We love contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
 ```bash
-# Clone the repo
 git clone https://github.com/hydrousdb/hydrousdb-js.git
 cd hydrousdb-js
-
-# Install dependencies
 npm install
-
-# Run tests
-npm test
-
-# Build
-npm run build
-
-# Run tests in watch mode
-npm run test:watch
+npm 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>
-</p>
+  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>