hydrousdb 2.0.0 → 2.0.1

package/README.md

@@ -1,777 +1,730 @@
-# hydrousdb
+# Hydrous SDK
 
-> **Official TypeScript SDK for [HydrousDB](https://db-api-82687684612.us-central1.run.app)**
-> — a cloud-native record store with built-in authentication, batch operations, analytics, and cursor-based pagination.
+Official JavaScript / TypeScript SDK for the **Hydrous** platform.  
+One package — auth, records, analytics, and storage.
 
-[![npm version](https://img.shields.io/npm/v/hydrousdb)](https://npmjs.com/package/hydrousdb)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+```bash
+npm install hydrous
+```
 
 ---
 
 ## Table of Contents
 
-- [Features](#features)
-- [Installation](#installation)
-- [Key Concepts](#key-concepts)
-- [Quick Start](#quick-start)
-- [Framework Guides](#framework-guides)
-  - [Next.js (App Router)](#nextjs-app-router)
-  - [Next.js (Pages Router)](#nextjs-pages-router)
-  - [Vue 3 / Nuxt 3](#vue-3--nuxt-3)
-  - [React (Vite / CRA)](#react-vite--cra)
-  - [Node.js / Express](#nodejs--express)
-- [API Reference](#api-reference)
-  - [createClient](#createclient)
-  - [Records](#records)
-  - [Auth](#auth)
-  - [Analytics](#analytics)
-- [Error Handling](#error-handling)
-- [Pagination](#pagination)
-- [TypeScript](#typescript)
-- [Migration from v1](#migration-from-v1)
-- [Contributing](#contributing)
-- [License](#license)
+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)
 
 ---
 
-## Features
+## 1. Quick Start
+
+```ts
+import { createClient } from 'hydrous';
+
+const hydrous = createClient({
+  url:    'https://api.yourapp.hydrous.app',
+  apiKey: 'hk_live_…',
+});
 
-- ✅ **Full TypeScript** — every method and response is fully typed
-- ✅ **Multi-bucket** — one client, any number of buckets; pass `bucketKey` per call
-- ✅ **Modular** — import only what you need (`hydrousdb/records`, `hydrousdb/auth`, `hydrousdb/analytics`)
-- ✅ **Tree-shakeable** — ships ESM + CJS with dual exports
-- ✅ **Auto-retry** — retries on transient 5xx / network errors with linear back-off
-- ✅ **Timeout control** — configurable per-client request timeout
-- ✅ **Cursor pagination helpers** — `queryAll()` / `listAllUsers()` handle cursor following for you
-- ✅ **Zero dependencies** — uses the native `fetch` API (Node 18+, all modern browsers)
+// 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}%`),
+  }
+);
+```
 
 ---
 
-## Installation
+## 2. Configuration
 
-```bash
-npm install hydrousdb
-# or
-pnpm add hydrousdb
-# or
-yarn add hydrousdb
+```ts
+import { HydrousClient } from 'hydrous';
+
+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)
+});
 ```
 
-> **Node.js ≥ 18** is required (uses native `fetch`). For Node 16/17, polyfill `fetch` with `node-fetch` or `undici`.
+| 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) |
 
 ---
 
-## Key Concepts
-
-### Two keys, one client
+## 3. Auth
 
-The SDK separates two distinct credentials:
+### Sign Up
 
-| Key | Config field | Used for |
-|-----|-------------|----------|
-| Auth key | `authKey` | All `/auth` routes — sign up, sign in, session management |
-| Security key | `securityKey` | All records and analytics routes — data access credential |
+```ts
+const { data, error } = await hydrous.auth.signUp({
+  email:    'user@example.com',
+  password: 'supersecret',
+  metadata: { plan: 'pro' },   // optional
+});
 
-### Bucket per call
+if (data) {
+  console.log('New user:', data.user.id);
+  console.log('Access token:', data.accessToken);
+}
+```
 
-Unlike v1, `bucketKey` is **not** set on the client — it's passed as an option on every records and analytics call. This means a **single client instance can read and write to any number of buckets** without re-initialising.
+### Sign In
 
 ```ts
-const db = createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
+const { data, error } = await hydrous.auth.signIn({
+  email:    'user@example.com',
+  password: 'supersecret',
+});
 
-// Same client, different buckets
-await db.records.insert({ values: { name: 'Alice' } }, { bucketKey: 'users' });
-await db.records.insert({ values: { order: '#1001' } }, { bucketKey: 'orders' });
-await db.analytics.count({ bucketKey: 'users' });
-await db.analytics.count({ bucketKey: 'orders' });
+if (data) {
+  console.log('Welcome back,', data.user.email);
+}
 ```
 
