hydrousdb 3.0.0 → 3.0.2

package/dist/index.d.cts

@@ -7,24 +7,58 @@ interface RequestOptions {
 }
 declare class HttpClient {
     private readonly baseUrl;
-    private readonly securityKey;
-    constructor(baseUrl: string, securityKey: string);
-    request<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;
-    get<T = unknown>(path: string, headers?: Record<string, string>): Promise<T>;
-    post<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-    put<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-    patch<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
-    delete<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    constructor(baseUrl: string);
+    request<T = unknown>(path: string, apiKeyOrOpts?: string | RequestOptions, opts?: RequestOptions): Promise<T>;
+    get<T = unknown>(path: string, apiKey?: string, headers?: Record<string, string>): Promise<T>;
+    post<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    put<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    patch<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    delete<T = unknown>(path: string, apiKey?: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
     putToSignedUrl(signedUrl: string, data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
 }
 
+/**
+ * Storage keys map — one named key per storage bucket/permission scope.
+ * Keys start with `ssk_`. You can define as many as you need.
+ *
+ * @example
+ * ```ts
+ * storageKeys: {
+ *   main:      'ssk_main_…',
+ *   avatars:   'ssk_avatars_…',
+ *   documents: 'ssk_docs_…',
+ * }
+ * ```
+ */
+type StorageKeys = Record<string, string>;
 interface HydrousConfig {
     /**
-     * Your project's Security Key (starts with `sk_`).
-     * Obtain this from your dashboard at https://hydrousdb.com/dashboard.
-     * This is your most important credential — keep it secret.
+     * Auth service key (starts with `hk_auth_`).
+     * Used exclusively for all `/auth/*` routes — signup, login, sessions, etc.
+     * Obtain from your dashboard at https://hydrousdb.com/dashboard.
      */
-    securityKey: string;
+    authKey: string;
+    /**
+     * Bucket security key (starts with `hk_bucket_`).
+     * Used for all `/records/*` and `/analytics/*` routes.
+     * Obtain from your dashboard at https://hydrousdb.com/dashboard.
+     */
+    bucketSecurityKey: string;
+    /**
+     * Named storage keys (each starts with `ssk_`).
+     * Define one key per storage bucket/permission scope.
+     * Pass the name of the key you want when calling `db.storage('keyName')`.
+     *
+     * @example
+     * ```ts
+     * storageKeys: {
+     *   main:      'ssk_main_…',      // default general-purpose bucket
+     *   avatars:   'ssk_avatars_…',   // user avatar uploads
+     *   documents: 'ssk_docs_…',      // private documents
+     * }
+     * ```
+     */
+    storageKeys: StorageKeys;
     /**
      * Override the API base URL. Defaults to the official HydrousDB endpoint.
      * You almost never need to set this.
@@ -304,175 +338,53 @@ interface CrossBucketRow {
 
 /**
  * AuthClient — full user authentication for a single bucket.
- *
- * Every method maps directly to a route in the server's `auth.js` router.
- * The bucket key is the name of your user bucket (e.g. "users" or "customers").
+ * Uses the `authKey` (`hk_auth_…`) sent via `X-Api-Key` header.
  *
  * @example
  * ```ts
- * const db = createClient({ securityKey: 'sk_...' });
+ * const db = createClient({ authKey: 'hk_auth_…', bucketSecurityKey: '…', storageKeys: { main: '…' } });
  * const auth = db.auth('my-app-users');
- *
- * const { user, session } = await auth.signup({
- *   email: 'alice@example.com',
- *   password: 'hunter2',
- *   fullName: 'Alice',
- * });
+ * const { user, session } = await auth.signup({ email: 'alice@example.com', password: 'hunter2' });
  * ```
  */
 declare class AuthClient {
     private readonly http;
-    private readonly bucketKey;
+    private readonly authKey;
     private readonly basePath;
-    constructor(http: HttpClient, bucketKey: string);
-    /**
-     * Register a new user in this bucket.
-     *
-     * @example
-     * ```ts
-     * const { user, session } = await auth.signup({
-     *   email: 'alice@example.com',
-     *   password: 'hunter2',
-     *   fullName: 'Alice Wonderland',
-     *   // Any extra fields are stored on the user record:
-     *   plan: 'pro',
-     * });
-     * ```
-     */
+    constructor(http: HttpClient, authKey: string, bucketKey: string);
+    private post;
+    private get;
+    private patch;
+    private delete;
     signup(options: SignupOptions): Promise<AuthResult>;
-    /**
-     * Authenticate an existing user and create a session.
-     * Sessions are valid for 24 hours; use `refreshSession` to extend.
-     *
-     * @example
-     * ```ts
-     * const { user, session } = await auth.login({
-     *   email: 'alice@example.com',
-     *   password: 'hunter2',
-     * });
-     * // Store session.sessionId safely — you'll need it for other calls.
-     * ```
-     */
     login(options: LoginOptions): Promise<AuthResult>;
-    /**
-     * Invalidate a session (sign out).
-     *
-     * @example
-     * ```ts
-     * await auth.logout({ sessionId: session.sessionId });
-     * ```
-     */
     logout({ sessionId }: {
         sessionId: string;
     }): Promise<void>;
-    /**
-     * Extend a session using its refresh token.
-     * Returns a new session object.
-     *
-     * @example
-     * ```ts
-     * const newSession = await auth.refreshSession({ refreshToken: session.refreshToken });
-     * ```
-     */
     refreshSession({ refreshToken }: {
         refreshToken: string;
     }): Promise<Session>;
-    /**
-     * Fetch a user by their ID.
-     *
-     * @example
-     * ```ts
-     * const user = await auth.getUser({ userId: 'usr_abc123' });
-     * ```
-     */
     getUser({ userId }: {
         userId: string;
     }): Promise<UserRecord>;
-    /**
-     * Update fields on a user record. Requires a valid session.
-     *
-     * @example
-     * ```ts
-     * const updated = await auth.updateUser({
-     *   sessionId: session.sessionId,
-     *   userId: user.id,
-     *   data: { fullName: 'Alice Smith', plan: 'enterprise' },
-     * });
-     * ```
-     */
     updateUser(options: UpdateUserOptions): Promise<UserRecord>;
-    /**
-     * Soft-delete a user. The record is marked deleted but not removed from storage.
-     * Requires a valid session (the user can delete themselves, or an admin can delete any user).
-     *
-     * @example
-     * ```ts
-     * await auth.deleteUser({ sessionId: session.sessionId, userId: user.id });
-     * ```
-     */
     deleteUser({ sessionId, userId }: {
         sessionId: string;
         userId: string;
     }): Promise<void>;
-    /**
-     * List all users in the bucket. **Admin session required.**
-     *
-     * @example
-     * ```ts
-     * const { users, total } = await auth.listUsers({
-     *   sessionId: adminSession.sessionId,
-     *   limit: 50,
-     *   offset: 0,
-     * });
-     * ```
-     */
     listUsers(options: ListUsersOptions): Promise<ListUsersResult>;
-    /**
-     * Permanently hard-delete a user and all their data. **Admin session required.**
-     * This action is irreversible.
-     *
-     * @example
-     * ```ts
-     * await auth.hardDeleteUser({ sessionId: adminSession.sessionId, userId: user.id });
-     * ```
-     */
     hardDeleteUser({ sessionId, userId }: {
         sessionId: string;
         userId: string;
     }): Promise<void>;
-    /**
-     * Bulk delete multiple users. **Admin session required.**
-     *
-     * @example
-     * ```ts
-     * const result = await auth.bulkDeleteUsers({
-     *   sessionId: adminSession.sessionId,
-     *   userIds: ['usr_a', 'usr_b'],
-     * });
-     * ```
-     */
-    bulkDeleteUsers({ sessionId, userIds, }: {
+    bulkDeleteUsers({ sessionId, userIds }: {
         sessionId: string;
         userIds: string[];
     }): Promise<{
         deleted: number;
         failed: string[];
     }>;
-    /**
-     * Lock a user account, preventing login. **Admin session required.**
-     *
-     * @param options.duration Lock duration in milliseconds. Defaults to 15 minutes.
-     *
-     * @example
-     * ```ts
-     * await auth.lockAccount({
-     *   sessionId: adminSession.sessionId,
-     *   userId: user.id,
-     *   duration: 60 * 60 * 1000, // 1 hour
-     * });
-     * ```
-     */
-    lockAccount({ sessionId, userId, duration, }: {
+    lockAccount({ sessionId, userId, duration }: {
         sessionId: string;
         userId: string;
         duration?: number;
@@ -480,392 +392,103 @@ declare class AuthClient {
         lockedUntil: number;
         unlockTime: string;
     }>;
-    /**
-     * Unlock a previously locked user account. **Admin session required.**
-     *
-     * @example
-     * ```ts
-     * await auth.unlockAccount({ sessionId: adminSession.sessionId, userId: user.id });
-     * ```
-     */
-    unlockAccount({ sessionId, userId, }: {
+    unlockAccount({ sessionId, userId }: {
         sessionId: string;
         userId: string;
     }): Promise<void>;
-    /**
-     * Change a user's password. The user must supply their current password.
-     *
-     * @example
-     * ```ts
-     * await auth.changePassword({
-     *   sessionId: session.sessionId,
-     *   userId: user.id,
-     *   currentPassword: 'hunter2',
-     *   newPassword: 'correcthorsebatterystaple',
-     * });
-     * ```
-     */
     changePassword(options: ChangePasswordOptions): Promise<void>;
-    /**
-     * Request a password reset email for a user.
-     * Always returns success to prevent user enumeration.
-     *
-     * @example
-     * ```ts
-     * await auth.requestPasswordReset({ email: 'alice@example.com' });
-     * ```
-     */
     requestPasswordReset({ email }: {
         email: string;
     }): Promise<void>;
-    /**
-     * Complete a password reset using the token from the reset email.
-     *
-     * @example
-     * ```ts
-     * await auth.confirmPasswordReset({
-     *   resetToken: 'tok_from_email',
-     *   newPassword: 'correcthorsebatterystaple',
-     * });
-     * ```
-     */
-    confirmPasswordReset({ resetToken, newPassword, }: {
+    confirmPasswordReset({ resetToken, newPassword }: {
         resetToken: string;
         newPassword: string;
     }): Promise<void>;
-    /**
-     * Send (or resend) an email verification message to a user.
-     *
-     * @example
-     * ```ts
-     * await auth.requestEmailVerification({ userId: user.id });
-     * ```
-     */
     requestEmailVerification({ userId }: {
         userId: string;
     }): Promise<void>;
-    /**
-     * Confirm an email address using the token from the verification email.
-     *
-     * @example
-     * ```ts
-     * await auth.confirmEmailVerification({ verifyToken: 'tok_from_email' });
-     * ```
-     */
     confirmEmailVerification({ verifyToken }: {
         verifyToken: string;
     }): Promise<void>;
 }
 
 /**
- * RecordsClient — create, read, update, delete, and query records in a bucket.
- *
- * A bucket is simply a named collection of JSON records. You create buckets
- * from your HydrousDB dashboard. Each record is a JSON object with any fields
- * you want; HydrousDB automatically adds `id`, `createdAt`, and `updatedAt`.
+ * RecordsClient — CRUD + query for a single bucket.
+ * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
  *
  * @example
  * ```ts
- * const db = createClient({ securityKey: 'sk_...' });
+ * const db = createClient({ authKey: '…', bucketSecurityKey: 'hk_bucket_…', storageKeys: { main: '…' } });
  * const posts = db.records('blog-posts');
- *
- * // Create a record
  * const post = await posts.create({ title: 'Hello World', status: 'draft' });
- *
- * // Query records
- * const { records } = await posts.query({
- *   filters: [{ field: 'status', op: '==', value: 'published' }],
- *   limit: 20,
- * });
  * ```
  */
 declare class RecordsClient<T extends RecordData = RecordData> {
     private readonly http;
     private readonly bucketKey;
     private readonly basePath;
-    constructor(http: HttpClient, bucketKey: string);
-    /**
-     * Create a new record.
-     *
-     * @example
-     * ```ts
-     * const user = await records.create({
-     *   name: 'Alice',
-     *   email: 'alice@example.com',
-     *   score: 100,
-     * });
-     * console.log(user.id); // "rec_xxxxxxxx"
-     * ```
-     */
+    private readonly bucketKey_;
+    constructor(http: HttpClient, bucketSecurityKey: string, bucketKey: string);
+    private get key();
     create(data: T): Promise<T & RecordResult>;
-    /**
-     * Fetch a single record by ID.
-     *
-     * @example
-     * ```ts
-     * const post = await records.get('rec_abc123');
-     * ```
-     */
     get(id: string): Promise<T & RecordResult>;
-    /**
-     * Overwrite a record entirely (full replace).
-     *
-     * @example
-     * ```ts
-     * const updated = await records.set('rec_abc123', {
-     *   name: 'Alice Updated',
-     *   email: 'alice2@example.com',
-     * });
-     * ```
-     */
     set(id: string, data: T): Promise<T & RecordResult>;
-    /**
-     * Partially update a record (merge by default).
-     *
-     * @example
-     * ```ts
-     * // Merge: only the provided fields are updated
-     * const updated = await records.patch('rec_abc123', { score: 200 });
-     *
-     * // Replace: equivalent to set()
-     * const replaced = await records.patch('rec_abc123', { score: 200 }, { merge: false });
-     * ```
-     */
     patch(id: string, data: Partial<T>, options?: PatchRecordOptions): Promise<T & RecordResult>;
-    /**
-     * Delete a record permanently.
-     *
-     * @example
-     * ```ts
-     * await records.delete('rec_abc123');
-     * ```
-     */
     delete(id: string): Promise<void>;
-    /**
-     * Create multiple records in one request.
-     *
-     * @example
-     * ```ts
-     * const created = await records.batchCreate([
-     *   { name: 'Alice', score: 100 },
-     *   { name: 'Bob',   score: 200 },
-     * ]);
-     * ```
-     */
     batchCreate(items: T[]): Promise<(T & RecordResult)[]>;
-    /**
-     * Delete multiple records by ID in one request.
-     *
-     * @example
-     * ```ts
-     * await records.batchDelete(['rec_a', 'rec_b', 'rec_c']);
-     * ```
-     */
     batchDelete(ids: string[]): Promise<{
         deleted: number;
         failed: string[];
     }>;
-    /**
-     * Query records with optional filters, sorting, and pagination.
-     *
-     * @example
-     * ```ts
-     * // Simple query
-     * const { records } = await posts.query({ limit: 10 });
-     *
-     * // Filtered query with cursor pagination
-     * const page1 = await posts.query({
-     *   filters: [
-     *     { field: 'status',    op: '==', value: 'published' },
-     *     { field: 'views',     op: '>',  value: 1000 },
-     *   ],
-     *   orderBy: 'createdAt',
-     *   order: 'desc',
-     *   limit: 20,
-     * });
-     *
-     * const page2 = await posts.query({
-     *   filters: [{ field: 'status', op: '==', value: 'published' }],
-     *   limit: 20,
-     *   startAfter: page1.nextCursor,
-     * });
-     * ```
-     */
     query(options?: QueryOptions): Promise<QueryResult<T>>;
-    /**
-     * Convenience alias: get all records up to `limit` (default 100).
-     *
-     * @example
-     * ```ts
-     * const allPosts = await posts.getAll({ limit: 500 });
-     * ```
-     */
     getAll(options?: Omit<QueryOptions, 'filters'>): Promise<(T & RecordResult)[]>;
-    /**
-     * Count records matching optional filters.
-     *
-     * @example
-     * ```ts
-     * const total = await posts.count([{ field: 'status', op: '==', value: 'published' }]);
-     * ```
-     */
     count(filters?: QueryOptions['filters']): Promise<number>;
-    /**
-     * Retrieve the full version history of a record.
-     * Each write creates a new version stored in GCS.
-     *
-     * @example
-     * ```ts
-     * const history = await records.getHistory('rec_abc123');
-     * console.log(history[0].data); // latest version
-     * ```
-     */
     getHistory(id: string): Promise<RecordHistoryEntry[]>;
-    /**
-     * Restore a record to a specific historical version.
-     *
-     * @example
-     * ```ts
-     * const history = await records.getHistory('rec_abc123');
-     * const restored = await records.restoreVersion('rec_abc123', history[2].version);
-     * ```
-     */
     restoreVersion(id: string, version: number): Promise<T & RecordResult>;
 }
 
 /**
- * AnalyticsClient — run powerful aggregation and time-series queries against
- * your bucket data using BigQuery under the hood.
- *
- * All query types accept an optional `dateRange` to filter by time.
- * The security key is sent automatically — you never pass it manually.
+ * AnalyticsClient — BigQuery-powered aggregations for a bucket.
+ * Uses the `bucketSecurityKey` (`hk_bucket_…`) sent via `X-Api-Key` header.
  *
  * @example
  * ```ts
- * const db = createClient({ securityKey: 'sk_...' });
+ * const db = createClient({ authKey: '…', bucketSecurityKey: 'hk_bucket_…', storageKeys: { main: '…' } });
  * const analytics = db.analytics('orders');
- *
- * // How many orders in the last 30 days?
- * const { count } = await analytics.count({
- *   dateRange: { start: Date.now() - 30 * 24 * 60 * 60 * 1000, end: Date.now() },
- * });
+ * const { count } = await analytics.count();
  * ```
  */
 declare class AnalyticsClient {
     private readonly http;
-    private readonly bucketKey;
+    private readonly bucketSecurityKey;
     private readonly basePath;
-    constructor(http: HttpClient, bucketKey: string);
-    /** Internal dispatcher — all queries POST to the same endpoint. */
+    constructor(http: HttpClient, bucketSecurityKey: string, bucketKey: string);
     private run;
-    /**
-     * Count the total number of records in the bucket, with optional date filter.
-     *
-     * @example
-     * ```ts
-     * const { count } = await analytics.count();
-     * // → { count: 4821 }
-     *
-     * // Count only this month's records
-     * const { count } = await analytics.count({
-     *   dateRange: { start: new Date('2025-01-01').getTime(), end: Date.now() },
-     * });
-     * ```
-     */
     count(opts?: {
         dateRange?: DateRange;
     }): Promise<CountResult>;
-    /**
-     * Count how many records have each unique value for a given field.
-     * Great for pie charts and bar charts.
-     *
-     * @example
-     * ```ts
-     * const rows = await analytics.distribution({
-     *   field: 'status',
-     *   limit: 10,
-     *   order: 'desc',
-     * });
-     * // → [{ value: 'completed', count: 312 }, { value: 'pending', count: 88 }, ...]
-     * ```
-     */
     distribution(opts: {
         field: string;
         limit?: number;
         order?: SortOrder;
         dateRange?: DateRange;
     }): Promise<DistributionRow[]>;
-    /**
-     * Sum a numeric field, optionally grouped by another field.
-     *
-     * @example
-     * ```ts
-     * // Total revenue
-     * const rows = await analytics.sum({ field: 'amount' });
-     * // → [{ sum: 198432.50 }]
-     *
-     * // Revenue by country
-     * const rows = await analytics.sum({ field: 'amount', groupBy: 'country', limit: 10 });
-     * // → [{ group: 'US', sum: 120000 }, { group: 'UK', sum: 45000 }, ...]
-     * ```
-     */
     sum(opts: {
         field: string;
         groupBy?: string;
         limit?: number;
         dateRange?: DateRange;
     }): Promise<SumRow[]>;
-    /**
-     * Count records created over time, grouped by a time granularity.
-     * Perfect for line charts and activity graphs.
-     *
-     * @example
-     * ```ts
-     * const rows = await analytics.timeSeries({
-     *   granularity: 'day',
-     *   dateRange: { start: Date.now() - 7 * 86400000, end: Date.now() },
-     * });
-     * // → [{ date: '2025-06-01', count: 42 }, { date: '2025-06-02', count: 67 }, ...]
-     * ```
-     */
     timeSeries(opts?: {
         granularity?: Granularity;
         dateRange?: DateRange;
     }): Promise<TimeSeriesRow[]>;
-    /**
-     * Aggregate a numeric field over time (e.g. daily revenue, hourly signups).
-     *
-     * @example
-     * ```ts
-     * const rows = await analytics.fieldTimeSeries({
-     *   field: 'amount',
-     *   aggregation: 'sum',
-     *   granularity: 'week',
-     * });
-     * // → [{ date: '2025-W22', value: 14230.50 }, ...]
-     * ```
-     */
     fieldTimeSeries(opts: {
         field: string;
         aggregation?: Aggregation;
         granularity?: Granularity;
         dateRange?: DateRange;
     }): Promise<FieldTimeSeriesRow[]>;
-    /**
-     * Get the top N values by frequency for a field.
-     * Optionally pair with a `labelField` for human-readable labels.
-     *
-     * @example
-     * ```ts
-     * // Top 5 most purchased products
-     * const rows = await analytics.topN({
-     *   field: 'productId',
-     *   labelField: 'productName',
-     *   n: 5,
-     * });
-     * // → [{ value: 'prod_123', label: 'Widget Pro', count: 892 }, ...]
-     * ```
-     */
     topN(opts: {
         field: string;
         n?: number;
@@ -873,34 +496,10 @@ declare class AnalyticsClient {
         order?: SortOrder;
         dateRange?: DateRange;
     }): Promise<TopNRow[]>;
-    /**
-     * Get statistical summary (min, max, avg, sum, count, stddev) for a numeric field.
-     *
-     * @example
-     * ```ts
-     * const stats = await analytics.stats({ field: 'orderValue' });
-     * // → { min: 4.99, max: 9999.99, avg: 87.23, sum: 420948.27, count: 4823, stddev: 143.2 }
-     * ```
-     */
     stats(opts: {
         field: string;
         dateRange?: DateRange;
     }): Promise<FieldStats>;
-    /**
-     * Query raw records with filters, field selection, and pagination.
-     * This is the analytics version of `records.query()` but powered by BigQuery.
-     *
-     * @example
-     * ```ts
-     * const { records } = await analytics.records({
-     *   filters: [{ field: 'status', op: '==', value: 'refunded' }],
-     *   selectFields: ['orderId', 'amount', 'createdAt'],
-     *   limit: 50,
-     *   orderBy: 'amount',
-     *   order: 'desc',
-     * });
-     * ```
-     */
     records<T extends RecordData = RecordData>(opts?: {
         filters?: AnalyticsFilter[];
         selectFields?: string[];
@@ -910,100 +509,35 @@ declare class AnalyticsClient {
         order?: SortOrder;
         dateRange?: DateRange;
     }): Promise<(T & RecordResult)[]>;
-    /**
-     * Calculate multiple aggregations in a single query.
-     * Ideal for dashboards that need several numbers at once.
-     *
-     * @example
-     * ```ts
-     * const result = await analytics.multiMetric({
-     *   metrics: [
-     *     { field: 'amount',   name: 'totalRevenue', aggregation: 'sum' },
-     *     { field: 'amount',   name: 'avgOrderValue', aggregation: 'avg' },
-     *     { field: 'userId',   name: 'uniqueCustomers', aggregation: 'count' },
-     *   ],
-     * });
-     * // → { totalRevenue: 198432.50, avgOrderValue: 87.23, uniqueCustomers: 2275 }
-     * ```
-     */
     multiMetric(opts: {
         metrics: MetricDefinition[];
         dateRange?: DateRange;
     }): Promise<MultiMetricResult>;
-    /**
-     * Get storage statistics for this bucket: record counts, byte sizes.
-     *
-     * @example
-     * ```ts
-     * const stats = await analytics.storageStats();
-     * // → { totalRecords: 4821, totalBytes: 48293820, avgBytes: 10015, ... }
-     * ```
-     */
     storageStats(opts?: {
         dateRange?: DateRange;
     }): Promise<StorageStatsResult>;
-    /**
-     * Compare the same field aggregation across multiple buckets in one query.
-     * Your security key must have read access to ALL listed buckets.
-     *
-     * @example
-     * ```ts
-     * const rows = await analytics.crossBucket({
-     *   bucketKeys: ['orders-us', 'orders-eu', 'orders-apac'],
-     *   field: 'amount',
-     *   aggregation: 'sum',
-     * });
-     * // → [
-     * //   { bucket: 'orders-us',   value: 120000 },
-     * //   { bucket: 'orders-eu',   value: 45000 },
-     * //   { bucket: 'orders-apac', value: 33000 },
-     * // ]
-     * ```
-     */
     crossBucket(opts: {
         bucketKeys: string[];
         field: string;
         aggregation?: Aggregation;
         dateRange?: DateRange;
     }): Promise<CrossBucketRow[]>;
-    /**
-     * Send a raw analytics query object. Use this when you need full control
-     * over the query shape or want to use a queryType not covered by the helpers.
-     *
-     * @example
-     * ```ts
-     * const result = await analytics.query({
-     *   queryType: 'topN',
-     *   field: 'category',
-     *   n: 3,
-     *   order: 'asc',
-     * });
-     * ```
-     */
     query<T = unknown>(query: AnalyticsQuery): Promise<AnalyticsResult<T>>;
 }
 
 /**
  * StorageManager — upload, download, list, move, copy, and delete files.
+ * Uses an `X-Storage-Key` (`ssk_…`) header — separate from auth and bucket keys.
+ * Each key is scoped to a specific storage bucket and permission set.
  *
- * Authentication is handled automatically via the X-Storage-Key header.
- * Files are scoped to your owner ID — you can never access another owner's files.
- *
- * **Recommended upload flow** (for progress tracking and large files):
- * 1. Call `getUploadUrl()` to get a signed PUT URL.
- * 2. Upload directly to GCS using XHR (supports progress events).
- * 3. Call `confirmUpload()` to finalize metadata.
- *
- * **Simple upload** (small files, no progress needed):
- * - Call `upload()` — it handles everything in one call.
+ * Get a StorageManager via `db.storage('keyName')` where the key name
+ * matches one of the keys you defined in `storageKeys` when calling `createClient`.
  *
  * @example
  * ```ts
- * const db = createClient({ securityKey: 'sk_...' });
- *
- * // Simple upload
- * const file = await db.storage.upload(fileBlob, 'avatars/alice.jpg', { isPublic: true });
- * console.log(file.publicUrl); // CDN URL, usable anywhere
+ * const db = createClient({ authKey: '…', bucketSecurityKey: '…', storageKeys: { avatars: 'ssk_avatars_…' } });
+ * const avatars = db.storage('avatars');
+ * const result = await avatars.upload(file, 'alice.jpg', { isPublic: true });
  * ```
  */
 declare class StorageManager {
@@ -1300,8 +834,6 @@ declare class StorageManager {
     }>;
 }
 
-/** Accepted data types for file uploads. */
-type UploadData = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer;
 /**
  * ScopedStorage — a StorageManager pre-scoped to a specific folder prefix.
  *
@@ -1326,7 +858,7 @@ declare class ScopedStorage {
     constructor(manager: StorageManager, prefix: string);
     private scopedPath;
     /** Upload a file within the scoped folder. */
-    upload(data: UploadData, path: string, options?: UploadOptions): Promise<UploadResult>;
+    upload(data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | Buffer, path: string, options?: UploadOptions): Promise<UploadResult>;
     /** Upload raw JSON or text within the scoped folder. */
     uploadRaw(data: unknown, path: string, options?: UploadOptions): Promise<UploadResult>;
     /** Get a signed upload URL for a file within the scoped folder. */
@@ -1337,8 +869,6 @@ declare class ScopedStorage {
         isPublic?: boolean;
         overwrite?: boolean;
     }): Promise<UploadUrlResult>;
-    /** Upload data directly to a signed GCS URL with optional progress tracking. */
-    uploadToSignedUrl(signedUrl: string, data: Blob | Uint8Array<ArrayBuffer> | ArrayBuffer, mimeType: string, onProgress?: (percent: number) => void): Promise<void>;
     /** Confirm a direct upload within the scoped folder. */
     confirmUpload(opts: {
         path: string;
@@ -1347,7 +877,10 @@ declare class ScopedStorage {
     }): Promise<UploadResult>;
     /** Download a file within the scoped folder. */
     download(path: string): Promise<ArrayBuffer>;
-    /** List files within the scoped folder. */
+    /**
+     * List files within the scoped folder.
+     * `prefix` in options is relative to the scope.
+     */
     list(opts?: ListOptions): Promise<ListResult>;
     /** Get metadata for a file within the scoped folder. */
     getMetadata(path: string): Promise<FileMetadata>;
@@ -1384,7 +917,7 @@ declare class ScopedStorage {
      * @example
      * ```ts
      * const uploads = db.storage.scope('user-uploads');
-     * const images  = uploads.scope('images'); // → "user-uploads/images/"
+     * const images = uploads.scope('images');   // → "user-uploads/images/"
      * ```
      */
     scope(subPrefix: string): ScopedStorage;
@@ -1393,75 +926,73 @@ declare class ScopedStorage {
 /**
  * HydrousClient — the main entry point for the HydrousDB SDK.
  *
- * Create one instance per application (it is safe to share globally).
- * Every sub-client (`auth`, `records`, `analytics`, `storage`) is lazily
- * instantiated and cached on first access.
+ * Each service uses its own dedicated key:
+ * - `authKey`            (`hk_auth_…`)   → `db.auth('bucket')`
+ * - `bucketSecurityKey`  (`hk_bucket_…`) → `db.records('bucket')` + `db.analytics('bucket')`
+ * - `storageKeys`        (`ssk_…`)       → `db.storage('keyName')`
  *
  * @example
  * ```ts
  * import { createClient } from 'hydrousdb';
  *
- * const db = createClient({ securityKey: 'sk_live_...' });
- *
- * // Records
- * const posts   = db.records('blog-posts');
- * const users   = db.records('app-users');
- *
- * // Auth
- * const auth    = db.auth('app-users');
+ * const db = createClient({
+ *   authKey:           'hk_auth_…',
+ *   bucketSecurityKey: 'hk_bucket_…',
+ *   storageKeys: {
+ *     main:      'ssk_main_…',
+ *     avatars:   'ssk_avatars_…',
+ *     documents: 'ssk_docs_…',
+ *   },
+ * });
  *
- * // Analytics
- * const stats   = db.analytics('orders');
+ * // Records & Analytics — use bucketSecurityKey automatically
+ * const posts     = db.records('blog-posts');
+ * const analytics = db.analytics('orders');
  *
- * // Storage (flat)
- * const storage = db.storage;               // StorageManager
+ * // Auth — uses authKey automatically
+ * const auth = db.auth('app-users');
  *
- * // Storage (scoped to a folder)
- * const avatars = db.storage.scope('avatars');
+ * // Storage — pick which key to use by name
+ * const avatarStorage   = db.storage('avatars');
+ * const documentStorage = db.storage('documents');
  * ```
  */
 declare class HydrousClient {
     private readonly http;
-    private readonly _storageKey;
-    private _storage;
+    private readonly authKey_;
+    private readonly bucketSecurityKey_;
+    private readonly storageKeys_;
     private readonly _recordsCache;
     private readonly _authCache;
     private readonly _analyticsCache;
+    private readonly _storageCache;
     constructor(config: HydrousConfig);
     /**
-     * Get a typed records client for the given bucket.
-     *
-     * The generic type parameter `T` describes the shape of records in this
-     * bucket. Leave it unset for a generic `Record<string, unknown>` shape.
-     *
-     * @param bucketKey  The name of your bucket (must match what you created in the dashboard).
+     * Get a typed records client for the named bucket.
+     * Uses your `bucketSecurityKey` automatically.
      *
      * @example
      * ```ts
-     * interface Post { title: string; body: string; published: boolean }
+     * interface Post { title: string; published: boolean }
      * const posts = db.records<Post>('blog-posts');
-     *
-     * const post = await posts.create({ title: 'Hello', body: '...', published: false });
-     * // post.id, post.createdAt, post.updatedAt are added automatically
+     * const post = await posts.create({ title: 'Hello', published: false });
      * ```
      */
     records<T extends RecordData = RecordData>(bucketKey: string): RecordsClient<T>;
     /**
-     * Get an auth client for the given user bucket.
-     *
-     * @param bucketKey  The name of your user bucket (e.g. `"app-users"`).
+     * Get an auth client for the named user bucket.
+     * Uses your `authKey` automatically.
      *
      * @example
      * ```ts
      * const auth = db.auth('app-users');
-     * const { user, session } = await auth.login({ email: '...', password: '...' });
+     * const { user, session } = await auth.login({ email: '…', password: '…' });
      * ```
      */
     auth(bucketKey: string): AuthClient;
     /**
-     * Get an analytics client for the given bucket.
-     *
-     * @param bucketKey  The name of the bucket to analyse.
+     * Get an analytics client for the named bucket.
+     * Uses your `bucketSecurityKey` automatically.
      *
      * @example
      * ```ts
@@ -1471,48 +1002,57 @@ declare class HydrousClient {
      */
     analytics(bucketKey: string): AnalyticsClient;
     /**
-     * The storage manager for uploading, downloading, listing, and managing files.
+     * Get a storage manager for the named storage key.
+     * The name must match a key you defined in `storageKeys` when calling `createClient`.
+     * Uses the corresponding `ssk_…` key automatically via `X-Storage-Key` header.
      *
-     * Scoped to your project — you can never access another project's files.
+     * @param keyName  The name of the storage key (e.g. `"avatars"`, `"documents"`, `"main"`).
      *
      * @example
      * ```ts
-     * // Upload a file
-     * const result = await db.storage.upload(file, 'images/photo.jpg', { isPublic: true });
+     * const avatars   = db.storage('avatars');
+     * const documents = db.storage('documents');
+     *
+     * // Upload to avatars bucket
+     * await avatars.upload(file, `${userId}.jpg`, { isPublic: true });
      *
-     * // Scope to a folder
-     * const avatars = db.storage.scope('user-avatars');
-     * await avatars.upload(blob, `${userId}.jpg`, { isPublic: true });
+     * // Scope to a sub-folder
+     * const userDocs = db.storage('documents').scope(`users/${userId}`);
+     * await userDocs.upload(pdfBuffer, 'contract.pdf');
      * ```
      */
-    get storage(): StorageManager & {
+    storage(keyName: string): StorageManager & {
         scope: (prefix: string) => ScopedStorage;
     };
 }
 /**
  * Create a new HydrousDB client.
  *
- * This is the **only** export you need to get started.
- * The API URL is pre-configured — you only need your Security Key.
- *
- * @param config.securityKey  Your project's Security Key from https://hydrousdb.com/dashboard
- * @param config.baseUrl      (Optional) Override the API base URL.
- *
  * @example
  * ```ts
  * import { createClient } from 'hydrousdb';
  *
  * const db = createClient({
- *   securityKey: process.env.HYDROUS_SECURITY_KEY!,
+ *   authKey:           process.env.HYDROUS_AUTH_KEY!,
+ *   bucketSecurityKey: process.env.HYDROUS_BUCKET_KEY!,
+ *   storageKeys: {
+ *     main:      process.env.HYDROUS_STORAGE_MAIN!,
+ *     avatars:   process.env.HYDROUS_STORAGE_AVATARS!,
+ *     documents: process.env.HYDROUS_STORAGE_DOCS!,
+ *   },
  * });
  * ```
  */
 declare function createClient(config: HydrousConfig): HydrousClient;
 
 declare class HydrousError extends Error {
+    /** Machine-readable error code returned by the API. */
     readonly code: string;
+    /** HTTP status code (if applicable). */
     readonly status?: number;
+    /** The original request ID for support tracing. */
     readonly requestId?: string;
+    /** Additional validation details. */
     readonly details?: string[];
     constructor(message: string, code: string, status?: number, requestId?: string, details?: string[]);
     toString(): string;