hydrousdb 2.0.1 → 3.0.0

package/README.md

@@ -1,730 +1,1126 @@
-# Hydrous SDK
+# HydrousDB JavaScript / TypeScript SDK
 
-Official JavaScript / TypeScript SDK for the **Hydrous** platform.  
-One package — auth, records, analytics, and storage.
+<p align="center">
+  <strong>The official SDK for <a href="https://hydrousdb.com">HydrousDB</a> — records, auth, file storage, and analytics in one package.</strong>
+</p>
 
-```bash
-npm install hydrous
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/hydrousdb"><img src="https://img.shields.io/npm/v/hydrousdb.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/hydrousdb"><img src="https://img.shields.io/npm/dm/hydrousdb.svg" alt="npm downloads"></a>
+  <a href="https://github.com/hydrousdb/hydrousdb-js/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/hydrousdb.svg" alt="MIT License"></a>
+  <a href="https://hydrousdb.com"><img src="https://img.shields.io/badge/docs-hydrousdb.com-blue" alt="Documentation"></a>
+</p>
 
 ---
 
 ## Table of Contents
 
-1. [Quick Start](#1-quick-start)
-2. [Configuration](#2-configuration)
-3. [Auth](#3-auth)
-   - [Sign Up](#sign-up)
-   - [Sign In](#sign-in)
-   - [Sign Out](#sign-out)
-   - [Get Current User](#get-current-user)
-4. [Records](#4-records)
-   - [Insert](#insert)
-   - [Select / Query](#select--query)
-   - [Get by ID](#get-by-id)
-   - [Update](#update)
-   - [Delete](#delete)
-   - [Query Helpers](#query-helpers)
-5. [Analytics](#5-analytics)
-   - [Track an Event](#track-an-event)
-   - [Batch Track](#batch-track)
-   - [Query Events](#query-events)
-6. [Storage](#6-storage)
-   - [How Bucket Keys Work](#how-bucket-keys-work)
-   - [Upload a File](#upload-a-file)
-   - [Upload Raw Text / JSON](#upload-raw-text--json)
-   - [Track Upload Progress](#track-upload-progress)
-   - [Batch Upload](#batch-upload)
-   - [Download a File](#download-a-file)
-   - [Batch Download](#batch-download)
-   - [List Files & Folders](#list-files--folders)
-   - [File Metadata](#file-metadata)
-   - [Delete a File](#delete-a-file)
-   - [Delete a Folder](#delete-a-folder)
-   - [Create a Folder](#create-a-folder)
-   - [Move a File](#move-a-file)
-   - [Copy a File](#copy-a-file)
-   - [Signed URLs](#signed-urls)
-   - [Bucket Stats](#bucket-stats)
-7. [Error Handling](#7-error-handling)
-8. [TypeScript Types Reference](#8-typescript-types-reference)
+- [What is HydrousDB?](#what-is-hydrousdb)
+- [Quick Start (5 minutes)](#quick-start-5-minutes)
+  - [Step 1 — Create your account](#step-1--create-your-account)
+  - [Step 2 — Create your first bucket](#step-2--create-your-first-bucket)
+  - [Step 3 — Grab your Security Key](#step-3--grab-your-security-key)
+  - [Step 4 — Install the SDK](#step-4--install-the-sdk)
+  - [Step 5 — Your first record](#step-5--your-first-record)
+- [Records](#records)
+  - [Create](#create-a-record)
+  - [Read](#read-a-record)
+  - [Update](#update-a-record)
+  - [Delete](#delete-a-record)
+  - [Query](#query-records)
+  - [Batch Operations](#batch-operations)
+  - [Version History](#version-history)
+- [Authentication](#authentication)
+  - [Sign Up](#sign-up-users)
+  - [Log In / Log Out](#log-in--log-out)
+  - [Session Management](#session-management)
+  - [Password Reset](#password-reset-flow)
+  - [Email Verification](#email-verification)
+  - [Admin Operations](#admin-operations)
+- [File Storage](#file-storage)
+  - [Simple Upload](#simple-upload)
+  - [Large File Upload (with progress)](#large-file-upload-with-progress)
+  - [Download](#download-files)
+  - [List Files](#list-files)
+  - [Scoped Storage](#scoped-storage)
+  - [Share & Visibility](#share--visibility)
+  - [File Operations](#file-operations)
+- [Analytics](#analytics)
+  - [Count](#count)
+  - [Distribution](#distribution)
+  - [Time Series](#time-series)
+  - [Top N](#top-n)
+  - [Field Stats](#field-stats)
+  - [Multi-Metric Dashboard](#multi-metric-dashboard)
+  - [Cross-Bucket Comparison](#cross-bucket-comparison)
+- [TypeScript Support](#typescript-support)
+- [Error Handling](#error-handling)
+- [Security Best Practices](#security-best-practices)
+- [API Reference](#api-reference)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
-## 1. Quick Start
+## What is HydrousDB?
 
-```ts
-import { createClient } from 'hydrous';
+HydrousDB is a **backend-as-a-service** platform that gives your app a fully managed backend in minutes. Instead of spinning up servers, databases, and storage buckets yourself, you call an API.
 
-const hydrous = createClient({
-  url:    'https://api.yourapp.hydrous.app',
-  apiKey: 'hk_live_…',
-});
+| Feature | What it does |
+|---|---|
+| **Records** | Schemaless JSON document store. Create, read, update, delete and query records in named *buckets*. |
+| **Auth** | Full user authentication — signup, login, sessions, password reset, email verification, and admin controls. |
+| **Storage** | File uploads and downloads backed by Google Cloud Storage. Public and private files, signed share URLs. |
+| **Analytics** | BigQuery-powered aggregations — counts, distributions, time series, top-N, multi-metric dashboards, and cross-bucket comparisons. |
 
-// Upload a file
-const { data, error } = await hydrous.storage.upload(
-  'ssk_my_bucket_key',       // ← bucket key always comes first
-  file,
-  {
-    path:       'avatars/alice.jpg',
-    onProgress: (p) => console.log(`${p.percent}%`),
-  }
-);
-```
+Everything is organised around two concepts:
+
+- **Security Key (`sk_...`)** — your master credential. Authenticate all API calls. Keep it secret.
+- **Bucket Key** — just the name of your bucket (e.g. `"blog-posts"`, `"app-users"`). Not a secret.
 
 ---
 
-## 2. Configuration
+## Quick Start (5 minutes)
 
-```ts
-import { HydrousClient } from 'hydrous';
+### Step 1 — Create your account
 
