@seaverse/data-service-sdk 0.5.0 → 0.5.2

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
 
@@ -190,6 +237,20 @@ const app = initializeApp({
 
 const auth = getAuth(app);
 await signInWithCustomToken(auth, tokenResponse.custom_token);
+
+// ⚠️ IMPORTANT: Must specify database_id!
+const db = getFirestore(app, tokenResponse.database_id);
+```
+
+**🚨 CRITICAL: Always Specify database_id**
+
+When initializing Firestore, you MUST pass the `database_id` from the token response:
+
+```typescript
+// ✅ CORRECT - Specify database_id
+const db = getFirestore(app, tokenResponse.database_id);
+
+// ❌ WRONG - Will try to use "(default)" database which may not exist
 const db = getFirestore(app);
 ```
 

package/dist/browser.js

@@ -4251,8 +4251,9 @@ async function initializeWithToken(tokenResponse) {
     // Sign in with custom token
     const auth = getAuth(app);
     await signInWithCustomToken(auth, tokenResponse.custom_token);
-    // Get Firestore instance
-    const db = getFirestore(app);
+    // Get Firestore instance with correct database ID
+    // IMPORTANT: Must specify database_id, not just use default!
+    const db = getFirestore(app, tokenResponse.database_id);
     return {
         app,
         auth,