@seaverse/data-service-sdk 0.5.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -3
- package/dist/index.d.ts +21 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -17,9 +17,56 @@ SeaVerse organizes your Firestore data into three permission levels:
|
|
|
17
17
|
|
|
18
18
|
| Permission Level | Path Pattern | Read Access | Write Access | Use Case |
|
|
19
19
|
|-----------------|--------------|-------------|--------------|----------|
|
|
20
|
-
| **publicRead** | `appData/{app_id}/publicRead
|
|
21
|
-
| **publicData** | `appData/{app_id}/publicData
|
|
22
|
-
| **userData** | `appData/{app_id}/userData/{user_id}
|
|
20
|
+
| **publicRead** | `appData/{app_id}/publicRead/{collection}/{docId}` | All authenticated users | Admin only | System configs, announcements, static content |
|
|
21
|
+
| **publicData** | `appData/{app_id}/publicData/{collection}/{docId}` | All authenticated users | All authenticated users | User posts, comments, shared content |
|
|
22
|
+
| **userData** | `appData/{app_id}/userData/{user_id}/{collection}/{docId}` | Owner only | Owner only | User settings, private notes, personal data |
|
|
23
|
+
|
|
24
|
+
### 🚨 CRITICAL: Firestore Path Rules (For LLM)
|
|
25
|
+
|
|
26
|
+
**Firestore path segments MUST follow these rules:**
|
|
27
|
+
|
|
28
|
+
1. **Collection paths = ODD number of segments** (1, 3, 5, 7...)
|
|
29
|
+
- Example: `appData/my-app/publicData/posts` (4 segments) ❌ WRONG!
|
|
30
|
+
- Correct: Use collection() function, Firestore handles this automatically
|
|
31
|
+
|
|
32
|
+
2. **Document paths = EVEN number of segments** (2, 4, 6, 8...)
|
|
33
|
+
- Example: `appData/my-app/publicData/posts/doc123` (5 segments) ✅ CORRECT!
|
|
34
|
+
|
|
35
|
+
3. **How to use correctly:**
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
// ✅ CORRECT - Using collection() for collection paths
|
|
39
|
+
collection(db, `appData/${appId}/publicData/posts`) // Firestore handles this as a collection
|
|
40
|
+
|
|
41
|
+
// ✅ CORRECT - Using doc() for document paths
|
|
42
|
+
doc(db, `appData/${appId}/publicData/posts/doc123`) // 5 segments (odd) = document
|
|
43
|
+
|
|
44
|
+
// ❌ WRONG - Manually counting segments
|
|
45
|
+
// Don't worry about counting! Use Firebase functions:
|
|
46
|
+
// - collection() for collections
|
|
47
|
+
// - doc() for documents
|
|
48
|
+
// - addDoc() automatically adds document ID
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
**Path Structure Examples:**
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
// Public Data (everyone can read/write)
|
|
55
|
+
const postsRef = collection(db, `appData/${appId}/publicData/posts`);
|
|
56
|
+
await addDoc(postsRef, { ...data }); // Firestore adds document ID
|
|
57
|
+
|
|
58
|
+
// User Private Data (owner only)
|
|
59
|
+
const notesRef = collection(db, `appData/${appId}/userData/${userId}/notes`);
|
|
60
|
+
await addDoc(notesRef, { ...data });
|
|
61
|
+
|
|
62
|
+
// Public Read-Only (everyone can read, admin can write)
|
|
63
|
+
const configRef = collection(db, `appData/${appId}/publicRead/config`);
|
|
64
|
+
await getDocs(configRef);
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
**The pattern is always:**
|
|
68
|
+
- `appData` → `{app_id}` → `{permission_layer}` → `{collection}` → (auto-generated doc ID)
|
|
69
|
+
- This gives you 5 segments total = document path ✅
|
|
23
70
|
|
|
24
71
|
### Required Fields
|
|
25
72
|
|
package/dist/index.d.ts
CHANGED
|
@@ -23,6 +23,27 @@ import { AxiosRequestConfig } from 'axios';
|
|
|
23
23
|
* appData/{app_id}/publicData/{collection}/{docId}
|
|
24
24
|
* appData/{app_id}/userData/{userId}/{collection}/{docId}
|
|
25
25
|
*
|
|
26
|
+
* 🚨 CRITICAL FIRESTORE PATH RULES (FOR LLM):
|
|
27
|
+
* ------------------------------------------
|
|
28
|
+
* Firestore paths have strict segment count rules:
|
|
29
|
+
* - Collection paths = ODD segments (1, 3, 5, 7...)
|
|
30
|
+
* - Document paths = EVEN segments (2, 4, 6, 8...)
|
|
31
|
+
*
|
|
32
|
+
* When using Firebase SDK, ALWAYS use these functions:
|
|
33
|
+
* - collection(db, path) - for collections (don't count segments manually)
|
|
34
|
+
* - doc(db, path) - for documents
|
|
35
|
+
* - addDoc(collectionRef, data) - automatically generates document ID
|
|
36
|
+
*
|
|
37
|
+
* Example:
|
|
38
|
+
* ```typescript
|
|
39
|
+
* // ✅ CORRECT
|
|
40
|
+
* const postsRef = collection(db, `appData/${appId}/publicData/posts`);
|
|
41
|
+
* await addDoc(postsRef, { _appId, _createdAt, _createdBy, ...yourData });
|
|
42
|
+
*
|
|
43
|
+
* // ❌ WRONG - Don't use raw string paths without collection()/doc()
|
|
44
|
+
* // await setDoc(`appData/${appId}/publicData/posts`, data); // This will fail!
|
|
45
|
+
* ```
|
|
46
|
+
*
|
|
26
47
|
* REQUIRED FIELDS FOR ALL DOCUMENTS:
|
|
27
48
|
* ---------------------------------
|
|
28
49
|
* All Firestore documents MUST include these fields:
|
package/package.json
CHANGED