hydrousdb 1.1.1 → 2.0.1

package/README.md

@@ -1,686 +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)
-- [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)
-- [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
-
-- ✅ **Full TypeScript** — every method and response is fully typed
-- ✅ **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)
+## 1. Quick Start
 
----
+```ts
+import { createClient } from 'hydrous';
 
-## Installation
+const hydrous = createClient({
+  url:    'https://api.yourapp.hydrous.app',
+  apiKey: 'hk_live_…',
+});
 
-```bash
-npm install hydrousdb
-# or
-pnpm add hydrousdb
-# or
-yarn add hydrousdb
+// 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}%`),
+  }
+);
 ```
 
-> **Node.js ≥ 18** is required (uses native `fetch`). For Node 16/17, polyfill `fetch` with `node-fetch` or `undici`.
-
 ---
 
-## Quick Start
+## 2. Configuration
 
 ```ts
-import { createClient } from 'hydrousdb';
-
-const db = createClient({
-  authKey:    'your-auth-key',
-  bucketKey: 'your-bucket-key',
-});
+import { HydrousClient } from 'hydrous';
 
-// Insert a record
-const { data, meta } = await db.records.insert({
-  values: { name: 'Alice', score: 99 },
-  queryableFields: ['name'],
-});
-console.log('Created record:', meta.id);
-
-// Query records
-const { data: records } = await db.records.query({
-  filters: [{ field: 'score', op: '>=', value: 90 }],
-  limit: 20,
-});
-
-// Auth — sign a user in
-const { data: user, session } = await db.auth.signIn({
-  email: 'alice@example.com',
-  password: 'Str0ng@Pass!',
+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)
 });
 ```
 
----
+| 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) |
 
-## Framework Guides
+---
 
-### Next.js (App Router)
+## 3. Auth
 
-**1. Create a shared client singleton**
+### Sign Up
 
 ```ts
-// lib/db.ts
-import { createClient } from 'hydrousdb';
-
-// The client is re-used across all server components in the same process
-export const db = createClient({
-  authKey:    process.env.HYDROUS_AUTH_KEY!,
-  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
+const { data, error } = await hydrous.auth.signUp({
+  email:    'user@example.com',
+  password: 'supersecret',
+  metadata: { plan: 'pro' },   // optional
 });
-```
 
-**2. Use in a Server Component**
+if (data) {
+  console.log('New user:', data.user.id);
+  console.log('Access token:', data.accessToken);
+}
+```
 
-```tsx
-// app/products/page.tsx
-import { db } from '@/lib/db';
+### Sign In
 
-export default async function ProductsPage() {
-  const { data: products } = await db.records.query({
-    filters: [{ field: 'category', op: '==', value: 'shoes' }],
-    limit: 24,
-    sortOrder: 'desc',
-  });
+```ts
+const { data, error } = await hydrous.auth.signIn({
+  email:    'user@example.com',
+  password: 'supersecret',
+});
 
-  return (
-    <ul>
-      {products.map(p => (
-        <li key={p.id}>{String(p.name)}</li>
-      ))}
-    </ul>
-  );
+if (data) {
+  console.log('Welcome back,', data.user.email);
 }
 ```
 
-**3. Use in a Route Handler**
+### Sign Out
 
 ```ts
-// app/api/records/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { db } from '@/lib/db';
-import { HydrousError } from 'hydrousdb';
+await hydrous.auth.signOut();
+```
 
-export async function POST(req: NextRequest) {
-  try {
-    const body = await req.json();
-    const result = await db.records.insert({
-      values: body,
-      queryableFields: ['email', 'name'],
-    });
-    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 });
-  }
-}
+### Get Current User
+
+```ts
+const { data: user } = await hydrous.auth.getUser();
+console.log(user?.email);
 ```
 
-**4. Auth middleware example**
+### Refresh Session
 
 ```ts
-// middleware.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { db } from '@/lib/db';
+const { data: session } = await hydrous.auth.refreshSession();
+```
 
-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));
-  }
-}
+## 4. Records
+
+### Insert
+
+Single record:
 
-export const config = { matcher: ['/dashboard/:path*'] };
+```ts
+const { data, error } = await hydrous.records.insert('users', {
+  name:  'Alice',
+  email: 'alice@example.com',
+  role:  'admin',
+});
 ```
 
-**5. Environment variables**
+Bulk insert (array):
 
-```env
-# .env.local
-HYDROUS_API_KEY=your-api-key
-HYDROUS_BUCKET_KEY=your-bucket-key
+```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`);
 ```
 
----
+### Select / Query
+
+```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
+});
+```
 
-### Next.js (Pages Router)
+Multiple filters:
 
 ```ts
