@seaverse/dataservice 1.6.1 → 1.7.0

package/README.md

@@ -17,19 +17,61 @@ A TypeScript/JavaScript SDK for universal data storage with PostgREST backend. S
 npm install @seaverse/dataservice
 ```
 
-## Quick Start
+## Package Exports
+
+This package uses a **factory pattern** for client creation. Here's what it exports:
+
+**Functions:**
+- `createClient(config)` - Factory function to create a client instance (async)
+- `debugSetToken(token)` - Set debug token for testing (call before createClient)
+
+**Types (TypeScript):**
+- `DataServiceClient` - Type of the client instance (**not a constructor**)
+- `DataRecord<T>` - Type of stored records
+- `Collection<T>` - Type of collection instances
+- `QueryBuilder<T>` - Type of query builder instances
+- `DataTable` - Type of data table instances
+- `ClientConfig` - Configuration options for createClient
+- `DataServiceError` - Error class for API errors
+
+**Constants:**
+- `VERSION` - SDK version string
+
+**Important:** Always use `createClient()` to create clients. `DataServiceClient` is a TypeScript type, not a class constructor.
 
 ```typescript
+// ✓ CORRECT
 import { createClient } from '@seaverse/dataservice';
+const client = await createClient({});
+
+// ✗ WRONG - DataServiceClient is not a constructor
+import { DataServiceClient } from '@seaverse/dataservice';
+const client = new DataServiceClient(); // This will fail!
+```
+
+## Quick Start
+
+### Creating a Client
+
+The SDK uses a **factory function pattern**. Always use `createClient()`:
+
+**Important:** The SDK automatically obtains the service host from the parent page via PostMessage (500ms timeout). If the fetch fails, it defaults to `https://dataservice-api.seaverse.ai`. No configuration is needed.
+
+```typescript
+import { createClient, debugSetToken } from '@seaverse/dataservice';
 
-// Auto-fetch token from parent page (iframe)
+// Production: Auto-fetch token and serviceHost from parent page (when running in iframe)
+// Falls back to https://dataservice-api.seaverse.ai if fetch fails
 const client = await createClient({});
 
-// For development/testing, use debugSetToken
-import { debugSetToken } from '@seaverse/dataservice';
+// Development/Testing: Use debug token
 debugSetToken('your-test-token');
 const client = await createClient({});
+```
 
+### Basic Operations
+
+```typescript
 // Store user preferences (single record)
 const userPrefs = client.userData.collection('user_preferences');
 await userPrefs.insert({
@@ -269,7 +311,6 @@ interface DataRecord<T> {
 import { createClient } from '@seaverse/dataservice';
 
 const client = await createClient({
-  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)
@@ -278,6 +319,14 @@ const client = await createClient({
 });
 ```
 
+**ServiceHost Auto-Detection:**
+
+The SDK automatically fetches the service host from the parent page via PostMessage:
+- **Timeout**: 500ms (hardcoded, not configurable)
+- **Protocol**: Sends `{ type: 'seaverse:get_service_host', payload: { serviceName: 'dataservice' } }`
+- **Fallback**: If fetch fails, defaults to `https://dataservice-api.seaverse.ai`
+- **No user configuration**: ServiceHost is managed internally to prevent request failures
+
 **Token Authentication Priority:**
 
 The SDK uses the following priority order for obtaining authentication tokens:
@@ -288,16 +337,22 @@ The SDK uses the following priority order for obtaining authentication tokens:
 
 **Production Usage (Auto-fetch from parent):**
 
-The SDK automatically fetches the authentication token from the parent page via PostMessage when running in an iframe:
+The SDK automatically fetches the authentication token and service host from the parent page via PostMessage when running in an iframe:
 
 ```typescript
-// No token needed - auto-fetches from parent
+// No configuration needed - auto-fetches token and serviceHost from parent
 const client = await createClient({});
 
 // Parent page should respond to PostMessage:
+// Token request:
 // Send: { type: 'seaverse:get_token' }
 // Receive: { type: 'seaverse:token', payload: { accessToken: string, expiresIn: number } }
 // Error: { type: 'seaverse:error', error: string }
+
+// ServiceHost request:
+// Send: { type: 'seaverse:get_service_host', payload: { serviceName: 'dataservice' } }
+// Receive: { type: 'seaverse:service_host', payload: { serviceHost: string } }
+// Error: { type: 'seaverse:error', error: string }
 ```
 
 **Development/Testing (Debug Token):**
