transloadit 4.1.0 → 4.1.3

package/src/alphalib/types/robots/audio-waveform.ts

@@ -59,7 +59,8 @@ Here is an example waveform image:
   stage: 'ga',
 }
 
-export const robotAudioWaveformInstructionsSchema = robotBase
+// Base schema with common fields
+const robotAudioWaveformInstructionsBaseSchema = robotBase
   .merge(robotUse)
   .merge(robotFFmpeg)
   .extend({
@@ -89,12 +90,6 @@ The width of the resulting image if the format \`"image"\` was selected.
       .default(64)
       .describe(`
 The height of the resulting image if the format \`"image"\` was selected.
-`),
-    style: z
-      .union([z.literal(0), z.literal(1)])
-      .default(0)
-      .describe(`
-Either a value of \`0\` or \`1\`, corresponding to using either the legacy waveform tool, or the new tool respectively, with the new tool offering an improved style. Other Robot parameters still function as described, with either tool.
 `),
     antialiasing: z
       .union([z.literal(0), z.literal(1), z.boolean()])
@@ -110,6 +105,142 @@ The color used in the center of the gradient. The format is "rrggbbaa" (red, gre
 `),
     outer_color: color_with_alpha.default('000000ff').describe(`
 The color used in the outer parts of the gradient. The format is "rrggbbaa" (red, green, blue, alpha).
+`),
+  })
+
+const styleSchema = z.preprocess(
+  (val) => {
+    // Backwards compatibility: historically this robot used numeric styles 0/1/2.
+    // The new API is `style: "v0" | "v1"`. Old v2 values are mapped to v1.
+    if (val === 'v1' || val === 1 || val === '1') return 'v1'
+    if (val === 'v0' || val === 0 || val === '0') return 'v0'
+    return val
+  },
+  z.enum(['v0', 'v1']).default('v0'),
+)
+
+// Unified schema: all parameters exist for both styles, but v1-only parameters only apply when
+// `style` is `v1` (they are accepted for v0 but have no effect).
+export const robotAudioWaveformInstructionsSchema = robotAudioWaveformInstructionsBaseSchema
+  .extend({
+    style: styleSchema.describe(`
+Waveform style version.
+
+- \`"v0"\`: Legacy waveform generation (default).
+- \`"v1"\`: Advanced waveform generation with additional parameters.
+
+For backwards compatibility, numeric values \`0\`, \`1\`, \`2\` are also accepted and mapped to \`"v0"\` (0) and \`"v1"\` (1/2).
+`),
+
+    // v1-only parameters (accepted for v0 but have no effect)
+    split_channels: z
+      .boolean()
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. If set to \`true\`, outputs multi-channel waveform data or image files, one per channel.
+`),
+    zoom: z
+      .number()
+      .int()
+      .min(1)
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Zoom level in samples per pixel. This parameter cannot be used together with \`pixels_per_second\`.
+`),
+    pixels_per_second: z
+      .number()
+      .positive()
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Zoom level in pixels per second. This parameter cannot be used together with \`zoom\`.
+`),
+    bits: z
+      .union([z.literal(8), z.literal(16)])
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Bit depth for waveform data. Can be 8 or 16.
+`),
+    start: z
+      .number()
+      .min(0)
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Start time in seconds.
+`),
+    end: z
+      .number()
+      .min(0)
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. End time in seconds (0 means end of audio).
+`),
+    colors: z
+      .enum(['audition', 'audacity'])
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Color scheme to use. Can be "audition" or "audacity".
+`),
+    border_color: color_with_alpha.optional().describe(`
+Available when style is \`"v1"\`. Border color in "rrggbbaa" format.
+`),
+    waveform_style: z
+      .enum(['normal', 'bars'])
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Waveform style. Can be "normal" or "bars".
+`),
+    bar_width: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Width of bars in pixels when waveform_style is "bars".
+`),
+    bar_gap: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Gap between bars in pixels when waveform_style is "bars".
+`),
+    bar_style: z
+      .enum(['square', 'rounded'])
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Bar style when waveform_style is "bars".
+`),
+    axis_label_color: color_with_alpha.optional().describe(`
+Available when style is \`"v1"\`. Color for axis labels in "rrggbbaa" format.
+`),
+    no_axis_labels: z
+      .boolean()
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. If set to \`true\`, renders waveform image without axis labels.
+`),
+    with_axis_labels: z
+      .boolean()
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. If set to \`true\`, renders waveform image with axis labels.
+`),
+    amplitude_scale: z
+      .number()
+      .positive()
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. Amplitude scale factor.
+`),
+    compression: z
+      .number()
+      .int()
+      .min(-1)
+      .max(9)
+      .optional()
+      .describe(`
+Available when style is \`"v1"\`. PNG compression level: 0 (none) to 9 (best), or -1 (default). Only applicable when format is "image".
 `),
   })
   .strict()
