@seaverse/data-service-sdk 0.5.2 → 0.6.0

package/README.md

@@ -10,6 +10,7 @@ SeaVerse Data Service SDK for accessing Firestore with secure token management a
 - 🔒 Automatic data isolation by app_id
 - 📝 TypeScript support with full type definitions
 - 🤖 LLM-friendly documentation with clear examples
+- 🛡️ Path helper functions to prevent permission-denied errors
 
 ## Three-Tier Permission Model
 
@@ -130,12 +131,116 @@ const { DataServiceClient } = require('@seaverse/data-service-sdk');
 import { DataServiceClient } from '@seaverse/data-service-sdk';
 ```
 
+## Path Helper Functions (🚨 Recommended for LLM)
+
+To prevent `permission-denied` errors caused by incorrect paths, we provide helper functions that generate the correct Firestore paths automatically.
+
+### Why Use Path Helpers?
+
+**Problem**: LLM or developers might accidentally use wrong paths:
+```typescript
+// ❌ WRONG - Will cause permission-denied!
+collection(db, `apps/${appId}/publicArticles`)  // Not matching security rules!
+collection(db, `apps/${appId}/users/${userId}/articles`)  // Not matching security rules!
+```
+
+**Solution**: Use path helper functions:
+```typescript
+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
+```
+
+### Available Path Helpers
+
+```typescript
+import {
+  getPublicReadPath,      // For read-only public data
+  getPublicDataPath,      // For public read/write data
+  getUserDataPath,        // For private user data
+  getPublicReadDocPath,   // For specific public document
+  getPublicDataDocPath,   // For specific public data document
+  getUserDataDocPath,     // For specific user document
+  PathBuilder             // For advanced path building
+} from '@seaverse/data-service-sdk';
+```
+
+### Basic Usage Examples
+
+```typescript
+// Public data that everyone can read/write
+const postsPath = getPublicDataPath(appId, 'posts');
+await addDoc(collection(db, postsPath), {
+  _appId: appId,
+  _createdAt: serverTimestamp(),
+  _createdBy: userId,
+  title: 'My Post'
+});
+
+// Private user data
+const notesPath = getUserDataPath(appId, userId, 'notes');
+await addDoc(collection(db, notesPath), {
+  _appId: appId,
+  _createdAt: serverTimestamp(),
+  _createdBy: userId,
+  content: 'Private note'
+});
+
+// Public read-only data (admin writes only)
+const configPath = getPublicReadPath(appId, 'config');
+const configs = await getDocs(collection(db, configPath));
+
+// Access specific document
+const docPath = getPublicDataDocPath(appId, 'posts', 'post-123');
+const docSnap = await getDoc(doc(db, docPath));
+```
+
+### Advanced: PathBuilder
+
+For complex path construction:
+
+```typescript
+import { PathBuilder } from '@seaverse/data-service-sdk';
+
+const builder = new PathBuilder(appId);
+
+// Build collection path
+const path = builder.publicData('posts').build();
+// Returns: 'appData/my-app/publicData/posts'
+
+// Build document path
+const docPath = builder.publicData('posts').doc('post-123').build();
+// Returns: 'appData/my-app/publicData/posts/post-123'
+
+// Build user data path
+const userPath = builder.userData(userId, 'notes').build();
+// Returns: 'appData/my-app/userData/user-123/notes'
+```
+
+### Error Prevention
+
+Path helpers validate inputs to prevent common mistakes:
+
+```typescript
+// ❌ These will throw errors:
+getPublicDataPath('my-app', 'posts/comments');  // Error: cannot contain /
+getPublicDataPath('my-app', '');  // Error: must be non-empty string
+getUserDataPath('my-app', '', 'notes');  // Error: userId must be non-empty
+```
+
 ## Quick Start
 
 ### 🚀 Easiest Way (Recommended - Auto Firebase Setup)
 
 ```typescript
