transloadit 4.13.1 → 5.0.0

package/src/alphalib/types/storageAsset.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 
+import { describeApiParameter, describeApiParameterFields } from './apiParameterDescription.ts'
+
 /** Maximum normalized Storage path length supported by the catalog schema. */
 export const damPathMaxCodePoints = 512
 
@@ -10,43 +12,97 @@ const boundedPathSchema = z.string().regex(new RegExp(`^[\\s\\S]{0,${damPathMaxC
 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.')
+export const damIdSchema = describeApiParameter(
+  'damId',
+  z.string().regex(damIdPattern),
+  'Case-sensitive, canonical 22-character Base64URL DAM 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(),
-})
+export const storedAssetSchema = z.object(
+  describeApiParameterFields(
+    'storedAsset',
+    {
+      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(),
+      thumbhash: z
+        .string()
+        .regex(
+          /^(?:[A-Za-z0-9+/]{4}){1,15}(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)$/u,
+        )
+        .optional(),
+      has_alpha: z.boolean().optional(),
+    },
+    {
+      workspace:
+        'Workspace slug that owns this asset. Authenticate for the same Workspace when reading or managing it.',
+      asset_id:
+        'Stable asset ID. It survives native moves and renames; use it without a version to select the current bytes.',
+      version_id:
+        'Exact immutable version of this asset. Pair with asset_id to select retained bytes; a missing version never falls back to the current version.',
+      path: 'Current mutable location relative to the Workspace. A rename makes the previous path stale; overwriting can change the bytes at this path.',
+      size: 'Size of the stored file in bytes.',
+      mime: 'MIME type of the stored bytes, or null when unknown.',
+      md5hash: 'Lowercase MD5 checksum of the stored bytes, when available.',
+      sha256: 'Lowercase SHA-256 checksum of the stored bytes, when available.',
+      width: 'Display width in pixels, after applying EXIF orientation, when known.',
+      height: 'Display height in pixels, after applying EXIF orientation, when known.',
+      thumbhash:
+        'Base64-encoded ThumbHash of this version’s displayed pixels, when requested with output_meta.thumbhash on its producing Step. This is image data: apply the same access controls as the original.',
+      has_alpha:
+        'Whether the image has an alpha channel, even if all its pixels are opaque. Present when ThumbHash extraction succeeds; absence means unknown.',
+    },
+  ),
+)
 
-/** Store, read and recovery share this shape; image clients may enrich it with placeholders. */
+/** Store, read and recovery share this version-pinned shape, including optional placeholders. */
 export type StoredAsset = z.infer<typeof storedAssetSchema>
 
+/** Shared explanations for portable client options and normalized API request fields. */
+export const damAssetsListDescriptions = {
+  prefix:
+    'Only list current asset paths starting with this case-sensitive prefix. The empty default includes the whole Workspace; include a trailing slash to select a directory boundary.',
+  cursor:
+    'Opaque continuation value from next_cursor in the previous response. Keep the same prefix while paging. Omit for the first page.',
+  limit:
+    'Maximum number of assets per page. Defaults to 100 and accepts up to 500; follow next_cursor until null.',
+} as const
+
 /** 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),
-})
+export const damAssetsListOptionsSchema = z.object(
+  describeApiParameterFields(
+    'storedAssetsList',
+    {
+      prefix: boundedPathSchema.default(''),
+      cursor: boundedPathSchema.min(1).optional(),
+      limit: z.number().int().min(1).max(500).default(100),
+    },
+    damAssetsListDescriptions,
+  ),
+)
 
 /** An omitted version selects the current version; an explicit version never falls back. */
-export const damAssetGetOptionsSchema = z.object({ version_id: damIdSchema.optional() })
+export const damAssetGetOptionsSchema = z.object({
+  version_id: describeApiParameter(
+    'storedAssetGetVersionId',
+    damIdSchema.optional(),
+    'Optional retained version of the selected asset. Omit for the current version. A missing or deleted version returns an error and never falls back to current bytes.',
+  ),
+})
 
 /** Omit the destination to rename in place; null moves to the Workspace root. */
 export const damAssetMoveOptionsSchema = z.object({

package/src/alphalib/types/utility.ts

@@ -0,0 +1,52 @@
+/** An array of an object's own enumerable entries with typed keys and values. */
+export type ObjectEntries<T extends object> =
+  T extends Map<infer Key, infer Value>
+    ? [Key, Value][]
+    : T extends Set<infer Item>
+      ? [Item, Item][]
+      : T extends readonly unknown[]
+        ? [number, T[number]][]
+        : T extends object
+          ? [keyof T, T[keyof T]][]
+          : never
+
+/** A value that may be returned directly or through a promise-like object. */
+export type Promisable<T> = T | PromiseLike<T>
+
+type Simplify<T> = { [Key in keyof T]: T[Key] } & {}
+
+type PickIndexSignature<T> = {
+  // biome-ignore lint/complexity/noBannedTypes: Empty-object assignability distinguishes index signatures from required keys.
+  [Key in keyof T as {} extends Record<Key, unknown> ? Key : never]: T[Key]
+}
+
+type OmitIndexSignature<T> = {
+  // biome-ignore lint/complexity/noBannedTypes: Empty-object assignability distinguishes index signatures from required keys.
+  [Key in keyof T as {} extends Record<Key, unknown> ? never : Key]: T[Key]
+}
+
+type SimpleMerge<Destination, Source> = {
+  [Key in keyof Destination as Key extends keyof Source ? never : Key]: Destination[Key]
+} & Source
+
+/** An object type formed by overwriting destination properties with source properties. */
+export type MergeObjects<Destination, Source> = Simplify<
+  SimpleMerge<PickIndexSignature<Destination>, PickIndexSignature<Source>> &
+    SimpleMerge<OmitIndexSignature<Destination>, OmitIndexSignature<Source>>
+>
+
+/** A string literal type with every search occurrence replaced. */
+export type StringReplaceAll<
+  Input extends string,
+  Search extends string,
+  Replacement extends string,
+  Accumulator extends string = '',
+> = Search extends string
+  ? Search extends ''
+    ? Input
+    : Replacement extends string
+      ? Input extends `${infer Head}${Search}${infer Tail}`
+        ? StringReplaceAll<Tail, Search, Replacement, `${Accumulator}${Head}${Replacement}`>
+        : `${Accumulator}${Input}`
+      : never
+  : never

package/src/cli/commands/storage.ts

@@ -11,6 +11,7 @@ import { z } from 'zod'
 import { ApiError } from '../../ApiError.ts'
 import { storedAssetSchema } from '../../alphalib/types/storageAsset.ts'
 import InconsistentResponseError from '../../InconsistentResponseError.ts'
+import { storageImagePlaceholderSchema } from '../../storageImage.ts'
 import { normalizeStoragePublicPrefix } from '../../storagePublicPrefixes.ts'
 import { Transloadit } from '../../Transloadit.ts'
 import { noticeCliCredentialSource, quoteCliArgument, resolveCliConfig } from '../helpers.ts'
@@ -235,6 +236,8 @@ export class StorageStoreCommand extends StorageProjectCommand {
       Storage writes must be enabled. Existing Storage paths conflict unless --overwrite is explicit.
       --hashed inserts eight MD5 hex digits before the extension. Matching catalog receipts skip
       repeat uploads; changed bytes get a fresh name. --hashed cannot be combined with --overwrite.
+      --placeholder blur requests server metadata on new uploads. Successful extraction adds
+      metadata usage of 20% of the file bytes. Missing placeholders never retry a completed upload.
       The project catalog binds workspace, published prefixes and image receipts. Each successful
       upload is saved atomically before the next. Do not run two writers against the same catalog.
       The catalog defaults to transloadit.images.json; --receipts selects another file.
@@ -254,6 +257,9 @@ export class StorageStoreCommand extends StorageProjectCommand {
   overwrite = Option.Boolean('--overwrite', false, {
     description: 'Explicitly replace an existing Storage path',
   })
+  placeholder = Option.String('--placeholder', {
+    description: 'Server placeholder: blur opts into metadata extraction; empty is the default',
+  })
   publicDelivery = Option.Boolean('--public', false, {
     description:
       'Publish the destination directory recursively, including current and future objects',
@@ -267,6 +273,9 @@ export class StorageStoreCommand extends StorageProjectCommand {
     let published: string | undefined
     try {
       noticeCliCredentialSource(this.cliConfig, this.output)
+      const placeholder = storageImagePlaceholderSchema.optional().parse(this.placeholder, {
+        path: ['--placeholder'],
+      })
       if (this.hashed && this.overwrite)
         throw new Error(
           '--hashed cannot be combined with --overwrite; changed bytes get a new name',
@@ -350,6 +359,7 @@ export class StorageStoreCommand extends StorageProjectCommand {
             }
             stored.receipt ??= await this.client.storeImage(input.file, {
               path: destination,
+              ...(placeholder === undefined ? {} : { placeholder }),
               signal,
               onReceipt: (receipt, expected, assemblyId) => {
                 const sizeMatches = receipt.size === expected.size
@@ -429,9 +439,19 @@ export class StorageStoreCommand extends StorageProjectCommand {
           })
         }
         const receipt = stored.receipt
+        if (placeholder === 'blur' && receipt.thumbhash === undefined) {
+          this.output.notice(
+            unchanged
+              ? `Placeholder unavailable for ${JSON.stringify(receipt.path)}. Use storage receipts sync to recover metadata already on the server; no file was uploaded or replaced. Sync cannot generate a missing hash.`
+              : `Placeholder unavailable for ${JSON.stringify(receipt.path)}; the image was stored successfully. Extraction is best-effort; the saved receipt remains usable without blur.`,
+          )
+        }
         publicImage ||= published !== undefined && receipt.path.startsWith(published)
         const blur =
-          saved && publicImage && receipt.thumbhash !== undefined && receipt.hasAlpha !== true
+          saved &&
+          publicImage &&
+          receipt.thumbhash !== undefined &&
+          (receipt.has_alpha ?? receipt.hasAlpha) !== true
         // A foreign catalog says nothing about this destination's policy or rendering setup.
         const setupAdvice =
           !saved || setupPrinted
@@ -665,7 +685,13 @@ export class StorageReceiptsSyncCommand extends UnauthenticatedCommand {
                 evidence.data.version_id === asset.version_id
                   ? evidence.data
                   : {}
-              return [asset.path, { ...retained, ...asset, apiOrigin: endpoint }]
+              const merged: z.infer<typeof uploadEvidenceSchema> = {
+                ...retained,
+                ...asset,
+                apiOrigin: endpoint,
+              }
+              if (asset.has_alpha !== undefined) delete merged.hasAlpha
+              return [asset.path, merged]
             })
             count = entries.length
             return Object.fromEntries(entries)

package/src/cli/semanticIntents/imageGenerate.ts

@@ -5,7 +5,7 @@ import { basename } from 'node:path'
 
 import { parseOptionalEnumValue } from './parsing.ts'
 
-const defaultImageGenerateModel = 'google/nano-banana-2'
+const defaultImageGenerateModel = 'openai/gpt-image-2.5-flare'
 const imageGenerateFormats = ['jpeg', 'jpg', 'png', 'gif', 'webp', 'svg'] as const
 
 const imageGenerateOptionDefinitions = [
@@ -23,7 +23,7 @@ const imageGenerateOptionDefinitions = [
     kind: 'string',
     propertyName: 'model',
     optionFlags: '--model',
-    description: `The AI model to use for image generation. Defaults to ${defaultImageGenerateModel}. Backend-supported models include openai/gpt-image-2 and Google Nano Banana variants.`,
+    description: `Defaults to ${defaultImageGenerateModel}. Choose openai/gpt-image-2.5-sunburst for precision. Explicit older models remain supported.`,
     required: false,
     exampleValue: defaultImageGenerateModel,
   },
@@ -96,8 +96,8 @@ const imageGenerateCommandPresentation = {
       'transloadit image generate --prompt "A red bicycle in a studio" --output output.png',
     ],
     [
-      'Generate with OpenAI gpt-image-2',
-      'transloadit image generate --model openai/gpt-image-2 --width 1024 --height 1024 --prompt "A ceramic coffee mug on a white sweep" --output output.png',
+      'Generate with OpenAI Images 2.5 Sunburst',
+      'transloadit image generate --model openai/gpt-image-2.5-sunburst --width 1024 --height 1024 --prompt "A ceramic coffee mug on a white sweep" --output output.png',
     ],
     [
       'Guide generation with one input image',

package/src/cli/storageReceipts.ts

@@ -69,6 +69,9 @@ export function storageTypesPath(catalog: string): string {
 }
 
 function catalogTypes(catalog: StorageProjectCatalog, file?: string): string {
+  // Headerless files predate has_alpha. Ownership checks must reproduce their exact format;
+  // newly generated files always name their catalog and include the canonical field.
+  const alphaType = file === undefined ? '' : ' has_alpha?: boolean;'
   // Canonical LF keeps generated output deterministic; Git controls checkout-specific EOL conversion.
   const properties = Object.entries(catalog.images)
     .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
@@ -78,7 +81,7 @@ function catalogTypes(catalog: StorageProjectCatalog, file?: string): string {
       if (!dimensions.success) return []
       const { width, height, asset_id, version_id, workspace } = dimensions.data
       const name = JSON.stringify(path)
-      return `    ${name}: { path: ${name}; workspace: ${JSON.stringify(workspace)}; asset_id: ${JSON.stringify(asset_id)}; version_id: ${JSON.stringify(version_id)}; width: ${width}; height: ${height}; thumbhash?: string; hasAlpha?: boolean }`
+      return `    ${name}: { path: ${name}; workspace: ${JSON.stringify(workspace)}; asset_id: ${JSON.stringify(asset_id)}; version_id: ${JSON.stringify(version_id)}; width: ${width}; height: ${height}; thumbhash?: string;${alphaType} hasAlpha?: boolean }`
     })
   return [
     typesHeader,

package/src/storageImage.ts

@@ -1,4 +1,5 @@
 import type { AssemblyStatus } from './alphalib/types/assemblyStatus.ts'
+import type { InterpolatableRobotUploadHandleInstructionsInput } from './alphalib/types/robots/upload-handle.ts'
 import type { StoredAsset } from './alphalib/types/storageAsset.ts'
 import type { CreateAssemblyOptions, Transloadit } from './Transloadit.ts'
 
@@ -17,15 +18,16 @@ import InconsistentResponseError from './InconsistentResponseError.ts'
  * Width and height reflect EXIF auto-orientation, matching Storage preview delivery.
  */
 export interface StoredImageReceipt extends Readonly<StoredAsset> {
-  /** Optional metadata indicating that the original has an alpha channel. */
+  /** Legacy catalog spelling; new server receipts use has_alpha. */
   readonly hasAlpha?: boolean
   readonly height: number
   readonly md5hash: string
-  /** Optional base64 ThumbHash of the original pixels, for an inline blur placeholder. */
-  readonly thumbhash?: string
   readonly width: number
 }
 
+/** Shared SDK/CLI opt-in for server extraction; rendering remains a separate choice. */
+export const storageImagePlaceholderSchema = z.enum(['blur', 'empty'])
+
 /** One explicit destination, with the existing Assembly upload and polling controls. */
 export interface StoreImageOptions
   extends Pick<
@@ -36,6 +38,8 @@ export interface StoreImageOptions
   path: string
   /** Explicit opt-in replacement of an existing path; defaults to false. */
   overwrite?: boolean
+  /** Request a server ThumbHash. Successful extraction adds metadata usage of 20% of the file bytes. */
+  placeholder?: z.infer<typeof storageImagePlaceholderSchema>
   /** Observe verified metadata. Not awaited; sync and async observer errors cannot undo a write. */
   onReceipt?: (
     receipt: StoredImageReceipt,
@@ -111,6 +115,9 @@ export async function storeImage(
     timeout,
   } = options
   validateDestination(path)
+  const placeholder = storageImagePlaceholderSchema.optional().parse(options.placeholder, {
+    path: ['placeholder'],
+  })
   if (overwrite !== undefined && typeof overwrite !== 'boolean')
     throw new TypeError('overwrite must be a boolean')
   signal?.throwIfAborted()
@@ -130,6 +137,14 @@ export async function storeImage(
     onUploadProgress,
     params: {
       steps: {
+        ...(placeholder === 'blur'
+          ? {
+              ':original': {
+                robot: '/upload/handle',
+                output_meta: { thumbhash: true },
+              } satisfies InterpolatableRobotUploadHandleInstructionsInput,
+            }
+          : {}),
         stored: {
           robot: '/transloadit/store',
           use: ':original',