@transloadit/zod 7.0.0 → 7.1.1

package/README.md

@@ -1,10 +1,20 @@
 # @transloadit/zod
 
-**Stability:** This package is still relatively new and may evolve quickly.
+**Stability:** Exported names, helper functions and supported Zod versions follow strict SemVer.
+API contract types and schemas follow API2 and can change in minor releases, including
+type-breaking updates. See the
+[versioning policy](https://github.com/transloadit/node-sdk/blob/main/CONTRIBUTING.md#versioning-policy).
+
+- Commit your lockfile and type-check dependency update PRs.
+- Use `~` ranges for stable contract types within a minor; patch releases do not change contract
+  types. Use `^` to follow the API as it evolves.
+- Use input types for instructions you write, such as `AssemblyInstructionsInput`; narrow fields
+  from responses and parsed output before use (`null`, `undefined`, unknown strings).
+- Do not depend on Zod internals such as wrapper classes, `.shape` or parse-time defaults.
 
 Exports Zod schemas derived from Transloadit types.
 
-For the stable SDK, use the unscoped `transloadit` package.
+For the SDK client, use `@transloadit/node` or the unscoped `transloadit` package.
 
 ## Migrating schema consumers
 

package/dist/v3/builtinTemplates.d.ts

@@ -80,4 +80,44 @@ export declare const builtinTemplateDocsSchema: z.ZodArray<z.ZodObject<{
     }[];
 }>, "many">;
 export type BuiltinTemplateDoc = z.infer<typeof builtinTemplateDocSchema>;
+/** Standalone catalog JSON Schema, or null when a Builtin has no declared fields contract. */
+export declare const builtinTemplateFieldsSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+/**
+ * Runtime catalog projection used by Builtin clients. API2 supplies descriptions, field schemas
+ * and defaults; absent and null schemas remain distinct, and neither declares a usable contract.
+ */
+export declare const builtinTemplateCatalogItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    fields_schema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    content: z.ZodObject<{
+        fields: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        fields: Record<string, unknown>;
+    }, {
+        fields?: Record<string, unknown> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    content: {
+        fields: Record<string, unknown>;
+    };
+    id: string;
+    description?: string | undefined;
+    fields_schema?: Record<string, unknown> | null | undefined;
+}, {
+    content: {
+        fields?: Record<string, unknown> | undefined;
+    };
+    id: string;
+    description?: string | undefined;
+    fields_schema?: Record<string, unknown> | null | undefined;
+}>;
+/** Runtime catalog item after missing fields have been normalized to an empty object. */
+export type BuiltinTemplateCatalogItem = z.infer<typeof builtinTemplateCatalogItemSchema>;
+/**
+ * MCP channel approvals: exact reviewed versions and temporarily excluded field values.
+ * Membership is explicit; a catalog schema, a new Builtin version, or Storage eligibility does
+ * not grant MCP approval. Keep runtime descriptions, schemas and defaults in API2's catalog.
+ */
+export declare const mcpBuiltinTemplateManifest: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
 //# sourceMappingURL=builtinTemplates.d.ts.map

package/dist/v3/builtinTemplates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtinTemplates.d.ts","sourceRoot":"","sources":["../../src/v3/builtinTemplates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiB1B,CAAA;AAEX,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAoC,CAAA;AAE1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA"}
+{"version":3,"file":"builtinTemplates.d.ts","sourceRoot":"","sources":["../../src/v3/builtinTemplates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiB1B,CAAA;AAEX,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAoC,CAAA;AAE1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEzE,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B,uDAA+C,CAAA;AAEvF;;;GAGG;AACH,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;EAK3C,CAAA;AAEF,yFAAyF;AACzF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAA;AAEzF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAC/C,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC,CAY5D,CAAA"}

package/dist/v3/builtinTemplates.js

@@ -16,3 +16,32 @@ export const builtinTemplateDocSchema = z
 })
     .strict();
 export const builtinTemplateDocsSchema = z.array(builtinTemplateDocSchema);
+/** Standalone catalog JSON Schema, or null when a Builtin has no declared fields contract. */
+export const builtinTemplateFieldsSchema = z.record(z.string(), z.unknown()).nullable();
+/**
+ * Runtime catalog projection used by Builtin clients. API2 supplies descriptions, field schemas
+ * and defaults; absent and null schemas remain distinct, and neither declares a usable contract.
+ */
+export const builtinTemplateCatalogItemSchema = z.object({
+    id: z.string(),
+    description: z.string().optional(),
+    fields_schema: builtinTemplateFieldsSchema.optional(),
+    content: z.object({ fields: z.record(z.string(), z.unknown()).default({}) }),
+});
+/**
+ * MCP channel approvals: exact reviewed versions and temporarily excluded field values.
+ * Membership is explicit; a catalog schema, a new Builtin version, or Storage eligibility does
+ * not grant MCP approval. Keep runtime descriptions, schemas and defaults in API2's catalog.
+ */
+export const mcpBuiltinTemplateManifest = {
+    'builtin/caption-video@0.0.1': {},
+    'builtin/capture-webpage@0.0.1': {},
+    'builtin/convert-to-pdf@0.0.1': {},
+    // Remove only after api2#9960 is deployed and its VP8/turbo output is verified.
+    'builtin/encode-video@0.0.1': { preset: ['webm'] },
+    'builtin/extract-text@0.0.1': {},
+    'builtin/prepare-image@0.0.1': {},
+    'builtin/remove-background@0.0.1': {},
+    'builtin/transcribe@0.0.1': {},
+    'builtin/video-covers@0.0.1': {},
+};

