onbuzz 5.1.0 → 5.4.0

package/src/interfaces/__tests__/attachmentRoutes.test.js

@@ -0,0 +1,118 @@
+import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import { registerAttachmentRoutes } from '../attachmentRoutes.js';
+
+async function post(url, body) {
+  const resp = await globalThis.fetch(url, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body || {}),
+  });
+  const ct = resp.headers.get('content-type') || '';
+  return { status: resp.status, body: ct.includes('json') ? await resp.json() : await resp.text() };
+}
+
+function startApp(getIngestionService) {
+  const app = express();
+  // NOTE: deliberately NO global express.json — the route mounts its own parser.
+  registerAttachmentRoutes(app, { getIngestionService, logger: { error: jest.fn() } });
+  const server = createServer(app);
+  return new Promise((r) => server.listen(0, () => r({ server, baseUrl: `http://localhost:${server.address().port}` })));
+}
+
+let ingestion;
+beforeEach(() => {
+  ingestion = {
+    ingestUpload: jest.fn().mockResolvedValue({ fileId: 'f1', fileName: 'pic.png' }),
+    ingestServerPath: jest.fn().mockResolvedValue({ fileId: 'f2', fileName: 'doc.pdf' }),
+  };
+});
+
+describe('POST /api/agents/:id/attachments', () => {
+  let server, baseUrl;
+  beforeEach(async () => { ({ server, baseUrl } = await startApp(() => ingestion)); });
+  afterEach(() => server?.close());
+
+  it('routes a base64 upload to ingestUpload', async () => {
+    const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'pic.png', dataBase64: 'AAAA', mode: 'content' });
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ success: true, attachment: { fileId: 'f1', fileName: 'pic.png' } });
+    expect(ingestion.ingestUpload).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'a1', fileName: 'pic.png', dataBase64: 'AAAA', mode: 'content' }));
+    expect(ingestion.ingestServerPath).not.toHaveBeenCalled();
+  });
+
+  it('routes a server filePath to ingestServerPath', async () => {
+    const r = await post(`${baseUrl}/api/agents/a1/attachments`, { filePath: '/srv/doc.pdf', fileName: 'doc.pdf' });
+    expect(r.status).toBe(200);
+    expect(r.body.attachment.fileId).toBe('f2');
+    expect(ingestion.ingestServerPath).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'a1', filePath: '/srv/doc.pdf', fileName: 'doc.pdf' }));
+  });
+
+  it('forwards scope + conversationId to ingestion', async () => {
+    await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA', scope: 'conversation', conversationId: 'c1' });
+    expect(ingestion.ingestUpload).toHaveBeenCalledWith(expect.objectContaining({ scope: 'conversation', conversationId: 'c1' }));
+  });
+
+  it('prefers dataBase64 over filePath when both are present', async () => {
+    await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA', filePath: '/srv/x' });
+    expect(ingestion.ingestUpload).toHaveBeenCalledTimes(1);
+    expect(ingestion.ingestServerPath).not.toHaveBeenCalled();
+  });
+
+  it('400s when neither source is provided', async () => {
+    const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x' });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toMatch(/Provide dataBase64.*or filePath/);
+  });
+
+  it('400s with the error message when ingestion throws (validation)', async () => {
+    ingestion.ingestUpload.mockRejectedValueOnce(new Error('Executable files (.exe) are not allowed'));
+    const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'm.exe', dataBase64: 'AA' });
+    expect(r.status).toBe(400);
+    expect(r.body).toMatchObject({ success: false, error: /not allowed/ });
+  });
+});
+
+describe('service-absent + defensive', () => {
+  it('503 when the ingestion service is not wired yet (boot ordering)', async () => {
+    const { server, baseUrl } = await startApp(() => null);
+    try {
+      const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA' });
+      expect(r.status).toBe(503);
+    } finally { server.close(); }
+  });
+
+  it('503 when no thunk is supplied at all', async () => {
+    const { server, baseUrl } = await startApp(undefined);
+    try {
+      expect((await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA' })).status).toBe(503);
+    } finally { server.close(); }
+  });
+
+  it('no-ops when app is null (with and without an options object)', () => {
+    expect(() => registerAttachmentRoutes(null, {})).not.toThrow();
+    expect(() => registerAttachmentRoutes(undefined)).not.toThrow(); // default {} options arm
+  });
+
+  it('handles a request whose body the JSON parser left unset (non-JSON content-type)', async () => {
+    const { server, baseUrl } = await startApp(() => ingestion);
+    try {
+      const resp = await globalThis.fetch(`${baseUrl}/api/agents/a1/attachments`, {
+        method: 'POST', headers: { 'content-type': 'text/plain' }, body: 'not json',
+      });
+      expect(resp.status).toBe(400); // req.body || {} → no source → 400, no crash
+    } finally { server.close(); }
+  });
+
+  it('works with no logger supplied (uses the no-op fallback) on the error path', async () => {
+    const ing = { ingestUpload: jest.fn().mockRejectedValue(new Error('boom')), ingestServerPath: jest.fn() };
+    const app = express();
+    registerAttachmentRoutes(app, { getIngestionService: () => ing }); // no logger
+    const server = createServer(app);
+    await new Promise((r) => server.listen(0, r));
+    const baseUrl = `http://localhost:${server.address().port}`;
+    try {
+      const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA' });
+      expect(r.status).toBe(400); // error path ran through the no-op logger without throwing
+    } finally { server.close(); }
+  });
+});

package/src/interfaces/__tests__/imageServing.test.js

@@ -226,3 +226,91 @@ describe('/api/images/:sessionId/:filename', () => {
     expect(body.error).toBe('Image not found');
   });
 });
