@ai-sdk/provider-utils 4.0.0-beta.53 → 4.0.0-beta.55

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @ai-sdk/provider-utils
 
+## 4.0.0-beta.55
+
+### Patch Changes
+
+- 50b70d6: feat(anthropic): add programmatic tool calling
+
+## 4.0.0-beta.54
+
+### Patch Changes
+
+- 9061dc0: feat: image editing
+- Updated dependencies [9061dc0]
+  - @ai-sdk/provider@3.0.0-beta.28
+
 ## 4.0.0-beta.53
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { LanguageModelV3FunctionTool, LanguageModelV3ProviderTool, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV3Prompt, SharedV3ProviderOptions } from '@ai-sdk/provider';
+import { LanguageModelV3FunctionTool, LanguageModelV3ProviderTool, ImageModelV3File, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV3Prompt, SharedV3ProviderOptions } from '@ai-sdk/provider';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 export * from '@standard-schema/spec';
 import * as z3 from 'zod/v3';
@@ -91,6 +91,76 @@ declare function extractResponseHeaders(response: Response): {
     [k: string]: string;
 };
 
+/**
+ * Convert an ImageModelV3File to a URL or data URI string.
+ *
+ * If the file is a URL, it returns the URL as-is.
+ * If the file is base64 data, it returns a data URI with the base64 data.
+ * If the file is a Uint8Array, it converts it to base64 and returns a data URI.
+ */
+declare function convertImageModelFileToDataUri(file: ImageModelV3File): string;
+
+/**
+ * Converts an input object to FormData for multipart/form-data requests.
+ *
+ * Handles the following cases:
+ * - `null` or `undefined` values are skipped
+ * - Arrays with a single element are appended as a single value
+ * - Arrays with multiple elements are appended with `[]` suffix (e.g., `image[]`)
+ *   unless `useArrayBrackets` is set to `false`
+ * - All other values are appended directly
+ *
+ * @param input - The input object to convert. Use a generic type for type validation.
+ * @param options - Optional configuration object.
+ * @param options.useArrayBrackets - Whether to add `[]` suffix for multi-element arrays.
+ *   Defaults to `true`. Set to `false` for APIs that expect repeated keys without brackets.
+ * @returns A FormData object containing the input values.
+ *
+ * @example
+ * ```ts
+ * type MyInput = {
+ *   model: string;
+ *   prompt: string;
+ *   images: Blob[];
+ * };
+ *
+ * const formData = convertToFormData<MyInput>({
+ *   model: 'gpt-image-1',
+ *   prompt: 'A cat',
+ *   images: [blob1, blob2],
+ * });
+ * ```
+ */
+declare function convertToFormData<T extends Record<string, unknown>>(input: T, options?: {
+    useArrayBrackets?: boolean;
+}): FormData;
+
+/**
+ * Download a file from a URL and return it as a Blob.
+ *
+ * @param url - The URL to download from.
+ * @returns A Promise that resolves to the downloaded Blob.
+ *
+ * @throws DownloadError if the download fails.
+ */
+declare function downloadBlob(url: string): Promise<Blob>;
+
+declare const symbol: unique symbol;
+declare class DownloadError extends AISDKError {
+    private readonly [symbol];
+    readonly url: string;
+    readonly statusCode?: number;
+    readonly statusText?: string;
+    constructor({ url, statusCode, statusText, cause, message, }: {
+        url: string;
+        statusCode?: number;
+        statusText?: string;
+        message?: string;
+        cause?: unknown;
+    });
+    static isInstance(error: unknown): error is DownloadError;
+}
+
 /**
  * Fetch function type (standardizes the version of fetch used).
  */
@@ -1042,6 +1112,20 @@ The ID of the tool. Must follow the format `<provider-name>.<unique-tool-name>`.
 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.
+     *
+     * When true, the tool result may not be returned in the same turn as the
+     * tool call (e.g., when using programmatic tool calling where a server tool
+     * triggers a client-executed tool, and the server tool's result is deferred
+     * until the client tool is resolved).
+     *
+     * This flag allows the AI SDK to handle tool results that arrive without
+     * a matching tool call in the current response.
+     *
+     * @default false
+     */
+    supportsDeferredResults?: boolean;
 });
 /**
  * Infer the input type of a tool.
@@ -1114,10 +1198,21 @@ type ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object> = (
     onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
 }) => Tool<INPUT, OUTPUT>;
-declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object>({ id, inputSchema, outputSchema, }: {
+declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object>({ id, inputSchema, outputSchema, supportsDeferredResults, }: {
     id: `${string}.${string}`;
     inputSchema: FlexibleSchema<INPUT>;
     outputSchema: FlexibleSchema<OUTPUT>;
+    /**
+     * Whether this provider-executed tool supports deferred results.
+     *
+     * When true, the tool result may not be returned in the same turn as the
+     * tool call (e.g., when using programmatic tool calling where a server tool
+     * triggers a client-executed tool, and the server tool's result is deferred
+     * until the client tool is resolved).
+     *
+     * @default false
+     */
+    supportsDeferredResults?: boolean;
 }): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS>;
 
 /**
@@ -1265,4 +1360,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
  */
 type ToolCallOptions = ToolExecutionOptions;
 