@@ -129,9 +260,10 @@ export type RobotAudioWaveformInstructionsWithHiddenFields = z.infer<
 export const interpolatableRobotAudioWaveformInstructionsSchema = interpolateRobot(
   robotAudioWaveformInstructionsSchema,
 )
-export type InterpolatableRobotAudioWaveformInstructions =
-  InterpolatableRobotAudioWaveformInstructionsInput
 
+export type InterpolatableRobotAudioWaveformInstructions = z.input<
+  typeof interpolatableRobotAudioWaveformInstructionsSchema
+>
 export type InterpolatableRobotAudioWaveformInstructionsInput = z.input<
   typeof interpolatableRobotAudioWaveformInstructionsSchema
 >
@@ -139,6 +271,7 @@ export type InterpolatableRobotAudioWaveformInstructionsInput = z.input<
 export const interpolatableRobotAudioWaveformInstructionsWithHiddenFieldsSchema = interpolateRobot(
   robotAudioWaveformInstructionsWithHiddenFieldsSchema,
 )
+
 export type InterpolatableRobotAudioWaveformInstructionsWithHiddenFields = z.infer<
   typeof interpolatableRobotAudioWaveformInstructionsWithHiddenFieldsSchema
 >

package/src/alphalib/types/robots/image-bgremove.ts

@@ -53,6 +53,12 @@ export const robotImageBgremoveInstructionsSchema = robotBase
       .enum(['transloadit', 'replicate', 'fal'])
       .optional()
       .describe('Provider to use for removing the background.'),
+    model: z
+      .string()
+      .optional()
+      .describe(
+        'Provider-specific model to use for removing the background. Mostly intended for testing and evaluation.',
+      ),
   })
   .strict()
 

package/src/alphalib/types/robots/image-generate.ts

