transloadit 4.3.0 → 4.6.0

package/src/Transloadit.ts

@@ -52,7 +52,7 @@ import type {
 import { lintAssemblyInstructions as lintAssemblyInstructionsInternal } from './lintAssemblyInstructions.ts'
 import PaginationStream from './PaginationStream.ts'
 import PollingTimeoutError from './PollingTimeoutError.ts'
-import type { Stream } from './tus.ts'
+import type { Stream, UploadBehavior } from './tus.ts'
 import { sendTusRequest } from './tus.ts'
 
 // See https://github.com/sindresorhus/got/tree/v11.8.6?tab=readme-ov-file#errors
@@ -66,11 +66,31 @@ export {
   TimeoutError,
   UploadError,
 } from 'got'
-
 export type { AssemblyStatus } from './alphalib/types/assemblyStatus.ts'
 export * from './apiTypes.ts'
 export { InconsistentResponseError, ApiError }
+export { extractFieldNamesFromTemplate } from './alphalib/stepParsing.ts'
+// Builtin templates replace the legacy golden template helpers.
+export { mergeTemplateContent } from './alphalib/templateMerge.ts'
+export type {
+  Base64Strategy,
+  InputFile,
+  PrepareInputFilesOptions,
+  PrepareInputFilesResult,
+  UploadInput,
+  UrlStrategy,
+} from './inputFiles.ts'
+export { prepareInputFiles } from './inputFiles.ts'
 export type { LintAssemblyInstructionsResult, LintFatalLevel } from './lintAssemblyInstructions.ts'
+export type {
+  RobotHelp,
+  RobotHelpOptions,
+  RobotListItem,
+  RobotListOptions,
+  RobotListResult,
+  RobotParamHelp,
+} from './robots.ts'
+export { getRobotHelp, isKnownRobot, listRobots } from './robots.ts'
 
 const log = debug('transloadit')
 const logWarn = debug('transloadit:warn')
@@ -80,6 +100,12 @@ export interface UploadProgress {
   totalBytes?: number | undefined
 }
 
+export type { UploadBehavior }
+
+export type AssemblyStatusWithUploadUrls = AssemblyStatus & {
+  upload_urls?: Record<string, string>
+}
+
 const { version } = packageJson
 
 export type AssemblyProgress = (assembly: AssemblyStatus) => void
@@ -157,6 +183,7 @@ interface AssemblyUploadOptions {
   uploads?: {
     [name: string]: Readable | IntoStreamInput
   }
+  uploadBehavior?: UploadBehavior
   waitForCompletion?: boolean
   chunkSize?: number
   uploadConcurrency?: number
@@ -173,6 +200,10 @@ interface AssemblyUploadOptions {
 export interface CreateAssemblyOptions extends AssemblyUploadOptions {
   params?: CreateAssemblyParams
   assemblyId?: string
+  /**
+   * Expected number of tus uploads when files will be uploaded separately.
+   */
+  expectedUploads?: number
 }
 
 export interface ResumeAssemblyUploadsOptions extends AssemblyUploadOptions {
@@ -237,7 +268,7 @@ export interface SmartCDNUrlOptions {
 export type Fields = Record<string, string | number>
 
 // A special promise that lets the user immediately get the assembly ID (synchronously before the request is sent)
-interface CreateAssemblyPromise extends Promise<AssemblyStatus> {
+interface CreateAssemblyPromise extends Promise<AssemblyStatusWithUploadUrls> {
   assemblyId: string
 }
 
@@ -273,21 +304,36 @@ function checkResult<T>(result: T | { error: string }): asserts result is T {
   }
 }
 
-export interface Options {
+type AuthKeySecret = {
   authKey: string
   authSecret: string
+  authToken?: undefined
+}
+
+type AuthToken = {
+  authToken: string
+  authKey?: string
+  authSecret?: string
+}
+
+type BaseOptions = {
   endpoint?: string
   maxRetries?: number
   timeout?: number
   gotRetry?: Partial<RetryOptions>
   validateResponses?: boolean
+  clientName?: string
 }
 
+export type Options = BaseOptions & (AuthKeySecret | AuthToken)
+
 export class Transloadit {
   private _authKey: string
 
   private _authSecret: string
 
+  private _authToken: string | null
+
   private _endpoint: string
 
   private _maxRetries: number
@@ -296,28 +342,37 @@ export class Transloadit {
 
   private _gotRetry: Partial<RetryOptions>
 
+  private _clientName: string
+
   private _lastUsedAssemblyUrl = ''
 
   private _validateResponses = false
 
   constructor(opts: Options) {
-    if (opts?.authKey == null) {
-      throw new Error('Please provide an authKey')
-    }
-
-    if (opts.authSecret == null) {
-      throw new Error('Please provide an authSecret')
-    }
+    const rawToken = typeof opts?.authToken === 'string' ? opts.authToken.trim() : ''
+    const hasToken = rawToken.length > 0
 
     if (opts.endpoint?.endsWith('/')) {
       throw new Error('Trailing slash in endpoint is not allowed')
     }
 
-    this._authKey = opts.authKey
-    this._authSecret = opts.authSecret
+    if (!hasToken) {
+      if (opts?.authKey == null) {
+        throw new Error('Please provide an authKey')
+      }
+
+      if (opts.authSecret == null) {
+        throw new Error('Please provide an authSecret')
+      }
+    }
+
+    this._authKey = opts.authKey ?? ''
+    this._authSecret = opts.authSecret ?? ''
+    this._authToken = hasToken ? rawToken : null
     this._endpoint = opts.endpoint || 'https://api2.transloadit.com'
     this._maxRetries = opts.maxRetries != null ? opts.maxRetries : 5
     this._defaultTimeout = opts.timeout != null ? opts.timeout : 60000
+    this._clientName = opts.clientName?.trim() || `node-sdk:${version}`
 
     // Passed on to got https://github.com/sindresorhus/got/blob/main/documentation/7-retry.md
     this._gotRetry = opts.gotRetry != null ? opts.gotRetry : { limit: 0 }
@@ -350,7 +405,9 @@ export class Transloadit {
       files = {},
       uploads = {},
       assemblyId,
+      expectedUploads,
       signal,
+      uploadBehavior = 'await',
     } = opts
 
     // Keep track of how long the request took
@@ -406,30 +463,38 @@ export class Transloadit {
       const streamErrorPromise = createStreamErrorPromise(allStreamsMap)
 
       const createAssemblyAndUpload = async () => {
-        const result: AssemblyStatus = await this._remoteJson({
+        const totalExpectedUploads =
+          expectedUploads == null ? allStreams.length : Math.max(expectedUploads, allStreams.length)
+
+        const result: AssemblyStatusWithUploadUrls = await this._remoteJson({
           urlSuffix,
           method: 'post',
           timeout: { request: timeout },
           params,
           fields: {
-            tus_num_expected_upload_files: allStreams.length,
+            tus_num_expected_upload_files: totalExpectedUploads,
           },
           signal,
         })
         checkResult(result)
 
         if (Object.keys(allStreamsMap).length > 0) {
-          await sendTusRequest({
+          const { uploadUrls } = await sendTusRequest({
             streamsMap: allStreamsMap,
             assembly: result,
             onProgress: onUploadProgress,
             requestedChunkSize,
             uploadConcurrency,
             signal,
+            uploadBehavior,
           })
+          if (uploadBehavior !== 'await' && Object.keys(uploadUrls).length > 0) {
+            result.upload_urls = uploadUrls
+          }
         }
 
-        if (!waitForCompletion) return result
+        const shouldWaitForCompletion = waitForCompletion && uploadBehavior === 'await'
+        if (!shouldWaitForCompletion) return result
 
         if (result.assembly_id == null) {
           throw new InconsistentResponseError(
@@ -478,7 +543,9 @@ export class Transloadit {
     })
   }
 
-  async resumeAssemblyUploads(opts: ResumeAssemblyUploadsOptions): Promise<AssemblyStatus> {
+  async resumeAssemblyUploads(
+    opts: ResumeAssemblyUploadsOptions,
+  ): Promise<AssemblyStatusWithUploadUrls> {
     const {
       assemblyUrl,
       files = {},
@@ -490,12 +557,16 @@ export class Transloadit {
       onUploadProgress = () => {},
       onAssemblyProgress = () => {},
       signal,
+      uploadBehavior = 'await',
     } = opts
 
     const startTimeMs = getHrTimeMs()
 
     getAssemblyIdFromUrl(assemblyUrl)
-    const assembly = await this._fetchAssemblyStatus({ url: assemblyUrl, signal })
+    const assembly: AssemblyStatusWithUploadUrls = await this._fetchAssemblyStatus({
+      url: assemblyUrl,
+      signal,
+    })
     const statusUrl = assembly.assembly_ssl_url ?? assembly.assembly_url ?? assemblyUrl
 
     const finishedKeys = new Set<string>()
@@ -571,13 +642,25 @@ export class Transloadit {
         onProgress: onUploadProgress,
         signal,
         uploadUrls: uploadUrlsByLabel,
+        uploadBehavior,
       })
 
       await Promise.race([uploadPromise, streamErrorPromise])
+      const { uploadUrls } = await uploadPromise
+      if (uploadBehavior !== 'await' && Object.keys(uploadUrls).length > 0) {
+        assembly.upload_urls = uploadUrls
+      }
     }
 
-    const latestAssembly = await this._fetchAssemblyStatus({ url: statusUrl, signal })
-    if (!waitForCompletion) return latestAssembly
+    const latestAssembly: AssemblyStatusWithUploadUrls = await this._fetchAssemblyStatus({
+      url: statusUrl,
+      signal,
+    })
+    if (uploadBehavior !== 'await' && assembly.upload_urls) {
+      latestAssembly.upload_urls = assembly.upload_urls
+    }
+    const shouldWaitForCompletion = waitForCompletion && uploadBehavior === 'await'
+    if (!shouldWaitForCompletion) return latestAssembly
 
     if (latestAssembly.assembly_id == null) {
       throw new InconsistentResponseError(
@@ -701,6 +784,7 @@ export class Transloadit {
     const { assembly_ssl_url: url } = await this.getAssembly(assemblyId)
     const rawResult = await this._remoteJson<Record<string, unknown>, OptionalAuthParams>({
       url,
+      isTrustedUrl: true,
       method: 'delete',
     })
 
@@ -829,6 +913,7 @@ export class Transloadit {
     const rawResult = await this._remoteJson<Record<string, unknown>, OptionalAuthParams>({
       url,
       urlSuffix: url ? undefined : `/assemblies/${assemblyId}`,
+      isTrustedUrl: Boolean(url),
       signal,
     })
 
@@ -1021,6 +1106,9 @@ export class Transloadit {
     params: OptionalAuthParams,
     algorithm?: string,
   ): { signature: string; params: string } {
+    if (!this._authKey || !this._authSecret) {
+      throw new Error('Cannot sign params without authKey and authSecret.')
+    }
     const jsonParams = this._prepareParams(params)
     const signature = this._calcSignature(jsonParams, algorithm)
 
@@ -1031,6 +1119,9 @@ export class Transloadit {
    * Construct a signed Smart CDN URL. See https://transloadit.com/docs/topics/signature-authentication/#smart-cdn.
    */
   getSignedSmartCDNUrl(opts: SmartCDNUrlOptions): string {
+    if (!this._authKey || !this._authSecret) {
+      throw new Error('authKey and authSecret are required to sign Smart CDN URLs.')
+    }
     return getSignedSmartCdnUrl({
       ...opts,
       authKey: this._authKey,
@@ -1039,15 +1130,24 @@ export class Transloadit {
   }
 
   private _calcSignature(toSign: string, algorithm = 'sha384'): string {
+    if (!this._authSecret) {
+      throw new Error('Cannot sign params without authSecret.')
+    }
     return signParamsSync(toSign, this._authSecret, algorithm)
   }
 
   // Sets the multipart/form-data for POST, PUT and DELETE requests, including
   // the streams, the signed params, and any additional fields.
   private _appendForm(form: FormData, params: OptionalAuthParams, fields?: Fields): void {
-    const sigData = this.calcSignature(params)
-    const jsonParams = sigData.params
-    const { signature } = sigData
+    const shouldSign = Boolean(this._authKey && this._authSecret)
+    let jsonParams = JSON.stringify(params ?? {})
+    let signature: string | undefined
+
+    if (shouldSign) {
+      const sigData = this.calcSignature(params)
+      jsonParams = sigData.params
+      signature = sigData.signature
+    }
 
     form.append('params', jsonParams)
 
@@ -1057,16 +1157,24 @@ export class Transloadit {
       }
     }
 
-    form.append('signature', signature)
+    if (signature) {
+      form.append('signature', signature)
+    }
   }
 
   // Implements HTTP GET query params, handling the case where the url already
   // has params.
   private _appendParamsToUrl(url: string, params: OptionalAuthParams): string {
-    const { signature, params: jsonParams } = this.calcSignature(params)
-
     const prefix = url.indexOf('?') === -1 ? '?' : '&'
 
+    const shouldSign = Boolean(this._authKey && this._authSecret)
+    if (!shouldSign) {
+      const jsonParams = JSON.stringify(params ?? {})
+      return `${url}${prefix}params=${encodeURIComponent(jsonParams)}`
+    }
+
+    const { signature, params: jsonParams } = this.calcSignature(params)
+
     return `${url}${prefix}signature=${signature}&params=${encodeURIComponent(jsonParams)}`
   }
 
@@ -1102,6 +1210,7 @@ export class Transloadit {
   private async _remoteJson<TRet, TParams extends OptionalAuthParams>(opts: {
     urlSuffix?: string
     url?: string
+    isTrustedUrl?: boolean
     timeout?: Delays
     method?: 'delete' | 'get' | 'post' | 'put'
     params?: TParams
@@ -1112,6 +1221,7 @@ export class Transloadit {
     const {
       urlSuffix,
       url: urlInput,
+      isTrustedUrl = false,
       timeout = { request: this._defaultTimeout },
       method = 'get',
       params = {},
@@ -1123,6 +1233,13 @@ export class Transloadit {
     // Allow providing either a `urlSuffix` or a full `url`
     if (!urlSuffix && !urlInput) throw new Error('No URL provided')
     let url = urlInput || `${this._endpoint}${urlSuffix}`
+    if (urlInput && !isTrustedUrl) {
+      const allowed = new URL(this._endpoint)
+      const candidate = new URL(urlInput)
+      if (allowed.origin !== candidate.origin) {
+        throw new Error(`Untrusted URL: ${candidate.origin}`)
+      }
+    }
 
     if (method === 'get') {
       url = this._appendParamsToUrl(url, params)
@@ -1145,8 +1262,9 @@ export class Transloadit {
         body: form,
         timeout,
         headers: {
-          'Transloadit-Client': `node-sdk:${version}`,
+          'Transloadit-Client': this._clientName,
           'User-Agent': undefined, // Remove got's user-agent
+          ...(this._authToken ? { Authorization: `Bearer ${this._authToken}` } : {}),
           ...headers,
         },
         responseType: 'json',

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/apiTypes.ts

@@ -98,6 +98,7 @@ export type ListTemplatesParams = OptionalAuthParams & {
   fromdate?: string
   todate?: string
   keywords?: string[]
+  include_builtin?: 'all' | 'latest' | 'exclusively-all' | 'exclusively-latest'
 }
 
 interface TemplateResponseBase {
@@ -108,10 +109,13 @@ interface TemplateResponseBase {
 }
 
 export interface ListedTemplate extends TemplateResponseBase {
-  encryption_version: number
-  last_used?: string
-  created: string
-  modified: string
+  // API responses may omit or null these fields for builtin or legacy templates.
+  encryption_version?: number | null
+  last_used?: string | null
+  created?: string | null
+  modified?: string | null
+  description?: string
+  builtin_version?: string
 }
 
 export interface TemplateResponse extends TemplateResponseBase, BaseResponse {}