# API IPC Reference

## Context Bridge

Tutte le API sono esposte tramite `window.electronAPI`:

```typescript
// TypeScript declaration
interface ElectronAPI {
  // Telnet
  telnetConnect: (host: string, port: number) => Promise<boolean>;
  telnetDisconnect: () => Promise<void>;
  telnetSend: (data: string) => Promise<boolean>;
  telnetGetOutput: () => Promise<string>;
  onTelnetOutput: (callback: (data: string) => void) => void;

  // Ollama
  ollamaChat: (messages: OllamaMessage[], options?: OllamaOptions) => Promise<OllamaResponse>;
  ollamaGetModels: () => Promise<string[]>;
  ollamaIsAvailable: () => Promise<boolean>;

  // Autoplayer
  autoplayerConfigure: (config: AutoplayerConfig) => Promise<void>;
  autoplayerStart: () => Promise<void>;
  autoplayerStop: () => Promise<void>;
  autoplayerIsActive: () => Promise<boolean>;
  autoplayerExecuteAction: (action: string) => Promise<void>;
  onAutoplayerDecision: (callback: (decision: string) => void) => void;
  onAutoplayerAction: (callback: (action: string) => void) => void;
  onAutoplayerState: (callback: (state: GameState) => void) => void;
}
```

---

## Telnet API

### telnetConnect

Stabilisce connessione Telnet al server MUD.

```typescript
const connected = await window.electronAPI.telnetConnect('172.24.19.225', 6666);
```

**Params:**
| Param | Type | Description |
|-------|------|-------------|
| host | string | Indirizzo server MUD |
| port | number | Porta Telnet |

**Returns:** `Promise<boolean>` - true se connessione riuscita

**Errors:** Connection timeout, host unreachable

### telnetDisconnect

Chiude connessione Telnet.

```typescript
await window.electronAPI.telnetDisconnect();
```

### telnetSend

Invia comando al server MUD.

```typescript
const sent = await window.electronAPI.telnetSend('look\n');
```

**Params:**
| Param | Type | Description |
|-------|------|-------------|
| data | string | Comando da inviare (newline esclusa) |

**Returns:** `Promise<boolean>` - true se invio riuscito

### telnetGetOutput

Restituisce buffer output Telnet accumulato.

```typescript
const output = await window.electronAPI.telnetGetOutput();
```

**Returns:** `Promise<string>` - Output completo con HTML colors

### onTelnetOutput

Subscribe a nuovi output dal server.

```typescript
window.electronAPI.onTelnetOutput((data) => {
  console.log('Nuovo output:', data);
});
```

**Callback Params:**
| Param | Type | Description |
|-------|------|-------------|
| data | string | Chunk output HTML |

---

## Ollama API

### ollamaChat

Invia messaggi a Ollama e riceve risposta.

```typescript
const response = await window.electronAPI.ollamaChat([
  { role: 'system', content: 'You are a MUD player' },
  { role: 'user', content: 'What should I do?' }
], {
  model: 'llama3.2',
  temperature: 0.7
});
```

**Params:**
| Param | Type | Description |
|-------|------|-------------|
| messages | OllamaMessage[] | Storico conversazione |
| options | OllamaOptions | Opzioni (opzionali) |

**OllamaMessage:**
```typescript
{
  role: 'user' | 'assistant' | 'system';
  content: string;
}
```

**OllamaOptions:**
```typescript
{
  model?: string;        // Default: 'llama3.2'
  temperature?: number;  // Default: 0.7
}
```

**Returns:** `Promise<OllamaResponse>`
```typescript
{
  model: string;
  response: string;
  done: boolean;
}
```

### ollamaGetModels

Lista modelli disponibili sul server.

```typescript
const models = await window.electronAPI.ollamaGetModels();
// ['llama3.2', 'llama3.1', 'mistral', ...]
```

**Returns:** `Promise<string[]>` - Nomi modelli

### ollamaIsAvailable

Verifica se server Ollama raggiungibile.

```typescript
const available = await window.electronAPI.ollamaIsAvailable();
// true se server risponde
```

**Returns:** `Promise<boolean>`

---

## Autoplayer API

### autoplayerConfigure

Configura comportamento autoplayer.

