@axonflow/sdk 1.11.1 → 1.12.0

package/dist/esm/client.js

@@ -18,6 +18,7 @@ export class AxonFlow {
             apiKey: config.apiKey,
             licenseKey: config.licenseKey,
             endpoint,
+            orchestratorEndpoint: config.orchestratorEndpoint,
             mode: config.mode || (hasCredentials ? 'production' : 'sandbox'),
             tenant: config.tenant || 'default',
             debug: config.debug || false,
@@ -1740,5 +1741,613 @@ export class AxonFlow {
             exportedAt: response.exported_at,
         };
     }
+    // ============================================================================
+    // Execution Replay Methods
+    // ============================================================================
+    /**
+     * Get the orchestrator URL for Execution Replay API.
+     * Falls back to agent endpoint with port 8081 if not configured.
+     */
+    getOrchestratorUrl() {
+        if (this.config.orchestratorEndpoint) {
+            return this.config.orchestratorEndpoint;
+        }
+        // Default: assume orchestrator is on same host as agent, port 8081
+        try {
+            const url = new URL(this.config.endpoint);
+            url.port = '8081';
+            return url.toString().replace(/\/$/, '');
+        }
+        catch {
+            return 'http://localhost:8081';
+        }
+    }
+    /**
+     * Generic HTTP request helper for orchestrator APIs
+     */
+    async orchestratorRequest(method, path, body) {
+        const url = `${this.getOrchestratorUrl()}${path}`;
+        const headers = this.buildAuthHeaders();
+        const options = {
+            method,
+            headers,
+            signal: AbortSignal.timeout(this.config.timeout),
+        };
+        if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
+            options.body = JSON.stringify(body);
+        }
+        const response = await fetch(url, options);
+        if (!response.ok) {
+            const errorText = await response.text();
+            if (response.status === 401 || response.status === 403) {
+                throw new AuthenticationError(`Request failed: ${errorText}`);
+            }
+            if (response.status === 404) {
+                throw new APIError(404, 'Not Found', errorText);
+            }
+            throw new APIError(response.status, response.statusText, errorText);
+        }
+        // Handle DELETE responses with no body
+        if (response.status === 204 || method === 'DELETE') {
+            return undefined;
+        }
+        return response.json();
+    }
+    /**
+     * List workflow executions with optional filtering and pagination.
+     *
+     * @param options - Filtering and pagination options
+     * @returns Paginated list of execution summaries
+     *
+     * @example
+     * ```typescript
+     * // List completed executions
+     * const { executions, total } = await axonflow.listExecutions({
+     *   status: 'completed',
+     *   limit: 10
+     * });
+     *
+     * for (const exec of executions) {
+     *   console.log(`${exec.requestId}: ${exec.status} (${exec.totalSteps} steps)`);
+     * }
+     * ```
+     */
+    async listExecutions(options) {
+        const params = new URLSearchParams();
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        if (options?.offset)
+            params.set('offset', String(options.offset));
+        if (options?.status)
+            params.set('status', options.status);
+        if (options?.workflowId)
+            params.set('workflow_id', options.workflowId);
+        if (options?.startTime)
+            params.set('start_time', options.startTime);
+        if (options?.endTime)
+            params.set('end_time', options.endTime);
+        const queryString = params.toString();
+        const path = `/api/v1/executions${queryString ? `?${queryString}` : ''}`;
+        if (this.config.debug) {
+            debugLog('Listing executions', { options });
+        }
+        const response = await this.orchestratorRequest('GET', path);
+        return {
+            executions: (response.executions || []).map(e => ({
+                requestId: e.request_id,
+                workflowName: e.workflow_name,
+                status: e.status,
+                totalSteps: e.total_steps,
+                completedSteps: e.completed_steps,
+                startedAt: e.started_at,
+                completedAt: e.completed_at,
+                durationMs: e.duration_ms,
+                totalTokens: e.total_tokens,
+                totalCostUsd: e.total_cost_usd,
+                orgId: e.org_id,
+                tenantId: e.tenant_id,
+                userId: e.user_id,
+                errorMessage: e.error_message,
+                inputSummary: e.input_summary,
+                outputSummary: e.output_summary,
+            })),
+            total: response.total,
+            limit: response.limit,
+            offset: response.offset,
+        };
+    }
+    /**
+     * Get a complete execution record including summary and all steps.
+     *
+     * @param executionId - Execution ID (request_id)
+     * @returns Full execution details with all step snapshots
+     *
+     * @example
+     * ```typescript
+     * const execution = await axonflow.getExecution('exec-abc123');
+     * console.log(`Execution: ${execution.summary.requestId} - ${execution.summary.status}`);
+     *
+     * for (const step of execution.steps) {
+     *   console.log(`  Step ${step.stepIndex}: ${step.stepName} (${step.durationMs}ms)`);
+     * }
+     * ```
+     */
+    async getExecution(executionId) {
+        if (this.config.debug) {
+            debugLog('Getting execution', { executionId });
+        }
+        const response = await this.orchestratorRequest('GET', `/api/v1/executions/${executionId}`);
+        return {
+            summary: {
+                requestId: response.summary.request_id,
+                workflowName: response.summary.workflow_name,
+                status: response.summary.status,
+                totalSteps: response.summary.total_steps,
+                completedSteps: response.summary.completed_steps,
+                startedAt: response.summary.started_at,
+                completedAt: response.summary.completed_at,
+                durationMs: response.summary.duration_ms,
+                totalTokens: response.summary.total_tokens,
+                totalCostUsd: response.summary.total_cost_usd,
+                orgId: response.summary.org_id,
+                tenantId: response.summary.tenant_id,
+                userId: response.summary.user_id,
+                errorMessage: response.summary.error_message,
+                inputSummary: response.summary.input_summary,
+                outputSummary: response.summary.output_summary,
+            },
+            steps: response.steps.map(s => ({
+                requestId: s.request_id,
+                stepIndex: s.step_index,
+                stepName: s.step_name,
+                status: s.status,
+                startedAt: s.started_at,
+                completedAt: s.completed_at,
+                durationMs: s.duration_ms,
+                provider: s.provider,
+                model: s.model,
+                tokensIn: s.tokens_in,
+                tokensOut: s.tokens_out,
+                costUsd: s.cost_usd,
+                input: s.input,
+                output: s.output,
+                errorMessage: s.error_message,
+                policiesChecked: s.policies_checked,
+                policiesTriggered: s.policies_triggered,
+                approvalRequired: s.approval_required,
+                approvedBy: s.approved_by,
+                approvedAt: s.approved_at,
+            })),
+        };
+    }
+    /**
+     * Get all step snapshots for an execution.
+     *
+     * @param executionId - Execution ID (request_id)
+     * @returns Array of step snapshots
+     *
+     * @example
+     * ```typescript
+     * const steps = await axonflow.getExecutionSteps('exec-abc123');
+     * for (const step of steps) {
+     *   console.log(`Step ${step.stepIndex}: ${step.stepName} - ${step.status}`);
+     * }
+     * ```
+     */
+    async getExecutionSteps(executionId) {
+        if (this.config.debug) {
+            debugLog('Getting execution steps', { executionId });
+        }
+        const response = await this.orchestratorRequest('GET', `/api/v1/executions/${executionId}/steps`);
+        return response.map(s => ({
+            requestId: s.request_id,
+            stepIndex: s.step_index,
+            stepName: s.step_name,
+            status: s.status,
+            startedAt: s.started_at,
+            completedAt: s.completed_at,
+            durationMs: s.duration_ms,
+            provider: s.provider,
+            model: s.model,
+            tokensIn: s.tokens_in,
+            tokensOut: s.tokens_out,
+            costUsd: s.cost_usd,
+            input: s.input,
+            output: s.output,
+            errorMessage: s.error_message,
+            policiesChecked: s.policies_checked,
+            policiesTriggered: s.policies_triggered,
+            approvalRequired: s.approval_required,
+            approvedBy: s.approved_by,
+            approvedAt: s.approved_at,
+        }));
+    }
+    /**
+     * Get a timeline view of execution events for visualization.
+     *
+     * @param executionId - Execution ID (request_id)
+     * @returns Array of timeline entries
+     *
+     * @example
+     * ```typescript
+     * const timeline = await axonflow.getExecutionTimeline('exec-abc123');
+     * for (const entry of timeline) {
+     *   let info = `[${entry.stepIndex}] ${entry.stepName}: ${entry.status}`;
+     *   if (entry.hasError) info += ' [ERROR]';
+     *   if (entry.hasApproval) info += ' [APPROVED]';
+     *   console.log(info);
+     * }
+     * ```
+     */
+    async getExecutionTimeline(executionId) {
+        if (this.config.debug) {
+            debugLog('Getting execution timeline', { executionId });
+        }
+        const response = await this.orchestratorRequest('GET', `/api/v1/executions/${executionId}/timeline`);
+        return response.map(t => ({
+            stepIndex: t.step_index,
+            stepName: t.step_name,
+            status: t.status,
+            startedAt: t.started_at,
+            completedAt: t.completed_at,
+            durationMs: t.duration_ms,
+            hasError: t.has_error,
+            hasApproval: t.has_approval,
+        }));
+    }
+    /**
+     * Export a complete execution record for compliance or archival.
+     *
+     * @param executionId - Execution ID (request_id)
+     * @param options - Export options
+     * @returns Execution data in requested format
+     *
+     * @example
+     * ```typescript
+     * const exportData = await axonflow.exportExecution('exec-abc123', {
+     *   includeInput: true,
+     *   includeOutput: true
+     * });
+     *
+     * // Save to file for audit
+     * fs.writeFileSync('audit-export.json', JSON.stringify(exportData, null, 2));
+     * ```
+     */
+    async exportExecution(executionId, options) {
+        const params = new URLSearchParams();
+        if (options?.format)
+            params.set('format', options.format);
+        if (options?.includeInput)
+            params.set('include_input', 'true');
+        if (options?.includeOutput)
+            params.set('include_output', 'true');
+        if (options?.includePolicies)
+            params.set('include_policies', 'true');
+        const queryString = params.toString();
+        const path = `/api/v1/executions/${executionId}/export${queryString ? `?${queryString}` : ''}`;
+        if (this.config.debug) {
+            debugLog('Exporting execution', { executionId, options });
+        }
+        return this.orchestratorRequest('GET', path);
+    }
+    /**
+     * Delete an execution and all associated step snapshots.
+     *
+     * @param executionId - Execution ID (request_id)
+     *
+     * @example
+     * ```typescript
+     * await axonflow.deleteExecution('exec-abc123');
+     * console.log('Execution deleted');
+     * ```
+     */
+    async deleteExecution(executionId) {
+        if (this.config.debug) {
+            debugLog('Deleting execution', { executionId });
+        }
+        await this.orchestratorRequest('DELETE', `/api/v1/executions/${executionId}`);
+    }
+    // ========================================
+    // COST CONTROLS - BUDGETS
+    // ========================================
+    /**
+     * Create a new budget.
+     *
+     * @param request - Budget creation request
+     * @returns Created budget
+     */
+    async createBudget(request) {
+        const body = {
+            id: request.id,
+            name: request.name,
+            scope: request.scope,
+            limit_usd: request.limitUsd,
+            period: request.period,
+            on_exceed: request.onExceed,
+            alert_thresholds: request.alertThresholds,
+            scope_id: request.scopeId,
+        };
+        const response = await this.orchestratorRequest('POST', '/api/v1/budgets', body);
+        return this.mapBudgetResponse(response);
+    }
+    /**
+     * Get a budget by ID.
+     *
+     * @param budgetId - Budget ID
+     * @returns Budget
+     */
+    async getBudget(budgetId) {
+        const response = await this.orchestratorRequest('GET', `/api/v1/budgets/${budgetId}`);
+        return this.mapBudgetResponse(response);
+    }
+    /**
+     * List all budgets.
+     *
+     * @param options - Filtering and pagination options
+     * @returns List of budgets
+     */
+    async listBudgets(options) {
+        const params = new URLSearchParams();
+        if (options?.scope)
+            params.set('scope', options.scope);
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        if (options?.offset)
+            params.set('offset', String(options.offset));
+        const queryString = params.toString();
+        const path = `/api/v1/budgets${queryString ? `?${queryString}` : ''}`;
+        const response = await this.orchestratorRequest('GET', path);
+        return {
+            budgets: (response.budgets || []).map(b => this.mapBudgetResponse(b)),
+            total: response.total || 0,
+        };
+    }
+    /**
+     * Update an existing budget.
+     *
+     * @param budgetId - Budget ID
+     * @param request - Update request
+     * @returns Updated budget
+     */
+    async updateBudget(budgetId, request) {
+        const body = {};
+        if (request.name !== undefined)
+            body.name = request.name;
+        if (request.limitUsd !== undefined)
+            body.limit_usd = request.limitUsd;
+        if (request.onExceed !== undefined)
+            body.on_exceed = request.onExceed;
+        if (request.alertThresholds !== undefined)
+            body.alert_thresholds = request.alertThresholds;
+        const response = await this.orchestratorRequest('PUT', `/api/v1/budgets/${budgetId}`, body);
+        return this.mapBudgetResponse(response);
+    }
+    /**
+     * Delete a budget.
+     *
+     * @param budgetId - Budget ID
+     */
+    async deleteBudget(budgetId) {
+        await this.orchestratorRequest('DELETE', `/api/v1/budgets/${budgetId}`);
+    }
+    // ========================================
+    // COST CONTROLS - BUDGET STATUS & ALERTS
+    // ========================================
+    /**
+     * Get the current status of a budget.
+     *
+     * @param budgetId - Budget ID
+     * @returns Budget status
+     */
+    async getBudgetStatus(budgetId) {
+        const response = await this.orchestratorRequest('GET', `/api/v1/budgets/${budgetId}/status`);
+        return {
+            budget: this.mapBudgetResponse(response.budget),
+            usedUsd: response.used_usd || 0,
+            remainingUsd: response.remaining_usd || 0,
+            percentage: response.percentage || 0,
+            isExceeded: response.is_exceeded || false,
+            isBlocked: response.is_blocked || false,
+            periodStart: response.period_start || '',
+            periodEnd: response.period_end || '',
+        };
+    }
+    /**
+     * Get alerts for a budget.
+     *
+     * @param budgetId - Budget ID
+     * @returns Budget alerts
+     */
+    async getBudgetAlerts(budgetId) {
+        const response = await this.orchestratorRequest('GET', `/api/v1/budgets/${budgetId}/alerts`);
+        const alerts = (response.alerts || []).map((a) => ({
+            id: a.id || '',
+            budgetId: a.budget_id || '',
+            alertType: a.alert_type || '',
+            threshold: a.threshold || 0,
+            percentageReached: a.percentage_reached || 0,
+            amountUsd: a.amount_usd || 0,
+            message: a.message || '',
+            createdAt: a.created_at || '',
+        }));
+        return {
+            alerts,
+            count: response.count || 0,
+        };
+    }
+    /**
+     * Perform a pre-flight budget check.
+     *
+     * @param request - Check request
+     * @returns Budget decision
+     */
+    async checkBudget(request) {
+        const body = {};
+        if (request.orgId)
+            body.org_id = request.orgId;
+        if (request.teamId)
+            body.team_id = request.teamId;
+        if (request.agentId)
+            body.agent_id = request.agentId;
+        if (request.workflowId)
+            body.workflow_id = request.workflowId;
+        if (request.userId)
+            body.user_id = request.userId;
+        const response = await this.orchestratorRequest('POST', '/api/v1/budgets/check', body);
+        return {
+            allowed: response.allowed || false,
+            action: response.action,
+            message: response.message,
+            budgets: response.budgets
+                ? (response.budgets || []).map(b => this.mapBudgetResponse(b))
+                : undefined,
+        };
+    }
+    // ========================================
+    // COST CONTROLS - USAGE
+    // ========================================
+    /**
+     * Get usage summary for a period.
+     *
+     * @param period - Period (daily, weekly, monthly, quarterly, yearly)
+     * @returns Usage summary
+     */
+    async getUsageSummary(period) {
+        const path = period ? `/api/v1/usage?period=${period}` : '/api/v1/usage';
+        const response = await this.orchestratorRequest('GET', path);
+        return {
+            totalCostUsd: response.total_cost_usd || 0,
+            totalRequests: response.total_requests || 0,
+            totalTokensIn: response.total_tokens_in || 0,
+            totalTokensOut: response.total_tokens_out || 0,
+            averageCostPerRequest: response.average_cost_per_request || 0,
+            period: response.period || '',
+            periodStart: response.period_start || '',
+            periodEnd: response.period_end || '',
+        };
+    }
+    /**
+     * Get usage breakdown by a grouping dimension.
+     *
+     * @param groupBy - Dimension to group by (provider, model, agent, team, workflow)
+     * @param period - Period (daily, weekly, monthly, quarterly, yearly)
+     * @returns Usage breakdown
+     */
+    async getUsageBreakdown(groupBy, period) {
+        const params = new URLSearchParams();
+        params.set('group_by', groupBy);
+        if (period)
+            params.set('period', period);
+        const response = await this.orchestratorRequest('GET', `/api/v1/usage/breakdown?${params.toString()}`);
+        const items = (response.items || []).map((i) => ({
+            groupValue: i.group_value || '',
+            costUsd: i.cost_usd || 0,
+            percentage: i.percentage || 0,
+            requestCount: i.request_count || 0,
+            tokensIn: i.tokens_in || 0,
+            tokensOut: i.tokens_out || 0,
+        }));
+        return {
+            groupBy: response.group_by || '',
+            totalCostUsd: response.total_cost_usd || 0,
+            items,
+            period: response.period || '',
+            periodStart: response.period_start || '',
+            periodEnd: response.period_end || '',
+        };
+    }
+    /**
+     * List usage records.
+     *
+     * @param options - Filtering and pagination options
+     * @returns List of usage records
+     */
+    async listUsageRecords(options) {
+        const params = new URLSearchParams();
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        if (options?.offset)
+            params.set('offset', String(options.offset));
+        if (options?.provider)
+            params.set('provider', options.provider);
+        if (options?.model)
+            params.set('model', options.model);
+        const queryString = params.toString();
+        const path = `/api/v1/usage/records${queryString ? `?${queryString}` : ''}`;
+        const response = await this.orchestratorRequest('GET', path);
+        const records = (response.records || []).map((r) => ({
+            id: r.id || '',
+            provider: r.provider || '',
+            model: r.model || '',
+            tokensIn: r.tokens_in || 0,
+            tokensOut: r.tokens_out || 0,
+            costUsd: r.cost_usd || 0,
+            requestId: r.request_id,
+            orgId: r.org_id,
+            agentId: r.agent_id,
+            timestamp: r.timestamp,
+        }));
+        return {
+            records,
+            total: response.total || 0,
+        };
+    }
+    // ========================================
+    // COST CONTROLS - PRICING
+    // ========================================
+    /**
+     * Get pricing information for models.
+     *
+     * @param provider - Filter by provider (optional)
+     * @param model - Filter by model (optional)
+     * @returns Pricing information
+     */
+    async getPricing(provider, model) {
+        const params = new URLSearchParams();
+        if (provider)
+            params.set('provider', provider);
+        if (model)
+            params.set('model', model);
+        const queryString = params.toString();
+        const path = `/api/v1/pricing${queryString ? `?${queryString}` : ''}`;
+        const response = await this.orchestratorRequest('GET', path);
+        // Handle single object vs array response
+        if (response.provider !== undefined) {
+            // Single object response - wrap in list
+            const pricing = this.mapPricingResponse(response);
+            return { pricing: [pricing] };
+        }
+        const pricingList = (response.pricing || []).map(p => this.mapPricingResponse(p));
+        return { pricing: pricingList };
+    }
+    // ========================================
+    // COST CONTROLS - HELPER METHODS
+    // ========================================
+    mapBudgetResponse(response) {
+        return {
+            id: response.id || '',
+            name: response.name || '',
+            scope: response.scope || '',
+            limitUsd: response.limit_usd || 0,
+            period: response.period || '',
+            onExceed: response.on_exceed || '',
+            alertThresholds: response.alert_thresholds || [],
+            enabled: response.enabled ?? true,
+            scopeId: response.scope_id,
+            createdAt: response.created_at,
+            updatedAt: response.updated_at,
+        };
+    }
+    mapPricingResponse(response) {
+        const pricingData = response.pricing;
+        return {
+            provider: response.provider || '',
+            model: response.model || '',
+            pricing: {
+                inputPer1k: pricingData?.input_per_1k || 0,
+                outputPer1k: pricingData?.output_per_1k || 0,
+            },
+        };
+    }
 }
 //# sourceMappingURL=client.js.map