onbuzz 5.1.0 → 5.3.0

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();
+  });
+});

package/src/interfaces/attachmentRoutes.js

@@ -0,0 +1,56 @@
+/**
+ * Chat attachment ingest route.
+ *
+ * POST /api/agents/:agentId/attachments
+ *   - { fileName, dataBase64, mode? } → binary-safe upload of raw bytes
+ *   - { filePath, mode?, fileName? }  → ingest a file already on the server
+ *
+ * Mounted with its OWN higher-limit JSON parser so base64 uploads aren't capped
+ * by the global 10 MB body limit (base64 inflates ~33%, so 50 MB ≈ a ~37 MB
+ * file). Extracted into a register helper so it mounts on a bare Express app
+ * for testing — same idiom as registerScheduleRoutes. The ingestion service is
+ * read through a thunk because it's wired after routes are registered at boot.
+ *
+ * NOTE: true multipart/streaming (busboy) is a future optimization for very
+ * large files; base64 ingestion is dependency-free, binary-correct, and covers
+ * the practical size range.
+ */
+import express from 'express';
+
+export function registerAttachmentRoutes(app, { getIngestionService, logger, jsonLimit = '50mb' } = {}) {
+  if (!app) return;
+  const svc = () => (typeof getIngestionService === 'function' ? getIngestionService() : null);
+  const log = logger || { error() {} };
+  const bigJson = express.json({ limit: jsonLimit });
+
+  app.post('/api/agents/:agentId/attachments', bigJson, async (req, res) => {
+    try {
+      const ingestion = svc();
+      if (!ingestion) {
+        return res.status(503).json({ success: false, error: 'Attachment ingestion not available' });
+      }
+      const { agentId } = req.params;
+      /* istanbul ignore next: bigJson always populates req.body on this route; the ||{} is a pure safety net */
+      const { fileName, dataBase64, filePath, mode, scope, conversationId } = req.body || {};
+
+      let attachment;
+      if (dataBase64) {
+        attachment = await ingestion.ingestUpload({ agentId, fileName, dataBase64, mode, scope, conversationId });
+      } else if (filePath) {
+        attachment = await ingestion.ingestServerPath({ agentId, filePath, mode, fileName, scope, conversationId });
+      } else {
+        return res.status(400).json({
+          success: false,
+          error: 'Provide dataBase64 (upload) or filePath (server file)',
+        });
+      }
+
+      res.json({ success: true, attachment });
+    } catch (error) {
+      log.error('Attachment ingest failed', { agentId: req.params.agentId, error: error.message });
+      res.status(400).json({ success: false, error: error.message });
+    }
+  });
+}
+
+export default registerAttachmentRoutes;

package/src/interfaces/scheduleRoutes.js

