@seaverse/dataservice 1.5.0 → 1.6.0

package/README.md

@@ -22,13 +22,13 @@ npm install @seaverse/dataservice
 ```typescript
 import { createClient } from '@seaverse/dataservice';
 
-// Option 1: Auto-fetch token from parent page (iframe only)
+// Auto-fetch token from parent page (iframe)
 const client = await createClient({});
 
-// Option 2: Provide token explicitly
-const client = await createClient({
-  token: 'your-jwt-token',
-});
+// For development/testing, use debugSetToken
+import { debugSetToken } from '@seaverse/dataservice';
+debugSetToken('your-test-token');
+const client = await createClient({});
 
 // Store user preferences (single record)
 const userPrefs = client.userData.collection('user_preferences');
@@ -269,7 +269,6 @@ interface DataRecord<T> {
 import { createClient } from '@seaverse/dataservice';
 
 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)
@@ -279,11 +278,17 @@ const client = await createClient({
 });
 ```
 
-**Token Options:**
+**Token Authentication Priority:**
+
+The SDK uses the following priority order for obtaining authentication tokens:
 
-The SDK supports two ways to provide authentication:
+1. **Debug Token (Highest Priority)** - Set via `debugSetToken()`
+2. **Parent Page Token** - Auto-fetched via PostMessage when in iframe
+3. **No Token** - Client created without authentication (API calls will fail with 401)
 
-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:
+**Production Usage (Auto-fetch from parent):**
+
+The SDK automatically fetches the authentication token from the parent page via PostMessage when running in an iframe:
 
 ```typescript
 // No token needed - auto-fetches from parent
@@ -295,18 +300,37 @@ const client = await createClient({});
 // Error: { type: 'seaverse:error', error: string }
 ```
 
-2. **Explicit token**: Provide the token directly (Bearer prefix is auto-added):
+**Development/Testing (Debug Token):**
+
+For development and testing, use `debugSetToken` to bypass the parent page token fetch:
 
 ```typescript
-// Token without Bearer prefix
-const client = await createClient({
-  token: 'your-jwt-token',
-});
+import { debugSetToken, createClient } from '@seaverse/dataservice';
 
-// Or with explicit Bearer prefix (both work)
-const client = await createClient({
-  token: 'Bearer your-jwt-token',
-});
+// Set debug token BEFORE creating client (highest priority)
+debugSetToken('your-test-token');
+
+// Client will use debug token directly, skipping parent page fetch
+const client = await createClient({});
+```
+
+**Graceful Degradation:**
+
+If token fetching fails (e.g., not in an iframe, parent doesn't respond), the SDK will create a client without a token. API calls that require authentication will return 401 errors:
+
+```typescript
+// Client creation never throws, even if token fetch fails
+const client = await createClient({});
+
+try {
+  // API calls may fail with authentication errors if no token
+  const data = await client.userData.collection('test').insert({ foo: 'bar' });
+} catch (error) {
+  if (error instanceof DataServiceError && error.statusCode === 401) {
+    console.log('Authentication required - no token available');
+    // Handle authentication error (e.g., show login prompt)
+  }
+}
 ```
 
 **Custom Endpoint:**
@@ -315,7 +339,6 @@ const client = await createClient({
 // Use custom API endpoint
 const client = await createClient({
   url: 'https://your-custom-api.example.com',
-  token: 'your-jwt-token',
 });
 ```
 
@@ -453,9 +476,10 @@ type Order = {
   notes?: string;
 };
 
-const client = createClient({
-  token: process.env.JWT_TOKEN!,
-});
+// For development/testing with Node.js
+import { debugSetToken, createClient } from '@seaverse/dataservice';
+debugSetToken(process.env.JWT_TOKEN!);
+const client = await createClient({});
 
 // Create multiple orders - each with unique collection name
 const orderNumber1 = `ORD-${Date.now()}`;

package/dist/index.d.mts

@@ -12,18 +12,13 @@
  * @example
  * ```typescript
  * const config: ClientConfig = {
- *   token: 'Bearer your-jwt-token-here',
+ *   url: 'https://dataservice-api.seaverse.ai',
  * };
  * ```
  */
 interface ClientConfig {
     /** PostgREST API base URL (default: https://dataservice-api.seaverse.ai) */
     url?: 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) */
@@ -268,30 +263,24 @@ declare function debugSetToken(token: string): void;
  *
  * AI-friendly: Single entry point with clear configuration
  *
- * @param config - Client configuration (token optional, will auto-fetch from parent if in iframe)
+ * @param config - Client configuration
  * @returns DataServiceClient instance
  *
  * @example
  * ```typescript
- * // Auto-fetch token from parent page (iframe only)
+ * // Auto-fetch token from parent page (iframe)
  * 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',
- * });
- *
  * // Custom endpoint
  * const client = await createClient({
  *   url: 'https://your-postgrest-api.example.com',
- *   token: 'your-jwt-token-here',
  * });
  *
+ * // For development/testing, use debugSetToken
+ * import { debugSetToken, createClient } from '@seaverse/dataservice';
+ * debugSetToken('your-test-token');
+ * const client = await createClient({});
+ *
  * // appId is automatically extracted from current URL
  * const order = await client.userData.collection('orders').insert({ ... });
  * const orders = await client.userData.collection('orders').select().execute();
@@ -308,15 +297,14 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *
  * @example Basic Usage with Auto Token Fetch
  * ```typescript
- * import { createClient } from '@seaverse/dataservice';
+ * import { createClient, debugSetToken } from '@seaverse/dataservice';
  *
- * // Auto-fetch token from parent page (iframe only)
+ * // Auto-fetch token from parent page (iframe)
  * const client = await createClient({});
  *
- * // Or provide token explicitly
- * const client = await createClient({
- *   token: 'your-jwt-token',
- * });
+ * // For development/testing, use debugSetToken
+ * debugSetToken('your-test-token');
+ * const client = await createClient({});
  *
  * // appId is automatically extracted from current URL
  * // Insert data

package/dist/index.d.ts

@@ -12,18 +12,13 @@
  * @example
  * ```typescript
  * const config: ClientConfig = {
- *   token: 'Bearer your-jwt-token-here',
+ *   url: 'https://dataservice-api.seaverse.ai',
  * };
  * ```
  */
 interface ClientConfig {
     /** PostgREST API base URL (default: https://dataservice-api.seaverse.ai) */
     url?: 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) */
@@ -268,30 +263,24 @@ declare function debugSetToken(token: string): void;
  *
  * AI-friendly: Single entry point with clear configuration
  *
- * @param config - Client configuration (token optional, will auto-fetch from parent if in iframe)
+ * @param config - Client configuration
  * @returns DataServiceClient instance
  *
  * @example
  * ```typescript
- * // Auto-fetch token from parent page (iframe only)
+ * // Auto-fetch token from parent page (iframe)
  * 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',
- * });
- *
  * // Custom endpoint
  * const client = await createClient({
  *   url: 'https://your-postgrest-api.example.com',
- *   token: 'your-jwt-token-here',
  * });
  *
