moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-firestore/SKILL.md

@@ -1,326 +1,84 @@
 ---
-name: moai-platform-firestore
-description: Firebase Firestore specialist covering NoSQL patterns, real-time sync, offline caching, and Security Rules. Use when building mobile-first apps with offline support, implementing real-time listeners, or configuring Firestore security.
-version: 1.0.0
-category: platform
-updated: 2025-12-07
-status: active
-tags:
-  - firestore
-  - firebase
-  - nosql
-  - realtime
-  - offline
-  - mobile
-context7-libraries:
-  - /firebase/firebase-docs
-related-skills:
-  - moai-platform-firebase-auth
-  - moai-lang-flutter
-  - moai-lang-typescript
-allowed-tools: Read, Write, Bash, Grep, Glob
+name: "moai-platform-firestore"
+description: "Firebase Firestore specialist covering NoSQL patterns, real-time sync, offline caching, and Security Rules. Use when building mobile-first apps with offline support, implementing real-time listeners, or configuring Firestore security."
+version: 2.1.0
+category: "platform"
+modularized: true
+user-invocable: false
+tags: ['firestore', 'firebase', 'nosql', 'realtime', 'offline', 'mobile']
+updated: 2026-01-11
+status: "active"
+context7-libraries: ['/firebase/firebase-docs']
+related-skills: ['moai-platform-firebase-auth', 'moai-lang-flutter', 'moai-lang-typescript']
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
 ---
 
 # moai-platform-firestore: Firebase Firestore Specialist
 
-## Quick Reference (30 seconds)
+## Quick Reference
 
 Firebase Firestore Expertise: NoSQL document database with real-time synchronization, offline-first architecture, Security Rules, Cloud Functions triggers, and mobile-optimized SDKs.
 
 ### Core Capabilities
 
-Real-time Sync: Automatic synchronization across all connected clients
-Offline Caching: IndexedDB persistence with automatic sync when online
-Security Rules: Declarative field-level access control
-Cloud Functions: Document triggers for server-side processing
-Composite Indexes: Complex query optimization
+Real-time Sync provides automatic synchronization across all connected clients.
 
-### When to Use Firestore
-
-- Mobile-first applications with offline support
-- Real-time collaborative features
-- Cross-platform apps (iOS, Android, Web, Flutter)
-- Projects requiring Google Cloud integration
-- Apps with flexible, evolving data structures
+Offline Caching uses IndexedDB persistence with automatic sync when online.
 
-### Context7 Library Access
+Security Rules offer declarative field-level access control.
 
-```python
-docs = await mcp__context7__get_library_docs(
-    context7CompatibleLibraryID="/firebase/firebase-docs",
-    topic="firestore security-rules offline-persistence cloud-functions indexes",
-    tokens=6000
-)
-```
+Cloud Functions enable document triggers for server-side processing.
 
----
+Composite Indexes support complex query optimization.
 
-## Implementation Guide
+### When to Use Firestore
 
-### Firestore Initialization with Offline Persistence
+Use Firestore for mobile-first applications with offline support, real-time collaborative features, cross-platform apps across iOS, Android, Web, and Flutter, projects requiring Google Cloud integration, and apps with flexible evolving data structures.
 
