@ai-sdk/provider-utils 5.0.0-beta.28 → 5.0.0-beta.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "5.0.0-beta.28",
+  "version": "5.0.0-beta.29",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,7 +35,7 @@
     "@standard-schema/spec": "^1.1.0",
     "@workflow/serde": "4.1.0",
     "eventsource-parser": "^3.0.8",
-    "@ai-sdk/provider": "4.0.0-beta.13"
+    "@ai-sdk/provider": "4.0.0-beta.14"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/add-additional-properties-to-json-schema.ts

@@ -1,4 +1,4 @@
-import { JSONSchema7, JSONSchema7Definition } from '@ai-sdk/provider';
+import type { JSONSchema7, JSONSchema7Definition } from '@ai-sdk/provider';
 
 /**
  * Recursively adds additionalProperties: false to the JSON schema. This is necessary because some providers (e.g. OpenAI) do not support additionalProperties: true.

package/src/convert-image-model-file-to-data-uri.ts

@@ -1,4 +1,4 @@
-import { ImageModelV4File } from '@ai-sdk/provider';
+import type { ImageModelV4File } from '@ai-sdk/provider';
 import { convertUint8ArrayToBase64 } from './uint8-utils';
 
 /**

package/src/convert-inline-file-data-to-uint8-array.ts

@@ -0,0 +1,30 @@
+import type { FilePart } from './types/content-part';
+import { convertBase64ToUint8Array } from './uint8-utils';
+
+type InlineFileData = Extract<
+  FilePart['data'],
+  { type: 'data' } | { type: 'text' }
+>;
+
+/**
+ * Converts inline file data (a tagged `data` or `text` shape) into raw bytes.
+ *
+ * - `{ type: 'text', text }` → UTF-8 encoded bytes
+ * - `{ type: 'data', data: Uint8Array | Buffer }` → returned as-is
+ * - `{ type: 'data', data: ArrayBuffer }` → wrapped in a `Uint8Array`
+ * - `{ type: 'data', data: string }` → decoded as base64
+ */
+export function convertInlineFileDataToUint8Array(
+  data: InlineFileData,
+): Uint8Array {
+  if (data.type === 'text') {
+    return new TextEncoder().encode(data.text);
+  }
+  if (data.data instanceof Uint8Array) {
+    return data.data;
+  }
+  if (data.data instanceof ArrayBuffer) {
+    return new Uint8Array(data.data);
+  }
+  return convertBase64ToUint8Array(data.data);
+}

package/src/create-tool-name-mapping.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   LanguageModelV4FunctionTool,
   LanguageModelV4ProviderTool,
 } from '@ai-sdk/provider';

package/src/detect-media-type.ts

