@bifravst/http-api-mock 2.1.465 → 2.2.0-dev.1

package/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2024-2025, Nordic Semiconductor ASA | nordicsemi.no
+Copyright (c) 2024-2026, Nordic Semiconductor ASA | nordicsemi.no
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

package/README.md

@@ -37,3 +37,19 @@ npx @bifravst/http-api-mock describe <stackName>
 ```bash
 npx @bifravst/http-api-mock destroy <stackName>
 ```
+
+## Node & NPM
+
+This project requires Node.js `>=24.19.0 <25` and npm `>=12.0.2 <13` (enforced
+via `check-node-version` on `npm install` and `npm ci`).
+
+The check is skipped during `npm publish` and `npm pack`, because
+`semantic-release` bundles its own npm (`@semantic-release/npm` depends on
+`npm@^11.6.2`) and runs the publish with that version rather than the one
+installed in CI.
+
+## TypeScript 6 and 7
+
+This repo
+[runs TypeScript 6 and 7 side by side](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0),
+[so that eslint works](https://github.com/typescript-eslint/typescript-eslint/issues/10940#issuecomment-4922812181).

package/npm/cdk/App.js

@@ -0,0 +1,15 @@
+import { App } from 'aws-cdk-lib';
+import { HTTPAPIMockStack } from './Stack.js';
+export class HTTPAPIMockApp extends App {
+    constructor(stackName, { lambdaSources, layer }){
+        super({
+            context: {
+                isTest: true
+            }
+        });
+        new HTTPAPIMockStack(this, stackName, {
+            lambdaSources,
+            layer
+        });
+    }
+}

package/npm/cdk/Stack.js

@@ -0,0 +1,45 @@
+import { LambdaSource } from '@bifravst/aws-cdk-lambda-helpers/cdk';
+import { CfnOutput, aws_lambda as Lambda, Stack } from 'aws-cdk-lib';
+import { HttpApiMock } from './resources/HttpApiMock.js';
+/**
+ * This is CloudFormation stack sets up a dummy HTTP API which stores all requests in SQS for inspection
+ */ export class HTTPAPIMockStack extends Stack {
+    constructor(parent, stackName, { lambdaSources, layer }){
+        super(parent, stackName, {
+            description: 'Provides a mock HTTP API for testing third-party API integrations.'
+        });
+        const baseLayer = new Lambda.LayerVersion(this, 'baseLayer', {
+            layerVersionName: `${Stack.of(this).stackName}-baseLayer`,
+            code: new LambdaSource(this, {
+                id: 'baseLayer',
+                zipFilePath: layer.layerZipFilePath,
+                hash: layer.hash
+            }).code,
+            compatibleArchitectures: [
+                Lambda.Architecture.ARM_64
+            ],
+            compatibleRuntimes: [
+                Lambda.Runtime.NODEJS_24_X
+            ]
+        });
+        const httpMockApi = new HttpApiMock(this, {
+            lambdaSources,
+            layers: [
+                baseLayer
+            ]
+        });
+        // Export these so the test runner can use them
+        new CfnOutput(this, 'apiURL', {
+            value: httpMockApi.api.url,
+            exportName: `${this.stackName}:apiURL`
+        });
+        new CfnOutput(this, 'responsesTableName', {
+            value: httpMockApi.responsesTable.tableName,
+            exportName: `${this.stackName}:responsesTableName`
+        });
+        new CfnOutput(this, 'requestsTableName', {
+            value: httpMockApi.requestsTable.tableName,
+            exportName: `${this.stackName}:requestsTableName`
+        });
+    }
+}

package/npm/cdk/http-api-mock.js

@@ -0,0 +1,77 @@
+import { Toolkit } from '@aws-cdk/toolkit-lib';
+import { CloudFormationClient } from '@aws-sdk/client-cloudformation';
+import { packLambdaFromPath } from '@bifravst/aws-cdk-lambda-helpers';
+import { packLayer } from '@bifravst/aws-cdk-lambda-helpers/layer';
+import { stackOutput } from '@bifravst/cloudformation-helpers';
+import commandLineArgs from 'command-line-args';
+import { writeFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomString } from '../src/randomString.js';
+import { HTTPAPIMockApp } from './App.js';
+const options = commandLineArgs([
+    {
+        name: 'config',
+        type: Boolean,
+        defaultValue: false
+    },
+    {
+        name: 'destroy',
+        type: Boolean,
+        defaultValue: false
+    }
+]);
+const loadConfig = async ()=>{
+    try {
+        const config = JSON.parse(await fs.readFile(path.join(process.cwd(), 'http-api-mock.json'), 'utf-8'));
+        return config;
+    } catch  {
+        return {};
+    }
+};
+const stackName = process.env.HTTP_API_MOCK_STACK_NAME ?? (await loadConfig())?.stackName ?? `http-api-mock-${randomString()}`;
+const saveConfig = async ()=>{
+    writeFileSync(path.join(process.cwd(), 'http-api-mock.json'), JSON.stringify({
+        stackName,
+        ...await stackOutput(new CloudFormationClient({}))(stackName)
+    }, null, 2));
+};
+if (options.config === true) {
+    await saveConfig();
+    process.exit(0);
+}
+const baseDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const distDir = await fs.mkdtemp(path.join(os.tmpdir(), 'temp-'));
+const lambdasDir = path.join(distDir, 'lambdas');
+await fs.mkdir(lambdasDir);
+const layersDir = path.join(distDir, 'layers');
+await fs.mkdir(layersDir);
+const dependencies = [
+    '@bifravst/from-env'
+];
+const app = new HTTPAPIMockApp(stackName, {
+    lambdaSources: {
+        httpApiMock: await packLambdaFromPath({
+            id: 'httpApiMock',
+            sourceFilePath: 'cdk/resources/http-api-mock-lambda.ts',
+            baseDir,
+            distDir: lambdasDir
+        })
+    },
+    layer: await packLayer({
+        id: 'testResources',
+        dependencies,
+        baseDir,
+        distDir: layersDir
+    })
+});
+const cdk = new Toolkit();
+const cx = await cdk.fromAssemblyBuilder(async ()=>app.synth());
+if (options.destroy === true) {
+    await cdk.destroy(cx);
+} else {
+    await cdk.deploy(cx);
+    await saveConfig();
+}

package/npm/cdk/resources/HttpApiMock.js

@@ -0,0 +1,87 @@
+import { LambdaLogGroup, LambdaSource } from '@bifravst/aws-cdk-lambda-helpers/cdk';
+import { aws_apigateway as ApiGateway, Duration, aws_dynamodb as DynamoDB, aws_iam as IAM, aws_lambda as Lambda, aws_logs as Logs, RemovalPolicy, Resource } from 'aws-cdk-lib';
+export class HttpApiMock extends Resource {
+    api;
+    requestsTable;
+    responsesTable;
+    constructor(parent, { lambdaSources, layers }){
+        super(parent, 'http-api-mock');
+        // This table will store all the requests made to the API Gateway
+        this.requestsTable = new DynamoDB.Table(this, 'requests', {
+            billingMode: DynamoDB.BillingMode.PAY_PER_REQUEST,
+            partitionKey: {
+                name: 'requestId',
+                type: DynamoDB.AttributeType.STRING
+            },
+            sortKey: {
+                name: 'timestamp',
+                type: DynamoDB.AttributeType.STRING
+            },
+            removalPolicy: RemovalPolicy.DESTROY
+        });
+        this.requestsTable.addGlobalSecondaryIndex({
+            indexName: 'methodPathQuery',
+            partitionKey: {
+                name: 'methodPathQuery',
+                type: DynamoDB.AttributeType.STRING
+            },
+            projectionType: DynamoDB.ProjectionType.ALL
+        });
+        // This table will store optional responses to be sent
+        this.responsesTable = new DynamoDB.Table(this, 'responses', {
+            billingMode: DynamoDB.BillingMode.PAY_PER_REQUEST,
+            partitionKey: {
+                name: 'responseId',
+                type: DynamoDB.AttributeType.STRING
+            },
+            sortKey: {
+                name: 'timestamp',
+                type: DynamoDB.AttributeType.STRING
+            },
+            removalPolicy: RemovalPolicy.DESTROY,
+            timeToLiveAttribute: 'ttl'
+        });
+        this.responsesTable.addGlobalSecondaryIndex({
+            indexName: 'methodPathQuery',
+            partitionKey: {
+                name: 'methodPathQuery',
+                type: DynamoDB.AttributeType.STRING
+            },
+            projectionType: DynamoDB.ProjectionType.ALL
+        });
+        // This lambda will publish all requests made to the API Gateway in the queue
+        const lambda = new Lambda.Function(this, 'Lambda', {
+            description: 'Mocks a HTTP API and stores all requests in SQS for inspection, and optionally replies with enqued responses',
+            code: new LambdaSource(this, lambdaSources.httpApiMock).code,
+            layers,
+            handler: lambdaSources.httpApiMock.handler,
+            architecture: Lambda.Architecture.ARM_64,
+            runtime: Lambda.Runtime.NODEJS_24_X,
+            timeout: Duration.seconds(5),
+            environment: {
+                REQUESTS_TABLE_NAME: this.requestsTable.tableName,
+                RESPONSES_TABLE_NAME: this.responsesTable.tableName,
+                LOG_LEVEL: this.node.tryGetContext('logLevel'),
+                NODE_NO_WARNINGS: '1'
+            },
+            ...new LambdaLogGroup(this, 'LambdaLogs', Logs.RetentionDays.ONE_DAY)
+        });
+        this.responsesTable.grantReadWriteData(lambda);
+        this.requestsTable.grantReadWriteData(lambda);
+        // This is the API Gateway, AWS CDK automatically creates a prod stage and deployment
+        this.api = new ApiGateway.RestApi(this, 'api', {
+            restApiName: `HTTP Mock API for testing`,
+            description: 'API Gateway to test outgoing requests',
+            binaryMediaTypes: [
+                'application/octet-stream'
+            ]
+        });
+        const proxyResource = this.api.root.addResource('{proxy+}');
+        proxyResource.addMethod('ANY', new ApiGateway.LambdaIntegration(lambda));
+        // API Gateway needs to be able to call the lambda
+        lambda.addPermission('InvokeByApiGateway', {
+            principal: new IAM.ServicePrincipal('apigateway.amazonaws.com'),
+            sourceArn: this.api.arnForExecuteApi()
+        });
+    }
+}

package/npm/cdk/resources/checkMatchingQueryParams.js

@@ -0,0 +1,31 @@
+const matchRegex = /^\/(?<re>.+)\/(?<option>[gi])?$/;
+export const checkMatchingQueryParams = (actual, expected, log)=>{
+    log?.debug('checkMatchingQueryParams', {
+        actual,
+        expected
+    });
+    if (actual === null) return false;
+    // Check whether expected query parameters is subset of actual query parameters
+    for(const prop in expected){
+        const expectedValue = expected[prop];
+        const actualValue = actual?.[prop];
+        if (actualValue === undefined) return false;
+        if (typeof expectedValue === 'string') {
+            const match = matchRegex.exec(expectedValue);
+            if (match !== null) {
+                log?.debug('Compare using regex', {
+                    expectedValue
+                });
+                // Expect is regex
+                const check = new RegExp(match?.groups?.re ?? '', match?.groups?.option).test(String(actualValue));
+                if (check === false) return false;
+            } else {
+                if (actualValue !== expectedValue) return false;
+            }
+        } else {
+            // All query parameters are string
+            if (actualValue !== String(expectedValue)) return false;
+        }
+    }
+    return true;
+};

package/npm/cdk/resources/http-api-mock-lambda.js

@@ -0,0 +1,90 @@
+import { DeleteItemCommand, DynamoDBClient, PutItemCommand, ScanCommand } from '@aws-sdk/client-dynamodb';
+import { marshall, unmarshall } from '@aws-sdk/util-dynamodb';
+import { URLSearchParams } from 'url';
+import { sortQueryString } from '../../src/sortQueryString.js';
+import { checkMatchingQueryParams } from './checkMatchingQueryParams.js';
+import { splitMockResponse } from './splitMockResponse.js';
+const db = new DynamoDBClient({});
+export const handler = async (event, context)=>{
+    console.log(JSON.stringify({
+        event
+    }));
+    const query = event.queryStringParameters !== null && event.queryStringParameters !== undefined ? new URLSearchParams(event.queryStringParameters) : undefined;
+    const path = event.path.replace(/^\//, '');
+    const pathWithQuery = sortQueryString(`${path}${query !== undefined ? `?${query.toString()}` : ''}`);
+    const request = {
+        methodPathQuery: `${event.httpMethod} ${pathWithQuery}`,
+        timestamp: new Date().toISOString(),
+        requestId: context.awsRequestId,
+        method: event.httpMethod,
+        path,
+        query: query === undefined ? null : Object.fromEntries(query),
+        body: event.body ?? '{}',
+        headers: JSON.stringify(event.headers)
+    };
+    // Check if response exists
+    console.debug(`Checking if response exists for ${event.httpMethod} ${pathWithQuery}...`);
+    // Scan using httpMethod and path only so query strings can be partially matched
+    const { Items } = await db.send(new ScanCommand({
+        TableName: process.env.RESPONSES_TABLE_NAME,
+        FilterExpression: 'begins_with(methodPathQuery, :methodPath)',
+        ExpressionAttributeValues: {
+            [':methodPath']: {
+                S: `${event.httpMethod} ${path}`
+            }
+        }
+    }));
+    console.debug(`Found response items beginning with same path: ${Items?.length}`);
+    // use newest response first
+    const itemsByTimestampDesc = (Items ?? []).map((Item)=>unmarshall(Item)).sort((a, b)=>b.timestamp.localeCompare(a.timestamp));
+    let res = {
+        statusCode: 404,
+        body: 'No responses found'
+    };
+    for (const objItem of itemsByTimestampDesc){
+        const hasExpectedQueryParams = 'queryParams' in objItem || query !== undefined;
+        const matchedQueryParams = hasExpectedQueryParams ? checkMatchingQueryParams(event.queryStringParameters, objItem.queryParams) : true;
+        if (matchedQueryParams === false) continue;
+        console.debug(`Matched response`, JSON.stringify({
+            response: objItem
+        }));
+        if (objItem?.requestId !== undefined && objItem?.timestamp !== undefined && objItem?.keep !== true) {
+            await db.send(new DeleteItemCommand({
+                TableName: process.env.RESPONSES_TABLE_NAME,
+                Key: marshall({
+                    requestId: objItem.requestId,
+                    timestamp: objItem.timestamp
+                })
+            }));
+        }
+        const { body, headers } = splitMockResponse(objItem.body ?? '');
+        // Send as binary, if mock response is HEX encoded. See https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings.html
+        const isBinary = /^[0-9a-f]+$/.test(body);
+        res = {
+            statusCode: objItem.statusCode ?? 200,
+            headers: isBinary ? {
+                ...headers,
+                'Content-Type': 'application/octet-stream'
+            } : headers,
+            body: isBinary ? /* body is HEX encoded */ Buffer.from(body, 'hex').toString('base64') : body,
+            isBase64Encoded: isBinary
+        };
+        break;
+    }
+    console.debug(`Return response`, JSON.stringify({
+        response: res
+    }));
+    await db.send(new PutItemCommand({
+        TableName: process.env.REQUESTS_TABLE_NAME,
+        Item: marshall({
+            ...request,
+            responseStatusCode: res.statusCode,
+            responseHeaders: res.headers,
+            responseBody: res.body,
+            responseIsBase64Encoded: res.isBase64Encoded
+        }, {
+            removeUndefinedValues: true
+        })
+    }));
+    return res;
+};

package/npm/cdk/resources/splitMockResponse.js

@@ -0,0 +1,15 @@
+export const splitMockResponse = (r)=>{
+    const trimmedLines = r.split('\n').map((s)=>s.trim()).join('\n');
+    const blankLineLocation = trimmedLines.indexOf('\n\n');
+    if (blankLineLocation === -1) return {
+        headers: {},
+        body: trimmedLines
+    };
+    return {
+        headers: trimmedLines.slice(0, blankLineLocation).split('\n').map((s)=>s.split(':', 2)).reduce((headers, [k, v])=>({
+                ...headers,
+                [k]: v?.trim()
+            }), {}),
+        body: trimmedLines.slice(blankLineLocation + 2)
+    };
+};

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@bifravst/http-api-mock",
-  "version": "2.1.465",
+  "version": "2.2.0-dev.1",
   "description": "Helper functions for AWS lambdas written in TypeScript.",
   "exports": {
     "./*": {
       "import": {
-        "types": "./npm/*.d.ts",
-        "default": "./npm/*.js"
+        "default": "./npm/src/*.js",
+        "types": "./src/*.ts"
       }
     }
   },
+  "bin": "node --no-warnings ./npm/cdk/http-api-mock.js",
   "type": "module",
   "scripts": {
-    "prepare": "husky",
-    "prepublishOnly": "node --experimental-strip-types ./.npm/compile.ts && npx tsgo src/*.ts --emitDeclarationOnly --declaration --ignoreConfig --allowImportingTsExtensions --target esnext --module nodenext --moduleResolution nodenext --outDir ./npm && mv npm/src/* npm",
+    "prepare": "husky && case \"$npm_command\" in install|ci) check-node-version --package ;; esac",
+    "prepublishOnly": "node --no-warnings --experimental-transform-types  ./.npm/compile.ts",
     "test": "node --no-warnings --experimental-transform-types --test \"!(node_modules|e2e-tests|integration-tests)/**/*.spec.ts\""
   },
   "repository": {
@@ -41,8 +42,8 @@
     ]
   },
   "engines": {
-    "node": ">=24",
-    "npm": ">=11"
+    "node": ">=24.19.0 <25",
+    "npm": ">=12.0.2 <13"
   },
   "release": {
     "branches": [
@@ -67,35 +68,37 @@
   },
   "files": [
     "npm",
+    "src",
     "LICENSE",
     "README.md"
   ],
   "prettier": "@bifravst/prettier-config",
   "dependencies": {
-    "@aws-sdk/client-cloudformation": "3.981.0",
-    "@aws-sdk/client-dynamodb": "3.981.0",
-    "@aws-sdk/client-sts": "3.981.0",
-    "@aws-sdk/util-dynamodb": "3.981.0",
+    "@aws-sdk/client-cloudformation": "3.1111.0",
+    "@aws-sdk/client-dynamodb": "3.1111.0",
+    "@aws-sdk/client-sts": "3.1111.0",
+    "@aws-sdk/util-dynamodb": "3.996.9",
     "@bifravst/aws-cdk-lambda-helpers": "4.0.96",
     "@bifravst/cloudformation-helpers": "9.1.1",
     "@bifravst/from-env": "3.0.2",
     "@bifravst/run": "1.2.0",
-    "aws-cdk-lib": "2.260.0",
-    "cdk": "2.1133.0",
-    "chalk": "5.6.2",
-    "tsx": "4.23.1"
+    "aws-cdk-lib": "2.265.0",
+    "cdk": "2.1136.0",
+    "chalk": "6.0.0"
   },
   "devDependencies": {
-    "@aws-cdk/toolkit-lib": "1.29.1",
-    "@bifravst/eslint-config-typescript": "6.4.4",
+    "@aws-cdk/toolkit-lib": "1.38.2",
+    "@bifravst/eslint-config-typescript": "7.0.34",
     "@bifravst/prettier-config": "1.1.17",
-    "@commitlint/config-conventional": "20.5.3",
+    "@commitlint/config-conventional": "21.2.2",
     "@types/aws-lambda": "8.10.162",
     "@types/command-line-args": "5.2.3",
-    "@types/node": "25.9.5",
-    "@typescript/native-preview": "7.0.0-dev.20260309.1",
+    "@types/node": "26.2.0",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "check-node-version": "4.2.1",
     "command-line-args": "6.0.2",
-    "commitlint": "20.5.3",
-    "husky": "9.1.7"
+    "commitlint": "21.2.2",
+    "husky": "9.1.7",
+    "typescript": "npm:@typescript/typescript6@6.0.2"
   }
 }

package/src/mock.spec.ts

@@ -0,0 +1,52 @@
+import type { AttributeValue, DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import { unmarshall } from '@aws-sdk/util-dynamodb'
+import assert from 'node:assert/strict'
+import { describe, it, mock as testMock } from 'node:test'
+import { mock } from './mock.ts'
+
+void describe('mock()', () => {
+	void it('should register a response', async () => {
+		const db = {
+			send: testMock.fn(async () => Promise.resolve(undefined)),
+		}
+		const httpApiMock = mock({
+			db: db as unknown as DynamoDBClient,
+			responsesTable: 'response-table',
+		})
+
+		await httpApiMock.response(`GET foo/bar?k=v`, {
+			status: 200,
+			headers: new Headers({
+				'content-type': 'application/json; charset=utf-8',
+			}),
+			body: JSON.stringify({
+				result: 'some-value',
+			}),
+		})
+
+		assert.equal(db.send.mock.callCount(), 1)
+		const [{ input: args }] = db.send.mock.calls[0]?.arguments as unknown as [
+			{
+				input: {
+					TableName: string
+					Item: Record<string, AttributeValue>
+				}
+			},
+		]
+		assert.equal(args.TableName, 'response-table')
+		const { methodPathQuery, statusCode, body, queryParams } = unmarshall(
+			args.Item,
+		)
+		assert.equal(statusCode, 200)
+		assert.equal(methodPathQuery, 'GET foo/bar?k=v')
+		assert.equal(
+			body,
+			[
+				`content-type: application/json; charset=utf-8`,
+				``,
+				JSON.stringify({ result: 'some-value' }),
+			].join('\n'),
+		)
+		assert.deepEqual(queryParams, { k: 'v' })
+	})
+})

package/src/mock.ts

@@ -0,0 +1,61 @@
+import type { DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import { registerResponse } from './responses.ts'
+
+type MockResponseFn = (
+	// The expected request in the form 'GET resource/subresource?query=value
+	methodPathQuery: string,
+	// The response
+	response: Partial<{
+		headers: Headers
+		status: number
+		body: string
+	}>,
+	keep?: boolean,
+) => Promise<void>
+
+export const mockResponse =
+	(db: DynamoDBClient, responsesTable: string): MockResponseFn =>
+	async (methodPathQuery, response, keep) => {
+		const [method, pathWithQuery] = methodPathQuery.split(' ', 2)
+		if (!/^[A-Z]+$/.test(method ?? ''))
+			throw new Error(`Invalid method ${method} in ${methodPathQuery}!`)
+		if (pathWithQuery === undefined)
+			throw new Error(`Missing path in ${methodPathQuery}!`)
+		const [path, query] = pathWithQuery.split('?', 2) as [
+			string,
+			string | undefined,
+		]
+		if (path.startsWith('/'))
+			throw new Error(`Path ${path} must not start with /!`)
+
+		const bodyParts = []
+		if (response.headers !== undefined) {
+			for (const [k, v] of response.headers.entries()) {
+				bodyParts.push(`${k}: ${v}`)
+			}
+			bodyParts.push('')
+		}
+		if (response.body !== undefined) bodyParts.push(response.body)
+		await registerResponse(db, responsesTable, {
+			path,
+			method: method ?? 'GET',
+			queryParams: new URLSearchParams(query),
+			body: bodyParts.length > 0 ? bodyParts.join('\n') : undefined,
+			statusCode: response.status,
+			keep,
+		})
+	}
+
+export type HttpAPIMock = {
+	response: MockResponseFn
+}
+
+export const mock = ({
+	db,
+	responsesTable,
+}: {
+	db: DynamoDBClient
+	responsesTable: string
+}): HttpAPIMock => ({
+	response: mockResponse(db, responsesTable),
+})

package/src/parseMockRequest.spec.ts

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { parseMockRequest } from './parseMockRequest.ts'
+
+void describe('parseMockRequest()', () => {
+	void it('should parse method, resource, protocol, headers and body', () =>
+		assert.deepEqual(
+			parseMockRequest(
+				[
+					`PATCH /v1/devices/foo/state HTTP/1.1`,
+					`Content-Length: 36`,
+					`Content-Type: application/json`,
+					`If-Match: 8835`,
+					``,
+					`{"desired":{"config":{"nod":null}}}`,
+				].join('\n'),
+			),
+			{
+				method: 'PATCH',
+				resource: '/v1/devices/foo/state',
+				protocol: 'HTTP/1.1',
+				headers: {
+					'Content-Length': '36',
+					'Content-Type': 'application/json',
+					'If-Match': '8835',
+				},
+				body: '{"desired":{"config":{"nod":null}}}',
+			},
+		))
+})

package/src/parseMockRequest.ts

@@ -0,0 +1,35 @@
+export const parseMockRequest = (
+	r: string,
+): {
+	method: string
+	resource: string
+	protocol: string // 'HTTP/1.0' | 'HTTP/1.1'
+	headers: Record<string, string>
+	body: string
+} => {
+	const lines = r.split('\n')
+	const methodResourceProtol = lines.shift()
+	const blankLineLocation = lines.indexOf('')
+	const headerLines =
+		blankLineLocation === -1 ? lines : lines.slice(0, blankLineLocation)
+	const body =
+		blankLineLocation === -1
+			? ''
+			: lines.slice(blankLineLocation + 1).join('\n')
+
+	const requestInfo =
+		/^(?<method>[A-Z]+) (?<resource>[^ ]+) (?<protocol>HTTP\/[0-9.]+)/.exec(
+			methodResourceProtol ?? '',
+		)?.groups as { method: string; resource: string; protocol: string }
+
+	if (requestInfo === null)
+		throw new Error(`Invalid request info: ${methodResourceProtol}`)
+
+	return {
+		...requestInfo,
+		headers: headerLines
+			.map((s) => s.split(':', 2))
+			.reduce((headers, [k, v]) => ({ ...headers, [k ?? '']: v?.trim() }), {}),
+		body,
+	}
+}

package/src/parseMockResponse.spec.ts

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { parseMockResponse } from './parseMockResponse.ts'
+
+void describe('parseMockResponse()', () => {
+	void it('should parse protocol, statusCode, headers and body', () =>
+		assert.deepEqual(
+			parseMockResponse(
+				[
+					`HTTP/1.1 202 Accepted`,
+					`Content-Length: 36`,
+					`Content-Type: application/json`,
+					``,
+					`{"desired":{"config":{"nod":null}}}`,
+				].join('\n'),
+			),
+			{
+				statusCode: 202,
+				protocol: 'HTTP/1.1',
+				headers: {
+					'Content-Length': '36',
+					'Content-Type': 'application/json',
+				},
+				body: '{"desired":{"config":{"nod":null}}}',
+			},
+		))
+})

package/src/parseMockResponse.ts

@@ -0,0 +1,35 @@
+export const parseMockResponse = (
+	r: string,
+): {
+	statusCode: number
+	protocol: string // 'HTTP/1.0' | 'HTTP/1.1'
+	headers: Record<string, string>
+	body: string
+} => {
+	const lines = r.split('\n')
+	const protocolStatusCode = lines.shift()
+	const blankLineLocation = lines.indexOf('')
+	const headerLines =
+		blankLineLocation === -1 ? lines : lines.slice(0, blankLineLocation)
+	const body =
+		blankLineLocation === -1
+			? ''
+			: lines.slice(blankLineLocation + 1).join('\n')
+
+	const responseInfo =
+		/^(?<protocol>HTTP\/[0-9.]+) (?<statusCode>[0-9]+) /.exec(
+			protocolStatusCode ?? '',
+		)?.groups as { statusCode: string; protocol: string }
+
+	if (responseInfo === null)
+		throw new Error(`Invalid request info: ${protocolStatusCode}`)
+
+	return {
+		statusCode: parseInt(responseInfo.statusCode, 10),
+		protocol: responseInfo.protocol,
+		headers: headerLines
+			.map((s) => s.split(':', 2))
+			.reduce((headers, [k, v]) => ({ ...headers, [k ?? '']: v?.trim() }), {}),
+		body,
+	}
+}

package/src/randomString.ts

@@ -0,0 +1,7 @@
+import crypto from 'node:crypto'
+
+export const randomString = (): string =>
+	crypto
+		.randomBytes(Math.ceil(8 * 0.5))
+		.toString('hex')
+		.slice(0, 8)

package/src/requests.ts

@@ -0,0 +1,28 @@
+import { ScanCommand, type DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import { unmarshall } from '@aws-sdk/util-dynamodb'
+
+export type Request = {
+	path: string //e.g.'555c3960-2092-438b-b2b0-f28eebd1f5bb'
+	query: null
+	timestamp: string //e.g.'2024-04-05T13:01:14.434Z'
+	ttl: string //e.g. 1712322374
+	headers: Record<string, string> //e.g. '{"Accept":"*/*","Accept-Encoding":"br, gzip, deflate","Accept-Language":"*","CloudFront-Forwarded-Proto":"https","CloudFront-Is-Desktop-Viewer":"true","CloudFront-Is-Mobile-Viewer":"false","CloudFront-Is-SmartTV-Viewer":"false","CloudFront-Is-Tablet-Viewer":"false","CloudFront-Viewer-ASN":"2116","CloudFront-Viewer-Country":"NO","Host":"idj1fffo0k.execute-api.eu-west-1.amazonaws.com","sec-fetch-mode":"cors","User-Agent":"node","Via":"1.1 b053873243f91b1bb6dc406ce0c67db4.cloudfront.net (CloudFront)","X-Amz-Cf-Id":"_vJIGo6Z89QxDzoqOZL4G0PQqPFWGesVXVan4ND934_Urqn2ifSOsQ==","X-Amzn-Trace-Id":"Root=1-660ff61a-25e1219a7f153e1b0c768358","X-Forwarded-For":"194.19.86.146, 130.176.182.18","X-Forwarded-Port":"443","X-Forwarded-Proto":"https"}'
+	method: string //e.g.'GET'
+	requestId: string //e.g.'f34b042b-e9a2-4089-97a2-241516d40d64'
+	body: string //e.g.'{}'
+	methodPathQuery: string //e.g.'GET 555c3960-2092-438b-b2b0-f28eebd1f5bb'
+}
+
+export const listRequests = async (
+	db: DynamoDBClient,
+	requestsTable: string,
+): Promise<Array<Request>> =>
+	((await db.send(new ScanCommand({ TableName: requestsTable }))).Items ?? [])
+		.map((item) => {
+			const i = unmarshall(item)
+			return {
+				...i,
+				headers: JSON.parse(i.headers),
+			} as Request
+		})
+		.sort((i1, i2) => i1.timestamp.localeCompare(i2.timestamp))

package/src/responses.ts

@@ -0,0 +1,50 @@
+import { PutItemCommand, type DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import { marshall } from '@aws-sdk/util-dynamodb'
+import { randomUUID } from 'node:crypto'
+import { sortQuery } from './sortQueryString.ts'
+
+export type Response = {
+	// e.g. 'GET'
+	method: string
+	// without leading slash
+	path: string
+	queryParams?: URLSearchParams
+	statusCode?: number
+	/**
+	 * Header + Body
+	 *
+	 * @see splitMockResponse
+	 */
+	body?: string
+	ttl?: number
+	// Whether to delete the message after sending it
+	keep?: boolean
+}
+
+export const registerResponse = async (
+	db: DynamoDBClient,
+	responsesTable: string,
+	response: Response,
+): Promise<void> => {
+	await db.send(
+		new PutItemCommand({
+			TableName: responsesTable,
+			Item: marshall(
+				{
+					responseId: randomUUID(),
+					methodPathQuery: `${response.method} ${response.path}${response.queryParams !== undefined ? `?${sortQuery(response.queryParams)}` : ``}`,
+					timestamp: new Date().toISOString(),
+					statusCode: response.statusCode,
+					body: response.body,
+					queryParams:
+						response.queryParams !== undefined
+							? Object.fromEntries(response.queryParams)
+							: undefined,
+					ttl: response.ttl,
+					keep: response.keep,
+				},
+				{ removeUndefinedValues: true },
+			),
+		}),
+	)
+}

package/src/sortQueryString.spec.ts

@@ -0,0 +1,38 @@
+import assert from 'node:assert'
+import { describe, test as it } from 'node:test'
+import { URLSearchParams } from 'node:url'
+import { sortQuery, sortQueryString } from './sortQueryString.ts'
+
+void describe('sortQueryString', () => {
+	void it('should sort the query part of a mock URL', () =>
+		assert.deepStrictEqual(
+			sortQueryString(
+				'api.nrfcloud.com/v1/location/agps?eci=73393515&tac=132&requestType=custom&mcc=397&mnc=73&customTypes=2',
+			),
+			'api.nrfcloud.com/v1/location/agps?customTypes=2&eci=73393515&mcc=397&mnc=73&requestType=custom&tac=132',
+		))
+})
+
+void describe('sortQuery', () => {
+	void it('should sort URLSearchParams', () =>
+		assert.equal(
+			sortQuery(
+				new URLSearchParams(
+					'eci=73393515&tac=132&requestType=custom&mcc=397&mnc=73&customTypes=2',
+				),
+			),
+			'customTypes=2&eci=73393515&mcc=397&mnc=73&requestType=custom&tac=132',
+		))
+	void it('should sort a Record', () =>
+		assert.equal(
+			sortQuery({
+				eci: '73393515',
+				tac: '132',
+				requestType: 'custom',
+				mcc: '397',
+				mnc: '73',
+				customTypes: '2',
+			}),
+			'customTypes=2&eci=73393515&mcc=397&mnc=73&requestType=custom&tac=132',
+		))
+})

package/src/sortQueryString.ts

@@ -0,0 +1,26 @@
+import { URLSearchParams } from 'node:url'
+
+export const sortQueryString = (mockUrl: string): string => {
+	const [host, query] = mockUrl.split('?', 2) as [string, string | undefined]
+	if (query === undefined || (query?.length ?? 0) === 0) return host
+	return `${host}?${sortQuery(new URLSearchParams(query))}`
+}
+
+export const sortQuery = (
+	query: URLSearchParams | Record<string, string>,
+): string => {
+	const params: string[][] = []
+	if (query instanceof URLSearchParams) {
+		query.forEach((v, k) => {
+			params.push([k, v])
+		})
+	} else {
+		params.push(...Object.entries(query))
+	}
+	params.sort(([k1], [k2]) => (k1 ?? '').localeCompare(k2 ?? ''))
+	const sortedParams = new URLSearchParams()
+	for (const [k, v] of params) {
+		sortedParams.append(k as string, v as string)
+	}
+	return sortedParams.toString()
+}

package/npm/mock.d.ts

@@ -1,15 +0,0 @@
-import type { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-type MockResponseFn = (methodPathQuery: string, response: Partial<{
-    headers: Headers;
-    status: number;
-    body: string;
-}>, keep?: boolean) => Promise<void>;
-export declare const mockResponse: (db: DynamoDBClient, responsesTable: string) => MockResponseFn;
-export type HttpAPIMock = {
-    response: MockResponseFn;
-};
-export declare const mock: ({ db, responsesTable, }: {
-    db: DynamoDBClient;
-    responsesTable: string;
-}) => HttpAPIMock;
-export {};

package/npm/mock.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/npm/parseMockRequest.d.ts

@@ -1,7 +0,0 @@
-export declare const parseMockRequest: (r: string) => {
-    method: string;
-    resource: string;
-    protocol: string;
-    headers: Record<string, string>;
-    body: string;
-};

package/npm/parseMockRequest.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/npm/parseMockResponse.d.ts

@@ -1,6 +0,0 @@
-export declare const parseMockResponse: (r: string) => {
-    statusCode: number;
-    protocol: string;
-    headers: Record<string, string>;
-    body: string;
-};

package/npm/parseMockResponse.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/npm/randomString.d.ts

@@ -1 +0,0 @@
-export declare const randomString: () => string;

package/npm/requests.d.ts

@@ -1,13 +0,0 @@
-import { type DynamoDBClient } from '@aws-sdk/client-dynamodb';
-export type Request = {
-    path: string;
-    query: null;
-    timestamp: string;
-    ttl: string;
-    headers: Record<string, string>;
-    method: string;
-    requestId: string;
-    body: string;
-    methodPathQuery: string;
-};
-export declare const listRequests: (db: DynamoDBClient, requestsTable: string) => Promise<Request[]>;

package/npm/responses.d.ts

@@ -1,16 +0,0 @@
-import { type DynamoDBClient } from '@aws-sdk/client-dynamodb';
-export type Response = {
-    method: string;
-    path: string;
-    queryParams?: URLSearchParams;
-    statusCode?: number;
-    /**
-     * Header + Body
-     *
-     * @see splitMockResponse
-     */
-    body?: string;
-    ttl?: number;
-    keep?: boolean;
-};
-export declare const registerResponse: (db: DynamoDBClient, responsesTable: string, response: Response) => Promise<void>;

package/npm/sortQueryString.d.ts

@@ -1,3 +0,0 @@
-import { URLSearchParams } from 'node:url';
-export declare const sortQueryString: (mockUrl: string) => string;
-export declare const sortQuery: (query: Record<string, string> | URLSearchParams) => string;

package/npm/sortQueryString.spec.d.ts

@@ -1 +0,0 @@
-export {};