Skip to content

Latest commit

 

History

History
552 lines (433 loc) · 9.04 KB

API_DOCUMENTATION.md

File metadata and controls

552 lines (433 loc) · 9.04 KB

API Documentation - Self-Building Desktop Application

Table of Contents

  1. Overview
  2. Core Modules
  3. Utility Modules
  4. Security Modules
  5. Feature Modules
  6. IPC Communication
  7. Error Codes
  8. Examples

Overview

The Self-Building Desktop Application provides a comprehensive API for AI-powered code generation, project management, and development automation. This documentation covers all public APIs, their usage, and best practices.

Base Configuration

{
  apiKey: 'your-anthropic-api-key',
  apiEndpoint: 'https://api.anthropic.com',
  dataPath: './data',
  logsPath: './logs',
  maxRetries: 3,
  timeout: 30000
}

Core Modules

set-api-key

Sets the Anthropic API key for code generation.

Parameters:

  • apiKey (string, required): The Anthropic API key

Returns:

{
  success: boolean,
  error?: string
}

Example:

await window.electronAPI.setApiKey('sk-ant-...');

generate-code

Generates code from a natural language prompt.

Parameters:

  • prompt (string, required): Natural language description (max 10,000 chars)

Returns:

{
  success: boolean,
  data?: {
    packages: string[],
    code: string,
    description: string
  },
  metadata?: {
    processingTime: number,
    retryCount: number,
    enhanced: boolean,
    fromCache?: boolean
  },
  error?: string
}

Example:

const result = await window.electronAPI.generateCode('Create a todo list app');

execute-code

Executes generated code in a sandboxed Node.js environment.

Parameters:

  • code (string, required): JavaScript code to execute
  • packages (string[], optional): NPM packages to install
  • sessionId (string, required): Session identifier

Returns:

{
  success: boolean,
  output?: string,
  errors?: string,
  exitCode?: number
}

Example:

await window.electronAPI.executeCode({
  code: 'console.log("Hello World")',
  packages: ['lodash'],
  sessionId: 'session_123_abc'
});

execute-dom-code

Executes DOM-based code in the renderer process.

Parameters:

  • code (string, required): DOM manipulation code
  • sessionId (string, required): Session identifier

Returns:

{
  success: boolean,
  output?: string,
  logs?: Array<{type: string, message: string, timestamp: number}>
}

Session Management

create-session

Creates a new session for tracking code generation and execution.

Parameters:

  • sessionId (string, required): Unique session identifier
  • prompt (string, optional): Initial prompt for the session

Returns:

{
  success: boolean,
  session?: {
    id: string,
    created: string,
    status: string,
    metadata: object
  }
}

get-session

Retrieves session information.

Parameters:

  • sessionId (string, required): Session identifier

Returns:

{
  success: boolean,
  session?: SessionObject
}

get-session-history

Gets recent session history.

Parameters:

  • limit (number, optional): Maximum number of sessions (1-100, default: 20)

Returns:

{
  success: boolean,
  history?: Array<SessionSummary>
}

get-session-stats

Gets aggregated session statistics.

Parameters: None

Returns:

{
  success: boolean,
  stats?: {
    totalSessions: number,
    totalExecutions: number,
    successfulExecutions: number,
    averageCodeLength: number,
    statusDistribution: object,
    recentActivity: number
  }
}

cleanup-session

Cleans up a session and its temporary files.

Parameters:

  • sessionId (string, required): Session identifier

Returns:

{
  success: boolean,
  error?: string
}

export-sessions

Exports all sessions for backup.

Parameters: None

Returns:

{
  success: boolean,
  data?: {
    exported: string,
    version: string,
    sessions: Array<SessionObject>
  }
}

Configuration

get-config

Retrieves current application configuration.

Parameters: None

Returns:

{
  success: boolean,
  config?: ConfigObject
}

update-config

Updates application configuration.

Parameters:

  • config (object, required): Configuration updates

Returns:

{
  success: boolean,
  config?: ConfigObject,
  error?: string
}

Example:

await window.electronAPI.updateConfig({
  execution: {
    maxConcurrentExecutions: 5,
    executionTimeout: 60000
  }
});

Security

scan-code-security

Scans code for security issues before execution.

Parameters:

  • code (string, required): Code to scan

Returns:

{
  success: boolean,
  scan?: {
    safe: boolean,
    issues: Array<{
      type: string,
      severity: string,
      description: string
    }>,
    riskLevel: string
  }
}

select-api-key-file

Opens file dialog to select API key file.

Parameters: None

Returns:

{
  success: boolean,
  apiKey?: string,
  error?: string
}

Monitoring

get-system-health

Gets current system health metrics.

Parameters: None

Returns:

{
  success: boolean,
  health?: {
    cpu: { usage: number, status: string },
    memory: { total: number, used: number, free: number, usage: number, status: string },
    disk: { total: number, used: number, free: number, usage: number, status: string }
  },
  stats?: ExecutionStats
}

get-active-sessions

Gets list of currently active sessions.

Parameters: None

Returns:

{
  success: boolean,
  sessions?: Array<{
    id: string,
    startTime: number,
    packages: string[],
    codeLength: number,
    duration: number
  }>
}

check-for-updates

Checks for application updates.

Parameters: None

Returns:

{
  success: boolean,
  result?: UpdateInfo,
  error?: string
}

Cache Management

get-cache-stats

Gets cache performance statistics.

Parameters: None

Returns:

{
  success: boolean,
  stats?: {
    size: number,
    maxSize: number,
    hitRate: string,
    hits: number,
    misses: number,
    evictions: number,
    totalRequests: number,
    config: object
  }
}

clear-cache

Clears the code generation cache.

Parameters: None

Returns:

{
  success: boolean,
  error?: string
}

update-cache-config

Updates cache configuration.

Parameters:

  • config (object, required): Cache configuration

Returns:

{
  success: boolean,
  config?: CacheConfig,
  error?: string
}

User Feedback

submit-feedback

Submits user feedback for a session.

Parameters:

  • feedback (object, required):
    • sessionId (string, required): Session identifier
    • rating (string, required): 'good' or 'bad'
    • prompt (string, optional): Original prompt
    • timestamp (number, optional): Timestamp

Returns:

{
  success: boolean,
  error?: string
}

Error Handling

All IPC endpoints follow a consistent error handling pattern:

  1. Success Response:
{
  success: true,
  // ... endpoint-specific data
}
  1. Error Response:
{
  success: false,
  error: "Error message",
  details?: ["Validation error 1", "Validation error 2"]
}

Rate Limiting

Some endpoints have rate limiting to prevent abuse:

  • generate-code: 10 requests per minute
  • execute-code: 20 requests per minute
  • scan-code-security: 30 requests per minute

When rate limit is exceeded:

{
  success: false,
  error: "Rate limit exceeded. Please try again later."
}

Security Considerations

  1. Input Validation: All inputs are validated and sanitized
  2. Session IDs: Must match pattern session_\d+_[a-z0-9]+
  3. Code Length: Maximum 100,000 characters
  4. Prompt Length: Maximum 10,000 characters
  5. Package Filtering: Dangerous packages are blocked

Usage Example

// Complete workflow example
async function generateAndExecute() {
  // Set API key
  await window.electronAPI.setApiKey('your-api-key');
  
  // Create session
  const sessionId = window.electronAPI.generateSessionId();
  await window.electronAPI.createSession(sessionId, 'Create a calculator');
  
  // Generate code
  const generated = await window.electronAPI.generateCode('Create a calculator');
  
  if (generated.success) {
    // Scan for security issues
    const scan = await window.electronAPI.scanCodeSecurity(generated.data.code);
    
    if (scan.scan.safe) {
      // Execute code
      const result = await window.electronAPI.executeCode({
        code: generated.data.code,
        packages: generated.data.packages,
        sessionId: sessionId
      });
      
      console.log('Execution result:', result);
    }
  }
  
  // Cleanup
  await window.electronAPI.cleanupSession(sessionId);
}