@@ -0,0 +1,312 @@
+import { convertBase64ToUint8Array } from './uint8-utils';
+
+const imageMediaTypeSignatures = [
+  {
+    mediaType: 'image/gif' as const,
+    bytesPrefix: [0x47, 0x49, 0x46], // GIF
+  },
+  {
+    mediaType: 'image/png' as const,
+    bytesPrefix: [0x89, 0x50, 0x4e, 0x47], // PNG
+  },
+  {
+    mediaType: 'image/jpeg' as const,
+    bytesPrefix: [0xff, 0xd8], // JPEG
+  },
+  {
+    mediaType: 'image/webp' as const,
+    bytesPrefix: [
+      0x52,
+      0x49,
+      0x46,
+      0x46, // "RIFF"
+      null,
+      null,
+      null,
+      null, // file size (variable)
+      0x57,
+      0x45,
+      0x42,
+      0x50, // "WEBP"
+    ],
+  },
+  {
+    mediaType: 'image/bmp' as const,
+    bytesPrefix: [0x42, 0x4d],
+  },
+  {
+    mediaType: 'image/tiff' as const,
+    bytesPrefix: [0x49, 0x49, 0x2a, 0x00],
+  },
+  {
+    mediaType: 'image/tiff' as const,
+    bytesPrefix: [0x4d, 0x4d, 0x00, 0x2a],
+  },
+  {
+    mediaType: 'image/avif' as const,
+    bytesPrefix: [
+      0x00, 0x00, 0x00, 0x20, 0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69, 0x66,
+    ],
+  },
+  {
+    mediaType: 'image/heic' as const,
+    bytesPrefix: [
+      0x00, 0x00, 0x00, 0x20, 0x66, 0x74, 0x79, 0x70, 0x68, 0x65, 0x69, 0x63,
+    ],
+  },
+] as const;
+
+const documentMediaTypeSignatures = [
+  {
+    mediaType: 'application/pdf' as const,
+    bytesPrefix: [0x25, 0x50, 0x44, 0x46], // %PDF
+  },
+] as const;
+
+const audioMediaTypeSignatures = [
+  {
+    mediaType: 'audio/mpeg' as const,
+    bytesPrefix: [0xff, 0xfb],
+  },
+  {
+    mediaType: 'audio/mpeg' as const,
+    bytesPrefix: [0xff, 0xfa],
+  },
+  {
+    mediaType: 'audio/mpeg' as const,
+    bytesPrefix: [0xff, 0xf3],
+  },
+  {
+    mediaType: 'audio/mpeg' as const,
+    bytesPrefix: [0xff, 0xf2],
+  },
+  {
+    mediaType: 'audio/mpeg' as const,
+    bytesPrefix: [0xff, 0xe3],
+  },
+  {
+    mediaType: 'audio/mpeg' as const,
+    bytesPrefix: [0xff, 0xe2],
+  },
+  {
+    mediaType: 'audio/wav' as const,
+    bytesPrefix: [
+      0x52, // R
+      0x49, // I
+      0x46, // F
+      0x46, // F
+      null,
+      null,
+      null,
+      null,
+      0x57, // W
+      0x41, // A
+      0x56, // V
+      0x45, // E
+    ],
+  },
+  {
+    mediaType: 'audio/ogg' as const,
+    bytesPrefix: [0x4f, 0x67, 0x67, 0x53],
+  },
+  {
+    mediaType: 'audio/flac' as const,
+    bytesPrefix: [0x66, 0x4c, 0x61, 0x43],
+  },
+  {
+    mediaType: 'audio/aac' as const,
+    bytesPrefix: [0x40, 0x15, 0x00, 0x00],
+  },
+  {
+    mediaType: 'audio/mp4' as const,
+    bytesPrefix: [0x66, 0x74, 0x79, 0x70],
+  },
+  {
+    mediaType: 'audio/webm',
+    bytesPrefix: [0x1a, 0x45, 0xdf, 0xa3],
+  },
+] as const;
+
+const videoMediaTypeSignatures = [
+  {
+    mediaType: 'video/mp4' as const,
+    bytesPrefix: [
+      0x00,
+      0x00,
+      0x00,
+      null,
+      0x66,
+      0x74,
+      0x79,
+      0x70, // ftyp
+    ],
+  },
+  {
+    mediaType: 'video/webm' as const,
+    bytesPrefix: [0x1a, 0x45, 0xdf, 0xa3], // EBML
+  },
+  {
+    mediaType: 'video/quicktime' as const,
+    bytesPrefix: [
+      0x00,
+      0x00,
+      0x00,
+      0x14,
+      0x66,
+      0x74,
+      0x79,
+      0x70,
+      0x71,
+      0x74, // ftypqt
+    ],
+  },
+  {
+    mediaType: 'video/x-msvideo' as const,
+    bytesPrefix: [0x52, 0x49, 0x46, 0x46], // RIFF (AVI)
+  },
+] as const;
+
+const stripID3 = (data: Uint8Array | string) => {
+  const bytes =
+    typeof data === 'string' ? convertBase64ToUint8Array(data) : data;
+  const id3Size =
+    ((bytes[6] & 0x7f) << 21) |
+    ((bytes[7] & 0x7f) << 14) |
+    ((bytes[8] & 0x7f) << 7) |
+    (bytes[9] & 0x7f);
+
+  // The raw MP3 starts here
+  return bytes.slice(id3Size + 10);
+};
+
+function stripID3TagsIfPresent(data: Uint8Array | string): Uint8Array | string {
+  const hasId3 =
+    (typeof data === 'string' && data.startsWith('SUQz')) ||
+    (typeof data !== 'string' &&
+      data.length > 10 &&
+      data[0] === 0x49 && // 'I'
+      data[1] === 0x44 && // 'D'
+      data[2] === 0x33); // '3'
+
+  return hasId3 ? stripID3(data) : data;
+}
+
+type MediaTypeSignatures = ReadonlyArray<{
+  readonly mediaType: string;
+  readonly bytesPrefix: ReadonlyArray<number | null>;
+}>;
+
+function detectMediaTypeBySignatures<T extends MediaTypeSignatures>({
+  data,
+  signatures,
+}: {
+  data: Uint8Array | string;
+  signatures: T;
+}): T[number]['mediaType'] | undefined {
+  const processedData = stripID3TagsIfPresent(data);
+
+  // Convert the first ~18 bytes (24 base64 chars) for consistent detection logic:
+  const bytes =
+    typeof processedData === 'string'
+      ? convertBase64ToUint8Array(
+          processedData.substring(0, Math.min(processedData.length, 24)),
+        )
+      : processedData;
+
+  for (const signature of signatures) {
+    if (
+      bytes.length >= signature.bytesPrefix.length &&
+      signature.bytesPrefix.every(
+        (byte, index) => byte === null || bytes[index] === byte,
+      )
+    ) {
+      return signature.mediaType;
+    }
+  }
+
+  return undefined;
+}
+
+const topLevelSignatureTables = {
+  image: imageMediaTypeSignatures,
+  audio: audioMediaTypeSignatures,
+  video: videoMediaTypeSignatures,
+  application: documentMediaTypeSignatures,
+} as const;
+
+type TopLevelMediaType = keyof typeof topLevelSignatureTables;
+
+/**
+ * Detect the IANA media type of a file from its raw bytes or base64 string.
+ *
+ * - When `topLevelType` is omitted, every known signature is considered
+ *   (image, audio, video, and application). Returns `undefined` when the
+ *   bytes do not match any known signature.
+ * - When `topLevelType` is provided, only signatures for that top-level
+ *   segment are considered. Returns `undefined` for unsupported segments
+ *   (e.g. `"text"`) or when no signature matches.
+ */
+export function detectMediaType({
+  data,
+  topLevelType,
+}: {
+  data: Uint8Array | string;
+  topLevelType?: string;
+}): string | undefined {
+  if (topLevelType === undefined) {
+    return detectMediaTypeBySignatures({
+      data,
+      signatures: [
+        ...imageMediaTypeSignatures,
+        ...documentMediaTypeSignatures,
+        ...audioMediaTypeSignatures,
+        ...videoMediaTypeSignatures,
+      ],
+    });
+  }
+
+  const signatures = topLevelSignatureTables[topLevelType as TopLevelMediaType];
+
+  if (signatures === undefined) {
+    return undefined;
+  }
+
+  return detectMediaTypeBySignatures({ data, signatures });
+}
+
+/**
+ * Returns the top-level segment of a media type (the portion before `/`).
+ *
+ * Examples:
+ *   - `"image/png"` -> `"image"`
+ *   - `"image/*"` -> `"image"`
+ *   - `"image"` -> `"image"`
+ *   - `"image/"` -> `"image"`
+ *   - `""` -> `""`
+ *   - `"/"` -> `""`
+ */
+export function getTopLevelMediaType(mediaType: string): string {
+  const slashIndex = mediaType.indexOf('/');
+  return slashIndex === -1 ? mediaType : mediaType.substring(0, slashIndex);
+}
+
+/**
+ * Returns `true` only when the given media type has a non-empty, non-wildcard
+ * subtype (i.e. matches the form `type/subtype`, and `subtype` is not `*`).
+ *
+ * Examples:
+ *   - `"image/png"` -> `true`
+ *   - `"image/*"` -> `false`
+ *   - `"image"` -> `false`
+ *   - `"image/"` -> `false`
+ *   - `""` -> `false`
+ *   - `"/"` -> `false`
+ */
+export function isFullMediaType(mediaType: string): boolean {
+  const slashIndex = mediaType.indexOf('/');
+  if (slashIndex === -1) {
+    return false;
+  }
+  const subtype = mediaType.substring(slashIndex + 1);
+  return subtype.length > 0 && subtype !== '*';
+}

