transloadit 6.8.0 → 6.9.1

package/dist/storageImage.js

@@ -1,152 +1,32 @@
-import { createHash } from 'node:crypto';
-import { createReadStream } from 'node:fs';
-import debug from 'debug';
 import { z } from 'zod';
-import { ApiError } from "./ApiError.js";
 import { storedAssetSchema } from "./alphalib/types/storageAsset.js";
 import InconsistentResponseError from "./InconsistentResponseError.js";
-/** Shared SDK/CLI opt-in for server extraction; rendering remains a separate choice. */
-export const storageImagePlaceholderSchema = z.enum(['blur', 'empty']);
-const positiveIntegerSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
-const receiptRequestSchema = z.object({
-    assemblyId: z.string().regex(/^[A-Za-z0-9_-]+$/),
-    expected: z.object({
-        path: z.string(),
-        size: positiveIntegerSchema,
-        md5hash: z.string().regex(/^[a-f0-9]{32}$/),
-    }),
+import { getOriginalReceipt, storeOriginal } from "./storageAsset.js";
+export { storageImagePlaceholderSchema } from "./storageAsset.js";
+const imageReceiptSchema = storedAssetSchema.extend({
+    md5hash: storedAssetSchema.shape.md5hash.unwrap(),
+    height: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    width: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
 });
-const completedImageSchema = z.object({
-    ok: z.literal('ASSEMBLY_COMPLETED'),
-    results: z.object({
-        ':original': z.tuple([
-            storedAssetSchema.extend({
-                md5hash: storedAssetSchema.shape.md5hash.unwrap(),
-                height: positiveIntegerSchema,
-                width: positiveIntegerSchema,
-                size: positiveIntegerSchema,
-            }),
-        ]),
-    }),
-});
-function validateDestination(path) {
-    if (typeof path !== 'string' ||
-        path.trim() !== path ||
-        Buffer.byteLength(path) > 1024 ||
-        path.normalize('NFC') !== path ||
-        /[\p{Cc}\p{Cs}\\|]/u.test(path) ||
-        path.includes('${') ||
-        path.split('/').some((segment) => segment.trim() === '' || segment === '.' || segment === '..')) {
-        throw new TypeError('Storage path must be a complete relative filename without interpolation');
+function requireImage(receipt) {
+    const image = imageReceiptSchema.safeParse(receipt);
+    if (!image.success) {
+        throw new InconsistentResponseError('The Assembly did not return a matching Storage image receipt', {
+            cause: { receipt },
+        });
     }
+    return image.data;
 }
-/** Stores one original without overwriting; receipt validation occurs after the Storage write. */
+/** Retains the image API's transformed-byte semantics; use storeAsset for exact originals. */
 export async function storeImage(client, filePath, options) {
-    const { path, chunkSize, onAssemblyProgress, onUploadProgress, onReceipt, overwrite, signal, 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');
-    let size = 0;
-    for await (const chunk of createReadStream(filePath, { signal })) {
-        checksum.update(chunk);
-        size += chunk.length;
-    }
-    if (size === 0)
-        throw new Error('Cannot store an empty image');
-    const md5hash = checksum.digest('hex');
-    signal?.throwIfAborted();
-    const assembly = await client.createAssembly({
-        chunkSize,
-        files: { image: filePath },
-        onAssemblyProgress,
-        onUploadProgress,
-        params: {
-            steps: {
-                ...(placeholder === 'blur'
-                    ? {
-                        ':original': {
-                            robot: '/upload/handle',
-                            output_meta: { thumbhash: true },
-                        },
-                    }
-                    : {}),
-                stored: {
-                    robot: '/transloadit/store',
-                    use: ':original',
-                    path,
-                    conflict_strategy: overwrite === true ? 'overwrite' : 'error',
-                },
-            },
-        },
-        signal,
-        timeout,
-        waitForCompletion: true,
-    });
-    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);
-    const observerFailed = () => {
-        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?.({ ...receipt }, input, assembly.assembly_id)).catch(observerFailed);
-    }
-    catch {
-        observerFailed();
-    }
-    return receipt;
+    const receipt = await storeOriginal(client, filePath, {
+        ...options,
+        onReceipt: (asset, input, assemblyId) => options.onReceipt?.(requireImage(asset), input, assemblyId),
+    }, true);
+    return requireImage(receipt);
 }
-/** Fetches authoritative Assembly status and applies the same validation as a local image store. */
+/** Recovers one image receipt with the same strict byte checks as generic receipt recovery. */
 export async function getStoredImageReceipt(client, options) {
-    const { assemblyId, expected } = receiptRequestSchema.parse(options);
-    validateDestination(expected.path);
-    const assembly = await client.getAssembly(assemblyId);
-    if (assembly.assembly_id !== assemblyId) {
-        throw new InconsistentResponseError('The response did not match the requested Assembly', {
-            cause: { assemblyId },
-        });
-    }
-    return validateReceipt(assembly, expected);
-}
-function validateReceipt(assembly, expected, acceptTransformed = false) {
-    const { path, size, md5hash } = expected;
-    if (typeof assembly.error === 'string')
-        throw new ApiError({ body: assembly });
-    if (assembly.ok === 'ASSEMBLY_CANCELED') {
-        throw new InconsistentResponseError('The Storage Assembly ended with ASSEMBLY_CANCELED', {
-            cause: { assemblyId: assembly.assembly_id },
-        });
-    }
-    if (assembly.ok === 'ASSEMBLY_UPLOADING' ||
-        assembly.ok === 'ASSEMBLY_EXECUTING' ||
-        assembly.ok === 'ASSEMBLY_REPLAYING') {
-        throw new InconsistentResponseError(`The Storage Assembly is not complete (${assembly.ok})`, {
-            cause: { assemblyId: assembly.assembly_id },
-        });
-    }
-    const parsed = completedImageSchema.safeParse(assembly);
-    const result = parsed.success ? parsed.data.results[':original'][0] : undefined;
-    const originals = assembly.results?.[':original'];
-    const receiptCheck = {
-        originalCount: Array.isArray(originals) ? originals.length : 0,
-        metadataValid: parsed.success,
-        pathMatches: result === undefined ? undefined : result.path === path,
-        sizeMatches: result === undefined ? undefined : result.size === size,
-        md5Matches: result === undefined ? undefined : result.md5hash === md5hash,
-    };
-    if (result === undefined ||
-        result.path !== path ||
-        (!acceptTransformed && (!receiptCheck.sizeMatches || !receiptCheck.md5Matches))) {
-        throw new InconsistentResponseError('The Assembly did not return a matching Storage image receipt', {
-            cause: { assemblyId: assembly.assembly_id, receiptCheck },
-        });
-    }
-    return result;
+    return requireImage(await getOriginalReceipt(client, options, true));
 }
 //# sourceMappingURL=storageImage.js.map

package/dist/storageImage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storageImage.js","sourceRoot":"","sources":["../src/storageImage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storageImage.js","sourceRoot":"","sources":["../src/storageImage.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AACpE,OAAO,yBAAyB,MAAM,gCAAgC,CAAA;AACtE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAErE,OAAO,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAA;AAoBjE,MAAM,kBAAkB,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAClD,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC;IAChE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC;CAChE,CAAC,CAAA;AAEF,SAAS,YAAY,CAAC,OAA2B;IAC/C,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,IAAI,yBAAyB,CACjC,8DAA8D,EAC9D;YACE,KAAK,EAAE,EAAE,OAAO,EAAE;SACnB,CACF,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAA;AACnB,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAmB,EACnB,QAAgB,EAChB,OAA0B;IAE1B,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,MAAM,EACN,QAAQ,EACR;QACE,GAAG,OAAO;QACV,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CACtC,OAAO,CAAC,SAAS,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC;KAC9D,EACD,IAAI,CACL,CAAA;IACD,OAAO,YAAY,CAAC,OAAO,CAAC,CAAA;AAC9B,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAmB,EACnB,OAAqC;IAErC,OAAO,YAAY,CAAC,MAAM,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA;AACtE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transloadit",
-  "version": "6.8.0",
+  "version": "6.9.1",
   "description": "Node.js SDK and `transloadit` CLI for Transloadit",
   "homepage": "https://github.com/transloadit/node-sdk/tree/main/packages/node",
   "bugs": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@transloadit/sev-logger": "^0.1.9",
-    "@transloadit/utils": "^4.10.0",
+    "@transloadit/utils": "^4.11.0",
     "cacheable-lookup": "^7.0.0",
     "clipanion": "^4.0.0-rc.4",
     "debug": "^4.4.3",

package/src/Transloadit.ts

@@ -54,6 +54,11 @@ import type {
   LintAssemblyInstructionsInput,
   LintAssemblyInstructionsResult,
 } from './lintAssemblyInstructions.ts'
+import type {
+  GetStoredAssetReceiptOptions,
+  StoreAssetOptions,
+  StoredAssetReceipt,
+} from './storageAsset.ts'
 import type {
   GetStoredImageReceiptOptions,
   StoredImageReceipt,
@@ -108,6 +113,7 @@ import InconsistentResponseError from './InconsistentResponseError.ts'
 import { lintAssemblyInstructions as lintAssemblyInstructionsInternal } from './lintAssemblyInstructions.ts'
 import PaginationStream from './PaginationStream.ts'
 import PollingTimeoutError from './PollingTimeoutError.ts'
+import { getStoredAssetReceipt, storeAsset } from './storageAsset.ts'
 import { getStoredImageReceipt, storeImage } from './storageImage.ts'
 import {
   normalizeStoragePublicPrefix,
@@ -151,6 +157,12 @@ export type {
   RobotListResult,
   RobotParamHelp,
 } from './robots.ts'
+export type {
+  GetStoredAssetReceiptOptions,
+  StoreAssetOptions,
+  StoredAssetExpectation,
+  StoredAssetReceipt,
+} from './storageAsset.ts'
 export type {
   GetStoredImageReceiptOptions,
   StoredImageExpectation,
@@ -573,6 +585,16 @@ export class Transloadit {
     this._defaultTimeout = timeout
   }
 
+  /** Stores one byte-identical local original of any media type and returns its verified receipt. */
+  storeAsset(filePath: string, options: StoreAssetOptions): Promise<StoredAssetReceipt> {
+    return storeAsset(this, filePath, options)
+  }
+
+  /** Recovers a generic original receipt without uploading or accepting changed bytes. */
+  getStoredAssetReceipt(options: GetStoredAssetReceiptOptions): Promise<StoredAssetReceipt> {
+    return getStoredAssetReceipt(this, options)
+  }
+
   /** Stores one local original at an explicit path and returns its verified image metadata. */
   storeImage(filePath: string, options: StoreImageOptions): Promise<StoredImageReceipt> {
     return storeImage(this, filePath, options)

package/src/bearerToken.ts

@@ -24,6 +24,8 @@ export type MintBearerTokenOptions = {
    */
   scope?: string[] | string
   timeoutMs?: number
+  /** Optional presentation of API refusals; omitted for the SDK's existing error strings. */
+  formatError?: (body: unknown, message: string) => string
 }
 
 export type MintBearerTokenResult =
@@ -208,17 +210,13 @@ export async function mintBearerTokenWithCredentials(
   }
 
   const parsedError = tokenErrorSchema.safeParse(parsedJson)
-  if (parsedError.success) {
-    return {
-      ok: false,
-      error: parsedError.data.message
-        ? `${parsedError.data.error}: ${parsedError.data.message}`
-        : parsedError.data.error,
-    }
-  }
-
+  const error = parsedError.success
+    ? parsedError.data.message
+      ? `${parsedError.data.error}: ${parsedError.data.message}`
+      : parsedError.data.error
+    : `Token request failed (${res.status}): ${trimmed || res.statusText}`
   return {
     ok: false,
-    error: `Token request failed (${res.status}): ${trimmed || res.statusText}`,
+    error: options.formatError?.(parsedJson, error) ?? error,
   }
 }

package/src/cli/commands/assemblies.ts

@@ -308,7 +308,7 @@ export async function lint(
       })
     }
   } catch (error) {
-    output.error(ensureError(error).message)
+    output.error(formatAPIError(error))
     return 1
   }
 
@@ -2098,7 +2098,10 @@ async function createWithLocalInputs(
         })
       } catch (err) {
         const error = ensureError(err)
-        const message = error instanceof RequestError ? formatAPIError(error) : error.message
+        const message =
+          error instanceof RequestError
+            ? formatAPIError(error)
+            : formatAPIError(error, error.message)
         throw new Error(`${message} (${assemblyReference})`, { cause: error })
       }
 
@@ -2130,13 +2133,13 @@ async function createWithLocalInputs(
         )
       }
 
