@ai-sdk/provider 4.0.9 → 4.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider",
-  "version": "4.0.9",
+  "version": "4.0.11",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/batch/v4/batch-v4-request.ts

@@ -0,0 +1,15 @@
+/**
+ * Fields shared by every request in a batch.
+ */
+export type BatchV4RequestBase<ModelId extends string = string> = {
+  /**
+   * Application-provided identifier used to correlate the request with its
+   * result.
+   */
+  readonly id: string;
+
+  /**
+   * Provider-specific model ID for this request.
+   */
+  readonly modelId: ModelId;
+};

package/src/batch/v4/batch-v4.ts

@@ -3,6 +3,32 @@ import type {
   SharedV4ProviderOptions,
   SharedV4Warning,
 } from '../../shared';
+import type { LanguageModelV4GenerateResult } from '../../language-model/v4/language-model-v4-generate-result';
+import type { TextBatchV4Request } from './text-batch-v4-request';
+
+/**
+ * Model IDs accepted by each batch modality.
+ *
+ * Additional modality-specific model ID types can be added to this mapping.
+ */
+export type BatchV4ModelIds = {
+  readonly text: string;
+};
+
+type BatchV4CallOptions = {
+  readonly providerOptions?: SharedV4ProviderOptions;
+  readonly abortSignal?: AbortSignal;
+  readonly headers?: Record<string, string | undefined>;
+};
+
+type BatchV4StartCallOptions = BatchV4CallOptions & {
+  /**
+   * URL the provider notifies when the batch reaches a terminal state.
+   * Providers that do not support completion webhooks should return an
+   * unsupported warning.
+   */
+  readonly webhookUrl?: string;
+};
 
 /**
  * Serializable error information for a batch or batch item.
@@ -32,21 +58,19 @@ export type BatchV4Status = {
   readonly providerMetadata?: SharedV4ProviderMetadata;
 };
 
+export type BatchV4Request<ModelIds extends BatchV4ModelIds = BatchV4ModelIds> =
+  TextBatchV4Request<ModelIds['text']>;
+
 /**
- * Options for starting a batch.
+ * Options for starting a batch of requests discriminated by modality.
+ *
+ * Additional modality-specific request variants can be added to
+ * `BatchV4Request`.
  */
-export type BatchV4StartOptions<REQUEST> = {
-  readonly requests: ReadonlyArray<REQUEST>;
-  readonly providerOptions?: SharedV4ProviderOptions;
-  readonly abortSignal?: AbortSignal;
-  readonly headers?: Record<string, string | undefined>;
-
-  /**
-   * URL the provider notifies when the batch reaches a terminal state.
-   * Providers that do not support completion webhooks should return an
-   * unsupported warning.
-   */
-  readonly webhookUrl?: string;
+export type BatchV4StartOptions<
+  ModelIds extends BatchV4ModelIds = BatchV4ModelIds,
+> = BatchV4StartCallOptions & {
+  readonly requests: ReadonlyArray<BatchV4Request<ModelIds>>;
 };
 
 /**
@@ -65,15 +89,9 @@ export type BatchV4StartResult = BatchV4Status & {
  */
 export type BatchV4OperationOptions = {
   readonly batchId: string;
-  readonly providerOptions?: SharedV4ProviderOptions;
-  readonly abortSignal?: AbortSignal;
-  readonly headers?: Record<string, string | undefined>;
-};
+} & BatchV4CallOptions;
 
-/**
- * A complete terminal result for one request in a batch.
- */
-export type BatchV4ItemResult<RESULT> =
+type BatchV4ItemResultBase<RESULT> =
   | {
       readonly id: string;
       readonly status: 'succeeded';
@@ -93,19 +111,50 @@ export type BatchV4ItemResult<RESULT> =
     };
 
 /**
- * Experimental structural capability for models that support durable batch
- * processing.
+ * A complete terminal result for one request in a text batch.
+ */
+export type TextBatchV4ItemResult = {
+  readonly type: 'text';
+} & BatchV4ItemResultBase<LanguageModelV4GenerateResult>;
+
+/**
+ * A complete terminal result for one request in a batch, discriminated by
+ * modality.
+ *
+ * Additional modality-specific item results can be added to this union.
  */
