transloadit 4.12.0 → 4.13.1

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

@@ -102,6 +102,8 @@ export const robotNames = z.enum([
   'TextSpeakRobot',
   'TextTranslateRobot',
   'FilePreviewRobot',
+  'TransloaditImportRobot',
+  'TransloaditStoreRobot',
   'TusStoreRobot',
   'ProgressSimulateRobot',
 ])

package/src/alphalib/types/robots/file-serve.ts

@@ -66,11 +66,11 @@ Also consider configuring caching headers and cache-control directives to contro
 You can leverage [signed Smart CDN URLs](/docs/api/authentication/#smart-cdn) to avoid abuse of our encoding platform. Below is a quick Node.js example using our Node SDK, but there are [examples for other languages and SDKs](/docs/api/authentication/#example-code) as well.
 
 \`\`\`javascript
-// yarn add transloadit
+// yarn add @transloadit/node
 // or
-// npm install --save transloadit
+// npm install --save @transloadit/node
 
-import { Transloadit } from 'transloadit'
+import { Transloadit } from '@transloadit/node'
 
 const transloadit = new Transloadit({
   authKey: 'YOUR_TRANSLOADIT_KEY',
@@ -108,6 +108,14 @@ An optional duration in seconds that the served file should be cached. When set,
 
 This is useful for controlling data retention in CDNs. For instance, if your temporary files are deleted after 24 hours, you can set \`cache_duration\` to \`86400\` to ensure cached copies also expire within that window.
 `),
+    download_name: z
+      .string()
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: reject header-injection control characters, not literal text.
+      .regex(/^[^/\\\u0000-\u001f\u007f-\u009f]{0,255}$/u)
+      .optional()
+      .describe(
+        'Serve as an attachment using this Unicode filename. Empty or omitted keeps inline delivery. Overrides a Content-Disposition header without changing the bytes or Range support.',
+      ),
     headers: z
       .record(z.string())
       .default({

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

@@ -0,0 +1,154 @@
+import type { RobotMetaInput } from './_instructions-primitives.ts'
+
+import { z } from 'zod'
+
+import { damIdSchema } from '../storageAsset.ts'
+import {
+  booleanStringSchema,
+  interpolateRobot,
+  interpolationSchemaFull,
+  recursive,
+  robotBase,
+  robotImport,
+} from './_instructions-primitives.ts'
+
+/** Cross-field validation runs after interpolation-aware parsing at the Assembly Step boundary. */
+export function refineTransloaditImportSelector(
+  step: {
+    robot: string
+    path?: unknown
+    asset_id?: unknown
+    version_id?: unknown
+    recursive?: unknown
+  },
+  context: z.RefinementCtx,
+): void {
+  if (step.robot !== '/transloadit/import') return
+  const hasPath = step.path !== undefined
+  const hasAsset = step.asset_id !== undefined
+  if (hasPath === hasAsset || (step.version_id !== undefined && !hasAsset)) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: [step.version_id !== undefined && !hasAsset ? 'version_id' : 'asset_id'],
+      message: 'Select either path, or asset_id with an optional version_id.',
+    })
+  }
+  if (hasAsset && step.recursive === true) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['recursive'],
+      message: 'Recursive imports require a path, not an asset_id.',
+    })
+  }
+}
+
+const recursiveDescription = `
+Whether to import files from subfolders and sub-subfolders when \`path\` is a folder. By default
+only the folder's own files are imported.
+`
+
+export const meta: RobotMetaInput = {
+  bytescount: 10,
+  discount_factor: 0.1,
+  discount_pct: 90,
+  example_code: {
+    steps: {
+      imported: {
+        robot: '/transloadit/import',
+        path: 'photos/cat.jpg',
+      },
+    },
+  },
+  example_code_description: 'Import a file from Transloadit Storage:',
+  has_small_icon: true,
+  isAllowedForUrlTransform: true,
+  isInternal: false,
+  minimum_charge: 0,
+  name: 'TransloaditImportRobot',
+  output_factor: 1,
+  override_lvl1: 'File Importing',
+  priceFactor: 10,
+  purpose_sentence: 'imports files from Transloadit Storage',
+  purpose_verb: 'import',
+  purpose_word: 'Transloadit Storage',
+  purpose_words: 'Import files from Transloadit Storage',
+  queueSlotCount: 10,
+  removeJobResultFilesFromDiskRightAfterStoringOnS3: true,
+  service_slug: 'file-importing',
+  slot_count: 10,
+  stage: 'beta',
+  title: 'Import files from Transloadit Storage',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotTransloaditImportInstructionsSchema = robotBase
+  .merge(robotImport)
+  .extend({
+    robot: z.literal('/transloadit/import').describe(`
+Imports files from your Workspace's Transloadit Storage. Select a mutable location with
+\`path\`, or a logical asset with \`asset_id\`. Add \`version_id\` to pin the exact stored bytes.
+IDs remain subject to Workspace access and version retention.
+`),
+    path: z
+      .string()
+      .optional()
+      .describe(`
+The current file or folder location, for example \`photos/cat.jpg\`. Use either \`path\` or
+\`asset_id\`, not both. Renaming makes an old path stale; overwriting changes what it imports.
+`),
+    asset_id: damIdSchema.optional().describe(`
+The stored asset's stable ID. Without \`version_id\`, imports its current version even after
+renaming or moving it. Cannot be combined with \`path\` or recursive folder imports.
+`),
+    version_id: damIdSchema.optional().describe(`
+The exact retained version of \`asset_id\` to import. Requires \`asset_id\`; a missing or deleted
+version never falls back to the current version.
+`),
+    recursive: recursive.describe(recursiveDescription),
+  })
+  .strict()
+
+export const robotTransloaditImportInstructionsWithHiddenFieldsSchema =
+  robotTransloaditImportInstructionsSchema.extend({
+    result: z
+      .union([z.literal('debug'), robotTransloaditImportInstructionsSchema.shape.result])
+      .optional(),
+  })
+
+export type RobotTransloaditImportInstructions = z.infer<
+  typeof robotTransloaditImportInstructionsSchema
+>
+export type RobotTransloaditImportInstructionsWithHiddenFields = z.infer<
+  typeof robotTransloaditImportInstructionsWithHiddenFieldsSchema
+>
+
+export const interpolatableRobotTransloaditImportInstructionsSchema = interpolateRobot(
+  robotTransloaditImportInstructionsSchema,
+).extend({
+  // The generic boolean interpolator changes literal false to true. Keep Storage's documented
+  // false default intact; unresolved variables are validated after uploader interpolation.
+  recursive: z
+    .union([
+      recursive,
+      booleanStringSchema.transform((value) => value === 'true'),
+      interpolationSchemaFull,
+    ])
+    .describe(recursiveDescription),
+})
+export type InterpolatableRobotTransloaditImportInstructions =
+  InterpolatableRobotTransloaditImportInstructionsInput
+
+export type InterpolatableRobotTransloaditImportInstructionsInput = z.input<
+  typeof interpolatableRobotTransloaditImportInstructionsSchema
+>
+
+export const interpolatableRobotTransloaditImportInstructionsWithHiddenFieldsSchema =
+  interpolateRobot(robotTransloaditImportInstructionsWithHiddenFieldsSchema).extend({
+    recursive: interpolatableRobotTransloaditImportInstructionsSchema.shape.recursive,
+  })
+export type InterpolatableRobotTransloaditImportInstructionsWithHiddenFields =
+  InterpolatableRobotTransloaditImportInstructionsWithHiddenFieldsInput
+export type InterpolatableRobotTransloaditImportInstructionsWithHiddenFieldsInput = z.input<
+  typeof interpolatableRobotTransloaditImportInstructionsWithHiddenFieldsSchema
+>

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

@@ -0,0 +1,98 @@
+import type { RobotMetaInput } from './_instructions-primitives.ts'
+
+import { z } from 'zod'
+
+import { interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
+
+export const meta: RobotMetaInput = {
+  bytescount: 10,
+  discount_factor: 0.1,
+  discount_pct: 90,
+  example_code: {
+    steps: {
+      stored: {
+        robot: '/transloadit/store',
+        use: ':original',
+      },
+    },
+  },
+  example_code_description: 'Store uploaded files in Transloadit Storage:',
+  has_small_icon: true,
+  isAllowedForUrlTransform: false,
+  isInternal: false,
+  minimum_charge: 0,
+  name: 'TransloaditStoreRobot',
+  output_factor: 1,
+  override_lvl1: 'File Exporting',
+  priceFactor: 10,
+  purpose_sentence: 'stores files privately in Transloadit Storage',
+  purpose_verb: 'export',
+  purpose_word: 'Transloadit Storage',
+  purpose_words: 'Store files in Transloadit Storage',
+  queueSlotCount: 2,
+  removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
+  service_slug: 'file-exporting',
+  slot_count: 2,
+  stage: 'beta',
+  title: 'Store files in Transloadit Storage',
+  trackOutputFileSize: true,
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotTransloaditStoreInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/transloadit/store').describe(`
+Stores each input privately in Transloadit Storage.
+`),
+    conflict_strategy: z
+      .enum(['error', 'overwrite', 'rename'])
+      .default('error')
+      .describe(`
+Chooses how to handle an existing destination. By default, an occupied path fails. Select
+\`rename\` to allocate a different filename, or \`overwrite\` to create a new version of the
+existing asset. Always save the returned asset identity, version and final path.
+`),
+    path: z
+      .string()
+      .default('${file.url_name}')
+      .describe(`
+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.
+`),
+  })
+  .strict()
+
+export const robotTransloaditStoreInstructionsWithHiddenFieldsSchema =
+  robotTransloaditStoreInstructionsSchema.extend({
+    result: z
+      .union([z.literal('debug'), robotTransloaditStoreInstructionsSchema.shape.result])
+      .optional(),
+  })
+
+export type RobotTransloaditStoreInstructions = z.infer<
+  typeof robotTransloaditStoreInstructionsSchema
+>
+export type RobotTransloaditStoreInstructionsWithHiddenFields = z.infer<
+  typeof robotTransloaditStoreInstructionsWithHiddenFieldsSchema
+>
+
+export const interpolatableRobotTransloaditStoreInstructionsSchema = interpolateRobot(
+  robotTransloaditStoreInstructionsSchema,
+)
+export type InterpolatableRobotTransloaditStoreInstructions =
+  InterpolatableRobotTransloaditStoreInstructionsInput
+
+export type InterpolatableRobotTransloaditStoreInstructionsInput = z.input<
+  typeof interpolatableRobotTransloaditStoreInstructionsSchema
+>
+
+export const interpolatableRobotTransloaditStoreInstructionsWithHiddenFieldsSchema =
+  interpolateRobot(robotTransloaditStoreInstructionsWithHiddenFieldsSchema)
+export type InterpolatableRobotTransloaditStoreInstructionsWithHiddenFields =
+  InterpolatableRobotTransloaditStoreInstructionsWithHiddenFieldsInput
+export type InterpolatableRobotTransloaditStoreInstructionsWithHiddenFieldsInput = z.input<
+  typeof interpolatableRobotTransloaditStoreInstructionsWithHiddenFieldsSchema
+>

package/src/alphalib/types/storageAsset.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod'
+
+/** Maximum normalized Storage path length supported by the catalog schema. */
+export const damPathMaxCodePoints = 512
+
+// A Unicode regexp counts code points and stays portable across the published Zod 3/4 schemas.
+const boundedPathSchema = z.string().regex(new RegExp(`^[\\s\\S]{0,${damPathMaxCodePoints}}$`, 'u'))
+
+/** Canonical path and JSON representation of a 128-bit Storage identifier. */
+export const damIdPattern = /^[A-Za-z0-9_-]{21}[AQgw]$/u
+
+/** Canonical public Storage asset, version and folder identifier. */
+export const damIdSchema = z
+  .string()
+  .regex(damIdPattern)
+  .describe('Case-sensitive, canonical 22-character Base64URL Storage identifier.')
+
+/** A retained version of a live Workspace asset, independent of its mutable location. */
+export const storedAssetSchema = z.object({
+  workspace: z.string().min(1),
+  asset_id: damIdSchema,
+  version_id: damIdSchema,
+  path: z.string().min(1),
+  size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  mime: z.string().nullable(),
+  md5hash: z
+    .string()
+    .regex(/^[a-f0-9]{32}$/u)
+    .optional(),
+  sha256: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/u)
+    .optional(),
+  width: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+  height: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+})
+
+/** Store, read and recovery share this shape; image clients may enrich it with placeholders. */
+export type StoredAsset = z.infer<typeof storedAssetSchema>
+
+/** Bounded metadata paging; cursors are the last returned, case-sensitive asset path. */
+export const damAssetsListOptionsSchema = z.object({
+  prefix: boundedPathSchema.default(''),
+  cursor: boundedPathSchema.min(1).optional(),
+  limit: z.number().int().min(1).max(500).default(100),
+})
+
+/** An omitted version selects the current version; an explicit version never falls back. */
+export const damAssetGetOptionsSchema = z.object({ version_id: damIdSchema.optional() })
+
+/** Omit the destination to rename in place; null moves to the Workspace root. */
+export const damAssetMoveOptionsSchema = z.object({
+  destination_folder_id: damIdSchema.nullable().optional(),
+  filename: z
+    .string()
+    .regex(/^[^/\\\p{Cc}]{1,255}$/u)
+    .refine(
+      (name) => name.trim() === name && name !== '.' && name !== '..',
+      'Use a filename, not a path',
+    )
+    .optional(),
+})
+
+export type MoveStoredAssetOptions = z.input<typeof damAssetMoveOptionsSchema>
+
+/** Native metadata is the same version-pinned shape returned by storing a file. */
+export const damAssetFoundResponseSchema = z
+  .object({
+    message: z.string().min(1),
+    ok: z.literal('DAM_ASSET_FOUND'),
+    asset: storedAssetSchema,
+  })
+  .strict()
+
+/** A bounded catalog page; null means there is no next page, even in an empty Workspace. */
+export const damAssetsListedResponseSchema = z
+  .object({
+    workspace: storedAssetSchema.shape.workspace,
+    message: z.string().min(1),
+    ok: z.literal('DAM_ASSETS_LISTED'),
+    assets: z.array(storedAssetSchema),
+    next_cursor: z.string().nullable(),
+  })
+  .strict()
+
+export type StoredAssetsPage = z.infer<typeof damAssetsListedResponseSchema>
+export type ListStoredAssetsOptions = z.input<typeof damAssetsListOptionsSchema>
+export type GetStoredAssetOptions = z.input<typeof damAssetGetOptionsSchema>