-const hydrous = new HydrousClient({
-  url:     'https://api.yourapp.hydrous.app', // your project URL
-  apiKey:  'hk_live_…',                       // your project API key
-  timeout: 30_000,                             // optional — ms (default 30s)
-});
-```
+Go to **[https://hydrousdb.com](https://hydrousdb.com)** and sign up for a free account.
 
-| Option    | Type     | Required | Description                          |
-|-----------|----------|----------|--------------------------------------|
-| `url`     | `string` | ✅       | Your Hydrous project base URL         |
-| `apiKey`  | `string` | ✅       | Your project API key                  |
-| `timeout` | `number` | ✗        | Request timeout in ms (default 30000) |
+### Step 2 — Create your first bucket
 
----
+1. Log in to your dashboard at **[https://hydrousdb.com/dashboard](https://hydrousdb.com/dashboard)**.
+2. Click **"New Bucket"**.
+3. Give it a name — use lowercase letters, numbers, hyphens, or underscores (e.g. `my-first-bucket`).
+4. Click **"Create"**.
 
-## 3. Auth
+> 💡 **What is a bucket?** A bucket is a named collection of JSON records — similar to a table in SQL or a collection in MongoDB.
 
-### Sign Up
+### Step 3 — Grab your Security Key
 
-```ts
-const { data, error } = await hydrous.auth.signUp({
-  email:    'user@example.com',
-  password: 'supersecret',
-  metadata: { plan: 'pro' },   // optional
-});
+1. In the dashboard, go to **Settings → API Keys**.
+2. Click **"Generate Security Key"**.
+3. Copy the key — it looks like `sk_live_xxxxxxxxxxxxxxxxxxxx`.
 
-if (data) {
-  console.log('New user:', data.user.id);
-  console.log('Access token:', data.accessToken);
-}
+> ⚠️ **Your Security Key is your most important credential.** Treat it like a password. Never commit it to Git. Use environment variables.
+
+### Step 4 — Install the SDK
+
+```bash
+npm install hydrousdb
+# or
+yarn add hydrousdb
+# or
+pnpm add hydrousdb
 ```
 
-### Sign In
+**Requirements:** Node.js 18+ (uses the native `fetch` API).
 
-```ts
-const { data, error } = await hydrous.auth.signIn({
-  email:    'user@example.com',
-  password: 'supersecret',
-});
+### Step 5 — Your first record
 
-if (data) {
-  console.log('Welcome back,', data.user.email);
-}
-```
+```typescript
+import { createClient } from 'hydrousdb';
 
-### Sign Out
+// Create the client once — reuse it everywhere
+const db = createClient({
+  securityKey: process.env.HYDROUS_SECURITY_KEY!, // from Step 3
+});
 
-```ts
-await hydrous.auth.signOut();
-```
+// Write a record to your bucket
+const post = await db.records('my-first-bucket').create({
+  title:     'Hello, HydrousDB!',
+  body:      'My first record.',
+  published: false,
+});
 
-### Get Current User
+console.log(post.id);        // "rec_a1b2c3d4"
+console.log(post.createdAt); // 1717200000000
 
-```ts
-const { data: user } = await hydrous.auth.getUser();
-console.log(user?.email);
-```
+// Read it back
+const fetched = await db.records('my-first-bucket').get(post.id);
+console.log(fetched.title);  // "Hello, HydrousDB!"
 
-### Refresh Session
+// Update it
+const updated = await db.records('my-first-bucket').patch(post.id, { published: true });
 
-```ts
-const { data: session } = await hydrous.auth.refreshSession();
+// Delete it
+await db.records('my-first-bucket').delete(post.id);
 ```
 
+🎉 **That's it!** You're live with zero configuration beyond your Security Key.
+
 ---
 
-## 4. Records
+## Records
+
+Records are JSON objects stored in named buckets. Every record automatically gets:
+- `id` — unique record identifier (e.g. `"rec_a1b2c3d4"`)
+- `createdAt` — Unix timestamp in milliseconds
+- `updatedAt` — Unix timestamp in milliseconds (updated on every write)
 
-### Insert
+### Create a Record
 
-Single record:
+```typescript
+const products = db.records('products');
 
-```ts
-const { data, error } = await hydrous.records.insert('users', {
-  name:  'Alice',
-  email: 'alice@example.com',
-  role:  'admin',
+const product = await products.create({
+  name:     'Wireless Headphones',
+  price:    79.99,
+  inStock:  true,
+  tags:     ['audio', 'wireless'],
 });
+
+// product.id, product.createdAt, product.updatedAt are added automatically
 ```
 
-Bulk insert (array):
+### Read a Record
 
