hydrousdb 3.5.0 → 3.5.2

package/README.md

@@ -1,6 +1,6 @@
 # HydrousDB JS/TS SDK
 
-**A database that doesn't choke on big JSON.** Store, query, and analyse massive records — with auth and file storage built in.
+**A database that doesn't choke on big JSON.** Store, query, and analyse massive records — with auth, Google sign-in, and file storage built in.
 
 ```bash
 npm install hydrousdb
@@ -10,17 +10,75 @@ 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)
+  - [Date Range Queries](#date-range-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)
+  - [Google Sign-In](#google-sign-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 +90,295 @@ 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
 });
+```
 
-// Next page
+**Supported filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`
+
+You can combine multiple filters. The first equality filter (`==`) drives the GCS index — additional filters are applied in-memory after hydration. This means you get fast indexed lookups for equality filters and flexible in-memory filtering for everything else.
+
+**Filter combinations:**
+```ts
+// Equality only — fast index path
+await posts.query({ filters: [{ field: 'status', op: '==', value: 'published' }] });
+
+// Equality + range — index on status, range applied in-memory
+await posts.query({ filters: [
+  { field: 'status', op: '==', value: 'published' },
+  { field: 'views',  op: '>=', value: 100 },
+]});
+
+// Equality + contains — index on status, contains applied in-memory
+await posts.query({ filters: [
+  { field: 'status', op: '==',       value: 'published' },
+  { field: 'title',  op: 'contains', value: 'hello' },
+]});
+
+// Multiple equality — first drives index, rest applied in-memory
+await posts.query({ filters: [
+  { field: 'status',   op: '==', value: 'published' },
+  { field: 'category', op: '==', value: 'tech' },
+]});
+```
+
+---
+
+### Time Scope on Queries
+
+Pass `timeScope` to restrict records to a specific **day, month, or year**. 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,
+});
+
+// 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 — this is the recommended pattern for large buckets
+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
+### Date Range Queries
 
-Avoid race conditions with server-side operations inside `patch()`:
+Pass `startDate` and/or `endDate` (ISO date strings) to walk records within a calendar range. Both fields are optional — omit either for an open-ended range.
+
+```ts
+// Records from a specific month
+const { records } = await posts.query({
+  startDate: '2026-04-01',
+  endDate:   '2026-04-30',
+});
+
+// Records since a specific date (no end bound)
+const { records: recent } = await posts.query({
+  startDate: '2026-01-01',
+  orderBy:   'createdAt',
+  order:     'desc',
+});
+
+// Walk a specific year using the year shorthand
+const { records: yearRecords } = await posts.query({
+  year:  '26',        // two-digit year
+  order: 'desc',
+  limit: 100,
+});
+
+// Combine with filters
+const { records: paidOrders } = await orders.query({
+  startDate: '2026-04-01',
+  endDate:   '2026-04-30',
+  filters:   [{ field: 'status', op: '==', value: 'paid' }],
+});
+
+// Sort by any field
+const { records: byPrice } = await rooms.query({
+  timeScope: '_month_2604',
+  filters:   [{ field: 'status', op: '==', value: 'available' }],
+  sortBy:    'pricePerNight',
+  order:     'asc',
+});
+```
+
+---
+
+### Pagination
+
+`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
+  oldTag:   { __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
+  score:    { __op: 'setIf', value: 99, cond: { op: '>=', value: 50 } }, // conditional set
 } 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,15 +387,39 @@ 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.
