@seaverse/data-service-sdk 0.5.2 → 0.7.0

package/dist/index.js

@@ -1,4 +1,5 @@
 import axios from 'axios';
+export { addDoc, arrayRemove, arrayUnion, collection, collectionGroup, deleteDoc, deleteField, doc, endAt, endBefore, getDoc, getDocs, getFirestore, increment, limit, limitToLast, onSnapshot, orderBy, query, runTransaction, serverTimestamp, setDoc, startAfter, startAt, updateDoc, where, writeBatch } from 'firebase/firestore';
 
 /**
  * Data Service SDK configuration
@@ -263,6 +264,628 @@ class DataServiceClient {
     }
 }
 
+/**
+ * Firestore Path Helper Functions
+ *
+ * These helper functions generate correct Firestore paths that match
+ * the security rules. Use these instead of manually constructing paths
+ * to avoid permission-denied errors.
+ *
+ * 🚨 IMPORTANT: These paths are designed to work with SeaVerse Firestore Rules
+ *
+ * Permission Levels:
+ * - publicRead: Read-only for all users, write for admins only
+ * - publicData: Read/write for all authenticated users
+ * - userData: Read/write only for the data owner
+ */
+/**
+ * Generate path for publicRead data (read-only for users, write for admins)
+ *
+ * @param appId - Your application ID
+ * @param collection - Collection name (e.g., 'announcements', 'config')
+ * @returns Firestore path string
+ *
+ * @example
+ * ```typescript
+ * // Read system announcements
+ * const path = getPublicReadPath('my-app', 'announcements');
+ * // Returns: 'appData/my-app/publicRead/announcements'
+ *
+ * const snapshot = await getDocs(collection(db, path));
+ * ```
+ */
+function getPublicReadPath(appId, collectionName) {
+    validateSegment('appId', appId);
+    validateSegment('collectionName', collectionName);
+    return `appData/${appId}/publicRead/${collectionName}`;
+}
+/**
+ * Generate path for publicData (read/write for all authenticated users)
+ *
+ * @param appId - Your application ID
+ * @param collection - Collection name (e.g., 'posts', 'comments')
+ * @returns Firestore path string
+ *
+ * @example
+ * ```typescript
+ * // Write a public post
+ * const path = getPublicDataPath('my-app', 'posts');
+ * // Returns: 'appData/my-app/publicData/posts'
+ *
+ * await addDoc(collection(db, path), {
+ *   _appId: appId,
+ *   _createdAt: serverTimestamp(),
+ *   _createdBy: userId,
+ *   title: 'My Post'
+ * });
+ * ```
+ */
+function getPublicDataPath(appId, collectionName) {
+    validateSegment('appId', appId);
+    validateSegment('collectionName', collectionName);
+    return `appData/${appId}/publicData/${collectionName}`;
+}
+/**
+ * Generate path for userData (private, read/write only by owner)
+ *
+ * @param appId - Your application ID
+ * @param userId - User ID who owns this data
+ * @param collection - Collection name (e.g., 'notes', 'settings')
+ * @returns Firestore path string
+ *
+ * @example
+ * ```typescript
+ * // Write private user notes
+ * const path = getUserDataPath('my-app', 'user-123', 'notes');
+ * // Returns: 'appData/my-app/userData/user-123/notes'
+ *
+ * await addDoc(collection(db, path), {
+ *   _appId: appId,
+ *   _createdAt: serverTimestamp(),
+ *   _createdBy: userId,
+ *   content: 'Private note'
+ * });
+ * ```
+ */
+function getUserDataPath(appId, userId, collectionName) {
+    validateSegment('appId', appId);
+    validateSegment('userId', userId);
+    validateSegment('collectionName', collectionName);
+    return `appData/${appId}/userData/${userId}/${collectionName}`;
+}
+/**
+ * Generate path for a specific document in publicRead
+ *
+ * @param appId - Your application ID
+ * @param collection - Collection name
+ * @param docId - Document ID
+ * @returns Firestore document path string
+ *
+ * @example
+ * ```typescript
+ * const path = getPublicReadDocPath('my-app', 'announcements', 'announcement-1');
+ * // Returns: 'appData/my-app/publicRead/announcements/announcement-1'
+ *
+ * const docSnap = await getDoc(doc(db, path));
+ * ```
+ */
+function getPublicReadDocPath(appId, collectionName, docId) {
+    validateSegment('appId', appId);
+    validateSegment('collectionName', collectionName);
+    validateSegment('docId', docId);
+    return `appData/${appId}/publicRead/${collectionName}/${docId}`;
+}
+/**
+ * Generate path for a specific document in publicData
+ *
+ * @param appId - Your application ID
+ * @param collection - Collection name
+ * @param docId - Document ID
+ * @returns Firestore document path string
+ *
+ * @example
+ * ```typescript
+ * const path = getPublicDataDocPath('my-app', 'posts', 'post-123');
+ * // Returns: 'appData/my-app/publicData/posts/post-123'
+ *
+ * const docSnap = await getDoc(doc(db, path));
+ * ```
+ */
+function getPublicDataDocPath(appId, collectionName, docId) {
+    validateSegment('appId', appId);
+    validateSegment('collectionName', collectionName);
+    validateSegment('docId', docId);
+    return `appData/${appId}/publicData/${collectionName}/${docId}`;
+}
+/**
+ * Generate path for a specific document in userData
+ *
+ * @param appId - Your application ID
+ * @param userId - User ID who owns this data
+ * @param collection - Collection name
+ * @param docId - Document ID
+ * @returns Firestore document path string
+ *
+ * @example
+ * ```typescript
+ * const path = getUserDataDocPath('my-app', 'user-123', 'notes', 'note-456');
+ * // Returns: 'appData/my-app/userData/user-123/notes/note-456'
+ *
+ * const docSnap = await getDoc(doc(db, path));
+ * ```
+ */
+function getUserDataDocPath(appId, userId, collectionName, docId) {
+    validateSegment('appId', appId);
+    validateSegment('userId', userId);
+    validateSegment('collectionName', collectionName);
+    validateSegment('docId', docId);
+    return `appData/${appId}/userData/${userId}/${collectionName}/${docId}`;
+}
+/**
+ * Validate a path segment to ensure it doesn't contain invalid characters
+ *
+ * @param name - Parameter name for error messages
+ * @param value - The segment value to validate
+ * @throws Error if the segment is invalid
+ */
+function validateSegment(name, value) {
+    if (!value || typeof value !== 'string') {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+    if (value.includes('/')) {
+        throw new Error(`${name} cannot contain forward slashes (/). Got: "${value}"`);
+    }
+    if (value.trim() !== value) {
+        throw new Error(`${name} cannot start or end with whitespace. Got: "${value}"`);
+    }
+}
+/**
+ * Path builder for advanced use cases
+ * Provides a fluent interface for building Firestore paths
+ *
+ * @example
+ * ```typescript
+ * // Build a path step by step
+ * const builder = new PathBuilder('my-app');
+ * const path = builder.publicData('posts').build();
+ * // Returns: 'appData/my-app/publicData/posts'
+ *
+ * // With document ID
+ * const docPath = builder.publicData('posts').doc('post-123').build();
+ * // Returns: 'appData/my-app/publicData/posts/post-123'
+ * ```
+ */
+class PathBuilder {
+    constructor(appId) {
+        this.appId = appId;
+        this.segments = ['appData'];
+        validateSegment('appId', appId);
+        this.segments.push(appId);
+    }
+    /**
+     * Add publicRead collection to path
+     */
+    publicRead(collectionName) {
+        validateSegment('collectionName', collectionName);
+        this.segments.push('publicRead', collectionName);
+        return this;
+    }
+    /**
+     * Add publicData collection to path
+     */
+    publicData(collectionName) {
+        validateSegment('collectionName', collectionName);
+        this.segments.push('publicData', collectionName);
+        return this;
+    }
+    /**
+     * Add userData collection to path
+     */
+    userData(userId, collectionName) {
+        validateSegment('userId', userId);
+        validateSegment('collectionName', collectionName);
+        this.segments.push('userData', userId, collectionName);
+        return this;
+    }
+    /**
+     * Add document ID to path
+     */
+    doc(docId) {
+        validateSegment('docId', docId);
+        this.segments.push(docId);
+        return this;
+    }
+    /**
+     * Build the final path string
+     */
+    build() {
+        return this.segments.join('/');
+    }
+}
+/**
+ * Common path patterns as constants for frequently used paths
+ */
+const PATH_PATTERNS = {
+    /**
+     * Base pattern for all SeaVerse data
+     */
+    APP_DATA: 'appData',
+    /**
+     * Permission layers
+     */
+    PUBLIC_READ: 'publicRead',
+    PUBLIC_DATA: 'publicData',
+    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
  *
@@ -296,23 +919,32 @@ function getFirebaseConfig(tokenResponse) {
  * 1. Creates Firebase config from token response
  * 2. Initializes Firebase app
  * 3. Signs in with the custom token
- * 4. Returns authenticated Firebase instances
+ * 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 app, auth, and db instances
+ * @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 { app, auth, db, userId, appId } = await initializeWithToken(tokenResponse);
+ * const { db, userId, appId, helper } = await initializeWithToken(tokenResponse);
  *
- * // Ready to use Firestore!
- * const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
+ * // ✅ 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) {
@@ -344,14 +976,19 @@ async function initializeWithToken(tokenResponse) {
     // 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: tokenResponse.user_id,
-        appId: tokenResponse.app_id || '',
+        userId,
+        appId,
+        helper,
     };
 }
 
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, getFirebaseConfig, initializeWithToken };
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, FirestoreHelper, PATH_PATTERNS, PathBuilder, addDocWithMeta, getFirebaseConfig, getPublicDataDocPath, getPublicDataPath, getPublicReadDocPath, getPublicReadPath, getUserDataDocPath, getUserDataPath, initializeWithToken, updateDocWithMeta };
 //# sourceMappingURL=index.js.map