package/src/alphalib/types/template.ts

@@ -9,6 +9,7 @@ import type {
   RobotsWithHiddenBotsAndFields,
 } from './robots/_index.ts'
 import type { RobotUse } from './robots/_instructions-primitives.ts'
+import { refineTransloaditImportSelector } from './robots/transloadit-import.ts'
 
 export type Step = RobotsSchema
 export type StepInput = Step
@@ -24,6 +25,7 @@ export const stepSchema: z.ZodType<Step> = z
       .describe('Identifier of the [robot](https://transloadit.com/docs/robots/) to execute'),
   })
   .and(robotsSchema)
+  .superRefine(refineTransloaditImportSelector)
 export const stepsSchema: z.ZodType<Steps> = z
   .record(stepSchema)
   .describe('Contains Assembly Instructions.')
@@ -42,6 +44,7 @@ export const stepSchemaWithHiddenFields: z.ZodType<StepWithHiddenFields> = z
       .describe('Identifier of the [robot](https://transloadit.com/docs/robots/) to execute'),
   })
   .and(robotsWithHiddenBotsAndFieldsSchema)
+  .superRefine(refineTransloaditImportSelector)
 export const stepsSchemaWithHiddenFields: z.ZodType<StepsWithHiddenFields> = z
   .record(stepSchemaWithHiddenFields)
   .describe('Contains Assembly Instructions.')

