@seaverse/dataservice 1.2.0 → 1.5.0

package/README.md

@@ -22,33 +22,46 @@ npm install @seaverse/dataservice
 ```typescript
 import { createClient } from '@seaverse/dataservice';
 
-// Create client (uses default SeaVerse API, appId auto-extracted from URL)
-const client = createClient({
-  token: 'Bearer your-jwt-token',
+// Option 1: Auto-fetch token from parent page (iframe only)
+const client = await createClient({});
+
+// Option 2: Provide token explicitly
+const client = await createClient({
+  token: 'your-jwt-token',
 });
 
-// Access user data table
-const orders = client.userData.collection('orders');
+// Store user preferences (single record)
+const userPrefs = client.userData.collection('user_preferences');
+await userPrefs.insert({
+  theme: 'dark',
+  language: 'en',
+  notifications: true,
+});
 
-// Insert data
-const order = await orders.insert({
+// Update preferences
+await userPrefs.patch(userPrefs.id, { theme: 'light' });
+
+// Store multiple items (e.g., orders) - each needs unique collection name
+const order1 = await client.userData.collection('order_001').insert({
   order_number: 'ORD-001',
   status: 'pending',
   total: 99.99,
 });
 
-// Query data
-const pending = await orders
-  .select()
-  .eq('data->>status', 'pending')
-  .order('created_at', { descending: true })
-  .execute();
+const order2 = await client.userData.collection('order_002').insert({
+  order_number: 'ORD-002',
+  status: 'shipped',
+  total: 149.99,
+});
 
-// Update data
-await orders.patch(order.id, { status: 'completed' });
+// Or use batch insert for multiple records
+const orders = await client.userData.batchInsert('order', [
+  { order_number: 'ORD-003', status: 'pending', total: 79.99 },
+  { order_number: 'ORD-004', status: 'pending', total: 199.99 },
+]);
 
-// Delete data
-await orders.delete(order.id);
+// Delete a specific record
+await client.userData.collection('order_001').delete(order1.id);
 ```
 
 ## Core Concepts
@@ -91,22 +104,144 @@ The SDK provides access to different data tables with different permission scope
 
 ### Collections
 
-Collections are logical groupings within a table. Each collection stores one record per `(user_id, app_id, collection_name)` combination.
+**Critical Understanding**: A collection name identifies a **single record**, not a container for multiple records.
+
+The `(user_id, app_id, collection_name)` combination is a **unique constraint** - meaning each collection name can only store ONE record per user and app.
 