-      // Malformed error fields still signal failure, but only sanitized values enter the message.
+      // Retain the response so final formatting can show its reason after bounding a long message.
       if (assembly.error || (assembly.ok && assembly.ok !== 'ASSEMBLY_COMPLETED')) {
         const details =
           [summary.error ?? summary.ok, summary.message].filter(Boolean).join(': ') ||
           'Unknown Assembly error'
         const msg = `Assembly failed: ${details} (${assemblyReference})`
-        throw new Error(msg)
+        throw new Error(msg, { cause: assembly })
       }
 
       return { assembly, assemblyId }

package/src/cli/commands/auth.ts

@@ -18,6 +18,7 @@ import { Transloadit } from '../../Transloadit.ts'
 import {
   buildMissingCredentialsMessage,
   cliSignatureAlgorithmSchema,
+  formatAPIError,
   readCliInput,
   requireCliCredentials,
   resolveCliConfig,
@@ -455,6 +456,7 @@ export class TokenCommand extends UnauthenticatedCommand {
       endpoint: this.endpoint ?? resolved.config.credentialsEndpoint,
       aud: this.aud,
       scope: this.scope,
+      formatError: formatAPIError,
     })
 
     if (result.ok) {

package/src/cli/commands/image.ts

@@ -5,7 +5,7 @@ import { validateStoragePathPrefix } from '@transloadit/utils'
 import { Command, Option } from 'clipanion'
 import { z } from 'zod'
 
-import { noticeCliCredentialSource, resolveCliConfig } from '../helpers.ts'
+import { formatAPIError, noticeCliCredentialSource, resolveCliConfig } from '../helpers.ts'
 import { resolveStorageWorkspace } from '../storageCatalog.ts'
 import { storagePublicError } from '../storagePublic.ts'
 import {
@@ -17,7 +17,7 @@ import {
   updateStorageReceipts,
 } from '../storageReceipts.ts'
 import { nextAppRoot, storageImageEnvBlock, storageImagePage } from '../storageSnippets.ts'
-import { ensureError, isErrnoException } from '../types.ts'
+import { isErrnoException } from '../types.ts'
 import { UnauthenticatedCommand } from './BaseCommand.ts'
 
 /** Scaffolds the Node-runtime Next.js integration without overwriting code or env files. */
@@ -274,7 +274,7 @@ export class ImageInitCommand extends UnauthenticatedCommand {
         })
       }
       this.output.error(
-        `${ensureError(error).message}${published === undefined ? '' : ` The server prefix ${published} remains public; use storage unpublish deliberately if needed.`}`,
+        `${formatAPIError(error)}${published === undefined ? '' : ` The server prefix ${published} remains public; use storage unpublish deliberately if needed.`}`,
       )
       return 1
     }

