@seaverse/data-service-sdk 0.7.0 → 0.9.0

package/README.md

@@ -2,17 +2,36 @@
 
 SeaVerse Data Service SDK for accessing Firestore with secure token management and three-tier permission model.
 
-## 🤖 For LLM Users
+---
 
-**👉 Want the simplest way to use this SDK? Check out the [LLM Quick Start Guide](./LLM-QUICK-START.md)**
+## 🤖 **For LLM: START HERE!**
 
-The Quick Start guide shows you the **recommended LLM-friendly API** that automatically handles:
-- ✅ Required fields (`_appId`, `_createdAt`, `_createdBy`)
-- ✅ Correct Firestore paths
-- ✅ Server timestamps
-- ✅ Single import source
+### 🚀 5-Minute Quick Start
 
-**Most common LLM mistakes prevented!**
+**👉 Simplest Way**: Check **[LLM-FIRST.md](./LLM-FIRST.md)** - Complete HTML page examples (copy & paste ready)
+
+**⚡ Core API Quick Reference** (Only 4 methods to remember):
+
+| What You Want to Do | Use Which API | Code Example |
+|---------------------|---------------|--------------|
+| **Write Public Data** | `helper.addToPublicData()` | `await helper.addToPublicData('posts', {title: 'Hello'})` |
+| **Read Public Data** | `helper.getPublicData()` | `const posts = await helper.getPublicData('posts')` |
+| **Write Private Data** | `helper.addToUserData()` | `await helper.addToUserData('notes', {text: 'Secret'})` |
+| **Read Private Data** | `helper.getUserData()` | `const notes = await helper.getUserData('notes')` |
+
+**✨ Key Benefits**:
+- ✅ `helper` automatically handles required fields (`_appId`, `_createdAt`, `_createdBy`)
+- ✅ Automatically uses correct Firestore paths
+- ✅ Automatically uses server timestamps
+- ✅ Single import source (no need to import from multiple packages)
+
+**🎯 Quick Links**:
+- **[LLM-FIRST.md](./LLM-FIRST.md)** - Complete HTML examples (todo list, message board)
+- **[LLM-QUICK-START.md](./LLM-QUICK-START.md)** - Code snippets and common mistakes
+
+---
+
+## 📖 For Developers
 
 ## Features
 
@@ -30,8 +49,8 @@ SeaVerse organizes your Firestore data into three permission levels:
 
 | Permission Level | Path Pattern | Read Access | Write Access | Use Case |
 |-----------------|--------------|-------------|--------------|----------|
-| **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 |
+| **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 |
 
 ### 🚨 CRITICAL: Firestore Path Rules (For LLM)
@@ -39,33 +58,31 @@ SeaVerse organizes your Firestore data into three permission levels:
 **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
+   - Example: `appData/my-app/publicData/_data/posts` (5 segments) ✅ CORRECT!
+   - Firestore requires odd-numbered segments for collections
 
 2. **Document paths = EVEN number of segments** (2, 4, 6, 8...)