-```typescript
-import { initializeApp } from 'firebase/app'
-import {
-  initializeFirestore,
-  persistentLocalCache,
-  persistentMultipleTabManager,
-  CACHE_SIZE_UNLIMITED
-} from 'firebase/firestore'
-
-const app = initializeApp({
-  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
-  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
-  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID
-})
-
-export const db = initializeFirestore(app, {
-  localCache: persistentLocalCache({
-    tabManager: persistentMultipleTabManager(),
-    cacheSizeBytes: CACHE_SIZE_UNLIMITED
-  })
-})
-```
-
-### Real-time Listeners with Metadata
-
-```typescript
-import { collection, query, where, orderBy, onSnapshot } from 'firebase/firestore'
-
-export function subscribeToDocuments(userId: string, callback: (docs: any[]) => void) {
-  const q = query(
-    collection(db, 'documents'),
-    where('collaborators', 'array-contains', userId),
-    orderBy('createdAt', 'desc')
-  )
-
-  return onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => {
-    callback(snapshot.docs.map((doc) => ({
-      id: doc.id,
-      ...doc.data(),
-      _pending: doc.metadata.hasPendingWrites,
-      _fromCache: doc.metadata.fromCache
-    })))
-  })
-}
-```
-
-### Security Rules
-
-Basic Structure:
-```javascript
-rules_version = '2';
-service cloud.firestore {
-  match /databases/{database}/documents {
-    match /users/{userId} {
-      allow read, write: if request.auth.uid == userId;
-    }
-
-    match /documents/{docId} {
-      allow read: if resource.data.isPublic == true
-        || request.auth.uid == resource.data.ownerId
-        || request.auth.uid in resource.data.collaborators;
-      allow create: if request.auth != null
-        && request.resource.data.ownerId == request.auth.uid;
-      allow update, delete: if request.auth.uid == resource.data.ownerId;
-    }
-  }
-}
-```
-
-Role-Based Access with Custom Claims:
-```javascript
-rules_version = '2';
-service cloud.firestore {
-  match /databases/{database}/documents {
-    function isSignedIn() { return request.auth != null; }
-    function isAdmin() { return request.auth.token.admin == true; }
-
-    match /organizations/{orgId} {
-      function isMember() {
-        return exists(/databases/$(database)/documents/organizations/$(orgId)/members/$(request.auth.uid));
-      }
-      function getMemberRole() {
-        return get(/databases/$(database)/documents/organizations/$(orgId)/members/$(request.auth.uid)).data.role;
-      }
-      function isOrgAdmin() { return isMember() && getMemberRole() in ['admin', 'owner']; }
-
-      allow read: if isSignedIn() && isMember();
-      allow update: if isOrgAdmin();
-      allow delete: if getMemberRole() == 'owner';
-
-      match /members/{memberId} {
-        allow read: if isMember();
-        allow write: if isOrgAdmin();
-      }
-
-      match /projects/{projectId} {
-        allow read: if isMember();
-        allow create: if isMember() && getMemberRole() in ['admin', 'owner', 'editor'];
-        allow update, delete: if isOrgAdmin() || resource.data.createdBy == request.auth.uid;
-      }
-    }
-  }
-}
-```
+### Context7 Documentation Access
 
-### Composite Indexes Configuration
+Step 1: Resolve the Firebase library ID using mcp__context7__resolve-library-id with libraryName "firebase" to get the Context7-compatible library ID.
 
-```json
-{
-  "indexes": [
-    {
-      "collectionGroup": "documents",
-      "queryScope": "COLLECTION",
-      "fields": [
-        { "fieldPath": "organizationId", "order": "ASCENDING" },
-        { "fieldPath": "createdAt", "order": "DESCENDING" }
-      ]
-    },
-    {
-      "collectionGroup": "documents",
-      "queryScope": "COLLECTION",
-      "fields": [
-        { "fieldPath": "tags", "arrayConfig": "CONTAINS" },
-        { "fieldPath": "createdAt", "order": "DESCENDING" }
-      ]
-    }
-  ]
-}
-```
-
-### Cloud Functions V2 Triggers
-
-```typescript
-import { onDocumentUpdated } from 'firebase-functions/v2/firestore'
-import { onCall, HttpsError } from 'firebase-functions/v2/https'
-import { onSchedule } from 'firebase-functions/v2/scheduler'
-import { getFirestore, FieldValue } from 'firebase-admin/firestore'
-
-const db = getFirestore()
-
-export const onDocumentUpdate = onDocumentUpdated(
-  { document: 'documents/{docId}', region: 'us-central1' },
-  async (event) => {
-    const before = event.data?.before.data()
-    const after = event.data?.after.data()
-    if (!before || !after) return
-
-    const batch = db.batch()
-    batch.set(db.collection('changes').doc(), {
-      documentId: event.params.docId,
-      before, after,
-      changedAt: FieldValue.serverTimestamp()
-    })
-    batch.update(db.doc('stats/documents'), {
-      totalModifications: FieldValue.increment(1)
-    })
-    await batch.commit()
-  }
-)
-
-export const inviteToOrganization = onCall({ region: 'us-central1' }, async (request) => {
-  if (!request.auth) throw new HttpsError('unauthenticated', 'Must be signed in')
-
-  const { organizationId, email, role } = request.data
-  const memberDoc = await db.doc(`organizations/${organizationId}/members/${request.auth.uid}`).get()
-
-  if (!memberDoc.exists || !['admin', 'owner'].includes(memberDoc.data()?.role)) {
-    throw new HttpsError('permission-denied', 'Must be organization admin')
-  }
-
-  const invitation = await db.collection('invitations').add({
-    organizationId, email, role,
-    invitedBy: request.auth.uid,
-    createdAt: FieldValue.serverTimestamp(),
-    status: 'pending'
-  })
-
-  return { invitationId: invitation.id }
-})
-
-export const dailyCleanup = onSchedule(
-  { schedule: '0 0 * * *', timeZone: 'UTC', region: 'us-central1' },
-  async () => {
-    const thirtyDaysAgo = new Date()
-    thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30)
-
-    const oldDocs = await db.collection('tempFiles')
-      .where('createdAt', '<', thirtyDaysAgo).limit(500).get()
-
-    const batch = db.batch()
-    oldDocs.docs.forEach((doc) => batch.delete(doc.ref))
-    await batch.commit()
-  }
-)
-```
+Step 2: Fetch Firestore documentation using mcp__context7__get-library-docs with the resolved ID. Set topic to specific areas such as "firestore security-rules", "firestore offline", or "firestore real-time". Allocate 6000 to 8000 tokens for comprehensive coverage.
 
