@palbase/modules-docs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Palbase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,293 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CollectionRef: () => CollectionRef,
+  DocsClient: () => DocsClient,
+  DocumentRef: () => DocumentRef
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/docs-client.ts
+var import_core = require("@palbase/core");
+
+// src/document-ref.ts
+var SEGMENT_RE = /^[a-zA-Z0-9_\-]+$/;
+function validateSegment(segment, label) {
+  if (!SEGMENT_RE.test(segment)) {
+    throw new Error(`Invalid ${label}: "${segment}". Must match ${SEGMENT_RE.source}`);
+  }
+}
+var DocumentRef = class {
+  path;
+  httpClient;
+  constructor(httpClient, path) {
+    this.httpClient = httpClient;
+    this.path = path;
+  }
+  async set(data) {
+    return this.httpClient.request("PUT", `/v1/docs/${this.path}`, {
+      body: data
+    });
+  }
+  async get() {
+    const response = await this.httpClient.request(
+      "GET",
+      `/v1/docs/${this.path}`
+    );
+    if (response.error) {
+      return {
+        data: null,
+        error: response.error,
+        status: response.status
+      };
+    }
+    const raw = response.data;
+    const snapshot = {
+      id: raw?.id ?? this.getDocId(),
+      exists: raw?.exists ?? false,
+      data: () => raw?.data,
+      ref: { path: this.path }
+    };
+    return { data: snapshot, error: null, status: response.status };
+  }
+  async update(data) {
+    return this.httpClient.request("PATCH", `/v1/docs/${this.path}`, {
+      body: data
+    });
+  }
+  async delete() {
+    return this.httpClient.request("DELETE", `/v1/docs/${this.path}`);
+  }
+  collection(name) {
+    validateSegment(name, "subcollection name");
+    return new CollectionRef(this.httpClient, `${this.path}/${name}`);
+  }
+  getDocId() {
+    const segments = this.path.split("/");
+    return segments[segments.length - 1] ?? "";
+  }
+};
+
+// src/collection-ref.ts
+var SEGMENT_RE2 = /^[a-zA-Z0-9_\-]+$/;
+function validateSegment2(segment, label) {
+  if (!SEGMENT_RE2.test(segment)) {
+    throw new Error(`Invalid ${label}: "${segment}". Must match ${SEGMENT_RE2.source}`);
+  }
+}
+var CollectionRef = class _CollectionRef {
+  path;
+  httpClient;
+  whereClauses = [];
+  orderByClauses = [];
+  limitValue;
+  constructor(httpClient, path) {
+    this.httpClient = httpClient;
+    this.path = path;
+  }
+  doc(id) {
+    validateSegment2(id, "document ID");
+    return new DocumentRef(this.httpClient, `${this.path}/${id}`);
+  }
+  async add(data) {
+    const response = await this.httpClient.request(
+      "POST",
+      `/v1/docs/${this.path}`,
+      { body: data }
+    );
+    if (response.error || !response.data) {
+      return {
+        data: null,
+        error: response.error,
+        status: response.status
+      };
+    }
+    const ref = new DocumentRef(this.httpClient, `${this.path}/${response.data.id}`);
+    return { data: ref, error: null, status: response.status };
+  }
+  where(field, op, value) {
+    const clone = this.clone();
+    clone.whereClauses.push({ field, op, value });
+    return clone;
+  }
+  orderBy(field, direction) {
+    const clone = this.clone();
+    clone.orderByClauses.push({ field, direction: direction ?? "asc" });
+    return clone;
+  }
+  limit(n) {
+    const clone = this.clone();
+    clone.limitValue = n;
+    return clone;
+  }
+  async get() {
+    const hasQuery = this.whereClauses.length > 0 || this.orderByClauses.length > 0 || this.limitValue !== void 0;
+    if (hasQuery) {
+      return this.executeQuery();
+    }
+    const response = await this.httpClient.request(
+      "GET",
+      `/v1/docs/${this.path}`
+    );
+    if (response.error) {
+      return { data: null, error: response.error, status: response.status };
+    }
+    const docs = (response.data?.documents ?? []).map((doc) => this.toSnapshot(doc));
+    return {
+      data: this.toQuerySnapshot(docs),
+      error: null,
+      status: response.status
+    };
+  }
+  onSnapshot(callback) {
+    const body = this.buildQueryBody();
+    let active = true;
+    let controller;
+    const poll = async () => {
+      if (!active) return;
+      controller = new AbortController();
+      const response = await this.httpClient.request(
+        "POST",
+        `/v1/docs/${this.path}/listen`,
+        { body, signal: controller.signal }
+      );
+      if (!active) return;
+      if (response.data) {
+        const docs = (response.data.documents ?? []).map((doc) => this.toSnapshot(doc));
+        callback(this.toQuerySnapshot(docs));
+      }
+    };
+    void poll();
+    return () => {
+      active = false;
+      controller?.abort();
+    };
+  }
+  async executeQuery() {
+    const body = this.buildQueryBody();
+    const response = await this.httpClient.request(
+      "POST",
+      `/v1/docs/${this.path}/query`,
+      { body }
+    );
+    if (response.error) {
+      return { data: null, error: response.error, status: response.status };
+    }
+    const docs = (response.data?.documents ?? []).map((doc) => this.toSnapshot(doc));
+    return {
+      data: this.toQuerySnapshot(docs),
+      error: null,
+      status: response.status
+    };
+  }
+  buildQueryBody() {
+    const body = {};
+    if (this.whereClauses.length > 0) {
+      body["where"] = this.whereClauses.map((w) => ({
+        field: w.field,
+        op: w.op,
+        value: w.value
+      }));
+    }
+    if (this.orderByClauses.length > 0) {
+      body["orderBy"] = this.orderByClauses.map((o) => ({
+        field: o.field,
+        direction: o.direction
+      }));
+    }
+    if (this.limitValue !== void 0) {
+      body["limit"] = this.limitValue;
+    }
+    return body;
+  }
+  toSnapshot(doc) {
+    return {
+      id: doc.id,
+      exists: true,
+      data: () => doc.data,
+      ref: { path: `${this.path}/${doc.id}` }
+    };
+  }
+  toQuerySnapshot(docs) {
+    return {
+      docs,
+      empty: docs.length === 0,
+      size: docs.length,
+      docChanges: () => docs.map((doc) => ({ type: "added", doc }))
+    };
+  }
+  clone() {
+    const cloned = new _CollectionRef(this.httpClient, this.path);
+    cloned.whereClauses.push(...this.whereClauses);
+    cloned.orderByClauses.push(...this.orderByClauses);
+    cloned.limitValue = this.limitValue;
+    return cloned;
+  }
+};
+
+// src/docs-client.ts
+var MAX_BATCH_SIZE = 500;
+var SEGMENT_RE3 = /^[a-zA-Z0-9_\-]+$/;
+function validateSegment3(segment, label) {
+  if (!SEGMENT_RE3.test(segment)) {
+    throw new Error(`Invalid ${label}: "${segment}". Must match ${SEGMENT_RE3.source}`);
+  }
+}
+var DocsClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  collection(name) {
+    validateSegment3(name, "collection name");
+    return new CollectionRef(this.httpClient, name);
+  }
+  async batch(operations) {
+    if (operations.length > MAX_BATCH_SIZE) {
+      return {
+        data: null,
+        error: new import_core.PalbaseError(
+          "batch_too_large",
+          `Batch size ${operations.length} exceeds maximum of ${MAX_BATCH_SIZE}`,
+          400
+        ),
+        status: 400
+      };
+    }
+    if (operations.length === 0) {
+      return { data: null, error: null, status: 200 };
+    }
+    const body = operations.map((op) => ({
+      op: op.op,
+      path: op.ref.path,
+      data: op.data
+    }));
+    return this.httpClient.request("POST", "/v1/docs/batch", { body });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CollectionRef,
+  DocsClient,
+  DocumentRef
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/docs-client.ts","../src/document-ref.ts","../src/collection-ref.ts"],"sourcesContent":["export { DocsClient } from './docs-client.js';\nexport { CollectionRef } from './collection-ref.js';\nexport { DocumentRef } from './document-ref.js';\nexport type {\n  WhereOperator,\n  OrderDirection,\n  WhereClause,\n  OrderByClause,\n  DocumentData,\n  DocumentSnapshot,\n  DocChange,\n  QuerySnapshot,\n  SnapshotCallback,\n  BatchOperationType,\n  BatchOperation,\n} from './types.js';\n","import type { HttpClient, PalbaseResponse } from '@palbase/core';\nimport { PalbaseError } from '@palbase/core';\nimport { CollectionRef } from './collection-ref.js';\nimport type { BatchOperation, DocumentData } from './types.js';\n\nconst MAX_BATCH_SIZE = 500;\nconst SEGMENT_RE = /^[a-zA-Z0-9_\\-]+$/;\n\nfunction validateSegment(segment: string, label: string): void {\n  if (!SEGMENT_RE.test(segment)) {\n    throw new Error(`Invalid ${label}: \"${segment}\". Must match ${SEGMENT_RE.source}`);\n  }\n}\n\nexport class DocsClient {\n  private readonly httpClient: HttpClient;\n\n  constructor(httpClient: HttpClient) {\n    this.httpClient = httpClient;\n  }\n\n  collection<T = DocumentData>(name: string): CollectionRef<T> {\n    validateSegment(name, 'collection name');\n    return new CollectionRef<T>(this.httpClient, name);\n  }\n\n  async batch(operations: BatchOperation[]): Promise<PalbaseResponse<void>> {\n    if (operations.length > MAX_BATCH_SIZE) {\n      return {\n        data: null,\n        error: new PalbaseError(\n          'batch_too_large',\n          `Batch size ${operations.length} exceeds maximum of ${MAX_BATCH_SIZE}`,\n          400,\n        ),\n        status: 400,\n      };\n    }\n\n    if (operations.length === 0) {\n      return { data: null, error: null, status: 200 };\n    }\n\n    const body = operations.map((op) => ({\n      op: op.op,\n      path: op.ref.path,\n      data: op.data,\n    }));\n\n    return this.httpClient.request<void>('POST', '/v1/docs/batch', { body });\n  }\n}\n","import type { HttpClient, PalbaseResponse } from '@palbase/core';\nimport { CollectionRef } from './collection-ref.js';\nimport type { DocumentData, DocumentSnapshot } from './types.js';\n\nconst SEGMENT_RE = /^[a-zA-Z0-9_\\-]+$/;\n\nfunction validateSegment(segment: string, label: string): void {\n  if (!SEGMENT_RE.test(segment)) {\n    throw new Error(`Invalid ${label}: \"${segment}\". Must match ${SEGMENT_RE.source}`);\n  }\n}\n\nexport class DocumentRef<T = DocumentData> {\n  readonly path: string;\n  private readonly httpClient: HttpClient;\n\n  constructor(httpClient: HttpClient, path: string) {\n    this.httpClient = httpClient;\n    this.path = path;\n  }\n\n  async set(data: T): Promise<PalbaseResponse<void>> {\n    return this.httpClient.request<void>('PUT', `/v1/docs/${this.path}`, {\n      body: data,\n    });\n  }\n\n  async get(): Promise<PalbaseResponse<DocumentSnapshot<T>>> {\n    const response = await this.httpClient.request<{ id: string; data: T; exists: boolean }>(\n      'GET',\n      `/v1/docs/${this.path}`,\n    );\n\n    if (response.error) {\n      return {\n        data: null,\n        error: response.error,\n        status: response.status,\n      };\n    }\n\n    const raw = response.data;\n    const snapshot: DocumentSnapshot<T> = {\n      id: raw?.id ?? this.getDocId(),\n      exists: raw?.exists ?? false,\n      data: () => raw?.data,\n      ref: { path: this.path },\n    };\n\n    return { data: snapshot, error: null, status: response.status };\n  }\n\n  async update(data: Partial<T>): Promise<PalbaseResponse<void>> {\n    return this.httpClient.request<void>('PATCH', `/v1/docs/${this.path}`, {\n      body: data,\n    });\n  }\n\n  async delete(): Promise<PalbaseResponse<void>> {\n    return this.httpClient.request<void>('DELETE', `/v1/docs/${this.path}`);\n  }\n\n  collection(name: string): CollectionRef {\n    validateSegment(name, 'subcollection name');\n    return new CollectionRef(this.httpClient, `${this.path}/${name}`);\n  }\n\n  private getDocId(): string {\n    const segments = this.path.split('/');\n    return segments[segments.length - 1] ?? '';\n  }\n}\n","import type { HttpClient, PalbaseResponse } from '@palbase/core';\nimport { DocumentRef } from './document-ref.js';\nimport type {\n  DocumentData,\n  DocumentSnapshot,\n  OrderByClause,\n  OrderDirection,\n  QuerySnapshot,\n  SnapshotCallback,\n  WhereClause,\n  WhereOperator,\n} from './types.js';\n\nconst SEGMENT_RE = /^[a-zA-Z0-9_\\-]+$/;\n\nfunction validateSegment(segment: string, label: string): void {\n  if (!SEGMENT_RE.test(segment)) {\n    throw new Error(`Invalid ${label}: \"${segment}\". Must match ${SEGMENT_RE.source}`);\n  }\n}\n\nexport class CollectionRef<T = DocumentData> {\n  readonly path: string;\n  private readonly httpClient: HttpClient;\n  private readonly whereClauses: WhereClause[] = [];\n  private readonly orderByClauses: OrderByClause[] = [];\n  private limitValue: number | undefined;\n\n  constructor(httpClient: HttpClient, path: string) {\n    this.httpClient = httpClient;\n    this.path = path;\n  }\n\n  doc(id: string): DocumentRef<T> {\n    validateSegment(id, 'document ID');\n    return new DocumentRef<T>(this.httpClient, `${this.path}/${id}`);\n  }\n\n  async add(data: T): Promise<PalbaseResponse<DocumentRef<T>>> {\n    const response = await this.httpClient.request<{ id: string }>(\n      'POST',\n      `/v1/docs/${this.path}`,\n      { body: data },\n    );\n\n    if (response.error || !response.data) {\n      return {\n        data: null,\n        error: response.error,\n        status: response.status,\n      };\n    }\n\n    const ref = new DocumentRef<T>(this.httpClient, `${this.path}/${response.data.id}`);\n    return { data: ref, error: null, status: response.status };\n  }\n\n  where(field: string, op: WhereOperator, value: unknown): CollectionRef<T> {\n    const clone = this.clone();\n    clone.whereClauses.push({ field, op, value });\n    return clone;\n  }\n\n  orderBy(field: string, direction?: OrderDirection): CollectionRef<T> {\n    const clone = this.clone();\n    clone.orderByClauses.push({ field, direction: direction ?? 'asc' });\n    return clone;\n  }\n\n  limit(n: number): CollectionRef<T> {\n    const clone = this.clone();\n    clone.limitValue = n;\n    return clone;\n  }\n\n  async get(): Promise<PalbaseResponse<QuerySnapshot<T>>> {\n    const hasQuery = this.whereClauses.length > 0 || this.orderByClauses.length > 0 || this.limitValue !== undefined;\n\n    if (hasQuery) {\n      return this.executeQuery();\n    }\n\n    const response = await this.httpClient.request<{ documents: { id: string; data: T }[] }>(\n      'GET',\n      `/v1/docs/${this.path}`,\n    );\n\n    if (response.error) {\n      return { data: null, error: response.error, status: response.status };\n    }\n\n    const docs = (response.data?.documents ?? []).map((doc) => this.toSnapshot(doc));\n    return {\n      data: this.toQuerySnapshot(docs),\n      error: null,\n      status: response.status,\n    };\n  }\n\n  onSnapshot(callback: SnapshotCallback<T>): () => void {\n    const body = this.buildQueryBody();\n\n    let active = true;\n    let controller: AbortController | undefined;\n\n    const poll = async () => {\n      if (!active) return;\n      controller = new AbortController();\n\n      const response = await this.httpClient.request<{ documents: { id: string; data: T }[] }>(\n        'POST',\n        `/v1/docs/${this.path}/listen`,\n        { body, signal: controller.signal },\n      );\n\n      if (!active) return;\n\n      if (response.data) {\n        const docs = (response.data.documents ?? []).map((doc) => this.toSnapshot(doc));\n        callback(this.toQuerySnapshot(docs));\n      }\n    };\n\n    // Start initial poll\n    void poll();\n\n    return () => {\n      active = false;\n      controller?.abort();\n    };\n  }\n\n  private async executeQuery(): Promise<PalbaseResponse<QuerySnapshot<T>>> {\n    const body = this.buildQueryBody();\n\n    const response = await this.httpClient.request<{ documents: { id: string; data: T }[] }>(\n      'POST',\n      `/v1/docs/${this.path}/query`,\n      { body },\n    );\n\n    if (response.error) {\n      return { data: null, error: response.error, status: response.status };\n    }\n\n    const docs = (response.data?.documents ?? []).map((doc) => this.toSnapshot(doc));\n    return {\n      data: this.toQuerySnapshot(docs),\n      error: null,\n      status: response.status,\n    };\n  }\n\n  private buildQueryBody(): Record<string, unknown> {\n    const body: Record<string, unknown> = {};\n\n    if (this.whereClauses.length > 0) {\n      body['where'] = this.whereClauses.map((w) => ({\n        field: w.field,\n        op: w.op,\n        value: w.value,\n      }));\n    }\n\n    if (this.orderByClauses.length > 0) {\n      body['orderBy'] = this.orderByClauses.map((o) => ({\n        field: o.field,\n        direction: o.direction,\n      }));\n    }\n\n    if (this.limitValue !== undefined) {\n      body['limit'] = this.limitValue;\n    }\n\n    return body;\n  }\n\n  private toSnapshot(doc: { id: string; data: T }): DocumentSnapshot<T> {\n    return {\n      id: doc.id,\n      exists: true,\n      data: () => doc.data,\n      ref: { path: `${this.path}/${doc.id}` },\n    };\n  }\n\n  private toQuerySnapshot(docs: DocumentSnapshot<T>[]): QuerySnapshot<T> {\n    return {\n      docs,\n      empty: docs.length === 0,\n      size: docs.length,\n      docChanges: () => docs.map((doc) => ({ type: 'added' as const, doc })),\n    };\n  }\n\n  private clone(): CollectionRef<T> {\n    const cloned = new CollectionRef<T>(this.httpClient, this.path);\n    cloned.whereClauses.push(...this.whereClauses);\n    cloned.orderByClauses.push(...this.orderByClauses);\n    cloned.limitValue = this.limitValue;\n    return cloned;\n  }\n}\n"],"mappings":"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","names":["SEGMENT_RE","validateSegment","SEGMENT_RE","validateSegment"]}

package/dist/index.d.cts

@@ -0,0 +1,85 @@
+import { HttpClient, PalbaseResponse } from '@palbase/core';
+
+type WhereOperator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'array-contains';
+type OrderDirection = 'asc' | 'desc';
+interface WhereClause {
+    field: string;
+    op: WhereOperator;
+    value: unknown;
+}
+interface OrderByClause {
+    field: string;
+    direction: OrderDirection;
+}
+interface DocumentData {
+    [key: string]: unknown;
+}
+interface DocumentSnapshot<T = DocumentData> {
+    id: string;
+    exists: boolean;
+    data(): T | undefined;
+    ref: {
+        path: string;
+    };
+}
+interface DocChange<T = DocumentData> {
+    type: 'added' | 'modified' | 'removed';
+    doc: DocumentSnapshot<T>;
+}
+interface QuerySnapshot<T = DocumentData> {
+    docs: DocumentSnapshot<T>[];
+    empty: boolean;
+    size: number;
+    docChanges(): DocChange<T>[];
+}
+type SnapshotCallback<T = DocumentData> = (snapshot: QuerySnapshot<T>) => void;
+type BatchOperationType = 'set' | 'update' | 'delete';
+interface BatchOperation {
+    op: BatchOperationType;
+    ref: {
+        path: string;
+    };
+    data?: DocumentData;
+}
+
+declare class DocumentRef<T = DocumentData> {
+    readonly path: string;
+    private readonly httpClient;
+    constructor(httpClient: HttpClient, path: string);
+    set(data: T): Promise<PalbaseResponse<void>>;
+    get(): Promise<PalbaseResponse<DocumentSnapshot<T>>>;
+    update(data: Partial<T>): Promise<PalbaseResponse<void>>;
+    delete(): Promise<PalbaseResponse<void>>;
+    collection(name: string): CollectionRef;
+    private getDocId;
+}
+
+declare class CollectionRef<T = DocumentData> {
+    readonly path: string;
+    private readonly httpClient;
+    private readonly whereClauses;
+    private readonly orderByClauses;
+    private limitValue;
+    constructor(httpClient: HttpClient, path: string);
+    doc(id: string): DocumentRef<T>;
+    add(data: T): Promise<PalbaseResponse<DocumentRef<T>>>;
+    where(field: string, op: WhereOperator, value: unknown): CollectionRef<T>;
+    orderBy(field: string, direction?: OrderDirection): CollectionRef<T>;
+    limit(n: number): CollectionRef<T>;
+    get(): Promise<PalbaseResponse<QuerySnapshot<T>>>;
+    onSnapshot(callback: SnapshotCallback<T>): () => void;
+    private executeQuery;
+    private buildQueryBody;
+    private toSnapshot;
+    private toQuerySnapshot;
+    private clone;
+}
+
+declare class DocsClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    collection<T = DocumentData>(name: string): CollectionRef<T>;
+    batch(operations: BatchOperation[]): Promise<PalbaseResponse<void>>;
+}
+
+export { type BatchOperation, type BatchOperationType, CollectionRef, type DocChange, DocsClient, type DocumentData, DocumentRef, type DocumentSnapshot, type OrderByClause, type OrderDirection, type QuerySnapshot, type SnapshotCallback, type WhereClause, type WhereOperator };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { HttpClient, PalbaseResponse } from '@palbase/core';
+
+type WhereOperator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'array-contains';
+type OrderDirection = 'asc' | 'desc';
+interface WhereClause {
+    field: string;
+    op: WhereOperator;
+    value: unknown;
+}
+interface OrderByClause {
+    field: string;
+    direction: OrderDirection;
+}
+interface DocumentData {
+    [key: string]: unknown;
+}
+interface DocumentSnapshot<T = DocumentData> {
+    id: string;
+    exists: boolean;
+    data(): T | undefined;
+    ref: {
+        path: string;
+    };
+}
+interface DocChange<T = DocumentData> {
+    type: 'added' | 'modified' | 'removed';
+    doc: DocumentSnapshot<T>;
+}
+interface QuerySnapshot<T = DocumentData> {
+    docs: DocumentSnapshot<T>[];
+    empty: boolean;
+    size: number;
+    docChanges(): DocChange<T>[];
+}
+type SnapshotCallback<T = DocumentData> = (snapshot: QuerySnapshot<T>) => void;
+type BatchOperationType = 'set' | 'update' | 'delete';
+interface BatchOperation {
+    op: BatchOperationType;
+    ref: {
+        path: string;
+    };
+    data?: DocumentData;
+}
+
+declare class DocumentRef<T = DocumentData> {
+    readonly path: string;
+    private readonly httpClient;
+    constructor(httpClient: HttpClient, path: string);
+    set(data: T): Promise<PalbaseResponse<void>>;
+    get(): Promise<PalbaseResponse<DocumentSnapshot<T>>>;
+    update(data: Partial<T>): Promise<PalbaseResponse<void>>;
+    delete(): Promise<PalbaseResponse<void>>;
+    collection(name: string): CollectionRef;
+    private getDocId;
+}
+
+declare class CollectionRef<T = DocumentData> {
+    readonly path: string;
+    private readonly httpClient;
+    private readonly whereClauses;
+    private readonly orderByClauses;
+    private limitValue;
+    constructor(httpClient: HttpClient, path: string);
+    doc(id: string): DocumentRef<T>;
+    add(data: T): Promise<PalbaseResponse<DocumentRef<T>>>;
+    where(field: string, op: WhereOperator, value: unknown): CollectionRef<T>;
+    orderBy(field: string, direction?: OrderDirection): CollectionRef<T>;
+    limit(n: number): CollectionRef<T>;
+    get(): Promise<PalbaseResponse<QuerySnapshot<T>>>;
+    onSnapshot(callback: SnapshotCallback<T>): () => void;
+    private executeQuery;
+    private buildQueryBody;
+    private toSnapshot;
+    private toQuerySnapshot;
+    private clone;
+}
+
+declare class DocsClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    collection<T = DocumentData>(name: string): CollectionRef<T>;
+    batch(operations: BatchOperation[]): Promise<PalbaseResponse<void>>;
+}
+
+export { type BatchOperation, type BatchOperationType, CollectionRef, type DocChange, DocsClient, type DocumentData, DocumentRef, type DocumentSnapshot, type OrderByClause, type OrderDirection, type QuerySnapshot, type SnapshotCallback, type WhereClause, type WhereOperator };

package/dist/index.js

@@ -0,0 +1,264 @@
+// src/docs-client.ts
+import { PalbaseError } from "@palbase/core";
+
+// src/document-ref.ts
+var SEGMENT_RE = /^[a-zA-Z0-9_\-]+$/;
+function validateSegment(segment, label) {
+  if (!SEGMENT_RE.test(segment)) {
+    throw new Error(`Invalid ${label}: "${segment}". Must match ${SEGMENT_RE.source}`);
+  }
+}
+var DocumentRef = class {
+  path;
+  httpClient;
+  constructor(httpClient, path) {
+    this.httpClient = httpClient;
+    this.path = path;
+  }
+  async set(data) {
+    return this.httpClient.request("PUT", `/v1/docs/${this.path}`, {
+      body: data
+    });
+  }
+  async get() {
+    const response = await this.httpClient.request(
+      "GET",
+      `/v1/docs/${this.path}`
+    );
+    if (response.error) {
+      return {
+        data: null,
+        error: response.error,
+        status: response.status
+      };
+    }
+    const raw = response.data;
+    const snapshot = {
+      id: raw?.id ?? this.getDocId(),
+      exists: raw?.exists ?? false,
+      data: () => raw?.data,
+      ref: { path: this.path }
+    };
+    return { data: snapshot, error: null, status: response.status };
+  }
+  async update(data) {
+    return this.httpClient.request("PATCH", `/v1/docs/${this.path}`, {
+      body: data
+    });
+  }
+  async delete() {
+    return this.httpClient.request("DELETE", `/v1/docs/${this.path}`);
+  }
+  collection(name) {
+    validateSegment(name, "subcollection name");
+    return new CollectionRef(this.httpClient, `${this.path}/${name}`);
+  }
+  getDocId() {
+    const segments = this.path.split("/");
+    return segments[segments.length - 1] ?? "";
+  }
+};
+
+// src/collection-ref.ts
+var SEGMENT_RE2 = /^[a-zA-Z0-9_\-]+$/;
+function validateSegment2(segment, label) {
+  if (!SEGMENT_RE2.test(segment)) {
+    throw new Error(`Invalid ${label}: "${segment}". Must match ${SEGMENT_RE2.source}`);
+  }
+}
+var CollectionRef = class _CollectionRef {
+  path;
+  httpClient;
+  whereClauses = [];
+  orderByClauses = [];
+  limitValue;
+  constructor(httpClient, path) {
+    this.httpClient = httpClient;
+    this.path = path;
+  }
+  doc(id) {
+    validateSegment2(id, "document ID");
+    return new DocumentRef(this.httpClient, `${this.path}/${id}`);
+  }
+  async add(data) {
+    const response = await this.httpClient.request(
+      "POST",
+      `/v1/docs/${this.path}`,
+      { body: data }
+    );
+    if (response.error || !response.data) {
+      return {
+        data: null,
+        error: response.error,
+        status: response.status
+      };
+    }
+    const ref = new DocumentRef(this.httpClient, `${this.path}/${response.data.id}`);
+    return { data: ref, error: null, status: response.status };
+  }
+  where(field, op, value) {
+    const clone = this.clone();
+    clone.whereClauses.push({ field, op, value });
+    return clone;
+  }
+  orderBy(field, direction) {
+    const clone = this.clone();
+    clone.orderByClauses.push({ field, direction: direction ?? "asc" });
+    return clone;
+  }
+  limit(n) {
+    const clone = this.clone();
+    clone.limitValue = n;
+    return clone;
+  }
+  async get() {
+    const hasQuery = this.whereClauses.length > 0 || this.orderByClauses.length > 0 || this.limitValue !== void 0;
+    if (hasQuery) {
+      return this.executeQuery();
+    }
+    const response = await this.httpClient.request(
+      "GET",
+      `/v1/docs/${this.path}`
+    );
+    if (response.error) {
+      return { data: null, error: response.error, status: response.status };
+    }
+    const docs = (response.data?.documents ?? []).map((doc) => this.toSnapshot(doc));
+    return {
+      data: this.toQuerySnapshot(docs),
+      error: null,
+      status: response.status
+    };
+  }
+  onSnapshot(callback) {
+    const body = this.buildQueryBody();
+    let active = true;
+    let controller;
+    const poll = async () => {
+      if (!active) return;
+      controller = new AbortController();
+      const response = await this.httpClient.request(
+        "POST",
+        `/v1/docs/${this.path}/listen`,
+        { body, signal: controller.signal }
+      );
+      if (!active) return;
+      if (response.data) {
+        const docs = (response.data.documents ?? []).map((doc) => this.toSnapshot(doc));
+        callback(this.toQuerySnapshot(docs));
+      }
+    };
+    void poll();
+    return () => {
+      active = false;
+      controller?.abort();
+    };
+  }
+  async executeQuery() {
+    const body = this.buildQueryBody();
+    const response = await this.httpClient.request(
+      "POST",
+      `/v1/docs/${this.path}/query`,
+      { body }
+    );
+    if (response.error) {
+      return { data: null, error: response.error, status: response.status };
+    }
+    const docs = (response.data?.documents ?? []).map((doc) => this.toSnapshot(doc));
+    return {
+      data: this.toQuerySnapshot(docs),
+      error: null,
+      status: response.status
+    };
+  }
+  buildQueryBody() {
+    const body = {};
+    if (this.whereClauses.length > 0) {
+      body["where"] = this.whereClauses.map((w) => ({
+        field: w.field,
+        op: w.op,
+        value: w.value
+      }));
+    }
+    if (this.orderByClauses.length > 0) {
+      body["orderBy"] = this.orderByClauses.map((o) => ({
+        field: o.field,
+        direction: o.direction
+      }));
+    }
+    if (this.limitValue !== void 0) {
+      body["limit"] = this.limitValue;
+    }
+    return body;
+  }
+  toSnapshot(doc) {
+    return {
+      id: doc.id,
+      exists: true,
+      data: () => doc.data,
+      ref: { path: `${this.path}/${doc.id}` }
+    };
+  }
+  toQuerySnapshot(docs) {
+    return {
+      docs,
+      empty: docs.length === 0,
+      size: docs.length,
+      docChanges: () => docs.map((doc) => ({ type: "added", doc }))
+    };
+  }
+  clone() {
+    const cloned = new _CollectionRef(this.httpClient, this.path);
+    cloned.whereClauses.push(...this.whereClauses);
+    cloned.orderByClauses.push(...this.orderByClauses);
+    cloned.limitValue = this.limitValue;
+    return cloned;
+  }
+};
+
+// src/docs-client.ts
+var MAX_BATCH_SIZE = 500;
+var SEGMENT_RE3 = /^[a-zA-Z0-9_\-]+$/;
+function validateSegment3(segment, label) {
+  if (!SEGMENT_RE3.test(segment)) {
+    throw new Error(`Invalid ${label}: "${segment}". Must match ${SEGMENT_RE3.source}`);
+  }
+}
+var DocsClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  collection(name) {
+    validateSegment3(name, "collection name");
+    return new CollectionRef(this.httpClient, name);
+  }
+  async batch(operations) {
+    if (operations.length > MAX_BATCH_SIZE) {
+      return {
+        data: null,
+        error: new PalbaseError(
+          "batch_too_large",
+          `Batch size ${operations.length} exceeds maximum of ${MAX_BATCH_SIZE}`,
+          400
+        ),
+        status: 400
+      };
+    }
+    if (operations.length === 0) {
+      return { data: null, error: null, status: 200 };
+    }
+    const body = operations.map((op) => ({
+      op: op.op,
+      path: op.ref.path,
+      data: op.data
+    }));
+    return this.httpClient.request("POST", "/v1/docs/batch", { body });
+  }
+};
+export {
+  CollectionRef,
+  DocsClient,
+  DocumentRef
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/docs-client.ts","../src/document-ref.ts","../src/collection-ref.ts"],"sourcesContent":["import type { HttpClient, PalbaseResponse } from '@palbase/core';\nimport { PalbaseError } from '@palbase/core';\nimport { CollectionRef } from './collection-ref.js';\nimport type { BatchOperation, DocumentData } from './types.js';\n\nconst MAX_BATCH_SIZE = 500;\nconst SEGMENT_RE = /^[a-zA-Z0-9_\\-]+$/;\n\nfunction validateSegment(segment: string, label: string): void {\n  if (!SEGMENT_RE.test(segment)) {\n    throw new Error(`Invalid ${label}: \"${segment}\". Must match ${SEGMENT_RE.source}`);\n  }\n}\n\nexport class DocsClient {\n  private readonly httpClient: HttpClient;\n\n  constructor(httpClient: HttpClient) {\n    this.httpClient = httpClient;\n  }\n\n  collection<T = DocumentData>(name: string): CollectionRef<T> {\n    validateSegment(name, 'collection name');\n    return new CollectionRef<T>(this.httpClient, name);\n  }\n\n  async batch(operations: BatchOperation[]): Promise<PalbaseResponse<void>> {\n    if (operations.length > MAX_BATCH_SIZE) {\n      return {\n        data: null,\n        error: new PalbaseError(\n          'batch_too_large',\n          `Batch size ${operations.length} exceeds maximum of ${MAX_BATCH_SIZE}`,\n          400,\n        ),\n        status: 400,\n      };\n    }\n\n    if (operations.length === 0) {\n      return { data: null, error: null, status: 200 };\n    }\n\n    const body = operations.map((op) => ({\n      op: op.op,\n      path: op.ref.path,\n      data: op.data,\n    }));\n\n    return this.httpClient.request<void>('POST', '/v1/docs/batch', { body });\n  }\n}\n","import type { HttpClient, PalbaseResponse } from '@palbase/core';\nimport { CollectionRef } from './collection-ref.js';\nimport type { DocumentData, DocumentSnapshot } from './types.js';\n\nconst SEGMENT_RE = /^[a-zA-Z0-9_\\-]+$/;\n\nfunction validateSegment(segment: string, label: string): void {\n  if (!SEGMENT_RE.test(segment)) {\n    throw new Error(`Invalid ${label}: \"${segment}\". Must match ${SEGMENT_RE.source}`);\n  }\n}\n\nexport class DocumentRef<T = DocumentData> {\n  readonly path: string;\n  private readonly httpClient: HttpClient;\n\n  constructor(httpClient: HttpClient, path: string) {\n    this.httpClient = httpClient;\n    this.path = path;\n  }\n\n  async set(data: T): Promise<PalbaseResponse<void>> {\n    return this.httpClient.request<void>('PUT', `/v1/docs/${this.path}`, {\n      body: data,\n    });\n  }\n\n  async get(): Promise<PalbaseResponse<DocumentSnapshot<T>>> {\n    const response = await this.httpClient.request<{ id: string; data: T; exists: boolean }>(\n      'GET',\n      `/v1/docs/${this.path}`,\n    );\n\n    if (response.error) {\n      return {\n        data: null,\n        error: response.error,\n        status: response.status,\n      };\n    }\n\n    const raw = response.data;\n    const snapshot: DocumentSnapshot<T> = {\n      id: raw?.id ?? this.getDocId(),\n      exists: raw?.exists ?? false,\n      data: () => raw?.data,\n      ref: { path: this.path },\n    };\n\n    return { data: snapshot, error: null, status: response.status };\n  }\n\n  async update(data: Partial<T>): Promise<PalbaseResponse<void>> {\n    return this.httpClient.request<void>('PATCH', `/v1/docs/${this.path}`, {\n      body: data,\n    });\n  }\n\n  async delete(): Promise<PalbaseResponse<void>> {\n    return this.httpClient.request<void>('DELETE', `/v1/docs/${this.path}`);\n  }\n\n  collection(name: string): CollectionRef {\n    validateSegment(name, 'subcollection name');\n    return new CollectionRef(this.httpClient, `${this.path}/${name}`);\n  }\n\n  private getDocId(): string {\n    const segments = this.path.split('/');\n    return segments[segments.length - 1] ?? '';\n  }\n}\n","import type { HttpClient, PalbaseResponse } from '@palbase/core';\nimport { DocumentRef } from './document-ref.js';\nimport type {\n  DocumentData,\n  DocumentSnapshot,\n  OrderByClause,\n  OrderDirection,\n  QuerySnapshot,\n  SnapshotCallback,\n  WhereClause,\n  WhereOperator,\n} from './types.js';\n\nconst SEGMENT_RE = /^[a-zA-Z0-9_\\-]+$/;\n\nfunction validateSegment(segment: string, label: string): void {\n  if (!SEGMENT_RE.test(segment)) {\n    throw new Error(`Invalid ${label}: \"${segment}\". Must match ${SEGMENT_RE.source}`);\n  }\n}\n\nexport class CollectionRef<T = DocumentData> {\n  readonly path: string;\n  private readonly httpClient: HttpClient;\n  private readonly whereClauses: WhereClause[] = [];\n  private readonly orderByClauses: OrderByClause[] = [];\n  private limitValue: number | undefined;\n\n  constructor(httpClient: HttpClient, path: string) {\n    this.httpClient = httpClient;\n    this.path = path;\n  }\n\n  doc(id: string): DocumentRef<T> {\n    validateSegment(id, 'document ID');\n    return new DocumentRef<T>(this.httpClient, `${this.path}/${id}`);\n  }\n\n  async add(data: T): Promise<PalbaseResponse<DocumentRef<T>>> {\n    const response = await this.httpClient.request<{ id: string }>(\n      'POST',\n      `/v1/docs/${this.path}`,\n      { body: data },\n    );\n\n    if (response.error || !response.data) {\n      return {\n        data: null,\n        error: response.error,\n        status: response.status,\n      };\n    }\n\n    const ref = new DocumentRef<T>(this.httpClient, `${this.path}/${response.data.id}`);\n    return { data: ref, error: null, status: response.status };\n  }\n\n  where(field: string, op: WhereOperator, value: unknown): CollectionRef<T> {\n    const clone = this.clone();\n    clone.whereClauses.push({ field, op, value });\n    return clone;\n  }\n\n  orderBy(field: string, direction?: OrderDirection): CollectionRef<T> {\n    const clone = this.clone();\n    clone.orderByClauses.push({ field, direction: direction ?? 'asc' });\n    return clone;\n  }\n\n  limit(n: number): CollectionRef<T> {\n    const clone = this.clone();\n    clone.limitValue = n;\n    return clone;\n  }\n\n  async get(): Promise<PalbaseResponse<QuerySnapshot<T>>> {\n    const hasQuery = this.whereClauses.length > 0 || this.orderByClauses.length > 0 || this.limitValue !== undefined;\n\n    if (hasQuery) {\n      return this.executeQuery();\n    }\n\n    const response = await this.httpClient.request<{ documents: { id: string; data: T }[] }>(\n      'GET',\n      `/v1/docs/${this.path}`,\n    );\n\n    if (response.error) {\n      return { data: null, error: response.error, status: response.status };\n    }\n\n    const docs = (response.data?.documents ?? []).map((doc) => this.toSnapshot(doc));\n    return {\n      data: this.toQuerySnapshot(docs),\n      error: null,\n      status: response.status,\n    };\n  }\n\n  onSnapshot(callback: SnapshotCallback<T>): () => void {\n    const body = this.buildQueryBody();\n\n    let active = true;\n    let controller: AbortController | undefined;\n\n    const poll = async () => {\n      if (!active) return;\n      controller = new AbortController();\n\n      const response = await this.httpClient.request<{ documents: { id: string; data: T }[] }>(\n        'POST',\n        `/v1/docs/${this.path}/listen`,\n        { body, signal: controller.signal },\n      );\n\n      if (!active) return;\n\n      if (response.data) {\n        const docs = (response.data.documents ?? []).map((doc) => this.toSnapshot(doc));\n        callback(this.toQuerySnapshot(docs));\n      }\n    };\n\n    // Start initial poll\n    void poll();\n\n    return () => {\n      active = false;\n      controller?.abort();\n    };\n  }\n\n  private async executeQuery(): Promise<PalbaseResponse<QuerySnapshot<T>>> {\n    const body = this.buildQueryBody();\n\n    const response = await this.httpClient.request<{ documents: { id: string; data: T }[] }>(\n      'POST',\n      `/v1/docs/${this.path}/query`,\n      { body },\n    );\n\n    if (response.error) {\n      return { data: null, error: response.error, status: response.status };\n    }\n\n    const docs = (response.data?.documents ?? []).map((doc) => this.toSnapshot(doc));\n    return {\n      data: this.toQuerySnapshot(docs),\n      error: null,\n      status: response.status,\n    };\n  }\n\n  private buildQueryBody(): Record<string, unknown> {\n    const body: Record<string, unknown> = {};\n\n    if (this.whereClauses.length > 0) {\n      body['where'] = this.whereClauses.map((w) => ({\n        field: w.field,\n        op: w.op,\n        value: w.value,\n      }));\n    }\n\n    if (this.orderByClauses.length > 0) {\n      body['orderBy'] = this.orderByClauses.map((o) => ({\n        field: o.field,\n        direction: o.direction,\n      }));\n    }\n\n    if (this.limitValue !== undefined) {\n      body['limit'] = this.limitValue;\n    }\n\n    return body;\n  }\n\n  private toSnapshot(doc: { id: string; data: T }): DocumentSnapshot<T> {\n    return {\n      id: doc.id,\n      exists: true,\n      data: () => doc.data,\n      ref: { path: `${this.path}/${doc.id}` },\n    };\n  }\n\n  private toQuerySnapshot(docs: DocumentSnapshot<T>[]): QuerySnapshot<T> {\n    return {\n      docs,\n      empty: docs.length === 0,\n      size: docs.length,\n      docChanges: () => docs.map((doc) => ({ type: 'added' as const, doc })),\n    };\n  }\n\n  private clone(): CollectionRef<T> {\n    const cloned = new CollectionRef<T>(this.httpClient, this.path);\n    cloned.whereClauses.push(...this.whereClauses);\n    cloned.orderByClauses.push(...this.orderByClauses);\n    cloned.limitValue = this.limitValue;\n    return cloned;\n  }\n}\n"],"mappings":"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","names":["SEGMENT_RE","validateSegment","SEGMENT_RE","validateSegment"]}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@palbase/modules-docs",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@palbase/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "biome check src/ __tests__/"
+  }
+}