@seaverse/data-service-sdk 0.5.2 → 0.6.0

package/dist/browser.umd.js

@@ -4269,11 +4269,273 @@
       };
   }
 
+  /**
+   * Firestore Path Helper Functions
+   *
+   * These helper functions generate correct Firestore paths that match
+   * the security rules. Use these instead of manually constructing paths
+   * to avoid permission-denied errors.
+   *
+   * 🚨 IMPORTANT: These paths are designed to work with SeaVerse Firestore Rules
+   *
+   * Permission Levels:
+   * - publicRead: Read-only for all users, write for admins only
+   * - publicData: Read/write for all authenticated users
+   * - userData: Read/write only for the data owner
+   */
+  /**
+   * Generate path for publicRead data (read-only for users, write for admins)
+   *
+   * @param appId - Your application ID
+   * @param collection - Collection name (e.g., 'announcements', 'config')
+   * @returns Firestore path string
+   *
+   * @example
+   * ```typescript
+   * // Read system announcements
+   * const path = getPublicReadPath('my-app', 'announcements');
+   * // Returns: 'appData/my-app/publicRead/announcements'
+   *
+   * const snapshot = await getDocs(collection(db, path));
+   * ```
+   */
+  function getPublicReadPath(appId, collectionName) {
+      validateSegment('appId', appId);
+      validateSegment('collectionName', collectionName);
+      return `appData/${appId}/publicRead/${collectionName}`;
+  }
+  /**
+   * Generate path for publicData (read/write for all authenticated users)
+   *
+   * @param appId - Your application ID
+   * @param collection - Collection name (e.g., 'posts', 'comments')
+   * @returns Firestore path string
+   *
+   * @example
+   * ```typescript
+   * // Write a public post
+   * const path = getPublicDataPath('my-app', 'posts');
+   * // Returns: 'appData/my-app/publicData/posts'
+   *
+   * await addDoc(collection(db, path), {
+   *   _appId: appId,
+   *   _createdAt: serverTimestamp(),
+   *   _createdBy: userId,
+   *   title: 'My Post'
+   * });
+   * ```
+   */
+  function getPublicDataPath(appId, collectionName) {
+      validateSegment('appId', appId);
+      validateSegment('collectionName', collectionName);
+      return `appData/${appId}/publicData/${collectionName}`;
+  }
+  /**
+   * Generate path for userData (private, read/write only by owner)
+   *
+   * @param appId - Your application ID
+   * @param userId - User ID who owns this data
+   * @param collection - Collection name (e.g., 'notes', 'settings')
+   * @returns Firestore path string
+   *
+   * @example
+   * ```typescript
+   * // Write private user notes
+   * const path = getUserDataPath('my-app', 'user-123', 'notes');
+   * // Returns: 'appData/my-app/userData/user-123/notes'
+   *
+   * await addDoc(collection(db, path), {
+   *   _appId: appId,
+   *   _createdAt: serverTimestamp(),
+   *   _createdBy: userId,
+   *   content: 'Private note'
+   * });
+   * ```
+   */
+  function getUserDataPath(appId, userId, collectionName) {
+      validateSegment('appId', appId);
+      validateSegment('userId', userId);
+      validateSegment('collectionName', collectionName);
+      return `appData/${appId}/userData/${userId}/${collectionName}`;
+  }
+  /**
+   * Generate path for a specific document in publicRead
+   *
+   * @param appId - Your application ID
+   * @param collection - Collection name
+   * @param docId - Document ID
+   * @returns Firestore document path string
+   *
+   * @example
+   * ```typescript
+   * const path = getPublicReadDocPath('my-app', 'announcements', 'announcement-1');
+   * // Returns: 'appData/my-app/publicRead/announcements/announcement-1'
+   *
+   * const docSnap = await getDoc(doc(db, path));
+   * ```
+   */
+  function getPublicReadDocPath(appId, collectionName, docId) {
+      validateSegment('appId', appId);
+      validateSegment('collectionName', collectionName);
+      validateSegment('docId', docId);
+      return `appData/${appId}/publicRead/${collectionName}/${docId}`;
+  }
+  /**
+   * Generate path for a specific document in publicData
+   *
+   * @param appId - Your application ID
+   * @param collection - Collection name
+   * @param docId - Document ID
+   * @returns Firestore document path string
+   *
+   * @example
+   * ```typescript
+   * const path = getPublicDataDocPath('my-app', 'posts', 'post-123');
+   * // Returns: 'appData/my-app/publicData/posts/post-123'
+   *
+   * const docSnap = await getDoc(doc(db, path));
+   * ```
+   */
+  function getPublicDataDocPath(appId, collectionName, docId) {
+      validateSegment('appId', appId);
+      validateSegment('collectionName', collectionName);
+      validateSegment('docId', docId);
+      return `appData/${appId}/publicData/${collectionName}/${docId}`;
+  }
+  /**
+   * Generate path for a specific document in userData
+   *
+   * @param appId - Your application ID
+   * @param userId - User ID who owns this data
+   * @param collection - Collection name
+   * @param docId - Document ID
+   * @returns Firestore document path string
+   *
+   * @example
+   * ```typescript
+   * const path = getUserDataDocPath('my-app', 'user-123', 'notes', 'note-456');
+   * // Returns: 'appData/my-app/userData/user-123/notes/note-456'
+   *
+   * const docSnap = await getDoc(doc(db, path));
+   * ```
+   */
+  function getUserDataDocPath(appId, userId, collectionName, docId) {
+      validateSegment('appId', appId);
+      validateSegment('userId', userId);
+      validateSegment('collectionName', collectionName);
+      validateSegment('docId', docId);
+      return `appData/${appId}/userData/${userId}/${collectionName}/${docId}`;
+  }
+  /**
+   * Validate a path segment to ensure it doesn't contain invalid characters
+   *
+   * @param name - Parameter name for error messages
+   * @param value - The segment value to validate
+   * @throws Error if the segment is invalid
+   */
+  function validateSegment(name, value) {
+      if (!value || typeof value !== 'string') {
+          throw new Error(`${name} must be a non-empty string`);
+      }
+      if (value.includes('/')) {
+          throw new Error(`${name} cannot contain forward slashes (/). Got: "${value}"`);
+      }
+      if (value.trim() !== value) {
+          throw new Error(`${name} cannot start or end with whitespace. Got: "${value}"`);
+      }
+  }
+  /**
+   * Path builder for advanced use cases
+   * Provides a fluent interface for building Firestore paths
+   *
+   * @example
+   * ```typescript
+   * // Build a path step by step
+   * const builder = new PathBuilder('my-app');
+   * const path = builder.publicData('posts').build();
+   * // Returns: 'appData/my-app/publicData/posts'
+   *
+   * // With document ID
+   * const docPath = builder.publicData('posts').doc('post-123').build();
+   * // Returns: 'appData/my-app/publicData/posts/post-123'
+   * ```
+   */
+  class PathBuilder {
+      constructor(appId) {
+          this.appId = appId;
+          this.segments = ['appData'];
+          validateSegment('appId', appId);
+          this.segments.push(appId);
+      }
+      /**
+       * Add publicRead collection to path
+       */
+      publicRead(collectionName) {
+          validateSegment('collectionName', collectionName);
+          this.segments.push('publicRead', collectionName);
+          return this;
+      }
+      /**
+       * Add publicData collection to path
+       */
+      publicData(collectionName) {
+          validateSegment('collectionName', collectionName);
+          this.segments.push('publicData', collectionName);
+          return this;
+      }
+      /**
+       * Add userData collection to path
+       */
+      userData(userId, collectionName) {
+          validateSegment('userId', userId);
+          validateSegment('collectionName', collectionName);
+          this.segments.push('userData', userId, collectionName);
+          return this;
+      }
+      /**
+       * Add document ID to path
+       */
+      doc(docId) {
+          validateSegment('docId', docId);
+          this.segments.push(docId);
+          return this;
+      }
+      /**
+       * Build the final path string
+       */
+      build() {
+          return this.segments.join('/');
+      }
+  }
+  /**
+   * Common path patterns as constants for frequently used paths
+   */
+  const PATH_PATTERNS = {
+      /**
+       * Base pattern for all SeaVerse data
+       */
+      APP_DATA: 'appData',
+      /**
+       * Permission layers
+       */
+      PUBLIC_READ: 'publicRead',
+      PUBLIC_DATA: 'publicData',
+      USER_DATA: 'userData',
+  };
+
   exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
   exports.DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
   exports.DataServiceClient = DataServiceClient;
   exports.ENDPOINTS = ENDPOINTS;
+  exports.PATH_PATTERNS = PATH_PATTERNS;
+  exports.PathBuilder = PathBuilder;
   exports.getFirebaseConfig = getFirebaseConfig;
+  exports.getPublicDataDocPath = getPublicDataDocPath;
+  exports.getPublicDataPath = getPublicDataPath;
+  exports.getPublicReadDocPath = getPublicReadDocPath;
+  exports.getPublicReadPath = getPublicReadPath;
+  exports.getUserDataDocPath = getUserDataDocPath;
+  exports.getUserDataPath = getUserDataPath;
   exports.initializeWithToken = initializeWithToken;
 
 }));