```typescript
await window.electronAPI.autoplayerConfigure({
  model: 'llama3.2',
  systemPrompt: 'You are an explorer...',
  temperature: 0.7,
  autoSend: true
});
```

**AutoplayerConfig:**
```typescript
{
  model: string;           // Model LLM
  systemPrompt: string;    // Personalità bot
  temperature?: number;    // Creatività (0.0-1.0)
  autoSend?: boolean;      // Auto-esegui azioni
}
```

### autoplayerStart

Avvia loop autoplayer.

```typescript
await window.electronAPI.autoplayerStart();
```

### autoplayerStop

Ferma loop autoplayer.

```typescript
await window.electronAPI.autoplayerStop();
```

### autoplayerIsActive

Verifica se autoplayer in esecuzione.

```typescript
const active = await window.electronAPI.autoplayerIsActive();
```

**Returns:** `Promise<boolean>`

### autoplayerExecuteAction

Esegui azione manualmente (senza passare per decision engine).

```typescript
await window.electronAPI.autoplayerExecuteAction('go north');
```

### onAutoplayerDecision

Subscribe a decisioni LLM.

```typescript
window.electronAPI.onAutoplayerDecision((decision) => {
  console.log('LLM decision:', decision);
});
```

**Callback Params:**
| Param | Type | Description |
|-------|------|-------------|
| decision | string | Risposta completa LLM |

### onAutoplayerAction

Subscribe ad azioni generate.

```typescript
window.electronAPI.onAutoplayerAction((action) => {
  console.log('Action to execute:', action);
});
```

**Callback Params:**
| Param | Type | Description |
|-------|------|-------------|
| action | string | Comando da eseguire |

### onAutoplayerState

Subscribe a updates stato gioco parsato.

```typescript
window.electronAPI.onAutoplayerState((state) => {
  console.log('Current location:', state.location);
  console.log('Exits:', state.exits);
});
```

**GameState:**
```typescript
{
  location: string;      // Nome location corrente
  description: string;   // Descrizione stanza
  exits: string[];       // Uscite disponibili
  players: string[];     // Giocatori presenti
  objects: string[];     // Oggetti nella stanza
  health?: string;       // HP corrente
  mana?: string;         // Mana corrente
  prompt?: string;       // Prompt del gioco
}
```

---

## Esempi Completi

### Connessione e Game Loop

```typescript
// 1. Connetti
const connected = await window.electronAPI.telnetConnect('172.24.19.225', 6666);
if (!connected) {
  console.error('Connessione fallita');
  return;
}

// 2. Subscribe output
window.electronAPI.onTelnetOutput((data) => {
  // Aggiorna UI
  setOutput(prev => prev + data);
});

// 3. Invia comando
await window.electronAPI.telnetSend('look\n');
```

### Autoplayer Workflow

```typescript
// 1. Configura
await window.electronAPI.autoplayerConfigure({
  model: 'llama3.2',
  systemPrompt: 'You are a helpful MUD player. Explore and interact naturally.',
  temperature: 0.7,
  autoSend: false  // Review manuale azioni
});

// 2. Subscribe decisioni
window.electronAPI.onAutoplayerAction((action) => {
  console.log('Pending action:', action);
  // Possibile review manuale qui
});

// 3. Avvia
await window.electronAPI.autoplayerStart();

// 4. Per fermare
await window.electronAPI.autoplayerStop();
```

### Ollama Chat Diretta

```typescript
// Test chat con Ollama
const response = await window.electronAPI.ollamaChat([
  { role: 'system', content: 'You are a fantasy game master.' },
  { role: 'user', content: 'Describe a dark forest.' }
], { temperature: 0.8 });

console.log(response.response);
```

---

## Error Handling

```typescript
try {
  await window.electronAPI.telnetConnect(host, port);
} catch (error) {
  console.error('Connection error:', error);
}

// Event-based errors
window.electronAPI.onTelnetOutput((data) => {
  // Gestisci errori in output
});
```

## Note

- Tutte le chiamate IPC sono asincrone (Promise-based)
- Gli eventi devono essere sottoscritti una volta (non in useEffect ripetuti)
- Cleanup event listeners quando il componente unmount
- Utilizzare `window.electronAPI` solo dopo il mount del componente