availsync 0.1.0

package/tests/setup.ts

@@ -0,0 +1,4 @@
+process.env.DATABASE_URL =
+  process.env.TEST_DATABASE_URL ||
+  'postgresql://postgres:postgres@localhost:5432/availsync_test';
+process.env.NODE_ENV = 'test';

package/tests/smoke.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+set -e
+BASE="http://localhost:3000"
+ERRORS=0
+
+check() {
+  local desc=$1
+  local expected=$2
+  local actual=$3
+  if [ "$actual" = "$expected" ]; then
+    echo "OK: $desc"
+  else
+    echo "FAIL: $desc (expected $expected, got $actual)"
+    ERRORS=$((ERRORS + 1))
+  fi
+}
+
+echo "=== Availsync Smoke Tests ==="
+
+STATUS=$(curl -s -o /dev/null -w "%{http_code}" $BASE/health)
+check "Health endpoint" "200" "$STATUS"
+
+ORG_RESPONSE=$(curl -s -X POST $BASE/v1/orgs \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Test Org"}')
+ORG_ID=$(echo $ORG_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+check "Create org returns id" "true" "$([ -n "$ORG_ID" ] && echo true || echo false)"
+
+AGENT_RESPONSE=$(curl -s -X POST $BASE/v1/orgs/$ORG_ID/agents \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Sales Bot", "agent_type": "external_meeting"}')
+API_KEY=$(echo $AGENT_RESPONSE | grep -o '"api_key":"[^"]*"' | cut -d'"' -f4)
+AGENT_ID=$(echo $AGENT_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+check "Create agent returns api_key" "true" "$([ -n "$API_KEY" ] && echo true || echo false)"
+
+TOMORROW=$(date -d "+1 day" +%Y-%m-%dT09:00:00Z 2>/dev/null || date -v+1d +%Y-%m-%dT09:00:00Z)
+TOMORROW_END=$(date -d "+1 day" +%Y-%m-%dT17:00:00Z 2>/dev/null || date -v+1d +%Y-%m-%dT17:00:00Z)
+WIN_STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X POST $BASE/v1/availability-windows \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"agent_id\":\"$AGENT_ID\",\"start_at\":\"$TOMORROW\",\"end_at\":\"$TOMORROW_END\",\"window_type\":\"available\"}")
+check "Create availability window" "201" "$WIN_STATUS"
+
+AVAIL_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+  "$BASE/v1/availability?agent_id=$AGENT_ID&from=$TOMORROW&to=$TOMORROW_END&duration_minutes=30" \
+  -H "Authorization: Bearer $API_KEY")
+check "Get availability" "200" "$AVAIL_STATUS"
+
+HOLD_END=$(date -d "+1 day" +%Y-%m-%dT10:00:00Z 2>/dev/null || date -v+1d +%Y-%m-%dT10:00:00Z)
+HOLD_RESPONSE=$(curl -s -X POST $BASE/v1/holds \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"agent_id\":\"$AGENT_ID\",\"start_at\":\"$TOMORROW\",\"end_at\":\"$HOLD_END\",\"reason\":\"Test booking\"}")
+HOLD_STATUS=$(echo $HOLD_RESPONSE | grep -o '"status":"[^"]*"' | head -1 | cut -d'"' -f4)
+check "Book hold returns confirmed status" "confirmed" "$HOLD_STATUS"
+
+UNAUTH_STATUS=$(curl -s -o /dev/null -w "%{http_code}" $BASE/v1/availability?agent_id=$AGENT_ID)
+check "Unauthenticated request returns 401" "401" "$UNAUTH_STATUS"
+
+echo ""
+echo "=== Results: $ERRORS failure(s) ==="
+exit $ERRORS

package/tests/unit/auth.test.ts

@@ -0,0 +1,114 @@
+import { beforeEach, describe, expect, jest, test } from '@jest/globals';
+import type { NextFunction, Response } from 'express';
+import { authMiddleware, type AuthenticatedRequest } from '../../src/middleware/auth';
+import pool from '../../src/db/client';
+import bcrypt from 'bcrypt';
+
+jest.mock('../../src/db/client', () => ({
+  __esModule: true,
+  default: {
+    query: jest.fn(),
+  },
+}));
+
+jest.mock('bcrypt', () => ({
+  __esModule: true,
+  default: {
+    compare: jest.fn(),
+  },
+}));
+
+const response = () => {
+  const res = {
+    status: jest.fn().mockReturnThis(),
+    json: jest.fn().mockReturnThis(),
+  };
+  return res as unknown as Response;
+};
+
+describe('authMiddleware', () => {
+  const validToken = `avs_live_${'a'.repeat(16)}_${'b'.repeat(64)}`;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test('returns 401 when Authorization header is missing', async () => {
+    const req = { header: jest.fn().mockReturnValue(undefined) } as unknown as AuthenticatedRequest;
+    const res = response();
+    const next = jest.fn() as unknown as NextFunction;
+
+    await authMiddleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({ error: 'missing_auth' });
+  });
+
+  test('returns 401 when prefix lookup misses but still runs dummy bcrypt compare', async () => {
+    jest.mocked(pool.query).mockResolvedValueOnce({ rows: [] } as never);
+    jest.mocked(bcrypt.compare).mockResolvedValueOnce(false as never);
+    const req = { header: jest.fn().mockReturnValue(`Bearer ${validToken}`) } as unknown as AuthenticatedRequest;
+    const res = response();
+    const next = jest.fn() as unknown as NextFunction;
+
+    await authMiddleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({ error: 'invalid_key' });
+    expect(String(jest.mocked(pool.query).mock.calls[0][0])).toContain('agents.api_key_prefix = $1');
+    expect(jest.mocked(pool.query).mock.calls[0][1]).toEqual(['a'.repeat(16)]);
+    expect(bcrypt.compare).toHaveBeenCalledTimes(1);
+  });
+
+  test('sets req.agent and req.org for a valid prefixed bearer token using one row lookup', async () => {
+    jest.mocked(pool.query).mockResolvedValueOnce({
+      rows: [
+        {
+          agent_id: 'agent-1',
+          agent_name: 'Sales Bot',
+          api_key_hash: 'hash',
+          agent_type: 'external_meeting',
+          priority: 10,
+          enforcement_mode: 'enforce',
+          last_seen_at: null,
+          mcp_last_seen_at: null,
+          mcp_client_name: null,
+          agent_created_at: new Date('2026-01-01T00:00:00Z'),
+          org_id: 'org-1',
+          org_name: 'Org',
+          plan: 'free',
+          agent_limit: 3,
+          org_created_at: new Date('2026-01-01T00:00:00Z'),
+        },
+      ],
+    } as never);
+    jest.mocked(bcrypt.compare).mockResolvedValueOnce(true as never);
+    const req = { header: jest.fn().mockReturnValue(`Bearer ${validToken}`) } as unknown as AuthenticatedRequest;
+    const res = response();
+    const next = jest.fn() as unknown as NextFunction;
+
+    await authMiddleware(req, res, next);
+
+    expect(req.agent.id).toBe('agent-1');
+    expect(req.org.id).toBe('org-1');
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(jest.mocked(pool.query)).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(pool.query).mock.calls[0][1]).toEqual(['a'.repeat(16)]);
+    expect(String(jest.mocked(pool.query).mock.calls[1][0])).toContain('last_seen_at');
+    expect(jest.mocked(pool.query).mock.calls[1][1]).toEqual(['agent-1']);
+    expect(bcrypt.compare).toHaveBeenCalledTimes(1);
+  });
+
+  test('invalid key format is rejected before database or bcrypt work', async () => {
+    const req = { header: jest.fn().mockReturnValue('Bearer avs_live_bad') } as unknown as AuthenticatedRequest;
+    const res = response();
+    const next = jest.fn() as unknown as NextFunction;
+
+    await authMiddleware(req, res, next);
+
+    expect(pool.query).not.toHaveBeenCalled();
+    expect(bcrypt.compare).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({ error: 'invalid_key' });
+  });
+});

package/tests/unit/availability.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, jest, test } from '@jest/globals';
+import { getAvailableSlots } from '../../src/core/availability';
+
+type Query = { rows: unknown[] };
+
+const mockClient = (results: Query[]) => {
+  let index = 0;
+  return {
+    query: jest.fn(async () => results[index++]),
+  };
+};
+
+const defaults = {
+  agent_id: 'agent-1',
+  buffer_minutes_after: 0,
+  buffer_minutes_before: 0,
+  focus_blocks: [],
+  priority_over_agents: [],
+  booking_window_days: 30,
+  allow_back_to_back: true,
+};
+
+const window = {
+  id: 'window-1',
+  agent_id: 'agent-1',
+  start_at: new Date('2026-05-12T09:00:00Z'),
+  end_at: new Date('2026-05-12T10:00:00Z'),
+  window_type: 'available',
+  recurrence: null,
+};
+
+const params = {
+  agent_id: 'agent-1',
+  org_id: 'org-1',
+  from: new Date('2026-05-12T09:00:00Z'),
+  to: new Date('2026-05-12T10:00:00Z'),
+  duration_minutes: 30,
+};
+
+describe('getAvailableSlots', () => {
+  test('returns slots inside an availability window', async () => {
+    const client = mockClient([
+      { rows: [window] },
+      { rows: [defaults] },
+      { rows: [] },
+    ]);
+
+    const slots = await getAvailableSlots(params, client as never);
+
+    expect(slots.map((slot) => slot.start.toISOString())).toEqual([
+      '2026-05-12T09:00:00.000Z',
+      '2026-05-12T09:30:00.000Z',
+    ]);
+  });
+
+  test('filters slots overlapping a hold', async () => {
+    const client = mockClient([
+      { rows: [window] },
+      { rows: [defaults] },
+      {
+        rows: [
+          {
+            agent_id: 'agent-1',
+            start_at: new Date('2026-05-12T09:30:00Z'),
+            end_at: new Date('2026-05-12T10:00:00Z'),
+          },
+        ],
+      },
+    ]);
+
+    const slots = await getAvailableSlots(params, client as never);
+
+    expect(slots).toHaveLength(1);
+    expect(slots[0].start.toISOString()).toBe('2026-05-12T09:00:00.000Z');
+  });
+
+  test('buffer time removes slots near holds', async () => {
+    const client = mockClient([
+      { rows: [window] },
+      { rows: [{ ...defaults, buffer_minutes_after: 15 }] },
+      {
+        rows: [
+          {
+            agent_id: 'agent-1',
+            start_at: new Date('2026-05-12T09:00:00Z'),
+            end_at: new Date('2026-05-12T09:30:00Z'),
+          },
+        ],
+      },
+    ]);
+
+    const slots = await getAvailableSlots(params, client as never);
+
+    expect(slots).toHaveLength(0);
+  });
+
+  test('focus block removes overlapping slots', async () => {
+    const client = mockClient([
+      { rows: [window] },
+      {
+        rows: [
+          {
+            ...defaults,
+            focus_blocks: [{ weekday: 2, start_time: '09:00', end_time: '09:45' }],
+          },
+        ],
+      },
+      { rows: [] },
+    ]);
+
+    const slots = await getAvailableSlots(params, client as never);
+
+    expect(slots).toHaveLength(0);
+  });
+
+  test('calculates confidence from nearby competing holds', async () => {
+    const client = mockClient([
+      { rows: [window] },
+      { rows: [defaults] },
+      {
+        rows: [
+          {
+            agent_id: 'agent-2',
+            start_at: new Date('2026-05-12T10:00:00Z'),
+            end_at: new Date('2026-05-12T10:30:00Z'),
+          },
+        ],
+      },
+    ]);
+
+    const slots = await getAvailableSlots(
+      { ...params, include_competing_agents: true },
+      client as never,
+    );
+
+    expect(slots[1]).toMatchObject({
+      confidence: 0.85,
+      competing_holds_count: 1,
+    });
+  });
+
+  test('returns an empty list when no slots are available', async () => {
+    const client = mockClient([{ rows: [] }, { rows: [defaults] }, { rows: [] }]);
+
+    const slots = await getAvailableSlots(params, client as never);
+
+    expect(slots).toEqual([]);
+  });
+});

