chore: update tooling requirements and parity checks

Author: kvz

.github/workflows/ci.yml

@@ -196,11 +196,12 @@ jobs:
       - uses: softprops/action-gh-release@v1
         with:
           draft: true
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: 22
           registry-url: https://registry.npmjs.org
-      - uses: actions/download-artifact@v4
-        with: { name: package }
-      - run: npm install -g npm@^11.5.1
-      - run: npm publish *.tgz --provenance
+      - run: corepack yarn
+      - run: corepack yarn changeset publish
+        env:
+          NPM_CONFIG_PROVENANCE: "true"

CONTRIBUTING.md

@@ -20,6 +20,10 @@ To check for updates, run:
 yarn upgrade-interactive
 ```
 
+## Tooling requirements
+
+Local tooling (the TypeScript scripts in `scripts/` and package tests) requires Node 22.18+ so `node file.ts` works without flags. The published packages still support Node 20+ at runtime.
+
 ## Linting
 
 This project is linted using Biome. You can lint the project by running:
@@ -89,7 +93,7 @@ yarn pack
 
 ## Releasing
 
-Only maintainers can make releases. Releases to [npm](https://www.npmjs.com) are automated using GitHub actions. To make a release, perform the following steps:
+Only maintainers can make releases. Releases to [npm](https://www.npmjs.com) are automated using GitHub actions and Changesets (including the legacy `transloadit` package). To make a release, perform the following steps:
 
 1. Create a changeset:
    - `yarn changeset`
@@ -101,5 +105,12 @@ Only maintainers can make releases. Releases to [npm](https://www.npmjs.com) are
 4. Publish (maintainers only; GitHub Actions handles the release):
    - `yarn changeset publish`
 5. When successful add [release notes](https://github.com/transloadit/node-sdk/releases).
-6. If this was a pre-release, remember to reset the [npm `latest` tag](https://www.npmjs.com/package/transloadit?activeTab=versions) to the previous version (replace `x.y.z` with previous version):
+6. Scoped packages publish with the `experimental` dist-tag by default. If you need to promote a scoped package to `latest`, update the tag manually.
+7. If this was a pre-release, remember to reset the [npm `latest` tag](https://www.npmjs.com/package/transloadit?activeTab=versions) to the previous version (replace `x.y.z` with previous version):
    - `npm dist-tag add [email protected] latest`
+
+### Release FAQ
+
+- **Lockstep versions:** Changesets use a fixed group, so version bumps and releases are always in lock‑step across `transloadit`, `@transloadit/node`, `@transloadit/types`, and `@transloadit/zod`.
+- **Legacy parity:** `transloadit` is generated from `@transloadit/node` artifacts via `scripts/prepare-transloadit.ts`, then verified with `yarn parity:transloadit`. Only `package.json` metadata drift is allowed; any other drift fails.
+- **Experimental packages:** Scoped packages (`@transloadit/node`, `@transloadit/types`, `@transloadit/zod`) publish with the `experimental` dist-tag. The unscoped `transloadit` package remains stable.

docs/fingerprint/transloadit-after.json

@@ -2,8 +2,8 @@
   "packageDir": "/home/kvz/code/node-sdk/packages/transloadit",
   "tarball": {
     "filename": "transloadit-4.1.2.tgz",
-    "sizeBytes": 1110479,
-    "sha256": "1f9d45a0d0055c488da28eac563ad79073cedfab16ccf7bd4e5ea9bb50cf655a"
+    "sizeBytes": 1110470,
+    "sha256": "61a25c361b18372e0e590cf3195c617ae88966e53b3217acc88e1680493cad9f"
   },
   "packageJson": {
     "name": "transloadit",
@@ -13,7 +13,10 @@
       ".": "./dist/Transloadit.js",
       "./package.json": "./package.json"
     },
-    "files": ["dist", "src"]
+    "files": [
+      "dist",
+      "src"
+    ]
   },
   "files": [
     {
@@ -613,8 +616,8 @@
     },
     {
       "path": "package.json",
-      "sizeBytes": 2648,
-      "sha256": "a2fd83a1adc245ade4d1a376c3d8c92ba286e73412afb89fa5d8ef31212f560d"
+      "sizeBytes": 2601,
+      "sha256": "18cd60ab2fb8dd2a146181d9b0965e40e42a4ee1ffa9100f812bff85bd88a185"
     },
     {
       "path": "dist/alphalib/types/robots/_index.d.ts.map",

docs/fingerprint/transloadit-baseline.package.json

@@ -0,0 +1,87 @@
+{
+  "name": "transloadit",
+  "version": "4.1.2",
+  "description": "Node.js SDK for Transloadit",
+  "type": "module",
+  "keywords": [
+    "transloadit",
+    "encoding",
+    "transcoding",
+    "video",
+    "audio",
+    "mp3"
+  ],
+  "author": "Tim Koschuetzki <[email protected]>",
+  "packageManager": "[email protected]",
+  "engines": {
+    "node": ">= 20"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.891.0",
+    "@aws-sdk/s3-request-presigner": "^3.891.0",
+    "@transloadit/sev-logger": "^0.0.15",
+    "clipanion": "^4.0.0-rc.4",
+    "debug": "^4.4.3",
+    "dotenv": "^17.2.3",
+    "form-data": "^4.0.4",
+    "got": "14.4.9",
+    "into-stream": "^9.0.0",
+    "is-stream": "^4.0.1",
+    "node-watch": "^0.7.4",
+    "p-map": "^7.0.3",
+    "p-queue": "^9.0.1",
+    "recursive-readdir": "^2.2.3",
+    "tus-js-client": "^4.3.1",
+    "type-fest": "^4.41.0",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.4",
+    "@types/debug": "^4.1.12",
+    "@types/recursive-readdir": "^2.2.4",
+    "@types/temp": "^0.9.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "badge-maker": "^5.0.2",
+    "execa": "9.6.0",
+    "image-size": "^2.0.2",
+    "nock": "^14.0.10",
+    "npm-run-all": "^4.1.5",
+    "p-retry": "^7.0.0",
+    "rimraf": "^6.1.2",
+    "temp": "^0.9.4",
+    "tsx": "4.20.5",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/transloadit/node-sdk.git"
+  },
+  "directories": {
+    "src": "./src"
+  },
+  "scripts": {
+    "check": "yarn lint:ts && yarn fix && yarn test:unit",
+    "fix:js": "biome check --write .",
+    "lint:ts": "tsc --build",
+    "fix:js:unsafe": "biome check --write . --unsafe",
+    "lint:js": "biome check .",
+    "lint": "npm-run-all --parallel 'lint:js'",
+    "fix": "npm-run-all --serial 'fix:js'",
+    "prepack": "rm -f tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && tsc --build tsconfig.build.json",
+    "test:unit": "vitest run --coverage ./test/unit",
+    "test:e2e": "vitest run ./test/e2e",
+    "test": "vitest run --coverage"
+  },
+  "license": "MIT",
+  "main": "./dist/Transloadit.js",
+  "exports": {
+    ".": "./dist/Transloadit.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "bin": "./dist/cli.js"
+}

docs/monorepo-architecture.md

@@ -38,6 +38,7 @@ node-sdk/
 - Publishes the legacy package name.
 - Built from the same runtime artifacts as `@transloadit/node`.
 - Compatibility is verified via tarball fingerprinting.
+- Allowed drift is limited to `package.json` metadata and is reported explicitly.
 
 ### @transloadit/types
 - Pure type package; no Zod runtime dependency.
@@ -84,14 +85,25 @@ The `@transloadit/zod` `check` script runs `sync`, `tsc`, and runtime parity.
 
 ## Node & TypeScript execution
 
-All internal scripts are TypeScript and run via Node 24’s erasable syntax support (no `--experimental-strip-types` in the zod package). Other packages may still use the flag where needed.
+All internal scripts are TypeScript and rely on Node’s built-in type stripping. Tooling expects Node 22.18+ (or newer) so scripts can run directly via `node script.ts` without flags.
 
 ## Publishing strategy
 
 - `@transloadit/node` is canonical.
 - `transloadit` is generated from the same artifacts and fingerprinted.
 - `@transloadit/types` and `@transloadit/zod` are versioned in lock‑step (changesets).
 
+### Parity verification
+
+The `transloadit` tarball is compared against a recorded baseline:
+
+- `scripts/fingerprint-pack.ts` creates a tarball fingerprint.
+- `scripts/verify-fingerprint.ts` compares fingerprints and reports drift.
+- `docs/fingerprint/transloadit-baseline.json` is the baseline fingerprint.
+- `docs/fingerprint/transloadit-baseline.package.json` is used to diff `package.json`.
+
+Only `package.json` metadata drift is currently allowed; any other file difference fails the check.
+
 ## Future extensions
 
 - Add JSON Schema export for v4 (`@transloadit/jsonschema` or subpath) once v4 tooling is stable.

docs/todo.md

@@ -15,8 +15,8 @@
 - [x] Hash the tarball SHA256
 - [x] Hash each file via `tar -tf` + `tar -xOf`
 - [x] Output JSON artifact for comparison
-- [x] Support `node --experimental-strip-types scripts/fingerprint-pack.ts .`
-- [x] Support `node --experimental-strip-types scripts/fingerprint-pack.ts packages/transloadit`
+- [x] Support `node scripts/fingerprint-pack.ts .`
+- [x] Support `node scripts/fingerprint-pack.ts packages/transloadit`
 
 ## Versioning and releases
 - [x] Add Changesets at workspace root

package.json

@@ -15,7 +15,8 @@
     "fix:js": "biome check --write .",
     "fix:js:unsafe": "biome check --write . --unsafe",
     "knip": "yarn workspace @transloadit/node knip",
-    "pack": "node --experimental-strip-types scripts/pack-transloadit.ts",
+    "pack": "node scripts/pack-transloadit.ts",
+    "parity:transloadit": "node scripts/fingerprint-pack.ts packages/transloadit --ignore-scripts --out /tmp/transloadit-after.json && node scripts/verify-fingerprint.ts --current /tmp/transloadit-after.json --baseline docs/fingerprint/transloadit-baseline.json --allow package.json --baseline-package-json docs/fingerprint/transloadit-baseline.package.json --current-package-json packages/transloadit/package.json",
     "test:unit": "yarn workspace @transloadit/node test:unit && yarn workspace @transloadit/types test:unit && yarn workspace @transloadit/zod test:unit",
     "test:e2e": "yarn workspace @transloadit/node test:e2e",
     "test": "yarn workspace @transloadit/node test"

packages/node/README.md

@@ -1,6 +1,9 @@
 [![Build Status](https://github.com/transloadit/node-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/transloadit/node-sdk/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/transloadit/node-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/transloadit/node-sdk)
 
+> **Stability: Experimental.** This scoped package is new and may change without notice.  
+> For the stable SDK, use the unscoped `transloadit` package.
+
 <a href="https://transloadit.com/?utm_source=github&utm_medium=referral&utm_campaign=sdks&utm_content=node_sdk">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://assets.transloadit.com/assets/images/sponsorships/logo-dark.svg">

packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transloadit/node",
-  "version": "4.1.3",
+  "version": "4.1.2",
   "description": "Node.js SDK for Transloadit",
   "type": "module",
   "keywords": ["transloadit", "encoding", "transcoding", "video", "audio", "mp3"],
@@ -29,6 +29,9 @@
     "type-fest": "^4.41.0",
     "zod": "3.25.76"
   },
+  "publishConfig": {
+    "tag": "experimental"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.3.11",
     "@types/debug": "^4.1.12",

packages/node/src/InconsistentResponseError.ts

@@ -1,3 +1,3 @@
-export class InconsistentResponseError extends Error {
+export default class InconsistentResponseError extends Error {
   override name = 'InconsistentResponseError'
 }