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

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

@@ -1,398 +1,158 @@
 ---
-name: moai-platform-convex
-description: Convex real-time backend specialist covering TypeScript-first reactive patterns, optimistic updates, and server functions. Use when building real-time collaborative apps.
-version: 1.0.0
-category: platform
-tags: convex, realtime, reactive, typescript, optimistic-updates
-context7-libraries: /get-convex/convex
-related-skills: moai-platform-supabase, moai-lang-typescript
-allowed-tools: Read, Write, Bash, Grep, Glob
+name: "moai-platform-convex"
+description: "Convex real-time backend specialist covering TypeScript-first reactive patterns, optimistic updates, server functions, and file storage. Use when building real-time collaborative apps, implementing reactive queries, or integrating with Clerk/Auth0."
+version: 2.1.0
+category: "platform"
+modularized: true
+user-invocable: false
+tags: ['convex', 'realtime', 'reactive', 'typescript', 'optimistic-updates']
+context7-libraries: "/get-convex/convex"
+related-skills: "moai-platform-supabase, moai-lang-typescript, moai-domain-frontend"
+updated: 2026-01-11
+status: "active"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
 ---
 
-# moai-platform-convex: Convex Real-time Backend Specialist
-
-## Quick Reference (30 seconds)
+# Convex Real-time Backend Specialist
 
 Convex is a real-time reactive backend platform with TypeScript-first design, automatic caching, and optimistic updates.
 
+---
+
+## Quick Reference
+
 ### When to Use Convex
 
-- Real-time collaborative applications (docs, whiteboards, chat)
-- Apps requiring instant UI updates without manual refetching
-- TypeScript-first projects needing end-to-end type safety
-- Applications with complex optimistic update requirements
+Use Convex for real-time collaborative applications including docs, whiteboards, and chat. Choose Convex for apps requiring instant UI updates without manual refetching. Select Convex for TypeScript-first projects needing end-to-end type safety. Use Convex for applications with complex optimistic update requirements.
 
 ### Core Concepts
 
-Server Functions: queries (read), mutations (write), actions (external APIs)
-Reactive Queries: Automatic re-execution when underlying data changes
-Optimistic Updates: Instant UI updates before server confirmation
-Automatic Caching: Built-in query result caching with intelligent invalidation
+Server Functions include queries for read operations, mutations for write operations, and actions for external API calls.
+
+Reactive Queries automatically re-execute when underlying data changes.
+
+Optimistic Updates provide instant UI updates before server confirmation.
+
+Automatic Caching provides built-in query result caching with intelligent invalidation.
 
 ### Quick Start
 
-```bash
-npm create convex@latest
-npx convex dev
-```
+Initialize a new Convex project using npm create convex@latest. Start the development server with npx convex dev.
+
+### Context7 Library
 
-### Context7 Library: /get-convex/convex
+Use mcp__context7__resolve-library-id with "convex" to get the library ID, then use mcp__context7__get-library-docs for latest documentation.
 
 ---
 
-## Implementation Guide
+## Module Index
 
-### Project Structure
+This skill is organized into specialized modules for detailed implementation guidance:
 
-```
-my-app/
-  convex/
-    _generated/         # Auto-generated types and API
-    schema.ts           # Database schema definition
-    functions/          # Server functions by domain
-    http.ts             # HTTP endpoints (optional)
-    crons.ts            # Scheduled jobs (optional)
-  src/
-    ConvexProvider.tsx  # Client setup
-```
+### Reactive Queries Module
 
-### Schema Definition
+Location: modules/reactive-queries.md
 
