|
| 1 | +# @transloadit/notify-url-relay |
| 2 | + |
| 3 | +Local `notify_url` relay for Transloadit Assemblies. This tool polls the status of Assemblies until they complete, then pushes the status to a pingback URL of your choosing. This is useful while on a development machine, which is inaccessible from the public internet and hence can't be notified by Transloadit. |
| 4 | + |
| 5 | +You can alternatively use a tunnel like ngrok or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) for this, this is just one more way. |
| 6 | + |
| 7 | +This version is modernized for: |
| 8 | + |
| 9 | +- Node.js 24+ |
| 10 | +- Native TypeScript execution (type stripping) |
| 11 | +- ESM |
| 12 | +- Yarn 4 |
| 13 | +- Biome + Vitest + GitHub Actions + Changesets |
| 14 | + |
| 15 | +Notify payloads are signed via `@transloadit/utils` using prefixed `sha384` signatures. |
| 16 | +Forwarding uses native `fetch`, polling retries use `p-retry`, and logs are emitted via `@transloadit/sev-logger`. |
| 17 | +Metrics hooks are available for counters, gauges, and timings. |
| 18 | + |
| 19 | +## Install |
| 20 | + |
| 21 | +```bash |
| 22 | +npm install @transloadit/notify-url-relay |
| 23 | +``` |
| 24 | + |
| 25 | +## CLI usage |
| 26 | + |
| 27 | +```bash |
| 28 | +export TRANSLOADIT_SECRET="your-secret" |
| 29 | + |
| 30 | +notify-url-relay \ |
| 31 | + --notifyUrl "http://127.0.0.1:3000/transloadit" \ |
| 32 | + --port 8888 \ |
| 33 | + --notifyOnTerminalError \ |
| 34 | + --log-level info |
| 35 | +``` |
| 36 | + |
| 37 | +Run `notify-url-relay --help` for all options. |
| 38 | + |
| 39 | +Log level accepts `0-8` or names: |
| 40 | +`emerg`, `alert`, `crit`, `err`, `warn`, `notice`, `info`, `debug`, `trace`. |
| 41 | +You can also set `TRANSLOADIT_LOG_LEVEL`. |
| 42 | + |
| 43 | +### Reactive TUI Mode |
| 44 | + |
| 45 | +```bash |
| 46 | +notify-url-relay --ui --log-level info |
| 47 | +``` |
| 48 | + |
| 49 | +This opens a live terminal dashboard with: |
| 50 | + |
| 51 | +- throughput and retry counters |
| 52 | +- in-flight queue gauges |
| 53 | +- latency sparklines |
| 54 | +- streaming logs |
| 55 | + |
| 56 | +## Programmatic usage |
| 57 | + |
| 58 | +```ts |
| 59 | +import { TransloaditNotifyUrlProxy } from '@transloadit/notify-url-relay' |
| 60 | + |
| 61 | +const proxy = new TransloaditNotifyUrlProxy( |
| 62 | + process.env.TRANSLOADIT_SECRET ?? '', |
| 63 | + 'http://127.0.0.1:3000/transloadit' |
| 64 | +) |
| 65 | + |
| 66 | +proxy.run({ |
| 67 | + port: 8888, |
| 68 | + target: 'https://api2.transloadit.com', |
| 69 | + forwardTimeoutMs: 15000, |
| 70 | + pollIntervalMs: 2000, |
| 71 | + pollMaxIntervalMs: 30000, |
| 72 | + pollBackoffFactor: 2, |
| 73 | + pollRequestTimeoutMs: 15000, |
| 74 | + maxPollAttempts: 10, |
| 75 | + maxInFlightPolls: 4, |
| 76 | + notifyOnTerminalError: false, |
| 77 | + notifyTimeoutMs: 15000, |
| 78 | + notifyMaxAttempts: 3, |
| 79 | + notifyIntervalMs: 500, |
| 80 | + notifyMaxIntervalMs: 5000, |
| 81 | + notifyBackoffFactor: 2 |
| 82 | +}) |
| 83 | +``` |
| 84 | + |
| 85 | +## Development |
| 86 | + |
| 87 | +```bash |
| 88 | +corepack yarn |
| 89 | +corepack yarn workspace @transloadit/notify-url-relay check |
| 90 | +corepack yarn workspace @transloadit/notify-url-relay test:real |
| 91 | +``` |
| 92 | + |
| 93 | +## Real API E2E |
| 94 | + |
| 95 | +Run an opt-in test against the real Transloadit API (default `yarn test` excludes this test): |
| 96 | + |
| 97 | +```bash |
| 98 | +# set locally (for example in .env) |
| 99 | +export TRANSLOADIT_KEY="your-key" |
| 100 | +export TRANSLOADIT_SECRET="your-secret" |
| 101 | +# optional |
| 102 | +export TRANSLOADIT_ENDPOINT="https://api2.transloadit.com" |
| 103 | + |
| 104 | +corepack yarn workspace @transloadit/notify-url-relay test:real |
| 105 | +``` |
| 106 | + |
| 107 | +For CI, configure repository secrets: |
| 108 | + |
| 109 | +- `TRANSLOADIT_KEY` |
| 110 | +- `TRANSLOADIT_SECRET` |
| 111 | +- `TRANSLOADIT_ENDPOINT` (optional) |
| 112 | + |
| 113 | +## Releases |
| 114 | + |
| 115 | +Changesets drives releases for this package: |
| 116 | + |
| 117 | +```bash |
| 118 | +corepack yarn changeset |
| 119 | +corepack yarn changeset:version |
| 120 | +``` |
| 121 | + |
| 122 | +On pushes to `main`, `.github/workflows/release.yml` runs `changesets/action` to publish. |
0 commit comments