@seaverse/data-service-sdk 0.10.2 → 0.11.1

package/README.md

@@ -53,7 +53,7 @@ SeaVerse organizes your Firestore data into three permission levels:
 |-----------------|--------------|-------------|--------------|----------|
 | **publicRead** | `appData/{app_id}/publicRead/_data/{collection}/{docId}` | All authenticated users | Admin only | System configs, announcements, static content |
 | **publicData** | `appData/{app_id}/publicData/_data/{collection}/{docId}` | All authenticated users | All authenticated users | User posts, comments, shared content |
-| **userData** | `appData/{app_id}/userData/{user_id}/_data/{collection}/{docId}` | Owner only | Owner only | User settings, private notes, personal data |
+| **userData** | `appData/{app_id}/userData/{user_id}/{collection}/{docId}` | Owner only | Owner only | User settings, private notes, personal data |
 
 ### 🚨 CRITICAL: Firestore Path Rules (For LLM)
 
@@ -88,7 +88,7 @@ const postsRef = collection(db, `appData/${appId}/publicData/_data/posts`);
 await addDoc(postsRef, { ...data });  // Firestore adds document ID
 
 // User Private Data (owner only)
-const notesRef = collection(db, `appData/${appId}/userData/${userId}/_data/notes`);
+const notesRef = collection(db, `appData/${appId}/userData/${userId}/notes`);
 await addDoc(notesRef, { ...data });
 
 // Public Read-Only (everyone can read, admin can write)
@@ -97,9 +97,9 @@ await getDocs(configRef);
 ```
 
 **The pattern is always:**
-- `appData` → `{app_id}` → `{permission_layer}` → (`{user_id}` for userData) → `_data` → `{collection}` → (auto-generated doc ID)
+- `appData` → `{app_id}` → `{permission_layer}` → `_data` (for publicRead/publicData) OR `{user_id}` (for userData) → `{collection}` → (auto-generated doc ID)
 - publicRead/publicData Collection: 5 segments (odd) ✅
-- userData Collection: 6 segments (even) ✅ (includes userId)
+- userData Collection: 5 segments (odd) ✅ (userId replaces _data segment)
 - Document paths: add 1 more segment for docId
 
 ### Required Fields
@@ -383,6 +383,23 @@ await helper.addToUserData('notes', {
   title: 'Private Note',
   content: 'Only I can see this'
 });
+
+// ✅ NEW in v0.11.0: Simple Pagination Support
+// Get first 20 posts
+const first20 = await helper.getPublicData('posts', false, { limit: 20 });
+first20.forEach(doc => {
+  console.log(doc.id, doc.data());
+});
+
+// Get next page after last document
+const lastDoc = first20.docs[first20.docs.length - 1];
+const next20 = await helper.getPublicData('posts', false, {
+  limit: 20,
+  startAfter: lastDoc
+});
+
+// Also works with getUserData
+const first10Notes = await helper.getUserData('notes', false, { limit: 10 });
 ```
 
 <details>