+A complete user system — signup, login, Google sign-in, sessions, password reset, email verification, and admin controls.
 
 ```ts
 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 +436,190 @@ 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.
+
+| Token | Lifetime |
+|---|---|
+| `sessionId` | 24 hours |
+| `refreshToken` | 30 days |
+
+---
+
+### Google Sign-In
+
+Allow users to sign in or create an account with one tap — no password required.
+
+The flow is the same regardless of platform: get a Google ID token on the client, pass it to `continueWithGoogle`. The server verifies the token and returns a session identical in shape to `login()` and `signup()`.
+
+**Web (Google Identity Services)**
+
+```html
+<!-- Add to your HTML <head> -->
+<script src="https://accounts.google.com/gsi/client" async defer></script>
+```
+
+```ts
+google.accounts.id.initialize({
+  client_id: 'YOUR_GOOGLE_CLIENT_ID',  // from Google Cloud Console
+  callback: async ({ credential }) => {
+    const { user, session, isNew } = await db.auth().continueWithGoogle({
+      idToken: credential,
+    });
+    if (isNew) router.push('/onboarding');  // brand-new account
+    else       router.push('/dashboard');   // returning user
+  },
+});
+
+// Render the button anywhere in your page
+google.accounts.id.renderButton(
+  document.getElementById('google-btn'),
+  { theme: 'outline', size: 'large', text: 'continue_with' },
+);
+```
+
+**React Native**
+
+```ts
+import { GoogleSignin } from '@react-native-google-signin/google-signin';
+
+GoogleSignin.configure({ webClientId: 'YOUR_GOOGLE_CLIENT_ID' });
+
+const { idToken } = await GoogleSignin.signIn();
+const { user, session, isNew } = await db.auth().continueWithGoogle({ idToken });
+if (isNew) navigation.navigate('Onboarding');
+```
+
+**Flutter**
+
+```dart
+final googleUser = await GoogleSignIn().signIn();
+final auth       = await googleUser!.authentication;
+// Send auth.idToken to your backend which calls the HydrousDB SDK
+```
+
+**What `isNew` tells you**
+
+```ts
+const { user, session, isNew } = await auth.continueWithGoogle({ idToken });
+
+if (isNew) {
+  // Account was just created — show onboarding, collect extra info, etc.
+  console.log('Welcome!', user.fullName);
+} else {
+  // Returning user — go straight to the app
+  console.log('Welcome back!', user.email);
+}
+```
+
+**Link Google to an existing email/password account**
+
+```ts
+// User is signed in with email. They click "Connect Google" in settings.
+const { idToken } = await GoogleSignin.signIn();
+const updatedUser = await auth.linkGoogle({
+  sessionId: currentSession.sessionId,
+  idToken,
+});
+// After linking, the user can sign in with either method
+```
+
+**Unlink Google**
+
+```ts
+// Only works if the user has a password set — prevents account lockout
+await auth.unlinkGoogle({ sessionId: currentSession.sessionId });
+```
+
+**Setting a password on a Google-only account**
+
+```ts
+// Google users have no password by default.
+// Pass an empty string for currentPassword to set the first one.
+await auth.changePassword({
+  sessionId:       session.sessionId,
+  userId:          user.id,
+  currentPassword: '',         // empty — no password set yet
+  newPassword:     'newpassword123',
+});
+// After this, the user can sign in with email+password AND Google
+```
+
+The `UserRecord` for Google users includes:
+
+```ts
+interface UserRecord {
+  authProvider?: 'email' | 'google';  // 'google' for Google sign-in users
+  picture?:      string | null;        // profile photo URL from Google
+  googleId?:     string;               // stable Google identifier
+  // ... all other standard fields
+}
 ```
 
-Store `session.sessionId` and `session.refreshToken` in your app. Sessions expire after **24 hours**, refresh tokens after **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>;
+  authProvider?:  'email' | 'google';   // how the account was created
+  picture?:       string | null;         // Google profile photo URL
+  [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
+// Pass empty string for currentPassword to SET a first password (Google users)
 await auth.changePassword({
   sessionId:       session.sessionId,
   userId:          user.id,
@@ -204,8 +627,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 +636,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 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
 });
 
-// Lock / unlock an account
-await auth.lockAccount({ sessionId: adminSession.sessionId, userId: user.id });
+// 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 +675,226 @@ 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 all at once
+const { succeeded, failed } = await storage.batchConfirmUploads([
+  { path: 'docs/a.pdf', mimeType: 'application/pdf' },
+  { path: 'docs/b.pdf', mimeType: 'application/pdf' },
+]);
+```
+
+---
+
+### Download
 
