@seaverse/dataservice 1.7.0 → 1.8.1

package/README.md

@@ -24,6 +24,7 @@ This package uses a **factory pattern** for client creation. Here's what it expo
 **Functions:**
 - `createClient(config)` - Factory function to create a client instance (async)
 - `debugSetToken(token)` - Set debug token for testing (call before createClient)
+- `setAppId(appId)` - **[Deprecated]** Set application ID manually (not recommended)
 
 **Types (TypeScript):**
 - `DataServiceClient` - Type of the client instance (**not a constructor**)
@@ -137,6 +138,27 @@ Access the extracted ID:
 console.log(client.appId); // "app_8e5e867e-user_f4ed2364"
 ```
 
+**Manual Override (Not Recommended):**
+
+For special cases where auto-extraction doesn't work, you can manually set the appId using `setAppId()`:
+
+```typescript
+import { setAppId, createClient } from '@seaverse/dataservice';
+
+// Set manual appId before creating client (highest priority)
+setAppId('my-custom-app-id');
+
+// Client will use manual appId instead of auto-extraction
+const client = await createClient({});
+console.log(client.appId); // "my-custom-app-id"
+```
+
+⚠️ **Note:** `setAppId()` is deprecated and not recommended for normal use. The SDK automatically extracts appId from the URL, which is the recommended approach. Only use this for special cases where auto-extraction doesn't work.
+
+**AppId Priority (from highest to lowest):**
+1. `setAppId()` - Manual override (not recommended)
+2. URL extraction (browser) / Environment variable (Node.js) - Automatic and recommended
+
 ### Data Tables
 
 The SDK provides access to different data tables with different permission scopes:
@@ -335,6 +357,13 @@ The SDK uses the following priority order for obtaining authentication tokens:
 2. **Parent Page Token** - Auto-fetched via PostMessage when in iframe
 3. **No Token** - Client created without authentication (API calls will fail with 401)
 
+**AppId Configuration Priority:**
+
+The SDK uses the following priority order for determining the application ID:
+
+1. **Manual AppId (Highest Priority)** - Set via `setAppId()` (not recommended, deprecated)
+2. **Auto-extraction** - Extracted from URL (browser) or environment variable (Node.js)
+
 **Production Usage (Auto-fetch from parent):**
 
 The SDK automatically fetches the authentication token and service host from the parent page via PostMessage when running in an iframe:
@@ -369,6 +398,34 @@ debugSetToken('your-test-token');
 const client = await createClient({});
 ```
 
+**Manual AppId Override (Not Recommended):**
+
+For special cases, you can force a specific appId using `setAppId()`, which will override auto-extraction:
+
+```typescript
+import { setAppId, createClient } from '@seaverse/dataservice';
+
+// Current URL: https://app_auto_extracted.app.seaverse.ai
+// Without setAppId, client.appId would be "app_auto_extracted"
+
+// Force specific appId (overrides auto-extraction)
+setAppId('my-custom-app-id');
+
+const client = await createClient({});
+console.log(client.appId); // "my-custom-app-id" (not "app_auto_extracted")
+
+// All operations will use the manual appId
+await client.userData.collection('test').insert({ foo: 'bar' });
+// ↑ This record will be stored with app_id = "my-custom-app-id"
+```
+
+⚠️ **Warning:** `setAppId()` is deprecated. Only use it when:
+- Testing in environments where URL-based extraction doesn't work
+- Debugging issues with specific appIds
+- Working around temporary limitations
+
+In production, always rely on automatic appId extraction from the URL.
+
 **Graceful Degradation:**
 
 If token or serviceHost fetching fails, the SDK gracefully handles the failure:

package/dist/index.d.mts

