Merge: remove parse-link-header, raise Node floor to 24

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: kadamwhite

.github/workflows/ci.yml

@@ -6,16 +6,12 @@ on:
   pull_request:
 
 jobs:
-  # tsdown/rolldown require Node >=22.18 to run; vitest requires >=20. The
-  # published library itself only requires Node >=18 (see `engines` in
-  # package.json) — that promise is checked separately by `dist-smoke` below,
-  # against the pre-built output, without needing the build tooling to run.
   test:
     name: Lint, typecheck, build & unit test (Node ${{ matrix.node-version }})
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [ 22, 24, latest ]
+        node-version: [ 24, latest ]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -34,13 +30,16 @@ jobs:
           path: dist
           retention-days: 1
 
+  # Smokes the built artifact under a production-only install (no devDependencies),
+  # which the test job above cannot catch: it verifies dist/ is self-contained and
+  # requires nothing outside the declared runtime dependencies.
   dist-smoke:
     name: Published dist works on Node ${{ matrix.node-version }}
     runs-on: ubuntu-latest
     needs: test
     strategy:
       matrix:
-        node-version: [ 18, 20 ]
+        node-version: [ 24 ]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -79,7 +78,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
       - run: npm ci
       - run: npm run env:start

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## v2.0.0 [**unreleased**] _Second Toughest in the Infants_
 - **BREAKING**: "Node-style" error-first callbacks (_e.g._ `.get( ( err, data ) => {} )`) are no longer supported. All transport request methods return Promises.
-- **BREAKING**: The minimum supported Node.js version is now v18; Internet Explorer is no longer supported.
+- **BREAKING**: The minimum supported Node.js version is now v24; Internet Explorer is no longer supported.
 - **BREAKING**: HTTP requests are made with the native `fetch` API. The superagent transport and the `wpapi/superagent` entrypoint introduced in the v2 alphas are removed; the default `wpapi` export makes HTTP requests out of the box again, with no additional dependencies. `wpapi/fetch` remains as an alias for the default export.
 - **BREAKING**: Media uploads use native `FormData`/`Blob`. `.file()` accepts a file path (Node), a `Buffer` or `Blob` plus a file name, or a `File` object; streams are no longer supported. The multipart part's content type is no longer inferred from the file name (WordPress determines the type server-side from the name); pass a `Blob` or `File` with an explicit `type` to control it.
 - **BREAKING**: Autodiscovery now either succeeds or fails; a WPAPI instance configured with default routes will no longer be returned.

README.md

@@ -62,7 +62,7 @@ const WPAPI = require( 'wpapi' );
 import WPAPI from 'wpapi';
 ```
 
-HTTP requests are made with the `fetch` API built into Node 18+, browsers and other modern JavaScript runtimes, so no other dependencies are required. This library is designed to work in the browser as well, via a build system such as Vite or Webpack; just install the package and import it from your application code.
+HTTP requests are made with the `fetch` API built into Node.js (v24 or later is required), browsers and other modern JavaScript runtimes, so no other dependencies are required. This library is designed to work in the browser as well, via a build system such as Vite or Webpack; just install the package and import it from your application code.
 
 ### Download the UMD Bundle
 

fetch/README.md

@@ -7,8 +7,8 @@ provides; the subpath remains as an alias for code written against the v2 alphas
 ## Installation & Usage
 
 Install `wpapi` using the command `npm install --save wpapi`. No separate fetch
-implementation is needed — the library uses the `fetch` global built into Node 18+,
-browsers and other modern JavaScript runtimes.
+implementation is needed — the library uses the `fetch` global built into Node.js
+(v24+), browsers and other modern JavaScript runtimes.
 
 ```js
 import WPAPI from 'wpapi/fetch';

fetch/fetch-transport.ts

@@ -205,10 +205,10 @@ const createUploadForm = async (
 	}
 
 	const form = new FormData();
-	// An undefined name must be genuinely omitted, not passed as an explicit third
-	// argument: FormData coerces a present-but-undefined filename to the string
-	// "undefined" on Node 18-22, clobbering a File attachment's own name. (Node 24+
-	// treats a trailing undefined as absent, which masked this in local dev.)
+	// An undefined name is genuinely omitted rather than passed as an explicit third
+	// argument: some FormData implementations (Node <=22 among them) coerce a
+	// present-but-undefined filename to the string "undefined", clobbering a File
+	// attachment's own name, and browser bundles run on engines we don't control.
 	// Cast: by this point `file` is always a Blob at runtime (the `string` and
 	// `Buffer` cases above always reassign it to one), but TS can't prove the
 	// `globalThis.Buffer &&`-guarded branch always narrows away `Buffer`.

handoff.md

