transloadit 4.14.0 → 5.0.1

package/src/alphalib/types/robots/_instructions-primitives.ts

@@ -1,8 +1,17 @@
-import type { Replace } from 'type-fest'
+import type { StringReplaceAll } from '../utility.ts'
 
 import { z } from 'zod'
 
-import { stackVersions } from '../stackVersions.ts'
+import { formatEnglishList } from '../../englishList.ts'
+import {
+  ecmaWhitespaceCharacterClass,
+  zodInputPreservingTransform,
+  zodStableJsonDefault,
+  zodWithConservativeJsonInputSchema,
+  zodWithJsonInputSchema,
+} from '../../lib/zodInputSemantics.ts'
+import { inheritApiParameterDescription } from '../apiParameterDescription.ts'
+import { runtimeStackVersions, stackVersions } from '../stackVersions.ts'
 
 export const robotNames = z.enum([
   'AiChatRobot',
@@ -80,6 +89,7 @@ export const robotNames = z.enum([
   'DropboxImportRobot',
   'DropboxStoreRobot',
   'HttpImportRobot',
+  'HttpRequestRobot',
   'SftpImportRobot',
   'SftpStoreRobot',
   'FtpImportRobot',
@@ -102,12 +112,17 @@ export const robotNames = z.enum([
   'TextSpeakRobot',
   'TextTranslateRobot',
   'FilePreviewRobot',
+  'TusStoreRobot',
   'TransloaditImportRobot',
   'TransloaditStoreRobot',
-  'TusStoreRobot',
   'ProgressSimulateRobot',
 ])
 
+const awsGcpMinimumChargeUsdSchema = z.object({
+  aws: z.number(),
+  gcp: z.number(),
+})
+
 export const robotMetaSchema = z.object({
   // Added keys from api2/lib/config.ts:
   name: robotNames,
@@ -117,18 +132,12 @@ export const robotMetaSchema = z.object({
   preserveInputFileUrls: z.boolean().optional(),
   minimumCharge: z.number().optional(),
   minimumChargeUsd: z.number().optional(),
-  minimumChargeUsdPerSpeechTranscribeMinute: z
-    .object({
-      aws: z.number(),
-      gcp: z.number(),
-    })
-    .optional(),
-  minimumChargeUsdPerDocumentOcrPage: z
-    .object({
-      aws: z.number(),
-      gcp: z.number(),
+  minimumChargeUsdPerSpeechTranscribeMinute: awsGcpMinimumChargeUsdSchema
+    .extend({
+      replicate: z.literal('variable').optional(),
     })
     .optional(),
+  minimumChargeUsdPerDocumentOcrPage: awsGcpMinimumChargeUsdSchema.optional(),
   applyCommunityPlanMediaTrim: z.boolean().optional(),
   isAllowedForUrlTransform: z.boolean(),
   removeJobResultFilesFromDiskRightAfterStoringOnS3: z.boolean(),
@@ -142,22 +151,14 @@ export const robotMetaSchema = z.object({
   extraChargeForImageResize: z.number().optional(),
 
   // Original keys from content repo:
-  bytescount: z.number(),
   description: z.string().optional(),
-  discount_factor: z.number(),
-  discount_pct: z.number(),
-  // To avoid a cycling dependency back to template.ts, we'll use any for now:
-  // example_code: assemblyInstructionsSchema.optional(),
-  example_code: z.any().optional(),
+  // Validate against assembled public Robot schemas at publication, outside this dependency cycle.
+  example_code: z.unknown().optional(),
   example_code_description: z.string().optional(),
   extended_description: z.string().optional(),
   has_small_icon: z.literal(true).optional(),
-  minimum_charge: z.number(),
-  minimum_charge_usd: z.union([z.number(), z.record(z.string(), z.number())]).optional(),
-  minimum_charge_usd_note: z.string().optional(),
   ogimage: z.string().optional(),
   marketing_intro: z.string().optional(),
-  output_factor: z.number(),
   override_lvl1: z.string().optional(),
   purpose_sentence: z.string(),
   purpose_verb: z.enum([
@@ -212,11 +213,10 @@ export const robotMetaSchema = z.object({
     'file-filtering',
     'file-importing',
     'handling-uploads',
-    'image-manipulation',
+    'image-processing',
     'media-cataloging',
     'video-encoding',
   ]),
-  slot_count: z.number(),
   title: z.string(),
   typical_file_size_mb: z.number(),
   typical_file_type: z.enum([
@@ -233,6 +233,193 @@ export const robotMetaSchema = z.object({
 
 export type RobotMetaInput = z.input<typeof robotMetaSchema>
 
+/** Shared processing metadata; per-Robot exceptions stay explicit. */
+export const robotProcessingMeta = {
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+  queueSlotCount: 10,
+  priceFactor: 1,
+  isAllowedForUrlTransform: true,
+  isInternal: false,
+  removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
+  stage: 'ga',
+} satisfies Partial<RobotMetaInput>
+
+/** Shared artificial-intelligence metadata; exceptions stay local. */
+export const robotArtificialIntelligenceMeta = {
+  ...robotProcessingMeta,
+  service_slug: 'artificial-intelligence',
+  typical_file_type: 'image',
+  trackOutputFileSize: true,
+} satisfies Partial<RobotMetaInput>
+
+/** Shared audio-encoding metadata; exceptions stay local. */
+export const robotAudioEncodingMeta = {
+  ...robotProcessingMeta,
+  override_lvl1: 'Audio Encoding',
+  service_slug: 'audio-encoding',
+  typical_file_size_mb: 3.8,
+  typical_file_type: 'audio file',
+  priceFactor: 4,
+  queueSlotCount: 20,
+  trackOutputFileSize: true,
+  applyCommunityPlanMediaTrim: true,
+} satisfies Partial<RobotMetaInput>
+
+/** Shared document-processing metadata; exceptions stay local. */
+export const robotDocumentProcessingMeta = {
+  ...robotProcessingMeta,
+  override_lvl1: 'Document Processing',
+  service_slug: 'document-processing',
+  typical_file_size_mb: 0.8,
+  typical_file_type: 'document',
+  minimumCharge: 1048576,
+} satisfies Partial<RobotMetaInput>
+
+/** Shared content-delivery metadata; exceptions stay local. */
+export const robotContentDeliveryMeta = {
+  ...robotProcessingMeta,
+  service_slug: 'content-delivery',
+  queueSlotCount: 0,
+  downloadInputFiles: false,
+  preserveInputFileUrls: true,
+  isAllowedForUrlTransform: false,
+  trackOutputFileSize: false,
+  isInternal: true,
+} satisfies Partial<RobotMetaInput>
+
+/** Shared file-filtering metadata; exceptions stay local. */
+export const robotFileFilteringMeta = {
+  ...robotProcessingMeta,
+  override_lvl1: 'File Filtering',
+  service_slug: 'file-filtering',
+  trackOutputFileSize: true,
+} satisfies Partial<RobotMetaInput>
+
+/** Shared media-cataloging metadata; exceptions stay local. */
+export const robotMediaCatalogingMeta = {
+  ...robotProcessingMeta,
+  override_lvl1: 'Media Cataloging',
+  service_slug: 'media-cataloging',
+  queueSlotCount: 15,
+} satisfies Partial<RobotMetaInput>
+
+/** Shared image-processing metadata; exceptions stay local. */
+export const robotImageProcessingMeta = {
+  ...robotProcessingMeta,
+  override_lvl1: 'Image Processing',
+  service_slug: 'image-processing',
+  typical_file_size_mb: 0.8,
+  typical_file_type: 'image',
+} satisfies Partial<RobotMetaInput>
+
+/** Shared code-evaluation metadata; exceptions stay local. */
+export const robotCodeEvaluationMeta = {
+  ...robotProcessingMeta,
+  override_lvl1: 'Code Evaluation',
+  service_slug: 'code-evaluation',
+  isAllowedForUrlTransform: false,
+  trackOutputFileSize: true,
+} satisfies Partial<RobotMetaInput>
+
+/** Shared video-encoding metadata; exceptions stay local. */
+export const robotVideoEncodingMeta = {
+  ...robotProcessingMeta,
+  override_lvl1: 'Video Encoding',
+  service_slug: 'video-encoding',
+  typical_file_size_mb: 80,
+  typical_file_type: 'video',
+  queueSlotCount: 60,
+  isAllowedForUrlTransform: false,
+  trackOutputFileSize: true,
+  applyCommunityPlanMediaTrim: true,
+} satisfies Partial<RobotMetaInput>
+
+/** Shared import metadata; provider-specific prices, queues, and flags override it locally. */
+export const robotImportMeta = {
+  override_lvl1: 'File Importing',
+  purpose_verb: 'import',
+  service_slug: 'file-importing',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+  priceFactor: 6.6666,
+  queueSlotCount: 20,
+  isAllowedForUrlTransform: true,
+  trackOutputFileSize: false,
+  isInternal: false,
+  removeJobResultFilesFromDiskRightAfterStoringOnS3: true,
+  stage: 'ga',
+} satisfies Partial<RobotMetaInput>
+
+/** Shared store metadata; provider-specific prices, queues, and flags override it locally. */
+export const robotStoreMeta = {
+  override_lvl1: 'File Exporting',
+  purpose_verb: 'export',
+  service_slug: 'file-exporting',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+  priceFactor: 6.6666,
+  queueSlotCount: 10,
+  isAllowedForUrlTransform: true,
+  trackOutputFileSize: false,
+  isInternal: false,
+  removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
+  stage: 'ga',
+} satisfies Partial<RobotMetaInput>
+
+/** Single-Step processing example; unusual input relationships stay explicit. */
+export function createProcessingExample(
+  name: string,
+  robot: string,
+  parameters: Record<string, unknown> = {},
+): { steps: Record<string, Record<string, unknown>> } {
+  return { steps: { [name]: { robot, use: ':original', ...parameters } } }
+}
+
+interface StorageExampleStep {
+  robot: string
+  credentials: string
+  path: string
+  recursive?: true
+  use?: ':original'
+}
+
+interface StorageRobotExample {
+  steps: Record<string, StorageExampleStep>
+}
+
+/** Standard directory import example; nonrecursive providers omit the flag. */
+export function createStorageImportExample(
+  robot: string,
+  credentials: string,
+  recursive = true,
+): StorageRobotExample {
+  return {
+    steps: {
+      imported: {
+        robot,
+        credentials,
+        path: 'path/to/files/',
+        ...(recursive ? { recursive: true } : {}),
+      },
+    },
+  }
+}
+
+/** Standard export example shared by compatible storage providers. */
+export function createStorageStoreExample(robot: string, credentials: string): StorageRobotExample {
+  return {
+    steps: {
+      exported: {
+        robot,
+        use: ':original',
+        credentials,
+        path: 'my_target_folder/${unique_prefix}/${file.url_name}',
+      },
+    },
+  }
+}
+
 // These schemas can be reproduced with z.string().regex(). However, this causes some issues.
 // We use this in combination with unions. Internally Zod normalizes unions. A string schema and
 // enums merged in some way. Both are validated. Normally, if a Zod union has errors, all of them
@@ -242,29 +429,24 @@ export type RobotMetaInput = z.input<typeof robotMetaSchema>
 // is more useful in pretty much every case. To work around this, we use z.custom() instead, as Zod
 // can’t normalize that.
 const interpolationRegexFull = /^\${.+}$/
-export const interpolationSchemaFull = z.custom<`\${${string}}`>(
-  (input) => typeof input === 'string' && interpolationRegexFull.test(input),
-  'Must be a full interpolation string',
+export const interpolationSchemaFull = zodWithJsonInputSchema(
+  z.custom<`\${${string}}`>(
+    (input) => typeof input === 'string' && interpolationRegexFull.test(input),
+    'Must be a full interpolation string',
+  ),
+  z.string().regex(/^\$\{[^\n\r\u2028\u2029]+\}$/u),
 )
 const interpolationRegexPartial = /\${.+}/
-export const interpolationSchemaPartial = z.custom<string>(
-  (input) => typeof input === 'string' && interpolationRegexPartial.test(input),
-  'Must be a partially interpolatable string',
+export const interpolationSchemaPartial = zodWithJsonInputSchema(
+  z.custom<string>(
+    (input) => typeof input === 'string' && interpolationRegexPartial.test(input),
+    'Must be a partially interpolatable string',
+  ),
+  z.string().regex(/\$\{[^\n\r\u2028\u2029]+\}/u),
 )
 
 export const booleanStringSchema = z.enum(['true', 'false'])
 
-export const inputSortBySchema = z
-  .enum(['auto', 'basename', 'import_order'])
-  .default('basename')
-  .describe(`
-Controls how bundled inputs are ordered when no explicit numbered alias such as \`video_1\` or \`document_1\` is used.
-
-The default \`"basename"\` keeps the legacy natural basename sorting behavior.
-
-Set this to \`"import_order"\` to preserve the order of array-based import steps when all input files carry complete import order metadata. \`"auto"\` has the same import-order preference with natural basename sorting as fallback.
-`)
-
 type InterpolatableTuple<Schemas extends readonly z.ZodTypeAny[]> = Schemas extends readonly [
   infer Head extends z.ZodTypeAny,
   ...infer Rest extends z.ZodTypeAny[],
@@ -348,9 +530,9 @@ function toInterpolatableUnionOptions(options: z.ZodTypeAny[]): z.ZodUnionOption
   return [head, ...tail]
 }
 
-export function interpolateRecursive<Schema extends z.ZodFirstPartySchemaTypes>(
-  schema: Schema,
-): InterpolatableSchema<Schema> {
+function interpolateRecursiveWithoutDescriptionRegistration<
+  Schema extends z.ZodFirstPartySchemaTypes,
+>(schema: Schema): InterpolatableSchema<Schema> {
   const def = schema._def
 
   switch (def.typeName) {
@@ -358,20 +540,21 @@ export function interpolateRecursive<Schema extends z.ZodFirstPartySchemaTypes>(
       return toInterpolatableSchema(
         z.union([
           interpolationSchemaFull,
-          z
-            .union([schema, booleanStringSchema])
-            .transform((value) => value === true || value === false),
+          zodInputPreservingTransform(
+            z.union([schema, booleanStringSchema]),
+            (value) => value === true || value === 'true',
+          ),
         ]),
       )
     case z.ZodFirstPartyTypeKind.ZodArray: {
       let replacement = z.array(interpolateRecursive(def.type), def)
 
       if (def.exactLength != null) {
-        replacement = replacement.min(def.exactLength.value, def.exactLength.message)
+        replacement = replacement.length(def.exactLength.value, def.exactLength.message)
       }
 
       if (def.maxLength != null) {
-        replacement = replacement.min(def.maxLength.value, def.maxLength.message)
+        replacement = replacement.max(def.maxLength.value, def.maxLength.message)
       }
 
       if (def.minLength != null) {
@@ -381,28 +564,45 @@ export function interpolateRecursive<Schema extends z.ZodFirstPartySchemaTypes>(
       return toInterpolatableSchema(z.union([interpolationSchemaFull, replacement]))
     }
     case z.ZodFirstPartyTypeKind.ZodDefault: {
-      const replacement = toInterpolatableSchema<Schema>(
-        interpolateRecursive(def.innerType),
-      ).default(def.defaultValue())
+      const replacement = zodStableJsonDefault(
+        toInterpolatableSchema<Schema>(interpolateRecursive(def.innerType)),
+        def.defaultValue(),
+      )
 
       return toInterpolatableSchema(
         def.description ? replacement.describe(def.description) : replacement,
       )
     }
     case z.ZodFirstPartyTypeKind.ZodEffects:
+      return toInterpolatableSchema(
+        z.union(
+          [
+            def.schema instanceof z.ZodString
+              ? interpolationSchemaPartial
+              : interpolationSchemaFull,
+            schema,
+          ],
+          def,
+        ),
+      )
     case z.ZodFirstPartyTypeKind.ZodEnum:
     case z.ZodFirstPartyTypeKind.ZodLiteral:
       return toInterpolatableSchema(z.union([interpolationSchemaFull, schema], def))
     case z.ZodFirstPartyTypeKind.ZodNumber:
+      if (!(schema instanceof z.ZodNumber)) {
+        throw new Error('A ZodNumber definition must belong to a ZodNumber schema')
+      }
       return toInterpolatableSchema(
         z.union(
           [
-            z
-              .string()
-              .regex(/^\d+(\.\d+)?$/)
-              .transform((value) => Number(value)),
+            zodInputPreservingTransform(z.string().regex(/^[0-9]+(\.[0-9]+)?$/u), (value) =>
+              Number(value),
+            ),
             interpolationSchemaFull,
-            schema,
+            zodWithJsonInputSchema(
+              zodInputPreservingTransform(schema, (value) => value),
+              schema.finite(),
+            ),
           ],
           def,
         ),
@@ -460,11 +660,21 @@ export function interpolateRecursive<Schema extends z.ZodFirstPartySchemaTypes>(
   }
 }
 
+/** Interpolate a schema while preserving stable API-description ownership metadata. */
+export function interpolateRecursive<Schema extends z.ZodFirstPartySchemaTypes>(
+  schema: Schema,
+): InterpolatableSchema<Schema> {
+  const interpolated = interpolateRecursiveWithoutDescriptionRegistration(schema)
+  return toInterpolatableSchema(inheritApiParameterDescription(schema, interpolated))
+}
+
 /**
  * The robot keys specified in this array can’t be interpolated.
  */
 const uninterpolatableKeys = ['interpolate', 'robot', 'use'] as const
 const uninterpolatableKeySet = new Set<string>(uninterpolatableKeys)
+const robotIdentifierDescription =
+  'Identifier of the [robot](https://transloadit.com/docs/robots/) to execute'
 
 type InterpolatableRobot<Schema extends z.ZodObject<z.ZodRawShape>> =
   Schema extends z.ZodObject<infer T, infer UnknownKeys, infer Catchall>
@@ -479,18 +689,31 @@ type InterpolatableRobot<Schema extends z.ZodObject<z.ZodRawShape>> =
       >
     : never
 
+const robotDocumentationSchemas = new WeakMap<z.ZodTypeAny, z.ZodObject<z.ZodRawShape>>()
+
+/** Recover the public schema before interpolation adds wire-only alternatives and generic copy. */
+export function getRobotDocumentationSchema(
+  schema: z.ZodObject<z.ZodRawShape>,
+): z.ZodObject<z.ZodRawShape> {
+  return robotDocumentationSchemas.get(schema) ?? schema
+}
+
 export function interpolateRobot<Schema extends z.ZodObject<z.ZodRawShape>>(
   schema: Schema,
 ): InterpolatableRobot<Schema> {
   const def = schema._def
-  return toInterpolatableRobot(
+  const interpolated = toInterpolatableRobot<Schema>(
     z
       .object(
         Object.fromEntries(
           Object.entries(def.shape()).map(([key, nested]) => [
             key,
             uninterpolatableKeySet.has(key)
-              ? nested
+              ? key === 'robot'
+                ? nested.description == null
+                  ? nested.describe(robotIdentifierDescription)
+                  : nested
+                : nested
               : interpolateRecursive(toFirstPartySchema(nested)),
           ]),
         ),
@@ -498,21 +721,26 @@ export function interpolateRobot<Schema extends z.ZodObject<z.ZodRawShape>>(
       )
       .strict(),
   )
+  robotDocumentationSchemas.set(interpolated, schema)
+  return interpolated
 }
 
-const robotInterpolateBooleanSchema = z
-  .union([z.boolean(), booleanStringSchema])
-  .transform((value) => value === true || value === 'true')
+const robotInterpolateBooleanSchema = zodInputPreservingTransform(
+  z.union([z.boolean(), booleanStringSchema]),
+  (value) => value === true || value === 'true',
+)
 
-export const robotInterpolateSchema = z
-  .union([robotInterpolateBooleanSchema, z.record(robotInterpolateBooleanSchema)])
-  .describe(`
+const robotInterpolateDescription = `
 Controls whether Assembly Variables are interpolated for individual instruction fields.
 
 By default, most Robot instruction fields interpolate Assembly Variables. Set this to \`false\` to treat every instruction field as literal text, or set an individual field path to \`false\` to treat only that field as literal text. For Robot-specific fields that are literal by default, set this to \`true\` or set that field path to \`true\` to opt back into interpolation.
 
 Use field names such as \`path\`, or dotted paths such as \`ffmpeg.vf\` for nested objects.
-`)
+`
+
+export const robotInterpolateSchema = z
+  .union([robotInterpolateBooleanSchema, z.record(robotInterpolateBooleanSchema)])
+  .describe(robotInterpolateDescription)
 
 /**
  * Fields that are shared by all Transloadit robots.
@@ -524,12 +752,7 @@ export const robotOutputMetaSchema = z.union([
 ])
 export type RobotOutputMeta = z.infer<typeof robotOutputMetaSchema>
 
-export type RobotBase = z.infer<typeof robotBase>
-export const robotBase = z
-  .object({
-    interpolate: robotInterpolateSchema.optional(),
-
-    output_meta: robotOutputMetaSchema.optional().describe(`
+const robotOutputMetaDescription = `
 Allows you to specify a set of metadata that is more expensive on CPU power to calculate, and thus is disabled by default to keep your Assemblies processing fast.
 
 For images, you can add \`"has_transparency": true\` in this object to extract if the image contains transparent parts and \`"dominant_colors": true\` to extract an array of hexadecimal color codes from the image.
@@ -538,31 +761,100 @@ For images, you can also add \`"blurhash": true\` to extract a [BlurHash](https:
 
 For images, \`"thumbhash": true\` instead extracts a base64-encoded [ThumbHash](https://evanw.github.io/thumbhash/) into \`meta.thumbhash\`, together with \`meta.has_alpha\` (whether an alpha channel exists, even when fully opaque). It describes EXIF-oriented pixels and uses the first frame of animated images. Extraction is best-effort: images above 40 megapixels, unsupported formats, or a failed/bounded decode produce no placeholder. Successful extraction adds a metadata charge equivalent to 20% of that file's bytes. No ThumbHash surcharge applies when disabled or when no hash is produced.
 
-For videos, you can add the \`"colorspace: true"\` parameter to extract the colorspace of the output video.
+Set this option on the Step producing the image, such as \`/upload/handle\` for uploaded originals or \`/image/resize\` for processed outputs. Setting it only on \`/transloadit/store\` does not request extraction: storage preserves the producer's metadata. Transloadit Storage persists a generated hash with its immutable version and returns it in stored results and native asset reads. Direct S3 uploads do not generate placeholders. A placeholder contains image information, so protect it with the same access controls as the full image.
+
+For videos, you can add the \`"colorspace": true\` parameter to extract the colorspace of the output video.
 
 For videos, you can also add \`"interlaced": true\` to detect whether the video is interlaced. This combines the cheap ffprobe \`field_order\` flag with a bounded \`idet\` sampling pass over the first frames of the source, exposing \`interlaced\`, \`field_order\`, and a diagnostic \`interlace_detection\` object under \`file.meta\`. This is computationally expensive and billed accordingly.
 
 For audio, you can add \`"mean_volume": true\` to get a single value representing the mean average volume of the audio file.
 
 You can also set this to \`false\` to skip metadata extraction and speed up transcoding.
-`),
+`
 
-    result: z
-      .boolean()
-      .default(false)
-      .describe('Whether the results of this Step should be present in the Assembly Status JSON'),
+const robotQueueDescription = `Setting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times`
 
-    queue: z
-      .enum(['batch'])
-      .optional()
-      .describe(
-        `Setting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times`,
-      ),
+const robotIgnoreErrorsPhaseDescriptions = `Ignore errors during specific phases of processing.
 
-    force_accept: z
-      .boolean()
-      .default(false)
-      .describe(`Force a Robot to accept a file type it would have ignored.
+Setting this to \`["meta"]\` will cause the Robot to ignore errors during metadata extraction.
+
+Setting this to \`["execute"]\` will cause the Robot to ignore errors during the main execution phase.`
+
+export const autoProviderDescription = 'Chooses the best provider based on your request.'
+
+const aiProviderDescription = `${autoProviderDescription}
+
+Select a specific provider to override automatic selection.`
+
+const legacyFfmpegVersions = formatEnglishList(
+  runtimeStackVersions.ffmpeg.valid.map((version) => JSON.stringify(version)),
+)
+const deprecatedFfmpegVersions = formatEnglishList([
+  ...new Set(
+    Object.keys(runtimeStackVersions.ffmpeg.deprecated).map((version) =>
+      JSON.stringify(`${version.split('.')[0]}.x`),
+    ),
+  ),
+])
+
+export const robotParameterDocs = {
+  adaptive_filtering: {
+    description: `
+Controls the image compression for PNG images. Setting to \`true\` results in smaller file size, while increasing processing time. It is encouraged to keep this option disabled.
+`,
+  },
+  ai_provider: {
+    description: aiProviderDescription,
+  },
+  audio_bitrate: {
+    description: `
+Bit rate of the resulting audio file, in bits per second. If not specified will default to the bit rate of the input audio file.
+`,
+  },
+
+  audio_preset: {
+    description: `
+Performs conversion using pre-configured settings.
+
+If you specify your own FFmpeg parameters using the <dfn>Robot</dfn>'s \`ffmpeg\` parameter and you have not specified a preset, then the default \`mp3\` preset is not applied. This is to prevent you from having to override each of the MP3 preset's values manually.
+
+For a list of audio presets, see [audio presets](/docs/presets/audio/).
+`,
+  },
+
+  audio_sample_rate: {
+    description: `
+Sample rate of the resulting audio file, in Hertz. If not specified will default to the sample rate of the input audio file.
+`,
+  },
+
+  auto_provider: {
+    description: autoProviderDescription,
+  },
+  error_msg: {
+    description: `
+The error message shown to your users (such as by Uppy) when a file is declined and \`error_on_decline\` is set to \`true\`.
+`,
+  },
+
+  error_on_decline: {
+    description: `
+If this is set to \`true\` and one or more files are declined, the Assembly will be stopped and marked with an error.
+`,
+  },
+
+  ffmpeg: {
+    description: `
+A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the [FFmpeg documentation](https://ffmpeg.org/ffmpeg-doc.html). Options specified here take precedence over the preset options.
+`,
+  },
+  ffmpeg_stack: {
+    description: `
+Selects the FFmpeg stack version to use for encoding. We currently recommend using "${stackVersions.ffmpeg.recommendedVersion}". The exact versions ${legacyFfmpegVersions} are legacy values that remain accepted for backward compatibility. Deprecated ${deprecatedFfmpegVersions} values are also accepted.
+`,
+  },
+  force_accept: {
+    description: `Force a Robot to accept a file type it would have ignored.
 
 By default, Robots ignore files they are not familiar with.
 [🤖/video/encode](/docs/robots/video-encode/), for
@@ -570,24 +862,282 @@ example, will happily ignore input images.
 
 With the \`force_accept\` parameter set to \`true\`, you can force Robots to accept all files thrown at them.
 This will typically lead to errors and should only be used for debugging or combatting edge cases.
-`),
+`,
+  },
+  force_name: {
+    description:
+      'Custom name for the imported file(s). By default file names are derived from the source.',
+  },
+  ignore_errors: {
+    description: `
+${robotIgnoreErrorsPhaseDescriptions}
 
-    ignore_errors: z
-      .union([z.boolean(), z.array(z.enum(['meta', 'execute']))])
-      .transform((value) => (value === true ? ['meta', 'execute'] : value === false ? [] : value))
-      .default([])
-      .describe(`
-Ignore errors during specific phases of processing.
+Setting this to \`true\` is equivalent to \`["meta", "execute"]\` and will ignore errors in both phases.
+`,
+  },
+  import_ignore_errors: {
+    description: `
+${robotIgnoreErrorsPhaseDescriptions}
 
-Setting this to \`["meta"]\` will cause the Robot to ignore errors during metadata extraction.
+Setting this to \`["import"]\` will cause the Robot to ignore errors while importing the source file. The \`"import"\` phase is only available to import Robots.
+
+Setting this to \`true\` is equivalent to \`["meta", "import", "execute"]\` and will ignore errors in all three phases.
+`,
+  },
+  import_on_errors: {
+    description: `
+Setting this to \`["meta"]\` will still import the file on metadata extraction errors. \`ignore_errors\` is similar, it also ignores the error and makes sure the Robot doesn't stop, but it doesn't import the file.
+`,
+  },
+  interpolate: {
+    description: robotInterpolateDescription,
+  },
+  ocr_format: {
+    description: `
+In what format to return the extracted text.
+- \`"json"\` returns a JSON file.
+- \`"meta"\` does not return a file, but stores the data inside Transloadit's file object (under \`\${file.meta.recognized_text}\`, which is an array of strings) that's passed around between encoding <dfn>Steps</dfn>, so that you can use the values to burn the data into videos, filter on them, etc.
+- \`"text"\` returns the recognized text as a plain UTF-8 encoded text file.
+`,
+  },
+  ocr_granularity: {
+    description: `
+Whether to return a full response including coordinates for the text (\`"full"\`), or a flat list of the extracted phrases (\`"list"\`). This parameter has no effect if the \`format\` parameter is set to \`"text"\`.
+`,
+  },
+  ocr_provider: {
+    description: `${aiProviderDescription}
+AWS supports detection for the following languages: English, Arabic, Russian, German, French, Italian, Portuguese and Spanish. GCP allows for a wider range of languages, with varying levels of support which can be found on the [official documentation](https://cloud.google.com/vision/docs/languages/).
+`,
+  },
+  output_meta: {
+    description: robotOutputMetaDescription,
+  },
+  queue: {
+    description: robotQueueDescription,
+  },
+  result: {
+    description: 'Whether the results of this Step should be present in the Assembly Status JSON',
+  },
+  return_file_stubs: {
+    description: `
+If set to \`true\`, the Robot will not yet import the actual files but instead return an empty file stub that includes a URL from where the file can be imported by subsequent Robots. This is useful for cases where subsequent Steps need more control over the import process, such as with 🤖/video/ondemand. This parameter should only be set if all subsequent Steps use Robots that support file stubs.
+`,
+  },
+  robot: {
+    description: `
+Specifies which Robot should process files passed to this Step.
+
+See [all Robots](https://transloadit.com/docs/robots/), each with their own parameters, such as
+\`width\` to control how an image is resized. The full list of parameters per Robot can be taken
+from the Robot docs.
+`,
+  },
+  seed: {
+    description: 'Seed for the random number generator.',
+  },
 
-Setting this to \`["execute"]\` will cause the Robot to ignore errors during the main execution phase.
+  sort_by: {
+    description: `
+Controls how bundled inputs are ordered when no explicit numbered alias for the input type is used. Numbered aliases end with a numeric suffix such as \`_1\`.
 
-Setting this to \`true\` is equivalent to \`["meta", "execute"]\` and will ignore errors in both phases.
-`),
+The default \`"basename"\` keeps the legacy natural basename sorting behavior.
+
+Set this to \`"import_order"\` to preserve the order of array-based import steps when all input files carry complete import order metadata. \`"auto"\` has the same import-order preference with natural basename sorting as fallback.
+`,
+  },
+  use: {
+    description: `
+Specifies which Step(s) to use as input.
+
+- You can pick any names for Steps except \`":original"\` (reserved for user uploads handled by Transloadit)
+- You can provide several Steps as input with arrays:
+  \`\`\`json
+  {
+    "use": [
+      ":original",
+      "encoded",
+      "resized"
+    ]
+  }
+  \`\`\`
+- You can also tag input Steps with \`as\` to pass semantic intent to robots:
+  \`\`\`json
+  {
+    "use": [
+      {
+        "name": ":original",
+        "as": "image"
+      },
+      {
+        "name": ":original",
+        "as": "mask"
+      }
+    ]
+  }
+  \`\`\`
+
+> [!Tip]
+> That's likely all you need to know about \`use\`, but you can view [Advanced use cases](/docs/topics/use-parameter/).
+`,
+  },
+  user_meta: {
+    description: `
+Adds custom JSON metadata to each emitted file without changing its contents. Nested objects and arrays are supported.
+
+Inheritance depends on the Robot. Values merge with existing \`user_meta\` on the output file; the current Step replaces matching top-level keys. Assign required keys explicitly when a Robot creates fresh outputs.
+
+In processing Steps, \`\${file.*}\` refers to the first input and \`\${result.*}\` to the emitted file. Values are evaluated per output after the Robot runs, before subsequent metadata extraction and temporary storage. On \`:original\`, values are evaluated per upload before metadata extraction.
+
+Downstream Steps read \`\${file.user_meta.key}\`. See [Custom metadata](https://transloadit.com/docs/topics/assembly-variables/#user-meta) for a complete example and inheritance rules.
+`,
+  },
+  video_background: {
+    description: `
+The background color of the resulting video in the \`"rrggbbaa"\` format (red, green, blue, alpha) when used with the \`"pad"\` resize strategy. The default color is black.
+`,
+  },
+  video_height: {
+    description: `
+Height of the new video, in pixels.
+
+If the value is not specified and the \`preset\` parameter is available, the \`preset\`'s [supplied height](/docs/presets/video/) will be implemented.
+`,
+  },
+  video_preset: {
+    description: `
+Converts a video according to [pre-configured settings](/docs/presets/video/).
+
+You can use the value \`'empty'\` here if you specify your own FFmpeg parameters using the <dfn>Robot</dfn> or do not want Transloadit to set any encoding settings.
+`,
+  },
+  video_width: {
+    description: `
+Width of the new video, in pixels.
+
+If the value is not specified and the \`preset\` parameter is available, the \`preset\`'s [supplied width](/docs/presets/video/) will be implemented.
+`,
+  },
+} as const
+
+export type RobotParameterDocId = keyof typeof robotParameterDocs
+
+export const inputSortBySchema = z
+  .enum(['auto', 'basename', 'import_order'])
+  .default('basename')
+  .describe(robotParameterDocs.sort_by.description)
+
+export const robotPathSchema = z
+  .string()
+  .regex(/^\/[a-z0-9_-]+\/[a-z0-9_-]+$/u)
+  .describe(robotParameterDocs.robot.description)
+
+export type RobotBase = z.infer<typeof robotBase>
+export const robotBase = z
+  .object({
+    interpolate: robotInterpolateSchema.optional(),
+
+    output_meta: robotOutputMetaSchema
+      .optional()
+      .describe(robotParameterDocs.output_meta.description),
+
+    user_meta: z.record(z.unknown()).default({}).describe(robotParameterDocs.user_meta.description),
+
+    result: z.boolean().default(false).describe(robotParameterDocs.result.description),
+
+    queue: z.enum(['batch']).optional().describe(robotParameterDocs.queue.description),
+
+    force_accept: z.boolean().default(false).describe(robotParameterDocs.force_accept.description),
+
+    ignore_errors: zodInputPreservingTransform(
+      z.union([z.boolean(), z.array(z.enum(['meta', 'execute']))]),
+      (value) => (value === true ? ['meta', 'execute'] : value === false ? [] : value),
+    )
+      .default([])
+      .describe(robotParameterDocs.ignore_errors.description),
   })
   .strict()
 
+/**
+ * Standard variants for strict Robot instructions without catchalls. Keep this outside the adapter
+ * replaced by the SDK's Zod 4 sync. Inference uses the active Zod version's object types.
+ */
+export function createRobotSchemaVariants<Shape extends z.ZodRawShape & { result: z.ZodType }>(
+  schema: z.ZodObject<Shape>,
+) {
+  const strictSchema = schema.strict()
+  const result: Shape['result'] = schema.shape.result
+  const withHiddenFields = strictSchema
+    .merge(z.object({ result: z.union([z.literal('debug'), result]).optional() }))
+    .strict()
+  return {
+    schema,
+    withHiddenFields,
+    interpolatable: interpolateRobot(strictSchema),
+    interpolatableWithHiddenFields: interpolateRobot(withHiddenFields),
+  }
+}
+
+/** Standard strict variants with extra internal fields. */
+export function extendRobotSchemaVariants<
+  Shape extends z.ZodRawShape & { result: z.ZodType },
+  HiddenShape extends z.ZodRawShape,
+>(schema: z.ZodObject<Shape>, hiddenFields: HiddenShape) {
+  const strictSchema = schema.strict()
+  const result: Shape['result'] = schema.shape.result
+  const withHiddenFields = strictSchema.extend({
+    result: z.union([z.literal('debug'), result]).optional(),
+    ...hiddenFields,
+  })
+  return {
+    schema,
+    withHiddenFields,
+    interpolatable: interpolateRobot(strictSchema),
+    interpolatableWithHiddenFields: interpolateRobot(withHiddenFields),
+  }
+}
+
+/**
+ * Named definition types keep the SDK's emitted declarations small. Robot modules explicitly
+ * reference their existing schema types instead of emitting another copy of each schema shape.
+ */
+export type RobotDefinition<Shape extends z.ZodRawShape & { result: z.ZodType }> = ReturnType<
+  typeof createRobotSchemaVariants<Shape>
+> & { meta: RobotMetaInput }
+
+/** A Robot definition whose internal schema has additional fields. */
+export type RobotDefinitionWithHiddenFields<
+  Shape extends z.ZodRawShape & { result: z.ZodType },
+  HiddenShape extends z.ZodRawShape,
+> = ReturnType<typeof extendRobotSchemaVariants<Shape, HiddenShape>> & { meta: RobotMetaInput }
+
+/** Existing schema variants for Robots that require custom construction. */
+export interface RobotSchemaPair<PublicSchema, InternalSchema> {
+  meta: RobotMetaInput
+  interpolatable: PublicSchema
+  interpolatableWithHiddenFields: InternalSchema
+}
+
+/** Define a strict Robot's schema variants together with its metadata. */
+export function defineRobot<Shape extends z.ZodRawShape & { result: z.ZodType }>(
+  meta: RobotMetaInput,
+  schema: z.ZodObject<Shape>,
+): RobotDefinition<Shape> {
+  return { meta, ...createRobotSchemaVariants(schema) }
+}
+
+/** Define a strict Robot with extra internal fields and its metadata. */
+export function defineRobotWithHiddenFields<
+  Shape extends z.ZodRawShape & { result: z.ZodType },
+  HiddenShape extends z.ZodRawShape,
+>(
+  meta: RobotMetaInput,
+  schema: z.ZodObject<Shape>,
+  hiddenFields: HiddenShape,
+): RobotDefinitionWithHiddenFields<Shape, HiddenShape> {
+  return { meta, ...extendRobotSchemaVariants(schema, hiddenFields) }
+}
+
 export const useParamObjectSchema = z
   .object({
     name: z.string(),
@@ -653,42 +1203,7 @@ export const robotUse = z
   .object({
     use: z
       .union([useParamStepsSchema, useParamObjectOfStepsSchema])
-      .describe(
-        `
-Specifies which Step(s) to use as input.
-
-- You can pick any names for Steps except \`":original"\` (reserved for user uploads handled by Transloadit)
-- You can provide several Steps as input with arrays:
-  \`\`\`json
-  {
-    "use": [
-      ":original",
-      "encoded",
-      "resized"
-    ]
-  }
-  \`\`\`
-- You can also tag an input Step with \`as\` to pass semantic intent to robots:
-- You can also tag input Steps with \`as\` to pass semantic intent to robots:
-  \`\`\`json
-  {
-    "use": [
-      {
-        "name": ":original",
-        "as": "image"
-      },
-      {
-        "name": ":original",
-        "as": "mask"
-      }
-    ]
-  }
-  \`\`\`
-
-> [!Tip]
-> That's likely all you need to know about \`use\`, but you can view [Advanced use cases](/docs/topics/use-parameter/).
-`,
-      )
+      .describe(robotParameterDocs.use.description)
       .optional(),
   })
   .strict()
@@ -698,61 +1213,26 @@ export const robotUseWithHiddenFields = z
   .object({
     use: z
       .union([useParamStepsWithHiddenFieldsSchema, useParamObjectOfStepsWithHiddenFieldsSchema])
-      .describe(
-        `
-Specifies which Step(s) to use as input.
-
-- You can pick any names for Steps except \`":original"\` (reserved for user uploads handled by Transloadit)
-- You can provide several Steps as input with arrays:
-  \`\`\`json
-  {
-    "use": [
-      ":original",
-      "encoded",
-      "resized"
-    ]
-  }
-  \`\`\`
-- You can also tag an input Step with \`as\` to pass semantic intent to robots:
-- You can also tag input Steps with \`as\` to pass semantic intent to robots:
-  \`\`\`json
-  {
-    "use": [
-      {
-        "name": ":original",
-        "as": "image"
-      },
-      {
-        "name": ":original",
-        "as": "mask"
-      }
-    ]
-  }
-  \`\`\`
-
-> [!Tip]
-> That's likely all you need to know about \`use\`, but you can view [Advanced use cases](/docs/topics/use-parameter/).
-`,
-      )
+      .describe(robotParameterDocs.use.description)
       .optional(),
   })
   .strict()
 
-export const complexWidthSchema = z.preprocess((val) => {
-  if (typeof val === 'string' && val.startsWith('${')) {
-    return val
-  }
-  if (typeof val === 'string') {
-    const num = Number.parseInt(val, 10)
-    if (Number.isNaN(num) || val.includes('x')) {
-      return val
-    }
-    return num
-  }
-  return val
-}, z.number().int().min(1).max(25_000))
+const complexDimensionNumberSchema = z.number().int().min(1).max(25_000)
+const complexDimensionStringSchema = z
+  .string()
+  .regex(
+    new RegExp(
+      `^${ecmaWhitespaceCharacterClass}*\\+?0*(?:[1-9][0-9]{0,3}|1[0-9]{4}|2[0-4][0-9]{3}|25000)(?:[^0-9x][^x]*)?$`,
+      'u',
+    ),
+  )
+const complexDimensionInputSchema = z.union([
+  complexDimensionNumberSchema,
+  complexDimensionStringSchema,
+])
 
-export const complexHeightSchema = z.preprocess((val) => {
+function normalizeComplexDimension(val: unknown): unknown {
   if (typeof val === 'string' && val.startsWith('${')) {
     return val
   }
@@ -764,7 +1244,17 @@ export const complexHeightSchema = z.preprocess((val) => {
     return num
   }
   return val
-}, z.number().int().min(1).max(25_000))
+}
+
+export const complexWidthSchema = zodWithJsonInputSchema(
+  z.preprocess(normalizeComplexDimension, complexDimensionNumberSchema),
+  complexDimensionInputSchema,
+)
+
+export const complexHeightSchema = zodWithJsonInputSchema(
+  z.preprocess(normalizeComplexDimension, complexDimensionNumberSchema),
+  complexDimensionInputSchema,
+)
 
 /**
  * A robot that uses FFmpeg.
@@ -879,17 +1369,16 @@ export const robotFFmpeg = z.object({
     })
     .passthrough()
     .optional()
-    .describe(`
-A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the [FFmpeg documentation](https://ffmpeg.org/ffmpeg-doc.html). Options specified here take precedence over the preset options.
-`),
+    .describe(robotParameterDocs.ffmpeg.description),
 
   ffmpeg_stack: z
     // Any semver in range is allowed and normalized. The enum is used for editor completions.
-    .union([z.enum(['v6', 'v7', 'v8']), z.string().regex(/^v?[5-8](\.\d+)?(\.\d+)?$/)])
-    .default('v6.0.0')
-    .describe(`
-Selects the FFmpeg stack version to use for encoding. These versions reflect real FFmpeg versions. We currently recommend to use "v6.0.0". Deprecated "v5.x" values are accepted for backward compatibility.
-`),
+    .union([
+      z.enum(stackVersions.ffmpeg.suggestedValues),
+      z.string().regex(stackVersions.ffmpeg.test),
+    ])
+    .default(runtimeStackVersions.ffmpeg.default)
+    .describe(robotParameterDocs.ffmpeg_stack.description),
 })
 
 /**
@@ -900,8 +1389,8 @@ Selects the FFmpeg stack version to use for encoding. These versions reflect rea
  * @returns
  *   The hyphenated preset.
  */
-function transformPreset<T extends string>(preset: T): Replace<T, '_', '-', { all: true }> {
-  return preset.replaceAll('_', '-') as Replace<T, '_', '-', { all: true }>
+function transformPreset<T extends string>(preset: T): StringReplaceAll<T, '_', '-'> {
+  return preset.replaceAll('_', '-') as StringReplaceAll<T, '_', '-'>
 }
 
 /**
@@ -989,17 +1478,9 @@ const audioPresets = createPresets([
 export type FFmpegAudio = z.infer<typeof robotFFmpegAudio>
 export const robotFFmpegAudio = robotFFmpeg
   .extend({
-    preset: z
-      .enum(audioPresets)
-      .transform(transformPreset)
+    preset: zodInputPreservingTransform(z.enum(audioPresets), transformPreset)
       .optional()
-      .describe(`
-Performs conversion using pre-configured settings.
-
-If you specify your own FFmpeg parameters using the <dfn>Robot</dfn>'s \`ffmpeg\` parameter and you have not specified a preset, then the default \`mp3\` preset is not applied. This is to prevent you from having to override each of the MP3 preset's values manually.
-
-For a list of audio presets, see [audio presets](/docs/presets/audio/).
-`),
+      .describe(robotParameterDocs.audio_preset.description),
   })
   .strict()
 
@@ -1009,28 +1490,10 @@ For a list of audio presets, see [audio presets](/docs/presets/audio/).
 export type FFmpegVideo = z.infer<typeof robotFFmpegVideo>
 export const robotFFmpegVideo = robotFFmpeg
   .extend({
-    width: z
-      .number()
-      .int()
-      .min(1)
-      .nullish()
-      .describe(`
-Width of the new video, in pixels.
-
-If the value is not specified and the \`preset\` parameter is available, the \`preset\`'s [supplied width](/docs/presets/video/) will be implemented.
-`),
-    height: z
-      .number()
-      .int()
-      .min(1)
-      .nullish()
-      .describe(`
-Height of the new video, in pixels.
-
-If the value is not specified and the \`preset\` parameter is available, the \`preset\`'s [supplied height](/docs/presets/video/) will be implemented.
-`),
-    preset: z
-      .enum([
+    width: z.number().int().min(1).nullish().describe(robotParameterDocs.video_width.description),
+    height: z.number().int().min(1).nullish().describe(robotParameterDocs.video_height.description),
+    preset: zodInputPreservingTransform(
+      z.enum([
         ...createPresets([
           'android',
           'android-high',
@@ -1125,14 +1588,11 @@ If the value is not specified and the \`preset\` parameter is available, the \`p
           'wmv',
         ]),
         ...audioPresets,
-      ])
-      .transform(transformPreset)
+      ]),
+      transformPreset,
+    )
       .optional()
-      .describe(`
-Converts a video according to [pre-configured settings](/docs/presets/video/).
-
-If you specify your own FFmpeg parameters using the <dfn>Robot</dfn>'s and/or do not not want Transloadit to set any encoding setting, starting \`ffmpeg_stack: "${stackVersions.ffmpeg.recommendedVersion}"\`,  you can use the value \`'empty'\` here.
-`),
+      .describe(robotParameterDocs.video_preset.description),
   })
   .strict()
 
@@ -1173,13 +1633,74 @@ export const page_number = z.number().int().default(1)
 
 export const recursive = z.boolean().default(false)
 
+export const bucketImportPath = path.describe(`
+The path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example: \`images/avatar.jpg\`.
+
+If it points to a directory, indicated by a trailing slash (\`/\`), then all files that are direct descendants of this directory will be imported. For example: \`images/\`.
+
+Directories are **not** imported recursively. If you want to import files from subdirectories and sub-subdirectories, enable the \`recursive\` parameter.
+
+If you want to import all files from the root directory, please use \`/\` as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with \`/\`, you'll receive an error: \`A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist.\`
+
+You can also use an array of path strings here to import multiple paths in the same <dfn>Robot</dfn>'s <dfn>Step</dfn>.
+`)
+
+export const storeFilePath = z
+  .string()
+  .default('${unique_prefix}/${file.url_name}')
+  .describe(`
+The path at which the file is to be stored. This may include any available [Assembly variables](/docs/topics/assembly-instructions/#assembly-variables). The path must not be a directory.
+`)
+
+export const recursiveImportPageNumber = page_number.describe(`
+The pagination page number. For now, in order to not break backwards compatibility in non-recursive imports, this only works when recursive is set to \`true\`.
+
+When doing big imports, make sure no files are added or removed from other scripts within your path, otherwise you might get weird results with the pagination.
+`)
+
+export const signedSslUrlLifetime = z
+  .number()
+  .int()
+  .min(0)
+  .optional()
+  .describe(`
+This parameter provides signed URLs in the result JSON (in the \`signed_ssl_url\` property). The number that you set this parameter to is the URL expiry time in seconds. If this parameter is not used, no URL signing is done.
+`)
+
+export const recursiveImportPageSize = files_per_page.describe(`
+The pagination page size. This only works when recursive is \`true\` for now, in order to not break backwards compatibility in non-recursive imports.
+`)
+
+const bucketRegion = z
+  .string()
+  .optional()
+  .describe(`
+The region where the bucket is located.
+`)
+
+export const storePath = z
+  .string()
+  .default('${unique_prefix}/${file.url_name}')
+  .describe(`
+The path at which the file is to be stored. This may include any available [Assembly variables](/docs/topics/assembly-instructions/#assembly-variables).
+`)
+
+export const storageAcl = z
+  .enum(['private', 'public-read'])
+  .default('public-read')
+  .describe(`
+The permissions used for this file.
+`)
+
+export const recursiveImport = recursive.describe(`
+Setting this to \`true\` will enable importing files from subdirectories and sub-subdirectories (etc.) of the given path.
+
+Please use the pagination parameters \`page_number\` and \`files_per_page\` wisely here.
+`)
+
 export const return_file_stubs = z
   .boolean()
-  .describe(
-    `
-If set to \`true\`, the Robot will not yet import the actual files but instead return an empty file stub that includes a URL from where the file can be imported by subsequent Robots. This is useful for cases where subsequent Steps need more control over the import process, such as with 🤖/video/ondemand. This parameter should only be set if all subsequent Steps use Robots that support file stubs.
-`,
-  )
+  .describe(robotParameterDocs.return_file_stubs.description)
   .default(false)
 
 export const port = z.number().int().min(1).max(65535)
@@ -1203,16 +1724,34 @@ export const positionSchema = z.enum([
   'top-right',
 ])
 
-export const percentageSchema = z.string().regex(/^\d+%$/)
+export const percentageSchema = z.string().regex(/^[0-9]+%$/u)
+
+const portableHttpUrlPattern = /^[Hh][Tt][Tt][Pp][Ss]?:\/\/(?:[^ ]|[ ])/u
 
-export const httpUrlSchema = z
+const portableHttpUrlInputSchema = z
   .string()
-  .url()
-  .regex(/^https?:\/\//i)
+  .regex(portableHttpUrlPattern, 'Must be an HTTP or HTTPS URL')
+
+export const httpUrlSchema = zodWithConservativeJsonInputSchema(
+  z
+    .string()
+    .url()
+    .refine((value) => /^https?:\/\//iu.test(value), 'Must be an HTTP or HTTPS URL'),
+  portableHttpUrlInputSchema,
+)
 
-export const color_with_alpha = z.string().regex(/^#?[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/)
+/** Header restrictions shared by HTTP import and request documentation. */
+export const httpHeaderSafetyDescription = `Header names must be valid HTTP tokens. Header values may contain horizontal tabs, but other control characters, including carriage returns and line feeds, are rejected.
 
-export const color_without_alpha = z.string().regex(/^#?[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/)
+In an array of header strings, \`"Header-Name;"\` sends an empty header value. Each entry must be a literal header; reading headers from a file with \`@filename\` is not supported.`
+
+export const color_with_alpha = z.string().regex(/^#?[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/u)
+
+export const color_without_alpha = z.string().regex(/^#?[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/u)
+
+export const videoBackgroundSchema = color_with_alpha
+  .default('#00000000')
+  .describe(robotParameterDocs.video_background.description)
 
 // Extended color schemas that also support named colors (for robots that support them)
 export const color_with_alpha_with_named = z.union([
@@ -1257,17 +1796,18 @@ export const bitrateSchema = z.number().int().min(1)
 
 export const sampleRateSchema = z.number().int().min(1)
 
-export const optimize_priority = z
-  .enum(['compression-ratio', 'conversion-speed'])
-  .default('conversion-speed')
+export const optimize_priority = z.enum(['compression-ratio', 'conversion-speed'])
 
 export type ImagemagickRobot = z.infer<typeof robotImagemagick>
 export const robotImagemagick = z
   .object({
     imagemagick_stack: z
       // Any semver in range is allowed and normalized. The enum is used for editor completions.
-      .union([z.enum(['v3']), z.string().regex(/^v?[23](\.\d+)?(\.\d+)?$/)])
-      .default('v3'),
+      .union([
+        z.enum([stackVersions.imagemagick.recommendedVersion]),
+        z.string().regex(stackVersions.imagemagick.test),
+      ])
+      .default(runtimeStackVersions.imagemagick.default),
   })
   .strict()
 
@@ -1309,19 +1849,18 @@ export const colorspaceSchema = z.enum([
   'YUV',
 ])
 
+export const imageAdaptiveFilteringSchema = z
+  .boolean()
+  .default(false)
+  .describe(robotParameterDocs.adaptive_filtering.description)
+
+export const imageQualityValueSchema = z.number().int().min(1).max(100)
+
 // TODO: add before and after images to the description.
-export const imageQualitySchema = z
-  .number()
-  .int()
-  .min(1)
-  .max(100)
-  .default(92)
-  .describe(`
+export const imageQualitySchema = imageQualityValueSchema.default(92).describe(`
 Controls the image compression for JPG and PNG images. Please also take a look at [🤖/image/optimize](/docs/robots/image-optimize/).
 `)
 
-export const autoProviderDescription = 'Chooses the best provider based on your request'
-
 export const awsGcpAiProviderSchema = z.enum(['auto', 'aws', 'gcp']).default('auto')
 
 export const aiProviderSchema = z
@@ -1340,21 +1879,17 @@ export const robotImport = z
       .union([z.string(), z.array(z.string())])
       .nullable()
       .default(null)
-      .describe(
-        'Custom name for the imported file(s). By default file names are derived from the source.',
-      ),
-    ignore_errors: z
-      .union([z.boolean(), z.array(z.enum(['meta', 'import', 'execute']))])
-      .transform((value) =>
-        value === true ? ['meta', 'import', 'execute'] : value === false ? [] : value,
-      )
-      .default([]),
+      .describe(robotParameterDocs.force_name.description),
+    ignore_errors: zodInputPreservingTransform(
+      z.union([z.boolean(), z.array(z.enum(['meta', 'import', 'execute']))]),
+      (value) => (value === true ? ['meta', 'import', 'execute'] : value === false ? [] : value),
+    )
+      .default([])
+      .describe(robotParameterDocs.import_ignore_errors.description),
     import_on_errors: z
       .array(z.enum(['meta']))
       .default([])
-      .describe(`
-Setting this to \`["meta"]\` will still import the file on metadata extraction errors. \`ignore_errors\` is similar, it also ignores the error and makes sure the Robot doesn't stop, but it doesn't import the file.
-`),
+      .describe(robotParameterDocs.import_on_errors.description),
   })
   .strict()
 
@@ -1442,7 +1977,7 @@ export const cloudflareBase = z
       .string()
       .optional()
       .describe(`
-Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your cloudflare bucket, Key, Secret and Bucket region.
+Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your Cloudflare R2 bucket, Key, Secret and Bucket region.
 
 While we recommend to use <dfn>Template Credentials</dfn> at all times, some use cases demand dynamic credentials for which using <dfn>Template Credentials</dfn> is too unwieldy because of their static nature. If you have this requirement, feel free to use the following parameters instead: \`"bucket"\`, \`"host"\`, \`"key"\`, \`"secret"\`.
 `),
@@ -1560,17 +2095,12 @@ export const megaBase = z
       .string()
       .optional()
       .describe(`
-Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your MEGA object storage bucket, Key, Secret and Bucket region.
+Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your MEGA S4 Object Storage bucket, Key, Secret and Bucket region.
 
 While we recommend to use <dfn>Template Credentials</dfn> at all times, some use cases demand dynamic credentials for which using <dfn>Template Credentials</dfn> is too unwieldy because of their static nature. If you have this requirement, feel free to use the following parameters instead: \`"bucket"\`, \`"bucket_region"\`, \`"key"\`, \`"secret"\`.
 `),
     bucket: z.string().optional(),
-    bucket_region: z
-      .string()
-      .optional()
-      .describe(`
-The region where the bucket is located.
-`),
+    bucket_region: bucketRegion,
     host: z.string().optional(),
     key: z.string().optional(),
     secret: z.string().optional(),
@@ -1584,7 +2114,7 @@ export const s3Base = z
       .string()
       .optional()
       .describe(`
-Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your S3 bucket, Key, Secret and Bucket region.
+Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your S3 \`bucket\`, \`key\`, \`secret\` and \`bucket_region\`.
 
 While we recommend to use <dfn>Template Credentials</dfn> at all times, some use cases demand dynamic credentials for which using <dfn>Template Credentials</dfn> is too unwieldy because of their static nature. If you have this requirement, feel free to use the following parameters instead: \`"bucket"\`, \`"bucket_region"\` (for example: \`"us-east-1"\` or \`"eu-west-2"\`), \`"key"\`, \`"secret"\`.
 `),
@@ -1627,12 +2157,7 @@ While we recommend to use <dfn>Template Credentials</dfn> at all times, some use
 If you do use these parameters, make sure to use the **Endpoint** value under \`Storage > S3 Connection\` in the Supabase console for the \`"host"\` value, and the values under **S3 Access Keys** on the same page for your \`"key"\` and \`"secret"\`.
 `),
     bucket: z.string().optional(),
-    bucket_region: z
-      .string()
-      .optional()
-      .describe(`
-The region where the bucket is located.
-`),
+    bucket_region: bucketRegion,
     host: z.string().optional(),
     key: z.string().optional(),
     secret: z.string().optional(),
@@ -1646,18 +2171,17 @@ export const swiftBase = z
       .string()
       .optional()
       .describe(`
-  Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your Swift bucket, Key, Secret and Bucket region.
+  Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your OpenStack Swift container (provided through the \`"bucket"\` parameter), host, Key and Secret.
 
   While we recommend to use <dfn>Template Credentials</dfn> at all times, some use cases demand dynamic credentials for which using <dfn>Template Credentials</dfn> is too unwieldy because of their static nature. If you have this requirement, feel free to use the following parameters instead: \`"bucket"\`, \`"host"\`, \`"key"\`, \`"secret"\`.
   `),
     bucket: z.string().optional(),
-    bucket_region: z
+    host: z
       .string()
       .optional()
       .describe(`
-The region where the bucket is located.
+The S3-compatible object storage endpoint for the OpenStack Swift service. This is required when supplying dynamic credentials directly instead of using Template Credentials.
 `),
-    host: z.string().optional(),
     key: z.string().optional(),
     secret: z.string().optional(),
   })
@@ -1670,17 +2194,12 @@ export const tigrisBase = z
       .string()
       .optional()
       .describe(`
-Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your MinIO bucket, Key, Secret and Bucket region.
+Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your Tigris bucket, Key, Secret and Bucket region.
 
 While we recommend to use <dfn>Template Credentials</dfn> at all times, some use cases demand dynamic credentials for which using <dfn>Template Credentials</dfn> is too unwieldy because of their static nature. If you have this requirement, feel free to use the following parameters instead: \`"bucket"\`, \`"host"\`, \`"key"\`, \`"secret"\`.
 `),
     bucket: z.string().optional(),
-    bucket_region: z
-      .string()
-      .optional()
-      .describe(`
-The region where the bucket is located.
-`),
+    bucket_region: bucketRegion,
     host: z.string().optional(),
     key: z.string().optional(),
     secret: z.string().optional(),
@@ -1699,12 +2218,7 @@ Please create your associated <dfn>Template Credentials</dfn> in your Transloadi
 While we recommend to use <dfn>Template Credentials</dfn> at all times, some use cases demand dynamic credentials for which using <dfn>Template Credentials</dfn> is too unwieldy because of their static nature. If you have this requirement, feel free to use the following parameters instead: \`"bucket"\`, \`"host"\`, \`"key"\`, \`"secret"\`.
 `),
     bucket: z.string().optional(),
-    bucket_region: z
-      .string()
-      .optional()
-      .describe(`
-The region where the bucket is located.
-`),
+    bucket_region: bucketRegion,
     host: z.string().optional(),
     key: z.string().optional(),
     secret: z.string().optional(),
@@ -1808,9 +2322,7 @@ You can also use a JSON string of such an object with coordinates in similar fas
 "{\\"x1\\": <Integer>, \\"y1\\": <Integer>, \\"x2\\": <Integer>, \\"y2\\": <Integer>}"
 \`\`\`
 `),
-    background: color_with_alpha.default('#00000000').describe(`
-The background color of the resulting video the \`"rrggbbaa"\` format (red, green, blue, alpha) when used with the \`"pad"\` resize strategy. The default color is black.
-`),
+    background: videoBackgroundSchema,
     rotate: z
       // We can’t use enum.
       // See https://github.com/colinhacks/zod/issues/2686
@@ -1964,3 +2476,22 @@ export interface NormalizedUse {
   group_by_original: boolean
   steps: NormalizedUseStep[]
 }
+
+/** Public input and output types for a Robot's schema variants. */
+export type RobotSchemaVariantTypes<
+  Variants extends {
+    schema: z.ZodType
+    withHiddenFields: z.ZodType
+    interpolatable: z.ZodType
+    interpolatableWithHiddenFields: z.ZodType
+  },
+> = {
+  output: z.output<Variants['schema']>
+  input: z.input<Variants['schema']>
+  hiddenOutput: z.output<Variants['withHiddenFields']>
+  hiddenInput: z.input<Variants['withHiddenFields']>
+  interpolatableOutput: z.output<Variants['interpolatable']>
+  interpolatableInput: z.input<Variants['interpolatable']>
+  interpolatableHiddenOutput: z.output<Variants['interpolatableWithHiddenFields']>
+  interpolatableHiddenInput: z.input<Variants['interpolatableWithHiddenFields']>
+}