@seaverse/data-service-sdk 0.10.0 → 0.10.2

package/README.md

@@ -53,7 +53,7 @@ SeaVerse organizes your Firestore data into three permission levels:
 |-----------------|--------------|-------------|--------------|----------|
 | **publicRead** | `appData/{app_id}/publicRead/_data/{collection}/{docId}` | All authenticated users | Admin only | System configs, announcements, static content |
 | **publicData** | `appData/{app_id}/publicData/_data/{collection}/{docId}` | All authenticated users | All authenticated users | User posts, comments, shared content |
-| **userData** | `appData/{app_id}/userData/{user_id}/{collection}/{docId}` | Owner only | Owner only | User settings, private notes, personal data |
+| **userData** | `appData/{app_id}/userData/{user_id}/_data/{collection}/{docId}` | Owner only | Owner only | User settings, private notes, personal data |
 
 ### 🚨 CRITICAL: Firestore Path Rules (For LLM)
 
@@ -88,7 +88,7 @@ const postsRef = collection(db, `appData/${appId}/publicData/_data/posts`);
 await addDoc(postsRef, { ...data });  // Firestore adds document ID
 
 // User Private Data (owner only)
-const notesRef = collection(db, `appData/${appId}/userData/${userId}/notes`);
+const notesRef = collection(db, `appData/${appId}/userData/${userId}/_data/notes`);
 await addDoc(notesRef, { ...data });
 
 // Public Read-Only (everyone can read, admin can write)
@@ -97,9 +97,10 @@ await getDocs(configRef);
 ```
 
 **The pattern is always:**
-- `appData` → `{app_id}` → `{permission_layer}` → `_data` → `{collection}` → (auto-generated doc ID)
-- Collection: 5 segments (odd) ✅
-- Document: 6 segments (even) ✅
+- `appData` → `{app_id}` → `{permission_layer}` → (`{user_id}` for userData) → `_data` → `{collection}` → (auto-generated doc ID)
+- publicRead/publicData Collection: 5 segments (odd) ✅
+- userData Collection: 6 segments (even) ✅ (includes userId)
+- Document paths: add 1 more segment for docId
 
 ### Required Fields
 
@@ -257,17 +258,17 @@ collection(db, `apps/${appId}/users/${userId}/articles`)  // Not matching securi
 import { getPublicDataPath, getUserDataPath } from '@seaverse/data-service-sdk';
 
 // ✅ CORRECT - Guaranteed to match security rules
-collection(db, getPublicDataPath(appId, 'posts'))  // → appData/{appId}/publicData/posts
-collection(db, getUserDataPath(appId, userId, 'notes'))  // → appData/{appId}/userData/{userId}/notes
+collection(db, getPublicDataPath(appId, 'posts'))  // → appData/{appId}/publicData/_data/posts
+collection(db, getUserDataPath(appId, userId, 'notes'))  // → appData/{appId}/userData/{userId}/_data/notes
 ```
 
 ### Available Path Helpers
 
 ```typescript
 import {
-  getPublicReadPath,      // For read-only public data
-  getPublicDataPath,      // For public read/write data
-  getUserDataPath,        // For private user data
+  getPublicReadPath,      // Returns: appData/{appId}/publicRead/_data/{collection}
+  getPublicDataPath,      // Returns: appData/{appId}/publicData/_data/{collection}
+  getUserDataPath,        // Returns: appData/{appId}/userData/{userId}/_data/{collection}
   getPublicReadDocPath,   // For specific public document
   getPublicDataDocPath,   // For specific public data document
   getUserDataDocPath,     // For specific user document
@@ -324,7 +325,7 @@ const docPath = builder.publicData('posts').doc('post-123').build();
 
 // Build user data path
 const userPath = builder.userData(userId, 'notes').build();
-// Returns: 'appData/my-app/userData/user-123/notes'
+// Returns: 'appData/my-app/userData/user-123/_data/notes'
 ```
 
 ### Error Prevention
@@ -631,9 +632,31 @@ initializeWithToken(tokenResponse: FirestoreTokenResponse): Promise<{
   db: Firestore;
   userId: string;
   appId: string;
+  helper: FirestoreHelper;
 }>
 ```
 
+**⚠️ IMPORTANT: Safe for Multiple Calls**
+
+This function has been updated to safely handle multiple calls:
+- ✅ **Reuses existing Firebase app** if already initialized
+- ✅ **Re-authenticates with new token** for token refresh scenarios
+- ✅ **Handles errors gracefully** with automatic cleanup
+- ✅ **Validates app_id** before initialization
+
+**Common Use Cases:**
+```typescript
+// ✅ SAFE: First-time initialization
+const { helper } = await initializeWithToken(tokenResponse);
+
+// ✅ SAFE: Token refresh (reuses existing app)
+const newTokenResponse = await client.generateFirestoreToken({ ... });
+const { helper: newHelper } = await initializeWithToken(newTokenResponse);
+
+// ✅ SAFE: User re-login (reuses existing app)
+const { helper } = await initializeWithToken(newUserTokenResponse);
+```
+
 **Example:**
 
 ```typescript