-export { type AssistantContent, type AssistantModelMessage, type DataContent, DelayedPromise, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, tool, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+export { type AssistantContent, type AssistantModelMessage, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, tool, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV3FunctionTool, LanguageModelV3ProviderTool, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV3Prompt, SharedV3ProviderOptions } from '@ai-sdk/provider';
+import { LanguageModelV3FunctionTool, LanguageModelV3ProviderTool, ImageModelV3File, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV3Prompt, SharedV3ProviderOptions } from '@ai-sdk/provider';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 export * from '@standard-schema/spec';
 import * as z3 from 'zod/v3';
@@ -91,6 +91,76 @@ declare function extractResponseHeaders(response: Response): {
     [k: string]: string;
 };
 
+/**
+ * Convert an ImageModelV3File to a URL or data URI string.
+ *
+ * If the file is a URL, it returns the URL as-is.
+ * If the file is base64 data, it returns a data URI with the base64 data.
+ * If the file is a Uint8Array, it converts it to base64 and returns a data URI.
+ */
+declare function convertImageModelFileToDataUri(file: ImageModelV3File): string;
+
+/**
+ * Converts an input object to FormData for multipart/form-data requests.
+ *
+ * Handles the following cases:
+ * - `null` or `undefined` values are skipped
+ * - Arrays with a single element are appended as a single value
+ * - Arrays with multiple elements are appended with `[]` suffix (e.g., `image[]`)
+ *   unless `useArrayBrackets` is set to `false`
+ * - All other values are appended directly
+ *
+ * @param input - The input object to convert. Use a generic type for type validation.
+ * @param options - Optional configuration object.
+ * @param options.useArrayBrackets - Whether to add `[]` suffix for multi-element arrays.
+ *   Defaults to `true`. Set to `false` for APIs that expect repeated keys without brackets.
+ * @returns A FormData object containing the input values.
+ *
+ * @example
+ * ```ts
+ * type MyInput = {
+ *   model: string;
+ *   prompt: string;
+ *   images: Blob[];
+ * };
+ *
+ * const formData = convertToFormData<MyInput>({
+ *   model: 'gpt-image-1',
+ *   prompt: 'A cat',
+ *   images: [blob1, blob2],
+ * });
+ * ```
+ */
+declare function convertToFormData<T extends Record<string, unknown>>(input: T, options?: {
+    useArrayBrackets?: boolean;
+}): FormData;
+
+/**
+ * Download a file from a URL and return it as a Blob.
+ *
+ * @param url - The URL to download from.
+ * @returns A Promise that resolves to the downloaded Blob.
+ *
+ * @throws DownloadError if the download fails.
+ */
+declare function downloadBlob(url: string): Promise<Blob>;
+
+declare const symbol: unique symbol;
+declare class DownloadError extends AISDKError {
+    private readonly [symbol];
+    readonly url: string;
+    readonly statusCode?: number;
+    readonly statusText?: string;
+    constructor({ url, statusCode, statusText, cause, message, }: {
+        url: string;
+        statusCode?: number;
+        statusText?: string;
+        message?: string;
+        cause?: unknown;
+    });
+    static isInstance(error: unknown): error is DownloadError;
+}
+
 /**
  * Fetch function type (standardizes the version of fetch used).
  */
@@ -1042,6 +1112,20 @@ The ID of the tool. Must follow the format `<provider-name>.<unique-tool-name>`.
 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.
+     *
+     * When true, the tool result may not be returned in the same turn as the
+     * tool call (e.g., when using programmatic tool calling where a server tool
+     * triggers a client-executed tool, and the server tool's result is deferred
+     * until the client tool is resolved).
+     *
+     * This flag allows the AI SDK to handle tool results that arrive without
+     * a matching tool call in the current response.
+     *
+     * @default false
+     */
+    supportsDeferredResults?: boolean;
 });
 /**
  * Infer the input type of a tool.
@@ -1114,10 +1198,21 @@ type ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object> = (
     onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
 }) => Tool<INPUT, OUTPUT>;
-declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object>({ id, inputSchema, outputSchema, }: {
+declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object>({ id, inputSchema, outputSchema, supportsDeferredResults, }: {
     id: `${string}.${string}`;
     inputSchema: FlexibleSchema<INPUT>;
     outputSchema: FlexibleSchema<OUTPUT>;
+    /**
+     * Whether this provider-executed tool supports deferred results.
+     *
+     * When true, the tool result may not be returned in the same turn as the
+     * tool call (e.g., when using programmatic tool calling where a server tool
+     * triggers a client-executed tool, and the server tool's result is deferred
+     * until the client tool is resolved).
+     *
+     * @default false
+     */
+    supportsDeferredResults?: boolean;
 }): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS>;
 
 /**
@@ -1265,4 +1360,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
  */
 type ToolCallOptions = ToolExecutionOptions;
 
-export { type AssistantContent, type AssistantModelMessage, type DataContent, DelayedPromise, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertToBase64, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, tool, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+export { type AssistantContent, type AssistantModelMessage, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, tool, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };