@seaverse/data-service-sdk 0.5.2 → 0.7.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
@@ -10,6 +22,7 @@ SeaVerse Data Service SDK for accessing Firestore with secure token management a
 - 🔒 Automatic data isolation by app_id
 - 📝 TypeScript support with full type definitions
 - 🤖 LLM-friendly documentation with clear examples
+- 🛡️ Path helper functions to prevent permission-denied errors
 
 ## Three-Tier Permission Model
 
@@ -130,14 +143,112 @@ const { DataServiceClient } = require('@seaverse/data-service-sdk');
 import { DataServiceClient } from '@seaverse/data-service-sdk';
 ```
 
+## Path Helper Functions (🚨 Recommended for LLM)
+
+To prevent `permission-denied` errors caused by incorrect paths, we provide helper functions that generate the correct Firestore paths automatically.
+
+### Why Use Path Helpers?
+
+**Problem**: LLM or developers might accidentally use wrong paths:
+```typescript
+// ❌ WRONG - Will cause permission-denied!
+collection(db, `apps/${appId}/publicArticles`)  // Not matching security rules!
+collection(db, `apps/${appId}/users/${userId}/articles`)  // Not matching security rules!
+```
+
+**Solution**: Use path helper functions:
+```typescript
+import { getPublicDataPath, getUserDataPath } from '@seaverse/data-service-sdk';
+
+// ✅ CORRECT - Guaranteed to match security rules
+collection(db, getPublicDataPath(appId, 'posts'))  // → appData/{appId}/publicData/posts
+collection(db, getUserDataPath(appId, userId, 'notes'))  // → appData/{appId}/userData/{userId}/notes
+```
+
+### Available Path Helpers
+
+```typescript
+import {
+  getPublicReadPath,      // For read-only public data
+  getPublicDataPath,      // For public read/write data
+  getUserDataPath,        // For private user data
+  getPublicReadDocPath,   // For specific public document
+  getPublicDataDocPath,   // For specific public data document
+  getUserDataDocPath,     // For specific user document
+  PathBuilder             // For advanced path building
+} from '@seaverse/data-service-sdk';
+```
+
+### Basic Usage Examples
+
+```typescript
+// Public data that everyone can read/write
+const postsPath = getPublicDataPath(appId, 'posts');
+await addDoc(collection(db, postsPath), {
+  _appId: appId,
+  _createdAt: serverTimestamp(),
+  _createdBy: userId,
+  title: 'My Post'
+});
+
+// Private user data
+const notesPath = getUserDataPath(appId, userId, 'notes');
+await addDoc(collection(db, notesPath), {
+  _appId: appId,
+  _createdAt: serverTimestamp(),
+  _createdBy: userId,
+  content: 'Private note'
+});
+
+// Public read-only data (admin writes only)
+const configPath = getPublicReadPath(appId, 'config');
+const configs = await getDocs(collection(db, configPath));
+
+// Access specific document
+const docPath = getPublicDataDocPath(appId, 'posts', 'post-123');
+const docSnap = await getDoc(doc(db, docPath));
+```
+
+### Advanced: PathBuilder
+
+For complex path construction:
+
+```typescript
+import { PathBuilder } from '@seaverse/data-service-sdk';
+
+const builder = new PathBuilder(appId);
+
+// Build collection path
+const path = builder.publicData('posts').build();
+// Returns: 'appData/my-app/publicData/posts'
+
+// Build document path
+const docPath = builder.publicData('posts').doc('post-123').build();
+// Returns: 'appData/my-app/publicData/posts/post-123'
+
+// Build user data path
+const userPath = builder.userData(userId, 'notes').build();
+// Returns: 'appData/my-app/userData/user-123/notes'
+```
+
+### Error Prevention
+
+Path helpers validate inputs to prevent common mistakes:
+
+```typescript
+// ❌ These will throw errors:
+getPublicDataPath('my-app', 'posts/comments');  // Error: cannot contain /
+getPublicDataPath('my-app', '');  // Error: must be non-empty string
+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 } 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' });
@@ -153,41 +264,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!
+// Step 4: Use Firestore with helper (automatic required fields!)
 
-// Write to publicData (everyone can write)
-await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
-  _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, `appData/${appId}/publicData/posts`));
-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)
-await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
+// ✅ LLM-FRIENDLY: Write to userData (private) - auto-isolated!
+await helper.addToUserData('notes', {
+  title: 'Private Note',
+  content: 'Only I can see this'
+});
+```
+
+<details>
+<summary>📖 Advanced: Manual Way (for fine-grained control)</summary>
+
+```typescript
+import {
+  DataServiceClient,
+  initializeWithToken,
+  getPublicDataPath,
+  getUserDataPath,
+  collection,
+  addDoc,
+  getDocs,
+  serverTimestamp
+} from '@seaverse/data-service-sdk';
+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: 'Private Note',
-  content: 'Only I can see this'
+  title: 'My First Post',
+  content: 'Hello world!'
 });
 ```
+</details>
 
-### 👤 For Guest Users (Even Simpler!)
+### 👤 For Guest Users (🤖 Even Simpler!)
 
 ```typescript
 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();
@@ -195,14 +330,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
-await addDoc(collection(db, `appData/${appId}/publicData/comments`), {
-  _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
 });
@@ -566,7 +698,19 @@ import type {
 
 When using this SDK with LLM-generated code:
 
-1. **Always include required fields:**
+1. **🛡️ MOST IMPORTANT: Use path helper functions to avoid permission-denied errors:**
+   ```typescript
+   import { getPublicDataPath, getUserDataPath } from '@seaverse/data-service-sdk';
+
+   // ✅ CORRECT - Use helpers
+   const path = getPublicDataPath(appId, 'posts');
+   await addDoc(collection(db, path), { ... });
+
+   // ❌ WRONG - Manual paths may be incorrect
+   await addDoc(collection(db, `apps/${appId}/posts`), { ... });
+   ```
+
+2. **Always include required fields:**
    ```typescript
    {
      _appId: appId,              // From token response
@@ -575,16 +719,26 @@ When using this SDK with LLM-generated code:
    }
    ```
 
-2. **Use correct data paths:**
-   - publicRead: `appData/${appId}/publicRead/{collection}/{docId}`
-   - publicData: `appData/${appId}/publicData/{collection}/{docId}`
-   - userData: `appData/${appId}/userData/${userId}/{collection}/{docId}`
+3. **Use correct data paths with helpers:**
+   ```typescript
+   // Use path helpers instead of manual strings!
+   import { getPublicReadPath, getPublicDataPath, getUserDataPath } from '@seaverse/data-service-sdk';
+
+   // publicRead
+   const configPath = getPublicReadPath(appId, 'config');
+
+   // publicData
+   const postsPath = getPublicDataPath(appId, 'posts');
+
+   // userData
+   const notesPath = getUserDataPath(appId, userId, 'notes');
+   ```
 
-3. **Handle token expiration:**
+4. **Handle token expiration:**
    - Tokens expire after 1 hour (3600 seconds)
    - Check `expires_in` field and refresh when needed
 
-4. **Use serverTimestamp() for timestamps:**
+5. **Use serverTimestamp() for timestamps:**
    ```typescript
    import { serverTimestamp } from 'firebase/firestore';
 
@@ -593,7 +747,7 @@ When using this SDK with LLM-generated code:
    }
    ```
 
-5. **Separate guest and authenticated flows:**
+6. **Separate guest and authenticated flows:**
    - Use `generateGuestFirestoreToken()` for anonymous users
    - Use `generateFirestoreToken()` for logged-in users