@@ -0,0 +1,128 @@
+/**
+ * Scheduled-tasks HTTP API.
+ *
+ * Extracted from webServer.setupRoutes so the whole /api/schedules surface
+ * (list, presets, create, read, update, delete, trigger, toggle) can be
+ * mounted on a bare Express app and tested without standing up the full
+ * server — same pattern as registerSchedulerRoutes.
+ *
+ * scheduleService is read through a thunk (getScheduleService) because the
+ * orchestrator wires it in AFTER routes are registered at boot; a handler
+ * that captured a null reference at registration time would 400/404 forever.
+ *
+ * Behavior (status codes + response shapes) mirrors the original inline
+ * handlers exactly — see scheduleRoutes.test.js for the locked contract.
+ */
+
+export function registerScheduleRoutes(app, { getScheduleService, logger } = {}) {
+  if (!app) return;
+  const svc = () => (typeof getScheduleService === 'function' ? getScheduleService() : null);
+  const log = logger || { error() {}, warn() {}, info() {} };
+
+  // List all schedules — degrades to an empty list when the service is absent.
+  app.get('/api/schedules', async (req, res) => {
+    try {
+      const s = svc();
+      if (!s) return res.json({ success: true, schedules: [] });
+      res.json({ success: true, schedules: s.listSchedules() });
+    } catch (error) {
+      log.error('Failed to list schedules', { error: error.message });
+      res.status(500).json({ success: false, error: error.message });
+    }
+  });
+
+  // Cron presets — registered BEFORE /:id so "presets" isn't captured as an id.
+  app.get('/api/schedules/presets', async (req, res) => {
+    try {
+      const s = svc();
+      if (!s) return res.json({ success: true, presets: {} });
+      res.json({ success: true, presets: s.getPresets() });
+    } catch (error) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  });
+
+  // Create
+  app.post('/api/schedules', async (req, res) => {
+    try {
+      const s = svc();
+      if (!s) return res.status(400).json({ success: false, error: 'Schedule service not available' });
+      const schedule = await s.createSchedule(req.body);
+      res.json({ success: true, schedule });
+    } catch (error) {
+      log.error('Failed to create schedule', { error: error.message });
+      res.status(400).json({ success: false, error: error.message });
+    }
+  });
+
+  // Read one
+  app.get('/api/schedules/:id', async (req, res) => {
+    try {
+      const s = svc();
+      if (!s) return res.status(404).json({ success: false, error: 'Schedule service not available' });
+      const schedule = s.getSchedule(req.params.id);
+      if (!schedule) return res.status(404).json({ success: false, error: 'Schedule not found' });
+      res.json({ success: true, schedule });
+    } catch (error) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  });
+
+  // Update
+  app.put('/api/schedules/:id', async (req, res) => {
+    try {
+      const s = svc();
+      if (!s) return res.status(400).json({ success: false, error: 'Schedule service not available' });
+      const schedule = await s.updateSchedule(req.params.id, req.body);
+      res.json({ success: true, schedule });
+    } catch (error) {
+      log.error('Failed to update schedule', { error: error.message });
+      res.status(400).json({ success: false, error: error.message });
+    }
+  });
+
+  // Delete
+  app.delete('/api/schedules/:id', async (req, res) => {
+    try {
+      const s = svc();
+      if (!s) return res.status(400).json({ success: false, error: 'Schedule service not available' });
+      await s.deleteSchedule(req.params.id);
+      res.json({ success: true });
+    } catch (error) {
+      log.error('Failed to delete schedule', { error: error.message });
+      res.status(400).json({ success: false, error: error.message });
+    }
+  });
+
+  // Force-trigger immediately (used by the Run-now button + CLI trigger-schedule)
+  app.post('/api/schedules/:id/trigger', async (req, res) => {
+    try {
+      const s = svc();
+      if (!s) return res.status(400).json({ success: false, error: 'Schedule service not available' });
+      if (!s.getSchedule(req.params.id)) {
+        return res.status(404).json({ success: false, error: 'Schedule not found' });
+      }
+      const schedule = await s.triggerSchedule(req.params.id);
+      res.json({ success: true, scheduleName: schedule.name, lastRunStatus: schedule.lastRunStatus });
+    } catch (error) {
+      log.error('Failed to trigger schedule', { error: error.message });
+      res.status(500).json({ success: false, error: error.message });
+    }
+  });
+
+  // Toggle enabled/disabled
+  app.post('/api/schedules/:id/toggle', async (req, res) => {
+    try {
+      const s = svc();
+      if (!s) return res.status(400).json({ success: false, error: 'Schedule service not available' });
+      const current = s.getSchedule(req.params.id);
+      if (!current) return res.status(404).json({ success: false, error: 'Schedule not found' });
+      const schedule = await s.updateSchedule(req.params.id, { enabled: !current.enabled });
+      res.json({ success: true, schedule });
+    } catch (error) {
+      res.status(400).json({ success: false, error: error.message });
+    }
+  });
+}
+
+export default registerScheduleRoutes;