@seaverse/dataservice 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Core type definitions for SeaVerse Data Service SDK
+ *
+ * These types are designed to be AI-friendly:
+ * - Clear, descriptive names
+ * - Self-documenting structure
+ * - Rich JSDoc comments
+ */
+/**
+ * Configuration options for creating a Data Service client
+ *
+ * @example
+ * ```typescript
+ * const config: ClientConfig = {
+ *   url: 'https://your-postgrest-api.example.com',
+ *   token: 'Bearer your-jwt-token-here',
+ * };
+ * ```
+ */
+interface ClientConfig {
+    /** PostgREST API base URL */
+    url: string;
+    /** JWT token containing user_id in payload.user_id */
+    token: string;
+    /** Optional configuration */
+    options?: {
+        /** Custom fetch implementation (useful for Node.js < 18) */
+        fetch?: typeof fetch;
+        /** Additional HTTP headers to include in all requests */
+        headers?: Record<string, string>;
+        /** Request timeout in milliseconds (default: 30000) */
+        timeout?: number;
+    };
+}
+/**
+ * Data record structure returned from the database
+ *
+ * @template T - Type of the data field (flexible JSONB)
+ *
+ * @example
+ * ```typescript
+ * type Order = DataRecord<{
+ *   order_number: string;
+ *   status: string;
+ *   total: number;
+ * }>;
+ * ```
+ */
+interface DataRecord<T = any> {
+    /** UUID primary key (database-generated or client-provided) */
+    id: string;
+    /** User ID (auto-filled from JWT token) */
+    user_id: string;
+    /** Application identifier */
+    app_id: string;
+    /** Collection name (like MongoDB collection) */
+    collection_name: string;
+    /** Flexible JSONB data field */
+    data: T;
+    /** Creation timestamp (auto-filled) */
+    created_at: string;
+    /** Last update timestamp (auto-updated) */
+    updated_at: string;
+    /** Soft delete timestamp (null if not deleted) */
+    deleted_at: string | null;
+}
+/**
+ * Query filter operators for building complex queries
+ *
+ * AI-friendly: Each operator has a clear, predictable name
+ */
+interface QueryFilter {
+    /** Field path (supports JSONB paths like 'data->status') */
+    field: string;
+    /** Operator type */
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'in' | 'contains' | 'overlaps';
+    /** Value to compare against */
+    value: any;
+}
+/**
+ * Query builder options for ordering results
+ */
+interface OrderOptions {
+    /** Sort in descending order (default: false) */
+    descending?: boolean;
+    /** Handle null values (first or last) */
+    nullsFirst?: boolean;
+}
+/**
+ * Statistics about user's data
+ *
+ * Returned by getStats() RPC function
+ */
+interface UserDataStats {
+    /** Total number of records (including deleted) */
+    total_records: number;
+    /** Number of active (non-deleted) records */
+    active_records: number;
+    /** Number of soft-deleted records */
+    deleted_records: number;
+    /** Number of unique app_ids */
+    total_apps: number;
+    /** Number of unique collection_names */
+    total_collections: number;
+}
+/**
+ * Error response from PostgREST API
+ */
+interface APIError {
+    /** Error code (e.g., '23505' for unique constraint violation) */
+    code?: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details */
+    details?: string;
+    /** Hint for resolving the error */
+    hint?: string;
+}
+/**
+ * Custom error class for SDK errors
+ *
+ * AI-friendly: Clear error types and messages
+ */
+declare class DataServiceError extends Error {
+    code?: string | undefined;
+    details?: string | undefined;
+    hint?: string | undefined;
+    statusCode?: number | undefined;
+    constructor(message: string, code?: string | undefined, details?: string | undefined, hint?: string | undefined, statusCode?: number | undefined);
+}
+/**
+ * Query builder interface for fluent API
+ *
+ * AI-friendly: Method chaining with clear intent
+ *
+ * @example
+ * ```typescript
+ * const results = await query
+ *   .eq('status', 'active')
+ *   .gt('total', 100)
+ *   .order('created_at', { descending: true })
+ *   .limit(20);
+ * ```
+ */
+interface QueryBuilder<T = any> {
+    /** Filter: field equals value */
+    eq(field: string, value: any): QueryBuilder<T>;
+    /** Filter: field not equals value */
+    neq(field: string, value: any): QueryBuilder<T>;
+    /** Filter: field greater than value */
+    gt(field: string, value: any): QueryBuilder<T>;
+    /** Filter: field greater than or equal to value */
+    gte(field: string, value: any): QueryBuilder<T>;
+    /** Filter: field less than value */
+    lt(field: string, value: any): QueryBuilder<T>;
+    /** Filter: field less than or equal to value */
+    lte(field: string, value: any): QueryBuilder<T>;
+    /** Filter: field matches pattern (case-sensitive) */
+    like(field: string, pattern: string): QueryBuilder<T>;
+    /** Filter: field matches pattern (case-insensitive) */
+    ilike(field: string, pattern: string): QueryBuilder<T>;
+    /** Filter: field value in array */
+    in(field: string, values: any[]): QueryBuilder<T>;
+    /** Filter: JSONB contains value */
+    contains(value: Record<string, any>): QueryBuilder<T>;
+    /** Filter: JSONB overlaps with value */
+    overlaps(value: Record<string, any>): QueryBuilder<T>;
+    /** Order results by field */
+    order(field: string, options?: OrderOptions): QueryBuilder<T>;
+    /** Limit number of results */
+    limit(count: number): QueryBuilder<T>;
+    /** Skip number of results (pagination) */
+    offset(count: number): QueryBuilder<T>;
+    /** Execute query and return results */
+    execute(): Promise<DataRecord<T>[]>;
+    /** Execute query and return count */
+    count(): Promise<number>;
+}
+/**
+ * Collection interface for CRUD operations
+ *
+ * AI-friendly: Clear method names indicating intent
+ */
+interface Collection<T = any> {
+    /** Insert a new record (optionally provide UUID) */
+    insert(data: T, id?: string): Promise<DataRecord<T>>;
+    /** Get a single record by ID (alias for selectById) */
+    get(id: string): Promise<DataRecord<T> | null>;
+    /** Select records with optional filters */
+    select(): QueryBuilder<T>;
+    /** Select a single record by ID */
+    selectById(id: string): Promise<DataRecord<T> | null>;
+    /** Update a record by ID (replaces entire data field) */
+    update(id: string, data: T): Promise<DataRecord<T>>;
+    /** Patch a record by ID (merges with existing data) */
+    patch(id: string, partial: Partial<T>): Promise<DataRecord<T>>;
+    /** Hard delete a record by ID */
+    delete(id: string): Promise<void>;
+    /** Soft delete a record by ID (sets deleted_at) */
+    softDelete(id: string): Promise<boolean>;
+    /** Restore a soft-deleted record */
+    restore(id: string): Promise<boolean>;
+    /** Search records by JSONB contains */
+    search(criteria: Partial<T>): Promise<DataRecord<T>[]>;
+    /** Count records in collection */
+    count(): Promise<number>;
+}
+/**
+ * Data table interface for accessing collections within a specific table
+ *
+ * Represents a physical database table (e.g., user_data, public_data)
+ */
+interface DataTable {
+    /** Get a collection from this table */
+    collection<T = any>(name: string): Collection<T>;
+    /** Batch insert multiple records into different collections */
+    batchInsert<T = any>(baseCollectionName: string, records: T[]): Promise<DataRecord<T>[]>;
+}
+/**
+ * Main client interface
+ *
+ * AI-friendly: Entry point with clear hierarchy
+ */
+interface DataServiceClient {
+    /** Automatically extracted application ID from current URL */
+    readonly appId: string;
+    /** Access user private data table (user_data) */
+    readonly userData: DataTable;
+    /** Get user data statistics (RPC call) */
+    getStats(): Promise<UserDataStats>;
+    /** Health check (RPC call) */
+    health(): Promise<{
+        status: string;
+        user_id: string;
+    }>;
+}
+
+/**
+ * Core client implementation for SeaVerse Data Service SDK
+ *
+ * Design principles:
+ * 1. AI-friendly: Clear method names, predictable behavior
+ * 2. Type-safe: Full TypeScript support
+ * 3. Chainable: Fluent API for query building
+ * 4. Secure: RLS enforced, token-based auth
+ */
+
+/**
+ * Create a new Data Service client
+ *
+ * AI-friendly: Single entry point with clear configuration
+ *
+ * @param config - Client configuration with URL and JWT token
+ * @returns DataServiceClient instance
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({
+ *   url: 'https://your-postgrest-api.example.com',
+ *   token: 'Bearer your-jwt-token-here',
+ * });
+ *
+ * // appId is automatically extracted from current URL
+ * // Direct access to collections - clean and simple
+ * const order = await client.userData.collection('orders').insert({ ... });
+ * const orders = await client.userData.collection('orders').select().execute();
+ * ```
+ */
+declare function createClient(config: ClientConfig): DataServiceClient;
+
+/**
+ * SeaVerse Data Service SDK
+ *
+ * AI-Friendly Universal Data Storage for TypeScript/JavaScript
+ *
+ * @packageDocumentation
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { createClient } from '@seaverse/data-service-sdk';
+ *
+ * // appId is automatically extracted from current URL
+ * const client = createClient({
+ *   url: 'https://postgrest.example.com',
+ *   token: 'your-jwt-token',
+ * });
+ *
+ * // Insert data - appId is automatically included
+ * const order = await client.userData.collection('orders').insert({
+ *   order_number: 'ORD-123',
+ *   status: 'pending',
+ *   total: 99.99,
+ * });
+ *
+ * // Query data
+ * const orders = await client.userData
+ *   .collection('orders')
+ *   .select()
+ *   .eq('status', 'pending')
+ *   .order('created_at', { descending: true })
+ *   .limit(10)
+ *   .execute();
+ * ```
+ */
+
+declare const VERSION = "1.0.0";
+
+export { type APIError, type ClientConfig, type Collection, type DataRecord, type DataServiceClient, DataServiceError, type DataTable, type OrderOptions, type QueryBuilder, type QueryFilter, type UserDataStats, VERSION, createClient };

