interaqt 0.8.4 → 0.8.6

package/agent/.claude/agents/frontend-generation-handler.md

@@ -205,6 +205,7 @@ npm run generate-frontend-api
 - **Framework**: React + TypeScript
 - **Build Tool**: Vite
 - **Styling**: Tailwind CSS
+- **Routing**: React Router
 - **State Management**: React Context (for API client and global state)
 
 **Project Structure:**
@@ -307,6 +308,22 @@ npm run generate-frontend-api
    - Test on different screen sizes
    - Ensure mobile-friendly layouts
 
+7. **Modular Navigation:**
+   - **Module Entry Points**: Create a main navigation menu listing all modules
+   - **Route Organization**: Structure routes with module prefixes (e.g., `/donate/*`, `/livestream/*`)
+   - **Active Module Indicator**: Highlight current module in navigation menu
+   - **Breadcrumb Navigation**: Show module name → page hierarchy
+   - **Module Switching**: Enable seamless navigation between modules
+   - **Example Structure**:
+     ```typescript
+     // Main App Router
+     <Routes>
+       <Route path="/" element={<ModuleSelector />} />
+       <Route path="/donate/*" element={<DonateModule />} />
+       <Route path="/livestream/*" element={<LivestreamModule />} />
+     </Routes>
+     ```
+
 **🔴 CRITICAL: Completeness Check**
 
 Before marking Step 4 complete, verify:

package/agent/.claude/agents/implement-integration-handler.md

