verify-phone-sms 0.9.76 → 0.9.77

package/README.md

@@ -252,7 +252,9 @@ X-API-Key: your_api_key
 
 ## API Documentation
 
-Visit `/docs` to see the interactive OpenAPI documentation.
+Visit `/docs` for the interactive Swagger UI, or `/openapi.json` for the
+OpenAPI 3.0 spec it renders. Both, along with `/` and `/health`, are
+unauthenticated.
 
 ## Authentication
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verify-phone-sms",
-  "version": "0.9.76",
+  "version": "0.9.77",
   "description": "SMS Phone Verification API using AWS SNS HTTP API with Hono server on Cloudflare Workers",
   "main": "src/verify-phone.ts",
   "type": "module",
@@ -31,7 +31,8 @@
     "test": "vitest run",
     "test:run": "vitest run",
     "test:ui": "vitest --ui",
-    "test:ci": "vitest run --reporter=default --reporter=junit --outputFile=junit.xml"
+    "test:ci": "vitest run --reporter=default --reporter=junit --outputFile=junit.xml --coverage --coverage.reporter=lcov --coverage.reporter=text",
+    "coverage": "vitest run --coverage"
   },
   "keywords": [
     "sms",
@@ -49,7 +50,7 @@
   "license": "MIT",
   "dependencies": {
     "@hono/swagger-ui": "^0.5.2",
-    "@hono/zod-openapi": "^0.19.9",
+    "@hono/zod-openapi": "^1.6.3",
     "grab-api.js": "^0.9.131",
     "hono": "^4.0.0",
     "hono-rate-limiter": "^0.2.2",

package/src/verify-phone-server.ts

@@ -95,6 +95,7 @@ app.get("/", (c) => {
       send: "/api/send",
       verify: "/api/verify",
       docs: "/docs",
+      openapi: "/openapi.json",
     },
   });
 });
@@ -109,6 +110,11 @@ app.get("/health", (c) => {
   });
 });
 
