import type { ClientEvent, ServerEvent } from '../../core/protocol.js';

/**
 * Fully-resolved, server-trusted session config. Never expose this shape to
 * the browser directly — `instructions` and `tools` in particular are
 * server-owned policy, not client input (see `resolveSessionConfig` in
 * `./session`).
 */
export interface ResolvedSessionConfig {
	model: string;
	instructions: string;
	voice?: string;
}

/**
 * A single live conversation with a backend model/pipeline. Speaks only the
 * normalized `ClientEvent`/`ServerEvent` vocabulary from `$lib/core/protocol`
 * — never a provider's own wire format. That constraint is what lets
 * `RealtimeSession` (./session.ts) stay identical across providers.
 */
export interface ProviderSession {
	send(event: ClientEvent): void;
	/** Only one handler is supported; a session has exactly one consumer. */
	onEvent(handler: (event: ServerEvent) => void): void;
	close(reason?: string): void;
}

/**
 * A backend capable of running realtime sessions — today, a single upstream
 * WebSocket to OpenAI Realtime. A future pipeline (STT -> LLM -> TTS) or a
 * different model provider implements this same interface; nothing else in
 * `$lib/server/core` needs to change.
 */
export interface RealtimeProvider {
	createSession(config: ResolvedSessionConfig): Promise<ProviderSession>;
}