transloadit 6.5.0 → 6.6.1

package/src/alphalib/types/robots/tigris-store.ts

@@ -33,9 +33,7 @@ export const robotTigrisStoreInstructionsSchema = robotBase
   .merge(robotUse)
   .merge(tigrisBase)
   .extend({
-    robot: z.literal('/tigris/store').describe(`
-The URL to the result file will be returned in the <dfn>Assembly Status JSON</dfn>.
-`),
+    robot: z.literal('/tigris/store'),
     path: storeFilePath,
     acl: storageAcl,
     headers: z
@@ -62,6 +60,7 @@ If this parameter is not used, no URL signing is done.
       .describe('The region of your Tigris bucket. This is optional as it can often be derived.'),
   })
   .strict()
+  .describe('The URL to the result file will be returned in the <dfn>Assembly Status JSON</dfn>.')
 
 export const robotDefinition: RobotDefinition<typeof robotTigrisStoreInstructionsSchema.shape> =
   defineRobot(meta, robotTigrisStoreInstructionsSchema)

package/src/alphalib/types/robots/transloadit-import.ts

@@ -40,12 +40,15 @@ Whether to import files from subfolders and sub-subfolders when \`path\` is a fo
 only the folder's own files are imported.
 `
 
-/** Storage imports require proof of possession independently of Workspace signature settings. */
+/** Private Storage imports require proof of possession independently of Workspace settings. */
 export const transloaditImportAuthenticationGuidanceLines = [
   'Assemblies that use `/transloadit/import`, directly or through a Template, require',
   'either a bearer token or signed `params` with a future `params.auth.expires` timestamp.',
   'This applies even when Workspace Signature Authentication is disabled. An Auth Key alone',
   'is not sufficient; bearer-authenticated requests do not need a separate signature or expiry.',
+  'Public Storage Builtin Templates are the exception: they can serve unsigned requests only',
+  'when every Storage import remains within a declared public prefix. This does not authorize',
+  'unsigned Assemblies with arbitrary Steps or access to private Storage paths.',
 ] as const
 
 export const meta: RobotMetaInput = {

package/src/alphalib/types/robots/transloadit-store.ts

@@ -64,6 +64,25 @@ existing asset. Always save the returned asset identity, version and final path.
 Sets the destination path inside your Transloadit Storage workspace, relative to its root: a
 filename, or folders and a filename such as \`website/hero.jpg\`. Folders that do not exist yet
 are created.
+
+Repeated interior slashes are collapsed after variable interpolation. For example,
+\`a/\${file.meta.relative_path}/\${file.name}\` stores a root-level HLS playlist as
+\`a/playlist.m3u8\` when \`relative_path\` is empty. Leading or trailing slashes and
+\`.\` or \`..\` segments remain invalid.
+`),
+    result: z
+      .boolean()
+      .default(true)
+      .describe(`
+Leave \`result\` unset or set it to \`true\` on this Storage Step. Setting \`result: false\`
+here can omit stored entries, including asset and version IDs, from the Assembly Status JSON
+even though the files are stored.
+
+Stored results appear under their producing Step in the Assembly Status JSON, or under
+\`:original\` for uploaded files, rather than under this Storage Step. Setting \`result: false\`
+on a producing processing Step also omits its stored entries, including asset and version IDs,
+from the Assembly Status JSON even though the files are stored. Leave \`result\` unset or set it
+to \`true\` on that Step to receive those identities.
 `),
   })
   .strict()

package/src/alphalib/types/robots/video-adaptive.ts