----
-
-## Quick Start
+### Sign Out
 
 ```ts
-import { createClient } from 'hydrousdb';
-
-const db = createClient({
-  authKey:     'your-auth-key',
-  securityKey: 'your-security-key',
-});
+await hydrous.auth.signOut();
+```
 
-// Insert a record into the 'users' bucket
-const { data, meta } = await db.records.insert(
-  { values: { name: 'Alice', score: 99 }, queryableFields: ['name'] },
-  { bucketKey: 'users' }
-);
-console.log('Created record:', meta.id);
+### Get Current User
 
-// Query records from the 'users' bucket
-const { data: records } = await db.records.query({
-  bucketKey: 'users',
-  filters: [{ field: 'score', op: '>=', value: 90 }],
-  limit: 20,
-});
+```ts
+const { data: user } = await hydrous.auth.getUser();
+console.log(user?.email);
+```
 
-// Auth — no bucketKey needed
-const { data: user, session } = await db.auth.signIn({
-  email: 'alice@example.com',
-  password: 'Str0ng@Pass!',
-});
+### Refresh Session
 
-// Analytics
-const { data: stats } = await db.analytics.count({ bucketKey: 'users' });
-console.log(stats.count);
+```ts
+const { data: session } = await hydrous.auth.refreshSession();
 ```
 
 ---
 
-## Framework Guides
+## 4. Records
 
-### Next.js (App Router)
+### Insert
 
-**1. Create a shared client singleton**
+Single record:
 
 ```ts
-// lib/db.ts
-import { createClient } from 'hydrousdb';
-
-export const db = createClient({
-  authKey:     process.env.HYDROUS_AUTH_KEY!,
-  securityKey: process.env.HYDROUS_SECURITY_KEY!,
+const { data, error } = await hydrous.records.insert('users', {
+  name:  'Alice',
+  email: 'alice@example.com',
+  role:  'admin',
 });
 ```
 
-**2. Use in a Server Component**
+Bulk insert (array):
 
-```tsx
-// app/products/page.tsx
-import { db } from '@/lib/db';
-
-export default async function ProductsPage() {
-  const { data: products } = await db.records.query({
-    bucketKey: 'products',
-    filters: [{ field: 'category', op: '==', value: 'shoes' }],
-    limit: 24,
-    sortOrder: 'desc',
-  });
-
-  return (
-    <ul>
-      {products.map(p => (
-        <li key={p.id}>{String(p.name)}</li>
-      ))}
-    </ul>
-  );
-}
+```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`);
 ```
 
-**3. Use in a Route Handler**
+### Select / Query
 
 ```ts
-// app/api/records/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { db } from '@/lib/db';
-import { HydrousError } from 'hydrousdb';
-
-export async function POST(req: NextRequest) {
-  try {
-    const body = await req.json();
-    const result = await db.records.insert(
-      { values: body, queryableFields: ['email', 'name'] },
-      { bucketKey: 'users' }
-    );
-    return NextResponse.json(result, { status: 201 });
-  } catch (err) {
-    if (err instanceof HydrousError) {
-      return NextResponse.json({ error: err.message }, { status: err.status });
-    }
-    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
-  }
-}
+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
+});
 ```
 
-**4. Auth middleware example**
+Multiple filters:
 
 ```ts
-// middleware.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { db } from '@/lib/db';
+import { eq, gt, inArray } from 'hydrous';
 
-export async function middleware(req: NextRequest) {
-  const sessionId = req.cookies.get('sessionId')?.value;
-  if (!sessionId) return NextResponse.redirect(new URL('/login', req.url));
-
-  try {
-    await db.auth.validateSession(sessionId);
-    return NextResponse.next();
-  } catch {
-    return NextResponse.redirect(new URL('/login', req.url));
-  }
-}
-
-export const config = { matcher: ['/dashboard/:path*'] };
+const { data } = await hydrous.records.select('orders', {
+  where: [
+    eq('status',  'shipped'),
+    gt('total',   100),
+    inArray('tag', ['vip', 'priority']),
+  ],
+});
 ```
 