+
+// ── /api/image?path=… (serve an image by absolute path) ─────────────
+
+function buildImageByPathApp() {
+  const app = express();
+  // Replicate the exact route from webServer.js
+  app.get('/api/image', async (req, res) => {
+    try {
+      const raw = req.query.path;
+      if (!raw || typeof raw !== 'string') {
+        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'path query is required' });
+      }
+      const resolved = path.resolve(raw);
+      const ext = path.extname(resolved).toLowerCase();
+      const ALLOWED = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.svg'];
+      if (!ALLOWED.includes(ext)) {
+        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported image type' });
+      }
+      const stats = await fs.stat(resolved).catch(() => null);
+      if (!stats || !stats.isFile()) {
+        return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+      }
+      res.sendFile(resolved, (err) => {
+        if (err && !res.headersSent) {
+          res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+        }
+      });
+    } catch (error) {
+      res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+    }
+  });
+  return app;
+}
+
+describe('/api/image?path=', () => {
+  let server, baseUrl, tmpDir, imgPath, txtPath;
+
+  beforeAll(async () => {
+    tmpDir = path.join(os.tmpdir(), `loxia-img-bypath-${Date.now()}`);
+    await fs.mkdir(tmpDir, { recursive: true });
+    imgPath = path.join(tmpDir, 'pic.png');
+    txtPath = path.join(tmpDir, 'notes.txt');
+    await fs.writeFile(imgPath, Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]));
+    await fs.writeFile(txtPath, 'not an image');
+
+    server = createServer(buildImageByPathApp());
+    await new Promise(resolve => server.listen(0, resolve));
+    baseUrl = `http://localhost:${server.address().port}`;
+  });
+
+  afterAll(async () => {
+    server?.close();
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('400 when path is missing', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/image`);
+    expect(status).toBe(400);
+    expect(body.error).toMatch(/path query is required/);
+  });
+
+  it('400 for a non-image extension', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/image?path=${encodeURIComponent(txtPath)}`);
+    expect(status).toBe(400);
+    expect(body.error).toMatch(/Unsupported image type/);
+  });
+
+  it('404 for an image path that does not exist', async () => {
+    const missing = path.join(tmpDir, 'ghost.png');
+    const { status, body } = await fetch(`${baseUrl}/api/image?path=${encodeURIComponent(missing)}`);
+    expect(status).toBe(404);
+    expect(body.error).toBe('Image not found');
+  });
+
+  it('404 when the path is a directory, not a file', async () => {
+    // A directory named like an image so the extension check passes.
+    const dirLikeImage = path.join(tmpDir, 'folder.png');
+    await fs.mkdir(dirLikeImage, { recursive: true });
+    const { status } = await fetch(`${baseUrl}/api/image?path=${encodeURIComponent(dirLikeImage)}`);
+    expect(status).toBe(404);
+  });
+
+  it('serves an existing image by absolute path', async () => {
+    const { status, headers } = await fetch(`${baseUrl}/api/image?path=${encodeURIComponent(imgPath)}`);
+    expect(status).toBe(200);
+    expect(headers.get('content-type')).toMatch(/image|octet/);
+  });
+});

