@seaverse/data-service-sdk 0.5.2 → 0.6.0

package/dist/index.cjs

@@ -355,10 +355,272 @@ async function initializeWithToken(tokenResponse) {
     };
 }
 
+/**
+ * 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;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/config.ts","../src/client.ts","../src/helpers.ts"],"sourcesContent":[null,null,null],"names":[],"mappings":"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"}
+{"version":3,"file":"index.cjs","sources":["../src/config.ts","../src/client.ts","../src/helpers.ts","../src/path-helpers.ts"],"sourcesContent":[null,null,null,null],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -518,5 +518,190 @@ declare function initializeWithToken(tokenResponse: FirestoreTokenResponse): Pro
     appId: string;
 }>;
 
-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));
+ * ```
+ */
+declare function getPublicReadPath(appId: string, collectionName: string): string;
+/**
+ * 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'
+ * });
+ * ```
+ */
+declare function getPublicDataPath(appId: string, collectionName: string): string;
+/**
+ * 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'
+ * });
+ * ```
+ */
+declare function getUserDataPath(appId: string, userId: string, collectionName: string): string;
+/**
+ * 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));
+ * ```
+ */
+declare function getPublicReadDocPath(appId: string, collectionName: string, docId: string): string;
+/**
+ * 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));
+ * ```
+ */
+declare function getPublicDataDocPath(appId: string, collectionName: string, docId: string): string;
+/**
+ * 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));
+ * ```
+ */
+declare function getUserDataDocPath(appId: string, userId: string, collectionName: string, docId: string): string;
+/**
+ * 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'
+ * ```
+ */
+declare class PathBuilder {
+    private appId;
+    private segments;
+    constructor(appId: string);
+    /**
+     * Add publicRead collection to path
+     */
+    publicRead(collectionName: string): this;
+    /**
+     * Add publicData collection to path
+     */
+    publicData(collectionName: string): this;
+    /**
+     * Add userData collection to path
+     */
+    userData(userId: string, collectionName: string): this;
+    /**
+     * Add document ID to path
+     */
+    doc(docId: string): this;
+    /**
+     * Build the final path string
+     */
+    build(): string;
+}
+/**
+ * Common path patterns as constants for frequently used paths
+ */
+declare const PATH_PATTERNS: {
+    /**
+     * Base pattern for all SeaVerse data
+     */
+    readonly APP_DATA: "appData";
+    /**
+     * Permission layers
+     */
+    readonly PUBLIC_READ: "publicRead";
+    readonly PUBLIC_DATA: "publicData";
+    readonly USER_DATA: "userData";
+};
+
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, PATH_PATTERNS, PathBuilder, getFirebaseConfig, getPublicDataDocPath, getPublicDataPath, getPublicReadDocPath, getPublicReadPath, getUserDataDocPath, getUserDataPath, initializeWithToken };
 export type { ApiError, ApiResponse, DataServiceClientOptions, FirebaseConfig, FirestoreTokenResponse, GenerateFirestoreTokenRequest, GenerateGuestFirestoreTokenRequest };