EU-Utility-V3/docs/API_DOCUMENTATION.md

# EU-Utility V3 - API Documentation

Complete API reference for plugin development.

---

## Table of Contents

1. [Overview](#overview)
2. [PluginAPI](#pluginapi)
3. [WidgetAPI](#widgetapi)
4. [ExternalAPI](#externalapi)
5. [TypeScript Types](#typescript-types)

---

## Overview

EU-Utility V3 provides a unified API for plugin development. Plugins run in a secure sandbox with controlled access to system resources.

### API Structure

```typescript
// Access the API
const api = window.EUPluginAPI;

// All methods return Promises
const result = await api.someMethod();
```

---

## PluginAPI

### Log Reader

```typescript
// Read last N log lines
const lines = await api.readLogLines(100);

// Read since timestamp
const recent = await api.readLogSince(Date.now() - 300000);

// Read filtered
const loot = await api.readLogFiltered('Loot:');
```

**Returns:** `Promise<string[]>`

---

### Window Manager

```typescript
// Get game window info
const window = await api.getGameWindow();

// Check focus
const focused = await api.isGameFocused();

// Bring to front
await api.bringGameToFront();

// Capture screenshot
const screenshot = await api.captureGameWindow();
```

**WindowInfo:**
```typescript
interface WindowInfo {
  x: number;
  y: number;
  width: number;
  height: number;
  isFocused: boolean;
}
```

---

### OCR Service

```typescript
// Check availability
const available = await api.ocrAvailable();

// Recognize text
const text = await api.recognizeText({
  x: 100,
  y: 100,
  width: 200,
  height: 50
});
```

**Returns:** `Promise<string>`

---

### Item Database API

```typescript
// Search items
const results = await api.searchItems({
  query: 'weapon',
  category: 'equipment',
  limit: 10
});

// Get item details
const details = await api.getItemDetails('12345');
```

**SearchResult:**
```typescript
interface Item {
  id: string;
  name: string;
  type: string;
  category: string;
  value?: number;
  markup?: number;
}
```

---

### HTTP Client

```typescript
// GET request
const data = await api.httpGet('https://api.example.com/data', {
  cache: true,
  ttl: 3600
});

// POST request
const result = await api.httpPost('https://api.example.com/save', {
  key: 'value'
});
```

---

### Notifications

```typescript
await api.showNotification({
  title: 'Alert',
  body: 'Something happened',
  duration: 3000
});
```

---

### Clipboard

```typescript
// Copy
await api.copyToClipboard('text');

// Paste
const text = await api.pasteFromClipboard();
```

---

### Event Bus

```typescript
// Subscribe
const subId = await api.subscribeEvent('loot.received', (event) => {
  console.log(event.data);
});

// Unsubscribe
await api.unsubscribeEvent(subId);

// Publish
await api.publishEvent('my.event', { data: 'value' });
```

---

### Data Storage

```typescript
// Save
await api.savePluginData('myPlugin', 'key', { data: 'value' });

// Load
const data = await api.loadPluginData('myPlugin', 'key');

// Delete
await api.deletePluginData('myPlugin', 'key');
```

---

## WidgetAPI

### Creating Widgets

```typescript
// Create overlay widget
const widget = await api.createWidget({
  id: 'my-widget',
  title: 'My Widget',
  width: 300,
  height: 200,
  x: 100,
  y: 100
});

// Update content
await api.updateWidget('my-widget', {
  title: 'Updated',
  content: htmlContent
});

// Close widget
await api.closeWidget('my-widget');
```

---

## ExternalAPI

### REST Endpoints

The application exposes a local REST API for external integrations.

```
GET  /api/plugins           - List all plugins
POST /api/plugins/{id}/activate
POST /api/plugins/{id}/deactivate
GET  /api/loot/recent       - Recent loot events
POST /api/ocr/recognize     - OCR text recognition
```

---

## TypeScript Types

```typescript
// Full type definitions for plugin development

interface PluginContext {
  api: PluginAPI;
  widget: WidgetAPI;
  logger: Logger;
  settings: SettingsManager;
}

interface PluginAPI {
  // Log Reader
  readLogLines(count: number): Promise<string[]>;
  readLogSince(timestamp: number): Promise<string[]>;
  readLogFiltered(pattern: string): Promise<string[]>;
  
  // Window
  getGameWindow(): Promise<WindowInfo | null>;
  isGameFocused(): Promise<boolean>;
  bringGameToFront(): Promise<void>;
  captureGameWindow(): Promise<string>; // base64
  
  // OCR
  ocrAvailable(): Promise<boolean>;
  recognizeText(region: Region): Promise<string>;
  
  // Item Database
  searchItems(params: SearchParams): Promise<Item[]>;
  getItemDetails(itemId: string): Promise<any>;
  
  // HTTP
  httpGet(url: string, options?: HttpOptions): Promise<any>;
  httpPost(url: string, body: any, options?: HttpOptions): Promise<any>;
  
  // Notifications
  showNotification(options: NotificationOptions): Promise<void>;
  
  // Clipboard
  copyToClipboard(text: string): Promise<void>;
  pasteFromClipboard(): Promise<string>;
  
  // Events
  subscribeEvent(type: string, handler: EventHandler): Promise<string>;
  unsubscribeEvent(id: string): Promise<void>;
  publishEvent(type: string, data: any): Promise<void>;
  
  // Storage
  savePluginData(pluginId: string, key: string, data: any): Promise<void>;
  loadPluginData(pluginId: string, key: string): Promise<any>;
  deletePluginData(pluginId: string, key: string): Promise<void>;
}
```

---

*API Documentation - EU-Utility V3*