Skip to content

Commit 5048d67

Browse files
kvzkvz
authored
Expand schema with constants (#231)
* Update assemblyStatus.ts * Update assemblyStatus.ts * Create MIGRATION.md * Update CONTRIBUTING.md * Update MIGRATION.md * Update MIGRATION.md * Update resize_an_image.ts * Update resize_an_image.ts * Update MIGRATION.md * Update resize_an_image.ts * Update resize_an_image.ts * Update resize_an_image.ts
1 parent 5841fac commit 5048d67

4 files changed

Lines changed: 211 additions & 36 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ Only maintainers can make releases. Releases to [npm](https://www.npmjs.com) are
8585

8686
1. Update the version using Yarn, e.g. `yarn version patch` (n.b. use `yarn version prerelease` for pre-releases). This will update the version in the `package.json` file.
8787
2. Commit the changes to the `package.json` file.
88-
3. Create a new Git tag, e.g. `git tag v4.0.0-6`.
88+
3. Create a new Git tag, e.g. `git tag v4.0.0-6` (add the `v`!).
8989
4. Push the tag to GitHub: `git push origin main --tags`
9090
5. If the tests pass, GitHub actions will now publish the new version to npm.
9191
6. When successful add [release notes](https://github.com/transloadit/node-sdk/releases).

‎MIGRATION.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Migration Guide: SDK v3.x to v4.x
2+
3+
This guide summarizes key changes and migration steps from SDK v3.x to v4.x, focusing on enhanced type safety, improved error handling, and Zod schema validation.
4+
5+
## Key Changes in v4.x
6+
7+
- Renamed `TransloaditClient` to `Transloadit`
8+
- Use named export for `Transloadit`, instead of default export.
9+
- Dropped support for Node.js < 20.
10+
- **Type Safety with Zod:** Assembly creation parameters and API responses are now validated using Zod schemas, providing accurate TypeScript types and IDE autocompletion. The main benefit for customers is less trips to the documentation as they are typing Assembly Instructions. Robot names and their available parameters are now all autocompleted.
11+
- **Improved Error Reporting:** Clearer client-side and API errors (`ApiError`, `InconsistentResponseError`) help quickly identify issues.
12+
- **Exported Schemas and Types:** Core schemas (`assemblyInstructionsSchema`, `assemblyStatusSchema`, etc.) and inferred types (`AssemblyInstructionsInput`, `AssemblyIndexItem`) are exported for reuse.
13+
- **Modernized Codebase:** Fully transitioned to TypeScript, removing manual `.d.ts` files.
14+
15+
## Migration Steps
16+
17+
### 1. Assembly Creation (`createAssembly`)
18+
19+
- Parameters are strictly validated against `assemblyInstructionsSchema`.
20+
- Incorrect Robot names, parameters, or types now cause immediate client-side errors or detailed API errors.
21+
22+
**Migration Steps:**
23+
24+
- Review and update all `createAssembly` calls to match the schema.
25+
- Use exported types for better IDE support:
26+
27+
```typescript
28+
import { Transloadit, AssemblyInstructionsInput } from 'transloadit'
29+
30+
const transloadit = new Transloadit({ authKey: 'YOUR_KEY', authSecret: 'YOUR_SECRET' })
31+
32+
const params: AssemblyInstructionsInput = {
33+
steps: {
34+
resize: {
35+
use: ':original',
36+
robot: '/image/resize',
37+
width: 100,
38+
height: 50,
39+
},
40+
},
41+
}
42+
43+
const assembly = await transloadit.createAssembly(params)
44+
```
45+
46+
### 2. Assembly Status Methods (`getAssembly`, `cancelAssembly`, `awaitAssemblyCompletion`)
47+
48+
- Methods now return strictly typed `AssemblyStatus` objects.
49+
- Schema mismatches trigger an `InconsistentResponseError` (logged, not thrown yet).
50+
51+
### 3. Listing Assemblies (`listAssemblies`)
52+
53+
- Returns `PaginationListWithCount<AssemblyIndexItem>` instead of `ListedAssembly`.
54+
- Items validated against `assemblyIndexItemSchema`.
55+
56+
**Migration Steps:**
57+
58+
- Update type annotations from `ListedAssembly` to `AssemblyIndexItem`.
59+
60+
```typescript
61+
const result = await transloadit.listAssemblies()
62+
result.items.forEach((item: AssemblyIndexItem) => {
63+
console.log(item.id, item.ok, item.created)
64+
})
65+
```
66+
67+
### 4. General Changes
68+
69+
- New custom errors (`ApiError`, `InconsistentResponseError`, `PollingTimeoutError`).
70+
- Modernized build system and testing (`vitest`).
71+
- Make sure you are on Node.js 20 or higher.
72+
73+
## Benefits of Upgrading
74+
75+
- **Increased Reliability:** Early detection of errors through schema validation.
76+
- **Improved Developer Experience:** Accurate types and autocompletion reduce guesswork.
77+
- **Clearer Diagnostics:** Specific errors pinpoint exact issues.
78+
79+
## Closing Thoughts
80+
81+
Transloadit is retrofitting types on an 15 year old codebase. The path we chose is to:
82+
83+
1. create schemas that model closely what the API currently outputs, and allows as inputs
84+
2. roll out the schemas in clients, and our test suite, even though they are not as narrow as we would like yet
85+
3. gradually narrow the schemas, our test suite will raise red flags, so we can adjust the API (unless it would break backwards compatibility)
86+
4. we rinse and repeat, until our API is as narrow as we like our schemas/types to be
87+
88+
We are currently at step 2, this means you'll find fairly wide types, but at least they do not lie, so that you should be able to build your integration on them without runtime type errors.
89+
90+
Please Test your integration thoroughly after upgrading. For issues or unexpected behavior, consult the SDK documentation or raise an issue.

‎examples/resize_an_image.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,13 @@ const transloadit = new Transloadit({
1313
authSecret: process.env.TRANSLOADIT_SECRET!,
1414
})
1515

16-
const filePath = process.argv[2]
17-
1816
const status = await transloadit.createAssembly({
1917
files: {
20-
file1: filePath,
18+
file1: process.argv[2],
2119
},
2220
params: {
2321
steps: {
24-
resize: {
22+
resized: {
2523
use: ':original',
2624
robot: '/image/resize',
2725
result: true,

‎src/alphalib/types/assemblyStatus.ts‎

Lines changed: 118 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -3,50 +3,137 @@ import { z } from 'zod'
33
const assemblyBusyCodeSchema = z.enum(['ASSEMBLY_UPLOADING'])
44

55
export const assemblyStatusOkCodeSchema = z.enum([
6-
'ASSEMBLY_COMPLETED',
7-
'REQUEST_ABORTED',
86
'ASSEMBLY_CANCELED',
7+
'ASSEMBLY_COMPLETED',
98
'ASSEMBLY_EXECUTING',
9+
'ASSEMBLY_EXPIRED',
10+
'ASSEMBLY_REPLAYING',
11+
'ASSEMBLY_UPLOADING',
12+
'REQUEST_ABORTED',
13+
// 'ASSEMBLY_EXECUTION_PROGRESS_FETCHED',
14+
// 'ASSEMBLY_FILE_ACCEPTED',
15+
// 'ASSEMBLY_FILE_RESERVED',
1016
])
1117

1218
export const assemblyStatusErrCodeSchema = z.enum([
13-
'INVALID_INPUT_ERROR',
14-
'FILE_FILTER_DECLINED_FILE',
15-
'INTERNAL_COMMAND_TIMEOUT',
16-
'FILE_META_DATA_ERROR',
17-
'INVALID_FILE_META_DATA',
18-
'INTERNAL_COMMAND_ERROR',
19-
'TEMPLATE_NOT_FOUND',
20-
'TEMPLATE_DENIES_STEPS_OVERRIDE',
21-
'NO_AUTH_EXPIRES_PARAMETER',
22-
'MAX_SIZE_EXCEEDED',
23-
'CLOUDFLARE_IMPORT_VALIDATION',
24-
'S3_NOT_FOUND',
25-
'IMPORT_FILE_ERROR',
26-
'USER_COMMAND_ERROR',
19+
'ADMIN_PERMISSIONS_REQUIRED',
20+
'ASSEMBLY_ACCOUNT_MISMATCH',
21+
'ASSEMBLY_CANNOT_BE_REPLAYED',
22+
'ASSEMBLY_COULD_NOT_BE_CREATED',
23+
'ASSEMBLY_CRASHED',
24+
'ASSEMBLY_DISALLOWED_ROBOTS_USED',
25+
'ASSEMBLY_EMPTY_STEPS',
26+
'ASSEMBLY_EXPIRED',
27+
'ASSEMBLY_FILE_NOT_RESERVED',
28+
'ASSEMBLY_INFINITE',
29+
'ASSEMBLY_INSTANCE_NOT_FOUND',
30+
'ASSEMBLY_INVALID_NOTIFY_URL',
31+
'ASSEMBLY_INVALID_NUM_EXPECTED_UPLOAD_FILES_PARAM',
32+
'ASSEMBLY_INVALID_STEPS',
33+
'ASSEMBLY_JOB_ENQUEUE_ERROR',
34+
'ASSEMBLY_LIST_ERROR',
35+
'ASSEMBLY_MEMORY_LIMIT_EXCEEDED',
36+
'ASSEMBLY_NO_CHARGEABLE_STEP',
37+
'ASSEMBLY_NO_STEPS',
38+
'ASSEMBLY_NOT_CAPABLE',
39+
'ASSEMBLY_NOT_FINISHED',
40+
'ASSEMBLY_NOT_FOUND',
41+
'ASSEMBLY_NOT_REPLAYED',
42+
'ASSEMBLY_NOTIFICATION_NOT_PERSISTED',
43+
'ASSEMBLY_ROBOT_MISSING',
44+
'ASSEMBLY_SATURATED',
45+
'ASSEMBLY_STATUS_NOT_FOUND',
46+
'ASSEMBLY_STATUS_PARSE_ERROR',
47+
'ASSEMBLY_STEP_INVALID_ROBOT',
48+
'ASSEMBLY_STEP_INVALID_USE',
49+
'ASSEMBLY_STEP_INVALID',
50+
'ASSEMBLY_STEP_NO_ROBOT',
51+
'ASSEMBLY_STEP_UNKNOWN_ROBOT',
52+
'ASSEMBLY_STEP_UNKNOWN_USE',
53+
'ASSEMBLY_URL_TRANSFORM_MISSING',
54+
'AUTH_EXPIRED',
55+
'AUTH_KEY_SCOPES_NOT_FOUND',
56+
'AUTH_KEYS_NOT_FOUND',
57+
'AUTH_SECRET_NOT_RETRIEVED',
2758
'BACKBLAZE_STORE_FAILURE',
59+
'BAD_PRICING',
60+
'BILL_LIMIT_EXCEEDED',
61+
'CANNOT_ACCEPT_NEW_ASSEMBLIES',
62+
'CANNOT_FETCH_ACTIVE_ASSEMBLIES',
63+
'CDN_REQUIRED',
64+
'CLOUDFILES_STORE_ERROR',
65+
'CLOUDFLARE_IMPORT_VALIDATION',
66+
'DO_NOT_REUSE_ASSEMBLY_IDS',
2867
'DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION',
29-
'INVALID_SIGNATURE',
30-
'GOOGLE_STORE_VALIDATION',
68+
'FILE_DOWNLOAD_ERROR',
69+
'FILE_FILTER_DECLINED_FILE',
3170
'FILE_FILTER_VALIDATION',
32-
'HTTP_IMPORT_ACCESS_DENIED',
33-
'TEMPLATE_CREDENTIALS_INJECTION_ERROR',
34-
'HTTP_IMPORT_VALIDATION',
35-
'ASSEMBLY_EXPIRED',
36-
'WORKER_JOB_ERROR',
37-
'ASSEMBLY_STEP_UNKNOWN_USE',
38-
'IMAGE_RESIZE_ERROR',
39-
'TMP_FILE_DOWNLOAD_ERROR',
40-
'ASSEMBLY_DISALLOWED_ROBOTS_USED',
71+
'FILE_META_DATA_ERROR',
4172
'FILE_PREVIEW_VALIDATION',
42-
'HTTP_IMPORT_NOT_FOUND',
73+
'GET_ACCOUNT_DB_ERROR',
74+
'GET_ACCOUNT_UNKNOWN_AUTH_KEY',
75+
'GOOGLE_IMPORT_VALIDATION',
76+
'GOOGLE_STORE_VALIDATION',
4377
'HTML_CONVERT_VALIDATION',
78+
'HTTP_IMPORT_ACCESS_DENIED',
4479
'HTTP_IMPORT_FAILURE',
80+
'HTTP_IMPORT_NOT_FOUND',
81+
'HTTP_IMPORT_VALIDATION',
82+
'IMAGE_RESIZE_ERROR',
4583
'IMAGE_RESIZE_VALIDATION',
46-
'GOOGLE_IMPORT_VALIDATION',
47-
'S3_STORE_ACCESS_DENIED',
84+
'IMPORT_FILE_ERROR',
85+
'INCOMPLETE_PRICING',
86+
'INSUFFICIENT_AUTH_SCOPE',
87+
'INTERNAL_COMMAND_ERROR',
88+
'INTERNAL_COMMAND_TIMEOUT',
89+
'INVALID_ASSEMBLY_STATUS',
90+
'INVALID_AUTH_EXPIRES_PARAMETER',
91+
'INVALID_AUTH_KEY_PARAMETER',
92+
'INVALID_AUTH_MAX_SIZE_PARAMETER',
93+
'INVALID_AUTH_REFERER_PARAMETER',
94+
'INVALID_FILE_META_DATA',
95+
'INVALID_FORM_DATA',
96+
'INVALID_INPUT_ERROR',
97+
'INVALID_PARAMS_FIELD',
98+
'INVALID_SIGNATURE',
99+
'INVALID_STEP_NAME',
100+
'INVALID_TEMPLATE_FIELD',
101+
'INVALID_UPLOAD_HANDLE_STEP_NAME',
102+
'MAX_SIZE_EXCEEDED',
103+
'NO_AUTH_EXPIRES_PARAMETER',
104+
'NO_AUTH_KEY_PARAMETER',
105+
'NO_AUTH_PARAMETER',
106+
'NO_COUNTRY',
107+
'NO_OBJECT_AUTH_PARAMETER',
108+
'NO_OBJECT_PARAMS_FIELD',
109+
'NO_PARAMS_FIELD',
110+
'NO_PRICING',
111+
'NO_RESULT_STEP_FOUND',
112+
'NO_RPC_RESULT_FROM_IMAGE_RESIZER',
113+
'NO_SIGNATURE_FIELD',
114+
'NO_TEMPLATE_ID',
115+
'PLAN_LIMIT_EXCEEDED',
116+
'POSSIBLY_MALICIOUS_FILE_FOUND',
117+
'PRIORITY_JOB_SLOTS_NOT_FOUND',
118+
'REFERER_MISMATCH',
119+
'REQUEST_PREMATURE_CLOSED',
120+
'ROBOT_VALIDATION_BASE_ERROR',
48121
'S3_ACCESS_DENIED',
49-
'CLOUDFILES_STORE_ERROR',
122+
'S3_NOT_FOUND',
123+
'S3_STORE_ACCESS_DENIED',
124+
'SERVER_403',
125+
'SERVER_404',
126+
'SERVER_500',
127+
'SIGNATURE_REUSE_DETECTED',
128+
'TEMPLATE_CREDENTIALS_INJECTION_ERROR',
129+
'TEMPLATE_DB_ERROR',
130+
'TEMPLATE_DENIES_STEPS_OVERRIDE',
131+
'TEMPLATE_INVALID_JSON',
132+
'TEMPLATE_NOT_FOUND',
133+
'TMP_FILE_DOWNLOAD_ERROR',
134+
'USER_COMMAND_ERROR',
135+
'VERIFIED_EMAIL_REQUIRED',
136+
'WORKER_JOB_ERROR',
50137
])
51138

52139
// --- Define Main Meta Schema (remove HLS specific fields) ---

0 commit comments

Comments
 (0)