-```typescript
-// convex/schema.ts
-import { defineSchema, defineTable } from 'convex/server'
-import { v } from 'convex/values'
-
-export default defineSchema({
-  documents: defineTable({
-    title: v.string(),
-    content: v.string(),
-    ownerId: v.string(),
-    isPublic: v.boolean(),
-    createdAt: v.number(),
-    updatedAt: v.number()
-  })
-    .index('by_owner', ['ownerId'])
-    .index('by_public', ['isPublic', 'createdAt'])
-    .searchIndex('search_content', {
-      searchField: 'content',
-      filterFields: ['ownerId', 'isPublic']
-    }),
-
-  collaborators: defineTable({
-    documentId: v.id('documents'),
-    userId: v.string(),
-    permission: v.union(v.literal('read'), v.literal('write'))
-  })
-    .index('by_document', ['documentId'])
-    .index('by_user', ['userId'])
-})
-```
-
-### Validators (v module)
-
-```typescript
-import { v } from 'convex/values'
-
-// Primitives: v.string(), v.number(), v.boolean(), v.null(), v.int64(), v.bytes()
-// Complex: v.array(v.string()), v.object({...}), v.union(...), v.optional(...)
-// References: v.id('tableName')
-```
-
-### Query Functions (Reactive)
-
-```typescript
-import { query } from '../_generated/server'
-import { v } from 'convex/values'
-
-export const list = query({
-  args: { ownerId: v.string() },
-  handler: async (ctx, args) => {
-    return await ctx.db
-      .query('documents')
-      .withIndex('by_owner', (q) => q.eq('ownerId', args.ownerId))
-      .order('desc')
-      .collect()
-  }
-})
-
-export const getById = query({
-  args: { id: v.id('documents') },
-  handler: async (ctx, args) => {
-    const doc = await ctx.db.get(args.id)
-    if (!doc) throw new Error('Document not found')
-    return doc
-  }
-})
-
-export const searchContent = query({
-  args: { searchQuery: v.string(), limit: v.optional(v.number()) },
-  handler: async (ctx, args) => {
-    return await ctx.db
-      .query('documents')
-      .withSearchIndex('search_content', (q) =>
-        q.search('content', args.searchQuery).eq('isPublic', true)
-      )
-      .take(args.limit ?? 10)
-  }
-})
-```
-
-### Mutation Functions
-
-```typescript
-import { mutation } from '../_generated/server'
-import { v } from 'convex/values'
-
-export const create = mutation({
-  args: { title: v.string(), content: v.string(), isPublic: v.boolean() },
-  handler: async (ctx, args) => {
-    const identity = await ctx.auth.getUserIdentity()
-    if (!identity) throw new Error('Unauthorized')
-    return await ctx.db.insert('documents', {
-      ...args,
-      ownerId: identity.subject,
-      createdAt: Date.now(),
-      updatedAt: Date.now()
-    })
-  }
-})
-
-export const update = mutation({
-  args: { id: v.id('documents'), title: v.optional(v.string()), content: v.optional(v.string()) },
-  handler: async (ctx, args) => {
-    const { id, ...updates } = args
-    const existing = await ctx.db.get(id)
-    if (!existing) throw new Error('Document not found')
-    const identity = await ctx.auth.getUserIdentity()
-    if (existing.ownerId !== identity?.subject) throw new Error('Forbidden')
-    await ctx.db.patch(id, { ...updates, updatedAt: Date.now() })
-  }
-})
-
-export const remove = mutation({
-  args: { id: v.id('documents') },
-  handler: async (ctx, args) => await ctx.db.delete(args.id)
-})
-```
-
-### Action Functions (External APIs)
-
-```typescript
-import { action } from '../_generated/server'
-import { internal } from '../_generated/api'
-import { v } from 'convex/values'
-
-export const generateSummary = action({
-  args: { documentId: v.id('documents') },
-  handler: async (ctx, args) => {
-    const doc = await ctx.runQuery(internal.documents.getById, { id: args.documentId })
-    const response = await fetch('https://api.openai.com/v1/completions', {
-      method: 'POST',
-      headers: { 'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ model: 'gpt-4', prompt: `Summarize: ${doc.content}`, max_tokens: 150 })
-    })
-    const result = await response.json()
-    await ctx.runMutation(internal.documents.updateSummary, { id: args.documentId, summary: result.choices[0].text })
-    return result.choices[0].text
-  }
-})
-```
+Covers real-time reactive query patterns including basic query structure, index-based queries, search indexes, pagination patterns, React integration with useQuery hooks, and optimistic updates.
 
-### React Client Setup
+### Server Functions Module
 
-```typescript
-import { ConvexProvider, ConvexReactClient } from 'convex/react'
-import { ConvexProviderWithClerk } from 'convex/react-clerk'
+Location: modules/server-functions.md
 
-const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL)
+Covers mutations for write operations, actions for external API integration, internal functions for server-to-server calls, scheduled functions using crons, and HTTP endpoints for webhooks.
 
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
-      {children}
-    </ConvexProviderWithClerk>
-  )
-}
-```
+### Authentication Integration Module
 
