@seaverse/data-service-sdk 0.9.0 → 0.10.1

package/dist/browser.js

@@ -3941,9 +3941,9 @@ const ENDPOINTS = {
  * ---------------------------
  * Your Firestore data is organized in three permission levels:
  *
- * 1. publicRead/   - System configs, announcements (Read: Everyone, Write: Admin only)
- * 2. publicData/   - User posts, shared content (Read: Everyone, Write: Everyone)
- * 3. userData/{userId}/ - Private user data (Read/Write: Owner only)
+ * 1. publicRead/_data/   - System configs, announcements (Read: Everyone, Write: Admin only)
+ * 2. publicData/_data/   - User posts, shared content (Read: Everyone, Write: Everyone)
+ * 3. userData/{userId}/_data/ - Private user data (Read/Write: Owner only)
  *
  * QUICK START FOR LLM:
  * -------------------
@@ -3995,7 +3995,7 @@ const ENDPOINTS = {
  * const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
  *
  * // Write to userData (only owner can write)
- * await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
+ * await addDoc(collection(db, `appData/${appId}/userData/${userId}/_data/notes`), {
  *   _appId: appId,              // REQUIRED
  *   _createdAt: serverTimestamp(), // REQUIRED
  *   _createdBy: userId,         // REQUIRED
@@ -4248,7 +4248,7 @@ function getPublicDataPath(appId, collectionName) {
  * ```typescript
  * // Write private user notes
  * const path = getUserDataPath('my-app', 'user-123', 'notes');
- * // Returns: 'appData/my-app/userData/user-123/notes'
+ * // Returns: 'appData/my-app/userData/user-123/_data/notes'
  *
  * await addDoc(collection(db, path), {
  *   _appId: appId,
@@ -4262,7 +4262,7 @@ function getUserDataPath(appId, userId, collectionName) {
     validateSegment('appId', appId);
     validateSegment('userId', userId);
     validateSegment('collectionName', collectionName);
-    return `appData/${appId}/userData/${userId}/${collectionName}`;
+    return `appData/${appId}/userData/${userId}/_data/${collectionName}`;
 }
 /**
  * Generate path for a specific document in publicRead
@@ -4320,7 +4320,7 @@ function getPublicDataDocPath(appId, collectionName, docId) {
  * @example
  * ```typescript
  * const path = getUserDataDocPath('my-app', 'user-123', 'notes', 'note-456');
- * // Returns: 'appData/my-app/userData/user-123/notes/note-456'
+ * // Returns: 'appData/my-app/userData/user-123/_data/notes/note-456'
  *
  * const docSnap = await getDoc(doc(db, path));
  * ```
@@ -4330,7 +4330,7 @@ function getUserDataDocPath(appId, userId, collectionName, docId) {
     validateSegment('userId', userId);
     validateSegment('collectionName', collectionName);
     validateSegment('docId', docId);
-    return `appData/${appId}/userData/${userId}/${collectionName}/${docId}`;
+    return `appData/${appId}/userData/${userId}/_data/${collectionName}/${docId}`;
 }
 /**
  * Validate a path segment to ensure it doesn't contain invalid characters
@@ -4395,7 +4395,7 @@ class PathBuilder {
     userData(userId, collectionName) {
         validateSegment('userId', userId);
         validateSegment('collectionName', collectionName);
-        this.segments.push('userData', userId, collectionName);
+        this.segments.push('userData', userId, '_data', collectionName);
         return this;
     }
     /**
@@ -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,36 @@ 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
+            // Use '!=' to include documents without _deleted field (new documents)
+            // This will return documents where _deleted is missing, null, undefined, or false
+            const q = query(colRef, where('_deleted', '!=', true));
+            return getDocs(q);
+        }
     }
     /**
      * Internal: Get collection reference
@@ -4901,5 +5222,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