@seaverse/data-service-sdk 0.9.0 → 0.10.0

package/dist/browser.umd.js

@@ -4433,6 +4433,260 @@
       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
    *
@@ -4527,25 +4781,36 @@
       /**
        * 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
@@ -4556,9 +4821,9 @@
        * });
        * ```
        */
-      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)
@@ -4638,6 +4903,8 @@
        * ```
        */
       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, {
@@ -4647,10 +4914,50 @@
           });
       }
       /**
-       * 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();
@@ -4686,22 +4993,34 @@
        * 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
@@ -5013,14 +5332,17 @@
     enumerable: true,
     get: function () { return firestore.writeBatch; }
   });
+  exports.ALLOWED_RESERVED_FIELDS = ALLOWED_RESERVED_FIELDS;
   exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
   exports.DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
   exports.DataServiceClient = DataServiceClient;
   exports.ENDPOINTS = ENDPOINTS;
   exports.FirestoreHelper = FirestoreHelper;
+  exports.MAX_DOCUMENT_SIZE = MAX_DOCUMENT_SIZE;
   exports.PATH_PATTERNS = PATH_PATTERNS;
   exports.PathBuilder = PathBuilder;
   exports.addDocWithMeta = addDocWithMeta;
+  exports.estimateDocumentSize = estimateDocumentSize;
   exports.getFirebaseConfig = getFirebaseConfig;
   exports.getPublicDataDocPath = getPublicDataDocPath;
   exports.getPublicDataPath = getPublicDataPath;
@@ -5029,7 +5351,12 @@
   exports.getUserDataDocPath = getUserDataDocPath;
   exports.getUserDataPath = getUserDataPath;
   exports.initializeWithToken = initializeWithToken;
+  exports.isDeleted = isDeleted;
   exports.updateDocWithMeta = updateDocWithMeta;
+  exports.validateDataDetailed = validateDataDetailed;
+  exports.validateDocumentSize = validateDocumentSize;
+  exports.validateFirestoreData = validateFirestoreData;
+  exports.validateReservedFields = validateReservedFields;
 
 }));
 //# sourceMappingURL=browser.umd.js.map