-**Important**: To store multiple records, use unique collection names:
+**To store multiple records, you MUST use unique collection names**:
 
 ```typescript
-// ✓ Correct: Unique collection names
-await client.userData.collection('order_1').insert(order1);
-await client.userData.collection('order_2').insert(order2);
+// ✓ CORRECT: Each record gets a unique collection name
+await client.userData.collection('order_001').insert(order1);
+await client.userData.collection('order_002').insert(order2);
+await client.userData.collection('order_003').insert(order3);
 
-// ✓ Or use batch insert helper
-await client.userData.batchInsert('order', [order1, order2]);
-// Creates: order_0, order_1, order_2, ...
+// ✓ RECOMMENDED: Use batch insert (auto-generates unique names)
+const insertedOrders = await client.userData.batchInsert('order', [order1, order2, order3]);
+// Creates collections: order_<timestamp>_0, order_<timestamp>_1, order_<timestamp>_2
 
-// ✗ Wrong: Same collection name
-await client.userData.collection('order').insert(order1);
-await client.userData.collection('order').insert(order2); // Error: 409 Conflict
+// ✗ WRONG: Reusing the same collection name
+const orders = client.userData.collection('orders');
+await orders.insert(order1); // ✓ Success
+await orders.insert(order2); // ✗ ERROR: 409 Conflict (collection 'orders' already exists)
+```
+
+**Why this design?**
+- Each collection name acts as a **unique key** for a single record
+- Think of it like a key-value store: `collection_name` → single record
+- For multiple records, use patterns like: `order_${orderId}`, `msg_${conversationId}_${msgId}`
+
+## ⚠️ Common Pitfalls
+
+### Pitfall #1: Treating Collections as Containers
+
+```typescript
+// ❌ WRONG: This looks like it should work, but it doesn't
+const orders = client.userData.collection('orders');
+await orders.insert({ order_number: 'ORD-001', total: 99.99 });  // ✓ Works
+await orders.insert({ order_number: 'ORD-002', total: 149.99 }); // ✗ ERROR: 409 Conflict!
+
+// ✓ CORRECT: Each record needs a unique collection name
+await client.userData.collection('order_001').insert({ order_number: 'ORD-001', total: 99.99 });
+await client.userData.collection('order_002').insert({ order_number: 'ORD-002', total: 149.99 });
+```
+
+**Why?** The `(user_id, app_id, collection_name)` combination is a unique constraint. Once you insert into `'orders'`, that collection name is "taken" for that user and app.
+
+### Pitfall #2: Expecting Query Methods to Return Multiple Records
+
+```typescript
+// ❌ MISLEADING: This looks like it queries multiple orders
+const orders = client.userData.collection('orders');
+const pending = await orders.select().eq('data->>status', 'pending').execute();
+// Returns: [] or [single order] - NOT multiple orders!
+
+// ✓ CORRECT: To work with multiple records, track them separately
+const orderIds = ['order_001', 'order_002', 'order_003'];
+const allOrders = await Promise.all(
+  orderIds.map(id => client.userData.collection(id).get(recordId))
+);
+```
+
+**Why?** A collection name identifies a single record, so queries on that collection can only return 0 or 1 record.
+
+### Pitfall #3: Using Plural Names for Collections
+
+```typescript
+// ❌ MISLEADING: Plural name suggests multiple items
+const orders = client.userData.collection('orders');
+const users = client.userData.collection('users');
+
+// ✓ BETTER: Use singular or ID-based names
+const order = client.userData.collection('order_12345');
+const userProfile = client.userData.collection('user_profile');
+const preference = client.userData.collection('user_preferences');
+```
+
+**Why?** Plural names create false expectations. Use singular names or include IDs to make it clear each collection is one record.
+
+## 💡 Best Practices
+
+### Pattern 1: Single Record per Concept
+
+Use this for user preferences, settings, profiles - things where you only need one record:
+
+```typescript
+// User preferences (one per user)
+const prefs = await client.userData.collection('preferences').insert({
+  theme: 'dark',
+  language: 'en',
+});
+
+// User profile (one per user)
+const profile = await client.userData.collection('profile').insert({
+  name: 'John Doe',
+  avatar: 'https://...',
+});
+```
+
+### Pattern 2: ID-Based Collection Names
+
+Use this for multiple items of the same type:
+
+```typescript
+// Multiple orders - each with unique collection name
+const order1 = await client.userData.collection(`order_${orderId1}`).insert(orderData1);
+const order2 = await client.userData.collection(`order_${orderId2}`).insert(orderData2);
+
+// Multiple conversations
+const conv1 = await client.userData.collection(`conv_${convId1}`).insert(convData1);
+const conv2 = await client.userData.collection(`conv_${convId2}`).insert(convData2);
+```
+
+### Pattern 3: Batch Insert for Multiple Records
+
+Use this when creating multiple records at once:
+
+```typescript
+// Create multiple orders in one call
+const orders = await client.userData.batchInsert('order', [
+  { order_number: 'ORD-001', total: 99.99 },
+  { order_number: 'ORD-002', total: 149.99 },
+  { order_number: 'ORD-003', total: 199.99 },
+]);
+
+// Returns array of DataRecord with auto-generated collection names
+// order_<timestamp>_0, order_<timestamp>_1, order_<timestamp>_2
+```
+
+### Pattern 4: Hierarchical Collection Names
+
+Use this for nested data structures:
+
+```typescript
+// Messages within a conversation
+await client.userData.collection(`conv_${convId}_msg_1`).insert(message1);
+await client.userData.collection(`conv_${convId}_msg_2`).insert(message2);
+
+// Tasks within a project
+await client.userData.collection(`project_${projId}_task_1`).insert(task1);
+await client.userData.collection(`project_${projId}_task_2`).insert(task2);
 ```
 
 ### Data Records
