@zze/mock-server 0.2.6 → 0.6.0

package/README.md

@@ -8,6 +8,8 @@ A reusable Node.js mock server for simulating backend APIs during local microfro
 - 🔄 **Hot reload** - Automatic config reloading on file changes
 - 🎭 **Scenarios** - Define multiple response scenarios per endpoint
 - 🌊 **Flows** - Activate groups of scenarios to simulate user journeys
+- 📁 **File download** - Serve binary files (PDFs, images, CSVs) from scenarios
+- 📤 **File upload** - Accept `multipart/form-data` upload requests out of the box
 - 🎨 **Admin UI** - Visual dashboard at `/mock-admin` to control the server
 - 🔌 **REST API** - Programmatic control via admin endpoints
 - 📦 **Single package** - Everything bundled, no external dependencies needed
@@ -138,12 +140,15 @@ interface ScenarioConfig {
   id: string;                    // Unique within endpoint
   name: string;                  // Display name in admin UI
   status: number;                // HTTP status code (100-599)
-  body?: any;                    // Response body (JSON or function)
+  body?: any;                    // Response body (JSON or function) — mutually exclusive with file
+  file?: string;                 // File path relative to configPath — mutually exclusive with body
   headers?: Record<string, string>;  // Custom response headers
   delay?: number;                // Response delay in ms
 }
 ```
 
+> **Note:** `body` and `file` are mutually exclusive. Setting both will cause a validation error at startup.
+
 ### Flow Config
 
 Flows activate multiple scenarios at once to simulate complex user journeys.
@@ -177,6 +182,107 @@ interface FlowConfig {
 
 ---
 
+## File Download
+
+A scenario can serve a file instead of JSON by specifying a `file` path relative to `configPath`:
+
+**mock-config/endpoints/reports.json**
+```json
+{
+  "id": "get-report",
+  "path": "/reports/:id",
+  "method": "GET",
+  "defaultScenarioId": "pdf",
+  "scenarios": [
+    {
+      "id": "pdf",
+      "name": "PDF Report",
+      "status": 200,
+      "file": "./assets/sample-report.pdf",
+      "headers": { "Content-Disposition": "attachment; filename=report.pdf" }
+    },
+    {
+      "id": "not-found",
+      "name": "Not Found",
+      "status": 404,
+      "body": { "error": "Report not found" }
+    }
+  ]
+}
+```
+
+Place the file at `mock-config/assets/sample-report.pdf`. The `Content-Type` header is inferred automatically from the file extension if not set explicitly.
+
+> `body` and `file` are mutually exclusive — setting both causes a validation error at startup.
+
+---
+
+## File Upload
+
+Upload endpoints work out of the box — no special configuration needed. The server accepts `multipart/form-data` requests, discards the uploaded files, and returns the active scenario response:
+
+**mock-config/endpoints/avatar.json**
+```json
+{
+  "id": "upload-avatar",
+  "path": "/users/:id/avatar",
+  "method": "POST",
+  "defaultScenarioId": "success",
+  "scenarios": [
+    {
+      "id": "success",
+      "name": "Upload OK",
+      "status": 200,
+      "body": { "url": "/cdn/avatar.jpg" }
+    },
+    {
+      "id": "too-large",
+      "name": "File Too Large",
+      "status": 413,
+      "body": { "error": "File exceeds maximum size" }
+    }
+  ]
+}
+```
+
+---
+
+## Global Delay
+
+Add a baseline latency to every response without modifying individual scenarios:
+
+```typescript
+const server = new MockServer({
+  configPath: './mock-config',
+  globalDelay: 200,             // every response waits 200 ms
+});
+```
+
+Or use a random range to simulate variable network conditions:
+
+```typescript
+const server = new MockServer({
+  configPath: './mock-config',
+  globalDelay: [100, 500],      // each response waits a random 100–500 ms
+});
+```
+
+**Priority:** a scenario's own `delay` field always takes precedence. `globalDelay` is only used when the resolved scenario has no `delay` set.
+
+```json
+{
+  "id": "fast-scenario",
+  "name": "Always fast",
+  "status": 200,
+  "delay": 0,
+  "body": { "ok": true }
+}
+```
+
+In the example above, `delay: 0` overrides any `globalDelay` — the response is immediate.
+
+---
+
 ## TypeScript Configs
 
 You can write configs in TypeScript for type safety and dynamic responses:
@@ -218,9 +324,6 @@ export default endpoint;
 The built-in admin UI is available at `/mock-admin` and provides:
 
 - **Endpoints Panel**: View all endpoints, expand to see scenarios, click to activate
-  - Create new endpoints with the JSON editor
-  - Edit existing endpoint configurations
-  - Delete endpoints with confirmation
 - **Flows Panel**: View and activate user flows with category grouping
   - Create new flows with the endpoint/scenario picker
   - Edit or duplicate existing flows
@@ -248,13 +351,6 @@ Control the mock server programmatically:
 | POST | `/mock-admin/api/flows/activate` | Activate/deactivate a flow |
 | POST | `/mock-admin/api/reset` | Reset to default state |
 
-### Endpoint CRUD
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | `/mock-admin/api/endpoints` | Create a new endpoint |
-| PUT | `/mock-admin/api/endpoints/:id` | Update an existing endpoint |
-| DELETE | `/mock-admin/api/endpoints/:id` | Delete an endpoint |
 
 ### Flow CRUD
 
@@ -289,19 +385,6 @@ curl -X POST http://localhost:3001/mock-admin/api/flows/activate \
 # Reset to defaults
 curl -X POST http://localhost:3001/mock-admin/api/reset
 
-# Create a new endpoint
-curl -X POST http://localhost:3001/mock-admin/api/endpoints \
-  -H "Content-Type: application/json" \
-  -d '{"endpoint": {"id": "new-endpoint", "method": "GET", "path": "/api/test", "scenarios": [{"id": "default", "name": "Default", "response": {"status": 200, "body": {}}}]}}'
-
-# Update an endpoint
-curl -X PUT http://localhost:3001/mock-admin/api/endpoints/new-endpoint \
-  -H "Content-Type: application/json" \
-  -d '{"endpoint": {"id": "new-endpoint", "method": "GET", "path": "/api/test-updated", "scenarios": [{"id": "default", "name": "Default", "response": {"status": 200, "body": {"updated": true}}}]}}'
-
-# Delete an endpoint
-curl -X DELETE http://localhost:3001/mock-admin/api/endpoints/new-endpoint
-
 # Create a new flow
 curl -X POST http://localhost:3001/mock-admin/api/flows \
   -H "Content-Type: application/json" \
@@ -328,13 +411,13 @@ curl -X DELETE http://localhost:3001/mock-admin/api/flows/my-flow
 ### MockServer Class
 
 ```typescript