----
+### Module Index
 
-## Advanced Patterns
+This skill is organized into specialized modules for deep implementation guidance:
 
-### Offline-First React Hook
+Security Rules Module at modules/security-rules.md covers basic rule structure and syntax, role-based access control patterns, custom claims integration, field-level validation, and testing and debugging rules.
 
-```typescript
-import { useEffect, useState } from 'react'
-import { collection, query, where, orderBy, onSnapshot, addDoc, updateDoc, doc, serverTimestamp } from 'firebase/firestore'
+Offline and Caching Module at modules/offline-cache.md covers persistent cache configuration, multi-tab manager setup, cache size optimization, sync status handling, and network state management.
 
-export function useTasks(userId: string) {
-  const [tasks, setTasks] = useState<any[]>([])
-  const [loading, setLoading] = useState(true)
+Real-time Listeners Module at modules/realtime-listeners.md covers snapshot listener patterns, metadata handling for pending writes, query subscription optimization, listener lifecycle management, and error handling strategies.
 
-  useEffect(() => {
-    if (!userId) return
-    const q = query(collection(db, 'tasks'), where('userId', '==', userId), orderBy('createdAt', 'desc'))
+Transactions Module at modules/transactions.md covers atomic batch operations, transaction patterns and constraints, distributed counter implementation, conflict resolution strategies, and performance considerations.
 
-    return onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => {
-      setTasks(snapshot.docs.map((doc) => ({
-        id: doc.id, ...doc.data(),
-        _pending: doc.metadata.hasPendingWrites,
-        _fromCache: doc.metadata.fromCache
-      })))
-      setLoading(false)
-    })
-  }, [userId])
+---
 
-  const addTask = (title: string) => addDoc(collection(db, 'tasks'), {
-    title, completed: false, userId, createdAt: serverTimestamp()
-  })
+## Implementation Guide
 
-  const toggleTask = (taskId: string, completed: boolean) =>
-    updateDoc(doc(db, 'tasks', taskId), { completed, updatedAt: serverTimestamp() })
+### Firestore Initialization with Offline Persistence
 
-  return { tasks, loading, addTask, toggleTask }
-}
-```
+Import initializeApp from firebase/app and initializeFirestore, persistentLocalCache, persistentMultipleTabManager, and CACHE_SIZE_UNLIMITED from firebase/firestore. Create the app with initializeApp passing the config object containing apiKey, authDomain, and projectId from environment variables. Export the db instance created with initializeFirestore, passing the app and a localCache configuration using persistentLocalCache with tabManager set to persistentMultipleTabManager() and cacheSizeBytes set to CACHE_SIZE_UNLIMITED.
 
-### Batch Operations and Transactions
+### Basic Security Rules Structure
 