package/tests/unit/conflict.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from '@jest/globals';
+import { determineWinner } from '../../src/core/conflict';
+import type { Agent, AgentPreferences, Hold } from '../../src/types';
+
+const hold = (id: string, agentId: string, createdAt: string): Hold => ({
+  id,
+  agent_id: agentId,
+  org_id: 'org-1',
+  start_at: new Date('2026-05-12T10:00:00Z'),
+  end_at: new Date('2026-05-12T11:00:00Z'),
+  status: 'confirmed',
+  created_at: new Date(createdAt),
+});
+
+const agent = (
+  id: string,
+  agent_type: Agent['agent_type'],
+  priority = 0,
+): Agent => ({
+  id,
+  org_id: 'org-1',
+  name: id,
+  api_key_hash: 'hash',
+  agent_type,
+  priority,
+  enforcement_mode: 'enforce',
+  created_at: new Date('2026-01-01T00:00:00Z'),
+});
+
+const prefs = (
+  agentId: string,
+  priorityOverAgents: string[] = [],
+): AgentPreferences => ({
+  agent_id: agentId,
+  buffer_minutes_after: 15,
+  buffer_minutes_before: 0,
+  focus_blocks: [],
+  priority_over_agents: priorityOverAgents,
+  booking_window_days: 30,
+  allow_back_to_back: false,
+});
+
+describe('determineWinner', () => {
+  test('agent_type hierarchy decides when there is no explicit priority override', () => {
+    const external = agent('external', 'external_meeting');
+    const generic = agent('generic', 'generic', 10);
+
+    const winner = determineWinner(
+      hold('hold-a', external.id, '2026-05-01T10:00:00Z'),
+      external,
+      hold('hold-b', generic.id, '2026-05-01T09:00:00Z'),
+      generic,
+      [prefs(external.id), prefs(generic.id)],
+    );
+
+    expect(winner.id).toBe('hold-a');
+  });
+
+  test('external_meeting wins over internal', () => {
+    const external = agent('external', 'external_meeting');
+    const internal = agent('internal', 'internal');
+
+    const winner = determineWinner(
+      hold('hold-a', internal.id, '2026-05-01T09:00:00Z'),
+      internal,
+      hold('hold-b', external.id, '2026-05-01T10:00:00Z'),
+      external,
+      [prefs(internal.id), prefs(external.id)],
+    );
+
+    expect(winner.id).toBe('hold-b');
+  });
+
+  test('priority field decides when agent_type is tied', () => {
+    const low = agent('low', 'internal', 1);
+    const high = agent('high', 'internal', 5);
+
+    const winner = determineWinner(
+      hold('hold-a', low.id, '2026-05-01T09:00:00Z'),
+      low,
+      hold('hold-b', high.id, '2026-05-01T10:00:00Z'),
+      high,
+      [prefs(low.id), prefs(high.id)],
+    );
+
+    expect(winner.id).toBe('hold-b');
+  });
+
+  test('oldest hold wins a complete tie', () => {
+    const first = agent('first', 'internal', 1);
+    const second = agent('second', 'internal', 1);
+
+    const winner = determineWinner(
+      hold('hold-a', first.id, '2026-05-01T09:00:00Z'),
+      first,
+      hold('hold-b', second.id, '2026-05-01T10:00:00Z'),
+      second,
+      [prefs(first.id), prefs(second.id)],
+    );
+
+    expect(winner.id).toBe('hold-a');
+  });
+
+  test('explicit priority_over_agents overrides all other rules', () => {
+    const generic = agent('generic', 'generic', 0);
+    const external = agent('external', 'external_meeting', 100);
+
+    const winner = determineWinner(
+      hold('hold-a', generic.id, '2026-05-01T10:00:00Z'),
+      generic,
+      hold('hold-b', external.id, '2026-05-01T09:00:00Z'),
+      external,
+      [prefs(generic.id, [external.id]), prefs(external.id)],
+    );
+
+    expect(winner.id).toBe('hold-a');
+  });
+});

