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

moai_adk/templates/.claude/skills/moai-platform-convex/reference.md

@@ -0,0 +1,385 @@
+# Convex Platform Reference
+
+Extended documentation, API reference, and deployment guidance for Convex applications.
+
+---
+
+## Convex CLI Reference
+
+### Development Commands
+
+```bash
+# Start development server
+npx convex dev
+
+# Deploy to production
+npx convex deploy
+
+# Run specific function
+npx convex run functions/documents:list
+
+# Generate types
+npx convex codegen
+```
+
+### Environment Management
+
+```bash
+# Set environment variable
+npx convex env set OPENAI_API_KEY sk-...
+
+# List environment variables
+npx convex env list
+
+# Remove environment variable
+npx convex env unset OPENAI_API_KEY
+```
+
+### Database Operations
+
+```bash
+# Export data
+npx convex export --path ./backup
+
+# Import data
+npx convex import --path ./backup
+
+# Clear all data (development only)
+npx convex dev --clear
+```
+
+---
+
+## Schema Reference
+
+### Validator Types
+
+Primitive Validators:
+- v.string() - String values
+- v.number() - Floating point numbers
+- v.boolean() - Boolean values
+- v.null() - Null value
+- v.int64() - 64-bit integer
+- v.bytes() - Binary data
+
+Complex Validators:
+- v.array(validator) - Array of specified type
+- v.object({...}) - Object with specified fields
+- v.union(...validators) - One of multiple types
+- v.optional(validator) - Optional field
+- v.literal(value) - Exact value match
+- v.any() - Any value (use sparingly)
+
+Reference Validators:
+- v.id('tableName') - Document ID reference
+
+### Index Types
+
+Standard Index:
+```typescript
+defineTable({...})
+  .index('index_name', ['field1', 'field2'])
+```
+
+Search Index:
+```typescript
+defineTable({...})
+  .searchIndex('search_name', {
+    searchField: 'content',
+    filterFields: ['category', 'status']
+  })
+```
+
+---
+
+## Query Builder Reference
+
+### Query Methods
+
+```typescript
+// Basic query
+ctx.db.query('tableName')
+
+// With index
+.withIndex('index_name', (q) => q.eq('field', value))
+
+// Ordering
+.order('asc')  // or 'desc'
+
+// Collect results
+.collect()  // Returns array
+
+// Get first result
+.first()  // Returns single document or null
+
+// Pagination
+.paginate(paginationOpts)
+
+// Take limited results
+.take(10)
+```
+
+### Index Query Operators
+
+```typescript
+// Equality
+q.eq('field', value)
+
+// Greater than / less than
+q.gt('field', value)
+q.gte('field', value)
+q.lt('field', value)
+q.lte('field', value)
+
+// Chaining (compound index)
+q.eq('field1', value1).eq('field2', value2)
+```
+
+### Search Query Operators
+
+```typescript
+// Full-text search
+q.search('fieldName', 'search terms')
+
+// With filters
+q.search('content', 'query').eq('isPublic', true)
+```
+
+---
+
+## React Hooks Reference
+
+### useQuery
+
+```typescript
+// Basic usage
+const data = useQuery(api.module.queryName, { arg1: 'value' })
+
+// Returns undefined while loading
+// Returns null if query returns null
+// Returns data when loaded
+
+// Conditional query (skip)
+const data = useQuery(
+  api.module.queryName,
+  condition ? { arg: value } : 'skip'
+)
+```
+
+### useMutation
+
+```typescript
+// Basic usage
+const mutation = useMutation(api.module.mutationName)
+await mutation({ arg1: 'value' })
+
+// With optimistic update
+const mutation = useMutation(api.module.mutationName)
+  .withOptimisticUpdate((localStore, args) => {
+    // Update local cache
+  })
+```
+
+### usePaginatedQuery
+
+```typescript
+const { results, status, loadMore } = usePaginatedQuery(
+  api.module.paginatedQuery,
+  { arg: value },
+  { initialNumItems: 10 }
+)
+
+// status: 'LoadingFirstPage' | 'CanLoadMore' | 'LoadingMore' | 'Exhausted'
+// loadMore: (numItems: number) => void
+```
+
+### useAction
+
+```typescript
+const action = useAction(api.module.actionName)
+const result = await action({ arg: value })
+```
+
+---
+
+## Function Context Reference
+
+### Query Context (ctx)
+
+```typescript
+ctx.db          // Database access
+ctx.auth        // Authentication
+ctx.storage     // File storage (read-only in queries)
+```
+
+### Mutation Context (ctx)
+
+```typescript
+ctx.db          // Database access (read/write)
+ctx.auth        // Authentication
+ctx.storage     // File storage (read/write)
+ctx.scheduler   // Schedule functions
+```
+
+### Action Context (ctx)
+
+```typescript
+ctx.auth        // Authentication
+ctx.storage     // File storage (read/write)
+ctx.runQuery    // Run queries
+ctx.runMutation // Run mutations
+ctx.runAction   // Run other actions
+ctx.scheduler   // Schedule functions
+```
+
+---
+
+## Database Operations Reference
+
+### Read Operations
+
+```typescript
+// Get by ID
+const doc = await ctx.db.get(documentId)
+
+// Query with collect
+const docs = await ctx.db.query('table').collect()
+
+// Query with first
+const doc = await ctx.db.query('table').first()
+```
+
+### Write Operations
+
+```typescript
+// Insert
+const id = await ctx.db.insert('table', { field: value })
+
+// Patch (partial update)
+await ctx.db.patch(documentId, { field: newValue })
+
+// Replace (full update)
+await ctx.db.replace(documentId, { ...allFields })
+
+// Delete
+await ctx.db.delete(documentId)
+```
+
+---
+
+## Storage Operations Reference
+
+### Upload Flow
+
+```typescript
+// 1. Generate upload URL (mutation)
+const uploadUrl = await ctx.storage.generateUploadUrl()
+
+// 2. Upload file (client)
+const response = await fetch(uploadUrl, {
+  method: 'POST',
+  headers: { 'Content-Type': file.type },
+  body: file
+})
+const { storageId } = await response.json()
+
+// 3. Get download URL (query)
+const url = await ctx.storage.getUrl(storageId)
+
+// 4. Delete file (mutation)
+await ctx.storage.delete(storageId)
+```
+
+---
+
+## Scheduler Reference
+
+### Schedule Functions
+
+```typescript
+// Schedule after delay
+await ctx.scheduler.runAfter(
+  60000, // milliseconds
+  internal.module.function,
+  { arg: value }
+)
+
+// Schedule at specific time
+await ctx.scheduler.runAt(
+  timestamp, // milliseconds since epoch
+  internal.module.function,
+  { arg: value }
+)
+```
+
+### Cancel Scheduled Function
+
+```typescript
+await ctx.scheduler.cancel(scheduledFunctionId)
+```
+
+---
+
+## Deployment Reference
+
+### Production Deployment
+
+```bash
+# Deploy all functions
+npx convex deploy
+
+# Deploy with production flag
+npx convex deploy --prod
+```
+
+### Environment Configuration
+
+Development (.env.local):
+```
+CONVEX_DEPLOYMENT=dev:your-deployment
+VITE_CONVEX_URL=https://your-deployment.convex.cloud
+```
+
+Production:
+```
+CONVEX_DEPLOYMENT=prod:your-deployment
+VITE_CONVEX_URL=https://your-deployment.convex.cloud
+```
+
+---
+
+## Error Codes Reference
+
+Common Convex Errors:
+- UNAUTHORIZED: User not authenticated
+- FORBIDDEN: User lacks permission
+- NOT_FOUND: Resource not found
+- VALIDATION_ERROR: Invalid input
+- RATE_LIMITED: Too many requests
+- INTERNAL_ERROR: Server error
+
+---
+
+## Performance Considerations
+
+Query Performance:
+- Always use indexes for filtered queries
+- Avoid full table scans
+- Use pagination for large result sets
+- Limit search results with take()
+
+Mutation Performance:
+- Keep transactions small
+- Batch related operations
+- Use internal mutations for complex workflows
+
+Action Performance:
+- Cache external API responses when possible
+- Use appropriate timeouts
+- Handle rate limits gracefully
+
+---
+
+Version: 2.0.0
+Type: Reference Documentation
+Parent Skill: moai-platform-convex

