@axonflow/sdk 4.1.0 → 4.3.0

package/dist/esm/client.js

@@ -153,12 +153,12 @@ export class AxonFlow {
      * });
      * ```
      *
-     * See: https://docs.getaxonflow.com/sdk/gateway-mode
+     * See: https://docs.getaxonflow.com/docs/sdk/gateway-mode
      */
     async protect(aiCall) {
         console.warn('[AxonFlow] protect() is deprecated and will be removed in a future version. ' +
             'Use Gateway Mode (getPolicyApprovedContext + auditLLMCall) or Proxy Mode (proxyLLMCall) instead. ' +
-            'See: https://docs.getaxonflow.com/sdk/gateway-mode');
+            'See: https://docs.getaxonflow.com/docs/sdk/gateway-mode');
         try {
             // Extract request details from the AI call
             const aiRequest = await this.extractRequest(aiCall);
@@ -1495,6 +1495,267 @@ export class AxonFlow {
         };
     }
     // ============================================================================
+    // Circuit Breaker Observability Methods
+    // ============================================================================
+    /**
+     * Get all active circuit breaker circuits.
+     *
+     * Returns the current state of all open/half-open circuits across
+     * the platform, including emergency stop status.
+     *
+     * @returns Promise resolving to circuit breaker status
+     *
+     * @example
+     * ```typescript
+     * const status = await axonflow.getCircuitBreakerStatus();
+     * console.log(`Active circuits: ${status.count}`);
+     * console.log(`Emergency stop: ${status.emergencyStopActive}`);
+     * for (const circuit of status.activeCircuits) {
+     *   console.log(`${circuit.scope}/${circuit.scopeId}: ${circuit.state}`);
+     * }
+     * ```
+     */
+    async getCircuitBreakerStatus() {
+        const response = await this.orchestratorRequest('GET', '/api/v1/circuit-breaker/status');
+        const data = response.data;
+        return {
+            activeCircuits: (data.active_circuits || []).map(c => ({
+                id: c.id,
+                scope: c.scope,
+                scopeId: c.scope_id,
+                orgId: c.org_id,
+                state: c.state,
+                tripReason: c.trip_reason,
+                trippedBy: c.tripped_by,
+                trippedAt: c.tripped_at,
+                expiresAt: c.expires_at,
+                errorCount: c.error_count,
+                violationCount: c.violation_count,
+            })),
+            count: data.count,
+            emergencyStopActive: data.emergency_stop_active,
+        };
+    }
+    /**
+     * Get circuit breaker history for audit trail.
+     *
+     * Returns historical circuit breaker events including trips, resets,
+     * and manual interventions. Useful for compliance reporting.
+     *
+     * @param limit - Maximum number of history entries to return
+     * @returns Promise resolving to circuit breaker history
+     *
+     * @example
+     * ```typescript
+     * const history = await axonflow.getCircuitBreakerHistory(50);
+     * for (const entry of history.history) {
+     *   console.log(`${entry.trippedAt}: ${entry.scope}/${entry.scopeId} - ${entry.state}`);
+     * }
+     * ```
+     */
+    async getCircuitBreakerHistory(limit) {
+        const params = new URLSearchParams();
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        const queryString = params.toString();
+        const path = `/api/v1/circuit-breaker/history${queryString ? `?${queryString}` : ''}`;
+        const response = await this.orchestratorRequest('GET', path);
+        const data = response.data;
+        return {
+            history: (data.history || []).map(h => ({
+                id: h.id,
+                orgId: h.org_id,
+                scope: h.scope,
+                scopeId: h.scope_id,
+                state: h.state,
+                tripReason: h.trip_reason,
+                trippedBy: h.tripped_by,
+                trippedByEmail: h.tripped_by_email,
+                tripComment: h.trip_comment,
+                trippedAt: h.tripped_at,
+                expiresAt: h.expires_at,
+                resetBy: h.reset_by,
+                resetAt: h.reset_at,
+                errorCount: h.error_count,
+                violationCount: h.violation_count,
+            })),
+            count: data.count,
+        };
+    }
+    /**
+     * Get circuit breaker config (global or tenant-specific).
+     *
+     * Returns the effective circuit breaker configuration, including
+     * any tenant-specific overrides.
+     *
+     * @param tenantId - Optional tenant ID to get tenant-specific config
+     * @returns Promise resolving to circuit breaker config
+     *
+     * @example
+     * ```typescript
+     * // Get global config
+     * const globalConfig = await axonflow.getCircuitBreakerConfig();
+     * console.log(`Error threshold: ${globalConfig.errorThreshold}`);
+     *
+     * // Get tenant-specific config
+     * const tenantConfig = await axonflow.getCircuitBreakerConfig('tenant-123');
+     * ```
+     */
+    async getCircuitBreakerConfig(tenantId) {
+        const params = new URLSearchParams();
+        if (tenantId !== undefined)
+            params.set('tenant_id', tenantId);
+        const queryString = params.toString();
+        const path = `/api/v1/circuit-breaker/config${queryString ? `?${queryString}` : ''}`;
+        const response = await this.orchestratorRequest('GET', path);
+        const data = response.data;
+        return {
+            source: data.source,
+            errorThreshold: data.error_threshold,
+            violationThreshold: data.violation_threshold,
+            windowSeconds: data.window_seconds,
+            defaultTimeoutSeconds: data.default_timeout_seconds,
+            maxTimeoutSeconds: data.max_timeout_seconds,
+            enableAutoRecovery: data.enable_auto_recovery,
+            tenantId: data.tenant_id,
+            overrides: data.overrides,
+        };
+    }
+    /**
+     * Update per-tenant circuit breaker config.
+     *
+     * Allows customizing circuit breaker thresholds for a specific tenant.
+     * Only provided fields will be updated; others retain their current values.
+     *
+     * @param config - Configuration update with tenant ID and fields to change
+     * @returns Promise resolving to confirmation with tenant ID and message
+     *
+     * @example
+     * ```typescript
+     * const result = await axonflow.updateCircuitBreakerConfig({
+     *   tenantId: 'tenant-123',
+     *   errorThreshold: 10,
+     *   windowSeconds: 120,
+     * });
+     * console.log(result.message); // "config updated"
+     * ```
+     */
+    async updateCircuitBreakerConfig(config) {
+        if (!config.tenantId) {
+            throw new ConfigurationError('tenantId is required');
+        }
+        const body = {
+            tenant_id: config.tenantId,
+        };
+        if (config.errorThreshold !== undefined)
+            body.error_threshold = config.errorThreshold;
+        if (config.violationThreshold !== undefined)
+            body.violation_threshold = config.violationThreshold;
+        if (config.windowSeconds !== undefined)
+            body.window_seconds = config.windowSeconds;
+        if (config.defaultTimeoutSeconds !== undefined)
+            body.default_timeout_seconds = config.defaultTimeoutSeconds;
+        if (config.maxTimeoutSeconds !== undefined)
+            body.max_timeout_seconds = config.maxTimeoutSeconds;
+        if (config.enableAutoRecovery !== undefined)
+            body.enable_auto_recovery = config.enableAutoRecovery;
+        const response = await this.orchestratorRequest('PUT', '/api/v1/circuit-breaker/config', body);
+        return {
+            tenantId: response.data.tenant_id,
+            message: response.data.message,
+        };
+    }
+    // ============================================================================
+    // Policy Simulation Methods (Evaluation Tier+)
+    // ============================================================================
+    /**
+     * Simulate policy evaluation against a hypothetical request.
+     *
+     * Dry-run policy evaluation that shows which policies would match and what
+     * actions would be taken, without affecting live traffic. Available on
+     * Evaluation tier and above.
+     *
+     * @param request - The simulated request to evaluate against policies
+     * @returns Promise resolving to simulation results
+     *
+     * @example
+     * ```typescript
+     * const result = await axonflow.simulatePolicies({
+     *   query: 'Show me all customer SSNs',
+     *   request_type: 'chat',
+     *   user: { role: 'analyst', department: 'support' },
+     * });
+     * console.log(`Allowed: ${result.allowed}`);
+     * console.log(`Policies matched: ${result.applied_policies.join(', ')}`);
+     * console.log(`Risk score: ${result.risk_score}`);
+     * ```
+     */
+    async simulatePolicies(request) {
+        const body = { query: request.query };
+        if (request.request_type !== undefined)
+            body.request_type = request.request_type;
+        if (request.user !== undefined)
+            body.user = request.user;
+        if (request.client !== undefined)
+            body.client = request.client;
+        if (request.context !== undefined)
+            body.context = request.context;
+        return this.orchestratorRequest('POST', '/api/v1/policies/simulate', body);
+    }
+    /**
+     * Generate a policy impact report for a specific policy against sample inputs.
+     *
+     * Tests a policy against multiple sample inputs to understand its match rate,
+     * block rate, and per-input behavior. Useful for tuning policy configurations
+     * before deploying to production.
+     *
+     * @param policyId - The ID of the policy to evaluate
+     * @param inputs - Array of sample inputs to test against the policy
+     * @returns Promise resolving to the impact report
+     *
+     * @example
+     * ```typescript
+     * const report = await axonflow.getPolicyImpactReport('policy-123', [
+     *   { query: 'Show me all customer SSNs', request_type: 'chat' },
+     *   { query: 'What is the weather today?', request_type: 'chat' },
+     *   { query: 'Delete all user records', request_type: 'chat' },
+     * ]);
+     * console.log(`Match rate: ${report.match_rate}`);
+     * console.log(`Block rate: ${report.block_rate}`);
+     * ```
+     */
+    async getPolicyImpactReport(policyId, inputs) {
+        return this.orchestratorRequest('POST', '/api/v1/policies/impact-report', {
+            policy_id: policyId,
+            inputs,
+        });
+    }
+    /**
+     * Detect conflicts between policies.
+     *
+     * Analyzes policies for overlapping rules, contradictory actions, or
+     * other conflict patterns. Optionally scoped to a specific policy.
+     *
+     * @param policyId - Optional policy ID to check conflicts for a specific policy
+     * @returns Promise resolving to detected conflicts
+     *
+     * @example
+     * ```typescript
+     * // Check all policies for conflicts
+     * const allConflicts = await axonflow.detectPolicyConflicts();
+     * console.log(`Found ${allConflicts.conflict_count} conflicts`);
+     *
+     * // Check conflicts for a specific policy
+     * const policyConflicts = await axonflow.detectPolicyConflicts('policy-123');
+     * ```
+     */
+    async detectPolicyConflicts(policyId) {
+        const body = {};
+        if (policyId !== undefined)
+            body.policy_id = policyId;
+        return this.orchestratorRequest('POST', '/api/v1/policies/conflicts', body);
+    }
+    // ============================================================================
     // Audit Log Read Methods
     // ============================================================================
     /**