package/src/get-from-api.ts

@@ -1,9 +1,9 @@
 import { APICallError } from '@ai-sdk/provider';
 import { extractResponseHeaders } from './extract-response-headers';
-import { FetchFunction } from './fetch-function';
+import type { FetchFunction } from './fetch-function';
 import { handleFetchError } from './handle-fetch-error';
 import { isAbortError } from './is-abort-error';
-import { ResponseHandler } from './response-handler';
+import type { ResponseHandler } from './response-handler';
 import { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';
 import { withUserAgentSuffix } from './with-user-agent-suffix';
 import { VERSION } from './version';

package/src/index.ts

@@ -2,6 +2,7 @@ export { asArray } from './as-array';
 export type { Arrayable } from './as-array';
 export * from './combine-headers';
 export { convertAsyncIteratorToReadableStream } from './convert-async-iterator-to-readable-stream';
+export { convertInlineFileDataToUint8Array } from './convert-inline-file-data-to-uint8-array';
 export { convertImageModelFileToDataUri } from './convert-image-model-file-to-data-uri';
 export { convertToFormData } from './convert-to-form-data';
 export {
@@ -10,6 +11,11 @@ export {
 } from './create-tool-name-mapping';
 export * from './delay';
 export { DelayedPromise } from './delayed-promise';
+export {
+  detectMediaType,
+  getTopLevelMediaType,
+  isFullMediaType,
+} from './detect-media-type';
 export { downloadBlob } from './download-blob';
 export { DownloadError } from './download-error';
 export * from './extract-response-headers';
@@ -22,6 +28,7 @@ export { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-a
 export type { HasRequiredKey } from './has-required-key';
 export { injectJsonInstructionIntoMessages } from './inject-json-instruction';
 export * from './is-abort-error';
+export { isBuffer } from './is-buffer';
 export { isNonNullable } from './is-non-nullable';
 export { isProviderReference } from './is-provider-reference';
 export { isUrlSupported } from './is-url-supported';
@@ -56,6 +63,7 @@ export {
 } from './read-response-with-size-limit';
 export * from './remove-undefined-entries';
 export * from './resolve';
+export { resolveFullMediaType } from './resolve-full-media-type';
 export { resolveProviderReference } from './resolve-provider-reference';
 export * from './response-handler';
 export {

package/src/inject-json-instruction.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   JSONSchema7,
   LanguageModelV4Message,
   LanguageModelV4Prompt,

package/src/is-buffer.ts

@@ -0,0 +1,9 @@
+/**
+ * Type-guard for Node.js `Buffer` instances.
+ *
+ * Uses optional chaining on `globalThis.Buffer` so it returns `false` in
+ * runtimes where `Buffer` is not available (e.g. CloudFlare Workers).
+ */
+export function isBuffer(value: unknown): value is Buffer {
+  return globalThis.Buffer?.isBuffer(value) ?? false;
+}

package/src/is-json-serializable.ts

@@ -1,4 +1,4 @@
-import { JSONValue } from '@ai-sdk/provider';
+import type { JSONValue } from '@ai-sdk/provider';
 
 /**
  * Checks whether a value can cross a workflow serialization boundary.

package/src/is-provider-reference.ts

@@ -1,18 +1,21 @@
-import {
-  LanguageModelV4FilePart,
-  SharedV4ProviderReference,
-} from '@ai-sdk/provider';
+import type { SharedV4ProviderReference } from '@ai-sdk/provider';
+import { isBuffer } from './is-buffer';
 
 /**
- * Checks whether file part data is a provider reference (a mapping of provider
- * names to provider-specific identifiers) as opposed to raw bytes or a URL.
+ * Checks whether a value is a provider reference (a mapping of provider names
+ * to provider-specific identifiers) as opposed to raw bytes, a URL, or a
+ * tagged `{ type: ... }` object.
  */
 export function isProviderReference(
-  data: LanguageModelV4FilePart['data'],
+  data: unknown,
 ): data is SharedV4ProviderReference {
   return (
     typeof data === 'object' &&
+    data !== null &&
     !(data instanceof Uint8Array) &&
-    !(data instanceof URL)
+    !(data instanceof URL) &&
+    !(data instanceof ArrayBuffer) &&
+    !isBuffer(data) &&
+    !('type' in data)
   );
 }

package/src/is-url-supported.ts

@@ -1,7 +1,9 @@
 /**
  * Checks if the given URL is supported natively by the model.
  *
- * @param mediaType - The media type of the URL. Case-sensitive.
+ * @param mediaType - The media type of the URL. Case-sensitive. May be a full
+ *                    `type/subtype`, a wildcard `type/*`, or just the
+ *                    top-level segment (e.g. `image`).
  * @param url - The URL to check.
  * @param supportedUrls - A record where keys are case-sensitive media types (or '*')
  *                        and values are arrays of RegExp patterns for URLs.
@@ -22,6 +24,8 @@ export function isUrlSupported({
   url = url.toLowerCase();
   mediaType = mediaType.toLowerCase();
 
+  const isTopLevelOnly = !mediaType.includes('/');
+
   return (
     Object.entries(supportedUrls)
       // standardize supported url map into lowercase prefixes:
@@ -32,7 +36,18 @@ export function isUrlSupported({
           : { mediaTypePrefix: mediaType.replace(/\*/, ''), regexes: value };
       })
       // gather all regexp pattern from matched media type prefixes:
-      .filter(({ mediaTypePrefix }) => mediaType.startsWith(mediaTypePrefix))
+      .filter(({ mediaTypePrefix }) => {
+        if (mediaTypePrefix === '') {
+          return true;
+        }
+        // For a top-level-only media type (e.g. `image`), we cannot determine
+        // whether a specific subtype (e.g. `image/png`) would apply, so we
+        // only match the corresponding `type/*` prefix exactly.
+        if (isTopLevelOnly) {
+          return `${mediaType}/` === mediaTypePrefix;
+        }
+        return mediaType.startsWith(mediaTypePrefix);
+      })
       .flatMap(({ regexes }) => regexes)
       // check if any pattern matches the url:
       .some(pattern => pattern.test(url))

package/src/map-reasoning-to-provider.ts

@@ -1,4 +1,7 @@
-import { LanguageModelV4CallOptions, SharedV4Warning } from '@ai-sdk/provider';
+import type {
+  LanguageModelV4CallOptions,
+  SharedV4Warning,
+} from '@ai-sdk/provider';
 
 export type ReasoningLevel = Exclude<
   LanguageModelV4CallOptions['reasoning'],

package/src/parse-json-event-stream.ts

@@ -1,9 +1,9 @@
 import {
-  EventSourceMessage,
   EventSourceParserStream,
+  type EventSourceMessage,
 } from 'eventsource-parser/stream';