+// Apply authentication to all API routes. This must be registered before the
+// `/api/*` handlers below: Hono runs middleware only for routes defined after
+// it, so registering this at the bottom of the file left every endpoint open.
+app.use("/api/*", authenticateApiKey);
+
 // Generate verification code
 function generateCode(length = 6) {
   const chars = "0123456789";
@@ -446,7 +452,7 @@ app.openAPIRegistry.registerComponent("securitySchemes", "apiKey", {
   in: "header",
 });
 
-app.doc("/docs", {
+app.doc("/openapi.json", {
   openapi: "3.0.0",
   info: {
     title: "SMS Verification API",
@@ -466,10 +472,7 @@ app.doc("/docs", {
 });
 
 // Swagger UI
-app.get("/docs", swaggerUI({ url: "/docs" }));
-
-// Apply authentication to all API routes
-app.use("/api/*", authenticateApiKey);
+app.get("/docs", swaggerUI({ url: "/openapi.json" }));
 
 // Error handling
 app.onError((err, c) => {

package/test/api.test.ts

@@ -1,5 +1,13 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+/**
+ * Endpoint-level tests for the routes `src/verify-phone-server.ts` serves:
+ * `/`, `/health`, `POST /api/send`, `POST /api/verify`, `POST /api/sms`, and
+ * the documentation pair `/docs` (Swagger UI) and `/openapi.json` (the spec).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { vi } from 'vitest';
 import { createApp } from '../src/verify-phone-server';
+import { apiRequest, stubNetwork, TEST_API_KEY, TEST_MESSAGE_ID } from './helpers';
 
 declare global {
   // eslint-disable-next-line no-var
@@ -11,195 +19,209 @@ describe('SMS Verification API', () => {
 
   beforeEach(() => {
     app = createApp(globalThis.env);
+    stubNetwork();
   });
 
-  describe('Health Check', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe('Service endpoints', () => {
+    it('should describe the API on the root endpoint', async () => {
+      const res = await app.request('http://localhost/', {}, globalThis.env);
+      const data: any = await res.json();
+
+      expect(res.status).toBe(200);
+      expect(data).toMatchObject({
+        success: true,
+        message: 'SMS Verification API',
+      });
+      expect(data.endpoints).toMatchObject({
+        health: '/health',
+        send: '/api/send',
+        verify: '/api/verify',
+        docs: '/docs',
+        openapi: '/openapi.json',
+      });
+    });
+
     it('should return health status', async () => {
-      const req = new Request('http://localhost/health');
-      const res = await app.request(req, globalThis.env);
+      const res = await app.request('http://localhost/health', {}, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
       expect(data).toMatchObject({
-        status: 'ok'
+        success: true,
+        status: 'healthy',
       });
       expect(data.timestamp).toBeDefined();
     });
+
+    it('should not require an API key for the public endpoints', async () => {
+      for (const path of ['/', '/health', '/docs', '/openapi.json']) {
+        const res = await app.request(`http://localhost${path}`, {}, globalThis.env);
+        expect(res.status, `${path} should be public`).toBe(200);
+      }
+    });
   });
 
   describe('Send Verification Code', () => {
     it('should require API key authentication', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=%2B1234567890');
-      const res = await app.request(req, globalThis.env);
+      const req = apiRequest('/api/send', { phoneNumber: '+12025550123' }, {});
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(401);
       expect(data).toMatchObject({
-        error: 'API key required'
+        success: false,
+        error: 'Unauthorized',
+        message: 'Invalid or missing API key',
       });
     });
 
     it('should reject invalid API key', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=%2B1234567890', {
-        headers: {
-          'X-API-Key': 'invalid-key'
-        }
+      const req = apiRequest('/api/send', { phoneNumber: '+12025550123' }, {
+        'X-API-Key': 'wrong-key',
       });
-      const res = await app.request(req, globalThis.env);
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(401);
-      expect(data).toMatchObject({
-        error: 'Invalid API key'
-      });
+      expect(data).toMatchObject({ success: false, error: 'Unauthorized' });
     });
 
     it('should accept Bearer token authentication', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=%2B1234567890', {
-        headers: {
-          'Authorization': 'Bearer test-api-key'
-        }
+      const req = apiRequest('/api/send', { phoneNumber: '+12025550123' }, {
+        Authorization: `Bearer ${TEST_API_KEY}`,
       });
-      const res = await app.request(req, globalThis.env);
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
       expect(data.success).toBe(true);
+      expect(data.messageId).toBe(TEST_MESSAGE_ID);
     });
 
     it('should reject invalid phone number format', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=invalid-phone', {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+      const req = apiRequest('/api/send', { phoneNumber: 'invalid-phone' });
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(400);
-      expect(data).toMatchObject({
-        error: 'Invalid phone number format'
-      });
+      expect(data.success).toBe(false);
+      expect(data.error).toContain('Invalid phone number format');
     });
 
-    it('should format phone number correctly', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=1234567890', {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+    it('should format a 10-digit phone number to E.164', async () => {
+      const req = apiRequest('/api/send', { phoneNumber: '2025550123' });
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
       expect(data.success).toBe(true);
+      expect(data.phoneNumber).toBe('+12025550123');
     });
 
-    it('should accept blockVoip parameter', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=%2B1234567890&blockVoip=true', {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+    it('should return the generated code and its expiry', async () => {
+      const req = apiRequest('/api/send', { phoneNumber: '+12025550123' });
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
-      expect(data.success).toBe(true);
+      expect(data.code).toMatch(/^\d{6}$/);
+      expect(data.expiresIn).toBe(600);
     });
 
-    it('should handle blockVoip=false parameter', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=%2B1234567890&blockVoip=false', {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+    it('should send the caller-supplied code', async () => {
+      const req = apiRequest('/api/send', { phoneNumber: '+12025550123', code: '424242' });
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
-      expect(data.success).toBe(true);
+      expect(data.code).toBe('424242');
     });
   });
 
   describe('Verify Code', () => {
     it('should require API key authentication', async () => {
-      const req = new Request('http://localhost/api/verify-code?phoneNumber=%2B1234567890&code=123456');
-      const res = await app.request(req, globalThis.env);
+      const req = apiRequest('/api/verify', { phoneNumber: '+12025550123', code: '123456' }, {});
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(401);
-      expect(data).toMatchObject({
-        error: 'API key required'
-      });
+      expect(data).toMatchObject({ success: false, error: 'Unauthorized' });
     });
 
     it('should reject invalid API key', async () => {
-      const req = new Request('http://localhost/api/verify-code?phoneNumber=%2B1234567890&code=123456', {
-        headers: {
-          'X-API-Key': 'invalid-key'
-        }
+      const req = apiRequest('/api/verify', { phoneNumber: '+12025550123', code: '123456' }, {
+        'X-API-Key': 'wrong-key',
       });
-      const res = await app.request(req, globalThis.env);
-      const data: any = await res.json();
+      const res = await app.request(req, undefined, globalThis.env);
 
       expect(res.status).toBe(401);
-      expect(data).toMatchObject({
-        error: 'Invalid API key'
-      });
     });
 
-    it('should reject invalid phone number format', async () => {
-      const req = new Request('http://localhost/api/verify-code?phoneNumber=invalid-phone&code=123456', {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
+    it('should accept Bearer token authentication', async () => {
+      const req = apiRequest('/api/verify', { phoneNumber: '+12025550123', code: '123456' }, {
+        Authorization: `Bearer ${TEST_API_KEY}`,
       });
-      const res = await app.request(req, globalThis.env);
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
-      expect(res.status).toBe(400);
-      expect(data).toMatchObject({
-        error: 'Invalid phone number format'
-      });
+      expect(res.status).toBe(200);
+      expect(data).toMatchObject({ success: true, verified: true });
     });
+  });
 
-    it('should accept Bearer token authentication', async () => {
-      const req = new Request('http://localhost/api/verify-code?phoneNumber=%2B1234567890&code=123456', {
-        headers: {
-          'Authorization': 'Bearer test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+  describe('General SMS', () => {
+    it('should require API key authentication', async () => {
+      const req = apiRequest('/api/sms', { phoneNumber: '+12025550123', message: 'hello' }, {});
+      const res = await app.request(req, undefined, globalThis.env);
+
+      expect(res.status).toBe(401);
+    });
+
+    it('should send a custom message', async () => {
+      const req = apiRequest('/api/sms', { phoneNumber: '+12025550123', message: 'hello' });
+      const res = await app.request(req, undefined, globalThis.env);
       const data: any = await res.json();
 
-      expect(res.status).toBe(400); // Will fail because no code was sent, but auth works
-      expect(data.error).toBeDefined();
+      expect(res.status).toBe(200);
+      expect(data).toMatchObject({
+        success: true,
+        message: 'SMS sent successfully',
+        messageId: TEST_MESSAGE_ID,
+      });
     });
   });
 
   describe('Documentation Endpoints', () => {
-    it('should serve OpenAPI documentation', async () => {
-      const req = new Request('http://localhost/openapi.json');
-      const res = await app.request(req, globalThis.env);
+    it('should serve the OpenAPI spec as JSON', async () => {
+      const res = await app.request('http://localhost/openapi.json', {}, globalThis.env);
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
-      expect(data).toMatchObject({
-        openapi: '3.0.0',
-        info: {
-          title: 'SMS API',
-          version: '1.0.0'
-        }
-      });
+      expect(data).toMatchObject({ openapi: '3.0.0' });
+      expect(data.info.title).toBe('SMS Verification API');
+      expect(data.paths['/api/send']).toBeDefined();
     });
 
-    it('should serve Swagger UI', async () => {
-      const req = new Request('http://localhost/');
-      const res = await app.request(req, globalThis.env);
+    it('should serve Swagger UI as HTML', async () => {
+      const res = await app.request('http://localhost/docs', {}, globalThis.env);
 
       expect(res.status).toBe(200);
       expect(res.headers.get('content-type')).toContain('text/html');
+      expect(await res.text()).toContain('/openapi.json');
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should return a JSON 404 for unknown endpoints', async () => {
+      const res = await app.request('http://localhost/nonexistent', {}, globalThis.env);
+      const data: any = await res.json();
+
+      expect(res.status).toBe(404);
+      expect(data).toMatchObject({ success: false, error: 'Not found' });
     });
   });
-}); 
+});

package/test/helpers.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared test helpers.
+ *
+ * Both outbound calls this package makes — the AWS SNS `Publish` request and
+ * the sent.dm phone lookup — go through `fetch`. Stubbing `fetch` keeps the
+ * suite offline and deterministic; without it the VoIP tests hit a public API
+ * that rate-limits (HTTP 429) and the send tests hit SNS with fake credentials.
+ */
+
+import { vi } from 'vitest';
+
+export const TEST_API_KEY = 'test-api-key';
+export const TEST_MESSAGE_ID = 'test-message-id-0001';
+
+/** The subset of an SNS `Publish` response that `parseXMLResponse` reads. */
+const snsPublishOk = `<?xml version="1.0"?>
+<PublishResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
+  <PublishResult><MessageId>${TEST_MESSAGE_ID}</MessageId></PublishResult>
+</PublishResponse>`;
+
+export interface NetworkStubOptions {
+  /** What the phone lookup should report the number as. */
+  lookup?: 'voip' | 'cellular' | 'landline' | 'none';
+  /** Make the phone lookup fail with this status instead of answering. */
+  lookupStatus?: number;
+}
+
+/**
+ * Replace `globalThis.fetch` for the duration of a test. Any URL the package
+ * is not expected to call fails the test rather than escaping to the network.
+ */
+export function stubNetwork(options: NetworkStubOptions = {}) {
+  const { lookup = 'cellular', lookupStatus } = options;
+
+  const lookupBodies = {
+    voip: { carrier: { name: 'Bandwidth', type: 'voip' }, portability: { line_type: 'landline' } },
+    cellular: { carrier: { name: 'Verizon Wireless', type: 'cellular' }, portability: { line_type: 'landline' } },
+    landline: { carrier: { name: 'AT&T', type: 'landline' }, portability: { line_type: 'landline' } },
+    none: null,
+  } as const;
+
+  const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+
+    if (url.includes('amazonaws.com')) {
+      return new Response(snsPublishOk, {
+        status: 200,
+        headers: { 'Content-Type': 'text/xml' },
+      });
+    }
+
+    if (url.includes('sent.dm/api/phone-lookup')) {
+      if (lookupStatus) {
+        return new Response('rate limited', { status: lookupStatus });
+      }
+      return new Response(JSON.stringify(lookupBodies[lookup]), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    throw new Error(`Unexpected network call in tests: ${url}`);
+  });
+
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+/** Build a JSON POST request carrying the given auth headers. */
+export function apiRequest(
+  path: string,
+  body: unknown,
+  headers: Record<string, string> = { 'X-API-Key': TEST_API_KEY },
+) {
+  return new Request(`http://localhost${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify(body),
+  });
+}

package/test/integration.test.ts

@@ -1,152 +1,151 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+/**
+ * Cross-cutting behaviour: the two accepted authentication schemes, and the
+ * phone-number formatting `verifyPhone` applies before handing off to SNS.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createApp } from '../src/verify-phone-server';
+import { apiRequest, stubNetwork, TEST_API_KEY } from './helpers';
 
 describe('SMS Verification API Integration Tests', () => {
   let app: ReturnType<typeof createApp>;
 
   beforeEach(() => {
     app = createApp(globalThis.env);
+    stubNetwork();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
   });
 
   describe('Authentication Methods', () => {
     it('should accept both X-API-Key and Bearer token headers', async () => {
-      const phoneNumber = '+1234567890';
-
-      // Test X-API-Key header
-      const req1 = new Request(`http://localhost/api/send-verification?phoneNumber=${encodeURIComponent(phoneNumber)}`, {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res1 = await app.request(req1, globalThis.env);
-      const data1: any = await res1.json();
-
-      expect(res1.status).toBe(200);
-      expect(data1.success).toBe(true);
-
-      // Test Bearer token header
-      const req2 = new Request(`http://localhost/api/send-verification?phoneNumber=${encodeURIComponent(phoneNumber)}`, {
-        headers: {
-          'Authorization': 'Bearer test-api-key'
-        }
-      });
-      const res2 = await app.request(req2, globalThis.env);
-      const data2: any = await res2.json();
-
-      expect(res2.status).toBe(200);
-      expect(data2.success).toBe(true);
+      const body = { phoneNumber: '+12025550123' };
+
+      const viaHeader = await app.request(
+        apiRequest('/api/send', body, { 'X-API-Key': TEST_API_KEY }),
+        undefined,
+        globalThis.env,
+      );
+      expect(viaHeader.status).toBe(200);
+      expect(((await viaHeader.json()) as any).success).toBe(true);
+
+      const viaBearer = await app.request(
+        apiRequest('/api/send', body, { Authorization: `Bearer ${TEST_API_KEY}` }),
+        undefined,
+        globalThis.env,
+      );
+      expect(viaBearer.status).toBe(200);
+      expect(((await viaBearer.json()) as any).success).toBe(true);
     });
 
     it('should reject requests without authentication', async () => {
-      const phoneNumber = '+1234567890';
-
-      const req = new Request(`http://localhost/api/send-verification?phoneNumber=${encodeURIComponent(phoneNumber)}`);
-      const res = await app.request(req, globalThis.env);
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123' }, {}),
+        undefined,
+        globalThis.env,
+      );
       const data: any = await res.json();
 
       expect(res.status).toBe(401);
-      expect(data.error).toBe('API key required');
+      expect(data.error).toBe('Unauthorized');
+      expect(data.message).toBe('Invalid or missing API key');
     });
 
     it('should reject requests with invalid authentication', async () => {
-      const phoneNumber = '+1234567890';
-
-      const req = new Request(`http://localhost/api/send-verification?phoneNumber=${encodeURIComponent(phoneNumber)}`, {
-        headers: {
-          'X-API-Key': 'invalid-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123' }, { 'X-API-Key': 'not-the-key' }),
+        undefined,
+        globalThis.env,
+      );
       const data: any = await res.json();
 
       expect(res.status).toBe(401);
-      expect(data.error).toBe('Invalid API key');
+      expect(data.error).toBe('Unauthorized');
+    });
+
+    it('should not reach the SMS provider when authentication fails', async () => {
+      const fetchMock = stubNetwork();
+
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123' }, {}),
+        undefined,
+        globalThis.env,
+      );
+
+      expect(res.status).toBe(401);
+      expect(fetchMock).not.toHaveBeenCalled();
     });
   });
 
   describe('Phone Number Formatting', () => {
     it('should format various phone number formats correctly', async () => {
-      const testCases = [
-        '1234567890',
-        '11234567890',
-        '+1234567890',
-        '(123) 456-7890',
-        '123-456-7890',
+      const cases: [string, string][] = [
+        ['2025550123', '+12025550123'],
+        ['12025550123', '+12025550123'],
+        ['+12025550123', '+12025550123'],
+        ['(202) 555-0123', '+12025550123'],
+        ['202-555-0123', '+12025550123'],
       ];
 
-      for (const phoneNumber of testCases) {
-        const req = new Request(`http://localhost/api/send-verification?phoneNumber=${encodeURIComponent(phoneNumber)}`, {
-          headers: {
-            'X-API-Key': 'test-api-key'
-          }
-        });
-        const res = await app.request(req, globalThis.env);
+      for (const [input, expected] of cases) {
+        const res = await app.request(
+          apiRequest('/api/send', { phoneNumber: input }),
+          undefined,
+          globalThis.env,
+        );
         const data: any = await res.json();
 
-        expect(res.status).toBe(200);
+        expect(res.status, `${input} should be accepted`).toBe(200);
         expect(data.success).toBe(true);
+        expect(data.phoneNumber, `${input} should normalise`).toBe(expected);
       }
     });
 
     it('should reject clearly invalid phone numbers', async () => {
-      const invalidNumbers = [
-        'not-a-number',
-        '123',
-        '12345678901234567890', // Too long
-        '+', // Just plus sign
-        'abc123def',
-      ];
-
-      for (const invalidNumber of invalidNumbers) {
-        const req = new Request(`http://localhost/api/send-verification?phoneNumber=${encodeURIComponent(invalidNumber)}`, {
-          headers: {
-            'X-API-Key': 'test-api-key'
-          }
-        });
-        const res = await app.request(req, globalThis.env);
+      for (const input of ['not-a-number', '123', 'abc-def-ghij', '']) {
+        const res = await app.request(
+          apiRequest('/api/send', { phoneNumber: input }),
+          undefined,
+          globalThis.env,
+        );
         const data: any = await res.json();
 
-        expect(res.status).toBe(400);
-        expect(data.error).toBe('Invalid phone number format');
+        expect(res.status, `${input} should be rejected`).toBe(400);
+        expect(data.success).toBe(false);
+        expect(data.error).toBeDefined();
       }
     });
   });
 
   describe('API Endpoints', () => {
-    it('should handle send verification endpoint', async () => {
-      const phoneNumber = '+1234567890';
-
-      const req = new Request(`http://localhost/api/send-verification?phoneNumber=${encodeURIComponent(phoneNumber)}`, {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+    it('should handle the send verification endpoint', async () => {
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123' }),
+        undefined,
+        globalThis.env,
+      );
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
       expect(data).toMatchObject({
         success: true,
         message: 'Verification code sent successfully',
-        expiresIn: 600
+        phoneNumber: '+12025550123',
       });
-      expect(data.messageId).toBeDefined();
     });
 
-    it('should handle verify code endpoint', async () => {
-      const phoneNumber = '+1234567890';
-      const code = '123456';
-
-      const req = new Request(`http://localhost/api/verify-code?phoneNumber=${encodeURIComponent(phoneNumber)}&code=${code}`, {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+    it('should handle the verify code endpoint', async () => {
+      const res = await app.request(
+        apiRequest('/api/verify', { phoneNumber: '+12025550123', code: '123456' }),
+        undefined,
+        globalThis.env,
+      );
       const data: any = await res.json();
 
-      expect(res.status).toBe(400); // Will fail because no code was sent, but endpoint works
-      expect(data.error).toBeDefined();
+      expect(res.status).toBe(200);
+      expect(data).toMatchObject({ success: true, verified: true });
     });
   });
-}); 
+});

package/test/server.test.ts

@@ -1,143 +1,115 @@
-/**
- * Test file for the SMS Verification API server
- */
-
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { Hono } from 'hono';
-import app from '../src/verify-phone-server.js';
-
-describe('SMS Verification API Server', () => {
-  let server;
-
-  beforeAll(() => {
-    server = new Hono();
-    server.route('/', app);
-  });
-
-  afterAll(() => {
-    // Cleanup if needed
-  });
-
-  describe('Health Check Endpoints', () => {
-    it('should return API info on root endpoint', async () => {
-      const res = await server.request('/');
-      const data: any = await res.json();
-      
-      expect(res.status).toBe(200);
-      expect(data.success).toBe(true);
-      expect(data.message).toBe('SMS Verification API');
-      expect(data.endpoints).toBeDefined();
-    });
-
-    it('should return health status', async () => {
-      const res = await server.request('/health');
-      const data: any = await res.json();
-      
-      expect(res.status).toBe(200);
-      expect(data.success).toBe(true);
-      expect(data.status).toBe('healthy');
-      expect(data.timestamp).toBeDefined();
-    });
-  });
-
-  describe('API Authentication', () => {
-    it('should require API key for protected endpoints', async () => {
-      const res = await server.request('/api/send', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({
-          phoneNumber: '+1234567890'
-        })
-      });
-      
-      expect(res.status).toBe(401);
-    });
-
-    it('should accept valid API key', async () => {
-      const res = await server.request('/api/send', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': 'sms_1234567890abcdef1234567890abcdef'
-        },
-        body: JSON.stringify({
-          phoneNumber: '+1234567890'
-        })
-      });
-      
-      // Should not be 401 (unauthorized) - might be 500 due to missing AWS credentials
-      expect(res.status).not.toBe(401);
-    });
-  });
-
-  describe('Documentation', () => {
-    it('should serve OpenAPI documentation', async () => {
-      const res = await server.request('/docs');
-      expect(res.status).toBe(200);
-    });
-  });
-
-  describe('Error Handling', () => {
-    it('should return 404 for non-existent endpoints', async () => {
-      const res = await server.request('/nonexistent');
-      const data: any = await res.json();
-      
-      expect(res.status).toBe(404);
-      expect(data.success).toBe(false);
-      expect(data.error).toBe('Not found');
-    });
-  });
-});
-
-// Example usage functions
-export async function sendVerificationCode(phoneNumber, apiKey) {
-  const response = await fetch('http://localhost:8787/api/send', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'X-API-Key': apiKey
-    },
-    body: JSON.stringify({
-      phoneNumber,
-      blockVoip: true,
-      senderId: 'MyApp'
-    })
-  });
-  
-  return response.json();
-}
-
-export async function verifyCode(phoneNumber, code, apiKey) {
-  const response = await fetch('http://localhost:8787/api/verify', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'X-API-Key': apiKey
-    },
-    body: JSON.stringify({
-      phoneNumber,
-      code
-    })
-  });
-  
-  return response.json();
-}
-
-export async function sendGeneralSMS(phoneNumber, message, apiKey) {
-  const response = await fetch('http://localhost:8787/api/sms', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'X-API-Key': apiKey
-    },
-    body: JSON.stringify({
-      phoneNumber,
-      message,
-      senderId: 'MyApp'
-    })
-  });
-  
-  return response.json();
-} 
+/**
+ * Server-level tests exercising the default export the Worker entry point
+ * (`src/index.ts`) mounts, rather than the `createApp` factory.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import app from '../src/verify-phone-server';
+import { apiRequest, stubNetwork, TEST_API_KEY } from './helpers';
+
+describe('SMS Verification API Server', () => {
+  beforeEach(() => {
+    stubNetwork();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe('Health Check Endpoints', () => {
+    it('should return API info on root endpoint', async () => {
+      const res = await app.request('http://localhost/', {}, globalThis.env);
+      const data: any = await res.json();
+
+      expect(res.status).toBe(200);
+      expect(data.success).toBe(true);
+      expect(data.message).toBe('SMS Verification API');
+      expect(data.endpoints).toBeDefined();
+    });
+
+    it('should return health status', async () => {
+      const res = await app.request('http://localhost/health', {}, globalThis.env);
+      const data: any = await res.json();
+
+      expect(res.status).toBe(200);
+      expect(data.success).toBe(true);
+      expect(data.status).toBe('healthy');
+      expect(data.timestamp).toBeDefined();
+    });
+  });
+
+  describe('API Authentication', () => {
+    it('should require API key for protected endpoints', async () => {
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123' }, {}),
+        undefined,
+        globalThis.env,
+      );
+
+      expect(res.status).toBe(401);
+    });
+
+    it('should reject a key that does not match the configured one', async () => {
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123' }, {
+          'X-API-Key': 'sms_1234567890abcdef1234567890abcdef',
+        }),
+        undefined,
+        globalThis.env,
+      );
+
+      expect(res.status).toBe(401);
+    });
+
+    it('should accept valid API key', async () => {
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123' }, { 'X-API-Key': TEST_API_KEY }),
+        undefined,
+        globalThis.env,
+      );
+
+      expect(res.status).toBe(200);
+    });
+
+    it('should reject every /api/* route without a key', async () => {
+      const routes: [string, unknown][] = [
+        ['/api/send', { phoneNumber: '+12025550123' }],
+        ['/api/verify', { phoneNumber: '+12025550123', code: '123456' }],
+        ['/api/sms', { phoneNumber: '+12025550123', message: 'hello' }],
+      ];
+
+      for (const [path, body] of routes) {
+        const res = await app.request(apiRequest(path, body, {}), undefined, globalThis.env);
+        expect(res.status, `${path} should be protected`).toBe(401);
+      }
+    });
+  });
+
+  describe('Documentation', () => {
+    it('should serve Swagger UI at /docs', async () => {
+      const res = await app.request('http://localhost/docs', {}, globalThis.env);
+
+      expect(res.status).toBe(200);
+      expect(res.headers.get('content-type')).toContain('text/html');
+    });
+
+    it('should serve the OpenAPI spec at /openapi.json', async () => {
+      const res = await app.request('http://localhost/openapi.json', {}, globalThis.env);
+      const data: any = await res.json();
+
+      expect(res.status).toBe(200);
+      expect(data.openapi).toBe('3.0.0');
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should return 404 for non-existent endpoints', async () => {
+      const res = await app.request('http://localhost/nonexistent', {}, globalThis.env);
+      const data: any = await res.json();
+
+      expect(res.status).toBe(404);
+      expect(data.success).toBe(false);
+      expect(data.error).toBe('Not found');
+    });
+  });
+});

package/test/voip.test.ts

@@ -1,5 +1,11 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { createApp } from '../src/verify-phone-server';
+/**
+ * VoIP blocking: the `blockVoip` flag on `POST /api/send`, and the
+ * `isPhoneNumberVoip` lookup behind it.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createApp, isPhoneNumberVoip } from '../src/verify-phone-server';
+import { apiRequest, stubNetwork } from './helpers';
 
 describe('VoIP Blocking Functionality', () => {
   let app: ReturnType<typeof createApp>;
@@ -8,106 +14,93 @@ describe('VoIP Blocking Functionality', () => {
     app = createApp(globalThis.env);
   });
 
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
   describe('blockVoip parameter', () => {
-    it('should allow requests when blockVoip is not specified', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=%2B1234567890', {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+    it('should skip the lookup entirely when blockVoip is not specified', async () => {
+      const fetchMock = stubNetwork({ lookup: 'voip' });
+
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123' }),
+        undefined,
+        globalThis.env,
+      );
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
       expect(data.success).toBe(true);
+      const lookups = fetchMock.mock.calls.filter(([url]) => String(url).includes('phone-lookup'));
+      expect(lookups).toHaveLength(0);
     });
 
     it('should allow requests when blockVoip is false', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=%2B1234567890&blockVoip=false', {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+      stubNetwork({ lookup: 'voip' });
+
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123', blockVoip: false }),
+        undefined,
+        globalThis.env,
+      );
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
       expect(data.success).toBe(true);
     });
 
-    it('should accept blockVoip=true parameter', async () => {
-      const req = new Request('http://localhost/api/send-verification?phoneNumber=%2B1234567890&blockVoip=true', {
-        headers: {
-          'X-API-Key': 'test-api-key'
-        }
-      });
-      const res = await app.request(req, globalThis.env);
+    it('should send when blockVoip is true and the number is not VoIP', async () => {
+      stubNetwork({ lookup: 'landline' });
+
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123', blockVoip: true }),
+        undefined,
+        globalThis.env,
+      );
       const data: any = await res.json();
 
       expect(res.status).toBe(200);
       expect(data.success).toBe(true);
     });
+
+    it('should reject when blockVoip is true and the number is VoIP', async () => {
+      stubNetwork({ lookup: 'voip' });
+
+      const res = await app.request(
+        apiRequest('/api/send', { phoneNumber: '+12025550123', blockVoip: true }),
+        undefined,
+        globalThis.env,
+      );
+      const data: any = await res.json();
+
+      expect(res.status).toBe(400);
+      expect(data).toMatchObject({
+        success: false,
+        error: 'VoIP numbers are not allowed',
+        isVoip: true,
+      });
+    });
   });
 
   describe('VoIP detection logic', () => {
-    it('should correctly identify VoIP numbers', async () => {
-      // Import the function from the module
-      const module = await import('../src/verify-phone-server');
-      const { isPhoneNumberVoip } = module;
-
-      // Mock the grab function to return VoIP data
-      const g = globalThis as any;
-      const originalGrab = g.grab;
-      g.grab = {
-        instance: () => ({
-          "phone-lookup": async () => ({
-            carrier: {
-              name: 'Bandwidth',
-              type: 'voip'
-            },
-            portability: {
-              line_type: 'landline'
-            }
-          })
-        })
-      };
-      
-      // Test VoIP number
-      const isVoip = await isPhoneNumberVoip('+1234567890');
-      expect(isVoip).toBe(true);
-      
-      // Mock the grab function to return mobile data
-      g.grab = {
-        instance: () => ({
-          "phone-lookup": async () => ({
-            carrier: {
-              name: 'Verizon Wireless',
-              type: 'mobile'
-            },
-            portability: {
-              line_type: 'mobile'
-            }
-          })
-        })
-      };
-      
-      // Test mobile number
-      const isMobile = await isPhoneNumberVoip('+1234567890');
-      expect(isMobile).toBe(false);
-      
-      // Mock the grab function to return null data
-      g.grab = {
-        instance: () => ({
-          "phone-lookup": async () => null
-        })
-      };
-      
-      // Test null data
-      const isNull = await isPhoneNumberVoip('+1234567890');
-      expect(isNull).toBe(false);
-      
-      // Restore original grab function
-      g.grab = originalGrab;
+    it('should report a Bandwidth/VoIP carrier as VoIP', async () => {
+      stubNetwork({ lookup: 'voip' });
+      await expect(isPhoneNumberVoip('+12025550123')).resolves.toBe(true);
+    });
+
+    it('should report a landline carrier as not VoIP', async () => {
+      stubNetwork({ lookup: 'landline' });
+      await expect(isPhoneNumberVoip('+12025550123')).resolves.toBe(false);
+    });
+
+    it('should treat an empty lookup response as not VoIP', async () => {
+      stubNetwork({ lookup: 'none' });
+      await expect(isPhoneNumberVoip('+12025550123')).resolves.toBe(false);
+    });
+
+    it('should default to allowing the number when the lookup fails', async () => {
+      stubNetwork({ lookupStatus: 429 });
+      await expect(isPhoneNumberVoip('+12025550123')).resolves.toBe(false);
     });
   });
-}); 
+});