-import { MockServer } from '@zze/mock-server';
-
 const server = new MockServer({
-  configPath: './mock-config',  // Required
+  configPath: './mock-config',
   port: 3001,                   // Default: 3001
   apiPrefix: '/api',            // Default: '/api'
-  hotReload: true               // Default: true
+  hotReload: true,              // Default: true
+  globalDelay: 200              // Optional: add 200 ms to every response (unless scenario overrides)
+  // globalDelay: [100, 500]   // Or a random range in ms
 });
 ```
 
@@ -592,6 +675,12 @@ interface MockServerOptions {
   apiPrefix?: string;
   hotReload?: boolean;
   watcherOptions?: WatcherOptions;
+  /**
+   * Global delay fallback for all responses.
+   * Scenario-level `delay` always overrides this.
+   * A number is a fixed ms value; a tuple is a [min, max] random range.
+   */
+  globalDelay?: number | [number, number];
 }
 
 // Server state

package/dist/__tests__/mock-server.test.js

@@ -231,7 +231,10 @@ const supertest_1 = __importDefault(require("supertest"));
             }
         });
         (0, vitest_1.it)('should reload configuration manually', async () => {
-            await createEndpoint('test1', '/test1');
+            await createEndpoint('test1', '/test1', 'GET', [
+                { id: 'success', name: 'Success', status: 200, body: { message: 'ok' }, isDefault: true },
+                { id: 'error', name: 'Error', status: 500, body: { error: 'failed' } },
+            ]);
             server = new mock_server_js_1.MockServer({
                 configPath: configDir,
                 port: 3015,
@@ -239,10 +242,12 @@ const supertest_1 = __importDefault(require("supertest"));
             });
             await server.start();
             (0, vitest_1.expect)(server.getEndpoints().length).toBe(1);
+            server.activateScenario('test1', 'error');
             // Add another endpoint
             await createEndpoint('test2', '/test2');
             await server.reload();
             (0, vitest_1.expect)(server.getEndpoints().length).toBe(2);
+            (0, vitest_1.expect)(server.getState().activeScenarios.test1).toBe('error');
         });
         (0, vitest_1.it)('should throw if server is not running', async () => {
             server = new mock_server_js_1.MockServer({
@@ -596,4 +601,56 @@ const supertest_1 = __importDefault(require("supertest"));
             (0, vitest_1.expect)(mockResponse.status).toBe(500);
         });
     });
+    (0, vitest_1.describe)('globalDelay option', () => {
+        let server;
+        (0, vitest_1.afterEach)(async () => {
+            if (server?.getState().running) {
+                await server.stop();
+            }
+        });
+        (0, vitest_1.it)('should apply static globalDelay to responses', async () => {
+            await createEndpoint('delay-ep', '/delay-ep', 'GET', [
+                { id: 'default', name: 'Default', status: 200, body: { ok: true }, isDefault: true },
+            ]);
+            server = new mock_server_js_1.MockServer({
+                configPath: configDir,
+                port: 3040,
+                hotReload: false,
+                globalDelay: 80,
+            });
+            await server.start();
+            const app = server.getApp();
+            const start = Date.now();
+            const res = await (0, supertest_1.default)(app).get('/api/delay-ep');
+            const elapsed = Date.now() - start;
+            (0, vitest_1.expect)(res.status).toBe(200);
+            (0, vitest_1.expect)(elapsed).toBeGreaterThanOrEqual(70); // 80 ms with small margin
+        });
+        (0, vitest_1.it)('scenario-level delay should take precedence over globalDelay', async () => {
+            await createEndpoint('prio-ep', '/prio-ep', 'GET', [
+                {
+                    id: 'fast',
+                    name: 'Fast',
+                    status: 200,
+                    body: { ok: true },
+                    // @ts-ignore - delay is valid in EndpointConfig scenarios
+                    delay: 0,
+                    isDefault: true,
+                },
+            ]);
+            server = new mock_server_js_1.MockServer({
+                configPath: configDir,
+                port: 3041,
+                hotReload: false,
+                globalDelay: 5000, // would time out the test if used
+            });
+            await server.start();
+            const app = server.getApp();
+            const start = Date.now();
+            const res = await (0, supertest_1.default)(app).get('/api/prio-ep');
+            const elapsed = Date.now() - start;
+            (0, vitest_1.expect)(res.status).toBe(200);
+            (0, vitest_1.expect)(elapsed).toBeLessThan(300); // scenario delay=0 wins, should be fast
+        });
+    });
 });

package/dist/admin/__tests__/admin-router.test.js

@@ -10,6 +10,7 @@ const mock_server_app_js_1 = require("../../server/mock-server-app.js");
 const mockEndpoints = [
     {
         id: 'get-users',
+        sourceFile: 'accounts/users.ts',
         path: '/users',
         method: 'GET',
         scenarios: [
@@ -74,6 +75,7 @@ const mockFlows = [
             (0, vitest_1.expect)(usersEndpoint).toBeDefined();
             (0, vitest_1.expect)(usersEndpoint.path).toBe('/users');
             (0, vitest_1.expect)(usersEndpoint.method).toBe('GET');
+            (0, vitest_1.expect)(usersEndpoint.sourceFile).toBe('accounts/users.ts');
             (0, vitest_1.expect)(usersEndpoint.scenarios).toHaveLength(2);
             (0, vitest_1.expect)(usersEndpoint.defaultScenarioId).toBe('success');
         });
@@ -281,131 +283,6 @@ const mockFlows = [
                 .expect(200);
         });
     });
-    (0, vitest_1.describe)('Endpoint CRUD operations', () => {
-        let mockConfigWriter;
-        let onConfigChangeCalled;
-        (0, vitest_1.beforeEach)(() => {
-            onConfigChangeCalled = false;
-            mockConfigWriter = {
-                writeEndpoint: vitest_1.vi.fn().mockResolvedValue({ success: true, filePath: '/test/endpoint.json' }),
-                writeFlow: vitest_1.vi.fn().mockResolvedValue({ success: true, filePath: '/test/flow.json' }),
-                deleteEndpoint: vitest_1.vi.fn().mockResolvedValue({ success: true }),
-                deleteFlow: vitest_1.vi.fn().mockResolvedValue({ success: true }),
-                getEndpointFilePath: vitest_1.vi.fn().mockReturnValue('/test/endpoint.json'),
-                getFlowFilePath: vitest_1.vi.fn().mockReturnValue('/test/flow.json'),
-                findEndpointFile: vitest_1.vi.fn().mockResolvedValue(null),
-                findFlowFile: vitest_1.vi.fn().mockResolvedValue(null),
-            };
-            serverApp.setConfigWriter(mockConfigWriter, async () => {
-                onConfigChangeCalled = true;
-            });
-        });
-        (0, vitest_1.describe)('POST /mock-admin/api/endpoints', () => {
-            (0, vitest_1.it)('should create a new endpoint', async () => {
-                const newEndpoint = {
-                    id: 'new-endpoint',
-                    path: '/new',
-                    method: 'POST',
-                    scenarios: [
-                        { id: 'success', name: 'Success', status: 201, body: { created: true } },
-                    ],
-                    defaultScenarioId: 'success',
-                };
-                const res = await (0, supertest_1.default)(serverApp.getApp())
-                    .post('/mock-admin/api/endpoints')
-                    .send(newEndpoint)
-                    .expect(201);
-                (0, vitest_1.expect)(res.body.id).toBe('new-endpoint');
-                (0, vitest_1.expect)(res.body.filePath).toBeDefined();
-                (0, vitest_1.expect)(mockConfigWriter.writeEndpoint).toHaveBeenCalledWith(newEndpoint);
-                (0, vitest_1.expect)(onConfigChangeCalled).toBe(true);
-            });
-            (0, vitest_1.it)('should return 409 if endpoint already exists', async () => {
-                const existingEndpoint = {
-                    id: 'get-users',
-                    path: '/users',
-                    method: 'GET',
-                    scenarios: [{ id: 's', name: 'S', status: 200, body: {} }],
-                    defaultScenarioId: 's',
-                };
-                const res = await (0, supertest_1.default)(serverApp.getApp())
-                    .post('/mock-admin/api/endpoints')
-                    .send(existingEndpoint)
-                    .expect(409);
-                (0, vitest_1.expect)(res.body.error).toContain('already exists');
-            });
-            (0, vitest_1.it)('should return 400 for invalid endpoint', async () => {
-                const res = await (0, supertest_1.default)(serverApp.getApp())
-                    .post('/mock-admin/api/endpoints')
-                    .send({ id: 'test' }) // Missing required fields
-                    .expect(400);
-                (0, vitest_1.expect)(res.body.error).toBe('Invalid request body');
-            });
-        });
-        (0, vitest_1.describe)('PUT /mock-admin/api/endpoints/:id', () => {
-            (0, vitest_1.it)('should update an existing endpoint', async () => {
-                const updatedEndpoint = {
-                    id: 'get-users',
-                    path: '/users/updated',
-                    method: 'GET',
-                    scenarios: [
-                        { id: 'success', name: 'Success', status: 200, body: { updated: true } },
-                    ],
-                    defaultScenarioId: 'success',
-                };
-                const res = await (0, supertest_1.default)(serverApp.getApp())
-                    .put('/mock-admin/api/endpoints/get-users')
-                    .send(updatedEndpoint)
-                    .expect(200);
-                (0, vitest_1.expect)(res.body.id).toBe('get-users');
-                (0, vitest_1.expect)(mockConfigWriter.writeEndpoint).toHaveBeenCalledWith(updatedEndpoint);
-                (0, vitest_1.expect)(onConfigChangeCalled).toBe(true);
-            });
-            (0, vitest_1.it)('should return 404 if endpoint not found', async () => {
-                const endpoint = {
-                    id: 'nonexistent',
-                    path: '/test',
-                    method: 'GET',
-                    scenarios: [{ id: 's', name: 'S', status: 200, body: {} }],
-                    defaultScenarioId: 's',
-                };
-                const res = await (0, supertest_1.default)(serverApp.getApp())
-                    .put('/mock-admin/api/endpoints/nonexistent')
-                    .send(endpoint)
-                    .expect(404);
-                (0, vitest_1.expect)(res.body.error).toContain('not found');
-            });
-            (0, vitest_1.it)('should return 400 if ID in body does not match URL', async () => {
-                const endpoint = {
-                    id: 'different-id',
-                    path: '/users',
-                    method: 'GET',
-                    scenarios: [{ id: 's', name: 'S', status: 200, body: {} }],
-                    defaultScenarioId: 's',
-                };
-                const res = await (0, supertest_1.default)(serverApp.getApp())
-                    .put('/mock-admin/api/endpoints/get-users')
-                    .send(endpoint)
-                    .expect(400);
-                (0, vitest_1.expect)(res.body.error).toContain('must match');
-            });
-        });
-        (0, vitest_1.describe)('DELETE /mock-admin/api/endpoints/:id', () => {
-            (0, vitest_1.it)('should delete an existing endpoint', async () => {
-                await (0, supertest_1.default)(serverApp.getApp())
-                    .delete('/mock-admin/api/endpoints/get-users')
-                    .expect(204);
-                (0, vitest_1.expect)(mockConfigWriter.deleteEndpoint).toHaveBeenCalledWith('get-users');
-                (0, vitest_1.expect)(onConfigChangeCalled).toBe(true);
-            });
-            (0, vitest_1.it)('should return 404 if endpoint not found', async () => {
-                const res = await (0, supertest_1.default)(serverApp.getApp())
-                    .delete('/mock-admin/api/endpoints/nonexistent')
-                    .expect(404);
-                (0, vitest_1.expect)(res.body.error).toContain('not found');
-            });
-        });
-    });
     (0, vitest_1.describe)('Flow CRUD operations', () => {
         let mockConfigWriter;
         let onConfigChangeCalled;
@@ -561,32 +438,6 @@ const mockFlows = [
         });
     });
     (0, vitest_1.describe)('CRUD operations without ConfigWriter', () => {
-        (0, vitest_1.it)('should return 501 for endpoint CRUD when ConfigWriter not configured', async () => {
-            const endpoint = {
-                id: 'test',
-                path: '/test',
-                method: 'GET',
-                scenarios: [{ id: 's', name: 'S', status: 200, body: {} }],
-                defaultScenarioId: 's',
-            };
-            // POST
-            let res = await (0, supertest_1.default)(serverApp.getApp())
-                .post('/mock-admin/api/endpoints')
-                .send(endpoint)
-                .expect(501);
-            (0, vitest_1.expect)(res.body.error).toContain('not available');
-            // PUT
-            res = await (0, supertest_1.default)(serverApp.getApp())
-                .put('/mock-admin/api/endpoints/get-users')
-                .send({ ...endpoint, id: 'get-users' })
-                .expect(501);
-            (0, vitest_1.expect)(res.body.error).toContain('not available');
-            // DELETE
-            res = await (0, supertest_1.default)(serverApp.getApp())
-                .delete('/mock-admin/api/endpoints/get-users')
-                .expect(501);
-            (0, vitest_1.expect)(res.body.error).toContain('not available');
-        });
         (0, vitest_1.it)('should return 501 for flow CRUD when ConfigWriter not configured', async () => {
             const flow = {
                 id: 'test',

package/dist/admin/admin-router.d.ts

@@ -1,12 +1,12 @@
 import { Router } from 'express';
-import type { EndpointConfig, FlowConfig } from '../schemas/index.js';
+import type { FlowConfig } from '../schemas/index.js';
 import type { StateManager } from '../state/index.js';
-import type { ConfigWriter } from '../config/index.js';
+import type { ConfigWriter, RuntimeEndpointConfig } from '../config/index.js';
 /**
  * Options for creating the admin router
  */
 export interface AdminRouterOptions {
-    getEndpoints: () => EndpointConfig[];
+    getEndpoints: () => RuntimeEndpointConfig[];
     getFlows: () => FlowConfig[];
     stateManager: StateManager;
     getConfigWriter?: () => ConfigWriter | undefined;
@@ -19,7 +19,7 @@ export declare function createAdminRouter(options: AdminRouterOptions): Router;
 /**
  * @deprecated Use options object instead
  */
-export declare function createAdminRouter(getEndpoints: () => EndpointConfig[], getFlows: () => FlowConfig[], stateManager: StateManager): Router;
+export declare function createAdminRouter(getEndpoints: () => RuntimeEndpointConfig[], getFlows: () => FlowConfig[], stateManager: StateManager): Router;
 /**
  * Admin API path constant
  */

package/dist/admin/admin-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin-router.d.ts","sourceRoot":"","sources":["../../src/admin/admin-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAmC,MAAM,SAAS,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYvD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,cAAc,EAAE,CAAC;IACrC,QAAQ,EAAE,MAAM,UAAU,EAAE,CAAC;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,YAAY,GAAG,SAAS,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC;AACvE;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,cAAc,EAAE,EACpC,QAAQ,EAAE,MAAM,UAAU,EAAE,EAC5B,YAAY,EAAE,YAAY,GACzB,MAAM,CAAC;AAkrBV;;GAEG;AACH,eAAO,MAAM,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"admin-router.d.ts","sourceRoot":"","sources":["../../src/admin/admin-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAmC,MAAM,SAAS,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAW9E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,qBAAqB,EAAE,CAAC;IAC5C,QAAQ,EAAE,MAAM,UAAU,EAAE,CAAC;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,YAAY,GAAG,SAAS,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC;AACvE;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,qBAAqB,EAAE,EAC3C,QAAQ,EAAE,MAAM,UAAU,EAAE,EAC5B,YAAY,EAAE,YAAY,GACzB,MAAM,CAAC;AA2cV;;GAEG;AACH,eAAO,MAAM,cAAc,oBAAoB,CAAC"}