package/dist/v3/responseErrors/DocumentConvertRobot.d.ts

@@ -0,0 +1,17 @@
+/** Public reason when diagnostics identify a service-side document-loading failure. */
+export declare const documentConvertLoadInternalErrorReason = "LibreOffice could not load the document. Please contact support.";
+/** Public reason for a load refusal without evidence of a service-side failure. */
+export declare const documentConvertLoadUserErrorReason = "LibreOffice could not load the document. It may be damaged, password-protected, or in an unsupported format. If it opens elsewhere, please contact support.";
+/** DocumentConvertRobot error payloads shared by runtime and the Assembly Status contract. */
+export declare const documentConvertRobotErrors: {
+    readonly DOCUMENT_CONVERT_VALIDATION: {
+        readonly error: "DOCUMENT_CONVERT_VALIDATION";
+        readonly http_code: 400;
+    };
+    readonly DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION: {
+        readonly error: "DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION";
+        readonly http_code: 400;
+        readonly message: "The conversion from the input file's format to the desired output format is not supported.";
+    };
+};
+//# sourceMappingURL=DocumentConvertRobot.d.ts.map

package/dist/v3/responseErrors/DocumentConvertRobot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentConvertRobot.d.ts","sourceRoot":"","sources":["../../../src/v3/responseErrors/DocumentConvertRobot.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,eAAO,MAAM,sCAAsC,qEACiB,CAAA;AAEpE,mFAAmF;AACnF,eAAO,MAAM,kCAAkC,gKACgH,CAAA;AAE/J,8FAA8F;AAC9F,eAAO,MAAM,0BAA0B;;;;;;;;;;CAW7B,CAAA"}

package/dist/v3/responseErrors/DocumentConvertRobot.js

@@ -0,0 +1,16 @@
+/** Public reason when diagnostics identify a service-side document-loading failure. */
+export const documentConvertLoadInternalErrorReason = 'LibreOffice could not load the document. Please contact support.';
+/** Public reason for a load refusal without evidence of a service-side failure. */
+export const documentConvertLoadUserErrorReason = 'LibreOffice could not load the document. It may be damaged, password-protected, or in an unsupported format. If it opens elsewhere, please contact support.';
+/** DocumentConvertRobot error payloads shared by runtime and the Assembly Status contract. */
+export const documentConvertRobotErrors = {
+    DOCUMENT_CONVERT_VALIDATION: {
+        error: 'DOCUMENT_CONVERT_VALIDATION',
+        http_code: 400,
+    },
+    DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION: {
+        error: 'DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION',
+        http_code: 400,
+        message: "The conversion from the input file's format to the desired output format is not supported.",
+    },
+};

package/dist/v3/robots/document-convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-convert.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/document-convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAW1B,4FAA4F;AAC5F,eAAO,MAAM,8BAA8B,iNAE1C,CAAA;AAED,eAAO,MAAM,IAAI,EAAE,cAwElB,CAAA;AAED,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4KxC,CAAA;AAEX,eAAO,MAAM,eAAe,EAAE,eAAe,CAAC,OAAO,sCAAsC,CAAC,KAAK,CACtC,CAAA;AAE3D,eAAO,MACa,sDAAsD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACxD,oDAAoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAElE,oEAAoE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACrD,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,gCAAgC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACrE,MAAM,MAAM,gDAAgD,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AAC3F,MAAM,MAAM,8CAA8C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AAChG,MAAM,MAAM,mDAAmD,GAC7D,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACrC,MAAM,MAAM,8DAA8D,GACxE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,mEAAmE,GAC7E,YAAY,CAAC,2BAA2B,CAAC,CAAA"}
+{"version":3,"file":"document-convert.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/document-convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAsB1B,4FAA4F;AAC5F,eAAO,MAAM,8BAA8B,iNAE1C,CAAA;AAQD,eAAO,MAAM,IAAI,EAAE,cA4ElB,CAAA;AAED,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgLxC,CAAA;AAEX,eAAO,MAAM,eAAe,EAAE,eAAe,CAAC,OAAO,sCAAsC,CAAC,KAAK,CACtC,CAAA;AAE3D,eAAO,MACa,sDAAsD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACxD,oDAAoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAElE,oEAAoE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACrD,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,gCAAgC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACrE,MAAM,MAAM,gDAAgD,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AAC3F,MAAM,MAAM,8CAA8C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AAChG,MAAM,MAAM,mDAAmD,GAC7D,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACrC,MAAM,MAAM,8DAA8D,GACxE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,mEAAmE,GAC7E,YAAY,CAAC,2BAA2B,CAAC,CAAA"}

