@transloadit/node 4.5.1 → 4.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transloadit/node",
-  "version": "4.5.1",
+  "version": "4.6.0",
   "description": "Node.js SDK for Transloadit",
   "type": "module",
   "keywords": [
@@ -76,7 +76,7 @@
     "fix": "npm-run-all --serial 'fix:js'",
     "lint:deps": "knip --dependencies --no-progress",
     "fix:deps": "knip --dependencies --no-progress --fix",
-    "prepack": "rm -f tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && yarn --cwd ../.. tsc:node",
+    "prepack": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && rm -f tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && yarn --cwd ../.. tsc:node",
     "test:unit": "yarn --cwd ../.. tsc:utils && ../../node_modules/.bin/vitest run --coverage ./test/unit",
     "test:e2e": "yarn --cwd ../.. tsc:utils && ../../node_modules/.bin/vitest run ./test/e2e",
     "test": "yarn --cwd ../.. tsc:utils && ../../node_modules/.bin/vitest run --coverage"

package/src/Transloadit.ts

@@ -90,7 +90,7 @@ export type {
   RobotListResult,
   RobotParamHelp,
 } from './robots.ts'
-export { getRobotHelp, listRobots } from './robots.ts'
+export { getRobotHelp, isKnownRobot, listRobots } from './robots.ts'
 
 const log = debug('transloadit')
 const logWarn = debug('transloadit:warn')

package/src/alphalib/mcache.ts

@@ -98,9 +98,11 @@ export class Mcache<T> {
     })
 
     this.#pending.set(key, promise)
-    void promise.finally(() => {
-      this.#pending.delete(key)
-    })
+    void promise
+      .finally(() => {
+        this.#pending.delete(key)
+      })
+      .catch(() => undefined)
     return promise
   }
 

package/src/alphalib/types/assemblyStatus.ts

