transloadit 3.0.2 → 4.0.0-2

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

@@ -0,0 +1,104 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: false,
+  bytescount: 1,
+  discount_factor: 1,
+  discount_pct: 0,
+  example_code: {
+    steps: {
+      compressed: {
+        robot: '/file/compress',
+        use: {
+          steps: [':original'],
+          bundle_steps: true,
+        },
+        format: 'zip',
+      },
+    },
+  },
+  example_code_description: 'Compress uploaded files into a ZIP archive:',
+  extended_description: `
+### Archive structure for the \`"advanced"\` file layout.
+
+There are a few things that we kept in mind when designing the \`"advanced"\` archive structure:
+
+- There could be naming collisions.
+- You want to know which <dfn>Step</dfn> a result file belongs to.
+- You want to know from which originally uploaded file a result file was generated.
+- Ideally, you want subfolders for a better structure of files.
+
+To achieve all this, we have created the following archive file structure.
+
+- There is a subfolder for each <dfn>Step</dfn> name that has result files in the archive.
+- Files are named according to the first two letters of the unique original prefix + "_" + the first two letters of the unique prefix + "_" + the original file name. If you do not know what the original prefixes are, please check [our available Assembly variables](/docs/topics/assembly-instructions/#assembly-variables) and look for \`\${unique_original_prefix}\` and \`\${unique_prefix}\`.
+- Files that belong to the \`:original\` <dfn>Step</dfn> (originally uploaded files) do **not** include the first two letters of the \`unique_original_prefix\`.
+- If you are dealing with thumbnails from [🤖/video/thumbs](/docs/transcoding/video-encoding/video-thumbs/), there is an additional digit representing the order in the file name.
+
+Here is an example:
+
+\`\`\`yaml
+":original":
+  - gh_a.mov          # "gh" are the first 2 letters of the unique prefix.
+                      # "a.mov" was the file name of the uploaded file.
+  - ff_b.mov
+"thumbed":
+  - gh_e8_thumb_1.jpg # "gh" is the unique original prefix, meaning it's a result of a.mov.
+                      # "e8" is the file's unique prefix.
+                      # The "1" shows the thumbnail order.
+  - gh_cv_thumb_2.jpg
+  - ff_9b_thumb_3.jpg
+"resized":
+  - gh_ll_thumb.jpg
+  - gh_df_thumb.jpg
+  - ff_jk_thumb.jpg   # is a child of b.mov, as it starts with "ff"
+\`\`\`
+`,
+  minimum_charge: 0,
+  output_factor: 1,
+  override_lvl1: 'File Compressing',
+  purpose_sentence: 'creates archives of files or file conversion results',
+  purpose_verb: 'compress',
+  purpose_word: 'compress',
+  purpose_words: 'Compress files',
+  service_slug: 'file-compressing',
+  slot_count: 15,
+  title: 'Compress files',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotFileCompressInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/file/compress'),
+    format: z.enum(['tar', 'zip']).default('tar').describe(`
+The format of the archive to be created. Supported values are \`"tar"\` and \`"zip"\`.
+
+Note that \`"tar"\` without setting \`gzip\` to \`true\` results in an archive that's not compressed in any way.
+`),
+    gzip: z.boolean().default(false).describe(`
+Determines if the result archive should also be gzipped. Gzip compression is only applied if you use the \`"tar"\` format.
+`),
+    password: z.string().nullable().default(null).describe(`
+This allows you to encrypt all archive contents with a password and thereby protect it against unauthorized use. To unzip the archive, the user will need to provide the password in a text input field prompt.
+
+This parameter has no effect if the format parameter is anything other than \`"zip"\`.
+`),
+    compression_level: z.number().int().min(-9).max(0).default(-6).describe(`
+Determines how fiercely to try to compress the archive. \`-0\` is compressionless, which is suitable for media that is already compressed. \`-1\` is fastest with lowest compression. \`-9\` is slowest with the highest compression.
+
+If you are using \`-0\` in combination with the \`tar\` format with \`gzip\` enabled, consider setting \`gzip: false\` instead. This results in a plain Tar archive, meaning it already has no compression.
+`),
+    file_layout: z.enum(['advanced', 'simple']).default('advanced').describe(`
+Determines if the result archive should contain all files in one directory (value for this is \`"simple"\`) or in subfolders according to the explanation below (value for this is \`"advanced"\`).
+
+Files with same names are numbered in the \`"simple"\` file layout to avoid naming collisions.
+`),
+  })
+  .strict()
+
+export type RobotFileCompressInstructions = z.infer<typeof robotFileCompressInstructionsSchema>

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

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: true,
+  bytescount: 1,
+  discount_factor: 0.8,
+  discount_pct: 20,
+  example_code: {
+    steps: {
+      decompressed: {
+        robot: '/file/decompress',
+        use: ':original',
+      },
+    },
+  },
+  example_code_description: 'Decompress an uploaded archive:',
+  minimum_charge: 0,
+  output_factor: 1,
+  override_lvl1: 'File Compressing',
+  purpose_sentence:
+    'extracts entire archives of files to be consumed by other Robots or exported as individual files',
+  purpose_verb: 'decompress',
+  purpose_word: 'decompress',
+  purpose_words: 'Decompress archives',
+  service_slug: 'file-compressing',
+  slot_count: 10,
+  title: 'Decompress archives',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotFileDecompressInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/file/decompress').describe(`
+This Robot supports the following archive formats:
+
+- ZIP archives (with uncompressed or "deflate"-compressed entries)
+- 7-Zip archives
+- RAR archives
+- GNU tar format (including GNU long filenames, long link names, and sparse files)
+- Solaris 9 extended tar format (including ACLs)
+- Old V7 tar archives
+- POSIX ustar
+- POSIX pax interchange format
+- POSIX octet-oriented cpio
+- SVR4 ASCII cpio
+- POSIX octet-oriented cpio
+- Binary cpio (big-endian or little-endian)
+- ISO9660 CD-ROM images (with optional Rockridge or Joliet extensions)
+- GNU and BSD "ar" archives
+- "mtree" format
+- Microsoft CAB format
+- LHA and LZH archives
+- XAR archives
+
+This <dfn>Robot</dfn> also detects and handles any of the following before evaluating the archive file:
+
+- uuencoded files
+- Files with RPM wrapper
+- gzip compression
+- bzip2 compression
+- compress/LZW compression
+- lzma, lzip, and xz compression
+
+For security reasons, archives that contain symlinks to outside the archived dir, will error out the <dfn>Assembly</dfn>. Decompressing password-protected archives (encrypted archives) is currently not fully supported but will not cause an <dfn>Assembly</dfn> to fail.
+`),
+    ignore_errors: z
+      .union([z.boolean(), z.array(z.enum(['meta']))])
+      .transform((ignoreErrors): 'meta'[] =>
+        ignoreErrors === true ? ['meta'] : ignoreErrors === false ? [] : ignoreErrors,
+      )
+      .default([]).describe(`
+A possible array member is only \`"meta"\`.
+
+You might see an error when trying to extract metadata from the files inside your archive. This happens, for example, for files with a size of zero bytes. Setting this to \`true\` will cause the <dfn>Robot</dfn> to not stop the file decompression (and the entire <dfn>Assembly</dfn>) when that happens.
+
+To keep backwards compatibility, setting this parameter to \`true\` will set it to \`["meta"]\` internally.
+`),
+  })
+  .strict()
+
+export type RobotFileDecompressInstructions = z.infer<typeof robotFileDecompressInstructionsSchema>

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

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: true,
+  bytescount: 0,
+  discount_factor: 0,
+  discount_pct: 100,
+  example_code: {
+    steps: {
+      filtered: {
+        robot: '/file/filter',
+        use: ':original',
+        declines: [['${file.size}', '>', '20971520']],
+        error_on_decline: true,
+        error_msg: 'File size must not exceed 20 MB',
+      },
+    },
+  },
+  example_code_description: 'Reject files that are larger than 20 MB:',
+  minimum_charge: 0,
+  output_factor: 1,
+  override_lvl1: 'File Filtering',
+  purpose_sentence: 'directs files to different encoding Steps based on your conditions',
+  purpose_verb: 'filter',
+  purpose_word: 'filter',
+  purpose_words: 'Filter files',
+  service_slug: 'file-filtering',
+  slot_count: 0,
+  title: 'Filter files',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotFileFilterInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/file/filter').describe(`
+Think of this <dfn>Robot</dfn> as an \`if/else\` condition for building advanced file conversion workflows. With it, you can filter and direct certain uploaded files depending on their metadata.
+
+The <dfn>Robot</dfn> has two modes of operation:
+
+- Constructing conditions out of arrays with 3 members each. For example, \`["\${file.size}", "<=", "720"]\`
+- Writing conditions in JavaScript. For example, \`\${file.size <= 720}\`. See also [Dynamic Evaluation](/docs/topics/dynamic-evaluation/).
+
+Passing JavaScript allows you to implement logic as complex as you wish, however it’s slower than combining arrays of conditions, and will be charged for per invocation via [🤖/script/run](/docs/transcoding/code-evaluation/script-run/).
+
+### Conditions as arrays
+
+The \`accepts\` and \`declines\` parameters can each be set to an array of arrays with three members:
+
+1. A value or job variable, such as \`\${file.mime}\`
+2. One of the following operators: \`==\`, \`===\`, \`<\`, \`>\`, \`<=\`, \`>=\`, \`!=\`, \`!==\`, \`regex\`, \`!regex\`
+3. A value or job variable, such as \`50\` or \`"foo"\`
+
+Examples:
+
+- \`[["\${file.meta.width}", ">", "\${file.meta.height}"]]\`
+- \`[["\${file.size}", "<=", "720"]]\`
+- \`[["720", ">=", "\${file.size}"]]\`
+- \`[["\${file.mime}", "regex", "image"]]\`
+
+**Warning:** If you would like to match against a \`null\` value or a value that is not present (like an audio file does not have a \`video_codec\` property in its metadata), match against \`""\` (an empty string) instead. We’ll support proper matching against \`null\` in the future, but we cannot easily do so right now without breaking backwards compatibility. [{.alert .alert-warning}]
+
+### Conditions as JavaScript
+
+The \`accepts\` and \`declines\` parameters can each be set to strings of JavaScript, which return a boolean value.
+
+Examples:
+
+- \`\${file.meta.width > file.meta.height}\`
+- \`\${file.size <= 720}\`
+- \`\${/image/.test(file.mime)}\`
+- \`\${Math.max(file.meta.width, file.meta.height) > 100}\`
+
+As indicated, we charge for this via [🤖/script/run](/docs/transcoding/code-evaluation/script-run/). See also [Dynamic Evaluation](/docs/topics/dynamic-evaluation/) for more details on allowed syntax and behavior.
+`),
+    accepts: z
+      .array(
+        z.union([z.string(), z.tuple([z.string(), z.string(), z.union([z.string(), z.number()])])]),
+      )
+      .default([]).describe(`
+Files that match at least one requirement will be accepted, or declined otherwise. If the array is empty, all files will be accepted. Example:
+
+\`[["\${file.mime}", "==", "image/gif"]]\`.
+
+If the \`condition_type\` parameter is set to \`"and"\`, then all requirements must match for the file to be accepted.
+`),
+    declines: z
+      .array(
+        z.union([z.string(), z.tuple([z.string(), z.string(), z.union([z.string(), z.number()])])]),
+      )
+      .default([]).describe(`
+Files that match at least one requirement will be declined, or accepted otherwise. Example:
+
+\`[["\${file.size}",">","1024"]]\`.
+
+If the \`condition_type\` parameter is set to \`"and"\`, then all requirements must match for the file to be declined.
+`),
+    condition_type: z.enum(['and', 'or']).default('or').describe(`
+Specifies the condition type according to which the members of the \`accepts\` or \`declines\` arrays should be evaluated. Can be \`"or"\` or \`"and"\`.
+`),
+    error_on_decline: z.boolean().default(false).describe(`
+If this is set to \`true\` and one or more files are declined, the Assembly will be stopped and marked with an error.
+`),
+    error_msg: z.string().default('One of your files was declined').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\`.
+`),
+  })
+  .strict()
+
+export type RobotFileFilterInstructions = z.infer<typeof robotFileFilterInstructionsSchema>
+export type RobotFileFilterInstructionsInput = z.input<typeof robotFileFilterInstructionsSchema>

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

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: false,
+  bytescount: 5,
+  discount_factor: 0.2,
+  discount_pct: 80,
+  example_code: {
+    steps: {
+      hashed: {
+        robot: '/file/hash',
+        use: ':original',
+        algorithm: 'sha1',
+      },
+    },
+  },
+  example_code_description: 'Hash each uploaded file using the SHA-1 algorithm:',
+  minimum_charge: 0,
+  output_factor: 1,
+  override_lvl1: 'Media Cataloging',
+  purpose_sentence: 'hashes files in Assemblies',
+  purpose_verb: 'hash',
+  purpose_word: 'file',
+  purpose_words: 'Hash files',
+  service_slug: 'media-cataloging',
+  slot_count: 60,
+  title: 'Hash Files',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotFileHashInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/file/hash').describe(`
+This <dfn>Robot</dfn> allows you to hash any file as part of the <dfn>Assembly</dfn> execution process. This can be useful for verifying the integrity of a file for example.
+`),
+    algorithm: z
+      .enum(['b2', 'md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'])
+      .default('sha256').describe(`
+The hashing algorithm to use.
+
+The file hash is exported as \`file.meta.hash\`.
+`),
+  })
+  .strict()
+
+export type RobotFileHashInstructions = z.infer<typeof robotFileHashInstructionsSchema>

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