-### React Hooks Usage
+Location: modules/auth-integration.md
 
-```typescript
-import { useQuery, useMutation } from 'convex/react'
-import { api } from '../../convex/_generated/api'
+Covers Clerk integration, Auth0 integration, server-side authentication patterns, authorization and role-based access control, and session management.
 
-export function DocumentList({ userId }: { userId: string }) {
-  const documents = useQuery(api.functions.documents.list, { ownerId: userId })
-  const createDocument = useMutation(api.functions.documents.create)
+### File Storage Module
 
-  if (documents === undefined) return <Loading />
+Location: modules/file-storage.md
 
-  return (
-    <div>
-      <button onClick={() => createDocument({ title: 'New', content: '', isPublic: false })}>
-        New Document
-      </button>
-      {documents.map((doc) => <DocumentCard key={doc._id} document={doc} />)}
-    </div>
-  )
-}
-```
+Covers file upload workflows, storage URL generation, client-side upload with progress, file display components, and file management operations.
 
 ---
 
-## Advanced Patterns
-
-### Optimistic Updates
-
-```typescript
-import { useMutation } from 'convex/react'
-import { api } from '../../convex/_generated/api'
-
-export function useOptimisticUpdate() {
-  return useMutation(api.functions.documents.update)
-    .withOptimisticUpdate((localStore, args) => {
-      const { id, ...updates } = args
-      const existing = localStore.getQuery(api.functions.documents.getById, { id })
-      if (existing) {
-        localStore.setQuery(api.functions.documents.getById, { id }, {
-          ...existing, ...updates, updatedAt: Date.now()
-        })
-      }
-    })
-}
-```
-
-### File Storage
-
-```typescript
-// Server-side
-export const generateUploadUrl = mutation({
-  handler: async (ctx) => await ctx.storage.generateUploadUrl()
-})
-
-export const saveFile = mutation({
-  args: { storageId: v.id('_storage'), fileName: v.string() },
-  handler: async (ctx, args) => await ctx.db.insert('files', { ...args, uploadedAt: Date.now() })
-})
-
-export const getFileUrl = query({
-  args: { storageId: v.id('_storage') },
-  handler: async (ctx, args) => await ctx.storage.getUrl(args.storageId)
-})
-```
-
-```typescript
-// Client-side upload
-export function useFileUpload() {
-  const generateUploadUrl = useMutation(api.functions.files.generateUploadUrl)
-  const saveFile = useMutation(api.functions.files.saveFile)
-
-  return async (file: File) => {
-    const uploadUrl = await generateUploadUrl()
-    const response = await fetch(uploadUrl, { method: 'POST', headers: { 'Content-Type': file.type }, body: file })
-    const { storageId } = await response.json()
-    await saveFile({ storageId, fileName: file.name })
-    return storageId
-  }
-}
-```
-
-### Scheduled Functions (Crons)
-
-```typescript
-import { cronJobs } from 'convex/server'
-import { internal } from './_generated/api'
-
-const crons = cronJobs()
-crons.interval('cleanup old drafts', { hours: 24 }, internal.documents.cleanupOldDrafts)
-crons.cron('daily analytics', '0 0 * * *', internal.analytics.generateDailyReport)
-export default crons
-```
-
-### HTTP Endpoints
-
-```typescript
-import { httpRouter } from 'convex/server'
-import { httpAction } from './_generated/server'
-
-const http = httpRouter()
-http.route({
-  path: '/webhook/stripe',
-  method: 'POST',
-  handler: httpAction(async (ctx, request) => {
-    const body = await request.text()
-    await ctx.runMutation(internal.payments.processWebhook, { body, signature: request.headers.get('stripe-signature') })
-    return new Response('OK', { status: 200 })
-  })
-})
-export default http
-```
-
-### Authentication (Clerk)
-
-```typescript
-export const current = query({
-  handler: async (ctx) => {
-    const identity = await ctx.auth.getUserIdentity()
-    if (!identity) return null
-    return await ctx.db.query('users').withIndex('by_token', (q) => q.eq('tokenIdentifier', identity.tokenIdentifier)).first()
-  }
-})
-
-export const ensureUser = mutation({
-  handler: async (ctx) => {
-    const identity = await ctx.auth.getUserIdentity()
-    if (!identity) throw new Error('Unauthorized')
-    const existing = await ctx.db.query('users').withIndex('by_token', (q) => q.eq('tokenIdentifier', identity.tokenIdentifier)).first()
-    if (existing) return existing._id
-    return await ctx.db.insert('users', { tokenIdentifier: identity.tokenIdentifier, email: identity.email, name: identity.name, createdAt: Date.now() })
-  }
-})
-```
-
-### Error Handling
-
-```typescript
-import { ConvexError } from 'convex/values'
-
-export const secureOperation = mutation({
-  args: { id: v.id('documents') },
-  handler: async (ctx, args) => {
-    const identity = await ctx.auth.getUserIdentity()
-    if (!identity) throw new ConvexError('UNAUTHORIZED')
-    const doc = await ctx.db.get(args.id)
-    if (!doc) throw new ConvexError({ code: 'NOT_FOUND', message: 'Document not found' })
-  }
-})
-```
+## Implementation Guide
+
+### Project Structure
+
+A Convex project contains a convex directory with _generated subdirectory for auto-generated types and API, schema.ts for database schema definition, a functions subdirectory for server functions organized by domain, optional http.ts for HTTP endpoints, and optional crons.ts for scheduled jobs. The src directory contains ConvexProvider.tsx for client setup.
+
+### Schema Definition
+
+The schema.ts file imports defineSchema and defineTable from convex/server and v from convex/values. The default export uses defineSchema to define tables. Each table is defined with defineTable specifying field types such as v.string(), v.boolean(), and v.number(). Tables can have indexes defined using the index method with index name and field array. Search indexes use the searchIndex method specifying searchField and filterFields.
+
+### Validators
+
+The v module from convex/values provides primitive validators including v.string(), v.number(), v.boolean(), v.null(), v.int64(), and v.bytes().
+
+Complex types include v.array() for arrays of a type, v.object() for objects with specified fields, v.union() for union types with v.literal() options, and v.optional() for optional fields.
+
+Reference validators include v.id() for references to table documents.
+
+### React Client Setup
+
+The ConvexProvider component imports ConvexProvider and ConvexReactClient from convex/react, ConvexProviderWithClerk from convex/react-clerk, and useAuth from @clerk/clerk-react. Create a ConvexReactClient instance with the VITE_CONVEX_URL environment variable. The Providers component wraps children with ConvexProviderWithClerk passing the client and useAuth hook.
+
+### React Hooks Usage
+
+Import useQuery and useMutation from convex/react and api from the generated API module. In a component, call useQuery with the query function and parameters to get reactive data. Call useMutation to get a mutation function. Handle the undefined state during loading. Render the data and use the mutation function in event handlers.
 
 ---
 
 ## Best Practices
 
 Query Optimization:
