@seaverse/data-service-sdk 0.9.0 → 0.10.1

package/README.md

@@ -42,6 +42,8 @@ SeaVerse Data Service SDK for accessing Firestore with secure token management a
 - 📝 TypeScript support with full type definitions
 - 🤖 LLM-friendly documentation with clear examples
 - 🛡️ Path helper functions to prevent permission-denied errors
+- ✅ Built-in validation (reserved fields, document size)
+- 🗑️ Soft delete support (mark as deleted without removing)
 
 ## Three-Tier Permission Model
 
@@ -51,7 +53,7 @@ SeaVerse organizes your Firestore data into three permission levels:
 |-----------------|--------------|-------------|--------------|----------|
 | **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 |
+| **userData** | `appData/{app_id}/userData/{user_id}/_data/{collection}/{docId}` | Owner only | Owner only | User settings, private notes, personal data |
 
 ### 🚨 CRITICAL: Firestore Path Rules (For LLM)
 
@@ -86,7 +88,7 @@ const postsRef = collection(db, `appData/${appId}/publicData/_data/posts`);
 await addDoc(postsRef, { ...data });  // Firestore adds document ID
 
 // User Private Data (owner only)
-const notesRef = collection(db, `appData/${appId}/userData/${userId}/notes`);
+const notesRef = collection(db, `appData/${appId}/userData/${userId}/_data/notes`);
 await addDoc(notesRef, { ...data });
 
 // Public Read-Only (everyone can read, admin can write)
@@ -95,9 +97,10 @@ await getDocs(configRef);
 ```
 
 **The pattern is always:**
-- `appData` → `{app_id}` → `{permission_layer}` → `_data` → `{collection}` → (auto-generated doc ID)
-- Collection: 5 segments (odd) ✅
-- Document: 6 segments (even) ✅
+- `appData` → `{app_id}` → `{permission_layer}` → (`{user_id}` for userData) → `_data` → `{collection}` → (auto-generated doc ID)
+- publicRead/publicData Collection: 5 segments (odd) ✅
+- userData Collection: 6 segments (even) ✅ (includes userId)
+- Document paths: add 1 more segment for docId
 
 ### Required Fields
 
@@ -113,6 +116,82 @@ All Firestore documents MUST include these three fields:
 
 These fields are enforced by Firestore Security Rules and ensure proper data isolation.
 
+**🎯 Good News for LLM**: When using `FirestoreHelper`, these fields are automatically injected - you don't need to remember them!
+
+### Reserved Fields & Validation
+
+**⚠️ IMPORTANT: Fields starting with `_` are reserved for system use!**
+
+The SDK automatically validates your data to prevent common mistakes:
+
+1. **Reserved Fields**: You cannot create custom fields starting with `_`
+   ```typescript
+   // ❌ WRONG - Will throw error
+   await helper.addToPublicData('posts', {
+     _custom: 'value',  // Reserved field!
+     title: 'My Post'
+   });
+
+   // ✅ CORRECT
+   await helper.addToPublicData('posts', {
+     customField: 'value',  // No underscore prefix
+     title: 'My Post'
+   });
+   ```
+
+2. **Document Size**: Documents are limited to 256 KB
+   ```typescript
+   // SDK will automatically check size and throw error if too large
+   ```
+
+3. **Automatic Validation**: All `FirestoreHelper` methods validate data automatically
+   ```typescript
+   // Manual validation if needed
+   import { validateFirestoreData, validateDataDetailed } from '@seaverse/data-service-sdk';
+
+   try {
+     validateFirestoreData(myData);
+     // Data is valid
+   } catch (error) {
+     console.error('Validation failed:', error.message);
+   }
+
+   // Or get detailed errors without throwing
+   const result = validateDataDetailed(myData);
+   if (!result.valid) {
+     console.error('Errors:', result.errors);
+   }
+   ```
+
+### Soft Delete Support
+
+**🗑️ Recommended Practice: Use soft delete instead of hard delete**
+
+Soft delete marks documents as deleted without removing them from the database:
+
+```typescript
+// ✅ RECOMMENDED: Soft delete (mark as deleted)
+await helper.softDeleteDoc(
+  getPublicDataPath(appId, 'posts'),
+  'post-123'
+);
+
+// Document is still in database but marked as _deleted = true
+// By default, helper.getPublicData() won't return deleted documents
+
+// ❌ Hard delete (only for admins, permanent)
+await helper.deleteDoc(
+  getPublicDataPath(appId, 'posts'),
+  'post-123'
+);
+```
+
+**Why soft delete?**
+- ✅ Data recovery possible
+- ✅ Audit trail preserved
+- ✅ Safer for production
+- ✅ Follows industry best practices
+
 ## Installation
 
 ```bash
@@ -179,17 +258,17 @@ collection(db, `apps/${appId}/users/${userId}/articles`)  // Not matching securi
 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
