Multi-package setup: types/zod + legacy wrapper (#277)

* Add multi-package proposal and fingerprint script

* Update proposal for zod3 and types strategy

* Refine proposal for zod versioning and type generation

* Add type generation scaffold and equality check

* chore: monorepo structure and fingerprinting

* chore: align types version with node and transloadit

* chore: add changeset for monorepo alignment

* chore: version packages with changesets

* docs: add cross-repo schema validation todo

* docs: mark cross-repo schema validation complete

* chore: sync transloadit wrapper packaging

* fix: align codecov path and schema exports

* fix: pack job and types exports

* refactor: unify pack flow and exports

* docs: add dual zod v3/v4 generation plan

* chore(zod): add v4 sync and parity checks

* docs: rename plan and harden zod fixtures

* test: guard zod export parity

* test: add assembly status parity fixtures

* chore: slim transloadit pack output

* docs: note legacy transloadit packaging

* fix: stabilize e2e tooling paths

* chore: expand yarn check scope

* fix: harden zod scripts and tooling

* fix: normalize type export paths

* fix: guard zod sync patching

* docs(ci): note Node 24 requirement for root tests

* chore: update tooling requirements and parity checks

* chore: apply yarn check formatting

* fix: restore biome and sync before zod tests

* chore: update yarn.lock

* Fix Biome lint after yarn install

* Consolidate toolchain devDependencies

* Run knip from yarn check

* Run knip across workspaces

* Add root knip dep scripts

* Run knip deps check in CI

* Add CI checks for parity and zod types

* Refine verify scripts and CI wiring

* Fix CI types build and CLI bin naming

* Sync zod sources before typecheck

* Release patch versions

* Align transloadit bin entry

Author: kvz

.ai/AGENTS.md

@@ -4,9 +4,9 @@ This document serves as a quick reference for agentic coding assistants working
 
 ## Check your work
 
-After making changes, always run `corepack yarn check`, this lints with typescript, formats code,
-and runs quick unit tests. Remember that this formats code and may make changes, that you are to
-commit if you were working on those files.
+After making changes, always run `corepack yarn check`, which runs Knip (with fixes/removals),
+lints TypeScript, formats code, and runs quick unit tests. Remember that Knip and formatting may
+make changes that you must review and commit when you touched the affected files.
 
 ## When running in GitHub Actions
 

.changeset/README.md

@@ -0,0 +1,3 @@
+# Changesets
+
+Run `yarn changeset` to add a release note for your change.

.changeset/config.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": [
+    "@changesets/cli/changelog",
+    {
+      "repo": "transloadit/node-sdk"
+    }
+  ],
+  "commit": false,
+  "fixed": [["@transloadit/node", "transloadit", "@transloadit/types", "@transloadit/zod"]],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/ci.yml

@@ -21,44 +21,33 @@ jobs:
         with:
           node-version: 22
       - run: corepack yarn
-      - run: corepack yarn pack
+      - run: corepack yarn run pack
       - uses: actions/upload-artifact@v4
         with:
           name: package
           path: '*.tgz'
 
-  biome:
-    name: Lint (Biome)
+  verify:
+    name: Verify (fast)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
-      - run: corepack yarn
-      - run: corepack yarn lint:js
-
-  knip:
-    name: Knip
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
+          node-version: 24
       - run: corepack yarn
-      - run: corepack yarn knip
+      - run: corepack yarn verify
 
-  typescript:
-    name: Lint (TypeScript)
+  verify-full:
+    name: Verify (full)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
       - run: corepack yarn
-      - run: corepack yarn lint:ts
+      - run: corepack yarn verify:full
 
   unit:
     name: Unit tests (Node ${{ matrix.node }})
@@ -75,13 +64,18 @@ jobs:
         with:
           node-version: ${{ matrix.node }}
       - run: corepack yarn
+      # Root unit tests execute TypeScript scripts via Node's strip-types support.
+      # Keep those on Node 24+; Node 20/22 only run @transloadit/node unit tests.
       - run: corepack yarn test:unit
+        if: matrix.node == 24
+      - run: corepack yarn workspace @transloadit/node test:unit
+        if: matrix.node != 24
       - name: Upload coverage reports artifact
         if: matrix.node == 24
         uses: actions/upload-artifact@v4
         with:
           name: coverage-reports
