@ai-sdk/provider 0.0.0-01d6317c-20260129172110

package/src/errors/type-validation-error.ts

@@ -0,0 +1,108 @@
+import { AISDKError } from './ai-sdk-error';
+import { getErrorMessage } from './get-error-message';
+
+const name = 'AI_TypeValidationError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export interface TypeValidationContext {
+  /**
+   * Field path in dot notation (e.g., "message.metadata", "message.parts[3].data")
+   */
+  field?: string;
+
+  /**
+   * Entity name (e.g., tool name, data type name)
+   */
+  entityName?: string;
+
+  /**
+   * Entity identifier (e.g., message ID, tool call ID)
+   */
+  entityId?: string;
+}
+
+export class TypeValidationError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly value: unknown;
+  readonly context?: TypeValidationContext;
+
+  constructor({
+    value,
+    cause,
+    context,
+  }: {
+    value: unknown;
+    cause: unknown;
+    context?: TypeValidationContext;
+  }) {
+    let contextPrefix = 'Type validation failed';
+
+    if (context?.field) {
+      contextPrefix += ` for ${context.field}`;
+    }
+
+    if (context?.entityName || context?.entityId) {
+      contextPrefix += ' (';
+      const parts: string[] = [];
+      if (context.entityName) {
+        parts.push(context.entityName);
+      }
+      if (context.entityId) {
+        parts.push(`id: "${context.entityId}"`);
+      }
+      contextPrefix += parts.join(', ');
+      contextPrefix += ')';
+    }
+
+    super({
+      name,
+      message:
+        `${contextPrefix}: ` +
+        `Value: ${JSON.stringify(value)}.\n` +
+        `Error message: ${getErrorMessage(cause)}`,
+      cause,
+    });
+
+    this.value = value;
+    this.context = context;
+  }
+
+  static isInstance(error: unknown): error is TypeValidationError {
+    return AISDKError.hasMarker(error, marker);
+  }
+
+  /**
+   * Wraps an error into a TypeValidationError.
+   * If the cause is already a TypeValidationError with the same value and context, it returns the cause.
+   * Otherwise, it creates a new TypeValidationError.
+   *
+   * @param {Object} params - The parameters for wrapping the error.
+   * @param {unknown} params.value - The value that failed validation.
+   * @param {unknown} params.cause - The original error or cause of the validation failure.
+   * @param {TypeValidationContext} params.context - Optional context about what is being validated.
+   * @returns {TypeValidationError} A TypeValidationError instance.
+   */
+  static wrap({
+    value,
+    cause,
+    context,
+  }: {
+    value: unknown;
+    cause: unknown;
+    context?: TypeValidationContext;
+  }): TypeValidationError {
+    if (
+      TypeValidationError.isInstance(cause) &&
+      cause.value === value &&
+      cause.context?.field === context?.field &&
+      cause.context?.entityName === context?.entityName &&
+      cause.context?.entityId === context?.entityId
+    ) {
+      return cause;
+    }
+
+    return new TypeValidationError({ value, cause, context });
+  }
+}

package/src/errors/unsupported-functionality-error.ts

@@ -0,0 +1,26 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_UnsupportedFunctionalityError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class UnsupportedFunctionalityError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly functionality: string;
+
+  constructor({
+    functionality,
+    message = `'${functionality}' functionality not supported.`,
+  }: {
+    functionality: string;
+    message?: string;
+  }) {
+    super({ name, message });
+    this.functionality = functionality;
+  }
+
+  static isInstance(error: unknown): error is UnsupportedFunctionalityError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/image-model/index.ts

@@ -0,0 +1,2 @@
+export * from './v3/index';
+export * from './v2/index';

package/src/image-model/v2/image-model-v2-call-options.ts

