diff --git a/CHANGELOG.md b/CHANGELOG.md index b2c85b3f..4163e4b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,54 @@ # Changelog -We're no longer using this file. Please refer to [GitHub releases](https://github.com/transloadit/node-sdk/releases) to see documented changes after version 2.0.10. +You may also want to refer to [GitHub releases](https://github.com/transloadit/node-sdk/releases). + +## v4.0.1 + +Released: 2025-09-18. + +[Diff](https://github.com/transloadit/node-sdk/compare/v4.0.0...v4.0.1). + +- [x] Re-published v4.0.0 under v4.0.1 to fix release metadata. No functional changes. + +## v4.0.0 + +Released: 2025-09-18. + +[Diff](https://github.com/transloadit/node-sdk/compare/v3.0.2...v4.0.0). + +- [x] **Breaking:** Package is now pure ESM, requires Node.js 20+, and exports `{ Transloadit }` instead of a default client. +- [x] **Breaking:** Assembly inputs are validated against rich schemas; migrate to the new `AssemblyInstructionsInput` types and expect `listAssemblies()` to return `{ items, count }`. +- [x] Added end-to-end TypeScript typings for robots, assemblies, templates, and responses, so assembly instructions now autocomplete every robot and its supported parameters. +- [x] Introduced structured error classes (`ApiError`, `InconsistentResponseError`, `PollingTimeoutError`) that preserve assembly IDs and server metadata. +- [x] Added opt-in `validateResponses` safeguard and a `getSignedSmartCDNUrl` helper for generating signed Smart CDN URLs. +- [x] Modernized tooling, tests, and examples (Vitest, Biome, TypeScript examples). See [MIGRATION.md](./MIGRATION.md) for a guided upgrade path. + +## v3.0.2 + +Released: 2021-04-06. + +[Diff](https://github.com/transloadit/node-sdk/compare/v3.0.1...v3.0.2). + +- [x] Generate assembly IDs on the client to avoid relying on server timing. +- [x] Completed TypeScript surface for assembly responses by adding missing output properties. + +## v3.0.1 + +Released: 2021-03-31. + +[Diff](https://github.com/transloadit/node-sdk/compare/v3.0.0...v3.0.1). + +- [x] Fixed the published default export to match the actual runtime client. + +## v3.0.0 + +Released: 2021-03-16. + +[Diff](https://github.com/transloadit/node-sdk/compare/v2.0.10...v3.0.0). + +- [x] Finalized the promise-based client by removing legacy wrappers and tightening trailing-slash validation. +- [x] Expanded continuous testing, linting, and documentation coverage ahead of the stable v3 release. +- [x] Improved `createAssembly` diagnostics by logging assembly IDs and exposing replayed assembly URLs. ## v2.0.10 diff --git a/MIGRATION.md b/MIGRATION.md index ff4ab8f4..cca8754c 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,25 +1,48 @@ # Migration Guide: v3 → v4 -v4 focuses on type-safety, clearer errors, and modern Node support. Most changes are mechanical. - -## Breaking changes (quick scan) - -- `TransloaditClient` (default export) ➜ **`{ Transloadit }`** (named export) -- Requires **Node >= 20** -- `createAssembly` input validated by `assemblyInstructionsSchema` -- `listAssemblies()` now returns `PaginationListWithCount` (was `ListedAssembly`) -- New errors: `ApiError`, `InconsistentResponseError`, `PollingTimeoutError` +Version 4 focuses on type-safety, clearer errors, and modern Node support. Most updates are mechanical, but there are a few breaking changes that need attention. + +## TL;DR checklist + +- [ ] Ensure your runtime is Node.js **20 or newer**. +- [ ] Switch from the v3 default export to the named `{ Transloadit }` ESM export. +- [ ] Adopt the new typed assembly instructions (`AssemblyInstructionsInput`) and update code that reads `listAssemblies()` results. +- [ ] Adjust error handling to account for the new `ApiError`, `InconsistentResponseError`, and `PollingTimeoutError` classes. +- [ ] (Optional) Opt into `validateResponses` or use `getSignedSmartCDNUrl` if you need the new safeguards and helpers. + +## Before you begin + +- Update `transloadit` to `^4.0.0` in `package.json` and reinstall dependencies. +- Node 20+ is required. Tooling such as `ts-node`, Jest, or your bundler must be ESM-aware. +- The SDK ships with `"type": "module"` and `.d.ts` typings. Pure CommonJS projects will need to either migrate to ESM or load the client via `import()` inside async code. + +```js +// CommonJS example +async function getClient() { + const { Transloadit } = await import('transloadit') + return new Transloadit({ + authKey: process.env.TRANSLOADIT_KEY ?? '', + authSecret: process.env.TRANSLOADIT_SECRET ?? '', + }) +} +``` -## Upgrade in 4 steps +## 1. Update imports -1. Update imports +`TransloaditClient` (default export) was removed. Import `Transloadit` (and any helper types) as named exports. ```ts -import TransloaditClient from 'transloadit' -+import { Transloadit, AssemblyInstructionsInput, AssemblyIndexItem } from 'transloadit' +-const transloadit = new TransloaditClient(opts) ++import { Transloadit, AssemblyInstructionsInput, AssemblyStatus } from 'transloadit' ++const transloadit = new Transloadit(opts) ``` -2. Adapt assembly creation (now type-checked) +The package also exports `AssemblyInstructionsInput`, `AssemblyIndexItem`, `AssemblyStatus`, and the error classes so you can type your own helpers. + +## 2. Adopt typed assembly instructions + +`createAssembly` now validates its `params` using rich schemas. TypeScript users get autocomplete for every robot and parameter out of the box. ```ts const params: AssemblyInstructionsInput = { @@ -27,32 +50,79 @@ const params: AssemblyInstructionsInput = { resize: { use: ':original', robot: '/image/resize', - width: 100, - height: 50, + width: 320, + height: 240, + result: true, }, }, } -await transloadit.createAssembly(params) +await transloadit.createAssembly({ params, waitForCompletion: true }) ``` -3. Update list & status handling +If validation fails, `createAssembly` throws an `ApiError` before making a network request, helping you catch mistakes locally. + +## 3. Adjust API result handling + +- `listAssemblies()` now returns a `PaginationListWithCount` instead of the legacy `ListedAssembly` array. + + ```ts + const { items, count } = await transloadit.listAssemblies() + items.forEach((assembly) => console.log(assembly.id, assembly.status)) + ``` + +- `AssemblyStatus` objects are now fully typed. Update any custom helpers to use the exported types instead of hand-rolled interfaces. +- The pagination helpers (`PaginationStream`) are written in TypeScript and ship `.d.ts` files; imports work the same, but you can lean on the IDE for guidance now. + +## 4. Update error handling + +- `ApiError` wraps responses that contain an `error` payload even when the HTTP status code is 2xx. It carries `assemblyId`, `transloaditErrorCode`, and the raw `body`. +- `InconsistentResponseError` is thrown if the Transloadit API omits critical fields (for example, missing assembly URLs). +- `PollingTimeoutError` is thrown when waiting for an assembly to finish via `waitForCompletion` exceeds the timeout. ```ts -const { items } = await transloadit.listAssemblies() -items.forEach((a: AssemblyIndexItem) => console.log(a.id, a.created)) +try { + await transloadit.createAssembly({ params }) +} catch (error) { + if (error instanceof ApiError && error.assemblyId) { + console.error( + 'Troubleshoot at https://transloadit.com/c/assemblies/' + error.assemblyId + ) + } + throw error +} ``` -4. Run your code on **Node 20+**. +## 5. Optional enhancements + +- `validateResponses` (client option) replays schema validation against responses you receive. Enable it when integrating with new workflows to surface unexpected fields early: + + ```ts + const transloadit = new Transloadit({ + authKey, + authSecret, + validateResponses: true, + }) + ``` + +- `getSignedSmartCDNUrl` generates Smart CDN URLs with signatures that match the server-side implementation: -## Why upgrade? + ```ts + const signedUrl = transloadit.getSignedSmartCDNUrl({ + workspace: 'my-team', + template: 'hero-image', + input: 'landing.jpg', + urlParams: { format: 'webp' }, + }) + ``` -- IDE autocomplete for every Robot & parameter, as well as the API response -- Local schema validation catches mistakes before the request -- Improved error objects simplify debugging +## Testing & troubleshooting -## Heads-up +- Run your existing integration tests on Node 20+. If you relied on CommonJS `require`, convert those modules or wrap calls in `import()` shims as shown above. +- If TypeScript raises errors about unfamiliar properties, import the respective types from `transloadit` instead of redefining them. +- Schemas intentionally mirror the current public API. Some properties remain permissive while we tighten validation in the API itself; report gaps if the SDK raises or misses invalid data. -Schemas are still bit wider than we would like as the first priority when retrofitting our API with schemas/types, was modeling its behavior exactly, or we'd risk the types being a lie, and hence runtime type errors. +## Additional resources -We'll also outfit our API's testsuite with these schemas, and this will allow us to gradually, over time, narrow what our API can respond, along with the schemas. +- The [CHANGELOG](./CHANGELOG.md) summarises every change since v3.0.2. +- Reach out to support@transloadit.com if you encounter schema validation mismatches or missing robot definitions.