@ai-sdk/provider-utils 4.0.10 → 4.0.11

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @ai-sdk/provider-utils
 
+## 4.0.11
+
+### Patch Changes
+
+- 2810850: fix(ai): improve type validation error messages with field paths and entity identifiers
+- Updated dependencies [2810850]
+  - @ai-sdk/provider@3.0.6
+
 ## 4.0.10
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { LanguageModelV3FunctionTool, LanguageModelV3ProviderTool, ImageModelV3File, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV3Prompt, SharedV3ProviderOptions } from '@ai-sdk/provider';
+import { LanguageModelV3FunctionTool, LanguageModelV3ProviderTool, ImageModelV3File, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV3Prompt, SharedV3ProviderOptions, TypeValidationContext } from '@ai-sdk/provider';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 export * from '@standard-schema/spec';
 import * as z3 from 'zod/v3';
@@ -82,11 +82,11 @@ declare class DelayedPromise<T> {
 }
 
 /**
-Extracts the headers from a response object and returns them as a key-value object.
-
-@param response - The response object to extract headers from.
-@returns The headers as a key-value object.
-*/
+ * Extracts the headers from a response object and returns them as a key-value object.
+ *
+ * @param response - The response object to extract headers from.
+ * @returns The headers as a key-value object.
+ */
 declare function extractResponseHeaders(response: Response): {
     [k: string]: string;
 };
