transloadit 4.13.0 → 4.14.0

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> {
-  /** Present as true only when the locally decoded 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,
@@ -94,35 +98,6 @@ function validateDestination(path: string): void {
   }
 }
 
-async function imagePlaceholderMetadata(
-  bytes: Buffer,
-): Promise<Pick<StoredImageReceipt, 'thumbhash' | 'hasAlpha'> | undefined> {
-  try {
-    const [{ default: sharp }, { rgbaToThumbHash }] = await Promise.all([
-      import('sharp'),
-      import('thumbhash'),
-    ])
-    const image = sharp(bytes, { limitInputPixels: 40_000_000 })
-    // Read original-channel metadata, not the alpha channel added for ThumbHash's RGBA input.
-    const { hasAlpha } = await image.metadata()
-    const { data, info } = await image
-      .autoOrient()
-      .resize(100, 100, { fit: 'inside', withoutEnlargement: true })
-      .ensureAlpha()
-      .raw()
-      .timeout({ seconds: 2 })
-      .toBuffer({ resolveWithObject: true })
-    return {
-      thumbhash: Buffer.from(rgbaToThumbHash(info.width, info.height, data)).toString('base64'),
-      ...(hasAlpha ? { hasAlpha: true } : {}),
-    }
-  } catch {
-    // A locally unsupported/oversized image can still be stored and decoded by the origin.
-    debug('transloadit:warn')('Omitted optional ThumbHash: local image decoding was unavailable')
-    return undefined
-  }
-}
-
 /** Stores one original without overwriting; receipt validation occurs after the Storage write. */
 export async function storeImage(
   client: Transloadit,
@@ -140,28 +115,21 @@ 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()
   const checksum = createHash('md5')
-  // Reuse the checksum read, bounded independently of file size; uploads still stream from disk.
-  let thumbnailChunks: Buffer[] | undefined = []
   let size = 0
   for await (const chunk of createReadStream(filePath, { signal })) {
     checksum.update(chunk)
     size += chunk.length
-    if (size > 32 * 1024 * 1024) thumbnailChunks = undefined
-    else thumbnailChunks?.push(chunk)
   }
   if (size === 0) throw new Error('Cannot store an empty image')
   const md5hash = checksum.digest('hex')
   signal?.throwIfAborted()
-  const placeholder =
-    thumbnailChunks === undefined
-      ? undefined
-      : await imagePlaceholderMetadata(Buffer.concat(thumbnailChunks))
-  thumbnailChunks = undefined
-  signal?.throwIfAborted()
   const assembly = await client.createAssembly({
     chunkSize,
     files: { image: filePath },
@@ -169,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',
@@ -184,23 +160,18 @@ export async function storeImage(
   const input = { path, size, md5hash }
   // API2 can watermark uploads before Robots run; this exact write's result describes stored bytes.
   const receipt = validateReceipt(assembly, input, true)
-  // A watermark or other origin-side rewrite makes the local pixels the wrong placeholder.
-  const withPlaceholder =
-    placeholder === undefined || receipt.md5hash !== md5hash || receipt.size !== size
-      ? receipt
-      : { ...receipt, ...placeholder }
   const observerFailed = (): void => {
     debug('transloadit:warn')('Ignored onReceipt observer failure after a completed Storage write')
   }
   try {
     // Neither a stalled observer nor its rejection may hide a successfully stored receipt.
-    void Promise.resolve(onReceipt?.({ ...withPlaceholder }, input, assembly.assembly_id)).catch(
+    void Promise.resolve(onReceipt?.({ ...receipt }, input, assembly.assembly_id)).catch(
       observerFailed,
     )
   } catch {
     observerFailed()
   }
-  return withPlaceholder
+  return receipt
 }
 
 /** Fetches authoritative Assembly status and applies the same validation as a local image store. */