-// pages/api/records.ts
-import type { NextApiRequest, NextApiResponse } from 'next';
-import { createClient, HydrousError } from 'hydrousdb';
+import { eq, gt, inArray } from 'hydrous';
 
-const db = createClient({
-  authKey:    process.env.HYDROUS_AUTH_KEY!,
-  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
+const { data } = await hydrous.records.select('orders', {
+  where: [
+    eq('status',  'shipped'),
+    gt('total',   100),
+    inArray('tag', ['vip', 'priority']),
+  ],
 });
+```
 
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  if (req.method === 'GET') {
-    try {
-      const result = await db.records.query({ 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();
-}
+### Get by ID
+
+```ts
+const { data: user } = await hydrous.records.get('users', 'user_abc123');
 ```
 
----
+### Update
 
-### Vue 3 / Nuxt 3
+```ts
+const { data } = await hydrous.records.update('users', 'user_abc123', {
+  name: 'Alice Smith',
+});
+```
 
-**Nuxt 3 — plugin**
+### Delete
 
 ```ts
-// plugins/hydrousdb.ts
-import { createClient } from 'hydrousdb';
+const { error } = await hydrous.records.delete('users', 'user_abc123');
+```
 
-export default defineNuxtPlugin(() => {
-  const config = useRuntimeConfig();
+### Query Helpers
 
-  const db = createClient({
-    authKey:    config.hydrousAuthKey as string,
-    bucketKey: config.hydrousBucketKey as string,
-  });
+| 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 (…)`        |
 
-  return { provide: { db } };
-});
+```ts
+import { eq, gt, inArray } from 'hydrous';
 ```
 
+---
+
+## 5. Analytics
+
+### Track an Event
+
 ```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  runtimeConfig: {
-    hydrousApiKey:    '',  // Set via NUXT_HYDROUS_API_KEY env var
-    hydrousBucketKey: '',  // Set via NUXT_HYDROUS_BUCKET_KEY env var
-  },
+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({ 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,
-  bucketKey: import.meta.env.VITE_HYDROUS_BUCKET_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,
-  bucketKey: import.meta.env.VITE_HYDROUS_BUCKET_KEY,
-});
+### How Bucket Keys Work
 
-export function useRecords(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({ 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();
-  }, [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!,
-  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
-});
-const app = express();
-app.use(express.json());
-
-app.get('/records', async (req, res) => {
-  try {
-    const result = await db.records.query({ 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 service key
-  bucketKey: string,           // required — your bucket identifier
-  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`;
+}
 ```
 
----
+**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`.
+---
 
-| Method | Description |
-|---|---|
-| `get(recordId, opts?)` | Fetch a single record |
-| `getSnapshot(recordId, generation, opts?)` | Fetch a historical version |
-| `query(opts?)` | Query a collection with filters / pagination |
-| `queryAll(opts?)` | Fetch all pages automatically |
-| `insert(payload, opts?)` | Create a new record |
-| `update(payload, opts?)` | Update an existing record |
-| `delete(recordId, opts?)` | Delete a record |
-| `exists(recordId, opts?)` | HEAD check — returns metadata or `null` |
-| `batchInsert(payload, opts?)` | Insert up to 500 records |
-| `batchUpdate(payload, opts?)` | Update up to 500 records |
-| `batchDelete(payload, 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', { 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({
-  filters:   [{ field: 'status', op: '==', value: 'active' }],
-  timeScope: '30d',
-  sortOrder: 'desc',
-  limit:     50,
-  cursor:    meta.nextCursor ?? undefined, // for pagination
-  fields:    'id,name,status',            // select specific fields
+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)`
+### Download a File
+
+Returns the file as an `ArrayBuffer`.
 
 ```ts
-const { data, meta } = await db.records.insert({
-  values: { name: 'Alice', role: 'admin', score: 100 },
-  queryableFields: ['name', 'role'],   // fields you want to filter by later
-  userEmail: 'system@example.com',
-});
-// meta.id — the new record's ID
+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.update(payload)`
+---
+
+### Batch Download
 
 ```ts
-await db.records.update({
-  recordId: 'rec_abc',
-  values:   { score: 150 },
-  track_record_history: true,  // snapshot the previous version
-  reason: 'Manual score adjustment',
-});
+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'
+    },
+  }
+);
+
+// files[n].content  — ArrayBuffer
+// files[n].mimeType — string
+// files[n].path     — original path
+// files[n].size     — bytes
 ```
 
