hydrousdb 1.1.0 → 2.0.0

package/README.md

@@ -13,6 +13,7 @@
 
 - [Features](#features)
 - [Installation](#installation)
+- [Key Concepts](#key-concepts)
 - [Quick Start](#quick-start)
 - [Framework Guides](#framework-guides)
   - [Next.js (App Router)](#nextjs-app-router)
@@ -28,6 +29,7 @@
 - [Error Handling](#error-handling)
 - [Pagination](#pagination)
 - [TypeScript](#typescript)
+- [Migration from v1](#migration-from-v1)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -36,6 +38,7 @@
 ## Features
 
 - ✅ **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
@@ -59,34 +62,66 @@ yarn add hydrousdb
 
 ---
 
+## Key Concepts
+
+### Two keys, one client
+
+The SDK separates two distinct credentials:
+
+| 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 |
+
+### Bucket per call
+
+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.
+
+```ts
+const db = createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
+
+// 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' });
+```
+
+---
+
 ## Quick Start
 
 ```ts
 import { createClient } from 'hydrousdb';
 
 const db = createClient({
-  apiKey:    'your-api-key',
-  bucketKey: 'your-bucket-key',
+  authKey:     'your-auth-key',
+  securityKey: 'your-security-key',
 });
 
-// Insert a record
-const { data, meta } = await db.records.insert({
-  values: { name: 'Alice', score: 99 },
-  queryableFields: ['name'],
-});
+// 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);
 
-// Query records
+// Query records from the 'users' bucket
 const { data: records } = await db.records.query({
+  bucketKey: 'users',
   filters: [{ field: 'score', op: '>=', value: 90 }],
   limit: 20,
 });
 
-// Auth — sign a user in
+// Auth — no bucketKey needed
 const { data: user, session } = await db.auth.signIn({
   email: 'alice@example.com',
   password: 'Str0ng@Pass!',
 });
+
+// Analytics
+const { data: stats } = await db.analytics.count({ bucketKey: 'users' });
+console.log(stats.count);
 ```
 
 ---
@@ -101,10 +136,9 @@ const { data: user, session } = await db.auth.signIn({
 // lib/db.ts
 import { createClient } from 'hydrousdb';
 
-// The client is re-used across all server components in the same process
 export const db = createClient({
-  apiKey:    process.env.HYDROUS_API_KEY!,
-  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
+  authKey:     process.env.HYDROUS_AUTH_KEY!,
+  securityKey: process.env.HYDROUS_SECURITY_KEY!,
 });
 ```
 
@@ -116,6 +150,7 @@ 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',
@@ -142,10 +177,10 @@ 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'],
-    });
+    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) {
@@ -182,8 +217,8 @@ export const config = { matcher: ['/dashboard/:path*'] };
 
 ```env
 # .env.local
-HYDROUS_API_KEY=your-api-key
-HYDROUS_BUCKET_KEY=your-bucket-key
+HYDROUS_AUTH_KEY=your-auth-key
+HYDROUS_SECURITY_KEY=your-security-key
 ```
 
 ---
@@ -196,14 +231,14 @@ import type { NextApiRequest, NextApiResponse } from 'next';
 import { createClient, HydrousError } from 'hydrousdb';
 
 const db = createClient({
-  apiKey:    process.env.HYDROUS_API_KEY!,
-  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
+  authKey:     process.env.HYDROUS_AUTH_KEY!,
+  securityKey: process.env.HYDROUS_SECURITY_KEY!,
 });
 
 export default async function handler(req: NextApiRequest, res: NextApiResponse) {
   if (req.method === 'GET') {
     try {
-      const result = await db.records.query({ limit: 50 });
+      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 });
@@ -229,8 +264,8 @@ export default defineNuxtPlugin(() => {
   const config = useRuntimeConfig();
 
   const db = createClient({
-    apiKey:    config.hydrousApiKey as string,
-    bucketKey: config.hydrousBucketKey as string,
+    authKey:     config.hydrousAuthKey as string,
+    securityKey: config.hydrousSecurityKey as string,
   });
 
   return { provide: { db } };
@@ -241,8 +276,8 @@ export default defineNuxtPlugin(() => {
 // 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
+    hydrousAuthKey:     '',  // NUXT_HYDROUS_AUTH_KEY
+    hydrousSecurityKey: '',  // NUXT_HYDROUS_SECURITY_KEY
   },
 });
 ```
@@ -254,7 +289,7 @@ export default defineNuxtConfig({
 const { $db } = useNuxtApp();
 
 const { data: records, pending } = await useAsyncData('records', () =>
-  $db.records.query({ limit: 20 })
+  $db.records.query({ bucketKey: 'products', limit: 20 })
 );
 </script>
 
@@ -273,8 +308,8 @@ const { data: records, pending } = await useAsyncData('records', () =>
 import { createClient } from 'hydrousdb';
 
 const db = createClient({
-  apiKey:    import.meta.env.VITE_HYDROUS_API_KEY,
-  bucketKey: import.meta.env.VITE_HYDROUS_BUCKET_KEY,
+  authKey:     import.meta.env.VITE_HYDROUS_AUTH_KEY,
+  securityKey: import.meta.env.VITE_HYDROUS_SECURITY_KEY,
 });
 
 export function useHydrous() {
@@ -292,11 +327,11 @@ import { useEffect, useState } from 'react';
 import { createClient, HydrousRecord, HydrousError } from 'hydrousdb';
 
 const db = createClient({
-  apiKey:    import.meta.env.VITE_HYDROUS_API_KEY,
-  bucketKey: import.meta.env.VITE_HYDROUS_BUCKET_KEY,
+  authKey:     import.meta.env.VITE_HYDROUS_AUTH_KEY,
+  securityKey: import.meta.env.VITE_HYDROUS_SECURITY_KEY,
 });
 
-export function useRecords(limit = 20) {
+export function useRecords(bucketKey: string, limit = 20) {
   const [records, setRecords] = useState<HydrousRecord[]>([]);
   const [loading, setLoading] = useState(true);
   const [error, setError]     = useState<string | null>(null);
@@ -304,13 +339,13 @@ export function useRecords(limit = 20) {
   useEffect(() => {
     const controller = new AbortController();
 
-    db.records.query({ limit }, { signal: controller.signal })
+    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));
 
     return () => controller.abort();
-  }, [limit]);
+  }, [bucketKey, limit]);
 
   return { records, loading, error };
 }
@@ -326,15 +361,15 @@ import express from 'express';
 import { createClient, HydrousError } from 'hydrousdb';
 
 const db  = createClient({
-  apiKey:    process.env.HYDROUS_API_KEY!,
-  bucketKey: process.env.HYDROUS_BUCKET_KEY!,
+  authKey:     process.env.HYDROUS_AUTH_KEY!,
+  securityKey: process.env.HYDROUS_SECURITY_KEY!,
 });
 const app = express();
 app.use(express.json());
 
-app.get('/records', async (req, res) => {
+app.get('/orders', async (req, res) => {
   try {
-    const result = await db.records.query({ limit: 50 });
+    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 });
@@ -355,89 +390,101 @@ app.listen(3000, () => console.log('Listening on :3000'));
 import { createClient } from 'hydrousdb';
 
 const db = createClient({
-  apiKey:    string,           // required — your HydrousDB API 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)
+  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)
 });
 ```
 
+> **Note:** `bucketKey` is no longer part of the client config. It is passed as an option on each individual records and analytics call.
+
 ---
 
 ### Records
 
-All methods live on `db.records`.
+All methods live on `db.records`. Every method requires a `bucketKey` option.
 
 | 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 |
-
-#### `db.records.get(recordId, options?)`
+| `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 |
+
+#### `db.records.get(recordId, options)`
 
 ```ts
-const { data, history } = await db.records.get('rec_abc', { showHistory: true });
+const { data, history } = await db.records.get('rec_abc', {
+  bucketKey:   'users',
+  showHistory: true,
+});
 ```
 
-#### `db.records.query(options?)`
+#### `db.records.query(options)`
 
 ```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
+  bucketKey:  'orders',
+  filters:    [{ field: 'status', op: '==', value: 'active' }],
+  timeScope:  '30d',
+  sortOrder:  'desc',
+  limit:      50,
+  cursor:     meta.nextCursor ?? undefined,
+  fields:     'id,name,status',
 });
 ```
 
-**Filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`
+**Filter operators:** `==` `!=` `>` `<` `>=` `<=` `contains`  
 **Max 3 filters per query.**
 
-#### `db.records.insert(payload)`
+#### `db.records.insert(payload, options)`
 
 ```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',
-});
+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
 ```
 
-#### `db.records.update(payload)`
+#### `db.records.update(payload, options)`
 
 ```ts
-await db.records.update({
-  recordId: 'rec_abc',
-  values:   { score: 150 },
-  track_record_history: true,  // snapshot the previous version
-  reason: 'Manual score adjustment',
-});
+await db.records.update(
+  {
+    recordId:             'rec_abc',
+    values:               { score: 150 },
+    track_record_history: true,
+    reason:               'Manual score adjustment',
+  },
+  { bucketKey: 'users' }
+);
 ```
 
-#### `db.records.batchInsert(payload)`
+#### `db.records.batchInsert(payload, options)`
 
 ```ts
-const result = await db.records.batchInsert({
-  records: [
-    { name: 'Alice', score: 99 },
-    { name: 'Bob',   score: 82 },
-  ],
-  queryableFields: ['name'],
-  userEmail: 'import@example.com',
-});
+const result = await db.records.batchInsert(
+  {
+    records:         [{ name: 'Alice', score: 99 }, { name: 'Bob', score: 82 }],
+    queryableFields: ['name'],
+    userEmail:       'import@example.com',
+  },
+  { bucketKey: 'users' }
+);
 // result.meta.failed — number of records that failed
 ```
 
@@ -445,7 +492,7 @@ const result = await db.records.batchInsert({
 
 ### Auth
 
-All methods live on `db.auth`.
+All methods live on `db.auth`. Auth routes use `authKey` and do **not** require a `bucketKey`.
 
 | Method | Description |
 |---|---|
@@ -477,7 +524,7 @@ const { data: user, session } = await db.auth.signUp({
   fullName: 'Alice Smith',
 });
 
-// 2. Store session tokens (e.g. in a cookie or localStorage)
+// 2. Store session tokens
 const { sessionId, refreshToken, expiresAt } = session;
 
 // 3. On each request, validate the session
@@ -494,32 +541,30 @@ await db.auth.signOut({ sessionId });
 
 ### Analytics
 
-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.
+All methods live on `db.analytics`. Every method requires a `bucketKey` option.
 
 | 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 |
+| `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 |
 
 #### Date ranges
 
 All analytics methods accept a `dateRange` option:
 
 ```ts
-// Scope to a specific date window
 const dateRange = { startDate: '2025-01-01', endDate: '2025-12-31' };
-
-// Or scope to a year / month / day
+// Or scope to a year / month
 const dateRange = { year: '2025', month: '03' };
 ```
 
@@ -527,57 +572,63 @@ const dateRange = { year: '2025', month: '03' };
 
 ```ts
 // Total records
-const { data } = await db.analytics.count();
+const { data } = await db.analytics.count({ bucketKey: 'orders' });
 console.log(data.count);
 
 // Status breakdown
-const { data } = await db.analytics.distribution('status');
+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', {
-  groupBy: 'region',
-  dateRange: { startDate: '2025-01-01', endDate: '2025-03-31' },
+  bucketKey:  'orders',
+  groupBy:    'region',
+  dateRange:  { startDate: '2025-01-01', endDate: '2025-03-31' },
 });
 
 // Daily signups this week
 const { data } = await db.analytics.timeSeries({
+  bucketKey:   'users',
   granularity: 'day',
-  dateRange: { startDate: '2025-03-01' },
+  dateRange:   { startDate: '2025-03-01' },
 });
 
 // Score percentiles
-const { data } = await db.analytics.stats('score');
+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);
+const { data } = await db.analytics.topN('country', 5, { bucketKey: 'users' });
 
 // 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' },
-]);
+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' }
+);
 console.log(data.totalRevenue, data.avgScore);
 
 // Storage usage
-const { data } = await db.analytics.storageStats();
+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 (supports: == != > < >= <= CONTAINS)
+// Raw records with filters
 const { data } = await db.analytics.records({
-  filters: [{ field: 'role', op: '==', value: 'admin' }],
+  bucketKey:    'users',
+  filters:      [{ field: 'role', op: '==', value: 'admin' }],
   selectFields: ['email', 'createdAt'],
-  limit: 50,
-  offset: 0,
+  limit:        50,
 });
 console.log(data.data, data.hasMore);
 ```
@@ -586,13 +637,11 @@ console.log(data.data, data.hasMore);
 
 ## Error Handling
 
-The SDK throws typed errors you can `instanceof` check:
-
 ```ts
 import { HydrousError, HydrousNetworkError, HydrousTimeoutError } from 'hydrousdb';
 
 try {
-  await db.records.get('rec_does_not_exist');
+  await db.records.get('rec_does_not_exist', { bucketKey: 'users' });
 } catch (err) {
   if (err instanceof HydrousError) {
     console.error(err.message);   // human-readable message
@@ -620,17 +669,19 @@ let cursor: string | null = null;
 
 do {
   const { data, meta } = await db.records.query({
-    limit:  100,
-    cursor: cursor ?? undefined,
+    bucketKey: 'orders',
+    limit:     100,
+    cursor:    cursor ?? undefined,
   });
 
   processBatch(data);
   cursor = meta.nextCursor;
 } while (cursor);
 
-// — OR — let the SDK handle it for you
+// — OR — let the SDK handle it
 const allRecords = await db.records.queryAll({
-  filters: [{ field: 'status', op: '==', value: 'active' }],
+  bucketKey: 'orders',
+  filters:   [{ field: 'status', op: '==', value: 'active' }],
 });
 ```
 
@@ -648,21 +699,23 @@ import type {
   AuthUser,
   SessionInfo,
   HydrousConfig,
+  BucketOptions,
   Filter,
 } from 'hydrousdb';
 ```
 
-You can also use the generic `query<T>` overload to type your records:
+Use the generic `query<T>` overload to type your records:
 
 ```ts
 interface Product {
-  name: string;
-  price: number;
+  name:     string;
+  price:    number;
   category: string;
 }
 
 const { data } = await db.records.query<Product>({
-  filters: [{ field: 'category', op: '==', value: 'shoes' }],
+  bucketKey: 'products',
+  filters:   [{ field: 'category', op: '==', value: 'shoes' }],
 });
 
 // data is (Product & HydrousRecord)[]
@@ -671,6 +724,44 @@ console.log(data[0].name, data[0].price);
 
 ---
 
+## Migration from v1
+
+v2 introduces two breaking changes:
+
+### 1. `bucketKey` moves from `createClient` to per-call options
+
+```ts
+// v1
+const db = createClient({ authKey: 'ak_...', bucketKey: 'users' });
+await db.records.query({ limit: 50 });
+
+// v2
+const db = createClient({ authKey: 'ak_...', securityKey: 'sk_...' });
+await db.records.query({ bucketKey: 'users', limit: 50 });
+```
+
+### 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.
+
+```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)
+```
+
+**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
+
+---
+
 ## Contributing
 
 1. Fork the repo and clone it