Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
/**
* `docs/06-api-specification.md` is the reference a REST consumer reads when there is no SDK — curl,
* Postman, n8n. It restates the published contract by hand, and nothing bound the two, so operations
* shipped without ever reaching it: `GET`/`PATCH /api/sessions/{id}/config` are implemented by all
* five SDKs and documented only in `docs/05`, and the integration redrive route was documented
* nowhere at all.
*
* This gate compares the document's route headings to `openapi.json` in both directions. An
* operation added without a heading, a heading left behind after a route is renamed, and a stale
* allowlist entry all fail here.
*
* Operations deliberately documented in another file carry an allowlist entry naming that file, and
* the gate reads the file to confirm the path is really there — otherwise "documented in docs/25"
* would be an unchecked claim, which is the exact failure this gate exists to prevent.
*/
describe('docs/06 matches the published contract', () => {
const REPO = join(__dirname, '..', '..', '..');
const read = (...parts: string[]): string => readFileSync(join(REPO, ...parts), 'utf8');
const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
/** The contract writes `{id}`, the prose writes `:id`. Normalise both to `:id`. */
const normalise = (path: string): string => path.replace(/\{(\w+)\}/g, ':$1').replace(/\/+$/, '');
/**
* A path with its parameter segments collapsed. Used only for the allowlist backing check: the
* contract names a segment `{path}` where docs/25 names the same segment `:route`, and a parameter
* name is a documentation choice rather than part of the route's identity.
*/
const shape = (path: string): string =>
path
.split('/')
.map(segment => (segment.startsWith(':') || segment.startsWith('{') ? ':*' : segment))
.join('/');
const contractOperations = (): Set<string> => {
const spec = JSON.parse(read('openapi.json')) as { paths: Record<string, Record<string, unknown>> };
const operations = new Set<string>();
for (const [path, item] of Object.entries(spec.paths)) {
for (const method of Object.keys(item)) {
if (METHODS.includes(method)) operations.add(`${method.toUpperCase()} ${normalise(path)}`);
}
}
return operations;
};
const documentedHeadings = (): Set<string> =>
new Set(
[...read('docs', '06-api-specification.md').matchAll(/^#### (GET|POST|PUT|PATCH|DELETE) (\S+)/gm)].map(
match => `${match[1]} ${normalise(match[2])}`,
),
);
/**
* Operations deliberately documented in another file carry an allowlist entry naming that file, and
* the gate reads the file to confirm the path is really there — otherwise "documented in docs/25"
* would be an unchecked claim, which is the exact failure this gate exists to prevent.
*
* The set is EMPTY today: every operation the contract publishes carries its own heading in
* docs/06 (the session-config routes and the integration instance/ingress family moved in from
* docs/05 and docs/25, which keep their design-level treatment). The mechanism stays for a future
* deliberate exception — an entry is honored only while the named file really contains the path
* and docs/06 has no heading for it, and the stale-entry test below retires it automatically.
*/
const DOCUMENTED_ELSEWHERE = new Map<string, string>([]);
/**
* Headings with no contract operation, and why the contract cannot carry them. `POST /mcp` is
* mounted on raw Express outside Nest, so the Swagger scanner never sees it.
*/
const NOT_IN_CONTRACT = new Set(['POST /mcp']);
/** True when `file` contains a path of the same shape as `operation`. */
const backs = (file: string, operation: string): boolean => {
const wanted = shape(operation.slice(operation.indexOf(' ') + 1));
const body = read(...file.split('/'));
return [...body.matchAll(/\/api\/[A-Za-z0-9:{}_\-/]+/g)].some(match => shape(normalise(match[0])) === wanted);
};
/** Contract operations with neither a docs/06 heading nor an allowlist entry. */
const undocumentedOf = (operations: Set<string>, headings: Set<string>): string[] =>
[...operations].filter(operation => !headings.has(operation) && !DOCUMENTED_ELSEWHERE.has(operation)).sort();
it('documents every contract operation, or allowlists it to a file that really documents it', () => {
const operations = contractOperations();
const headings = documentedHeadings();
expect(operations.size).toBeGreaterThan(150);
expect(headings.size).toBeGreaterThan(150);
expect(undocumentedOf(operations, headings)).toEqual([]);
});
it('every allowlisted operation is really documented in the file it names', () => {
const unbacked = [...DOCUMENTED_ELSEWHERE]
.filter(([operation, file]) => !backs(file, operation))
.map(([operation, file]) => `${operation} claims ${file}, which does not contain that path`);
expect(unbacked).toEqual([]);
});
it('has no heading for a route the contract no longer publishes', () => {
const operations = contractOperations();
const stale = [...documentedHeadings()]
.filter(heading => !operations.has(heading) && !NOT_IN_CONTRACT.has(heading))
.sort();
expect(stale).toEqual([]);
});
it('has no stale allowlist entry', () => {
const operations = contractOperations();
const headings = documentedHeadings();
const stale = [...DOCUMENTED_ELSEWHERE.keys()]
.filter(operation => !operations.has(operation) || headings.has(operation))
.sort();
expect(stale).toEqual([]);
});
/**
* Route-specific status codes must be restated per operation, not left to §6.2's generic table.
* `400`/`401`/`403`/`404` are universal (every route can answer them via validation, auth, role
* and existence guards) and stay covered by the General Error Codes table; the codes below only
* appear on routes that deliberately declare them, so a consumer reading the section for retry
* and engine-support logic must see them there. This closed a drift where 409 was missing from
* 82 sections, 503 from 47 and 501 from 16 while the contract declared all of them.
*/
const ROUTE_SPECIFIC_CODES = new Set(['409', '413', '415', '422', '429', '501', '502', '503']);
const readContract = () =>
JSON.parse(read('openapi.json')) as {
paths: Record<string, Record<string, { responses?: Record<string, unknown> }>>;
};
/** The status codes each operation's `**Errors:**` block names, keyed like the contract operations. */
const documentedErrors = (): Map<string, string[]> => {
const doc = read('docs', '06-api-specification.md');
// Slice the document into per-heading sections so each Errors line is matched to its operation.
const headings = [...doc.matchAll(/^#### (GET|POST|PUT|PATCH|DELETE) (\S+)$/gm)];
const errorsOf = new Map<string, string[]>();
for (let i = 0; i < headings.length; i++) {
const key = `${headings[i][1]} ${normalise(headings[i][2])}`;
const body = doc.slice(headings[i].index, (headings[i + 1] ?? { index: doc.length }).index);
// An Errors block may wrap across physical lines (long route-specific descriptions); join the
// block until the first blank line or next heading so codes on continuation lines count too.
const blockLines: string[] = [];
let capturing = false;
for (const raw of body.split('\n')) {
if (/^\*\*Errors:\*\*/.test(raw)) capturing = true;
else if (capturing && (raw.trim() === '' || /^#{2,4} /.test(raw))) break;
if (capturing) blockLines.push(raw);
}
const line = blockLines.join('\n');
errorsOf.set(key, [...new Set([...line.matchAll(/`(\d{3})`/g)].map(match => match[1]))]);
}
return errorsOf;
};
it('documents every route-specific status code the contract declares for the operation', () => {
const spec = readContract();
const errorsOf = documentedErrors();
const missing: string[] = [];
let checked = 0;
for (const [path, item] of Object.entries(spec.paths)) {
for (const method of METHODS) {
if (!item[method]) continue;
const key = `${method.toUpperCase()} ${normalise(path)}`;
const declared = Object.keys(item[method].responses ?? {}).filter(code => ROUTE_SPECIFIC_CODES.has(code));
if (declared.length === 0) continue;
checked++;
const documented = errorsOf.get(key) ?? [];
for (const code of declared) {
if (!documented.includes(code)) missing.push(`${key} misses ${code}`);
}
}
}
// Non-vacuity: the contract declares route-specific codes on a large share of the surface.
expect(checked).toBeGreaterThan(80);
expect(missing).toEqual([]);
});
/**
* The reverse direction: a code the section promises must be one the contract declares, or a
* generated client and the published schema disagree with the prose about what the route answers.
* `415`/`429`/`500`/`503` can come from any route (compressed body, rate limiter, unexpected
* error, body budget or a dependency not ready) and `400`/`404` are the universal validation and
* existence answers, so the General Error Codes table covers them and a section may restate them
* without the operation declaring them.
*/
const UNDECLARED_ALLOWED = new Set(['400', '404', '415', '429', '500', '503']);
it('declares in the contract every status code the section documents', () => {
const spec = readContract();
const undeclared: string[] = [];
let checked = 0;
for (const [key, codes] of documentedErrors()) {
const [method, path] = key.split(' ');
const operation = Object.entries(spec.paths).find(([candidate]) => normalise(candidate) === path)?.[1][
method.toLowerCase()
];
if (!operation) continue;
for (const code of codes) {
if (UNDECLARED_ALLOWED.has(code)) continue;
checked++;
if (!operation.responses?.[code]) undeclared.push(`${key} documents ${code}`);
}
}
// Non-vacuity: nearly every section names its auth and conflict answers.
expect(checked).toBeGreaterThan(400);
expect(undeclared.sort()).toEqual([]);
});
// The gate's own controls. Without these, a matcher that silently stops working is
// indistinguishable from a document that is correct.
describe('the checks themselves can fail', () => {
it('reports an operation with neither a heading nor an allowlist entry', () => {
const operations = contractOperations();
const headings = documentedHeadings();
const [victim] = [...operations];
headings.delete(victim);
expect(undocumentedOf(operations, headings)).toEqual([victim]);
});
it('reports an allowlist entry whose file does not contain the path', () => {
expect(backs('docs/05-database-design.md', 'GET /api/nowhere/:id')).toBe(false);
});
it('accepts a documenting file that spells the parameter differently', () => {
// docs/25 writes `:route` where the contract writes `{path}`.
expect(backs('docs/25-integration-fabric.md', 'GET /api/ingress/:pluginId/:instanceId/:path')).toBe(true);
});
});
});