package/dist/index.js

@@ -0,0 +1,371 @@
+"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 src_exports = {};
+__export(src_exports, {
+  DataServiceError: () => DataServiceError,
+  VERSION: () => VERSION,
+  createClient: () => createClient
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/types.ts
+var DataServiceError = class extends Error {
+  constructor(message, code, details, hint, statusCode) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.hint = hint;
+    this.statusCode = statusCode;
+    this.name = "DataServiceError";
+  }
+};
+
+// src/client.ts
+function extractAppId() {
+  if (typeof globalThis !== "undefined" && "location" in globalThis) {
+    const location = globalThis.location;
+    const hostname = location.hostname;
+    const withoutSeaverse = hostname.replace(/\.app\.seaverse\.ai$/, "").replace(/\.seaverse\.ai$/, "");
+    return withoutSeaverse !== hostname ? withoutSeaverse : hostname;
+  }
+  if (typeof process !== "undefined" && process.env) {
+    return process.env.SEAVERSE_APP_ID || "default";
+  }
+  return "default";
+}
+var HTTPClient = class {
+  baseUrl;
+  headers;
+  fetchFn;
+  timeout;
+  constructor(config) {
+    this.baseUrl = config.url.replace(/\/$/, "");
+    this.fetchFn = config.options?.fetch || globalThis.fetch;
+    this.timeout = config.options?.timeout || 3e4;
+    this.headers = {
+      "Authorization": config.token,
+      "Content-Type": "application/json",
+      "Prefer": "return=representation",
+      ...config.options?.headers
+    };
+  }
+  /**
+   * Make HTTP request with timeout and error handling
+   */
+  async request(method, path, body, additionalHeaders) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+        method,
+        headers: { ...this.headers, ...additionalHeaders },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        let error;
+        try {
+          error = await response.json();
+        } catch {
+          error = { message: response.statusText };
+        }
+        throw new DataServiceError(
+          error.message || "Request failed",
+          error.code,
+          error.details,
+          error.hint,
+          response.status
+        );
+      }
+      const text = await response.text();
+      return text ? JSON.parse(text) : null;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof DataServiceError) {
+        throw error;
+      }
+      if (error.name === "AbortError") {
+        throw new DataServiceError("Request timeout", "TIMEOUT");
+      }
+      throw new DataServiceError(
+        error.message || "Unknown error",
+        "NETWORK_ERROR"
+      );
+    }
+  }
+  async get(path, params) {
+    const query = params ? "?" + new URLSearchParams(params).toString() : "";
+    return this.request("GET", `${path}${query}`);
+  }
+  async post(path, body, headers) {
+    return this.request("POST", path, body, headers);
+  }
+  async patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  async delete(path) {
+    await this.request("DELETE", path);
+  }
+};
+var QueryBuilderImpl = class {
+  constructor(client, tablePath, appId, collectionName) {
+    this.client = client;
+    this.tablePath = tablePath;
+    this.appId = appId;
+    this.collectionName = collectionName;
+  }
+  filters = [];
+  ordering = null;
+  limitValue = null;
+  offsetValue = null;
+  eq(field, value) {
+    this.filters.push(`${field}=eq.${encodeURIComponent(String(value))}`);
+    return this;
+  }
+  neq(field, value) {
+    this.filters.push(`${field}=neq.${encodeURIComponent(String(value))}`);
+    return this;
+  }
+  gt(field, value) {
+    this.filters.push(`${field}=gt.${encodeURIComponent(String(value))}`);
+    return this;
+  }
+  gte(field, value) {
+    this.filters.push(`${field}=gte.${encodeURIComponent(String(value))}`);
+    return this;
+  }
+  lt(field, value) {
+    this.filters.push(`${field}=lt.${encodeURIComponent(String(value))}`);
+    return this;
+  }
+  lte(field, value) {
+    this.filters.push(`${field}=lte.${encodeURIComponent(String(value))}`);
+    return this;
+  }
+  like(field, pattern) {
+    this.filters.push(`${field}=like.${encodeURIComponent(pattern)}`);
+    return this;
+  }
+  ilike(field, pattern) {
+    this.filters.push(`${field}=ilike.${encodeURIComponent(pattern)}`);
+    return this;
+  }
+  in(field, values) {
+    const encoded = values.map((v) => encodeURIComponent(String(v))).join(",");
+    this.filters.push(`${field}=in.(${encoded})`);
+    return this;
+  }
+  contains(value) {
+    this.filters.push(`data=@>.${encodeURIComponent(JSON.stringify(value))}`);
+    return this;
+  }
+  overlaps(value) {
+    this.filters.push(`data=&&.${encodeURIComponent(JSON.stringify(value))}`);
+    return this;
+  }
+  order(field, options = {}) {
+    let orderStr = field;
+    if (options.descending)
+      orderStr += ".desc";
+    if (options.nullsFirst !== void 0) {
+      orderStr += options.nullsFirst ? ".nullsfirst" : ".nullslast";
+    }
+    this.ordering = orderStr;
+    return this;
+  }
+  limit(count) {
+    this.limitValue = count;
+    return this;
+  }
+  offset(count) {
+    this.offsetValue = count;
+    return this;
+  }
+  async execute() {
+    const params = {
+      app_id: `eq.${this.appId}`,
+      collection_name: `eq.${this.collectionName}`,
+      ...Object.fromEntries(this.filters.map((f, i) => [`filter${i}`, f]))
+    };
+    if (this.ordering)
+      params.order = this.ordering;
+    if (this.limitValue !== null)
+      params.limit = String(this.limitValue);
+    if (this.offsetValue !== null)
+      params.offset = String(this.offsetValue);
+    return this.client.get(this.tablePath, params);
+  }
+  async count() {
+    const params = {
+      app_id: `eq.${this.appId}`,
+      collection_name: `eq.${this.collectionName}`,
+      ...Object.fromEntries(this.filters.map((f, i) => [`filter${i}`, f]))
+    };
+    const response = await this.client.get(this.tablePath, {
+      ...params,
+      select: "count"
+    });
+    return response.length;
+  }
+};
+var CollectionImpl = class {
+  constructor(client, tablePath, appId, collectionName) {
+    this.client = client;
+    this.tablePath = tablePath;
+    this.appId = appId;
+    this.collectionName = collectionName;
+  }
+  async insert(data, id) {
+    const payload = {
+      app_id: this.appId,
+      collection_name: this.collectionName,
+      data
+    };
+    if (id) {
+      payload.id = id;
+    }
+    const response = await this.client.post(this.tablePath, payload);
+    return Array.isArray(response) ? response[0] : response;
+  }
+  async get(id) {
+    return this.selectById(id);
+  }
+  select() {
+    return new QueryBuilderImpl(this.client, this.tablePath, this.appId, this.collectionName);
+  }
+  async selectById(id) {
+    try {
+      const results = await this.client.get(
+        `/user_data?id=eq.${id}&app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`
+      );
+      return results[0] || null;
+    } catch (error) {
+      if (error.statusCode === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async update(id, data) {
+    const response = await this.client.patch(
+      `/user_data?id=eq.${id}&app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`,
+      { data }
+    );
+    return Array.isArray(response) ? response[0] : response;
+  }
+  async patch(id, partial) {
+    const existing = await this.selectById(id);
+    if (!existing) {
+      throw new DataServiceError(`Record with id ${id} not found`, "NOT_FOUND");
+    }
+    const merged = { ...existing.data, ...partial };
+    return this.update(id, merged);
+  }
+  async delete(id) {
+    await this.client.delete(
+      `/user_data?id=eq.${id}&app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`
+    );
+  }
+  async softDelete(id) {
+    const response = await this.client.post("/rpc/soft_delete_user_data", {
+      p_id: id
+    });
+    return response;
+  }
+  async restore(id) {
+    const response = await this.client.post("/rpc/restore_user_data", {
+      p_id: id
+    });
+    return response;
+  }
+  async search(criteria) {
+    return this.client.get(this.tablePath, {
+      app_id: `eq.${this.appId}`,
+      collection_name: `eq.${this.collectionName}`,
+      data: `@>.${JSON.stringify(criteria)}`
+    });
+  }
+  async count() {
+    const results = await this.client.get(this.tablePath, {
+      app_id: `eq.${this.appId}`,
+      collection_name: `eq.${this.collectionName}`
+    });
+    return results.length;
+  }
+};
+var DataTableImpl = class {
+  constructor(client, tablePath, appId) {
+    this.client = client;
+    this.tablePath = tablePath;
+    this.appId = appId;
+  }
+  collection(name) {
+    return new CollectionImpl(this.client, this.tablePath, this.appId, name);
+  }
+  async batchInsert(baseCollectionName, records) {
+    const results = [];
+    for (let i = 0; i < records.length; i++) {
+      const uniqueCollectionName = `${baseCollectionName}_${Date.now()}_${i}`;
+      const collection = new CollectionImpl(
+        this.client,
+        this.tablePath,
+        this.appId,
+        uniqueCollectionName
+      );
+      const result = await collection.insert(records[i]);
+      results.push(result);
+      if (i < records.length - 1) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+      }
+    }
+    return results;
+  }
+};
+var DataServiceClientImpl = class {
+  client;
+  userData;
+  appId;
+  constructor(config) {
+    this.client = new HTTPClient(config);
+    this.appId = extractAppId();
+    this.userData = new DataTableImpl(this.client, "/user_data", this.appId);
+  }
+  async getStats() {
+    const response = await this.client.post("/rpc/get_user_data_stats");
+    return Array.isArray(response) ? response[0] : response;
+  }
+  async health() {
+    return this.client.post("/rpc/health");
+  }
+};
+function createClient(config) {
+  return new DataServiceClientImpl(config);
+}
+
+// src/index.ts
+var VERSION = "1.0.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DataServiceError,
+  VERSION,
+  createClient
+});