@@ -316,10 +371,13 @@ 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:
+If token or serviceHost fetching fails, the SDK gracefully handles the failure:
+
+- **Token fetch failure**: Creates client without authentication (API calls will return 401)
+- **ServiceHost fetch failure**: Falls back to default `https://dataservice-api.seaverse.ai`
 
 ```typescript
-// Client creation never throws, even if token fetch fails
+// Client creation never throws, even if fetch fails
 const client = await createClient({});
 
 try {
@@ -333,15 +391,6 @@ try {
 }
 ```
 
-**Custom Endpoint:**
-
-```typescript
-// Use custom API endpoint
-const client = await createClient({
-  url: 'https://your-custom-api.example.com',
-});
-```
-
 ### DataTable Methods
 
 ```typescript

package/dist/index.d.mts

@@ -12,13 +12,13 @@
  * @example
  * ```typescript
  * const config: ClientConfig = {
- *   url: 'https://dataservice-api.seaverse.ai',
+ *   options: {
+ *     timeout: 10000,
+ *   }
  * };
  * ```
  */
 interface ClientConfig {
-    /** PostgREST API base URL (default: https://dataservice-api.seaverse.ai) */
-    url?: string;
     /** Optional configuration */
     options?: {
         /** Custom fetch implementation (useful for Node.js < 18) */
@@ -214,7 +214,27 @@ interface DataTable {
 /**
  * Main client interface
  *
+ * **IMPORTANT:** This is a TypeScript type definition, NOT a class constructor.
+ * Use the `createClient()` factory function to create client instances.
+ *
  * AI-friendly: Entry point with clear hierarchy
+ *
+ * @example Correct Usage
+ * ```typescript
+ * import { createClient } from '@seaverse/dataservice';
+ *
+ * // ✓ CORRECT - Use factory function
+ * const client = await createClient({});
+ * console.log(client.appId);
+ * ```
+ *
+ * @example INCORRECT Usage
+ * ```typescript
+ * import { DataServiceClient } from '@seaverse/dataservice';
+ *
+ * // ✗ WRONG - DataServiceClient is NOT a constructor
+ * const client = new DataServiceClient(); // This will throw an error!
+ * ```
  */
 interface DataServiceClient {
     /** Automatically extracted application ID from current URL */
@@ -261,21 +281,20 @@ declare function debugSetToken(token: string): void;
 /**
  * Create a new Data Service client
  *
+ * The SDK automatically obtains the service host from the parent page via PostMessage (500ms timeout).
+ * If the fetch fails, it falls back to the default host: https://dataservice-api.seaverse.ai
+ *
  * AI-friendly: Single entry point with clear configuration
  *
- * @param config - Client configuration
+ * @param config - Client configuration (optional)
  * @returns DataServiceClient instance
  *
  * @example
  * ```typescript
- * // Auto-fetch token from parent page (iframe)
+ * // Auto-fetch token and serviceHost from parent page (iframe)
+ * // ServiceHost fetch: 500ms timeout, falls back to https://dataservice-api.seaverse.ai
  * const client = await createClient({});
  *
- * // Custom endpoint
- * const client = await createClient({
- *   url: 'https://your-postgrest-api.example.com',
- * });
- *
  * // For development/testing, use debugSetToken
  * import { debugSetToken, createClient } from '@seaverse/dataservice';
  * debugSetToken('your-test-token');
@@ -293,13 +312,15 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *
  * AI-Friendly Universal Data Storage for TypeScript/JavaScript
  *
+ * **IMPORTANT:** This SDK uses a factory pattern. Use `createClient()` to create instances.
+ *
  * @packageDocumentation
  *
  * @example Basic Usage with Auto Token Fetch
  * ```typescript
  * import { createClient, debugSetToken } from '@seaverse/dataservice';
  *
- * // Auto-fetch token from parent page (iframe)
+ * // ✓ CORRECT - Use factory function
  * const client = await createClient({});
  *
  * // For development/testing, use debugSetToken
@@ -323,8 +344,15 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *   .limit(10)
  *   .execute();
  * ```