package/src/interfaces/__tests__/scheduleRoutes.test.js

@@ -0,0 +1,223 @@
+/**
+ * HTTP route tests for the scheduled-tasks API (registerScheduleRoutes).
+ *
+ * Mounts a real Express app + the production helper — the same shape
+ * webServer.js uses — so the status codes / response shapes and the
+ * service-absent + not-found + error branches are locked.
+ */
+import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import { registerScheduleRoutes } from '../scheduleRoutes.js';
+
+async function http(url, options = {}) {
+  const resp = await globalThis.fetch(url, options);
+  const ct = resp.headers.get('content-type') || '';
+  const body = ct.includes('json') ? await resp.json() : await resp.text();
+  return { status: resp.status, body };
+}
+
+function startApp(getScheduleService, logger = { error: jest.fn() }) {
+  const app = express();
+  app.use(express.json());
+  registerScheduleRoutes(app, { getScheduleService, logger });
+  const server = createServer(app);
+  return new Promise((resolve) => {
+    server.listen(0, () => resolve({ server, baseUrl: `http://localhost:${server.address().port}` }));
+  });
+}
+
+function fakeService(overrides = {}) {
+  return {
+    listSchedules: jest.fn().mockReturnValue([{ id: 's1', name: 'A' }]),
+    getPresets: jest.fn().mockReturnValue({ daily: '0 9 * * *' }),
+    createSchedule: jest.fn().mockResolvedValue({ id: 'new', name: 'New' }),
+    getSchedule: jest.fn().mockReturnValue({ id: 's1', name: 'A', enabled: true }),
+    updateSchedule: jest.fn().mockResolvedValue({ id: 's1', name: 'A', enabled: false }),
+    deleteSchedule: jest.fn().mockResolvedValue(undefined),
+    triggerSchedule: jest.fn().mockResolvedValue({ id: 's1', name: 'A', lastRunStatus: 'success' }),
+    ...overrides,
+  };
+}
+
+describe('registerScheduleRoutes — happy paths', () => {
+  let server, baseUrl, svc;
+  beforeEach(async () => {
+    svc = fakeService();
+    ({ server, baseUrl } = await startApp(() => svc));
+  });
+  afterEach(() => server?.close());
+
+  it('GET /api/schedules lists', async () => {
+    const r = await http(`${baseUrl}/api/schedules`);
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ success: true, schedules: [{ id: 's1', name: 'A' }] });
+  });
+
+  it('GET /api/schedules/presets returns presets (and is not captured by /:id)', async () => {
+    const r = await http(`${baseUrl}/api/schedules/presets`);
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ success: true, presets: { daily: '0 9 * * *' } });
+    expect(svc.getSchedule).not.toHaveBeenCalledWith('presets');
+  });
+
+  it('POST /api/schedules creates', async () => {
+    const r = await http(`${baseUrl}/api/schedules`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'New' }),
+    });
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ success: true, schedule: { id: 'new', name: 'New' } });
+    expect(svc.createSchedule).toHaveBeenCalledWith({ name: 'New' });
+  });
+
+  it('GET /api/schedules/:id reads', async () => {
+    const r = await http(`${baseUrl}/api/schedules/s1`);
+    expect(r.status).toBe(200);
+    expect(r.body.schedule.id).toBe('s1');
+  });
+
+  it('PUT /api/schedules/:id updates', async () => {
+    const r = await http(`${baseUrl}/api/schedules/s1`, {
+      method: 'PUT', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'A' }),
+    });
+    expect(r.status).toBe(200);
+    expect(svc.updateSchedule).toHaveBeenCalledWith('s1', { name: 'A' });
+  });
+
+  it('DELETE /api/schedules/:id deletes', async () => {
+    const r = await http(`${baseUrl}/api/schedules/s1`, { method: 'DELETE' });
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ success: true });
+    expect(svc.deleteSchedule).toHaveBeenCalledWith('s1');
+  });
+
+  it('POST /api/schedules/:id/trigger force-runs and returns run status', async () => {
+    const r = await http(`${baseUrl}/api/schedules/s1/trigger`, { method: 'POST' });
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ success: true, scheduleName: 'A', lastRunStatus: 'success' });
+    expect(svc.triggerSchedule).toHaveBeenCalledWith('s1');
+  });
+
+  it('POST /api/schedules/:id/toggle flips enabled', async () => {
+    const r = await http(`${baseUrl}/api/schedules/s1/toggle`, { method: 'POST' });
+    expect(r.status).toBe(200);
+    expect(svc.updateSchedule).toHaveBeenCalledWith('s1', { enabled: false }); // current.enabled was true
+  });
+});
+
+describe('registerScheduleRoutes — service absent (boot ordering)', () => {
+  let server, baseUrl;
+  beforeEach(async () => { ({ server, baseUrl } = await startApp(() => null)); });
+  afterEach(() => server?.close());
+
+  it('list degrades to an empty array', async () => {
+    expect(await http(`${baseUrl}/api/schedules`)).toMatchObject({ status: 200, body: { schedules: [] } });
+  });
+  it('presets degrade to an empty object', async () => {
+    expect(await http(`${baseUrl}/api/schedules/presets`)).toMatchObject({ status: 200, body: { presets: {} } });
+  });
+  it('create 400s', async () => {
+    expect((await http(`${baseUrl}/api/schedules`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' })).status).toBe(400);
+  });
+  it('read 404s', async () => {
+    expect((await http(`${baseUrl}/api/schedules/x`)).status).toBe(404);
+  });
+  it('update / delete / trigger / toggle 400 (trigger/toggle without a service)', async () => {
+    expect((await http(`${baseUrl}/api/schedules/x`, { method: 'PUT', headers: { 'content-type': 'application/json' }, body: '{}' })).status).toBe(400);
+    expect((await http(`${baseUrl}/api/schedules/x`, { method: 'DELETE' })).status).toBe(400);
+    expect((await http(`${baseUrl}/api/schedules/x/trigger`, { method: 'POST' })).status).toBe(400);
+    expect((await http(`${baseUrl}/api/schedules/x/toggle`, { method: 'POST' })).status).toBe(400);
+  });
+});
+
+describe('registerScheduleRoutes — not-found + error branches', () => {
+  it('trigger 404s when the schedule does not exist', async () => {
+    const svc = fakeService({ getSchedule: jest.fn().mockReturnValue(null) });
+    const { server, baseUrl } = await startApp(() => svc);
+    try {
+      const r = await http(`${baseUrl}/api/schedules/ghost/trigger`, { method: 'POST' });
+      expect(r.status).toBe(404);
+      expect(svc.triggerSchedule).not.toHaveBeenCalled();
+    } finally { server.close(); }
+  });
+
+  it('toggle 404s when the schedule does not exist', async () => {
+    const svc = fakeService({ getSchedule: jest.fn().mockReturnValue(null) });
+    const { server, baseUrl } = await startApp(() => svc);
+    try {
+      expect((await http(`${baseUrl}/api/schedules/ghost/toggle`, { method: 'POST' })).status).toBe(404);
+    } finally { server.close(); }
+  });
+
+  it('create 400s with the error message when the service throws (validation)', async () => {
+    const svc = fakeService({ createSchedule: jest.fn().mockRejectedValue(new Error('name is required')) });
+    const { server, baseUrl } = await startApp(() => svc);
+    try {
+      const r = await http(`${baseUrl}/api/schedules`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
+      expect(r.status).toBe(400);
+      expect(r.body).toMatchObject({ success: false, error: 'name is required' });
+    } finally { server.close(); }
+  });
+
+  it('list 500s when the service throws', async () => {
+    const svc = fakeService({ listSchedules: jest.fn(() => { throw new Error('boom'); }) });
+    const { server, baseUrl } = await startApp(() => svc);
+    try {
+      const r = await http(`${baseUrl}/api/schedules`);
+      expect(r.status).toBe(500);
+      expect(r.body).toMatchObject({ error: 'boom' });
+    } finally { server.close(); }
+  });
+
+  it('trigger 500s when triggerSchedule throws', async () => {
+    const svc = fakeService({ triggerSchedule: jest.fn().mockRejectedValue(new Error('exec fail')) });
+    const { server, baseUrl } = await startApp(() => svc);
+    try {
+      const r = await http(`${baseUrl}/api/schedules/s1/trigger`, { method: 'POST' });
+      expect(r.status).toBe(500);
+    } finally { server.close(); }
+  });
+
+  it('presets 500s when getPresets throws', async () => {
+    const svc = fakeService({ getPresets: jest.fn(() => { throw new Error('p'); }) });
+    const { server, baseUrl } = await startApp(() => svc);
+    try {
+      expect((await http(`${baseUrl}/api/schedules/presets`)).status).toBe(500);
+    } finally { server.close(); }
+  });
+
+  it('read 500s when getSchedule throws', async () => {
+    const svc = fakeService({ getSchedule: jest.fn(() => { throw new Error('r'); }) });
+    const { server, baseUrl } = await startApp(() => svc);
+    try {
+      expect((await http(`${baseUrl}/api/schedules/s1`)).status).toBe(500);
+    } finally { server.close(); }
+  });
+
+  it('update / delete / toggle 400 when the service throws', async () => {
+    const svc = fakeService({
+      updateSchedule: jest.fn().mockRejectedValue(new Error('u')),
+      deleteSchedule: jest.fn().mockRejectedValue(new Error('d')),
+    });
+    const { server, baseUrl } = await startApp(() => svc);
+    try {
+      expect((await http(`${baseUrl}/api/schedules/s1`, { method: 'PUT', headers: { 'content-type': 'application/json' }, body: '{}' })).status).toBe(400);
+      expect((await http(`${baseUrl}/api/schedules/s1`, { method: 'DELETE' })).status).toBe(400);
+      expect((await http(`${baseUrl}/api/schedules/s1/toggle`, { method: 'POST' })).status).toBe(400);
+    } finally { server.close(); }
+  });
+});
+
+describe('registerScheduleRoutes — defensive', () => {
+  it('no-ops when app is null (does not throw)', () => {
+    expect(() => registerScheduleRoutes(null, {})).not.toThrow();
+  });
+  it('tolerates a missing getScheduleService thunk (treats service as absent)', async () => {
+    const { server, baseUrl } = await startApp(undefined);
+    try {
+      expect((await http(`${baseUrl}/api/schedules`)).body.schedules).toEqual([]);
+    } finally { server.close(); }
+  });
+});

package/src/interfaces/__tests__/transcribeProxy.test.js

@@ -0,0 +1,85 @@
+import { describe, test, expect, jest } from '@jest/globals';
+import { proxyTranscribe } from '../transcribeProxy.js';
+
+const okJson = (data) => ({ ok: true, status: 200, json: async () => data, text: async () => JSON.stringify(data) });
+const errRes = (status, text) => ({ ok: false, status, json: async () => ({}), text: async () => text ?? '' });
+
+const base = { audioBase64: 'AAAA', apiKey: 'key-1', backendBaseUrl: 'https://backend.test' };
+
+describe('proxyTranscribe', () => {
+  test('400 when audioBase64 is missing or not a string', async () => {
+    expect((await proxyTranscribe()).status).toBe(400); // no args → default {} → 400
+    expect((await proxyTranscribe({ apiKey: 'k', fetchImpl: jest.fn() })).status).toBe(400);
+    expect((await proxyTranscribe({ audioBase64: 123, apiKey: 'k', fetchImpl: jest.fn() })).status).toBe(400);
+  });
+
+  test('401 when no apiKey', async () => {
+    const r = await proxyTranscribe({ audioBase64: 'AAAA', fetchImpl: jest.fn() });
+    expect(r.status).toBe(401);
+    expect(r.body.error).toMatch(/API key/);
+  });
+
+  test('500 when no fetch implementation', async () => {
+    const r = await proxyTranscribe({ ...base, fetchImpl: null });
+    expect(r.status).toBe(500);
+  });
+
+  test('forwards to <backend>/llm/transcribe with bearer auth + payload, returns trimmed text', async () => {
+    const fetchImpl = jest.fn(async () => okJson({ text: '  hello world  ' }));
+    const r = await proxyTranscribe({ ...base, mimeType: 'audio/ogg', filename: 'v.ogg', durationSeconds: 3, fetchImpl });
+    expect(r.status).toBe(200);
+    expect(r.body.text).toBe('hello world');
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const [url, opts] = fetchImpl.mock.calls[0];
+    expect(url).toBe('https://backend.test/llm/transcribe');
+    expect(opts.headers.Authorization).toBe('Bearer key-1');
+    const sent = JSON.parse(opts.body);
+    expect(sent).toMatchObject({ audioBase64: 'AAAA', mimeType: 'audio/ogg', filename: 'v.ogg', durationSeconds: 3 });
+  });
+
+  test('defaults mimeType/filename and omits durationSeconds when not a number', async () => {
+    const fetchImpl = jest.fn(async () => okJson({ text: 'hi' }));
+    await proxyTranscribe({ ...base, durationSeconds: 'nope', fetchImpl });
+    const sent = JSON.parse(fetchImpl.mock.calls[0][1].body);
+    expect(sent.mimeType).toBe('audio/webm');
+    expect(sent.filename).toBe('dictation.webm');
+    expect('durationSeconds' in sent).toBe(false);
+  });
+
+  test('503 from backend → 503 not-configured message', async () => {
+    const r = await proxyTranscribe({ ...base, fetchImpl: async () => errRes(503) });
+    expect(r.status).toBe(503);
+    expect(r.body.error).toMatch(/not configured/i);
+  });
+
+  test('non-ok backend → relays status + truncated details', async () => {
+    const r = await proxyTranscribe({ ...base, fetchImpl: async () => errRes(500, 'x'.repeat(500)), logger: { warn() {} } });
+    expect(r.status).toBe(500);
+    expect(r.body.error).toMatch(/Transcription failed \(500\)/);
+    expect(r.body.details.length).toBe(300);
+  });
+
+  test('fetch throwing → 502', async () => {
+    const r = await proxyTranscribe({ ...base, fetchImpl: async () => { throw new Error('socket'); }, logger: { error() {} } });
+    expect(r.status).toBe(502);
+    expect(r.body.error).toMatch(/socket/);
+  });
+
+  test('ok but non-JSON body → empty text (tolerated)', async () => {
+    const r = await proxyTranscribe({ ...base, fetchImpl: async () => ({ ok: true, status: 200, json: async () => { throw new Error('not json'); } }) });
+    expect(r.status).toBe(200);
+    expect(r.body.text).toBe('');
+  });
+
+  test('uses the default backend URL when none provided', async () => {
+    const fetchImpl = jest.fn(async () => okJson({ text: 'ok' }));
+    await proxyTranscribe({ audioBase64: 'AAAA', apiKey: 'k', fetchImpl });
+    expect(fetchImpl.mock.calls[0][0]).toMatch(/^https:\/\/.+\/llm\/transcribe$/);
+  });
+
+  test('non-ok with text() throwing still relays status', async () => {
+    const r = await proxyTranscribe({ ...base, fetchImpl: async () => ({ ok: false, status: 418, text: async () => { throw new Error('no body'); } }) });
+    expect(r.status).toBe(418);
+    expect(r.body.details).toBe('');
+  });
+});

package/src/interfaces/__tests__/transcribeRoute.test.js

@@ -0,0 +1,127 @@
+/**
+ * Route-level tests for POST /api/llm/transcribe (registerTranscribeRoute).
+ *
+ * The proxy itself (proxyTranscribe) is covered separately; here we lock the
+ * API-key resolution ladder and the status/body relay by mounting the real
+ * helper on a bare Express app with an injected proxy stub.
+ */
+import { jest, describe, it, expect, afterEach } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import { registerTranscribeRoute, resolveTranscribeApiKey } from '../transcribeRoute.js';
+
+async function post(url, body, headers = {}) {
+  const resp = await globalThis.fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body: JSON.stringify(body || {}),
+  });
+  const ct = resp.headers.get('content-type') || '';
+  return { status: resp.status, body: ct.includes('json') ? await resp.json() : await resp.text() };
+}
+
+function startApp(deps) {
+  const app = express();
+  app.use(express.json());
+  registerTranscribeRoute(app, deps);
+  const server = createServer(app);
+  return new Promise((resolve) => {
+    server.listen(0, () => resolve({ server, baseUrl: `http://localhost:${server.address().port}` }));
+  });
+}
+
+describe('resolveTranscribeApiKey (key ladder)', () => {
+  const OLD_ENV = process.env.LOXIA_API_KEY;
+  afterEach(() => {
+    if (OLD_ENV === undefined) delete process.env.LOXIA_API_KEY;
+    else process.env.LOXIA_API_KEY = OLD_ENV;
+  });
+
+  it('prefers the Bearer header', () => {
+    const key = resolveTranscribeApiKey({
+      authHeader: 'Bearer HEADERKEY',
+      apiKeyManager: { getKeysForRequest: () => ({ loxiaApiKey: 'MGR' }) },
+      config: { loxiaApiKey: 'CFG' },
+    });
+    expect(key).toBe('HEADERKEY');
+  });
+
+  it('falls back to the apiKeyManager platform key', () => {
+    const key = resolveTranscribeApiKey({
+      authHeader: undefined,
+      apiKeyManager: { getKeysForRequest: jest.fn().mockReturnValue({ loxiaApiKey: 'MGR' }) },
+      sessionId: 'sess',
+      config: { loxiaApiKey: 'CFG' },
+    });
+    expect(key).toBe('MGR');
+  });
+
+  it('falls back to config, then env, then null', () => {
+    delete process.env.LOXIA_API_KEY;
+    expect(resolveTranscribeApiKey({ config: { loxiaApiKey: 'CFG' } })).toBe('CFG');
+    process.env.LOXIA_API_KEY = 'ENVKEY';
+    expect(resolveTranscribeApiKey({ config: {} })).toBe('ENVKEY');
+    delete process.env.LOXIA_API_KEY;
+    expect(resolveTranscribeApiKey({ config: {} })).toBeNull();
+  });
+
+  it('ignores a non-Bearer auth header', () => {
+    expect(resolveTranscribeApiKey({ authHeader: 'Basic abc', config: { loxiaApiKey: 'CFG' } })).toBe('CFG');
+  });
+
+  it('falls through when the manager lacks getKeysForRequest (optional chain)', () => {
+    expect(resolveTranscribeApiKey({ apiKeyManager: {}, config: { loxiaApiKey: 'CFG' } })).toBe('CFG');
+  });
+
+  it('falls through when the manager returns no platform key', () => {
+    expect(resolveTranscribeApiKey({
+      apiKeyManager: { getKeysForRequest: () => ({}) },
+      config: { loxiaApiKey: 'CFG' },
+    })).toBe('CFG');
+  });
+});
+
+describe('POST /api/llm/transcribe', () => {
+  it('relays the proxy status + body and forwards the resolved key', async () => {
+    const proxyImpl = jest.fn().mockResolvedValue({ status: 200, body: { text: 'hello world' } });
+    const { server, baseUrl } = await startApp({
+      getApiKeyManager: () => null,
+      config: { loxiaApiKey: 'CFG', backend: { baseUrl: 'https://b' } },
+      logger: { warn: jest.fn() },
+      proxyImpl,
+    });
+    try {
+      const r = await post(`${baseUrl}/api/llm/transcribe`, { audioBase64: 'AAA', mimeType: 'audio/webm' });
+      expect(r.status).toBe(200);
+      expect(r.body).toEqual({ text: 'hello world' });
+      expect(proxyImpl).toHaveBeenCalledWith(expect.objectContaining({
+        audioBase64: 'AAA', mimeType: 'audio/webm', apiKey: 'CFG', backendBaseUrl: 'https://b',
+      }));
+    } finally { server.close(); }
+  });
+
+  it('relays a non-200 proxy result unchanged (e.g. 400 no audio)', async () => {
+    const proxyImpl = jest.fn().mockResolvedValue({ status: 400, body: { error: 'No audio provided' } });
+    const { server, baseUrl } = await startApp({ getApiKeyManager: () => null, config: {}, proxyImpl });
+    try {
+      const r = await post(`${baseUrl}/api/llm/transcribe`, {});
+      expect(r.status).toBe(400);
+      expect(r.body).toMatchObject({ error: 'No audio provided' });
+    } finally { server.close(); }
+  });
+
+  it('uses the apiKeyManager when no Bearer header is sent', async () => {
+    const proxyImpl = jest.fn().mockResolvedValue({ status: 200, body: { text: '' } });
+    const apiKeyManager = { getKeysForRequest: jest.fn().mockReturnValue({ loxiaApiKey: 'MGRKEY' }) };
+    const { server, baseUrl } = await startApp({ getApiKeyManager: () => apiKeyManager, config: {}, proxyImpl });
+    try {
+      await post(`${baseUrl}/api/llm/transcribe`, { audioBase64: 'X', sessionId: 's1' });
+      expect(apiKeyManager.getKeysForRequest).toHaveBeenCalledWith('s1', { platformProvided: true });
+      expect(proxyImpl).toHaveBeenCalledWith(expect.objectContaining({ apiKey: 'MGRKEY' }));
+    } finally { server.close(); }
+  });
+
+  it('no-ops registration when app is null', () => {
+    expect(() => registerTranscribeRoute(null, {})).not.toThrow();
+  });
+});