@@ -0,0 +1,60 @@
+import { SharedV2ProviderOptions } from '../../shared';
+
+export type ImageModelV2CallOptions = {
+  /**
+   * Prompt for the image generation.
+   */
+  prompt: string;
+
+  /**
+   * Number of images to generate.
+   */
+  n: number;
+
+  /**
+   * Size of the images to generate.
+   * Must have the format `{width}x{height}`.
+   * `undefined` will use the provider's default size.
+   */
+  size: `${number}x${number}` | undefined;
+
+  /**
+   * Aspect ratio of the images to generate.
+   * Must have the format `{width}:{height}`.
+   * `undefined` will use the provider's default aspect ratio.
+   */
+  aspectRatio: `${number}:${number}` | undefined;
+
+  /**
+   * Seed for the image generation.
+   * `undefined` will use the provider's default seed.
+   */
+  seed: number | undefined;
+
+  /**
+   * Additional provider-specific options that are passed through to the provider
+   * as body parameters.
+   *
+   * The outer record is keyed by the provider name, and the inner
+   * record is keyed by the provider-specific metadata key.
+   * ```ts
+   * {
+   * "openai": {
+   * "style": "vivid"
+   * }
+   * }
+   * ```
+   */
+  providerOptions: SharedV2ProviderOptions;
+
+  /**
+   * 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>;
+};

package/src/image-model/v2/image-model-v2-call-warning.ts

@@ -0,0 +1,16 @@
+import { ImageModelV2CallOptions } from './image-model-v2-call-options';
+
+/**
+ * Warning from the model provider for this call. The call will proceed, but e.g.
+ * some settings might not be supported, which can lead to suboptimal results.
+ */
+export type ImageModelV2CallWarning =
+  | {
+      type: 'unsupported-setting';
+      setting: keyof ImageModelV2CallOptions;
+      details?: string;
+    }
+  | {
+      type: 'other';
+      message: string;
+    };

package/src/image-model/v2/image-model-v2.ts

@@ -0,0 +1,104 @@
+import { JSONArray, JSONValue } from '../../json-value';
+import { ImageModelV2CallOptions } from './image-model-v2-call-options';
+import { ImageModelV2CallWarning } from './image-model-v2-call-warning';
+
+export type ImageModelV2ProviderMetadata = Record<
+  string,
+  {
+    images: JSONArray;
+  } & JSONValue
+>;
+
+type GetMaxImagesPerCallFunction = (options: {
+  modelId: string;
+}) => PromiseLike<number | undefined> | number | undefined;
+
+/**
+ * Image generation model specification version 2.
+ */
+export type ImageModelV2 = {
+  /**
+   * The image model must specify which image model interface
+   * version it implements. This will allow us to evolve the image
+   * model interface and retain backwards compatibility. The different
+   * implementation versions can be handled as a discriminated union
+   * on our side.
+   */
+  readonly specificationVersion: 'v2';
+
+  /**
+   * Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+   * Limit of how many images can be generated in a single API call.
+   * Can be set to a number for a fixed limit, to undefined to use
+   * the global limit, or a function that returns a number or undefined,
+   * optionally as a promise.
+   */
+  readonly maxImagesPerCall: number | undefined | GetMaxImagesPerCallFunction;
+
+  /**
+   * Generates an array of images.
+   */
+  doGenerate(options: ImageModelV2CallOptions): PromiseLike<{
+    /**
+     * Generated images as base64 encoded strings or binary data.
+     * The images should be returned without any unnecessary conversion.
+     * If the API returns base64 encoded strings, the images should be returned
+     * as base64 encoded strings. If the API returns binary data, the images should
+     * be returned as binary data.
+     */
+    images: Array<string> | Array<Uint8Array>;
+
+    /**
+     * Warnings for the call, e.g. unsupported settings.
+     */
+    warnings: Array<ImageModelV2CallWarning>;
+
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * from the provider to the AI SDK and enable provider-specific
+     * results that can be fully encapsulated in the provider.
+     *
+     * The outer record is keyed by the provider name, and the inner
+     * record is provider-specific metadata. It always includes an
+     * `images` key with image-specific metadata
+     *
+     * ```ts
+     * {
+     * "openai": {
+     * "images": ["revisedPrompt": "Revised prompt here."]
+     * }
+     * }
+     * ```
+     */
+    providerMetadata?: ImageModelV2ProviderMetadata;
+
+    /**
+     * Response information for telemetry and debugging purposes.
+     */
+    response: {
+      /**
+       * Timestamp for the start of the generated response.
+       */
+      timestamp: Date;
+
+      /**
+       * The ID of the response model that was used to generate the response.
+       */
+      modelId: string;
+
+      /**
+       * Response headers.
+       */
+      headers: Record<string, string> | undefined;
+    };
+  }>;
+};

package/src/image-model/v2/index.ts

@@ -0,0 +1,6 @@
+export type {
+  ImageModelV2,
+  ImageModelV2ProviderMetadata,
+} from './image-model-v2';
+export type { ImageModelV2CallOptions } from './image-model-v2-call-options';
+export type { ImageModelV2CallWarning } from './image-model-v2-call-warning';

package/src/image-model/v3/image-model-v3-call-options.ts

@@ -0,0 +1,74 @@
+import { SharedV3ProviderOptions } from '../../shared';
+import { ImageModelV3File } from './image-model-v3-file';
+
+export type ImageModelV3CallOptions = {
+  /**
+   * Prompt for the image generation. Some operations, like upscaling, may not require a prompt.
+   */
+  prompt: string | undefined;
+
+  /**
+   * Number of images to generate.
+   */
+  n: number;
+
+  /**
+   * Size of the images to generate.
+   * Must have the format `{width}x{height}`.
+   * `undefined` will use the provider's default size.
+   */
+  size: `${number}x${number}` | undefined;
+
+  /**
+   * Aspect ratio of the images to generate.
+   * Must have the format `{width}:{height}`.
+   * `undefined` will use the provider's default aspect ratio.
+   */
+  aspectRatio: `${number}:${number}` | undefined;
+
+  /**
+   * Seed for the image generation.
+   * `undefined` will use the provider's default seed.
+   */
+  seed: number | undefined;
+
+  /**
+   * Array of images for image editing or variation generation.
+   * The images should be provided as base64 encoded strings or binary data.
+   */
+  files: ImageModelV3File[] | undefined;
+
+  /**
+   * Mask image for inpainting operations.
+   * The mask should be provided as base64 encoded strings or binary data.
+   */
+  mask: ImageModelV3File | undefined;
+
+  /**
+   * Additional provider-specific options that are passed through to the provider
+   * as body parameters.
+   *
+   * The outer record is keyed by the provider name, and the inner
+   * record is keyed by the provider-specific metadata key.
+   *
+   * ```ts
+   * {
+   *   "openai": {
+   *     "style": "vivid"
+   *   }
+   * }
+   * ```
+   */
+  providerOptions: SharedV3ProviderOptions;
+
+  /**
+   * 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>;
+};

package/src/image-model/v3/image-model-v3-file.ts

@@ -0,0 +1,44 @@
+import { SharedV3ProviderMetadata } from '../../shared';
+
+/**
+ * An image file that can be used for image editing or variation generation.
+ */
+export type ImageModelV3File =
+  | {
+      type: 'file';
+
+      /**
+       * The IANA media type of the file, e.g. `image/png`. Any string is supported.
+       *
+       * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+       */
+      mediaType: string;
+
+      /**
+       * Generated file data as base64 encoded strings or binary data.
+       *
+       * The file data should be returned without any unnecessary conversion.
+       * If the API returns base64 encoded strings, the file data should be returned
+       * as base64 encoded strings. If the API returns binary data, the file data should
+       * be returned as binary data.
+       */
+      data: string | Uint8Array;
+
+      /**
+       * Optional provider-specific metadata for the file part.
+       */
+      providerOptions?: SharedV3ProviderMetadata;
+    }
+  | {
+      type: 'url';
+
+      /**
+       * The URL of the image file.
+       */
+      url: string;
+
+      /**
+       * Optional provider-specific metadata for the file part.
+       */
+      providerOptions?: SharedV3ProviderMetadata;
+    };

package/src/image-model/v3/image-model-v3-usage.ts

@@ -0,0 +1,19 @@
+/**
+ * Usage information for an image model call.
+ */
+export type ImageModelV3Usage = {
+  /**
+   * The number of input (prompt) tokens used.
+   */
+  inputTokens: number | undefined;
+
+  /**
+   * The number of output tokens used, if reported by the provider.
+   */
+  outputTokens: number | undefined;
+
+  /**
+   * The total number of tokens as reported by the provider.
+   */
+  totalTokens: number | undefined;
+};

package/src/image-model/v3/image-model-v3.ts

@@ -0,0 +1,110 @@
+import { JSONArray, JSONValue } from '../../json-value';
+import { ImageModelV3Usage } from './image-model-v3-usage';
+import { ImageModelV3CallOptions } from './image-model-v3-call-options';
+import { SharedV3Warning } from '../../shared/v3/shared-v3-warning';
+
+export type ImageModelV3ProviderMetadata = Record<
+  string,
+  {
+    images: JSONArray;
+  } & JSONValue
+>;
+
+type GetMaxImagesPerCallFunction = (options: {
+  modelId: string;
+}) => PromiseLike<number | undefined> | number | undefined;
+
+/**
+ * Image generation model specification version 3.
+ */
+export type ImageModelV3 = {
+  /**
+   * The image model must specify which image model interface
+   * version it implements. This will allow us to evolve the image
+   * model interface and retain backwards compatibility. The different
+   * implementation versions can be handled as a discriminated union
+   * on our side.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+   * Limit of how many images can be generated in a single API call.
+   * Can be set to a number for a fixed limit, to undefined to use
+   * the global limit, or a function that returns a number or undefined,
+   * optionally as a promise.
+   */
+  readonly maxImagesPerCall: number | undefined | GetMaxImagesPerCallFunction;
+
+  /**
+   * Generates an array of images.
+   */
+  doGenerate(options: ImageModelV3CallOptions): PromiseLike<{
+    /**
+     * Generated images as base64 encoded strings or binary data.
+     * The images should be returned without any unnecessary conversion.
+     * If the API returns base64 encoded strings, the images should be returned
+     * as base64 encoded strings. If the API returns binary data, the images should
+     * be returned as binary data.
+     */
+    images: Array<string> | Array<Uint8Array>;
+
+    /**
+     * Warnings for the call, e.g. unsupported features.
+     */
+    warnings: Array<SharedV3Warning>;
+
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * from the provider to the AI SDK and enable provider-specific
+     * results that can be fully encapsulated in the provider.
+     *
+     * The outer record is keyed by the provider name, and the inner
+     * record is provider-specific metadata. It always includes an
+     * `images` key with image-specific metadata
+     *
+     * ```ts
+     * {
+     * "openai": {
+     * "images": ["revisedPrompt": "Revised prompt here."]
+     * }
+     * }
+     * ```
+     */
+    providerMetadata?: ImageModelV3ProviderMetadata;
+
+    /**
+     * Response information for telemetry and debugging purposes.
+     */
+    response: {
+      /**
+       * Timestamp for the start of the generated response.
+       */
+      timestamp: Date;
+
+      /**
+       * The ID of the response model that was used to generate the response.
+       */
+      modelId: string;
+
+      /**
+       * Response headers.
+       */
+      headers: Record<string, string> | undefined;
+    };
+
+    /**
+     * Optional token usage for the image generation call (if the provider reports it).
+     */
+    usage?: ImageModelV3Usage;
+  }>;
+};

package/src/image-model/v3/index.ts

@@ -0,0 +1,7 @@
+export type {
+  ImageModelV3,
+  ImageModelV3ProviderMetadata,
+} from './image-model-v3';
+export type { ImageModelV3CallOptions } from './image-model-v3-call-options';
+export type { ImageModelV3Usage } from './image-model-v3-usage';
+export type { ImageModelV3File } from './image-model-v3-file';

package/src/image-model-middleware/index.ts

@@ -0,0 +1 @@
+export * from './v3/index';

package/src/image-model-middleware/v3/image-model-v3-middleware.ts

@@ -0,0 +1,61 @@
+import { ImageModelV3 } from '../../image-model/v3/image-model-v3';
+import { ImageModelV3CallOptions } from '../../image-model/v3/image-model-v3-call-options';
+
+/**
+ * Middleware for ImageModelV3.
+ * This type defines the structure for middleware that can be used to modify
+ * the behavior of ImageModelV3 operations.
+ */
+export type ImageModelV3Middleware = {
+  /**
+   * Middleware specification version. Use `v3` for the current version.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Override the provider name if desired.
+   * @param options.model - The image model instance.
+   */
+  overrideProvider?: (options: { model: ImageModelV3 }) => string;
+
+  /**
+   * Override the model ID if desired.
+   * @param options.model - The image model instance.
+   */
+  overrideModelId?: (options: { model: ImageModelV3 }) => string;
+
+  /**
+   * Override the limit of how many images can be generated in a single API call if desired.
+   * @param options.model - The image model instance.
+   */
+  overrideMaxImagesPerCall?: (options: {
+    model: ImageModelV3;
+  }) => ImageModelV3['maxImagesPerCall'];
+
+  /**
+   * Transforms the parameters before they are passed to the image model.
+   * @param options - Object containing the parameters.
+   * @param options.params - The original parameters for the image model call.
+   * @returns A promise that resolves to the transformed parameters.
+   */
+  transformParams?: (options: {
+    params: ImageModelV3CallOptions;
+    model: ImageModelV3;
+  }) => PromiseLike<ImageModelV3CallOptions>;
+
+  /**
+   * Wraps the generate operation of the image model.
+   *
+   * @param options - Object containing the generate function, parameters, and model.
+   * @param options.doGenerate - The original generate function.
+   * @param options.params - The parameters for the generate call. If the
+   * `transformParams` middleware is used, this will be the transformed parameters.
+   * @param options.model - The image model instance.
+   * @returns A promise that resolves to the result of the generate operation.
+   */
+  wrapGenerate?: (options: {
+    doGenerate: () => ReturnType<ImageModelV3['doGenerate']>;
+    params: ImageModelV3CallOptions;
+    model: ImageModelV3;
+  }) => Promise<Awaited<ReturnType<ImageModelV3['doGenerate']>>>;
+};

package/src/image-model-middleware/v3/index.ts

@@ -0,0 +1 @@
+export * from './image-model-v3-middleware';

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './embedding-model/index';
+export * from './errors/index';
+export * from './image-model/index';
+export * from './image-model-middleware/index';
+export * from './json-value/index';
+export * from './language-model-middleware/index';
+export * from './embedding-model-middleware/index';
+export * from './language-model/index';
+export * from './provider/index';
+export * from './reranking-model/index';
+export * from './shared/index';
+export * from './speech-model/index';
+export * from './transcription-model/index';
+
+export type { JSONSchema7, JSONSchema7Definition } from 'json-schema';

package/src/json-value/index.ts

@@ -0,0 +1,2 @@
+export { isJSONArray, isJSONObject, isJSONValue } from './is-json';
+export type { JSONArray, JSONObject, JSONValue } from './json-value';