package/tests/unit/env.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test, beforeEach, afterEach } from '@jest/globals';
+import { envReadiness, requiredEnvNames, stripeReadiness } from '../../src/lib/env';
+
+describe('environment readiness', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  test('production env requires deploy configuration but not billing when upgrades are disabled', () => {
+    delete process.env.BILLING_UPGRADES_ENABLED;
+    const names = requiredEnvNames(true);
+
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'DATABASE_URL',
+        'SESSION_SECRET',
+        'API_KEY_SALT_ROUNDS',
+        'APP_URL',
+        'CORS_ORIGINS',
+        'ADMIN_EMAILS',
+      ]),
+    );
+    expect(names).not.toEqual(expect.arrayContaining(['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET']));
+    expect(names).not.toContain('PORT');
+  });
+
+  test('production env requires Stripe configuration when billing upgrades are enabled', () => {
+    process.env.BILLING_UPGRADES_ENABLED = 'true';
+    const names = requiredEnvNames(true);
+
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'STRIPE_SECRET_KEY',
+        'STRIPE_WEBHOOK_SECRET',
+        'STRIPE_PRICE_INDIVIDUAL',
+        'STRIPE_PRICE_TEAM',
+      ]),
+    );
+  });
+
+  test('readiness reports missing env names without values', () => {
+    delete process.env.DATABASE_URL;
+    process.env.SESSION_SECRET = 'secret-value';
+    process.env.API_KEY_SALT_ROUNDS = '10';
+
+    const readiness = envReadiness(false);
+
+    expect(readiness.ok).toBe(false);
+    expect(readiness.missing).toContain('DATABASE_URL');
+    expect(JSON.stringify(readiness)).not.toContain('secret-value');
+  });
+
+  test('stripe readiness only reports configured booleans', () => {
+    process.env.STRIPE_SECRET_KEY = 'sk_test_hidden';
+    delete process.env.STRIPE_WEBHOOK_SECRET;
+
+    expect(stripeReadiness()).toMatchObject({
+      configured: true,
+      webhook_configured: false,
+    });
+    expect(JSON.stringify(stripeReadiness())).not.toContain('sk_test_hidden');
+  });
+});

