@transloadit/node 4.3.0 → 4.4.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,30 @@ export {
   TimeoutError,
   UploadError,
 } from 'got'
-
+export { goldenTemplates } from './alphalib/goldenTemplates.ts'
 export type { AssemblyStatus } from './alphalib/types/assemblyStatus.ts'
 export * from './apiTypes.ts'
 export { InconsistentResponseError, ApiError }
+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, listRobots } from './robots.ts'
 
 const log = debug('transloadit')
 const logWarn = debug('transloadit:warn')
@@ -80,6 +99,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 +182,7 @@ interface AssemblyUploadOptions {
   uploads?: {
     [name: string]: Readable | IntoStreamInput
   }
+  uploadBehavior?: UploadBehavior
   waitForCompletion?: boolean
   chunkSize?: number
   uploadConcurrency?: number
@@ -173,6 +199,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 +267,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,9 +303,19 @@ 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
@@ -283,11 +323,15 @@ export interface Options {
   validateResponses?: boolean
 }
 
+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
@@ -301,20 +345,26 @@ export class Transloadit {
   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
@@ -350,7 +400,9 @@ export class Transloadit {
       files = {},
       uploads = {},
       assemblyId,
+      expectedUploads,
       signal,
+      uploadBehavior = 'await',
     } = opts
 
     // Keep track of how long the request took
@@ -406,30 +458,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 +538,9 @@ export class Transloadit {
     })
   }
 