@@ -65,23 +65,34 @@ the exportless superagent stub (emits `export {}` — correct).
 Main's CI Node 22 leg had been red since the Phase 2 merge, unnoticed
 (local dev runs Node 24). Cause: `FormData#append( name, file, undefined )`
 with an explicit third argument coerces the filename to the string
-`"undefined"` on Node 18-22, clobbering a File attachment's own name;
+`"undefined"` on Node <=22, clobbering a File attachment's own name;
 Node 24+ treats a trailing undefined as absent. Fixed in fetch-transport's
-`createUploadForm` by omitting the argument when there is no name override.
-Lesson: run the transport suite under the oldest CI Node before merging
-transport changes (`nvm exec 22 npx vitest run fetch/tests/unit`).
+`createUploadForm` by omitting the argument when there is no name override
+(kept after the Node 24 floor bump: explicit omission also protects
+browser-bundle consumers on engines we don't control). Lesson: run the
+transport suite under the oldest supported Node before merging transport
+changes.
+
+### Node floor raised to 24 (post-Phase 3)
+
+`engines.node >=24`; CI test matrix is 24/latest, integration and
+dist-smoke run on 24 (dist-smoke retained for its production-only-install
+check of the built artifact, not for old-Node coverage). `@types/node@^24`.
+Newly unlocked, not yet used (candidates for Phase 4+): `File` global and
+`instanceof File` checks, `fs.openAsBlob()` to stream path uploads instead
+of buffering whole files, raising tsconfig `target` beyond es2020.
 
 ### Dependency notes
 
-- Added `@types/node@^20` (vitest 4's peer floor; the published runtime
-  floor is still Node 18 — types won't catch Node 19/20-only API use, so
-  keep runtime code 18-safe; CI dist-smoke on 18 covers require-ability
-  only), `@types/qs`, and an ambient `types/li.d.ts` (li has no published
-  types).
-- `parse-link-header` is a declared runtime dependency that nothing
-  imports (pagination uses `li`). Candidate for removal — human call.
-- The Dependabot alert (1 high) noted after the Phase 2 push is still
-  unaddressed and unrelated to this phase.
+- `parse-link-header` removed — it was dead weight since Dec 2018 (commit
+  4bf3a31 switched pagination back to `li` for bundle size but never
+  dropped it from package.json), and it was the repo's 1-high Dependabot
+  alert (runtime scope), now resolved.
+- `@types/qs` and an ambient `types/li.d.ts` added in Phase 3 (li has no
+  published types).
+- `npm audit` still reports 4 high in dev-only paths, all under
+  `jsdoc@3.6` (linkify-it, taffydb) — goes away when Phase 6 replaces
+  jsdoc with TypeDoc.
 
 ## Dev workflow
 
@@ -105,8 +116,9 @@ npm run test:integration
   rolldown trap above).
 - **One tsdown config per Node entry, each bundling its full closure** (a
   shared chunk breaks rolldown's CJS `module.exports` codegen).
-- **Build tooling needs Node 22+**; published dist supports 18+ (CI
-  dist-smoke checks that separately).
+- **Node 24+ everywhere** since the floor bump: runtime, build tooling,
+  and CI all share the same floor (this retired the old split where dist
+  supported 18+ but the toolchain needed 22+).
 - **Integration tests share one wp-env DB**: keep `--no-file-parallelism`.
 
 ## Known gap (deferred to Phase 5)

lib/constructors/wp-request.ts

@@ -626,9 +626,9 @@ class WPRequest {
 			}
 			// Uploads need a file name with an extension for WordPress to accept them, and
 			// raw data objects carry none of their own; require one rather than fail obscurely.
-			// A Blob is checked for a name property rather than a File instanceof because the
-			// File global does not exist on Node 18. (Blob's type has no `.name`, hence the
-			// cast: the check is a runtime duck-type test for a File masquerading as a Blob.)
+			// A Blob is checked for a name property rather than a File instanceof so that any
+			// Blob-like object carrying its own name is accepted, File instances included.
+			// (Blob's type has no `.name`, hence the cast for the duck-type test.)
 			if ( ! name && ( isBuffer || ( isBlob && typeof ( file as { name?: unknown } ).name !== 'string' ) ) ) {
 				throw new Error( '.file(): File name is a required argument when uploading a Buffer or Blob' );
 			}

package-lock.json

@@ -23,7 +23,7 @@
     "wordpress"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "scripts": {
     "build": "rimraf dist && tsdown && node build/scripts/finalize-dist.js",
@@ -55,12 +55,11 @@
   },
   "dependencies": {
     "li": "^1.3.0",
-    "parse-link-header": "^1.0.1",
     "qs": "^6.7.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
-    "@types/node": "^20.19.43",
+    "@types/node": "^24.13.3",
     "@types/qs": "^6.15.1",
     "@vitest/coverage-v8": "^4.1.10",
     "combyne": "^2.0.0",