@axonflow/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AxonFlow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,386 @@
+# AxonFlow SDK for TypeScript
+
+Add invisible AI governance to your applications in 3 lines of code. No UI changes. No user training. Just drop-in enterprise protection.
+
+## Installation
+
+```bash
+npm install @axonflow/sdk
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { AxonFlow } from '@axonflow/sdk';
+import OpenAI from 'openai';
+
+// Initialize your AI client as usual
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+// Add AxonFlow governance (3 lines)
+const axonflow = new AxonFlow({ apiKey: process.env.AXONFLOW_API_KEY });
+
+// Wrap any AI call with protect()
+const response = await axonflow.protect(async () => {
+  return openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Process this customer data...' }]
+  });
+});
+```
+
+### Even Easier with Client Wrapping
+
+```typescript
+import { AxonFlow, wrapOpenAIClient } from '@axonflow/sdk';
+import OpenAI from 'openai';
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const axonflow = new AxonFlow({ apiKey: process.env.AXONFLOW_API_KEY });
+
+// Wrap the entire client - all calls are now protected
+const protectedOpenAI = wrapOpenAIClient(openai, axonflow);
+
+// Use normally - governance happens invisibly
+const response = await protectedOpenAI.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Process this customer data...' }]
+});
+```
+
+## React Example
+
+```tsx
+import { AxonFlow } from '@axonflow/sdk';
+import { useState } from 'react';
+
+const axonflow = new AxonFlow({ apiKey: 'your-key' });
+
+function ChatComponent() {
+  const [response, setResponse] = useState('');
+
+  const handleSubmit = async (prompt: string) => {
+    // Your existing OpenAI call, now protected
+    const result = await axonflow.protect(async () => {
+      return fetch('/api/openai', {
+        method: 'POST',
+        body: JSON.stringify({ prompt })
+      }).then(r => r.json());
+    });
+
+    setResponse(result.text);
+  };
+
+  return (
+    // Your existing UI - no changes needed
+    <div>...</div>
+  );
+}
+```
+
+## Next.js API Route
+
+```typescript
+// pages/api/chat.ts
+import { AxonFlow } from '@axonflow/sdk';
+import OpenAI from 'openai';
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const axonflow = new AxonFlow({ apiKey: process.env.AXONFLOW_API_KEY });
+
+export default async function handler(req, res) {
+  const { prompt } = req.body;
+
+  try {
+    // Protect the OpenAI call
+    const response = await axonflow.protect(async () => {
+      return openai.chat.completions.create({
+        model: 'gpt-3.5-turbo',
+        messages: [{ role: 'user', content: prompt }]
+      });
+    });
+
+    res.json({ success: true, response });
+  } catch (error) {
+    // AxonFlow will block requests that violate policies
+    res.status(403).json({ error: error.message });
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+const axonflow = new AxonFlow({
+  apiKey: 'your-api-key',           // Required (use client_id from AxonFlow)
+
+  // Optional settings
+  mode: 'production',                // or 'sandbox' for testing
+  endpoint: 'https://staging-eu.getaxonflow.com', // Default public endpoint
+  tenant: 'your-tenant-id',         // For multi-tenant setups (use client_id)
+  debug: true,                       // Enable debug logging
+
+  // Retry configuration
+  retry: {
+    enabled: true,
+    maxAttempts: 3,
+    delay: 1000
+  },
+
+  // Cache configuration
+  cache: {
+    enabled: true,
+    ttl: 60000  // 1 minute
+  }
+});
+```
+
+### VPC Private Endpoint (Low-Latency)
+
+For customers running within AWS VPC, use the private endpoint for sub-10ms latency:
+
+```typescript
+const axonflow = new AxonFlow({
+  apiKey: 'your-client-id',
+  endpoint: 'https://10.0.2.67:8443',  // VPC private endpoint (EU)
+  tenant: 'your-client-id',
+  mode: 'production'
+});
+```
+
+**Performance:**
+- Public endpoint: ~100ms (internet routing)
+- VPC private endpoint: <10ms P99 (intra-VPC routing)
+
+**Note:** VPC endpoints require AWS VPC peering setup with AxonFlow infrastructure.
+
+## Sandbox Mode (Testing)
+
+```typescript
+// Use sandbox mode for testing without affecting production
+const axonflow = AxonFlow.sandbox('demo-key');
+
+// Test with aggressive policies
+const response = await axonflow.protect(async () => {
+  return openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{
+      role: 'user',
+      content: 'My SSN is 123-45-6789' // Will be blocked/redacted
+    }]
+  });
+});
+```
+
+## What Gets Protected?
+
+AxonFlow automatically:
+- **Blocks** prompts containing sensitive data (PII, credentials, etc.)
+- **Redacts** personal information from responses
+- **Enforces** rate limits and usage quotas
+- **Prevents** prompt injection attacks
+- **Logs** all requests for compliance audit trails
+- **Monitors** costs and usage patterns
+
+## Error Handling
+
+```typescript
+try {
+  const response = await axonflow.protect(() => openai.complete(prompt));
+} catch (error) {
+  if (error.message.includes('blocked by AxonFlow')) {
+    // Request violated a policy
+    console.log('Policy violation:', error.message);
+  } else {
+    // Other errors (network, API, etc.)
+    console.error('API error:', error);
+  }
+}
+```
+
+## Production Best Practices
+
+1. **Environment Variables**: Never hardcode API keys
+   ```typescript
+   const axonflow = new AxonFlow({
+     apiKey: process.env.AXONFLOW_API_KEY
+   });
+   ```
+
+2. **Fail Open**: In production, AxonFlow fails open if unreachable
+   ```typescript
+   // If AxonFlow is down, the original call proceeds
+   // This ensures your app stays operational
+   ```
+
+3. **Tenant Isolation**: Use tenant IDs for multi-tenant apps
+   ```typescript
+   const axonflow = new AxonFlow({
+     apiKey: 'your-key',
+     tenant: getCurrentTenantId()
+   });
+   ```
+
+## Support
+
+- Documentation: https://docs.axonflow.com
+- Email: support@axonflow.com
+- GitHub: https://github.com/axonflow/sdk-typescript
+
+## MCP Connector Marketplace
+
+Integrate with external data sources using AxonFlow's MCP (Model Context Protocol) connectors:
+
+### List Available Connectors
+
+```typescript
+const connectors = await axonflow.listConnectors();
+
+connectors.forEach(conn => {
+  console.log(`Connector: ${conn.name} (${conn.type})`);
+  console.log(`  Description: ${conn.description}`);
+  console.log(`  Installed: ${conn.installed}`);
+  console.log(`  Capabilities: ${conn.capabilities.join(', ')}`);
+});
+```
+
+### Install a Connector
+
+```typescript
+await axonflow.installConnector({
+  connector_id: 'amadeus-travel',
+  name: 'amadeus-prod',
+  tenant_id: 'your-tenant-id',
+  options: {
+    environment: 'production'
+  },
+  credentials: {
+    api_key: process.env.AMADEUS_API_KEY,
+    api_secret: process.env.AMADEUS_API_SECRET
+  }
+});
+
+console.log('Connector installed successfully!');
+```
+
+### Query a Connector
+
+```typescript
+// Query the Amadeus connector for flight information
+const resp = await axonflow.queryConnector(
+  'amadeus-prod',
+  'Find flights from Paris to Amsterdam on Dec 15',
+  {
+    origin: 'CDG',
+    destination: 'AMS',
+    date: '2025-12-15'
+  }
+);
+
+if (resp.success) {
+  console.log('Flight data:', resp.data);
+} else {
+  console.error('Query failed:', resp.error);
+}
+```
+
+## Multi-Agent Planning (MAP)
+
+Generate and execute complex multi-step plans using AI agent orchestration:
+
+### Generate a Plan
+
+```typescript
+// Generate a travel planning workflow
+const plan = await axonflow.generatePlan(
+  'Plan a 3-day trip to Paris with moderate budget',
+  'travel'  // Domain hint (optional)
+);
+
+console.log(`Generated plan ${plan.planId} with ${plan.steps.length} steps`);
+console.log(`Complexity: ${plan.complexity}, Parallel: ${plan.parallel}`);
+
+plan.steps.forEach((step, i) => {
+  console.log(`  Step ${i + 1}: ${step.name} (${step.type})`);
+  console.log(`    Description: ${step.description}`);
+  console.log(`    Agent: ${step.agent}`);
+  if (step.dependsOn.length > 0) {
+    console.log(`    Depends on: ${step.dependsOn.join(', ')}`);
+  }
+});
+```
+
+### Execute a Plan
+
+```typescript
+// Execute the generated plan
+const execResp = await axonflow.executePlan(plan.planId);
+
+console.log(`Plan Status: ${execResp.status}`);
+console.log(`Duration: ${execResp.duration}`);
+
+if (execResp.status === 'completed') {
+  console.log(`Result:\n${execResp.result}`);
+
+  // Access individual step results
+  Object.entries(execResp.stepResults || {}).forEach(([stepId, result]) => {
+    console.log(`  ${stepId}:`, result);
+  });
+} else if (execResp.status === 'failed') {
+  console.error(`Error: ${execResp.error}`);
+}
+```
+
+### Check Plan Status
+
+```typescript
+// For long-running plans, check status periodically
+const status = await axonflow.getPlanStatus(plan.planId);
+
+console.log(`Plan Status: ${status.status}`);
+if (status.status === 'running') {
+  console.log('Plan is still executing...');
+}
+```
+
+### Complete Example: Trip Planning with MAP
+
+```typescript
+import { AxonFlow } from '@axonflow/sdk';
+
+async function planTrip() {
+  // Initialize client
+  const axonflow = new AxonFlow({
+    apiKey: process.env.AXONFLOW_API_KEY,
+    debug: true
+  });
+
+  // 1. Generate multi-agent plan
+  const plan = await axonflow.generatePlan(
+    'Plan a 3-day trip to Paris for 2 people with moderate budget',
+    'travel'
+  );
+
+  console.log(`✅ Generated plan with ${plan.steps.length} steps (parallel: ${plan.parallel})`);
+
+  // 2. Execute the plan
+  console.log('\n🚀 Executing plan...');
+  const execResp = await axonflow.executePlan(plan.planId);
+
+  // 3. Display results
+  if (execResp.status === 'completed') {
+    console.log(`\n✅ Plan completed in ${execResp.duration}`);
+    console.log(`\n📋 Complete Itinerary:\n${execResp.result}`);
+  } else {
+    console.error(`\n❌ Plan failed: ${execResp.error}`);
+  }
+}
+
+planTrip().catch(console.error);
+```
+
+## License
+
+MIT

