@seaverse/data-service-sdk 0.10.1 → 0.11.0

package/README.md

@@ -16,6 +16,7 @@ SeaVerse Data Service SDK for accessing Firestore with secure token management a
 |---------------------|---------------|--------------|
 | **Write Public Data** | `helper.addToPublicData()` | `await helper.addToPublicData('posts', {title: 'Hello'})` |
 | **Read Public Data** | `helper.getPublicData()` | `const posts = await helper.getPublicData('posts')` |
+| **Read with Pagination** | `helper.getPublicData()` | `const posts = await helper.getPublicData('posts', false, {limit: 10})` |
 | **Write Private Data** | `helper.addToUserData()` | `await helper.addToUserData('notes', {text: 'Secret'})` |
 | **Read Private Data** | `helper.getUserData()` | `const notes = await helper.getUserData('notes')` |
 
@@ -378,6 +379,16 @@ posts.forEach(doc => {
   console.log(doc.id, doc.data());
 });
 
+// ✅ Pagination support: Get first 10 posts
+const firstPage = await helper.getPublicData('posts', false, { limit: 10 });
+
+// Get next 10 posts (start after last document)
+const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+const nextPage = await helper.getPublicData('posts', false, {
+  limit: 10,
+  startAfter: lastDoc
+});
+
 // ✅ LLM-FRIENDLY: Write to userData (private) - auto-isolated!
 await helper.addToUserData('notes', {
   title: 'Private Note',
@@ -632,9 +643,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 +676,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 +687,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
@@ -724,6 +773,42 @@ const userPosts = query(
 const snapshot = await getDocs(userPosts);
 ```
 
+### Use Case 5: Pagination (New!)
+
+```typescript
+// ✅ Simple pagination with FirestoreHelper
+
+// Get first page (10 posts)
+const firstPage = await helper.getPublicData('posts', false, { limit: 10 });
+
+console.log(`Fetched ${firstPage.docs.length} posts`);
+firstPage.forEach(doc => {
+  console.log('Post:', doc.id, doc.data());
+});
+
+// Check if there are more pages
+if (firstPage.docs.length === 10) {
+  // Get next page (start after last document)
+  const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+  const nextPage = await helper.getPublicData('posts', false, {
+    limit: 10,
+    startAfter: lastDoc
+  });
+
+  console.log(`Next page: ${nextPage.docs.length} posts`);
+}
+
+// Also works with getUserData and getPublicRead
+const userNotes = await helper.getUserData('notes', false, { limit: 20 });
+const configs = await helper.getPublicRead('config', { limit: 5 });
+```
+
+**Pagination Best Practices:**
+- Use a consistent `limit` value across pages for predictable UX
+- Store the last document from the current page to fetch the next page
+- Check if `docs.length` equals your limit to determine if there might be more pages
+- For infinite scroll, keep appending results; for traditional pagination, replace the view
+
 ## Permission Examples
 
 ### What Users CAN Do
@@ -791,6 +876,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:
@@ -1020,4 +1363,4 @@ Here's a complete example for using the SDK directly in the browser without any
 ## Related SDKs
 
 - [@seaverse/auth-sdk](../auth-sdk) - User authentication and account management
-- [@seaverse/payment-sdk](../payment-sdk) - Payment processing integration
+- [@seaverse/assets-sdk](../assets-sdk) - Assets and payment processing integration

package/dist/browser.js

@@ -4782,6 +4782,7 @@ class FirestoreHelper {
      *
      * @param collectionName - Collection name
      * @param includeDeleted - Include soft-deleted documents (default: false)
+     * @param options - Pagination options (limit and startAfter)
      * @returns QuerySnapshot with documents
      *
      * @example
@@ -4794,11 +4795,21 @@ class FirestoreHelper {
      *
      * // Include deleted posts (admin use case)
      * const allPosts = await helper.getPublicData('posts', true);
+     *
+     * // Pagination: Get first 10 posts
+     * const firstPage = await helper.getPublicData('posts', false, { limit: 10 });
+     *
+     * // Get next 10 posts (start after last document)
+     * const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+     * const nextPage = await helper.getPublicData('posts', false, {
+     *   limit: 10,
+     *   startAfter: lastDoc
+     * });
      * ```
      */
-    async getPublicData(collectionName, includeDeleted = false) {
+    async getPublicData(collectionName, includeDeleted = false, options) {
         const path = getPublicDataPath(this.appId, collectionName);
-        return this.getDocs(path, includeDeleted);
+        return this.getDocs(path, includeDeleted, options);
     }
     /**
      * Get all documents from userData collection (user's private data)
@@ -4807,6 +4818,7 @@ class FirestoreHelper {
      *
      * @param collectionName - Collection name
      * @param includeDeleted - Include soft-deleted documents (default: false)
+     * @param options - Pagination options (limit and startAfter)
      * @returns QuerySnapshot with documents
      *
      * @example
@@ -4815,26 +4827,45 @@ class FirestoreHelper {
      * snapshot.forEach(doc => {
      *   console.log('My note:', doc.data());
      * });
+     *
+     * // Pagination: Get first 20 notes
+     * const firstPage = await helper.getUserData('notes', false, { limit: 20 });
+     *
+     * // Get next page
+     * const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+     * const nextPage = await helper.getUserData('notes', false, {
+     *   limit: 20,
+     *   startAfter: lastDoc
+     * });
      * ```
      */
-    async getUserData(collectionName, includeDeleted = false) {
+    async getUserData(collectionName, includeDeleted = false, options) {
         const path = getUserDataPath(this.appId, this.userId, collectionName);
-        return this.getDocs(path, includeDeleted);
+        return this.getDocs(path, includeDeleted, options);
     }
     /**
      * Get all documents from publicRead collection (read-only for users)
      *
      * @param collectionName - Collection name
+     * @param options - Pagination options (limit and startAfter)
      * @returns QuerySnapshot with documents
      *
      * @example
      * ```typescript
      * const configs = await helper.getPublicRead('config');
+     *
+     * // Pagination
+     * const firstPage = await helper.getPublicRead('config', { limit: 10 });
+     * const lastDoc = firstPage.docs[firstPage.docs.length - 1];
+     * const nextPage = await helper.getPublicRead('config', {
+     *   limit: 10,
+     *   startAfter: lastDoc
+     * });
      * ```
      */
-    async getPublicRead(collectionName) {
+    async getPublicRead(collectionName, options) {
         const path = getPublicReadPath(this.appId, collectionName);
-        return this.getDocs(path);
+        return this.getDocs(path, false, options);
     }
     /**
      * Get collection reference for publicData
@@ -5003,22 +5034,36 @@ class FirestoreHelper {
     }
     /**
      * Internal: Get all documents from collection
-     * Optionally filter out soft-deleted documents
+     * Optionally filter out soft-deleted documents and support pagination
      */
-    async getDocs(collectionPath, includeDeleted = false) {
-        const { getDocs, collection, query, where } = await this.loadFirestore();
+    async getDocs(collectionPath, includeDeleted = false, options) {
+        const { getDocs, collection, query, where, limit, startAfter } = await this.loadFirestore();
         const colRef = collection(this.db, collectionPath);
-        if (includeDeleted) {
-            // Return all documents (including soft-deleted)
-            return getDocs(colRef);
-        }
-        else {
+        // Build query constraints
+        const constraints = [];
+        // Add soft-delete filter if needed
+        if (!includeDeleted) {
             // Filter out soft-deleted documents
             // 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));
+            constraints.push(where('_deleted', '!=', true));
+        }
+        // Add pagination constraints if provided
+        if (options?.limit) {
+            constraints.push(limit(options.limit));
+        }
+        if (options?.startAfter) {
+            constraints.push(startAfter(options.startAfter));
+        }
+        // Execute query
+        if (constraints.length > 0) {
+            const q = query(colRef, ...constraints);
             return getDocs(q);
         }
+        else {
+            // No constraints, return all documents
+            return getDocs(colRef);
+        }
     }
     /**
      * Internal: Get collection reference
@@ -5047,7 +5092,8 @@ class FirestoreHelper {
             query: firestore.query,
             where: firestore.where,
             orderBy: firestore.orderBy,
-            limit: firestore.limit
+            limit: firestore.limit,
+            startAfter: firestore.startAfter
         };
     }
 }
@@ -5149,7 +5195,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 +5203,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 +5235,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 +5262,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 {