transloadit 6.4.0 → 6.6.0

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

@@ -12,6 +12,7 @@ import {
   complexWidthSchema,
   createProcessingExample,
   defineRobot,
+  imageQualityValueSchema,
   optimize_priority,
   resize_strategy,
   robotBase,
@@ -19,6 +20,17 @@ import {
   robotUse,
 } from './_instructions-primitives.ts'
 
+/** Fallback order shared by schema defaults, published examples and worker normalization. */
+export const filePreviewStrategyDefaults = {
+  archive: ['icon'],
+  audio: ['artwork', 'waveform', 'icon'],
+  document: ['page', 'icon'],
+  image: ['image', 'embedded-preview', 'icon'],
+  unknown: ['icon'],
+  video: ['artwork', 'frame', 'icon'],
+  webpage: ['render', 'icon'],
+}
+
 export const meta: RobotMetaInput = {
   ...robotMediaCatalogingMeta,
   example_code: createProcessingExample('previewed', '/file/preview', {
@@ -44,17 +56,20 @@ export const robotFilePreviewInstructionsSchema = 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.
+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 [\`strategy\` parameter](#strategy) lists the available strategies and controls their fallback order.
 
-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.
+With the default strategy configuration, a generic icon is the fallback when no file-specific thumbnail can be generated. The default \`with-text\` icon style includes the file extension; \`icon_style\` and \`icon_text_content\` control its appearance.
 
-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.
+The default parameters produce still previews at the configured dimensions and format for integration into your application's UI. The optional \`clip\` strategy produces animated previews using \`clip_format\`. Preview images are optimized by default to reduce their file size while maintaining visual quality.
 `),
     format: z
       .enum(['avif', 'gif', 'jpeg', 'jpg', 'png', 'webp'])
       .default('png')
       .describe(`
-The output format for the generated thumbnail image. AVIF and WebP are also supported. If a short video clip is generated using the \`clip\` strategy, its format is defined by \`clip_format\`.
+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\`.
+`),
+    quality: imageQualityValueSchema.optional().describe(`
+Compression quality for still previews, from 1 to 100. When specified, the final image resize encodes directly into the requested format at this quality and strips embedded metadata. Omit it to retain the default encoding behavior. Animated clips use their own encoding settings. If \`optimize\` is enabled, optimization runs after this encoding.
 `),
     width: complexWidthSchema.default(300).describe(`
 Width of the thumbnail, in pixels.
@@ -80,32 +95,36 @@ Note that this parameter only affects strategies that produce a still image. Ani
 `),
     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']),
+        archive: z.array(z.string()).default(filePreviewStrategyDefaults.archive),
+        audio: z.array(z.string()).default(filePreviewStrategyDefaults.audio),
+        document: z.array(z.string()).default(filePreviewStrategyDefaults.document),
+        image: z.array(z.string()).default(filePreviewStrategyDefaults.image),
+        unknown: z.array(z.string()).default(filePreviewStrategyDefaults.unknown),
+        video: z.array(z.string()).default(filePreviewStrategyDefaults.video),
+        webpage: z.array(z.string()).default(filePreviewStrategyDefaults.webpage),
       })
       .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.
+Definition of the thumbnail generation process per file category. Each key selects a file category and its value is an ordered array of strategies:
+
+| File category | Available strategies |
+|---------------|----------------------|
+| \`audio\` | \`artwork\`, \`waveform\`, \`icon\` |
+| \`video\` | \`artwork\`, \`frame\`, \`clip\`, \`icon\` |
+| \`image\` | \`image\`, \`embedded-preview\`, \`icon\` |
+| \`document\` | \`page\`, \`icon\` |
+| \`archive\` | \`icon\` |
+| \`webpage\` | \`render\`, \`icon\` |
+| \`unknown\` | \`icon\` |
+
+\`artwork\` extracts embedded artwork, \`waveform\` draws an audio waveform, \`frame\` extracts a video frame, and \`clip\` creates an animated video preview. For images, \`image\` resizes the original and \`embedded-preview\` extracts an embedded preview when available. \`page\` renders the first document page, \`render\` captures a webpage, and \`icon\` generates a file-type icon.
 
 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"]
-}
+${JSON.stringify(filePreviewStrategyDefaults, null, 2)}
 \`\`\`
 `),
     artwork_outer_color: color_with_alpha.optional().describe(`
@@ -163,13 +182,13 @@ The font family of the text used in the icon. Only used if the \`icon\` strategy
       .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.
+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\` leaves the text box empty while reserving space for a custom text overlay, for example using HTML in your application.
 `),
     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/robots/image-optimize/).