package/dist/cjs/client.d.ts

@@ -0,0 +1,60 @@
+import { AxonFlowConfig, ConnectorMetadata, ConnectorInstallRequest, ConnectorResponse, PlanResponse, PlanExecutionResponse } from './types';
+/**
+ * Main AxonFlow client for invisible AI governance
+ */
+export declare class AxonFlow {
+    private config;
+    private interceptors;
+    constructor(config: AxonFlowConfig);
+    /**
+     * Main method to protect AI calls with governance
+     * @param aiCall The AI call to protect
+     * @returns The AI response after governance
+     */
+    protect<T = any>(aiCall: () => Promise<T>): Promise<T>;
+    /**
+     * Extract request details from an AI call
+     */
+    private extractRequest;
+    /**
+     * Check policies with AxonFlow Agent
+     */
+    private checkPolicies;
+    /**
+     * Log audit trail
+     */
+    private logAudit;
+    /**
+     * Check if an error is from AxonFlow (vs the AI provider)
+     */
+    private isAxonFlowError;
+    /**
+     * Create a sandbox client for testing
+     */
+    static sandbox(apiKey?: string): AxonFlow;
+    /**
+     * List all available MCP connectors from the marketplace
+     */
+    listConnectors(): Promise<ConnectorMetadata[]>;
+    /**
+     * Install an MCP connector from the marketplace
+     */
+    installConnector(request: ConnectorInstallRequest): Promise<void>;
+    /**
+     * Execute a query against an installed MCP connector
+     */
+    queryConnector(connectorName: string, query: string, params?: any): Promise<ConnectorResponse>;
+    /**
+     * Generate a multi-agent execution plan from a natural language query
+     */
+    generatePlan(query: string, domain?: string): Promise<PlanResponse>;
+    /**
+     * Execute a previously generated multi-agent plan
+     */
+    executePlan(planId: string): Promise<PlanExecutionResponse>;
+    /**
+     * Get the status of a running or completed plan
+     */
+    getPlanStatus(planId: string): Promise<PlanExecutionResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EAId,iBAAiB,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAMjB;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,YAAY,CAAyB;gBAEjC,MAAM,EAAE,cAAc;IAwBlC;;;;OAIG;IACG,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAqD5D;;OAEG;YACW,cAAc;IAiB5B;;OAEG;YACW,aAAa;IAuD3B;;OAEG;YACW,QAAQ;IAYtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,GAAE,MAAmB,GAAG,QAAQ;IASrD;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAqBpD;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBvE;;OAEG;IACG,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0CpG;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA6CzE;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAyCjE;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAwBpE"}