@@ -642,7 +665,7 @@ import { initializeWithToken } from '@seaverse/data-service-sdk';
 const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app' });
 
 // One line to get everything!
-const { db, appId, userId } = await initializeWithToken(tokenResponse);
+const { db, appId, userId, helper } = await initializeWithToken(tokenResponse);
 
 // Ready to use Firestore
 await addDoc(collection(db, `appData/${appId}/publicData/_data/posts`), { ... });
@@ -653,6 +676,22 @@ await addDoc(collection(db, `appData/${appId}/publicData/_data/posts`), { ... })
 npm install firebase
 ```
 
+**Error Handling:**
+
+```typescript
+try {
+  const { helper } = await initializeWithToken(tokenResponse);
+} catch (error) {
+  if (error.message.includes('app_id is required')) {
+    // Handle missing app_id in token response
+  } else if (error.message.includes('Firebase SDK not found')) {
+    // Handle missing Firebase installation
+  } else if (error.message.includes('Failed to initialize Firebase')) {
+    // Handle authentication or initialization errors
+  }
+}
+```
+
 ## Common Use Cases
 
 ### Use Case 1: Public Forum with Comments
@@ -678,7 +717,7 @@ const comments = await getDocs(
 
 ```typescript
 // Only the user can write to their own settings
-await setDoc(doc(db, `appData/${appId}/userData/${userId}/settings/preferences`), {
+await setDoc(doc(db, `appData/${appId}/userData/${userId}/_data/settings/preferences`), {
   _appId: appId,
   _createdAt: serverTimestamp(),
   _createdBy: userId,
@@ -689,7 +728,7 @@ await setDoc(doc(db, `appData/${appId}/userData/${userId}/settings/preferences`)
 
 // Only the user can read their own settings
 const settings = await getDoc(
-  doc(db, `appData/${appId}/userData/${userId}/settings/preferences`)
+  doc(db, `appData/${appId}/userData/${userId}/_data/settings/preferences`)
 );
 ```
 
@@ -730,7 +769,7 @@ const snapshot = await getDocs(userPosts);
 ✅ **Authenticated Users:**
 - Read `publicRead` data
 - Read and write `publicData` (all users' data)
-- Read and write their own `userData/{userId}` only
+- Read and write their own `userData/{userId}/_data/` only
 - Update/delete documents where `_createdBy == userId`
 
 ✅ **Guest Users:**
@@ -790,6 +829,264 @@ import type {
 } from '@seaverse/data-service-sdk';
 ```
 
+## Production Usage Recommendations
+
+### Token Expiration Management
+
+Firestore tokens expire after 1 hour (3600 seconds). For production applications, you should implement token refresh logic:
+
+```typescript
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
+
+class FirestoreManager {
+  private tokenExpiryTime: number | null = null;
+  private dataClient = new DataServiceClient();
+  private userToken: string | null = null;
+  private appId: string;
+
+  constructor(appId: string) {
+    this.appId = appId;
+  }
+
+  async initialize(userToken: string) {
+    this.userToken = userToken;
+
+    // Generate Firestore token
+    const tokenResponse = await this.dataClient.generateFirestoreToken({
+      token: userToken,
+      app_id: this.appId
+    });
+
+    // Initialize Firebase (safe to call multiple times)
+    const result = await initializeWithToken(tokenResponse);
+
+    // Track token expiry (expires_in is in seconds)
+    this.tokenExpiryTime = Date.now() + (tokenResponse.expires_in * 1000);
+
+    return result;
+  }
+
+  isTokenExpiringSoon(): boolean {
+    if (!this.tokenExpiryTime) return true;
+
+    // Check if token expires within 5 minutes
+    const fiveMinutes = 5 * 60 * 1000;
+    return Date.now() + fiveMinutes >= this.tokenExpiryTime;
+  }
+
+  async refreshTokenIfNeeded() {
+    if (this.isTokenExpiringSoon() && this.userToken) {
+      console.log('Token expiring soon, refreshing...');
+      return await this.initialize(this.userToken);
+    }
+  }
+}
+
+// Usage
+const manager = new FirestoreManager('my-app-123');
+
+// Initialize
+const { helper } = await manager.initialize(userJwtToken);
+
+// Before making Firestore operations, check token
+await manager.refreshTokenIfNeeded();
+await helper.addToPublicData('posts', { title: 'My Post' });
+```
+
+### Advanced: Singleton Pattern with React
+
+For React applications, you can create a singleton manager with hooks:
+
+```typescript
+// firestore-manager.ts
+class FirestoreManager {
+  private static instance: FirestoreManager | null = null;
+  private helper: FirestoreHelper | null = null;
+  private db: Firestore | null = null;
+  private appId: string | null = null;
+  private userId: string | null = null;
+  private tokenExpiryTime: number | null = null;
+
+  static getInstance(): FirestoreManager {
+    if (!FirestoreManager.instance) {
+      FirestoreManager.instance = new FirestoreManager();
+    }
+    return FirestoreManager.instance;
+  }
+
+  async initialize(tokenResponse: FirestoreTokenResponse) {
+    // Always call initializeWithToken - it's safe for multiple calls
+    const result = await initializeWithToken(tokenResponse);
+
+    this.db = result.db;
+    this.appId = result.appId;
+    this.userId = result.userId;
+    this.helper = result.helper;
+    this.tokenExpiryTime = Date.now() + (tokenResponse.expires_in * 1000);
+
+    return result;
+  }
+
+  getHelper(): FirestoreHelper | null {
+    return this.helper;
+  }
+
+  isTokenExpiringSoon(): boolean {
+    if (!this.tokenExpiryTime) return true;
+    const fiveMinutes = 5 * 60 * 1000;
+    return Date.now() + fiveMinutes >= this.tokenExpiryTime;
+  }
+
+  reset() {
+    this.db = null;
+    this.appId = null;
+    this.userId = null;
+    this.helper = null;
+    this.tokenExpiryTime = null;
+  }
+}
+
+export default FirestoreManager;
+
+// useFirestore.ts (React Hook)
+import { useState, useEffect } from 'react';
+import { DataServiceClient } from '@seaverse/data-service-sdk';
+import FirestoreManager from './firestore-manager';
+
+export function useFirestore(userToken: string, appId: string) {
+  const [helper, setHelper] = useState<FirestoreHelper | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    async function init() {
+      try {
+        const dataClient = new DataServiceClient();
+        const tokenResponse = await dataClient.generateFirestoreToken({
+          token: userToken,
+          app_id: appId
+        });
+
+        const manager = FirestoreManager.getInstance();
+        const { helper } = await manager.initialize(tokenResponse);
+
+        if (mounted) {
+          setHelper(helper);
+          setLoading(false);
+        }
+      } catch (err) {
+        if (mounted) {
+          setError(err as Error);
+          setLoading(false);
+        }
+      }
+    }
+
+    init();
+
+    return () => {
+      mounted = false;
+    };
+  }, [userToken, appId]);
+
+  return { helper, loading, error };
+}
+
+// Usage in component
+function MyComponent() {
+  const { helper, loading, error } = useFirestore(userToken, 'my-app-123');
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  const handleAddPost = async () => {
+    await helper.addToPublicData('posts', {
+      title: 'My Post',
+      content: 'Hello World'
+    });
+  };
+
+  return <button onClick={handleAddPost}>Add Post</button>;
+}
+```
+
+### Background Token Refresh
+
+For long-running applications, set up automatic background token refresh:
+
+```typescript
+class FirestoreManager {
+  private refreshTimer: NodeJS.Timeout | null = null;
+
+  async initialize(userToken: string, appId: string) {
+    const dataClient = new DataServiceClient();
+    const tokenResponse = await dataClient.generateFirestoreToken({
+      token: userToken,
+      app_id: appId
+    });
+
+    const result = await initializeWithToken(tokenResponse);
+
+    // Schedule token refresh 5 minutes before expiry
+    const refreshIn = (tokenResponse.expires_in - 5 * 60) * 1000;
+    this.scheduleRefresh(userToken, appId, refreshIn);
+
+    return result;
+  }
+
+  private scheduleRefresh(userToken: string, appId: string, delay: number) {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+    }
+
+    this.refreshTimer = setTimeout(async () => {
+      console.log('Auto-refreshing Firestore token...');
+      try {
+        await this.initialize(userToken, appId);
+      } catch (error) {
+        console.error('Failed to refresh token:', error);
+      }
+    }, delay);
+  }
+
+  cleanup() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+}
+```
+
+### Error Recovery
+
+Implement proper error recovery for network failures:
+
+```typescript
+async function initializeWithRetry(
+  tokenResponse: FirestoreTokenResponse,
+  maxRetries = 3
+) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await initializeWithToken(tokenResponse);
+    } catch (error) {
+      console.error(`Initialization attempt ${i + 1} failed:`, error);
+
+      if (i === maxRetries - 1) {
+        throw error; // Last attempt failed
+      }
+
+      // Wait before retry (exponential backoff)
+      const delay = Math.pow(2, i) * 1000;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}
+```
+
 ## Best Practices for LLM
 
 When using this SDK with LLM-generated code:
@@ -933,7 +1230,7 @@ async function completeExample() {
 
   // 7. Save user preferences (private)
   await addDoc(
-    collection(db, `appData/${appId}/userData/${userId}/preferences`),
+    collection(db, `appData/${appId}/userData/${userId}/_data/preferences`),
     {
       _appId: appId,
       _createdAt: serverTimestamp(),

package/dist/browser.js

@@ -3941,9 +3941,9 @@ const ENDPOINTS = {
  * ---------------------------
  * Your Firestore data is organized in three permission levels:
  *
- * 1. publicRead/   - System configs, announcements (Read: Everyone, Write: Admin only)
- * 2. publicData/   - User posts, shared content (Read: Everyone, Write: Everyone)
- * 3. userData/{userId}/ - Private user data (Read/Write: Owner only)
+ * 1. publicRead/_data/   - System configs, announcements (Read: Everyone, Write: Admin only)
+ * 2. publicData/_data/   - User posts, shared content (Read: Everyone, Write: Everyone)
+ * 3. userData/{userId}/_data/ - Private user data (Read/Write: Owner only)
  *
  * QUICK START FOR LLM:
  * -------------------
@@ -3995,7 +3995,7 @@ const ENDPOINTS = {
  * const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
  *
  * // Write to userData (only owner can write)
- * await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
+ * await addDoc(collection(db, `appData/${appId}/userData/${userId}/_data/notes`), {
  *   _appId: appId,              // REQUIRED
  *   _createdAt: serverTimestamp(), // REQUIRED
  *   _createdBy: userId,         // REQUIRED
@@ -4248,7 +4248,7 @@ function getPublicDataPath(appId, collectionName) {
  * ```typescript
  * // Write private user notes
  * const path = getUserDataPath('my-app', 'user-123', 'notes');
- * // Returns: 'appData/my-app/userData/user-123/notes'
+ * // Returns: 'appData/my-app/userData/user-123/_data/notes'
  *
  * await addDoc(collection(db, path), {
  *   _appId: appId,
@@ -4262,7 +4262,7 @@ function getUserDataPath(appId, userId, collectionName) {
     validateSegment('appId', appId);
     validateSegment('userId', userId);
     validateSegment('collectionName', collectionName);
-    return `appData/${appId}/userData/${userId}/${collectionName}`;
+    return `appData/${appId}/userData/${userId}/_data/${collectionName}`;
 }
 /**
  * Generate path for a specific document in publicRead
@@ -4320,7 +4320,7 @@ function getPublicDataDocPath(appId, collectionName, docId) {
  * @example
  * ```typescript
  * const path = getUserDataDocPath('my-app', 'user-123', 'notes', 'note-456');
- * // Returns: 'appData/my-app/userData/user-123/notes/note-456'
+ * // Returns: 'appData/my-app/userData/user-123/_data/notes/note-456'
  *
  * const docSnap = await getDoc(doc(db, path));
  * ```
@@ -4330,7 +4330,7 @@ function getUserDataDocPath(appId, userId, collectionName, docId) {
     validateSegment('userId', userId);
     validateSegment('collectionName', collectionName);
     validateSegment('docId', docId);
-    return `appData/${appId}/userData/${userId}/${collectionName}/${docId}`;
+    return `appData/${appId}/userData/${userId}/_data/${collectionName}/${docId}`;
 }
 /**
  * Validate a path segment to ensure it doesn't contain invalid characters
@@ -4395,7 +4395,7 @@ class PathBuilder {
     userData(userId, collectionName) {
         validateSegment('userId', userId);
         validateSegment('collectionName', collectionName);
-        this.segments.push('userData', userId, collectionName);
+        this.segments.push('userData', userId, '_data', collectionName);
         return this;
     }
     /**
@@ -5014,7 +5014,9 @@ class FirestoreHelper {
         }
         else {
             // Filter out soft-deleted documents
-            const q = query(colRef, where('_deleted', '==', false));
+            // Use '!=' to include documents without _deleted field (new documents)
+            // This will return documents where _deleted is missing, null, undefined, or false
+            const q = query(colRef, where('_deleted', '!=', true));
             return getDocs(q);
         }
     }
@@ -5147,7 +5149,7 @@ function getFirebaseConfig(tokenResponse) {
  *
  * This is a convenience function that automatically:
  * 1. Creates Firebase config from token response
- * 2. Initializes Firebase app
+ * 2. Initializes Firebase app (or reuses existing one)
  * 3. Signs in with the custom token
  * 4. Creates FirestoreHelper for LLM-friendly operations
  * 5. Returns authenticated Firebase instances
@@ -5155,11 +5157,20 @@ function getFirebaseConfig(tokenResponse) {
  * IMPORTANT: This function requires Firebase SDK to be installed separately:
  * npm install firebase
  *
+ * ⚠️ IMPORTANT: This function can be called multiple times safely. It will:
+ * - Reuse existing Firebase app if already initialized
+ * - Re-authenticate with new token if needed
+ * - Handle token refresh scenarios
+ *
  * 🎯 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
  *
+ * @throws {Error} If app_id is missing from token response
+ * @throws {Error} If Firebase SDK is not installed
+ * @throws {Error} If authentication fails
+ *
  * @example
  * ```typescript
  * import { initializeWithToken } from '@seaverse/data-service-sdk';
@@ -5178,17 +5189,25 @@ function getFirebaseConfig(tokenResponse) {
  * ```
  */
 async function initializeWithToken(tokenResponse) {
+    // ✅ FIX #3: Validate appId FIRST before any initialization
+    const appId = tokenResponse.app_id;
+    if (!appId) {
+        throw new Error('app_id is required in token response. ' +
+            'Make sure your token response includes a valid app_id field.');
+    }
     // Check if Firebase SDK is available
     let initializeApp;
     let getAuth;
     let signInWithCustomToken;
     let getFirestore;
+    let getApps;
     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;
+        getApps = firebaseApp.getApps;
         getAuth = firebaseAuth.getAuth;
         signInWithCustomToken = firebaseAuth.signInWithCustomToken;
         getFirestore = firebaseFirestore.getFirestore;
@@ -5197,17 +5216,57 @@ async function initializeWithToken(tokenResponse) {
         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);
+    // ✅ FIX #1: Check if Firebase app already exists
+    const existingApps = getApps();
+    const existingApp = existingApps.find((app) => app.name === '[DEFAULT]');
+    let app;
+    let auth;
+    let db;
+    if (existingApp) {
+        // ✅ FIX #2: Reuse existing app instead of creating new one
+        console.log('[SeaVerse SDK] Reusing existing Firebase app');
+        app = existingApp;
+        auth = getAuth(app);
+        db = getFirestore(app, tokenResponse.database_id);
+        // ✅ FIX #4: Re-authenticate with new token (for token refresh scenarios)
+        try {
+            await signInWithCustomToken(auth, tokenResponse.custom_token);
+            console.log('[SeaVerse SDK] Re-authenticated with new token');
+        }
+        catch (error) {
+            // If already signed in with same token, ignore error
+            // Only throw if it's a real authentication failure
+            if (error?.code !== 'auth/invalid-credential' && error?.code !== 'auth/network-request-failed') {
+                console.warn('[SeaVerse SDK] Re-authentication warning:', error?.message || error);
+            }
+        }
+    }
+    else {
+        // ✅ FIX #4: First-time initialization with proper error handling
+        console.log('[SeaVerse SDK] Initializing new Firebase app');
+        try {
+            const config = getFirebaseConfig(tokenResponse);
+            app = initializeApp(config);
+            auth = getAuth(app);
+            await signInWithCustomToken(auth, tokenResponse.custom_token);
+            // IMPORTANT: Must specify database_id, not just use default!
+            db = getFirestore(app, tokenResponse.database_id);
+        }
+        catch (error) {
+            // ✅ FIX #4: Cleanup on failure to prevent half-initialized state
+            if (app) {
+                try {
+                    await app.delete();
+                    console.log('[SeaVerse SDK] Cleaned up failed Firebase app initialization');
+                }
+                catch (cleanupError) {
+                    console.warn('[SeaVerse SDK] Failed to cleanup app:', cleanupError);
+                }
+            }
+            throw new Error(`Failed to initialize Firebase: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     const userId = tokenResponse.user_id;
-    const appId = tokenResponse.app_id || '';
     // Create LLM-friendly helper
     const helper = new FirestoreHelper(db, appId, userId);
     return {