@@ -278,6 +278,30 @@ interface DataServiceClient {
  * ```
  */
 declare function debugSetToken(token: string): void;
+/**
+ * Set application ID manually (not recommended)
+ *
+ * @deprecated This function is not recommended for normal use.
+ * The SDK automatically extracts appId from the URL, which is the recommended approach.
+ * Only use this for special cases where auto-extraction doesn't work.
+ *
+ * When set, this appId will take highest priority over auto-extracted appId.
+ *
+ * @param appId The application ID to use
+ *
+ * @example
+ * ```typescript
+ * import { setAppId, createClient } from '@seaverse/dataservice';
+ *
+ * // Set manual appId before creating client (highest priority)
+ * setAppId('my-custom-app-id');
+ *
+ * // Client will use manual appId instead of auto-extraction
+ * const client = await createClient({});
+ * console.log(client.appId); // "my-custom-app-id"
+ * ```
+ */
+declare function setAppId(appId: string): void;
 /**
  * Create a new Data Service client
  *
@@ -353,6 +377,6 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  * ```
  */
 
-declare const VERSION = "1.6.2";
+declare const VERSION = "1.8.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, debugSetToken };
+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, setAppId };

package/dist/index.d.ts

@@ -278,6 +278,30 @@ interface DataServiceClient {
  * ```
  */
 declare function debugSetToken(token: string): void;
+/**
+ * Set application ID manually (not recommended)
+ *
+ * @deprecated This function is not recommended for normal use.
+ * The SDK automatically extracts appId from the URL, which is the recommended approach.
+ * Only use this for special cases where auto-extraction doesn't work.
+ *
+ * When set, this appId will take highest priority over auto-extracted appId.
+ *
+ * @param appId The application ID to use
+ *
+ * @example
+ * ```typescript
+ * import { setAppId, createClient } from '@seaverse/dataservice';
+ *
+ * // Set manual appId before creating client (highest priority)
+ * setAppId('my-custom-app-id');
+ *
+ * // Client will use manual appId instead of auto-extraction
+ * const client = await createClient({});
+ * console.log(client.appId); // "my-custom-app-id"
+ * ```
+ */
+declare function setAppId(appId: string): void;
 /**
  * Create a new Data Service client
  *
@@ -353,6 +377,6 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  * ```
  */
 
-declare const VERSION = "1.6.2";
+declare const VERSION = "1.8.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, debugSetToken };
+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, setAppId };

package/dist/index.js

@@ -18,14 +18,15 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   DataServiceError: () => DataServiceError,
   VERSION: () => VERSION,
   createClient: () => createClient,