moai_adk/templates/.claude/skills/moai-platform-firebase-auth/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: "moai-platform-firebase-auth"
+description: "Firebase Authentication specialist covering Google ecosystem, social auth, phone auth, and mobile-first patterns. Use when building Firebase-backed or Google ecosystem apps, implementing social login, or adding phone verification."
+version: 2.1.0
+category: "platform"
+modularized: true
+user-invocable: false
+tags: ['firebase, google, social-auth, mobile, authentication']
+updated: 2026-01-11
+status: "active"
+context7-libraries: "/firebase/firebase-docs"
+related-skills: "moai-platform-firestore, moai-lang-flutter, moai-lang-typescript"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# Firebase Authentication Specialist
+
+Comprehensive Firebase Authentication implementation covering Google ecosystem integration, social authentication providers, phone authentication, anonymous auth, custom claims, and Security Rules integration.
+
+---
+
+## Quick Reference
+
+Firebase Auth Core Features:
+
+- Google Sign-In provides native Google ecosystem integration with Cloud Identity
+- Social Auth supports Facebook, Twitter/X, GitHub, Apple, Microsoft, and Yahoo providers
+- Phone Auth provides SMS-based verification with international support
+- Anonymous Auth offers guest access with account linking upgrade path
+- Custom Claims enable role-based access and admin privileges
+- Security Rules provide integration with Firestore, Storage, and Realtime Database
+
+Context7 Documentation Access:
+
+- Use resolve-library-id with "firebase" to get Context7 library ID
+- Use get-library-docs with resolved ID and topic "authentication" for latest API
+
+Platform SDK Support:
+
+- Web uses firebase/auth with modular SDK version 9 and higher
+- iOS uses FirebaseAuth with Swift and SwiftUI
+- Android uses firebase-auth with Kotlin
+- Flutter uses the firebase_auth package
+- React Native uses @react-native-firebase/auth
+
+Quick Decision Tree:
+
+- Need Google ecosystem integration? Use Firebase Auth
+- Building mobile-first application? Use Firebase Auth
+- Need serverless Cloud Functions? Use Firebase Auth
+- Need anonymous guest access? Use Firebase Auth
+- Existing Firebase infrastructure? Use Firebase Auth
+
+---
+
+## Module Index
+
+This skill uses progressive disclosure with specialized modules for detailed implementation guidance.
+
+### Social Authentication
+
+File: modules/social-auth.md
+
+Covers Google Sign-In, Facebook Login, Apple Sign-In, Twitter/X, GitHub, and Microsoft authentication. Includes web, Flutter, iOS, and Android implementations with configuration requirements and error handling.
+
+Key Topics include Google Sign-In with OAuth scopes and custom parameters, Facebook Login with Graph API access, Apple Sign-In which is required for iOS apps with third-party login, account linking between providers, and error handling for popup and redirect flows.
+
+### Phone Authentication
+
+File: modules/phone-auth.md
+
+Covers SMS-based phone number authentication with international support, reCAPTCHA verification, and platform-specific implementations.
+
+Key Topics include web implementation with RecaptchaVerifier, Flutter verifyPhoneNumber flow with auto-verification, iOS and Android native implementations, E.164 phone number formatting, and error handling and rate limiting.
+
+### Custom Claims and Role Management
+
+File: modules/custom-claims.md
+
+Covers custom claims, role-based access control (RBAC), and admin privileges with Security Rules integration.
+
+Key Topics include setting claims with Admin SDK for Node.js, Python, and Go, Cloud Functions for claim management, reading claims on client for Web, Flutter, and iOS, Security Rules integration for Firestore and Storage, and token refresh strategies.
+
+---
+
+## Implementation Guide
+
+### Firebase Project Setup
+
+Step 1: Create Firebase project at console.firebase.google.com. Step 2: Add your app for Web, iOS, Android, or Flutter. Step 3: Enable desired authentication providers. Step 4: Download and configure SDK credentials.
+
+### Web SDK Initialization
+
+Import initializeApp from firebase/app and getAuth with onAuthStateChanged from firebase/auth. Create a firebaseConfig object with apiKey, authDomain, and projectId values. Call initializeApp with the config to get the app instance. Call getAuth with the app to get the auth instance. Use onAuthStateChanged to listen for authentication state changes, logging signed in with user.uid when user exists or signed out when null.
+
+### Flutter SDK Initialization
+
+Import firebase_core and firebase_auth packages. In the main function, ensure Flutter bindings are initialized, await Firebase.initializeApp(), then run the app. Set up an auth state listener using FirebaseAuth.instance.authStateChanges().listen() to handle User objects, logging signed in with user.uid when user is not null.
+
+### Anonymous Authentication
+
+Import signInAnonymously, linkWithCredential, and EmailAuthProvider from firebase/auth. Call signInAnonymously with the auth instance to create an anonymous user, logging the anonymous UID from result.user.uid. To upgrade to a permanent account, create a credential using EmailAuthProvider.credential with email and password, then call linkWithCredential with the current user and credential.
+
+### Session Persistence
+
+Import setPersistence, browserLocalPersistence, and browserSessionPersistence from firebase/auth. Call setPersistence with auth and browserLocalPersistence to persist across browser sessions as the default behavior. Call setPersistence with auth and browserSessionPersistence to clear the session on tab close.
+
+---
+
+## Security Rules Integration
+
+### Firestore Rules
+
+For Firestore security rules, use rules_version 2 and service cloud.firestore. In the databases match block, create a users collection match with userId wildcard. Allow read and write if request.auth is not null and request.auth.uid equals userId. Create an admin collection match with document wildcard. Allow read and write if request.auth.token.admin equals true.
+
+### Storage Rules
+
+For Firebase Storage security rules, use rules_version 2 and service firebase.storage. In the bucket match block, create a users path match with userId wildcard and allPaths wildcard. Allow read and write if request.auth is not null and request.auth.uid equals userId.
+
+---
+
+## Advanced Patterns
+
+For advanced implementation patterns, see reference.md covering MFA, session cookies, Cloud Functions triggers, and Admin SDK setup. See examples.md for complete authentication services, React hooks, and Flutter providers.
+
+---
+
+## Resources
+
+Extended Documentation:
+
+- reference.md provides advanced patterns and configuration guides
+- examples.md provides working code examples across platforms
+
+Module Files:
+
+- modules/social-auth.md covers social identity providers
+- modules/phone-auth.md covers phone number authentication
+- modules/custom-claims.md covers role-based access control
+
+Firebase Official Resources:
+
+- Firebase Console at console.firebase.google.com
+- Authentication Documentation at firebase.google.com/docs/auth
+- Security Rules Reference at firebase.google.com/docs/rules
+
+Works Well With:
+
+- moai-platform-firestore for Firestore database with auth-based security
+- moai-lang-flutter for Flutter SDK for mobile Firebase Auth
+- moai-lang-typescript for TypeScript patterns for Firebase SDK
+- moai-domain-backend for backend architecture with Firebase Admin SDK
+
+---
+
+Status: Production Ready
+Version: 2.1.0 (Modular Architecture)
+Last Updated: 2026-01-11
+Provider Coverage: Firebase Authentication Only