vellum 0.2.1 → 0.2.2

package/src/__tests__/call-routes-http.test.ts

@@ -0,0 +1,459 @@
+/**
+ * HTTP-layer integration tests for the call API endpoints.
+ *
+ * Tests POST /v1/calls/start, GET /v1/calls/:id,
+ * POST /v1/calls/:id/cancel, and POST /v1/calls/:id/answer
+ * through RuntimeHttpServer.
+ */
+import { describe, test, expect, beforeEach, afterAll, mock } from 'bun:test';
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const testDir = realpathSync(mkdtempSync(join(tmpdir(), 'call-routes-http-test-')));
+
+mock.module('../util/platform.js', () => ({
+  getRootDir: () => testDir,
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => ({
+    model: 'test',
+    provider: 'test',
+    apiKeys: {},
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    secretDetection: { enabled: false },
+    calls: {
+      enabled: true,
+      provider: 'twilio',
+      maxDurationSeconds: 3600,
+      userConsultTimeoutSeconds: 120,
+      disclosure: { enabled: false, text: '' },
+      safety: { denyCategories: [] },
+    },
+  }),
+}));
+
+// Mock Twilio provider to avoid real API calls
+mock.module('../calls/twilio-provider.js', () => ({
+  TwilioConversationRelayProvider: class {
+    static getAuthToken() { return 'mock-auth-token'; }
+    static verifyWebhookSignature() { return true; }
+    async initiateCall() { return { callSid: 'CA_mock_sid_123' }; }
+    async endCall() { return; }
+  },
+}));
+
+// Mock Twilio config
+mock.module('../calls/twilio-config.js', () => ({
+  getTwilioConfig: () => ({
+    accountSid: 'AC_test',
+    authToken: 'test_token',
+    phoneNumber: '+15550001111',
+    webhookBaseUrl: 'https://test.example.com',
+    wssBaseUrl: 'wss://test.example.com',
+  }),
+}));
+
+// Mock secure keys
+mock.module('../security/secure-keys.js', () => ({
+  getSecureKey: () => null,
+}));
+
+import { initializeDb, getDb, resetDb } from '../memory/db.js';
+import { conversations } from '../memory/schema.js';
+import { RuntimeHttpServer } from '../runtime/http-server.js';
+import {
+  createCallSession,
+  updateCallSession,
+  createPendingQuestion,
+} from '../calls/call-store.js';
+import '../calls/call-state.js';
+
+initializeDb();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TEST_TOKEN = 'test-bearer-token-calls';
+const AUTH_HEADERS = { Authorization: `Bearer ${TEST_TOKEN}` };
+
+let ensuredConvIds = new Set<string>();
+
+function ensureConversation(id: string): void {
+  if (ensuredConvIds.has(id)) return;
+  const db = getDb();
+  const now = Date.now();
+  db.insert(conversations).values({
+    id,
+    title: `Test conversation ${id}`,
+    createdAt: now,
+    updatedAt: now,
+  }).run();
+  ensuredConvIds.add(id);
+}
+
+function resetTables() {
+  const db = getDb();
+  db.run('DELETE FROM call_pending_questions');
+  db.run('DELETE FROM call_events');
+  db.run('DELETE FROM call_sessions');
+  db.run('DELETE FROM conversations');
+  ensuredConvIds = new Set();
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('runtime call routes — HTTP layer', () => {
+  let server: RuntimeHttpServer;
+  let port: number;
+
+  beforeEach(() => {
+    resetTables();
+  });
+
+  afterAll(() => {
+    resetDb();
+    try { rmSync(testDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  });
+
+  async function startServer(): Promise<void> {
+    port = 19000 + Math.floor(Math.random() * 1000);
+    server = new RuntimeHttpServer({ port, bearerToken: TEST_TOKEN });
+    await server.start();
+  }
+
+  async function stopServer(): Promise<void> {
+    await server?.stop();
+  }
+
+  function callsUrl(path = ''): string {
+    return `http://127.0.0.1:${port}/v1/calls${path}`;
+  }
+
+  // ── POST /v1/calls/start ────────────────────────────────────────────
+
+  test('POST /v1/calls/start returns 201 with call session', async () => {
+    await startServer();
+    ensureConversation('conv-start-1');
+
+    const res = await fetch(callsUrl('/start'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({
+        phoneNumber: '+15559998888',
+        task: 'Book a table for two',
+        conversationId: 'conv-start-1',
+      }),
+    });
+
+    expect(res.status).toBe(201);
+
+    const body = await res.json() as {
+      callSessionId: string;
+      callSid: string;
+      status: string;
+      toNumber: string;
+      fromNumber: string;
+    };
+
+    expect(body.callSessionId).toBeDefined();
+    expect(body.callSid).toBe('CA_mock_sid_123');
+    expect(body.status).toBe('initiated');
+    expect(body.toNumber).toBe('+15559998888');
+    expect(body.fromNumber).toBe('+15550001111');
+
+    await stopServer();
+  });
+
+  test('POST /v1/calls/start returns 400 when conversationId missing', async () => {
+    await startServer();
+
+    const res = await fetch(callsUrl('/start'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({
+        phoneNumber: '+15559998888',
+        task: 'Book a table',
+      }),
+    });
+
+    expect(res.status).toBe(400);
+    const body = await res.json() as { error: string };
+    expect(body.error).toContain('conversationId');
+
+    await stopServer();
+  });
+
+  test('POST /v1/calls/start returns 400 for invalid phone number', async () => {
+    await startServer();
+    ensureConversation('conv-start-2');
+
+    const res = await fetch(callsUrl('/start'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({
+        phoneNumber: 'not-a-number',
+        task: 'Book a table',
+        conversationId: 'conv-start-2',
+      }),
+    });
+
+    expect(res.status).toBe(400);
+    const body = await res.json() as { error: string };
+    expect(body.error).toContain('E.164');
+
+    await stopServer();
+  });
+
+  test('POST /v1/calls/start returns 400 for malformed JSON', async () => {
+    await startServer();
+
+    const res = await fetch(callsUrl('/start'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: 'not-json{{',
+    });
+
+    expect(res.status).toBe(400);
+    const body = await res.json() as { error: string };
+    expect(body.error).toContain('Invalid JSON');
+
+    await stopServer();
+  });
+
+  // ── GET /v1/calls/:id ───────────────────────────────────────────────
+
+  test('GET /v1/calls/:id returns call status', async () => {
+    await startServer();
+    ensureConversation('conv-get-1');
+
+    const session = createCallSession({
+      conversationId: 'conv-get-1',
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15559998888',
+      task: 'Test task',
+    });
+
+    const res = await fetch(callsUrl(`/${session.id}`), {
+      headers: AUTH_HEADERS,
+    });
+
+    expect(res.status).toBe(200);
+
+    const body = await res.json() as {
+      callSessionId: string;
+      status: string;
+      toNumber: string;
+      fromNumber: string;
+      task: string;
+      pendingQuestion: null;
+    };
+
+    expect(body.callSessionId).toBe(session.id);
+    expect(body.status).toBe('initiated');
+    expect(body.toNumber).toBe('+15559998888');
+    expect(body.fromNumber).toBe('+15550001111');
+    expect(body.task).toBe('Test task');
+    expect(body.pendingQuestion).toBeNull();
+
+    await stopServer();
+  });
+
+  test('GET /v1/calls/:id returns 404 for unknown session', async () => {
+    await startServer();
+
+    const res = await fetch(callsUrl('/nonexistent-id'), {
+      headers: AUTH_HEADERS,
+    });
+
+    expect(res.status).toBe(404);
+
+    await stopServer();
+  });
+
+  // ── POST /v1/calls/:id/cancel ──────────────────────────────────────
+
+  test('POST /v1/calls/:id/cancel transitions to cancelled', async () => {
+    await startServer();
+    ensureConversation('conv-cancel-1');
+
+    const session = createCallSession({
+      conversationId: 'conv-cancel-1',
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15559998888',
+    });
+
+    const res = await fetch(callsUrl(`/${session.id}/cancel`), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ reason: 'User requested' }),
+    });
+
+    expect(res.status).toBe(200);
+
+    const body = await res.json() as { callSessionId: string; status: string };
+    expect(body.callSessionId).toBe(session.id);
+    expect(body.status).toBe('cancelled');
+
+    await stopServer();
+  });
+
+  test('POST /v1/calls/:id/cancel returns 409 for already-ended call', async () => {
+    await startServer();
+    ensureConversation('conv-cancel-2');
+
+    const session = createCallSession({
+      conversationId: 'conv-cancel-2',
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15559998888',
+    });
+
+    updateCallSession(session.id, { status: 'completed', endedAt: Date.now() });
+
+    const res = await fetch(callsUrl(`/${session.id}/cancel`), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({}),
+    });
+
+    expect(res.status).toBe(409);
+
+    await stopServer();
+  });
+
+  test('POST /v1/calls/:id/cancel returns 404 for unknown session', async () => {
+    await startServer();
+
+    const res = await fetch(callsUrl('/nonexistent-id/cancel'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({}),
+    });
+
+    expect(res.status).toBe(404);
+
+    await stopServer();
+  });
+
+  // ── POST /v1/calls/:id/answer ──────────────────────────────────────
+
+  test('POST /v1/calls/:id/answer returns 400 for malformed JSON', async () => {
+    await startServer();
+    ensureConversation('conv-answer-badjson');
+
+    const session = createCallSession({
+      conversationId: 'conv-answer-badjson',
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15559998888',
+    });
+
+    const res = await fetch(callsUrl(`/${session.id}/answer`), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: 'not-json{{',
+    });
+
+    expect(res.status).toBe(400);
+    const body = await res.json() as { error: string };
+    expect(body.error).toContain('Invalid JSON');
+
+    await stopServer();
+  });
+
+  test('POST /v1/calls/:id/answer returns 404 when no pending question', async () => {
+    await startServer();
+    ensureConversation('conv-answer-1');
+
+    const session = createCallSession({
+      conversationId: 'conv-answer-1',
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15559998888',
+    });
+
+    const res = await fetch(callsUrl(`/${session.id}/answer`), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ answer: 'Yes, please' }),
+    });
+
+    expect(res.status).toBe(404);
+    const body = await res.json() as { error: string };
+    expect(body.error).toContain('pending question');
+
+    await stopServer();
+  });
+
+  test('POST /v1/calls/:id/answer returns 400 when answer is empty', async () => {
+    await startServer();
+    ensureConversation('conv-answer-2');
+
+    const session = createCallSession({
+      conversationId: 'conv-answer-2',
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15559998888',
+    });
+
+    const res = await fetch(callsUrl(`/${session.id}/answer`), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ answer: '' }),
+    });
+
+    expect(res.status).toBe(400);
+
+    await stopServer();
+  });
+
+  test('POST /v1/calls/:id/answer returns 409 when no orchestrator', async () => {
+    await startServer();
+    ensureConversation('conv-answer-3');
+
+    const session = createCallSession({
+      conversationId: 'conv-answer-3',
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15559998888',
+    });
+
+    // Create a pending question but no orchestrator
+    createPendingQuestion(session.id, 'What date do you prefer?');
+
+    const res = await fetch(callsUrl(`/${session.id}/answer`), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
+      body: JSON.stringify({ answer: 'Tomorrow' }),
+    });
+
+    expect(res.status).toBe(409);
+    const body = await res.json() as { error: string };
+    expect(body.error).toContain('orchestrator');
+
+    await stopServer();
+  });
+});

