Storage images for Next.js: public CDN delivery, private authorization and CLI onboarding

.changeset/public-image-candidates.md

@@ -0,0 +1,9 @@
+---
+"@transloadit/utils": minor
+---
+
+Add `getSmartCdnImageCandidates` next to the signed candidate builder on the Node entry point.
+Share candidate validation and URL encoding while omitting signatures and expiry for genuinely
+public delivery. Callers can use receipt-derived version tags for stable, immutable cache keys.
+Include a proportional (rounded-up) fit height, or the backend limit without source metadata,
+so a Template's default height does not silently invalidate the width descriptors.

.changeset/storage-image-prefixes.md

@@ -0,0 +1,9 @@
+---
+"@transloadit/utils": minor
+"@transloadit/node": patch
+"transloadit": patch
+---
+
+Share Storage path and directory-prefix validation between image integrations and CLI scaffolds.
+Keep generated image recipes scoped, preserve relative imports for hidden receipt catalogs, and
+sign Storage listing requests against the endpoint belonging to the selected key credentials.

.changeset/storage-image-receipts.md

@@ -0,0 +1,78 @@
+---
+"@transloadit/node": minor
+"transloadit": minor
+"@transloadit/mcp-server": patch
+---
+
+Release gate: publish this minor release only after transloadit/api2#9057 and
+transloadit/content#5973 are deployed. Device login, public delivery and safe CLI-key revocation
+depend on that coordinated backend/Console rollout. The image package remains private dogfood.
+At publication, switch preview-branch documentation links to their then-merged main locations.
+Require Node 20.10.0+ for JSON import attributes and composed AbortSignal cancellation. Logout
+only forgets imported and legacy application keys unless revocation is explicitly requested
+with `--revoke`.
+
+Add `client.storeImage(filePath, { path })` for one original Storage image without overwriting.
+Stream the input checksum and verify the completed receipt's path, asset ID, stored bytes and
+EXIF-oriented display dimensions. Community-plan transformations may change the stored size/MD5;
+return authoritative result metadata and expose the input comparison through `onReceipt`.
+The CLI warns about changed bytes, saves the receipt and adds bounded debug diagnostics.
+Return typed metadata suitable for saving and rendering without another lookup. Preserve Assembly
+upload progress, cancellation and errors; receipt validation after a write is not a rollback.
+
+Add `transloadit storage store <file> <path>` using the CLI's existing
+Assembly credentials. Atomically append keyed receipts, preserve previous data on failures and
+reject concurrent writers, then print a ready-to-render StorageImage snippet.
+Add `storage store --hashed` for content-addressed filenames: eight MD5 hex digits before the
+extension, with catalog keys, generated types and JSX following the stored path. Retain the local
+filename as `source`; reuse matching full-checksum/size receipts without uploading. Never overwrite
+a hash conflict. Keep production-unavailable S3 recovery commands in the image reference only.
+When receipt validation fails after writing, print the destination and Assembly ID for recovery.
+Point to list/sync, not overwrite or another upload. Report pending browser approval every minute.
+Document npm-first onboarding, browser signup and free-plan watermark behavior.
+Keep receipts-file filesystem errors distinct from JSON validation failures, with the file path.
+Retain a completed temporary catalog on local replacement failures, print the verified receipt,
+and preserve an existing catalog's permissions.
+
+Add `getStoredImageReceipt({ assemblyId, expected })` to recover the same verified metadata after
+a trusted upload notification or a local file error. Add explicit `store --overwrite` and
+read-scoped `storage ls <prefix>`; overwriting is never implicit.
+
+Add `storage receipts sync <prefix> --receipts images.json` to recover rendering metadata from
+signed, paginated List + HEAD reads without an Assembly or original download. Rebuild
+path/width/height with an optional compatible MD5 ETag, without inventing an asset ID. Share
+atomic receipt-file writes and credential-bound endpoint resolution with the existing commands;
+preserve unmatched records and the entire previous file on metadata, listing or write failures.
+
+Add browser device authorization for `auth login`, with bounded polling, cancellation and
+owner-only credential persistence. Keep `--stdin` for an existing Auth Key, verified by a signed read.
+Keep newly entered credentials independent from project dotenv endpoint settings; save an explicit
+trusted endpoint with the key. Add `image init [--public | --private]`, with
+opt-in private `.env.local` scaffolding via `--write-env`. Never overwrite existing application files.
+Default store/sync catalogs to `transloadit.images.json`. Init writes an empty catalog and a runnable example
+for `app` or `src/app`, preserving existing files. Store prints only the saved path and component
+usage; its snippet-only public/private flags and init's dead next flag are removed. Keep upload
+asset IDs and sizes on sync only when the HEAD MD5 still matches the stored receipt.
+
+Consolidate the unpublished Next factories into `createStorageImages`; select `public`, `authorize`,
+or `delivery: 'direct'` explicitly. The authorize overload retains its typed redirect handler.
+Require Next 16.3.3 or newer in the peer range.
+
+Reuse the login workspace and combined Auth Key for optional env scaffolding without extra prompts.
+Add signed public-prefix declaration, revocation and listing methods with `storage publish`,
+`storage unpublish` and `storage publications`. Public image init declares server policy before writing
+files and explains that already cached public bytes cannot be recalled.
+
+Preserve the device key's signing algorithm in CLI credentials and subsequent API requests.
+Add `signatureAlgorithm` to SDK client options while retaining the legacy SHA-384 default and
+explicit per-call overrides. Init's env setup uses the saved key/workspace/endpoint together,
+independently of stale project or shell credentials. Public/private Template overrides are separate.
+
+Public init stores workspace and published prefixes in the committed catalog, with no app env file.
+Require public/private intent and bind Storage operations to the selected key's verified workspace.
+Support multi-file store, auth status and server-side auth logout before removing credentials.
+Infer allowed directories from
+public policy even with an empty catalog, and accepts a missing trailing slash. Storage commands
+report the winning credential source without showing credentials; store prints constrained JSX
+bounded to the receipt width. Login makes a bounded read-only Storage policy preflight and gives
+Console advice when unavailable. Keep the image quickstart concise and ship its detailed reference.