@@ -10,7 +10,6 @@ export const assemblyStatusOkCodeSchema = z.enum([
   'ASSEMBLY_CANCELED',
   'ASSEMBLY_COMPLETED',
   'ASSEMBLY_EXECUTING',
-  'ASSEMBLY_EXPIRED',
   'ASSEMBLY_REPLAYING',
   'ASSEMBLY_UPLOADING',
   'REQUEST_ABORTED',
@@ -27,6 +26,7 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'ASSEMBLY_CRASHED',
   'ASSEMBLY_DISALLOWED_ROBOTS_USED',
   'ASSEMBLY_EMPTY_STEPS',
+  'ASSEMBLY_EXECUTION_PROGRESS_NOT_ENABLED',
   'ASSEMBLY_EXPIRED',
   'ASSEMBLY_FILE_NOT_RESERVED',
   'ASSEMBLY_INFINITE',
@@ -43,9 +43,17 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'ASSEMBLY_NOT_FINISHED',
   'ASSEMBLY_NOT_FOUND',
   'ASSEMBLY_NOT_REPLAYED',
+  'ASSEMBLY_NOTIFICATION_LIST_ERROR',
   'ASSEMBLY_NOTIFICATION_NOT_PERSISTED',
+  'ASSEMBLY_NOTIFICATION_NOT_REPLAYED',
+  'ASSEMBLY_NOTIFICATIONS_LIST_ERROR',
+  'ASSEMBLY_NO_NOTIFY_URL',
   'ASSEMBLY_ROBOT_MISSING',
   'ASSEMBLY_SATURATED',
+  'ASSEMBLY_STATS_ERROR',
+  'ASSEMBLY_STATS_INVALID_TIME',
+  'ASSEMBLY_STATS_MISSING_REGION',
+  'ASSEMBLY_STATUS_FETCHING_RATE_LIMIT_REACHED',
   'ASSEMBLY_STATUS_NOT_FOUND',
   'ASSEMBLY_STATUS_PARSE_ERROR',
   'ASSEMBLY_STEP_INVALID_ROBOT',
@@ -61,6 +69,9 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'AUTH_KEYS_NOT_FOUND',
   'AUTH_SECRET_NOT_RETRIEVED',
   'AZURE_STORE_ACCESS_DENIED',
+  'BEARER_TOKEN_AUTH_KEY_MISMATCH',
+  'BEARER_TOKEN_EXPIRED',
+  'BEARER_TOKEN_INVALID',
   'BACKBLAZE_IMPORT_ACCESS_DENIED',
   'BACKBLAZE_IMPORT_NOT_FOUND',
   'BACKBLAZE_STORE_ACCESS_DENIED',
@@ -88,6 +99,7 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'FILE_META_DATA_ERROR',
   'FILE_PREVIEW_VALIDATION',
   'FILE_READ_VALIDATION_ERROR',
+  'FILE_SERVE_NO_RESULT',
   'FILE_VERIFY_INVALID_FILE',
   'FILE_VIRUSSCAN_DECLINED_FILE',
   'GET_ACCOUNT_DB_ERROR',

package/src/alphalib/types/robots/ai-chat.ts

@@ -150,6 +150,7 @@ export const MODEL_CAPABILITIES: Record<string, { pdf: boolean; image: boolean }
   'anthropic/claude-4-opus-20250514': { pdf: true, image: true },
   'anthropic/claude-sonnet-4-5': { pdf: true, image: true },
   'anthropic/claude-opus-4-5': { pdf: true, image: true },
+  'anthropic/claude-opus-4-6': { pdf: true, image: true },
   'openai/gpt-4.1-2025-04-14': { pdf: false, image: true },
   'openai/chatgpt-4o-latest': { pdf: false, image: true },
   'openai/o3-2025-04-16': { pdf: false, image: true },
@@ -197,21 +198,28 @@ export const robotAiChatInstructionsSchema = robotBase
     credentials: z
       .union([z.string(), z.array(z.string())])
       .optional()
-      .describe('Names of template credentials to make available to the robot.'),
+      .describe(
+        'Names of template credentials to make available to the robot. When using your own AI provider keys, Transloadit charges a 10% markup (minimum $0.0005 per request).',
+      ),
     test_credentials: z
       .boolean()
       .optional()
-      .describe('Use Transloadit-provided credentials for testing.'),
+      .describe(
+        'Use Transloadit-provided credentials for testing. Usage is billed at provider cost plus a 10% markup (minimum $0.0005 per request).',
+      ),
     mcp_servers: z
       .array(
         z.object({
           type: z.enum(['sse', 'http']),
           url: z.string(),
           headers: z.record(z.string()).optional(),
+          auth: z.enum(['transloadit']).optional(),
         }),
       )
       .optional()
-      .describe('The MCP servers to use. This is used to call tools from the LLM.'),
+      .describe(
+        'The MCP servers to use. This is used to call tools from the LLM. Use `headers` to pass `Authorization: Bearer <token>` when needed. You can use any MCP server reachable from your environment. For Transloadit\'s own MCP server, you can set `auth: "transloadit"` to let API2 auto-auth and inject an Authorization header for you (only for Transloadit-hosted MCP servers).',
+      ),
   })
   .strict()
 

package/src/cli/commands/assemblies.ts

