@seaverse/dataservice 1.8.4 → 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) */

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) */

package/dist/index.js

@@ -44,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;
 }
@@ -400,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 = {
@@ -418,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);
   }
@@ -473,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 = [];
@@ -489,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);
@@ -504,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");
@@ -561,7 +645,8 @@ 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

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");
@@ -530,7 +614,8 @@ 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

package/package.json

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