Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
ci(sdk): enforce and document the Node floor for SDK tests (#1844)
Yudhi Armyndharis69a87edeae4e
diff --git a/.github/workflows/js-sdk-release.yml b/.github/workflows/js-sdk-release.ymlindex 851cb9a6f..c7ce93823 100644--- a/.github/workflows/js-sdk-release.yml+++ b/.github/workflows/js-sdk-release.yml@@ -84,7 +84,8 @@ jobs:npm install -g [email protected]npm --version- - run: npm ci+ # --engine-strict: the tests below must not run on a Node the locked toolchain does not support.+ - run: npm ci --engine-strict# Same gates as SDK CI, and for the same reason Java's release runs its tests: the artifact that# reaches the registry must be the one that passed, not a rebuild nobody checked.diff --git a/.github/workflows/sdk-ci.yml b/.github/workflows/sdk-ci.ymlindex 4d4f95af2..e4e700464 100644--- a/.github/workflows/sdk-ci.yml+++ b/.github/workflows/sdk-ci.yml@@ -40,9 +40,9 @@ jobs:strategy:fail-fast: falsematrix:- # 18 is the published package's engines floor; vitest 4 needs Node 20+, so 18 only gates the- # typecheck, build and smoke (packaging plus real requests through each build's client), and- # the unit tests run on 20 and 22.+ # 18 is the published package's engines floor; vitest 4 needs Node 20.19+ or 22.12+, so 18+ # only gates the typecheck, build and smoke (packaging plus real requests through each+ # build's client), and the unit tests run on 20 and 22.node: ['18', '20', '22']defaults:run:@@ -54,7 +54,11 @@ jobs:node-version: ${{ matrix.node }}cache: 'npm'cache-dependency-path: sdk/javascript/package-lock.json- - run: npm ci+ # The lane that runs the tests installs with --engine-strict, so a locked toolchain that drops+ # its Node fails here, naming the package, instead of warning and then testing on an+ # unsupported runtime or failing at startup on a skipped native binding. The condition is the+ # test step's own.+ - run: npm ci --engine-strict=${{ matrix.node != '18' }}- run: npm testif: matrix.node != '18'# The build tsconfigs exclude test/, and vitest strips types without checking them, so thediff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4bd68b329..f855f5b78 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Changed- The JavaScript SDK CommonJS build no longer sets `moduleResolution` node10, which TypeScript 7 removed; the built output is unchanged.+- JavaScript SDK CI and release jobs install with `--engine-strict` wherever they run the tests, so an unsupported Node fails at install.- The JavaScript SDK smoke check sends requests through both built clients, so the Node 18 CI lane covers the request path.- Retire the whatsapp-web.js download-mimetype install patch; inbound media downloads now pass the mimetype themselves.- CI and the weekly security scan run `npm audit` over the JavaScript SDK, and Dependabot watches its lockfile.@@ -114,7 +115,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Dependencies- `handlebars` 4.7.9 to 4.7.10, closing two critical advisories in which a crafted template could inject JavaScript into compiled output. It reaches the root tree only through `ts-jest`, so it is dev-only and nothing that ships changes.-- `vitest` 2.1 to 4.1 in the JavaScript SDK tree, closing its dev-only advisories. Its tests now need Node 20+; the published package still supports Node 18.+- `vitest` 2.1 to 4.1 in the JavaScript SDK tree, closing its dev-only advisories. Its tests now need Node 20.19+ or 22.12+; the published package still supports Node 18.### Upgrade notes (behavior changes)diff --git a/docs/09-testing-strategy.md b/docs/09-testing-strategy.mdindex ef69907e9..1b39a50e4 100644--- a/docs/09-testing-strategy.md+++ b/docs/09-testing-strategy.md@@ -271,7 +271,7 @@ contract surfaces that SDKs mirror (`src/**/dto/**`, `src/**/*.controller.ts`, ``src/engine/interfaces/whatsapp-engine.interface.ts`), so any backend controller or service change alsore-runs the SDK suites. It runs:-- JavaScript SDK type-check, build, and dual CJS/ESM smoke test (module loading plus requests through each build's client) on Node 18 (the `engines` floor), 20 and 22, with unit tests on 20 and 22 (vitest 4 needs Node 20+).+- JavaScript SDK type-check, build, and dual CJS/ESM smoke test (module loading plus requests through each build's client) on Node 18 (the `engines` floor), 20 and 22, with unit tests on 20 and 22 (vitest 4 needs Node 20.19+ or 22.12+).- Python SDK type check with `mypy` and tests with `pytest` on Python 3.9 and 3.12.- PHP SDK tests with PHPUnit.- Java SDK tests with Maven.diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 929a73634..9ffff4c9a 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -1174,7 +1174,7 @@ The wire types live in a dedicated module (`types.ts` / `types.py`) so they can### Release process```bash-# JavaScript+# JavaScript (the tests need Node 20.19+ or 22.12+; the published package runs on Node 18+)cd sdk/javascript && npm test && npm run build && npm run smoke # smoke = require()+import() packaging plus request check# Pythoncd sdk/python && python -m pytest -qdiff --git a/sdk/javascript/scripts/smoke.mjs b/sdk/javascript/scripts/smoke.mjsindex 1c236a6d3..7ffb745d1 100644--- a/sdk/javascript/scripts/smoke.mjs+++ b/sdk/javascript/scripts/smoke.mjs@@ -31,9 +31,10 @@ for (const [format, mod] of [}}-// Request smoke: the Node 18 lane skips the unit tests (vitest 4 needs Node 20+), and the typecheck-// accepts DOM-declared globals Node 18 lacks, so send real requests through each build's client over-// the default global fetch: a parsed 2xx body, a typed error for a non-2xx, and the abort timeout.+// Request smoke: the Node 18 lane skips the unit tests (vitest 4 needs Node 20.19+ or 22.12+), and+// the typecheck accepts DOM-declared globals Node 18 lacks, so send real requests through each+// build's client over the default global fetch: a parsed 2xx body, a typed error for a non-2xx, and+// the abort timeout.const server = createServer((req, res) => {if (req.url === '/api/health') {res.writeHead(200, { 'Content-Type': 'application/json' });diff --git a/src/common/node-engine-floor.spec.ts b/src/common/node-engine-floor.spec.tsindex f93597c3e..53b94d6cc 100644--- a/src/common/node-engine-floor.spec.ts+++ b/src/common/node-engine-floor.spec.ts@@ -14,7 +14,7 @@ describe('package.json engines.node covers every installed package floor', () =>// Hoisted by the lockfile (bullmq, sharp and ts-jest depend on it); it ships no types of its own.// eslint-disable-next-line @typescript-eslint/no-require-importsconst semver = require('semver') as {- minVersion(range: string): { version: string } | null;+ minVersion(range: string): { version: string; major: number } | null;satisfies(version: string, range: string): boolean;};@@ -59,4 +59,40 @@ describe('package.json engines.node covers every installed package floor', () =>expect(unmetFloors('>=22.19', packages)).toEqual(['multi ^20.19.0 || >=24']);expect(unmetFloors('>=24', packages)).toEqual([]);});++ // The SDK's engines floor (>=18) covers the published package only; its test toolchain needs more,+ // so every place that tells a contributor which Node runs those tests must state a floor that the+ // SDK lockfile actually supports.+ it.each([+ 'docs/09-testing-strategy.md',+ 'docs/18-sdk-design.md',+ '.github/workflows/sdk-ci.yml',+ 'sdk/javascript/scripts/smoke.mjs',+ ])('%s states an SDK test floor every locked SDK package supports', file => {+ const lock = readJson<{ packages: Record<string, { optional?: boolean; engines?: unknown }> }>(+ 'sdk/javascript/package-lock.json',+ );+ // Join wrapped comment lines so a floor split across two of them is still read.+ const text = readFileSync(join(repo, file), 'utf8').replace(/\s*\n\s*(?:#|\/\/)?\s*/g, ' ');+ const statements = [...text.matchAll(/needs? Node (\d+(?:\.\d+){0,2})\+(?: or (\d+(?:\.\d+){0,2})\+)?/g)];+ expect(statements.length).toBeGreaterThan(0);+ // Guard the scan: the published floor is below the toolchain's, so a scan that read no ranges fails here.+ expect(unmetFloors('>=18', lock.packages)).not.toEqual([]);+ // "20.19+ or 22.12+" admits 20.19 on the 20 line and 22.12 on the 22 line, and every later line from+ // its first release, so the lowest release each statement admits is checked on every LTS (even) line+ // through two past the last one it names: a bare "20.19+" answers for 22.0 too.+ const lowest = statements.flatMap(([statement, ...floors]) => {+ const named = floors.filter(Boolean).map(floor => semver.minVersion(floor)!);+ const last = named[named.length - 1].major;+ const lines: [string, string][] = [];+ for (let major = named[0].major; major <= last + 2; major += 2) {+ const version = named.find(v => v.major === major)?.version ?? (major > last ? `${major}.0.0` : undefined);+ if (version) lines.push([statement, version]);+ }+ return lines;+ });+ expect(+ lowest.map(([statement, version]) => [statement, version, unmetFloors(`>=${version}`, lock.packages)]),+ ).toEqual(lowest.map(([statement, version]) => [statement, version, []]));+ });});diff --git a/src/common/release-gate-parity.spec.ts b/src/common/release-gate-parity.spec.tsindex 6bc4077e3..96ceeab1e 100644--- a/src/common/release-gate-parity.spec.ts+++ b/src/common/release-gate-parity.spec.ts@@ -178,6 +178,33 @@ describe('every npm tree is audited and kept current', () => {});});+/**+ * The SDK's engines floor (>=18) is for the published package; its test toolchain needs a newer+ * Node. npm only warns when a locked package's engines exclude the running Node, so a toolchain bump+ * that drops a lane's Node still installs there, then tests on an unsupported runtime or fails at+ * startup on an optional native binding npm skipped. Each job that runs the SDK tests installs under+ * --engine-strict on exactly the lanes the test step runs on.+ */+describe('the JavaScript SDK tests run only on a Node their toolchain supports', () => {+ it.each([+ ['sdk-ci.yml', 'javascript'],+ ['js-sdk-release.yml', 'publish'],+ ])('%s %s installs under --engine-strict wherever it runs npm test', (file, job) => {+ const steps = (+ yaml.load(fs.readFileSync(path.join(workflowDir, file), 'utf8')) as {+ jobs: Record<string, { steps: Array<{ run?: string; if?: string }> }>;+ }+ ).jobs[job].steps;+ const installs = steps.filter(step => /^npm ci\b/.test(step.run ?? ''));+ const tests = steps.filter(step => step.run === 'npm test');+ expect(installs).toHaveLength(1);+ expect(tests).toHaveLength(1);+ expect(installs[0].if).toBeUndefined();+ const gate = tests[0].if;+ expect(installs[0].run).toBe(gate ? `npm ci --engine-strict=\${{ ${gate} }}` : 'npm ci --engine-strict');+ });+});+/*** BuildKit's provenance and SBOM travel inside the image index unsigned, so nothing a user could check* tied a published image to this workflow. promote now records a signed build-provenance attestation