@@ -71,6 +71,18 @@ This <dfn>Robot</dfn> accepts all types of video files and audio files. Do not f
 
 This <dfn>Robot</dfn> is normally used in combination with [🤖/video/encode](/docs/robots/video-encode/). We have implemented video and audio encoding presets specifically for MPEG-Dash and HTTP Live Streaming support. These presets are prefixed with \`"dash/"\` and \`"hls/"\`. [View a HTTP Live Streaming demo here](/demos/video-encoding/implement-http-live-streaming/).
 
+### HLS subtitles
+
+With \`"technique": "hls"\`, the first embedded subtitle track of each input is converted to segmented WebVTT and linked from the master playlist. Additional subtitle tracks in the same input are dropped. The Assembly adds a warning when any input contains more than one subtitle track.
+
+To add a track before packaging, use [🤖/video/subtitle](/docs/robots/video-subtitle/) with \`"subtitles_type": "external"\`, \`"preset": "empty"\`, and a \`language\` such as \`"eng"\`. Then encode with an \`"hls/"\` preset and pass the encoded video to this Robot. By default, the playlist’s subtitle \`NAME\` uses the language’s English name, for example “English”; its \`LANGUAGE\` preserves the input’s language tag. Unrecognized language codes are used as the name. If the language is missing or \`"und"\`, the name is “Unknown”. Custom \`ffmpeg.var_stream_map\` mappings control their own subtitle labels.
+
+To set an explicit subtitle name in a custom \`ffmpeg.var_stream_map\`, select \`"ffmpeg_stack": "v8.0.0"\` and use its \`sname\` option.
+
+WebVTT cues and MPEG-TS video use the same timestamp timeline. AAC priming or video frame reordering can move both after zero, so a small nonzero first cue timestamp does not by itself mean subtitles are delayed. Preserve the generated timestamps to keep subtitles synchronized with the video. When any input to an HLS Step has subtitles, \`ffmpeg.muxdelay\` defaults to \`0\` for the whole Step, including renditions without subtitles. Overriding it or other timestamp options can change that alignment.
+
+Store the WebVTT segments and subtitle playlists along with all other results, preserving \`\${file.meta.relative_path}\` as described below.
+
 ### CMAF aspect ratios
 
 CMAF aligns near-equal rendition aspect ratios, within 1% of the largest rendition, without re-encoding or changing pixel dimensions. This lets presets such as \`"hls/480p"\` and \`"hls/720p"\` support bitrate switching together.

package/src/alphalib/types/robots/video-concat.ts

@@ -8,6 +8,7 @@ import { z } from 'zod'
 
 import {
   defineRobot,
+  getConcatFadeDescription,
   inputSortBySchema,
   robotBase,
   robotFFmpegVideo,
@@ -67,23 +68,23 @@ It’s possible to concatenate a virtually infinite number of video files using
 `),
     video_fade_seconds: z
       .number()
-      .default(1)
+      .default(0)
       .describe(`
-When used this adds a video fade in and out effect between each section of your concatenated video. The float value is used so if you want a video delay effect of 500 milliseconds between each video section you would select \`0.5\`, however, integer values can also be represented.
+${getConcatFadeDescription('video')}
 
-This parameter does not add a video fade effect at the beginning or end of your video. If you want to do so, create an additional [🤖/video/encode](/docs/robots/video-encode/) Step and use our \`ffmpeg\` parameter as shown in this [demo](/demos/video-encoding/concatenate-fade-effect/).
+This parameter only applies when \`transition\` is \`"none"\`. It is ignored when \`transition\` is \`"crossfade"\` or \`"fade_to_black"\`; use \`transition_duration\` for those effects. Audio fades are controlled separately by \`audio_fade_seconds\`.
 
-Please note this parameter is independent of adding audio fades between sections.
+To add a fade-in at the beginning of the output, use an additional [video encoding Step](/docs/robots/video-encode/) with the \`ffmpeg\` parameter, as shown in the [video fade demo](/demos/video-encoding/concatenate-fade-effect/).
 `),
     audio_fade_seconds: z
       .number()
-      .default(1)
+      .default(0)
       .describe(`
-When used this adds an audio fade in and out effect between each section of your concatenated video. The float value is used so if you want an audio delay effect of 500 milliseconds between each video section you would select \`0.5\`, however, integer values can also be represented.
+${getConcatFadeDescription('audio')}
 
-This parameter does not add an audio fade effect at the beginning or end of your video. If you want to do so, create an additional [🤖/video/encode](/docs/robots/video-encode/) Step and use our \`ffmpeg\` parameter as shown in this [demo](/demos/audio-encoding/ffmpeg-fade-in-and-out/).
+This parameter only applies when \`transition\` is \`"none"\`. It is ignored when \`transition\` is \`"crossfade"\` or \`"fade_to_black"\`; use \`transition_duration\` for those effects. Video fades are controlled separately by \`video_fade_seconds\`.
 
-Please note this parameter is independent of adding video fades between sections.
+To add an audio fade-in at the beginning of the output, use an additional [video encoding Step](/docs/robots/video-encode/) with the \`ffmpeg\` parameter. The [audio fade demo](/demos/audio-encoding/ffmpeg-fade-in-and-out/) shows the corresponding FFmpeg audio filter.
 `),
     chapter_markers: z
       .boolean()