package/src/cli/commands/BaseCommand.ts

@@ -1,3 +1,4 @@
+import type { ResolvedCliConfig } from '../helpers.ts'
 import type { IOutputCtl } from '../OutputCtl.ts'
 
 import { Command, Option } from 'clipanion'
@@ -22,6 +23,7 @@ abstract class BaseCommand extends Command {
 
   protected output!: IOutputCtl
   protected client!: TransloaditClient
+  protected cliConfig!: ResolvedCliConfig
 
   protected setupOutput(): void {
     const logLevel = this.logLevelOption ? parseLogLevel(this.logLevelOption) : LOG_LEVEL_DEFAULT
@@ -31,8 +33,8 @@ abstract class BaseCommand extends Command {
     })
   }
 
-  protected setupClient(): boolean {
-    const config = resolveCliConfig()
+  protected setupClient(config: ResolvedCliConfig = resolveCliConfig()): boolean {
+    this.cliConfig = config
     if (config.auth == null) {
       this.output.error(config.loadError ?? buildMissingAuthMessage())
       return false

package/src/cli/commands/assemblies.ts

@@ -132,9 +132,11 @@ function parseTemplateFieldAssignments(
   return fieldsMap
 }
 
-const AssemblySchema = z.object({
-  id: z.string(),
-})
+const AssemblySchema = z
+  .object({
+    id: z.string(),
+  })
+  .passthrough()
 
 // --- Business logic functions (from assemblies.ts) ---
 
@@ -163,8 +165,14 @@ export function list(
       if (fields == null) {
         output.print(parsed.data.id, assembly)
       } else {
-        const assemblyRecord = assembly as Record<string, unknown>
-        output.print(fields.map((field) => assemblyRecord[field]).join(' '), assembly)
+        const record = parsed.data
+        const selected = fields.filter((field) => Object.hasOwn(record, field))
+        output.print(
+          fields
+            .map((field) => (Object.hasOwn(record, field) ? record[field] : undefined))
+            .join(' '),
+          Object.fromEntries(selected.map((field) => [field, record[field]])),
+        )
       }
     }
   })

package/src/cli/commands/auth.ts

@@ -110,10 +110,10 @@ function parseJsonObject<TSchema extends z.ZodTypeAny>(
 // Core logic for signature generation
 function generateSignature(
   input: string,
-  credentials: { authKey: string; authSecret: string },
+  credentials: CliKeySecretCredentials,
   algorithm?: string,
 ): OutputResult {
-  const { authKey, authSecret } = credentials
+  const { authKey } = credentials
   let params: CliSignatureParams
 
   if (input === '') {
@@ -136,7 +136,7 @@ function generateSignature(
     }
   }
 
-  const client = new Transloadit({ authKey, authSecret })
+  const client = new Transloadit(credentials)
   try {
     const signature = client.calcSignature(params as OptionalAuthParams, algorithm)
     return { ok: true, output: JSON.stringify(signature) }
@@ -286,6 +286,29 @@ export async function runSmartSig(options: RunSmartSigOptions = {}): Promise<voi
   }
 }
 
+/** Auth group help lists command definitions once while preserving every invocation alias. */
+export class AuthHelpCommand extends Command {
+  // Explicit help paths avoid Clipanion's prefix matching, which lists each alias as a command.
+  static override paths = [['auth', '--help'], ['auth', '-h'], ['auth']]
+
+  override execute(): Promise<void> {
+    const commands = this.cli
+      .definitions()
+      .filter((command) => command.path.startsWith(`${this.cli.binaryName} auth `))
+    this.context.stdout.write(
+      [
+        'Authentication commands',
+        '',
+        ...commands.map((command) => `  ${command.path}\n    ${command.description ?? ''}`),
+        '',
+        'Use <command> --help for options.',
+        '',
+      ].join('\n'),
+    )
+    return Promise.resolve()
+  }
+}
+
 /**
  * Generate a signature for assembly params
  */