@seaverse/data-service-sdk 0.6.0 → 0.7.0

package/dist/browser.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
-  typeof define === 'function' && define.amd ? define(['exports'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.SeaVerseDataService = {}));
-})(this, (function (exports) { 'use strict';
+  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('firebase/firestore')) :
+  typeof define === 'function' && define.amd ? define(['exports', 'firebase/firestore'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.SeaVerseDataService = {}, global.firestore));
+})(this, (function (exports, firestore) { 'use strict';
 
   /**
    * Create a bound version of a function with a specified `this` context
@@ -4179,96 +4179,6 @@
       }
   }
 
-  /**
-   * Create Firebase configuration from Firestore token response
-   *
-   * This helper function extracts the Firebase config from the token response,
-   * making it easy to initialize Firebase app.
-   *
-   * @param tokenResponse - The Firestore token response from SDK
-   * @returns Firebase configuration object ready for initializeApp()
-   *
-   * @example
-   * ```typescript
-   * import { initializeApp } from 'firebase/app';
-   * import { getFirebaseConfig } from '@seaverse/data-service-sdk';
-   *
-   * const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app' });
-   * const firebaseConfig = getFirebaseConfig(tokenResponse);
-   *
-   * const app = initializeApp(firebaseConfig);
-   * ```
-   */
-  function getFirebaseConfig(tokenResponse) {
-      return {
-          apiKey: tokenResponse.web_api_key,
-          projectId: tokenResponse.project_id,
-      };
-  }
-  /**
-   * Initialize Firebase with Firestore token response (browser only)
-   *
-   * This is a convenience function that automatically:
-   * 1. Creates Firebase config from token response
-   * 2. Initializes Firebase app
-   * 3. Signs in with the custom token
-   * 4. Returns authenticated Firebase instances
-   *
-   * IMPORTANT: This function requires Firebase SDK to be installed separately:
-   * npm install firebase
-   *
-   * @param tokenResponse - The Firestore token response from SDK
-   * @returns Object containing initialized Firebase app, auth, and db instances
-   *
-   * @example
-   * ```typescript
-   * import { initializeWithToken } from '@seaverse/data-service-sdk';
-   *
-   * const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app' });
-   * const { app, auth, db, userId, appId } = await initializeWithToken(tokenResponse);
-   *
-   * // Ready to use Firestore!
-   * const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
-   * ```
-   */
-  async function initializeWithToken(tokenResponse) {
-      // Check if Firebase SDK is available
-      let initializeApp;
-      let getAuth;
-      let signInWithCustomToken;
-      let getFirestore;
-      try {
-          // Try to import Firebase modules
-          const firebaseApp = await import('firebase/app');
-          const firebaseAuth = await import('firebase/auth');
-          const firebaseFirestore = await import('firebase/firestore');
-          initializeApp = firebaseApp.initializeApp;
-          getAuth = firebaseAuth.getAuth;
-          signInWithCustomToken = firebaseAuth.signInWithCustomToken;
-          getFirestore = firebaseFirestore.getFirestore;
-      }
-      catch (error) {
-          throw new Error('Firebase SDK not found. Please install it: npm install firebase\n' +
-              'Or import manually and use getFirebaseConfig() helper instead.');
-      }
-      // Initialize Firebase
-      const config = getFirebaseConfig(tokenResponse);
-      const app = initializeApp(config);
-      // Sign in with custom token
-      const auth = getAuth(app);
-      await signInWithCustomToken(auth, tokenResponse.custom_token);
-      // Get Firestore instance with correct database ID
-      // IMPORTANT: Must specify database_id, not just use default!
-      const db = getFirestore(app, tokenResponse.database_id);
-      return {
-          app,
-          auth,
-          db,
-          userId: tokenResponse.user_id,
-          appId: tokenResponse.app_id || '',
-      };
-  }
-
   /**
    * Firestore Path Helper Functions
    *
@@ -4523,12 +4433,594 @@
       USER_DATA: 'userData',
   };
 
+  /**
+   * Firestore Helper - LLM-Friendly Firestore Operations
+   *
+   * This helper class automatically handles required fields (_appId, _createdAt, _createdBy)
+   * so LLM doesn't need to remember them. It provides a simple, high-level API.
+   *
+   * 🎯 LLM-FIRST DESIGN:
+   * - No need to remember required fields
+   * - No need to construct paths manually
+   * - No need to import serverTimestamp
+   * - One method does everything
+   */
+  /**
+   * Firestore operations helper with automatic metadata injection
+   *
+   * This class wraps Firestore operations and automatically adds required fields:
+   * - _appId: Application ID (for data isolation)
+   * - _createdAt: Server timestamp (for creation time)
+   * - _createdBy: User ID (for ownership tracking)
+   *
+   * @example
+   * ```typescript
+   * const helper = new FirestoreHelper(db, appId, userId);
+   *
+   * // ✅ LLM-friendly: Just pass your data, required fields auto-injected
+   * await helper.addToPublicData('posts', {
+   *   title: 'My Post',
+   *   content: 'Hello world'
+   * });
+   *
+   * // ❌ OLD WAY: LLM needs to remember 3 required fields
+   * await addDoc(collection(db, path), {
+   *   _appId: appId,
+   *   _createdAt: serverTimestamp(),
+   *   _createdBy: userId,
+   *   title: 'My Post',
+   *   content: 'Hello world'
+   * });
+   * ```
+   */
+  class FirestoreHelper {
+      constructor(db, appId, userId) {
+          this.db = db;
+          this.appId = appId;
+          this.userId = userId;
+      }
+      /**
+       * Add document to publicData (shared, read/write for all users)
+       *
+       * Automatically injects: _appId, _createdAt, _createdBy
+       *
+       * @param collectionName - Collection name (e.g., 'posts', 'comments')
+       * @param data - Your business data
+       * @returns Document reference
+       *
+       * @example
+       * ```typescript
+       * // ✅ LLM-friendly: Simple and clean
+       * const docRef = await helper.addToPublicData('posts', {
+       *   title: 'My First Post',
+       *   content: 'Hello world'
+       * });
+       * console.log('Created post:', docRef.id);
+       * ```
+       */
+      async addToPublicData(collectionName, data) {
+          const path = getPublicDataPath(this.appId, collectionName);
+          return this.addDocWithMeta(path, data);
+      }
+      /**
+       * Add document to userData (private, only owner can read/write)
+       *
+       * Automatically injects: _appId, _createdAt, _createdBy
+       *
+       * @param collectionName - Collection name (e.g., 'notes', 'settings')
+       * @param data - Your business data
+       * @returns Document reference
+       *
+       * @example
+       * ```typescript
+       * // ✅ LLM-friendly: Private data, auto-isolated
+       * await helper.addToUserData('notes', {
+       *   title: 'Private Note',
+       *   content: 'Only I can see this'
+       * });
+       * ```
+       */
+      async addToUserData(collectionName, data) {
+          const path = getUserDataPath(this.appId, this.userId, collectionName);
+          return this.addDocWithMeta(path, data);
+      }
+      /**
+       * Get all documents from publicData collection
+       *
+       * @param collectionName - Collection name
+       * @returns QuerySnapshot with documents
+       *
+       * @example
+       * ```typescript
+       * const snapshot = await helper.getPublicData('posts');
+       * snapshot.forEach(doc => {
+       *   console.log(doc.id, doc.data());
+       * });
+       * ```
+       */
+      async getPublicData(collectionName) {
+          const path = getPublicDataPath(this.appId, collectionName);
+          return this.getDocs(path);
+      }
+      /**
+       * Get all documents from userData collection (user's private data)
+       *
+       * @param collectionName - Collection name
+       * @returns QuerySnapshot with documents
+       *
+       * @example
+       * ```typescript
+       * const snapshot = await helper.getUserData('notes');
+       * snapshot.forEach(doc => {
+       *   console.log('My note:', doc.data());
+       * });
+       * ```
+       */
+      async getUserData(collectionName) {
+          const path = getUserDataPath(this.appId, this.userId, collectionName);
+          return this.getDocs(path);
+      }
+      /**
+       * Get all documents from publicRead collection (read-only for users)
+       *
+       * @param collectionName - Collection name
+       * @returns QuerySnapshot with documents
+       *
+       * @example
+       * ```typescript
+       * const configs = await helper.getPublicRead('config');
+       * ```
+       */
+      async getPublicRead(collectionName) {
+          const path = getPublicReadPath(this.appId, collectionName);
+          return this.getDocs(path);
+      }
+      /**
+       * Get collection reference for publicData
+       * Use this for advanced queries with where(), orderBy(), limit()
+       *
+       * @param collectionName - Collection name
+       * @returns Collection reference
+       *
+       * @example
+       * ```typescript
+       * import { query, where, orderBy } from 'firebase/firestore';
+       *
+       * const postsRef = helper.publicDataCollection('posts');
+       * const q = query(
+       *   postsRef,
+       *   where('_createdBy', '==', userId),
+       *   orderBy('_createdAt', 'desc')
+       * );
+       * const snapshot = await getDocs(q);
+       * ```
+       */
+      publicDataCollection(collectionName) {
+          const path = getPublicDataPath(this.appId, collectionName);
+          return this.getCollection(path);
+      }
+      /**
+       * Get collection reference for userData
+       *
+       * @param collectionName - Collection name
+       * @returns Collection reference
+       */
+      userDataCollection(collectionName) {
+          const path = getUserDataPath(this.appId, this.userId, collectionName);
+          return this.getCollection(path);
+      }
+      /**
+       * Get collection reference for publicRead
+       *
+       * @param collectionName - Collection name
+       * @returns Collection reference
+       */
+      publicReadCollection(collectionName) {
+          const path = getPublicReadPath(this.appId, collectionName);
+          return this.getCollection(path);
+      }
+      /**
+       * Update document with automatic metadata update
+       *
+       * Automatically sets: _updatedAt, _updatedBy
+       *
+       * @param collectionPath - Full collection path
+       * @param docId - Document ID
+       * @param data - Data to update
+       *
+       * @example
+       * ```typescript
+       * await helper.updateDoc(
+       *   getPublicDataPath(appId, 'posts'),
+       *   'post-123',
+       *   { title: 'Updated Title' }
+       * );
+       * ```
+       */
+      async updateDoc(collectionPath, docId, data) {
+          const { updateDoc, doc, serverTimestamp } = await this.loadFirestore();
+          const docRef = doc(this.db, collectionPath, docId);
+          return updateDoc(docRef, {
+              ...data,
+              _updatedAt: serverTimestamp(),
+              _updatedBy: this.userId
+          });
+      }
+      /**
+       * Delete document
+       *
+       * @param collectionPath - Full collection path
+       * @param docId - Document ID
+       */
+      async deleteDoc(collectionPath, docId) {
+          const { deleteDoc, doc } = await this.loadFirestore();
+          const docRef = doc(this.db, collectionPath, docId);
+          return deleteDoc(docRef);
+      }
+      /**
+       * Get single document by ID
+       *
+       * @param collectionPath - Full collection path
+       * @param docId - Document ID
+       *
+       * @example
+       * ```typescript
+       * const docSnap = await helper.getDoc(
+       *   getPublicDataPath(appId, 'posts'),
+       *   'post-123'
+       * );
+       * if (docSnap.exists()) {
+       *   console.log(docSnap.data());
+       * }
+       * ```
+       */
+      async getDoc(collectionPath, docId) {
+          const { getDoc, doc } = await this.loadFirestore();
+          const docRef = doc(this.db, collectionPath, docId);
+          return getDoc(docRef);
+      }
+      // ============================================================================
+      // Private Helper Methods
+      // ============================================================================
+      /**
+       * Internal: Add document with metadata injection
+       */
+      async addDocWithMeta(collectionPath, data) {
+          const { addDoc, collection, serverTimestamp } = await this.loadFirestore();
+          const colRef = collection(this.db, collectionPath);
+          return addDoc(colRef, {
+              _appId: this.appId,
+              _createdAt: serverTimestamp(),
+              _createdBy: this.userId,
+              ...data
+          });
+      }
+      /**
+       * Internal: Get all documents from collection
+       */
+      async getDocs(collectionPath) {
+          const { getDocs, collection } = await this.loadFirestore();
+          const colRef = collection(this.db, collectionPath);
+          return getDocs(colRef);
+      }
+      /**
+       * Internal: Get collection reference
+       */
+      getCollection(collectionPath) {
+          // Note: This is sync, so we can't use dynamic import
+          // We assume firebase/firestore is already loaded by initializeWithToken
+          const { collection } = require('firebase/firestore');
+          return collection(this.db, collectionPath);
+      }
+      /**
+       * Internal: Lazy load Firebase Firestore functions
+       */
+      async loadFirestore() {
+          const firestore = await import('firebase/firestore');
+          return {
+              collection: firestore.collection,
+              doc: firestore.doc,
+              addDoc: firestore.addDoc,
+              setDoc: firestore.setDoc,
+              getDoc: firestore.getDoc,
+              getDocs: firestore.getDocs,
+              updateDoc: firestore.updateDoc,
+              deleteDoc: firestore.deleteDoc,
+              serverTimestamp: firestore.serverTimestamp,
+              query: firestore.query,
+              where: firestore.where,
+              orderBy: firestore.orderBy,
+              limit: firestore.limit
+          };
+      }
+  }
+  /**
+   * Standalone helper function: Add document with automatic metadata injection
+   *
+   * Use this if you don't want to create a FirestoreHelper instance.
+   *
+   * @param db - Firestore instance
+   * @param collectionPath - Full collection path
+   * @param appId - Application ID
+   * @param userId - User ID
+   * @param data - Your business data
+   * @returns Document reference
+   *
+   * @example
+   * ```typescript
+   * import { addDocWithMeta, getPublicDataPath } from '@seaverse/data-service-sdk';
+   *
+   * const docRef = await addDocWithMeta(
+   *   db,
+   *   getPublicDataPath(appId, 'posts'),
+   *   appId,
+   *   userId,
+   *   { title: 'Post', content: 'Hello' }
+   * );
+   * ```
+   */
+  async function addDocWithMeta(db, collectionPath, appId, userId, data) {
+      const { addDoc, collection, serverTimestamp } = await import('firebase/firestore');
+      const colRef = collection(db, collectionPath);
+      return addDoc(colRef, {
+          _appId: appId,
+          _createdAt: serverTimestamp(),
+          _createdBy: userId,
+          ...data
+      });
+  }
+  /**
+   * Standalone helper function: Update document with automatic metadata
+   *
+   * @param db - Firestore instance
+   * @param collectionPath - Full collection path
+   * @param docId - Document ID
+   * @param userId - User ID (for _updatedBy field)
+   * @param data - Data to update
+   *
+   * @example
+   * ```typescript
+   * import { updateDocWithMeta, getPublicDataPath } from '@seaverse/data-service-sdk';
+   *
+   * await updateDocWithMeta(
+   *   db,
+   *   getPublicDataPath(appId, 'posts'),
+   *   'post-123',
+   *   userId,
+   *   { title: 'Updated Title' }
+   * );
+   * ```
+   */
+  async function updateDocWithMeta(db, collectionPath, docId, userId, data) {
+      const { updateDoc, doc, serverTimestamp } = await import('firebase/firestore');
+      const docRef = doc(db, collectionPath, docId);
+      return updateDoc(docRef, {
+          ...data,
+          _updatedAt: serverTimestamp(),
+          _updatedBy: userId
+      });
+  }
+
+  /**
+   * Create Firebase configuration from Firestore token response
+   *
+   * This helper function extracts the Firebase config from the token response,
+   * making it easy to initialize Firebase app.
+   *
+   * @param tokenResponse - The Firestore token response from SDK
+   * @returns Firebase configuration object ready for initializeApp()
+   *
+   * @example
+   * ```typescript
+   * import { initializeApp } from 'firebase/app';
+   * import { getFirebaseConfig } from '@seaverse/data-service-sdk';
+   *
+   * const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app' });
+   * const firebaseConfig = getFirebaseConfig(tokenResponse);
+   *
+   * const app = initializeApp(firebaseConfig);
+   * ```
+   */
+  function getFirebaseConfig(tokenResponse) {
+      return {
+          apiKey: tokenResponse.web_api_key,
+          projectId: tokenResponse.project_id,
+      };
+  }
+  /**
+   * Initialize Firebase with Firestore token response (browser only)
+   *
+   * This is a convenience function that automatically:
+   * 1. Creates Firebase config from token response
+   * 2. Initializes Firebase app
+   * 3. Signs in with the custom token
+   * 4. Creates FirestoreHelper for LLM-friendly operations
+   * 5. Returns authenticated Firebase instances
+   *
+   * IMPORTANT: This function requires Firebase SDK to be installed separately:
+   * npm install firebase
+   *
+   * 🎯 LLM RECOMMENDED: Use the `helper` object for simplified operations
+   *
+   * @param tokenResponse - The Firestore token response from SDK
+   * @returns Object containing initialized Firebase instances and LLM-friendly helper
+   *
+   * @example
+   * ```typescript
+   * import { initializeWithToken } from '@seaverse/data-service-sdk';
+   *
+   * const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app' });
+   * const { db, userId, appId, helper } = await initializeWithToken(tokenResponse);
+   *
+   * // ✅ LLM-FRIENDLY: Use helper (automatic required fields)
+   * await helper.addToPublicData('posts', {
+   *   title: 'My Post',
+   *   content: 'Hello'
+   * });
+   *
+   * // ❌ OLD WAY: Manual (need to remember required fields)
+   * // await addDoc(collection(db, path), { _appId, _createdAt, _createdBy, ...data });
+   * ```
+   */
+  async function initializeWithToken(tokenResponse) {
+      // Check if Firebase SDK is available
+      let initializeApp;
+      let getAuth;
+      let signInWithCustomToken;
+      let getFirestore;
+      try {
+          // Try to import Firebase modules
+          const firebaseApp = await import('firebase/app');
+          const firebaseAuth = await import('firebase/auth');
+          const firebaseFirestore = await import('firebase/firestore');
+          initializeApp = firebaseApp.initializeApp;
+          getAuth = firebaseAuth.getAuth;
+          signInWithCustomToken = firebaseAuth.signInWithCustomToken;
+          getFirestore = firebaseFirestore.getFirestore;
+      }
+      catch (error) {
+          throw new Error('Firebase SDK not found. Please install it: npm install firebase\n' +
+              'Or import manually and use getFirebaseConfig() helper instead.');
+      }
+      // Initialize Firebase
+      const config = getFirebaseConfig(tokenResponse);
+      const app = initializeApp(config);
+      // Sign in with custom token
+      const auth = getAuth(app);
+      await signInWithCustomToken(auth, tokenResponse.custom_token);
+      // Get Firestore instance with correct database ID
+      // IMPORTANT: Must specify database_id, not just use default!
+      const db = getFirestore(app, tokenResponse.database_id);
+      const userId = tokenResponse.user_id;
+      const appId = tokenResponse.app_id || '';
+      // Create LLM-friendly helper
+      const helper = new FirestoreHelper(db, appId, userId);
+      return {
+          app,
+          auth,
+          db,
+          userId,
+          appId,
+          helper,
+      };
+  }
+
+  Object.defineProperty(exports, "addDoc", {
+    enumerable: true,
+    get: function () { return firestore.addDoc; }
+  });
+  Object.defineProperty(exports, "arrayRemove", {
+    enumerable: true,
+    get: function () { return firestore.arrayRemove; }
+  });
+  Object.defineProperty(exports, "arrayUnion", {
+    enumerable: true,
+    get: function () { return firestore.arrayUnion; }
+  });
+  Object.defineProperty(exports, "collection", {
+    enumerable: true,
+    get: function () { return firestore.collection; }
+  });
+  Object.defineProperty(exports, "collectionGroup", {
+    enumerable: true,
+    get: function () { return firestore.collectionGroup; }
+  });
+  Object.defineProperty(exports, "deleteDoc", {
+    enumerable: true,
+    get: function () { return firestore.deleteDoc; }
+  });
+  Object.defineProperty(exports, "deleteField", {
+    enumerable: true,
+    get: function () { return firestore.deleteField; }
+  });
+  Object.defineProperty(exports, "doc", {
+    enumerable: true,
+    get: function () { return firestore.doc; }
+  });
+  Object.defineProperty(exports, "endAt", {
+    enumerable: true,
+    get: function () { return firestore.endAt; }
+  });
+  Object.defineProperty(exports, "endBefore", {
+    enumerable: true,
+    get: function () { return firestore.endBefore; }
+  });
+  Object.defineProperty(exports, "getDoc", {
+    enumerable: true,
+    get: function () { return firestore.getDoc; }
+  });
+  Object.defineProperty(exports, "getDocs", {
+    enumerable: true,
+    get: function () { return firestore.getDocs; }
+  });
+  Object.defineProperty(exports, "getFirestore", {
+    enumerable: true,
+    get: function () { return firestore.getFirestore; }
+  });
+  Object.defineProperty(exports, "increment", {
+    enumerable: true,
+    get: function () { return firestore.increment; }
+  });
+  Object.defineProperty(exports, "limit", {
+    enumerable: true,
+    get: function () { return firestore.limit; }
+  });
+  Object.defineProperty(exports, "limitToLast", {
+    enumerable: true,
+    get: function () { return firestore.limitToLast; }
+  });
+  Object.defineProperty(exports, "onSnapshot", {
+    enumerable: true,
+    get: function () { return firestore.onSnapshot; }
+  });
+  Object.defineProperty(exports, "orderBy", {
+    enumerable: true,
+    get: function () { return firestore.orderBy; }
+  });
+  Object.defineProperty(exports, "query", {
+    enumerable: true,
+    get: function () { return firestore.query; }
+  });
+  Object.defineProperty(exports, "runTransaction", {
+    enumerable: true,
+    get: function () { return firestore.runTransaction; }
+  });
+  Object.defineProperty(exports, "serverTimestamp", {
+    enumerable: true,
+    get: function () { return firestore.serverTimestamp; }
+  });
+  Object.defineProperty(exports, "setDoc", {
+    enumerable: true,
+    get: function () { return firestore.setDoc; }
+  });
+  Object.defineProperty(exports, "startAfter", {
+    enumerable: true,
+    get: function () { return firestore.startAfter; }
+  });
+  Object.defineProperty(exports, "startAt", {
+    enumerable: true,
+    get: function () { return firestore.startAt; }
+  });
+  Object.defineProperty(exports, "updateDoc", {
+    enumerable: true,
+    get: function () { return firestore.updateDoc; }
+  });
+  Object.defineProperty(exports, "where", {
+    enumerable: true,
+    get: function () { return firestore.where; }
+  });
+  Object.defineProperty(exports, "writeBatch", {
+    enumerable: true,
+    get: function () { return firestore.writeBatch; }
+  });
   exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
   exports.DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
   exports.DataServiceClient = DataServiceClient;
   exports.ENDPOINTS = ENDPOINTS;
+  exports.FirestoreHelper = FirestoreHelper;
   exports.PATH_PATTERNS = PATH_PATTERNS;
   exports.PathBuilder = PathBuilder;
+  exports.addDocWithMeta = addDocWithMeta;
   exports.getFirebaseConfig = getFirebaseConfig;
   exports.getPublicDataDocPath = getPublicDataDocPath;
   exports.getPublicDataPath = getPublicDataPath;
@@ -4537,6 +5029,7 @@
   exports.getUserDataDocPath = getUserDataDocPath;
   exports.getUserDataPath = getUserDataPath;
   exports.initializeWithToken = initializeWithToken;
+  exports.updateDocWithMeta = updateDocWithMeta;
 
 }));
 //# sourceMappingURL=browser.umd.js.map