-export type BatchModelV4<REQUEST, RESULT> = {
-  experimental_doStartBatch(
-    options: BatchV4StartOptions<REQUEST>,
+export type BatchV4ItemResult = TextBatchV4ItemResult;
+
+/**
+ * Specification for a batch interface that implements batch interface version 4.
+ */
+export type BatchV4<ModelIds extends BatchV4ModelIds = BatchV4ModelIds> = {
+  /**
+   * The batch interface must specify which batch interface version it implements.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Provider ID.
+   */
+  readonly provider: string;
+
+  /**
+   * Supported URL patterns by media type for requests in this batch interface.
+   */
+  readonly supportedUrls:
+    | PromiseLike<Record<string, RegExp[]>>
+    | Record<string, RegExp[]>;
+
+  doStartBatch(
+    options: BatchV4StartOptions<ModelIds>,
   ): PromiseLike<BatchV4StartResult>;
 
-  experimental_doGetBatchStatus(
+  doGetBatchStatus(
     options: BatchV4OperationOptions,
   ): PromiseLike<BatchV4Status>;
 
-  experimental_doGetBatchResults(
+  doGetBatchResults(
     options: BatchV4OperationOptions,
-  ): PromiseLike<ReadableStream<BatchV4ItemResult<RESULT>>>;
+  ): PromiseLike<ReadableStream<BatchV4ItemResult>>;
 };

package/src/batch/v4/index.ts

@@ -1,9 +1,14 @@
 export type {
-  BatchModelV4 as Experimental_BatchModelV4,
+  BatchV4 as Experimental_BatchV4,
   BatchV4Error as Experimental_BatchV4Error,
   BatchV4ItemResult as Experimental_BatchV4ItemResult,
+  BatchV4ModelIds as Experimental_BatchV4ModelIds,
   BatchV4OperationOptions as Experimental_BatchV4OperationOptions,
+  BatchV4Request as Experimental_BatchV4Request,
   BatchV4StartOptions as Experimental_BatchV4StartOptions,
   BatchV4StartResult as Experimental_BatchV4StartResult,
   BatchV4Status as Experimental_BatchV4Status,
+  TextBatchV4ItemResult as Experimental_TextBatchV4ItemResult,
 } from './batch-v4';
+export type { BatchV4RequestBase as Experimental_BatchV4RequestBase } from './batch-v4-request';
+export type { TextBatchV4Request as Experimental_TextBatchV4Request } from './text-batch-v4-request';

package/src/batch/v4/text-batch-v4-request.ts

@@ -0,0 +1,27 @@
+import type { LanguageModelV4CallOptions } from '../../language-model/v4/language-model-v4-call-options';
+import type { BatchV4RequestBase } from './batch-v4-request';
+
+/**
+ * A normalized text generation request within a batch.
+ */
+export type TextBatchV4Request<ModelId extends string = string> =
+  BatchV4RequestBase<ModelId> & {
+    readonly type: 'text';
+    readonly options: Pick<
+      LanguageModelV4CallOptions,
+      | 'prompt'
+      | 'maxOutputTokens'
+      | 'temperature'
+      | 'stopSequences'
+      | 'topP'
+      | 'topK'
+      | 'presencePenalty'
+      | 'frequencyPenalty'
+      | 'seed'
+      | 'reasoning'
+      | 'responseFormat'
+      | 'toolChoice'
+      | 'tools'
+      | 'providerOptions'
+    >;
+  };

package/src/files/v4/files-v4-delete-file-call-options.ts

@@ -0,0 +1,30 @@
+import type { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
+import type { SharedV4ProviderReference } from '../../shared/v4/shared-v4-provider-reference';
+
+/**
+ * Options for deleting a file via the files interface.
+ */
+export type FilesV4DeleteFileCallOptions = {
+  /**
+   * The provider reference of the file, as returned by `uploadFile`.
+   */
+  file: SharedV4ProviderReference;
+
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: Record<string, string | undefined>;
+
+  /**
+   * 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.
+   */
+  providerOptions?: SharedV4ProviderOptions;
+};

package/src/files/v4/files-v4-delete-file-result.ts

@@ -0,0 +1,32 @@
+import type { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
+import type { SharedV4ProviderReference } from '../../shared/v4/shared-v4-provider-reference';
+import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+/**
+ * Result of deleting a file via the files interface.
+ */
+export type FilesV4DeleteFileResult = {
+  /**
+   * A provider reference mapping provider names to provider-specific file identifiers.
+   * Contains only the operated provider's entry — when working with a merged
+   * multi-provider reference, do not reassign it with this result.
+   */
+  providerReference: SharedV4ProviderReference;
+
+  /**
+   * Whether the provider confirmed the deletion.
+   */
+  deleted: boolean;
+
+  /**
+   * 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.
+   */
+  providerMetadata?: SharedV4ProviderMetadata;
+
+  /**
+   * Warnings from the provider.
+   */
+  warnings: Array<SharedV4Warning>;
+};

package/src/files/v4/files-v4-download-file-call-options.ts

@@ -0,0 +1,30 @@
+import type { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
+import type { SharedV4ProviderReference } from '../../shared/v4/shared-v4-provider-reference';
+
+/**
+ * Options for downloading file content via the files interface.
+ */
+export type FilesV4DownloadFileCallOptions = {
+  /**
+   * The provider reference of the file, as returned by `uploadFile`.
+   */
+  file: SharedV4ProviderReference;
+
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: Record<string, string | undefined>;
+
+  /**
+   * 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.
+   */
+  providerOptions?: SharedV4ProviderOptions;
+};

package/src/files/v4/files-v4-download-file-result.ts

@@ -0,0 +1,30 @@
+import type { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
+import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+/**
+ * Result of downloading file content via the files interface.
+ */
+export type FilesV4DownloadFileResult = {
+  /**
+   * The file content as a byte stream.
+   * The consumer is responsible for draining or cancelling the stream.
+   */
+  content: ReadableStream<Uint8Array>;
+
+  /**
+   * The IANA media type of the file, if available from the provider.
+   */
+  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.
+   */
+  providerMetadata?: SharedV4ProviderMetadata;
+
+  /**
+   * Warnings from the provider.
+   */
+  warnings: Array<SharedV4Warning>;
+};

package/src/files/v4/files-v4-get-file-metadata-call-options.ts

@@ -0,0 +1,30 @@
+import type { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
+import type { SharedV4ProviderReference } from '../../shared/v4/shared-v4-provider-reference';
+
+/**
+ * Options for retrieving file metadata via the files interface.
+ */
+export type FilesV4GetFileMetadataCallOptions = {
+  /**
+   * The provider reference of the file, as returned by `uploadFile`.
+   */
+  file: SharedV4ProviderReference;
+
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: Record<string, string | undefined>;
+
+  /**
+   * 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.
+   */
+  providerOptions?: SharedV4ProviderOptions;
+};

package/src/files/v4/files-v4-get-file-metadata-result.ts

@@ -0,0 +1,53 @@
+import type { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
+import type { SharedV4ProviderReference } from '../../shared/v4/shared-v4-provider-reference';
+import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+/**
+ * Result of retrieving file metadata via the files interface.
+ */
+export type FilesV4GetFileMetadataResult = {
+  /**
+   * A provider reference mapping provider names to provider-specific file identifiers.
+   * Contains only the operated provider's entry — when working with a merged
+   * multi-provider reference, do not reassign it with this result.
+   */
+  providerReference: SharedV4ProviderReference;
+
+  /**
+   * The filename of the file, if available from the provider.
+   */
+  filename?: string;
+
+  /**
+   * The IANA media type of the file, if available from the provider.
+   */
+  mediaType?: string;
+
+  /**
+   * The size of the file in bytes, if available from the provider.
+   */
+  byteSize?: number;
+
+  /**
+   * When the file was created, if available from the provider.
+   */
+  createdAt?: Date;
+
+  /**
+   * When the provider will delete the file (retention expiry),
+   * if available from the provider.
+   */
+  expiresAt?: Date;
+
+  /**
+   * 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.
+   */
+  providerMetadata?: SharedV4ProviderMetadata;
+
+  /**
+   * Warnings from the provider.
+   */
+  warnings: Array<SharedV4Warning>;
+};

package/src/files/v4/files-v4-upload-file-call-options.ts

@@ -4,6 +4,15 @@ import type {
 } from '../../shared/v4/shared-v4-file-data';
 import type { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
 
+/**
+ * File data variant containing a byte stream. Providers that support
+ * streaming uploads send it without buffering the full file in memory.
+ */
+export interface FilesV4UploadFileStreamData {
+  type: 'stream';
+  stream: ReadableStream<Uint8Array>;
+}
+
 /**
  * Options for uploading a file via the files interface.
  */
@@ -13,8 +22,13 @@ export type FilesV4UploadFileCallOptions = {
    *
    * - `{ type: 'data', data }`: raw bytes (`Uint8Array`) or a base64-encoded string.
    * - `{ type: 'text', text }`: inline text (UTF-8).
+   * - `{ type: 'stream', stream }`: a byte stream (not buffered by providers
+   *   that support streaming uploads).
    */
-  data: SharedV4FileDataData | SharedV4FileDataText;
+  data:
+    | SharedV4FileDataData
+    | SharedV4FileDataText
+    | FilesV4UploadFileStreamData;
 
   /**
    * The IANA media type of the file (e.g. `'application/pdf'`).
@@ -26,6 +40,17 @@ export type FilesV4UploadFileCallOptions = {
    */
   filename?: string;
 
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: Record<string, string | undefined>;
+
   /**
    * Additional provider-specific options. They are passed through
    * to the provider from the AI SDK and enable provider-specific

package/src/files/v4/files-v4-upload-file-result.ts

@@ -8,6 +8,8 @@ import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
 export type FilesV4UploadFileResult = {
   /**
    * A provider reference mapping provider names to provider-specific file identifiers.
+   * The key is the canonical provider name (e.g. `openai`) and may differ from
+   * the interface's `provider` id (e.g. `openai.files`).
    */
   providerReference: SharedV4ProviderReference;
 
@@ -21,6 +23,22 @@ export type FilesV4UploadFileResult = {
    */
   filename?: string;
 
+  /**
+   * The size of the uploaded file in bytes, if available from the provider.
+   */
+  byteSize?: number;
+
+  /**
+   * When the file was created, if available from the provider.
+   */
+  createdAt?: Date;
+
+  /**
+   * When the provider will delete the file (retention expiry, e.g. from a
+   * requested upload TTL), if available from the provider.
+   */
+  expiresAt?: Date;
+
   /**
    * Additional provider-specific metadata. They are passed through
    * to the provider from the AI SDK and enable provider-specific

package/src/files/v4/files-v4.ts

@@ -1,8 +1,18 @@
+import type { FilesV4DeleteFileCallOptions } from './files-v4-delete-file-call-options';
+import type { FilesV4DeleteFileResult } from './files-v4-delete-file-result';
+import type { FilesV4DownloadFileCallOptions } from './files-v4-download-file-call-options';
+import type { FilesV4DownloadFileResult } from './files-v4-download-file-result';
+import type { FilesV4GetFileMetadataCallOptions } from './files-v4-get-file-metadata-call-options';
+import type { FilesV4GetFileMetadataResult } from './files-v4-get-file-metadata-result';
 import type { FilesV4UploadFileCallOptions } from './files-v4-upload-file-call-options';
 import type { FilesV4UploadFileResult } from './files-v4-upload-file-result';
 
 /**
  * Specification for a file management interface that implements the files interface version 4.
+ *
+ * Only `uploadFile` is required. The other operations are optional
+ * capabilities: their presence signals that the provider supports them
+ * (mirroring the optional-method pattern of `VideoModelV4`).
  */
 export type FilesV4 = {
   /**
@@ -22,4 +32,28 @@ export type FilesV4 = {
   uploadFile(
     options: FilesV4UploadFileCallOptions,
   ): PromiseLike<FilesV4UploadFileResult>;
+
+  /**
+   * Retrieves metadata for a previously uploaded file.
+   * Optional: presence signals that the provider supports metadata reads.
+   */
+  getFileMetadata?(
+    options: FilesV4GetFileMetadataCallOptions,
+  ): PromiseLike<FilesV4GetFileMetadataResult>;
+
+  /**
+   * Downloads the content of a previously uploaded file as a byte stream.
+   * Optional: presence signals that the provider supports content download.
+   */
+  downloadFile?(
+    options: FilesV4DownloadFileCallOptions,
+  ): PromiseLike<FilesV4DownloadFileResult>;
+
+  /**
+   * Deletes a previously uploaded file.
+   * Optional: presence signals that the provider supports deletion.
+   */
+  deleteFile?(
+    options: FilesV4DeleteFileCallOptions,
+  ): PromiseLike<FilesV4DeleteFileResult>;
 };

package/src/files/v4/index.ts

@@ -1,3 +1,12 @@
 export type { FilesV4 } from './files-v4';
-export type { FilesV4UploadFileCallOptions } from './files-v4-upload-file-call-options';
+export type { FilesV4DeleteFileCallOptions } from './files-v4-delete-file-call-options';
+export type { FilesV4DeleteFileResult } from './files-v4-delete-file-result';
+export type { FilesV4DownloadFileCallOptions } from './files-v4-download-file-call-options';
+export type { FilesV4DownloadFileResult } from './files-v4-download-file-result';
+export type { FilesV4GetFileMetadataCallOptions } from './files-v4-get-file-metadata-call-options';
+export type { FilesV4GetFileMetadataResult } from './files-v4-get-file-metadata-result';
+export type {
+  FilesV4UploadFileCallOptions,
+  FilesV4UploadFileStreamData,
+} from './files-v4-upload-file-call-options';
 export type { FilesV4UploadFileResult } from './files-v4-upload-file-result';

package/src/image-model/v4/image-model-v4-result.ts

@@ -22,6 +22,12 @@ export type ImageModelV4Result = {
    */
   images: Array<string> | Array<Uint8Array>;
 
+  /**
+   * Whether an unsuccessful result, such as an empty image result, can be
+   * retried. When omitted, the result is unclassified.
+   */
+  isRetryable?: boolean;
+
   /**
    * Warnings for the call, e.g. unsupported features.
    */

package/src/language-model/v4/index.ts

@@ -20,7 +20,3 @@ export * from './language-model-v4-tool-call';
 export * from './language-model-v4-tool-choice';
 export * from './language-model-v4-tool-result';
 export * from './language-model-v4-usage';
-export type {
-  BatchLanguageModelV4 as Experimental_BatchLanguageModelV4,
-  LanguageModelV4BatchRequest as Experimental_LanguageModelV4BatchRequest,
-} from './language-model-v4-batch';

package/src/language-model/v4/language-model-v4-batch.ts

@@ -1,42 +0,0 @@
-import type { BatchModelV4 } from '../../batch/v4/batch-v4';
-import type { LanguageModelV4 } from './language-model-v4';
-import type { LanguageModelV4CallOptions } from './language-model-v4-call-options';
-import type { LanguageModelV4GenerateResult } from './language-model-v4-generate-result';
-
-/**
- * A normalized language model call within a batch.
- */
-export type LanguageModelV4BatchRequest = {
-  /**
-   * Application-provided identifier used to correlate the request with its
-   * result.
-   */
-  readonly id: string;
-
-  /**
-   * Normalized text-generation options for the request.
-   */
-  readonly options: Pick<
-    LanguageModelV4CallOptions,
-    | 'prompt'
-    | 'maxOutputTokens'
-    | 'temperature'
-    | 'stopSequences'
-    | 'topP'
-    | 'topK'
-    | 'presencePenalty'
-    | 'frequencyPenalty'
-    | 'seed'
-    | 'reasoning'
-    | 'responseFormat'
-    | 'toolChoice'
-    | 'tools'
-    | 'providerOptions'
-  >;
-};
-
-/**
- * Language model V4 with durable batch-processing support.
- */
-export type BatchLanguageModelV4 = LanguageModelV4 &
-  BatchModelV4<LanguageModelV4BatchRequest, LanguageModelV4GenerateResult>;