@seaverse/data-service-sdk 0.4.0 → 0.5.1

package/README.md

@@ -17,9 +17,56 @@ SeaVerse organizes your Firestore data into three permission levels:
 
 | Permission Level | Path Pattern | Read Access | Write Access | Use Case |
 |-----------------|--------------|-------------|--------------|----------|
-| **publicRead** | `appData/{app_id}/publicRead/...` | All authenticated users | Admin only | System configs, announcements, static content |
-| **publicData** | `appData/{app_id}/publicData/...` | All authenticated users | All authenticated users | User posts, comments, shared content |
-| **userData** | `appData/{app_id}/userData/{user_id}/...` | Owner only | Owner only | User settings, private notes, personal data |
+| **publicRead** | `appData/{app_id}/publicRead/{collection}/{docId}` | All authenticated users | Admin only | System configs, announcements, static content |
+| **publicData** | `appData/{app_id}/publicData/{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 |
+
+### 🚨 CRITICAL: Firestore Path Rules (For LLM)
+
+**Firestore path segments MUST follow these rules:**
+
+1. **Collection paths = ODD number of segments** (1, 3, 5, 7...)
+   - Example: `appData/my-app/publicData/posts` (4 segments) ❌ WRONG!
+   - Correct: Use collection() function, Firestore handles this automatically
+
+2. **Document paths = EVEN number of segments** (2, 4, 6, 8...)
+   - Example: `appData/my-app/publicData/posts/doc123` (5 segments) ✅ CORRECT!
+
+3. **How to use correctly:**
+
+```typescript
+// ✅ CORRECT - Using collection() for collection paths
+collection(db, `appData/${appId}/publicData/posts`)  // Firestore handles this as a collection
+
+// ✅ CORRECT - Using doc() for document paths
+doc(db, `appData/${appId}/publicData/posts/doc123`)  // 5 segments (odd) = document
+
+// ❌ WRONG - Manually counting segments
+// Don't worry about counting! Use Firebase functions:
+// - collection() for collections
+// - doc() for documents
+// - addDoc() automatically adds document ID
+```
+
+**Path Structure Examples:**
+
+```typescript
+// Public Data (everyone can read/write)
+const postsRef = collection(db, `appData/${appId}/publicData/posts`);
+await addDoc(postsRef, { ...data });  // Firestore adds document ID
+
+// User Private Data (owner only)
+const notesRef = collection(db, `appData/${appId}/userData/${userId}/notes`);
+await addDoc(notesRef, { ...data });
+
+// Public Read-Only (everyone can read, admin can write)
+const configRef = collection(db, `appData/${appId}/publicRead/config`);
+await getDocs(configRef);
+```
+
+**The pattern is always:**
+- `appData` → `{app_id}` → `{permission_layer}` → `{collection}` → (auto-generated doc ID)
+- This gives you 5 segments total = document path ✅
 
 ### Required Fields
 
@@ -85,16 +132,14 @@ import { DataServiceClient } from '@seaverse/data-service-sdk';
 
 ## Quick Start
 
-### For Authenticated Users
+### 🚀 Easiest Way (Recommended - Auto Firebase Setup)
 
 ```typescript
-import { DataServiceClient } from '@seaverse/data-service-sdk';
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
 import { AuthClient } from '@seaverse/auth-sdk';