@@ -717,7 +734,7 @@ const comments = await getDocs(
 
 ```typescript
 // Only the user can write to their own settings
-await setDoc(doc(db, `appData/${appId}/userData/${userId}/_data/settings/preferences`), {
+await setDoc(doc(db, `appData/${appId}/userData/${userId}/settings/preferences`), {
   _appId: appId,
   _createdAt: serverTimestamp(),
   _createdBy: userId,
@@ -728,7 +745,7 @@ await setDoc(doc(db, `appData/${appId}/userData/${userId}/_data/settings/prefere
 
 // Only the user can read their own settings
 const settings = await getDoc(
-  doc(db, `appData/${appId}/userData/${userId}/_data/settings/preferences`)
+  doc(db, `appData/${appId}/userData/${userId}/settings/preferences`)
 );
 ```
 
@@ -1230,7 +1247,7 @@ async function completeExample() {
 
   // 7. Save user preferences (private)
   await addDoc(
-    collection(db, `appData/${appId}/userData/${userId}/_data/preferences`),
+    collection(db, `appData/${appId}/userData/${userId}/preferences`),
     {
       _appId: appId,
       _createdAt: serverTimestamp(),
@@ -1316,4 +1333,4 @@ Here's a complete example for using the SDK directly in the browser without any
 ## Related SDKs
 
 - [@seaverse/auth-sdk](../auth-sdk) - User authentication and account management
-- [@seaverse/payment-sdk](../payment-sdk) - Payment processing integration
+- [@seaverse/assets-sdk](../assets-sdk) - Assets and payment processing integration

package/dist/browser.js

@@ -4248,7 +4248,7 @@ function getPublicDataPath(appId, collectionName) {
  * ```typescript
  * // Write private user notes
  * const path = getUserDataPath('my-app', 'user-123', 'notes');
- * // Returns: 'appData/my-app/userData/user-123/_data/notes'
+ * // Returns: 'appData/my-app/userData/user-123/notes'
  *
  * await addDoc(collection(db, path), {
  *   _appId: appId,
@@ -4262,7 +4262,7 @@ function getUserDataPath(appId, userId, collectionName) {
     validateSegment('appId', appId);
     validateSegment('userId', userId);
     validateSegment('collectionName', collectionName);
-    return `appData/${appId}/userData/${userId}/_data/${collectionName}`;
+    return `appData/${appId}/userData/${userId}/${collectionName}`;
 }
 /**
  * Generate path for a specific document in publicRead
@@ -4320,7 +4320,7 @@ function getPublicDataDocPath(appId, collectionName, docId) {
  * @example
  * ```typescript
  * const path = getUserDataDocPath('my-app', 'user-123', 'notes', 'note-456');
- * // Returns: 'appData/my-app/userData/user-123/_data/notes/note-456'
+ * // Returns: 'appData/my-app/userData/user-123/notes/note-456'
  *
  * const docSnap = await getDoc(doc(db, path));
  * ```
@@ -4330,7 +4330,7 @@ function getUserDataDocPath(appId, userId, collectionName, docId) {
     validateSegment('userId', userId);
     validateSegment('collectionName', collectionName);
     validateSegment('docId', docId);
-    return `appData/${appId}/userData/${userId}/_data/${collectionName}/${docId}`;
+    return `appData/${appId}/userData/${userId}/${collectionName}/${docId}`;
 }
 /**
  * Validate a path segment to ensure it doesn't contain invalid characters
@@ -4395,7 +4395,7 @@ class PathBuilder {
     userData(userId, collectionName) {
         validateSegment('userId', userId);
         validateSegment('collectionName', collectionName);
-        this.segments.push('userData', userId, '_data', collectionName);
+        this.segments.push('userData', userId, collectionName);
         return this;
     }
     /**
@@ -4782,6 +4782,7 @@ class FirestoreHelper {
      *
      * @param collectionName - Collection name
      * @param includeDeleted - Include soft-deleted documents (default: false)
+     * @param options - Optional query options (limit, startAfter)
      * @returns QuerySnapshot with documents
      *
      * @example
@@ -4794,11 +4795,21 @@ class FirestoreHelper {
      *
      * // Include deleted posts (admin use case)
      * const allPosts = await helper.getPublicData('posts', true);
+     *
+     * // Get first 20 posts (simple pagination)
+     * const first20 = await helper.getPublicData('posts', false, { limit: 20 });
+     *
+     * // Get next page after last document
+     * const lastDoc = first20.docs[first20.docs.length - 1];
+     * const next20 = await helper.getPublicData('posts', false, {
+     *   limit: 20,
+     *   startAfter: lastDoc
+     * });
      * ```
      */
-    async getPublicData(collectionName, includeDeleted = false) {
+    async getPublicData(collectionName, includeDeleted = false, options) {
         const path = getPublicDataPath(this.appId, collectionName);
-        return this.getDocs(path, includeDeleted);
+        return this.getDocs(path, includeDeleted, options);
     }
     /**
      * Get all documents from userData collection (user's private data)
@@ -4807,6 +4818,7 @@ class FirestoreHelper {
      *
      * @param collectionName - Collection name
      * @param includeDeleted - Include soft-deleted documents (default: false)
+     * @param options - Optional query options (limit, startAfter)
      * @returns QuerySnapshot with documents
      *
      * @example
@@ -4815,11 +4827,14 @@ class FirestoreHelper {
      * snapshot.forEach(doc => {
      *   console.log('My note:', doc.data());
      * });
+     *
+     * // Get first 10 notes with pagination
+     * const first10 = await helper.getUserData('notes', false, { limit: 10 });
      * ```
      */
-    async getUserData(collectionName, includeDeleted = false) {
+    async getUserData(collectionName, includeDeleted = false, options) {
         const path = getUserDataPath(this.appId, this.userId, collectionName);
-        return this.getDocs(path, includeDeleted);
+        return this.getDocs(path, includeDeleted, options);
     }
     /**
      * Get all documents from publicRead collection (read-only for users)
@@ -5004,21 +5019,36 @@ class FirestoreHelper {
     /**
      * Internal: Get all documents from collection
      * Optionally filter out soft-deleted documents
+     * Supports pagination with limit and startAfter options
      */
-    async getDocs(collectionPath, includeDeleted = false) {
-        const { getDocs, collection, query, where } = await this.loadFirestore();
+    async getDocs(collectionPath, includeDeleted = false, options) {
+        const { getDocs, collection, query, where, limit, startAfter } = await this.loadFirestore();
         const colRef = collection(this.db, collectionPath);
-        if (includeDeleted) {
-            // Return all documents (including soft-deleted)
-            return getDocs(colRef);
-        }
-        else {
+        // Build query constraints
+        const constraints = [];
+        // Add soft-delete filter if needed
+        if (!includeDeleted) {
             // Filter out soft-deleted documents
             // Use '!=' to include documents without _deleted field (new documents)
             // This will return documents where _deleted is missing, null, undefined, or false
-            const q = query(colRef, where('_deleted', '!=', true));
+            constraints.push(where('_deleted', '!=', true));
+        }
+        // Add pagination options if provided
+        if (options?.startAfter) {
+            constraints.push(startAfter(options.startAfter));
+        }
+        if (options?.limit) {
+            constraints.push(limit(options.limit));
+        }
+        // Execute query
+        if (constraints.length > 0) {
+            const q = query(colRef, ...constraints);
             return getDocs(q);
         }
+        else {
+            // No constraints, return all documents
+            return getDocs(colRef);
+        }
     }
     /**
      * Internal: Get collection reference
@@ -5047,7 +5077,8 @@ class FirestoreHelper {
             query: firestore.query,
             where: firestore.where,
             orderBy: firestore.orderBy,
-            limit: firestore.limit
+            limit: firestore.limit,
+            startAfter: firestore.startAfter
         };
     }
 }