hydrousdb 3.0.0 → 3.0.2

package/README.md

@@ -1,7 +1,8 @@
 # HydrousDB JavaScript / TypeScript SDK
 
 <p align="center">
-  <strong>The official SDK for <a href="https://hydrousdb.com">HydrousDB</a> — records, auth, file storage, and analytics in one package.</strong>
+  <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">
@@ -16,12 +17,8 @@
 ## Table of Contents
 
 - [What is HydrousDB?](#what-is-hydrousdb)
+- [How It Works](#how-it-works)
 - [Quick Start (5 minutes)](#quick-start-5-minutes)
-  - [Step 1 — Create your account](#step-1--create-your-account)
-  - [Step 2 — Create your first bucket](#step-2--create-your-first-bucket)
-  - [Step 3 — Grab your Security Key](#step-3--grab-your-security-key)
-  - [Step 4 — Install the SDK](#step-4--install-the-sdk)
-  - [Step 5 — Your first record](#step-5--your-first-record)
 - [Records](#records)
   - [Create](#create-a-record)
   - [Read](#read-a-record)
@@ -48,11 +45,14 @@
 - [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)
@@ -64,19 +64,54 @@
 
 ## What is HydrousDB?
 
-HydrousDB is a **backend-as-a-service** platform that gives your app a fully managed backend in minutes. Instead of spinning up servers, databases, and storage buckets yourself, you call an API.
+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 document store. Create, read, update, delete and query records in named *buckets*. |
+| **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 and downloads backed by Google Cloud Storage. Public and private files, signed share URLs. |
-| **Analytics** | BigQuery-powered aggregations — counts, distributions, time series, top-N, multi-metric dashboards, and cross-bucket comparisons. |
+| **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. |
 
-Everything is organised around two concepts:
+---
+
+## 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.
 
-- **Security Key (`sk_...`)** — your master credential. Authenticate all API calls. Keep it secret.
-- **Bucket Key** — just the name of your bucket (e.g. `"blog-posts"`, `"app-users"`). Not a secret.
+```
+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
 
 ---
 
@@ -95,13 +130,21 @@ Go to **[https://hydrousdb.com](https://hydrousdb.com)** and sign up for a free
 
 > 💡 **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 Security Key
+### 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. Click **"Generate Security Key"**.
-3. Copy the key — it looks like `sk_live_xxxxxxxxxxxxxxxxxxxx`.
+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.
 
-> ⚠️ **Your Security Key is your most important credential.** Treat it like a password. Never commit it to Git. Use environment variables.
+> ⚠️ **These keys are your credentials.** Treat them like passwords. Never commit them to Git. Use environment variables.
 
 ### Step 4 — Install the SDK
 
@@ -122,7 +165,11 @@ import { createClient } from 'hydrousdb';
 
 // Create the client once — reuse it everywhere
 const db = createClient({
-  securityKey: process.env.HYDROUS_SECURITY_KEY!, // from Step 3
+  authKey:           process.env.HYDROUS_AUTH_KEY!,           // hk_auth_…
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,         // hk_bucket_…
+  storageKeys: {
+    main: process.env.HYDROUS_STORAGE_MAIN!,                  // ssk_…
+  },
 });
 
 // Write a record to your bucket
@@ -132,41 +179,43 @@ const post = await db.records('my-first-bucket').create({
   published: false,
 });
 
-console.log(post.id);        // "rec_a1b2c3d4"
+console.log(post.id);        // "260601-rec_01JA2XYZ"
 console.log(post.createdAt); // 1717200000000
 
-// Read it back
+// 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
-const updated = await db.records('my-first-bucket').patch(post.id, { published: true });
+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 with zero configuration beyond your Security Key.
+🎉 **That's it.** You're live.
 
 ---
 
 ## Records
 
 Records are JSON objects stored in named buckets. Every record automatically gets:
-- `id` — unique record identifier (e.g. `"rec_a1b2c3d4"`)
+- `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'],
+  name:    'Wireless Headphones',
+  price:   79.99,
+  inStock: true,
+  tags:    ['audio', 'wireless'],
 });
 
 // product.id, product.createdAt, product.updatedAt are added automatically
@@ -175,16 +224,16 @@ const product = await products.create({
 ### Read a Record
 
 ```typescript
-// Get by ID
+// Get by ID — the storage path is derived from the ID in memory, no index read
 const product = await products.get('rec_abc123');
 
-// product is null-safe: throws HydrousError with code RECORD_NOT_FOUND if missing
+// Throws HydrousError with code RECORD_NOT_FOUND if missing
 ```
 
 ### Update a Record
 
 ```typescript
-// Patch (merge) — only the listed fields are changed
+// Patch (merge) — only the specified fields are changed
 const updated = await products.patch('rec_abc123', {
   price:   69.99,
   inStock: false,
@@ -214,8 +263,8 @@ const { records } = await products.query();
 // With filters
 const { records: affordableStock } = await products.query({
   filters: [
-    { field: 'inStock', op: '==', value: true  },
-    { field: 'price',   op: '<',  value: 100   },
+    { field: 'inStock', op: '==', value: true },
+    { field: 'price',   op: '<',  value: 100  },
   ],
 });
 
@@ -236,7 +285,7 @@ if (hasMore) {
   });
 }
 
-// Select only specific fields
+// Select specific fields only
 const { records: lightRecords } = await products.query({
   fields: 'name,price,inStock',
 });
@@ -267,23 +316,26 @@ const { records: recent } = await products.query({
 ```typescript
 // Create multiple records at once
 const created = await products.batchCreate([
-  { name: 'Item A', price: 10.00, inStock: true },
+  { name: 'Item A', price: 10.00, inStock: true  },
   { name: 'Item B', price: 20.00, inStock: false },
-  { name: 'Item C', price: 30.00, inStock: true },
+  { name: 'Item C', price: 30.00, inStock: true  },
 ]);
-// → [{ id: 'rec_1', ... }, { id: 'rec_2', ... }, { id: 'rec_3', ... }]
+// → [{ id: '260601-rec_1', ... }, { id: '260601-rec_2', ... }, ...]
 
 // Count records
-const total = await products.count();
+const total   = await products.count();
 const inStock = await products.count([{ field: 'inStock', op: '==', value: true }]);
 
+// Get all records without filters (shortcut for query)
+const all = await products.getAll({ orderBy: 'price', order: 'asc' });
+
 // Delete multiple records
 const { deleted, failed } = await products.batchDelete(['rec_1', 'rec_2', 'rec_3']);
 ```
 
 ### Version History
 
-Every write to a record creates a new version stored in GCS, so you can travel back in time.
+Every write to a record creates a new version, so you can travel back in time.
 
 ```typescript
 // Get the full version history of a record
@@ -298,9 +350,7 @@ const restored = await products.restoreVersion('rec_abc123', history[2]!.version
 
 ## Authentication
 
-HydrousDB has a built-in user auth system. Your users live in a bucket you create
-(e.g. `"app-users"`). You get sessions, refresh tokens, password reset, email
-verification, and admin controls out of the box.
+HydrousDB has a 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.
 
 ```typescript
 const auth = db.auth('app-users');
@@ -311,15 +361,15 @@ const auth = db.auth('app-users');
 ```typescript
 const { user, session } = await auth.signup({
   email:    'alice@example.com',
-  password: 'hunter2',           // min 8 characters, validated server-side
+  password: 'hunter2',         // min 8 characters, validated server-side
   fullName: 'Alice Wonderland',
   // Any extra fields are stored on the user record:
   plan:     'pro',
   referral: 'friend123',
 });
 
-// user.id          → "usr_xxxxxxxxxx"
-// session.sessionId → persist this in your app
+// user.id              → "usr_xxxxxxxxxx"
+// session.sessionId    → persist this in your app
 // session.refreshToken → persist this for long-lived sessions
 ```
 
@@ -338,7 +388,7 @@ await auth.logout({ sessionId: session.sessionId });
 
 ### Session Management
 
-Sessions expire after **24 hours**. Use the refresh token to get a new session (refresh tokens last **30 days**).
+Sessions expire after **24 hours**. Use the refresh token to get a new session — refresh tokens last **30 days**.
 
 ```typescript
 // Refresh the session before it expires
@@ -371,7 +421,7 @@ const updated = await auth.updateUser({
 // 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 (your app handles the email sending)
+// 2. User receives an email with a reset token
 
 // 3. User submits the new password
 await auth.confirmPasswordReset({
@@ -452,11 +502,14 @@ const { deleted, failed } = await auth.bulkDeleteUsers({
 
 ## File Storage
 
-HydrousDB Storage is backed by Google Cloud Storage. Your files live at:
-```
-hydrous-storage/{your-owner-id}/{your-path}
+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');
 ```
-You never see or specify the owner prefix — the SDK handles it transparently.
 
 ### Simple Upload
 
@@ -464,10 +517,9 @@ For files up to **500 MB** when you don't need upload progress:
 
 ```typescript
 // Browser: upload from a file input
-const fileInput = document.querySelector('input[type="file"]');
-const file = fileInput.files[0];
+const file = document.querySelector('input[type="file"]').files[0];
 
-const result = await db.storage.upload(file, `uploads/${file.name}`, {
+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
 });
@@ -480,14 +532,14 @@ 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.upload(buffer, 'reports/q3.pdf');
+const result = await db.storage('documents').upload(buffer, 'reports/q3.pdf');
 console.log(result.downloadUrl); // requires X-Storage-Key to access
 ```
 
 ### Upload Raw JSON or Text
 
 ```typescript
-const result = await db.storage.uploadRaw(
+const result = await db.storage('main').uploadRaw(
   { theme: 'dark', language: 'en' },
   'user-config/alice.json',
   { isPublic: false },
@@ -496,20 +548,21 @@ const result = await db.storage.uploadRaw(
 
 ### Large File Upload (with progress)
 
-For files over 10 MB or when you need a progress bar. The file goes directly
-to GCS — your server never buffers it.
+For files over 10 MB or when you need a progress bar. The file goes directly to GCS — your server never buffers it.
 
 ```typescript
+const storage = db.storage('main');
+
 // Step 1: Get a signed upload URL
-const { uploadUrl, path } = await db.storage.getUploadUrl({
+const { uploadUrl, path } = await storage.getUploadUrl({
   path:     'videos/product-demo.mp4',
   mimeType: 'video/mp4',
   size:     file.size,
   isPublic: true,
 });
 
-// Step 2: Upload directly to GCS with progress
-await db.storage.uploadToSignedUrl(
+// Step 2: Upload directly to GCS with progress tracking
+await storage.uploadToSignedUrl(
   uploadUrl,
   file,
   'video/mp4',
@@ -519,8 +572,8 @@ await db.storage.uploadToSignedUrl(
   },
 );
 
-// Step 3: Confirm the upload (registers metadata)
-const result = await db.storage.confirmUpload({
+// Step 3: Confirm the upload (registers metadata server-side)
+const result = await storage.confirmUpload({
   path:     path,
   mimeType: 'video/mp4',
   isPublic: true,
@@ -532,49 +585,53 @@ console.log(result.publicUrl); // ready to use
 ### Batch Upload
 
 ```typescript
-// Get signed URLs for multiple files
-const { files } = await db.storage.getBatchUploadUrls([
+const storage = db.storage('main');
+
+// 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 },
 ]);
 
-// Upload each one
+// Upload each one directly to GCS
 for (const f of files) {
-  await db.storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
+  await storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
 }
 
 // Confirm all at once
-const results = await db.storage.batchConfirmUploads(
-  files.map(f => ({ path: f.path, mimeType: f.mimeType, isPublic: true }))
+const results = await storage.batchConfirmUploads(
+  files.map(f => ({ path: f.path, mimeType: f.mimeType, isPublic: true })),
 );
 ```
 
 ### Download Files
 
 ```typescript
-// Private files require authentication — download as ArrayBuffer
-const buffer = await db.storage.download('reports/q3.pdf');
+// Private files require authentication — returns ArrayBuffer
+const buffer = await db.storage('documents').download('reports/q3.pdf');
 const blob   = new Blob([buffer], { type: 'application/pdf' });
 
-// In a browser: trigger a file download
-const url = URL.createObjectURL(blob);
-const a   = document.createElement('a');
-a.href    = url;
+// 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: just use the publicUrl directly (no SDK needed)
+// Public files: use publicUrl directly — no SDK needed
 // <img src={result.publicUrl} />
 ```
 
 ### List Files
 
 ```typescript
+const storage = db.storage('main');
+
 // List everything at the root
-const { files, folders } = await db.storage.list();
+const { files, folders } = await storage.list();
 
 // List a specific folder
-const { files, folders, hasMore, nextCursor } = await db.storage.list({
+const { files, folders, hasMore, nextCursor } = await storage.list({
   prefix:    'gallery/',
   limit:     50,
   recursive: false,
@@ -582,7 +639,7 @@ const { files, folders, hasMore, nextCursor } = await db.storage.list({
 
 // Paginate
 if (hasMore) {
-  const page2 = await db.storage.list({ prefix: 'gallery/', cursor: nextCursor });
+  const page2 = await storage.list({ prefix: 'gallery/', cursor: nextCursor });
 }
 ```
 
@@ -602,11 +659,11 @@ Each file entry includes:
 
 ### Scoped Storage
 
-Working within a specific folder? Use `.scope()` to avoid typing the prefix on every call.
+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.scope('user-avatars');
+const avatars = db.storage('avatars').scope('user-avatars');
 
 await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
 // → uploads to "user-avatars/{userId}.jpg"
@@ -625,42 +682,45 @@ const thumbnails = avatars.scope('thumbnails');
 ### Share & Visibility
 
 ```typescript
-// Get file metadata (sizes, URLs, visibility)
-const meta = await db.storage.getMetadata('reports/q3.pdf');
+const storage = db.storage('documents');
+
+// Get file metadata (size, MIME type, URLs, visibility)
+const meta = await storage.getMetadata('reports/q3.pdf');
 
 // Generate a time-limited share link for a private file
 // (no auth key needed to use the link)
-const { signedUrl, expiresAt } = await db.storage.getSignedUrl(
+const { signedUrl, expiresAt } = await storage.getSignedUrl(
   'reports/q3.pdf',
-  3600,  // expires in 1 hour (default)
+  3600, // expires in 1 hour (default)
 );
-// Share signedUrl with whoever needs it
 
 // Toggle visibility after upload
-const result = await db.storage.setVisibility('reports/q3.pdf', true);  // make public
-const result2 = await db.storage.setVisibility('reports/q3.pdf', false); // make private
+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 db.storage.move('drafts/report.pdf', 'published/report-2025.pdf');
+await storage.move('drafts/report.pdf', 'published/report-2025.pdf');
 
 // Copy a file
-await db.storage.copy('templates/invoice.html', 'invoices/inv-001.html');
+await storage.copy('templates/invoice.html', 'invoices/inv-001.html');
 
 // Create a folder
-await db.storage.createFolder('archive/2025/');
+await storage.createFolder('archive/2025/');
 
 // Delete a file
-await db.storage.deleteFile('temp/scratch.txt');
+await storage.deleteFile('temp/scratch.txt');
 
 // Delete a folder and all its contents
-await db.storage.deleteFolder('temp/');
+await storage.deleteFolder('temp/');
 
 // Get key-level stats
-const stats = await db.storage.getStats();
+const stats = await storage.getStats();
 // → { totalFiles: 842, totalBytes: 1073741824, uploadCount: 1200, ... }
 ```
 
@@ -668,8 +728,7 @@ const stats = await db.storage.getStats();
 
 ## Analytics
 
-HydrousDB Analytics runs your queries against BigQuery, so they're fast even
-on millions of records. All queries accept an optional `dateRange` filter.
+HydrousDB Analytics runs queries directly against BigQuery on your GCS data — zero ETL, no data duplication, live results. Fast even on billions of records.
 
 ```typescript
 const analytics = db.analytics('orders');
@@ -710,7 +769,7 @@ const rows = await analytics.distribution({ field: 'status', limit: 10, order: '
 const rows = await analytics.sum({ field: 'amount' });
 // → [{ sum: 198432.50 }]
 
-// Revenue by country
+// Revenue grouped by country
 const byCountry = await analytics.sum({
   field:   'amount',
   groupBy: 'country',
@@ -721,11 +780,11 @@ const byCountry = await analytics.sum({
 
 ### Time Series
 
-Record counts over time — ideal for activity charts.
+Record counts over time — ideal for activity and growth charts.
 
 ```typescript
 const rows = await analytics.timeSeries({
-  granularity: 'day',       // 'hour' | 'day' | 'week' | 'month' | 'year'
+  granularity: 'day',  // 'hour' | 'day' | 'week' | 'month' | 'year'
   dateRange: {
     start: new Date('2025-01-01').getTime(),
     end:   new Date('2025-06-01').getTime(),
@@ -734,12 +793,12 @@ const rows = await analytics.timeSeries({
 // → [{ date: '2025-01-01', count: 42 }, { date: '2025-01-02', count: 67 }, ...]
 ```
 
-Aggregate a field over time:
+Aggregate a numeric field over time:
 
 ```typescript
 const revenue = await analytics.fieldTimeSeries({
   field:       'amount',
-  aggregation: 'sum',   // 'sum' | 'avg' | 'min' | 'max' | 'count'
+  aggregation: 'sum',  // 'sum' | 'avg' | 'min' | 'max' | 'count'
   granularity: 'week',
 });
 // → [{ date: '2025-W01', value: 12340.50 }, ...]
@@ -752,7 +811,7 @@ Most common values for a field:
 ```typescript
 const topProducts = await analytics.topN({
   field:      'productId',
-  labelField: 'productName',  // optional: include a human-readable label
+  labelField: 'productName', // optional: include a human-readable label
   n:          5,
   order:      'desc',
 });
@@ -781,10 +840,10 @@ Calculate several aggregations in a single BigQuery query:
 ```typescript
 const dashboard = await analytics.multiMetric({
   metrics: [
-    { field: 'amount',   name: 'totalRevenue',    aggregation: 'sum'   },
-    { field: 'amount',   name: 'avgOrderValue',   aggregation: 'avg'   },
-    { field: 'amount',   name: 'maxOrder',        aggregation: 'max'   },
-    { field: 'userId',   name: 'totalOrders',     aggregation: 'count' },
+    { field: 'amount', name: 'totalRevenue',  aggregation: 'sum'   },
+    { field: 'amount', name: 'avgOrderValue', aggregation: 'avg'   },
+    { field: 'amount', name: 'maxOrder',      aggregation: 'max'   },
+    { field: 'userId', name: 'totalOrders',   aggregation: 'count' },
   ],
   dateRange: { start: new Date('2025-01-01').getTime(), end: Date.now() },
 });
@@ -798,7 +857,7 @@ const dashboard = await analytics.multiMetric({
 
 ### Filtered Records (BigQuery)
 
-Query raw records with full BigQuery speed:
+Query raw records at full BigQuery speed:
 
 ```typescript
 const records = await analytics.records({
@@ -830,7 +889,7 @@ const comparison = await analytics.crossBucket({
 // ]
 ```
 
-> ⚠️ Your Security Key must have read access to **all** buckets in the list.
+> ⚠️ Your Bucket Security Key must have read access to **all** listed buckets.
 
 ### Storage Stats
 
@@ -843,13 +902,12 @@ const stats = await analytics.storageStats();
 
 ## TypeScript Support
 
-The SDK is written in TypeScript and ships with full type definitions. Use generic
-type parameters to describe the shape of your records and get autocomplete throughout.
+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
 import { createClient } from 'hydrousdb';
 
-// Define your data models
+// Define your data models as plain interfaces — no index signature needed
 interface Order {
   customerId: string;
   items:      Array<{ productId: string; qty: number; price: number }>;
@@ -865,7 +923,11 @@ interface Customer {
   credits: number;
 }
 
-const db = createClient({ securityKey: process.env.HYDROUS_SECURITY_KEY! });
+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');
@@ -881,7 +943,7 @@ const order = await orders.create({
 });
 
 // TypeScript catches mistakes at compile time:
-// order.nonExistentField  // ← TS error ✓
+// order.nonExistentField   // ← TS error ✓
 // order.status = 'invalid' // ← TS error ✓
 ```
 
@@ -918,19 +980,19 @@ All errors thrown by the SDK extend `HydrousError`, which carries:
 import { HydrousError, NetworkError, AuthError } from 'hydrousdb';
 
 try {
-  const user = await auth.login({ email: 'a@b.com', password: 'wrong' });
+  const { user } = await auth.login({ email: 'a@b.com', password: 'wrong' });
 } catch (err) {
   if (err instanceof AuthError) {
     // Authentication-specific error
     console.error(`Auth failed: ${err.code}`);
-    // err.code might be: INVALID_CREDENTIALS, ACCOUNT_LOCKED, EMAIL_NOT_VERIFIED, etc.
+    // 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 this in support tickets
+    console.error(`Request ID: ${err.requestId}`); // include in support tickets
   }
 }
 ```
@@ -943,8 +1005,8 @@ try {
 | `INVALID_CREDENTIALS` | Wrong email or password |
 | `ACCOUNT_LOCKED` | The account is temporarily locked |
 | `INVALID_SESSION` | Session expired or revoked — re-authenticate |
-| `MISSING_API_KEY` | Security key not provided |
-| `INVALID_SECURITY_KEY` | Security key is wrong or revoked |
+| `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 |
@@ -956,31 +1018,32 @@ try {
 
 ## Security Best Practices
 
-1. **Never hard-code your Security Key.** Use environment variables:
+1. **Never hard-code your keys.** Use environment variables:
 
    ```bash
    # .env (add to .gitignore)
-   HYDROUS_SECURITY_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx
+   HYDROUS_AUTH_KEY=hk_auth_xxxxxxxxxxxxxxxxxxxx
+   HYDROUS_BUCKET_KEY=hk_bucket_xxxxxxxxxxxxxxxxxxxx
+   HYDROUS_STORAGE_MAIN=ssk_xxxxxxxxxxxxxxxxxxxx
    ```
 
    ```typescript
-   const db = createClient({ securityKey: process.env.HYDROUS_SECURITY_KEY! });
+   const db = createClient({
+     authKey:           process.env.HYDROUS_AUTH_KEY!,
+     bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+     storageKeys: { main: process.env.HYDROUS_STORAGE_MAIN! },
+   });
    ```
 
-2. **Never expose your Security Key to browsers.** For browser-side apps,
-   route requests through your own backend, or use per-user session tokens.
+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()`.
 
-3. **Your Security Key is sent via the `X-Api-Key` header — never in URLs.**
-   The SDK enforces this automatically, so keys never appear in server logs or
-   browser history.
+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.
 
 4. **Rotate keys periodically.** Revoke old keys from the dashboard after rotation.
 
-5. **Use scoped storage** (`db.storage.scope(...)`) to isolate access by user or
-   feature, reducing the blast radius of any misconfiguration.
+5. **Use scoped storage** (`db.storage('keyName').scope('prefix/')`) to isolate access by user or feature, reducing the blast radius of any misconfiguration.
 
-6. **Use `isPublic: false` (the default) for sensitive files.** Use signed URLs
-   for time-limited sharing instead of making files permanently public.
+6. **Use `isPublic: false` (the default) for sensitive files.** Use signed URLs for time-limited sharing instead of making files permanently public.
 
 ---
 
@@ -988,18 +1051,24 @@ try {
 
 ### `createClient(config)`
 
-Creates and returns a `HydrousClient` instance. Call this once and reuse the instance.
+Creates and returns a `HydrousClient` instance. Call this once and reuse it everywhere.
 
 ```typescript
 const db = createClient({
-  securityKey: 'sk_live_...',   // Required — from https://hydrousdb.com/dashboard
-  baseUrl:     'https://...',   // Optional — defaults to official HydrousDB endpoint
+  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)`
 
-Returns a `RecordsClient<T>` for the named bucket.
+Returns a `RecordsClient<T>` for the named bucket. Uses `bucketSecurityKey` automatically.
 
 | Method | Description |
 |---|---|
@@ -1014,78 +1083,83 @@ Returns a `RecordsClient<T>` for the named bucket.
 | `batchCreate(items)` | Create multiple records |
 | `batchDelete(ids)` | Delete multiple records |
 | `getHistory(id)` | Get version history |
-| `restoreVersion(id, version)` | Restore to a version |
+| `restoreVersion(id, version)` | Restore to a previous version |
 
 ### `db.auth(bucketKey)`
 
-Returns an `AuthClient` for the named user bucket.
+Returns an `AuthClient` for the named user bucket. Uses `authKey` automatically.
 
 | Method | Description |
 |---|---|
 | `signup(opts)` | Register a new user |
-| `login(opts)` | Authenticate and create session |
-| `logout({ sessionId })` | Invalidate session |
+| `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 |
-| `deleteUser(opts)` | Soft-delete a user |
-| `hardDeleteUser(opts)` | Permanently delete a user (admin) |
-| `listUsers(opts)` | List all users (admin) |
-| `bulkDeleteUsers(opts)` | Bulk delete (admin) |
-| `lockAccount(opts)` | Lock a user (admin) |
-| `unlockAccount(opts)` | Unlock a user (admin) |
 | `changePassword(opts)` | Change password (authenticated) |
 | `requestPasswordReset(opts)` | Send reset email |
-| `confirmPasswordReset(opts)` | Apply new password |
+| `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.
+Returns an `AnalyticsClient` for the named bucket. Uses `bucketSecurityKey` automatically.
 
 | Method | Description |
 |---|---|
 | `count(opts?)` | Count records |
 | `distribution(opts)` | Value distribution for a field |
-| `sum(opts)` | Sum (with optional groupBy) |
-| `timeSeries(opts?)` | Records over time |
+| `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 field |
-| `records(opts?)` | Filtered raw records (BigQuery) |
+| `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 across multiple buckets |
+| `crossBucket(opts)` | Compare a metric across multiple buckets |
 | `query(query)` | Raw analytics query |
 
-### `db.storage`
+### `db.storage(keyName)`
 
-The `StorageManager` instance. Also has `.scope(prefix)` for folder-scoped access.
+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?)` | Simple server-buffered upload |
-| `uploadRaw(data, path, opts?)` | Upload JSON/text data |
-| `getUploadUrl(opts)` | Step 1: Get signed GCS upload URL |
-| `uploadToSignedUrl(url, data, mime, onProgress?)` | Step 2: Upload to GCS directly |
+| `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)` | Batch signed upload URLs |
-| `batchConfirmUploads(items)` | Confirm batch uploads |
-| `download(path)` | Download private file |
-| `batchDownload(paths)` | Batch download |
+| `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)` | File metadata |
-| `getSignedUrl(path, expiresIn?)` | Time-limited share URL |
-| `setVisibility(path, isPublic)` | Toggle public/private |
+| `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 recursively |
-| `move(from, to)` | Move/rename |
-| `copy(from, to)` | Copy |
-| `getStats()` | Key-level stats |
-| `info()` | Server ping (no auth) |
-| `scope(prefix)` | Get a ScopedStorage instance |
+| `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 |
 
 ---
 
@@ -1121,6 +1195,6 @@ MIT — see [LICENSE](./LICENSE) for details.
 
 <p align="center">
   Built with ❤️ by the <a href="https://hydrousdb.com">HydrousDB</a> team.<br>
-  Questions? <a href="mailto:support@hydrousdb.com">support@hydrousdb.com</a> · 
+  Questions? <a href="mailto:support@hydrousdb.com">support@hydrousdb.com</a> ·
   <a href="https://github.com/hydrousdb/hydrousdb-js/issues">Open an issue</a>
-</p>
+</p>