-**5. Environment variables**
+### Get by ID
 
-```env
-# .env.local
-HYDROUS_AUTH_KEY=your-auth-key
-HYDROUS_SECURITY_KEY=your-security-key
+```ts
+const { data: user } = await hydrous.records.get('users', 'user_abc123');
 ```
 
----
-
-### Next.js (Pages Router)
+### Update
 
 ```ts
-// pages/api/records.ts
-import type { NextApiRequest, NextApiResponse } from 'next';
-import { createClient, HydrousError } from 'hydrousdb';
-
-const db = createClient({
-  authKey:     process.env.HYDROUS_AUTH_KEY!,
-  securityKey: process.env.HYDROUS_SECURITY_KEY!,
+const { data } = await hydrous.records.update('users', 'user_abc123', {
+  name: 'Alice Smith',
 });
-
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  if (req.method === 'GET') {
-    try {
-      const result = await db.records.query({ bucketKey: 'orders', limit: 50 });
-      return res.status(200).json(result);
-    } catch (err) {
-      if (err instanceof HydrousError) return res.status(err.status).json({ error: err.message });
-      return res.status(500).json({ error: 'Internal Server Error' });
-    }
-  }
-  res.setHeader('Allow', ['GET']);
-  res.status(405).end();
-}
 ```
 
----
+### Delete
 
-### Vue 3 / Nuxt 3
+```ts
+const { error } = await hydrous.records.delete('users', 'user_abc123');
+```
+
+### Query Helpers
 
-**Nuxt 3 — plugin**
+| 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 (…)`        |
 
 ```ts
-// plugins/hydrousdb.ts
-import { createClient } from 'hydrousdb';
+import { eq, gt, inArray } from 'hydrous';
+```
 
-export default defineNuxtPlugin(() => {
-  const config = useRuntimeConfig();
+---
 
-  const db = createClient({
-    authKey:     config.hydrousAuthKey as string,
-    securityKey: config.hydrousSecurityKey as string,
-  });
+## 5. Analytics
 
-  return { provide: { db } };
-});
-```
+### Track an Event
 
 ```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  runtimeConfig: {
-    hydrousAuthKey:     '',  // NUXT_HYDROUS_AUTH_KEY
-    hydrousSecurityKey: '',  // NUXT_HYDROUS_SECURITY_KEY
-  },
+await hydrous.analytics.track({
+  event:      'page_view',
+  properties: { page: '/home', referrer: 'google.com' },
+  userId:     'user_abc123',
+  sessionId:  'sess_xyz',
 });
 ```
 
-**Usage in a component**
+### Batch Track
 
-```vue
-<script setup lang="ts">
-const { $db } = useNuxtApp();
+More efficient than calling `track()` in a loop:
 
-const { data: records, pending } = await useAsyncData('records', () =>
-  $db.records.query({ bucketKey: 'products', limit: 20 })
-);
-</script>
-
-<template>
-  <div v-if="pending">Loading…</div>
-  <ul v-else>
-    <li v-for="r in records?.data" :key="r.id">{{ r.name }}</li>
-  </ul>
-</template>
+```ts
+await hydrous.analytics.trackBatch([
+  { event: 'signup',    userId: 'u1' },
+  { event: 'onboarded', userId: 'u1', properties: { step: 'profile' } },
+]);
 ```
 
-**Vue 3 standalone — composable**
+### Query Events
 
 ```ts
-// composables/useHydrous.ts
-import { createClient } from 'hydrousdb';
-
-const db = createClient({
-  authKey:     import.meta.env.VITE_HYDROUS_AUTH_KEY,
-  securityKey: import.meta.env.VITE_HYDROUS_SECURITY_KEY,
+const { data, count } = await hydrous.analytics.query({
+  event:   'page_view',
+  from:    '2024-01-01',
+  to:      '2024-01-31',
+  limit:   500,
+  groupBy: 'properties.page',
 });
-
-export function useHydrous() {
-  return db;
-}
 ```
 
 ---
 
-### React (Vite / CRA)
+## 6. Storage
 
-```tsx
-// src/hooks/useRecords.ts
-import { useEffect, useState } from 'react';
-import { createClient, HydrousRecord, HydrousError } from 'hydrousdb';
+The storage module handles all file operations. Every method takes a **bucket key** as its **first argument** — a string that begins with `ssk_`.
 
-const db = createClient({
-  authKey:     import.meta.env.VITE_HYDROUS_AUTH_KEY,
-  securityKey: import.meta.env.VITE_HYDROUS_SECURITY_KEY,
-});
+### How Bucket Keys Work
 
-export function useRecords(bucketKey: string, limit = 20) {
-  const [records, setRecords] = useState<HydrousRecord[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError]     = useState<string | null>(null);
+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.
 
-  useEffect(() => {
-    const controller = new AbortController();
+```
+hydrous.storage.<method>(
+  'ssk_your_bucket_key',   // ← first, always a string
+  ...args
+)
+```
 
-    db.records.query({ bucketKey, limit }, { signal: controller.signal })
-      .then(r  => setRecords(r.data))
-      .catch(e => { if (!(e instanceof DOMException)) setError(String(e)); })
-      .finally(() => setLoading(false));
+---
+
+### Upload a File
 
-    return () => controller.abort();
-  }, [bucketKey, limit]);
+```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 + '%');
+    },
+  }
+);
 
