hydrousdb 2.0.1 → 2.0.3

package/dist/index.mjs

@@ -1,14 +1,14 @@
 // src/utils/errors.ts
-var HydrousSDKError = class extends Error {
+var HydrousDBError = class extends Error {
   constructor(message, code = "SDK_ERROR", status) {
     super(message);
-    this.name = "HydrousSDKError";
+    this.name = "HydrousDBError";
     this.code = code;
     this.status = status;
   }
 };
 function toHydrousError(err) {
-  if (err instanceof HydrousSDKError) {
+  if (err instanceof HydrousDBError) {
     return { message: err.message, code: err.code, status: err.status };
   }
   if (err instanceof Error) {
@@ -17,7 +17,7 @@ function toHydrousError(err) {
   return { message: String(err), code: "UNKNOWN_ERROR" };
 }
 function isHydrousError(err) {
-  return err instanceof HydrousSDKError;
+  return err instanceof HydrousDBError;
 }
 
 // src/utils/http.ts
@@ -26,16 +26,14 @@ async function parseResponse(res) {
   try {
     body = await res.json();
   } catch (e) {
-    if (!res.ok) {
-      throw new HydrousSDKError(`HTTP ${res.status}`, "HTTP_ERROR", res.status);
-    }
+    if (!res.ok) throw new HydrousDBError(`HTTP ${res.status}`, "HTTP_ERROR", res.status);
     return void 0;
   }
   if (!res.ok) {
-    const err = body;
-    throw new HydrousSDKError(
-      err.error || err.message || `HTTP ${res.status}`,
-      err.code || "HTTP_ERROR",
+    const e = body;
+    throw new HydrousDBError(
+      e.error || e.message || `HTTP ${res.status}`,
+      e.code || "HTTP_ERROR",
       res.status
     );
   }
@@ -45,15 +43,13 @@ function buildUrl(base, path, params) {
   const url = new URL(path, base.endsWith("/") ? base : base + "/");
   if (params) {
     for (const [k, v] of Object.entries(params)) {
-      if (v !== void 0 && v !== null) {
-        url.searchParams.set(k, String(v));
-      }
+      if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
     }
   }
   return url.toString();
 }
-function mergeHeaders(defaults, overrides) {
-  return { ...defaults, ...overrides };
+function mergeHeaders(a, b) {
+  return { ...a, ...b };
 }
 async function readSSEStream(response, onEvent) {
   if (!response.body) return;
@@ -87,17 +83,32 @@ async function readSSEStream(response, onEvent) {
   }
   if (buf.trim()) flush("");
 }
-function xhrUpload(url, body, headers, onXhrProgress) {
+function parseSSEText(text, onEvent) {
+  const blocks = text.split("\n\n");
+  for (const block of blocks) {
+    if (!block.trim()) continue;
+    let eventType = "message";
+    let dataLine = null;
+    for (const line of block.split("\n")) {
+      if (line.startsWith("event:")) eventType = line.slice(6).trim();
+      if (line.startsWith("data:")) dataLine = line.slice(5).trim();
+    }
+    if (dataLine === null) continue;
+    try {
+      onEvent(eventType, JSON.parse(dataLine));
+    } catch (e) {
+    }
+  }
+}
+function xhrUpload(url, body, headers, onProgress) {
   return new Promise((resolve, reject) => {
     const xhr = new XMLHttpRequest();
     xhr.open("POST", url);
-    for (const [key, val] of Object.entries(headers)) {
-      xhr.setRequestHeader(key, val);
-    }
+    for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
     xhr.responseType = "text";
-    if (onXhrProgress) {
+    if (onProgress) {
       xhr.upload.onprogress = (e) => {
-        if (e.lengthComputable) onXhrProgress(e.loaded, e.total);
+        if (e.lengthComputable) onProgress(e.loaded, e.total);
       };
     }
     xhr.onload = () => {
@@ -107,35 +118,18 @@ function xhrUpload(url, body, headers, onXhrProgress) {
       } else {
         try {
           const d = JSON.parse(xhr.responseText);
-          reject(new HydrousSDKError((_a = d.error) != null ? _a : `HTTP ${xhr.status}`, "HTTP_ERROR", xhr.status));
+          reject(new HydrousDBError((_a = d.error) != null ? _a : `HTTP ${xhr.status}`, "HTTP_ERROR", xhr.status));
         } catch (e) {
-          reject(new HydrousSDKError(`HTTP ${xhr.status}`, "HTTP_ERROR", xhr.status));
+          reject(new HydrousDBError(`HTTP ${xhr.status}`, "HTTP_ERROR", xhr.status));
         }
       }
     };
-    xhr.onerror = () => reject(new HydrousSDKError("Network error", "NETWORK_ERROR"));
-    xhr.onabort = () => reject(new HydrousSDKError("Upload aborted", "UPLOAD_ABORTED"));
-    xhr.ontimeout = () => reject(new HydrousSDKError("Upload timed out", "UPLOAD_TIMEOUT"));
+    xhr.onerror = () => reject(new HydrousDBError("Network error", "NETWORK_ERROR"));
+    xhr.onabort = () => reject(new HydrousDBError("Upload aborted", "UPLOAD_ABORTED"));
+    xhr.ontimeout = () => reject(new HydrousDBError("Upload timed out", "UPLOAD_TIMEOUT"));
     xhr.send(body);
   });
 }
-function parseSSEText(text, onEvent) {
-  const blocks = text.split("\n\n");
-  for (const block of blocks) {
-    if (!block.trim()) continue;
-    let eventType = "message";
-    let dataLine = null;
-    for (const line of block.split("\n")) {
-      if (line.startsWith("event:")) eventType = line.slice(6).trim();
-      if (line.startsWith("data:")) dataLine = line.slice(5).trim();
-    }
-    if (dataLine === null) continue;
-    try {
-      onEvent(eventType, JSON.parse(dataLine));
-    } catch (e) {
-    }
-  }
-}
 
 // src/auth/client.ts
 var AuthClient = class {
@@ -144,23 +138,13 @@ var AuthClient = class {
     this.baseUrl = config.url;
     this.headers = {
       "Content-Type": "application/json",
-      "Authorization": `Bearer ${config.apiKey}`
+      "Authorization": `Bearer ${config.authKey}`
     };
   }
-  // ─── SIGN UP ───────────────────────────────────────────────────────────────
-  /**
-   * Create a new user account and return a session.
-   *
-   * @example
-   * const { data, error } = await hydrous.auth.signUp({
-   *   email:    'user@example.com',
-   *   password: 'supersecret',
-   * });
-   */
+  /** Create a new user account */
   async signUp(options) {
     try {
-      const url = buildUrl(this.baseUrl, "auth/signup");
-      const res = await fetch(url, {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/signup"), {
         method: "POST",
         headers: this.headers,
         body: JSON.stringify(options)
@@ -172,21 +156,10 @@ var AuthClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ─── SIGN IN ───────────────────────────────────────────────────────────────
-  /**
-   * Sign in with email and password.
-   *
-   * @example
-   * const { data, error } = await hydrous.auth.signIn({
-   *   email:    'user@example.com',
-   *   password: 'supersecret',
-   * });
-   * if (data) console.log('Signed in as', data.user.email);
-   */
+  /** Sign in with email and password */
   async signIn(options) {
     try {
-      const url = buildUrl(this.baseUrl, "auth/signin");
-      const res = await fetch(url, {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/signin"), {
         method: "POST",
         headers: this.headers,
         body: JSON.stringify(options)
@@ -198,14 +171,10 @@ var AuthClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ─── SIGN OUT ──────────────────────────────────────────────────────────────
-  /**
-   * Sign out the current user and invalidate their session.
-   */
+  /** Sign out and invalidate the current session */
   async signOut() {
     try {
-      const url = buildUrl(this.baseUrl, "auth/signout");
-      const res = await fetch(url, {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/signout"), {
         method: "POST",
         headers: mergeHeaders(this.headers, this._sessionHeader())
       });
@@ -216,12 +185,10 @@ var AuthClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ─── GET USER ──────────────────────────────────────────────────────────────
-  /** Return the currently authenticated user, or null if not signed in. */
+  /** Get the currently authenticated user */
   async getUser() {
     try {
-      const url = buildUrl(this.baseUrl, "auth/user");
-      const res = await fetch(url, {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/user"), {
         headers: mergeHeaders(this.headers, this._sessionHeader())
       });
       const json = await parseResponse(res);
@@ -230,19 +197,14 @@ var AuthClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ─── REFRESH TOKEN ────────────────────────────────────────────────────────
-  /**
-   * Refresh the access token using the stored refresh token.
-   * Called automatically by the SDK when a 401 is received.
-   */
+  /** Refresh the access token using the stored refresh token */
   async refreshSession() {
     var _a;
     if (!((_a = this.session) == null ? void 0 : _a.refreshToken)) {
-      return { data: null, error: { message: "No session", code: "NO_SESSION" } };
+      return { data: null, error: { message: "No active session", code: "NO_SESSION" } };
     }
     try {
-      const url = buildUrl(this.baseUrl, "auth/refresh");
-      const res = await fetch(url, {
+      const res = await fetch(buildUrl(this.baseUrl, "auth/refresh"), {
         method: "POST",
         headers: this.headers,
         body: JSON.stringify({ refreshToken: this.session.refreshToken })
@@ -254,7 +216,7 @@ var AuthClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  /** Return the current in-memory session (may be null). */
+  /** Return the current in-memory session (may be null) */
   getSession() {
     return this.session;
   }
@@ -270,34 +232,22 @@ function serialiseQuery(opts = {}) {
   const params = {};
   if (opts.limit !== void 0) params["limit"] = String(opts.limit);
   if (opts.offset !== void 0) params["offset"] = String(opts.offset);
-  if (opts.select && opts.select.length > 0) {
-    params["select"] = opts.select.join(",");
-  }
+  if (opts.select && opts.select.length > 0) params["select"] = opts.select.join(",");
   if (opts.orderBy) {
     params["orderBy"] = opts.orderBy.field;
     params["direction"] = (_a = opts.orderBy.direction) != null ? _a : "asc";
   }
   const filters = opts.where ? Array.isArray(opts.where) ? opts.where : [opts.where] : [];
-  if (filters.length > 0) {
-    params["where"] = JSON.stringify(filters);
-  }
+  if (filters.length > 0) params["where"] = JSON.stringify(filters);
   return params;
 }
-function eq(field, value) {
-  return { field, operator: "eq", value };
-}
-function neq(field, value) {
-  return { field, operator: "neq", value };
-}
-function gt(field, value) {
-  return { field, operator: "gt", value };
-}
-function lt(field, value) {
-  return { field, operator: "lt", value };
-}
-function inArray(field, value) {
-  return { field, operator: "in", value };
-}
+var eq = (field, value) => ({ field, operator: "eq", value });
+var neq = (field, value) => ({ field, operator: "neq", value });
+var gt = (field, value) => ({ field, operator: "gt", value });
+var lt = (field, value) => ({ field, operator: "lt", value });
+var gte = (field, value) => ({ field, operator: "gte", value });
+var lte = (field, value) => ({ field, operator: "lte", value });
+var inArray = (field, value) => ({ field, operator: "in", value });
 
 // src/records/client.ts
 var RecordsClient = class {
@@ -305,27 +255,13 @@ var RecordsClient = class {
     this.baseUrl = config.url;
     this.headers = {
       "Content-Type": "application/json",
-      "Authorization": `Bearer ${config.apiKey}`
+      "Authorization": `Bearer ${config.bucketSecurityKey}`
     };
   }
-  // ─── SELECT ────────────────────────────────────────────────────────────────
-  /**
-   * Query records from a collection.
-   *
-   * @param collection - Collection name (e.g. "users")
-   * @param options    - Filters, ordering, pagination
-   *
-   * @example
-   * const { data, error } = await hydrous.records.select('users', {
-   *   where:   { field: 'role', operator: 'eq', value: 'admin' },
-   *   orderBy: { field: 'createdAt', direction: 'desc' },
-   *   limit:   20,
-   * });
-   */
+  /** Query records from a collection */
   async select(collection, options = {}) {
     try {
-      const params = serialiseQuery(options);
-      const url = buildUrl(this.baseUrl, `records/${collection}`, params);
+      const url = buildUrl(this.baseUrl, `records/${collection}`, serialiseQuery(options));
       const res = await fetch(url, { headers: this.headers });
       const json = await parseResponse(res);
       return { data: json.data, count: json.count, error: null };
@@ -333,45 +269,20 @@ var RecordsClient = class {
       return { data: [], count: 0, error: toHydrousError(err) };
     }
   }
-  // ─── GET ONE ───────────────────────────────────────────────────────────────
-  /**
-   * Fetch a single record by its ID.
-   *
-   * @example
-   * const { data, error } = await hydrous.records.get('users', 'user_abc123');
-   */
+  /** Fetch a single record by ID */
   async get(collection, id) {
     try {
-      const url = buildUrl(this.baseUrl, `records/${collection}/${id}`);
-      const res = await fetch(url, { headers: this.headers });
+      const res = await fetch(buildUrl(this.baseUrl, `records/${collection}/${id}`), { headers: this.headers });
       const json = await parseResponse(res);
       return { data: json.data, error: null };
     } catch (err) {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ─── INSERT ────────────────────────────────────────────────────────────────
-  /**
-   * Insert one or more records into a collection.
-   *
-   * @param collection - Collection name
-   * @param payload    - A single record object or an array of record objects
-   *
-   * @example
-   * // Single insert
-   * const { data, error } = await hydrous.records.insert('users', {
-   *   name: 'Alice', email: 'alice@example.com'
-   * });
-   *
-   * // Bulk insert
-   * const { data, error } = await hydrous.records.insert('users', [
-   *   { name: 'Alice' }, { name: 'Bob' }
-   * ]);
-   */
+  /** Insert one or more records */
   async insert(collection, payload) {
     try {
-      const url = buildUrl(this.baseUrl, `records/${collection}`);
-      const res = await fetch(url, {
+      const res = await fetch(buildUrl(this.baseUrl, `records/${collection}`), {
         method: "POST",
         headers: this.headers,
         body: JSON.stringify(payload)
@@ -382,19 +293,10 @@ var RecordsClient = class {
       return { data: [], count: 0, error: toHydrousError(err) };
     }
   }
-  // ─── UPDATE ────────────────────────────────────────────────────────────────
-  /**
-   * Update a record by ID.
-   *
-   * @example
-   * const { data, error } = await hydrous.records.update('users', 'user_abc123', {
-   *   name: 'Alice Smith'
-   * });
-   */
+  /** Update a record by ID */
   async update(collection, id, payload) {
     try {
-      const url = buildUrl(this.baseUrl, `records/${collection}/${id}`);
-      const res = await fetch(url, {
+      const res = await fetch(buildUrl(this.baseUrl, `records/${collection}/${id}`), {
         method: "PATCH",
         headers: this.headers,
         body: JSON.stringify(payload)
@@ -405,17 +307,13 @@ var RecordsClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ─── DELETE ────────────────────────────────────────────────────────────────
-  /**
-   * Delete a record by ID.
-   *
-   * @example
-   * const { error } = await hydrous.records.delete('users', 'user_abc123');
-   */
+  /** Delete a record by ID */
   async delete(collection, id) {
     try {
-      const url = buildUrl(this.baseUrl, `records/${collection}/${id}`);
-      const res = await fetch(url, { method: "DELETE", headers: this.headers });
+      const res = await fetch(buildUrl(this.baseUrl, `records/${collection}/${id}`), {
+        method: "DELETE",
+        headers: this.headers
+      });
       await parseResponse(res);
       return { data: void 0, error: null };
     } catch (err) {
@@ -430,31 +328,17 @@ var AnalyticsClient = class {
     this.baseUrl = config.url;
     this.headers = {
       "Content-Type": "application/json",
-      "Authorization": `Bearer ${config.apiKey}`
+      "Authorization": `Bearer ${config.bucketSecurityKey}`
     };
   }
-  // ─── TRACK ────────────────────────────────────────────────────────────────
-  /**
-   * Track an analytics event.
-   *
-   * @example
-   * await hydrous.analytics.track({
-   *   event:      'page_view',
-   *   properties: { page: '/home', referrer: 'google.com' },
-   *   userId:     'user_abc123',
-   * });
-   */
+  /** Track a single analytics event */
   async track(options) {
     var _a;
     try {
-      const url = buildUrl(this.baseUrl, "analytics/track");
-      const res = await fetch(url, {
+      const res = await fetch(buildUrl(this.baseUrl, "analytics/track"), {
         method: "POST",
         headers: this.headers,
-        body: JSON.stringify({
-          ...options,
-          timestamp: (_a = options.timestamp) != null ? _a : Date.now()
-        })
+        body: JSON.stringify({ ...options, timestamp: (_a = options.timestamp) != null ? _a : Date.now() })
       });
       await parseResponse(res);
       return { data: void 0, error: null };
@@ -462,18 +346,25 @@ var AnalyticsClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ─── QUERY ────────────────────────────────────────────────────────────────
-  /**
-   * Query recorded analytics events.
-   *
-   * @example
-   * const { data } = await hydrous.analytics.query({
-   *   event: 'page_view',
-   *   from:  '2024-01-01',
-   *   to:    '2024-01-31',
-   *   limit: 100,
-   * });
-   */
+  /** Track many events in one request */
+  async trackBatch(events) {
+    try {
+      const stamped = events.map((e) => {
+        var _a;
+        return { ...e, timestamp: (_a = e.timestamp) != null ? _a : Date.now() };
+      });
+      const res = await fetch(buildUrl(this.baseUrl, "analytics/track/batch"), {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify({ events: stamped })
+      });
+      await parseResponse(res);
+      return { data: void 0, error: null };
+    } catch (err) {
+      return { data: null, error: toHydrousError(err) };
+    }
+  }
+  /** Query recorded analytics events */
   async query(options = {}) {
     try {
       const params = {};
@@ -490,56 +381,23 @@ var AnalyticsClient = class {
       return { data: [], count: 0, error: toHydrousError(err) };
     }
   }
-  // ─── BATCH TRACK ─────────────────────────────────────────────────────────
-  /**
-   * Track multiple events in a single request (more efficient than
-   * calling `track` in a loop).
-   *
-   * @example
-   * await hydrous.analytics.trackBatch([
-   *   { event: 'signup',   userId: 'u1' },
-   *   { event: 'onboarded', userId: 'u1' },
-   * ]);
-   */
-  async trackBatch(events) {
-    try {
-      const url = buildUrl(this.baseUrl, "analytics/track/batch");
-      const stamped = events.map((e) => {
-        var _a;
-        return {
-          ...e,
-          timestamp: (_a = e.timestamp) != null ? _a : Date.now()
-        };
-      });
-      const res = await fetch(url, {
-        method: "POST",
-        headers: this.headers,
-        body: JSON.stringify({ events: stamped })
-      });
-      await parseResponse(res);
-      return { data: void 0, error: null };
-    } catch (err) {
-      return { data: null, error: toHydrousError(err) };
-    }
-  }
 };
 
-// src/storage/client.ts
+// src/storage/scoped.ts
 var isBrowser = typeof window !== "undefined" && typeof XMLHttpRequest !== "undefined";
-function bucketFromKey(key) {
-  return encodeURIComponent(key);
-}
-function storageUrl(base, bucketKey, path) {
-  const bucket = bucketFromKey(bucketKey);
-  return `${base.replace(/\/$/, "")}/storage/${bucket}/${path.replace(/^\//, "")}`;
+function storageBase(url, bucketKey) {
+  return `${url.replace(/\/$/, "")}/storage/${encodeURIComponent(bucketKey)}`;
 }
 function storageHeaders(bucketKey) {
   return { "X-Storage-Key": bucketKey };
 }
-function drainSSEProgress(rawText, onProgress) {
+function jsonHeaders(bucketKey) {
+  return { "X-Storage-Key": bucketKey, "Content-Type": "application/json" };
+}
+function drainSSE(raw, onProgress) {
   const results = [];
   const errors = [];
-  parseSSEText(rawText, (eventType, data) => {
+  parseSSEText(raw, (eventType, data) => {
     var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
     const d = data;
     if (eventType === "progress" && onProgress) {
@@ -561,11 +419,9 @@ function drainSSEProgress(rawText, onProgress) {
     if (eventType === "done") {
       if (d["path"]) {
         results.push(d);
-      } else if (Array.isArray(d["errors"])) {
-        const succeeded = (_j = d["succeeded"]) != null ? _j : [];
-        const errs = d["errors"];
-        results.push(...succeeded);
-        errors.push(...errs);
+      } else if (Array.isArray(d["succeeded"])) {
+        results.push(...d["succeeded"]);
+        errors.push(...(_j = d["errors"]) != null ? _j : []);
       }
     }
     if (eventType === "error") {
@@ -578,51 +434,44 @@ function drainSSEProgress(rawText, onProgress) {
   });
   return { results, errors };
 }
-var StorageClient = class {
-  constructor(config) {
-    this.baseUrl = config.url;
+var ScopedStorageClient = class {
+  constructor(baseUrl, keyName, bucketKey) {
+    this.base = storageBase(baseUrl, bucketKey);
+    this.key = bucketKey;
+    this.keyName = keyName;
   }
   // ══════════════════════════════════════════════════════════════════════════
-  // UPLOAD
+  // UPLOAD — single file
   // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Upload a single file to a bucket.
+   * Upload a single file.
    *
-   * The bucket key **always comes first**.
-   * Supply an `onProgress` callback to receive live upload progress including
-   * bytes transferred, speed (bytes/sec), ETA, and lifecycle stage.
+   * Supply `onProgress` to receive live upload ticks including bytes
+   * transferred, speed (bytes/sec), ETA, and lifecycle stage.
    *
-   * ### Stages fired via `onProgress`
-   * | Stage        | Meaning                                 |
-   * |-------------|------------------------------------------|
-   * | `pending`   | Queued, not yet started                 |
-   * | `compressing` | Server is compressing the file         |
-   * | `uploading` | Bytes flowing to cloud storage           |
-   * | `done`      | Confirmed written to cloud storage       |
-   * | `error`     | Something went wrong                    |
+   * **Stage sequence:**
+   * `pending → compressing → uploading → done | error`
    *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param file       A `File`, `Blob`, or `Buffer` (Node)
-   * @param options    Path, overwrite flag, progress callback
+   * In browsers the progress is tracked at the network level via XHR, so
+   * `percent` reflects actual bytes leaving the device.  `done` only fires
+   * after the server confirms the write to cloud storage, so 100% is real.
    *
    * @example
-   * const { data, error } = await hydrous.storage.upload(
-   *   'ssk_my_bucket_key',
-   *   file,
-   *   {
-   *     path:       'avatars/alice.jpg',
-   *     overwrite:  true,
-   *     onProgress: (p) => {
-   *       console.log(`${p.stage} — ${p.percent}%  ${p.bytesPerSecond} B/s  ETA ${p.eta}s`);
-   *     },
-   *   }
-   * );
+   * const { data, error } = await db.storage('avatars').upload(file, {
+   *   path:      'users/alice.jpg',
+   *   overwrite: true,
+   *   onProgress: (p) => {
+   *     setProgress(p.percent);              // e.g. drive a <progress> bar
+   *     setSpeed(`${p.bytesPerSecond} B/s`);
+   *     setEta(`${p.eta}s remaining`);
+   *   },
+   * });
    */
-  async upload(bucketKey, file, options = {}) {
+  async upload(file, options = {}) {
     var _a, _b;
     const { path, overwrite = false, onProgress } = options;
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "upload");
+      const url = `${this.base}/upload`;
       const form = new FormData();
       if (file instanceof Uint8Array) {
         form.append("file", new Blob([file.buffer]), path != null ? path : "file");
@@ -633,25 +482,23 @@ var StorageClient = class {
       }
       if (path) form.append("path", path);
       if (overwrite) form.append("overwrite", "true");
-      const headers = storageHeaders(bucketKey);
+      const headers = storageHeaders(this.key);
       if (isBrowser) {
         const totalBytes = file instanceof Blob ? file.size : file instanceof Uint8Array ? file.byteLength : file.byteLength;
         const rawBody = await xhrUpload(url, form, headers, (loaded, total) => {
-          if (onProgress) {
-            onProgress({
-              index: 0,
-              total: 1,
-              path: path != null ? path : "",
-              stage: "uploading",
-              bytesUploaded: loaded,
-              totalBytes: total || totalBytes,
-              percent: Math.min(99, Math.round(loaded / (total || totalBytes) * 100)),
-              bytesPerSecond: null,
-              eta: null
-            });
-          }
+          onProgress == null ? void 0 : onProgress({
+            index: 0,
+            total: 1,
+            path: path != null ? path : "",
+            stage: "uploading",
+            bytesUploaded: loaded,
+            totalBytes: total || totalBytes,
+            percent: Math.min(99, Math.round(loaded / (total || totalBytes) * 100)),
+            bytesPerSecond: null,
+            eta: null
+          });
         });
-        const { results, errors } = drainSSEProgress(rawBody, onProgress);
+        const { results, errors } = drainSSE(rawBody, onProgress);
         if (errors.length > 0 && results.length === 0) {
           return { data: null, error: { message: errors[0].error, code: errors[0].code } };
         }
@@ -674,33 +521,32 @@ var StorageClient = class {
       }
       const res = await fetch(url, { method: "POST", headers, body: form });
       if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw new HydrousSDKError((_b = err.error) != null ? _b : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+        const e = await res.json().catch(() => ({}));
+        throw new HydrousDBError((_b = e.error) != null ? _b : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
       }
       let finalResult = null;
       await readSSEStream(res, (eventType, data) => {
-        var _a2, _b2, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+        var _a2, _b2, _c, _d, _e, _f, _g, _h;
         const d = data;
         if (eventType === "progress" && onProgress) {
           onProgress({
-            index: (_a2 = d["index"]) != null ? _a2 : 0,
-            total: (_b2 = d["total"]) != null ? _b2 : 1,
-            path: (_d = (_c = d["path"]) != null ? _c : path) != null ? _d : "",
-            stage: (_e = d["stage"]) != null ? _e : "uploading",
-            bytesUploaded: (_f = d["bytesUploaded"]) != null ? _f : 0,
-            totalBytes: (_g = d["totalBytes"]) != null ? _g : 0,
-            percent: (_h = d["percent"]) != null ? _h : 0,
-            bytesPerSecond: (_i = d["bytesPerSecond"]) != null ? _i : null,
-            eta: (_j = d["eta"]) != null ? _j : null,
-            result: d["result"],
-            error: d["error"]
+            index: 0,
+            total: 1,
+            path: path != null ? path : "",
+            stage: (_a2 = d["stage"]) != null ? _a2 : "uploading",
+            bytesUploaded: (_b2 = d["bytesUploaded"]) != null ? _b2 : 0,
+            totalBytes: (_c = d["totalBytes"]) != null ? _c : 0,
+            percent: (_d = d["percent"]) != null ? _d : 0,
+            bytesPerSecond: (_e = d["bytesPerSecond"]) != null ? _e : null,
+            eta: (_f = d["eta"]) != null ? _f : null,
+            result: d["result"]
           });
         }
         if (eventType === "done") finalResult = data;
         if (eventType === "error") {
-          throw new HydrousSDKError(
-            (_k = d["error"]) != null ? _k : "Upload failed",
-            (_l = d["code"]) != null ? _l : "UPLOAD_ERROR"
+          throw new HydrousDBError(
+            (_g = d["error"]) != null ? _g : "Upload failed",
+            (_h = d["code"]) != null ? _h : "UPLOAD_ERROR"
           );
         }
       });
@@ -710,39 +556,31 @@ var StorageClient = class {
     }
   }
   // ══════════════════════════════════════════════════════════════════════════
-  // UPLOAD RAW (text / JSON / binary from string)
+  // UPLOAD TEXT / JSON
   // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Upload raw text or JSON content directly — no `File` object needed.
-   * Great for saving generated content, config files, or JSON records.
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param path       Destination path (e.g. `"configs/settings.json"`)
-   * @param content    String content to store
-   * @param options    `mimeType`, `overwrite`, `onProgress`
+   * Upload raw text or JSON content directly — no File object needed.
    *
    * @example
-   * await hydrous.storage.uploadText(
-   *   'ssk_my_bucket_key',
-   *   'reports/summary.txt',
-   *   'Hello from Hydrous!',
-   *   { mimeType: 'text/plain' }
+   * // Save a JSON config
+   * await db.storage('configs').uploadText(
+   *   'settings/app.json',
+   *   JSON.stringify({ theme: 'dark' }),
+   *   { mimeType: 'application/json' }
    * );
    */
-  async uploadText(bucketKey, path, content, options = {}) {
+  async uploadText(path, content, options = {}) {
     var _a;
     const { mimeType = "text/plain", overwrite = false, onProgress } = options;
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "upload-raw");
-      const headers = { ...storageHeaders(bucketKey), "Content-Type": "application/json" };
-      const res = await fetch(url, {
+      const res = await fetch(`${this.base}/upload-raw`, {
         method: "POST",
-        headers,
+        headers: jsonHeaders(this.key),
         body: JSON.stringify({ path, content, mimeType, overwrite })
       });
       if (!res.ok) {
         const e = await res.json().catch(() => ({}));
-        throw new HydrousSDKError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+        throw new HydrousDBError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
       }
       let finalResult = null;
       await readSSEStream(res, (eventType, data) => {
@@ -774,84 +612,62 @@ var StorageClient = class {
   /**
    * Upload multiple files in one request.
    *
-   * `onProgress` fires for **every file individually** — the `index` field
-   * tells you which file the event belongs to (0-based, same order as `files`).
-   * All files receive a `pending` event upfront before any uploads start,
-   * so you can render all progress bars immediately.
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param files      Array of `File` objects (browser) or `{ name, data }` objects (Node)
-   * @param options    Prefix, per-file paths, overwrite, concurrency, onProgress
+   * `onProgress` fires per file — use `p.index` to identify which file.
+   * All files receive a `pending` event upfront so you can render progress
+   * bars immediately before any data is sent.
    *
    * @example
-   * await hydrous.storage.batchUpload(
-   *   'ssk_my_bucket_key',
-   *   fileArray,
-   *   {
-   *     prefix:     'uploads/2024/',
-   *     onProgress: (p) => {
-   *       console.log(`File ${p.index}: ${p.stage} ${p.percent}%`);
-   *     },
-   *   }
-   * );
+   * await db.storage('documents').batchUpload(files, {
+   *   prefix:     'reports/2024/',
+   *   onProgress: (p) => updateBar(p.index, p.percent),
+   * });
    */
-  async batchUpload(bucketKey, files, options = {}) {
+  async batchUpload(files, options = {}) {
     var _a;
     const { prefix = "", paths, overwrite = false, onProgress } = options;
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "batch-upload");
+      const url = `${this.base}/batch-upload`;
+      const resolvedPaths = files.map((f, i) => {
+        var _a2;
+        return (_a2 = paths == null ? void 0 : paths[i]) != null ? _a2 : `${prefix}${f.name}`;
+      });
       const form = new FormData();
-      const resolvedPaths = files.map(
-        (f, i) => {
-          var _a2;
-          return (_a2 = paths == null ? void 0 : paths[i]) != null ? _a2 : `${prefix}${f.name}`;
-        }
-      );
       files.forEach((f) => form.append("files", f, f.name));
       form.append("paths", JSON.stringify(resolvedPaths));
       if (overwrite) form.append("overwrite", "true");
-      const headers = storageHeaders(bucketKey);
+      const headers = storageHeaders(this.key);
       if (isBrowser) {
         const totalBytes = files.reduce((s, f) => s + f.size, 0);
         const rawBody = await xhrUpload(url, form, headers, (loaded, total) => {
-          if (onProgress) {
-            let cursor = 0;
-            for (let i = 0; i < files.length; i++) {
-              const share = files[i].size / (totalBytes || 1);
-              const myStart = cursor;
-              const myEnd = cursor + share;
-              const fileLoaded = Math.max(0, Math.min(
-                files[i].size,
-                (loaded / (total || totalBytes) - myStart) / share * files[i].size
-              ));
-              onProgress({
-                index: i,
-                total: files.length,
-                path: resolvedPaths[i],
-                stage: "uploading",
-                bytesUploaded: Math.round(fileLoaded),
-                totalBytes: files[i].size,
-                percent: Math.min(99, Math.round(fileLoaded / files[i].size * 100)),
-                bytesPerSecond: null,
-                eta: null
-              });
-              cursor = myEnd;
-            }
+          if (!onProgress) return;
+          let cursor = 0;
+          for (let i = 0; i < files.length; i++) {
+            const share = files[i].size / (totalBytes || 1);
+            const fileLoaded = Math.max(0, Math.min(
+              files[i].size,
+              (loaded / (total || totalBytes) - cursor) / share * files[i].size
+            ));
+            onProgress({
+              index: i,
+              total: files.length,
+              path: resolvedPaths[i],
+              stage: "uploading",
+              bytesUploaded: Math.round(fileLoaded),
+              totalBytes: files[i].size,
+              percent: Math.min(99, Math.round(fileLoaded / files[i].size * 100)),
+              bytesPerSecond: null,
+              eta: null
+            });
+            cursor += share;
           }
         });
-        const { results, errors } = drainSSEProgress(rawBody, onProgress);
-        return {
-          data: {
-            succeeded: results,
-            failed: errors
-          },
-          error: null
-        };
+        const { results, errors } = drainSSE(rawBody, onProgress);
+        return { data: { succeeded: results, failed: errors }, error: null };
       }
       const res = await fetch(url, { method: "POST", headers, body: form });
       if (!res.ok) {
         const e = await res.json().catch(() => ({}));
-        throw new HydrousSDKError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+        throw new HydrousDBError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
       }
       const succeeded = [];
       const failed = [];
@@ -868,10 +684,7 @@ var StorageClient = class {
             totalBytes: (_f = d["totalBytes"]) != null ? _f : 0,
             percent: (_g = d["percent"]) != null ? _g : 0,
             bytesPerSecond: (_h = d["bytesPerSecond"]) != null ? _h : null,
-            eta: (_i = d["eta"]) != null ? _i : null,
-            result: d["result"],
-            error: d["error"],
-            code: d["code"]
+            eta: (_i = d["eta"]) != null ? _i : null
           });
         }
         if (eventType === "done" && d["succeeded"]) {
@@ -890,30 +703,22 @@ var StorageClient = class {
   /**
    * Download a single file and return its content as an `ArrayBuffer`.
    *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param filePath   Path of the file within your bucket
-   *
    * @example
-   * const { data, error } = await hydrous.storage.download(
-   *   'ssk_my_bucket_key',
-   *   'avatars/alice.jpg'
-   * );
-   * if (data) {
-   *   const blob = new Blob([data]);
-   *   const url  = URL.createObjectURL(blob);
-   * }
+   * const { data } = await db.storage('avatars').download('users/alice.jpg');
+   * const blob = new Blob([data!]);
+   * img.src = URL.createObjectURL(blob);
    */
-  async download(bucketKey, filePath) {
+  async download(filePath) {
     var _a;
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, `download/${filePath}`);
-      const res = await fetch(url, { headers: storageHeaders(bucketKey) });
+      const res = await fetch(`${this.base}/download/${filePath}`, {
+        headers: storageHeaders(this.key)
+      });
       if (!res.ok) {
         const e = await res.json().catch(() => ({}));
-        throw new HydrousSDKError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+        throw new HydrousDBError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
       }
-      const buffer = await res.arrayBuffer();
-      return { data: buffer, error: null };
+      return { data: await res.arrayBuffer(), error: null };
     } catch (err) {
       return { data: null, error: toHydrousError(err) };
     }
@@ -924,36 +729,26 @@ var StorageClient = class {
   /**
    * Download multiple files in one request.
    *
-   * When `autoSave: true` (browser only) each file is automatically saved
-   * to the user's Downloads folder as it arrives.
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param filePaths  Array of file paths within your bucket
-   * @param options    Concurrency, onProgress, autoSave
+   * Set `autoSave: true` (browser only) to trigger a Save dialog per file.
    *
    * @example
-   * const { data } = await hydrous.storage.batchDownload(
-   *   'ssk_my_bucket_key',
-   *   ['reports/jan.pdf', 'reports/feb.pdf'],
-   *   {
-   *     onProgress: (p) => console.log(p.path, p.status),
-   *     autoSave:   true,  // triggers browser file-save dialog per file
-   *   }
+   * const { data } = await db.storage('reports').batchDownload(
+   *   ['jan.pdf', 'feb.pdf'],
+   *   { autoSave: true, onProgress: (p) => console.log(p.path, p.status) }
    * );
    */
-  async batchDownload(bucketKey, filePaths, options = {}) {
+  async batchDownload(filePaths, options = {}) {
     var _a;
     const { concurrency = 5, onProgress, autoSave = false } = options;
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "batch-download");
-      const res = await fetch(url, {
+      const res = await fetch(`${this.base}/batch-download`, {
         method: "POST",
-        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        headers: jsonHeaders(this.key),
         body: JSON.stringify({ paths: filePaths, concurrency })
       });
       if (!res.ok) {
         const e = await res.json().catch(() => ({}));
-        throw new HydrousSDKError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
+        throw new HydrousDBError((_a = e.error) != null ? _a : `HTTP ${res.status}`, "HTTP_ERROR", res.status);
       }
       const downloadedFiles = [];
       await readSSEStream(res, (eventType, data) => {
@@ -968,20 +763,10 @@ var StorageClient = class {
           const binary = atob(base64);
           const bytes = new Uint8Array(binary.length);
           for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-          const content = bytes.buffer;
-          downloadedFiles.push({ path, content, mimeType, size });
-          if (onProgress) {
-            onProgress({
-              index,
-              total: filePaths.length,
-              path,
-              status: "success",
-              size,
-              mimeType
-            });
-          }
+          downloadedFiles.push({ path, content: bytes.buffer, mimeType, size });
+          onProgress == null ? void 0 : onProgress({ index, total: filePaths.length, path, status: "success", size, mimeType });
           if (autoSave && isBrowser) {
-            const blob = new Blob([content], { type: mimeType });
+            const blob = new Blob([bytes.buffer], { type: mimeType });
             const blobUrl = URL.createObjectURL(blob);
             const a = document.createElement("a");
             a.href = blobUrl;
@@ -1010,37 +795,30 @@ var StorageClient = class {
   // LIST
   // ══════════════════════════════════════════════════════════════════════════
   /**
-   * List files and folders inside a bucket (or a folder within it).
-   *
-   * Results are paginated — use `pagination.nextCursor` to fetch the next page.
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param options    `prefix`, `limit`, `cursor`
+   * List files and folders (paginated).
    *
    * @example
-   * const { data } = await hydrous.storage.list('ssk_my_bucket_key', {
-   *   prefix: 'avatars/',
-   *   limit:  50,
-   * });
-   * for (const item of data.items) {
-   *   console.log(item.type, item.path);
+   * const { data } = await db.storage('avatars').list({ prefix: 'users/' });
+   * for (const item of data!.items) {
+   *   console.log(item.type, item.path, item.size);
    * }
    */
-  async list(bucketKey, options = {}) {
+  async list(options = {}) {
     const { prefix = "", limit = 50, cursor } = options;
     try {
-      const params = {
+      const url = buildUrl(this.base, "list", {
         prefix: prefix || void 0,
         limit,
         cursor: cursor || void 0
-      };
-      const url = buildUrl(
-        this.baseUrl,
-        `storage/${bucketFromKey(bucketKey)}/list`,
-        params
-      );
-      const res = await fetch(url, { headers: storageHeaders(bucketKey) });
-      const json = await parseResponse(res);
+      });
+      const res = await fetch(url.replace(this.base + "/list", `${this.base}/list`), {
+        headers: storageHeaders(this.key)
+      });
+      const u = `${this.base}/list?${new URLSearchParams(
+        Object.entries({ prefix: prefix || "", limit: String(limit), ...cursor ? { cursor } : {} }).filter(([, v]) => v !== "")
+      ).toString()}`;
+      const r = await fetch(u, { headers: storageHeaders(this.key) });
+      const json = await parseResponse(r);
       return { data: json, error: null };
     } catch (err) {
       return { data: null, error: toHydrousError(err) };
@@ -1050,22 +828,17 @@ var StorageClient = class {
   // METADATA
   // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Get metadata for a specific file (size, MIME type, compression info, etc.)
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param filePath   Path of the file within your bucket
+   * Get metadata for a file (size, MIME type, compression, etc.)
    *
    * @example
-   * const { data } = await hydrous.storage.metadata(
-   *   'ssk_my_bucket_key',
-   *   'avatars/alice.jpg'
-   * );
-   * console.log(data.size, data.mimeType);
+   * const { data: meta } = await db.storage('docs').metadata('report.pdf');
+   * console.log(meta!.size, meta!.mimeType, meta!.isCompressed);
    */
-  async metadata(bucketKey, filePath) {
+  async metadata(filePath) {
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, `metadata/${filePath}`);
-      const res = await fetch(url, { headers: storageHeaders(bucketKey) });
+      const res = await fetch(`${this.base}/metadata/${filePath}`, {
+        headers: storageHeaders(this.key)
+      });
       const json = await parseResponse(res);
       return { data: json.data, error: null };
     } catch (err) {
@@ -1073,23 +846,14 @@ var StorageClient = class {
     }
   }
   // ══════════════════════════════════════════════════════════════════════════
-  // DELETE FILE
+  // DELETE
   // ══════════════════════════════════════════════════════════════════════════
-  /**
-   * Delete a single file.
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param filePath   Path of the file to delete
-   *
-   * @example
-   * await hydrous.storage.deleteFile('ssk_my_bucket_key', 'avatars/old.jpg');
-   */
-  async deleteFile(bucketKey, filePath) {
+  /** Delete a single file */
+  async deleteFile(filePath) {
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "file");
-      const res = await fetch(url, {
+      const res = await fetch(`${this.base}/file`, {
         method: "DELETE",
-        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        headers: jsonHeaders(this.key),
         body: JSON.stringify({ path: filePath })
       });
       await parseResponse(res);
@@ -1098,24 +862,12 @@ var StorageClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // DELETE FOLDER
-  // ══════════════════════════════════════════════════════════════════════════
-  /**
-   * Recursively delete a folder and all of its contents.
-   *
-   * @param bucketKey   Your storage bucket key (`ssk_…`)
-   * @param folderPath  Folder path to delete (e.g. `"old-uploads/"`)
-   *
-   * @example
-   * await hydrous.storage.deleteFolder('ssk_my_bucket_key', 'temp/');
-   */
-  async deleteFolder(bucketKey, folderPath) {
+  /** Recursively delete a folder and all its contents */
+  async deleteFolder(folderPath) {
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "folder");
-      const res = await fetch(url, {
+      const res = await fetch(`${this.base}/folder`, {
         method: "DELETE",
-        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        headers: jsonHeaders(this.key),
         body: JSON.stringify({ path: folderPath })
       });
       await parseResponse(res);
@@ -1124,24 +876,12 @@ var StorageClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // CREATE FOLDER
-  // ══════════════════════════════════════════════════════════════════════════
-  /**
-   * Create an empty folder.
-   *
-   * @param bucketKey   Your storage bucket key (`ssk_…`)
-   * @param folderPath  Path for the new folder (e.g. `"avatars/2024/"`)
-   *
-   * @example
-   * await hydrous.storage.createFolder('ssk_my_bucket_key', 'avatars/2024/');
-   */
-  async createFolder(bucketKey, folderPath) {
+  /** Create an empty folder */
+  async createFolder(folderPath) {
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "folder");
-      const res = await fetch(url, {
+      const res = await fetch(`${this.base}/folder`, {
         method: "POST",
-        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        headers: jsonHeaders(this.key),
         body: JSON.stringify({ path: folderPath })
       });
       await parseResponse(res);
@@ -1151,28 +891,14 @@ var StorageClient = class {
     }
   }
   // ══════════════════════════════════════════════════════════════════════════
-  // MOVE
+  // MOVE & COPY
   // ══════════════════════════════════════════════════════════════════════════
-  /**
-   * Move (rename) a file to a new path.
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param fromPath   Current path of the file
-   * @param toPath     New path for the file
-   *
-   * @example
-   * await hydrous.storage.move(
-   *   'ssk_my_bucket_key',
-   *   'drafts/report.pdf',
-   *   'published/report.pdf'
-   * );
-   */
-  async move(bucketKey, fromPath, toPath) {
+  /** Move (rename) a file */
+  async move(fromPath, toPath) {
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "move");
-      const res = await fetch(url, {
+      const res = await fetch(`${this.base}/move`, {
         method: "POST",
-        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        headers: jsonHeaders(this.key),
         body: JSON.stringify({ from: fromPath, to: toPath })
       });
       await parseResponse(res);
@@ -1181,29 +907,12 @@ var StorageClient = class {
       return { data: null, error: toHydrousError(err) };
     }
   }
-  // ══════════════════════════════════════════════════════════════════════════
-  // COPY
-  // ══════════════════════════════════════════════════════════════════════════
-  /**
-   * Copy a file to a new path (original is kept).
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param fromPath   Source path
-   * @param toPath     Destination path
-   *
-   * @example
-   * await hydrous.storage.copy(
-   *   'ssk_my_bucket_key',
-   *   'templates/invoice.pdf',
-   *   'invoices/invoice-001.pdf'
-   * );
-   */
-  async copy(bucketKey, fromPath, toPath) {
+  /** Copy a file (original is kept) */
+  async copy(fromPath, toPath) {
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "copy");
-      const res = await fetch(url, {
+      const res = await fetch(`${this.base}/copy`, {
         method: "POST",
-        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        headers: jsonHeaders(this.key),
         body: JSON.stringify({ from: fromPath, to: toPath })
       });
       await parseResponse(res);
@@ -1218,25 +927,16 @@ var StorageClient = class {
   /**
    * Generate a time-limited public URL for a private file.
    *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
-   * @param filePath   Path of the file
-   * @param options    `expiresIn` seconds (default: 3600)
-   *
    * @example
-   * const { data } = await hydrous.storage.signedUrl(
-   *   'ssk_my_bucket_key',
-   *   'private/contract.pdf',
-   *   { expiresIn: 300 }   // 5 minutes
-   * );
-   * console.log(data.signedUrl);  // share this URL
+   * const { data } = await db.storage('contracts').signedUrl('nda.pdf', { expiresIn: 300 });
+   * console.log(data!.signedUrl); // share this
    */
-  async signedUrl(bucketKey, filePath, options = {}) {
+  async signedUrl(filePath, options = {}) {
     const { expiresIn = 3600 } = options;
     try {
-      const url = storageUrl(this.baseUrl, bucketKey, "signed-url");
-      const res = await fetch(url, {
+      const res = await fetch(`${this.base}/signed-url`, {
         method: "POST",
-        headers: { ...storageHeaders(bucketKey), "Content-Type": "application/json" },
+        headers: jsonHeaders(this.key),
         body: JSON.stringify({ path: filePath, expiresInSeconds: expiresIn })
       });
       const json = await parseResponse(res);
@@ -1249,18 +949,17 @@ var StorageClient = class {
   // STATS
   // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Get usage and billing statistics for this bucket key.
-   *
-   * @param bucketKey  Your storage bucket key (`ssk_…`)
+   * Get usage and billing stats for this storage key.
    *
    * @example
-   * const { data } = await hydrous.storage.stats('ssk_my_bucket_key');
-   * console.log(`${data.totalFiles} files, ${data.totalSizeBytes} bytes stored`);
+   * const { data } = await db.storage('main').stats();
+   * console.log(data!.totalFiles, data!.totalSizeBytes);
    */
-  async stats(bucketKey) {
+  async stats() {
     try {
-      const url = buildUrl(this.baseUrl, `storage/${bucketFromKey(bucketKey)}/stats`);
-      const res = await fetch(url, { headers: storageHeaders(bucketKey) });
+      const res = await fetch(`${this.base}/stats`, {
+        headers: storageHeaders(this.key)
+      });
       const json = await parseResponse(res);
       return { data: json.data, error: null };
     } catch (err) {
@@ -1269,15 +968,63 @@ var StorageClient = class {
   }
 };
 
+// src/storage/manager.ts
+var StorageManager = class {
+  constructor(config) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.baseUrl = config.url;
+    this._keys = config.storageKeys;
+  }
+  /**
+   * Get a storage client scoped to a named key.
+   *
+   * @param keyName - Must match a property you declared in `storageKeys`
+   *
+   * @example
+   * const avatarStore   = db.storage('avatars');
+   * const documentStore = db.storage('documents');
+   *
+   * await avatarStore.upload(file, { path: 'users/alice.jpg' });
+   * const list = await documentStore.list({ prefix: 'invoices/' });
+   */
+  use(keyName) {
+    const bucketKey = this._keys[keyName];
+    if (!bucketKey) {
+      const available = Object.keys(this._keys).join(", ");
+      throw new HydrousDBError(
+        `Storage key "${keyName}" is not defined.
+Available: ${available || "(none)"}`,
+        "UNKNOWN_STORAGE_KEY"
+      );
+    }
+    if (!this.cache.has(keyName)) {
+      this.cache.set(keyName, new ScopedStorageClient(this.baseUrl, keyName, bucketKey));
+    }
+    return this.cache.get(keyName);
+  }
+  /** Return the names of all configured storage keys */
+  keyNames() {
+    return Object.keys(this._keys);
+  }
+};
+
 // src/client.ts
 var HydrousClient = class {
   constructor(config) {
-    if (!config.url) throw new Error("[Hydrous] config.url is required");
-    if (!config.apiKey) throw new Error("[Hydrous] config.apiKey is required");
+    if (!config.url) throw new Error("[HydrousDB] config.url is required");
+    if (!config.authKey) throw new Error("[HydrousDB] config.authKey is required");
+    if (!config.bucketSecurityKey) throw new Error("[HydrousDB] config.bucketSecurityKey is required");
+    if (!config.storageKeys || typeof config.storageKeys !== "object") {
+      throw new Error("[HydrousDB] config.storageKeys must be an object of named keys");
+    }
     this.auth = new AuthClient(config);
     this.records = new RecordsClient(config);
     this.analytics = new AnalyticsClient(config);
-    this.storage = new StorageClient(config);
+    const manager = new StorageManager(config);
+    const fn = (keyName) => manager.use(keyName);
+    fn.use = (keyName) => manager.use(keyName);
+    fn.keyNames = () => manager.keyNames();
+    this.storage = fn;
   }
 };
 
@@ -1286,6 +1033,6 @@ function createClient(config) {
   return new HydrousClient(config);
 }
 
-export { AnalyticsClient, AuthClient, HydrousClient, HydrousSDKError, RecordsClient, StorageClient, createClient, eq, gt, inArray, isHydrousError, lt, neq };
+export { AnalyticsClient, AuthClient, HydrousClient, HydrousDBError, RecordsClient, ScopedStorageClient, StorageManager, createClient, eq, gt, gte, inArray, isHydrousError, lt, lte, neq };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map