@seaverse/data-service-sdk 0.6.0 → 0.8.0

package/README.md

@@ -2,6 +2,18 @@
 
 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)**
+
+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
+
+**Most common LLM mistakes prevented!**
+
 ## Features
 
 - 🔐 Secure Firestore token generation for authenticated users and guests
@@ -18,8 +30,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)
@@ -27,33 +39,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)
@@ -61,13 +71,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
 
@@ -232,17 +243,11 @@ getUserDataPath('my-app', '', 'notes');  // Error: userId must be non-empty
 
 ## Quick Start
 
-### 🚀 Easiest Way (Recommended - Auto Firebase Setup)
+### 🚀 Easiest Way (🤖 LLM-Recommended)
 
 ```typescript
-import {
-  DataServiceClient,
-  initializeWithToken,
-  getPublicDataPath,  // 🛡️ Use path helpers!
-  getUserDataPath     // 🛡️ Use path helpers!
-} from '@seaverse/data-service-sdk';
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
 import { AuthClient } from '@seaverse/auth-sdk';
-import { collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
 
 // Step 1: Login user
 const authClient = new AuthClient({ appId: 'my-app-123' });
@@ -258,47 +263,65 @@ const tokenResponse = await dataClient.generateFirestoreToken({
   app_id: 'my-app-123'
 });
 
-// Step 3: Auto-initialize Firebase (ONE LINE!)
-const { db, appId, userId } = await initializeWithToken(tokenResponse);
+// Step 3: Initialize Firebase & get helper
+const { helper } = await initializeWithToken(tokenResponse);
 
-// Step 4: Use Firestore directly with path helpers!
+// Step 4: Use Firestore with helper (automatic required fields!)
 
-// Write to publicData (everyone can write)
-const postsPath = getPublicDataPath(appId, 'posts');  // 🛡️ Safe path!
-await addDoc(collection(db, postsPath), {
-  _appId: appId,              // REQUIRED
-  _createdAt: serverTimestamp(), // REQUIRED
-  _createdBy: userId,         // REQUIRED
+// ✅ LLM-FRIENDLY: Write to publicData - required fields auto-injected!
+await helper.addToPublicData('posts', {
   title: 'My First Post',
   content: 'Hello world!'
 });
 
-// Read from publicData
-const snapshot = await getDocs(collection(db, postsPath));
-snapshot.forEach(doc => {
+// ✅ LLM-FRIENDLY: Read from publicData
+const posts = await helper.getPublicData('posts');
+posts.forEach(doc => {
   console.log(doc.id, doc.data());
 });
 
-// Write to userData (private)
-const notesPath = getUserDataPath(appId, userId, 'notes');  // 🛡️ Safe path!
-await addDoc(collection(db, notesPath), {
-  _appId: appId,              // REQUIRED
-  _createdAt: serverTimestamp(), // REQUIRED
-  _createdBy: userId,         // REQUIRED
+// ✅ LLM-FRIENDLY: Write to userData (private) - auto-isolated!
+await helper.addToUserData('notes', {
   title: 'Private Note',
   content: 'Only I can see this'
 });
 ```
 
-### 👤 For Guest Users (Even Simpler!)
+<details>
+<summary>📖 Advanced: Manual Way (for fine-grained control)</summary>
 
 ```typescript
 import {
   DataServiceClient,
   initializeWithToken,
-  getPublicDataPath  // 🛡️ Use path helpers!
+  getPublicDataPath,
+  getUserDataPath,
+  collection,
+  addDoc,
+  getDocs,
+  serverTimestamp
 } from '@seaverse/data-service-sdk';
-import { collection, addDoc, serverTimestamp } from 'firebase/firestore';
+import { AuthClient } from '@seaverse/auth-sdk';
+
+// ... login and initialize ...
+const { db, appId, userId } = await initializeWithToken(tokenResponse);
+
+// Manual way: Use path helpers + required fields
+const postsPath = getPublicDataPath(appId, 'posts');
+await addDoc(collection(db, postsPath), {
+  _appId: appId,              // REQUIRED
+  _createdAt: serverTimestamp(), // REQUIRED
+  _createdBy: userId,         // REQUIRED
+  title: 'My First Post',
+  content: 'Hello world!'
+});
+```
+</details>
+
+### 👤 For Guest Users (🤖 Even Simpler!)
+
+```typescript
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
 
 // Step 1: Get guest token (no authentication needed!)
 const dataClient = new DataServiceClient();
@@ -306,15 +329,11 @@ const tokenResponse = await dataClient.generateGuestFirestoreToken({
   app_id: 'my-app-123'
 });
 
-// Step 2: Auto-initialize Firebase (ONE LINE!)
-const { db, appId, userId } = await initializeWithToken(tokenResponse);
+// Step 2: Initialize & get helper
+const { helper } = await initializeWithToken(tokenResponse);
 
-// Step 3: Guest can write to publicData
-const commentsPath = getPublicDataPath(appId, 'comments');  // 🛡️ Safe path!
-await addDoc(collection(db, commentsPath), {
-  _appId: appId,
-  _createdAt: serverTimestamp(),
-  _createdBy: userId,  // Guest user ID (e.g., 'guest-abc123')
+// Step 3: Guest can write to publicData (automatic required fields!)
+await helper.addToPublicData('comments', {
   comment: 'Great app!',
   rating: 5
 });
@@ -529,7 +548,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:
@@ -543,7 +562,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,
@@ -554,7 +573,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`)
 );
 ```
 
@@ -583,7 +602,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 => {
@@ -598,7 +617,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)
@@ -769,7 +788,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(),
@@ -783,7 +802,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());
@@ -791,7 +810,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);