+Specifies whether the generated preview image should be optimized to reduce its file size while maintaining visual quality. If enabled, the image will be optimized using [🤖/image/optimize](/docs/robots/image-optimize/).
 `),
     optimize_priority: optimize_priority.default('conversion-speed').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/robots/image-optimize/#priority) for more details.
@@ -186,14 +205,14 @@ Specifies whether images should be interlaced, which makes the result image load
       .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.
+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 broad support in software, but only supports a limited color palette. APNG supports a variety of color depths, but its lossless compression produces large images for videos. AVIF offers efficient compression, but animation support varies between browsers. WebP offers a balance between small file sizes and visual quality and is 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.
+The start position in seconds of where the clip is cut. Only used if the \`clip\` strategy for video files is applied. For large videos, only portions of the file may be imported to improve speed. An offset outside the available media data can prevent clip generation.
 `),
     clip_duration: z
       .number()

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

@@ -7,6 +7,7 @@ import type {
 import { z } from 'zod'
 
 import {
+  createProcessingExample,
   defineRobot,
   httpHeaderSafetyDescription,
   httpUrlSchema,
@@ -17,17 +18,11 @@ import {
 
 export const meta: RobotMetaInput = {
   ...robotCodeEvaluationMeta,
-  example_code: {
-    steps: {
-      request: {
-        robot: '/http/request',
-        method: 'POST',
-        payload: 'metadata',
-        url: 'https://example.com/transloadit/files',
-        use: [],
-      },
-    },
-  },
+  example_code: createProcessingExample('request', '/http/request', {
+    method: 'POST',
+    payload: 'metadata',
+    url: 'https://example.com/transloadit/files',
+  }),
   example_code_description: 'Ask your application which input files should continue:',
   extended_description: `
 Use this <dfn>Robot</dfn> when your application should inspect the current Assembly state or input
@@ -56,7 +51,7 @@ in the Assembly Template and use this Step as their input.
 `,
   override_lvl1: 'Workflow Automation',
   purpose_sentence:
-    'calls your application during an Assembly and emits returned input file references',
+    'calls your application during an Assembly and emits selected input files or downloads returned result-file URLs',
   purpose_verb: 'run',
   purpose_word: 'HTTP endpoint',
   purpose_words: 'Call HTTP endpoints',
@@ -100,7 +95,8 @@ Controls what is sent to your endpoint.
 - \`file\`: Send multipart form data with a \`payload\` JSON field and the first input file as a
   \`file\` part.
 - \`files\`: Send multipart form data with a \`payload\` JSON field and all input files as repeated
-  \`files[]\` parts. Useful with \`bundle_steps\`.
+  \`files[]\` parts. To send several input files in one request, set \`bundle_steps: true\` in the
+  advanced [\`use\` options](/docs/topics/use-parameter/#step-bundling).
 
 The \`payload\` JSON object contains \`assembly\`, \`fields\`, \`previous_step\`, \`file\`, and
 \`files\`. \`file\` is the first input file’s metadata or \`null\`; \`files\` is an array of input

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

@@ -77,11 +77,11 @@ export const robotImageEnhanceInstructionsSchema = robotBase
   .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.
+With this <dfn>Robot</dfn> you can automatically enhance images by adjusting levels, gamma, and sharpness. The selected enhancement mode determines which adjustments are applied. It also supports named photo filter presets (e.g. \`warm\`, \`cool\`, \`vintage\`, \`vivid\`) for 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.
 
-This <dfn>Robot</dfn> accepts all image types supported by ImageMagick and passes unsupported types through unchanged. \`engine: "classic"\` uses \`enhance\`, \`preset\`, \`sharpen\`, and \`denoise\`, while \`engine: "ai"\` uses \`ai_preset\` and \`quality\`; classic controls are ignored in AI mode. 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.
+This <dfn>Robot</dfn> accepts all image types supported by ImageMagick and passes unsupported image types through unchanged. \`engine: "classic"\` uses \`enhance\`, \`preset\`, \`sharpen\`, and \`denoise\`, while \`engine: "ai"\` uses \`ai_preset\`; classic controls are ignored in AI mode. Both engines use \`quality\` for the output image. 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).

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

@@ -443,7 +443,7 @@ Changes the hue by rotating the color of the image. The value \`100\` would prod
       .max(2)
       .default(1)
       .describe(`
-Adjusts the contrast of the image. A value of \`1\` produces no change. Values below \`1\` decrease contrast (with \`0\` being minimum contrast), and values above \`1\` increase contrast (with \`2\` being maximum contrast). This works like the \`brightness\` parameter.
+Adjusts the contrast of the image. A value of \`1\` produces no change. Values below \`1\` decrease contrast, and values above \`1\` increase it. Start with small adjustments, such as \`0.9\` or \`1.1\`. Larger increases can clip shadows and highlights.
 `),
     watermark_url: httpUrlSchema.optional().describe(`
 A URL indicating a PNG image to be overlaid above this image. Please note that you can also  [supply the watermark via another Assembly Step](/docs/topics/use-parameter/#supplying-the-watermark-via-an-assembly-step). With watermarking you can add an image onto another image. This is usually used for logos.
@@ -480,6 +480,8 @@ Values can be both positive and negative and yield different results depending o
 The size of the watermark, as a percentage.
 
 For example, a value of \`"50%"\` means that size of the watermark will be 50% of the size of image on which it is placed. The exact sizing depends on \`watermark_resize_strategy\`, too.
+
+With \`watermark_repeat_x\` or \`watermark_repeat_y\`, this sizes each tile relative to the output image, before repeating it. It does not set the percentage of the image covered by the whole pattern. Smaller values produce more, smaller tiles. If omitted, the watermark keeps its original pixel dimensions.
 `),
     watermark_resize_strategy: z
       .enum(['area', 'fit', 'min_fit', 'stretch'])

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

@@ -70,7 +70,7 @@ export const robotImageUpscaleInstructionsSchema = robotBase
     face_enhance: upscaleFaceEnhanceSchema
       .optional()
       .describe(
-        `Enable face enhancement for better face restoration. Defaults to ${upscaleFaceEnhanceSchema.parse(undefined)}.`,
+        `Enable face enhancement with Real-ESRGAN or face upsampling with CodeFormer. GFPGAN always performs face restoration and ignores this parameter. Defaults to ${upscaleFaceEnhanceSchema.parse(undefined)}.`,
       ),
   })
   .strict()

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

@@ -43,40 +43,39 @@ export const robotS3ImportInstructionsSchema = robotBase
     robot: z.literal('/s3/import').describe(`
 If you are new to Amazon S3, see our tutorial on [using your own S3 bucket](/docs/faq/how-to-set-up-an-amazon-s3-bucket/).
 
-The URL to the result file in your S3 bucket will be returned in the <dfn>Assembly Status JSON</dfn>.
-
-> [!Warning]
-> **Use DNS-compliant bucket names**. Your bucket name [must be DNS-compliant](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) and must not contain uppercase letters. Any non-alphanumeric characters in the file names will be replaced with an underscore, and spaces will be replaced with dashes. If your existing S3 bucket contains uppercase letters or is otherwise not DNS-compliant, rewrite the result URLs using the <dfn>Robot</dfn>’s \`url_prefix\` parameter.
-
 <span id="minimum-s3-iam-permissions" aria-hidden="true"></span>
 
 ## Limit access
 
-You will also need to add permissions to your bucket so that Transloadit can access it properly. Here is an example IAM policy that you can use. Following the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), it contains the **minimum required permissions** to import a file from your S3 bucket using Transloadit. You may require more permissions (especially viewing permissions) depending on your application.
+Use dedicated AWS credentials in your <dfn>Template Credentials</dfn> and grant that IAM identity access only to the bucket and objects it needs. The following example is an **identity-based IAM policy** for reading current objects from one general purpose S3 bucket. Attach it to the IAM user or role whose credentials you supply to Transloadit, not to the bucket. An identity-based policy has no \`Principal\` element: it applies to the identity it is attached to.
 
-Please change \`{BUCKET_NAME}\` in the values for \`Sid\` and \`Resource\` accordingly. Also, this policy will grant the minimum required permissions to all your users. We advise you to create a separate Amazon IAM user, and use its User ARN (can be found in the "Summary" tab of a user [here](https://console.aws.amazon.com/iam/home#users)) for the \`Principal\` value. More information about this can be found [here](https://docs.aws.amazon.com/AmazonS3/latest/dev/AccessPolicyLanguage_UseCases_s3_a.html).
+Replace \`{BUCKET_NAME}\` in both \`Resource\` values with your bucket name. The bucket-level statement permits listing objects and discovering the bucket's region; the object-level statement permits downloading them. See [AWS's S3 operation permissions](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-policy-actions.html) and [identity-based versus resource-based policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html).
 
 \`\`\`json
 {
   "Version": "2012-10-17",
   "Statement": [
     {
-      "Sid": "AllowTransloaditToImportFilesIn{BUCKET_NAME}Bucket",
+      "Sid": "ReadBucketMetadata",
       "Effect": "Allow",
       "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
-      "Resource": ["arn:aws:s3:::{BUCKET_NAME}", "arn:aws:s3:::{BUCKET_NAME}/*"]
+      "Resource": "arn:aws:s3:::{BUCKET_NAME}"
+    },
+    {
+      "Sid": "ReadBucketObjects",
+      "Effect": "Allow",
+      "Action": "s3:GetObject",
+      "Resource": "arn:aws:s3:::{BUCKET_NAME}/*"
     }
   ]
 }
 \`\`\`
 
-The \`Sid\` value is just an identifier for you to recognize the rule later. You can name it anything you like.
-
-The policy needs to be separated into two parts, because the \`ListBucket\` action requires permissions on the bucket while the other actions require permissions on the objects in the bucket. When targeting the objects there's a trailing slash and an asterisk in the \`Resource\` parameter, whereas when the policy targets the bucket, the slash and the asterisk are omitted.
+The \`Sid\` values are labels for recognizing statements. Supplying the correct \`bucket_region\` avoids automatic region discovery and its \`s3:GetBucketLocation\` permission. The example still grants bucket-wide listing and reads: narrow its object resources and listing conditions when your workflow needs only a specific prefix.
 
-In order to build proper result URLs we need to know the region in which your S3 bucket resides. For this we require the \`GetBucketLocation\` permission. Figuring out your bucket's region this way will also slow down your Assemblies. To make this much faster and to also not require the \`GetBucketLocation\` permission, we have added the \`bucket_region\` parameter to the /s3/store and /s3/import Robots. We recommend using them at all times.
+This example is not a guarantee of access. Explicit denies, organization policies, permission boundaries, cross-account bucket policies, and object ownership can affect the result. For cross-account access, review [AWS's policy evaluation guidance](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic-cross-account.html).
 
-Please keep in mind that if you use bucket encryption you may also need to add \`"sts:*"\` and \`"kms:*"\` to the bucket policy. Please read [here](https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html) and [here](https://aws.amazon.com/blogs/security/how-to-restrict-amazon-s3-bucket-access-to-a-specific-iam-role/) in case you run into trouble with our example bucket policy.
+For SSE-KMS-encrypted objects, also configure the IAM identity and KMS key policy with the key permissions required by [AWS's GetObject documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html), scoped to the intended key. KMS actions belong in IAM identity policies and KMS key policies, **not S3 bucket policies**. Do not grant broad \`sts:*\` or \`kms:*\` permissions as a workaround.
 `),
     path: path.describe(`
 The path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example: \`images/avatar.jpg\`.
@@ -85,7 +84,7 @@ If it points to a directory, indicated by a trailing slash (\`/\`), then all fil
 
 Directories are **not** imported recursively. If you want to import files from subdirectories and sub-subdirectories, enable the \`recursive\` parameter.
 
-If you want to import all files from the root directory, please use \`/\` as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with \`/\`, you'll receive an error: \`A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist.\`
+Use \`/\` to import files from the bucket root. Object keys do not need a leading slash. Enable \`recursive\` to include files under nested prefixes.
 
 You can also use an array of path strings here to import multiple paths in the same <dfn>Robot</dfn>'s <dfn>Step</dfn>.
 `),

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

@@ -33,8 +33,30 @@ export const robotSupabaseStoreInstructionsSchema = robotBase
   .merge(robotUse)
   .merge(supabaseBase)
   .extend({
-    robot: z.literal('/supabase/store'),
+    robot: z.literal('/supabase/store').describe(`
+## Upload as a Supabase user
+
+For [Supabase session-token authentication](https://supabase.com/docs/guides/storage/s3/authentication#session-token), supply your project ref as \`key\`, your project’s anon key as \`secret\`, and the user’s access-token JWT as \`session_token\`. Supabase applies the authenticated user’s Row Level Security (RLS) policies to these uploads. Choose a \`path\` those policies permit, and use the endpoint and region from your project’s S3 connection settings.
+
+Send the user’s JWT with each Assembly from your trusted backend. It must remain valid through queuing, processing, and upload retries; the Robot does not refresh it. Without \`session_token\`, continue using your generated Supabase S3 access key and secret. Those generated S3 access keys bypass RLS.
+
+Supply \`session_token\` inline in the Step. Assembly Status returns \`fields\` unchanged, so passing the JWT through Assembly \`fields\` exposes it in the status response.
+
+The result URL uses Supabase’s public-object URL format. It does not grant read access to a private bucket; use Supabase’s download authorization for private objects.
+`),
+    credentials: supabaseBase.shape.credentials.describe(`
+The name of your Supabase <dfn>Template Credentials</dfn>, containing the bucket, host, key, secret, and bucket region. You can instead supply those parameters directly in the Step.
+
+For generated S3 access-key authentication, use the endpoint and S3 access keys from your Supabase project’s S3 connection settings. For user-scoped session-token authentication, use the project ref as \`key\` and the project’s anon key as \`secret\`, then supply the user’s access-token JWT as \`session_token\` with each Assembly.
+`),
     path: storeFilePath,
+    session_token: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(`
+The user’s Supabase access-token JWT for [session-token authentication](https://supabase.com/docs/guides/storage/s3/authentication#session-token). Use the Supabase project ref as \`key\` and the project’s anon key as \`secret\` so Supabase applies that user’s RLS policies. The JWT must remain valid through queuing, processing, and upload retries; the Robot does not refresh it. Supply this value directly in the Step; Assembly Status exposes values in \`fields\`.
+`),
     headers: z
       .record(z.string())
       .default({ 'Content-Type': '${file.mime}' })

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

@@ -33,9 +33,7 @@ export const robotTigrisStoreInstructionsSchema = robotBase
   .merge(robotUse)
   .merge(tigrisBase)
   .extend({
-    robot: z.literal('/tigris/store').describe(`
-The URL to the result file will be returned in the <dfn>Assembly Status JSON</dfn>.
-`),
+    robot: z.literal('/tigris/store'),
     path: storeFilePath,
     acl: storageAcl,
     headers: z
@@ -62,6 +60,7 @@ If this parameter is not used, no URL signing is done.
       .describe('The region of your Tigris bucket. This is optional as it can often be derived.'),
   })
   .strict()
+  .describe('The URL to the result file will be returned in the <dfn>Assembly Status JSON</dfn>.')
 
 export const robotDefinition: RobotDefinition<typeof robotTigrisStoreInstructionsSchema.shape> =
   defineRobot(meta, robotTigrisStoreInstructionsSchema)

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

@@ -40,12 +40,15 @@ Whether to import files from subfolders and sub-subfolders when \`path\` is a fo
 only the folder's own files are imported.
 `
 
-/** Storage imports require proof of possession independently of Workspace signature settings. */
+/** Private Storage imports require proof of possession independently of Workspace settings. */
 export const transloaditImportAuthenticationGuidanceLines = [
   'Assemblies that use `/transloadit/import`, directly or through a Template, require',
   'either a bearer token or signed `params` with a future `params.auth.expires` timestamp.',
   'This applies even when Workspace Signature Authentication is disabled. An Auth Key alone',
   'is not sufficient; bearer-authenticated requests do not need a separate signature or expiry.',
+  'Public Storage Builtin Templates are the exception: they can serve unsigned requests only',
+  'when every Storage import remains within a declared public prefix. This does not authorize',
+  'unsigned Assemblies with arbitrary Steps or access to private Storage paths.',
 ] as const
 
 export const meta: RobotMetaInput = {

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

@@ -64,6 +64,25 @@ existing asset. Always save the returned asset identity, version and final path.
 Sets the destination path inside your Transloadit Storage workspace, relative to its root: a
 filename, or folders and a filename such as \`website/hero.jpg\`. Folders that do not exist yet
 are created.
+
+Repeated interior slashes are collapsed after variable interpolation. For example,
+\`a/\${file.meta.relative_path}/\${file.name}\` stores a root-level HLS playlist as
+\`a/playlist.m3u8\` when \`relative_path\` is empty. Leading or trailing slashes and
+\`.\` or \`..\` segments remain invalid.
+`),
+    result: z
+      .boolean()
+      .default(true)
+      .describe(`
+Leave \`result\` unset or set it to \`true\` on this Storage Step. Setting \`result: false\`
+here can omit stored entries, including asset and version IDs, from the Assembly Status JSON
+even though the files are stored.
+
+Stored results appear under their producing Step in the Assembly Status JSON, or under
+\`:original\` for uploaded files, rather than under this Storage Step. Setting \`result: false\`
+on a producing processing Step also omits its stored entries, including asset and version IDs,
+from the Assembly Status JSON even though the files are stored. Leave \`result\` unset or set it
+to \`true\` on that Step to receive those identities.
 `),
   })
   .strict()

package/src/alphalib/types/robots/video-adaptive.ts

@@ -71,6 +71,18 @@ This <dfn>Robot</dfn> accepts all types of video files and audio files. Do not f
 
 This <dfn>Robot</dfn> is normally used in combination with [🤖/video/encode](/docs/robots/video-encode/). We have implemented video and audio encoding presets specifically for MPEG-Dash and HTTP Live Streaming support. These presets are prefixed with \`"dash/"\` and \`"hls/"\`. [View a HTTP Live Streaming demo here](/demos/video-encoding/implement-http-live-streaming/).
 
+### HLS subtitles
+
+With \`"technique": "hls"\`, the first embedded subtitle track of each input is converted to segmented WebVTT and linked from the master playlist. Additional subtitle tracks in the same input are dropped. The Assembly adds a warning when any input contains more than one subtitle track.
+
+To add a track before packaging, use [🤖/video/subtitle](/docs/robots/video-subtitle/) with \`"subtitles_type": "external"\`, \`"preset": "empty"\`, and a \`language\` such as \`"eng"\`. Then encode with an \`"hls/"\` preset and pass the encoded video to this Robot. By default, the playlist’s subtitle \`NAME\` uses the language’s English name, for example “English”; its \`LANGUAGE\` preserves the input’s language tag. Unrecognized language codes are used as the name. If the language is missing or \`"und"\`, the name is “Unknown”. Custom \`ffmpeg.var_stream_map\` mappings control their own subtitle labels.
+
+To set an explicit subtitle name in a custom \`ffmpeg.var_stream_map\`, select \`"ffmpeg_stack": "v8.0.0"\` and use its \`sname\` option.
+
+WebVTT cues and MPEG-TS video use the same timestamp timeline. AAC priming or video frame reordering can move both after zero, so a small nonzero first cue timestamp does not by itself mean subtitles are delayed. Preserve the generated timestamps to keep subtitles synchronized with the video. When any input to an HLS Step has subtitles, \`ffmpeg.muxdelay\` defaults to \`0\` for the whole Step, including renditions without subtitles. Overriding it or other timestamp options can change that alignment.
+
+Store the WebVTT segments and subtitle playlists along with all other results, preserving \`\${file.meta.relative_path}\` as described below.
+
 ### CMAF aspect ratios
 
 CMAF aligns near-equal rendition aspect ratios, within 1% of the largest rendition, without re-encoding or changing pixel dimensions. This lets presets such as \`"hls/480p"\` and \`"hls/720p"\` support bitrate switching together.

package/src/alphalib/types/robots/video-concat.ts

@@ -8,6 +8,7 @@ import { z } from 'zod'
 
 import {
   defineRobot,
+  getConcatFadeDescription,
   inputSortBySchema,
   robotBase,
   robotFFmpegVideo,
@@ -67,23 +68,23 @@ It’s possible to concatenate a virtually infinite number of video files using
 `),
     video_fade_seconds: z
       .number()