package/src/__tests__/call-state-machine.test.ts

@@ -0,0 +1,143 @@
+import { describe, test, expect } from 'bun:test';
+import { validateTransition, isTerminalState } from '../calls/call-state-machine.js';
+import type { CallStatus } from '../calls/types.js';
+
+describe('call-state-machine', () => {
+  // ── Valid transitions ───────────────────────────────────────────────
+
+  describe('valid transitions', () => {
+    const validCases: Array<[CallStatus, CallStatus]> = [
+      // From initiated
+      ['initiated', 'ringing'],
+      ['initiated', 'in_progress'],
+      ['initiated', 'completed'],
+      ['initiated', 'failed'],
+      ['initiated', 'cancelled'],
+
+      // From ringing
+      ['ringing', 'in_progress'],
+      ['ringing', 'completed'],
+      ['ringing', 'failed'],
+      ['ringing', 'cancelled'],
+
+      // From in_progress
+      ['in_progress', 'waiting_on_user'],
+      ['in_progress', 'completed'],
+      ['in_progress', 'failed'],
+      ['in_progress', 'cancelled'],
+
+      // From waiting_on_user
+      ['waiting_on_user', 'in_progress'],
+      ['waiting_on_user', 'completed'],
+      ['waiting_on_user', 'failed'],
+      ['waiting_on_user', 'cancelled'],
+    ];
+
+    for (const [from, to] of validCases) {
+      test(`${from} -> ${to} is valid`, () => {
+        const result = validateTransition(from, to);
+        expect(result.valid).toBe(true);
+        expect(result.reason).toBeUndefined();
+      });
+    }
+  });
+
+  // ── Same-state transitions (no-op, valid) ──────────────────────────
+
+  describe('same-state transitions', () => {
+    const allStatuses: CallStatus[] = [
+      'initiated', 'ringing', 'in_progress', 'waiting_on_user',
+      'completed', 'failed', 'cancelled',
+    ];
+
+    for (const status of allStatuses) {
+      test(`${status} -> ${status} is valid (no-op)`, () => {
+        const result = validateTransition(status, status);
+        expect(result.valid).toBe(true);
+      });
+    }
+  });
+
+  // ── Invalid transitions ─────────────────────────────────────────────
+
+  describe('invalid transitions', () => {
+    const invalidCases: Array<[CallStatus, CallStatus]> = [
+      // Cannot skip backwards
+      ['ringing', 'initiated'],
+      ['in_progress', 'initiated'],
+      ['in_progress', 'ringing'],
+      ['waiting_on_user', 'initiated'],
+      ['waiting_on_user', 'ringing'],
+    ];
+
+    for (const [from, to] of invalidCases) {
+      test(`${from} -> ${to} is invalid`, () => {
+        const result = validateTransition(from, to);
+        expect(result.valid).toBe(false);
+        expect(result.reason).toBeDefined();
+        expect(result.reason!.length).toBeGreaterThan(0);
+      });
+    }
+  });
+
+  // ── Terminal state immutability ─────────────────────────────────────
+
+  describe('terminal state immutability', () => {
+    const terminalStates: CallStatus[] = ['completed', 'failed', 'cancelled'];
+    const nonTerminalTargets: CallStatus[] = [
+      'initiated', 'ringing', 'in_progress', 'waiting_on_user',
+    ];
+
+    for (const terminal of terminalStates) {
+      for (const target of nonTerminalTargets) {
+        test(`${terminal} -> ${target} is rejected (terminal state)`, () => {
+          const result = validateTransition(terminal, target);
+          expect(result.valid).toBe(false);
+          expect(result.reason).toContain('terminal');
+        });
+      }
+
+      // Also cannot go between terminal states
+      for (const otherTerminal of terminalStates) {
+        if (otherTerminal === terminal) continue;
+        test(`${terminal} -> ${otherTerminal} is rejected (terminal to terminal)`, () => {
+          const result = validateTransition(terminal, otherTerminal);
+          expect(result.valid).toBe(false);
+          expect(result.reason).toContain('terminal');
+        });
+      }
+    }
+  });
+
+  // ── isTerminalState ─────────────────────────────────────────────────
+
+  describe('isTerminalState', () => {
+    test('completed is terminal', () => {
+      expect(isTerminalState('completed')).toBe(true);
+    });
+
+    test('failed is terminal', () => {
+      expect(isTerminalState('failed')).toBe(true);
+    });
+
+    test('cancelled is terminal', () => {
+      expect(isTerminalState('cancelled')).toBe(true);
+    });
+
+    test('initiated is not terminal', () => {
+      expect(isTerminalState('initiated')).toBe(false);
+    });
+
+    test('ringing is not terminal', () => {
+      expect(isTerminalState('ringing')).toBe(false);
+    });
+
+    test('in_progress is not terminal', () => {
+      expect(isTerminalState('in_progress')).toBe(false);
+    });
+
+    test('waiting_on_user is not terminal', () => {
+      expect(isTerminalState('waiting_on_user')).toBe(false);
+    });
+  });
+});