-   - Example: `appData/my-app/publicData/posts/doc123` (5 segments) ✅ CORRECT!
+   - Example: `appData/my-app/publicData/_data/posts/doc123` (6 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 - Collection paths have ODD segments
+collection(db, `appData/${appId}/publicData/_data/posts`)  // 5 segments (odd)
 
-// ✅ CORRECT - Using doc() for document paths
-doc(db, `appData/${appId}/publicData/posts/doc123`)  // 5 segments (odd) = document
+// ✅ CORRECT - Document paths have EVEN segments
+doc(db, `appData/${appId}/publicData/_data/posts/doc123`)  // 6 segments (even)
 
-// ❌ WRONG - Manually counting segments
-// Don't worry about counting! Use Firebase functions:
-// - collection() for collections
-// - doc() for documents
-// - addDoc() automatically adds document ID
+// 💡 TIP: Always use path helper functions to avoid counting!
+// - getPublicDataPath(appId, 'posts')  // Returns correct collection path
+// - getPublicDataDocPath(appId, 'posts', 'doc123')  // Returns correct document path
 ```
 
 **Path Structure Examples:**
 
 ```typescript
 // Public Data (everyone can read/write)
-const postsRef = collection(db, `appData/${appId}/publicData/posts`);
+const postsRef = collection(db, `appData/${appId}/publicData/_data/posts`);
 await addDoc(postsRef, { ...data });  // Firestore adds document ID
 
 // User Private Data (owner only)
@@ -73,13 +90,14 @@ 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`);
+const configRef = collection(db, `appData/${appId}/publicRead/_data/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 ✅
+- `appData` → `{app_id}` → `{permission_layer}` → `_data` → `{collection}` → (auto-generated doc ID)
+- Collection: 5 segments (odd) ✅
+- Document: 6 segments (even) ✅
 
 ### Required Fields
 
@@ -549,7 +567,7 @@ const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app
 const { db, appId, userId } = await initializeWithToken(tokenResponse);
 
 // Ready to use Firestore
-await addDoc(collection(db, `appData/${appId}/publicData/posts`), { ... });
+await addDoc(collection(db, `appData/${appId}/publicData/_data/posts`), { ... });
 ```
 
 **Note:** This function requires Firebase SDK to be installed separately:
@@ -563,7 +581,7 @@ npm install firebase
 
 ```typescript
 // Anyone (including guests) can post comments
-await addDoc(collection(db, `appData/${appId}/publicData/comments`), {
+await addDoc(collection(db, `appData/${appId}/publicData/_data/comments`), {
   _appId: appId,
   _createdAt: serverTimestamp(),
   _createdBy: userId,
@@ -574,7 +592,7 @@ await addDoc(collection(db, `appData/${appId}/publicData/comments`), {
 
 // Anyone can read comments
 const comments = await getDocs(
-  collection(db, `appData/${appId}/publicData/comments`)
+  collection(db, `appData/${appId}/publicData/_data/comments`)
 );
 ```
 
@@ -603,7 +621,7 @@ const settings = await getDoc(
 // Only admins can write to publicRead
 // Regular users and guests can only read
 const announcements = await getDocs(
-  collection(db, `appData/${appId}/publicRead/announcements`)
+  collection(db, `appData/${appId}/publicRead/_data/announcements`)
 );
 
 announcements.forEach(doc => {
@@ -618,7 +636,7 @@ import { query, where, orderBy, limit } from 'firebase/firestore';
 
 // Query posts created by a specific user
 const userPosts = query(
-  collection(db, `appData/${appId}/publicData/posts`),
+  collection(db, `appData/${appId}/publicData/_data/posts`),
   where('_createdBy', '==', userId),
   orderBy('_createdAt', 'desc'),
   limit(10)
@@ -789,7 +807,7 @@ async function completeExample() {
 
   // 4. Create a post (publicData)
   const postRef = await addDoc(
-    collection(db, `appData/${appId}/publicData/posts`),
+    collection(db, `appData/${appId}/publicData/_data/posts`),
     {
       _appId: appId,
       _createdAt: serverTimestamp(),
@@ -803,7 +821,7 @@ async function completeExample() {
 
   // 5. Read all posts
   const postsSnapshot = await getDocs(
-    collection(db, `appData/${appId}/publicData/posts`)
+    collection(db, `appData/${appId}/publicData/_data/posts`)
   );
   postsSnapshot.forEach(doc => {
     console.log('Post:', doc.id, doc.data());
@@ -811,7 +829,7 @@ async function completeExample() {
 
   // 6. Query user's own posts
   const myPostsQuery = query(
-    collection(db, `appData/${appId}/publicData/posts`),
+    collection(db, `appData/${appId}/publicData/_data/posts`),
     where('_createdBy', '==', userId)
   );
   const myPosts = await getDocs(myPostsQuery);

package/dist/browser.js

@@ -4200,7 +4200,7 @@ class DataServiceClient {
  * ```typescript
  * // Read system announcements
  * const path = getPublicReadPath('my-app', 'announcements');
- * // Returns: 'appData/my-app/publicRead/announcements'
+ * // Returns: 'appData/my-app/publicRead/_data/announcements'
  *
  * const snapshot = await getDocs(collection(db, path));
  * ```
@@ -4208,7 +4208,7 @@ class DataServiceClient {
 function getPublicReadPath(appId, collectionName) {
     validateSegment('appId', appId);
     validateSegment('collectionName', collectionName);
-    return `appData/${appId}/publicRead/${collectionName}`;
+    return `appData/${appId}/publicRead/_data/${collectionName}`;
 }
 /**
  * Generate path for publicData (read/write for all authenticated users)
@@ -4221,7 +4221,7 @@ function getPublicReadPath(appId, collectionName) {
  * ```typescript
  * // Write a public post
  * const path = getPublicDataPath('my-app', 'posts');
- * // Returns: 'appData/my-app/publicData/posts'
+ * // Returns: 'appData/my-app/publicData/_data/posts'
  *
  * await addDoc(collection(db, path), {
  *   _appId: appId,
@@ -4234,7 +4234,7 @@ function getPublicReadPath(appId, collectionName) {
 function getPublicDataPath(appId, collectionName) {
     validateSegment('appId', appId);
     validateSegment('collectionName', collectionName);
-    return `appData/${appId}/publicData/${collectionName}`;
+    return `appData/${appId}/publicData/_data/${collectionName}`;
 }
 /**
  * Generate path for userData (private, read/write only by owner)
@@ -4275,7 +4275,7 @@ function getUserDataPath(appId, userId, collectionName) {
  * @example
  * ```typescript
  * const path = getPublicReadDocPath('my-app', 'announcements', 'announcement-1');
- * // Returns: 'appData/my-app/publicRead/announcements/announcement-1'
+ * // Returns: 'appData/my-app/publicRead/_data/announcements/announcement-1'
  *
  * const docSnap = await getDoc(doc(db, path));
  * ```
@@ -4284,7 +4284,7 @@ function getPublicReadDocPath(appId, collectionName, docId) {
     validateSegment('appId', appId);
     validateSegment('collectionName', collectionName);
     validateSegment('docId', docId);
-    return `appData/${appId}/publicRead/${collectionName}/${docId}`;
+    return `appData/${appId}/publicRead/_data/${collectionName}/${docId}`;
 }
 /**
  * Generate path for a specific document in publicData
@@ -4297,7 +4297,7 @@ function getPublicReadDocPath(appId, collectionName, docId) {
  * @example
  * ```typescript
  * const path = getPublicDataDocPath('my-app', 'posts', 'post-123');
- * // Returns: 'appData/my-app/publicData/posts/post-123'
+ * // Returns: 'appData/my-app/publicData/_data/posts/post-123'
  *
  * const docSnap = await getDoc(doc(db, path));
  * ```
@@ -4306,7 +4306,7 @@ function getPublicDataDocPath(appId, collectionName, docId) {
     validateSegment('appId', appId);
     validateSegment('collectionName', collectionName);
     validateSegment('docId', docId);
-    return `appData/${appId}/publicData/${collectionName}/${docId}`;
+    return `appData/${appId}/publicData/_data/${collectionName}/${docId}`;
 }
 /**
  * Generate path for a specific document in userData