transloadit 4.7.4 → 4.8.0

package/src/alphalib/types/robots/file-serve.ts

@@ -4,10 +4,26 @@ import type { RobotMetaInput } from './_instructions-primitives.ts'
 import { interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 4,
   discount_factor: 0.25,
   discount_pct: 75,
+  example_code: {
+    steps: {
+      resized: {
+        robot: '/image/resize',
+        use: ':original',
+        width: 800,
+        height: 450,
+        resize_strategy: 'fit',
+      },
+      served: {
+        robot: '/file/serve',
+        use: 'resized',
+        cache_duration: 86400,
+      },
+    },
+  },
+  example_code_description: 'Serve transformed files with explicit browser and CDN cache duration:',
   minimum_charge: 0,
   output_factor: 1,
   purpose_sentence: 'serves files to web browsers',
@@ -35,7 +51,7 @@ export const robotFileServeInstructionsSchema = robotBase
   .merge(robotUse)
   .extend({
     robot: z.literal('/file/serve').describe(`
-When you want Transloadit to tranform files on the fly, you can use this <dfn>Robot</dfn> to determine which <dfn>Step</dfn> of a <dfn>Template</dfn> should be served to the end-user (via a CDN), as well as set extra information on the served files, such as headers. This way you can for instance suggest the CDN for how long to keep cached copies of the result around. By default, as you can see in the \`headers\` parameter, we instruct browsers to cache the result for 72h (\`259200\` seconds) and CDNs to cache the content for 24h (\`86400\` seconds). These values should be adjusted to suit your use case.
+When you want Transloadit to tranform files on the fly, you can use this <dfn>Robot</dfn> to determine which <dfn>Step</dfn> of a <dfn>Template</dfn> should be served to the end-user (via a CDN), as well as set extra information on the served files, such as headers. This way you can for instance suggest the CDN for how long to keep cached copies of the result around. By default, we instruct browsers to cache the result for 72h (\`259200\` seconds) and CDNs to cache the content for 24h (\`86400\` seconds). Use the \`cache_duration\` parameter to customize both values at once.
 
 🤖/file/serve merely acts as the glue layer between our <dfn>Assembly</dfn> engine and serving files over HTTP. It let's you pick the proper result of a series of <dfn>Steps</dfn> via the \`use\` parameter and configure headers on the original content. That is where its responsibilies end, and 🤖/tlcdn/deliver, then takes over to globally distribute this original content across the globe, and make sure that is cached close to your end-users, when they make requests such as <https://my-app.tlcdn.com/resize-img/canoe.jpg?w=500>, another. 🤖/tlcdn/deliver is not a part of your <dfn>Assembly Instructions</dfn>, but it may appear on your invoices as bandwidth charges incur when distributing the cached copies. 🤖/file/serve only charges when the CDN does not have a cached copy and requests to regenerate the original content, which depending on your caching settings could be just once a month, or year, per file/transformation.
 
@@ -43,9 +59,9 @@ While theoretically possible, you could use [🤖/file/serve](/docs/robots/file-
 
 Also consider configuring caching headers and cache-control directives to control how content is cached and invalidated on the CDN edge servers, balancing between freshness and efficiency.
 
-## Smart CDN Security with Signature Authentication
+## Smart CDN security with signed URLs
 
-You can leverage [Signature Authentication](/docs/api/authentication/#smart-cdn) to avoid abuse of our encoding platform. Below is a quick Node.js example using our Node SDK, but there are [examples for other languages and SDKs](/docs/api/authentication/#example-code) as well.
+You can leverage [signed Smart CDN URLs](/docs/api/authentication/#smart-cdn) to avoid abuse of our encoding platform. Below is a quick Node.js example using our Node SDK, but there are [examples for other languages and SDKs](/docs/api/authentication/#example-code) as well.
 
 \`\`\`javascript
 // yarn add transloadit
@@ -71,28 +87,44 @@ console.log(url)
 
 This will generate a signed Smart CDN URL that includes authentication parameters, preventing unauthorized access to your transformation endpoints.
 
+For new integrations, use the modern \`sig\` + \`exp\` format. Legacy \`s\` signatures are deprecated. Also note that the expiration window is the practical cache window for signed results: shorter expirations tighten access control, while longer expirations improve cache reuse and lower encoding volume.
+
 ## More information
 
 - [Content Delivery](/services/content-delivery/)
 - [🤖/file/serve](/docs/robots/file-serve/) pricing
 - [🤖/tlcdn/deliver](/docs/robots/tlcdn-deliver/) pricing
 - [File Preview Feature](/blog/2024/06/file-preview-with-smart-cdn/) blog post
+`),
+    cache_duration: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(`
+An optional duration in seconds that the served file should be cached. When set, this value is used for both the \`max-age\` (browser cache) and \`s-maxage\` (shared/CDN cache) directives in the \`Cache-Control\` header, overriding the defaults. For example, setting \`cache_duration\` to \`43200\` would cache the file for 12 hours.
+
+This is useful for controlling data retention in CDNs. For instance, if your temporary files are deleted after 24 hours, you can set \`cache_duration\` to \`86400\` to ensure cached copies also expire within that window.
 `),
     headers: z
       .record(z.string())
       .default({
         'Access-Control-Allow-Headers':
-          'X-Requested-With, Content-Type, Cache-Control, Accept, Content-Length, Transloadit-Client, Authorization',
+          'X-Requested-With, Content-Type, Cache-Control, Accept, Content-Length, Transloadit-Client, Authorization, Range, If-Range',
         'Access-Control-Allow-Methods': 'POST, GET, PUT, DELETE, OPTIONS',
         'Access-Control-Allow-Origin': '*',
-        'Cache-Control': 'public, max-age=259200, s-max-age=86400',
+        'Access-Control-Expose-Headers':
+          'Transloadit-Assembly-URL, Content-Range, Content-Length, Accept-Ranges',
+        'Cache-Control': 'public, max-age=259200, s-maxage=86400',
         'Content-Type': '${file.mime}; charset=utf-8',
-        'Transfer-Encoding': 'chunked',
         'Transloadit-Assembly': '…',
         'Transloadit-RequestID': '…',
+        'Accept-Ranges': 'bytes',
       })
       .describe(`
 An object containing a list of headers to be set for a file as we serve it to a CDN/web browser, such as \`{ FileURL: "\${file.url_name}" }\` which will be merged over the defaults, and can include any available [Assembly Variable](/docs/topics/assembly-instructions/#assembly-variables).
+
+The \`Accept-Ranges: bytes\` header advertises that HTTP range requests are supported for seekable media playback. This relies on Transloadit's storage backends (S3, GCS, etc.) all honoring Range request headers. The CORS headers include \`Range\` and \`If-Range\` in \`Access-Control-Allow-Headers\` to permit cross-origin range requests, and expose \`Content-Range\`, \`Content-Length\`, and \`Accept-Ranges\` via \`Access-Control-Expose-Headers\` so browser JavaScript can read these values.
 `),
   })
   .strict()

package/src/alphalib/types/robots/file-verify.ts

@@ -4,7 +4,6 @@ import type { RobotMetaInput } from './_instructions-primitives.ts'
 import { interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 4,
   description:
     '/file/verify is a simple Robot that helps ensure that the files you upload are of the type you initially intended. This is especially useful when handling user-generated content, where you may not want to run certain Steps in your Template if the user hasn’t uploaded a file of the correct type. Another use case for /file/verify is when a user uploads a ZIP file, but we find that it has a few damaged files inside when we extract it. Perhaps you don’t want to error out, but only send the good files to a next processing step. With /file/verify, you can do exactly that (assuming the default of `error_on_decline`: `true`).',

package/src/alphalib/types/robots/file-virusscan.ts

@@ -4,7 +4,6 @@ import type { RobotMetaInput } from './_instructions-primitives.ts'
 import { interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: false,
   bytescount: 1,
   description:
     'While 100% security is a myth, having /file/virusscan as a gatekeeper bot helps reject millions of trojans, viruses, malware & other malicious threats before they reach your platform.',
@@ -32,16 +31,19 @@ export const meta: RobotMetaInput = {
   purpose_word: 'scan for viruses and reject malware',
   purpose_words: 'Scan files for viruses',
   service_slug: 'file-filtering',
-  slot_count: 38,
+  slot_count: 16,
   title: 'Scan files for viruses',
   typical_file_size_mb: 1.2,
   typical_file_type: 'file',
   name: 'FileVirusscanRobot',
   priceFactor: 1,
-  queueSlotCount: 38,
+  queueSlotCount: 16,
   minimumCharge: 1048576,
   lazyLoad: true,
-  installVersionFile: process.env.API2_CLAMD_INSTALL_VERSION_FILE || '',
+  installVersionFile:
+    typeof process !== 'undefined' && process.env.API2_CLAMD_INSTALL_VERSION_FILE
+      ? process.env.API2_CLAMD_INSTALL_VERSION_FILE
+      : '',
   isAllowedForUrlTransform: false,
   trackOutputFileSize: true,
   isInternal: false,

package/src/alphalib/types/robots/file-watermark.ts

@@ -6,6 +6,16 @@ import { interpolateRobot, robotBase, robotUse } from './_instructions-primitive
 // @ts-expect-error - FileWatermarkRobot is not ready yet @TODO please supply missing keys
 export const meta: RobotMetaInput = {
   name: 'FileWatermarkRobot',
+  example_code: {
+    steps: {
+      watermarked: {
+        robot: '/file/watermark',
+        use: ':original',
+        randomize: true,
+      },
+    },
+  },
+  example_code_description: 'Apply randomized watermarking to uploaded files:',
   priceFactor: 4,
   queueSlotCount: 20,
   isAllowedForUrlTransform: true,

package/src/alphalib/types/robots/ftp-import.ts

@@ -10,7 +10,6 @@ import {
 } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 10,
   discount_factor: 0.1,
   discount_pct: 90,

package/src/alphalib/types/robots/ftp-store.ts

@@ -4,7 +4,6 @@ import type { RobotMetaInput } from './_instructions-primitives.ts'
 import { ftpBase, interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 6,
   discount_factor: 0.15000150001500018,
   discount_pct: 84.99984999849998,

package/src/alphalib/types/robots/google-import.ts

@@ -13,7 +13,6 @@ import {
 } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 10,
   discount_factor: 0.1,
   discount_pct: 90,

package/src/alphalib/types/robots/google-store.ts

@@ -4,7 +4,6 @@ import type { RobotMetaInput } from './_instructions-primitives.ts'
 import { googleBase, interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 6,
   discount_factor: 0.15000150001500018,
   discount_pct: 84.99984999849998,

package/src/alphalib/types/robots/html-convert.ts

@@ -4,7 +4,6 @@ import type { RobotMetaInput } from './_instructions-primitives.ts'
 import { interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 1,
   discount_factor: 1,
   discount_pct: 0,

package/src/alphalib/types/robots/http-import.ts

@@ -9,7 +9,6 @@ import {
 } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 10,
   discount_factor: 0.1,
   discount_pct: 90,

package/src/alphalib/types/robots/image-bgremove.ts

@@ -4,7 +4,6 @@ import type { RobotMetaInput } from './_instructions-primitives.ts'
 import { interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   discount_factor: 1,
   bytescount: 1,
   discount_pct: 0,
@@ -48,7 +47,10 @@ export const robotImageBgremoveInstructionsSchema = robotBase
       .enum(['foreground', 'background'])
       .optional()
       .describe('Region to select and keep in the image. The other region is removed.'),
-    format: z.enum(['png', 'gif', 'webp']).optional().describe('Format of the generated image.'),
+    format: z
+      .enum(['png', 'gif', 'webp'])
+      .default('png')
+      .describe('Format of the generated image. Defaults to PNG when not provided.'),
     provider: z
       .enum(['transloadit', 'replicate', 'fal'])
       .optional()

package/src/alphalib/types/robots/image-copyrightdetect.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod'
+
+import type { RobotMetaInput } from './_instructions-primitives.ts'
+import { interpolateRobot, robotBase, robotUse } from './_instructions-primitives.ts'
+
+export const meta: RobotMetaInput = {
+  bytescount: 1,
+  discount_factor: 1,
+  discount_pct: 0,
+  example_code: {
+    steps: {
+      copyright_checked: {
+        robot: '/image/copyrightdetect',
+        use: ':original',
+        confidence_threshold: 80,
+        error_on_decline: true,
+        error_msg: 'This image appears to be a known stock photo. Please upload original content.',
+      },
+    },
+  },
+  example_code_description:
+    'Detect known stock photos and copyrighted works in uploaded images and reject flagged files:',
+  extended_description: `
+> [!Note]
+> This <dfn>Robot</dfn> detects **known stock photos, brand logos, and watermarked images** by performing reverse image lookups against web databases. It is best understood as "stock photo detection" — it tells you if an uploaded image matches a known copyrighted work in indexed databases (Getty Images, Shutterstock, Adobe Stock, etc.), not whether an image is copyrighted in the legal sense (since technically all photos are copyrighted by their creator).
+
+> [!Warning]
+> This <dfn>Robot</dfn> provides a **risk signal**, not a legal determination. Results should be interpreted as "potentially copyrighted" — never as definitive proof of infringement. Copyright law varies by jurisdiction and the system cannot know if a user holds a valid license. We recommend using this Robot as one input in a broader content moderation workflow.
+
+> [!Warning]
+> Transloadit aims to be deterministic, but this <dfn>Robot</dfn> uses third-party AI services. The providers will evolve their models over time, giving different responses for the same input images. Avoid relying on exact responses in your tests and application.
+
+> [!Tip]
+> If you want to keep only files below your confidence threshold (for example keep 20 out of 100), set \`format\` to \`"meta"\` and add a [🤖/file/filter](/docs/robots/file-filter/) Step after this one:
+>
+> ~~~json
+> {
+>   "steps": {
+>     "copyright_scan": {
+>       "robot": "/image/copyrightdetect",
+>       "use": ":original",
+>       "format": "meta",
+>       "confidence_threshold": 80,
+>       "error_on_decline": false
+>     },
+>     "keep_safe": {
+>       "robot": "/file/filter",
+>       "use": "copyright_scan",
+>       "declines": "\${file.meta.copyright?.flagged === true}"
+>     }
+>   }
+> }
+> ~~~
+>
+> In this setup, files with at least one match at or above your threshold are declined, and only the remaining files continue to later Steps.
+`,
+  minimum_charge: 1572864,
+  output_factor: 0.05,
+  override_lvl1: 'Artificial Intelligence',
+  purpose_sentence:
+    'detects known stock photos, brand logos, and watermarked images in uploaded files using reverse image search',
+  purpose_verb: 'detect',
+  purpose_word: 'detect stock photos and copyrighted works',
+  purpose_words: 'Detect known stock photos and copyrighted works in images',
+  service_slug: 'artificial-intelligence',
+  slot_count: 10,
+  title: 'Detect known stock photos and copyrighted works in images',
+  typical_file_size_mb: 0.8,
+  typical_file_type: 'image',
+  name: 'ImageCopyrightdetectRobot',
+  priceFactor: 1,
+  queueSlotCount: 10,
+  minimumChargeUsd: 0.0013,
+  isAllowedForUrlTransform: true,
+  trackOutputFileSize: true,
+  isInternal: false,
+  removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
+  stage: 'alpha',
+}
+
+export const robotImageCopyrightdetectInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/image/copyrightdetect').describe(`
+Detects known stock photos, brand logos, and watermarked images in uploaded files by performing reverse image lookups against web databases. This is best understood as "stock photo detection" — it identifies whether an uploaded image matches a known copyrighted work in indexed databases (Getty Images, Shutterstock, Adobe Stock, etc.).
+
+Returns a \`licenses[]\` array with match details including source collection, license type, confidence scores, and source URLs. Can optionally halt the <dfn>Assembly</dfn> when a known copyrighted work is detected, similar to how \`/file/virusscan\` handles malicious files.
+
+This <dfn>Robot</dfn> provides a **risk signal**, not a legal determination. A match means the image was found in a stock photo or rights-managed database — it does not mean the user lacks a valid license.
+`),
+    confidence_threshold: z
+      .number()
+      .min(0)
+      .max(100)
+      .default(80)
+      .describe(`
+Minimum confidence percentage (0\u2013100) for a match to be considered a copyright concern. Matches below this threshold are still returned in results but not flagged. Higher values reduce false positives but may miss some matches.
+`),
+    categories: z
+      .array(z.enum(['stock_photo', 'brand_logo', 'artwork', 'watermarked', 'all']))
+      .nonempty()
+      .default(['all'])
+      .describe(`
+Which categories of copyrighted content to detect.
+
+- \`"stock_photo"\` \u2014 Known stock photography (Shutterstock, Getty, Adobe Stock, etc.)
+- \`"brand_logo"\` \u2014 Registered brand logos and trademarks
+- \`"artwork"\` \u2014 Famous artworks and illustrations
+- \`"watermarked"\` \u2014 Images containing visible watermarks
+- \`"all"\` \u2014 All categories
+`),
+    error_on_decline: z
+      .boolean()
+      .default(false)
+      .describe(`
+If set to \`true\` and one or more files match a known stock photo or copyrighted work (above the \`confidence_threshold\`), the <dfn>Assembly</dfn> will be stopped and marked with an error. Works the same way as \`/file/virusscan\`'s \`error_on_decline\`.
+`),
+    error_msg: z
+      .string()
+      .default('One of your files matched a known stock photo or copyrighted work')
+      .describe(`
+The error message shown to your users (such as by Uppy) when a file is declined and \`error_on_decline\` is set to \`true\`.
+`),
+    format: z
+      .enum(['json', 'meta'])
+      .default('json')
+      .describe(`
+In what format to return the detection results.
+
+- \`"json"\` returns a JSON file with full match details including \`licenses[]\`, plus summary fields \`flagged\`, \`max_confidence\`, and \`confidence_threshold\`.
+- \`"meta"\` does not return a file, but stores the same data object (including \`licenses[]\`, \`flagged\`, \`max_confidence\`, and \`confidence_threshold\`) inside Transloadit's file object (under \`\${file.meta.copyright}\`) that's passed around between encoding <dfn>Steps</dfn>, so that you can use the values to filter on them, etc.
+`),
+  })
+  .strict()
+
+export const robotImageCopyrightdetectInstructionsWithHiddenFieldsSchema =
+  robotImageCopyrightdetectInstructionsSchema.extend({
+    result: z
+      .union([z.literal('debug'), robotImageCopyrightdetectInstructionsSchema.shape.result])
+      .optional(),
+  })
+
+export type RobotImageCopyrightdetectInstructions = z.infer<
+  typeof robotImageCopyrightdetectInstructionsSchema
+>
+export type RobotImageCopyrightdetectInstructionsWithHiddenFields = z.infer<
+  typeof robotImageCopyrightdetectInstructionsWithHiddenFieldsSchema
+>
+
+export const interpolatableRobotImageCopyrightdetectInstructionsSchema = interpolateRobot(
+  robotImageCopyrightdetectInstructionsSchema,
+)
+export type InterpolatableRobotImageCopyrightdetectInstructions =
+  InterpolatableRobotImageCopyrightdetectInstructionsInput
+
+export type InterpolatableRobotImageCopyrightdetectInstructionsInput = z.input<
+  typeof interpolatableRobotImageCopyrightdetectInstructionsSchema
+>
+
+export const interpolatableRobotImageCopyrightdetectInstructionsWithHiddenFieldsSchema =
+  interpolateRobot(robotImageCopyrightdetectInstructionsWithHiddenFieldsSchema)
+export type InterpolatableRobotImageCopyrightdetectInstructionsWithHiddenFields = z.infer<
+  typeof interpolatableRobotImageCopyrightdetectInstructionsWithHiddenFieldsSchema
+>
+export type InterpolatableRobotImageCopyrightdetectInstructionsWithHiddenFieldsInput = z.input<
+  typeof interpolatableRobotImageCopyrightdetectInstructionsWithHiddenFieldsSchema
+>

package/src/alphalib/types/robots/image-describe.ts

@@ -10,7 +10,6 @@ import {
 } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 1,
   discount_factor: 1,
   discount_pct: 0,

package/src/alphalib/types/robots/image-enhance.ts

@@ -0,0 +1,185 @@
+import { z } from 'zod'
+
+import type { RobotMetaInput } from './_instructions-primitives.ts'
+import {
+  imageQualitySchema,
+  interpolateRobot,
+  robotBase,
+  robotImagemagick,
+  robotUse,
+} from './_instructions-primitives.ts'
+
+export const meta: RobotMetaInput = {
+  bytescount: 1,
+  discount_factor: 1,
+  discount_pct: 0,
+  example_code: {
+    steps: {
+      enhanced_classic: {
+        robot: '/image/enhance',
+        use: ':original',
+        enhance: 'auto',
+        preset: 'vivid',
+      },
+      enhanced_ai: {
+        robot: '/image/enhance',
+        use: ':original',
+        engine: 'ai',
+        ai_preset: 'restore',
+      },
+    },
+  },
+  example_code_description: 'Enhance uploaded images with classic auto mode or AI restoration:',
+  minimum_charge: 0,
+  output_factor: 0.6,
+  override_lvl1: 'Image Manipulation',
+  purpose_sentence:
+    'automatically enhances images by adjusting levels, contrast, and sharpness, and optionally applies photo filter presets',
+  purpose_verb: 'enhance',
+  purpose_word: 'enhance',
+  purpose_words: 'Enhance images',
+  service_slug: 'image-manipulation',
+  slot_count: 15,
+  title: 'Enhance images',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'image',
+  name: 'ImageEnhanceRobot',
+  priceFactor: 1,
+  queueSlotCount: 15,
+  isAllowedForUrlTransform: true,
+  trackOutputFileSize: true,
+  isInternal: false,
+  removeJobResultFilesFromDiskRightAfterStoringOnS3: false,
+  stage: 'beta',
+}
+
+const enhanceModeSchema = z.enum(['auto', 'auto_gentle', 'auto_aggressive', 'none']).default('auto')
+
+const presetSchema = z
+  .enum([
+    'none',
+    'warm',
+    'cool',
+    'vintage',
+    'vivid',
+    'matte',
+    'cinematic',
+    'golden_hour',
+    'bw_dramatic',
+    'bw_classic',
+    'noir',
+    'fade',
+    'pastel',
+    'teal_orange',
+  ])
+  .default('none')
+
+const engineSchema = z.enum(['classic', 'ai']).default('classic')
+
+const aiPresetSchema = z.enum(['restore', 'face_restore']).default('restore')
+
+export const robotImageEnhanceInstructionsSchema = robotBase
+  .merge(robotUse)
+  .merge(robotImagemagick)
+  .extend({
+    robot: z.literal('/image/enhance').describe(`
+With this <dfn>Robot</dfn> you can automatically enhance images with one click — adjusting levels, contrast, saturation, sharpness, and white balance to produce an optimally balanced image. It also supports a library of named photo filter presets (e.g. \`warm\`, \`cool\`, \`vintage\`, \`vivid\`) that apply curated color grading and tone adjustments.
+
+It works well together with [🤖/image/resize](/docs/robots/image-resize/) — you can enhance first, then resize, or vice versa.
+
+> [!Note]
+> This <dfn>Robot</dfn> accepts all image types supported by ImageMagick and will pass through unsupported types unchanged.
+
+> [!Note]
+> \`engine: "classic"\` uses \`enhance\`, \`preset\`, \`sharpen\`, and \`denoise\`. \`engine: "ai"\` uses \`ai_preset\` and \`quality\`; classic controls are ignored in AI mode.
+
+> [!Note]
+> Output keeps the original file extension when possible. In AI mode, if the target extension is not writable by the selected \`imagemagick_stack\`, the file is passed through unchanged.
+`),
+    enhance: enhanceModeSchema.describe(`
+The auto-enhancement mode. \`"auto"\` applies balanced auto-levels, gamma correction, and subtle sharpening. \`"auto_gentle"\` is more conservative (good for already-decent photos). \`"auto_aggressive"\` applies stronger normalization and contrast. \`"none"\` skips auto-enhance (useful when only applying a preset filter).
+`),
+    preset: presetSchema.describe(`
+A named color grading preset to apply. Applied after auto-enhancement. Use \`"none"\` to skip preset application.
+
+Available presets:
+- \`warm\` — Warm golden tones
+- \`cool\` — Cool blue-shifted tones
+- \`vintage\` — Faded retro look with warm shadows
+- \`vivid\` — Boosted saturation and contrast
+- \`matte\` — Lifted blacks for a matte film look
+- \`cinematic\` — Teal-and-orange cinema grading
+- \`golden_hour\` — Warm sunset-like glow
+- \`bw_dramatic\` — High-contrast black and white
+- \`bw_classic\` — Classic film black and white
+- \`noir\` — Dark, moody black and white
+- \`fade\` — Washed-out faded look
+- \`pastel\` — Soft, desaturated pastel tones
+- \`teal_orange\` — Complementary teal shadows and orange highlights
+`),
+    engine: engineSchema.describe(`
+Enhancement engine to use.
+
+- \`"classic"\` uses ImageMagick-based adjustments and presets.
+- \`"ai"\` uses AI restoration models on Replicate (typically higher latency and cost than classic mode).
+`),
+    ai_preset: aiPresetSchema.describe(`
+AI enhancement preset used when \`engine\` is set to \`"ai"\`:
+- \`restore\` — General image restoration.
+- \`face_restore\` — Portrait-focused face restoration.
+
+AI mode is not intended for image upscaling. For dedicated upscaling, use [🤖/image/upscale](/docs/robots/image-upscale/).
+`),
+    sharpen: z
+      .number()
+      .min(0)
+      .max(10)
+      .default(0)
+      .describe(`
+Additional sharpening amount (\`0\` = none, \`10\` = maximum). The \`"auto"\` enhance mode already applies subtle sharpening; this parameter adds more on top.
+`),
+    denoise: z
+      .number()
+      .min(0)
+      .max(10)
+      .default(0)
+      .describe(`
+Noise reduction strength (\`0\` = none, \`10\` = maximum). Useful for high-ISO photos.
+`),
+    quality: imageQualitySchema.describe(`
+Quality of the output image. A value between \`1\` and \`100\`. Defaults to \`92\`.
+`),
+  })
+  .strict()
+
+export const robotImageEnhanceInstructionsWithHiddenFieldsSchema =
+  robotImageEnhanceInstructionsSchema.extend({
+    result: z
+      .union([z.literal('debug'), robotImageEnhanceInstructionsSchema.shape.result])
+      .optional(),
+  })
+
+export type RobotImageEnhanceInstructions = z.infer<typeof robotImageEnhanceInstructionsSchema>
+export type RobotImageEnhanceInstructionsWithHiddenFields = z.infer<
+  typeof robotImageEnhanceInstructionsWithHiddenFieldsSchema
+>
+
+export const interpolatableRobotImageEnhanceInstructionsSchema = interpolateRobot(
+  robotImageEnhanceInstructionsSchema,
+)
+export type InterpolatableRobotImageEnhanceInstructions =
+  InterpolatableRobotImageEnhanceInstructionsInput
+
+export type InterpolatableRobotImageEnhanceInstructionsInput = z.input<
+  typeof interpolatableRobotImageEnhanceInstructionsSchema
+>
+
+export const interpolatableRobotImageEnhanceInstructionsWithHiddenFieldsSchema = interpolateRobot(
+  robotImageEnhanceInstructionsWithHiddenFieldsSchema,
+)
+export type InterpolatableRobotImageEnhanceInstructionsWithHiddenFields = z.infer<
+  typeof interpolatableRobotImageEnhanceInstructionsWithHiddenFieldsSchema
+>
+export type InterpolatableRobotImageEnhanceInstructionsWithHiddenFieldsInput = z.input<
+  typeof interpolatableRobotImageEnhanceInstructionsWithHiddenFieldsSchema
+>

package/src/alphalib/types/robots/image-facedetect.ts

@@ -9,7 +9,6 @@ import {
 } from './_instructions-primitives.ts'
 
 export const meta: RobotMetaInput = {
-  allowed_for_url_transform: true,
   bytescount: 1,
   discount_factor: 1,
   discount_pct: 0,