-// Step 3 — confirm and get the final result
-const result = await storage.confirmUpload({ path, mimeType: 'video/mp4', isPublic: true });
+```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')
+}
 
-// List files
-const { files, folders, hasMore, nextCursor } = await storage.list({ prefix: 'avatars/' });
+for (const err of failed) {
+  console.error(err.path, err.error, err.code);
+}
+```
+
+---
+
+### 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)
+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/');
+```
+
+---
+
+### Scoped Storage
 
-Automatically prefix every path — useful for per-user file isolation:
+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 +905,265 @@ 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**. 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(),
+  },
+});
+```
+
+---
+
+### Distribution
+
+How many records have each value of a field.
+
+```ts
+const dist = await analytics.distribution({
+  field:     'status',
+  limit:     10,
+  order:     'desc',
+  dateRange: { start: new Date('2025-01-01').getTime() },
+});
+// → [{ value: 'published', count: 320 }, { value: 'draft', count: 80 }, …]
+```
+
+---
+
+### 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 }, …]
+```
+
+---
 
-// Sum of `amount`, grouped by `region`
-const sums = await analytics.sum({ field: 'amount', groupBy: 'region' });
+### Time Series
 
-// Records over time
-const daily = await analytics.timeSeries({ granularity: 'day' });
+Count of records over time — useful for activity graphs.
 
-// How `revenue` changes over time
-const trend = await analytics.fieldTimeSeries({ field: 'revenue', aggregation: 'sum' });
+```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 }, …]
 
-// Top 10 countries by record count
-const top10 = await analytics.topN({ field: 'country', n: 10 });
+// Monthly, all time
+const monthly = await analytics.timeSeries({ granularity: 'month' });
+```
+
+---
 
-// Min / max / avg / sum / stddev for a numeric field
-const stats = await analytics.stats({ field: 'price' });
+### Field Time Series
 
-// Multiple aggregations in one round-trip
+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(),
+  },
+});
+
+// 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
+const top10 = await analytics.topN({
+  field:      'countryCode',
+  n:          10,
+  labelField: 'countryName',
+  order:      'desc',
+  dateRange:  { start: new Date('2025-01-01').getTime() },
+});
+// → [{ value: 'US', label: 'United States', count: 420 }, …]
+```
+
+---
+
+### 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 the GCS index. 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'],
+  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, maxOrder: 999, orderCount: 500 }
+```
+
+---
+
+### Storage Stats (Analytics)
+
+Record count and byte statistics for the bucket.
+
+```ts
+const storageInfo = await analytics.storageStats({
+  dateRange: { start: new Date('2025-01-01').getTime() },
 });
-// → { totalRevenue: 48200, avgOrder: 96.4, orderCount: 500 }
+// → { totalRecords, totalBytes, avgBytes, minBytes, maxBytes }
+```
+
+---
+
+### Cross-Bucket
+
+Compare the same metric across multiple buckets in a single query.
 
-// Compare a metric across buckets
+```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 +1172,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 +1236,28 @@ 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,
+  GoogleSignInOptions, GoogleLinkOptions,
+  UploadOptions, UploadResult,
+  ListOptions, ListResult, FileMetadata, SignedUrlResult,
+  StorageStats,
+} from 'hydrousdb';
 ```
 
 ---
@@ -428,25 +1265,35 @@ 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.
+- **Google ID tokens are verified server-side** — the SDK never sends tokens to Google directly after initial sign-in.
 
 ---
 
-## 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 +1309,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 +1333,126 @@ 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`, `timeScope`, `startDate`, `endDate`, `year`, `sortBy`. |
+| `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 (server maps to `sortBy`) |
+| `sortBy` | `string` | Alias for `orderBy` — maps directly to `?sortBy=` |
+| `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` |
+| `startDate` | `string` | ISO date string e.g. `'2026-01-01'` — GCS day-range walk start |
+| `endDate` | `string` | ISO date string e.g. `'2026-12-31'` — GCS day-range walk end |
+| `year` | `string` | Two-digit year e.g. `'26'` — restricts monthly walk to that year |
 
-### `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. |
+| `continueWithGoogle({ idToken })` | Sign in or create account via Google ID token. Returns `isNew` flag. |
+| `linkGoogle({ sessionId, idToken })` | Add Google sign-in to an existing email/password account. |
+| `unlinkGoogle({ sessionId })` | Remove Google sign-in (only if a password is set). |
+| `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). |
+| `deleteUser(sessionId, userId)` | Soft-delete a user. |
+| `changePassword(opts)` | Authenticated password change. Pass `currentPassword: ''` to set first password on Google accounts. |
+| `requestPasswordReset(email)` | Send reset email (always succeeds to prevent enumeration). |
+| `confirmPasswordReset(token, newPw)` | Apply new password from reset token. |
+| `requestEmailVerification(userId)` | Send verification email. Not needed for Google users. |
+| `confirmEmailVerification(token)` | Mark email verified from token. |
+| `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. |
+
+---
+
+### `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`. |
 
 ---