@seaverse/data-service-sdk 0.10.1 → 0.10.2

package/README.md

@@ -632,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
@@ -643,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`), { ... });
@@ -654,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
@@ -791,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:

package/dist/browser.js

@@ -5149,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
@@ -5157,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';
@@ -5180,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;
@@ -5199,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 {