package/dist/v3/robots/document-convert.js

@@ -1,8 +1,19 @@
 import { z } from 'zod/v3';
 import { zodCaseInsensitiveEnum } from "../lib/zodInputSemantics.js";
+import { documentConvertLoadInternalErrorReason, documentConvertLoadUserErrorReason, } from "../responseErrors/DocumentConvertRobot.js";
 import { createProcessingExample, defineRobot, robotBase, robotDocumentProcessingMeta, robotUse, } from "./_instructions-primitives.js";
+const transcriptSrtDocumentation = 'Timestamped JSON from `/speech/transcribe` with `"format": "json"` can be converted to SRT. ' +
+    'Set `"format": "srt"` here. JSON words are grouped into cues of up to three words, breaking ' +
+    'at sentence endings and pauses longer than 0.4 seconds. Casing and punctuation are preserved. ' +
+    'JSON input is limited to 32 MiB and is only supported for SRT output. ' +
+    'SRT-to-SRT copies the original cues unchanged.';
 /** Accepts Playwright's paper-format case variants while publishing canonical spellings. */
 export const documentConvertPdfFormatSchema = zodCaseInsensitiveEnum(z.enum(['A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'Ledger', 'Legal', 'Letter', 'Tabloid']));
+const documentLoadErrorDocumentation = `
+A generic LibreOffice load refusal returns \`USER_COMMAND_ERROR\` with the reason “${documentConvertLoadUserErrorReason}” This preserves the user error code for integrations without assuming the document is corrupt.
+
+When diagnostics identify a problem in the conversion service, the load failure returns \`INTERNAL_COMMAND_ERROR\` with the reason “${documentConvertLoadInternalErrorReason}” Private diagnostics are not included in either response.
+`;
 export const meta = {
     ...robotDocumentProcessingMeta,
     example_code: createProcessingExample('converted', '/document/convert', {
@@ -20,6 +31,10 @@ Using this <dfn>Robot</dfn>, you can bypass the issues that certain file types m
 > ![Warning]
 > A general rule of this <dfn>Robot</dfn> is that converting files into an alien format category will result in an error. For example, SRT files can be converted into the VTT format, but not to an image.
 
+${documentLoadErrorDocumentation}
+
+${transcriptSrtDocumentation}
+
 The following file formats can be converted from:
 
 - \`ai\`
@@ -89,6 +104,10 @@ Using this Robot, you can bypass the issues that certain file types may bring, b
 > [!Warning]
 > A general rule of this Robot is that converting files into an alien format category will result in an error. For example, SRT files can be converted into the VTT format (and vice versa), but not to an image.
 
+${documentLoadErrorDocumentation}
+
+${transcriptSrtDocumentation}
+
 The following file formats can be converted from:
 
 - \`ai\`

package/dist/v3/robots/document-extract.d.ts

@@ -1,5 +1,17 @@
 import type { RobotDefinition, RobotMetaInput, RobotSchemaVariantTypes } from './_instructions-primitives.ts';
 import { z } from 'zod/v3';
+/** Validate OCR dependencies after interpolation-aware parsing at the Assembly Step boundary. */
+export declare function refineDocumentExtractOcr(step: {
+    robot: string;
+    extract?: unknown;
+    text_method?: unknown;
+    ocr_provider?: unknown;
+    password?: unknown;
+    page_range?: unknown;
+    text_granularity?: unknown;
+}, context: z.RefinementCtx, options?: {
+    allowInterpolation?: boolean;
+}): void;
 export declare const meta: RobotMetaInput;
 export declare const robotDocumentExtractInstructionsSchema: z.ZodObject<{
     interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "true" | "false">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "true" | "false">>]>>;
@@ -80,9 +92,9 @@ export declare const robotDocumentExtractInstructionsSchema: z.ZodObject<{
     user_meta: Record<string, unknown>;
     force_accept: boolean;
     ignore_errors: string[];
+    text_granularity: "document" | "page";
     text_method: "auto" | "native" | "ocr";
     text_format: "json" | "txt";
-    text_granularity: "document" | "page";
     image_format: "auto" | "jpg" | "png" | "original";
     min_image_width: number;
     min_image_height: number;
@@ -107,8 +119,8 @@ export declare const robotDocumentExtractInstructionsSchema: z.ZodObject<{
     output_meta?: boolean | string[] | Record<string, boolean> | undefined;
     queue?: "batch" | undefined;
     password?: string | undefined;
-    page_range?: string | undefined;
     ocr_provider?: "aws" | "gcp" | undefined;
+    page_range?: string | undefined;
 }, {
     robot: "/document/extract";
     extract?: "text" | "images" | ("text" | "images")[] | undefined;
@@ -134,11 +146,11 @@ export declare const robotDocumentExtractInstructionsSchema: z.ZodObject<{
     force_accept?: boolean | undefined;
     ignore_errors?: boolean | ("meta" | "execute")[] | undefined;
     password?: string | undefined;
-    text_method?: "auto" | "native" | "ocr" | undefined;
-    page_range?: string | undefined;
     ocr_provider?: "aws" | "gcp" | undefined;
-    text_format?: "json" | "txt" | undefined;
+    page_range?: string | undefined;
     text_granularity?: "document" | "page" | undefined;
+    text_method?: "auto" | "native" | "ocr" | undefined;
+    text_format?: "json" | "txt" | undefined;
     image_format?: "auto" | "jpg" | "png" | "original" | undefined;
     min_image_width?: number | undefined;
     min_image_height?: number | undefined;
@@ -224,9 +236,9 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     user_meta: Record<string, unknown>;
     force_accept: boolean;
     ignore_errors: string[];
+    text_granularity: "document" | "page";
     text_method: "auto" | "native" | "ocr";
     text_format: "json" | "txt";
-    text_granularity: "document" | "page";
     image_format: "auto" | "jpg" | "png" | "original";
     min_image_width: number;
     min_image_height: number;
@@ -252,8 +264,8 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     output_meta?: boolean | string[] | Record<string, boolean> | undefined;
     queue?: "batch" | undefined;
     password?: string | undefined;
-    page_range?: string | undefined;
     ocr_provider?: "aws" | "gcp" | undefined;
+    page_range?: string | undefined;
 }, {
     robot: "/document/extract";
     extract?: "text" | "images" | ("text" | "images")[] | undefined;
@@ -279,11 +291,11 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     force_accept?: boolean | undefined;
     ignore_errors?: boolean | ("meta" | "execute")[] | undefined;
     password?: string | undefined;
-    text_method?: "auto" | "native" | "ocr" | undefined;
-    page_range?: string | undefined;
     ocr_provider?: "aws" | "gcp" | undefined;
-    text_format?: "json" | "txt" | undefined;
+    page_range?: string | undefined;
     text_granularity?: "document" | "page" | undefined;
+    text_method?: "auto" | "native" | "ocr" | undefined;
+    text_format?: "json" | "txt" | undefined;
     image_format?: "auto" | "jpg" | "png" | "original" | undefined;
     min_image_width?: number | undefined;
     min_image_height?: number | undefined;
@@ -367,9 +379,9 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     user_meta: Record<string, unknown>;
     force_accept: string | boolean;
     ignore_errors: string | string[];
+    text_granularity: string;
     text_method: string;
     text_format: string;
-    text_granularity: string;
     image_format: string;
     min_image_width: string | number;
     min_image_height: string | number;
@@ -394,8 +406,8 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     output_meta?: string | boolean | string[] | Record<string, string | boolean> | undefined;
     queue?: string | undefined;
     password?: string | undefined;
-    page_range?: string | undefined;
     ocr_provider?: string | undefined;
+    page_range?: string | undefined;
 }, {
     robot: "/document/extract";
     extract?: string | string[] | undefined;
@@ -421,11 +433,11 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     force_accept?: string | boolean | undefined;
     ignore_errors?: string | boolean | ("meta" | "execute")[] | undefined;
     password?: string | undefined;
-    text_method?: string | undefined;
-    page_range?: string | undefined;
     ocr_provider?: string | undefined;
-    text_format?: string | undefined;
+    page_range?: string | undefined;
     text_granularity?: string | undefined;
+    text_method?: string | undefined;
+    text_format?: string | undefined;
     image_format?: string | undefined;
     min_image_width?: string | number | undefined;
     min_image_height?: string | number | undefined;
@@ -508,9 +520,9 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     user_meta: Record<string, unknown>;
     force_accept: string | boolean;
     ignore_errors: string | string[];
+    text_granularity: string;
     text_method: string;
     text_format: string;
-    text_granularity: string;
     image_format: string;
     min_image_width: string | number;
     min_image_height: string | number;
@@ -536,8 +548,8 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     output_meta?: string | boolean | string[] | Record<string, string | boolean> | undefined;
     queue?: string | undefined;
     password?: string | undefined;
-    page_range?: string | undefined;
     ocr_provider?: string | undefined;
+    page_range?: string | undefined;
 }, {
     robot: "/document/extract";
     extract?: string | string[] | undefined;
@@ -563,11 +575,11 @@ export declare const robotDocumentExtractInstructionsWithHiddenFieldsSchema: z.Z
     force_accept?: string | boolean | undefined;
     ignore_errors?: string | boolean | ("meta" | "execute")[] | undefined;
     password?: string | undefined;
-    text_method?: string | undefined;
-    page_range?: string | undefined;
     ocr_provider?: string | undefined;
-    text_format?: string | undefined;
+    page_range?: string | undefined;
     text_granularity?: string | undefined;
+    text_method?: string | undefined;
+    text_format?: string | undefined;
     image_format?: string | undefined;
     min_image_width?: string | number | undefined;
     min_image_height?: string | number | undefined;

package/dist/v3/robots/document-extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-extract.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/document-extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAkB1B,eAAO,MAAM,IAAI,EAAE,cAclB,CAAA;AAED,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuGxC,CAAA;AAEX,eAAO,MAAM,eAAe,EAAE,eAAe,CAAC,OAAO,sCAAsC,CAAC,KAAK,CACtC,CAAA;AAE3D,eAAO,MACa,sDAAsD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACxD,oDAAoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAElE,oEAAoE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACrD,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,gCAAgC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACrE,MAAM,MAAM,gDAAgD,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AAC3F,MAAM,MAAM,8CAA8C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AAChG,MAAM,MAAM,mDAAmD,GAC7D,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACrC,MAAM,MAAM,8DAA8D,GACxE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,mEAAmE,GAC7E,YAAY,CAAC,2BAA2B,CAAC,CAAA"}
+{"version":3,"file":"document-extract.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/document-extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAmB1B,iGAAiG;AACjG,wBAAgB,wBAAwB,CACtC,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B,EACD,OAAO,EAAE,CAAC,CAAC,aAAa,EACxB,OAAO,GAAE;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7C,IAAI,CA4DN;AAED,eAAO,MAAM,IAAI,EAAE,cAclB,CAAA;AAED,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuGxC,CAAA;AAEX,eAAO,MAAM,eAAe,EAAE,eAAe,CAAC,OAAO,sCAAsC,CAAC,KAAK,CACtC,CAAA;AAE3D,eAAO,MACa,sDAAsD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACxD,oDAAoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAElE,oEAAoE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACrD,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,gCAAgC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACrE,MAAM,MAAM,gDAAgD,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AAC3F,MAAM,MAAM,8CAA8C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AAChG,MAAM,MAAM,mDAAmD,GAC7D,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACrC,MAAM,MAAM,8DAA8D,GACxE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,mEAAmE,GAC7E,YAAY,CAAC,2BAA2B,CAAC,CAAA"}

package/dist/v3/robots/document-extract.js

@@ -1,12 +1,62 @@
 import { z } from 'zod/v3';
 import { ecmaWhitespaceCharacterClass } from "../lib/zodInputSemantics.js";
-import { createProcessingExample, defineRobot, robotBase, robotDocumentProcessingMeta, robotUse, } from "./_instructions-primitives.js";
+import { createProcessingExample, defineRobot, interpolationSchemaFull, robotBase, robotDocumentProcessingMeta, robotUse, } from "./_instructions-primitives.js";
 const extractTargets = z.enum(['text', 'images']);
 const imageFormats = z.enum(['auto', 'original', 'png', 'jpg']);
 const ocrProviders = z.enum(['aws', 'gcp']);
 const textFormats = z.enum(['txt', 'json']);
 const textGranularities = z.enum(['document', 'page']);
 const textMethods = z.enum(['native', 'ocr', 'auto']);
+/** Validate OCR dependencies after interpolation-aware parsing at the Assembly Step boundary. */
+export function refineDocumentExtractOcr(step, context, options = {}) {
+    if (step.robot !== '/document/extract')
+        return;
+    if (step.text_method !== 'ocr' && step.text_method !== 'auto')
+        return;
+    // Image-only extraction never invokes OCR; unresolved targets are checked at runtime.
+    const extractsText = step.extract === undefined ||
+        step.extract === 'text' ||
+        (Array.isArray(step.extract) && step.extract.includes('text'));
+    if (!extractsText)
+        return;
+    if (step.ocr_provider === undefined) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['ocr_provider'],
+            message: 'The ocr_provider parameter is required when text_method is ocr or auto.',
+        });
+    }
+    // Assembly Steps preserve opaque interpolation until the Robot checks the resolved values.
+    // Builtin fields can opt out because those values are already resolved at their boundary.
+    // Keep these constraints aligned with the matching stepJsonInputSchema branch in template.ts.
+    if (step.password !== undefined &&
+        step.password !== '' &&
+        !(options.allowInterpolation !== false &&
+            interpolationSchemaFull.safeParse(step.password).success)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['password'],
+            message: 'The password parameter is only supported for native text extraction and embedded image extraction.',
+        });
+    }
+    // Defer full page-range interpolation to runtime, consistently with the other unresolved fields.
+    if (step.page_range !== undefined &&
+        !(options.allowInterpolation !== false &&
+            interpolationSchemaFull.safeParse(step.page_range).success)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['page_range'],
+            message: 'The page_range parameter is only supported for native text extraction.',
+        });
+    }
+    if (step.text_granularity === 'page') {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['text_granularity'],
+            message: 'The page text_granularity is only supported for native text extraction.',
+        });
+    }
+}
 export const meta = {
     ...robotDocumentProcessingMeta,
     example_code: createProcessingExample('extracted', '/document/extract', {

package/dist/v3/robots/html-convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-convert.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/html-convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+BAA+B,EAC/B,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAS1B,eAAO,MAAM,IAAI,EAAE,cA4BlB,CAAA;AAED,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgFpC,CAAA;AAEX,QAAA,MAAM,YAAY;;;;CAIjB,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,+BAA+B,CAC3D,OAAO,kCAAkC,CAAC,KAAK,EAC/C,OAAO,YAAY,CACkE,CAAA;AAEvF,eAAO,MACa,kDAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACpD,gDAAgD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAChC,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAC/E,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,4BAA4B,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACjE,MAAM,MAAM,4CAA4C,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AACvF,MAAM,MAAM,0CAA0C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AAC5F,MAAM,MAAM,+CAA+C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACjG,MAAM,MAAM,0DAA0D,GACpE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,+DAA+D,GACzE,YAAY,CAAC,2BAA2B,CAAC,CAAA"}
+{"version":3,"file":"html-convert.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/html-convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+BAA+B,EAC/B,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAS1B,eAAO,MAAM,IAAI,EAAE,cA4BlB,CAAA;AAED,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiFpC,CAAA;AAEX,QAAA,MAAM,YAAY;;;;CAIjB,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,+BAA+B,CAC3D,OAAO,kCAAkC,CAAC,KAAK,EAC/C,OAAO,YAAY,CACkE,CAAA;AAEvF,eAAO,MACa,kDAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACpD,gDAAgD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAChC,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAC/E,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,4BAA4B,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACjE,MAAM,MAAM,4CAA4C,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AACvF,MAAM,MAAM,0CAA0C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AAC5F,MAAM,MAAM,+CAA+C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACjG,MAAM,MAAM,0DAA0D,GACpE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,+DAA+D,GACzE,YAAY,CAAC,2BAA2B,CAAC,CAAA"}

package/dist/v3/robots/html-convert.js

@@ -43,6 +43,7 @@ Use [🤖/image/resize](/docs/robots/image-resize/) to resize or crop the screen
         .default(null)
         .describe(`
 The URL of the web page to be converted. Optional, as you can also upload/import HTML files and pass it to this <dfn>Robot</dfn>.
+Omit it, or use \`null\` or an empty string, to convert uploaded HTML instead.
 `),
     format: z
         .enum(['jpeg', 'jpg', 'pdf', 'png'])

package/dist/v3/robots/speech-transcribe.d.ts

@@ -1,5 +1,7 @@
 import type { RobotDefinitionWithHiddenFields, RobotMetaInput, RobotSchemaVariantTypes } from './_instructions-primitives.ts';
 import { z } from 'zod/v3';
+/** Shared vocabulary limits keep inline hints within GCP and Whisper prompt budgets. */
+export declare const speechTranscribeVocabularySchema: z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>;
 export declare const meta: RobotMetaInput;
 export declare const robotSpeechTranscribeInstructionsSchema: z.ZodObject<{
     interpolate: z.ZodOptional<z.ZodUnion<[z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "true" | "false">, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false"]>]>, boolean, boolean | "true" | "false">>]>>;
@@ -61,6 +63,7 @@ export declare const robotSpeechTranscribeInstructionsSchema: z.ZodObject<{
 } & {
     robot: z.ZodLiteral<"/speech/transcribe">;
     provider: z.ZodDefault<z.ZodEnum<["auto", "aws", "gcp", "replicate"]>>;
+    vocabulary: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
     granularity: z.ZodDefault<z.ZodEnum<["full", "list"]>>;
     format: z.ZodDefault<z.ZodEnum<["json", "meta", "srt", "text", "webvtt"]>>;
     speaker_labels: z.ZodDefault<z.ZodBoolean>;
@@ -97,6 +100,7 @@ export declare const robotSpeechTranscribeInstructionsSchema: z.ZodObject<{
     output_meta?: boolean | string[] | Record<string, boolean> | undefined;
     queue?: "batch" | undefined;
     target_language?: string | undefined;
+    vocabulary?: string[] | undefined;
 }, {
     robot: "/speech/transcribe";
     result?: boolean | undefined;
@@ -124,6 +128,7 @@ export declare const robotSpeechTranscribeInstructionsSchema: z.ZodObject<{
     format?: "json" | "text" | "meta" | "srt" | "webvtt" | undefined;
     granularity?: "full" | "list" | undefined;
     target_language?: string | undefined;
+    vocabulary?: string[] | undefined;
     speaker_labels?: boolean | undefined;
     max_speakers?: number | undefined;
     source_language?: string | undefined;
@@ -189,6 +194,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
         group_by_original?: boolean | undefined;
     }>]>>;
     robot: z.ZodLiteral<"/speech/transcribe">;
+    vocabulary: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
     granularity: z.ZodDefault<z.ZodEnum<["full", "list"]>>;
     format: z.ZodDefault<z.ZodEnum<["json", "meta", "srt", "text", "webvtt"]>>;
     speaker_labels: z.ZodDefault<z.ZodBoolean>;
@@ -230,6 +236,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
     output_meta?: boolean | string[] | Record<string, boolean> | undefined;
     queue?: "batch" | undefined;
     target_language?: string | undefined;
+    vocabulary?: string[] | undefined;
 }, {
     robot: "/speech/transcribe";
     result?: boolean | "debug" | undefined;
@@ -258,6 +265,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
     format?: "json" | "text" | "meta" | "srt" | "webvtt" | undefined;
     granularity?: "full" | "list" | undefined;
     target_language?: string | undefined;
+    vocabulary?: string[] | undefined;
     speaker_labels?: boolean | undefined;
     max_speakers?: number | undefined;
     source_language?: string | undefined;
@@ -319,6 +327,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
     }>]>>;
     robot: z.ZodLiteral<"/speech/transcribe">;
     provider: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<["auto", "aws", "gcp", "replicate"]>]>>;
+    vocabulary: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>]>>;
     granularity: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<["full", "list"]>]>>;
     format: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<["json", "meta", "srt", "text", "webvtt"]>]>>;
     speaker_labels: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
@@ -355,6 +364,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
     output_meta?: string | boolean | string[] | Record<string, string | boolean> | undefined;
     queue?: string | undefined;
     target_language?: string | undefined;
+    vocabulary?: string | string[] | undefined;
 }, {
     robot: "/speech/transcribe";
     result?: string | boolean | undefined;
@@ -382,6 +392,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
     format?: string | undefined;
     granularity?: string | undefined;
     target_language?: string | undefined;
+    vocabulary?: string | string[] | undefined;
     speaker_labels?: string | boolean | undefined;
     max_speakers?: string | number | undefined;
     source_language?: string | undefined;
@@ -441,6 +452,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
         group_by_original?: boolean | undefined;
     }>]>>;
     robot: z.ZodLiteral<"/speech/transcribe">;
+    vocabulary: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>]>>;
     granularity: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<["full", "list"]>]>>;
     format: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodEnum<["json", "meta", "srt", "text", "webvtt"]>]>>;
     speaker_labels: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
@@ -481,6 +493,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
     output_meta?: string | boolean | string[] | Record<string, string | boolean> | undefined;
     queue?: string | undefined;
     target_language?: string | undefined;
+    vocabulary?: string | string[] | undefined;
 }, {
     robot: "/speech/transcribe";
     result?: string | boolean | undefined;
@@ -509,6 +522,7 @@ export declare const robotSpeechTranscribeInstructionsWithHiddenFieldsSchema: z.
     format?: string | undefined;
     granularity?: string | undefined;
     target_language?: string | undefined;
+    vocabulary?: string | string[] | undefined;
     speaker_labels?: string | boolean | undefined;
     max_speakers?: string | number | undefined;
     source_language?: string | undefined;

package/dist/v3/robots/speech-transcribe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"speech-transcribe.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/speech-transcribe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+BAA+B,EAC/B,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAiB1B,eAAO,MAAM,IAAI,EAAE,cA2BlB,CAAA;AAED,eAAO,MAAM,uCAAuC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsGzC,CAAA;AAEX,QAAA,MAAM,YAAY;;;CAGjB,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,+BAA+B,CAC3D,OAAO,uCAAuC,CAAC,KAAK,EACpD,OAAO,YAAY,CACuE,CAAA;AAE5F,eAAO,MACa,uDAAuD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACzD,qDAAqD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEnE,qEAAqE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACtD,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,iCAAiC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACtE,MAAM,MAAM,iDAAiD,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AAC5F,MAAM,MAAM,+CAA+C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACjG,MAAM,MAAM,oDAAoD,GAC9D,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACrC,MAAM,MAAM,+DAA+D,GACzE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,oEAAoE,GAC9E,YAAY,CAAC,2BAA2B,CAAC,CAAA"}
+{"version":3,"file":"speech-transcribe.d.ts","sourceRoot":"","sources":["../../../src/v3/robots/speech-transcribe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+BAA+B,EAC/B,cAAc,EACd,uBAAuB,EACxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAkB1B,wFAAwF;AACxF,eAAO,MAAM,gCAAgC,qGAoB5C,CAAA;AAED,eAAO,MAAM,IAAI,EAAE,cA2BlB,CAAA;AAED,eAAO,MAAM,uCAAuC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2HzC,CAAA;AAEX,QAAA,MAAM,YAAY;;;CAGjB,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,+BAA+B,CAC3D,OAAO,uCAAuC,CAAC,KAAK,EACpD,OAAO,YAAY,CACuE,CAAA;AAE5F,eAAO,MACa,uDAAuD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACzD,qDAAqD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEnE,qEAAqE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACtD,CAAA;AAEnB,KAAK,YAAY,GAAG,uBAAuB,CAAC,OAAO,eAAe,CAAC,CAAA;AAEnE,MAAM,MAAM,iCAAiC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AACtE,MAAM,MAAM,iDAAiD,GAAG,YAAY,CAAC,cAAc,CAAC,CAAA;AAC5F,MAAM,MAAM,+CAA+C,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACjG,MAAM,MAAM,oDAAoD,GAC9D,YAAY,CAAC,qBAAqB,CAAC,CAAA;AACrC,MAAM,MAAM,+DAA+D,GACzE,YAAY,CAAC,4BAA4B,CAAC,CAAA;AAC5C,MAAM,MAAM,oEAAoE,GAC9E,YAAY,CAAC,2BAA2B,CAAC,CAAA"}

package/dist/v3/robots/speech-transcribe.js

@@ -1,9 +1,28 @@
 import { z } from 'zod/v3';
+import { zodWithConservativeJsonInputSchema } from "../lib/zodInputSemantics.js";
 import { autoProviderDescription, createProcessingExample, defineRobotWithHiddenFields, granularitySchema, robotArtificialIntelligenceMeta, robotBase, robotUse, } from "./_instructions-primitives.js";
 const speechTranscribeProviderSchema = z.enum(['auto', 'aws', 'gcp', 'replicate']).default('auto');
 const speechTranscribeProviderWithHiddenFieldsSchema = z
     .enum(['auto', 'aws', 'gcp', 'replicate', 'transloadit'])
     .default('auto');
+/** Shared vocabulary limits keep inline hints within GCP and Whisper prompt budgets. */
+export const speechTranscribeVocabularySchema = zodWithConservativeJsonInputSchema(z
+    .array(z
+    .string()
+    .trim()
+    .min(1)
+    .max(100)
+    .regex(/^[^\p{Cc}]+$/u))
+    .max(50)
+    .refine((terms) => new Set(terms.map((term) => term.toLowerCase())).size === terms.length, {
+    message: 'Vocabulary terms must be unique, ignoring case.',
+})
+    // Byte-level tokenization uses at most one token per byte. Reserve room for sentence styling.
+    .refine((terms) => new TextEncoder().encode(terms.join(', ')).byteLength <= 200, {
+    message: 'Vocabulary terms joined with comma-space must not exceed 200 UTF-8 bytes.',
+}), 
+// Trimming, Unicode case uniqueness and a joined UTF-8 budget have no portable JSON Schema form.
+z.array(z.string().min(1)).max(50));
 export const meta = {
     ...robotArtificialIntelligenceMeta,
     example_code: createProcessingExample('transcribed', '/speech/transcribe', {
@@ -58,7 +77,8 @@ recurring speakers:
 \`\`\`
 
 Speaker labels are currently supported by the \`aws\` and \`gcp\` providers. If you enable
-\`speaker_labels\` without setting \`provider\`, Transloadit uses \`aws\` for that <dfn>Step</dfn>. Labels
+\`speaker_labels\` without setting \`provider\`, Transloadit uses \`aws\` for that <dfn>Step</dfn>, or
+\`gcp\` when \`vocabulary\` is also supplied. Labels
 are normalized as \`speaker_1\`, \`speaker_2\`, and so on:
 
 \`\`\`json
@@ -81,7 +101,27 @@ ${autoProviderDescription}
 
 Set this to \`"aws"\`, \`"gcp"\`, or \`"replicate"\` to force a specific provider.
 When set to \`"auto"\`, Transloadit uses \`"replicate"\` by default and uses \`"aws"\` when
-\`speaker_labels\` is enabled.
+\`speaker_labels\` is enabled. If both \`speaker_labels\` and a nonempty \`vocabulary\` are set,
+\`"auto"\` uses \`"gcp"\`.
+`),
+    vocabulary: speechTranscribeVocabularySchema.optional().describe(`
+Words or phrases to favor during speech recognition, using the spelling you want in the output.
+For example, \`["Transloadit", "Uppy", "tus"]\` helps the provider recognize brand and product names.
+
+Supply up to 50 distinct terms, each between 1 and 100 characters after trimming surrounding
+whitespace. Terms must not contain control characters or case-insensitive duplicates. The terms
+joined with \`", "\` must fit within 200 UTF-8 bytes, keeping all terms within Whisper’s prompt
+budget. Omitting this parameter or supplying an empty array leaves recognition unchanged.
+
+Supported by \`"replicate"\` and \`"gcp"\`. Replicate uses a prompt-capable WhisperX large-v3 model
+with aligned word timestamps when vocabulary is supplied. GCP uses inline boosted phrase hints.
+Explicit \`"aws"\` requests with vocabulary return a validation error because AWS requires a
+pre-created Custom Vocabulary. Use \`"auto"\`, \`"replicate"\`, or \`"gcp"\` instead.
+
+Hints improve recognition but do not guarantee that a term is recognized. Afterwards, complete
+case-insensitive matches use your supplied spelling in every output format, including JSON words
+and speaker segments, without changing timestamps. Similar-sounding words are never replaced:
+\`"transloadit"\` becomes \`"Transloadit"\`, but \`"Transloaded"\` stays unchanged.
 `),
     granularity: granularitySchema.describe(`
 Both \`"full"\` and \`"list"\` currently return the same complete transcription response. \`"list"\` remains accepted for backward compatibility.