@@ -0,0 +1,174 @@
+import { z } from 'zod'
+
+import {
+  color_with_optional_alpha,
+  complexHeightSchema,
+  complexWidthSchema,
+  interpolationSchemaToYieldNumber,
+  optimize_priority,
+  resize_strategy,
+  robotBase,
+  robotUse,
+} from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: true,
+  bytescount: 1,
+  discount_factor: 1,
+  discount_pct: 0,
+  docs_redirect_from: ['/docs/media-preview/', '/docs/transcoding/media-cataloging/media-preview/'],
+  example_code: {
+    steps: {
+      previewed: {
+        robot: '/file/preview',
+        use: ':original',
+        height: 400,
+        width: 300,
+        format: 'png',
+      },
+    },
+  },
+  example_code_description: 'Generate a preview thumbnail for any uploaded file:',
+  minimum_charge: 1048576,
+  output_factor: 1,
+  override_lvl1: 'Media Cataloging',
+  purpose_sentence:
+    'generates a thumbnail for any uploaded file to preview its content, similar to the thumbnails in desktop file managers',
+  purpose_verb: 'generate',
+  purpose_word: 'generate',
+  purpose_words: 'Generate a preview thumbnail',
+  service_slug: 'media-cataloging',
+  slot_count: 15,
+  title: 'Generate a preview thumbnail',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotFilePreviewInstructionsInterpolatedSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/file/preview').describe(`
+This <dfn>Robot</dfn>'s purpose is to generate a meaningful preview image for any file, in such a way that the resulting thumbnail highlights the file's content. The goal is not to losslessly present the original media in a smaller way. Instead, it is to maximize the chance of a person recognizing the media at a glance, while being visually pleasing and consistent with other previews. The generation process depends on the file type. For example, the <dfn>Robot</dfn> can extract artwork from media files, frames from videos, generate a waveform for audio files, and preview the content of documents and images. The details of all available strategies are provided in the next section.
+
+If no file-specific thumbnail can be generated because the file type is not supported, a generic icon containing the file extension will be generated.
+
+The default parameters ensure that the <dfn>Robot</dfn> always generates a preview image with the predefined dimensions and formats, to allow an easy integration into your application's UI. In addition, the generated preview images are optimized by default to reduce their file size while keeping their quality.
+`),
+    format: z.enum(['gif', 'jpg', 'png']).default('png').describe(`
+The output format for the generated thumbnail image. If a short video clip is generated using the \`clip\` strategy, its format is defined by \`clip_format\`.
+`),
+    width: complexWidthSchema.default(300).describe(`
+Width of the thumbnail, in pixels.
+`),
+    height: complexHeightSchema.default(200).describe(`
+Height of the thumbnail, in pixels.
+`),
+    resize_strategy: resize_strategy.describe(`
+To achieve the desired dimensions of the preview thumbnail, the <dfn>Robot</dfn> might have to resize the generated image. This happens, for example, when the dimensions of a frame extracted from a video do not match the chosen \`width\` and \`height\` parameters.
+
+See the list of available [resize strategies](/docs/transcoding/image-manipulation/image-resize/#resize-strategies) for more details.
+`),
+    background: color_with_optional_alpha.default('#ffffffff').describe(`
+The hexadecimal code of the color used to fill the background (only used for the pad resize strategy). The format is \`#rrggbb[aa]\` (red, green, blue, alpha). Use \`#00000000\` for a transparent padding.
+`),
+    strategy: z
+      .object({
+        archive: z.array(z.string()).default(['icon']),
+        audio: z.array(z.string()).default(['artwork', 'waveform', 'icon']),
+        document: z.array(z.string()).default(['page', 'icon']),
+        image: z.array(z.string()).default(['image', 'icon']),
+        unknown: z.array(z.string()).default(['icon']),
+        video: z.array(z.string()).default(['artwork', 'frame', 'icon']),
+        webpage: z.array(z.string()).default(['render', 'icon']),
+      })
+      .optional().describe(`
+Definition of the thumbnail generation process per file category. The parameter must be an object whose keys can be one of the file categories: \`audio\`, \`video\`, \`image\`, \`document\`, \`archive\`, \`webpage\`, and \`unknown\`. The corresponding value is an array of strategies for the specific file category. See the above section for a list of all available strategies.
+
+For each file, the <dfn>Robot</dfn> will attempt to use the first strategy to generate the thumbnail. If this process fails (e.g., because no artwork is available in a video file), the next strategy is attempted. This is repeated until either a thumbnail is generated or the list is exhausted. Selecting the \`icon\` strategy as the last entry provides a fallback mechanism to ensure that an appropriate strategy is always available.
+
+The parameter defaults to the following definition:
+
+\`\`\`json
+{
+  "audio": ["artwork", "waveform", "icon"],
+  "video": ["artwork", "frame", "icon"],
+  "document": ["page", "icon"],
+  "image": ["image", "icon"],
+  "webpage": ["render", "icon"],
+  "archive": ["icon"],
+  "unknown": ["icon"]
+}
+\`\`\`
+`),
+    waveform_center_color: color_with_optional_alpha.default('#000000ff').describe(`
+The color used in the center of the waveform's gradient. The format is \`#rrggbb[aa]\` (red, green, blue, alpha). Only used if the \`waveform\` strategy for audio files is applied.
+`),
+    waveform_outer_color: color_with_optional_alpha.default('#000000ff').describe(`
+The color used in the outer parts of the waveform's gradient. The format is \`#rrggbb[aa]\` (red, green, blue, alpha). Only used if the \`waveform\` strategy for audio files is applied.
+`),
+    waveform_height: z.number().int().min(1).max(5000).default(100).describe(`
+Height of the waveform, in pixels. Only used if the \`waveform\` strategy for audio files is applied. It can be utilized to ensure that the waveform only takes up a section of the preview thumbnail.
+`),
+    waveform_width: z.number().int().min(1).max(5000).default(300).describe(`
+Width of the waveform, in pixels. Only used if the \`waveform\` strategy for audio files is applied. It can be utilized to ensure that the waveform only takes up a section of the preview thumbnail.
+`),
+    icon_style: z.enum(['square', 'with-text']).default('with-text').describe(`
+The style of the icon generated if the \`icon\` strategy is applied. The default style, \`with-text\`, includes an icon showing the file type and a text box below it, whose content can be controlled by the \`icon_text_content\` parameter and defaults to the file extension (e.g. MP4, JPEG). The \`square\` style only includes a square variant of the icon showing the file type. Below are exemplary previews generated for a text file utilizing the different styles:
+
+<br><br> <strong>\`with-text\` style:</strong> <br>
+![Image with text style]({{site.asset_cdn}}/assets/images/file-preview/icon-with-text.png)
+<br><br> <strong>\`square\` style:</strong> <br>
+![Image with square style]({{site.asset_cdn}}/assets/images/file-preview/icon-square.png)
+`),
+    icon_text_color: color_with_optional_alpha.default('#a2a2a2').describe(`
+The color of the text used in the icon. The format is \`#rrggbb[aa]\`. Only used if the \`icon\` strategy is applied.
+`),
+    // TODO: Determine the font enum.
+    icon_text_font: z.string().default('Roboto').describe(`
+The font family of the text used in the icon. Only used if the \`icon\` strategy is applied. [Here](/docs/supported-formats/fonts/) is a list of all supported fonts.
+`),
+    icon_text_content: z.enum(['extension', 'none']).default('extension').describe(`
+The content of the text box in generated icons. Only used if the \`icon_style\` parameter is set to \`with-text\`. The default value, \`extension\`, adds the file extension (e.g. MP4, JPEG) to the icon. The value \`none\` can be used to render an empty text box, which is useful if no text should not be included in the raster image, but some place should be reserved in the image for later overlaying custom text over the image using HTML etc.
+`),
+    optimize: z.boolean().default(true).describe(`
+Specifies whether the generated preview image should be optimized to reduce the image's file size while keeping their quaility. If enabled, the images will be optimized using [🤖/image/optimize](/docs/transcoding/image-manipulation/image-optimize/).
+`),
+    optimize_priority: optimize_priority.describe(`
+Specifies whether conversion speed or compression ratio is prioritized when optimizing images. Only used if \`optimize\` is enabled. Please see the [🤖/image/optimize documentation](/docs/transcoding/image-manipulation/image-optimize/#param-priority) for more details.
+`),
+    optimize_progressive: z.boolean().default(false).describe(`
+Specifies whether images should be interlaced, which makes the result image load progressively in browsers. Only used if \`optimize\` is enabled. Please see the [🤖/image/optimize documentation](/docs/transcoding/image-manipulation/image-optimize/#param-progressive) for more details.
+`),
+    clip_format: z.enum(['apng', 'avif', 'gif', 'webp']).default('webp').describe(`
+The animated image format for the generated video clip. Only used if the \`clip\` strategy for video files is applied.
+
+Please consult the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types) for detailed information about the image formats and their characteristics. GIF enjoys the broadest support in software, but only supports a limit color palette. APNG supports a variety of color depths, but its lossless compression produces large images for videos. AVIF is a modern image format that offers great compression, but proper support for animations is still lacking in some browsers. WebP on the other hand, enjoys broad support while offering a great balance between small file sizes and good visual quality, making it the default clip format.
+`),
+    clip_offset: z.number().min(0).default(1).describe(`
+The start position in seconds of where the clip is cut. Only used if the \`clip\` strategy for video files is applied. Be aware that for larger video only the first few MBs of the file may be imported to improve speed. Larger offsets may seek to a position outside of the imported part and thus fail to generate a clip.
+`),
+    clip_duration: z.number().min(0).default(5).describe(`
+The duration in seconds of the generated video clip. Only used if the \`clip\` strategy for video files is applied. Be aware that a longer clip duration also results in a larger file size, which might be undesirable for previews.
+`),
+    clip_framerate: z.number().int().min(1).max(60).default(5).describe(`
+The framerate of the generated video clip. Only used if the \`clip\` strategy for video files is applied. Be aware that a higher framerate appears smoother but also results in a larger file size, which might be undesirable for previews.
+`),
+    clip_loop: z.boolean().default(true).describe(`
+Specifies whether the generated animated image should loop forever (\`true\`) or stop after playing the animation once (\`false\`). Only used if the \`clip\` strategy for video files is applied.
+`),
+  })
+  .strict()
+
+export const robotFilePreviewInstructionsSchema =
+  robotFilePreviewInstructionsInterpolatedSchema.extend({
+    width: robotFilePreviewInstructionsInterpolatedSchema.shape.width.or(
+      interpolationSchemaToYieldNumber,
+    ),
+    height: robotFilePreviewInstructionsInterpolatedSchema.shape.height.or(
+      interpolationSchemaToYieldNumber,
+    ),
+  })
+
+export type RobotFilePreviewInstructions = z.infer<typeof robotFilePreviewInstructionsSchema>
+export type RobotFilePreviewInstructionsInput = z.input<typeof robotFilePreviewInstructionsSchema>

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

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: true,
+  bytescount: 5,
+  discount_factor: 0.2,
+  discount_pct: 80,
+  minimum_charge: 512000,
+  output_factor: 1,
+  override_lvl1: 'Document Processing',
+  purpose_sentence: 'reads file contents from supported file-types',
+  purpose_verb: 'read',
+  purpose_word: 'read files',
+  purpose_words: 'Read file contents',
+  service_slug: 'document-processing',
+  slot_count: 5,
+  title: 'Read file contents',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotFileReadInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/file/read').describe(`
+This <dfn>Robot</dfn> accepts any file, and will read the file using UTF-8 encoding. The result is outputted to \`file.meta.content\` to be accessed in later <dfn>Steps</dfn>.
+
+The <dfn>Robot</dfn> currently only accepts files under 500KB.
+`),
+  })
+  .strict()
+
+export type RobotFileReadInstructions = z.infer<typeof robotFileReadInstructionsSchema>

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