package/src/alphalib/types/robots/video-thumbs.ts

@@ -91,18 +91,18 @@ For an upload-to-poster Template, SDK usage, and publication checks, see the [HT
     count: thumbnailCountSchema.describe(`
 The number of thumbnails to be extracted. As some videos have incorrect durations, the actual number of thumbnails generated may be less in rare cases. The maximum number of thumbnails we currently allow is 999.
 
-The thumbnails are taken at regular intervals, determined by dividing the video duration by the count. For example, a count of 3 will produce thumbnails at 25%, 50% and 75% through the video.
+When \`smart\` is \`false\`, the thumbnails are taken at regular intervals. For example, a count of 3 produces thumbnails at 25%, 50% and 75% through the video. With \`smart: true\`, this is the number of thumbnails selected from the candidate pool instead.
 
 To extract thumbnails for specific timestamps, use the \`offsets\` parameter.
 `),
     offsets: z
-      .union([z.array(z.number().finite()), z.array(percentageSchema)])
+      .union([z.array(z.number().finite()).min(1), z.array(percentageSchema).min(1)])
       .nullable()
-      .default([])
+      .optional()
       .describe(`
 An array of offsets representing seconds of the file duration, such as \`[ 2, 45, 120 ]\`. Millisecond durations of a file can also be used by using decimal place values. For example, an offset from 1250 milliseconds would be represented with \`1.25\`. Offsets can also be percentage values such as \`[ "2%", "50%", "75%" ]\`.
 
-This option cannot be used with the \`count\` parameter, and takes precedence if both are specified. Out-of-range offsets are silently ignored.
+When \`smart\` is \`false\`, \`offsets\` takes precedence over \`count\`. Request timestamps within the video duration. If FFmpeg produces no frame at a requested offset, the Robot may retry without timestamp seeking and return an early frame instead. It does not simply ignore the offset, and extraction can still fail if no frame is available.
 
 When \`smart\` is \`true\`, smart selection ignores \`offsets\` and uses \`count\` to select from its own candidate timestamps. If no smart candidates can be extracted, the Robot falls back to standard extraction, where \`offsets\` takes precedence. Use \`smart: false\` to consistently extract the specified timestamps.
 
@@ -128,17 +128,17 @@ The width of the thumbnail, in pixels. Omit or use \`null\` for the original wid
       .number()
       .int()
       .min(1)
-      .max(1080)
+      .max(1920)
       .nullable()
       .optional()
       .describe(`
-The height of the thumbnail, in pixels. Omit or use \`null\` for the original height of the video.
+The thumbnail height in pixels, capped like \`width\`. Omit or use \`null\` for the original height.
 `),
     resize_strategy: resize_strategy.describe(`
 One of the [available resize strategies](/docs/topics/resize-strategies/).
 `),
-    background: color_with_alpha.default('#00000000').describe(`
-The background color of the resulting thumbnails in the \`"rrggbbaa"\` format (red, green, blue, alpha) when used with the \`"pad"\` resize strategy. The default color is black.
+    background: color_with_alpha.default('#000000ff').describe(`
+The background color of the resulting thumbnails in the \`"rrggbbaa"\` format (red, green, blue, alpha) when used with the \`"pad"\` resize strategy. The default color is opaque black.
 `),
     rotate: z
       .union([z.literal(0), z.literal(90), z.literal(180), z.literal(270), z.literal(360)])

package/src/alphalib/types/robots/vimeo-store.ts

@@ -39,7 +39,7 @@ export const robotVimeoStoreInstructionsSchema = robotBase
     robot: z.literal('/vimeo/store').describe(`
 ## Getting started
 
-Since Vimeo works with OAuth, you will need to generate [Template Credentials](https://transloadit.com/c/template-credentials/) to use this <dfn>Robot</dfn>.
+Create [Template Credentials](https://transloadit.com/c/template-credentials/) using Vimeo OAuth for uploads, or paste your own personal access token. A personal token needs \`upload\`, \`edit\`, and \`interact\` for this <dfn>Robot</dfn>, plus \`public\`, \`private\`, and \`video_files\` when saving it through the Console for imports. Your Vimeo app must have upload access. Follow the [Vimeo token instructions](/docs/topics/template-credentials/#vimeo) to create a token or reconnect.
 
 To change the \`title\` or \`description\` per video, we recommend to [inject variables into your Template](/docs/topics/templates/).
 

package/src/alphalib/types/templateValues.ts

@@ -0,0 +1,157 @@
+import type { SimpleValueReason } from '../renderSimpleValue.ts'
+
+import { formatSimpleValueReason } from '../renderSimpleValue.ts'
+
+/** Usage in MiB charged for each dynamically evaluated Assembly expression. */
+export const expressionEvaluationUsageMebibytes = 0.2
+
+/** Character domain shared by stored Template IDs and their pagination cursors. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Stored Template IDs allow the full ASCII range.
+export const storedTemplateIdentifierPattern = /^[\x00-\x7F]*$/u
+
+/** Template Assembly Status retention values shared by runtime validation and contracts. */
+export const templateAssemblyStatusExpiries = Object.freeze({
+  noTmpFileRetention: 'NoSave',
+  oneDay: '1day',
+  sevenDays: '7days',
+  thirtyDays: '30days',
+  ninetyDays: '90days',
+})
+
+/** Template transcoding-result retention values shared by runtime validation and contracts. */
+export const templateTranscodingResultExpiries = Object.freeze({
+  noTmpFileRetention: 'NoSave',
+  oneDay: '1day',
+})
+
+/** Default storage lifecycle selections; separate from upload and execution phase timeouts. */
+export const templateRetentionDefaults = Object.freeze({
+  assemblyStatus: templateAssemblyStatusExpiries.ninetyDays,
+  transcodingResult: templateTranscodingResultExpiries.oneDay,
+})
+
+export const templateListFieldValues = [
+  'account_id',
+  'assembly_status_expiry',
+  'cron_auth_key_id',
+  'cron_enabled',
+  'cron_max_concurrent_runs',
+  'cron_region',
+  'cron_schedule_with_seconds',
+  'created',
+  'deleted',
+  'encryption_version',
+  'id',
+  'json',
+  'last_used',
+  'modified',
+  'name',
+  'require_signature_auth',
+  'transcoding_result_expiry',
+] as const
+
+export type TemplateListField = (typeof templateListFieldValues)[number]
+
+export const templateListDefaultFields = [
+  'id',
+  'name',
+  'json',
+  'encryption_version',
+  'require_signature_auth',
+  'assembly_status_expiry',
+  'transcoding_result_expiry',
+  'last_used',
+  'created',
+  'modified',
+] as const satisfies readonly TemplateListField[]
+
+export const templateListOrderValues = ['asc', 'desc'] as const
+export type TemplateListOrder = (typeof templateListOrderValues)[number]
+
+export const templateListSortValues = ['id', 'name', 'created', 'modified', 'last_used'] as const
+export type TemplateListSort = (typeof templateListSortValues)[number]
+
+export const templateIncludeBuiltinModes = ['none', 'latest', 'all'] as const
+export type TemplateIncludeBuiltinMode = (typeof templateIncludeBuiltinModes)[number]
+
+export const templateIncludeBuiltinValues = [
+  ...templateIncludeBuiltinModes,
+  'exclusively-latest',
+  'exclusively-all',
+] as const
+export type TemplateIncludeBuiltinValue = (typeof templateIncludeBuiltinValues)[number]
+
+/** Canonical Template-list defaults shared by API2 and generated clients. */
+export const templateListDefaults = Object.freeze({
+  includeBuiltin: 'none',
+  keywords: '',
+  order: 'desc',
+  page: 1,
+  pagesize: 850,
+  sort: 'created',
+} satisfies {
+  includeBuiltin: TemplateIncludeBuiltinValue
+  keywords: string
+  order: TemplateListOrder
+  page: number
+  pagesize: number
+  sort: TemplateListSort
+})
+
+/** Maximum page size accepted by Template listing. */
+export const templateListMaxPageSize = 850
+
+/** Code-unit length retained for the private admin Workspace override. */
+export const templateListWorkspaceIdCodeUnits = 32
+
+/** Maximum customer-supplied characters retained in a Template-list error reason. */
+export const templateListInvalidRequestValueMaxCharacters = 200
+
+/** Handler-priority Template-list validation reasons shared by runtime and contract enforcement. */
+export const templateListInvalidRequestReasons = {
+  order: {
+    message: 'Invalid order (must be "asc" or "desc")',
+    value: 'string',
+  },
+  sort: {
+    message: 'Invalid sort (must be "created", "modified", "name", "id" or "last_used")',
+    suffix: '.',
+    value: 'string',
+  },
+  pagesize: {
+    message: `Invalid pagesize (must be between 1 and ${templateListMaxPageSize})`,
+    suffix: '.',
+    value: 'integer-prefix',
+  },
+  page: {
+    message: 'Invalid page',
+    suffix: '.',
+    value: 'integer-prefix',
+  },
+  account_id: {
+    message: 'Invalid accountId',
+    suffix: '.',
+    value: 'string',
+  },
+  include_builtin: {
+    message: 'Invalid include_builtin',
+    value: 'string',
+  },
+} satisfies Record<string, SimpleValueReason>
+
+export type TemplateListInvalidRequestField = keyof typeof templateListInvalidRequestReasons
+
+/** Formats one established Template-list reason from its shared contract fact. */
+export function formatTemplateListInvalidRequestReason(
+  field: TemplateListInvalidRequestField,
+  value: unknown,
+): string {
+  const reason = templateListInvalidRequestReasons[field]
+  return formatSimpleValueReason(
+    typeof value === 'number' && reason.value === 'integer-prefix'
+      ? { ...reason, value: 'string' }
+      : reason,
+    value,
+    templateListInvalidRequestValueMaxCharacters,
+  )
+}

package/src/cli/stepsInput.ts

@@ -13,11 +13,44 @@ import { CliInputError, formatSchemaIssues } from './errors.ts'
 
 const stepsWrapperSchema = z.object({ steps: z.record(z.unknown()) })
 
-/** CLI inputs can be partial overrides; API2 validates OCR after merging their runtime context. */
+/** CLI overrides warn on new parameters and defer contextual OCR checks to API2. */
 export function createCliStepsSchema(
   output: Pick<IOutputCtl, 'warn'> = console,
 ): z.ZodType<StepsInput> {
-  const cliStepSchema = robotsSchema
+  const cliStepSchema = z
+    .object({ robot: z.string() })
+    .catchall(z.unknown())
+    .transform((step, context) => {
+      let validated = robotsSchema.safeParse(step, { path: context.path })
+      const unknownKeys = new Set<string>()
+      if (!validated.success) {
+        for (const issue of validated.error.issues) {
+          // Only new top-level Robot parameters are advisory; nested objects stay strict.
+          if (issue.code !== 'unrecognized_keys' || issue.path.length !== context.path.length)
+            continue
+          for (const key of issue.keys) unknownKeys.add(key)
+        }
+        if (unknownKeys.size > 0) {
+          validated = robotsSchema.safeParse(
+            Object.fromEntries(Object.entries(step).filter(([key]) => !unknownKeys.has(key))),
+            { path: context.path },
+          )
+        }
+      }
+      if (!validated.success) {
+        for (const issue of validated.error.issues) {
+          // Keep nested union diagnostics rooted at the Step while addIssue prefixes its own path.
+          context.addIssue({ ...issue, path: issue.path.slice(context.path.length) })
+        }
+        return z.NEVER
+      }
+      if (unknownKeys.size > 0) {
+        output.warn(
+          `${context.path.join('.')}: Unrecognized step parameters: ${[...unknownKeys].join(', ')}. Preserving them for API validation when submitted.`,
+        )
+      }
+      return { ...step, ...validated.data }
+    })
     .superRefine(refineTransloaditImportSelector)
     .superRefine((step, context) => {
       // API2 merges Template defaults before Robot validation. New OCR checks must not reject