transloadit 4.14.0 → 5.0.1

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,51 +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(),
-  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()
-    .describe('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: z.boolean().optional().describe('Whether the image has an alpha channel, even if all its pixels are opaque. Present when ThumbHash extraction succeeds; absence means unknown.'),
-})
+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 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/storageResults.ts

@@ -0,0 +1,75 @@
+import type { StoredAsset } from './storageAsset.ts'
+
+import { z } from 'zod'
+
+import { storedAssetSchema } from './storageAsset.ts'
+
+// SDK-owned extraction is outside alphalib-sync's explicit node-sdk syncIncludes. Co-location
+// reuses canonical schemas and their Types/Zod generation without adding a runtime package.
+
+/** Server-owned Assembly identity and expected Workspace, never untrusted notification fields. */
+export const storedAssemblyResultsOptionsSchema = z.object({
+  assemblyId: z.string().regex(/^[A-Za-z0-9_-]+$/),
+  workspace: z.string().min(1),
+})
+
+export type GetStoredAssemblyResultsOptions = z.infer<typeof storedAssemblyResultsOptionsSchema>
+
+/** Canonical retained receipt and producing result provenance, for idempotent registration. */
+export interface StoredAssemblyResult {
+  assembly_id: string
+  step: string
+  result_id: string
+  original_id?: string | (string | null)[]
+  asset: StoredAsset
+}
+
+const resultSchema = storedAssetSchema.extend({
+  id: z.string().min(1),
+  original_id: z.union([z.string(), z.array(z.string().nullable())]).optional(),
+})
+const assemblySchema = z.object({
+  assembly_id: z.string(),
+  ok: z.string().nullable().optional(),
+  error: z.string().optional(),
+  results: z.record(z.array(z.record(z.unknown()))).optional(),
+})
+
+/**
+ * Pure extraction from a fetched/verified Assembly bound to an authorized app upload. Validates
+ * every retained result atomically; temporary outputs are ignored, partial receipts are rejected.
+ * This does not authenticate notifications or check application permissions.
+ */
+export function extractStoredAssemblyResults(
+  input: unknown,
+  options: GetStoredAssemblyResultsOptions,
+): StoredAssemblyResult[] {
+  const { assemblyId, workspace } = storedAssemblyResultsOptionsSchema.parse(options)
+  const assembly = assemblySchema.parse(input)
+  if (assembly.assembly_id !== assemblyId)
+    throw new Error('The response did not match the requested Assembly')
+  if (assembly.error !== undefined || assembly.ok !== 'ASSEMBLY_COMPLETED')
+    throw new Error(`The Storage Assembly is not complete (${assembly.error ?? assembly.ok})`)
+  if (assembly.results === undefined)
+    throw new Error('The completed Assembly did not contain results')
+  const results: StoredAssemblyResult[] = []
+  for (const [step, files] of Object.entries(assembly.results)) {
+    for (const file of files) {
+      if (
+        file.asset_id === undefined &&
+        file.version_id === undefined &&
+        file.workspace === undefined
+      )
+        continue
+      const parsed = resultSchema.safeParse(file)
+      if (!parsed.success || parsed.data.workspace !== workspace) {
+        throw new Error('The Assembly returned an invalid or cross-Workspace Storage result', {
+          cause: { assemblyId, step },
+        })
+      }
+      const { id, original_id, ...asset } = parsed.data
+      results.push({ assembly_id: assemblyId, step, result_id: id, original_id, asset })
+    }
+  }
+  return results
+}

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/storageResults.ts

@@ -1,11 +1,17 @@
 import type { StoredAsset } from './alphalib/types/storageAsset.ts'
+import type {
+  GetStoredAssemblyResultsOptions,
+  StoredAssemblyResult,
+} from './alphalib/types/storageResults.ts'
 import type { Transloadit } from './Transloadit.ts'
 