-  return { records, loading, error };
+if (data) {
+  console.log('Stored at:', data.path);
+  console.log('Space saved:', data.spaceSaved, 'bytes');
 }
 ```
 
 ---
 
-### Node.js / Express
+### Upload Raw Text / JSON
 
-```ts
-// server.ts
-import express from 'express';
-import { createClient, HydrousError } from 'hydrousdb';
+No `File` object needed — pass any string directly.
 
-const db  = createClient({
-  authKey:     process.env.HYDROUS_AUTH_KEY!,
-  securityKey: process.env.HYDROUS_SECURITY_KEY!,
-});
-const app = express();
-app.use(express.json());
-
-app.get('/orders', async (req, res) => {
-  try {
-    const result = await db.records.query({ bucketKey: 'orders', limit: 50 });
-    res.json(result);
-  } catch (err) {
-    if (err instanceof HydrousError) return res.status(err.status).json({ error: err.message });
-    res.status(500).json({ error: 'Internal Server Error' });
-  }
-});
+```ts
+// Upload a plain text file
+await hydrous.storage.uploadText(
+  'ssk_my_bucket_key',
+  'reports/summary.txt',
+  'Monthly report content…',
+  { mimeType: 'text/plain' }
+);
 
-app.listen(3000, () => console.log('Listening on :3000'));
+// Upload JSON
+await hydrous.storage.uploadText(
+  'ssk_my_bucket_key',
+  'data/config.json',
+  JSON.stringify({ theme: 'dark', lang: 'en' }),
+  { mimeType: 'application/json' }
+);
 ```
 
 ---
 
-## API Reference
+### Track Upload Progress
 
-### `createClient`
+`onProgress` is called on every progress tick with a rich `UploadProgress` object.
 
 ```ts
-import { createClient } from 'hydrousdb';
+await hydrous.storage.upload(
+  'ssk_my_bucket_key',
+  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;
+      }
+    },
+  }
+);
 
-const db = createClient({
-  authKey:     string,  // required — your HydrousDB auth key (for /auth routes)
-  securityKey: string,  // required — your HydrousDB security key (for records & analytics)
-  baseUrl?:    string,  // override API base URL
-  timeout?:    number,  // request timeout in ms (default: 30_000)
-  retries?:    number,  // retries on network/5xx errors (default: 2)
-});
+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`;
+}
 ```
 
-> **Note:** `bucketKey` is no longer part of the client config. It is passed as an option on each individual records and analytics call.
+**Stage lifecycle:**
 
----
+```
+pending → compressing → uploading → done
+                                  ↘ error
+```
 
-### Records
+> **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.
 
-All methods live on `db.records`. Every method requires a `bucketKey` option.
+---
 
-| Method | Description |
-|---|---|
-| `get(recordId, { bucketKey, ...opts })` | Fetch a single record |
-| `getSnapshot(recordId, generation, { bucketKey, ...opts })` | Fetch a historical version |
-| `query({ bucketKey, ...opts })` | Query a collection with filters / pagination |
-| `queryAll({ bucketKey, ...opts })` | Fetch all pages automatically |
-| `insert(payload, { bucketKey, ...opts })` | Create a new record |
-| `update(payload, { bucketKey, ...opts })` | Update an existing record |
-| `delete(recordId, { bucketKey, ...opts })` | Delete a record |
-| `exists(recordId, { bucketKey, ...opts })` | HEAD check — returns metadata or `null` |
-| `batchInsert(payload, { bucketKey, ...opts })` | Insert up to 500 records |
-| `batchUpdate(payload, { bucketKey, ...opts })` | Update up to 500 records |
-| `batchDelete(payload, { bucketKey, ...opts })` | Delete up to 500 records |
+### Batch Upload
 
-#### `db.records.get(recordId, options)`
+Upload many files in one request. Progress fires per-file so you can render
+individual progress bars.
 
 ```ts
