export type Key = string; export type Capabilities = { capture: boolean; render: boolean; aec: boolean; recognition: boolean; preview: boolean; hotwords: boolean; synthesis: boolean; sounds: boolean; test_io: boolean; }; export type Profile = { id: Key; label: string; description: string; installed: boolean; capabilities: Capabilities; }; export type Asset = { id: Key; kind: "model" | "runtime" | "sound"; destination: string; source: string; sha256: string; download_bytes: number; installed_bytes: number; cached: boolean; license: { name: string; url: string; acceptance_required: boolean }; }; export type Plan = { id: Key; profile: Key; ready: boolean; writes_required: boolean; download_bytes: number; installed_bytes: number; items: Asset[]; blockers: string[]; expires_in_ms: number; }; export type Sound = { id: Key; label: string; installed: boolean; sha256: string; }; export type Limits = { line_bytes: number; pending_requests: number; active_operations: number; resources: number; text_chars: number; queued_text_chars: number; unacked_segments: number; hotwords: number; hotword_chars: number; waveform_bins: number; output_queue_bytes: number; instance_requests: number; instance_operations: number; }; export type ServiceInfo = { instance: Key; io_mode: "device" | "fixture" | "fake"; profiles: Profile[]; devices: Array<{ id: Key; label: string; direction: "capture" | "render"; available: boolean; }>; sounds: Sound[]; capabilities: Capabilities; limits: Limits; }; export type ErrorData = { kind: | "invalid" | "unsupported" | "busy" | "missing_assets" | "consent" | "stale" | "not_found" | "device" | "integrity" | "io" | "timeout" | "cancelled" | "internal"; retryable: boolean; field: string | null; resource: Key | null; operation: Key | null; detail: string; }; export type OperationOutcome = { outcome: "completed" | "cancelled" | "failed"; reason: string; stop_frame: number | null; error: ErrorData | null; }; export type SpeakEvent = { method: | "operation.progress" | "operation.ended" | "resource.ready" | "resource.health" | "resource.closed" | "recognition.activity" | "recognition.pending" | "recognition.preview" | "recognition.preview_cleared" | "recognition.final" | "recognition.empty" | "synthesis.phrase" | "playback.progress" | "playback.boundary" | "audio.level" | "service.warning"; params: { instance: Key; seq: number; resource: Key | null; epoch: number | null; operation: Key | null; data: Record; }; }; const eventNames = new Set([ "operation.progress", "operation.ended", "resource.ready", "resource.health", "resource.closed", "recognition.activity", "recognition.pending", "recognition.preview", "recognition.preview_cleared", "recognition.final", "recognition.empty", "synthesis.phrase", "playback.progress", "playback.boundary", "audio.level", "service.warning", ]); type JsonRecord = Record & { kind?: unknown; retryable?: unknown; field?: unknown; resource?: unknown; operation?: unknown; detail?: unknown; done_bytes?: unknown; total_bytes?: unknown; outcome?: unknown; reason?: unknown; stop_frame?: unknown; error?: unknown; capture?: unknown; render?: unknown; speech?: unknown; capture_rate?: unknown; render_rate?: unknown; status?: unknown; capture_frame?: unknown; render_frame?: unknown; active?: unknown; segment?: unknown; pending?: unknown; revision?: unknown; text?: unknown; start_frame?: unknown; end_frame?: unknown; index?: unknown; input?: unknown; output?: unknown; waveform?: unknown; playing?: unknown; busy?: unknown; phase?: unknown; through_revision?: unknown; through_frame?: unknown; consumed_frames?: unknown; played_text?: unknown; message?: unknown; instance?: unknown; seq?: unknown; epoch?: unknown; data?: unknown; }; export function isRecord(value: unknown): value is JsonRecord { return typeof value === "object" && value !== null && !Array.isArray(value); } function key(value: unknown): value is Key { return typeof value === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(value); } function text(value: unknown, limit = 8_000): value is string { return typeof value === "string" && [...value].length <= limit; } function integer(value: unknown): value is number { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0; } function nullableKey(value: unknown): boolean { return value === null || key(value); } function requireFields( value: Record, fields: readonly string[], ): boolean { return fields.every((field) => field in value); } function validError(value: unknown): boolean { return ( isRecord(value) && requireFields(value, [ "kind", "retryable", "field", "resource", "operation", "detail", ]) && [ "invalid", "unsupported", "busy", "missing_assets", "consent", "stale", "not_found", "device", "integrity", "io", "timeout", "cancelled", "internal", ].includes(value.kind as string) && typeof value.retryable === "boolean" && (value.field === null || text(value.field, 256)) && nullableKey(value.resource) && nullableKey(value.operation) && text(value.detail, 512) ); } function validData(method: string, value: unknown): boolean { if (!isRecord(value)) return false; const numbers = (...names: string[]) => names.every((name) => integer(value[name])); switch (method) { case "operation.progress": return ( ["validating", "downloading", "installing", "loading"].includes( value.phase as string, ) && numbers("done_bytes", "total_bytes") && (value.done_bytes as number) <= (value.total_bytes as number) ); case "operation.ended": return ( (value.outcome === "completed" || value.outcome === "cancelled" || value.outcome === "failed") && text(value.reason, 64) && (value.stop_frame === null || integer(value.stop_frame)) && (value.outcome === "failed") === (value.error !== null) && (value.error === null || validError(value.error)) ); case "resource.ready": return ( typeof value.capture === "boolean" && typeof value.render === "boolean" && typeof value.speech === "boolean" && (value.capture_rate === null || (integer(value.capture_rate) && value.capture_rate >= 1 && value.capture_rate <= 384_000)) && (value.render_rate === null || (integer(value.render_rate) && value.render_rate >= 1 && value.render_rate <= 384_000)) ); case "resource.health": return ( value.status === "unavailable" && numbers("capture_frame", "render_frame") && validError(value.error) ); case "resource.closed": return numbers("capture_frame", "render_frame"); case "recognition.activity": return typeof value.active === "boolean" && nullableKey(value.segment); case "recognition.pending": return typeof value.pending === "boolean"; case "recognition.preview": return ( key(value.segment) && numbers("revision") && (value.revision as number) >= 1 && text(value.text) ); case "recognition.preview_cleared": return key(value.segment) && numbers("through_revision"); case "recognition.final": return ( key(value.segment) && text(value.text) && numbers("start_frame", "end_frame") && (value.start_frame as number) <= (value.end_frame as number) ); case "recognition.empty": return ( key(value.segment) && numbers("start_frame", "end_frame") && (value.start_frame as number) <= (value.end_frame as number) ); case "synthesis.phrase": return numbers("index") && text(value.text) && /\S/u.test(value.text); case "playback.progress": return ( numbers("through_frame", "consumed_frames") && text(value.played_text) ); case "playback.boundary": return numbers("through_frame"); case "audio.level": return ( typeof value.input === "number" && Number.isFinite(value.input) && value.input >= 0 && typeof value.output === "number" && Number.isFinite(value.output) && value.output >= 0 && Array.isArray(value.waveform) && value.waveform.length <= 32 && value.waveform.every( (item) => typeof item === "number" && Number.isFinite(item) && item >= 0, ) && typeof value.playing === "boolean" && typeof value.busy === "boolean" ); case "service.warning": return ( [ "invalid", "unsupported", "busy", "missing_assets", "consent", "stale", "not_found", "device", "integrity", "io", "timeout", "cancelled", "internal", ].includes(value.kind as string) && text(value.message, 512) ); default: return false; } } /** Validates known event shapes; unknown events retain the common sequence fence. */ export function parseEvent( method: unknown, params: unknown, ): SpeakEvent | undefined { if (typeof method !== "string" || !isRecord(params)) throw new Error("invalid notification"); if ( !requireFields(params, [ "instance", "seq", "resource", "epoch", "operation", "data", ]) || !key(params.instance) || !integer(params.seq) || params.seq < 1 || !nullableKey(params.resource) || (params.epoch !== null && (!integer(params.epoch) || params.epoch < 1)) || !nullableKey(params.operation) || !isRecord(params.data) ) throw new Error("invalid event fence"); if (!eventNames.has(method)) return undefined; if (!validData(method, params.data)) throw new Error(`invalid ${method} event`); return { method: method as SpeakEvent["method"], params: params as SpeakEvent["params"], }; }