package/src/cli/commands/login.ts

@@ -8,17 +8,19 @@ import { Command, Option } from 'clipanion'
 import { parse } from 'dotenv'
 import { z } from 'zod'
 
+import { tryCatch } from '../../alphalib/tryCatch.ts'
 import { Transloadit } from '../../Transloadit.ts'
 import { deviceLogin } from '../deviceLogin.ts'
 import {
   cliSignatureAlgorithmSchema,
+  formatAPIError,
   getConfiguredCredentialsFilePath,
   parseCliLoginSnapshot,
   readCliInput,
   resolveCliConfig,
 } from '../helpers.ts'
 import { quoteCredential } from '../secretInput.ts'
-import { ensureError, isErrnoException } from '../types.ts'
+import { isErrnoException } from '../types.ts'
 import { UnauthenticatedCommand } from './BaseCommand.ts'
 
 const credentialSchema = z
@@ -185,17 +187,14 @@ export class AuthLoginCommand extends UnauthenticatedCommand {
       }
       // A signed read checks dam:write access and catalog readiness without publishing anything.
       // It does not prove that the worker's object store can accept a later upload.
-      const storagePolicyAccess = await new Transloadit({
+      const storageClient = new Transloadit({
         ...credentials,
         endpoint: origin,
         maxRetries: 0,
         timeout: 10_000,
       })
-        .listPublicStoragePrefixes()
-        .then(
-          () => true,
-          () => false,
-        )
+      const [storagePolicyError] = await tryCatch(storageClient.listPublicStoragePrefixes())
+      const storagePolicyAccess = storagePolicyError === null
       if (!storagePolicyAccess) {
         const workspace =
           credentials.workspace !== undefined &&
@@ -203,7 +202,10 @@ export class AuthLoginCommand extends UnauthenticatedCommand {
             ? credentials.workspace
             : '<workspace>'
         this.output.warn(
-          `Login saved, but Storage policy access could not be verified. Before uploading, check Storage availability and the Auth Key dam:write scope at https://transloadit.com/c/${workspace}/template-credentials/. A temporary network failure can also prevent this check; retry with transloadit storage publications.`,
+          formatAPIError(
+            storagePolicyError,
+            `Login saved, but Storage policy access could not be verified. Before uploading, check Storage availability and the Auth Key dam:write scope at https://transloadit.com/c/${workspace}/template-credentials/. A temporary network failure can also prevent this check; retry with transloadit storage publications.`,
+          ),
         )
       }
       const message =
@@ -231,7 +233,7 @@ export class AuthLoginCommand extends UnauthenticatedCommand {
                 : `Review it in Console → Credentials: https://transloadit.com/c/${loginWorkspace ?? '<workspace>'}/template-credentials/; revoke it there if no longer needed.`,
               'Be careful: auth logout would use the saved login, not this unsaved one.',
             ].join('\n')
-          : ensureError(error).message,
+          : formatAPIError(error),
       )
       return 1
     } finally {
@@ -365,7 +367,7 @@ export class AuthLogoutCommand extends UnauthenticatedCommand {
       this.output.error(
         isErrnoException(error) && error.code === 'ENOENT'
           ? 'Not logged in; no saved credentials file.'
-          : ensureError(error).message,
+          : formatAPIError(error),
       )
       return 1
     }

package/src/cli/commands/notifications.ts

@@ -4,7 +4,7 @@ import type { IOutputCtl } from '../OutputCtl.ts'
 import { Command, Option } from 'clipanion'
 
 import { tryCatch } from '../../alphalib/tryCatch.ts'
-import { ensureError } from '../types.ts'
+import { formatAPIError } from '../helpers.ts'
 import { AuthenticatedCommand } from './BaseCommand.ts'
 
 // --- Types and business logic ---
@@ -22,7 +22,7 @@ async function replay(
   const promises = assemblies.map((id) => client.replayAssemblyNotification(id, { notify_url }))
   const [err] = await tryCatch(Promise.all(promises))
   if (err) {
-    output.error(ensureError(err).message)
+    output.error(formatAPIError(err))
   }
 }