Add assembly status busy/terminal helpers (#280)

* Add assembly status helpers

* Drop isAssemblyCompleted helper

* docs: clarify changeset visibility for transloadit

* fix: treat system errors as terminal

* Apply suggestion from @kvz

* chore: refresh transloadit parity baseline

* docs: note how to accept intended parity drift

Author: kvz

.changeset/bright-sloths-care.md

@@ -0,0 +1,8 @@
+---
+"@transloadit/node": patch
+"@transloadit/zod": patch
+"@transloadit/types": patch
+"transloadit": patch
+---
+
+Add assembly status helpers and expand busy status codes for consistent terminal checks.

CONTRIBUTING.md

@@ -119,4 +119,6 @@ Notes:
 
 - **Lockstep versions:** Changesets use a fixed group, so version bumps and releases are always in lock‑step across `transloadit`, `@transloadit/node`, `@transloadit/types`, and `@transloadit/zod`.
 - **Legacy parity:** `transloadit` is generated from `@transloadit/node` artifacts via `scripts/prepare-transloadit.ts`, then verified with `yarn parity:transloadit`. Only `package.json` metadata drift is allowed; any other drift fails.
+- **Accepting intentional drift:** run `node scripts/prepare-transloadit.ts` before updating the parity baseline, then follow the parity tool instructions to regenerate `docs/fingerprint/*` so the baseline reflects the latest build.
 - **Experimental packages:** Scoped packages (`@transloadit/node`, `@transloadit/types`, `@transloadit/zod`) publish with the `experimental` dist-tag. The unscoped `transloadit` package remains stable.
+- **Changelog visibility:** Because versions are locked, a changeset that only lists scoped packages will still bump `transloadit` but may leave its changelog empty. If a change affects `transloadit` users (which happens because it is just a generated clone of `@transloadit/node`, so if it is affected, `transloadit` is too automatically), include `transloadit` in the changeset so the changelog entry is visible.

docs/fingerprint/transloadit-baseline.json

@@ -1,13 +1,13 @@
 {
-  "packageDir": "/Users/kvz/code/node-sdk/packages/transloadit",
+  "packageDir": "/home/kvz/code/node-sdk/packages/transloadit",
   "tarball": {
-    "filename": "transloadit-4.1.3.tgz",
-    "sizeBytes": 1112110,
-    "sha256": "973f2846fe89338a05f6416d54722726d4ad7334181d02fd09b0838b30ab739e"
+    "filename": "transloadit-4.1.4.tgz",
+    "sizeBytes": 1112173,
+    "sha256": "58d8c372fb4be8b14c7fcd2ba528846837b6d536ed80f2d55d36de6384f89684"
   },
   "packageJson": {
     "name": "transloadit",
-    "version": "4.1.3",
+    "version": "4.1.4",
     "main": "./dist/Transloadit.js",
     "exports": {
       ".": "./dist/Transloadit.js",
@@ -73,8 +73,8 @@
     },
     {
       "path": "dist/alphalib/types/assemblyStatus.js",
-      "sizeBytes": 28422,
-      "sha256": "aa59b5ea94ac88ab533233a76cd394f9d81d1631f3620cbe51e54261a96a07cb"
+      "sizeBytes": 30275,
+      "sha256": "965681e5d34df579fa11b8903c8fdf2823636be5830e97ab751fe5a531cad608"
     },
     {
       "path": "dist/alphalib/types/robots/audio-artwork.js",
@@ -614,7 +614,7 @@
     {
       "path": "package.json",
       "sizeBytes": 2201,
-      "sha256": "4836303837df371e1cae0c1eab22c353d6efef46695047ddb428fc544df416a5"
+      "sha256": "e0d0a327efa47840315ea7e37947e10feda0280754250302000ba016b388fa75"
     },
     {
       "path": "dist/alphalib/types/robots/_index.d.ts.map",
@@ -718,13 +718,13 @@
     },
     {
       "path": "dist/alphalib/types/assemblyStatus.d.ts.map",
-      "sizeBytes": 73453,
-      "sha256": "ba4ef1d696b4e2206f1f653816b4482e9c7d828e67932d3dc65c34901b8645ce"
+      "sizeBytes": 74444,
+      "sha256": "2a863f4791a4963c77806332af2a6353d158457b4c6a59ba5f7b6f271849643d"
     },
     {
       "path": "dist/alphalib/types/assemblyStatus.js.map",
-      "sizeBytes": 31752,
-      "sha256": "a34d73de1bfacf8481c2113ba52dca1c9323c0b72d2c85d1eedda9a5b04121d5"
+      "sizeBytes": 32930,
+      "sha256": "12d13cf45eaffea8afb16faaf9eac3bb9b0385e11a63606cfcddcc7a5c89c090"
     },
     {
       "path": "dist/alphalib/types/robots/audio-artwork.d.ts.map",
@@ -1903,13 +1903,13 @@
     },
     {
       "path": "dist/alphalib/types/assemblyStatus.d.ts",
-      "sizeBytes": 4247223,
-      "sha256": "a73d095037fd45c143b9f2f11f0b95ba5d0eb788e566d2ece74752b6b84feec9"
+      "sizeBytes": 4249145,
+      "sha256": "85f796b227939cd5546c2ea92f2ae0b5929b6b3eabbb9b563df4079c61ea0463"
     },
     {
       "path": "src/alphalib/types/assemblyStatus.ts",
-      "sizeBytes": 29509,
-      "sha256": "05e6b21ec4d572b95e0a6731633402a775de0aeb77b95c4cac87ac8cbcdab656"
+      "sizeBytes": 31951,
+      "sha256": "64f22e7547af8f406a7b4de333074bbbbe61ad4f2c3bb46ed076e682c466d5fa"
     },
     {
       "path": "dist/alphalib/types/robots/audio-artwork.d.ts",

docs/fingerprint/transloadit-baseline.package.json

@@ -1,6 +1,6 @@
 {
   "name": "transloadit",
-  "version": "4.1.3",
+  "version": "4.1.4",
   "description": "Node.js SDK for Transloadit",
   "type": "module",
   "keywords": ["transloadit", "encoding", "transcoding", "video", "audio", "mp3"],

packages/node/src/alphalib/types/assemblyStatus.ts

@@ -1,6 +1,10 @@
 import { z } from 'zod'
 
-export const assemblyBusyCodeSchema = z.enum(['ASSEMBLY_UPLOADING'])
+export const assemblyBusyCodeSchema = z.enum([
+  'ASSEMBLY_UPLOADING',
+  'ASSEMBLY_EXECUTING',
+  'ASSEMBLY_REPLAYING',
+])
 
 export const assemblyStatusOkCodeSchema = z.enum([
   'ASSEMBLY_CANCELED',
@@ -733,6 +737,79 @@ export function getOk(assembly: AssemblyStatus | undefined | null): string | und
     : undefined
 }
 
+/**
+ * Type guard to check if a status string is a busy (in-progress) state.
+ */
+export function isAssemblyBusyStatus(
+  status: string | undefined | null,
+): status is z.infer<typeof assemblyBusyCodeSchema> {
+  return Boolean(status) && assemblyBusyCodeSchema.safeParse(status).success
+}
+
+/**
+ * Type guard to check if a status string is an ok (non-error) state.
+ */
+export function isAssemblyOkStatus(
+  status: string | undefined | null,
+): status is z.infer<typeof assemblyStatusOkCodeSchema> {
+  return Boolean(status) && assemblyStatusOkCodeSchema.safeParse(status).success
+}
+
+/**
+ * Type guard to check if a status string is an error state.
+ */
+export function isAssemblyErrorStatus(
+  status: string | undefined | null,
+): status is z.infer<typeof assemblyStatusErrCodeSchema> {
+  return Boolean(status) && assemblyStatusErrCodeSchema.safeParse(status).success
+}
+
+/**
+ * Type guard to check if an assembly matches the system error shape.
+ */
+export function isAssemblySysError(
+  assembly: AssemblyStatus | undefined | null,
+): assembly is z.infer<typeof assemblyStatusSysErrSchema> {
+  return Boolean(assembly) && assemblyStatusSysErrSchema.safeParse(assembly).success
+}
+
+/**
+ * Type guard to check if a status string is terminal (ok, but not busy).
+ */
+export function isAssemblyTerminalOkStatus(
+  status: string | undefined | null,
+): status is z.infer<typeof assemblyStatusOkCodeSchema> {
+  return isAssemblyOkStatus(status) && !isAssemblyBusyStatus(status)
+}
+
+/**
+ * Returns true if the assembly is in a busy (in-progress) state.
+ */
+export function isAssemblyBusy(assembly: AssemblyStatus | undefined | null): boolean {
+  return isAssemblyBusyStatus(getOk(assembly))
+}
+
+/**
+ * Returns true if the assembly is in a terminal ok state.
+ */
+export function isAssemblyTerminalOk(assembly: AssemblyStatus | undefined | null): boolean {
+  return isAssemblyTerminalOkStatus(getOk(assembly))
+}
+
+/**
+ * Returns true if the assembly has a terminal error state.
+ */
+export function isAssemblyTerminalError(assembly: AssemblyStatus | undefined | null): boolean {
+  return isAssemblyErrorStatus(getError(assembly)) || isAssemblySysError(assembly)
+}
+
+/**
+ * Returns true if the assembly is terminal (ok or error).
+ */
+export function isAssemblyTerminal(assembly: AssemblyStatus | undefined | null): boolean {
+  return isAssemblyTerminalOk(assembly) || isAssemblyTerminalError(assembly)
+}
+
 /**
  * This type and these functions below are compatibility helpers for
  * working with partial assembly status objects during the transition

packages/node/test/unit/assembly-status-helpers.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+
+import type { AssemblyStatus } from '../../src/alphalib/types/assemblyStatus.ts'
+import {
+  isAssemblySysError,
+  isAssemblyTerminal,
+  isAssemblyTerminalError,
+} from '../../src/alphalib/types/assemblyStatus.ts'
+
+describe('assembly status helpers', () => {
+  it('treats system error shapes as terminal errors', () => {
+    const sysError = {
+      errno: -2,
+      code: 'ENOENT',
+      syscall: 'stat',
+      path: '/tmp/missing',
+    } as AssemblyStatus
+
+    expect(isAssemblySysError(sysError)).toBe(true)
+    expect(isAssemblyTerminalError(sysError)).toBe(true)
+    expect(isAssemblyTerminal(sysError)).toBe(true)
+  })
+})