-import { z } from 'zod'
-
 import { ApiError } from './ApiError.ts'
 import { robotFileServeInstructionsSchema } from './alphalib/types/robots/file-serve.ts'
 import { storedAssetSchema } from './alphalib/types/storageAsset.ts'
+import {
+  extractStoredAssemblyResults,
+  storedAssemblyResultsOptionsSchema,
+} from './alphalib/types/storageResults.ts'
 import InconsistentResponseError from './InconsistentResponseError.ts'
 
 /** Original-byte delivery, not a preview or transcode; authorize the application's asset first. */
@@ -46,29 +52,10 @@ export function getStoredAssetUrl(
   })
 }
 
-/** Server-owned Assembly identity and expected Workspace, not values from an untrusted notification. */
-export interface GetStoredAssemblyResultsOptions {
-  assemblyId: string
-  workspace: string
-}
-
-/** A canonical stored asset with the producing result's provenance; one input can have many outputs. */
-export interface StoredAssemblyResult {
-  assembly_id: string
-  step: string
-  result_id: string
-  original_id?: string | (string | null)[]
-  asset: StoredAsset
-}
-
-const requestSchema = z.object({
-  assemblyId: z.string().regex(/^[A-Za-z0-9_-]+$/),
-  workspace: z.string().min(1),
-})
-const resultSchema = storedAssetSchema.extend({
-  id: z.string().min(1),
-  original_id: z.union([z.string(), z.array(z.string().nullable())]).optional(),
-})
+export type {
+  GetStoredAssemblyResultsOptions,
+  StoredAssemblyResult,
+} from './alphalib/types/storageResults.ts'
 
 /**
  * Fetches a completed Assembly and verifies all retained results, including non-image media.
@@ -79,41 +66,17 @@ export async function getStoredAssemblyResults(
   client: Transloadit,
   options: GetStoredAssemblyResultsOptions,
 ): Promise<StoredAssemblyResult[]> {
-  const { assemblyId, workspace } = requestSchema.parse(options)
+  const { assemblyId, workspace } = storedAssemblyResultsOptionsSchema.parse(options)
   const assembly = await client.getAssembly(assemblyId)
   if (assembly.assembly_id !== assemblyId) {
     throw new InconsistentResponseError('The response did not match the requested Assembly')
   }
   if (typeof assembly.error === 'string') throw new ApiError({ body: assembly })
-  if (assembly.ok !== 'ASSEMBLY_COMPLETED') {
-    throw new InconsistentResponseError(`The Storage Assembly is not complete (${assembly.ok})`)
-  }
-  if (assembly.results === undefined) {
-    throw new InconsistentResponseError('The completed Assembly did not contain results')
-  }
-  const results: StoredAssemblyResult[] = []
-  for (const [step, files] of Object.entries(assembly.results)) {
-    for (const file of files) {
-      // Ordinary temporary/exported outputs are not Storage receipts. Partial Storage records
-      // must fail validation rather than disappearing from an otherwise successful batch.
-      if (
-        file.asset_id === undefined &&
-        file.version_id === undefined &&
-        file.workspace === undefined
-      )
-        continue
-      const parsed = resultSchema.safeParse(file)
-      if (!parsed.success || parsed.data.workspace !== workspace) {
-        throw new InconsistentResponseError(
-          'The Assembly returned an invalid or cross-Workspace Storage result',
-          {
-            cause: { assemblyId, step },
-          },
-        )
-      }
-      const { id, original_id, ...asset } = parsed.data
-      results.push({ assembly_id: assemblyId, step, result_id: id, original_id, asset })
-    }
+  try {
+    return extractStoredAssemblyResults(assembly, { assemblyId, workspace })
+  } catch (error) {
+    // Keep the Node SDK error contract while sharing strict extraction with Web runtimes.
+    if (!(error instanceof Error)) throw new Error('Invalid Assembly response', { cause: error })
+    throw new InconsistentResponseError(error.message, { cause: error.cause ?? error })
   }
-  return results
 }