@seaverse/dataservice 1.8.3 → 1.8.5

package/README.md

@@ -471,6 +471,9 @@ collection.insert(data: T): Promise<DataRecord<T>>
 
 // Insert with custom UUID
 collection.insert(data: T, id: string): Promise<DataRecord<T>>
+
+// Upsert with deterministic per-user UUID derived from user_id + app_id + collection name
+collection.upsert(data: T): Promise<DataRecord<T>>
 ```
 
 #### Read

package/dist/index.d.mts

@@ -183,6 +183,13 @@ interface QueryBuilder<T = any> {
 interface Collection<T = any> {
     /** Insert a new record (optionally provide UUID) */
     insert(data: T, id?: string): Promise<DataRecord<T>>;
+    /**
+     * Upsert a record using a stable per-user key.
+     *
+     * The SDK derives a deterministic UUID from the authenticated user_id,
+     * app_id, and collection name, then uses PostgREST on_conflict=id.
+     */
+    upsert(data: T): Promise<DataRecord<T>>;
     /** Get a single record by ID (alias for selectById) */
     get(id: string): Promise<DataRecord<T> | null>;
     /** Select records with optional filters */
@@ -239,6 +246,8 @@ interface DataTable {
 interface DataServiceClient {
     /** Automatically extracted application ID from current URL */
     readonly appId: string;
+    /** User ID decoded from the JWT token when available */
+    readonly userId: string | null;
     /** Access user private data table (user_data) */
     readonly userData: DataTable;
     /** Get user data statistics (RPC call) */
@@ -302,6 +311,53 @@ declare function debugSetToken(token: string): void;
  * ```
  */
 declare function setAppId(appId: 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 (optional)
+ * @returns DataServiceClient instance
+ *
+ * @example
+ * ```typescript
+ * // 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({});
+ *
+ * // 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();
+ * ```
+ */
+/**
+ * Notify the parent (SeaVerse App or iframe) of the current game score.
+ *
+ * Fire-and-forget — no response is expected.
+ *
+ * Protocol:
+ * - RN WebView: window.ReactNativeWebView.postMessage({ type: 'seaverse:game_score', score: number })
+ * - iframe:     window.parent.postMessage({ type: 'seaverse:game_score', score: number }, '*')
+ *
+ * @param score Current game score (must be a non-negative number)
+ *
+ * @example
+ * ```typescript
+ * import { notifyGameScore } from '@seaverse/dataservice';
+ *
+ * // Call whenever the score updates
+ * notifyGameScore(1234);
+ * ```
+ */
+declare function notifyGameScore(score: number): void;
 declare function createClient(config?: ClientConfig): Promise<DataServiceClient>;
 
 /**
@@ -350,6 +406,6 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  * ```
  */
 
-declare const VERSION = "1.8.0";
+declare const VERSION = "1.8.4";
 
-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 };
+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, notifyGameScore, setAppId };

package/dist/index.d.ts

