@onmars/lunar-voice 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onMars Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @onmars/lunar-voice
+
+Voice synthesis adapter (ElevenLabs TTS) for [Lunar](https://github.com/onmars-tech/lunar).
+
+This package is used internally by `@onmars/lunar-cli`. Install the CLI instead:
+
+```bash
+bun install -g @onmars/lunar-cli
+```
+
+## License
+
+MIT — [onMars Tech](https://github.com/onmars-tech)

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@onmars/lunar-voice",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": ["src/", "LICENSE"],
+  "dependencies": {
+    "@onmars/lunar-core": "0.1.0"
+  },
+  "description": "Voice synthesis adapter for Lunar (ElevenLabs TTS)",
+  "author": "onMars Tech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onmars-tech/lunar",
+    "directory": "packages/voice"
+  },
+  "homepage": "https://github.com/onmars-tech/lunar",
+  "bugs": "https://github.com/onmars-tech/lunar/issues",
+  "keywords": ["lunar", "ai", "voice", "tts", "elevenlabs", "bun"],
+  "publishConfig": {
+  "access": "public"
+},
+"engines": {
+"bun": ">=1.2"
+}
+}

package/src/__tests__/elevenlabs.test.ts

@@ -0,0 +1,281 @@
+/**
+ * # ElevenLabs TTS Provider — Functional Specification
+ *
+ * ## Constructor
+ * Stores config: apiKey, voiceId, modelId, language, stability, similarityBoost, speed.
+ * Base URL: https://api.elevenlabs.io/v1
+ *
+ * ## init() / destroy()
+ * init() logs initialization (no-op beyond that).
+ * destroy() is a no-op.
+ *
+ * ## synthesize(text, options?)
+ * POST to /text-to-speech/{voiceId} with:
+ * - Headers: xi-api-key, Content-Type: application/json
+ * - Body: text, model_id (default 'eleven_multilingual_v2'),
+ *   language_code, voice_settings (stability, similarity_boost, speed)
+ * - Options override config: voice (voiceId), speed, language
+ * Returns: { audio: Buffer, format: 'mp3' }
+ * Throws on non-OK response.
+ *
+ * ## health()
+ * GET /user with xi-api-key header. Returns { ok: boolean, error? }.
+ * Catches fetch errors gracefully.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { type ElevenLabsConfig, ElevenLabsTTS } from '../elevenlabs'
+
+// ─── Mock fetch ──────────────────────────────────────────────────
+
+const originalFetch = globalThis.fetch
+
+function mockFetch(handler: (url: string, init?: RequestInit) => Response | Promise<Response>) {
+  globalThis.fetch = handler as any
+}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+// ─── Shared fixtures ─────────────────────────────────────────────
+
+const baseConfig: ElevenLabsConfig = {
+  apiKey: 'test-xi-api-key',
+  voiceId: 'voice_abc123',
+}
+
+function createProvider(overrides: Partial<ElevenLabsConfig> = {}): ElevenLabsTTS {
+  return new ElevenLabsTTS({ ...baseConfig, ...overrides })
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Constructor and metadata
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ElevenLabsTTS — metadata', () => {
+  it('has correct id and name', () => {
+    const tts = createProvider()
+    expect(tts.id).toBe('elevenlabs')
+    expect(tts.name).toBe('ElevenLabs')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// init / destroy — lifecycle
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ElevenLabsTTS — lifecycle', () => {
+  it('init() resolves without error', async () => {
+    const tts = createProvider()
+    await tts.init() // should not throw
+  })
+
+  it('destroy() resolves without error', async () => {
+    const tts = createProvider()
+    await tts.destroy() // should not throw
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// synthesize — TTS API call
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ElevenLabsTTS — synthesize', () => {
+  it('POSTs to correct URL with correct headers and body', async () => {
+    let capturedUrl = ''
+    let capturedInit: RequestInit | undefined
+
+    mockFetch(async (url, init) => {
+      capturedUrl = url
+      capturedInit = init
+      return new Response(new ArrayBuffer(100), { status: 200 })
+    })
+
+    const tts = createProvider()
+    await tts.synthesize('Hello world')
+
+    expect(capturedUrl).toBe('https://api.elevenlabs.io/v1/text-to-speech/voice_abc123')
+    expect(capturedInit?.method).toBe('POST')
+
+    const headers = capturedInit?.headers as Record<string, string>
+    expect(headers['xi-api-key']).toBe('test-xi-api-key')
+    expect(headers['Content-Type']).toBe('application/json')
+
+    const body = JSON.parse(capturedInit?.body as string)
+    expect(body.text).toBe('Hello world')
+    expect(body.model_id).toBe('eleven_multilingual_v2')
+  })
+
+  it('uses custom modelId from config', async () => {
+    let capturedBody: any
+
+    mockFetch(async (_url, init) => {
+      capturedBody = JSON.parse(init?.body as string)
+      return new Response(new ArrayBuffer(10), { status: 200 })
+    })
+
+    const tts = createProvider({ modelId: 'eleven_turbo_v2_5' })
+    await tts.synthesize('test')
+
+    expect(capturedBody.model_id).toBe('eleven_turbo_v2_5')
+  })
+
+  it('uses config voice_settings defaults', async () => {
+    let capturedBody: any
+
+    mockFetch(async (_url, init) => {
+      capturedBody = JSON.parse(init?.body as string)
+      return new Response(new ArrayBuffer(10), { status: 200 })
+    })
+
+    const tts = createProvider({
+      stability: 0.8,
+      similarityBoost: 0.9,
+      speed: 1.2,
+      language: 'es',
+    })
+    await tts.synthesize('test')
+
+    expect(capturedBody.voice_settings.stability).toBe(0.8)
+    expect(capturedBody.voice_settings.similarity_boost).toBe(0.9)
+    expect(capturedBody.voice_settings.speed).toBe(1.2)
+    expect(capturedBody.language_code).toBe('es')
+  })
+
+  it('uses default voice_settings when config omits them', async () => {
+    let capturedBody: any
+
+    mockFetch(async (_url, init) => {
+      capturedBody = JSON.parse(init?.body as string)
+      return new Response(new ArrayBuffer(10), { status: 200 })
+    })
+
+    const tts = createProvider()
+    await tts.synthesize('test')
+
+    expect(capturedBody.voice_settings.stability).toBe(0.5)
+    expect(capturedBody.voice_settings.similarity_boost).toBe(0.75)
+    expect(capturedBody.voice_settings.speed).toBe(1.0)
+  })
+
+  it('options.voice overrides config voiceId', async () => {
+    let capturedUrl = ''
+
+    mockFetch(async (url) => {
+      capturedUrl = url
+      return new Response(new ArrayBuffer(10), { status: 200 })
+    })
+
+    const tts = createProvider()
+    await tts.synthesize('test', { voice: 'voice_override' })
+
+    expect(capturedUrl).toBe('https://api.elevenlabs.io/v1/text-to-speech/voice_override')
+  })
+
+  it('options.speed overrides config speed', async () => {
+    let capturedBody: any
+
+    mockFetch(async (_url, init) => {
+      capturedBody = JSON.parse(init?.body as string)
+      return new Response(new ArrayBuffer(10), { status: 200 })
+    })
+
+    const tts = createProvider({ speed: 1.0 })
+    await tts.synthesize('test', { speed: 2.0 })
+
+    expect(capturedBody.voice_settings.speed).toBe(2.0)
+  })
+
+  it('options.language overrides config language', async () => {
+    let capturedBody: any
+
+    mockFetch(async (_url, init) => {
+      capturedBody = JSON.parse(init?.body as string)
+      return new Response(new ArrayBuffer(10), { status: 200 })
+    })
+
+    const tts = createProvider({ language: 'en' })
+    await tts.synthesize('test', { language: 'fr' })
+
+    expect(capturedBody.language_code).toBe('fr')
+  })
+
+  it('returns { audio: Buffer, format: "mp3" }', async () => {
+    const audioData = new Uint8Array([0x49, 0x44, 0x33]) // ID3 header
+    mockFetch(async () => new Response(audioData.buffer, { status: 200 }))
+
+    const tts = createProvider()
+    const result = await tts.synthesize('test')
+
+    expect(result.format).toBe('mp3')
+    expect(result.audio).toBeInstanceOf(Buffer)
+    expect(result.audio.length).toBe(3)
+  })
+
+  it('throws on non-OK response', async () => {
+    mockFetch(async () => new Response('{"error":"quota_exceeded"}', { status: 429 }))
+
+    const tts = createProvider()
+    await expect(tts.synthesize('test')).rejects.toThrow('ElevenLabs API error 429')
+  })
+
+  it('includes response body in error message', async () => {
+    mockFetch(async () => new Response('{"detail":"Invalid API key"}', { status: 401 }))
+
+    const tts = createProvider()
+    await expect(tts.synthesize('test')).rejects.toThrow('Invalid API key')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// health — Provider health check
+// ═══════════════════════════════════════════════════════════════════
+
+describe('ElevenLabsTTS — health', () => {
+  it('returns { ok: true } on successful API call', async () => {
+    mockFetch(async (url) => {
+      expect(url).toBe('https://api.elevenlabs.io/v1/user')
+      return new Response('{}', { status: 200 })
+    })
+
+    const tts = createProvider()
+    const health = await tts.health()
+
+    expect(health.ok).toBe(true)
+  })
+
+  it('sends xi-api-key header', async () => {
+    let capturedHeaders: any
+
+    mockFetch(async (_url, init) => {
+      capturedHeaders = init?.headers
+      return new Response('{}', { status: 200 })
+    })
+
+    const tts = createProvider()
+    await tts.health()
+
+    expect(capturedHeaders['xi-api-key']).toBe('test-xi-api-key')
+  })
+
+  it('returns { ok: false } on non-OK response', async () => {
+    mockFetch(async () => new Response('Unauthorized', { status: 401 }))
+
+    const tts = createProvider()
+    const health = await tts.health()
+
+    expect(health.ok).toBe(false)
+  })
+
+  it('returns { ok: false, error } on network error', async () => {
+    mockFetch(async () => {
+      throw new Error('DNS resolution failed')
+    })
+
+    const tts = createProvider()
+    const health = await tts.health()
+
+    expect(health.ok).toBe(false)
+    expect(health.error).toBe('DNS resolution failed')
+  })
+})

package/src/__tests__/whisper.test.ts

@@ -0,0 +1,308 @@
+/**
+ * # Whisper STT Provider — Functional Specification
+ *
+ * ## Constructor
+ * Stores config: apiKey, model (default 'whisper-1'), language (optional).
+ * Base URL: https://api.openai.com/v1
+ *
+ * ## init() / destroy()
+ * Both are no-ops (stateless HTTP API).
+ *
+ * ## transcribe(audio, options?)
+ * POST multipart/form-data to /audio/transcriptions with:
+ * - Authorization: Bearer <apiKey>
+ * - FormData: file (Blob), model, language (optional), response_format: verbose_json
+ * - Options override config: model, language
+ * Returns: { text, language?, durationMs? }
+ * Throws on non-OK response (truncated to 200 chars).
+ *
+ * ## health()
+ * GET /models/whisper-1 with Authorization header.
+ * Returns { ok: boolean, error?: string }.
+ * Catches fetch errors gracefully.
+ */
+import { afterEach, describe, expect, it } from 'bun:test'
+import { type WhisperConfig, WhisperSTT } from '../whisper'
+
+// ─── Mock fetch ──────────────────────────────────────────────────
+
+const originalFetch = globalThis.fetch
+
+function mockFetch(handler: (url: string, init?: RequestInit) => Response | Promise<Response>) {
+  globalThis.fetch = handler as any
+}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+// ─── Shared fixtures ─────────────────────────────────────────────
+
+const baseConfig: WhisperConfig = {
+  apiKey: 'sk-test-openai-key',
+}
+
+function createProvider(overrides: Partial<WhisperConfig> = {}): WhisperSTT {
+  return new WhisperSTT({ ...baseConfig, ...overrides })
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Constructor and metadata
+// ═══════════════════════════════════════════════════════════════════
+
+describe('WhisperSTT — metadata', () => {
+  it('has correct id and name', () => {
+    const stt = createProvider()
+    expect(stt.id).toBe('whisper')
+    expect(stt.name).toBe('OpenAI Whisper')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// init / destroy — lifecycle
+// ═══════════════════════════════════════════════════════════════════
+
+describe('WhisperSTT — lifecycle', () => {
+  it('init() resolves without error', async () => {
+    const stt = createProvider()
+    await stt.init()
+  })
+
+  it('destroy() resolves without error', async () => {
+    const stt = createProvider()
+    await stt.destroy()
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// transcribe — STT API call
+// ═══════════════════════════════════════════════════════════════════
+
+describe('WhisperSTT — transcribe', () => {
+  const fakeAudio = Buffer.from([0x00, 0x01, 0x02, 0x03])
+
+  it('POSTs to correct URL with Authorization header', async () => {
+    let capturedUrl = ''
+    let capturedHeaders: Record<string, string> = {}
+
+    mockFetch(async (url, init) => {
+      capturedUrl = url
+      // Extract Authorization header from init
+      const h = init?.headers as Record<string, string> | undefined
+      if (h) capturedHeaders = h
+      return new Response(JSON.stringify({ text: 'Hello', language: 'en', duration: 1.5 }), {
+        status: 200,
+      })
+    })
+
+    const stt = createProvider()
+    await stt.transcribe(fakeAudio)
+
+    expect(capturedUrl).toBe('https://api.openai.com/v1/audio/transcriptions')
+    expect(capturedHeaders['Authorization']).toBe('Bearer sk-test-openai-key')
+  })
+
+  it('sends FormData with file, model, and response_format', async () => {
+    let capturedBody: FormData | undefined
+
+    mockFetch(async (_url, init) => {
+      capturedBody = init?.body as any
+      return new Response(JSON.stringify({ text: 'Hello' }), { status: 200 })
+    })
+
+    const stt = createProvider()
+    await stt.transcribe(fakeAudio)
+
+    expect(capturedBody).toBeInstanceOf(FormData)
+    expect(capturedBody!.get('model')).toBe('whisper-1')
+    expect(capturedBody!.get('response_format')).toBe('verbose_json')
+    expect(capturedBody!.get('file')).toBeInstanceOf(Blob)
+  })
+
+  it('uses custom model from config', async () => {
+    let capturedBody: FormData | undefined
+
+    mockFetch(async (_url, init) => {
+      capturedBody = init?.body as any
+      return new Response(JSON.stringify({ text: 'test' }), { status: 200 })
+    })
+
+    const stt = createProvider({ model: 'whisper-large-v3' })
+    await stt.transcribe(fakeAudio)
+
+    expect(capturedBody!.get('model')).toBe('whisper-large-v3')
+  })
+
+  it('options.model overrides config model', async () => {
+    let capturedBody: FormData | undefined
+
+    mockFetch(async (_url, init) => {
+      capturedBody = init?.body as any
+      return new Response(JSON.stringify({ text: 'test' }), { status: 200 })
+    })
+
+    const stt = createProvider({ model: 'whisper-1' })
+    await stt.transcribe(fakeAudio, { model: 'whisper-large-v3' })
+
+    expect(capturedBody!.get('model')).toBe('whisper-large-v3')
+  })
+
+  it('includes language from config when set', async () => {
+    let capturedBody: FormData | undefined
+
+    mockFetch(async (_url, init) => {
+      capturedBody = init?.body as any
+      return new Response(JSON.stringify({ text: 'test' }), { status: 200 })
+    })
+
+    const stt = createProvider({ language: 'es' })
+    await stt.transcribe(fakeAudio)
+
+    expect(capturedBody!.get('language')).toBe('es')
+  })
+
+  it('options.language overrides config language', async () => {
+    let capturedBody: FormData | undefined
+
+    mockFetch(async (_url, init) => {
+      capturedBody = init?.body as any
+      return new Response(JSON.stringify({ text: 'test' }), { status: 200 })
+    })
+
+    const stt = createProvider({ language: 'en' })
+    await stt.transcribe(fakeAudio, { language: 'ja' })
+
+    expect(capturedBody!.get('language')).toBe('ja')
+  })
+
+  it('omits language when not configured', async () => {
+    let capturedBody: FormData | undefined
+
+    mockFetch(async (_url, init) => {
+      capturedBody = init?.body as any
+      return new Response(JSON.stringify({ text: 'test' }), { status: 200 })
+    })
+
+    const stt = createProvider()
+    await stt.transcribe(fakeAudio)
+
+    expect(capturedBody!.get('language')).toBeNull()
+  })
+
+  it('returns text, language, and durationMs from response', async () => {
+    mockFetch(
+      async () =>
+        new Response(
+          JSON.stringify({ text: 'Transcribed text', language: 'en', duration: 3.456 }),
+          { status: 200 },
+        ),
+    )
+
+    const stt = createProvider()
+    const result = await stt.transcribe(fakeAudio)
+
+    expect(result.text).toBe('Transcribed text')
+    expect(result.language).toBe('en')
+    expect(result.durationMs).toBe(3456)
+  })
+
+  it('durationMs is undefined when duration is not in response', async () => {
+    mockFetch(async () => new Response(JSON.stringify({ text: 'No duration' }), { status: 200 }))
+
+    const stt = createProvider()
+    const result = await stt.transcribe(fakeAudio)
+
+    expect(result.text).toBe('No duration')
+    expect(result.durationMs).toBeUndefined()
+  })
+
+  it('rounds durationMs to nearest millisecond', async () => {
+    mockFetch(
+      async () => new Response(JSON.stringify({ text: 'test', duration: 1.2345 }), { status: 200 }),
+    )
+
+    const stt = createProvider()
+    const result = await stt.transcribe(fakeAudio)
+
+    expect(result.durationMs).toBe(1235) // Math.round(1234.5)
+  })
+
+  it('throws on non-OK response with status and truncated body', async () => {
+    const longError = 'x'.repeat(500)
+    mockFetch(async () => new Response(longError, { status: 400 }))
+
+    const stt = createProvider()
+    await expect(stt.transcribe(fakeAudio)).rejects.toThrow('Whisper API error 400')
+  })
+
+  it('truncates error body to 200 characters', async () => {
+    const longError = 'e'.repeat(500)
+    mockFetch(async () => new Response(longError, { status: 500 }))
+
+    const stt = createProvider()
+
+    try {
+      await stt.transcribe(fakeAudio)
+      expect(true).toBe(false) // should not reach
+    } catch (err: any) {
+      // The error message includes "Whisper API error 500: " + 200 chars
+      const bodyPart = err.message.split(': ').slice(1).join(': ')
+      expect(bodyPart.length).toBeLessThanOrEqual(200)
+    }
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// health — Provider health check
+// ═══════════════════════════════════════════════════════════════════
+
+describe('WhisperSTT — health', () => {
+  it('returns { ok: true } on successful API call', async () => {
+    mockFetch(async (url) => {
+      expect(url).toBe('https://api.openai.com/v1/models/whisper-1')
+      return new Response('{}', { status: 200 })
+    })
+
+    const stt = createProvider()
+    const health = await stt.health()
+
+    expect(health.ok).toBe(true)
+    expect(health.error).toBeUndefined()
+  })
+
+  it('sends correct Authorization header', async () => {
+    let capturedHeaders: any
+
+    mockFetch(async (_url, init) => {
+      capturedHeaders = init?.headers
+      return new Response('{}', { status: 200 })
+    })
+
+    const stt = createProvider()
+    await stt.health()
+
+    expect(capturedHeaders['Authorization']).toBe('Bearer sk-test-openai-key')
+  })
+
+  it('returns { ok: false, error } on non-OK response', async () => {
+    mockFetch(async () => new Response('Unauthorized', { status: 401 }))
+
+    const stt = createProvider()
+    const health = await stt.health()
+
+    expect(health.ok).toBe(false)
+    expect(health.error).toBe('HTTP 401')
+  })
+
+  it('returns { ok: false, error } on network error', async () => {
+    mockFetch(async () => {
+      throw new Error('ECONNREFUSED')
+    })
+
+    const stt = createProvider()
+    const health = await stt.health()
+
+    expect(health.ok).toBe(false)
+    expect(health.error).toBe('ECONNREFUSED')
+  })
+})

package/src/elevenlabs.ts

@@ -0,0 +1,74 @@
+import type { TTSOptions, TTSProvider, TTSResult } from '@onmars/lunar-core'
+import { log } from '@onmars/lunar-core'
+
+export interface ElevenLabsConfig {
+  apiKey: string
+  voiceId: string
+  modelId?: string
+  language?: string
+  stability?: number
+  similarityBoost?: number
+  speed?: number
+}
+
+export class ElevenLabsTTS implements TTSProvider {
+  readonly id = 'elevenlabs'
+  readonly name = 'ElevenLabs'
+
+  private baseUrl = 'https://api.elevenlabs.io/v1'
+
+  constructor(private config: ElevenLabsConfig) {}
+
+  async init(): Promise<void> {
+    log.info({ voiceId: this.config.voiceId }, 'ElevenLabs TTS initialized')
+  }
+
+  async destroy(): Promise<void> {}
+
+  async synthesize(text: string, options?: TTSOptions): Promise<TTSResult> {
+    const voiceId = options?.voice ?? this.config.voiceId
+    const url = `${this.baseUrl}/text-to-speech/${voiceId}`
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'xi-api-key': this.config.apiKey,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        text,
+        model_id: this.config.modelId ?? 'eleven_multilingual_v2',
+        language_code: options?.language ?? this.config.language,
+        voice_settings: {
+          stability: this.config.stability ?? 0.5,
+          similarity_boost: this.config.similarityBoost ?? 0.75,
+          speed: options?.speed ?? this.config.speed ?? 1.0,
+        },
+      }),
+    })
+
+    if (!response.ok) {
+      const err = await response.text()
+      throw new Error(`ElevenLabs API error ${response.status}: ${err}`)
+    }
+
+    const arrayBuffer = await response.arrayBuffer()
+    const audio = Buffer.from(arrayBuffer)
+
+    return {
+      audio,
+      format: 'mp3',
+    }
+  }
+
+  async health(): Promise<{ ok: boolean; error?: string }> {
+    try {
+      const res = await fetch(`${this.baseUrl}/user`, {
+        headers: { 'xi-api-key': this.config.apiKey },
+      })
+      return { ok: res.ok }
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { ElevenLabsTTS } from './elevenlabs'
+export { WhisperSTT } from './whisper'

package/src/whisper.ts

@@ -0,0 +1,83 @@
+import type { STTOptions, STTProvider, STTResult } from '@onmars/lunar-core'
+
+export interface WhisperConfig {
+  /** OpenAI API key */
+  apiKey: string
+  /** Model ID (default: whisper-1) */
+  model?: string
+  /** Default language hint */
+  language?: string
+}
+
+/**
+ * OpenAI Whisper STT — Speech to text via OpenAI Audio Transcriptions API.
+ *
+ * Uses the multipart/form-data endpoint. Supports all audio formats
+ * that Whisper accepts: mp3, mp4, mpeg, mpga, m4a, wav, webm, ogg.
+ */
+export class WhisperSTT implements STTProvider {
+  readonly id = 'whisper'
+  readonly name = 'OpenAI Whisper'
+
+  private baseUrl = 'https://api.openai.com/v1'
+
+  constructor(private config: WhisperConfig) {}
+
+  async init(): Promise<void> {
+    // No-op — stateless API
+  }
+
+  async destroy(): Promise<void> {
+    // No-op
+  }
+
+  async transcribe(audio: Buffer, options?: STTOptions): Promise<STTResult> {
+    const model = options?.model ?? this.config.model ?? 'whisper-1'
+    const language = options?.language ?? this.config.language
+
+    const form = new FormData()
+    form.append('file', new Blob([audio], { type: 'audio/ogg' }), 'audio.ogg')
+    form.append('model', model)
+    if (language) {
+      form.append('language', language)
+    }
+    form.append('response_format', 'verbose_json')
+
+    const response = await fetch(`${this.baseUrl}/audio/transcriptions`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+      },
+      body: form,
+    })
+
+    if (!response.ok) {
+      const err = await response.text()
+      throw new Error(`Whisper API error ${response.status}: ${err.slice(0, 200)}`)
+    }
+
+    const data = (await response.json()) as {
+      text: string
+      language?: string
+      duration?: number
+    }
+
+    return {
+      text: data.text,
+      language: data.language,
+      durationMs: data.duration ? Math.round(data.duration * 1000) : undefined,
+    }
+  }
+
+  async health(): Promise<{ ok: boolean; error?: string }> {
+    try {
+      // Verify API key by hitting the models endpoint
+      const res = await fetch(`${this.baseUrl}/models/whisper-1`, {
+        headers: { Authorization: `Bearer ${this.config.apiKey}` },
+      })
+      return { ok: res.ok, error: res.ok ? undefined : `HTTP ${res.status}` }
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) }
+    }
+  }
+}