hydrousdb 3.5.0 → 3.5.1

package/README.md

@@ -10,17 +10,73 @@ npm install hydrousdb
 
 ---
 
+## Table of Contents
+
+- [Setup](#setup)
+- [Records](#records)
+  - [Create, Read, Update, Delete](#create-read-update-delete)
+  - [Querying & Filtering](#querying--filtering)
+  - [Time Scope on Queries](#time-scope-on-queries)
+  - [Pagination](#pagination)
+  - [Atomic Field Updates](#atomic-field-updates)
+  - [Batch Operations](#batch-operations)
+  - [Version History](#version-history)
+  - [Custom Record IDs](#custom-record-ids)
+  - [Existence Check](#existence-check)
+  - [Get All Records](#get-all-records)
+- [Auth](#auth)
+  - [Sign Up & Log In](#sign-up--log-in)
+  - [Session Management](#session-management)
+  - [User Profile](#user-profile)
+  - [Password & Email](#password--email)
+  - [Admin Controls](#admin-controls)
+- [File Storage](#file-storage)
+  - [Upload](#upload)
+  - [Large Files with Progress](#large-files-with-progress)
+  - [Batch Uploads](#batch-uploads)
+  - [Download](#download)
+  - [Batch Download](#batch-download)
+  - [List, Metadata & Signed URLs](#list-metadata--signed-urls)
+  - [Move, Copy & Delete](#move-copy--delete)
+  - [Visibility](#visibility)
+  - [Folders](#folders)
+  - [Scoped Storage](#scoped-storage)
+  - [Storage Stats](#storage-stats)
+- [Analytics](#analytics)
+  - [Date Range (Time Scope)](#date-range-time-scope)
+  - [Count](#count)
+  - [Distribution](#distribution)
+  - [Sum](#sum)
+  - [Time Series](#time-series)
+  - [Field Time Series](#field-time-series)
+  - [Top N](#top-n)
+  - [Stats](#stats)
+  - [Records via BigQuery](#records-via-bigquery)
+  - [Multi-Metric](#multi-metric)
+  - [Storage Stats](#storage-stats-1)
+  - [Cross-Bucket](#cross-bucket)
+  - [Raw Query](#raw-query)
+- [Error Handling](#error-handling)
+- [TypeScript](#typescript)
+- [Security](#security)
+- [Framework Examples](#framework-examples)
+- [API Reference](#api-reference)
+
+---
+
 ## Setup
 
 ```ts
 import { createClient } from 'hydrousdb';
 
 const db = createClient({
-  authKey:           process.env.HYDROUS_AUTH_KEY!,
-  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+  authKey:           process.env.HYDROUS_AUTH_KEY!,          // hk_auth_…
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,        // hk_bucket_…
   storageKeys: {
-    main: process.env.HYDROUS_STORAGE_KEY!,
+    main: process.env.HYDROUS_STORAGE_KEY!,                  // ssk_…
+    // add more named storage keys as needed
   },
+  // baseUrl: 'https://custom-endpoint.example.com',         // optional override
 });
 ```
 
@@ -32,104 +88,225 @@ Works in **React, Next.js, Vue, React Native, Node.js** — anywhere that runs m
 
 ## Records
 
-JSON objects stored in named buckets. Every record gets `id`, `createdAt`, and `updatedAt` automatically.
+JSON objects stored in named buckets. Every record automatically gets `id`, `createdAt`, and `updatedAt`.
 
 ```ts
 const posts = db.records('blog-posts');
+```
+
+### Create, Read, Update, Delete
 
+```ts
 // Create
 const post = await posts.create(
   { title: 'Hello', status: 'draft', views: 0 },
-  { queryableFields: ['status'] },   // declare fields you want to filter on
+  {
+    queryableFields: ['status', 'views'],  // declare fields you want to filter on
+    userEmail: 'alice@example.com',        // optional — for audit trails
+  },
 );
-console.log(post.id); // "260601-rec_01JA2XYZ"
+console.log(post.id);        // "260601-rec_01JA2XYZ"
+console.log(post.createdAt); // Unix ms timestamp
 
-// Read  (path computed from ID — zero index lookups)
+// Read by ID
 const found = await posts.get(post.id);
 
-// Update  (only the fields you pass are changed)
+// Partial update — only the fields you pass are changed
 await posts.patch(post.id, { status: 'published' });
 
-// Delete
+// Merge mode — deeply merge nested objects instead of replacing them
+await posts.patch(post.id, { meta: { seo: true } }, { merge: true });
+
+// Delete permanently
 await posts.delete(post.id);
 ```
 
-> **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.
+> **Why `queryableFields`?** Records are stored as compressed blobs. Fields you want to filter or sort by must be declared at write time. You only pay the indexing overhead for what you actually query.
 
-### Query
+---
+
+### Querying & Filtering
 
 ```ts
 const { records, hasMore, nextCursor } = await posts.query({
   filters: [
-    { field: 'status', op: '==', value: 'published' },
-    { field: 'views',  op: '>',  value: 100 },
+    { field: 'status', op: '==',       value: 'published' },
+    { field: 'views',  op: '>',        value: 100 },
+    { field: 'title',  op: 'contains', value: 'hello' },
   ],
   orderBy: 'createdAt',
   order:   'desc',
   limit:   20,
+  fields:  'id,title,status', // optional — return only these fields
+});
+```
+
+**Supported filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`
+
+---
+
+### Time Scope on Queries
+
+Pass `timeScope` to restrict records to a specific **day, month, or year** using the record ID prefix convention. This is the fastest way to scope a query by time — no timestamp arithmetic needed.
+
+| Scope | Format | Example | Matches |
+|---|---|---|---|
+| Day | `_day_YYMMDD` | `_day_260305` | March 5, 2026 |
+| Month | `_month_YYMM` | `_month_2603` | March 2026 |
+| Year | `_year_YY` | `_year_26` | All of 2026 |
+
+```ts
+// All records from March 2026
+const { records, hasMore, nextCursor } = await posts.query({
+  timeScope: '_month_2603',
+  order:     'desc',
+  limit:     50,
 });
 
-// Next page
+// Paginate through a time-scoped result set
 if (hasMore) {
-  const page2 = await posts.query({ limit: 20, startAfter: nextCursor });
+  const page2 = await posts.query({
+    timeScope:  '_month_2603',
+    startAfter: nextCursor,
+  });
 }
+
+// A specific day
+const { records: dayRecords } = await posts.query({
+  timeScope: '_day_260305',   // March 5, 2026
+  order:     'asc',
+});
+
+// An entire year
+const { records: yearRecords } = await posts.query({
+  timeScope: '_year_26',
+  orderBy:   'createdAt',
+  order:     'asc',
+  limit:     100,
+});
+
+// Fully composable with filters
+const { records: published } = await posts.query({
+  timeScope: '_month_2603',
+  filters:   [{ field: 'status', op: '==', value: 'published' }],
+  orderBy:   'createdAt',
+  order:     'desc',
+});
+
+// getAll() also respects timeScope
+const all = await posts.getAll({ timeScope: '_year_26' });
 ```
 
-Filter operators: `==` `!=` `>` `<` `>=` `<=` `CONTAINS`
+---
 
-### Atomic field updates
+### Pagination
 
-Avoid race conditions with server-side operations inside `patch()`:
+`query()` returns a cursor you can pass straight into the next call.
+
+```ts
+// Page 1
+const page1 = await posts.query({ limit: 20, orderBy: 'createdAt', order: 'desc' });
+
+// Page 2
+if (page1.hasMore) {
+  const page2 = await posts.query({
+    limit:      20,
+    orderBy:    'createdAt',
+    order:      'desc',
+    startAfter: page1.nextCursor,   // cursor-based — no offset drift
+  });
+}
+
+// You can also use startAt / endAt for range-based cursor control
+const window = await posts.query({ startAt: cursorA, endAt: cursorB });
+```
+
+---
+
+### Atomic Field Updates
+
+Avoid race conditions with server-side sentinels 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' },
+  views:    { __op: 'increment',      delta: 1 },          // add N
+  credits:  { __op: 'decrement',      delta: 5 },          // subtract N
+  slug:     { __op: 'setOnce',        value: 'my-post' },  // set only if currently empty
+  tags:     { __op: 'appendUnique',   item: 'featured' },  // add to array, no duplicates
+  tags:     { __op: 'removeFromArray', item: 'draft' },    // remove from array
+  rating:   { __op: 'clamp',          value: 6, min: 0, max: 5 }, // clamp to range
+  price:    { __op: 'multiplyBy',     factor: 1.1 },       // multiply
+  active:   { __op: 'toggleBool' },                        // flip boolean
+  syncedAt: { __op: 'serverTimestamp' },                   // set to server time
 } as any);
 ```
 
-### Batch operations
+Enable audit trails and history with extra `patch` options:
+
+```ts
+await posts.patch(
+  post.id,
+  { status: 'published' },
+  { userEmail: 'alice@example.com', trackHistory: true },
+);
+```
+
+---
+
+### Batch Operations
 
 ```ts
 // Create up to 500 records at once
-const { results, errors } = await posts.batchCreate(
-  [{ title: 'A' }, { title: 'B' }],
-  { queryableFields: ['title'] },
+const { results, errors, successful, failed } = await posts.batchCreate(
+  [{ title: 'A', status: 'draft' }, { title: 'B', status: 'draft' }],
+  { queryableFields: ['title', 'status'], userEmail: 'alice@example.com' },
 );
 
 // Update up to 500 records at once
-await posts.batchUpdate([
-  { recordId: 'id1', values: { status: 'archived' } },
-  { recordId: 'id2', values: { status: 'archived' } },
-]);
+const { successful, failed } = await posts.batchUpdate(
+  [
+    { recordId: 'id1', values: { status: 'archived' } },
+    { recordId: 'id2', values: { status: 'archived' } },
+  ],
+  'alice@example.com', // optional userEmail
+);
 
 // Delete up to 500 records at once
 const { successful, failed } = await posts.batchDelete(['id1', 'id2']);
 ```
 
-### Version history
+Batch upsert using custom IDs — include `_customRecordId` on each item:
+
+```ts
+await posts.batchCreate([
+  { _customRecordId: '260601-post_hello', title: 'Hello' },
+  { _customRecordId: '260601-post_world', title: 'World' },
+] as any);
+```
+
+---
+
+### Version History
 
-Every write is automatically versioned.
+Every write is automatically versioned when `trackHistory` is enabled.
 
 ```ts
+// List all saved versions
 const history = await posts.getHistory(post.id);
-// [{ generation, savedAt, savedBy, sizeBytes }, …]
+// → [{ generation, savedAt, savedBy, sizeBytes }, …]
 
-// Read a specific past version
+// Retrieve a specific past version
 const v1 = await posts.getVersion(post.id, history[0].generation!);
 ```
 
-### Custom record IDs
+---
+
+### Custom Record IDs
+
+Supply your own ID at creation time — if it already exists the record is upserted in-place.
 
 ```ts
-// If the ID already exists, the record is upserted
+// Format: YYMMDD-segment1__segment2
 const post = await posts.create(
   { title: 'Welcome' },
   { customRecordId: '260601-post_welcome' },
@@ -138,6 +315,30 @@ const post = await posts.create(
 
 ---
 
+### Existence Check
+
+A lightweight HEAD request — much cheaper than fetching the full record:
+
+```ts
+const exists = await posts.exists(post.id); // true | false
+```
+
+---
+
+### Get All Records
+
+Fetches every record matching the options without filter support. Use `query()` when you need filters.
+
+```ts
+const all = await posts.getAll({
+  orderBy: 'createdAt',
+  order:   'desc',
+  limit:   500,
+});
+```
+
+---
+
 ## Auth
 
 A complete user system — signup, login, sessions, password reset, email verification, and admin controls.
@@ -146,7 +347,7 @@ A complete user system — signup, login, sessions, password reset, email verifi
 const auth = db.auth();
 ```
 
-### Sign up & log in
+### Sign Up & Log In
 
 ```ts
 // Sign up — extra fields beyond email/password are stored on the user
@@ -163,40 +364,75 @@ const { user, session } = await auth.login({
   password: 'hunter2',
 });
 
-// Log out (pass allDevices: true to log out everywhere)
+// Log out this device
 await auth.logout({ sessionId: session.sessionId });
+
+// Log out everywhere
+await auth.logout({ sessionId: session.sessionId, allDevices: true });
 ```
 
-Store `session.sessionId` and `session.refreshToken` in your app. Sessions expire after **24 hours**, refresh tokens after **30 days**.
+Store `session.sessionId` and `session.refreshToken` in your app.
+
+| Token | Lifetime |
+|---|---|
+| `sessionId` | 24 hours |
+| `refreshToken` | 30 days |
+
+---
 
-### Session management
+### Session Management
 
 ```ts
-// Check if a session is still valid (use on your backend)
-const { user } = await auth.validateSession(session.sessionId);
+// Validate a session and get the current user (use on your backend)
+const { user, session } = await auth.validateSession(session.sessionId);
+// session → { sessionId, expiresAt }
 
-// Get a new session using the refresh token
+// Get a brand-new session from a refresh token (before the old one expires)
 const newSession = await auth.refreshSession(session.refreshToken);
 ```
 
-### User profile
+---
+
+### User Profile
 
 ```ts
+// Fetch a user by ID
 const user = await auth.getUser(session.userId);
 
+// Update profile fields (users can update themselves; admins can update anyone)
 await auth.updateUser({
   sessionId: session.sessionId,
   userId:    user.id,
   updates:   { fullName: 'Alice Johnson', plan: 'enterprise' },
 });
 
+// Soft-delete (users can delete themselves; admins can delete anyone)
 await auth.deleteUser(session.sessionId, user.id);
 ```
 
-### Password & email
+The `UserRecord` shape:
+
+```ts
+interface UserRecord {
+  id:             string;
+  email:          string;
+  fullName?:      string | null;
+  emailVerified:  boolean;
+  accountStatus:  'active' | 'locked' | 'suspended';
+  role:           'user' | 'admin';
+  createdAt:      number;   // Unix ms
+  updatedAt:      number;   // Unix ms
+  metadata?:      Record<string, unknown>;
+  [key: string]:  unknown;  // custom fields from signup
+}
+```
+
+---
+
+### Password & Email
 
 ```ts
-// Change password (requires active session)
+// Change password — requires an active session AND the current password
 await auth.changePassword({
   sessionId:       session.sessionId,
   userId:          user.id,
@@ -204,8 +440,8 @@ await auth.changePassword({
   newPassword:     'correcthorsebatterystaple',
 });
 
-// Forgot password flow
-await auth.requestPasswordReset('alice@example.com');
+// Forgot-password flow
+await auth.requestPasswordReset('alice@example.com');  // always succeeds (prevents enumeration)
 await auth.confirmPasswordReset(tokenFromEmail, 'newpassword123');
 
 // Email verification
@@ -213,25 +449,38 @@ await auth.requestEmailVerification(user.id);
 await auth.confirmEmailVerification(tokenFromEmail);
 ```
 
-### Admin
+---
+
+### Admin Controls
+
+All admin methods require an active admin session.
 
 ```ts
-// List all users (paginated)
+// Paginated user list
 const { users, hasMore, nextCursor } = await auth.listUsers({
   sessionId: adminSession.sessionId,
   limit:     50,
+  cursor:    previousNextCursor, // optional — for subsequent pages
 });
 
-// Lock / unlock an account
-await auth.lockAccount({ sessionId: adminSession.sessionId, userId: user.id });
+// Lock an account (default: 15 minutes)
+const { lockedUntil, unlockTime } = await auth.lockAccount({
+  sessionId: adminSession.sessionId,
+  userId:    user.id,
+  duration:  60 * 60 * 1000, // optional ms — lock for 1 hour
+});
+
+// Unlock an account
 await auth.unlockAccount(adminSession.sessionId, user.id);
 
-// Delete users
+// Permanent (hard) delete — cannot be undone
 await auth.hardDeleteUser(adminSession.sessionId, user.id);
-await auth.bulkDeleteUsers({
+
+// Bulk delete — soft or hard
+const { succeeded, failed } = await auth.bulkDeleteUsers({
   sessionId: adminSession.sessionId,
-  userIds:   ['id1', 'id2'],
-  hard:      true,
+  userIds:   ['id1', 'id2', 'id3'],
+  hard:      true, // optional — defaults to soft delete
 });
 ```
 
@@ -239,79 +488,227 @@ await auth.bulkDeleteUsers({
 
 ## File Storage
 
+Files are **private by default** and scoped to your storage key server-side.
+
 ```ts
-const storage = db.storage('main');
+const storage = db.storage('main'); // 'main' matches a key in storageKeys config
 ```
 
 ### Upload
 
 ```ts
-// Simple upload (up to 500 MB)
-const result = await storage.upload(file, 'avatars/alice.jpg', { isPublic: true });
-console.log(result.publicUrl);    // permanent CDN URL
-console.log(result.downloadUrl);  // authenticated download URL (if private)
-
-// Upload a JSON object or string directly
-await storage.uploadRaw({ theme: 'dark' }, 'config.json');
+// Simple upload — anything up to 500 MB
+const result = await storage.upload(file, 'avatars/alice.jpg', {
+  isPublic:        true,     // public CDN URL (default: false)
+  overwrite:       true,     // replace if the path exists (default: false)
+  mimeType:        'image/jpeg',  // optional — auto-detected from content if omitted
+  expiresInSeconds: 3600,    // optional — auto-delete after N seconds
+});
+console.log(result.publicUrl);   // permanent CDN URL (if isPublic: true)
+console.log(result.downloadUrl); // authenticated URL (if private)
+console.log(result.path);
+console.log(result.size);
+console.log(result.mimeType);
+
+// Upload a JS object or string directly as a file
+await storage.uploadRaw({ theme: 'dark', lang: 'en' }, 'settings/config.json');
+await storage.uploadRaw('<html>…</html>', 'pages/home.html', { mimeType: 'text/html' });
 ```
 
-**Large files with progress tracking** (recommended for anything > 10 MB):
+---
+
+### Large Files with Progress
+
+Recommended for files > 10 MB or when you need a progress indicator (browsers only).
 
 ```ts
-// Step 1 — get a signed upload URL
-const { uploadUrl, path } = await storage.getUploadUrl({
-  path:     'videos/intro.mp4',
+// Step 1 — get a signed GCS PUT URL
+const { uploadUrl, path, expiresAt, expiresIn } = await storage.getUploadUrl({
+  path:             'videos/intro.mp4',
+  mimeType:         'video/mp4',
+  size:             file.size,
+  isPublic:         true,
+  overwrite:        false,
+  expiresInSeconds: 3600, // URL lifetime
+});
+
+// Step 2 — upload directly to GCS with progress callback (browser XHR)
+await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', (percent) => {
+  console.log(`${percent}% uploaded`);
+});
+
+// Step 3 — confirm and register metadata server-side
+const result = await storage.confirmUpload({
+  path,
   mimeType: 'video/mp4',
-  size:     file.size,
   isPublic: true,
 });
+```
 
-// Step 2 — upload directly to GCS (supports onProgress in browsers)
-await storage.uploadToSignedUrl(uploadUrl, file, 'video/mp4', pct => {
-  console.log(`${pct}% uploaded`);
-});
+---
+
+### Batch Uploads
+
+Get signed URLs for up to 50 files at once, upload them in parallel, then confirm in one call.
+
+```ts
+// Step 1 — get signed URLs for multiple files
+const { files: urls } = await storage.getBatchUploadUrls([
+  { path: 'docs/a.pdf', mimeType: 'application/pdf', size: fileA.size, isPublic: false },
+  { path: 'docs/b.pdf', mimeType: 'application/pdf', size: fileB.size, isPublic: false },
+]);
+
+// Step 2 — upload each file (run in parallel)
+await Promise.all(
+  urls.map(({ uploadUrl, path }, i) =>
+    storage.uploadToSignedUrl(uploadUrl, files[i], 'application/pdf'),
+  ),
+);
 
-// Step 3 — confirm and get the final result
-const result = await storage.confirmUpload({ path, mimeType: 'video/mp4', isPublic: true });
+// Step 3 — confirm all at once
+const { succeeded, failed } = await storage.batchConfirmUploads([
+  { path: 'docs/a.pdf', mimeType: 'application/pdf' },
+  { path: 'docs/b.pdf', mimeType: 'application/pdf' },
+]);
+```
+
+---
+
+### Download
+
+```ts
+// Download a private file as ArrayBuffer
+const buffer = await storage.download('private/report.pdf');
+
+// Convert to a Blob for use in the browser
+const blob = new Blob([buffer], { type: 'application/pdf' });
+const url  = URL.createObjectURL(blob);
 ```
 
-### Download, list, manage
+For **public** files, just use the `publicUrl` directly — no SDK or authentication needed.
+
+---
+
+### Batch Download
+
+Downloads up to 20 files at once. Content is returned as base64-encoded strings.
 
 ```ts
-// Download a private file
-const buffer = await storage.download('private/doc.pdf');
+const { succeeded, failed } = await storage.batchDownload([
+  'docs/report.pdf',
+  'images/chart.png',
+]);
+
+for (const file of succeeded) {
+  console.log(file.path, file.mimeType, file.size);
+  // file.content is base64 — decode with atob() or Buffer.from(content, 'base64')
+}
+
+for (const err of failed) {
+  console.error(err.path, err.error, err.code);
+}
+```
+
+---
 
-// List files
-const { files, folders, hasMore, nextCursor } = await storage.list({ prefix: 'avatars/' });
+### List, Metadata & Signed URLs
+
+```ts
+// List files and folders (paginated)
+const { files, folders, hasMore, nextCursor } = await storage.list({
+  prefix:    'avatars/',  // optional path prefix to list under
+  limit:     50,
+  cursor:    previousNextCursor,
+  recursive: true,  // include files in sub-folders (default: false)
+});
+
+// Page 2
+if (hasMore) {
+  const page2 = await storage.list({ prefix: 'avatars/', cursor: nextCursor });
+}
 
 // Get file metadata
 const meta = await storage.getMetadata('avatars/alice.jpg');
+// → { path, size, mimeType, isPublic, publicUrl, downloadUrl, createdAt, updatedAt }
 
-// Time-limited share link (no login needed to access)
-const { signedUrl } = await storage.getSignedUrl('private/report.pdf', 3600);
+// Generate a time-limited link — anyone with the URL can download (no key needed)
+// Note: downloads via signed URL bypass the server, so download stats are NOT tracked
+const { signedUrl, expiresAt, expiresIn } = await storage.getSignedUrl(
+  'private/report.pdf',
+  3600, // lifetime in seconds (default: 3600)
+);
+```
 
-// Move, copy, delete
+---
+
+### Move, Copy & Delete
+
+```ts
 await storage.move('old/path.jpg', 'new/path.jpg');
-await storage.copy('template.html', 'pages/home.html');
+await storage.copy('templates/base.html', 'pages/home.html');
 await storage.deleteFile('avatars/old.jpg');
-await storage.deleteFolder('temp/');
+await storage.deleteFolder('temp/');  // recursively deletes all contents
+```
+
+---
+
+### Visibility
+
+```ts
+// Make a private file public
+const result = await storage.setVisibility('reports/q1.pdf', true);
+console.log(result.publicUrl);
 
-// Change visibility after upload
-await storage.setVisibility('alice.jpg', false);  // make private
+// Make a public file private
+await storage.setVisibility('reports/q1.pdf', false);
 ```
 
-### Scoped storage
+---
+
+### Folders
+
+```ts
+// Create an explicit folder marker (usually not needed — folders are implicit)
+await storage.createFolder('projects/2025/');
+```
 
-Automatically prefix every path — useful for per-user file isolation:
+---
+
+### Scoped Storage
+
+Automatically prefix every path — ideal for per-user file isolation.
 
 ```ts
 const userFiles = db.storage('main').scope(`users/${userId}/`);
 
 await userFiles.upload(pdf, 'contract.pdf');      // → users/{userId}/contract.pdf
-const { files } = await userFiles.list();         // → only lists users/{userId}/
+await userFiles.uploadRaw({ key: 'val' }, 'prefs.json');
+const { files } = await userFiles.list();          // → only lists users/{userId}/
 
 // Nest deeper
-const reports = userFiles.scope('reports/');      // → users/{userId}/reports/
+const reports = userFiles.scope('reports/');       // → users/{userId}/reports/
+await reports.upload(file, 'q1.pdf');              // → users/{userId}/reports/q1.pdf
+
+// All StorageManager methods are available on ScopedStorage
+const meta        = await userFiles.getMetadata('contract.pdf');
+const { signedUrl } = await userFiles.getSignedUrl('contract.pdf', 900);
+await userFiles.move('old.pdf', 'new.pdf');
+await userFiles.deleteFile('contract.pdf');
+await userFiles.deleteFolder('reports/');
+```
+
+---
+
+### Storage Stats
+
+```ts
+// Stats for this storage key
+const stats = await storage.getStats();
+// → { totalFiles, totalBytes, uploadCount, downloadCount, deleteCount }
+
+// Server info (no auth required)
+const info = await storage.info();
+// → { ok: true, storageRoot: '…' }
 ```
 
 ---
@@ -322,48 +719,267 @@ BigQuery-powered aggregations. No ETL, no pipelines — just query.
 
 ```ts
 const analytics = db.analytics('orders');
+```
+
+### Date Range (Time Scope)
+
+Almost every analytics method accepts an optional `dateRange` to restrict results to a time window. Both `start` and `end` are Unix timestamps **in milliseconds** — the server converts them to ISO strings internally. Both fields are optional; omit either for an open-ended range.
+
+```ts
+interface DateRange {
+  start?: number;  // Unix ms — inclusive lower bound
+  end?:   number;  // Unix ms — inclusive upper bound
+}
+```
+
+**Granularity options** (for time series methods):
+
+| Value | Buckets results by |
+|---|---|
+| `'hour'` | Each hour |
+| `'day'` | Each calendar day |
+| `'week'` | Each week |
+| `'month'` | Each month |
+| `'year'` | Each year |
+
+**Aggregation options** (for numeric field methods):
+
+| Value | Meaning |
+|---|---|
+| `'sum'` | Total |
+| `'avg'` | Average |
+| `'min'` | Minimum |
+| `'max'` | Maximum |
+| `'count'` | Record count |
+
+---
 
-// Total record count
+### Count
+
+```ts
+// All-time total
 const { count } = await analytics.count();
 
-// How many records have each value of `status`
-const dist = await analytics.distribution({ field: 'status' });
+// Within a time window
+const { count: lastWeek } = await analytics.count({
+  dateRange: {
+    start: Date.now() - 7 * 24 * 60 * 60 * 1000,
+    end:   Date.now(),
+  },
+});
+```
 
-// Sum of `amount`, grouped by `region`
-const sums = await analytics.sum({ field: 'amount', groupBy: 'region' });
+---
 
-// Records over time
-const daily = await analytics.timeSeries({ granularity: 'day' });
+### Distribution
 
-// How `revenue` changes over time
-const trend = await analytics.fieldTimeSeries({ field: 'revenue', aggregation: 'sum' });
+How many records have each value of a field.
 
-// Top 10 countries by record count
-const top10 = await analytics.topN({ field: 'country', n: 10 });
+```ts
+const dist = await analytics.distribution({
+  field:     'status',
+  limit:     10,
+  order:     'desc', // 'asc' | 'desc'
+  dateRange: { start: new Date('2025-01-01').getTime() },
+});
+// → [{ value: 'published', count: 320 }, { value: 'draft', count: 80 }, …]
+```
 
-// Min / max / avg / sum / stddev for a numeric field
-const stats = await analytics.stats({ field: 'price' });
+---
+
+### Sum
+
+Sum a numeric field, optionally grouped by another field.
+
+```ts
+// Total revenue
+const [{ sum: totalRevenue }] = await analytics.sum({ field: 'amount' });
+
+// Revenue by region, last quarter
+const sums = await analytics.sum({
+  field:     'amount',
+  groupBy:   'region',
+  limit:     20,
+  dateRange: {
+    start: new Date('2025-01-01').getTime(),
+    end:   new Date('2025-03-31').getTime(),
+  },
+});
+// → [{ group: 'Europe', sum: 18200 }, { group: 'Americas', sum: 29400 }, …]
+```
+
+---
+
+### Time Series
+
+Count of records over time — useful for activity graphs.
+
+```ts
+// Daily record counts, last 30 days
+const daily = await analytics.timeSeries({
+  granularity: 'day',
+  dateRange: {
+    start: Date.now() - 30 * 24 * 60 * 60 * 1000,
+    end:   Date.now(),
+  },
+});
+// → [{ date: '2025-03-01', count: 42 }, { date: '2025-03-02', count: 55 }, …]
+
+// Monthly, all time
+const monthly = await analytics.timeSeries({ granularity: 'month' });
+```
+
+---
+
+### Field Time Series
+
+Aggregate a numeric field over time — useful for revenue, score, or usage trends.
+
+```ts
+// Daily sum of revenue, last 90 days
+const revTrend = await analytics.fieldTimeSeries({
+  field:       'amount',
+  aggregation: 'sum',
+  granularity: 'day',
+  dateRange: {
+    start: Date.now() - 90 * 24 * 60 * 60 * 1000,
+    end:   Date.now(),
+  },
+});
+// → [{ date: '2025-01-01', value: 4820.5 }, …]
+
+// Monthly average order value
+const avgTrend = await analytics.fieldTimeSeries({
+  field:       'amount',
+  aggregation: 'avg',
+  granularity: 'month',
+});
+```
+
+---
+
+### Top N
+
+Most frequent values for a field by record count.
+
+```ts
+// Top 10 countries
+const top10 = await analytics.topN({
+  field:      'countryCode',
+  n:          10,
+  labelField: 'countryName', // optional — include a human-readable label alongside the value
+  order:      'desc',
+  dateRange:  { start: new Date('2025-01-01').getTime() },
+});
+// → [{ value: 'US', label: 'United States', count: 420 }, …]
+```
 
-// Multiple aggregations in one round-trip
+---
+
+### Stats
+
+Statistical summary for a numeric field.
+
+```ts
+const priceStats = await analytics.stats({
+  field:     'price',
+  dateRange: { start: new Date('2025-01-01').getTime() },
+});
+// → { min, max, avg, sum, count, stddev }
+```
+
+---
+
+### Records via BigQuery
+
+Fetch filtered records through the BigQuery engine instead of Firestore. Useful for large result sets or complex server-side filtering.
+
+```ts
+const records = await analytics.records<Order>({
+  filters: [
+    { field: 'status',  op: '==',       value: 'paid' },
+    { field: 'amount',  op: '>=',       value: 100 },
+    { field: 'country', op: 'CONTAINS', value: 'US' },
+  ],
+  selectFields: ['id', 'amount', 'country', 'createdAt'], // optional projection
+  orderBy:      'createdAt',
+  order:        'desc',
+  limit:        1000,
+  offset:       0,
+  dateRange: {
+    start: new Date('2025-01-01').getTime(),
+    end:   new Date('2025-03-31').getTime(),
+  },
+});
+```
+
+Analytics filter operators: `==` `!=` `>` `<` `>=` `<=` `CONTAINS`
+
+---
+
+### Multi-Metric
+
+Compute multiple aggregations in a single round-trip — perfect for dashboards.
+
+```ts
 const dashboard = await analytics.multiMetric({
   metrics: [
     { field: 'amount',   name: 'totalRevenue', aggregation: 'sum' },
     { field: 'amount',   name: 'avgOrder',     aggregation: 'avg' },
+    { field: 'amount',   name: 'maxOrder',     aggregation: 'max' },
     { field: 'recordId', name: 'orderCount',   aggregation: 'count' },
   ],
+  dateRange: { start: Date.now() - 30 * 24 * 60 * 60 * 1000 },
 });
-// → { totalRevenue: 48200, avgOrder: 96.4, orderCount: 500 }
+// → { totalRevenue: 48200, avgOrder: 96.4, maxOrder: 999, orderCount: 500 }
+```
+
+---
+
+### Storage Stats (Analytics)
+
+Record count and byte statistics for the bucket.
 
-// Compare a metric across buckets
+```ts
+const storageInfo = await analytics.storageStats({
+  dateRange: { start: new Date('2025-01-01').getTime() },
+});
+// → { totalRecords, totalBytes, avgBytes, minBytes, maxBytes }
+```
+
+---
+
+### Cross-Bucket
+
+Compare the same metric across multiple buckets in a single query. Your key must have read access to all listed buckets. System buckets are blocked.
+
+```ts
 const compare = await analytics.crossBucket({
   bucketKeys:  ['orders-2024', 'orders-2025'],
   field:       'amount',
   aggregation: 'sum',
+  dateRange:   { start: new Date('2025-01-01').getTime() },
 });
+// → [{ bucket: 'orders-2024', value: 38200 }, { bucket: 'orders-2025', value: 52100 }]
+```
+
+---
+
+### Raw Query
+
+Escape hatch for query types not covered by the typed helpers.
 
-// All queries accept an optional date range
-const { count } = await analytics.count({
-  dateRange: { start: Date.now() - 7 * 24 * 60 * 60 * 1000, end: Date.now() },
+```ts
+import type { AnalyticsQuery, AnalyticsResult } from 'hydrousdb';
+
+const result = await analytics.query<MyResultType>({
+  queryType:   'distribution',
+  field:       'category',
+  granularity: 'month',
+  filters:     [{ field: 'active', op: '==', value: true }],
+  dateRange:   { start: Date.now() - 30 * 24 * 60 * 60 * 1000 },
+  limit:       50,
+  order:       'desc',
 });
 ```
 
@@ -372,37 +988,52 @@ const { count } = await analytics.count({
 ## Error Handling
 
 ```ts
-import { HydrousError, NetworkError } from 'hydrousdb';
+import {
+  HydrousError,
+  AuthError,
+  RecordError,
+  StorageError,
+  AnalyticsError,
+  ValidationError,
+  NetworkError,
+} from 'hydrousdb';
 
 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 AuthError) {
+    console.log(err.code);      // 'INVALID_CREDENTIALS'
+    console.log(err.status);    // 401
+    console.log(err.message);   // human-readable
+    console.log(err.requestId); // for support
+  }
+
+  if (err instanceof ValidationError) {
+    console.log(err.details);   // string[] of specific validation failures
   }
+
   if (err instanceof NetworkError) {
     console.log('No internet or server unreachable');
+    console.log(err.cause);     // original error
   }
 }
 ```
 
 | 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 |
+| `HydrousError` | Base class — all SDK errors extend this. Has `code`, `status`, `requestId`, `details`. |
+| `AuthError` | Login failures, invalid/expired sessions, permission denied |
+| `RecordError` | Record not found, write validation failures |
 | `StorageError` | Upload/download failures, file not found |
 | `AnalyticsError` | Invalid query, bucket not found |
-| `NetworkError` | No network, request timed out |
-| `ValidationError` | Bad input caught client-side before the request is sent |
+| `ValidationError` | Bad input caught client-side before the request is sent. Has `details: string[]`. |
+| `NetworkError` | No network, server unreachable, request timed out. Has `cause`. |
 
 ---
 
 ## TypeScript
 
-The SDK is written in TypeScript. Type your records for full autocomplete:
+The SDK is written in TypeScript. Type your records for full autocomplete and safety:
 
 ```ts
 interface Order {
@@ -421,6 +1052,27 @@ const order = await orders.create({
   items:      [{ sku: 'SHOE-42', qty: 1 }],
 });
 // order.status → 'pending' | 'paid' | 'refunded'  ✓
+// order.id, order.createdAt, order.updatedAt are automatically added ✓
+
+const result = await orders.query({
+  filters: [{ field: 'status', op: '==', value: 'paid' }],
+});
+// result.records → (Order & RecordResult)[]  ✓
+```
+
+Key exported types:
+
+```ts
+import type {
+  HydrousConfig,
+  RecordData, RecordResult, QueryOptions, QueryFilter, QueryResult,
+  DateRange, Granularity, Aggregation, SortOrder,
+  AnalyticsQuery, AnalyticsResult, AnalyticsFilter,
+  UserRecord, AuthResult, Session,
+  UploadOptions, UploadResult,
+  ListOptions, ListResult, FileMetadata, SignedUrlResult,
+  StorageStats,
+} from 'hydrousdb';
 ```
 
 ---
@@ -428,25 +1080,34 @@ const order = await orders.create({
 ## Security
 
 - **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.
+- **Never expose keys in the browser.** For client-side apps, proxy all SDK calls through your own backend.
+- **Keys travel in headers only** — the SDK enforces this. They never appear in URLs, query strings, access logs, or browser history.
 - **Files are private by default.** `isPublic` defaults to `false`. Use `getSignedUrl()` for temporary external sharing.
-- **Use scoped storage** (`storage.scope('prefix/')`) to isolate files per user.
+- **Use scoped storage** (`storage.scope('prefix/')`) to isolate files per user and prevent path-traversal bugs.
 
 ---
 
-## Framework examples
+## Framework Examples
 
 **Next.js (App Router)**
 ```ts
 // lib/db.ts
 import { createClient } from 'hydrousdb';
-export const db = createClient({ … });
+export const db = createClient({
+  authKey:           process.env.HYDROUS_AUTH_KEY!,
+  bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+  storageKeys:       { main: process.env.HYDROUS_STORAGE_KEY! },
+});
 
 // app/api/posts/route.ts
 import { db } from '@/lib/db';
 export async function GET() {
-  const { records } = await db.records('posts').query({ limit: 10 });
+  const { records } = await db.records('posts').query({
+    filters:  [{ field: 'status', op: '==', value: 'published' }],
+    orderBy:  'createdAt',
+    order:    'desc',
+    limit:    10,
+  });
   return Response.json(records);
 }
 ```
@@ -462,14 +1123,22 @@ const data = await res.json();
 ```ts
 // composables/useDb.ts
 import { createClient } from 'hydrousdb';
-export const db = createClient({ … });
+export const db = createClient({
+  authKey:           import.meta.env.VITE_HYDROUS_AUTH_KEY,
+  bucketSecurityKey: import.meta.env.VITE_HYDROUS_BUCKET_KEY,
+  storageKeys:       { main: import.meta.env.VITE_HYDROUS_STORAGE_KEY },
+});
 ```
 
 **React Native**
 ```ts
 import { createClient } from 'hydrousdb';
 // Works out of the box — uses the global fetch available in React Native
-const db = createClient({ … });
+const db = createClient({
+  authKey:           HYDROUS_AUTH_KEY,
+  bucketSecurityKey: HYDROUS_BUCKET_KEY,
+  storageKeys:       { main: HYDROUS_STORAGE_KEY },
+});
 ```
 
 ---
@@ -478,79 +1147,121 @@ const db = createClient({ … });
 
 ### `createClient(config)`
 
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `authKey` | `string` | ✓ | `hk_auth_…` — for auth routes |
+| `bucketSecurityKey` | `string` | ✓ | `hk_bucket_…` — for records & analytics |
+| `storageKeys` | `{ [name]: string }` | ✓ | One or more `ssk_…` keys for file storage |
+| `baseUrl` | `string` | — | Override the API endpoint (no trailing slash) |
+
+---
+
+### `db.records<T>(bucket)` — all methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `create(data, opts?)` | `T & RecordResult` | Create a record. `opts.queryableFields` enables filtering. `opts.customRecordId` enables upsert. |
+| `get(id)` | `T & RecordResult` | Fetch a record by ID. |
+| `patch(id, data, opts?)` | `{ id, updatedAt? }` | Partial update. `opts.merge` for deep merge. `opts.trackHistory` to save a version. |
+| `delete(id)` | `void` | Permanently delete a record. |
+| `exists(id)` | `boolean` | Lightweight existence check (HEAD request). |
+| `query(opts?)` | `QueryResult<T>` | Filter, sort, paginate. Supports `dateRange`. |
+| `getAll(opts?)` | `(T & RecordResult)[]` | Fetch all records (no filter support — use `query` for filters). |
+| `batchCreate(items, opts?)` | `{ results, errors, successful, failed }` | Up to 500 records at once. |
+| `batchUpdate(updates, userEmail?)` | `{ successful, failed }` | Up to 500 records at once. |
+| `batchDelete(ids, userEmail?)` | `{ successful, failed }` | Up to 500 records at once. |
+| `getHistory(id)` | `RecordHistoryEntry[]` | List all saved versions. |
+| `getVersion(id, generation)` | `T & RecordResult` | Fetch a specific past version. |
+
+**`QueryOptions` fields:**
+
 | Field | Type | Description |
 |---|---|---|
-| `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) |
+| `filters` | `QueryFilter[]` | Array of `{ field, op, value }` |
+| `fields` | `string` | Comma-separated list of fields to return |
+| `orderBy` | `string` | Field to sort by |
+| `order` | `'asc' \| 'desc'` | Sort direction |
+| `limit` | `number` | Max records to return |
+| `offset` | `number` | Skip N records |
+| `startAfter` | `string` | Cursor from `nextCursor` for next-page pagination |
+| `startAt` | `string` | Cursor — include the record at this cursor |
+| `endAt` | `string` | Cursor — stop at this cursor |
+| `dateRange` | `DateRange` | `{ start?, end? }` in Unix ms |
+| `timeScope` | `string` | Prefix-based time filter: `_day_YYMMDD`, `_month_YYMM`, or `_year_YY` |
 
-### `db.records(bucket)` — key methods
+---
 
-| Method | What it does |
-|---|---|
-| `create(data, opts?)` | Create a record. Use `opts.queryableFields` to enable filtering. |
-| `get(id)` | Fetch by ID. |
-| `patch(id, data)` | Partial update — only the fields you pass are changed. |
-| `delete(id)` | Permanent delete. |
-| `query(opts?)` | Filter, sort, paginate. |
-| `batchCreate(items, opts?)` | Up to 500 at once. |
-| `batchUpdate(updates)` | Up to 500 at once. |
-| `batchDelete(ids)` | Up to 500 at once. |
-| `getHistory(id)` | Full version list. |
-| `getVersion(id, generation)` | Read a past version. |
-| `exists(id)` | Lightweight existence check (HEAD request). |
-
-### `db.auth()` — key methods
-
-| Method | What it does |
+### `db.auth()` — all methods
+
+| Method | Description |
 |---|---|
-| `signup(opts)` | Register + create session. |
+| `signup(opts)` | Register + create session. Extra fields on `opts` are stored on the user. |
 | `login(opts)` | Authenticate + create session. |
-| `logout({ sessionId })` | Revoke session(s). |
-| `validateSession(sessionId)` | Check if a session is active. |
+| `logout({ sessionId, allDevices? })` | Revoke one session or all sessions. |
+| `validateSession(sessionId)` | Check if a session is active; returns current user. |
 | `refreshSession(refreshToken)` | Get a new session from a refresh token. |
 | `getUser(userId)` | Fetch a user by ID. |
 | `updateUser(opts)` | Update profile fields. |
-| `changePassword(opts)` | Authenticated password change. |
-| `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). |
+| `changePassword(opts)` | Authenticated password change (requires current password). |
+| `requestPasswordReset(email)` | Send reset email (always succeeds to prevent enumeration). |
+| `confirmPasswordReset(token, newPw)` | Apply new password from reset token. |
+| `requestEmailVerification(userId)` | Send verification email. |
+| `confirmEmailVerification(token)` | Mark email verified from token. |
+| `getUser(userId)` | Fetch a user by ID. |
+| `listUsers(opts)` | Paginated user list. Admin only. |
+| `lockAccount(opts)` | Lock a user account. Admin only. |
+| `unlockAccount(sessionId, userId)` | Unlock a user account. Admin only. |
+| `hardDeleteUser(sessionId, userId)` | Permanent delete. Admin only. |
+| `bulkDeleteUsers(opts)` | Delete many users at once (soft or hard). Admin only. |
+
+---
 
-### `db.storage(keyName)` — key methods
+### `db.storage(keyName)` — all methods
 
-| Method | What it does |
+| 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 |
-|---|---|
-| `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. |
+| `getUploadUrl(opts)` | Step 1 of signed-URL upload — get a GCS PUT URL. |
+| `uploadToSignedUrl(url, data, mime, onProgress?)` | Step 2 — upload directly to GCS (supports progress in browsers). |
+| `confirmUpload(opts)` | Step 3 — register metadata server-side. |
+| `getBatchUploadUrls(files)` | Get signed URLs for up to 50 files at once. |
+| `batchConfirmUploads(items)` | Confirm multiple direct uploads at once. |
+| `download(path)` | Download a private file as `ArrayBuffer`. |
+| `batchDownload(paths, concurrency?)` | Download up to 20 files at once (base64 content). |
+| `list(opts?)` | List files and folders. Supports `prefix`, `limit`, `cursor`, `recursive`. |
+| `getMetadata(path)` | File size, MIME type, visibility, URLs. |
+| `getSignedUrl(path, expiresIn?)` | Time-limited share link (default 3600 s). |
+| `setVisibility(path, isPublic)` | Toggle a file between public and private. |
+| `createFolder(path)` | Create an explicit folder marker. |
+| `move(from, to)` | Move (rename) a file. |
+| `copy(from, to)` | Copy a file to a new path. |
+| `deleteFile(path)` | Permanently delete a file. |
+| `deleteFolder(path)` | Recursively delete a folder and all its contents. |
+| `getStats()` | Upload/download/delete counts and total bytes. |
+| `info()` | Server info — no auth required. |
+| `scope(prefix)` | Get a `ScopedStorage` that auto-prefixes all paths. |
+
+`ScopedStorage` exposes every method above (except `info`) plus `scope(subPrefix)` for nesting deeper.
+
+---
+
+### `db.analytics(bucket)` — all methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `count(opts?)` | `{ count }` | Total record count, optionally within a `dateRange`. |
+| `distribution(opts)` | `DistributionRow[]` | Per-value counts for a field. |
+| `sum(opts)` | `SumRow[]` | Sum a numeric field, optional `groupBy`. |
+| `timeSeries(opts?)` | `TimeSeriesRow[]` | Record counts bucketed by `granularity`. |
+| `fieldTimeSeries(opts)` | `FieldTimeSeriesRow[]` | Numeric field aggregated over time. |
+| `topN(opts)` | `TopNRow[]` | Most frequent field values. |
+| `stats(opts)` | `FieldStats` | min / max / avg / sum / count / stddev. |
+| `records(opts?)` | `(T & RecordResult)[]` | Filtered records via BigQuery (good for large sets). |
+| `multiMetric(opts)` | `MultiMetricResult` | Multiple aggregations in one request. |
+| `storageStats(opts?)` | `StorageStatsResult` | Record count and byte stats for the bucket. |
+| `crossBucket(opts)` | `CrossBucketRow[]` | Compare a metric across multiple buckets. |
+| `query(query)` | `AnalyticsResult<T>` | Raw escape hatch for any `AnalyticsQuery`. |
 
 ---