@@ -167,14 +167,14 @@ declare class DownloadError extends AISDKError {
 type FetchFunction = typeof globalThis.fetch;
 
 /**
-Creates an ID generator.
-The total length of the ID is the sum of the prefix, separator, and random part length.
-Not cryptographically secure.
-
-@param alphabet - The alphabet to use for the ID. Default: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'.
-@param prefix - The prefix of the ID to generate. Optional.
-@param separator - The separator between the prefix and the random part of the ID. Default: '-'.
-@param size - The size of the random part of the ID to generate. Default: 16.
+ * Creates an ID generator.
+ * The total length of the ID is the sum of the prefix, separator, and random part length.
+ * Not cryptographically secure.
+ *
+ * @param alphabet - The alphabet to use for the ID. Default: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'.
+ * @param prefix - The prefix of the ID to generate. Optional.
+ * @param separator - The separator between the prefix and the random part of the ID. Default: '-'.
+ * @param size - The size of the random part of the ID to generate. Default: 16.
  */
 declare const createIdGenerator: ({ prefix, size, alphabet, separator, }?: {
     prefix?: string;
@@ -183,12 +183,12 @@ declare const createIdGenerator: ({ prefix, size, alphabet, separator, }?: {
     alphabet?: string;
 }) => IdGenerator;
 /**
-A function that generates an ID.
+ * A function that generates an ID.
  */
 type IdGenerator = () => string;
 /**
-Generates a 16-character random string to use for IDs.
-Not cryptographically secure.
+ * Generates a 16-character random string to use for IDs.
+ * Not cryptographically secure.
  */
 declare const generateId: IdGenerator;
 
@@ -497,86 +497,86 @@ declare const postToApi: <T>({ url, headers, body, successfulResponseHandler, fa
 }>;
 
 /**
-Data content. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
+ * Data content. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
  */
 type DataContent = string | Uint8Array | ArrayBuffer | Buffer;
 
 /**
-Additional provider-specific options.
-
-They are passed through to the provider from the AI SDK and enable
-provider-specific functionality that can be fully encapsulated in the provider.
+ * Additional provider-specific options.
+ *
+ * They are passed through to the provider from the AI SDK and enable
+ * provider-specific functionality that can be fully encapsulated in the provider.
  */
 type ProviderOptions = SharedV3ProviderOptions;
 
 /**
-Text content part of a prompt. It contains a string of text.
+ * Text content part of a prompt. It contains a string of text.
  */
 interface TextPart {
     type: 'text';
     /**
-  The text content.
+     * The text content.
      */
     text: string;
     /**
-  Additional provider-specific metadata. They are passed through
-  to the provider from the AI SDK and enable provider-specific
-  functionality that can be fully encapsulated in the provider.
-   */
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
     providerOptions?: ProviderOptions;
 }
 /**
-Image content part of a prompt. It contains an image.
+ * Image content part of a prompt. It contains an image.
  */
 interface ImagePart {
     type: 'image';
     /**
-  Image data. Can either be:
-  
-  - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
-  - URL: a URL that points to the image
+     * Image data. Can either be:
+     *
+     * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+     * - URL: a URL that points to the image
      */
     image: DataContent | URL;
     /**
-  Optional IANA media type of the image.
-  
-  @see https://www.iana.org/assignments/media-types/media-types.xhtml
+     * Optional IANA media type of the image.
+     *
+     * @see https://www.iana.org/assignments/media-types/media-types.xhtml
      */
     mediaType?: string;
     /**
-  Additional provider-specific metadata. They are passed through
-  to the provider from the AI SDK and enable provider-specific
-  functionality that can be fully encapsulated in the provider.
-   */
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
     providerOptions?: ProviderOptions;
 }
 /**
-File content part of a prompt. It contains a file.
+ * File content part of a prompt. It contains a file.
  */
 interface FilePart {
     type: 'file';
     /**
-  File data. Can either be:
-  
-  - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
-  - URL: a URL that points to the image
+     * File data. Can either be:
+     *
+     * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+     * - URL: a URL that points to the image
      */
     data: DataContent | URL;
     /**
-  Optional filename of the file.
+     * Optional filename of the file.
      */
     filename?: string;
     /**
-  IANA media type of the file.
-  
-  @see https://www.iana.org/assignments/media-types/media-types.xhtml
+     * IANA media type of the file.
+     *
+     * @see https://www.iana.org/assignments/media-types/media-types.xhtml
      */
     mediaType: string;
     /**
-  Additional provider-specific metadata. They are passed through
-  to the provider from the AI SDK and enable provider-specific
-  functionality that can be fully encapsulated in the provider.
-   */
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
     providerOptions?: ProviderOptions;
 }
 /**
@@ -585,66 +585,66 @@ interface FilePart {
 interface ReasoningPart {
     type: 'reasoning';
     /**
-  The reasoning text.
+     * The reasoning text.
      */
     text: string;
     /**
-  Additional provider-specific metadata. They are passed through
-  to the provider from the AI SDK and enable provider-specific
-  functionality that can be fully encapsulated in the provider.
-   */
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
     providerOptions?: ProviderOptions;
 }
 /**
-Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
+ * Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
  */
 interface ToolCallPart {
     type: 'tool-call';
     /**
-  ID of the tool call. This ID is used to match the tool call with the tool result.
-   */
+     * ID of the tool call. This ID is used to match the tool call with the tool result.
+     */
     toolCallId: string;
     /**
-  Name of the tool that is being called.
-   */
+     * Name of the tool that is being called.
+     */
     toolName: string;
     /**
-  Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+     * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
      */
     input: unknown;
     /**
-  Additional provider-specific metadata. They are passed through
-  to the provider from the AI SDK and enable provider-specific
-  functionality that can be fully encapsulated in the provider.
-   */
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
     providerOptions?: ProviderOptions;
     /**
-  Whether the tool call was executed by the provider.
-   */
+     * Whether the tool call was executed by the provider.
+     */
     providerExecuted?: boolean;
 }
 /**
-Tool result content part of a prompt. It contains the result of the tool call with the matching ID.
+ * Tool result content part of a prompt. It contains the result of the tool call with the matching ID.
  */
 interface ToolResultPart {
     type: 'tool-result';
     /**
-  ID of the tool call that this result is associated with.
-   */
+     * ID of the tool call that this result is associated with.
+     */
     toolCallId: string;
     /**
-  Name of the tool that generated this result.
-    */
+     * Name of the tool that generated this result.
+     */
     toolName: string;
     /**
-  Result of the tool call. This is a JSON-serializable object.
+     * Result of the tool call. This is a JSON-serializable object.
      */
     output: ToolResultOutput;
     /**
-  Additional provider-specific metadata. They are passed through
-  to the provider from the AI SDK and enable provider-specific
-  functionality that can be fully encapsulated in the provider.
-   */
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
     providerOptions?: ProviderOptions;
 }
 /**
@@ -699,8 +699,8 @@ type ToolResultOutput = {
     value: Array<{
         type: 'text';
         /**
-Text content.
-*/
+         * Text content.
+         */
         text: string;
         /**
          * Provider-specific options.
@@ -716,13 +716,13 @@ Text content.
     } | {
         type: 'file-data';
         /**
-Base-64 encoded media data.
-*/
+         * Base-64 encoded media data.
+         */
         data: string;
         /**
-IANA media type.
-@see https://www.iana.org/assignments/media-types/media-types.xhtml
-*/
+         * IANA media type.
+         * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+         */
         mediaType: string;
         /**
          * Optional filename of the file.
@@ -763,13 +763,13 @@ IANA media type.
          */
         type: 'image-data';
         /**
-Base-64 encoded image data.
-*/
+         * Base-64 encoded image data.
+         */
         data: string;
         /**
-IANA media type.
-@see https://www.iana.org/assignments/media-types/media-types.xhtml
-*/
+         * IANA media type.
+         * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+         */
         mediaType: string;
         /**
          * Provider-specific options.
@@ -835,39 +835,39 @@ type ToolApprovalRequest = {
 };
 
 /**
-An assistant message. It can contain text, tool calls, or a combination of text and tool calls.
+ * An assistant message. It can contain text, tool calls, or a combination of text and tool calls.
  */
 type AssistantModelMessage = {
     role: 'assistant';
     content: AssistantContent;
     /**
-    Additional provider-specific metadata. They are passed through
-    to the provider from the AI SDK and enable provider-specific
-    functionality that can be fully encapsulated in the provider.
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
      */
     providerOptions?: ProviderOptions;
 };
 /**
-Content of an assistant message.
-It can be a string or an array of text, image, reasoning, redacted reasoning, and tool call parts.
+ * Content of an assistant message.
+ * It can be a string or an array of text, image, reasoning, redacted reasoning, and tool call parts.
  */
 type AssistantContent = string | Array<TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart | ToolApprovalRequest>;
 
 /**
- A system message. It can contain system information.
-
- Note: using the "system" part of the prompt is strongly preferred
- to increase the resilience against prompt injection attacks,
- and because not all providers support several system messages.
+ * A system message. It can contain system information.
+ *
+ * Note: using the "system" part of the prompt is strongly preferred
+ * to increase the resilience against prompt injection attacks,
+ * and because not all providers support several system messages.
  */
 type SystemModelMessage = {
     role: 'system';
     content: string;
     /**
-      Additional provider-specific metadata. They are passed through
-      to the provider from the AI SDK and enable provider-specific
-      functionality that can be fully encapsulated in the provider.
-       */
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
     providerOptions?: ProviderOptions;
 };
 
@@ -896,44 +896,44 @@ type ToolApprovalResponse = {
 };
 
 /**
-A tool message. It contains the result of one or more tool calls.
+ * A tool message. It contains the result of one or more tool calls.
  */
 type ToolModelMessage = {
     role: 'tool';
     content: ToolContent;
     /**
-    Additional provider-specific metadata. They are passed through
-    to the provider from the AI SDK and enable provider-specific
-    functionality that can be fully encapsulated in the provider.
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
      */
     providerOptions?: ProviderOptions;
 };
 /**
-Content of a tool message. It is an array of tool result parts.
+ * Content of a tool message. It is an array of tool result parts.
  */
 type ToolContent = Array<ToolResultPart | ToolApprovalResponse>;
 
 /**
-A user message. It can contain text or a combination of text and images.
+ * A user message. It can contain text or a combination of text and images.
  */
 type UserModelMessage = {
     role: 'user';
     content: UserContent;
     /**
-      Additional provider-specific metadata. They are passed through
-      to the provider from the AI SDK and enable provider-specific
-      functionality that can be fully encapsulated in the provider.
-       */
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
     providerOptions?: ProviderOptions;
 };
 /**
-  Content of a user message. It can be a string or an array of text and image parts.
-   */
+ * Content of a user message. It can be a string or an array of text and image parts.
+ */
 type UserContent = string | Array<TextPart | ImagePart | FilePart>;
 
 /**
-A message that can be used in the `messages` field of a prompt.
-It can be a user message, an assistant message, or a tool message.
+ * A message that can be used in the `messages` field of a prompt.
+ * It can be a user message, an assistant message, or a tool message.
  */
 type ModelMessage = SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage;
 
@@ -992,12 +992,12 @@ type ToolExecuteFunction<INPUT, OUTPUT> = (input: INPUT, options: ToolExecutionO
 type NeverOptional<N, T> = 0 extends 1 & N ? Partial<T> : [N] extends [never] ? Partial<Record<keyof T, undefined>> : T;
 type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
     /**
-An async function that is called with the arguments from the tool call and produces a result.
-If not provided, the tool will not be executed automatically.
-
-@args is the input of the tool call.
-@options.abortSignal is a signal that can be used to abort the tool call.
-  */
+     * An async function that is called with the arguments from the tool call and produces a result.
+     * If not provided, the tool will not be executed automatically.
+     *
+     * @args is the input of the tool call.
+     * @options.abortSignal is a signal that can be used to abort the tool call.
+     */
     execute: ToolExecuteFunction<INPUT, OUTPUT>;
     outputSchema?: FlexibleSchema<OUTPUT>;
 } | {
@@ -1005,16 +1005,16 @@ If not provided, the tool will not be executed automatically.
     execute?: never;
 }>;
 /**
-A tool contains the description and the schema of the input that the tool expects.
-This enables the language model to generate the input.
-
-The tool can also contain an optional execute function for the actual execution function of the tool.
+ * A tool contains the description and the schema of the input that the tool expects.
+ * This enables the language model to generate the input.
+ *
+ * The tool can also contain an optional execute function for the actual execution function of the tool.
  */
 type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = {
     /**
-  An optional description of what the tool does.
-  Will be used by the language model to decide whether to use the tool.
-  Not used for provider-defined tools.
+     * An optional description of what the tool does.
+     * Will be used by the language model to decide whether to use the tool.
+     * Not used for provider-defined tools.
      */
     description?: string;
     /**
@@ -1022,9 +1022,9 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      */
     title?: string;
     /**
-  Additional provider-specific metadata. They are passed through
-  to the provider from the AI SDK and enable provider-specific
-  functionality that can be fully encapsulated in the provider.
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
      */
     providerOptions?: ProviderOptions;
     /**
@@ -1095,27 +1095,27 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
     }) => ToolResultOutput | PromiseLike<ToolResultOutput>;
 } & ({
     /**
-Tool with user-defined input and output schemas.
- */
+     * Tool with user-defined input and output schemas.
+     */
     type?: undefined | 'function';
 } | {
     /**
-Tool that is defined at runtime (e.g. an MCP tool).
-The types of input and output are not known at development time.
-   */
+     * Tool that is defined at runtime (e.g. an MCP tool).
+     * The types of input and output are not known at development time.
+     */
     type: 'dynamic';
 } | {
     /**
-Tool with provider-defined input and output schemas.
- */
+     * Tool with provider-defined input and output schemas.
+     */
     type: 'provider';
     /**
-The ID of the tool. Must follow the format `<provider-name>.<unique-tool-name>`.
-*/
+     * The ID of the tool. Must follow the format `<provider-name>.<unique-tool-name>`.
+     */
     id: `${string}.${string}`;
     /**
-The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.
- */
+     * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.
+     */
     args: Record<string, unknown>;
     /**
      * Whether this provider-executed tool supports deferred results.
@@ -1141,7 +1141,7 @@ type InferToolInput<TOOL extends Tool> = TOOL extends Tool<infer INPUT, any> ? I
  */
 type InferToolOutput<TOOL extends Tool> = TOOL extends Tool<any, infer OUTPUT> ? OUTPUT : never;
 /**
-Helper function for inferring the execute args of a tool.
+ * Helper function for inferring the execute args of a tool.
  */
 declare function tool<INPUT, OUTPUT>(tool: Tool<INPUT, OUTPUT>): Tool<INPUT, OUTPUT>;
 declare function tool<INPUT>(tool: Tool<INPUT, never>): Tool<INPUT, never>;
@@ -1245,11 +1245,13 @@ declare function convertToBase64(value: string | Uint8Array): string;
  * @template T - The type of the object to validate.
  * @param {string} options.value - The object to validate.
  * @param {Validator<T>} options.schema - The schema to use for validating the JSON.
+ * @param {TypeValidationContext} options.context - Optional context about what is being validated.
  * @returns {Promise<T>} - The typed object.
  */
-declare function validateTypes<OBJECT>({ value, schema, }: {
+declare function validateTypes<OBJECT>({ value, schema, context, }: {
     value: unknown;
     schema: FlexibleSchema<OBJECT>;
+    context?: TypeValidationContext;
 }): Promise<OBJECT>;
 /**
  * Safely validates the types of an unknown object using a schema and
@@ -1258,11 +1260,13 @@ declare function validateTypes<OBJECT>({ value, schema, }: {
  * @template T - The type of the object to validate.
  * @param {string} options.value - The JSON object to validate.
  * @param {Validator<T>} options.schema - The schema to use for validating the JSON.
+ * @param {TypeValidationContext} options.context - Optional context about what is being validated.
  * @returns An object with either a `success` flag and the parsed and typed data, or a `success` flag and an error object.
  */
-declare function safeValidateTypes<OBJECT>({ value, schema, }: {
+declare function safeValidateTypes<OBJECT>({ value, schema, context, }: {
     value: unknown;
     schema: FlexibleSchema<OBJECT>;
+    context?: TypeValidationContext;
 }): Promise<{
     success: true;
     value: OBJECT;
@@ -1302,20 +1306,20 @@ declare function executeTool<INPUT, OUTPUT>({ execute, input, options, }: {
 }>;
 
 /**
-Typed tool call that is returned by generateText and streamText.
-It contains the tool call ID, the tool name, and the tool arguments.
+ * Typed tool call that is returned by generateText and streamText.
+ * It contains the tool call ID, the tool name, and the tool arguments.
  */
 interface ToolCall<NAME extends string, INPUT> {
     /**
-  ID of the tool call. This ID is used to match the tool call with the tool result.
-   */
+     * ID of the tool call. This ID is used to match the tool call with the tool result.
+     */
     toolCallId: string;
     /**
-  Name of the tool that is being called.
-   */
+     * Name of the tool that is being called.
+     */
     toolName: NAME;
     /**
-  Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+     * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
      */
     input: INPUT;
     /**
@@ -1330,25 +1334,25 @@ interface ToolCall<NAME extends string, INPUT> {
 }
 
 /**
-Typed tool result that is returned by `generateText` and `streamText`.
-It contains the tool call ID, the tool name, the tool arguments, and the tool result.
+ * Typed tool result that is returned by `generateText` and `streamText`.
+ * It contains the tool call ID, the tool name, the tool arguments, and the tool result.
  */
 interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     /**
-  ID of the tool call. This ID is used to match the tool call with the tool result.
+     * ID of the tool call. This ID is used to match the tool call with the tool result.
      */
     toolCallId: string;
     /**
-  Name of the tool that was called.
+     * Name of the tool that was called.
      */
     toolName: NAME;
     /**
-  Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
-       */
+     * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+     */
     input: INPUT;
     /**
-  Result of the tool call. This is the result of the tool's execution.
-       */
+     * Result of the tool call. This is the result of the tool's execution.
+     */
     output: OUTPUT;
     /**
      * Whether the tool result has been executed by the provider.