@transloadit/node 4.10.8 → 4.11.1

package/src/Transloadit.ts

@@ -1,5 +1,9 @@
 import type { Readable } from 'node:stream'
 
+import type {
+  CompileAssemblyInstructionsOptions,
+  CompileAssemblyInstructionsResult,
+} from '@transloadit/utils'
 import type { Delays, Headers, OptionsOfJSONResponseBody, RetryOptions } from 'got'
 
 import type { TransloaditErrorResponseBody } from './ApiError.ts'
@@ -43,6 +47,7 @@ import { access, stat } from 'node:fs/promises'
 import { basename } from 'node:path'
 import { setTimeout as delay } from 'node:timers/promises'
 
+import { compileAssemblyInstructionsFromPrompt } from '@transloadit/utils'
 import { getSignedSmartCdnUrl, signParamsSync } from '@transloadit/utils/node'
 import debug from 'debug'
 import FormData from 'form-data'
@@ -62,6 +67,14 @@ import PaginationStream from './PaginationStream.ts'
 import PollingTimeoutError from './PollingTimeoutError.ts'
 import { sendTusRequest } from './tus.ts'
 
+export type {
+  CompileAssemblyInstructionsAttempt,
+  CompileAssemblyInstructionsClient,
+  CompileAssemblyInstructionsLintIssue,
+  CompileAssemblyInstructionsMessage,
+  CompileAssemblyInstructionsResult,
+} from '@transloadit/utils'
+
 export type { AssemblyStatus } from './alphalib/types/assemblyStatus.ts'
 export type {
   Base64Strategy,
@@ -81,6 +94,11 @@ export type {
   RobotParamHelp,
 } from './robots.ts'
 
+export {
+  buildCompileAssemblyInstructionsSystemPrompt,
+  CompileAssemblyInstructionsError,
+  parseCompileAssemblyInstructionsResponse,
+} from '@transloadit/utils'
 // See https://github.com/sindresorhus/got/tree/v11.8.6?tab=readme-ov-file#errors
 // Expose relevant errors
 export {
@@ -274,6 +292,13 @@ export interface SmartCDNUrlOptions {
   expiresAt?: number
 }
 
+export type CompileAssemblyInstructionsFromPromptOptions = Omit<
+  CompileAssemblyInstructionsOptions,
+  'client'
+> & {
+  timeout?: number
+}
+
 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)
@@ -313,6 +338,37 @@ function checkResult<T>(result: T | { error: string }): asserts result is T {
   }
 }
 
+function getResultBilledChargeUsd(result: unknown): number | undefined {
+  if (typeof result !== 'object' || result === null || Array.isArray(result)) {
+    return undefined
+  }
+
+  if (!('meta' in result)) {
+    return undefined
+  }
+
+  const { meta } = result
+  if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) {
+    return undefined
+  }
+
+  if (!('billed_charge_usd' in meta)) {
+    return undefined
+  }
+
+  const { billed_charge_usd: billedChargeUsd } = meta
+  return typeof billedChargeUsd === 'number' ? billedChargeUsd : undefined
+}
+
+async function fetchJson(url: string): Promise<unknown> {
+  const response = await fetch(url)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch AI response: ${response.status} ${response.statusText}`)
+  }
+
+  return await response.json()
+}
+
 type AuthKeySecret = {
   authKey: string
   authSecret: string
@@ -552,6 +608,56 @@ export class Transloadit {
     })
   }
 
+  /**
+   * Compile a natural-language prompt into validated Assembly Instructions.
+   *
+   * This creates a zero-upload /ai/chat Assembly, validates the structured response,
+   * and lints the generated instructions locally before returning them.
+   */
+  async compileAssemblyInstructionsFromPrompt(
+    options: CompileAssemblyInstructionsFromPromptOptions,
+  ): Promise<CompileAssemblyInstructionsResult> {
+    const timeout = options.timeout ?? 5 * 60 * 1000
+
+    return await compileAssemblyInstructionsFromPrompt({
+      ...options,
+      mcpServerUrl: options.mcpServerUrl ?? `${this._endpoint}/mcp`,
+      client: {
+        runAssemblyInstructionsCompiler: async ({ aiStep }) => {
+          const assembly = await this.createAssembly({
+            params: {
+              steps: {
+                ai: aiStep,
+              },
+            },
+            waitForCompletion: true,
+            expectedUploads: 0,
+            timeout,
+          })
+
+          const result = assembly.results?.ai?.[0]
+          const resultUrl = result?.url
+          if (!resultUrl) {
+            throw new Error('No AI response in Assembly results.')
+          }
+
+          return {
+            response: await fetchJson(resultUrl),
+            assemblyUrl: assembly.assembly_ssl_url ?? assembly.assembly_url ?? undefined,
+            billedChargeUsd: getResultBilledChargeUsd(result),
+            usageBytes: assembly.bytes_usage ?? undefined,
+          }
+        },
+        lintAssemblyInstructions: async (instructionsJson) => {
+          const lintResult = await this.lintAssemblyInstructions({
+            assemblyInstructions: instructionsJson,
+          })
+          return lintResult.issues
+        },
+      },
+    })
+  }
+
   /**
    * Mint a short-lived bearer token via POST /token.
    *

package/src/alphalib/imagemagickDensity.ts

@@ -0,0 +1,15 @@
+const positiveDecimalDensityPart = String.raw`(?:0*[1-9]\d*(?:\.\d+)?|0+\.\d*[1-9]\d*)`
+
+const imagemagickDensityPattern = new RegExp(
+  `^${positiveDecimalDensityPart}(?:x${positiveDecimalDensityPart})?$`,
+)
+
+function isValidImagemagickDensity(value: unknown): boolean {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value > 0
+  }
+
+  return typeof value === 'string' && imagemagickDensityPattern.test(value)
+}
+
+export { imagemagickDensityPattern, isValidImagemagickDensity }

package/src/alphalib/types/assemblyReplay.ts

@@ -4,14 +4,43 @@ import {
   assemblyAuthInstructionsSchema,
   fieldsSchema,
   notifyUrlSchema,
-  optionalStepsSchema,
   templateIdSchema,
 } from './template.ts'
 
+export const assemblyReplayStepSchema = z
+  .object({
+    field: z.unknown().optional(),
+    force_name: z.unknown().optional(),
+    force_original_id: z.unknown().optional(),
+    key: z.unknown().optional(),
+    output_meta: z.unknown().optional(),
+    password: z.unknown().optional(),
+    prompt: z.unknown().optional(),
+    robot: z.string().optional(),
+    secret: z.unknown().optional(),
+    url: z.unknown().optional(),
+    use: z.unknown().optional(),
+  })
+  .passthrough()
+  .describe(
+    'A full Assembly step or partial replay step override. Replay keeps this relaxed so credentials and missing robot properties can be merged back from the original Template before normal Assembly validation runs.',
+  )
+
+export const assemblyReplayStepsSchema = z
+  .union([z.record(assemblyReplayStepSchema), z.array(assemblyReplayStepSchema)])
+  .describe(
+    'Replay step overrides. Object-form steps are the normal Assembly shape; array-form steps are accepted for legacy replay compatibility and normalized before execution.',
+  )
+
+export const optionalAssemblyReplayStepsSchema = assemblyReplayStepsSchema.optional()
+
+export type AssemblyReplayStep = z.infer<typeof assemblyReplayStepSchema>
+export type AssemblyReplaySteps = z.infer<typeof assemblyReplayStepsSchema>
+
 export const assemblyReplaySchema = z
   .object({
     auth: assemblyAuthInstructionsSchema,
-    steps: optionalStepsSchema as typeof optionalStepsSchema,
+    steps: optionalAssemblyReplayStepsSchema,
     template_id: templateIdSchema,
     notify_url: notifyUrlSchema,
     fields: fieldsSchema,

package/src/alphalib/types/assemblyStatus.ts

@@ -120,15 +120,20 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'CLOUDFLARE_IMPORT_FAILURE',
   'CLOUDFLARE_IMPORT_NOT_FOUND',
   'CLOUDFLARE_IMPORT_VALIDATION',
+  'CLOUDFLARE_STORE_ACCESS_DENIED',
+  'CLOUDFLARE_STORE_NOT_FOUND',
   'CLOUDFLARE_STORE_URL_VERIFICATION_FAILURE',
   'CLOUDFLARE_STORE_VALIDATION',
+  'CLOUDFLARE_STORE_WRONG_REGION',
   'CLOUD_AI_IMAGE_VALIDATION',
   'DIGITALOCEAN_IMPORT_ACCESS_DENIED',
   'DIGITALOCEAN_IMPORT_FAILURE',
   'DIGITALOCEAN_IMPORT_NOT_FOUND',
   'DIGITALOCEAN_IMPORT_VALIDATION',
   'DIGITALOCEAN_STORE_ACCESS_DENIED',
+  'DIGITALOCEAN_STORE_NOT_FOUND',
   'DIGITALOCEAN_STORE_VALIDATION',
+  'DIGITALOCEAN_STORE_WRONG_REGION',
   'DOCUMENT_AUTOROTATE_VALIDATION',
   'DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION',
   'DOCUMENT_CONVERT_VALIDATION',
@@ -236,13 +241,19 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'MEGA_IMPORT_FAILURE',
   'MEGA_IMPORT_NOT_FOUND',
   'MEGA_IMPORT_VALIDATION',
+  'MEGA_STORE_ACCESS_DENIED',
+  'MEGA_STORE_NOT_FOUND',
   'MEGA_STORE_VALIDATION',
+  'MEGA_STORE_WRONG_REGION',
   'META_WRITE_VALIDATION',
   'MINIO_IMPORT_ACCESS_DENIED',
   'MINIO_IMPORT_FAILURE',
   'MINIO_IMPORT_NOT_FOUND',
   'MINIO_IMPORT_VALIDATION',
+  'MINIO_STORE_ACCESS_DENIED',
+  'MINIO_STORE_NOT_FOUND',
   'MINIO_STORE_VALIDATION',
+  'MINIO_STORE_WRONG_REGION',
   'NO_AUTH_EXPIRES_PARAMETER',
   'NO_AUTH_KEY_PARAMETER',
   'NO_AUTH_PARAMETER',
@@ -275,8 +286,10 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'S3_NOT_FOUND',
   'S3_STORE_ACCESS_DENIED',
   'S3_STORE_FAILURE',
+  'S3_STORE_NOT_FOUND',
   'S3_STORE_URL_VERIFICATION_FAILURE',
   'S3_STORE_VALIDATION',
+  'S3_STORE_WRONG_REGION',
   'SCRIPT_RUN_VALIDATION',
   'SERVER_403',
   'SERVER_404',
@@ -295,12 +308,18 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'SUPABASE_IMPORT_FAILURE',
   'SUPABASE_IMPORT_NOT_FOUND',
   'SUPABASE_IMPORT_VALIDATION',
+  'SUPABASE_STORE_ACCESS_DENIED',
+  'SUPABASE_STORE_NOT_FOUND',
   'SUPABASE_STORE_VALIDATION',
+  'SUPABASE_STORE_WRONG_REGION',
   'SWIFT_IMPORT_ACCESS_DENIED',
   'SWIFT_IMPORT_FAILURE',
   'SWIFT_IMPORT_NOT_FOUND',
   'SWIFT_IMPORT_VALIDATION',
+  'SWIFT_STORE_ACCESS_DENIED',
+  'SWIFT_STORE_NOT_FOUND',
   'SWIFT_STORE_VALIDATION',
+  'SWIFT_STORE_WRONG_REGION',
   'TEMPLATE_CREDENTIALS_INJECTION_ERROR',
   'TEMPLATE_DB_ERROR',
   'TEMPLATE_DENIES_STEPS_OVERRIDE',
@@ -312,7 +331,10 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'TIGRIS_IMPORT_FAILURE',
   'TIGRIS_IMPORT_NOT_FOUND',
   'TIGRIS_IMPORT_VALIDATION',
+  'TIGRIS_STORE_ACCESS_DENIED',
+  'TIGRIS_STORE_NOT_FOUND',
   'TIGRIS_STORE_VALIDATION',
+  'TIGRIS_STORE_WRONG_REGION',
   'TMP_FILE_DOWNLOAD_ERROR',
   'TOKEN_INVALID_CREDENTIALS',
   'TUS_STORE_VALIDATION',
@@ -348,7 +370,10 @@ export const assemblyStatusErrCodeSchema = z.enum([
   'WASABI_IMPORT_FAILURE',
   'WASABI_IMPORT_NOT_FOUND',
   'WASABI_IMPORT_VALIDATION',
+  'WASABI_STORE_ACCESS_DENIED',
+  'WASABI_STORE_NOT_FOUND',
   'WASABI_STORE_VALIDATION',
+  'WASABI_STORE_WRONG_REGION',
   'WORKER_JOB_ERROR',
   'YOUTUBE_STORE_PROBLEM_SENDING_FILE',
   'YOUTUBE_STORE_VALIDATION',
@@ -820,6 +845,10 @@ export const assemblyStatusBaseSchema = z.object({
   ignored_error_count: z.number().optional(),
 })
 
+export type AssemblyStatusTusUpload = NonNullable<
+  z.infer<typeof assemblyStatusBaseSchema>['tus_uploads']
+>[number]
+
 export const assemblyStatusBusySchema = z
   .object({
     ok: assemblyBusyCodeSchema,

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

@@ -127,6 +127,7 @@ export const robotMetaSchema = z.object({
       gcp: z.number(),
     })
     .optional(),
+  applyCommunityPlanMediaTrim: z.boolean().optional(),
   isAllowedForUrlTransform: z.boolean(),
   removeJobResultFilesFromDiskRightAfterStoringOnS3: z.boolean(),
   lazyLoad: z.boolean().optional(),
@@ -251,6 +252,17 @@ export const interpolationSchemaPartial = z.custom<string>(
 
 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[],
@@ -503,15 +515,19 @@ Use field names such as \`path\`, or dotted paths such as \`ffmpeg.vf\` for nest
 /**
  * Fields that are shared by all Transloadit robots.
  */
+export const robotOutputMetaSchema = z.union([
+  z.record(z.boolean()),
+  z.boolean(),
+  z.array(z.string()),
+])
+export type RobotOutputMeta = z.infer<typeof robotOutputMetaSchema>
+
 export type RobotBase = z.infer<typeof robotBase>
 export const robotBase = z
   .object({
     interpolate: robotInterpolateSchema.optional(),
 
-    output_meta: z
-      .union([z.record(z.boolean()), z.boolean(), z.array(z.string())])
-      .optional()
-      .describe(`
+    output_meta: robotOutputMetaSchema.optional().describe(`
 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.
@@ -1185,6 +1201,11 @@ export const positionSchema = z.enum([
 
 export const percentageSchema = z.string().regex(/^\d+%$/)
 
+export const httpUrlSchema = z
+  .string()
+  .url()
+  .regex(/^https?:\/\//i)
+
 export const color_with_alpha = z.string().regex(/^#?[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/)
 
 export const color_without_alpha = z.string().regex(/^#?[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/)
@@ -1295,7 +1316,13 @@ export const imageQualitySchema = z
 Controls the image compression for JPG and PNG images. Please also take a look at [🤖/image/optimize](/docs/robots/image-optimize/).
 `)
 
-export const aiProviderSchema = z.enum(['aws', 'gcp', 'replicate', 'fal', 'transloadit'])
+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
+  .enum(['auto', 'aws', 'gcp', 'replicate', 'fal', 'transloadit'])
+  .default('auto')
 
 export const granularitySchema = z.enum(['full', 'list']).default('full')
 
@@ -1318,6 +1345,12 @@ export const robotImport = z
         value === true ? ['meta', 'import', 'execute'] : value === false ? [] : value,
       )
       .default([]),
+    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.
+`),
   })
   .strict()
 
@@ -1810,7 +1843,7 @@ Splits the video into multiple chunks so that each chunk can be encoded in paral
 Allows you to specify the duration of each chunk when \`turbo\` is set to \`true\`. This means you can take advantage of that feature while using fewer <dfn>Priority Job Slots</dfn>. For instance, the longer each chunk is, the fewer <dfn>Encoding Jobs</dfn> will need to be used.
 `),
     watermark_url: z
-      .string()
+      .union([z.literal(''), httpUrlSchema])
       .default('')
       .describe(`
 A URL indicating a PNG image to be overlaid above this image. You can also [supply the watermark via another Assembly Step](/docs/topics/use-parameter/#supplying-the-watermark-via-an-assembly-step).