@@ -133,28 +268,54 @@ interface DataRecord<T> {
 ```typescript
 import { createClient } from '@seaverse/dataservice';
 
-const client = createClient({
-  token: string;            // JWT token (must contain user_id)
+const client = await createClient({
+  token?: string;           // JWT token (optional, auto-fetched from parent if in iframe)
   url?: string;             // PostgREST API URL (default: https://dataservice-api.seaverse.ai)
   options?: {
     timeout?: number;       // Request timeout in ms (default: 30000)
+    tokenFetchTimeout?: number; // Token fetch timeout in ms (default: 5000)
     headers?: Record<string, string>; // Additional headers
   };
 });
 ```
 
-**Examples:**
+**Token Options:**
+
+The SDK supports two ways to provide authentication:
+
+1. **Auto-fetch from parent page (iframe only)**: When running in an iframe, the SDK can automatically request the token from the parent page via PostMessage:
 
 ```typescript
-// Use default SeaVerse API
-const client = createClient({
+// No token needed - auto-fetches from parent
+const client = await createClient({});
+
+// Parent page should respond to PostMessage:
+// Send: { type: 'seaverse:get_token' }
+// Receive: { type: 'seaverse:token', payload: { accessToken: string, expiresIn: number } }
+// Error: { type: 'seaverse:error', error: string }
+```
+
+2. **Explicit token**: Provide the token directly (Bearer prefix is auto-added):
+
+```typescript
+// Token without Bearer prefix
+const client = await createClient({
+  token: 'your-jwt-token',
+});
+
+// Or with explicit Bearer prefix (both work)
+const client = await createClient({
   token: 'Bearer your-jwt-token',
 });
+```
+
+**Custom Endpoint:**
 
+```typescript
 // Use custom API endpoint
-const client = createClient({
+const client = await createClient({
   url: 'https://your-custom-api.example.com',
-  token: 'Bearer your-jwt-token',
+  token: 'your-jwt-token',
 });
 ```
 
@@ -213,14 +374,8 @@ collection.patch(id: string, partial: Partial<T>): Promise<DataRecord<T>>
 #### Delete
 
 ```typescript
-// Hard delete (permanent)
+// Delete a record by ID (permanent deletion)
 collection.delete(id: string): Promise<void>
-
-// Soft delete (sets deleted_at timestamp)
-collection.softDelete(id: string): Promise<boolean>
-
-// Restore soft-deleted record
-collection.restore(id: string): Promise<boolean>
 ```
 
 ### Query Builder
@@ -302,11 +457,10 @@ const client = createClient({
   token: process.env.JWT_TOKEN!,
 });
 
-const orders = client.userData.collection<Order>('orders');
-
-// Create order
-const order = await orders.insert({
-  order_number: `ORD-${Date.now()}`,
+// Create multiple orders - each with unique collection name
+const orderNumber1 = `ORD-${Date.now()}`;
+const order1 = await client.userData.collection<Order>(`order_${orderNumber1}`).insert({
+  order_number: orderNumber1,
   customer_email: 'customer@example.com',
   items: [
     { product_id: 'PROD-001', quantity: 2, price: 29.99 },
@@ -316,26 +470,36 @@ const order = await orders.insert({
   total: 109.97,
 });
 
-console.log('Order created:', order.id);
+console.log('Order created:', order1.id, 'Collection:', `order_${orderNumber1}`);
+
+// Create another order
+const orderNumber2 = `ORD-${Date.now() + 1}`;
+const order2 = await client.userData.collection<Order>(`order_${orderNumber2}`).insert({
+  order_number: orderNumber2,
+  customer_email: 'customer@example.com',
+  items: [
+    { product_id: 'PROD-003', quantity: 1, price: 199.99 },
+  ],
+  status: 'pending',
+  total: 199.99,
+});
 
-// Query pending orders over $50
-const pendingOrders = await orders
-  .select()
-  .eq('data->>status', 'pending')
-  .gt('data->total', '50')
-  .order('created_at', { descending: true })
-  .limit(10)
-  .execute();
+// Update order status (access by collection name)
+await client.userData.collection(`order_${orderNumber1}`).patch(order1.id, {
+  status: 'shipped'
+});
 
-console.log(`Found ${pendingOrders.length} pending orders`);
+// Get specific order
+const retrieved = await client.userData.collection(`order_${orderNumber1}`).get(order1.id);
+console.log('Order status:', retrieved?.data.status);
 
-// Update order status
-await orders.patch(order.id, { status: 'shipped' });
+// Delete a specific order
+await client.userData.collection(`order_${orderNumber1}`).delete(order1.id);
 
-// Search by customer email
-const customerOrders = await orders.search({
-  customer_email: 'customer@example.com',
-});
+// Note: To query across multiple orders, you would need to:
+// 1. Store order metadata in a separate tracking collection
+// 2. Or use a naming convention and iterate through known order IDs
+// 3. Or use the batchInsert pattern and track the generated collection names
 ```
 
 ### Chat Conversations
@@ -357,10 +521,9 @@ type Conversation = {
   };
 };
 
-const conversations = client.userData.collection<Conversation>('chats');
-
-// Create conversation
-const conv = await conversations.insert({
+// Create a new conversation with unique ID
+const conversationId = `conv_${Date.now()}`;
+const conv = await client.userData.collection<Conversation>(conversationId).insert({
   title: 'Project Planning Discussion',
   model: 'claude-3-opus',
   messages: [
@@ -372,10 +535,12 @@ const conv = await conversations.insert({
   ],
 });
 
-// Add assistant response
-const current = await conversations.get(conv.id);
+console.log('Conversation created:', conversationId);
+
+// Add assistant response to existing conversation
+const current = await client.userData.collection<Conversation>(conversationId).get(conv.id);
 if (current) {
-  await conversations.patch(conv.id, {
+  await client.userData.collection<Conversation>(conversationId).patch(conv.id, {
     messages: [
       ...current.data.messages,
       {
@@ -387,12 +552,23 @@ if (current) {
   });
 }
 
-// List recent conversations
-const recent = await conversations
-  .select()
-  .order('updated_at', { descending: true })
-  .limit(20)
-  .execute();
+// Store individual messages separately (alternative pattern)
+// Each message gets its own collection
+const msgId1 = await client.userData.collection(`${conversationId}_msg_1`).insert({
+  role: 'user',
+  content: 'Help me plan a new feature',
+  timestamp: new Date().toISOString(),
+});
+
+const msgId2 = await client.userData.collection(`${conversationId}_msg_2`).insert({
+  role: 'assistant',
+  content: 'I can help with that!',
+  timestamp: new Date().toISOString(),
+});
+
+// Get a specific conversation
+const retrieved = await client.userData.collection(conversationId).get(conv.id);
+console.log('Conversation title:', retrieved?.data.title);
 ```
 
 ### User Preferences

package/dist/index.d.mts

@@ -19,8 +19,11 @@
 interface ClientConfig {
     /** PostgREST API base URL (default: https://dataservice-api.seaverse.ai) */
     url?: string;
-    /** JWT token containing user_id in payload.user_id */
-    token: string;
+    /**
+     * JWT token containing user_id in payload.user_id
+     * If not provided, will attempt to fetch from parent page via PostMessage (iframe only)
+     */
+    token?: string;
     /** Optional configuration */
     options?: {
         /** Custom fetch implementation (useful for Node.js < 18) */
@@ -29,6 +32,8 @@ interface ClientConfig {
         headers?: Record<string, string>;
         /** Request timeout in milliseconds (default: 30000) */
         timeout?: number;
+        /** Timeout for fetching token from parent (milliseconds, default: 5000) */
+        tokenFetchTimeout?: number;
     };
 }
 /**
@@ -193,12 +198,8 @@ interface Collection<T = any> {
     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 a record by ID (permanent) */
     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 */
@@ -244,34 +245,59 @@ interface DataServiceClient {
  * 4. Secure: RLS enforced, token-based auth
  */
 
+/**
+ * Set debug token for testing/debugging
+ * This allows you to bypass the token fetch logic during development
+ *
+ * @param token The token to use for debugging
+ *
+ * @example
+ * ```typescript
+ * import { debugSetToken, createClient } from '@seaverse/dataservice';
+ *
+ * // Set debug token before creating client
+ * debugSetToken('your-test-token');
+ *
+ * // Client will use debug token instead of fetching
+ * const client = await createClient({});
+ * ```
+ */
+declare function debugSetToken(token: string): void;
 /**
  * Create a new Data Service client
  *
  * AI-friendly: Single entry point with clear configuration
  *
- * @param config - Client configuration with JWT token (URL defaults to https://dataservice-api.seaverse.ai)
+ * @param config - Client configuration (token optional, will auto-fetch from parent if in iframe)
  * @returns DataServiceClient instance
  *
  * @example
  * ```typescript
- * // Use default SeaVerse API endpoint
- * const client = createClient({
+ * // Auto-fetch token from parent page (iframe only)
+ * const client = await createClient({});
+ *
+ * // Or provide token explicitly
+ * const client = await createClient({
+ *   token: 'your-jwt-token-here',
+ * });
+ *
+ * // Bearer prefix is auto-added
+ * const client = await createClient({
  *   token: 'Bearer your-jwt-token-here',
  * });
  *
- * // Or specify custom endpoint
- * const client = createClient({
+ * // Custom endpoint
+ * const client = await createClient({
  *   url: 'https://your-postgrest-api.example.com',
- *   token: 'Bearer your-jwt-token-here',
+ *   token: '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;
+declare function createClient(config?: ClientConfig): Promise<DataServiceClient>;
 
 /**
  * SeaVerse Data Service SDK
@@ -280,18 +306,21 @@ declare function createClient(config: ClientConfig): DataServiceClient;
  *
  * @packageDocumentation
  *
- * @example Basic Usage
+ * @example Basic Usage with Auto Token Fetch
  * ```typescript
  * import { createClient } from '@seaverse/dataservice';
  *
- * // Create client (uses default SeaVerse API)
- * const client = createClient({
- *   token: 'Bearer your-jwt-token',
+ * // Auto-fetch token from parent page (iframe only)
+ * const client = await createClient({});
+ *
+ * // Or provide token explicitly
+ * const client = await createClient({
+ *   token: 'your-jwt-token',
  * });
  *
  * // appId is automatically extracted from current URL
  * // Insert data
- * const order = await client.userData.collection('orders').insert({
+ * const order = await client.userData.collection('order_001').insert({
  *   order_number: 'ORD-123',
  *   status: 'pending',
  *   total: 99.99,
@@ -299,7 +328,7 @@ declare function createClient(config: ClientConfig): DataServiceClient;
  *
  * // Query data
  * const orders = await client.userData
- *   .collection('orders')
+ *   .collection('order_001')
  *   .select()
  *   .eq('data->>status', 'pending')
  *   .order('created_at', { descending: true })
@@ -310,4 +339,4 @@ declare function createClient(config: ClientConfig): DataServiceClient;
 
 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 };
+export { type APIError, type ClientConfig, type Collection, type DataRecord, type DataServiceClient, DataServiceError, type DataTable, type OrderOptions, type QueryBuilder, type QueryFilter, type UserDataStats, VERSION, createClient, debugSetToken };

package/dist/index.d.ts

@@ -19,8 +19,11 @@
 interface ClientConfig {
     /** PostgREST API base URL (default: https://dataservice-api.seaverse.ai) */
     url?: string;
-    /** JWT token containing user_id in payload.user_id */
-    token: string;
+    /**
+     * JWT token containing user_id in payload.user_id
+     * If not provided, will attempt to fetch from parent page via PostMessage (iframe only)
+     */
+    token?: string;
     /** Optional configuration */
     options?: {
         /** Custom fetch implementation (useful for Node.js < 18) */
@@ -29,6 +32,8 @@ interface ClientConfig {
         headers?: Record<string, string>;
         /** Request timeout in milliseconds (default: 30000) */
         timeout?: number;
+        /** Timeout for fetching token from parent (milliseconds, default: 5000) */
+        tokenFetchTimeout?: number;
     };
 }
 /**
@@ -193,12 +198,8 @@ interface Collection<T = any> {
     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 a record by ID (permanent) */
     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 */
@@ -244,34 +245,59 @@ interface DataServiceClient {
  * 4. Secure: RLS enforced, token-based auth
  */
 
+/**
+ * Set debug token for testing/debugging
+ * This allows you to bypass the token fetch logic during development
+ *
+ * @param token The token to use for debugging
+ *
+ * @example
+ * ```typescript
+ * import { debugSetToken, createClient } from '@seaverse/dataservice';
+ *
+ * // Set debug token before creating client
+ * debugSetToken('your-test-token');
+ *
+ * // Client will use debug token instead of fetching
+ * const client = await createClient({});
+ * ```
+ */
+declare function debugSetToken(token: string): void;
 /**
  * Create a new Data Service client
  *
  * AI-friendly: Single entry point with clear configuration
  *
- * @param config - Client configuration with JWT token (URL defaults to https://dataservice-api.seaverse.ai)
+ * @param config - Client configuration (token optional, will auto-fetch from parent if in iframe)
  * @returns DataServiceClient instance
  *
  * @example
  * ```typescript
- * // Use default SeaVerse API endpoint
- * const client = createClient({
+ * // Auto-fetch token from parent page (iframe only)
+ * const client = await createClient({});
+ *
+ * // Or provide token explicitly
+ * const client = await createClient({
+ *   token: 'your-jwt-token-here',
+ * });
+ *
+ * // Bearer prefix is auto-added
+ * const client = await createClient({
  *   token: 'Bearer your-jwt-token-here',
  * });
  *
- * // Or specify custom endpoint
- * const client = createClient({
+ * // Custom endpoint
+ * const client = await createClient({
  *   url: 'https://your-postgrest-api.example.com',
- *   token: 'Bearer your-jwt-token-here',
+ *   token: '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;
+declare function createClient(config?: ClientConfig): Promise<DataServiceClient>;
 
 /**
  * SeaVerse Data Service SDK
@@ -280,18 +306,21 @@ declare function createClient(config: ClientConfig): DataServiceClient;
  *
  * @packageDocumentation
  *
- * @example Basic Usage
+ * @example Basic Usage with Auto Token Fetch
  * ```typescript
  * import { createClient } from '@seaverse/dataservice';
  *
- * // Create client (uses default SeaVerse API)
- * const client = createClient({
- *   token: 'Bearer your-jwt-token',
+ * // Auto-fetch token from parent page (iframe only)
+ * const client = await createClient({});
+ *
+ * // Or provide token explicitly
+ * const client = await createClient({
+ *   token: 'your-jwt-token',
  * });
  *
  * // appId is automatically extracted from current URL
  * // Insert data
- * const order = await client.userData.collection('orders').insert({
+ * const order = await client.userData.collection('order_001').insert({
  *   order_number: 'ORD-123',
  *   status: 'pending',
  *   total: 99.99,
@@ -299,7 +328,7 @@ declare function createClient(config: ClientConfig): DataServiceClient;
  *
  * // Query data
  * const orders = await client.userData
- *   .collection('orders')
+ *   .collection('order_001')
  *   .select()
  *   .eq('data->>status', 'pending')
  *   .order('created_at', { descending: true })
@@ -310,4 +339,4 @@ declare function createClient(config: ClientConfig): DataServiceClient;
 
 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 };
+export { type APIError, type ClientConfig, type Collection, type DataRecord, type DataServiceClient, DataServiceError, type DataTable, type OrderOptions, type QueryBuilder, type QueryFilter, type UserDataStats, VERSION, createClient, debugSetToken };

package/dist/index.js

@@ -22,7 +22,8 @@ var src_exports = {};
 __export(src_exports, {
   DataServiceError: () => DataServiceError,
   VERSION: () => VERSION,
-  createClient: () => createClient
+  createClient: () => createClient,
+  debugSetToken: () => debugSetToken
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -39,6 +40,54 @@ var DataServiceError = class extends Error {
 };
 
 // src/client.ts
+var debugToken = null;
+function debugSetToken(token) {
+  debugToken = token;
+}
+function isInIframe() {
+  try {
+    return typeof globalThis !== "undefined" && "window" in globalThis && globalThis.window.self !== globalThis.window.top;
+  } catch {
+    return false;
+  }
+}
+async function getTokenFromParent(timeout = 5e3) {
+  if (!isInIframe()) {
+    return null;
+  }
+  return new Promise((resolve) => {
+    const messageHandler = (event) => {
+      if (event.data && event.data.type === "seaverse:token") {
+        cleanup();
+        const token = event.data.payload?.accessToken;
+        resolve(token || null);
+      } else if (event.data && event.data.type === "seaverse:error") {
+        cleanup();
+        console.warn("[SeaVerse DataService SDK] Error getting token from parent:", event.data.error);
+        resolve(null);
+      }
+    };
+    const timeoutId = setTimeout(() => {
+      cleanup();
+      resolve(null);
+    }, timeout);
+    const cleanup = () => {
+      clearTimeout(timeoutId);
+      globalThis.window.removeEventListener("message", messageHandler);
+    };
+    globalThis.window.addEventListener("message", messageHandler);
+    try {
+      globalThis.window.parent.postMessage(
+        { type: "seaverse:get_token" },
+        "*"
+        // Allow any origin, supports cross-domain scenarios
+      );
+    } catch (e) {
+      cleanup();
+      resolve(null);
+    }
+  });
+}
 function extractAppId() {
   if (typeof globalThis !== "undefined" && "location" in globalThis) {
     const location = globalThis.location;
@@ -56,16 +105,27 @@ var HTTPClient = class {
   headers;
   fetchFn;
   timeout;
-  constructor(config) {
+  tokenPromise = null;
+  constructor(config, token) {
     this.baseUrl = (config.url || "https://dataservice-api.seaverse.ai").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
     };
+    if (token) {
+      const authToken = token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+      this.headers["Authorization"] = authToken;
+    }
+  }
+  /**
+   * Set authentication token (called after async token fetch)
+   */
+  setToken(token) {
+    const authToken = token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+    this.headers["Authorization"] = authToken;
   }
   /**
    * Make HTTP request with timeout and error handling
@@ -285,18 +345,6 @@ var CollectionImpl = class {
       `/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}`,
@@ -344,9 +392,9 @@ var DataServiceClientImpl = class {
   client;
   userData;
   appId;
-  constructor(config) {
-    this.client = new HTTPClient(config);
-    this.appId = extractAppId();
+  constructor(client, appId) {
+    this.client = client;
+    this.appId = appId;
     this.userData = new DataTableImpl(this.client, "/user_data", this.appId);
   }
   async getStats() {
@@ -357,8 +405,26 @@ var DataServiceClientImpl = class {
     return this.client.post("/rpc/health");
   }
 };
-function createClient(config) {
-  return new DataServiceClientImpl(config);
+async function createClient(config = {}) {
+  let token = config.token;
+  if (!token) {
+    if (debugToken) {
+      token = debugToken;
+    } else {
+      const timeout = config.options?.tokenFetchTimeout || 5e3;
+      const fetchedToken = await getTokenFromParent(timeout);
+      if (!fetchedToken) {
+        throw new DataServiceError(
+          "No token provided and failed to fetch from parent page. Please provide a token or ensure the app is running in an iframe with a parent that responds to seaverse:get_token messages.",
+          "NO_TOKEN"
+        );
+      }
+      token = fetchedToken;
+    }
+  }
+  const httpClient = new HTTPClient(config, token);
+  const appId = extractAppId();
+  return new DataServiceClientImpl(httpClient, appId);
 }
 
 // src/index.ts
@@ -367,5 +433,6 @@ var VERSION = "1.0.0";
 0 && (module.exports = {
   DataServiceError,
   VERSION,
-  createClient
+  createClient,
+  debugSetToken
 });

package/dist/index.mjs

@@ -11,6 +11,54 @@ var DataServiceError = class extends Error {
 };
 
 // src/client.ts
+var debugToken = null;
+function debugSetToken(token) {
+  debugToken = token;
+}
+function isInIframe() {
+  try {
+    return typeof globalThis !== "undefined" && "window" in globalThis && globalThis.window.self !== globalThis.window.top;
+  } catch {
+    return false;
+  }
+}
+async function getTokenFromParent(timeout = 5e3) {
+  if (!isInIframe()) {
+    return null;
+  }
+  return new Promise((resolve) => {
+    const messageHandler = (event) => {
+      if (event.data && event.data.type === "seaverse:token") {
+        cleanup();
+        const token = event.data.payload?.accessToken;
+        resolve(token || null);
+      } else if (event.data && event.data.type === "seaverse:error") {
+        cleanup();
+        console.warn("[SeaVerse DataService SDK] Error getting token from parent:", event.data.error);
+        resolve(null);
+      }
+    };
+    const timeoutId = setTimeout(() => {
+      cleanup();
+      resolve(null);
+    }, timeout);
+    const cleanup = () => {
+      clearTimeout(timeoutId);
+      globalThis.window.removeEventListener("message", messageHandler);
+    };
+    globalThis.window.addEventListener("message", messageHandler);
+    try {
+      globalThis.window.parent.postMessage(
+        { type: "seaverse:get_token" },
+        "*"
+        // Allow any origin, supports cross-domain scenarios
+      );
+    } catch (e) {
+      cleanup();
+      resolve(null);
+    }
+  });
+}
 function extractAppId() {
   if (typeof globalThis !== "undefined" && "location" in globalThis) {
     const location = globalThis.location;
@@ -28,16 +76,27 @@ var HTTPClient = class {
   headers;
   fetchFn;
   timeout;
-  constructor(config) {
+  tokenPromise = null;
+  constructor(config, token) {
     this.baseUrl = (config.url || "https://dataservice-api.seaverse.ai").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
     };
+    if (token) {
+      const authToken = token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+      this.headers["Authorization"] = authToken;
+    }
+  }
+  /**
+   * Set authentication token (called after async token fetch)
+   */
+  setToken(token) {
+    const authToken = token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+    this.headers["Authorization"] = authToken;
   }
   /**
    * Make HTTP request with timeout and error handling
@@ -257,18 +316,6 @@ var CollectionImpl = class {
       `/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}`,
@@ -316,9 +363,9 @@ var DataServiceClientImpl = class {
   client;
   userData;
   appId;
-  constructor(config) {
-    this.client = new HTTPClient(config);
-    this.appId = extractAppId();
+  constructor(client, appId) {
+    this.client = client;
+    this.appId = appId;
     this.userData = new DataTableImpl(this.client, "/user_data", this.appId);
   }
   async getStats() {
@@ -329,8 +376,26 @@ var DataServiceClientImpl = class {
     return this.client.post("/rpc/health");
   }
 };
-function createClient(config) {
-  return new DataServiceClientImpl(config);
+async function createClient(config = {}) {
+  let token = config.token;
+  if (!token) {
+    if (debugToken) {
+      token = debugToken;
+    } else {
+      const timeout = config.options?.tokenFetchTimeout || 5e3;
+      const fetchedToken = await getTokenFromParent(timeout);
+      if (!fetchedToken) {
+        throw new DataServiceError(
+          "No token provided and failed to fetch from parent page. Please provide a token or ensure the app is running in an iframe with a parent that responds to seaverse:get_token messages.",
+          "NO_TOKEN"
+        );
+      }
+      token = fetchedToken;
+    }
+  }
+  const httpClient = new HTTPClient(config, token);
+  const appId = extractAppId();
+  return new DataServiceClientImpl(httpClient, appId);
 }
 
 // src/index.ts
@@ -338,5 +403,6 @@ var VERSION = "1.0.0";
 export {
   DataServiceError,
   VERSION,
-  createClient
+  createClient,
+  debugSetToken
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seaverse/dataservice",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "AI-Friendly Universal Data Storage SDK for TypeScript/JavaScript",
   "main": "dist/index.js",
   "module": "dist/index.mjs",