Changelog

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
 

MIGRATION.md

@@ -1,58 +1,128 @@
 # 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<AssemblyIndexItem>` (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 = {
   steps: {
     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<AssemblyIndexItem>` 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.