-  async resumeAssemblyUploads(opts: ResumeAssemblyUploadsOptions): Promise<AssemblyStatus> {
+  async resumeAssemblyUploads(
+    opts: ResumeAssemblyUploadsOptions,
+  ): Promise<AssemblyStatusWithUploadUrls> {
     const {
       assemblyUrl,
       files = {},
@@ -490,12 +552,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 +637,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 +779,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 +908,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 +1101,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 +1114,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 +1125,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 +1152,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 +1205,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 +1216,7 @@ export class Transloadit {
     const {
       urlSuffix,
       url: urlInput,
+      isTrustedUrl = false,
       timeout = { request: this._defaultTimeout },
       method = 'get',
       params = {},
@@ -1123,6 +1228,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)
@@ -1147,6 +1259,7 @@ export class Transloadit {
         headers: {
           'Transloadit-Client': `node-sdk:${version}`,
           'User-Agent': undefined, // Remove got's user-agent
+          ...(this._authToken ? { Authorization: `Bearer ${this._authToken}` } : {}),
           ...headers,
         },
         responseType: 'json',

package/src/alphalib/goldenTemplates.ts

@@ -0,0 +1,53 @@
+export type GoldenTemplate = {
+  slug: string
+  version: string
+  description: string
+  steps: Record<string, unknown>
+}
+
+export const goldenTemplates = {
+  '~transloadit/encode-hls-video@0.0.1': {
+    slug: '~transloadit/encode-hls-video@0.0.1',
+    version: '0.0.1',
+    description:
+      'Encode an input video into HLS renditions (270p, 360p, 540p) with an adaptive playlist.',
+    steps: {
+      ':original': {
+        robot: '/upload/handle',
+      },
+      low: {
+        robot: '/video/encode',
+        use: ':original',
+        ffmpeg_stack: 'v7.0.0',
+        preset: 'hls-270p',
+        result: true,
+        turbo: true,
+      },
+      mid: {
+        robot: '/video/encode',
+        use: ':original',
+        ffmpeg_stack: 'v7.0.0',
+        preset: 'hls-360p',
+        result: true,
+        turbo: true,
+      },
+      high: {
+        robot: '/video/encode',
+        use: ':original',
+        ffmpeg_stack: 'v7.0.0',
+        preset: 'hls-540p',
+        result: true,
+        turbo: true,
+      },
+      adaptive: {
+        robot: '/video/adaptive',
+        use: {
+          steps: ['low', 'mid', 'high'],
+          bundle_steps: true,
+        },
+        technique: 'hls',
+        playlist_name: 'my_playlist.m3u8',
+      },
+    },
+  },
+} satisfies Record<string, GoldenTemplate>

package/src/cli/commands/index.ts

@@ -25,6 +25,7 @@ import {
   TemplatesModifyCommand,
   TemplatesSyncCommand,
 } from './templates.ts'
+import { UploadCommand } from './upload.ts'
 
 export function createCli(): Cli {
   const cli = new Cli({
@@ -63,5 +64,8 @@ export function createCli(): Cli {
   // Notifications commands
   cli.register(NotificationsReplayCommand)
 
+  // Uploads commands
+  cli.register(UploadCommand)
+
   return cli
 }

package/src/cli/commands/upload.ts

@@ -0,0 +1,129 @@
+import fs from 'node:fs'
+import { Command, Option } from 'clipanion'
+import type { AssemblyStatus } from '../../alphalib/types/assemblyStatus.ts'
+import { sendTusRequest } from '../../tus.ts'
+import type { IOutputCtl } from '../OutputCtl.ts'
+import { UnauthenticatedCommand } from './BaseCommand.ts'
+
+export interface UploadOptions {
+  file: string
+  createUploadEndpoint?: string
+  resumeUploadEndpoint?: string
+  assemblyUrl: string
+  field?: string
+}
+
+const deriveEndpointFromUploadUrl = (uploadUrl: string): string => {
+  const url = new URL(uploadUrl)
+  url.pathname = url.pathname.replace(/\/[^/]*$/, '/')
+  return url.toString()
+}
+
+export async function upload(
+  output: IOutputCtl,
+  {
+    file,
+    createUploadEndpoint,
+    resumeUploadEndpoint,
+    assemblyUrl,
+    field = ':original',
+  }: UploadOptions,
+): Promise<void> {
+  const tusEndpoint =
+    createUploadEndpoint ??
+    (resumeUploadEndpoint ? deriveEndpointFromUploadUrl(resumeUploadEndpoint) : undefined)
+
+  if (!tusEndpoint) {
+    throw new Error('Provide --create-upload-endpoint or --resume-upload-endpoint.')
+  }
+
+  const stream = fs.createReadStream(file)
+  const streamsMap = {
+    [field]: { path: file, stream },
+  }
+
+  const assembly: AssemblyStatus = {
+    tus_url: tusEndpoint,
+    assembly_ssl_url: assemblyUrl,
+  } as AssemblyStatus
+
+  const { uploadUrls } = await sendTusRequest({
+    streamsMap,
+    assembly,
+    requestedChunkSize: Number.POSITIVE_INFINITY,
+    uploadConcurrency: 1,
+    onProgress: () => {},
+    uploadUrls: resumeUploadEndpoint ? { [field]: resumeUploadEndpoint } : undefined,
+  })
+
+  const uploadUrl = uploadUrls[field]
+
+  output.print(`Uploaded ${file}`, {
+    status: 'ok',
+    file,
+    field,
+    assembly_url: assemblyUrl,
+    tus_endpoint: tusEndpoint,
+    resume_upload_endpoint: resumeUploadEndpoint,
+    upload_url: uploadUrl,
+  })
+}
+
+export class UploadCommand extends UnauthenticatedCommand {
+  static override paths = [['upload']]
+
+  static override usage = Command.Usage({
+    category: 'Uploads',
+    description: 'Upload a local file to a tus endpoint for an Assembly',
+    details: `
+      Upload a local file to a tus endpoint and attach it to an existing Assembly.
+      Use --create-upload-endpoint for new uploads or --resume-upload-endpoint to resume.
+    `,
+    examples: [
+      [
+        'Upload a file to an Assembly',
+        'transloadit upload ./video.mp4 --create-upload-endpoint https://api2.transloadit.com/resumable/files/ --assembly https://api2.transloadit.com/assemblies/ASSEMBLY_ID',
+      ],
+      [
+        'Resume a file upload',
+        'transloadit upload ./video.mp4 --resume-upload-endpoint https://api2.transloadit.com/resumable/files/UPLOAD_ID --assembly https://api2.transloadit.com/assemblies/ASSEMBLY_ID',
+      ],
+    ],
+  })
+
+  file = Option.String({ required: true })
+  tusEndpoint = Option.String({ required: false })
+
+  assemblyUrl = Option.String('--assembly', {
+    description: 'Assembly URL to attach this upload to',
+    required: true,
+  })
+
+  createUploadEndpoint = Option.String('--create-upload-endpoint', {
+    description: 'Tus create endpoint (e.g. https://api2.transloadit.com/resumable/files/)',
+  })
+
+  resumeUploadEndpoint = Option.String('--resume-upload-endpoint', {
+    description: 'Tus upload URL to resume (e.g. https://.../resumable/files/<id>)',
+  })
+
+  field = Option.String('--field', {
+    description: 'Field name for the upload (default: :original)',
+  })
+
+  protected async run(): Promise<number | undefined> {
+    try {
+      await upload(this.output, {
+        file: this.file,
+        createUploadEndpoint: this.createUploadEndpoint ?? this.tusEndpoint,
+        resumeUploadEndpoint: this.resumeUploadEndpoint,
+        assemblyUrl: this.assemblyUrl,
+        field: this.field,
+      })
+      return undefined
+    } catch (err) {
+      this.output.error(err instanceof Error ? err.message : String(err))
+      return 1
+    }
+  }
+}