hydrousdb 1.1.0

package/dist/records/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/query.ts","../../src/records/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Filter, QueryOptions } from '../types/index.js';\n\n/**\n * Converts a QueryOptions object into a flat Record suitable for URLSearchParams.\n *\n * Filter fields use the `field[op]=value` convention:\n *   { field: 'status', op: '==', value: 'active' }  → status=active\n *   { field: 'score',  op: '>',  value: 50 }         → score[>]=50\n */\nexport function buildQueryParams(\n  opts: QueryOptions\n): Record<string, string | number | boolean> {\n  const params: Record<string, string | number | boolean> = {};\n\n  if (opts.timeScope)  params['timeScope']  = opts.timeScope;\n  if (opts.year)       params['year']       = opts.year;\n  if (opts.sortOrder)  params['sortOrder']  = opts.sortOrder;\n  if (opts.limit)      params['limit']      = opts.limit;\n  if (opts.cursor)     params['cursor']     = opts.cursor;\n  if (opts.fields)     params['fields']     = opts.fields;\n\n  for (const filter of opts.filters ?? []) {\n    const paramKey = filter.op === '==' ? filter.field : `${filter.field}[${filter.op}]`;\n    params[paramKey] = filter.value as string | number | boolean;\n  }\n\n  return params;\n}\n\n/**\n * Validates a filter array and throws a descriptive error if invalid.\n */\nexport function validateFilters(filters: Filter[]): void {\n  const VALID_OPS = new Set(['==', '!=', '>', '<', '>=', '<=', 'contains']);\n\n  if (filters.length > 3) {\n    throw new Error('HydrousDB supports a maximum of 3 filters per query.');\n  }\n\n  for (const f of filters) {\n    if (!VALID_OPS.has(f.op)) {\n      throw new Error(\n        `Invalid filter operator \"${f.op}\". Valid operators: ${[...VALID_OPS].join(', ')}`\n      );\n    }\n    if (!f.field || typeof f.field !== 'string') {\n      throw new Error('Each filter must have a non-empty \"field\" string.');\n    }\n  }\n}\n","import type { HttpClient } from '../utils/http.js';\nimport { buildQueryParams, validateFilters } from '../utils/query.js';\nimport type {\n  GetRecordOptions,\n  GetRecordResponse,\n  GetSnapshotResponse,\n  QueryOptions,\n  QueryResponse,\n  InsertRecordPayload,\n  InsertRecordResponse,\n  UpdateRecordPayload,\n  UpdateRecordResponse,\n  DeleteRecordResponse,\n  RecordExistsInfo,\n  BatchUpdatePayload,\n  BatchUpdateResponse,\n  BatchDeletePayload,\n  BatchDeleteResponse,\n  BatchInsertPayload,\n  BatchInsertResponse,\n  RecordData,\n  HydrousRecord,\n  RequestOptions,\n} from '../types/index.js';\n\nexport class RecordsClient {\n  constructor(private readonly http: HttpClient) { }\n\n  private get path() {\n    return `/api/${this.http.bucketKey}`;\n  }\n\n  // ── GET — single record ────────────────────────────────────────────────────\n\n  /**\n   * Fetch a single record by ID.\n   *\n   * @example\n   * const { data } = await db.records.get('rec_abc123');\n   * const { data, history } = await db.records.get('rec_abc123', { showHistory: true });\n   */\n  async get(recordId: string, options?: GetRecordOptions & RequestOptions): Promise<GetRecordResponse> {\n    const params: Record<string, string | number | boolean | undefined | null> = { recordId };\n    if (options?.showHistory) params['showHistory'] = 'true';\n    return this.http.get<GetRecordResponse>(this.path, params, options);\n  }\n\n  // ── GET — historical snapshot ──────────────────────────────────────────────\n\n  /**\n   * Fetch a specific historical version (generation) of a record.\n   *\n   * @example\n   * const { data } = await db.records.getSnapshot('rec_abc123', '1700000000000000');\n   */\n  async getSnapshot(recordId: string, generation: string, opts?: RequestOptions): Promise<GetSnapshotResponse> {\n    return this.http.get<GetSnapshotResponse>(this.path, { recordId, generation }, opts);\n  }\n\n  // ── GET — collection query ─────────────────────────────────────────────────\n\n  /**\n   * Query a collection with optional filters, sorting, and pagination.\n   *\n   * @example\n   * // Simple query\n   * const { data, meta } = await db.records.query({ limit: 50, sortOrder: 'desc' });\n   *\n   * // Filtered query\n   * const { data } = await db.records.query({\n   *   filters: [{ field: 'status', op: '==', value: 'active' }],\n   *   timeScope: '7d',\n   * });\n   *\n   * // Paginated\n   * let cursor: string | null = null;\n   * do {\n   *   const result = await db.records.query({ limit: 100, cursor: cursor ?? undefined });\n   *   cursor = result.meta.nextCursor;\n   * } while (cursor);\n   */\n  async query<T extends RecordData = RecordData>(\n    options?: QueryOptions & RequestOptions\n  ): Promise<QueryResponse<T>> {\n    if (options?.filters) validateFilters(options.filters);\n    const params = buildQueryParams(options ?? {});\n    return this.http.get<QueryResponse<T>>(this.path, params, options);\n  }\n\n  // ── POST — insert ──────────────────────────────────────────────────────────\n\n  /**\n   * Insert a new record.\n   *\n   * @example\n   * const { data, meta } = await db.records.insert({\n   *   values: { name: 'Alice', score: 99 },\n   *   queryableFields: ['name'],\n   *   userEmail: 'alice@example.com',\n   * });\n   */\n  async insert(payload: InsertRecordPayload, opts?: RequestOptions): Promise<InsertRecordResponse> {\n    return this.http.post<InsertRecordResponse>(this.path, payload, opts);\n  }\n\n  // ── PATCH — update ─────────────────────────────────────────────────────────\n\n  /**\n   * Update an existing record.\n   *\n   * @example\n   * await db.records.update({\n   *   recordId: 'rec_abc123',\n   *   values: { score: 100 },\n   *   track_record_history: true,\n   * });\n   */\n  async update(payload: UpdateRecordPayload, opts?: RequestOptions): Promise<UpdateRecordResponse> {\n    return this.http.patch<UpdateRecordResponse>(this.path, payload, opts);\n  }\n\n  // ── DELETE ─────────────────────────────────────────────────────────────────\n\n  /**\n   * Delete a record permanently.\n   *\n   * @example\n   * await db.records.delete('rec_abc123');\n   */\n  async delete(recordId: string, opts?: RequestOptions): Promise<DeleteRecordResponse> {\n    return this.http.delete<DeleteRecordResponse>(this.path, { recordId }, opts);\n  }\n\n  // ── HEAD — existence check ─────────────────────────────────────────────────\n\n  /**\n   * Check whether a record exists without fetching its full data.\n   * Returns `null` if the record is not found.\n   *\n   * @example\n   * const info = await db.records.exists('rec_abc123');\n   * if (info?.exists) console.log('found at', info.updatedAt);\n   */\n  async exists(recordId: string, opts?: RequestOptions): Promise<RecordExistsInfo | null> {\n    const res = await this.http.head(this.path, { recordId }, opts);\n\n    if (res.status === 404) return null;\n    if (!res.ok) return null;\n\n    return {\n      exists: true,\n      id: res.headers.get('X-Record-Id') ?? recordId,\n      createdAt: res.headers.get('X-Created-At') ?? '',\n      updatedAt: res.headers.get('X-Updated-At') ?? '',\n      sizeBytes: res.headers.get('X-Size-Bytes') ?? '',\n    };\n  }\n\n  // ── Batch — update ─────────────────────────────────────────────────────────\n\n  /**\n   * Update up to 500 records in a single request.\n   *\n   * @example\n   * await db.records.batchUpdate({\n   *   updates: [\n   *     { recordId: 'rec_1', values: { status: 'archived' } },\n   *     { recordId: 'rec_2', values: { status: 'archived' } },\n   *   ],\n   * });\n   */\n  async batchUpdate(payload: BatchUpdatePayload, opts?: RequestOptions): Promise<BatchUpdateResponse> {\n    return this.http.post<BatchUpdateResponse>(\n      `${this.path}/batch/update`,\n      payload,\n      opts\n    );\n  }\n\n  // ── Batch — delete ─────────────────────────────────────────────────────────\n\n  /**\n   * Delete up to 500 records in a single request.\n   *\n   * @example\n   * await db.records.batchDelete({ recordIds: ['rec_1', 'rec_2', 'rec_3'] });\n   */\n  async batchDelete(payload: BatchDeletePayload, opts?: RequestOptions): Promise<BatchDeleteResponse> {\n    return this.http.post<BatchDeleteResponse>(\n      `${this.path}/batch/delete`,\n      payload,\n      opts\n    );\n  }\n\n  // ── Batch — insert ─────────────────────────────────────────────────────────\n\n  /**\n   * Insert up to 500 records in a single request.\n   * Returns HTTP 207 (multi-status) — check `meta.failed` for partial failures.\n   *\n   * @example\n   * const result = await db.records.batchInsert({\n   *   records: [{ name: 'Alice' }, { name: 'Bob' }],\n   *   queryableFields: ['name'],\n   * });\n   */\n  async batchInsert(payload: BatchInsertPayload, opts?: RequestOptions): Promise<BatchInsertResponse> {\n    return this.http.post<BatchInsertResponse>(\n      `${this.path}/batch/insert`,\n      payload,\n      opts\n    );\n  }\n\n  // ── Helpers ────────────────────────────────────────────────────────────────\n\n  /**\n   * Fetch ALL records matching a query, automatically following cursors.\n   * Use with care on large collections — prefer `query()` with manual pagination.\n   *\n   * @example\n   * const allRecords = await db.records.queryAll({\n   *   filters: [{ field: 'type', op: '==', value: 'invoice' }],\n   * });\n   */\n  async queryAll<T extends RecordData = RecordData>(\n    options?: Omit<QueryOptions, 'cursor'> & RequestOptions\n  ): Promise<(T & HydrousRecord)[]> {\n    const all: (T & HydrousRecord)[] = [];\n    let cursor: string | null = null;\n\n    do {\n      const result: any = await this.query<T>(cursor ? { ...options, cursor } : { ...options });\n      all.push(...result.data);\n      cursor = result.meta.nextCursor ?? null;\n    } while (cursor);\n\n    return all;\n  }\n}\n"]}

package/dist/records/index.mjs

@@ -0,0 +1,224 @@
+// src/utils/query.ts
+function buildQueryParams(opts) {
+  const params = {};
+  if (opts.timeScope) params["timeScope"] = opts.timeScope;
+  if (opts.year) params["year"] = opts.year;
+  if (opts.sortOrder) params["sortOrder"] = opts.sortOrder;
+  if (opts.limit) params["limit"] = opts.limit;
+  if (opts.cursor) params["cursor"] = opts.cursor;
+  if (opts.fields) params["fields"] = opts.fields;
+  for (const filter of opts.filters ?? []) {
+    const paramKey = filter.op === "==" ? filter.field : `${filter.field}[${filter.op}]`;
+    params[paramKey] = filter.value;
+  }
+  return params;
+}
+function validateFilters(filters) {
+  const VALID_OPS = /* @__PURE__ */ new Set(["==", "!=", ">", "<", ">=", "<=", "contains"]);
+  if (filters.length > 3) {
+    throw new Error("HydrousDB supports a maximum of 3 filters per query.");
+  }
+  for (const f of filters) {
+    if (!VALID_OPS.has(f.op)) {
+      throw new Error(
+        `Invalid filter operator "${f.op}". Valid operators: ${[...VALID_OPS].join(", ")}`
+      );
+    }
+    if (!f.field || typeof f.field !== "string") {
+      throw new Error('Each filter must have a non-empty "field" string.');
+    }
+  }
+}
+
+// src/records/client.ts
+var RecordsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  get path() {
+    return `/api/${this.http.bucketKey}`;
+  }
+  // ── GET — single record ────────────────────────────────────────────────────
+  /**
+   * Fetch a single record by ID.
+   *
+   * @example
+   * const { data } = await db.records.get('rec_abc123');
+   * const { data, history } = await db.records.get('rec_abc123', { showHistory: true });
+   */
+  async get(recordId, options) {
+    const params = { recordId };
+    if (options?.showHistory) params["showHistory"] = "true";
+    return this.http.get(this.path, params, options);
+  }
+  // ── GET — historical snapshot ──────────────────────────────────────────────
+  /**
+   * Fetch a specific historical version (generation) of a record.
+   *
+   * @example
+   * const { data } = await db.records.getSnapshot('rec_abc123', '1700000000000000');
+   */
+  async getSnapshot(recordId, generation, opts) {
+    return this.http.get(this.path, { recordId, generation }, opts);
+  }
+  // ── GET — collection query ─────────────────────────────────────────────────
+  /**
+   * Query a collection with optional filters, sorting, and pagination.
+   *
+   * @example
+   * // Simple query
+   * const { data, meta } = await db.records.query({ limit: 50, sortOrder: 'desc' });
+   *
+   * // Filtered query
+   * const { data } = await db.records.query({
+   *   filters: [{ field: 'status', op: '==', value: 'active' }],
+   *   timeScope: '7d',
+   * });
+   *
+   * // Paginated
+   * let cursor: string | null = null;
+   * do {
+   *   const result = await db.records.query({ limit: 100, cursor: cursor ?? undefined });
+   *   cursor = result.meta.nextCursor;
+   * } while (cursor);
+   */
+  async query(options) {
+    if (options?.filters) validateFilters(options.filters);
+    const params = buildQueryParams(options ?? {});
+    return this.http.get(this.path, params, options);
+  }
+  // ── POST — insert ──────────────────────────────────────────────────────────
+  /**
+   * Insert a new record.
+   *
+   * @example
+   * const { data, meta } = await db.records.insert({
+   *   values: { name: 'Alice', score: 99 },
+   *   queryableFields: ['name'],
+   *   userEmail: 'alice@example.com',
+   * });
+   */
+  async insert(payload, opts) {
+    return this.http.post(this.path, payload, opts);
+  }
+  // ── PATCH — update ─────────────────────────────────────────────────────────
+  /**
+   * Update an existing record.
+   *
+   * @example
+   * await db.records.update({
+   *   recordId: 'rec_abc123',
+   *   values: { score: 100 },
+   *   track_record_history: true,
+   * });
+   */
+  async update(payload, opts) {
+    return this.http.patch(this.path, payload, opts);
+  }
+  // ── DELETE ─────────────────────────────────────────────────────────────────
+  /**
+   * Delete a record permanently.
+   *
+   * @example
+   * await db.records.delete('rec_abc123');
+   */
+  async delete(recordId, opts) {
+    return this.http.delete(this.path, { recordId }, opts);
+  }
+  // ── HEAD — existence check ─────────────────────────────────────────────────
+  /**
+   * Check whether a record exists without fetching its full data.
+   * Returns `null` if the record is not found.
+   *
+   * @example
+   * const info = await db.records.exists('rec_abc123');
+   * if (info?.exists) console.log('found at', info.updatedAt);
+   */
+  async exists(recordId, opts) {
+    const res = await this.http.head(this.path, { recordId }, opts);
+    if (res.status === 404) return null;
+    if (!res.ok) return null;
+    return {
+      exists: true,
+      id: res.headers.get("X-Record-Id") ?? recordId,
+      createdAt: res.headers.get("X-Created-At") ?? "",
+      updatedAt: res.headers.get("X-Updated-At") ?? "",
+      sizeBytes: res.headers.get("X-Size-Bytes") ?? ""
+    };
+  }
+  // ── Batch — update ─────────────────────────────────────────────────────────
+  /**
+   * Update up to 500 records in a single request.
+   *
+   * @example
+   * await db.records.batchUpdate({
+   *   updates: [
+   *     { recordId: 'rec_1', values: { status: 'archived' } },
+   *     { recordId: 'rec_2', values: { status: 'archived' } },
+   *   ],
+   * });
+   */
+  async batchUpdate(payload, opts) {
+    return this.http.post(
+      `${this.path}/batch/update`,
+      payload,
+      opts
+    );
+  }
+  // ── Batch — delete ─────────────────────────────────────────────────────────
+  /**
+   * Delete up to 500 records in a single request.
+   *
+   * @example
+   * await db.records.batchDelete({ recordIds: ['rec_1', 'rec_2', 'rec_3'] });
+   */
+  async batchDelete(payload, opts) {
+    return this.http.post(
+      `${this.path}/batch/delete`,
+      payload,
+      opts
+    );
+  }
+  // ── Batch — insert ─────────────────────────────────────────────────────────
+  /**
+   * Insert up to 500 records in a single request.
+   * Returns HTTP 207 (multi-status) — check `meta.failed` for partial failures.
+   *
+   * @example
+   * const result = await db.records.batchInsert({
+   *   records: [{ name: 'Alice' }, { name: 'Bob' }],
+   *   queryableFields: ['name'],
+   * });
+   */
+  async batchInsert(payload, opts) {
+    return this.http.post(
+      `${this.path}/batch/insert`,
+      payload,
+      opts
+    );
+  }
+  // ── Helpers ────────────────────────────────────────────────────────────────
+  /**
+   * Fetch ALL records matching a query, automatically following cursors.
+   * Use with care on large collections — prefer `query()` with manual pagination.
+   *
+   * @example
+   * const allRecords = await db.records.queryAll({
+   *   filters: [{ field: 'type', op: '==', value: 'invoice' }],
+   * });
+   */
+  async queryAll(options) {
+    const all = [];
+    let cursor = null;
+    do {
+      const result = await this.query(cursor ? { ...options, cursor } : { ...options });
+      all.push(...result.data);
+      cursor = result.meta.nextCursor ?? null;
+    } while (cursor);
+    return all;
+  }
+};
+
+export { RecordsClient };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/records/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/query.ts","../../src/records/client.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import type { Filter, QueryOptions } from '../types/index.js';\n\n/**\n * Converts a QueryOptions object into a flat Record suitable for URLSearchParams.\n *\n * Filter fields use the `field[op]=value` convention:\n *   { field: 'status', op: '==', value: 'active' }  → status=active\n *   { field: 'score',  op: '>',  value: 50 }         → score[>]=50\n */\nexport function buildQueryParams(\n  opts: QueryOptions\n): Record<string, string | number | boolean> {\n  const params: Record<string, string | number | boolean> = {};\n\n  if (opts.timeScope)  params['timeScope']  = opts.timeScope;\n  if (opts.year)       params['year']       = opts.year;\n  if (opts.sortOrder)  params['sortOrder']  = opts.sortOrder;\n  if (opts.limit)      params['limit']      = opts.limit;\n  if (opts.cursor)     params['cursor']     = opts.cursor;\n  if (opts.fields)     params['fields']     = opts.fields;\n\n  for (const filter of opts.filters ?? []) {\n    const paramKey = filter.op === '==' ? filter.field : `${filter.field}[${filter.op}]`;\n    params[paramKey] = filter.value as string | number | boolean;\n  }\n\n  return params;\n}\n\n/**\n * Validates a filter array and throws a descriptive error if invalid.\n */\nexport function validateFilters(filters: Filter[]): void {\n  const VALID_OPS = new Set(['==', '!=', '>', '<', '>=', '<=', 'contains']);\n\n  if (filters.length > 3) {\n    throw new Error('HydrousDB supports a maximum of 3 filters per query.');\n  }\n\n  for (const f of filters) {\n    if (!VALID_OPS.has(f.op)) {\n      throw new Error(\n        `Invalid filter operator \"${f.op}\". Valid operators: ${[...VALID_OPS].join(', ')}`\n      );\n    }\n    if (!f.field || typeof f.field !== 'string') {\n      throw new Error('Each filter must have a non-empty \"field\" string.');\n    }\n  }\n}\n","import type { HttpClient } from '../utils/http.js';\nimport { buildQueryParams, validateFilters } from '../utils/query.js';\nimport type {\n  GetRecordOptions,\n  GetRecordResponse,\n  GetSnapshotResponse,\n  QueryOptions,\n  QueryResponse,\n  InsertRecordPayload,\n  InsertRecordResponse,\n  UpdateRecordPayload,\n  UpdateRecordResponse,\n  DeleteRecordResponse,\n  RecordExistsInfo,\n  BatchUpdatePayload,\n  BatchUpdateResponse,\n  BatchDeletePayload,\n  BatchDeleteResponse,\n  BatchInsertPayload,\n  BatchInsertResponse,\n  RecordData,\n  HydrousRecord,\n  RequestOptions,\n} from '../types/index.js';\n\nexport class RecordsClient {\n  constructor(private readonly http: HttpClient) { }\n\n  private get path() {\n    return `/api/${this.http.bucketKey}`;\n  }\n\n  // ── GET — single record ────────────────────────────────────────────────────\n\n  /**\n   * Fetch a single record by ID.\n   *\n   * @example\n   * const { data } = await db.records.get('rec_abc123');\n   * const { data, history } = await db.records.get('rec_abc123', { showHistory: true });\n   */\n  async get(recordId: string, options?: GetRecordOptions & RequestOptions): Promise<GetRecordResponse> {\n    const params: Record<string, string | number | boolean | undefined | null> = { recordId };\n    if (options?.showHistory) params['showHistory'] = 'true';\n    return this.http.get<GetRecordResponse>(this.path, params, options);\n  }\n\n  // ── GET — historical snapshot ──────────────────────────────────────────────\n\n  /**\n   * Fetch a specific historical version (generation) of a record.\n   *\n   * @example\n   * const { data } = await db.records.getSnapshot('rec_abc123', '1700000000000000');\n   */\n  async getSnapshot(recordId: string, generation: string, opts?: RequestOptions): Promise<GetSnapshotResponse> {\n    return this.http.get<GetSnapshotResponse>(this.path, { recordId, generation }, opts);\n  }\n\n  // ── GET — collection query ─────────────────────────────────────────────────\n\n  /**\n   * Query a collection with optional filters, sorting, and pagination.\n   *\n   * @example\n   * // Simple query\n   * const { data, meta } = await db.records.query({ limit: 50, sortOrder: 'desc' });\n   *\n   * // Filtered query\n   * const { data } = await db.records.query({\n   *   filters: [{ field: 'status', op: '==', value: 'active' }],\n   *   timeScope: '7d',\n   * });\n   *\n   * // Paginated\n   * let cursor: string | null = null;\n   * do {\n   *   const result = await db.records.query({ limit: 100, cursor: cursor ?? undefined });\n   *   cursor = result.meta.nextCursor;\n   * } while (cursor);\n   */\n  async query<T extends RecordData = RecordData>(\n    options?: QueryOptions & RequestOptions\n  ): Promise<QueryResponse<T>> {\n    if (options?.filters) validateFilters(options.filters);\n    const params = buildQueryParams(options ?? {});\n    return this.http.get<QueryResponse<T>>(this.path, params, options);\n  }\n\n  // ── POST — insert ──────────────────────────────────────────────────────────\n\n  /**\n   * Insert a new record.\n   *\n   * @example\n   * const { data, meta } = await db.records.insert({\n   *   values: { name: 'Alice', score: 99 },\n   *   queryableFields: ['name'],\n   *   userEmail: 'alice@example.com',\n   * });\n   */\n  async insert(payload: InsertRecordPayload, opts?: RequestOptions): Promise<InsertRecordResponse> {\n    return this.http.post<InsertRecordResponse>(this.path, payload, opts);\n  }\n\n  // ── PATCH — update ─────────────────────────────────────────────────────────\n\n  /**\n   * Update an existing record.\n   *\n   * @example\n   * await db.records.update({\n   *   recordId: 'rec_abc123',\n   *   values: { score: 100 },\n   *   track_record_history: true,\n   * });\n   */\n  async update(payload: UpdateRecordPayload, opts?: RequestOptions): Promise<UpdateRecordResponse> {\n    return this.http.patch<UpdateRecordResponse>(this.path, payload, opts);\n  }\n\n  // ── DELETE ─────────────────────────────────────────────────────────────────\n\n  /**\n   * Delete a record permanently.\n   *\n   * @example\n   * await db.records.delete('rec_abc123');\n   */\n  async delete(recordId: string, opts?: RequestOptions): Promise<DeleteRecordResponse> {\n    return this.http.delete<DeleteRecordResponse>(this.path, { recordId }, opts);\n  }\n\n  // ── HEAD — existence check ─────────────────────────────────────────────────\n\n  /**\n   * Check whether a record exists without fetching its full data.\n   * Returns `null` if the record is not found.\n   *\n   * @example\n   * const info = await db.records.exists('rec_abc123');\n   * if (info?.exists) console.log('found at', info.updatedAt);\n   */\n  async exists(recordId: string, opts?: RequestOptions): Promise<RecordExistsInfo | null> {\n    const res = await this.http.head(this.path, { recordId }, opts);\n\n    if (res.status === 404) return null;\n    if (!res.ok) return null;\n\n    return {\n      exists: true,\n      id: res.headers.get('X-Record-Id') ?? recordId,\n      createdAt: res.headers.get('X-Created-At') ?? '',\n      updatedAt: res.headers.get('X-Updated-At') ?? '',\n      sizeBytes: res.headers.get('X-Size-Bytes') ?? '',\n    };\n  }\n\n  // ── Batch — update ─────────────────────────────────────────────────────────\n\n  /**\n   * Update up to 500 records in a single request.\n   *\n   * @example\n   * await db.records.batchUpdate({\n   *   updates: [\n   *     { recordId: 'rec_1', values: { status: 'archived' } },\n   *     { recordId: 'rec_2', values: { status: 'archived' } },\n   *   ],\n   * });\n   */\n  async batchUpdate(payload: BatchUpdatePayload, opts?: RequestOptions): Promise<BatchUpdateResponse> {\n    return this.http.post<BatchUpdateResponse>(\n      `${this.path}/batch/update`,\n      payload,\n      opts\n    );\n  }\n\n  // ── Batch — delete ─────────────────────────────────────────────────────────\n\n  /**\n   * Delete up to 500 records in a single request.\n   *\n   * @example\n   * await db.records.batchDelete({ recordIds: ['rec_1', 'rec_2', 'rec_3'] });\n   */\n  async batchDelete(payload: BatchDeletePayload, opts?: RequestOptions): Promise<BatchDeleteResponse> {\n    return this.http.post<BatchDeleteResponse>(\n      `${this.path}/batch/delete`,\n      payload,\n      opts\n    );\n  }\n\n  // ── Batch — insert ─────────────────────────────────────────────────────────\n\n  /**\n   * Insert up to 500 records in a single request.\n   * Returns HTTP 207 (multi-status) — check `meta.failed` for partial failures.\n   *\n   * @example\n   * const result = await db.records.batchInsert({\n   *   records: [{ name: 'Alice' }, { name: 'Bob' }],\n   *   queryableFields: ['name'],\n   * });\n   */\n  async batchInsert(payload: BatchInsertPayload, opts?: RequestOptions): Promise<BatchInsertResponse> {\n    return this.http.post<BatchInsertResponse>(\n      `${this.path}/batch/insert`,\n      payload,\n      opts\n    );\n  }\n\n  // ── Helpers ────────────────────────────────────────────────────────────────\n\n  /**\n   * Fetch ALL records matching a query, automatically following cursors.\n   * Use with care on large collections — prefer `query()` with manual pagination.\n   *\n   * @example\n   * const allRecords = await db.records.queryAll({\n   *   filters: [{ field: 'type', op: '==', value: 'invoice' }],\n   * });\n   */\n  async queryAll<T extends RecordData = RecordData>(\n    options?: Omit<QueryOptions, 'cursor'> & RequestOptions\n  ): Promise<(T & HydrousRecord)[]> {\n    const all: (T & HydrousRecord)[] = [];\n    let cursor: string | null = null;\n\n    do {\n      const result: any = await this.query<T>(cursor ? { ...options, cursor } : { ...options });\n      all.push(...result.data);\n      cursor = result.meta.nextCursor ?? null;\n    } while (cursor);\n\n    return all;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "hydrousdb",
+  "version": "1.1.0",
+  "description": "Official TypeScript SDK for HydrousDB — a cloud-native record store with built-in auth, batch operations, analytics, and cursor-based pagination.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./records": {
+      "types": "./dist/records/index.d.ts",
+      "import": "./dist/records/index.mjs",
+      "require": "./dist/records/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.mjs",
+      "require": "./dist/auth/index.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics/index.d.ts",
+      "import": "./dist/analytics/index.mjs",
+      "require": "./dist/analytics/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "keywords": [
+    "hydrousdb",
+    "database",
+    "records",
+    "auth",
+    "cloud",
+    "sdk",
+    "typescript",
+    "nextjs",
+    "react",
+    "vue"
+  ],
+  "author": "HydrousDB",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}