-import { initializeApp } from 'firebase/app';
-import { getAuth, signInWithCustomToken } from 'firebase/auth';
-import { getFirestore, collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
+import { collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
 
-// Step 1: Login user with Auth SDK
+// Step 1: Login user
 const authClient = new AuthClient({ appId: 'my-app-123' });
 const loginResponse = await authClient.loginWithEmail({
   email: 'user@example.com',
@@ -103,20 +148,15 @@ const loginResponse = await authClient.loginWithEmail({
 
 // Step 2: Get Firestore token
 const dataClient = new DataServiceClient();
-const firestoreToken = await dataClient.generateFirestoreToken({
-  token: loginResponse.token,  // JWT from auth
+const tokenResponse = await dataClient.generateFirestoreToken({
+  token: loginResponse.token,
   app_id: 'my-app-123'
 });
 
-// Step 3: Initialize Firebase
-const app = initializeApp({ projectId: firestoreToken.project_id });
-const auth = getAuth(app);
-await signInWithCustomToken(auth, firestoreToken.custom_token);
-const db = getFirestore(app);
+// Step 3: Auto-initialize Firebase (ONE LINE!)
+const { db, appId, userId } = await initializeWithToken(tokenResponse);
 
-// Step 4: Use Firestore with proper paths
-const appId = firestoreToken.app_id;
-const userId = firestoreToken.user_id;
+// Step 4: Use Firestore directly!
 
 // Write to publicData (everyone can write)
 await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
@@ -143,31 +183,26 @@ await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
 });
 ```
 
-### For Guest Users
+### 👤 For Guest Users (Even Simpler!)
 
 ```typescript
-import { DataServiceClient } from '@seaverse/data-service-sdk';
-import { initializeApp } from 'firebase/app';
-import { getAuth, signInWithCustomToken } from 'firebase/auth';
-import { getFirestore, collection, addDoc, serverTimestamp } from 'firebase/firestore';
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
+import { collection, addDoc, serverTimestamp } from 'firebase/firestore';
 
 // Step 1: Get guest token (no authentication needed!)
 const dataClient = new DataServiceClient();
-const guestToken = await dataClient.generateGuestFirestoreToken({
+const tokenResponse = await dataClient.generateGuestFirestoreToken({
   app_id: 'my-app-123'
 });
 
-// Step 2: Initialize Firebase
-const app = initializeApp({ projectId: guestToken.project_id });
-const auth = getAuth(app);
-await signInWithCustomToken(auth, guestToken.custom_token);
-const db = getFirestore(app);
+// Step 2: Auto-initialize Firebase (ONE LINE!)
+const { db, appId, userId } = await initializeWithToken(tokenResponse);
 
 // Step 3: Guest can write to publicData
-await addDoc(collection(db, `appData/${guestToken.app_id}/publicData/comments`), {
-  _appId: guestToken.app_id,
+await addDoc(collection(db, `appData/${appId}/publicData/comments`), {
+  _appId: appId,
   _createdAt: serverTimestamp(),
-  _createdBy: guestToken.user_id,  // Guest user ID (e.g., 'guest-abc123')
+  _createdBy: userId,  // Guest user ID (e.g., 'guest-abc123')
   comment: 'Great app!',
   rating: 5
 });
@@ -175,6 +210,36 @@ await addDoc(collection(db, `appData/${guestToken.app_id}/publicData/comments`),
 // Note: Guests CANNOT access userData
 ```
 
+### 🔧 Manual Way (If you need more control)
+
+If you prefer to initialize Firebase manually:
+
+```typescript
+import { DataServiceClient, getFirebaseConfig } from '@seaverse/data-service-sdk';
+import { initializeApp } from 'firebase/app';
+import { getAuth, signInWithCustomToken } from 'firebase/auth';
+import { getFirestore } from 'firebase/firestore';
+
+const dataClient = new DataServiceClient();
+const tokenResponse = await dataClient.generateGuestFirestoreToken({
+  app_id: 'my-app-123'
+});
+
+// Option 1: Use getFirebaseConfig helper
+const firebaseConfig = getFirebaseConfig(tokenResponse);
+const app = initializeApp(firebaseConfig);
+
+// Option 2: Manual config
+const app = initializeApp({
+  apiKey: tokenResponse.web_api_key,  // ✅ Provided automatically!
+  projectId: tokenResponse.project_id
+});
+
+const auth = getAuth(app);
+await signInWithCustomToken(auth, tokenResponse.custom_token);
+const db = getFirestore(app);
+```
+
 ## API Reference
 
 ### DataServiceClient
@@ -232,11 +297,12 @@ interface GenerateFirestoreTokenRequest {
 ```typescript
 interface FirestoreTokenResponse {
   custom_token: string;     // Firebase Custom Token - use with signInWithCustomToken()
+  web_api_key: string;      // Firebase Web API Key - use with initializeApp()
   project_id: string;       // Firebase Project ID for initializeApp()
   database_id: string;      // Firestore Database ID
   app_id?: string;          // Application ID (use in Firestore paths)
   user_id: string;          // User ID (use in Firestore paths)
-  role?: string;            // User role ('guest', 'user', 'admin')
+  user_type: string;        // User type ('guest', 'user', 'admin', 'appadmin')
   expires_in: number;       // Token expiration in seconds (typically 3600)
 }
 ```
@@ -286,7 +352,63 @@ const guestToken = await client.generateGuestFirestoreToken({
 
 console.log('Guest Custom Token:', guestToken.custom_token);
 console.log('Guest User ID:', guestToken.user_id);
-console.log('Role:', guestToken.role); // 'guest'
+console.log('User Type:', guestToken.user_type); // 'guest'
+```
+
+### Helper Functions
+
+#### getFirebaseConfig
+
+Extract Firebase configuration from token response.
+
+```typescript
+getFirebaseConfig(tokenResponse: FirestoreTokenResponse): FirebaseConfig
+```
+
+**Example:**
+
+```typescript
+import { getFirebaseConfig } from '@seaverse/data-service-sdk';
+import { initializeApp } from 'firebase/app';
+
+const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app' });
+const firebaseConfig = getFirebaseConfig(tokenResponse);
+// Returns: { apiKey: '...', projectId: '...' }
+
+const app = initializeApp(firebaseConfig);
+```
+
+#### initializeWithToken
+
+Automatically initialize Firebase and sign in with token (one-line setup).
+
+```typescript
+initializeWithToken(tokenResponse: FirestoreTokenResponse): Promise<{
+  app: FirebaseApp;
+  auth: Auth;
+  db: Firestore;
+  userId: string;
+  appId: string;
+}>
+```
+
+**Example:**
+
+```typescript
+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);
+
+// Ready to use Firestore
+await addDoc(collection(db, `appData/${appId}/publicData/posts`), { ... });
+```
+
+**Note:** This function requires Firebase SDK to be installed separately:
+```bash
+npm install firebase
 ```
 
 ## Common Use Cases

package/dist/browser.js

@@ -4173,5 +4173,94 @@ class DataServiceClient {
     }
 }
 
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS };
+/**
+ * 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
+    const db = getFirestore(app);
+    return {
+        app,
+        auth,
+        db,
+        userId: tokenResponse.user_id,
+        appId: tokenResponse.app_id || '',
+    };
+}
+
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, getFirebaseConfig, initializeWithToken };
 //# sourceMappingURL=browser.js.map