+
 - Use indexes for all filtered queries
 - Prefer paginated queries for large datasets
 - Use search indexes for full-text search
+- Leverage automatic caching
 
 Mutation Design:
+
 - Keep mutations focused and atomic
 - Use internal mutations for multi-step operations
 - Validate all inputs with the v module
+- Always check authorization
+
+Error Handling:
+
+- Use ConvexError for structured errors
+- Check for undefined during loading states
+- Handle optimistic update rollbacks
 
 ---
 
 ## Works Well With
 
-- moai-platform-supabase - Alternative PostgreSQL-based backend
-- moai-lang-typescript - TypeScript patterns and best practices
-- moai-domain-frontend - React integration patterns
-- moai-quality-security - Authentication and authorization patterns
+- moai-platform-supabase for alternative PostgreSQL-based backend
+- moai-lang-typescript for TypeScript patterns and best practices
+- moai-domain-frontend for React integration patterns
+- moai-platform-clerk for Clerk authentication patterns
+- moai-platform-auth0 for Auth0 authentication patterns
+
+---
+
+## Resources
+
+- Official Documentation at docs.convex.dev
+- Context7 Library at /get-convex/convex
+- GitHub at github.com/get-convex/convex
 
 ---
 
 Status: Production Ready
-Generated with: MoAI-ADK Skill Factory v2.0
-Last Updated: 2025-12-07
+Version: 2.1.0
+Last Updated: 2026-01-11
 Platform: Convex Real-time Backend