@seaverse/data-service-sdk 0.9.0 → 0.10.1

package/dist/index.d.ts

@@ -16,14 +16,14 @@ export { CollectionReference, DocumentData, DocumentReference, DocumentSnapshot,
  * 2. publicData/   - Read-write public data (e.g., user-generated content)
  *                    Read: All authenticated users | Write: All authenticated users
  *
- * 3. userData/{userId}/ - Private user data (e.g., personal settings, private notes)
+ * 3. userData/{userId}/_data/ - Private user data (e.g., personal settings, private notes)
  *                    Read: Owner only | Write: Owner only
  *
  * DATA PATH STRUCTURE:
  * -------------------
- * appData/{app_id}/publicRead/{collection}/{docId}
- * appData/{app_id}/publicData/{collection}/{docId}
- * appData/{app_id}/userData/{userId}/{collection}/{docId}
+ * appData/{app_id}/publicRead/_data/{collection}/{docId}
+ * appData/{app_id}/publicData/_data/{collection}/{docId}
+ * appData/{app_id}/userData/{userId}/_data/{collection}/{docId}
  *
  * 🚨 CRITICAL FIRESTORE PATH RULES (FOR LLM):
  * ------------------------------------------
@@ -260,9 +260,9 @@ interface DataServiceClientOptions {
  * ---------------------------
  * 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:
  * -------------------
@@ -314,7 +314,7 @@ interface DataServiceClientOptions {
  * 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
@@ -544,22 +544,33 @@ declare 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);
      * ```
      */
-    getPublicData(collectionName: string): Promise<QuerySnapshot>;
+    getPublicData(collectionName: string, includeDeleted?: boolean): Promise<QuerySnapshot>;
     /**
      * 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
@@ -570,7 +581,7 @@ declare class FirestoreHelper {
      * });
      * ```
      */
-    getUserData(collectionName: string): Promise<QuerySnapshot>;
+    getUserData(collectionName: string, includeDeleted?: boolean): Promise<QuerySnapshot>;
     /**
      * Get all documents from publicRead collection (read-only for users)
      *
@@ -638,10 +649,43 @@ declare class FirestoreHelper {
      */
     updateDoc(collectionPath: string, docId: string, data: Record<string, any>): Promise<void>;
     /**
-     * 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'
+     * );
+     * ```
+     */
+    softDeleteDoc(collectionPath: string, docId: string): Promise<void>;
+    /**
+     * 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'
+     * );
+     * ```
      */
     deleteDoc(collectionPath: string, docId: string): Promise<void>;
     /**
@@ -668,6 +712,7 @@ declare class FirestoreHelper {
     private addDocWithMeta;
     /**
      * Internal: Get all documents from collection
+     * Optionally filter out soft-deleted documents
      */
     private getDocs;
     /**
@@ -868,7 +913,7 @@ declare function getPublicDataPath(appId: string, collectionName: string): strin
  * ```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,
@@ -925,7 +970,7 @@ declare function getPublicDataDocPath(appId: string, collectionName: string, doc
  * @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));
  * ```
@@ -988,5 +1033,149 @@ declare const PATH_PATTERNS: {
     readonly USER_DATA: "userData";
 };
 
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DataServiceClient, ENDPOINTS, FirestoreHelper, PATH_PATTERNS, PathBuilder, addDocWithMeta, getFirebaseConfig, getPublicDataDocPath, getPublicDataPath, getPublicReadDocPath, getPublicReadPath, getUserDataDocPath, getUserDataPath, initializeWithToken, updateDocWithMeta };
-export type { ApiError, ApiResponse, DataServiceClientOptions, FirebaseConfig, FirestoreTokenResponse, GenerateFirestoreTokenRequest, GenerateGuestFirestoreTokenRequest };
+/**
+ * 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
+ */
+declare const MAX_DOCUMENT_SIZE = 262144;
+/**
+ * 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)
+ */
+declare const ALLOWED_RESERVED_FIELDS: string[];
+/**
+ * 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"
+ * ```
+ */
+declare function validateReservedFields(data: Record<string, any>): void;
+/**
+ * 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');
+ * ```
+ */
+declare function estimateDocumentSize(data: Record<string, any>): number;
+/**
+ * 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
+ * ```
+ */
+declare function validateDocumentSize(data: Record<string, any>): void;
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare function validateFirestoreData(data: Record<string, any>): void;
+/**
+ * Check if data contains soft-delete markers
+ *
+ * @param data - Data object to check
+ * @returns True if document is marked as deleted
+ */
+declare function isDeleted(data: Record<string, any>): boolean;
+/**
+ * Validation result for detailed error reporting
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * 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
+ * }
+ * ```
+ */
+declare function validateDataDetailed(data: Record<string, any>): ValidationResult;
+
+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 };
+export type { ApiError, ApiResponse, DataServiceClientOptions, FirebaseConfig, FirestoreTokenResponse, GenerateFirestoreTokenRequest, GenerateGuestFirestoreTokenRequest, ValidationResult };