-const { data, history } = await db.records.get('rec_abc', {
-  bucketKey:   'users',
-  showHistory: true,
-});
+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}%`);
+    },
+  }
+);
+
+console.log('Succeeded:', data.succeeded.length);
+console.log('Failed:',    data.failed.length);
 ```
 
-#### `db.records.query(options)`
+Per-file paths override:
 
 ```ts
-const { data, meta } = await db.records.query({
-  bucketKey:  'orders',
-  filters:    [{ field: 'status', op: '==', value: 'active' }],
-  timeScope:  '30d',
-  sortOrder:  'desc',
-  limit:      50,
-  cursor:     meta.nextCursor ?? undefined,
-  fields:     'id,name,status',
+await hydrous.storage.batchUpload('ssk_key', files, {
+  paths: [
+    'documents/report-q1.pdf',
+    'documents/report-q2.pdf',
+  ],
 });
 ```
 
-**Filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`  
-**Max 3 filters per query.**
+> 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.
 
-#### `db.records.insert(payload, options)`
+---
 
-```ts
-const { data, meta } = await db.records.insert(
-  {
-    values:          { name: 'Alice', role: 'admin', score: 100 },
-    queryableFields: ['name', 'role'],
-    userEmail:       'system@example.com',
-  },
-  { bucketKey: 'users' }
-);
-// meta.id — the new record's ID
-```
+### Download a File
 
-#### `db.records.update(payload, options)`
+Returns the file as an `ArrayBuffer`.
 
 ```ts