@@ -302,6 +302,7 @@ interface IIntegration {
     setup?(controller: Controller): Promise<any>  // Setup phase with controller access
     createSideEffects(): RecordMutationSideEffect[]  // Listen to data mutations and create events
     createAPIs?(): APIs              // Expose custom APIs (e.g., webhook endpoints)
+    createMiddlewares?(): MiddlewareHandler[]  // Optional: Create HTTP middleware for request processing
 }
 ```
 
@@ -313,6 +314,63 @@ interface IIntegration {
   1. Webhook endpoints to receive external system callbacks
   2. Manual trigger/query APIs for status checks and retries
   3. Frontend support APIs (e.g., pre-signed URLs for uploads)
+- **createMiddlewares()**: Optional method to create HTTP middleware for request processing (e.g., authentication, authorization, request validation)
+
+**🔴 CRITICAL: Separation Between API Layer and Integration Layer**
+
+**API File Responsibilities** (`integrations/{name}/externalApi.ts` or `integrations/{name}/volcApi.ts`):
+- Construct HTTP requests according to external API documentation
+- Call external APIs and return raw responses
+- **NO data transformation** - return data as-is from external system
+- Define **strict TypeScript types** based on official API documentation:
+  - Input parameter types (exactly matching API requirements)
+  - Output response types (exactly matching API responses)
+- Handle only HTTP-level errors (network failures, status codes)
+
+**Integration File Responsibilities** (`integrations/{name}/index.ts`):
+- Call API file methods to interact with external system
+- **Transform external API responses** into internal event format
+- Map external data structures to business event entity fields
+- Create integration events following unified sequence
+- Handle business-level error scenarios
+
+**Example:**
+```typescript
+// ❌ WRONG: API file transforms data
+// integrations/tts/externalApi.ts
+export async function callTTSApi(params: TTSParams): Promise<{ audioUrl: string }> {
+  const response = await fetch(...)
+  const data = await response.json()
+  return { audioUrl: data.result.url }  // ❌ Transformation in API file
+}
+
+// ✅ CORRECT: API file returns raw response
+// integrations/tts/externalApi.ts
+export type TTSApiResponse = {
+  taskId: string
+  status: string
+  result?: {
+    url: string
+    duration: number
+  }
+}
+
+export async function callTTSApi(params: TTSParams): Promise<TTSApiResponse> {
+  const response = await fetch(...)
+  return await response.json()  // ✅ Raw response with strict types
+}
+
+// ✅ CORRECT: Integration file transforms data
+// integrations/tts/index.ts
+const apiResponse = await callTTSApi(requestParams)
+
+// Transform to internal event format
+await this.createIntegrationEvent(controller, apiCall.id, apiResponse.taskId, 'initialized', {
+  taskId: apiResponse.taskId,           // Map to event fields
+  status: apiResponse.status,
+  audioUrl: apiResponse.result?.url     // Extract what business needs
+}, null)
+```
 
 # Task 4: Integration Implementation
 
@@ -831,14 +889,26 @@ mkdir -p integrations/{integration-name}
 
 ### 4.4.2 Create External API Wrapper (if no SDK)
 
+**🔴 CRITICAL: API File Responsibilities**
+
+This file MUST:
+- Return raw API responses without transformation
+- Define strict TypeScript types matching official API documentation
+- Handle only HTTP-level errors
+
+This file MUST NOT:
+- Transform data to internal event format (that's integration file's job)
+- Create any integration events
+- Handle business logic
+
 Create `integrations/{integration-name}/externalApi.ts`:
 
 ```typescript
 /**
  * External API wrapper for {System Name}
  * 
- * This module encapsulates all external API calls to keep the integration
- * logic clean and testable.
+ * CRITICAL: This file returns raw API responses with strict types.
+ * NO data transformation - integration file handles that.
  */
 
 export type ExternalApiConfig = {
@@ -846,16 +916,37 @@ export type ExternalApiConfig = {
   baseUrl?: string
 }
 
+/**
+ * Request parameters - MUST match external API documentation exactly
+ */
 export type RequestParams = {
-  // Define request parameters
+  // Define according to official API docs
+  param1: string
+  param2: number
+  // ... more parameters
 }
 
+/**
+ * Response data - MUST match external API response exactly
+ */
 export type ResponseData = {
-  // Define response structure
+  // Define according to official API docs
+  taskId: string
+  status: 'pending' | 'processing' | 'completed' | 'failed'
+  result?: {
+    // Define result structure from API docs
+    data: any
+  }
+  error?: {
+    code: string
+    message: string
+  }
 }
 
 /**
  * Call external API
+ * 
+ * Returns raw API response - NO transformation
  */
 export async function callExternalApi(
   params: RequestParams,
@@ -882,7 +973,8 @@ export async function callExternalApi(
       throw new Error(`API call failed: ${response.statusText}`)
     }
 
-    const data = await response.json()
+    // Return raw response - integration file will transform it
+    const data: ResponseData = await response.json()
     return data
   } catch (error: any) {
     console.error('[ExternalAPI] Call failed:', error.message)
@@ -892,12 +984,26 @@ export async function callExternalApi(
 
 /**
  * Query external status
+ * 
+ * Returns raw status response - NO transformation
  */
 export async function queryExternalStatus(
   taskId: string,
   config?: ExternalApiConfig
 ): Promise<ResponseData> {
-  // Similar implementation
+  // Similar implementation - return raw response
+  const apiKey = config?.apiKey
+  const baseUrl = config?.baseUrl
+  
+  const response = await fetch(`${baseUrl}/v1/status/${taskId}`, {
+    method: 'GET',
+    headers: {
+      'Authorization': `Bearer ${apiKey}`
+    }
+  })
+
+  const data: ResponseData = await response.json()
+  return data  // Raw response
 }
 ```
 
@@ -912,8 +1018,9 @@ Create `integrations/{integration-name}/index.ts`:
  * Purpose: {Brief description}
  * 
  * Features:
- * - Listen to {Entity} mutations and trigger external API calls
- * - Convert external status updates to internal events
+ * - Listen to APICall entity creation and trigger external API calls
+ * - Transform external API responses to internal event format
+ * - Create integration events following unified sequence
  * - Provide manual status refresh API
  * - Factory function pattern for configuration flexibility
  */
@@ -1107,31 +1214,42 @@ export function create{IntegrationName}Integration(config: {IntegrationName}Conf
                 requestParams
               })
               
-              // Step 2: Call external API and create unified event sequence
+              // Step 2: Call external API (returns raw response with strict types)
               try {
-                const result = await callExternalApi(requestParams)
+                const apiResponse = await callExternalApi(requestParams)
+                // apiResponse has type ResponseData from API file
                 
+                // Step 3: Transform external response to internal event format
                 // Determine externalId: use API's task ID or generate one
-                const externalId = result.taskId || result.id || crypto.randomUUID()
+                const externalId = apiResponse.taskId 
                 
                 console.log('[{IntegrationName}] External API called', {
                   apiCallId: apiCall.id,
                   externalId,
-                  hasTaskId: !!(result.taskId || result.id)
+                  hasTaskId: !!(apiResponse.taskId)
                 })
                 
+                // Step 4: Transform and create 'initialized' event
+                // Map external fields to internal event format
+                const eventData = {
+                  taskId: apiResponse.taskId,
+                  status: apiResponse.status,
+                  // Map other fields as needed for business logic
+                  rawResponse: apiResponse  // Keep raw response if needed
+                }
+                
                 // ALWAYS create 'initialized' event with both entityId and externalId
                 await self.createIntegrationEvent(
                   this,
                   apiCall.id,              // entityId - APICall's id
                   externalId,              // externalId - task ID or generated UUID
                   'initialized',
-                  result,
+                  eventData,               // Transformed data, not raw response
                   null
                 )
                 
                 // For sync APIs (no task ID): immediately create processing and completed events
-                if (!result.taskId && !result.id) {
+                if (!apiResponse.taskId) {
                   // Immediately create processing event
                   await self.createIntegrationEvent(
                     this,
@@ -1142,19 +1260,26 @@ export function create{IntegrationName}Integration(config: {IntegrationName}Conf
                     null
                   )
                   
-                  // Immediately create completed event
+                  // Transform completion data
+                  const completedData = {
+                    status: 'completed',
+                    result: apiResponse.result,
+                    // Map other completion fields
+                  }
+                  
+                  // Immediately create completed event with transformed data
                   await self.createIntegrationEvent(
                     this,
                     null,
                     externalId,
                     'completed',
-                    result,
+                    completedData,         // Transformed data
                     null
                   )
                   
                   console.log('[{IntegrationName}] Sync API completed with unified event sequence')
                 }
-                // For async APIs: result will come later via webhook or polling
+                // For async APIs: status will come later via webhook or polling
                 
               } catch (error: any) {
                 console.error('[{IntegrationName}] External API call failed', {
@@ -1212,10 +1337,11 @@ export function create{IntegrationName}Integration(config: {IntegrationName}Conf
             apiCallId: string
           }) {
             try {
-              await self.checkAndUpdateStatus(params.apiCallId)
+              const apiResponse = await self.checkAndUpdateStatus(params.apiCallId)
               return {
                 success: true,
-                message: 'Status check triggered, integration event created'
+                message: 'Status check triggered, integration event created',
+                response: apiResponse
               }
             } catch (error: any) {
               console.error('[{IntegrationName}] Failed to query status', {
@@ -1343,25 +1469,36 @@ export function create{IntegrationName}Integration(config: {IntegrationName}Conf
         throw new Error(`No external ID found for APICall: ${apiCallId}`)
       }
 
-      // Query external system
-      const result = await queryExternalStatus(externalId)
+      // Query external system (returns raw response)
+      const apiResponse = await queryExternalStatus(externalId)
 
       console.log('[{IntegrationName}] Status checked', {
         apiCallId,
         externalId,
-        status: result.status
+        status: apiResponse.status
       })
 
+      // Transform external response to internal event format
+      const eventType = apiResponse.status  // Map external status to event type
+      const eventData = apiResponse.result ? {
+        status: apiResponse.status,
+        result: apiResponse.result,
+        // Map other fields as needed
+      } : null
+      const errorMessage = apiResponse.error?.message || null
+
       // Create integration event based on status
       // entityId is null because APICall already exists (not 'initialized' event)
       await this.createIntegrationEvent(
         this.controller,
         null,              // entityId - not needed for status updates
         externalId,        // externalId - to match with existing APICall
-        result.status,     // eventType - 'processing' | 'completed' | 'failed'
-        result.data || null,
-        result.error || null
+        eventType,         // eventType - 'processing' | 'completed' | 'failed'
+        eventData,         // Transformed data, not raw response
+        errorMessage       // Extracted error message
       )
+
+      return apiResponse
     }
   }
 }
@@ -1687,6 +1824,101 @@ createAPIs() {
 }
 ```
 
+## Integration Middleware
+
+**🔴 CRITICAL: Middleware for Request Processing**
+
+Integrations can provide HTTP middleware to handle cross-cutting concerns like authentication, authorization, request validation, logging, etc.
+
+**When to use middleware:**
+- Authentication and authorization (e.g., JWT verification)
+- Request/response transformation
+- Logging and monitoring
+- Rate limiting
+- CORS handling
+- Custom header processing
+
+**Middleware execution:**
+- Middleware runs BEFORE API handlers
+- Can access and modify request context
+- Can short-circuit request processing
+- Can inject context data for API handlers
+
+**Example: Authentication Middleware**
+
+```typescript
+export function createAuthIntegration(config: AuthIntegrationConfig) {
+  return class AuthIntegration implements IIntegration {
+    createMiddlewares(): MiddlewareHandler[] {
+      return [
+        async (c, next) => {
+          // Extract token from multiple sources
+          let token: string | undefined
+          const authToken = c.req.query('authToken')
+          const authHeader = c.req.header('authorization')
+          const cookieHeader = c.req.header('cookie')
+
+          if (authToken) {
+            token = authToken
+          } else if (authHeader?.startsWith('Bearer ')) {
+            token = authHeader.substring(7)
+          } else if (cookieHeader) {
+            const allCookies: Record<string, string> = {}
+            cookieHeader.split(';').forEach((cookie) => {
+              const [name, value] = cookie.trim().split('=')
+              if (name && value) {
+                allCookies[name] = decodeURIComponent(value)
+              }
+            })
+            token = allCookies.token
+          }
+
+          // Verify token and inject userId into context
+          if (token) {
+            try {
+              const decoded = await verify(token, jwtSecret) as any
+              c.set('userId', decoded.userId)
+            } catch (err) {
+              console.log('Invalid token', err)
+            }
+          }
+
+          await next()
+        }
+      ]
+    }
+
+    createAPIs() {
+      return {
+        login: createAPI(
+          async function(context, params: { identifier: string; password: string }) {
+            // Authenticate user
+            // Generate JWT token
+            // Return token to client
+          },
+          { allowAnonymous: true }
+        )
+      }
+    }
+  }
+}
+```
+
+**Key principles:**
+- **Middleware is optional**: Only use when needed for cross-cutting concerns
+- **Order matters**: Middleware executes in the order returned from createMiddlewares()
+- **Context injection**: Use `c.set()` to inject data into context for API handlers
+- **Non-blocking**: Always call `await next()` to continue the middleware chain
+- **Error handling**: Middleware can catch and handle errors before they reach API handlers
+
+**Common use cases:**
+1. **Authentication** (`integrations/auth/index.ts`): JWT verification, session management
+2. **Authorization**: Role-based access control, permission checks
+3. **Request validation**: Schema validation, sanitization
+4. **Logging**: Request/response logging, performance monitoring
+5. **Rate limiting**: Throttle requests per user/IP
+6. **CORS**: Handle cross-origin requests
+
 ## Example: Stripe Payment Integration
 
 ```typescript

package/agent/.claude/agents/requirements-analysis-handler.md

@@ -553,6 +553,80 @@ git commit -m "feat: Task 1.2 - Complete functional requirements analysis"
 
 **External side-effects requiring third-party APIs must be identified separately.**
 
+### Special Case: Authentication Integration
+
+**⚠️ CRITICAL: Authentication for Basic Module**
+
+If the current module is "basic", authentication (login/registration) requirements must be handled as an integration named **"auth"**.
+
+**Authentication vs Business Logic:**
+1. **Authentication (Integration)**:
+   - User login with credentials
+   - User registration/signup
+   - Password reset/recovery
+   - OAuth/social login
+   - These are NOT part of business logic - treat as integration "auth"
+
+2. **User Management (Business Logic)**:
+   - Administrator creates user accounts
+   - Administrator updates user information
+   - Administrator deactivates users
+   - These ARE business data operations - design as regular interactions
+
+**Handling Authentication Requirements:**
+
+**Case 1: User explicitly described login/registration requirements**
+- Extract ALL authentication-related requirements into integration "auth"
+- Do NOT create interactions for login/registration in Task 1.5
+- Document the specific authentication flow in integration.json
+
+**Case 2: User did NOT mention login/registration**
+- For "basic" module, assume authentication is needed
+- Design a simple password-based authentication integration
+- Use default specification (see example below)
+
+**Default Password Authentication Integration:**
+```json
+{
+  "id": "INT_AUTH",
+  "name": "auth",
+  "type": "stateful-system",
+  "type_explanation": "Authentication system maintains session state and user credentials. Requires bidirectional communication for login, registration, and session management.",
+  "external_system": "Authentication Service",
+  "purpose": "Handle user authentication and registration for the system",
+  "related_requirements": ["User login", "User registration"],
+  "flow_description": "For registration: User provides username/email and password in current system. System sends registration request (username, password) to authentication service. Authentication service validates uniqueness, hashes password, creates auth record, and returns user credentials. Current system receives response and creates User entity with returned user ID. For login: User provides credentials in current system. System sends login request to authentication service. Authentication service validates credentials and returns session token. Current system stores session and grants access.",
+  "user_interactions": {
+    "in_current_system": [
+      "User enters username/email and password for registration",
+      "User enters credentials for login",
+      "User views login success/failure messages"
+    ],
+    "in_external_system": [
+      "Authentication service validates credential format",
+      "Authentication service checks username/email uniqueness",
+      "Authentication service hashes password securely",
+      "Authentication service generates session tokens"
+    ]
+  },
+  "current_system_data": [
+    {
+      "entity": "User",
+      "properties": ["id", "username", "email"],
+      "usage": "Created after successful registration using ID returned from authentication service. Read during login to fetch user profile."
+    }
+  ],
+  "notes": "This is a default password-based authentication. If user requirements specify OAuth, biometric, or other authentication methods, adjust accordingly."
+}
+```
+
+**Important Notes:**
+- Authentication integration should ALWAYS be named "auth" for consistency
+- Do NOT create "User" entity properties for password, passwordHash, or session tokens - these belong to the auth integration
+- User entity should only contain business-related properties (username, email, profile info)
+- In Task 1.4, do NOT create entities for authentication (no AuthSession, no Credentials entities)
+- In Task 1.5, do NOT create login/registration interactions - these are handled by the auth integration
+
 ### What is NOT an Integration
 
 **⚠️ CRITICAL: Intra-Project Module Access**

package/agent/.claude/settings.local.json

@@ -73,7 +73,9 @@
       "Bash(else echo \"VOLC_ACCESS_KEY_ID is set\")",
       "Bash(fi:*)",
       "Bash(if [ -z \"$VOLC_SECRET_ACCESS_KEY\" ])",
-      "Bash(then echo \"VOLC_SECRET_ACCESS_KEY is empty or not set\")"
+      "Bash(then echo \"VOLC_SECRET_ACCESS_KEY is empty or not set\")",
+      "Bash(npm run)",
+      "Bash(chmod:*)"
     ],
     "deny": [],
     "ask": []

package/dist/index.js

@@ -93,7 +93,7 @@ const Ie = /^[a-zA-Z0-9_]+$/;
 class I {
   // for Merged Entity
   constructor(t, e) {
-    this._type = "Entity", this._options = e, this.uuid = k(e), this.name = t.name, this.properties = t.properties || [], this.computation = t.computation, this.baseEntity = t.baseEntity, this.matchExpression = t.matchExpression, this.inputEntities = t.inputEntities;
+    this._type = "Entity", this._options = e, this.uuid = k(e), this.name = t.name, this.properties = t.properties || [], this.computation = t.computation, this.baseEntity = t.baseEntity, this.matchExpression = t.matchExpression, this.inputEntities = t.inputEntities, this.commonProperties = t.commonProperties;
   }
   static {
     this.isKlass = !0;
@@ -122,6 +122,15 @@ class I {
         },
         defaultValue: () => []
       },
+      commonProperties: {
+        type: "Property",
+        collection: !0,
+        required: !1,
+        constraints: {
+          eachNameUnique: ({ properties: t }) => new Set(t.map((i) => i.name)).size === t.length
+        },
+        defaultValue: () => []
+      },
       computation: {
         type: [],
         collection: !1,
@@ -390,7 +399,7 @@ class P {
         if (s.target !== i.target)
           throw new Error("All inputRelations must have the same target");
       }
-      this.inputRelations = t.inputRelations, this.source = i.source, this.target = i.target, this.sourceProperty = t.sourceProperty, this.targetProperty = t.targetProperty, this.type = i.type, this.isTargetReliance = i.isTargetReliance, this._name = t.name;
+      this.inputRelations = t.inputRelations, this.source = i.source, this.target = i.target, this.sourceProperty = t.sourceProperty, this.targetProperty = t.targetProperty, this.type = i.type, this.isTargetReliance = i.isTargetReliance, this._name = t.name, this.commonProperties = t.commonProperties;
     } else if (t.baseRelation) {
       if (!t.sourceProperty || !t.targetProperty)
         throw new Error("Filtered relation must have sourceProperty and targetProperty");
@@ -5536,6 +5545,11 @@ function He(u, t, e, i) {
   );
   t.replace(n, u), c !== n && t.add(c);
   const l = pt(u);
+  if (u.commonProperties) {
+    const d = l.filter((h) => u.commonProperties.some((p) => !h.properties.some((y) => y.name === p.name && y.type === p.type)));
+    if (d.length > 0)
+      throw new Error(`Merged ${e} ${u.name} defined commonProperties, but these ${e}s do not have commonProperties: ${d.map((h) => h.name).join(", ")}`);
+  }
   if (l)
     for (const d of l)
       je(