-```ts
-const { data } = await hydrous.records.insert('products', [
-  { name: 'Widget A', price: 9.99 },
-  { name: 'Widget B', price: 14.99 },
-]);
-console.log(`Inserted ${data.length} products`);
+```typescript
+// Get by ID
+const product = await products.get('rec_abc123');
+
+// product is null-safe: throws HydrousError with code RECORD_NOT_FOUND if missing
 ```
 
-### Select / Query
+### Update a Record
 
-```ts
-const { data, count } = await hydrous.records.select('users', {
-  where:   { field: 'role', operator: 'eq', value: 'admin' },
-  orderBy: { field: 'createdAt', direction: 'desc' },
-  limit:   20,
-  offset:  0,
-  select:  ['id', 'name', 'email'],   // optional column projection
+```typescript
+// Patch (merge) — only the listed fields are changed
+const updated = await products.patch('rec_abc123', {
+  price:   69.99,
+  inStock: false,
+});
+
+// Set (full replace) — the entire record is replaced
+const replaced = await products.set('rec_abc123', {
+  name:    'Wireless Headphones v2',
+  price:   89.99,
+  inStock: true,
+  tags:    ['audio', 'wireless', 'premium'],
 });
 ```
 
-Multiple filters:
+### Delete a Record
+
+```typescript
+await products.delete('rec_abc123');
+```
 
-```ts
-import { eq, gt, inArray } from 'hydrous';
+### Query Records
 
-const { data } = await hydrous.records.select('orders', {
-  where: [
-    eq('status',  'shipped'),
-    gt('total',   100),
-    inArray('tag', ['vip', 'priority']),
+```typescript
+// Get all records (up to 100 by default)
+const { records } = await products.query();
+
+// With filters
+const { records: affordableStock } = await products.query({
+  filters: [
+    { field: 'inStock', op: '==', value: true  },
+    { field: 'price',   op: '<',  value: 100   },
   ],
 });
-```
 
-### Get by ID
+// Sort and paginate
+const { records, hasMore, nextCursor } = await products.query({
+  orderBy: 'price',
+  order:   'asc',
+  limit:   20,
+});
 
-```ts
-const { data: user } = await hydrous.records.get('users', 'user_abc123');
-```
+// Next page
+if (hasMore) {
+  const page2 = await products.query({
+    orderBy:    'price',
+    order:      'asc',
+    limit:      20,
+    startAfter: nextCursor,
+  });
+}
 
-### Update
+// Select only specific fields
+const { records: lightRecords } = await products.query({
+  fields: 'name,price,inStock',
+});
 
-```ts
-const { data } = await hydrous.records.update('users', 'user_abc123', {
-  name: 'Alice Smith',
+// Filter by date range
+const { records: recent } = await products.query({
+  dateRange: {
+    start: Date.now() - 7 * 24 * 60 * 60 * 1000, // 7 days ago
+    end:   Date.now(),
+  },
 });
 ```
 
-### Delete
+**Available filter operators:**
+
+| Operator | Meaning |
+|---|---|
+| `==` | Equal |
+| `!=` | Not equal |
+| `>` | Greater than |
+| `<` | Less than |
+| `>=` | Greater than or equal |
+| `<=` | Less than or equal |
+| `CONTAINS` | String contains (case-sensitive) |
+
+### Batch Operations
+
+```typescript
+// Create multiple records at once
+const created = await products.batchCreate([
+  { name: 'Item A', price: 10.00, inStock: true },
+  { name: 'Item B', price: 20.00, inStock: false },
+  { name: 'Item C', price: 30.00, inStock: true },
+]);
+// → [{ id: 'rec_1', ... }, { id: 'rec_2', ... }, { id: 'rec_3', ... }]
+
+// Count records
+const total = await products.count();
+const inStock = await products.count([{ field: 'inStock', op: '==', value: true }]);
 
-```ts
-const { error } = await hydrous.records.delete('users', 'user_abc123');
+// Delete multiple records
+const { deleted, failed } = await products.batchDelete(['rec_1', 'rec_2', 'rec_3']);
 ```
 
-### Query Helpers
+### Version History
+
+Every write to a record creates a new version stored in GCS, so you can travel back in time.
 
-| Helper              | SQL equivalent          |
-|---------------------|------------------------|
-| `eq(field, val)`    | `field = val`          |
-| `neq(field, val)`   | `field != val`         |
-| `gt(field, val)`    | `field > val`          |
-| `lt(field, val)`    | `field < val`          |
-| `inArray(field, [])` | `field IN (…)`        |
+```typescript
+// Get the full version history of a record
+const history = await products.getHistory('rec_abc123');
+// history[0] is the latest version, history[1] is one write before, etc.
 
-```ts
-import { eq, gt, inArray } from 'hydrous';
+// Restore to a specific version
+const restored = await products.restoreVersion('rec_abc123', history[2]!.version);
 ```
 
 ---
 
-## 5. Analytics
+## Authentication
+
+HydrousDB has a built-in user auth system. Your users live in a bucket you create
+(e.g. `"app-users"`). You get sessions, refresh tokens, password reset, email
+verification, and admin controls out of the box.
 
-### Track an Event
+```typescript
+const auth = db.auth('app-users');
+```
+
+### Sign Up Users
 
-```ts
-await hydrous.analytics.track({
-  event:      'page_view',
-  properties: { page: '/home', referrer: 'google.com' },
-  userId:     'user_abc123',
-  sessionId:  'sess_xyz',
+```typescript
+const { user, session } = await auth.signup({
+  email:    'alice@example.com',
+  password: 'hunter2',           // min 8 characters, validated server-side
+  fullName: 'Alice Wonderland',
+  // Any extra fields are stored on the user record:
+  plan:     'pro',
+  referral: 'friend123',
 });
+
+// user.id          → "usr_xxxxxxxxxx"
+// session.sessionId → persist this in your app
+// session.refreshToken → persist this for long-lived sessions
 ```
 
-### Batch Track
+### Log In / Log Out
 
-More efficient than calling `track()` in a loop:
+```typescript
+// Log in
+const { user, session } = await auth.login({
+  email:    'alice@example.com',
+  password: 'hunter2',
+});
 
-```ts
-await hydrous.analytics.trackBatch([
-  { event: 'signup',    userId: 'u1' },
-  { event: 'onboarded', userId: 'u1', properties: { step: 'profile' } },
-]);
+// Log out (invalidates the session server-side)
+await auth.logout({ sessionId: session.sessionId });
+```
+
+### Session Management
+
+Sessions expire after **24 hours**. Use the refresh token to get a new session (refresh tokens last **30 days**).
+
+```typescript
+// Refresh the session before it expires
+const newSession = await auth.refreshSession({
+  refreshToken: session.refreshToken,
+});
+// Store newSession.sessionId and newSession.refreshToken
+
+// Get the current user
+const user = await auth.getUser({ userId: session.userId });
 ```
 
-### Query Events
+### Update User Profile
+
+```typescript
+const updated = await auth.updateUser({
+  sessionId: session.sessionId,
+  userId:    user.id,
+  data: {
+    fullName: 'Alice Smith',
+    plan:     'enterprise',
+    avatar:   'https://example.com/avatar.jpg',
+  },
+});
+```
 
-```ts
-const { data, count } = await hydrous.analytics.query({
-  event:   'page_view',
-  from:    '2024-01-01',
-  to:      '2024-01-31',
-  limit:   500,
-  groupBy: 'properties.page',
+### Password Reset Flow
+
+```typescript
+// 1. User requests a reset (always returns success — prevents email enumeration)
+await auth.requestPasswordReset({ email: 'alice@example.com' });
+
+// 2. User receives an email with a reset token (your app handles the email sending)
+
+// 3. User submits the new password
+await auth.confirmPasswordReset({
+  resetToken:  'tok_from_email',
+  newPassword: 'correcthorsebatterystaple',
 });
+// All existing sessions for this user are automatically revoked
 ```
 
----
+### Change Password (authenticated)
 
-## 6. Storage
+```typescript
+await auth.changePassword({
+  sessionId:       session.sessionId,
+  userId:          user.id,
+  currentPassword: 'hunter2',
+  newPassword:     'correcthorsebatterystaple',
+});
+```
 
-The storage module handles all file operations. Every method takes a **bucket key** as its **first argument** — a string that begins with `ssk_`.
+### Email Verification
 
-### How Bucket Keys Work
+```typescript
+// 1. Send verification email
+await auth.requestEmailVerification({ userId: user.id });
 
-A bucket key (`ssk_…`) is a scoped credential that grants specific permissions (read / write / delete) to a bucket. You create them in the Hydrous dashboard.
+// 2. User clicks link in email, your app extracts the token
 
+// 3. Confirm the token
+await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
 ```
-hydrous.storage.<method>(
-  'ssk_your_bucket_key',   // ← first, always a string
-  ...args
-)
+
+### Admin Operations
+
+Admin operations require a valid session from a user with `role: 'admin'`.
+
+```typescript
+// List all users
+const { users, total } = await auth.listUsers({
+  sessionId: adminSession.sessionId,
+  limit:     50,
+  offset:    0,
+});
+
+// Lock an account (prevents login)
+await auth.lockAccount({
+  sessionId: adminSession.sessionId,
+  userId:    'usr_abc123',
+  duration:  60 * 60 * 1000, // lock for 1 hour (default: 15 minutes)
+});
+
+// Unlock an account
+await auth.unlockAccount({
+  sessionId: adminSession.sessionId,
+  userId:    'usr_abc123',
+});
+
+// Soft-delete a user (marks as deleted, keeps data)
+await auth.deleteUser({
+  sessionId: adminSession.sessionId,
+  userId:    'usr_abc123',
+});
+
+// Hard-delete a user (permanent — irreversible)
+await auth.hardDeleteUser({
+  sessionId: adminSession.sessionId,
+  userId:    'usr_abc123',
+});
+
+// Bulk delete multiple users
+const { deleted, failed } = await auth.bulkDeleteUsers({
+  sessionId: adminSession.sessionId,
+  userIds:   ['usr_a', 'usr_b', 'usr_c'],
+});
 ```
 
 ---
 
-### Upload a File
-
-```ts
-const { data, error } = await hydrous.storage.upload(
-  'ssk_my_bucket_key',
-  file,                      // File | Blob | Uint8Array | ArrayBuffer
-  {
-    path:      'avatars/alice.jpg',  // destination path in your bucket
-    overwrite: true,                 // replace if exists (default: false)
-    onProgress: (progress) => {
-      console.log(progress.stage, progress.percent + '%');
-    },
-  }
-);
+## File Storage
 
-if (data) {
-  console.log('Stored at:', data.path);
-  console.log('Space saved:', data.spaceSaved, 'bytes');
-}
+HydrousDB Storage is backed by Google Cloud Storage. Your files live at:
 ```
+hydrous-storage/{your-owner-id}/{your-path}
+```
+You never see or specify the owner prefix — the SDK handles it transparently.
 
----
+### Simple Upload
 
-### Upload Raw Text / JSON
+For files up to **500 MB** when you don't need upload progress:
 
-No `File` object needed — pass any string directly.
+```typescript
+// Browser: upload from a file input
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
 
-```ts
-// Upload a plain text file
-await hydrous.storage.uploadText(
-  'ssk_my_bucket_key',
-  'reports/summary.txt',
-  'Monthly report content…',
-  { mimeType: 'text/plain' }
-);
+const result = await db.storage.upload(file, `uploads/${file.name}`, {
+  isPublic:  true,   // publicly accessible without auth
+  overwrite: false,  // throw if the file already exists
+});
+
+console.log(result.publicUrl);   // CDN URL — usable anywhere
+console.log(result.downloadUrl); // null (it's public)
+console.log(result.size);        // bytes
+console.log(result.mimeType);    // auto-detected from extension
+
+// Node.js: upload from a Buffer
+import { readFileSync } from 'fs';
+const buffer = readFileSync('./report.pdf');
+const result = await db.storage.upload(buffer, 'reports/q3.pdf');
+console.log(result.downloadUrl); // requires X-Storage-Key to access
+```
+
+### Upload Raw JSON or Text
 
-// Upload JSON
-await hydrous.storage.uploadText(
-  'ssk_my_bucket_key',
-  'data/config.json',
-  JSON.stringify({ theme: 'dark', lang: 'en' }),
-  { mimeType: 'application/json' }
+```typescript
+const result = await db.storage.uploadRaw(
+  { theme: 'dark', language: 'en' },
+  'user-config/alice.json',
+  { isPublic: false },
 );
 ```
 
----
+### Large File Upload (with progress)
 
-### Track Upload Progress
+For files over 10 MB or when you need a progress bar. The file goes directly
+to GCS — your server never buffers it.
 
-`onProgress` is called on every progress tick with a rich `UploadProgress` object.
+```typescript
+// Step 1: Get a signed upload URL
+const { uploadUrl, path } = await db.storage.getUploadUrl({
+  path:     'videos/product-demo.mp4',
+  mimeType: 'video/mp4',
+  size:     file.size,
+  isPublic: true,
+});
 
-```ts
-await hydrous.storage.upload(
-  'ssk_my_bucket_key',
+// Step 2: Upload directly to GCS with progress
+await db.storage.uploadToSignedUrl(
+  uploadUrl,
   file,
-  {
-    onProgress: (p) => {
-      // p.stage          — 'pending' | 'compressing' | 'uploading' | 'done' | 'error'
-      // p.percent        — 0–100 integer
-      // p.bytesUploaded  — bytes sent so far
-      // p.totalBytes     — total bytes to send
-      // p.bytesPerSecond — current speed (null before first tick)
-      // p.eta            — estimated seconds remaining (null until speed is known)
-      // p.index          — file index (always 0 for single uploads)
-      // p.total          — total files (always 1 for single uploads)
-
-      switch (p.stage) {
-        case 'pending':
-          console.log('Queued');
-          break;
-        case 'compressing':
-          console.log('Compressing…');
-          break;
-        case 'uploading':
-          console.log(`Uploading ${p.percent}% — ${formatSpeed(p.bytesPerSecond)} — ETA ${p.eta}s`);
-          break;
-        case 'done':
-          console.log('✅ Done!', p.result);
-          break;
-        case 'error':
-          console.error('❌ Error:', p.error);
-          break;
-      }
-    },
-  }
+  'video/mp4',
+  (percent) => {
+    progressBar.style.width = `${percent}%`;
+    console.log(`${percent}% uploaded`);
+  },
 );
 
-function formatSpeed(bps: number | null): string {
-  if (!bps) return '—';
-  if (bps > 1_000_000) return `${(bps / 1_000_000).toFixed(1)} MB/s`;
-  if (bps > 1_000)     return `${(bps / 1_000).toFixed(0)} KB/s`;
-  return `${bps} B/s`;
-}
-```
-
-**Stage lifecycle:**
+// Step 3: Confirm the upload (registers metadata)
+const result = await db.storage.confirmUpload({
+  path:     path,
+  mimeType: 'video/mp4',
+  isPublic: true,
+});
 
-```
-pending → compressing → uploading → done
-                                  ↘ error
+console.log(result.publicUrl); // ready to use
 ```
 
-> **Note:** In browsers, upload progress (bytes leaving the NIC) is tracked via
-> `XMLHttpRequest`. The final `done` stage fires only after the server confirms
-> the write to cloud storage — so `100%` means the file is truly saved.
+### Batch Upload
 
----
+```typescript
+// Get signed URLs for multiple files
+const { files } = await db.storage.getBatchUploadUrls([
+  { path: 'gallery/photo1.jpg', mimeType: 'image/jpeg', size: 204800, isPublic: true },
+  { path: 'gallery/photo2.jpg', mimeType: 'image/jpeg', size: 153600, isPublic: true },
+]);
 
-### Batch Upload
+// Upload each one
+for (const f of files) {
+  await db.storage.uploadToSignedUrl(f.uploadUrl, blobs[f.index], f.mimeType);
+}
 
-Upload many files in one request. Progress fires per-file so you can render
-individual progress bars.
-
-```ts
-const inputFiles = Array.from(fileInput.files);  // FileList → array
-
-const { data, error } = await hydrous.storage.batchUpload(
-  'ssk_my_bucket_key',
-  inputFiles,
-  {
-    prefix:      'uploads/2024/',    // prepended to each filename
-    overwrite:   false,
-    concurrency: 5,                  // max parallel uploads on the server (1–10)
-    onProgress:  (p) => {
-      // p.index identifies WHICH file this event is for (0-based)
-      console.log(`File ${p.index} (${p.path}): ${p.stage} ${p.percent}%`);
-    },
-  }
+// Confirm all at once
+const results = await db.storage.batchConfirmUploads(
+  files.map(f => ({ path: f.path, mimeType: f.mimeType, isPublic: true }))
 );
+```
+
+### Download Files
+
+```typescript
+// Private files require authentication — download as ArrayBuffer
+const buffer = await db.storage.download('reports/q3.pdf');
+const blob   = new Blob([buffer], { type: 'application/pdf' });
 
-console.log('Succeeded:', data.succeeded.length);
-console.log('Failed:',    data.failed.length);
+// In a browser: trigger a file download
+const url = URL.createObjectURL(blob);
+const a   = document.createElement('a');
+a.href    = url;
+a.download = 'q3.pdf';
+a.click();
+
+// Public files: just use the publicUrl directly (no SDK needed)
+// <img src={result.publicUrl} />
 ```
 
-Per-file paths override:
+### List Files
 
-```ts
-await hydrous.storage.batchUpload('ssk_key', files, {
-  paths: [
-    'documents/report-q1.pdf',
-    'documents/report-q2.pdf',
-  ],
+```typescript
+// List everything at the root
+const { files, folders } = await db.storage.list();
+
+// List a specific folder
+const { files, folders, hasMore, nextCursor } = await db.storage.list({
+  prefix:    'gallery/',
+  limit:     50,
+  recursive: false,
 });
+
+// Paginate
+if (hasMore) {
+  const page2 = await db.storage.list({ prefix: 'gallery/', cursor: nextCursor });
+}
 ```
 
-> All files are validated upfront before any uploads begin — if your quota
-> would be exceeded the entire batch is rejected cleanly with no partial writes.
+Each file entry includes:
+```typescript
+{
+  name:        'photo1.jpg',
+  path:        'gallery/photo1.jpg',
+  size:        204800,
+  mimeType:    'image/jpeg',
+  isPublic:    true,
+  publicUrl:   'https://storage.googleapis.com/...',
+  downloadUrl: null,
+  updatedAt:   '2025-06-01T12:00:00.000Z',
+}
+```
 
----
+### Scoped Storage
 
-### Download a File
+Working within a specific folder? Use `.scope()` to avoid typing the prefix on every call.
 
-Returns the file as an `ArrayBuffer`.
+```typescript
+// All operations in the "user-avatars/" folder
+const avatars = db.storage.scope('user-avatars');
 
-```ts
-const { data: buffer, error } = await hydrous.storage.download(
-  'ssk_my_bucket_key',
-  'avatars/alice.jpg'
-);
+await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
+// → uploads to "user-avatars/{userId}.jpg"
 
-if (buffer) {
-  // Browser: display image
-  const blob = new Blob([buffer], { type: 'image/jpeg' });
-  img.src    = URL.createObjectURL(blob);
+const { files } = await avatars.list();
+// → lists files under "user-avatars/"
 
-  // Node: write to disk
-  import { writeFileSync } from 'fs';
-  writeFileSync('alice.jpg', Buffer.from(buffer));
-}
+await avatars.deleteFile(`${userId}.jpg`);
+// → deletes "user-avatars/{userId}.jpg"
+
+// Nest scopes
+const thumbnails = avatars.scope('thumbnails');
+// → all operations under "user-avatars/thumbnails/"
 ```
 
----
+### Share & Visibility
 
-### Batch Download
-
-```ts
-const { data: files } = await hydrous.storage.batchDownload(
-  'ssk_my_bucket_key',
-  ['reports/jan.pdf', 'reports/feb.pdf', 'reports/mar.pdf'],
-  {
-    concurrency: 3,
-    autoSave:    true,          // browser: auto-triggers Save dialog per file
-    onProgress:  (p) => {
-      console.log(`${p.path}: ${p.status}`);   // 'pending' | 'success' | 'error'
-    },
-  }
+```typescript
+// Get file metadata (sizes, URLs, visibility)
+const meta = await db.storage.getMetadata('reports/q3.pdf');
+
+// Generate a time-limited share link for a private file
+// (no auth key needed to use the link)
+const { signedUrl, expiresAt } = await db.storage.getSignedUrl(
+  'reports/q3.pdf',
+  3600,  // expires in 1 hour (default)
 );
+// Share signedUrl with whoever needs it
 
-// files[n].content  — ArrayBuffer
-// files[n].mimeType — string
-// files[n].path     — original path
-// files[n].size     — bytes
+// Toggle visibility after upload
+const result = await db.storage.setVisibility('reports/q3.pdf', true);  // make public
+const result2 = await db.storage.setVisibility('reports/q3.pdf', false); // make private
 ```
 
----
+### File Operations
 
-### List Files & Folders
+```typescript
+// Rename / move a file
+await db.storage.move('drafts/report.pdf', 'published/report-2025.pdf');
 
-```ts
-const { data } = await hydrous.storage.list('ssk_my_bucket_key', {
-  prefix: 'avatars/',   // list inside a folder — omit for root
-  limit:  50,           // max items per page (1–100)
-});
+// Copy a file
+await db.storage.copy('templates/invoice.html', 'invoices/inv-001.html');
 
-for (const item of data.items) {
-  if (item.type === 'folder') {
-    console.log('📁', item.path);
-  } else {
-    console.log('📄', item.path, item.size, 'bytes');
-  }
-}
+// Create a folder
+await db.storage.createFolder('archive/2025/');
 
-// Paginate
-if (data.pagination.hasNextPage) {
-  const page2 = await hydrous.storage.list('ssk_my_bucket_key', {
-    prefix: 'avatars/',
-    cursor: data.pagination.nextCursor,
-  });
-}
+// Delete a file
+await db.storage.deleteFile('temp/scratch.txt');
+
+// Delete a folder and all its contents
+await db.storage.deleteFolder('temp/');
+
+// Get key-level stats
+const stats = await db.storage.getStats();
+// → { totalFiles: 842, totalBytes: 1073741824, uploadCount: 1200, ... }
 ```
 
 ---
 
-### File Metadata
+## Analytics
 
-```ts
-const { data: meta } = await hydrous.storage.metadata(
-  'ssk_my_bucket_key',
-  'avatars/alice.jpg'
-);
+HydrousDB Analytics runs your queries against BigQuery, so they're fast even
+on millions of records. All queries accept an optional `dateRange` filter.
 
-console.log(meta.size);          // stored bytes
-console.log(meta.originalSize);  // bytes before compression
-console.log(meta.mimeType);
-console.log(meta.isCompressed);
-console.log(meta.updatedAt);
+```typescript
+const analytics = db.analytics('orders');
 ```
 
----
+### Count
 
-### Delete a File
+```typescript
+// Total records
+const { count } = await analytics.count();
 
-```ts
-const { error } = await hydrous.storage.deleteFile(
-  'ssk_my_bucket_key',
-  'avatars/old-photo.jpg'
-);
+// Records in a date range
+const { count: lastWeek } = await analytics.count({
+  dateRange: {
+    start: Date.now() - 7 * 24 * 60 * 60 * 1000,
+    end:   Date.now(),
+  },
+});
 ```
 
----
+### Distribution
 
-### Delete a Folder
+How many records have each unique value for a field?
 
-Recursively deletes the folder and everything inside it.
+```typescript
+const rows = await analytics.distribution({ field: 'status', limit: 10, order: 'desc' });
+// → [
+//   { value: 'completed', count: 8234 },
+//   { value: 'pending',   count: 1203 },
+//   { value: 'refunded',  count: 412  },
+// ]
+```
+
+### Sum
+
+```typescript
+// Total revenue
+const rows = await analytics.sum({ field: 'amount' });
+// → [{ sum: 198432.50 }]
 
-```ts
-await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
+// Revenue by country
+const byCountry = await analytics.sum({
+  field:   'amount',
+  groupBy: 'country',
+  limit:   10,
+});
+// → [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, ...]
 ```
 
----
+### Time Series
 
-### Create a Folder
+Record counts over time — ideal for activity charts.
 
-```ts
-await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
+```typescript
+const rows = await analytics.timeSeries({
+  granularity: 'day',       // 'hour' | 'day' | 'week' | 'month' | 'year'
+  dateRange: {
+    start: new Date('2025-01-01').getTime(),
+    end:   new Date('2025-06-01').getTime(),
+  },
+});
+// → [{ date: '2025-01-01', count: 42 }, { date: '2025-01-02', count: 67 }, ...]
 ```
 
----
+Aggregate a field over time:
+
+```typescript
+const revenue = await analytics.fieldTimeSeries({
+  field:       'amount',
+  aggregation: 'sum',   // 'sum' | 'avg' | 'min' | 'max' | 'count'
+  granularity: 'week',
+});
+// → [{ date: '2025-W01', value: 12340.50 }, ...]
+```
 
-### Move a File
+### Top N
 
-```ts
-await hydrous.storage.move(
-  'ssk_my_bucket_key',
-  'drafts/report.pdf',
-  'published/report.pdf'
-);
+Most common values for a field:
+
+```typescript
+const topProducts = await analytics.topN({
+  field:      'productId',
+  labelField: 'productName',  // optional: include a human-readable label
+  n:          5,
+  order:      'desc',
+});
+// → [
+//   { value: 'prod_123', label: 'Widget Pro', count: 892 },
+//   { value: 'prod_456', label: 'Gizmo Plus', count: 743 },
+// ]
 ```
 
----
+### Field Stats
 
-### Copy a File
+Statistical summary for any numeric field:
 
-```ts
-await hydrous.storage.copy(
-  'ssk_my_bucket_key',
-  'templates/invoice.pdf',
-  'invoices/invoice-001.pdf'
-);
+```typescript
+const stats = await analytics.stats({ field: 'orderValue' });
+// → {
+//   min: 4.99,  max: 9999.99, avg: 87.23,
+//   sum: 420948.27, count: 4823, stddev: 143.2
+// }
 ```
 
----
+### Multi-Metric Dashboard
 
-### Signed URLs
+Calculate several aggregations in a single BigQuery query:
 
-Generate a time-limited public URL for a private file.
+```typescript
+const dashboard = await analytics.multiMetric({
+  metrics: [
+    { field: 'amount',   name: 'totalRevenue',    aggregation: 'sum'   },
+    { field: 'amount',   name: 'avgOrderValue',   aggregation: 'avg'   },
+    { field: 'amount',   name: 'maxOrder',        aggregation: 'max'   },
+    { field: 'userId',   name: 'totalOrders',     aggregation: 'count' },
+  ],
+  dateRange: { start: new Date('2025-01-01').getTime(), end: Date.now() },
+});
+// → {
+//   totalRevenue:  198432.50,
+//   avgOrderValue: 87.23,
+//   maxOrder:      9999.99,
+//   totalOrders:   2275,
+// }
+```
 
-```ts
-const { data } = await hydrous.storage.signedUrl(
-  'ssk_my_bucket_key',
-  'contracts/agreement.pdf',
-  { expiresIn: 300 }   // 5 minutes (default: 3600 = 1 hour)
-);
+### Filtered Records (BigQuery)
 
-console.log(data.signedUrl);   // share this — expires at data.expiresAt
+Query raw records with full BigQuery speed:
+
+```typescript
+const records = await analytics.records({
+  filters: [
+    { field: 'status', op: '==', value: 'refunded' },
+    { field: 'amount', op: '>',  value: 100         },
+  ],
+  selectFields: ['orderId', 'amount', 'userId', 'createdAt'],
+  orderBy: 'amount',
+  order:   'desc',
+  limit:   50,
+});
 ```
 
----
+### Cross-Bucket Comparison
 
-### Bucket Stats
+Compare the same metric across multiple buckets in one query:
 
-```ts
-const { data: stats } = await hydrous.storage.stats('ssk_my_bucket_key');
+```typescript
+const comparison = await analytics.crossBucket({
+  bucketKeys:  ['orders-us', 'orders-eu', 'orders-apac'],
+  field:       'amount',
+  aggregation: 'sum',
+});
+// → [
+//   { bucket: 'orders-us',   value: 120000 },
+//   { bucket: 'orders-eu',   value: 45000  },
+//   { bucket: 'orders-apac', value: 33000  },
+// ]
+```
+
+> ⚠️ Your Security Key must have read access to **all** buckets in the list.
+
+### Storage Stats
 
-console.log('Files:',         stats.totalFiles);
-console.log('Stored:',        stats.totalSizeBytes,   'bytes');
-console.log('Space saved:',   stats.spaceSavedBytes,  'bytes');
-console.log('Credits used:',  stats.creditsTotalUsed);
-console.log('Compression:',   stats.compressionRatio);
+```typescript
+const stats = await analytics.storageStats();
+// → { totalRecords: 48210, totalBytes: 921600000, avgBytes: 19112, minBytes: 128, maxBytes: 5242880 }
 ```
 
 ---
 
-## 7. Error Handling
+## TypeScript Support
 
-Every method returns `{ data, error }`. `error` is `null` on success.
+The SDK is written in TypeScript and ships with full type definitions. Use generic
+type parameters to describe the shape of your records and get autocomplete throughout.
 
-```ts
-const { data, error } = await hydrous.storage.upload('ssk_key', file);
+```typescript
+import { createClient } from 'hydrousdb';
 
-if (error) {
-  console.error(error.message);  // human-readable message
-  console.error(error.code);     // machine-readable code e.g. 'QUOTA_EXCEEDED'
-  console.error(error.status);   // HTTP status code (if applicable)
+// Define your data models
+interface Order {
+  customerId: string;
+  items:      Array<{ productId: string; qty: number; price: number }>;
+  total:      number;
+  status:     'pending' | 'processing' | 'completed' | 'refunded';
+  country:    string;
 }
+
+interface Customer {
+  name:    string;
+  email:   string;
+  tier:    'free' | 'pro' | 'enterprise';
+  credits: number;
+}
+
+const db = createClient({ securityKey: process.env.HYDROUS_SECURITY_KEY! });
+
+// Fully typed clients
+const orders    = db.records<Order>('orders');
+const customers = db.records<Customer>('customers');
+
+// order.total, order.status, etc. are all type-safe
+const order = await orders.create({
+  customerId: 'cust_abc',
+  items:      [{ productId: 'prod_1', qty: 2, price: 29.99 }],
+  total:      59.98,
+  status:     'pending',
+  country:    'US',
+});
+
+// TypeScript catches mistakes at compile time:
+// order.nonExistentField  // ← TS error ✓
+// order.status = 'invalid' // ← TS error ✓
+```
+
+All exported types are available for import:
+
+```typescript
+import type {
+  HydrousConfig,
+  RecordResult,
+  QueryFilter,
+  QueryOptions,
+  UploadResult,
+  AnalyticsQuery,
+  DateRange,
+  // ... and many more
+} from 'hydrousdb';
 ```
 
-### Catching thrown errors
+---
+
+## Error Handling
+
+All errors thrown by the SDK extend `HydrousError`, which carries:
 
-If you prefer `try/catch`, import `isHydrousError`:
+| Property | Type | Description |
+|---|---|---|
+| `message` | `string` | Human-readable description |
+| `code` | `string` | Machine-readable error code (e.g. `"RECORD_NOT_FOUND"`) |
+| `status` | `number` | HTTP status code |
+| `requestId` | `string` | Server request ID (for support tracing) |
+| `details` | `string[]` | Validation error details |
 
-```ts
-import { isHydrousError } from 'hydrous';
+```typescript
+import { HydrousError, NetworkError, AuthError } from 'hydrousdb';
 
 try {
-  // ...
+  const user = await auth.login({ email: 'a@b.com', password: 'wrong' });
 } catch (err) {
-  if (isHydrousError(err)) {
-    console.error(err.code, err.message);
+  if (err instanceof AuthError) {
+    // Authentication-specific error
+    console.error(`Auth failed: ${err.code}`);
+    // err.code might be: INVALID_CREDENTIALS, ACCOUNT_LOCKED, EMAIL_NOT_VERIFIED, etc.
+  } else if (err instanceof NetworkError) {
+    // No internet / server unreachable
+    console.error('Cannot reach HydrousDB — check your internet connection');
+  } else if (err instanceof HydrousError) {
+    // Any other API error
+    console.error(`API error [${err.code}]: ${err.message}`);
+    console.error(`Request ID: ${err.requestId}`); // include this in support tickets
   }
 }
 ```
 
-### Common error codes
+**Common error codes:**
+
+| Code | Meaning |
+|---|---|
+| `RECORD_NOT_FOUND` | The requested record ID does not exist |
+| `INVALID_CREDENTIALS` | Wrong email or password |
+| `ACCOUNT_LOCKED` | The account is temporarily locked |
+| `INVALID_SESSION` | Session expired or revoked — re-authenticate |
+| `MISSING_API_KEY` | Security key not provided |
+| `INVALID_SECURITY_KEY` | Security key is wrong or revoked |
+| `FORBIDDEN` | Insufficient permissions |
+| `FILE_EXISTS` | File already exists at path (use `overwrite: true`) |
+| `LIMIT_EXCEEDED` | Storage quota or file size limit reached |
+| `SYSTEM_BUCKET_FORBIDDEN` | Cannot query system buckets via analytics |
+| `VALIDATION_ERROR` | Invalid input — check `err.details` |
+| `NETWORK_ERROR` | Failed to reach the API |
+
+---
+
+## Security Best Practices
 
-| Code                | Meaning                                      |
-|---------------------|----------------------------------------------|
-| `HTTP_ERROR`        | Non-2xx HTTP response from the server        |
-| `NETWORK_ERROR`     | Failed to reach the server                   |
-| `QUOTA_EXCEEDED`    | Storage quota has been reached               |
-| `FILE_TOO_LARGE`    | File exceeds the per-file size limit (50 MB) |
-| `INVALID_MIME`      | MIME type not permitted                      |
-| `FILE_EXISTS`       | File already exists and `overwrite` is false |
-| `UPLOAD_ABORTED`    | Upload was cancelled by the client           |
-| `UPLOAD_TIMEOUT`    | Upload timed out                             |
-| `NO_SESSION`        | Auth operation requires a session            |
-| `UNKNOWN_ERROR`     | An unexpected error occurred                 |
+1. **Never hard-code your Security Key.** Use environment variables:
+
+   ```bash
+   # .env (add to .gitignore)
+   HYDROUS_SECURITY_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx
+   ```
+
+   ```typescript
+   const db = createClient({ securityKey: process.env.HYDROUS_SECURITY_KEY! });
+   ```
+
+2. **Never expose your Security Key to browsers.** For browser-side apps,
+   route requests through your own backend, or use per-user session tokens.
+
+3. **Your Security Key is sent via the `X-Api-Key` header — never in URLs.**
+   The SDK enforces this automatically, so keys never appear in server logs or
+   browser history.
+
+4. **Rotate keys periodically.** Revoke old keys from the dashboard after rotation.
+
+5. **Use scoped storage** (`db.storage.scope(...)`) to isolate access by user or
+   feature, reducing the blast radius of any misconfiguration.
+
+6. **Use `isPublic: false` (the default) for sensitive files.** Use signed URLs
+   for time-limited sharing instead of making files permanently public.
 
 ---
 
-## 8. TypeScript Types Reference
-
-### `UploadProgress`
-
-```ts
-interface UploadProgress {
-  index:          number;          // file index (0-based)
-  total:          number;          // total files in the operation
-  path:           string;          // destination path
-  stage:          UploadStage;     // see below
-  bytesUploaded:  number;
-  totalBytes:     number;
-  percent:        number;          // 0–100
-  bytesPerSecond: number | null;   // null before first tick
-  eta:            number | null;   // seconds remaining, null until speed known
-  result?:        UploadResult;    // set when stage === 'done'
-  error?:         string;          // set when stage === 'error'
-  code?:          string;
-}
+## API Reference
 
-type UploadStage = 'pending' | 'compressing' | 'uploading' | 'done' | 'error';
-```
+### `createClient(config)`
 
-### `UploadResult`
+Creates and returns a `HydrousClient` instance. Call this once and reuse the instance.
 
-```ts
-interface UploadResult {
-  path:         string;
-  compressed:   boolean;
-  originalSize: number;
-  storedSize:   number;
-  spaceSaved:   number;
-  mimeType:     string;
-}
+```typescript
+const db = createClient({
+  securityKey: 'sk_live_...',   // Required — from https://hydrousdb.com/dashboard
+  baseUrl:     'https://...',   // Optional — defaults to official HydrousDB endpoint
+});
 ```
 
-### `StorageItem` (from `list()`)
+### `db.records<T>(bucketKey)`
+
+Returns a `RecordsClient<T>` for the named bucket.
+
+| Method | Description |
+|---|---|
+| `create(data)` | Create a new record |
+| `get(id)` | Get a record by ID |
+| `set(id, data)` | Full replace |
+| `patch(id, data, opts?)` | Partial update (merge by default) |
+| `delete(id)` | Delete a record |
+| `query(opts?)` | Query with filters, sort, pagination |
+| `getAll(opts?)` | Shortcut for query without filters |
+| `count(filters?)` | Count matching records |
+| `batchCreate(items)` | Create multiple records |
+| `batchDelete(ids)` | Delete multiple records |
+| `getHistory(id)` | Get version history |
+| `restoreVersion(id, version)` | Restore to a version |
+
+### `db.auth(bucketKey)`
+
+Returns an `AuthClient` for the named user bucket.
+
+| Method | Description |
+|---|---|
+| `signup(opts)` | Register a new user |
+| `login(opts)` | Authenticate and create session |
+| `logout({ sessionId })` | Invalidate session |
+| `refreshSession({ refreshToken })` | Extend a session |
+| `getUser({ userId })` | Get user by ID |
+| `updateUser(opts)` | Update user fields |
+| `deleteUser(opts)` | Soft-delete a user |
+| `hardDeleteUser(opts)` | Permanently delete a user (admin) |
+| `listUsers(opts)` | List all users (admin) |
+| `bulkDeleteUsers(opts)` | Bulk delete (admin) |
+| `lockAccount(opts)` | Lock a user (admin) |
+| `unlockAccount(opts)` | Unlock a user (admin) |
+| `changePassword(opts)` | Change password (authenticated) |
+| `requestPasswordReset(opts)` | Send reset email |
+| `confirmPasswordReset(opts)` | Apply new password |
+| `requestEmailVerification(opts)` | Send verification email |
+| `confirmEmailVerification(opts)` | Verify email with token |
+
+### `db.analytics(bucketKey)`
+
+Returns an `AnalyticsClient` for the named bucket.
+
+| Method | Description |
+|---|---|
+| `count(opts?)` | Count records |
+| `distribution(opts)` | Value distribution for a field |
+| `sum(opts)` | Sum (with optional groupBy) |
+| `timeSeries(opts?)` | Records over time |
+| `fieldTimeSeries(opts)` | Field aggregation over time |
+| `topN(opts)` | Top N values for a field |
+| `stats(opts)` | Statistical summary for a field |
+| `records(opts?)` | Filtered raw records (BigQuery) |
+| `multiMetric(opts)` | Multiple aggregations in one query |
+| `storageStats(opts?)` | Bucket storage statistics |
+| `crossBucket(opts)` | Compare across multiple buckets |
+| `query(query)` | Raw analytics query |
+
+### `db.storage`
+
+The `StorageManager` instance. Also has `.scope(prefix)` for folder-scoped access.
+
+| Method | Description |
+|---|---|
+| `upload(data, path, opts?)` | Simple server-buffered upload |
+| `uploadRaw(data, path, opts?)` | Upload JSON/text data |
+| `getUploadUrl(opts)` | Step 1: Get signed GCS upload URL |
+| `uploadToSignedUrl(url, data, mime, onProgress?)` | Step 2: Upload to GCS directly |
+| `confirmUpload(opts)` | Step 3: Register upload metadata |
+| `getBatchUploadUrls(files)` | Batch signed upload URLs |
+| `batchConfirmUploads(items)` | Confirm batch uploads |
+| `download(path)` | Download private file |
+| `batchDownload(paths)` | Batch download |
+| `list(opts?)` | List files and folders |
+| `getMetadata(path)` | File metadata |
+| `getSignedUrl(path, expiresIn?)` | Time-limited share URL |
+| `setVisibility(path, isPublic)` | Toggle public/private |
+| `createFolder(path)` | Create a folder |
+| `deleteFile(path)` | Delete a file |
+| `deleteFolder(path)` | Delete a folder recursively |
+| `move(from, to)` | Move/rename |
+| `copy(from, to)` | Copy |
+| `getStats()` | Key-level stats |
+| `info()` | Server ping (no auth) |
+| `scope(prefix)` | Get a ScopedStorage instance |
 
-```ts
-interface StorageItem {
-  name:         string;
-  path:         string;
-  type:         'file' | 'folder';
-  size?:        number | null;
-  mimeType?:    string | null;
-  isCompressed?: boolean;
-  updatedAt?:   string | null;
-}
-```
+---
 
-### `StorageStats`
-
-```ts
-interface StorageStats {
-  totalFiles:             number;
-  totalSizeBytes:         number;
-  totalOriginalSizeBytes: number;
-  spaceSavedBytes:        number;
-  uploadsCount:           number;
-  downloadsCount:         number;
-  creditsUsedUpload:      number;
-  creditsUsedDownload:    number;
-  creditsTotalUsed:       number;
-  compressionRatio:       string;  // e.g. "34.2%"
-}
+## Contributing
+
+We love contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+```bash
+# Clone the repo
+git clone https://github.com/hydrousdb/hydrousdb-js.git
+cd hydrousdb-js
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Run tests in watch mode
+npm run test:watch
 ```
 
 ---
 
 ## License
 
-MIT © Hydrous
+MIT — see [LICENSE](./LICENSE) for details.
+
+---
+
+<p align="center">
+  Built with ❤️ by the <a href="https://hydrousdb.com">HydrousDB</a> team.<br>
+  Questions? <a href="mailto:support@hydrousdb.com">support@hydrousdb.com</a> · 
+  <a href="https://github.com/hydrousdb/hydrousdb-js/issues">Open an issue</a>
+</p>