@@ -0,0 +1,60 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: true,
+  bytescount: 4,
+  discount_factor: 0.25,
+  discount_pct: 75,
+  minimum_charge: 0,
+  output_factor: 1,
+  purpose_sentence: 'serves files to web browsers',
+  purpose_verb: 'serve',
+  purpose_word: 'Serve files',
+  purpose_words: 'Serve files to web browsers',
+  service_slug: 'content-delivery',
+  slot_count: 0,
+  title: 'Serve files to web browsers',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+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.
+
+🤖/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.
+
+While theoretically possible, you could use [🤖/file/serve](/docs/transcoding/content-delivery/file-serve/) directly in HTML files, but we strongly recommend against this, because if your site gets popular and the media URL that /file/serve is handling gets hit one million times, that is one million new image resizes. Wrapping it with a CDN (and thanks to the caching that comes with it) makes sure encoding charges stay low, as well as latencies.
+
+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.
+
+More information on:
+
+- [Content Delivery](/services/content-delivery/).
+- [🤖/file/serve](/docs/transcoding/content-delivery/file-serve/) pricing.
+- [🤖/tlcdn/deliver](/docs/transcoding/content-delivery/tlcdn-deliver/) pricing.
+- [File Preview Feature](/blog/2024/06/file-preview-with-smart-cdn/) blog post.
+`),
+    headers: z.record(z.string()).default({
+      'Access-Control-Allow-Headers':
+        'X-Requested-With, Content-Type, Cache-Control, Accept, Content-Length, Transloadit-Client, Authorization',
+      'Access-Control-Allow-Methods': 'POST, GET, PUT, DELETE, OPTIONS',
+      'Access-Control-Allow-Origin': '*',
+      'Cache-Control': 'public, max-age=259200, s-max-age=86400',
+      'Content-Type': '${file.mime}; charset=utf-8',
+      'Transfer-Encoding': 'chunked',
+      'Transloadit-Assembly': '…',
+      'Transloadit-RequestID': '…',
+    }).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).
+`),
+  })
+  .strict()
+
+export type RobotFileServeInstructions = z.infer<typeof robotFileServeInstructionsSchema>
+export type RobotFileServeInstructionsInput = z.input<typeof robotFileServeInstructionsSchema>