-await db.records.update(
-  {
-    recordId:             'rec_abc',
-    values:               { score: 150 },
-    track_record_history: true,
-    reason:               'Manual score adjustment',
-  },
-  { bucketKey: 'users' }
+const { data: buffer, error } = await hydrous.storage.download(
+  'ssk_my_bucket_key',
+  'avatars/alice.jpg'
 );
+
+if (buffer) {
+  // Browser: display image
+  const blob = new Blob([buffer], { type: 'image/jpeg' });
+  img.src    = URL.createObjectURL(blob);
+
+  // Node: write to disk
+  import { writeFileSync } from 'fs';
+  writeFileSync('alice.jpg', Buffer.from(buffer));
+}
 ```
 
-#### `db.records.batchInsert(payload, options)`
+---
+
+### Batch Download
 
 ```ts
-const result = await db.records.batchInsert(
+const { data: files } = await hydrous.storage.batchDownload(
+  'ssk_my_bucket_key',
+  ['reports/jan.pdf', 'reports/feb.pdf', 'reports/mar.pdf'],
   {
-    records:         [{ name: 'Alice', score: 99 }, { name: 'Bob', score: 82 }],
-    queryableFields: ['name'],
-    userEmail:       'import@example.com',
-  },
-  { bucketKey: 'users' }
+    concurrency: 3,
+    autoSave:    true,          // browser: auto-triggers Save dialog per file
+    onProgress:  (p) => {
+      console.log(`${p.path}: ${p.status}`);   // 'pending' | 'success' | 'error'
+    },
+  }
 );
-// result.meta.failed — number of records that failed
+
+// files[n].content  — ArrayBuffer
+// files[n].mimeType — string
+// files[n].path     — original path
+// files[n].size     — bytes
 ```
 
 ---
 
-### Auth
-
-All methods live on `db.auth`. Auth routes use `authKey` and do **not** require a `bucketKey`.
-
-| Method | Description |
-|---|---|
-| `signUp(payload, opts?)` | Register a new user |
-| `signIn(payload, opts?)` | Authenticate with email + password |
-| `signOut(payload, opts?)` | Revoke session(s) |
-| `validateSession(sessionId, opts?)` | Verify a session is valid |
-| `refreshSession(refreshToken, opts?)` | Rotate session using refresh token |
-| `getUser(userId, opts?)` | Fetch user by ID |
-| `listUsers(opts?)` | Paginated user list |
-| `listAllUsers(opts?)` | All users (auto-paginates) |
-| `updateUser(payload, opts?)` | Update user profile |
-| `deleteUser(userId, opts?)` | Soft-delete a user |
-| `changePassword(payload, opts?)` | Change password (requires old password) |
-| `requestPasswordReset(payload, opts?)` | Trigger reset email |
-| `confirmPasswordReset(payload, opts?)` | Confirm reset with token |
-| `requestEmailVerification(payload, opts?)` | Trigger verification email |
-| `confirmEmailVerification(payload, opts?)` | Confirm email with token |
-| `lockAccount(payload, opts?)` | Lock account for a duration |
-| `unlockAccount(userId, opts?)` | Unlock account |
-
-#### Auth flow example
-
-```ts
-// 1. Sign up
-const { data: user, session } = await db.auth.signUp({
-  email:    'alice@example.com',
-  password: 'Str0ng@Pass!',
-  fullName: 'Alice Smith',
-});
-
-// 2. Store session tokens
-const { sessionId, refreshToken, expiresAt } = session;
+### List Files & Folders
 
-// 3. On each request, validate the session
-const { data: currentUser } = await db.auth.validateSession(sessionId);
+```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)
+});
 
-// 4. Before session expires, refresh it
-const { session: newSession } = await db.auth.refreshSession(refreshToken);
+for (const item of data.items) {
+  if (item.type === 'folder') {
+    console.log('📁', item.path);
+  } else {
+    console.log('📄', item.path, item.size, 'bytes');
+  }
+}
 
-// 5. Sign out
-await db.auth.signOut({ sessionId });
+// Paginate
+if (data.pagination.hasNextPage) {
+  const page2 = await hydrous.storage.list('ssk_my_bucket_key', {
+    prefix: 'avatars/',
+    cursor: data.pagination.nextCursor,
+  });
+}
 ```
 
 ---
 
-### Analytics
+### File Metadata
 
-All methods live on `db.analytics`. Every method requires a `bucketKey` option.
+```ts
+const { data: meta } = await hydrous.storage.metadata(
+  'ssk_my_bucket_key',
+  'avatars/alice.jpg'
+);
 
-| Method | Server `queryType` | Description |
-|---|---|---|
-| `count({ bucketKey, ...opts })` | `"count"` | Total record count |
-| `distribution(field, { bucketKey, ...opts })` | `"distribution"` | Value histogram for a field |
-| `sum(field, { bucketKey, ...opts })` | `"sum"` | Sum a numeric field, with optional group-by |
-| `timeSeries({ bucketKey, ...opts })` | `"timeSeries"` | Record count over time |
-| `fieldTimeSeries(field, { bucketKey, ...opts })` | `"fieldTimeSeries"` | Numeric field aggregated over time |
-| `topN(field, n, { bucketKey, ...opts })` | `"topN"` | Top N field values by frequency |
-| `stats(field, { bucketKey, ...opts })` | `"stats"` | min/max/avg/stddev/p50/p90/p99 |
-| `records({ bucketKey, ...opts })` | `"records"` | Filtered + paginated raw records |
-| `multiMetric(metrics, { bucketKey, ...opts })` | `"multiMetric"` | Multiple aggregations in one call |
-| `storageStats({ bucketKey, ...opts })` | `"storageStats"` | Bucket storage usage |
-| `crossBucket({ bucketKey, bucketKeys, ...opts })` | `"crossBucket"` | Compare metric across buckets |
-| `query(payload, { bucketKey, ...opts })` | any | Raw query — full control |
+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);
+```
 
-#### Date ranges
+---
 
-All analytics methods accept a `dateRange` option:
+### Delete a File
 
 ```ts
-const dateRange = { startDate: '2025-01-01', endDate: '2025-12-31' };
-// Or scope to a year / month
-const dateRange = { year: '2025', month: '03' };
+const { error } = await hydrous.storage.deleteFile(
+  'ssk_my_bucket_key',
+  'avatars/old-photo.jpg'
+);
 ```
 
-#### Examples
+---
+
+### Delete a Folder
+
+Recursively deletes the folder and everything inside it.
 
 ```ts
-// Total records
-const { data } = await db.analytics.count({ bucketKey: 'orders' });
-console.log(data.count);
+await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
+```
 
-// Status breakdown
-const { data } = await db.analytics.distribution('status', { bucketKey: 'orders' });
-// [{ value: 'active', count: 80 }, { value: 'archived', count: 20 }]
+---
 
-// Monthly revenue for Q1
-const { data } = await db.analytics.sum('amount', {
-  bucketKey:  'orders',
-  groupBy:    'region',
-  dateRange:  { startDate: '2025-01-01', endDate: '2025-03-31' },
-});
+### Create a Folder
 
-// Daily signups this week
-const { data } = await db.analytics.timeSeries({
-  bucketKey:   'users',
-  granularity: 'day',
-  dateRange:   { startDate: '2025-03-01' },
-});
+```ts
+await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
+```
 
-// Score percentiles
-const { data } = await db.analytics.stats('score', { bucketKey: 'users' });
-console.log(data.avg, data.p90, data.p99);
+---
 
-// Top 5 countries
-const { data } = await db.analytics.topN('country', 5, { bucketKey: 'users' });
+### Move a File
 
-// Dashboard stats — one round-trip for multiple metrics
-const { data } = await db.analytics.multiMetric(
-  [
-    { name: 'totalRevenue', field: 'amount', aggregation: 'sum' },
-    { name: 'avgScore',     field: 'score',  aggregation: 'avg' },
-    { name: 'userCount',    field: 'userId', aggregation: 'count' },
-  ],
-  { bucketKey: 'orders' }
+```ts
+await hydrous.storage.move(
+  'ssk_my_bucket_key',
+  'drafts/report.pdf',
+  'published/report.pdf'
 );
-console.log(data.totalRevenue, data.avgScore);
-
-// Storage usage
-const { data } = await db.analytics.storageStats({ bucketKey: 'orders' });
-console.log(data.totalRecords, data.totalBytes);
-
-// Cross-bucket revenue comparison
-const { data } = await db.analytics.crossBucket({
-  bucketKey:   'sales-2025',
-  bucketKeys:  ['sales-2024', 'sales-2025'],
-  field:       'amount',
-  aggregation: 'sum',
-});
-
-// Raw records with filters
-const { data } = await db.analytics.records({
-  bucketKey:    'users',
-  filters:      [{ field: 'role', op: '==', value: 'admin' }],
-  selectFields: ['email', 'createdAt'],
-  limit:        50,
-});
-console.log(data.data, data.hasMore);
 ```
 
 ---
 
-## Error Handling
+### Copy a File
 
 ```ts
-import { HydrousError, HydrousNetworkError, HydrousTimeoutError } from 'hydrousdb';
-
-try {
-  await db.records.get('rec_does_not_exist', { bucketKey: 'users' });
-} catch (err) {
-  if (err instanceof HydrousError) {
-    console.error(err.message);   // human-readable message
-    console.error(err.status);    // HTTP status code (e.g. 404)
-    console.error(err.code);      // machine-readable code (e.g. 'NOT_FOUND')
-    console.error(err.details);   // validation error details array
-    console.error(err.requestId); // server request ID for support
-  } else if (err instanceof HydrousTimeoutError) {
-    console.error('Request timed out');
-  } else if (err instanceof HydrousNetworkError) {
-    console.error('Network failure:', err.cause);
-  }
-}
+await hydrous.storage.copy(
+  'ssk_my_bucket_key',
+  'templates/invoice.pdf',
+  'invoices/invoice-001.pdf'
+);
 ```
 
 ---
 
-## Pagination
+### Signed URLs
 
-HydrousDB uses opaque cursor strings for pagination.
+Generate a time-limited public URL for a private file.
 
 ```ts
-// Manual pagination
-let cursor: string | null = null;
+const { data } = await hydrous.storage.signedUrl(
+  'ssk_my_bucket_key',
+  'contracts/agreement.pdf',
+  { expiresIn: 300 }   // 5 minutes (default: 3600 = 1 hour)
+);
 
-do {
-  const { data, meta } = await db.records.query({
-    bucketKey: 'orders',
-    limit:     100,
-    cursor:    cursor ?? undefined,
-  });
+console.log(data.signedUrl);   // share this — expires at data.expiresAt
+```
 
-  processBatch(data);
-  cursor = meta.nextCursor;
-} while (cursor);
+---
 
-// — OR — let the SDK handle it
-const allRecords = await db.records.queryAll({
-  bucketKey: 'orders',
-  filters:   [{ field: 'status', op: '==', value: 'active' }],
-});
+### Bucket Stats
+
+```ts
+const { data: stats } = await hydrous.storage.stats('ssk_my_bucket_key');
+
+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
+## 7. Error Handling
 
-All types are exported from the root package:
+Every method returns `{ data, error }`. `error` is `null` on success.
 
 ```ts
-import type {
-  HydrousRecord,
-  QueryOptions,
-  InsertRecordPayload,
-  AuthUser,
-  SessionInfo,
-  HydrousConfig,
-  BucketOptions,
-  Filter,
-} from 'hydrousdb';
+const { data, error } = await hydrous.storage.upload('ssk_key', file);
+
+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)
+}
 ```
 
-Use the generic `query<T>` overload to type your records:
+### Catching thrown errors
 
-```ts
-interface Product {
-  name:     string;
-  price:    number;
-  category: string;
-}
+If you prefer `try/catch`, import `isHydrousError`:
 
