@seaverse/data-service-sdk 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var axios = require('axios');
+var firestore = require('firebase/firestore');
 
 /**
  * Data Service SDK configuration
@@ -265,96 +266,6 @@ class DataServiceClient {
     }
 }
 
-/**
- * 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
  *
@@ -609,12 +520,594 @@ const PATH_PATTERNS = {
     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;
@@ -623,4 +1116,5 @@ exports.getPublicReadPath = getPublicReadPath;
 exports.getUserDataDocPath = getUserDataDocPath;
 exports.getUserDataPath = getUserDataPath;
 exports.initializeWithToken = initializeWithToken;
+exports.updateDocWithMeta = updateDocWithMeta;
 //# sourceMappingURL=index.cjs.map