Sync alphalib

Author: kvz

package.json

@@ -16,6 +16,8 @@
     "node": ">= 18"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.726.1",
+    "@aws-sdk/s3-request-presigner": "^3.726.1",
     "debug": "^4.3.7",
     "form-data": "^4.0.1",
     "got": "^11.8.6",

src/alphalib/types/robots/_instructions-primitives.ts

@@ -436,6 +436,6 @@ export const imageQualitySchema = z.number().int().min(1).max(100).default(92).d
 Controls the image compression for JPG and PNG images. Please also take a look at [🤖/image/optimize](/docs/transcoding/image-manipulation/image-optimize/).
 `)
 
-export const aiProviderSchema = z.enum(['aws', 'gcp'])
+export const aiProviderSchema = z.enum(['aws', 'gcp', 'replicate', 'fal', 'transloadit'])
 
 export const granularitySchema = z.enum(['full', 'list']).default('full')

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

@@ -40,7 +40,46 @@ export const robotFileFilterInstructionsSchema = z
       .boolean()
       .optional()
       .describe(`Whether the results of this Step should be present in the Assembly Status JSON`),
-    robot: z.literal('/file/filter'),
+    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]({{robot_links["/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]({{robot_links["/script/run"]}}). See also [Dynamic Evaluation](/docs/topics/dynamic-evaluation/) for more details on allowed syntax and behavior.
+`),
     use: useParamSchema,
     accepts: z
       .array(

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

@@ -44,7 +44,13 @@ export const robotFileVirusscanInstructionsSchema = z
       .boolean()
       .optional()
       .describe(`Whether the results of this Step should be present in the Assembly Status JSON`),
-    robot: z.literal('/file/virusscan'),
+    robot: z.literal('/file/virusscan').describe(`
+      This <dfn>Robot</dfn> is built on top of [ClamAV](https://www.clamav.net/), the best open source antivirus engine available. We update its signatures on a daily basis.
+
+By default, this <dfn>Robot</dfn> excludes all malicious files from further processing without any additional notification. This behavior can be changed by setting \`error_on_decline\` to \`true\`, which will stop <dfn>Assemblies</dfn> as soon as malicious files are found. Such <dfn>Assemblies</dfn> will then be marked with an error.
+
+We allow the use of industry standard [EICAR files](https://www.eicar.org/download-anti-malware-testfile/) for integration testing without needing to use potentially dangerous live virus samples.
+`),
     use: useParamSchema,
     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.

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

@@ -38,7 +38,18 @@ export const robotHttpImportInstructionsSchema = z
       .boolean()
       .optional()
       .describe(`Whether the results of this Step should be present in the Assembly Status JSON`),
-    robot: z.literal('/http/import'),
+    robot: z.literal('/http/import').describe(`
+The result of this <dfn>Robot</dfn> will carry a field \`import_url\` in their metadata, which references the URL from which they were imported. Further conversion results that use this file will also carry this \`import_url\` field. This allows you to to match conversion results with the original import URL that you used.
+
+This <dfn>Robot</dfn> knows to interpret links to files on these services:
+
+- Dropbox
+- Google Drive
+- Google Docs
+- OneDrive
+
+Instead of downloading the HTML page previewing the file, the actual file itself will be imported.
+`),
     ignore_errors,
     url: z.union([z.string().url(), z.array(z.string().url())]).describe(`
 The URL from which the file to be imported can be retrieved.

src/alphalib/types/robots/image-remove-background.ts

@@ -9,12 +9,15 @@ export const robotImageRemoveBackgroundInstructionsSchema = z
       .optional()
       .describe(`Whether the results of this Step should be present in the Assembly Status JSON`),
     robot: z.literal('/image/remove-background'),
-    endpoint: z.string().describe('The URL of the destination Tus server'),
     select: z
       .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.'),
+    provider: z
+      .enum(['transloadit', 'replicate', 'fal'])
+      .optional()
+      .describe('Provider to use for removing the background.'),
     output_meta: outputMetaParamSchema.optional(),
     use: useParamSchema,
   })

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

@@ -161,9 +161,9 @@ Controls the image compression for PNG images. Setting to \`true\` results in sm
     background: z
       .union([z.literal('transparent'), z.literal('none'), color_without_alpha])
       .default('#FFFFFF').describe(`
-Either the hexadecimal code or [name](https://www.imagemagick.org/script/color.php#color_names) of the color used to fill the background (only used for the pad resize strategy).
+Either the hexadecimal code or [name](https://www.imagemagick.org/script/color.php#color_names) of the color used to fill the background (used for the \`pad\` resize strategy).
 
-By default, the background of transparent images is changed to white. For details about how to preserve transparency across all image types, see [this demo](/demos/image-manipulation/properly-preserve-transparency-across-all-image-types/).
+**Note:** By default, the background of transparent images is changed to white. To preserve transparency, set \`"background"\` to \`"none"\`.
 `),
     frame: z.number().int().min(1).nullable().default(null).describe(`
 Use this parameter when dealing with animated GIF files to specify which frame of the GIF is used for the operation. Specify \`1\` to use the first frame, \`2\` to use the second, and so on. \`null\` means all frames.

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

@@ -49,7 +49,43 @@ export const robotS3ImportInstructionsSchema = z
       .boolean()
       .optional()
       .describe(`Whether the results of this Step should be present in the Assembly Status JSON`),
-    robot: z.literal('/s3/import'),
+    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>.
+
+**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. [{.alert .alert-warning}]
+
+<a id="minimum-s3-iam-permissions" aria-hidden="true"></a>
+
+## 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 export a file to your S3 bucket using Transloadit. You may require more permissions (especially viewing permissions) depending on your application.
+
+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).
+
+\`\`\`json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "AllowTransloaditToImportFilesIn{BUCKET_NAME}Bucket",
+      "Effect": "Allow",
+      "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
+      "Resource": ["arn:aws:s3:::{BUCKET_NAME}", "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.
+
+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.
+
+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.
+`),
     ignore_errors,
     credentials: credentials.describe(`
 Please create your associated <dfn>Template Credentials</dfn> in your Transloadit account and use the name of your <dfn>Template Credentials</dfn> as this parameter's value. They will contain the values for your S3 bucket, Key, Secret and Bucket region.

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

@@ -25,7 +25,7 @@ export const meta: RobotMeta = {
   override_lvl1: 'File Exporting',
   purpose_sentence: 'exports encoding results to supabase buckets',
   purpose_verb: 'export',
-  purpose_word: 'supabase',
+  purpose_word: 'Supabase',
   purpose_words: 'Export files to Supabase',
   service_slug: 'file-exporting',
   slot_count: 10,

src/alphalib/zodParseWithContext.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod'
 
-type ZodIssueWithContext = z.ZodIssue & { parentObj: unknown }
+export type ZodIssueWithContext = z.ZodIssue & { parentObj: unknown }
 
 function getByPath(obj: unknown, path: string): unknown {
   if (!path) return obj
@@ -13,28 +13,129 @@ function getByPath(obj: unknown, path: string): unknown {
   return current
 }
 
+interface ZodParseWithContextResult<T extends z.ZodType> {
+  success: boolean
+  safe?: z.infer<T>
+  errors: ZodIssueWithContext[]
+  humanReadable: string
+}
+
 export function zodParseWithContext<T extends z.ZodType>(
   schema: T,
   obj: unknown,
-): { success: boolean; safe?: z.infer<T>; errors: ZodIssueWithContext[] } {
+): ZodParseWithContextResult<T> {
   const zodRes = schema.safeParse(obj)
   if (!zodRes.success) {
-    const reportErrors: ZodIssueWithContext[] = []
-    for (const error of zodRes.error.errors) {
-      const lastPath = error.path
+    const zodIssuesWithContext: ZodIssueWithContext[] = []
+    for (const zodIssue of zodRes.error.errors) {
+      const lastPath = zodIssue.path
       let parentObj: unknown = {}
       if (lastPath) {
         const strPath = lastPath.slice(0, -1).join('.')
         parentObj = getByPath(obj, strPath) ?? {}
       }
 
-      reportErrors.push({
-        ...error,
+      zodIssuesWithContext.push({
+        ...zodIssue,
         parentObj,
       })
     }
-    return { success: false, errors: reportErrors }
+
+    const badPaths = new Map<string, string[]>()
+    for (const issue of zodIssuesWithContext) {
+      const path = issue.path
+        .map((p) => (typeof p === 'string' ? p.replaceAll('.', '\\.') : p))
+        .join('.')
+      if (!badPaths.has(path)) {
+        badPaths.set(path, [])
+      }
+
+      // Handle union type validation errors (e.g., when a value must be one of several allowed values)
+      // For example: z.union([z.literal(0), z.literal(90), z.literal(180)]) for rotation values
+      // This extracts all the valid values from the union type to show in the error message
+      if ('unionErrors' in issue && issue.unionErrors) {
+        const validValues: (string | number | boolean)[] = []
+        for (const unionError of issue.unionErrors) {
+          if (
+            Array.isArray(unionError.errors) &&
+            unionError.errors[0]?.code === 'invalid_literal'
+          ) {
+            const { expected } = unionError.errors[0]
+            if (
+              expected !== undefined &&
+              expected !== null &&
+              (typeof expected === 'string' ||
+                typeof expected === 'number' ||
+                typeof expected === 'boolean')
+            ) {
+              validValues.push(expected)
+            }
+          }
+        }
+        if (validValues.length > 0) {
+          badPaths.get(path)?.push(`should be one of: \`${validValues.join('`, `')}\``)
+        } else {
+          for (const unionError of issue.unionErrors) {
+            if ('expected' in unionError && typeof unionError.expected === 'string') {
+              badPaths.get(path)?.push(`should be ${unionError.expected}`)
+            } else {
+              badPaths.get(path)?.push(unionError.message)
+            }
+          }
+        }
+      } else if ('expected' in issue && typeof issue.expected === 'string') {
+        badPaths.get(path)?.push(`should be ${issue.expected}`)
+      } else {
+        // Handle specific error codes for better messages
+        let received: string
+        let type: string
+        let bigType: string
+
+        // Handle different validation error types with specific human-readable messages
+        // Each case formats the error message based on the type of validation that failed:
+        // - invalid_type: Wrong data type (e.g., string instead of number)
+        // - invalid_string: String format validation (email, url)
+        // - too_small/too_big: Length/size validations for strings and arrays
+        switch (issue.code) {
+          case 'invalid_type':
+            received = issue.received === 'undefined' ? 'missing' : issue.received
+            badPaths.get(path)?.push(`should be ${issue.expected} but got ${received}`)
+            break
+          case 'invalid_string':
+            if (issue.validation === 'email') {
+              badPaths.get(path)?.push('should be a valid email address')
+            } else if (issue.validation === 'url') {
+              badPaths.get(path)?.push('should be a valid URL')
+            } else {
+              badPaths.get(path)?.push(issue.message)
+            }
+            break
+          case 'too_small':
+            type = issue.type === 'string' ? 'characters' : 'items'
+            badPaths.get(path)?.push(`should have at least ${issue.minimum} ${type}`)
+            break
+          case 'too_big':
+            bigType = issue.type === 'string' ? 'characters' : 'items'
+            badPaths.get(path)?.push(`should have at most ${issue.maximum} ${bigType}`)
+            break
+          case 'custom':
+            badPaths.get(path)?.push(issue.message)
+            break
+          default:
+            badPaths.get(path)?.push(issue.message)
+        }
+      }
+    }
+
+    const humanReadable = Array.from(badPaths.entries())
+      .map(([path, messages]) => {
+        const field = path || 'Input'
+        return `Path \`${field}\` ${messages.join(', ')}`
+      })
+      .join('\n')
+
+    return { success: false, errors: zodIssuesWithContext, humanReadable }
   }
 
-  return { success: true, safe: zodRes.data, errors: [] }
+  return { success: true, safe: zodRes.data, errors: [], humanReadable: '' }
 }