@@ -183,6 +183,13 @@ interface QueryBuilder<T = any> {
 interface Collection<T = any> {
     /** Insert a new record (optionally provide UUID) */
     insert(data: T, id?: string): Promise<DataRecord<T>>;
+    /**
+     * Upsert a record using a stable per-user key.
+     *
+     * The SDK derives a deterministic UUID from the authenticated user_id,
+     * app_id, and collection name, then uses PostgREST on_conflict=id.
+     */
+    upsert(data: T): Promise<DataRecord<T>>;
     /** Get a single record by ID (alias for selectById) */
     get(id: string): Promise<DataRecord<T> | null>;
     /** Select records with optional filters */
@@ -239,6 +246,8 @@ interface DataTable {
 interface DataServiceClient {
     /** Automatically extracted application ID from current URL */
     readonly appId: string;
+    /** User ID decoded from the JWT token when available */
+    readonly userId: string | null;
     /** Access user private data table (user_data) */
     readonly userData: DataTable;
     /** Get user data statistics (RPC call) */
@@ -302,6 +311,53 @@ declare function debugSetToken(token: string): void;
  * ```
  */
 declare function setAppId(appId: 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 (optional)
+ * @returns DataServiceClient instance
+ *
+ * @example
+ * ```typescript
+ * // 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({});
+ *
+ * // 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();
+ * ```
+ */
+/**
+ * Notify the parent (SeaVerse App or iframe) of the current game score.
+ *
+ * Fire-and-forget — no response is expected.
+ *
+ * Protocol:
+ * - RN WebView: window.ReactNativeWebView.postMessage({ type: 'seaverse:game_score', score: number })
+ * - iframe:     window.parent.postMessage({ type: 'seaverse:game_score', score: number }, '*')
+ *
+ * @param score Current game score (must be a non-negative number)
+ *
+ * @example
+ * ```typescript
+ * import { notifyGameScore } from '@seaverse/dataservice';
+ *
+ * // Call whenever the score updates
+ * notifyGameScore(1234);
+ * ```
+ */
+declare function notifyGameScore(score: number): void;
 declare function createClient(config?: ClientConfig): Promise<DataServiceClient>;
 
 /**
@@ -350,6 +406,6 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  * ```
  */
 
-declare const VERSION = "1.8.0";
+declare const VERSION = "1.8.4";
 
-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 };
+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, notifyGameScore, setAppId };

package/dist/index.js

@@ -24,6 +24,7 @@ __export(index_exports, {
   VERSION: () => VERSION,
   createClient: () => createClient,
   debugSetToken: () => debugSetToken,
+  notifyGameScore: () => notifyGameScore,
   setAppId: () => setAppId
 });
 module.exports = __toCommonJS(index_exports);
@@ -43,6 +44,64 @@ var DataServiceError = class extends Error {
 // src/client.ts
 var debugToken = null;
 var manualAppId = null;
+function decodeBase64Url(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+  const buffer = globalThis.Buffer;
+  if (buffer) {
+    return buffer.from(padded, "base64").toString("utf8");
+  }
+  const atobFn = globalThis.atob;
+  if (typeof atobFn === "function") {
+    const binary = atobFn(padded);
+    const bytes = Uint8Array.from(Array.from(binary, (char) => char.charCodeAt(0)));
+    const textDecoder = globalThis.TextDecoder;
+    if (typeof textDecoder === "function") {
+      return new textDecoder().decode(bytes);
+    }
+    return binary;
+  }
+  throw new DataServiceError("Unable to decode JWT payload", "JWT_DECODE_UNSUPPORTED");
+}
+function extractUserIdFromToken(token) {
+  if (!token) return null;
+  const rawToken = token.startsWith("Bearer ") ? token.slice("Bearer ".length) : token;
+  const parts = rawToken.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const payload = JSON.parse(decodeBase64Url(parts[1]));
+    return payload?.payload?.user_id || payload?.user_id || payload?.sub || null;
+  } catch {
+    return null;
+  }
+}
+function stableUuidFromParts(...parts) {
+  const input = parts.join("");
+  let h1 = 3735928559;
+  let h2 = 1103547991;
+  let h3 = 3235826430;
+  let h4 = 305419896;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+    h3 = Math.imul(h3 ^ ch, 2246822507);
+    h4 = Math.imul(h4 ^ ch, 3266489909);
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h3 ^ h3 >>> 13, 3266489909);
+  h3 = Math.imul(h3 ^ h3 >>> 16, 2246822507) ^ Math.imul(h4 ^ h4 >>> 13, 3266489909);
+  h4 = Math.imul(h4 ^ h4 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+  const bytes = new Uint8Array(16);
+  new DataView(bytes.buffer).setUint32(0, h1 >>> 0);
+  new DataView(bytes.buffer).setUint32(4, h2 >>> 0);
+  new DataView(bytes.buffer).setUint32(8, h3 >>> 0);
+  new DataView(bytes.buffer).setUint32(12, h4 >>> 0);
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 function debugSetToken(token) {
   debugToken = token;
 }
@@ -399,11 +458,12 @@ var QueryBuilderImpl = class {
   }
 };
 var CollectionImpl = class {
-  constructor(client, tablePath, appId, collectionName) {
+  constructor(client, tablePath, appId, collectionName, userId) {
     this.client = client;
     this.tablePath = tablePath;
     this.appId = appId;
     this.collectionName = collectionName;
+    this.userId = userId;
   }
   async insert(data, id) {
     const payload = {
@@ -417,6 +477,27 @@ var CollectionImpl = class {
     const response = await this.client.post(this.tablePath, payload);
     return Array.isArray(response) ? response[0] : response;
   }
+  async upsert(data) {
+    if (!this.userId) {
+      throw new DataServiceError(
+        "Unable to derive user_id from token for deterministic upsert",
+        "MISSING_USER_ID"
+      );
+    }
+    const id = stableUuidFromParts(this.userId, this.appId, this.collectionName);
+    const payload = {
+      id,
+      app_id: this.appId,
+      collection_name: this.collectionName,
+      data
+    };
+    const response = await this.client.post(
+      `${this.tablePath}?on_conflict=id`,
+      payload,
+      { Prefer: "resolution=merge-duplicates,return=representation" }
+    );
+    return Array.isArray(response) ? response[0] : response;
+  }
   async get(id) {
     return this.selectById(id);
   }
@@ -472,13 +553,14 @@ var CollectionImpl = class {
   }
 };
 var DataTableImpl = class {
-  constructor(client, tablePath, appId) {
+  constructor(client, tablePath, appId, userId) {
     this.client = client;
     this.tablePath = tablePath;
     this.appId = appId;
+    this.userId = userId;
   }
   collection(name) {
-    return new CollectionImpl(this.client, this.tablePath, this.appId, name);
+    return new CollectionImpl(this.client, this.tablePath, this.appId, name, this.userId);
   }
   async batchInsert(baseCollectionName, records) {
     const results = [];
@@ -488,7 +570,8 @@ var DataTableImpl = class {
         this.client,
         this.tablePath,
         this.appId,
-        uniqueCollectionName
+        uniqueCollectionName,
+        this.userId
       );
       const result = await collection.insert(records[i]);
       results.push(result);
@@ -503,10 +586,12 @@ var DataServiceClientImpl = class {
   client;
   userData;
   appId;
-  constructor(client, appId) {
+  userId;
+  constructor(client, appId, userId) {
     this.client = client;
     this.appId = appId;
-    this.userData = new DataTableImpl(this.client, "/user_data", this.appId);
+    this.userId = userId;
+    this.userData = new DataTableImpl(this.client, "/user_data", this.appId, userId);
   }
   async getStats() {
     const response = await this.client.post("/rpc/get_user_data_stats");
@@ -516,6 +601,19 @@ var DataServiceClientImpl = class {
     return this.client.post("/rpc/health");
   }
 };
+function notifyGameScore(score) {
+  if (!isInIframe() && !isInSeaVerseApp()) return;
+  const payload = JSON.stringify({ type: "seaverse:game_score", score });
+  try {
+    if (isInSeaVerseApp()) {
+      globalThis.window.ReactNativeWebView.postMessage(payload);
+    } else {
+      globalThis.window.parent.postMessage({ type: "seaverse:game_score", score }, "*");
+    }
+  } catch (e) {
+    console.warn("[SeaVerse DataService SDK] Failed to notify game score:", e);
+  }
+}
 async function createClient(config = {}) {
   let token = null;
   let serviceHost = null;
@@ -547,16 +645,18 @@ async function createClient(config = {}) {
     }
   }
   const appId = manualAppId || parentAppId || extractAppId();
-  return new DataServiceClientImpl(httpClient, appId);
+  const userId = extractUserIdFromToken(token);
+  return new DataServiceClientImpl(httpClient, appId, userId);
 }
 
 // src/index.ts
-var VERSION = "1.8.0";
+var VERSION = "1.8.4";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DataServiceError,
   VERSION,
   createClient,
   debugSetToken,
+  notifyGameScore,
   setAppId
 });

package/dist/index.mjs

@@ -13,6 +13,64 @@ var DataServiceError = class extends Error {
 // src/client.ts
 var debugToken = null;
 var manualAppId = null;
+function decodeBase64Url(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+  const buffer = globalThis.Buffer;
+  if (buffer) {
+    return buffer.from(padded, "base64").toString("utf8");
+  }
+  const atobFn = globalThis.atob;
+  if (typeof atobFn === "function") {
+    const binary = atobFn(padded);
+    const bytes = Uint8Array.from(Array.from(binary, (char) => char.charCodeAt(0)));
+    const textDecoder = globalThis.TextDecoder;
+    if (typeof textDecoder === "function") {
+      return new textDecoder().decode(bytes);
+    }
+    return binary;
+  }
+  throw new DataServiceError("Unable to decode JWT payload", "JWT_DECODE_UNSUPPORTED");
+}
+function extractUserIdFromToken(token) {
+  if (!token) return null;
+  const rawToken = token.startsWith("Bearer ") ? token.slice("Bearer ".length) : token;
+  const parts = rawToken.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const payload = JSON.parse(decodeBase64Url(parts[1]));
+    return payload?.payload?.user_id || payload?.user_id || payload?.sub || null;
+  } catch {
+    return null;
+  }
+}
+function stableUuidFromParts(...parts) {
+  const input = parts.join("");
+  let h1 = 3735928559;
+  let h2 = 1103547991;
+  let h3 = 3235826430;
+  let h4 = 305419896;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+    h3 = Math.imul(h3 ^ ch, 2246822507);
+    h4 = Math.imul(h4 ^ ch, 3266489909);
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h3 ^ h3 >>> 13, 3266489909);
+  h3 = Math.imul(h3 ^ h3 >>> 16, 2246822507) ^ Math.imul(h4 ^ h4 >>> 13, 3266489909);
+  h4 = Math.imul(h4 ^ h4 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+  const bytes = new Uint8Array(16);
+  new DataView(bytes.buffer).setUint32(0, h1 >>> 0);
+  new DataView(bytes.buffer).setUint32(4, h2 >>> 0);
+  new DataView(bytes.buffer).setUint32(8, h3 >>> 0);
+  new DataView(bytes.buffer).setUint32(12, h4 >>> 0);
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 function debugSetToken(token) {
   debugToken = token;
 }
@@ -369,11 +427,12 @@ var QueryBuilderImpl = class {
   }
 };
 var CollectionImpl = class {
-  constructor(client, tablePath, appId, collectionName) {
+  constructor(client, tablePath, appId, collectionName, userId) {
     this.client = client;
     this.tablePath = tablePath;
     this.appId = appId;
     this.collectionName = collectionName;
+    this.userId = userId;
   }
   async insert(data, id) {
     const payload = {
@@ -387,6 +446,27 @@ var CollectionImpl = class {
     const response = await this.client.post(this.tablePath, payload);
     return Array.isArray(response) ? response[0] : response;
   }
+  async upsert(data) {
+    if (!this.userId) {
+      throw new DataServiceError(
+        "Unable to derive user_id from token for deterministic upsert",
+        "MISSING_USER_ID"
+      );
+    }
+    const id = stableUuidFromParts(this.userId, this.appId, this.collectionName);
+    const payload = {
+      id,
+      app_id: this.appId,
+      collection_name: this.collectionName,
+      data
+    };
+    const response = await this.client.post(
+      `${this.tablePath}?on_conflict=id`,
+      payload,
+      { Prefer: "resolution=merge-duplicates,return=representation" }
+    );
+    return Array.isArray(response) ? response[0] : response;
+  }
   async get(id) {
     return this.selectById(id);
   }
@@ -442,13 +522,14 @@ var CollectionImpl = class {
   }
 };
 var DataTableImpl = class {
-  constructor(client, tablePath, appId) {
+  constructor(client, tablePath, appId, userId) {
     this.client = client;
     this.tablePath = tablePath;
     this.appId = appId;
+    this.userId = userId;
   }
   collection(name) {
-    return new CollectionImpl(this.client, this.tablePath, this.appId, name);
+    return new CollectionImpl(this.client, this.tablePath, this.appId, name, this.userId);
   }
   async batchInsert(baseCollectionName, records) {
     const results = [];
@@ -458,7 +539,8 @@ var DataTableImpl = class {
         this.client,
         this.tablePath,
         this.appId,
-        uniqueCollectionName
+        uniqueCollectionName,
+        this.userId
       );
       const result = await collection.insert(records[i]);
       results.push(result);
@@ -473,10 +555,12 @@ var DataServiceClientImpl = class {
   client;
   userData;
   appId;
-  constructor(client, appId) {
+  userId;
+  constructor(client, appId, userId) {
     this.client = client;
     this.appId = appId;
-    this.userData = new DataTableImpl(this.client, "/user_data", this.appId);
+    this.userId = userId;
+    this.userData = new DataTableImpl(this.client, "/user_data", this.appId, userId);
   }
   async getStats() {
     const response = await this.client.post("/rpc/get_user_data_stats");
@@ -486,6 +570,19 @@ var DataServiceClientImpl = class {
     return this.client.post("/rpc/health");
   }
 };
+function notifyGameScore(score) {
+  if (!isInIframe() && !isInSeaVerseApp()) return;
+  const payload = JSON.stringify({ type: "seaverse:game_score", score });
+  try {
+    if (isInSeaVerseApp()) {
+      globalThis.window.ReactNativeWebView.postMessage(payload);
+    } else {
+      globalThis.window.parent.postMessage({ type: "seaverse:game_score", score }, "*");
+    }
+  } catch (e) {
+    console.warn("[SeaVerse DataService SDK] Failed to notify game score:", e);
+  }
+}
 async function createClient(config = {}) {
   let token = null;
   let serviceHost = null;
@@ -517,15 +614,17 @@ async function createClient(config = {}) {
     }
   }
   const appId = manualAppId || parentAppId || extractAppId();
-  return new DataServiceClientImpl(httpClient, appId);
+  const userId = extractUserIdFromToken(token);
+  return new DataServiceClientImpl(httpClient, appId, userId);
 }
 
 // src/index.ts
-var VERSION = "1.8.0";
+var VERSION = "1.8.4";
 export {
   DataServiceError,
   VERSION,
   createClient,
   debugSetToken,
+  notifyGameScore,
   setAppId
 };

package/package.json

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