package/tests/unit/migrations.test.ts

@@ -0,0 +1,135 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, test } from '@jest/globals';
+import type { Pool, PoolClient } from 'pg';
+import { runMigrations } from '../../src/db/migrations';
+
+type MigrationRecord = {
+  filename: string;
+  checksum: string;
+  status: 'running' | 'applied' | 'failed';
+  error_message: string | null;
+};
+
+function tempMigrationsDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'availsync-migrations-'));
+}
+
+function createMockDb() {
+  const records = new Map<string, MigrationRecord>();
+  const executedSql: string[] = [];
+  const queries: string[] = [];
+
+  const client = {
+    query: jest.fn(async (sql: string, params: unknown[] = []) => {
+      const text = String(sql);
+      queries.push(text);
+
+      if (text.includes('SELECT pg_advisory_lock') || text.includes('SELECT pg_advisory_unlock')) {
+        return { rows: [] };
+      }
+
+      if (text.includes('CREATE TABLE IF NOT EXISTS schema_migrations')) {
+        return { rows: [] };
+      }
+
+      if (text.includes('FROM schema_migrations') && text.includes('WHERE filename = $1')) {
+        const record = records.get(params[0] as string);
+        return { rows: record ? [record] : [] };
+      }
+
+      if (text.includes('INSERT INTO schema_migrations')) {
+        records.set(params[0] as string, {
+          filename: params[0] as string,
+          checksum: params[1] as string,
+          status: 'running',
+          error_message: null,
+        });
+        return { rows: [] };
+      }
+
+      if (text.includes("SET status = 'applied'")) {
+        const filename = params[0] as string;
+        const record = records.get(filename);
+        if (record) {
+          record.status = 'applied';
+          record.error_message = null;
+        }
+        return { rows: [] };
+      }
+
+      if (text.includes("SET status = 'failed'")) {
+        const filename = params[0] as string;
+        const record = records.get(filename);
+        if (record) {
+          record.status = 'failed';
+          record.error_message = params[1] as string;
+        }
+        return { rows: [] };
+      }
+
+      if (text === 'BEGIN' || text === 'COMMIT' || text === 'ROLLBACK') {
+        return { rows: [] };
+      }
+
+      if (text.includes('BROKEN')) {
+        throw new Error('syntax error at or near "BROKEN"');
+      }
+
+      executedSql.push(text);
+      return { rows: [] };
+    }),
+    release: jest.fn(),
+  } as unknown as PoolClient;
+
+  return {
+    db: {
+      connect: jest.fn(async () => client),
+    } as unknown as Pool,
+    client,
+    records,
+    executedSql,
+    queries,
+  };
+}
+
+describe('migration runner', () => {
+  const dirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of dirs.splice(0)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('records successful migrations once and skips them on the second run', async () => {
+    const dir = tempMigrationsDir();
+    dirs.push(dir);
+    fs.writeFileSync(path.join(dir, '001_demo.sql'), 'CREATE TABLE demo (id int);');
+    const { db, records, executedSql, queries } = createMockDb();
+
+    await runMigrations(db, dir);
+    await runMigrations(db, dir);
+
+    expect(records.get('001_demo.sql')?.status).toBe('applied');
+    expect(executedSql).toEqual(['CREATE TABLE demo (id int);']);
+    expect(queries.filter((query) => query.includes('SELECT pg_advisory_lock'))).toHaveLength(2);
+    expect(queries.filter((query) => query.includes('SELECT pg_advisory_unlock'))).toHaveLength(2);
+  });
+
+  test('records failed migrations and throws a clear filename-specific error', async () => {
+    const dir = tempMigrationsDir();
+    dirs.push(dir);
+    fs.writeFileSync(path.join(dir, '001_broken.sql'), 'BROKEN');
+    const { db, records } = createMockDb();
+
+    await expect(runMigrations(db, dir)).rejects.toThrow(
+      'Migration failed in 001_broken.sql: syntax error at or near "BROKEN"',
+    );
+    expect(records.get('001_broken.sql')).toMatchObject({
+      status: 'failed',
+      error_message: 'syntax error at or near "BROKEN"',
+    });
+  });
+});

package/tests/unit/request-id.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from '@jest/globals';
+import type { Request, Response } from 'express';
+import { requestIdMiddleware, REQUEST_ID_HEADER } from '../../src/middleware/requestId';
+
+describe('request id middleware', () => {
+  test('sets a response header and local request id', () => {
+    const req = {
+      header: () => undefined,
+    } as unknown as Request;
+    const res = {
+      locals: {},
+      setHeader: jest.fn(),
+    } as unknown as Response;
+    const next = jest.fn();
+
+    requestIdMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+    expect(res.locals.requestId).toEqual(expect.any(String));
+    expect(res.setHeader).toHaveBeenCalledWith(REQUEST_ID_HEADER, res.locals.requestId);
+  });
+
+  test('accepts a bounded incoming request id', () => {
+    const req = {
+      header: () => 'external-request-id',
+    } as unknown as Request;
+    const res = {
+      locals: {},
+      setHeader: jest.fn(),
+    } as unknown as Response;
+
+    requestIdMiddleware(req, res, jest.fn());
+
+    expect(res.locals.requestId).toBe('external-request-id');
+    expect(res.setHeader).toHaveBeenCalledWith(REQUEST_ID_HEADER, 'external-request-id');
+  });
+});