+ *
+ * @example INCORRECT Usage - Do NOT do this
+ * ```typescript
+ * // ✗ WRONG - DataServiceClient is a type, not a constructor
+ * import { DataServiceClient } from '@seaverse/dataservice';
+ * const client = new DataServiceClient(); // This will fail!
+ * ```
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.6.2";
 
 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

@@ -12,13 +12,13 @@
  * @example
  * ```typescript
  * const config: ClientConfig = {
- *   url: 'https://dataservice-api.seaverse.ai',
+ *   options: {
+ *     timeout: 10000,
+ *   }
  * };
  * ```
  */
 interface ClientConfig {
-    /** PostgREST API base URL (default: https://dataservice-api.seaverse.ai) */
-    url?: string;
     /** Optional configuration */
     options?: {
         /** Custom fetch implementation (useful for Node.js < 18) */
@@ -214,7 +214,27 @@ interface DataTable {
 /**
  * Main client interface
  *
+ * **IMPORTANT:** This is a TypeScript type definition, NOT a class constructor.
+ * Use the `createClient()` factory function to create client instances.
+ *
  * AI-friendly: Entry point with clear hierarchy
+ *
+ * @example Correct Usage
+ * ```typescript
+ * import { createClient } from '@seaverse/dataservice';
+ *
+ * // ✓ CORRECT - Use factory function
+ * const client = await createClient({});
+ * console.log(client.appId);
+ * ```
+ *
+ * @example INCORRECT Usage
+ * ```typescript
+ * import { DataServiceClient } from '@seaverse/dataservice';
+ *
+ * // ✗ WRONG - DataServiceClient is NOT a constructor
+ * const client = new DataServiceClient(); // This will throw an error!
+ * ```
  */
 interface DataServiceClient {
     /** Automatically extracted application ID from current URL */
@@ -261,21 +281,20 @@ declare function debugSetToken(token: string): void;
 /**
  * Create a new Data Service client
  *
+ * The SDK automatically obtains the service host from the parent page via PostMessage (500ms timeout).
+ * If the fetch fails, it falls back to the default host: https://dataservice-api.seaverse.ai
+ *
  * AI-friendly: Single entry point with clear configuration
  *
- * @param config - Client configuration
+ * @param config - Client configuration (optional)
  * @returns DataServiceClient instance
  *
  * @example
  * ```typescript
- * // Auto-fetch token from parent page (iframe)
+ * // Auto-fetch token and serviceHost from parent page (iframe)
+ * // ServiceHost fetch: 500ms timeout, falls back to https://dataservice-api.seaverse.ai
  * const client = await createClient({});
  *
- * // Custom endpoint
- * const client = await createClient({
- *   url: 'https://your-postgrest-api.example.com',
- * });
- *
  * // For development/testing, use debugSetToken
  * import { debugSetToken, createClient } from '@seaverse/dataservice';
  * debugSetToken('your-test-token');
@@ -293,13 +312,15 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *
  * AI-Friendly Universal Data Storage for TypeScript/JavaScript
  *
+ * **IMPORTANT:** This SDK uses a factory pattern. Use `createClient()` to create instances.
+ *
  * @packageDocumentation
  *
  * @example Basic Usage with Auto Token Fetch
  * ```typescript
  * import { createClient, debugSetToken } from '@seaverse/dataservice';
  *
- * // Auto-fetch token from parent page (iframe)
+ * // ✓ CORRECT - Use factory function
  * const client = await createClient({});
  *
  * // For development/testing, use debugSetToken
@@ -323,8 +344,15 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *   .limit(10)
  *   .execute();
  * ```
+ *
+ * @example INCORRECT Usage - Do NOT do this
+ * ```typescript
+ * // ✗ WRONG - DataServiceClient is a type, not a constructor
+ * import { DataServiceClient } from '@seaverse/dataservice';
+ * const client = new DataServiceClient(); // This will fail!
+ * ```
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.6.2";
 
 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

@@ -88,6 +88,43 @@ async function getTokenFromParent(timeout = 5e3) {
     }
   });
 }
+async function getServiceHostFromParent(timeout = 500, serviceName = "dataservice") {
+  if (!isInIframe()) {
+    return null;
+  }
+  return new Promise((resolve) => {
+    const messageHandler = (event) => {
+      if (event.data && event.data.type === "seaverse:service_host") {
+        cleanup();
+        const serviceHost = event.data.payload?.serviceHost;
+        resolve(serviceHost || null);
+      } else if (event.data && event.data.type === "seaverse:error") {
+        cleanup();
+        console.warn("[SeaVerse DataService SDK] Error getting serviceHost 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_service_host", payload: { serviceName } },
+        "*"
+        // 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;
@@ -106,8 +143,9 @@ var HTTPClient = class {
   fetchFn;
   timeout;
   tokenPromise = null;
-  constructor(config, token) {
-    this.baseUrl = (config.url || "https://dataservice-api.seaverse.ai").replace(/\/$/, "");
+  constructor(config, token, serviceHost) {
+    const defaultHost = "https://dataservice-api.seaverse.ai";
+    this.baseUrl = (serviceHost || defaultHost).replace(/\/$/, "");
     const customFetch = config.options?.fetch;
     this.fetchFn = customFetch ? customFetch.bind(customFetch) : globalThis.fetch.bind(globalThis);
     this.timeout = config.options?.timeout || 3e4;
@@ -408,6 +446,7 @@ var DataServiceClientImpl = class {
 };
 async function createClient(config = {}) {
   let token = null;
+  let serviceHost = null;
   if (debugToken) {
     token = debugToken;
   } else {
@@ -419,13 +458,19 @@ async function createClient(config = {}) {
       token = null;
     }
   }
-  const httpClient = new HTTPClient(config, token || void 0);
+  try {
+    serviceHost = await getServiceHostFromParent(500, "dataservice");
+  } catch (error) {
+    console.warn("[SeaVerse DataService SDK] Failed to fetch serviceHost:", error);
+    serviceHost = null;
+  }
+  const httpClient = new HTTPClient(config, token || void 0, serviceHost || void 0);
   const appId = extractAppId();
   return new DataServiceClientImpl(httpClient, appId);
 }
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.6.2";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DataServiceError,

package/dist/index.mjs

@@ -59,6 +59,43 @@ async function getTokenFromParent(timeout = 5e3) {
     }
   });
 }
+async function getServiceHostFromParent(timeout = 500, serviceName = "dataservice") {
+  if (!isInIframe()) {
+    return null;
+  }
+  return new Promise((resolve) => {
+    const messageHandler = (event) => {
+      if (event.data && event.data.type === "seaverse:service_host") {
+        cleanup();
+        const serviceHost = event.data.payload?.serviceHost;
+        resolve(serviceHost || null);
+      } else if (event.data && event.data.type === "seaverse:error") {
+        cleanup();
+        console.warn("[SeaVerse DataService SDK] Error getting serviceHost 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_service_host", payload: { serviceName } },
+        "*"
+        // 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;
@@ -77,8 +114,9 @@ var HTTPClient = class {
   fetchFn;
   timeout;
   tokenPromise = null;
-  constructor(config, token) {
-    this.baseUrl = (config.url || "https://dataservice-api.seaverse.ai").replace(/\/$/, "");
+  constructor(config, token, serviceHost) {
+    const defaultHost = "https://dataservice-api.seaverse.ai";
+    this.baseUrl = (serviceHost || defaultHost).replace(/\/$/, "");
     const customFetch = config.options?.fetch;
     this.fetchFn = customFetch ? customFetch.bind(customFetch) : globalThis.fetch.bind(globalThis);
     this.timeout = config.options?.timeout || 3e4;
@@ -379,6 +417,7 @@ var DataServiceClientImpl = class {
 };
 async function createClient(config = {}) {
   let token = null;
+  let serviceHost = null;
   if (debugToken) {
     token = debugToken;
   } else {
@@ -390,13 +429,19 @@ async function createClient(config = {}) {
       token = null;
     }
   }
-  const httpClient = new HTTPClient(config, token || void 0);
+  try {
+    serviceHost = await getServiceHostFromParent(500, "dataservice");
+  } catch (error) {
+    console.warn("[SeaVerse DataService SDK] Failed to fetch serviceHost:", error);
+    serviceHost = null;
+  }
+  const httpClient = new HTTPClient(config, token || void 0, serviceHost || void 0);
   const appId = extractAppId();
   return new DataServiceClientImpl(httpClient, appId);
 }
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.6.2";
 export {
   DataServiceError,
   VERSION,

package/package.json

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