@axonflow/sdk 2.1.0 → 2.3.0

package/dist/esm/client.js

@@ -1,4 +1,4 @@
-import { AuthenticationError, APIError, PolicyViolationError } from './errors.js';
+import { AuthenticationError, APIError, PolicyViolationError, ConfigurationError, ConnectorError, PlanExecutionError, } from './errors.js';
 import { OpenAIInterceptor } from './interceptors/openai.js';
 import { AnthropicInterceptor } from './interceptors/anthropic.js';
 import { generateRequestId, debugLog } from './utils/helpers.js';
@@ -9,15 +9,19 @@ export class AxonFlow {
     constructor(config) {
         this.interceptors = [];
         this.sessionCookie = null;
+        // Configuration validation
+        if (config.clientSecret && !config.clientId) {
+            throw new ConfigurationError('clientSecret requires clientId to be set. ' +
+                'Provide both clientId and clientSecret for OAuth2-style authentication.');
+        }
         // Set defaults first to determine endpoint
         const endpoint = config.endpoint || 'https://staging-eu.getaxonflow.com';
-        // Credentials are optional for community/self-hosted deployments
-        // Enterprise features (Gateway Mode, Policy CRUD) require credentials
-        const hasCredentials = !!(config.licenseKey || config.apiKey);
+        // Credentials check: OAuth2-style (clientId/clientSecret)
+        const hasCredentials = !!(config.clientId && config.clientSecret);
         // Set configuration
         this.config = {
-            apiKey: config.apiKey,
-            licenseKey: config.licenseKey,
+            clientId: config.clientId,
+            clientSecret: config.clientSecret,
             endpoint,
             mode: config.mode || (hasCredentials ? 'production' : 'sandbox'),
             tenant: config.tenant || 'default',
@@ -37,17 +41,33 @@ export class AxonFlow {
         // Initialize interceptors
         this.interceptors = [new OpenAIInterceptor(), new AnthropicInterceptor()];
         if (this.config.debug) {
+            // Determine auth method for logging
+            const authMethod = hasCredentials ? 'client-credentials' : 'community (no auth)';
             debugLog('AxonFlow initialized', {
                 mode: this.config.mode,
                 endpoint: this.config.endpoint,
-                authMethod: hasCredentials
-                    ? this.config.licenseKey
-                        ? 'license-key'
-                        : 'api-key'
-                    : 'community (no auth)',
+                authMethod,
             });
         }
     }
+    /**
+     * Get authentication headers based on configured credentials.
+     *
+     * Uses OAuth2-style Basic auth: Authorization: Basic base64(clientId:clientSecret)
+     * Also adds X-Tenant-ID header from clientId for tenant context.
+     *
+     * @returns Headers object with authentication headers
+     */
+    getAuthHeaders() {
+        const headers = {};
+        // OAuth2-style client credentials
+        if (this.config.clientId && this.config.clientSecret) {
+            const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+            headers['Authorization'] = `Basic ${credentials}`;
+            headers['X-Tenant-ID'] = this.config.clientId;
+        }
+        return headers;
+    }
     /**
      * Main method to protect AI calls with governance
      * @param aiCall The AI call to protect
@@ -166,8 +186,8 @@ export class AxonFlow {
         // Transform SDK request to Agent API format
         const agentRequest = {
             query: request.aiRequest.prompt,
-            user_token: this.config.apiKey || '',
-            client_id: this.config.tenant,
+            user_token: '',
+            client_id: this.config.clientId || this.config.tenant,
             request_type: 'llm_chat',
             context: {
                 provider: request.aiRequest.provider,
@@ -179,12 +199,8 @@ export class AxonFlow {
         };
         const headers = {
             'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
         };
-        // Add auth headers only when credentials are provided
-        // Community/self-hosted mode works without credentials
-        if (this.config.licenseKey) {
-            headers['X-License-Key'] = this.config.licenseKey;
-        }
         const response = await fetch(url, {
             method: 'POST',
             headers,
@@ -247,9 +263,10 @@ export class AxonFlow {
     /**
      * Create a sandbox client for testing
      */
-    static sandbox(apiKey = 'demo-key') {
+    static sandbox(clientId = 'demo-client', clientSecret = 'demo-secret') {
         return new AxonFlow({
-            apiKey,
+            clientId,
+            clientSecret,
             mode: 'sandbox',
             endpoint: 'https://staging-eu.getaxonflow.com',
             debug: true,
@@ -386,9 +403,11 @@ export class AxonFlow {
      * ```
      */
     async executeQuery(options) {
+        // Default to "anonymous" if userToken is empty/undefined (community mode)
+        const effectiveUserToken = options.userToken || 'anonymous';
         const agentRequest = {
             query: options.query,
-            user_token: options.userToken,
+            user_token: effectiveUserToken,
             client_id: this.config.tenant,
             request_type: options.requestType,
             context: options.context || {},
@@ -396,15 +415,8 @@ export class AxonFlow {
         const url = `${this.config.endpoint}/api/request`;
         const headers = {
             'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
         };
-        // Add auth headers only when credentials are provided
-        // Community/self-hosted mode works without credentials
-        if (this.config.licenseKey) {
-            headers['X-License-Key'] = this.config.licenseKey;
-        }
-        else if (this.config.apiKey) {
-            headers['X-Client-Secret'] = this.config.apiKey;
-        }
         if (this.config.debug) {
             debugLog('Proxy Mode: executeQuery', {
                 requestType: options.requestType,
@@ -529,8 +541,8 @@ export class AxonFlow {
     async queryConnector(connectorName, query, params) {
         const agentRequest = {
             query,
-            user_token: this.config.apiKey || '',
-            client_id: this.config.tenant,
+            user_token: '',
+            client_id: this.config.clientId || this.config.tenant,
             request_type: 'mcp-query',
             context: {
                 connector: connectorName,
@@ -540,10 +552,8 @@ export class AxonFlow {
         const url = `${this.config.endpoint}/api/request`;
         const headers = {
             'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
         };
-        if (this.config.licenseKey) {
-            headers['X-License-Key'] = this.config.licenseKey;
-        }
         const response = await fetch(url, {
             method: 'POST',
             headers,
@@ -552,7 +562,7 @@ export class AxonFlow {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Connector query failed: ${response.status} ${response.statusText} - ${errorText}`);
+            throw new ConnectorError(`Connector query failed: ${response.status} ${response.statusText} - ${errorText}`, connectorName, 'query');
         }
         const agentResponse = await response.json();
         if (this.config.debug) {
@@ -565,6 +575,94 @@ export class AxonFlow {
             meta: agentResponse.metadata,
         };
     }
+    /**
+     * Execute a query directly against the MCP connector endpoint.
+     *
+     * This method calls the agent's /mcp/resources/query endpoint which provides:
+     * - Request-phase policy evaluation (SQLi blocking, PII blocking)
+     * - Response-phase policy evaluation (PII redaction)
+     * - PolicyInfo metadata in responses
+     *
+     * @example
+     * ```typescript
+     * const response = await axonflow.mcpQuery({
+     *   connector: 'postgres',
+     *   statement: 'SELECT * FROM customers LIMIT 10',
+     * });
+     *
+     * if (response.redacted) {
+     *   console.log('Fields redacted:', response.redacted_fields);
+     * }
+     * console.log('Policies evaluated:', response.policy_info?.policies_evaluated);
+     * ```
+     *
+     * @param options - Query options including connector name and SQL statement
+     * @returns ConnectorResponse with data, redaction info, and policy_info
+     * @throws ConnectorError if the request is blocked by policy or fails
+     */
+    async mcpQuery(options) {
+        if (!options.connector) {
+            throw new ConnectorError('connector name is required', undefined, 'mcpQuery');
+        }
+        if (!options.statement) {
+            throw new ConnectorError('statement is required', undefined, 'mcpQuery');
+        }
+        const url = `${this.config.endpoint}/mcp/resources/query`;
+        const headers = {
+            'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
+        };
+        const body = {
+            connector: options.connector,
+            statement: options.statement,
+            options: options.options || {},
+        };
+        if (this.config.debug) {
+            debugLog('MCP Query', {
+                connector: options.connector,
+                statement: options.statement.substring(0, 50),
+            });
+        }
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.config.timeout),
+        });
+        const responseData = await response.json();
+        // Handle policy blocks (403 responses)
+        if (!response.ok) {
+            throw new ConnectorError(responseData.error || `MCP query failed: ${response.status} ${response.statusText}`, options.connector, 'mcpQuery');
+        }
+        if (this.config.debug) {
+            debugLog('MCP Query result', {
+                connector: options.connector,
+                success: responseData.success,
+                redacted: responseData.redacted,
+                policiesEvaluated: responseData.policy_info?.policies_evaluated,
+            });
+        }
+        return {
+            success: responseData.success,
+            data: responseData.data,
+            error: responseData.error,
+            meta: responseData.meta,
+            redacted: responseData.redacted,
+            redacted_fields: responseData.redacted_fields,
+            policy_info: responseData.policy_info,
+        };
+    }
+    /**
+     * Execute a statement against an MCP connector (alias for mcpQuery).
+     *
+     * Same as mcpQuery but follows the naming convention of other execute* methods.
+     *
+     * @param options - Query options including connector name and SQL statement
+     * @returns ConnectorResponse with data, redaction info, and policy_info
+     */
+    async mcpExecute(options) {
+        return this.mcpQuery(options);
+    }
     /**
      * Generate a multi-agent execution plan from a natural language query
      * @param query - Natural language query describing the task
@@ -582,10 +680,8 @@ export class AxonFlow {
         const url = `${this.config.endpoint}/api/request`;
         const headers = {
             'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
         };
-        if (this.config.licenseKey) {
-            headers['X-License-Key'] = this.config.licenseKey;
-        }
         // Use mapTimeout for MAP operations (default 2 minutes)
         const response = await fetch(url, {
             method: 'POST',
@@ -595,11 +691,11 @@ export class AxonFlow {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Plan generation failed: ${response.status} ${response.statusText} - ${errorText}`);
+            throw new PlanExecutionError(`Plan generation failed: ${response.status} ${response.statusText} - ${errorText}`, undefined, 'generation');
         }
         const agentResponse = await response.json();
         if (!agentResponse.success) {
-            throw new Error(`Plan generation failed: ${agentResponse.error}`);
+            throw new PlanExecutionError(`Plan generation failed: ${agentResponse.error}`, undefined, 'generation');
         }
         // plan_id can be at top level or inside data
         const planId = agentResponse.plan_id || agentResponse.data?.plan_id;
@@ -631,10 +727,8 @@ export class AxonFlow {
         const url = `${this.config.endpoint}/api/request`;
         const headers = {
             'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
         };
-        if (this.config.licenseKey) {
-            headers['X-License-Key'] = this.config.licenseKey;
-        }
         // Use mapTimeout for MAP operations (default 2 minutes)
         const response = await fetch(url, {
             method: 'POST',
@@ -644,7 +738,7 @@ export class AxonFlow {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Plan execution failed: ${response.status} ${response.statusText} - ${errorText}`);
+            throw new PlanExecutionError(`Plan execution failed: ${response.status} ${response.statusText} - ${errorText}`, planId, 'execution');
         }
         const agentResponse = await response.json();
         if (this.config.debug) {
@@ -663,7 +757,7 @@ export class AxonFlow {
      * Get the status of a running or completed plan
      */
     async getPlanStatus(planId) {
-        const url = `${this.config.endpoint}/api/plans/${planId}`;
+        const url = `${this.config.endpoint}/api/v1/plan/${planId}`;
         const response = await fetch(url, {
             method: 'GET',
             signal: AbortSignal.timeout(this.config.timeout),
@@ -746,15 +840,8 @@ export class AxonFlow {
         };
         const headers = {
             'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
         };
-        // Add auth headers only when credentials are provided
-        // Community/self-hosted mode works without credentials
-        if (this.config.licenseKey) {
-            headers['X-License-Key'] = this.config.licenseKey;
-        }
-        else if (this.config.apiKey) {
-            headers['X-Client-Secret'] = this.config.apiKey;
-        }
         if (this.config.debug) {
             debugLog('Gateway Mode: Pre-check', { query: options.query.substring(0, 50) });
         }
@@ -845,15 +932,8 @@ export class AxonFlow {
         };
         const headers = {
             'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
         };
-        // Add auth headers only when credentials are provided
-        // Community/self-hosted mode works without credentials
-        if (this.config.licenseKey) {
-            headers['X-License-Key'] = this.config.licenseKey;
-        }
-        else if (this.config.apiKey) {
-            headers['X-Client-Secret'] = this.config.apiKey;
-        }
         if (this.config.debug) {
             debugLog('Gateway Mode: Audit', {
                 contextId: options.contextId,
@@ -1035,24 +1115,20 @@ export class AxonFlow {
     // Policy CRUD Methods - Static Policies
     // ============================================================================
     /**
-     * Build authentication headers for API requests
+     * Build authentication headers for API requests.
+     * Includes Content-Type and X-Org-ID for policy APIs.
+     * Uses getAuthHeaders() for authentication credentials.
      */
     buildAuthHeaders() {
         const headers = {
             'Content-Type': 'application/json',
+            ...this.getAuthHeaders(),
         };
         // Always include tenant ID for policy APIs (X-Org-ID header for server compatibility)
+        // Note: getAuthHeaders() already adds X-Tenant-ID when tenant is non-default
         if (this.config.tenant) {
             headers['X-Org-ID'] = this.config.tenant;
         }
-        // Add auth headers only when credentials are provided
-        // Community/self-hosted mode works without credentials
-        if (this.config.licenseKey) {
-            headers['X-License-Key'] = this.config.licenseKey;
-        }
-        else if (this.config.apiKey) {
-            headers['X-Client-Secret'] = this.config.apiKey;
-        }
         return headers;
     }
     /**
@@ -1077,8 +1153,8 @@ export class AxonFlow {
             }
             throw new APIError(response.status, response.statusText, errorText);
         }
-        // Handle DELETE responses with no body
-        if (response.status === 204 || method === 'DELETE') {
+        // Handle 204 No Content responses
+        if (response.status === 204) {
             return undefined;
         }
         return response.json();
@@ -1432,7 +1508,7 @@ export class AxonFlow {
         // API returns {"policies": [...]} wrapper via Agent proxy
         const response = await this.orchestratorRequest('GET', path);
         // Handle both wrapped and unwrapped responses for compatibility
-        return Array.isArray(response) ? response : response.policies;
+        return Array.isArray(response) ? response : response.policies || [];
     }
     /**
      * Get a specific dynamic policy by ID.
@@ -1540,7 +1616,7 @@ export class AxonFlow {
         // API returns {"policies": [...]} wrapper via Agent proxy
         const response = await this.orchestratorRequest('GET', path);
         // Handle both wrapped and unwrapped responses for compatibility
-        return Array.isArray(response) ? response : response.policies;
+        return Array.isArray(response) ? response : response.policies || [];
     }
     // ============================================================================
     // Portal Authentication Methods (Enterprise)
@@ -1925,6 +2001,49 @@ export class AxonFlow {
             providerType: response.provider_type,
         };
     }
+    /**
+     * Close a PR without merging and optionally delete the branch.
+     * Useful for cleaning up test PRs created by examples.
+     *
+     * @param prId - PR record ID
+     * @param deleteBranch - Whether to delete the associated branch (default: true)
+     * @returns Closed PR record
+     *
+     * @example
+     * ```typescript
+     * // Close PR and delete branch
+     * const pr = await axonflow.closePR('pr_123');
+     * console.log(`PR #${pr.prNumber} closed`);
+     *
+     * // Close PR but keep branch
+     * const pr = await axonflow.closePR('pr_123', false);
+     * ```
+     */
+    async closePR(prId, deleteBranch = true) {
+        if (this.config.debug) {
+            debugLog('Closing PR', { prId, deleteBranch });
+        }
+        const query = deleteBranch ? '?delete_branch=true' : '';
+        const response = await this.portalRequest('DELETE', `/api/v1/code-governance/prs/${prId}${query}`);
+        return {
+            id: response.id,
+            prNumber: response.pr_number,
+            prUrl: response.pr_url,
+            title: response.title,
+            state: response.state,
+            owner: response.owner,
+            repo: response.repo,
+            headBranch: response.head_branch,
+            baseBranch: response.base_branch,
+            filesCount: response.files_count,
+            secretsDetected: response.secrets_detected,
+            unsafePatterns: response.unsafe_patterns,
+            createdAt: response.created_at,
+            closedAt: response.closed_at,
+            createdBy: response.created_by,
+            providerType: response.provider_type,
+        };
+    }
     /**
      * Sync PR status with the Git provider.
      * This updates the local record with the current state from GitHub/GitLab/Bitbucket.
@@ -2118,8 +2237,8 @@ export class AxonFlow {
             }
             throw new APIError(response.status, response.statusText, errorText);
         }
-        // Handle DELETE responses with no body
-        if (response.status === 204 || method === 'DELETE') {
+        // Handle 204 No Content responses
+        if (response.status === 204) {
             return undefined;
         }
         return response.json();
@@ -2162,8 +2281,8 @@ export class AxonFlow {
             }
             throw new APIError(response.status, response.statusText, errorText);
         }
-        // Handle DELETE responses with no body
-        if (response.status === 204 || method === 'DELETE') {
+        // Handle 204 No Content responses
+        if (response.status === 204) {
             return undefined;
         }
         return response.json();