feat!: modernize for Node 24, ESM, TypeScript, Yarn 4

.changeset/config.json

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

.changeset/major-modernization.md

@@ -0,0 +1,11 @@
+---
+"transloadit-notify-url-proxy": major
+---
+
+Modernize the package with breaking runtime and tooling changes:
+
+- switch to ESM and TypeScript source in `src/`
+- require Node.js 24+ with native TypeScript execution
+- add CLI bin entrypoint (`notify-url-proxy`)
+- replace deprecated dependencies (`request`, `underscore`) with native APIs
+- migrate project tooling to Yarn 4, Biome, Vitest, GitHub Actions, and Changesets

.env.example

@@ -0,0 +1,6 @@
+TRANSLOADIT_KEY=your-key
+TRANSLOADIT_SECRET=your-secret
+# Optional (defaults to https://api2.transloadit.com)
+TRANSLOADIT_ENDPOINT=https://api2.transloadit.com
+# Optional (0-8 or emerg/alert/crit/err/warn/notice/info/debug/trace)
+TRANSLOADIT_LOG_LEVEL=info

.github/workflows/ci.yml

@@ -0,0 +1,103 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Lint + Typecheck + Unit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Changeset policy (PR only)
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request
+            const labels = (pr.labels || []).map((label) => label.name)
+            const hasBypassLabel = labels.includes('no-changeset') || labels.includes('skip-changeset')
+
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr.number,
+              per_page: 100,
+            })
+
+            const touchesReleaseSurface = files.some((file) =>
+              /^src\/|^bin\/|^package\.json$|^README\.md$/.test(file.filename),
+            )
+
+            const hasChangeset = files.some((file) =>
+              file.filename.startsWith('.changeset/') &&
+              file.filename.endsWith('.md') &&
+              file.filename !== '.changeset/README.md',
+            )
+
+            if (touchesReleaseSurface && !hasChangeset && !hasBypassLabel) {
+              core.setFailed(
+                'This PR changes package behavior/release surface. Add a changeset or apply the no-changeset/skip-changeset label.',
+              )
+              return
+            }
+
+            core.info('Changeset policy passed.')
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: corepack enable
+      - run: yarn install --immutable
+      - run: yarn check
+
+  real-e2e:
+    name: Real API E2E (trusted runs)
+    if: >
+      github.event_name != 'pull_request' ||
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    needs:
+      - check
+    env:
+      TRANSLOADIT_KEY: ${{ secrets.TRANSLOADIT_KEY }}
+      TRANSLOADIT_SECRET: ${{ secrets.TRANSLOADIT_SECRET }}
+      TRANSLOADIT_ENDPOINT: ${{ secrets.TRANSLOADIT_ENDPOINT }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: corepack enable
+      - run: yarn install --immutable
+      - name: Skip if secrets are not configured
+        if: env.TRANSLOADIT_KEY == '' || env.TRANSLOADIT_SECRET == ''
+        run: echo "Skipping real E2E; TRANSLOADIT_KEY/TRANSLOADIT_SECRET are not configured."
+      - name: Run real API E2E
+        if: env.TRANSLOADIT_KEY != '' && env.TRANSLOADIT_SECRET != ''
+        run: yarn test:real
+
+  pack:
+    name: Package Smoke Test
+    runs-on: ubuntu-latest
+    needs:
+      - check
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: corepack enable
+      - run: yarn install --immutable
+      - run: yarn pack
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package
+          path: '*.tgz'

.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: Changesets Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - run: npm install -g npm@11.5.1
+      - run: corepack enable
+      - run: corepack yarn
+      - uses: changesets/action@v1
+        with:
+          version: corepack yarn changeset version
+          publish: corepack yarn changeset publish
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: 'true'
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -14,9 +14,22 @@ _bundle/
 
 env.*.sh
 env.sh
+.env
+.env.*
+!.env.example
 node_modules/
 node-flame.htm
 node-flame.svg
 npm-debug.log
 npm-debug.log*
 tmp/
+
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+.pnp.*
+coverage/
+dist/

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

README.md

@@ -1,5 +1,125 @@
-# notify-url-proxy
-Allows testing your notify_url locally.
+# transloadit-notify-url-proxy
 
+Local `notify_url` proxy for Transloadit assemblies.
 
-This project is heavily inspired by the work from @substantial's [node-transloadit-development_notify_url_proxy](https://github.com/substantial/node-transloadit-development_notify_url_proxy) project.
+This version is modernized for:
+
+- Node.js 24+
+- Native TypeScript execution (type stripping)
+- ESM
+- Yarn 4
+- Biome + Vitest + GitHub Actions + Changesets
+
+Notify payloads are signed via `@transloadit/utils` using prefixed `sha384` signatures.
+Forwarding uses native `fetch`, polling retries use `p-retry`, and logs are emitted via `@transloadit/sev-logger`.
+Metrics hooks are available for counters, gauges, and timings.
+
+## Install
+
+```bash
+yarn add transloadit-notify-url-proxy
+```
+
+## CLI usage
+
+```bash
+export TRANSLOADIT_SECRET="your-secret"
+
+notify-url-proxy \
+  --notifyUrl "http://127.0.0.1:3000/transloadit" \
+  --port 8888 \
+  --notifyOnTerminalError \
+  --log-level info
+```
+
+Run `notify-url-proxy --help` for all options.
+
+Log level accepts `0-8` or names:
+`emerg`, `alert`, `crit`, `err`, `warn`, `notice`, `info`, `debug`, `trace`.
+You can also set `TRANSLOADIT_LOG_LEVEL`.
+
+### Reactive TUI Mode
+
+```bash
+notify-url-proxy --ui --log-level info
+```
+
+This opens a live terminal dashboard with:
+
+- throughput and retry counters
+- in-flight queue gauges
+- latency sparklines
+- streaming logs
+
+## Programmatic usage
+
+```ts
+import TransloaditNotifyUrlProxy from 'transloadit-notify-url-proxy';
+
+const proxy = new TransloaditNotifyUrlProxy(
+  process.env.TRANSLOADIT_SECRET ?? '',
+  'http://127.0.0.1:3000/transloadit'
+);
+
+proxy.run({
+  port: 8888,
+  target: 'https://api2.transloadit.com',
+  forwardTimeoutMs: 15000,
+  pollIntervalMs: 2000,
+  pollMaxIntervalMs: 30000,
+  pollBackoffFactor: 2,
+  pollRequestTimeoutMs: 15000,
+  maxPollAttempts: 10,
+  maxInFlightPolls: 4,
+  notifyOnTerminalError: false,
+  notifyTimeoutMs: 15000,
+  notifyMaxAttempts: 3,
+  notifyIntervalMs: 500,
+  notifyMaxIntervalMs: 5000,
+  notifyBackoffFactor: 2
+});
+```
+
+## Development
+
+```bash
+corepack enable
+yarn install
+
+yarn lint
+yarn typecheck
+yarn test
+yarn test:real
+yarn check
+```
+
+## Real API E2E
+
+Run an opt-in test against the real Transloadit API (default `yarn test` excludes this test):
+
+```bash
+# set locally (for example in .env)
+export TRANSLOADIT_KEY="your-key"
+export TRANSLOADIT_SECRET="your-secret"
+# optional
+export TRANSLOADIT_ENDPOINT="https://api2.transloadit.com"
+
+yarn test:real
+```
+
+For CI, configure repository secrets:
+
+- `TRANSLOADIT_KEY`
+- `TRANSLOADIT_SECRET`
+- `TRANSLOADIT_ENDPOINT` (optional)
+
+## Releases
+
+Changesets drives releases:
+
+```bash
+yarn changeset
+yarn changeset:version
+```
+
+On pushes to `main`, `.github/workflows/release.yml` runs `changesets/action` to publish.