-import { ParseResult, safeParseJSON } from './parse-json';
-import { FlexibleSchema } from './schema';
+import { safeParseJSON, type ParseResult } from './parse-json';
+import type { FlexibleSchema } from './schema';
 
 /**
  * Parses a JSON event stream into a stream of parsed JSON objects.

package/src/parse-json.ts

@@ -1,11 +1,11 @@
 import {
   JSONParseError,
-  JSONValue,
   TypeValidationError,
+  type JSONValue,
 } from '@ai-sdk/provider';
 import { secureJsonParse } from './secure-json-parse';
 import { safeValidateTypes, validateTypes } from './validate-types';
-import { FlexibleSchema } from './schema';
+import type { FlexibleSchema } from './schema';
 
 /**
  * Parses a JSON string into an unknown object.

package/src/parse-provider-options.ts

@@ -1,6 +1,6 @@
 import { InvalidArgumentError } from '@ai-sdk/provider';
 import { safeValidateTypes } from './validate-types';
-import { FlexibleSchema } from './schema';
+import type { FlexibleSchema } from './schema';
 
 export async function parseProviderOptions<OPTIONS>({
   provider,

package/src/post-to-api.ts

@@ -1,9 +1,9 @@
 import { APICallError } from '@ai-sdk/provider';
 import { extractResponseHeaders } from './extract-response-headers';
-import { FetchFunction } from './fetch-function';
+import type { FetchFunction } from './fetch-function';
 import { handleFetchError } from './handle-fetch-error';
 import { isAbortError } from './is-abort-error';
-import { ResponseHandler } from './response-handler';
+import type { ResponseHandler } from './response-handler';
 import { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';
 import { withUserAgentSuffix } from './with-user-agent-suffix';
 import { VERSION } from './version';

package/src/provider-defined-tool-factory.ts

@@ -1,6 +1,7 @@
-import { tool, Tool, ToolExecuteFunction } from './types/tool';
-import { FlexibleSchema } from './schema';
-import { Context } from './types/context';
+import { tool, type ProviderDefinedTool, type Tool } from './types/tool';
+import type { FlexibleSchema } from './schema';
+import type { Context } from './types/context';
+import type { ToolExecuteFunction } from './types/tool-execute-function';
 /**
  * A provider-defined tool is a tool for which the provider defines the input
  * and output schemas, but does not execute the tool.
@@ -18,7 +19,7 @@ export type ProviderDefinedToolFactory<
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
   },
-) => Tool<INPUT, OUTPUT, CONTEXT>;
+) => ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>;
 
 export function createProviderDefinedToolFactory<
   INPUT,
@@ -48,7 +49,7 @@ export function createProviderDefinedToolFactory<
     onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
-  }): Tool<INPUT, OUTPUT, CONTEXT> =>
+  }): ProviderDefinedTool<INPUT, OUTPUT, CONTEXT> =>
     tool({
       type: 'provider',
       isProviderExecuted: false,
@@ -62,7 +63,7 @@ export function createProviderDefinedToolFactory<
       onInputStart,
       onInputDelta,
       onInputAvailable,
-    });
+    }) as ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>;
 }
 
 export type ProviderDefinedToolFactoryWithOutputSchema<
@@ -79,7 +80,7 @@ export type ProviderDefinedToolFactoryWithOutputSchema<
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
   },
-) => Tool<INPUT, OUTPUT, CONTEXT>;
+) => ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>;
 
 export function createProviderDefinedToolFactoryWithOutputSchema<
   INPUT,
@@ -110,7 +111,7 @@ export function createProviderDefinedToolFactoryWithOutputSchema<
     onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
     onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
     onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
-  }): Tool<INPUT, OUTPUT, CONTEXT> =>
+  }): ProviderDefinedTool<INPUT, OUTPUT, CONTEXT> =>
     tool({
       type: 'provider',
       isProviderExecuted: false,
@@ -124,5 +125,5 @@ export function createProviderDefinedToolFactoryWithOutputSchema<
       onInputStart,
       onInputDelta,
       onInputAvailable,
-    });
+    }) as ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>;
 }