API Documentation

# API Documentation

## Configuration

### Schema

The configuration follows a strict schema validated by Zod:

```typescript
interface PromptEngineConfig {
  version: "2.0";
  engine?: {
    apiKeys?: Record<string, string>;
    defaults?: {
      temperature?: number;      // 0-2
      maxTokens?: number;        // >= 1
      topP?: number;             // 0-1
    };
    rateLimiting?: {
      maxRequestsPerMinute?: number;
      maxTokensPerMinute?: number;
    };
    logging?: {
      level?: "debug" | "info" | "warn" | "error";
      output?: "console" | "file" | "both";
    };
  };
  prompts: Array<{
    id: string;
    name?: string;
    model: "gpt-4" | "claude" | "gemini" | "custom";
    template: string;
    variables?: Record<string, any>;
    temperature?: number;
    maxTokens?: number;
    systemPrompt?: string;
    outputFormat?: "text" | "json" | "markdown";
    metadata?: {
      version?: string;
      author?: string;
      description?: string;
      tags?: string[];
    };
  }>;
  patterns?: Array<{
    name: string;
    description?: string;
    template: string;
    metadata?: {
      category?: string;
      tags?: string[];
      version?: string;
    };
  }>;
}
```

### Loading Configuration

```typescript
import { loadConfig } from 'prompt-engine/config';

// Load JSON config
const config = await loadConfig('prompt-engine.config.json');

// Load YAML config (requires js-yaml)
const yamlConfig = await loadConfig('config.yaml');

// Load TOML config (requires @iarna/toml)
const tomlConfig = await loadConfig('config.toml');
```

## Monitoring API

### Diagnostics Channel Events

```typescript
import { monitor } from 'prompt-engine/monitoring';

// Listen to prompt start events
monitor.on('prompt.start', (data) => {
  console.log(`Starting prompt ${data.id}`);
});

// Listen to completion events
monitor.on('prompt.complete', (metrics) => {
  console.log(`Prompt completed:`, metrics);
});

// Listen to error events
monitor.on('prompt.error', (data) => {
  console.error(`Error: ${data.error.message}`);
});
```

### Tracking Execution

```typescript
import { trackPromptExecution } from 'prompt-engine/monitoring';

const result = await trackPromptExecution(
  'openai',              // provider
  'gpt-4',              // model
  'unique-prompt-id',   // prompt ID
  async () => {
    // Your execution logic
    const response = await callAPI();
    return {
      result: response.text,
      metrics: {
        promptTokens: response.promptTokens,
        completionTokens: response.completionTokens,
        totalTokens: response.totalTokens,
      }
    };
  }
);
```

### Metrics Collection

```typescript
import { metricsCollector } from 'prompt-engine/monitoring';

// Get summary
const summary = metricsCollector.getSummary();
console.log(`Total requests: ${summary.totalRequests}`);
console.log(`Total cost: $${summary.totalCost}`);

// Get metrics for last hour
const hourAgo = new Date(Date.now() - 3600000);
const recentMetrics = metricsCollector.getMetrics(100, hourAgo);

// Export all metrics
const exported = metricsCollector.exportMetrics();
```

### Cost Tracking

```typescript
import { costTracker } from 'prompt-engine/monitoring';

// Calculate cost
const cost = costTracker.calculateCost(
  'openai',
  'gpt-4',
  1000,  // prompt tokens
  500    // completion tokens
);
console.log(`Cost: $${cost.totalCost}`);

// Set custom pricing
costTracker.setCustomPricing('my-provider', {
  'my-model': {
    input: 2.00,   // $2 per 1M input tokens
    output: 6.00   // $6 per 1M output tokens
  }
});

// Estimate cost
const estimate = costTracker.estimateCost(
  'openai',
  'gpt-4',
  'This is my prompt text',
  1000  // estimated output tokens
);
```

## Security API

### Prompt Sanitization

```typescript
import { sanitizePrompt, sanitizeHtml } from 'prompt-engine/security';

// Full sanitization (XSS, injection, PII)
const safe = await sanitizePrompt(userInput);

// HTML sanitization only
const safeHtml = await sanitizeHtml(htmlContent);
```

### Detection Functions

```typescript
import { detectInjection, detectPII } from 'prompt-engine/security';

// Check for injection attempts
if (detectInjection(userInput)) {
  throw new Error('Potential injection detected');
}

// Check for PII
if (detectPII(userInput)) {
  console.warn('PII detected in input');
}
```

### PII Masking

```typescript
import { maskPII } from 'prompt-engine/security';

const masked = maskPII('My SSN is 123-45-6789');
// Output: 'My SSN is XXX-XX-XXXX'
```

## CLI API

### Commands

```bash
# Validate configuration
prompt-engine validate <config-file>

# Initialize new configuration
prompt-engine init <output-file>

# Show version
prompt-engine --version

# Show help
prompt-engine --help
```

### Programmatic CLI Usage

```typescript
import { cli } from 'prompt-engine/cli';

// Run CLI programmatically
await cli(['validate', 'config.json']);
```

## Template Patterns

### Using Built-in Patterns

```typescript
import { GPT4SystemPrompt, GPT4CodeGeneration } from 'prompt-engine/templates/gpt4';
import { ClaudeSystemPrompt } from 'prompt-engine/templates/claude';
import { GeminiConfig } from 'prompt-engine/templates/gemini';

// Use a pattern
const prompt = GPT4CodeGeneration.template.replace('{{language}}', 'TypeScript');
```

### Pattern Types

```typescript
interface BasePattern {
  name: string;
  description: string;
  template: string;
  metadata?: {
    category?: string;
    tags?: string[];
    version?: string;
  };
}
```

## Error Types

```typescript
import { ConfigError, ValidationError, ParsingError } from 'prompt-engine/types';

try {
  await loadConfig('config.json');
} catch (error) {
  if (error instanceof ConfigError) {
    console.error('Configuration error:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.errors);
  }
}
```

## TypeScript Support

All APIs are fully typed. Import types as needed:

```typescript
import type {
  PromptConfig,
  ExtendedPromptConfig,
  PromptMetrics,
  CostCalculation,
  TokenPricing
} from 'prompt-engine';
```