-          path: coverage/
+          path: packages/node/coverage/
 
   e2e:
     name: E2E tests
@@ -111,14 +105,14 @@ jobs:
           TRANSLOADIT_KEY: ${{ secrets.TRANSLOADIT_KEY }}
           TRANSLOADIT_SECRET: ${{ secrets.TRANSLOADIT_SECRET }}
           NODE_OPTIONS: --trace-deprecation --trace-warnings
-          CLOUDFLARED_PATH: ./cloudflared-linux-amd64
+          CLOUDFLARED_PATH: ${{ github.workspace }}/cloudflared-linux-amd64
           DEBUG: 'transloadit:*'
 
       - name: Generate the badge from the json-summary
-        run: node --experimental-strip-types test/generate-coverage-badge.ts coverage/coverage-summary.json
+        run: node --experimental-strip-types packages/node/test/generate-coverage-badge.ts packages/node/coverage/coverage-summary.json
       - name: Move HTML report and badge to the correct location
         run: |
-          mv coverage/lcov-report static-build
+          mv packages/node/coverage/lcov-report static-build
           mv coverage-badge.svg static-build/
       # *** BEGIN PUBLISH STATIC SITE STEPS ***
       # Use the standard checkout action to check out the destination repo to a separate directory
@@ -180,8 +174,8 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - pack
-      - biome
-      - typescript
+      - verify
+      - verify-full
       - unit
     if: startsWith(github.ref, 'refs/tags/')
     permissions:
@@ -191,11 +185,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"

.gitignore

@@ -8,6 +8,7 @@ sample.js
 npm-debug.log
 env.sh
 /coverage
+packages/node/coverage
 
 .pnp.*
 .yarn/*
@@ -19,3 +20,10 @@ env.sh
 .aider*
 .DS_Store
 .env
+packages/types/src/generated
+packages/zod/src/v3
+packages/zod/src/v4
+packages/transloadit/src
+packages/transloadit/README.md
+packages/transloadit/CHANGELOG.md
+packages/transloadit/LICENSE

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:
@@ -79,19 +83,34 @@ Coverage reports are:
 
 View the coverage report locally by opening `coverage/index.html` in your browser.
 
-## Releasing
+## Packaging the legacy `transloadit` package
 
-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:
+The `packages/transloadit` folder is a generated legacy wrapper. The `src` directory and top-level `README.md`, `CHANGELOG.md`, and `LICENSE` are produced during packing by `scripts/prepare-transloadit.ts` and are not tracked in git. If you need to validate the legacy package contents, run:
 
-1. Update `CHANGELOG.md` with a new entry describing the release. And `git add CHANGELOG.md && git commit -m "Update CHANGELOG.md"`.
-2. Update the version using npm. This will update the version in the `package.json` file and create a git tag. E.g.:
+```sh
+yarn pack
+```
 
-- `npm version patch`
-- OR, for pre-releases: `npm version prerelease`
+## Releasing
 
-3. Push the tag to GitHub: `git push origin main --tags`
-4. If the tests pass, GitHub actions will now publish the new version to npm.
+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`
+2. Version packages (updates `CHANGELOG.md` + workspace `package.json` files):
+   - `yarn changeset version`
+   - `git add -A && git commit -m "chore: version packages"`
+3. Push the version commit and tags:
+   - `git push origin main`
+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 run this 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 transloadit@X.Y.Z latest`
+
+### Release FAQ
 
-- `npm dist-tag add transloadit@X.Y.Z latest`
+- **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.

biome.json

@@ -1,16 +1,19 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
   "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
   "files": {
     "ignoreUnknown": false,
     "includes": [
       "**",
       "!package.json",
       "!coverage",
+      "!**/coverage",
       "!dist",
       "!fixture",
       "!.vscode",
-      "!src/alphalib"
+      "!packages/**/dist",
+      "!packages/**/node_modules",
+      "!packages/node/src/alphalib"
     ]
   },
   "formatter": {
@@ -93,6 +96,10 @@
     "actions": { "source": { "organizeImports": "on" } }
   },
   "overrides": [
+    {
+      "includes": ["**/package.json"],
+      "formatter": { "expand": "always" }
+    },
     {
       "includes": ["*.html"],
       "javascript": { "formatter": { "quoteStyle": "double" } }