-const { data } = await db.records.query<Product>({
-  bucketKey: 'products',
-  filters:   [{ field: 'category', op: '==', value: 'shoes' }],
-});
+```ts
+import { isHydrousError } from 'hydrous';
 
-// data is (Product & HydrousRecord)[]
-console.log(data[0].name, data[0].price);
+try {
+  // ...
+} catch (err) {
+  if (isHydrousError(err)) {
+    console.error(err.code, err.message);
+  }
+}
 ```
 
----
+### Common error codes
+
+| 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                 |
 
-## Migration from v1
+---
 
-v2 introduces two breaking changes:
+## 8. TypeScript Types Reference
 
-### 1. `bucketKey` moves from `createClient` to per-call options
+### `UploadProgress`
 
 ```ts
-// v1
-const db = createClient({ authKey: 'ak_...', bucketKey: 'users' });
-await db.records.query({ limit: 50 });
+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;
+}
 
-// v2
-const db = createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
-await db.records.query({ bucketKey: 'users', limit: 50 });
+type UploadStage = 'pending' | 'compressing' | 'uploading' | 'done' | 'error';
 ```
 
-### 2. `securityKey` replaces the implicit credential
-
-In v1 the SDK incorrectly used `bucketKey` as both the bucket identifier and the security credential in the URL. v2 adds an explicit `securityKey` that maps to the server's `:key` parameter.
+### `UploadResult`
 
 ```ts
-// v1 (broken — used bucketKey as both segments)
-createClient({ authKey: 'ak_...', bucketKey: 'users' });
-// → /api/users/users  ❌
-
-// v2 (correct)
-createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
-// → /api/users/sk_...  ✅  (bucketKey passed per-call)
+interface UploadResult {
+  path:         string;
+  compressed:   boolean;
+  originalSize: number;
+  storedSize:   number;
+  spaceSaved:   number;
+  mimeType:     string;
+}
 ```
 
-**Quick migration checklist:**
-1. Add `securityKey` to your `createClient` call
-2. Remove `bucketKey` from `createClient`
-3. Add `{ bucketKey: '...' }` to every `db.records.*` and `db.analytics.*` call
-4. Auth calls (`db.auth.*`) are unchanged
+### `StorageItem` (from `list()`)
 
----
+```ts
+interface StorageItem {
+  name:         string;
+  path:         string;
+  type:         'file' | 'folder';
+  size?:        number | null;
+  mimeType?:    string | null;
+  isCompressed?: boolean;
+  updatedAt?:   string | null;
+}
+```
 
-## Contributing
+### `StorageStats`
 
-1. Fork the repo and clone it
-2. `npm install`
-3. `npm run dev` — TypeScript watch mode
-4. `npm test` — run the test suite
-5. Open a PR 🚀
+```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%"
+}
+```
 
 ---
 
 ## License
 
-MIT © HydrousDB
+MIT © Hydrous