@@ -34,10 +34,13 @@ export const robotImageGenerateInstructionsSchema = robotBase
   .merge(robotUse)
   .extend({
     robot: z.literal('/image/generate'),
-    model: z.string(),
+    model: z
+      .string()
+      .optional()
+      .describe('The AI model to use for image generation. Defaults to google/nano-banana.'),
     prompt: z.string().describe('The prompt describing the desired image content.'),
     format: z
-      .enum(['jpeg', 'png', 'gif', 'webp', 'svg'])
+      .enum(['jpeg', 'jpg', 'png', 'gif', 'webp', 'svg'])
       .optional()
       .describe('Format of the generated image.'),
     seed: z.number().optional().describe('Seed for the random number generator.'),
@@ -69,7 +72,7 @@ export type RobotImageGenerateInstructionsWithHiddenFields = z.infer<
 >
 
 export const interpolatableRobotImageGenerateInstructionsSchema = interpolateRobot(
-  robotImageGenerateInstructionsSchema,
+  robotImageGenerateInstructionsWithHiddenFieldsSchema,
 )
 export type InterpolatableRobotImageGenerateInstructions =
   InterpolatableRobotImageGenerateInstructionsInput

package/src/alphalib/types/robots/meta-write.ts

@@ -53,8 +53,7 @@ export const robotMetaWriteInstructionsSchema = robotBase
 **Note:** This <dfn>Robot</dfn> currently accepts images, videos and audio files.
 `),
     data_to_write: z
-      .object({})
-      .passthrough()
+      .record(z.unknown())
       .default({})
       .describe(`
 A key/value map defining the metadata to write into the file.

package/src/alphalib/types/templateCredential.ts

@@ -20,6 +20,7 @@ export const templateCredentialsSchema = z
       ),
     type: z
       .enum([
+        'ai',
         'azure',
         'backblaze',
         'cloudflare',

package/src/cli/OutputCtl.ts

@@ -2,7 +2,7 @@
  * Log levels following syslog severity (https://en.wikipedia.org/wiki/Syslog#Severity_level)
  * Lower numbers = more severe, higher numbers = more verbose
  */
-export const LOG_LEVEL = {
+const LOG_LEVEL = {
   ERR: 3, // Error conditions
   WARN: 4, // Warning conditions
   NOTICE: 5, // Normal but significant (default)

package/src/cli/commands/BaseCommand.ts

@@ -1,11 +1,12 @@
+import 'dotenv/config'
 import process from 'node:process'
 import { Command, Option } from 'clipanion'
-import 'dotenv/config'
 import { Transloadit as TransloaditClient } from '../../Transloadit.ts'
+import { getEnvCredentials } from '../helpers.ts'
 import type { IOutputCtl } from '../OutputCtl.ts'
 import OutputCtl, { LOG_LEVEL_DEFAULT, LOG_LEVEL_NAMES, parseLogLevel } from '../OutputCtl.ts'
 
-export abstract class BaseCommand extends Command {
+abstract class BaseCommand extends Command {
   logLevelOption = Option.String('-l,--log-level', {
     description: `Log level: ${LOG_LEVEL_NAMES.join(', ')} or 3-8 (default: notice)`,
   })
@@ -31,7 +32,8 @@ export abstract class BaseCommand extends Command {
   }
 
   protected setupClient(): boolean {
-    if (!process.env.TRANSLOADIT_KEY || !process.env.TRANSLOADIT_SECRET) {
+    const creds = getEnvCredentials()
+    if (!creds) {
       this.output.error(
         'Please provide API authentication in the environment variables TRANSLOADIT_KEY and TRANSLOADIT_SECRET',
       )
@@ -40,11 +42,7 @@ export abstract class BaseCommand extends Command {
 
     const endpoint = this.endpoint || process.env.TRANSLOADIT_ENDPOINT
 
-    this.client = new TransloaditClient({
-      authKey: process.env.TRANSLOADIT_KEY,
-      authSecret: process.env.TRANSLOADIT_SECRET,
-      ...(endpoint && { endpoint }),
-    })
+    this.client = new TransloaditClient({ ...creds, ...(endpoint && { endpoint }) })
     return true
   }
 

package/src/cli/commands/assemblies.ts

@@ -36,7 +36,7 @@ export interface AssemblyGetOptions {
   assemblies: string[]
 }
 
-export interface AssemblyDeleteOptions {
+interface AssemblyDeleteOptions {
   assemblies: string[]
 }
 

package/src/cli/commands/auth.ts

@@ -8,6 +8,7 @@ import {
 } from '../../alphalib/types/template.ts'
 import type { OptionalAuthParams } from '../../apiTypes.ts'
 import { Transloadit } from '../../Transloadit.ts'
+import { getEnvCredentials } from '../helpers.ts'
 import { UnauthenticatedCommand } from './BaseCommand.ts'
 
 type UrlParamPrimitive = string | number | boolean
@@ -80,16 +81,7 @@ async function readStdin(): Promise<string> {
   return data
 }
 
-function getCredentials(): { authKey: string; authSecret: string } | null {
-  const authKey = process.env.TRANSLOADIT_KEY || process.env.TRANSLOADIT_AUTH_KEY
-  const authSecret = process.env.TRANSLOADIT_SECRET || process.env.TRANSLOADIT_AUTH_SECRET
-
-  if (!authKey || !authSecret) {
-    return null
-  }
-
-  return { authKey, authSecret }
-}
+const getCredentials = getEnvCredentials
 
 // Result type for signature operations
 type SigResult = { ok: true; output: string } | { ok: false; error: string }

package/src/cli/commands/notifications.ts

@@ -7,12 +7,12 @@ import { AuthenticatedCommand } from './BaseCommand.ts'
 
 // --- Types and business logic ---
 
-export interface NotificationsReplayOptions {
+interface NotificationsReplayOptions {
   notify_url?: string
   assemblies: string[]
 }
 
-export async function replay(
+async function replay(
   output: IOutputCtl,
   client: Transloadit,
   { notify_url, assemblies }: NotificationsReplayOptions,

package/src/cli/commands/templates.ts

@@ -33,11 +33,11 @@ export interface TemplateModifyOptions {
   file: string
 }
 
-export interface TemplateDeleteOptions {
+interface TemplateDeleteOptions {
   templates: string[]
 }
 
-export interface TemplateListOptions {
+interface TemplateListOptions {
   before?: string
   after?: string
   order?: 'asc' | 'desc'
@@ -162,7 +162,7 @@ const TemplateIdSchema = z.object({
   id: z.string(),
 })
 
-export function list(
+function list(
   output: IOutputCtl,
   client: Transloadit,
   { before, after, order, sort, fields }: TemplateListOptions,

package/src/cli/helpers.ts

@@ -1,8 +1,16 @@
 import fs from 'node:fs'
 import type { Readable } from 'node:stream'
-import type { APIError } from './types.ts'
 import { isAPIError } from './types.ts'
 
+export function getEnvCredentials(): { authKey: string; authSecret: string } | null {
+  const authKey = process.env.TRANSLOADIT_KEY ?? process.env.TRANSLOADIT_AUTH_KEY
+  const authSecret = process.env.TRANSLOADIT_SECRET ?? process.env.TRANSLOADIT_AUTH_SECRET
+
+  if (!authKey || !authSecret) return null
+
+  return { authKey, authSecret }
+}
+
 export function createReadStream(file: string): Readable {
   if (file === '-') return process.stdin
   return fs.createReadStream(file)
@@ -26,8 +34,9 @@ export function formatAPIError(err: unknown): string {
   return String(err)
 }
 
-// Re-export APIError type for convenience
-export type { APIError }
+// Re-export APIError type for CLI consumers relying on deep imports.
+/** @public */
+export type { APIError } from './types.ts'
 
 export function zip<A, B>(listA: A[], listB: B[]): [A, B][]
 export function zip<T>(...lists: T[][]): T[][]

package/src/cli/types.ts

@@ -1,23 +1,15 @@
 import { z } from 'zod'
 import type { Steps } from '../alphalib/types/template.ts'
 import { optionalStepsSchema } from '../alphalib/types/template.ts'
-import type { BillResponse, ListedTemplate, TemplateResponse } from '../apiTypes.ts'
-import type { AssemblyStatus, Transloadit } from '../Transloadit.ts'
-import type { IOutputCtl } from './OutputCtl.ts'
-
-// Re-export transloadit types for CLI use
-export type { AssemblyStatus, BillResponse, ListedTemplate, TemplateResponse }
-export type { Transloadit }
-export type { CreateAssemblyOptions } from '../Transloadit.ts'
 
 // Zod schemas for runtime validation
-export const APIErrorSchema = z.object({
+const APIErrorSchema = z.object({
   error: z.string(),
   message: z.string(),
 })
 export type APIError = z.infer<typeof APIErrorSchema>
 
-export const TransloaditAPIErrorSchema = z.object({
+const TransloaditAPIErrorSchema = z.object({
   error: z.string().optional(),
   message: z.string(),
   code: z.string().optional(),
@@ -54,98 +46,6 @@ export interface TemplateFile {
   data: TemplateFileData
 }
 
-// Template list item (from API)
-export interface TemplateListItem {
-  id: string
-  modified: string
-  name?: string
-}
-
-// CLI Invocation types
-export interface BaseInvocation {
-  error?: boolean
-  message?: string
-  mode: string
-  action?: string
-  logLevel?: number
-  jsonMode?: boolean
-}
-
-export interface AssemblyInvocation extends BaseInvocation {
-  mode: 'assemblies'
-  action?: 'create' | 'get' | 'list' | 'delete' | 'replay'
-  inputs: string[]
-  output?: string
-  recursive?: boolean
-  watch?: boolean
-  del?: boolean
-  reprocessStale?: boolean
-  steps?: string
-  template?: string
-  fields?: Record<string, string>
-  assemblies?: string[]
-  before?: string
-  after?: string
-  keywords?: string[]
-  notify_url?: string
-  reparse?: boolean
-}
-
-export interface TemplateInvocation extends BaseInvocation {
-  mode: 'templates'
-  action?: 'create' | 'get' | 'list' | 'delete' | 'modify' | 'sync'
-  templates?: string[]
-  template?: string
-  name?: string
-  file?: string
-  files?: string[]
-  before?: string
-  after?: string
-  order?: 'asc' | 'desc'
-  sort?: string
-  fields?: string[]
-  recursive?: boolean
-}
-
-export interface BillInvocation extends BaseInvocation {
-  mode: 'bills'
-  action?: 'get'
-  months: string[]
-}
-
-export interface NotificationInvocation extends BaseInvocation {
-  mode: 'assembly-notifications'
-  action?: 'list' | 'replay'
-  assemblies?: string[]
-  notify_url?: string
-  type?: string
-  assembly_id?: string
-  pagesize?: number
-}
-
-export interface HelpInvocation extends BaseInvocation {
-  mode: 'help' | 'version' | 'register'
-}
-
-export type Invocation =
-  | AssemblyInvocation
-  | TemplateInvocation
-  | BillInvocation
-  | NotificationInvocation
-  | HelpInvocation
-
-// Command handler type
-export type CommandHandler<T extends BaseInvocation = BaseInvocation> = (
-  output: IOutputCtl,
-  client: Transloadit | undefined,
-  invocation: T,
-) => void | Promise<void>
-
-// Type guard for Error
-export function isError(value: unknown): value is Error {
-  return value instanceof Error
-}
-
 // Helper to ensure error is Error type
 export function ensureError(value: unknown): Error {
   if (value instanceof Error) {
@@ -168,16 +68,3 @@ export function isTransloaditAPIError(value: unknown): value is TransloaditAPIEr
 export function isErrnoException(value: unknown): value is NodeJS.ErrnoException {
   return value instanceof Error && 'code' in value
 }
-
-// Safe array access helper
-export function safeGet<T>(arr: T[], index: number): T | undefined {
-  return arr[index]
-}
-
-// Assert defined helper
-export function assertDefined<T>(value: T | undefined | null, message: string): T {
-  if (value === undefined || value === null) {
-    throw new Error(message)
-  }
-  return value
-}