-      .default(1)
+      .default(0)
       .describe(`
-When used this adds a video fade in and out effect between each section of your concatenated video. The float value is used so if you want a video delay effect of 500 milliseconds between each video section you would select \`0.5\`, however, integer values can also be represented.
+${getConcatFadeDescription('video')}
 
-This parameter does not add a video fade effect at the beginning or end of your video. If you want to do so, create an additional [🤖/video/encode](/docs/robots/video-encode/) Step and use our \`ffmpeg\` parameter as shown in this [demo](/demos/video-encoding/concatenate-fade-effect/).
+This parameter only applies when \`transition\` is \`"none"\`. It is ignored when \`transition\` is \`"crossfade"\` or \`"fade_to_black"\`; use \`transition_duration\` for those effects. Audio fades are controlled separately by \`audio_fade_seconds\`.
 
-Please note this parameter is independent of adding audio fades between sections.
+To add a fade-in at the beginning of the output, use an additional [video encoding Step](/docs/robots/video-encode/) with the \`ffmpeg\` parameter, as shown in the [video fade demo](/demos/video-encoding/concatenate-fade-effect/).
 `),
     audio_fade_seconds: z
       .number()
-      .default(1)
+      .default(0)
       .describe(`
-When used this adds an audio fade in and out effect between each section of your concatenated video. The float value is used so if you want an audio delay effect of 500 milliseconds between each video section you would select \`0.5\`, however, integer values can also be represented.
+${getConcatFadeDescription('audio')}
 
-This parameter does not add an audio fade effect at the beginning or end of your video. If you want to do so, create an additional [🤖/video/encode](/docs/robots/video-encode/) Step and use our \`ffmpeg\` parameter as shown in this [demo](/demos/audio-encoding/ffmpeg-fade-in-and-out/).
+This parameter only applies when \`transition\` is \`"none"\`. It is ignored when \`transition\` is \`"crossfade"\` or \`"fade_to_black"\`; use \`transition_duration\` for those effects. Video fades are controlled separately by \`video_fade_seconds\`.
 
-Please note this parameter is independent of adding video fades between sections.
+To add an audio fade-in at the beginning of the output, use an additional [video encoding Step](/docs/robots/video-encode/) with the \`ffmpeg\` parameter. The [audio fade demo](/demos/audio-encoding/ffmpeg-fade-in-and-out/) shows the corresponding FFmpeg audio filter.
 `),
     chapter_markers: z
       .boolean()

