@seaverse/dataservice 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SeaVerse
+
+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/README.md

@@ -0,0 +1,389 @@
+# SeaVerse Data Service SDK
+
+TypeScript/JavaScript SDK for universal data storage with PostgREST.
+
+## Installation
+
+```bash
+npm install @seaverse/data-service-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from '@seaverse/data-service-sdk';
+
+// appId is automatically extracted from current URL
+const client = createClient({
+  url: 'https://your-postgrest-api.example.com',
+  token: 'Bearer your-jwt-token-here',
+});
+
+// Insert
+const order = await client.userData
+  .collection('orders')
+  .insert({
+    order_number: 'ORD-001',
+    status: 'pending',
+    total: 99.99,
+  });
+
+// Get by ID
+const record = await client.userData
+  .collection('orders')
+  .get(order.id);
+
+// Query
+const results = await client.userData
+  .collection('orders')
+  .select()
+  .eq('data->>status', 'pending')
+  .order('created_at', { descending: true })
+  .limit(10)
+  .execute();
+
+// Update
+await client.userData
+  .collection('orders')
+  .patch(order.id, { status: 'completed' });
+
+// Delete
+await client.userData
+  .collection('orders')
+  .delete(order.id);
+```
+
+## Core Concepts
+
+### Hierarchy
+
+```
+Client → DataTable (user_data) → Collection (collection_name) → Data (JSONB)
+```
+
+### Application ID (appId)
+
+**Automatic Extraction**: The SDK automatically extracts `app_id` from the current URL:
+
+```
+URL: https://app_8e5e867e-user_f4ed2364ffcf24d6c6707d5ca5e4fe6d.app.seaverse.ai
+→ appId: app_8e5e867e-user_f4ed2364ffcf24d6c6707d5ca5e4fe6d
+
+URL: https://example.com
+→ appId: example.com
+```
+
+**Node.js Environment**: Set via environment variable:
+```bash
+export SEAVERSE_APP_ID=my-app-id
+```
+
+### Unique Constraint
+
+**Important**: Only ONE record per `(user_id, app_id, collection_name)`.
+
+For multiple records, use unique collection names:
+
+```typescript
+// ✓ Correct
+await client.userData.collection('orders_1').insert(order1);
+await client.userData.collection('orders_2').insert(order2);
+
+// ✓ Or use batch insert
+await client.userData.batchInsert('orders', [order1, order2]);
+
+// ✗ Wrong - will fail
+await client.userData.collection('orders').insert(order1);
+await client.userData.collection('orders').insert(order2); // Error: 409 Conflict
+```
+
+## API Reference
+
+### Client
+
+```typescript
+createClient(config: ClientConfig): DataServiceClient
+
+interface ClientConfig {
+  url: string;           // PostgREST API URL
+  token: string;         // JWT token with user_id in payload
+  options?: {
+    timeout?: number;    // Request timeout (ms, default: 30000)
+    headers?: Record<string, string>;
+  };
+}
+
+// Client properties
+client.appId: string     // Auto-extracted from URL
+client.userData: DataTable
+```
+
+### DataTable
+
+```typescript
+client.userData.collection<T>(name: string): Collection<T>
+client.userData.batchInsert<T>(baseName: string, records: T[]): Promise<DataRecord<T>[]>
+```
+
+### Collection
+
+```typescript
+// Create
+collection.insert(data: T, id?: string): Promise<DataRecord<T>>  // Optional UUID
+
+// Read
+collection.get(id: string): Promise<DataRecord<T> | null>
+collection.selectById(id: string): Promise<DataRecord<T> | null>
+collection.select(): QueryBuilder<T>
+collection.search(criteria: Partial<T>): Promise<DataRecord<T>[]>
+collection.count(): Promise<number>
+
+// Update
+collection.update(id: string, data: T): Promise<DataRecord<T>>
+collection.patch(id: string, partial: Partial<T>): Promise<DataRecord<T>>
+
+// Delete
+collection.delete(id: string): Promise<void>
+collection.softDelete(id: string): Promise<boolean>
+collection.restore(id: string): Promise<boolean>
+```
+
+**Note**: All IDs are UUIDs (strings). Database auto-generates if not provided.
+
+### Query Builder
+
+```typescript
+query
+  .eq(field, value)      // Equal
+  .neq(field, value)     // Not equal
+  .gt(field, value)      // Greater than
+  .gte(field, value)     // Greater than or equal
+  .lt(field, value)      // Less than
+  .lte(field, value)     // Less than or equal
+  .like(field, pattern)  // Pattern match (case-sensitive)
+  .ilike(field, pattern) // Pattern match (case-insensitive)
+  .in(field, values)     // Value in array
+  .contains(value)       // JSONB contains
+  .order(field, options) // Sort
+  .limit(count)          // Limit results
+  .offset(count)         // Skip results
+  .execute()             // Get results
+  .count()               // Get count
+```
+
+### Client Methods
+
+```typescript
+client.getStats(): Promise<UserDataStats>
+client.health(): Promise<{ status: string; user_id: string }>
+```
+
+## Examples
+
+### E-Commerce Orders
+
+```typescript
+type Order = {
+  order_number: string;
+  customer_email: string;
+  items: Array<{ product_id: string; quantity: number; price: number }>;
+  status: 'pending' | 'processing' | 'shipped' | 'delivered';
+  total: number;
+};
+
+const orders = client.userData.collection<Order>('orders');
+
+// Create
+const order = await orders.insert({
+  order_number: `ORD-${Date.now()}`,
+  customer_email: 'customer@example.com',
+  items: [{ product_id: 'PROD-001', quantity: 2, price: 29.99 }],
+  status: 'pending',
+  total: 59.98,
+});
+
+// Query
+const pending = await orders
+  .select()
+  .eq('data->>status', 'pending')
+  .gt('data->>total', '50')
+  .order('created_at', { descending: true })
+  .execute();
+
+// Update
+await orders.patch(order.id, { status: 'shipped' });
+```
+
+### GPT Conversations
+
+```typescript
+type Conversation = {
+  title: string;
+  model: string;
+  messages: Array<{
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: string;
+  }>;
+};
+
+const conversations = client.userData.collection<Conversation>('chats');
+
+const conv = await conversations.insert({
+  title: 'Project Planning',
+  model: 'claude-3-opus',
+  messages: [
+    {
+      role: 'user',
+      content: 'Help me plan a new feature',
+      timestamp: new Date().toISOString(),
+    },
+  ],
+});
+
+// Add message
+const retrieved = await conversations.get(conv.id);
+await conversations.patch(conv.id, {
+  messages: [
+    ...retrieved!.data.messages,
+    {
+      role: 'assistant',
+      content: 'I can help you with that...',
+      timestamp: new Date().toISOString(),
+    },
+  ],
+});
+```
+
+## UUID Primary Keys
+
+All records use UUID strings as primary keys:
+
+```typescript
+// Database auto-generates UUID
+const order = await orders.insert({
+  order_number: 'ORD-001',
+  status: 'pending',
+});
+console.log(order.id); // "550e8400-e29b-41d4-a716-446655440000"
+
+// Or provide your own UUID
+import { randomUUID } from 'crypto';
+
+const customId = randomUUID();
+const order2 = await orders.insert(
+  { order_number: 'ORD-002', status: 'pending' },
+  customId
+);
+console.log(order2.id === customId); // true
+```
+
+**Client-side UUID generation** (recommended for offline-first apps):
+
+```typescript
+// Node.js
+import { randomUUID } from 'crypto';
+const id = randomUUID();
+
+// Browser
+const id = crypto.randomUUID();
+
+// TypeScript with uuid library
+import { v4 as uuidv4 } from 'uuid';
+const id = uuidv4();
+```
+
+## TypeScript Support
+
+```typescript
+type MyData = {
+  name: string;
+  count: number;
+};
+
+const collection = client.userData.collection<MyData>('items');
+
+const record = await collection.insert({
+  name: 'Item 1',
+  count: 42,
+});
+
+// TypeScript knows the shape
+console.log(record.data.name);    // ✓ OK
+console.log(record.data.invalid); // ✗ TypeScript error
+```
+
+## Error Handling
+
+```typescript
+import { DataServiceError } from '@seaverse/data-service-sdk';
+
+try {
+  await collection.insert(data);
+} catch (error) {
+  if (error instanceof DataServiceError) {
+    console.error('Code:', error.code);
+    console.error('Message:', error.message);
+    console.error('Status:', error.statusCode);
+
+    if (error.code === '23505') {
+      // Unique constraint violation
+      console.log('Collection name already exists');
+    }
+  }
+}
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/seaverse/data-service-sdk
+cd data-service-sdk
+npm install
+npm run build
+```
+
+### Testing
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit .env with your credentials
+# POSTGREST_URL=https://your-api.example.com
+# JWT_TOKEN=Bearer your-token-here
+
+# Run tests
+npm run test:examples
+```
+
+### Scripts
+
+- `npm run build` - Build the SDK
+- `npm run dev` - Build in watch mode
+- `npm run test:examples` - Run integration tests
+- `npm run lint` - Lint code
+- `npm run format` - Format code
+
+## Security
+
+Built on PostgreSQL Row-Level Security (RLS):
+- JWT authentication with user_id in payload
+- Automatic data isolation per user
+- No admin bypass
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+MIT - See [LICENSE](LICENSE)
+
+## Links
+
+- [GitHub](https://github.com/seaverse/data-service-sdk)
+- [Issues](https://github.com/seaverse/data-service-sdk/issues)
+- [AI Usage Guide](AI-USAGE-GUIDE.md)

package/dist/index.d.mts

@@ -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 };