-import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
+import {
+  DataServiceClient,
+  initializeWithToken,
+  getPublicDataPath,  // 🛡️ Use path helpers!
+  getUserDataPath     // 🛡️ Use path helpers!
+} from '@seaverse/data-service-sdk';
 import { AuthClient } from '@seaverse/auth-sdk';
 import { collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
 
@@ -156,10 +261,11 @@ const tokenResponse = await dataClient.generateFirestoreToken({
 // Step 3: Auto-initialize Firebase (ONE LINE!)
 const { db, appId, userId } = await initializeWithToken(tokenResponse);
 
-// Step 4: Use Firestore directly!
+// Step 4: Use Firestore directly with path helpers!
 
 // Write to publicData (everyone can write)
-await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
+const postsPath = getPublicDataPath(appId, 'posts');  // 🛡️ Safe path!
+await addDoc(collection(db, postsPath), {
   _appId: appId,              // REQUIRED
   _createdAt: serverTimestamp(), // REQUIRED
   _createdBy: userId,         // REQUIRED
@@ -168,13 +274,14 @@ await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
 });
 
 // Read from publicData
-const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
+const snapshot = await getDocs(collection(db, postsPath));
 snapshot.forEach(doc => {
   console.log(doc.id, doc.data());
 });
 
 // Write to userData (private)
-await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
+const notesPath = getUserDataPath(appId, userId, 'notes');  // 🛡️ Safe path!
+await addDoc(collection(db, notesPath), {
   _appId: appId,              // REQUIRED
   _createdAt: serverTimestamp(), // REQUIRED
   _createdBy: userId,         // REQUIRED
@@ -186,7 +293,11 @@ await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
 ### 👤 For Guest Users (Even Simpler!)
 
 ```typescript
-import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
+import {
+  DataServiceClient,
+  initializeWithToken,
+  getPublicDataPath  // 🛡️ Use path helpers!
+} from '@seaverse/data-service-sdk';
 import { collection, addDoc, serverTimestamp } from 'firebase/firestore';
 
 // Step 1: Get guest token (no authentication needed!)
@@ -199,7 +310,8 @@ const tokenResponse = await dataClient.generateGuestFirestoreToken({
 const { db, appId, userId } = await initializeWithToken(tokenResponse);
 
 // Step 3: Guest can write to publicData
-await addDoc(collection(db, `appData/${appId}/publicData/comments`), {
+const commentsPath = getPublicDataPath(appId, 'comments');  // 🛡️ Safe path!
+await addDoc(collection(db, commentsPath), {
   _appId: appId,
   _createdAt: serverTimestamp(),
   _createdBy: userId,  // Guest user ID (e.g., 'guest-abc123')
@@ -566,7 +678,19 @@ import type {
 
 When using this SDK with LLM-generated code:
 
-1. **Always include required fields:**
+1. **🛡️ MOST IMPORTANT: Use path helper functions to avoid permission-denied errors:**
+   ```typescript
+   import { getPublicDataPath, getUserDataPath } from '@seaverse/data-service-sdk';
+
+   // ✅ CORRECT - Use helpers
+   const path = getPublicDataPath(appId, 'posts');
+   await addDoc(collection(db, path), { ... });
+
+   // ❌ WRONG - Manual paths may be incorrect
+   await addDoc(collection(db, `apps/${appId}/posts`), { ... });
+   ```
+
+2. **Always include required fields:**
    ```typescript
    {
      _appId: appId,              // From token response
@@ -575,16 +699,26 @@ When using this SDK with LLM-generated code:
    }
    ```
 
-2. **Use correct data paths:**
-   - publicRead: `appData/${appId}/publicRead/{collection}/{docId}`
-   - publicData: `appData/${appId}/publicData/{collection}/{docId}`
-   - userData: `appData/${appId}/userData/${userId}/{collection}/{docId}`
+3. **Use correct data paths with helpers:**
+   ```typescript
+   // Use path helpers instead of manual strings!
+   import { getPublicReadPath, getPublicDataPath, getUserDataPath } from '@seaverse/data-service-sdk';
+
+   // publicRead
+   const configPath = getPublicReadPath(appId, 'config');
+
+   // publicData
+   const postsPath = getPublicDataPath(appId, 'posts');
+
+   // userData
+   const notesPath = getUserDataPath(appId, userId, 'notes');
+   ```
 
-3. **Handle token expiration:**
+4. **Handle token expiration:**
    - Tokens expire after 1 hour (3600 seconds)
    - Check `expires_in` field and refresh when needed
 
-4. **Use serverTimestamp() for timestamps:**
+5. **Use serverTimestamp() for timestamps:**
    ```typescript
    import { serverTimestamp } from 'firebase/firestore';
 
@@ -593,7 +727,7 @@ When using this SDK with LLM-generated code:
    }
    ```
 
-5. **Separate guest and authenticated flows:**
+6. **Separate guest and authenticated flows:**
    - Use `generateGuestFirestoreToken()` for anonymous users
    - Use `generateFirestoreToken()` for logged-in users
 

package/dist/browser.js

@@ -4263,5 +4263,259 @@ async function initializeWithToken(tokenResponse) {
     };
 }
 
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, getFirebaseConfig, initializeWithToken };
+/**
+ * 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',
+};
+
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, PATH_PATTERNS, PathBuilder, getFirebaseConfig, getPublicDataDocPath, getPublicDataPath, getPublicReadDocPath, getPublicReadPath, getUserDataDocPath, getUserDataPath, initializeWithToken };
 //# sourceMappingURL=browser.js.map