@ayurak/aribot-cli 1.0.5 → 1.0.7

package/src/sdk.ts

@@ -0,0 +1,1017 @@
+/**
+ * Aribot Node.js SDK - Economic, Regulatory & Security APIs for Modern Applications
+ *
+ * Analyze your tech stack. Optimize architecture. Model costs. Identify threats dynamically.
+ * APIs that help you build better systems with practical, actionable recommendations.
+ *
+ * Platform Capabilities:
+ *   - Advanced Threat Modeling: Multi-framework (STRIDE, PASTA, NIST, Aristiun Framework)
+ *   - Cloud Security: Real-time CSPM, CNAPP, misconfiguration detection
+ *   - Living Architecture: Dynamic architecture diagrams with real-time updates
+ *   - Economic Intelligence: Security ROI, TCO analysis, risk quantification in real dollars
+ *   - FinOps: Cloud cost optimization, security spend tracking
+ *   - Compliance: 100+ regulatory standards (SOC2, ISO27001, NIST, PCI-DSS, GDPR, HIPAA, etc.)
+ *   - Red Team: Automated attack simulations, penetration testing orchestration
+ *
+ * Usage:
+ *   import { AribotClient } from '@ayurak/aribot-cli';
+ *
+ *   const client = new AribotClient({ apiKey: 'ak_...' });
+ *
+ *   // Threat Modeling
+ *   const diagram = await client.threatModeling.upload('architecture.png');
+ *   const threats = await client.threatModeling.getThreats(diagram.id);
+ *
+ *   // Compliance
+ *   const assessment = await client.compliance.assess(diagramId, 'SOC2');
+ *
+ *   // Red Team
+ *   const simulation = await client.redteam.runSimulation(targetId, 'lateral_movement');
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+
+const VERSION = '1.0.6';
+const DEFAULT_BASE_URL = 'https://api.aribot.ayurak.com/aribot-api';
+
+// =============================================================================
+// TYPES & INTERFACES
+// =============================================================================
+
+export interface AribotConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+}
+
+export interface Diagram {
+  id: string;
+  name: string;
+  filename?: string;
+  stage: string;
+  threats_count: number;
+  created_at: string;
+  updated_at?: string;
+}
+
+export interface Threat {
+  id: string;
+  title: string;
+  description?: string;
+  severity: string;
+  category: string;
+  stride_category?: string;
+  mitigation?: string;
+  cvss_score?: number;
+  attack_vector?: string;
+}
+
+export interface ComplianceAssessment {
+  id: string;
+  standard: string;
+  score: number;
+  passed_controls: number;
+  failed_controls: number;
+  status: string;
+  created_at: string;
+}
+
+export interface SecurityFinding {
+  id: string;
+  title: string;
+  severity: string;
+  resource_type: string;
+  resource_id: string;
+  policy: string;
+  remediation?: string;
+  status: string;
+}
+
+export interface PaginatedResponse<T> {
+  count: number;
+  next?: string;
+  previous?: string;
+  results: T[];
+}
+
+// =============================================================================
+// ERRORS
+// =============================================================================
+
+export class AribotError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AribotError';
+  }
+}
+
+export class AuthenticationError extends AribotError {
+  constructor(message: string = 'Invalid or expired API key') {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class RateLimitError extends AribotError {
+  retryAfter?: number;
+
+  constructor(message: string = 'Rate limit exceeded', retryAfter?: number) {
+    super(message);
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class APIError extends AribotError {
+  statusCode?: number;
+  response?: any;
+
+  constructor(message: string, statusCode?: number, response?: any) {
+    super(message);
+    this.name = 'APIError';
+    this.statusCode = statusCode;
+    this.response = response;
+  }
+}
+
+// =============================================================================
+// API CLIENT
+// =============================================================================
+
+export class AribotClient {
+  private apiKey: string;
+  private baseUrl: string;
+  private timeout: number;
+  private maxRetries: number;
+
+  // Resource managers
+  public threatModeling: ThreatModelingResource;
+  public cloudSecurity: CloudSecurityResource;
+  public compliance: ComplianceResource;
+  public economics: EconomicsResource;
+  public finops: FinOpsResource;
+  public redteam: RedTeamResource;
+  public architecture: ArchitectureResource;
+  public user: UserResource;
+  public ai: AIResource;  // Secure AI usage management
+
+  // Aliases
+  public diagrams: ThreatModelingResource;
+
+  constructor(config: AribotConfig = {}) {
+    this.apiKey = config.apiKey || process.env.ARIBOT_API_KEY || '';
+    if (!this.apiKey) {
+      throw new AuthenticationError(
+        'API key required. Pass apiKey in config or set ARIBOT_API_KEY env var.'
+      );
+    }
+
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.timeout = config.timeout || 60000;
+    this.maxRetries = config.maxRetries || 3;
+
+    // Initialize resources
+    this.threatModeling = new ThreatModelingResource(this);
+    this.cloudSecurity = new CloudSecurityResource(this);
+    this.compliance = new ComplianceResource(this);
+    this.economics = new EconomicsResource(this);
+    this.finops = new FinOpsResource(this);
+    this.redteam = new RedTeamResource(this);
+    this.architecture = new ArchitectureResource(this);
+    this.user = new UserResource(this);
+    this.ai = new AIResource(this);
+
+    // Aliases
+    this.diagrams = this.threatModeling;
+  }
+
+  private getHeaders(contentType: string = 'application/json'): Record<string, string> {
+    const headers: Record<string, string> = {
+      'X-API-Key': this.apiKey,
+      'User-Agent': `aribot-sdk/${VERSION} (Node.js)`,
+      'X-Request-ID': crypto.randomBytes(16).toString('base64url'),
+      'X-Request-Timestamp': new Date().toISOString(),
+    };
+    if (contentType) {
+      headers['Content-Type'] = contentType;
+    }
+    return headers;
+  }
+
+  private getAuthHeader(): Record<string, string> {
+    return {
+      'Authorization': `Bearer ${this.apiKey}`,
+      'User-Agent': `aribot-sdk/${VERSION} (Node.js)`,
+      'X-Request-ID': crypto.randomBytes(16).toString('base64url'),
+      'X-Request-Timestamp': new Date().toISOString(),
+    };
+  }
+
+  async request<T = any>(
+    method: string,
+    endpoint: string,
+    options: {
+      body?: any;
+      params?: Record<string, string | number>;
+      formData?: FormData;
+    } = {}
+  ): Promise<T> {
+    const fetch = (await import('node-fetch')).default;
+    const url = new URL(`${this.baseUrl}${endpoint}`);
+
+    if (options.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        url.searchParams.set(key, String(value));
+      });
+    }
+
+    const headers = options.formData ? this.getAuthHeader() : this.getHeaders();
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const requestOptions: any = {
+          method,
+          headers,
+          timeout: this.timeout,
+        };
+
+        if (options.formData) {
+          requestOptions.body = options.formData;
+        } else if (options.body) {
+          requestOptions.body = JSON.stringify(options.body);
+        }
+
+        const response = await fetch(url.toString(), requestOptions);
+
+        if (response.ok) {
+          const contentType = response.headers.get('content-type');
+          if (contentType?.includes('application/json')) {
+            return await response.json() as T;
+          }
+          return await response.buffer() as any;
+        }
+
+        if (response.status === 401) {
+          throw new AuthenticationError();
+        }
+
+        if (response.status === 403) {
+          throw new AuthenticationError('Access denied. Check API key permissions.');
+        }
+
+        if (response.status === 429) {
+          const retryAfter = response.headers.get('Retry-After');
+          throw new RateLimitError(
+            'Rate limit exceeded',
+            retryAfter ? parseInt(retryAfter) : undefined
+          );
+        }
+
+        let errorMessage: string;
+        try {
+          const errorData = await response.json() as any;
+          errorMessage = errorData.detail || errorData.message || JSON.stringify(errorData);
+        } catch {
+          errorMessage = `HTTP ${response.status}`;
+        }
+
+        throw new APIError(errorMessage, response.status);
+
+      } catch (error: any) {
+        lastError = error;
+
+        if (error instanceof AuthenticationError) {
+          throw error;
+        }
+
+        if (error instanceof RateLimitError && error.retryAfter) {
+          await this.sleep(error.retryAfter * 1000);
+          continue;
+        }
+
+        if (error.code === 'ETIMEDOUT' || error.code === 'ECONNRESET') {
+          const sleepTime = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
+          await this.sleep(sleepTime);
+          continue;
+        }
+
+        throw error;
+      }
+    }
+
+    throw lastError || new APIError(`Request failed after ${this.maxRetries} attempts`);
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+// =============================================================================
+// THREAT MODELING RESOURCE
+// =============================================================================
+
+class ThreatModelingResource {
+  constructor(private client: AribotClient) {}
+
+  async list(options: { limit?: number; offset?: number } = {}): Promise<PaginatedResponse<Diagram>> {
+    return this.client.request('GET', '/v2/threat-modeling/diagrams/', {
+      params: { limit: options.limit || 20, offset: options.offset || 0 }
+    });
+  }
+
+  async get(diagramId: string): Promise<Diagram> {
+    return this.client.request('GET', `/v2/threat-modeling/diagrams/${diagramId}/`);
+  }
+
+  async upload(
+    filePath: string,
+    options: { name?: string; autoGenerateThreats?: boolean } = {}
+  ): Promise<Diagram> {
+    const FormData = (await import('form-data')).default;
+    const form = new FormData();
+
+    form.append('file', fs.createReadStream(filePath));
+    form.append('name', options.name || path.basename(filePath, path.extname(filePath)));
+    form.append('auto_generate_threats', String(options.autoGenerateThreats !== false));
+
+    return this.client.request('POST', '/v2/threat-modeling/diagrams/upload-analyze/', {
+      formData: form as any
+    });
+  }
+
+  async getThreats(diagramId: string, options: { severity?: string } = {}): Promise<Threat[]> {
+    const data = await this.client.request<any>('GET', `/v2/threat-modeling/diagrams/${diagramId}/threats/`, {
+      params: options.severity ? { severity: options.severity } : {}
+    });
+    return data.threats || data.results || [];
+  }
+
+  async generateThreats(
+    diagramId: string,
+    options: { waitForCompletion?: boolean; timeout?: number } = {}
+  ): Promise<Diagram> {
+    await this.client.request('POST', `/v2/threat-modeling/diagrams/${diagramId}/generate-threats/`);
+
+    if (options.waitForCompletion !== false) {
+      const timeout = options.timeout || 120000;
+      const start = Date.now();
+
+      while (Date.now() - start < timeout) {
+        await new Promise(r => setTimeout(r, 2000));
+        const status = await this.get(diagramId);
+        if (status.stage === 'completed') {
+          return status;
+        }
+      }
+    }
+
+    return this.get(diagramId);
+  }
+
+  async export(
+    diagramId: string,
+    options: { format?: string; outputPath?: string } = {}
+  ): Promise<any> {
+    const format = options.format || 'json';
+    const data = await this.client.request('GET', `/v2/threat-modeling/diagrams/${diagramId}/export/`, {
+      params: { format }
+    });
+
+    if (options.outputPath) {
+      if (format === 'json') {
+        fs.writeFileSync(options.outputPath, JSON.stringify(data, null, 2));
+      } else {
+        fs.writeFileSync(options.outputPath, data);
+      }
+    }
+
+    return data;
+  }
+}
+
+// =============================================================================
+// CLOUD SECURITY RESOURCE
+// =============================================================================
+
+class CloudSecurityResource {
+  constructor(private client: AribotClient) {}
+
+  async scanPosture(cloudProvider?: string): Promise<any> {
+    return this.client.request('POST', '/v2/cloud-security/scan/', {
+      params: cloudProvider ? { provider: cloudProvider } : {}
+    });
+  }
+
+  async getFindings(options: { severity?: string; status?: string; limit?: number } = {}): Promise<SecurityFinding[]> {
+    const data = await this.client.request<any>('GET', '/v2/cloud-security/findings/', {
+      params: {
+        status: options.status || 'open',
+        limit: options.limit || 50,
+        ...(options.severity && { severity: options.severity })
+      }
+    });
+    return data.results || data.findings || [];
+  }
+
+  async getDashboard(): Promise<any> {
+    return this.client.request('GET', '/v2/cloud-security/dashboard/');
+  }
+
+  async remediate(findingId: string, autoFix: boolean = false): Promise<any> {
+    return this.client.request('POST', `/v2/cloud-security/findings/${findingId}/remediate/`, {
+      body: { auto_fix: autoFix }
+    });
+  }
+}
+
+// =============================================================================
+// COMPLIANCE RESOURCE
+// =============================================================================
+
+class ComplianceResource {
+  // 100+ supported standards
+  static SUPPORTED_STANDARDS = [
+    'SOC2', 'ISO27001', 'ISO27017', 'ISO27018', 'ISO22301',
+    'NIST-CSF', 'NIST-800-53', 'NIST-800-171',
+    'PCI-DSS', 'PCI-DSS-4.0',
+    'GDPR', 'CCPA', 'LGPD', 'PIPEDA',
+    'HIPAA', 'HITRUST',
+    'FedRAMP-Low', 'FedRAMP-Moderate', 'FedRAMP-High',
+    'CIS-AWS', 'CIS-Azure', 'CIS-GCP', 'CIS-Kubernetes',
+    'SOX', 'GLBA', 'FISMA',
+    'CSA-CCM', 'CSA-STAR',
+    'MITRE-ATT&CK', 'OWASP-TOP-10',
+  ];
+
+  constructor(private client: AribotClient) {}
+
+  async listStandards(): Promise<any[]> {
+    return this.client.request('GET', '/v2/compliances/custom-standards/');
+  }
+
+  async assess(
+    diagramId: string,
+    standard: string = 'SOC2',
+    includeRecommendations: boolean = true
+  ): Promise<ComplianceAssessment> {
+    return this.client.request('POST', '/v2/compliances/assess_diagram/', {
+      body: {
+        diagram_id: diagramId,
+        standard,
+        include_recommendations: includeRecommendations
+      }
+    });
+  }
+
+  async getAssessment(assessmentId: string): Promise<ComplianceAssessment> {
+    return this.client.request('GET', `/v2/compliances/compliance-reports/${assessmentId}/`);
+  }
+
+  async listReports(limit: number = 20): Promise<ComplianceAssessment[]> {
+    const data = await this.client.request<any>('GET', '/v2/compliances/reports/', {
+      params: { limit }
+    });
+    return data.results || [];
+  }
+
+  async runScan(
+    targetId: string,
+    standards: string[] = ['SOC2', 'ISO27001'],
+    scanType: string = 'comprehensive'
+  ): Promise<any> {
+    return this.client.request('POST', '/v2/compliances/scan/', {
+      body: { target_id: targetId, standards, scan_type: scanType }
+    });
+  }
+
+  async getRemediation(findingId: string): Promise<any> {
+    return this.client.request('GET', `/v2/compliances/remediation/${findingId}/`);
+  }
+
+  async getDashboard(): Promise<any> {
+    return this.client.request('GET', '/v2/compliances/dashboard/trends/');
+  }
+}
+
+// =============================================================================
+// ECONOMICS INTELLIGENCE RESOURCE
+// =============================================================================
+
+class EconomicsResource {
+  constructor(private client: AribotClient) {}
+
+  async calculateROI(
+    securityInvestment: number,
+    riskReductionPercent: number = 50,
+    timeHorizonYears: number = 3
+  ): Promise<any> {
+    return this.client.request('POST', '/v2/economic-intelligence/v2/roi/create/', {
+      body: {
+        investment: securityInvestment,
+        risk_reduction: riskReductionPercent,
+        time_horizon: timeHorizonYears
+      }
+    });
+  }
+
+  async calculateTCO(
+    cloudProvider: string,
+    workloadType: string = 'general',
+    durationMonths: number = 36
+  ): Promise<any> {
+    return this.client.request('POST', '/v2/economic-intelligence/tco/', {
+      body: {
+        provider: cloudProvider,
+        workload_type: workloadType,
+        duration_months: durationMonths
+      }
+    });
+  }
+
+  async analyzeCosts(diagramId: string): Promise<any> {
+    return this.client.request('POST', '/v2/economic-intelligence/analyze/', {
+      body: { diagram_id: diagramId }
+    });
+  }
+
+  async getMarketIntelligence(): Promise<any> {
+    return this.client.request('GET', '/v2/economic-intelligence/v2/intelligence/');
+  }
+
+  async getDashboard(): Promise<any> {
+    return this.client.request('GET', '/v2/economic-intelligence/v2/dashboard/');
+  }
+
+  async createForecast(months: number = 12): Promise<any> {
+    return this.client.request('POST', '/v2/economic-intelligence/v2/forecast/create/', {
+      body: { forecast_months: months }
+    });
+  }
+}
+
+// =============================================================================
+// FINOPS RESOURCE
+// =============================================================================
+
+class FinOpsResource {
+  constructor(private client: AribotClient) {}
+
+  async getCloudCosts(options: { provider?: string; period?: string } = {}): Promise<any> {
+    return this.client.request('GET', '/v2/finops/costs/', {
+      params: {
+        period: options.period || 'month',
+        ...(options.provider && { provider: options.provider })
+      }
+    });
+  }
+
+  async getSecuritySpend(): Promise<any> {
+    return this.client.request('GET', '/v2/finops/security-spend/');
+  }
+
+  async getOptimizationRecommendations(): Promise<any[]> {
+    const data = await this.client.request<any>('GET', '/v2/finops/recommendations/');
+    return data.recommendations || [];
+  }
+
+  async getPricing(service: string, provider: string = 'aws'): Promise<any> {
+    return this.client.request('GET', '/v2/economic-intelligence/pricing/', {
+      params: { service, provider }
+    });
+  }
+}
+
+// =============================================================================
+// RED TEAM RESOURCE
+// =============================================================================
+
+class RedTeamResource {
+  static ATTACK_TYPES = [
+    'lateral_movement',
+    'privilege_escalation',
+    'data_exfiltration',
+    'ransomware',
+    'supply_chain',
+    'insider_threat',
+    'credential_theft',
+    'api_abuse',
+  ];
+
+  constructor(private client: AribotClient) {}
+
+  async runSimulation(
+    targetId: string,
+    attackType: string = 'lateral_movement',
+    intensity: string = 'medium'
+  ): Promise<any> {
+    if (!RedTeamResource.ATTACK_TYPES.includes(attackType)) {
+      throw new AribotError(`Invalid attack type. Choose from: ${RedTeamResource.ATTACK_TYPES.join(', ')}`);
+    }
+
+    return this.client.request('POST', '/v2/redteam/simulate/', {
+      body: {
+        target_id: targetId,
+        attack_type: attackType,
+        intensity
+      }
+    });
+  }
+
+  async getAttackPaths(diagramId: string): Promise<any[]> {
+    const data = await this.client.request<any>('GET', `/v2/threat-modeling/diagrams/${diagramId}/attack-paths/`);
+    return data.attack_paths || [];
+  }
+
+  async listSimulations(limit: number = 20): Promise<any[]> {
+    const data = await this.client.request<any>('GET', '/v2/redteam/simulations/', {
+      params: { limit }
+    });
+    return data.results || [];
+  }
+
+  async getSimulation(simulationId: string): Promise<any> {
+    return this.client.request('GET', `/v2/redteam/simulations/${simulationId}/`);
+  }
+}
+
+// =============================================================================
+// ARCHITECTURE RESOURCE
+// =============================================================================
+
+class ArchitectureResource {
+  constructor(private client: AribotClient) {}
+
+  async listComponents(diagramId: string): Promise<any[]> {
+    const data = await this.client.request<any>('GET', `/v2/threat-modeling/diagrams/${diagramId}/components/`);
+    return data.components || data.results || [];
+  }
+
+  async getComponent(diagramId: string, componentId: string): Promise<any> {
+    return this.client.request('GET', `/v2/threat-modeling/diagrams/${diagramId}/components/${componentId}/`);
+  }
+
+  async updateComponent(diagramId: string, componentId: string, updates: any): Promise<any> {
+    return this.client.request('PATCH', `/v2/threat-modeling/diagrams/${diagramId}/components/${componentId}/`, {
+      body: updates
+    });
+  }
+
+  async getConnections(diagramId: string): Promise<any[]> {
+    const data = await this.client.request<any>('GET', `/v2/threat-modeling/diagrams/${diagramId}/connections/`);
+    return data.connections || data.results || [];
+  }
+}
+
+// =============================================================================
+// USER RESOURCE
+// =============================================================================
+
+class UserResource {
+  constructor(private client: AribotClient) {}
+
+  async me(): Promise<any> {
+    return this.client.request('GET', '/v1/users/me/');
+  }
+
+  async apiKeys(): Promise<any[]> {
+    return this.client.request('GET', '/v1/developer/api-keys/');
+  }
+
+  async getUsage(): Promise<any> {
+    return this.client.request('GET', '/v1/developer/usage/');
+  }
+
+  async getRateLimits(): Promise<any> {
+    return this.client.request('GET', '/v1/developer/rate-limits/');
+  }
+}
+
+// =============================================================================
+// AI RESOURCE - Secure AI Usage Management
+// =============================================================================
+
+class AIResource {
+  /**
+   * Secure AI usage management and configuration.
+   *
+   * Features:
+   *   - AI model selection and configuration
+   *   - Usage tracking and quotas
+   *   - Cost monitoring for AI operations
+   *   - Secure prompt/response handling
+   *   - AI processing queue management
+   *
+   * Security:
+   *   - All AI requests are signed and authenticated
+   *   - Sensitive data is sanitized before AI processing
+   *   - Usage is tracked per API key for audit compliance
+   *   - Rate limiting prevents abuse
+   */
+
+  static AI_OPERATIONS = [
+    'threat_analysis',
+    'diagram_parsing',
+    'compliance_mapping',
+    'risk_scoring',
+    'attack_path_analysis',
+    'remediation_generation',
+    'architecture_optimization',
+  ];
+
+  static MODEL_TIERS = ['standard', 'advanced', 'enterprise'];
+
+  constructor(private client: AribotClient) {}
+
+  /**
+   * Get AI usage statistics for the current billing period.
+   */
+  async getUsage(): Promise<any> {
+    return this.client.request('GET', '/v2/ai/usage/');
+  }
+
+  /**
+   * Get current AI quota and limits.
+   */
+  async getQuota(): Promise<any> {
+    return this.client.request('GET', '/v2/ai/quota/');
+  }
+
+  /**
+   * List available AI models for your subscription tier.
+   */
+  async getModels(): Promise<any[]> {
+    return this.client.request('GET', '/v2/ai/models/');
+  }
+
+  /**
+   * Configure AI settings for your account.
+   */
+  async configure(options: {
+    modelTier?: string;
+    maxTokens?: number;
+    temperature?: number;
+    enableCaching?: boolean;
+  } = {}): Promise<any> {
+    const modelTier = options.modelTier || 'standard';
+    if (!AIResource.MODEL_TIERS.includes(modelTier)) {
+      throw new AribotError(`Invalid model tier. Choose from: ${AIResource.MODEL_TIERS.join(', ')}`);
+    }
+
+    return this.client.request('POST', '/v2/ai/configure/', {
+      body: {
+        model_tier: modelTier,
+        max_tokens: options.maxTokens || 4000,
+        temperature: options.temperature || 0.7,
+        enable_caching: options.enableCaching !== false,
+      }
+    });
+  }
+
+  /**
+   * Run AI analysis on content.
+   */
+  async analyze(
+    content: string,
+    options: {
+      operation?: string;
+      context?: Record<string, any>;
+      sanitizePii?: boolean;
+    } = {}
+  ): Promise<any> {
+    const operation = options.operation || 'threat_analysis';
+    if (!AIResource.AI_OPERATIONS.includes(operation)) {
+      throw new AribotError(`Invalid operation. Choose from: ${AIResource.AI_OPERATIONS.join(', ')}`);
+    }
+
+    return this.client.request('POST', '/v2/ai/analyze/', {
+      body: {
+        content,
+        operation,
+        context: options.context || {},
+        sanitize_pii: options.sanitizePii !== false,
+      }
+    });
+  }
+
+  /**
+   * Get status of pending AI processing jobs.
+   */
+  async getQueueStatus(): Promise<any> {
+    return this.client.request('GET', '/v2/ai/queue/status/');
+  }
+
+  /**
+   * List AI processing jobs.
+   */
+  async listJobs(options: { status?: string; limit?: number } = {}): Promise<any[]> {
+    const data = await this.client.request<any>('GET', '/v2/ai/jobs/', {
+      params: {
+        status: options.status || 'all',
+        limit: options.limit || 20,
+      }
+    });
+    return data.results || [];
+  }
+
+  /**
+   * Get details of a specific AI job.
+   */
+  async getJob(jobId: string): Promise<any> {
+    return this.client.request('GET', `/v2/ai/jobs/${jobId}/`);
+  }
+
+  /**
+   * Cancel a pending AI job.
+   */
+  async cancelJob(jobId: string): Promise<any> {
+    return this.client.request('POST', `/v2/ai/jobs/${jobId}/cancel/`);
+  }
+
+  /**
+   * Get cost estimate for an AI operation before executing.
+   */
+  async getCostEstimate(
+    operation: string,
+    contentLength: number,
+    modelTier: string = 'standard'
+  ): Promise<any> {
+    return this.client.request('POST', '/v2/ai/estimate/', {
+      body: {
+        operation,
+        content_length: contentLength,
+        model_tier: modelTier,
+      }
+    });
+  }
+
+  /**
+   * Get AI usage audit log for compliance.
+   */
+  async getAuditLog(options: {
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+  } = {}): Promise<any[]> {
+    const params: Record<string, string | number> = { limit: options.limit || 100 };
+    if (options.startDate) params.start_date = options.startDate;
+    if (options.endDate) params.end_date = options.endDate;
+
+    const data = await this.client.request<any>('GET', '/v2/ai/audit/', { params });
+    return data.entries || [];
+  }
+}
+
+// =============================================================================
+// SECURITY UTILITIES
+// =============================================================================
+
+/**
+ * HMAC-SHA256 request signing for API request integrity.
+ */
+export class RequestSigner {
+  /**
+   * Generate HMAC-SHA256 signature for request.
+   */
+  static sign(
+    apiKey: string,
+    method: string,
+    path: string,
+    timestamp: string,
+    body?: string
+  ): string {
+    const parts = [method.toUpperCase(), path, timestamp];
+    if (body) {
+      const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
+      parts.push(bodyHash);
+    }
+
+    const canonical = parts.join('\n');
+    const signature = crypto
+      .createHmac('sha256', apiKey)
+      .update(canonical)
+      .digest('base64');
+
+    return signature;
+  }
+
+  /**
+   * Verify request signature and timestamp freshness.
+   */
+  static verify(
+    apiKey: string,
+    signature: string,
+    method: string,
+    path: string,
+    timestamp: string,
+    body?: string,
+    maxAgeSeconds: number = 300
+  ): boolean {
+    // Check timestamp freshness
+    try {
+      const ts = new Date(timestamp);
+      const age = Math.abs(Date.now() - ts.getTime()) / 1000;
+      if (age > maxAgeSeconds) return false;
+    } catch {
+      return false;
+    }
+
+    // Verify signature
+    const expected = RequestSigner.sign(apiKey, method, path, timestamp, body);
+    return crypto.timingSafeEqual(
+      Buffer.from(signature),
+      Buffer.from(expected)
+    );
+  }
+}
+
+/**
+ * Secure credential storage utilities.
+ */
+export class SecureCredentialManager {
+  private static SERVICE_NAME = 'aribot-api';
+
+  /**
+   * Store API key securely using environment variable.
+   * For production, use OS keyring via native modules.
+   */
+  static setApiKey(apiKey: string): void {
+    process.env.ARIBOT_API_KEY = apiKey;
+  }
+
+  /**
+   * Retrieve API key from environment.
+   */
+  static getApiKey(): string | undefined {
+    return process.env.ARIBOT_API_KEY;
+  }
+
+  /**
+   * Clear stored API key.
+   */
+  static clearApiKey(): void {
+    delete process.env.ARIBOT_API_KEY;
+  }
+
+  /**
+   * Validate API key format.
+   */
+  static isValidFormat(apiKey: string): boolean {
+    return /^ak_[a-zA-Z0-9]{32,}$/.test(apiKey);
+  }
+}
+
+// =============================================================================
+// CONVENIENCE FUNCTIONS
+// =============================================================================
+
+/**
+ * Quick function to analyze a diagram and get threats.
+ */
+export async function analyzeDiagram(
+  filePath: string,
+  options: { apiKey?: string; name?: string; waitForThreats?: boolean } = {}
+): Promise<{ diagram: Diagram; threats: Threat[] }> {
+  const client = new AribotClient({ apiKey: options.apiKey });
+  const diagram = await client.threatModeling.upload(filePath, {
+    name: options.name,
+    autoGenerateThreats: options.waitForThreats !== false
+  });
+
+  if (options.waitForThreats !== false) {
+    await new Promise(r => setTimeout(r, 2000));
+
+    for (let i = 0; i < 30; i++) {
+      const updated = await client.threatModeling.get(diagram.id);
+      if (updated.stage === 'completed') {
+        break;
+      }
+      await new Promise(r => setTimeout(r, 2000));
+    }
+
+    const threats = await client.threatModeling.getThreats(diagram.id);
+    return { diagram, threats };
+  }
+
+  return { diagram, threats: [] };
+}
+
+/**
+ * Quick compliance check against multiple standards.
+ */
+export async function runComplianceCheck(
+  diagramId: string,
+  standards: string[] = ['SOC2', 'ISO27001'],
+  apiKey?: string
+): Promise<any> {
+  const client = new AribotClient({ apiKey });
+  return client.compliance.runScan(diagramId, standards);
+}
+
+// Export default client
+export default AribotClient;