package/src/alphalib/types/robots/video-thumbs.ts

@@ -91,18 +91,18 @@ For an upload-to-poster Template, SDK usage, and publication checks, see the [HT
     count: thumbnailCountSchema.describe(`
 The number of thumbnails to be extracted. As some videos have incorrect durations, the actual number of thumbnails generated may be less in rare cases. The maximum number of thumbnails we currently allow is 999.
 
-The thumbnails are taken at regular intervals, determined by dividing the video duration by the count. For example, a count of 3 will produce thumbnails at 25%, 50% and 75% through the video.
+When \`smart\` is \`false\`, the thumbnails are taken at regular intervals. For example, a count of 3 produces thumbnails at 25%, 50% and 75% through the video. With \`smart: true\`, this is the number of thumbnails selected from the candidate pool instead.
 
 To extract thumbnails for specific timestamps, use the \`offsets\` parameter.
 `),
     offsets: z
-      .union([z.array(z.number().finite()), z.array(percentageSchema)])
+      .union([z.array(z.number().finite()).min(1), z.array(percentageSchema).min(1)])
       .nullable()
-      .default([])
+      .optional()
       .describe(`
 An array of offsets representing seconds of the file duration, such as \`[ 2, 45, 120 ]\`. Millisecond durations of a file can also be used by using decimal place values. For example, an offset from 1250 milliseconds would be represented with \`1.25\`. Offsets can also be percentage values such as \`[ "2%", "50%", "75%" ]\`.
 
-This option cannot be used with the \`count\` parameter, and takes precedence if both are specified. Out-of-range offsets are silently ignored.
+When \`smart\` is \`false\`, \`offsets\` takes precedence over \`count\`. Request timestamps within the video duration. If FFmpeg produces no frame at a requested offset, the Robot may retry without timestamp seeking and return an early frame instead. It does not simply ignore the offset, and extraction can still fail if no frame is available.
 
 When \`smart\` is \`true\`, smart selection ignores \`offsets\` and uses \`count\` to select from its own candidate timestamps. If no smart candidates can be extracted, the Robot falls back to standard extraction, where \`offsets\` takes precedence. Use \`smart: false\` to consistently extract the specified timestamps.
 
@@ -128,17 +128,17 @@ The width of the thumbnail, in pixels. Omit or use \`null\` for the original wid
       .number()
       .int()
       .min(1)
-      .max(1080)
+      .max(1920)
       .nullable()
       .optional()
       .describe(`
-The height of the thumbnail, in pixels. Omit or use \`null\` for the original height of the video.
+The thumbnail height in pixels, capped like \`width\`. Omit or use \`null\` for the original height.
 `),
     resize_strategy: resize_strategy.describe(`
 One of the [available resize strategies](/docs/topics/resize-strategies/).
 `),
-    background: color_with_alpha.default('#00000000').describe(`
-The background color of the resulting thumbnails in the \`"rrggbbaa"\` format (red, green, blue, alpha) when used with the \`"pad"\` resize strategy. The default color is black.
+    background: color_with_alpha.default('#000000ff').describe(`
+The background color of the resulting thumbnails in the \`"rrggbbaa"\` format (red, green, blue, alpha) when used with the \`"pad"\` resize strategy. The default color is opaque black.
 `),
     rotate: z
       .union([z.literal(0), z.literal(90), z.literal(180), z.literal(270), z.literal(360)])

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

@@ -39,7 +39,7 @@ export const robotVimeoStoreInstructionsSchema = robotBase
     robot: z.literal('/vimeo/store').describe(`
 ## Getting started
 
-Since Vimeo works with OAuth, you will need to generate [Template Credentials](https://transloadit.com/c/template-credentials/) to use this <dfn>Robot</dfn>.
+Create [Template Credentials](https://transloadit.com/c/template-credentials/) using Vimeo OAuth for uploads, or paste your own personal access token. A personal token needs \`upload\`, \`edit\`, and \`interact\` for this <dfn>Robot</dfn>, plus \`public\`, \`private\`, and \`video_files\` when saving it through the Console for imports. Your Vimeo app must have upload access. Follow the [Vimeo token instructions](/docs/topics/template-credentials/#vimeo) to create a token or reconnect.
 
 To change the \`title\` or \`description\` per video, we recommend to [inject variables into your Template](/docs/topics/templates/).