-#### `db.records.batchInsert(payload)`
+---
+
+### List Files & Folders
 
 ```ts
-const result = await db.records.batchInsert({
-  records: [
-    { name: 'Alice', score: 99 },
-    { name: 'Bob',   score: 82 },
-  ],
-  queryableFields: ['name'],
-  userEmail: 'import@example.com',
+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)
 });
-// result.meta.failed — number of records that failed
+
+for (const item of data.items) {
+  if (item.type === 'folder') {
+    console.log('📁', item.path);
+  } else {
+    console.log('📄', item.path, item.size, 'bytes');
+  }
+}
+
+// Paginate
+if (data.pagination.hasNextPage) {
+  const page2 = await hydrous.storage.list('ssk_my_bucket_key', {
+    prefix: 'avatars/',
+    cursor: data.pagination.nextCursor,
+  });
+}
 ```
 
 ---
 
-### Auth
-
-All methods live on `db.auth`.
-
-| 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',
-});
+### File Metadata
 
-// 2. Store session tokens (e.g. in a cookie or localStorage)
-const { sessionId, refreshToken, expiresAt } = session;
+```ts
+const { data: meta } = await hydrous.storage.metadata(
+  'ssk_my_bucket_key',
+  'avatars/alice.jpg'
+);
+
+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);
+```
 
-// 3. On each request, validate the session
-const { data: currentUser } = await db.auth.validateSession(sessionId);
+---
 
-// 4. Before session expires, refresh it
-const { session: newSession } = await db.auth.refreshSession(refreshToken);
+### Delete a File
 
-// 5. Sign out
-await db.auth.signOut({ sessionId });
+```ts
+const { error } = await hydrous.storage.deleteFile(
+  'ssk_my_bucket_key',
+  'avatars/old-photo.jpg'
+);
 ```
 
 ---
 
-### Analytics
+### Delete a Folder
 
-All methods live on `db.analytics`. Every method maps to a BigQuery-backed analytics query. The server `queryType` string each method sends is noted for reference.
+Recursively deletes the folder and everything inside it.
 
-| Method | Server `queryType` | Description |
-|---|---|---|
-| `count(opts?)` | `"count"` | Total record count |
-| `distribution(field, opts?)` | `"distribution"` | Value histogram for a field |
-| `sum(field, opts?)` | `"sum"` | Sum a numeric field, with optional group-by |
-| `timeSeries(opts?)` | `"timeSeries"` | Record count over time |
-| `fieldTimeSeries(field, opts?)` | `"fieldTimeSeries"` | Numeric field aggregated over time |
-| `topN(field, n, opts?)` | `"topN"` | Top N field values by frequency |
-| `stats(field, opts?)` | `"stats"` | min/max/avg/stddev/p50/p90/p99 |
-| `records(opts?)` | `"records"` | Filtered + paginated raw records |
-| `multiMetric(metrics, opts?)` | `"multiMetric"` | Multiple aggregations in one call |
-| `storageStats(opts?)` | `"storageStats"` | Bucket storage usage |
-| `crossBucket(opts)` | `"crossBucket"` | Compare metric across buckets |
-| `query(payload, opts?)` | any | Raw query — full control |
+```ts
+await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
+```
 
-#### Date ranges
+---
 
-All analytics methods accept a `dateRange` option:
+### Create a Folder
 
 ```ts
-// Scope to a specific date window
-const dateRange = { startDate: '2025-01-01', endDate: '2025-12-31' };
-
-// Or scope to a year / month / day
-const dateRange = { year: '2025', month: '03' };
+await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
 ```
 
-#### Examples
+---
+
+### Move a File
 
 ```ts
-// Total records
-const { data } = await db.analytics.count();
-console.log(data.count);
+await hydrous.storage.move(
+  'ssk_my_bucket_key',
+  'drafts/report.pdf',
+  'published/report.pdf'
+);
+```
 
-// Status breakdown
-const { data } = await db.analytics.distribution('status');
-// [{ value: 'active', count: 80 }, { value: 'archived', count: 20 }]
+---
 
-// Monthly revenue for Q1
-const { data } = await db.analytics.sum('amount', {
-  groupBy: 'region',
-  dateRange: { startDate: '2025-01-01', endDate: '2025-03-31' },
-});
+### Copy a File
 