@@ -356,7 +356,12 @@ async function myStat(
 
 function dirProvider(output: string): OutstreamProvider {
   return async (inpath, indir = process.cwd()) => {
-    if (inpath == null || inpath === '-') {
+    // Inputless assemblies can still write into a directory, but output paths are derived from
+    // assembly results rather than an input file path (handled later).
+    if (inpath == null) {
+      return null
+    }
+    if (inpath === '-') {
       throw new Error('You must provide an input to output to a directory')
     }
 
@@ -937,13 +942,12 @@ export async function create(
       // Create fresh streams for this job
       const inStream = inPath ? fs.createReadStream(inPath) : null
       inStream?.on('error', () => {})
-      const outStream = outPath ? (fs.createWriteStream(outPath) as OutStream) : null
-      outStream?.on('error', () => {})
-      if (outStream) outStream.mtime = outMtime
 
       let superceded = false
-      if (outStream != null) {
-        outStream.on('finish', () => {
+      // When writing to a file path (non-directory output), we treat finish as a supersede signal.
+      // Directory-output multi-download mode does not use a single shared outstream.
+      const markSupersededOnFinish = (stream: OutStream) => {
+        stream.on('finish', () => {
           superceded = true
         })
       }
@@ -982,23 +986,124 @@ export async function create(
       }
 
       if (!assembly.results) throw new Error('No results in assembly')
-      const resultsKeys = Object.keys(assembly.results)
-      const firstKey = resultsKeys[0]
-      if (!firstKey) throw new Error('No results in assembly')
-      const firstResult = assembly.results[firstKey]
-      if (!firstResult || !firstResult[0]) throw new Error('No results in assembly')
-      const resulturl =
-        (firstResult[0] as { ssl_url?: string; url?: string }).ssl_url ?? firstResult[0].url
-
-      if (outStream != null && resulturl && !superceded) {
-        outputctl.debug('DOWNLOADING')
-        const [dlErr] = await tryCatch(
-          pipeline(got.stream(resulturl, { signal: abortController.signal }), outStream),
-        )
-        if (dlErr) {
-          if (dlErr.name !== 'AbortError') {
-            outputctl.error(dlErr.message)
-            throw dlErr
+
+      const outIsDirectory = Boolean(resolvedOutput != null && outstat?.isDirectory())
+      const entries = Object.entries(assembly.results)
+      const allFiles: Array<{
+        stepName: string
+        file: { name?: string; basename?: string; ext?: string; ssl_url?: string; url?: string }
+      }> = []
+      for (const [stepName, stepResults] of entries) {
+        for (const file of stepResults as Array<{
+          name?: string
+          basename?: string
+          ext?: string
+          ssl_url?: string
+          url?: string
+        }>) {
+          allFiles.push({ stepName, file })
+        }
+      }
+
+      const getFileUrl = (file: { ssl_url?: string; url?: string }): string | null =>
+        file.ssl_url ?? file.url ?? null
+
+      const sanitizeName = (value: string): string => {
+        const base = path.basename(value)
+        return base.replaceAll('\\', '_').replaceAll('/', '_').replaceAll('\u0000', '')
+      }
+
+      const ensureUniquePath = async (targetPath: string): Promise<string> => {
+        const parsed = path.parse(targetPath)
+        let candidate = targetPath
+        let counter = 1
+        while (true) {
+          const [statErr] = await tryCatch(fsp.stat(candidate))
+          if (statErr) return candidate
+          candidate = path.join(parsed.dir, `${parsed.name}__${counter}${parsed.ext}`)
+          counter += 1
+        }
+      }
+
+      if (resolvedOutput != null && !superceded) {
+        // Directory output:
+        // - For single-result, input-backed jobs, preserve existing behavior (write to mapped file path).
+        // - Otherwise (multi-result or inputless), download all results into a directory structure.
+        if (outIsDirectory && (inPath == null || allFiles.length !== 1 || outPath == null)) {
+          let baseDir = resolvedOutput
+          if (inPath != null) {
+            let relpath = path.relative(process.cwd(), inPath)
+            relpath = relpath.replace(/^(\.\.\/)+/, '')
+            baseDir = path.join(resolvedOutput, path.dirname(relpath), path.parse(relpath).name)
+          }
+          await fsp.mkdir(baseDir, { recursive: true })
+
+          for (const { stepName, file } of allFiles) {
+            const resultUrl = getFileUrl(file)
+            if (!resultUrl) continue
+
+            const stepDir = path.join(baseDir, stepName)
+            await fsp.mkdir(stepDir, { recursive: true })
+
+            const rawName =
+              file.name ??
+              (file.basename && file.ext ? `${file.basename}.${file.ext}` : undefined) ??
+              `${stepName}_result`
+            const safeName = sanitizeName(rawName)
+            const targetPath = await ensureUniquePath(path.join(stepDir, safeName))
+
+            outputctl.debug('DOWNLOADING')
+            const outStream = fs.createWriteStream(targetPath) as OutStream
+            outStream.on('error', () => {})
+            const [dlErr] = await tryCatch(
+              pipeline(got.stream(resultUrl, { signal: abortController.signal }), outStream),
+            )
+            if (dlErr) {
+              if (dlErr.name === 'AbortError') continue
+              outputctl.error(dlErr.message)
+              throw dlErr
+            }
+          }
+        } else if (!outIsDirectory && outPath != null) {
+          const first = allFiles[0]
+          const resultUrl = first ? getFileUrl(first.file) : null
+          if (resultUrl) {
+            outputctl.debug('DOWNLOADING')
+            const outStream = fs.createWriteStream(outPath) as OutStream
+            outStream.on('error', () => {})
+            outStream.mtime = outMtime
+            markSupersededOnFinish(outStream)
+
+            const [dlErr] = await tryCatch(
+              pipeline(got.stream(resultUrl, { signal: abortController.signal }), outStream),
+            )
+            if (dlErr) {
+              if (dlErr.name !== 'AbortError') {
+                outputctl.error(dlErr.message)
+                throw dlErr
+              }
+            }
+          }
+        } else if (outIsDirectory && outPath != null) {
+          // Single-result, input-backed job: preserve existing file mapping in outdir.
+          const first = allFiles[0]
+          const resultUrl = first ? getFileUrl(first.file) : null
+          if (resultUrl) {
+            outputctl.debug('DOWNLOADING')
+            const outStream = fs.createWriteStream(outPath) as OutStream
+            outStream.on('error', () => {})
+            outStream.mtime = outMtime
+            markSupersededOnFinish(outStream)
+
+            const [dlErr] = await tryCatch(
+              pipeline(got.stream(resultUrl, { signal: abortController.signal }), outStream),
+            )
+            if (dlErr) {
+              if (dlErr.name !== 'AbortError') {
+                outputctl.error(dlErr.message)
+                throw dlErr
+              }
+            }
           }
         }
       }
@@ -1272,8 +1377,9 @@ export class AssembliesCreateCommand extends AuthenticatedCommand {
       return 1
     }
 
-    // Default to stdin if no inputs and not a TTY
-    if (inputList.length === 0 && !process.stdin.isTTY) {
+    // Default to stdin only for `--steps` mode (common "pipe a file into a one-off assembly" use case).
+    // For `--template` mode, templates may be inputless or use /http/import, so stdin should be explicit (`--input -`).
+    if (this.steps && inputList.length === 0 && !process.stdin.isTTY) {
       inputList.push('-')
     }
 

package/src/cli/commands/docs.ts

@@ -0,0 +1,68 @@
+import { Option } from 'clipanion'
+import { getRobotHelp, isKnownRobot, listRobots } from '../../robots.ts'
+import { UnauthenticatedCommand } from './BaseCommand.ts'
+
+const splitRobotArgs = (values: string[]): string[] => {
+  const out: string[] = []
+  for (const value of values) {
+    for (const part of value.split(',')) {
+      const trimmed = part.trim()
+      if (trimmed) out.push(trimmed)
+    }
+  }
+  return out
+}
+
+export class DocsRobotsListCommand extends UnauthenticatedCommand {
+  static override paths = [['docs', 'robots', 'list']]
+
+  search = Option.String('--search', { description: 'Filter by substring match.' })
+  category = Option.String('--category', { description: 'Filter by category (service slug).' })
+  limit = Option.String('--limit', { description: 'Max results (default: 20).' })
+  cursor = Option.String('--cursor', { description: 'Pagination cursor.' })
+
+  protected override run(): Promise<number | undefined> {
+    const limitNum = this.limit ? Number.parseInt(this.limit, 10) : undefined
+    const result = listRobots({
+      search: this.search,
+      category: this.category,
+      limit: Number.isFinite(limitNum as number) ? (limitNum as number) : undefined,
+      cursor: this.cursor,
+    })
+
+    this.output.print(result.robots.map((r) => `${r.name}  ${r.summary}`).join('\n'), {
+      robots: result.robots,
+      nextCursor: result.nextCursor,
+    })
+
+    return Promise.resolve(0)
+  }
+}
+
+export class DocsRobotsGetCommand extends UnauthenticatedCommand {
+  static override paths = [['docs', 'robots', 'get']]
+
+  robots = Option.Rest({ required: 1 })
+
+  protected override run(): Promise<number | undefined> {
+    const requested = splitRobotArgs(this.robots)
+    const robots = []
+    const notFound: string[] = []
+
+    for (const robotName of requested) {
+      if (!isKnownRobot(robotName)) {
+        notFound.push(robotName)
+        continue
+      }
+      const help = getRobotHelp({ robotName, detailLevel: 'full' })
+      robots.push(help)
+    }
+
+    this.output.print(robots.length === 1 ? robots[0] : robots, {
+      robots,
+      notFound,
+    })
+
+    return Promise.resolve(notFound.length > 0 ? 1 : 0)
+  }
+}

package/src/cli/commands/index.ts

@@ -14,9 +14,8 @@ import {
 import { SignatureCommand, SmartCdnSignatureCommand } from './auth.ts'
 
 import { BillsGetCommand } from './bills.ts'
-
+import { DocsRobotsGetCommand, DocsRobotsListCommand } from './docs.ts'
 import { NotificationsReplayCommand } from './notifications.ts'
-
 import {
   TemplatesCreateCommand,
   TemplatesDeleteCommand,
@@ -67,5 +66,9 @@ export function createCli(): Cli {
   // Uploads commands
   cli.register(UploadCommand)
 
+  // Documentation commands (offline metadata)
+  cli.register(DocsRobotsListCommand)
+  cli.register(DocsRobotsGetCommand)
+
   return cli
 }

package/src/robots.ts

@@ -36,7 +36,7 @@ export type RobotHelp = {
 
 export type RobotHelpOptions = {
   robotName: string
-  detailLevel?: 'summary' | 'params' | 'examples'
+  detailLevel?: 'summary' | 'params' | 'examples' | 'full'
 }
 
 type RobotsMetaMap = typeof robotsMeta
@@ -299,11 +299,11 @@ export const getRobotHelp = (options: RobotHelpOptions): RobotHelp => {
   const help: RobotHelp = {
     name: path,
     summary,
-    requiredParams: detailLevel === 'params' ? params.required : [],
-    optionalParams: detailLevel === 'params' ? params.optional : [],
+    requiredParams: detailLevel === 'params' || detailLevel === 'full' ? params.required : [],
+    optionalParams: detailLevel === 'params' || detailLevel === 'full' ? params.optional : [],
   }
 
-  if (detailLevel === 'examples' && meta?.example_code) {
+  if ((detailLevel === 'examples' || detailLevel === 'full') && meta?.example_code) {
     const snippet = isRecord(meta.example_code) ? meta.example_code : {}
     help.examples = [
       {
@@ -315,3 +315,11 @@ export const getRobotHelp = (options: RobotHelpOptions): RobotHelp => {
 
   return help
 }
+
+export const isKnownRobot = (robotName: string): boolean => {
+  const { byPath, byName } = getMetaIndex()
+  const schemaIndex = getSchemaIndex()
+
+  const path = resolveRobotPath(robotName)
+  return byPath.has(path) || byName.has(robotName) || schemaIndex.has(path)
+}