moai-adk 0.25.4__py3-none-any.whl → 0.41.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,249 @@
+---
+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.0.0
+category: "platform"
+modularized: true
+tags: ['firebase, google, social-auth, mobile, authentication']
+updated: 2026-01-08
+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: Native Google ecosystem integration with Cloud Identity
+- Social Auth: Facebook, Twitter/X, GitHub, Apple, Microsoft, Yahoo
+- Phone Auth: SMS-based verification with international support
+- Anonymous Auth: Guest access with account linking upgrade path
+- Custom Claims: Role-based access and admin privileges
+- Security Rules: Firestore, Storage, and Realtime Database integration
+
+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: firebase/auth with modular SDK (v9+)
+- iOS: FirebaseAuth with Swift and SwiftUI
+- Android: firebase-auth with Kotlin
+- Flutter: firebase_auth package
+- React Native: @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:
+- Google Sign-In with OAuth scopes and custom parameters
+- Facebook Login with Graph API access
+- Apple Sign-In (required for iOS apps with third-party login)
+- Account linking between providers
+- 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:
+- Web implementation with RecaptchaVerifier
+- Flutter verifyPhoneNumber flow with auto-verification
+- iOS and Android native implementations
+- E.164 phone number formatting
+- 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:
+- Setting claims with Admin SDK (Node.js, Python, Go)
+- Cloud Functions for claim management
+- Reading claims on client (Web, Flutter, iOS)
+- Security Rules integration for Firestore and Storage
+- Token refresh strategies
+
+---
+
+## Implementation Guide
+
+### Firebase Project Setup
+
+Step 1: Create Firebase project at console.firebase.google.com
+Step 2: Add your app (Web, iOS, Android, or Flutter)
+Step 3: Enable desired authentication providers
+Step 4: Download and configure SDK credentials
+
+### Web SDK Initialization
+
+```typescript
+import { initializeApp } from 'firebase/app';
+import { getAuth, onAuthStateChanged } from 'firebase/auth';
+
+const firebaseConfig = {
+  apiKey: "your-api-key",
+  authDomain: "your-project.firebaseapp.com",
+  projectId: "your-project-id"
+};
+
+const app = initializeApp(firebaseConfig);
+const auth = getAuth(app);
+
+onAuthStateChanged(auth, (user) => {
+  if (user) {
+    console.log('Signed in:', user.uid);
+  } else {
+    console.log('Signed out');
+  }
+});
+```
+
+### Flutter SDK Initialization
+
+```dart
+import 'package:firebase_core/firebase_core.dart';
+import 'package:firebase_auth/firebase_auth.dart';
+
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Firebase.initializeApp();
+  runApp(MyApp());
+}
+
+// Auth state listener
+FirebaseAuth.instance.authStateChanges().listen((User? user) {
+  if (user != null) {
+    print('Signed in: ${user.uid}');
+  }
+});
+```
+
+### Anonymous Authentication
+
+```typescript
+import { signInAnonymously, linkWithCredential, EmailAuthProvider } from 'firebase/auth';
+
+// Sign in anonymously
+const result = await signInAnonymously(auth);
+console.log('Anonymous UID:', result.user.uid);
+
+// Upgrade to permanent account
+const credential = EmailAuthProvider.credential(email, password);
+await linkWithCredential(auth.currentUser, credential);
+```
+
+### Session Persistence
+
+```typescript
+import { setPersistence, browserLocalPersistence, browserSessionPersistence } from 'firebase/auth';
+
+// Persist across browser sessions (default)
+await setPersistence(auth, browserLocalPersistence);
+
+// Clear on tab close
+await setPersistence(auth, browserSessionPersistence);
+```
+
+---
+
+## Security Rules Integration
+
+### Firestore Rules
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /users/{userId} {
+      allow read, write: if request.auth != null && request.auth.uid == userId;
+    }
+    match /admin/{document=**} {
+      allow read, write: if request.auth.token.admin == true;
+    }
+  }
+}
+```
+
+### Storage Rules
+
+```javascript
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    match /users/{userId}/{allPaths=**} {
+      allow read, write: if request.auth != null && request.auth.uid == userId;
+    }
+  }
+}
+```
+
+---
+
+## Advanced Patterns
+
+For advanced implementation patterns, see:
+- reference.md: MFA, session cookies, Cloud Functions triggers, Admin SDK setup
+- examples.md: Complete authentication services, React hooks, Flutter providers
+
+---
+
+## Resources
+
+Extended Documentation:
+- reference.md: Advanced patterns and configuration guides
+- examples.md: Working code examples across platforms
+
+Module Files:
+- modules/social-auth.md: Social identity providers
+- modules/phone-auth.md: Phone number authentication
+- modules/custom-claims.md: Role-based access control
+
+Firebase Official Resources:
+- Firebase Console: console.firebase.google.com
+- Authentication Documentation: firebase.google.com/docs/auth
+- Security Rules Reference: firebase.google.com/docs/rules
+
+Works Well With:
+- moai-platform-firestore: Firestore database with auth-based security
+- moai-lang-flutter: Flutter SDK for mobile Firebase Auth
+- moai-lang-typescript: TypeScript patterns for Firebase SDK
+- moai-domain-backend: Backend architecture with Firebase Admin SDK
+
+---
+
+Status: Production Ready
+Version: 2.0.0 (Modular Architecture)
+Last Updated: 2025-12-07
+Provider Coverage: Firebase Authentication Only