.changeset/storage-image-seed.md

@@ -0,0 +1,13 @@
+---
+'@transloadit/node': patch
+'@transloadit/types': patch
+'@transloadit/zod': patch
+'transloadit': patch
+'@transloadit/mcp-server': patch
+---
+
+Include the Transloadit Storage import and store Robots in the offline catalog and generated
+instructions, and type the optional `asset_id` in Assembly results. Recognize Storage import/store
+error codes in response validation and terminal-status helpers, preserving API errors while polling.
+Sync the canonical `recursive` option for Storage folder imports into the offline linter and
+generated instructions without adding SDK-only schema fields.

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-      - name: Ensure yarn.lock matches dependency changes
+      - name: Ensure each package's lockfile matches dependency changes
         env:
           BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
           HEAD_SHA: ${{ github.sha }}
@@ -59,13 +59,11 @@ jobs:
             }
             return !file.startsWith('docs/fingerprint/')
           })
-          const lockfileChanged = diffNames.includes('yarn.lock')
-
           if (packageFiles.length === 0) {
             process.exit(0)
           }
 
-          const hasDependencyChanges = packageFiles.some((file) => {
+          const changedPackages = packageFiles.filter((file) => {
             let before = {}
             let after = {}
             try {
@@ -85,8 +83,15 @@ jobs:
             })
           })
 
-          if (hasDependencyChanges && !lockfileChanged) {
-            console.error('yarn.lock must be updated when dependency ranges change in package.json.')
+          // The packed Next app is a standalone npm consumer, outside the Yarn workspaces.
+          const missingLockfiles = new Set(changedPackages
+            .map((file) => file === 'scripts/fixtures/img-next/package.json'
+              ? 'scripts/fixtures/img-next/package-lock.json'
+              : 'yarn.lock')
+            .filter((lockfile) => !diffNames.includes(lockfile)))
+
+          if (missingLockfiles.size > 0) {
+            console.error(`${[...missingLockfiles].join(', ')} must be updated when dependency ranges change.`)
             process.exit(1)
           }
           NODE
@@ -161,6 +166,12 @@ jobs:
           node-version: 24
       - run: corepack yarn install --immutable
       - run: corepack yarn test:img:fixture
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: img-browser-evidence
+          path: test-results/img-next
+          if-no-files-found: ignore
 
   unit:
     name: Unit tests (Node ${{ matrix.node }})

.gitignore

@@ -8,6 +8,7 @@ sample.js
 npm-debug.log
 env.sh
 /coverage
+/test-results/
 packages/node/coverage
 
 .pnp.*

biome.json

@@ -147,6 +147,14 @@
     }
   },
   "overrides": [
+    {
+      "includes": ["scripts/fixtures/img-next/app/**"],
+      "linter": {
+        "rules": {
+          "correctness": { "useImportExtensions": "off" }
+        }
+      }
+    },
     {
       "includes": ["**/package.json"],
       "formatter": {