+collection(db, getPublicDataPath(appId, 'posts'))  // → appData/{appId}/publicData/_data/posts
+collection(db, getUserDataPath(appId, userId, 'notes'))  // → appData/{appId}/userData/{userId}/_data/notes
 ```
 
 ### Available Path Helpers
 
 ```typescript
 import {
-  getPublicReadPath,      // For read-only public data
-  getPublicDataPath,      // For public read/write data
-  getUserDataPath,        // For private user data
+  getPublicReadPath,      // Returns: appData/{appId}/publicRead/_data/{collection}
+  getPublicDataPath,      // Returns: appData/{appId}/publicData/_data/{collection}
+  getUserDataPath,        // Returns: appData/{appId}/userData/{userId}/_data/{collection}
   getPublicReadDocPath,   // For specific public document
   getPublicDataDocPath,   // For specific public data document
   getUserDataDocPath,     // For specific user document
@@ -246,7 +325,7 @@ const docPath = builder.publicData('posts').doc('post-123').build();
 
 // Build user data path
 const userPath = builder.userData(userId, 'notes').build();
-// Returns: 'appData/my-app/userData/user-123/notes'
+// Returns: 'appData/my-app/userData/user-123/_data/notes'
 ```
 
 ### Error Prevention
@@ -600,7 +679,7 @@ const comments = await getDocs(
 
 ```typescript
 // Only the user can write to their own settings
-await setDoc(doc(db, `appData/${appId}/userData/${userId}/settings/preferences`), {
+await setDoc(doc(db, `appData/${appId}/userData/${userId}/_data/settings/preferences`), {
   _appId: appId,
   _createdAt: serverTimestamp(),
   _createdBy: userId,
@@ -611,7 +690,7 @@ await setDoc(doc(db, `appData/${appId}/userData/${userId}/settings/preferences`)
 
 // Only the user can read their own settings
 const settings = await getDoc(
-  doc(db, `appData/${appId}/userData/${userId}/settings/preferences`)
+  doc(db, `appData/${appId}/userData/${userId}/_data/settings/preferences`)
 );
 ```
 
@@ -652,7 +731,7 @@ const snapshot = await getDocs(userPosts);
 ✅ **Authenticated Users:**
 - Read `publicRead` data
 - Read and write `publicData` (all users' data)
-- Read and write their own `userData/{userId}` only
+- Read and write their own `userData/{userId}/_data/` only
 - Update/delete documents where `_createdBy == userId`
 
 ✅ **Guest Users:**
@@ -716,7 +795,20 @@ import type {
 
 When using this SDK with LLM-generated code:
 
-1. **🛡️ MOST IMPORTANT: Use path helper functions to avoid permission-denied errors:**
+1. **🎯 EASIEST: Use `FirestoreHelper` for everything!**
+   ```typescript
+   // ✅ BEST PRACTICE - Let helper handle everything
+   const { helper } = await initializeWithToken(tokenResponse);
+   await helper.addToPublicData('posts', { title: 'Post', content: 'Hello' });
+
+   // No need to remember:
+   // - Required fields (_appId, _createdAt, _createdBy)
+   // - Path construction
+   // - Data validation
+   // - Soft delete logic
+   ```
+
+2. **🛡️ Use path helper functions to avoid permission-denied errors:**
    ```typescript
    import { getPublicDataPath, getUserDataPath } from '@seaverse/data-service-sdk';
 
@@ -728,35 +820,40 @@ When using this SDK with LLM-generated code:
    await addDoc(collection(db, `apps/${appId}/posts`), { ... });
    ```
 
-2. **Always include required fields:**
+3. **⚠️ Never use field names starting with `_`:**
    ```typescript
-   {
-     _appId: appId,              // From token response
-     _createdAt: serverTimestamp(), // Use serverTimestamp()
-     _createdBy: userId          // From token response
-   }
+   // ❌ WRONG - Reserved field
+   { _myField: 'value' }
+
+   // ✅ CORRECT
+   { myField: 'value' }
    ```
 
-3. **Use correct data paths with helpers:**
+4. **🗑️ Use soft delete instead of hard delete:**
    ```typescript
-   // Use path helpers instead of manual strings!
-   import { getPublicReadPath, getPublicDataPath, getUserDataPath } from '@seaverse/data-service-sdk';
+   // ✅ RECOMMENDED
+   await helper.softDeleteDoc(path, docId);
 
-   // publicRead
-   const configPath = getPublicReadPath(appId, 'config');
+   // ❌ Only for admins
+   await helper.deleteDoc(path, docId);
+   ```
 
-   // publicData
-   const postsPath = getPublicDataPath(appId, 'posts');
+5. **✅ Validation is automatic, but you can validate manually if needed:**
+   ```typescript
+   import { validateFirestoreData } from '@seaverse/data-service-sdk';
 
-   // userData
-   const notesPath = getUserDataPath(appId, userId, 'notes');
+   try {
+     validateFirestoreData(myData);
+   } catch (error) {
+     console.error('Invalid data:', error.message);
+   }
    ```
 
-4. **Handle token expiration:**
+6. **Handle token expiration:**
    - Tokens expire after 1 hour (3600 seconds)
    - Check `expires_in` field and refresh when needed
 
-5. **Use serverTimestamp() for timestamps:**
+7. **Use serverTimestamp() for timestamps:**
    ```typescript
    import { serverTimestamp } from 'firebase/firestore';
 
@@ -765,7 +862,7 @@ When using this SDK with LLM-generated code:
    }
    ```
 
-6. **Separate guest and authenticated flows:**
+8. **Separate guest and authenticated flows:**
    - Use `generateGuestFirestoreToken()` for anonymous users
    - Use `generateFirestoreToken()` for logged-in users
 
@@ -837,7 +934,7 @@ async function completeExample() {
 
   // 7. Save user preferences (private)
   await addDoc(
-    collection(db, `appData/${appId}/userData/${userId}/preferences`),
+    collection(db, `appData/${appId}/userData/${userId}/_data/preferences`),
     {
       _appId: appId,
       _createdAt: serverTimestamp(),