-// Daily signups this week
-const { data } = await db.analytics.timeSeries({
-  granularity: 'day',
-  dateRange: { startDate: '2025-03-01' },
-});
+```ts
+await hydrous.storage.copy(
+  'ssk_my_bucket_key',
+  'templates/invoice.pdf',
+  'invoices/invoice-001.pdf'
+);
+```
 
-// Score percentiles
-const { data } = await db.analytics.stats('score');
-console.log(data.avg, data.p90, data.p99);
+---
 
-// Top 5 countries
-const { data } = await db.analytics.topN('country', 5);
+### Signed URLs
 
-// 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' },
-]);
-console.log(data.totalRevenue, data.avgScore);
+Generate a time-limited public URL for a private file.
 
-// Storage usage
-const { data } = await db.analytics.storageStats();
-console.log(data.totalRecords, data.totalBytes);
-
-// Cross-bucket revenue comparison
-const { data } = await db.analytics.crossBucket({
-  bucketKeys:  ['sales-2024', 'sales-2025'],
-  field:       'amount',
-  aggregation: 'sum',
-});
+```ts
+const { data } = await hydrous.storage.signedUrl(
+  'ssk_my_bucket_key',
+  'contracts/agreement.pdf',
+  { expiresIn: 300 }   // 5 minutes (default: 3600 = 1 hour)
+);
 
-// Raw records with filters (supports: == != > < >= <= CONTAINS)
-const { data } = await db.analytics.records({
-  filters: [{ field: 'role', op: '==', value: 'admin' }],
-  selectFields: ['email', 'createdAt'],
-  limit: 50,
-  offset: 0,
-});
-console.log(data.data, data.hasMore);
+console.log(data.signedUrl);   // share this — expires at data.expiresAt
 ```
 
 ---
 
-## Error Handling
-
-The SDK throws typed errors you can `instanceof` check:
+### Bucket Stats
 
 ```ts
-import { HydrousError, HydrousNetworkError, HydrousTimeoutError } from 'hydrousdb';
+const { data: stats } = await hydrous.storage.stats('ssk_my_bucket_key');
 
-try {
-  await db.records.get('rec_does_not_exist');
-} 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);
-  }
-}
+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);
 ```
 
 ---
 
-## Pagination
+## 7. Error Handling
 
-HydrousDB uses opaque cursor strings for pagination.
+Every method returns `{ data, error }`. `error` is `null` on success.
 
 ```ts
-// Manual pagination
-let cursor: string | null = null;
+const { data, error } = await hydrous.storage.upload('ssk_key', file);
 
-do {
-  const { data, meta } = await db.records.query({
-    limit:  100,
-    cursor: cursor ?? undefined,
-  });
+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)
+}
+```
 
-  processBatch(data);
-  cursor = meta.nextCursor;
-} while (cursor);
+### Catching thrown errors
 
-// — OR — let the SDK handle it for you
-const allRecords = await db.records.queryAll({
-  filters: [{ field: 'status', op: '==', value: 'active' }],
-});
+If you prefer `try/catch`, import `isHydrousError`:
+
+```ts
+import { isHydrousError } from 'hydrous';
+
+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                 |
+
 ---
 
-## TypeScript
+## 8. TypeScript Types Reference
 
-All types are exported from the root package:
+### `UploadProgress`
 
 ```ts
-import type {
-  HydrousRecord,
-  QueryOptions,
-  InsertRecordPayload,
-  AuthUser,
-  SessionInfo,
-  HydrousConfig,
-  Filter,
-} from 'hydrousdb';
+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;
+}
+
+type UploadStage = 'pending' | 'compressing' | 'uploading' | 'done' | 'error';
 ```
 
-You can also use the generic `query<T>` overload to type your records:
+### `UploadResult`
 
 ```ts
-interface Product {
-  name: string;
-  price: number;
-  category: string;
+interface UploadResult {
+  path:         string;
+  compressed:   boolean;
+  originalSize: number;
+  storedSize:   number;
+  spaceSaved:   number;
+  mimeType:     string;
 }
+```
 
-const { data } = await db.records.query<Product>({
-  filters: [{ field: 'category', op: '==', value: 'shoes' }],
-});
+### `StorageItem` (from `list()`)
 
-// data is (Product & HydrousRecord)[]
-console.log(data[0].name, data[0].price);
+```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