@axonflow/sdk 3.3.1 → 3.5.0

package/dist/esm/client.js

@@ -434,6 +434,14 @@ export class AxonFlow {
             request_type: options.requestType,
             context: options.context || {},
         };
+        if (options.media && options.media.length > 0) {
+            agentRequest.media = options.media.map(m => ({
+                source: m.source,
+                base64_data: m.base64Data,
+                url: m.url,
+                mime_type: m.mimeType,
+            }));
+        }
         const url = `${this.config.endpoint}/api/request`;
         const headers = {
             'Content-Type': 'application/json',
@@ -533,6 +541,31 @@ export class AxonFlow {
                 action: data.budget_info.action,
             };
         }
+        // Parse media analysis if present
+        if (data.media_analysis) {
+            result.mediaAnalysis = {
+                results: (data.media_analysis.results ?? []).map((r) => ({
+                    mediaIndex: r.media_index ?? 0,
+                    sha256Hash: r.sha256_hash ?? '',
+                    hasFaces: r.has_faces ?? false,
+                    faceCount: r.face_count ?? 0,
+                    hasBiometricData: r.has_biometric_data ?? false,
+                    nsfwScore: r.nsfw_score ?? 0,
+                    violenceScore: r.violence_score ?? 0,
+                    contentSafe: r.content_safe !== undefined ? r.content_safe : true,
+                    documentType: r.document_type,
+                    isSensitiveDocument: r.is_sensitive_document ?? false,
+                    hasPII: r.has_pii ?? false,
+                    piiTypes: r.pii_types,
+                    hasExtractedText: r.has_extracted_text ?? false,
+                    extractedTextLength: r.extracted_text_length ?? 0,
+                    estimatedCostUsd: r.estimated_cost_usd ?? 0,
+                    warnings: r.warnings,
+                })),
+                totalCostUsd: data.media_analysis.total_cost_usd ?? 0,
+                analysisTimeMs: data.media_analysis.analysis_time_ms ?? 0,
+            };
+        }
         if (this.config.debug) {
             debugLog('Proxy Mode: proxyLLMCall result', {
                 success: result.success,
@@ -3264,6 +3297,25 @@ export class AxonFlow {
         const request = reason ? { reason } : {};
         await this.orchestratorRequest('POST', `/api/v1/workflows/${workflowId}/abort`, request);
     }
+    /**
+     * Fail a workflow.
+     *
+     * Call this when a workflow has encountered an unrecoverable error and should
+     * be marked as failed. Unlike abort (which is user-initiated), fail indicates
+     * the workflow could not complete due to an error condition.
+     *
+     * @example
+     * ```typescript
+     * await client.failWorkflow('wf_123', 'Step 3 exceeded retry limit');
+     * ```
+     */
+    async failWorkflow(workflowId, reason) {
+        if (!workflowId) {
+            throw new ConfigurationError('Workflow ID is required');
+        }
+        const request = reason ? { reason } : {};
+        await this.orchestratorRequest('POST', `/api/v1/workflows/${workflowId}/fail`, request);
+    }
     /**
      * Mark a workflow step as completed.
      *
@@ -4359,6 +4411,169 @@ export class AxonFlow {
         const body = reason ? { reason } : {};
         await this.orchestratorRequest('POST', `/api/v1/unified/executions/${executionId}/cancel`, body);
     }
+    // ===========================================================================
+    // HITL (Human-in-the-Loop) Queue Methods (Enterprise)
+    // ===========================================================================
+    /**
+     * List pending approval requests in the HITL queue.
+     *
+     * Returns a paginated list of approval requests that require human review.
+     * Filter by status and severity to find requests that need attention.
+     *
+     * Enterprise Feature: Requires AxonFlow Enterprise license.
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated list of HITL approval requests
+     *
+     * @example
+     * ```typescript
+     * // List all pending requests
+     * const result = await client.listHITLQueue();
+     * console.log(`${result.total} pending requests`);
+     *
+     * // List critical pending requests
+     * const critical = await client.listHITLQueue({
+     *   status: 'pending',
+     *   severity: 'critical',
+     *   limit: 10
+     * });
+     * ```
+     */
+    async listHITLQueue(options) {
+        const params = new URLSearchParams();
+        if (options?.status) {
+            params.set('status', options.status);
+        }
+        if (options?.severity) {
+            params.set('severity', options.severity);
+        }
+        if (options?.limit !== undefined) {
+            params.set('limit', options.limit.toString());
+        }
+        if (options?.offset !== undefined) {
+            params.set('offset', options.offset.toString());
+        }
+        const queryString = params.toString();
+        const path = `/api/v1/hitl/queue${queryString ? `?${queryString}` : ''}`;
+        if (this.config.debug) {
+            debugLog('Listing HITL queue', { options });
+        }
+        const response = await this.orchestratorRequest('GET', path);
+        return {
+            items: response.data || [],
+            total: response.meta?.total ?? 0,
+            has_more: (response.meta?.offset ?? 0) + (response.data?.length ?? 0) < (response.meta?.total ?? 0),
+        };
+    }
+    /**
+     * Get a specific HITL approval request by ID.
+     *
+     * Enterprise Feature: Requires AxonFlow Enterprise license.
+     *
+     * @param requestId - The approval request ID
+     * @returns The approval request details
+     *
+     * @example
+     * ```typescript
+     * const request = await client.getHITLRequest('req_abc123');
+     * console.log(`Query: ${request.original_query}`);
+     * console.log(`Policy: ${request.triggered_policy_name}`);
+     * console.log(`Severity: ${request.severity}`);
+     * ```
+     */
+    async getHITLRequest(requestId) {
+        if (!requestId) {
+            throw new ConfigurationError('Request ID is required');
+        }
+        if (this.config.debug) {
+            debugLog('Getting HITL request', { requestId });
+        }
+        const response = await this.orchestratorRequest('GET', `/api/v1/hitl/queue/${requestId}`);
+        return response.data;
+    }
+    /**
+     * Approve an HITL request.
+     *
+     * Approves the specified approval request, allowing the original query to proceed.
+     *
+     * Enterprise Feature: Requires AxonFlow Enterprise license.
+     *
+     * @param requestId - The approval request ID
+     * @param review - Reviewer information and optional comment
+     *
+     * @example
+     * ```typescript
+     * await client.approveHITLRequest('req_abc123', {
+     *   reviewer_id: 'user_456',
+     *   reviewer_email: 'reviewer@example.com',
+     *   comment: 'Approved after verifying compliance'
+     * });
+     * ```
+     */
+    async approveHITLRequest(requestId, review) {
+        if (!requestId) {
+            throw new ConfigurationError('Request ID is required');
+        }
+        if (this.config.debug) {
+            debugLog('Approving HITL request', { requestId, reviewerId: review.reviewer_id });
+        }
+        await this.orchestratorRequest('POST', `/api/v1/hitl/queue/${requestId}/approve`, review);
+    }
+    /**
+     * Reject an HITL request.
+     *
+     * Rejects the specified approval request, blocking the original query.
+     *
+     * Enterprise Feature: Requires AxonFlow Enterprise license.
+     *
+     * @param requestId - The approval request ID
+     * @param review - Reviewer information and optional comment
+     *
+     * @example
+     * ```typescript
+     * await client.rejectHITLRequest('req_abc123', {
+     *   reviewer_id: 'user_456',
+     *   reviewer_email: 'reviewer@example.com',
+     *   comment: 'Rejected: query contains PII data'
+     * });
+     * ```
+     */
+    async rejectHITLRequest(requestId, review) {
+        if (!requestId) {
+            throw new ConfigurationError('Request ID is required');
+        }
+        if (this.config.debug) {
+            debugLog('Rejecting HITL request', { requestId, reviewerId: review.reviewer_id });
+        }
+        await this.orchestratorRequest('POST', `/api/v1/hitl/queue/${requestId}/reject`, review);
+    }
+    /**
+     * Get HITL queue dashboard statistics.
+     *
+     * Returns summary statistics about the HITL queue including
+     * pending counts, priority breakdown, and age of oldest request.
+     *
+     * Enterprise Feature: Requires AxonFlow Enterprise license.
+     *
+     * @returns HITL queue statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.getHITLStats();
+     * console.log(`Pending: ${stats.total_pending}`);
+     * console.log(`Critical: ${stats.critical_priority}`);
+     * if (stats.oldest_pending_hours && stats.oldest_pending_hours > 24) {
+     *   console.warn('Oldest request is over 24 hours old!');
+     * }
+     * ```
+     */
+    async getHITLStats() {
+        if (this.config.debug) {
+            debugLog('Getting HITL stats');
+        }
+        const response = await this.orchestratorRequest('GET', '/api/v1/hitl/stats');
+        return response.data;
+    }
     /**
      * Stream real-time execution status updates via Server-Sent Events (SSE).
      *