-  debugSetToken: () => debugSetToken
+  debugSetToken: () => debugSetToken,
+  setAppId: () => setAppId
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
 var DataServiceError = class extends Error {
@@ -41,9 +42,13 @@ var DataServiceError = class extends Error {
 
 // src/client.ts
 var debugToken = null;
+var manualAppId = null;
 function debugSetToken(token) {
   debugToken = token;
 }
+function setAppId(appId) {
+  manualAppId = appId;
+}
 function isInIframe() {
   try {
     return typeof globalThis !== "undefined" && "window" in globalThis && globalThis.window.self !== globalThis.window.top;
@@ -125,6 +130,42 @@ async function getServiceHostFromParent(timeout = 500, serviceName = "dataservic
     }
   });
 }
+async function getAppIdFromParent(timeout = 500) {
+  if (!isInIframe()) {
+    return null;
+  }
+  return new Promise((resolve) => {
+    const messageHandler = (event) => {
+      if (event.data && event.data.type === "seaverse:appId") {
+        cleanup();
+        const appId = event.data.payload?.appId;
+        resolve(appId || null);
+      } else if (event.data && event.data.type === "seaverse:error") {
+        cleanup();
+        console.warn("[SeaVerse DataService SDK] Error getting appId 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_appId" },
+        "*"
+      );
+    } catch (e) {
+      cleanup();
+      resolve(null);
+    }
+  });
+}
 function extractAppId() {
   if (typeof globalThis !== "undefined" && "location" in globalThis) {
     const location = globalThis.location;
@@ -283,8 +324,7 @@ var QueryBuilderImpl = class {
   }
   order(field, options = {}) {
     let orderStr = field;
-    if (options.descending)
-      orderStr += ".desc";
+    if (options.descending) orderStr += ".desc";
     if (options.nullsFirst !== void 0) {
       orderStr += options.nullsFirst ? ".nullsfirst" : ".nullslast";
     }
@@ -305,12 +345,9 @@ var QueryBuilderImpl = class {
       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);
+    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() {
@@ -465,16 +502,26 @@ async function createClient(config = {}) {
     serviceHost = null;
   }
   const httpClient = new HTTPClient(config, token || void 0, serviceHost || void 0);
-  const appId = extractAppId();
+  let parentAppId = null;
+  if (!manualAppId) {
+    try {
+      parentAppId = await getAppIdFromParent(500);
+    } catch (error) {
+      console.warn("[SeaVerse DataService SDK] Failed to fetch appId:", error);
+      parentAppId = null;
+    }
+  }
+  const appId = manualAppId || parentAppId || extractAppId();
   return new DataServiceClientImpl(httpClient, appId);
 }
 
 // src/index.ts
-var VERSION = "1.6.2";
+var VERSION = "1.8.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DataServiceError,
   VERSION,
   createClient,
-  debugSetToken
+  debugSetToken,
+  setAppId
 });

package/dist/index.mjs

@@ -12,9 +12,13 @@ var DataServiceError = class extends Error {
 
 // src/client.ts
 var debugToken = null;
+var manualAppId = null;
 function debugSetToken(token) {
   debugToken = token;
 }
+function setAppId(appId) {
+  manualAppId = appId;
+}
 function isInIframe() {
   try {
     return typeof globalThis !== "undefined" && "window" in globalThis && globalThis.window.self !== globalThis.window.top;
@@ -96,6 +100,42 @@ async function getServiceHostFromParent(timeout = 500, serviceName = "dataservic
     }
   });
 }
+async function getAppIdFromParent(timeout = 500) {
+  if (!isInIframe()) {
+    return null;
+  }
+  return new Promise((resolve) => {
+    const messageHandler = (event) => {
+      if (event.data && event.data.type === "seaverse:appId") {
+        cleanup();
+        const appId = event.data.payload?.appId;
+        resolve(appId || null);
+      } else if (event.data && event.data.type === "seaverse:error") {
+        cleanup();
+        console.warn("[SeaVerse DataService SDK] Error getting appId 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_appId" },
+        "*"
+      );
+    } catch (e) {
+      cleanup();
+      resolve(null);
+    }
+  });
+}
 function extractAppId() {
   if (typeof globalThis !== "undefined" && "location" in globalThis) {
     const location = globalThis.location;
@@ -254,8 +294,7 @@ var QueryBuilderImpl = class {
   }
   order(field, options = {}) {
     let orderStr = field;
-    if (options.descending)
-      orderStr += ".desc";
+    if (options.descending) orderStr += ".desc";
     if (options.nullsFirst !== void 0) {
       orderStr += options.nullsFirst ? ".nullsfirst" : ".nullslast";
     }
@@ -276,12 +315,9 @@ var QueryBuilderImpl = class {
       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);
+    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() {
@@ -436,15 +472,25 @@ async function createClient(config = {}) {
     serviceHost = null;
   }
   const httpClient = new HTTPClient(config, token || void 0, serviceHost || void 0);
-  const appId = extractAppId();
+  let parentAppId = null;
+  if (!manualAppId) {
+    try {
+      parentAppId = await getAppIdFromParent(500);
+    } catch (error) {
+      console.warn("[SeaVerse DataService SDK] Failed to fetch appId:", error);
+      parentAppId = null;
+    }
+  }
+  const appId = manualAppId || parentAppId || extractAppId();
   return new DataServiceClientImpl(httpClient, appId);
 }
 
 // src/index.ts
-var VERSION = "1.6.2";
+var VERSION = "1.8.0";
 export {
   DataServiceError,
   VERSION,
   createClient,
-  debugSetToken
+  debugSetToken,
+  setAppId
 };

package/package.json

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