@seaverse/data-service-sdk 0.8.0 → 0.10.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
 
@@ -23,6 +42,8 @@ The Quick Start guide shows you the **recommended LLM-friendly API** that automa
 - 📝 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
 
@@ -94,6 +115,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
@@ -697,7 +794,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';
 
@@ -709,35 +819,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';
 
@@ -746,7 +861,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
 

package/dist/browser.js

@@ -4429,6 +4429,260 @@ const PATH_PATTERNS = {
     USER_DATA: 'userData',
 };
 
+/**
+ * Validation utilities for Firestore data
+ *
+ * These validators help ensure data follows SeaVerse Firestore security rules.
+ * They provide client-side validation before sending data to Firestore.
+ *
+ * 🚨 IMPORTANT: These are CLIENT-SIDE validations only!
+ * The actual security enforcement happens in Firestore Security Rules.
+ * These validators help catch errors early for better DX.
+ */
+/**
+ * Maximum document size in bytes (256 KB)
+ * This matches the Firestore security rule limit
+ */
+const MAX_DOCUMENT_SIZE = 262144; // 256 KB
+/**
+ * System reserved field names that users cannot create
+ *
+ * These fields are managed by the system and cannot be set by users:
+ * - _appId: Application ID (auto-injected)
+ * - _createdBy: Creator user ID (auto-injected)
+ * - _createdAt: Creation timestamp (auto-injected)
+ * - _updatedAt: Last update timestamp (auto-managed)
+ * - _deleted: Soft delete flag (auto-managed)
+ * - _deletedAt: Deletion timestamp (auto-managed)
+ */
+const ALLOWED_RESERVED_FIELDS = [
+    '_appId',
+    '_createdBy',
+    '_createdAt',
+    '_updatedAt',
+    '_deleted',
+    '_deletedAt',
+    '_updatedBy'
+];
+/**
+ * Common illegal reserved field patterns
+ * Based on Firestore security rules blacklist
+ */
+const ILLEGAL_RESERVED_FIELDS = [
+    // Single letter prefixes
+    '_a', '_b', '_c', '_d', '_e', '_f', '_g', '_h', '_i', '_j', '_k', '_l', '_m',
+    '_n', '_o', '_p', '_q', '_r', '_s', '_t', '_u', '_v', '_w', '_x', '_y', '_z',
+    '_A', '_B', '_C', '_D', '_E', '_F', '_G', '_H', '_I', '_J', '_K', '_L', '_M',
+    '_N', '_O', '_P', '_Q', '_R', '_S', '_T', '_U', '_V', '_W', '_X', '_Y', '_Z',
+    // Number prefixes
+    '_0', '_1', '_2', '_3', '_4', '_5', '_6', '_7', '_8', '_9',
+    // Multiple underscores
+    '__', '___', '____',
+    // Permission related
+    '_admin', '_user', '_role', '_permission', '_access', '_auth', '_owner', '_public',
+    // Metadata related
+    '_custom', '_data', '_meta', '_info', '_config', '_setting', '_value', '_key',
+    '_id', '_ID', '_ref', '_timestamp', '_time', '_date', '_status', '_type',
+    // Temporary fields
+    '_temp', '_tmp', '_test', '_new', '_old', '_bak', '_backup', '_copy',
+    // Common business fields
+    '_name', '_title', '_description', '_content', '_body', '_text', '_message',
+    '_email', '_phone', '_address', '_city', '_country', '_zip', '_code',
+    '_price', '_amount', '_quantity', '_total', '_subtotal', '_discount', '_tax',
+    '_image', '_avatar', '_photo', '_picture', '_file', '_url', '_link', '_path',
+    '_user_id', '_userId', '_username', '_nickname', '_displayName',
+    '_password', '_token', '_session', '_apiKey', '_secretKey', '_privateKey',
+    // Flag fields
+    '_flag', '_enabled', '_disabled', '_active', '_inactive', '_visible', '_hidden',
+    '_isAdmin', '_isPublic', '_isPrivate', '_isDeleted', '_isActive', '_isEnabled',
+    // State fields
+    '_state', '_mode', '_level', '_priority', '_order', '_index', '_count', '_number',
+    // System fields
+    '_system', '_internal', '_private', '_protected', '_reserved', '_secret', '_hidden'
+];
+/**
+ * Validate that data doesn't contain illegal reserved fields
+ *
+ * Reserved fields (starting with _) are for system use only.
+ * Users can only use allowed system fields.
+ *
+ * @param data - Data object to validate
+ * @throws Error if illegal reserved fields are found
+ *
+ * @example
+ * ```typescript
+ * // ✅ Valid - no reserved fields
+ * validateReservedFields({ title: 'Post', content: 'Hello' });
+ *
+ * // ✅ Valid - allowed system fields
+ * validateReservedFields({ _appId: 'app-1', _createdBy: 'user-1', title: 'Post' });
+ *
+ * // ❌ Invalid - illegal reserved field
+ * validateReservedFields({ _custom: 'value', title: 'Post' });
+ * // Throws: Error: Illegal reserved field "_custom"
+ * ```
+ */
+function validateReservedFields(data) {
+    const keys = Object.keys(data);
+    for (const key of keys) {
+        // Skip allowed system fields
+        if (ALLOWED_RESERVED_FIELDS.includes(key)) {
+            continue;
+        }
+        // Check if it's a reserved field (starts with _)
+        if (key.startsWith('_')) {
+            // Check if it's in the blacklist
+            if (ILLEGAL_RESERVED_FIELDS.includes(key)) {
+                throw new Error(`Illegal reserved field "${key}". ` +
+                    `Fields starting with "_" are reserved for system use. ` +
+                    `Please use a field name without the underscore prefix.`);
+            }
+            // Even if not in blacklist, warn about unknown _ fields
+            throw new Error(`Unknown reserved field "${key}". ` +
+                `Fields starting with "_" are reserved for system use. ` +
+                `Allowed system fields: ${ALLOWED_RESERVED_FIELDS.join(', ')}. ` +
+                `Please use a field name without the underscore prefix.`);
+        }
+    }
+}
+/**
+ * Estimate document size in bytes
+ *
+ * This is an approximation based on JSON serialization.
+ * Firestore may calculate size differently, but this gives a good estimate.
+ *
+ * @param data - Data object to measure
+ * @returns Estimated size in bytes
+ *
+ * @example
+ * ```typescript
+ * const data = { title: 'My Post', content: 'Long content...' };
+ * const size = estimateDocumentSize(data);
+ * console.log('Document size:', size, 'bytes');
+ * ```
+ */
+function estimateDocumentSize(data) {
+    try {
+        const json = JSON.stringify(data);
+        // Use Blob if available (browser), otherwise estimate from string length
+        if (typeof Blob !== 'undefined') {
+            return new Blob([json]).size;
+        }
+        else {
+            // Node.js or environments without Blob: estimate from UTF-8 encoded length
+            return Buffer.byteLength(json, 'utf8');
+        }
+    }
+    catch (error) {
+        // Fallback: rough estimate
+        return JSON.stringify(data).length * 2; // Assume ~2 bytes per char for safety
+    }
+}
+/**
+ * Validate document size doesn't exceed limit
+ *
+ * Firestore has a maximum document size of 1MB, but we enforce 256KB
+ * to match our security rules limit.
+ *
+ * @param data - Data object to validate
+ * @throws Error if document is too large
+ *
+ * @example
+ * ```typescript
+ * const data = { title: 'Post', content: 'Some content' };
+ * validateDocumentSize(data); // OK
+ *
+ * const hugeData = { content: 'x'.repeat(300000) };
+ * validateDocumentSize(hugeData); // Throws error
+ * ```
+ */
+function validateDocumentSize(data) {
+    const size = estimateDocumentSize(data);
+    if (size > MAX_DOCUMENT_SIZE) {
+        throw new Error(`Document size (${size} bytes) exceeds maximum allowed size (${MAX_DOCUMENT_SIZE} bytes / 256 KB). ` +
+            `Please reduce the amount of data you're storing in this document.`);
+    }
+}
+/**
+ * Validate data before sending to Firestore
+ *
+ * This runs all validations:
+ * - Reserved fields check
+ * - Document size check
+ *
+ * @param data - Data object to validate
+ * @throws Error if validation fails
+ *
+ * @example
+ * ```typescript
+ * // Use this before adding/updating documents
+ * try {
+ *   validateFirestoreData(myData);
+ *   await addDoc(collection(db, path), myData);
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message);
+ * }
+ * ```
+ */
+function validateFirestoreData(data) {
+    validateReservedFields(data);
+    validateDocumentSize(data);
+}
+/**
+ * Check if data contains soft-delete markers
+ *
+ * @param data - Data object to check
+ * @returns True if document is marked as deleted
+ */
+function isDeleted(data) {
+    return data._deleted === true;
+}
+/**
+ * Validate data and return detailed results instead of throwing
+ *
+ * Use this when you want to handle validation errors gracefully
+ * without try/catch blocks.
+ *
+ * @param data - Data object to validate
+ * @returns Validation result with errors
+ *
+ * @example
+ * ```typescript
+ * const result = validateDataDetailed(myData);
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ *   // Show errors to user
+ * } else {
+ *   // Proceed with save
+ * }
+ * ```
+ */
+function validateDataDetailed(data) {
+    const errors = [];
+    // Check reserved fields
+    try {
+        validateReservedFields(data);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            errors.push(error.message);
+        }
+    }
+    // Check document size
+    try {
+        validateDocumentSize(data);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            errors.push(error.message);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+
 /**
  * Firestore Helper - LLM-Friendly Firestore Operations
  *
@@ -4523,25 +4777,36 @@ class FirestoreHelper {
     /**
      * Get all documents from publicData collection
      *
+     * By default, this returns only non-deleted documents.
+     * Set includeDeleted=true to include soft-deleted documents.
+     *
      * @param collectionName - Collection name
+     * @param includeDeleted - Include soft-deleted documents (default: false)
      * @returns QuerySnapshot with documents
      *
      * @example
      * ```typescript
+     * // Get only active posts (not deleted)
      * const snapshot = await helper.getPublicData('posts');
      * snapshot.forEach(doc => {
      *   console.log(doc.id, doc.data());
      * });
+     *
+     * // Include deleted posts (admin use case)
+     * const allPosts = await helper.getPublicData('posts', true);
      * ```
      */
-    async getPublicData(collectionName) {
+    async getPublicData(collectionName, includeDeleted = false) {
         const path = getPublicDataPath(this.appId, collectionName);
-        return this.getDocs(path);
+        return this.getDocs(path, includeDeleted);
     }
     /**
      * Get all documents from userData collection (user's private data)
      *
+     * By default, this returns only non-deleted documents.
+     *
      * @param collectionName - Collection name
+     * @param includeDeleted - Include soft-deleted documents (default: false)
      * @returns QuerySnapshot with documents
      *
      * @example
@@ -4552,9 +4817,9 @@ class FirestoreHelper {
      * });
      * ```
      */
-    async getUserData(collectionName) {
+    async getUserData(collectionName, includeDeleted = false) {
         const path = getUserDataPath(this.appId, this.userId, collectionName);
-        return this.getDocs(path);
+        return this.getDocs(path, includeDeleted);
     }
     /**
      * Get all documents from publicRead collection (read-only for users)
@@ -4634,6 +4899,8 @@ class FirestoreHelper {
      * ```
      */
     async updateDoc(collectionPath, docId, data) {
+        // Validate user data
+        validateFirestoreData(data);
         const { updateDoc, doc, serverTimestamp } = await this.loadFirestore();
         const docRef = doc(this.db, collectionPath, docId);
         return updateDoc(docRef, {
@@ -4643,10 +4910,50 @@ class FirestoreHelper {
         });
     }
     /**
-     * Delete document
+     * Soft delete document (mark as deleted without removing)
+     *
+     * This is the RECOMMENDED way to delete documents. It marks the document
+     * as deleted without actually removing it from the database.
+     *
+     * Automatically sets: _deleted = true, _deletedAt = serverTimestamp()
+     *
+     * @param collectionPath - Full collection path
+     * @param docId - Document ID
+     *
+     * @example
+     * ```typescript
+     * // Soft delete a post (recommended)
+     * await helper.softDeleteDoc(
+     *   getPublicDataPath(appId, 'posts'),
+     *   'post-123'
+     * );
+     * ```
+     */
+    async softDeleteDoc(collectionPath, docId) {
+        const { updateDoc, doc, serverTimestamp } = await this.loadFirestore();
+        const docRef = doc(this.db, collectionPath, docId);
+        return updateDoc(docRef, {
+            _deleted: true,
+            _deletedAt: serverTimestamp()
+        });
+    }
+    /**
+     * Hard delete document (permanently remove from database)
+     *
+     * ⚠️ WARNING: This permanently removes the document.
+     * Only admins can hard delete. Regular users should use softDeleteDoc().
      *
      * @param collectionPath - Full collection path
      * @param docId - Document ID
+     *
+     * @example
+     * ```typescript
+     * // Hard delete (admin only)
+     * await helper.deleteDoc(
+     *   getPublicDataPath(appId, 'posts'),
+     *   'post-123'
+     * );
+     * ```
      */
     async deleteDoc(collectionPath, docId) {
         const { deleteDoc, doc } = await this.loadFirestore();
@@ -4682,22 +4989,34 @@ class FirestoreHelper {
      * Internal: Add document with metadata injection
      */
     async addDocWithMeta(collectionPath, data) {
+        // Validate user data before adding system fields
+        validateFirestoreData(data);
         const { addDoc, collection, serverTimestamp } = await this.loadFirestore();
         const colRef = collection(this.db, collectionPath);
-        return addDoc(colRef, {
+        const docData = {
             _appId: this.appId,
             _createdAt: serverTimestamp(),
             _createdBy: this.userId,
             ...data
-        });
+        };
+        return addDoc(colRef, docData);
     }
     /**
      * Internal: Get all documents from collection
+     * Optionally filter out soft-deleted documents
      */
-    async getDocs(collectionPath) {
-        const { getDocs, collection } = await this.loadFirestore();
+    async getDocs(collectionPath, includeDeleted = false) {
+        const { getDocs, collection, query, where } = await this.loadFirestore();
         const colRef = collection(this.db, collectionPath);
-        return getDocs(colRef);
+        if (includeDeleted) {
+            // Return all documents (including soft-deleted)
+            return getDocs(colRef);
+        }
+        else {
+            // Filter out soft-deleted documents
+            const q = query(colRef, where('_deleted', '==', false));
+            return getDocs(q);
+        }
     }
     /**
      * Internal: Get collection reference
@@ -4901,5 +5220,5 @@ async function initializeWithToken(tokenResponse) {
     };
 }
 
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, FirestoreHelper, PATH_PATTERNS, PathBuilder, addDocWithMeta, getFirebaseConfig, getPublicDataDocPath, getPublicDataPath, getPublicReadDocPath, getPublicReadPath, getUserDataDocPath, getUserDataPath, initializeWithToken, updateDocWithMeta };
+export { ALLOWED_RESERVED_FIELDS, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, FirestoreHelper, MAX_DOCUMENT_SIZE, PATH_PATTERNS, PathBuilder, addDocWithMeta, estimateDocumentSize, getFirebaseConfig, getPublicDataDocPath, getPublicDataPath, getPublicReadDocPath, getPublicReadPath, getUserDataDocPath, getUserDataPath, initializeWithToken, isDeleted, updateDocWithMeta, validateDataDetailed, validateDocumentSize, validateFirestoreData, validateReservedFields };
 //# sourceMappingURL=browser.js.map