-```typescript
-import { writeBatch, runTransaction, doc, increment } from 'firebase/firestore'
+Define Security Rules using rules_version 2 and service cloud.firestore. In the databases match block, create a users collection match with userId wildcard allowing read and write if request.auth.uid equals userId. Create a documents collection match with docId wildcard. Allow read if the document isPublic field is true, or if request.auth.uid equals the ownerId field, or if request.auth.uid is in the collaborators array. Allow create if request.auth is not null and the new document ownerId equals request.auth.uid. Allow update and delete if request.auth.uid equals the document ownerId.
 
-async function batchUpdate(updates: Array<{ id: string; data: any }>) {
-  const batch = writeBatch(db)
-  updates.forEach(({ id, data }) => {
-    batch.update(doc(db, 'documents', id), { ...data, updatedAt: serverTimestamp() })
-  })
-  await batch.commit()
-}
+### Real-time Listener with Metadata
 
-async function transferCredits(fromUserId: string, toUserId: string, amount: number) {
-  await runTransaction(db, async (transaction) => {
-    const fromRef = doc(db, 'users', fromUserId)
-    const toRef = doc(db, 'users', toUserId)
-    const fromDoc = await transaction.get(fromRef)
+Import collection, query, where, orderBy, and onSnapshot from firebase/firestore. Create a subscribeToDocuments function taking userId and a callback. Build a query on the documents collection filtering where collaborators array-contains userId and ordering by createdAt descending. Call onSnapshot with the query, includeMetadataChanges set to true, and a callback that maps snapshot.docs to objects containing id, document data spread, _pending set to doc.metadata.hasPendingWrites, and _fromCache set to doc.metadata.fromCache. Return the unsubscribe function.
 
-    if (!fromDoc.exists()) throw new Error('Sender not found')
-    if (fromDoc.data().credits < amount) throw new Error('Insufficient credits')
+### Composite Indexes Configuration
 
-    transaction.update(fromRef, { credits: increment(-amount) })
-    transaction.update(toRef, { credits: increment(amount) })
-  })
-}
-```
+Define indexes in firestore.indexes.json with an indexes array. Each index object specifies collectionGroup, queryScope as COLLECTION, and a fields array. Fields specify fieldPath and either order as ASCENDING or DESCENDING, or arrayConfig as CONTAINS for array fields. Create indexes for common query patterns such as organizationId with createdAt descending, or tags array with createdAt descending.
 
 ---
 
@@ -328,31 +86,42 @@ async function transferCredits(fromUserId: string, toUserId: string, amount: num
 
 ### Performance Characteristics
 
-Read Latency: 50-200ms (varies by region)
-Write Latency: 100-300ms
-Real-time Propagation: 100-500ms
-Offline Sync: Automatic on reconnection
+Read Latency ranges from 50 to 200 milliseconds depending on region.
+
+Write Latency ranges from 100 to 300 milliseconds.
+
+Real-time Propagation takes 100 to 500 milliseconds.
+
+Offline Sync occurs automatically on reconnection.
 
 ### Free Tier (2024)
 
-Storage: 1GB
-Daily Reads: 50,000
-Daily Writes: 20,000
-Daily Deletes: 20,000
+Storage: 1GB. Daily Reads: 50,000. Daily Writes: 20,000. Daily Deletes: 20,000.
 
 ---
 
 ## Works Well With
 
-- moai-platform-firebase-auth - Firebase Authentication integration
-- moai-lang-flutter - Flutter SDK patterns
-- moai-lang-typescript - TypeScript client patterns
-- moai-domain-mobile - Mobile architecture patterns
-- moai-quality-security - Security Rules best practices
+- moai-platform-firebase-auth for Firebase Authentication integration
+- moai-lang-flutter for Flutter SDK patterns
+- moai-lang-typescript for TypeScript client patterns
+- moai-domain-mobile for mobile architecture patterns
+- moai-quality-security for Security Rules best practices
+
+---
+
+## Additional Resources
+
+- reference.md provides extended documentation and best practices
+- examples.md provides complete working code examples
+- modules/security-rules.md provides Security Rules deep dive
+- modules/offline-cache.md covers offline persistence patterns
+- modules/realtime-listeners.md covers real-time subscription patterns
+- modules/transactions.md covers batch and transaction operations
 
 ---
 
 Status: Production Ready
 Generated with: MoAI-ADK Skill Factory v2.0
-Last Updated: 2025-12-07
+Last Updated: 2026-01-11
 Platform: Firebase Firestore