+ * // For development/testing, use debugSetToken
+ * import { debugSetToken, createClient } from '@seaverse/dataservice';
+ * debugSetToken('your-test-token');
+ * const client = await createClient({});
+ *
  * // appId is automatically extracted from current URL
  * const order = await client.userData.collection('orders').insert({ ... });
  * const orders = await client.userData.collection('orders').select().execute();
@@ -308,15 +297,14 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *
  * @example Basic Usage with Auto Token Fetch
  * ```typescript
- * import { createClient } from '@seaverse/dataservice';
+ * import { createClient, debugSetToken } from '@seaverse/dataservice';
  *
- * // Auto-fetch token from parent page (iframe only)
+ * // Auto-fetch token from parent page (iframe)
  * const client = await createClient({});
  *
- * // Or provide token explicitly
- * const client = await createClient({
- *   token: 'your-jwt-token',
- * });
+ * // For development/testing, use debugSetToken
+ * debugSetToken('your-test-token');
+ * const client = await createClient({});
  *
  * // appId is automatically extracted from current URL
  * // Insert data

package/dist/index.js

@@ -406,23 +406,19 @@ var DataServiceClientImpl = class {
   }
 };
 async function createClient(config = {}) {
-  let token = config.token;
-  if (!token) {
-    if (debugToken) {
-      token = debugToken;
-    } else {
+  let token = null;
+  if (debugToken) {
+    token = debugToken;
+  } else {
+    try {
       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;
+      token = await getTokenFromParent(timeout);
+    } catch (error) {
+      console.warn("[SeaVerse DataService SDK] Failed to fetch token:", error);
+      token = null;
     }
   }
-  const httpClient = new HTTPClient(config, token);
+  const httpClient = new HTTPClient(config, token || void 0);
   const appId = extractAppId();
   return new DataServiceClientImpl(httpClient, appId);
 }

package/dist/index.mjs

@@ -377,23 +377,19 @@ var DataServiceClientImpl = class {
   }
 };
 async function createClient(config = {}) {
-  let token = config.token;
-  if (!token) {
-    if (debugToken) {
-      token = debugToken;
-    } else {
+  let token = null;
+  if (debugToken) {
+    token = debugToken;
+  } else {
+    try {
       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;
+      token = await getTokenFromParent(timeout);
+    } catch (error) {
+      console.warn("[SeaVerse DataService SDK] Failed to fetch token:", error);
+      token = null;
     }
   }
-  const httpClient = new HTTPClient(config, token);
+  const httpClient = new HTTPClient(config, token || void 0);
   const appId = extractAppId();
   return new DataServiceClientImpl(httpClient, appId);
 }

package/package.json

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