@ai-sdk/provider-utils 5.0.0-beta.4 → 5.0.0-beta.49

package/src/fetch-with-validated-redirects.ts

@@ -0,0 +1,87 @@
+import { cancelResponseBody } from './cancel-response-body';
+import { DownloadError } from './download-error';
+import { isBrowserRuntime } from './is-browser-runtime';
+import { validateDownloadUrl } from './validate-download-url';
+
+const MAX_DOWNLOAD_REDIRECTS = 10;
+
+/**
+ * Fetches a URL while enforcing the SSRF download guard on every hop.
+ *
+ * Redirects are followed manually (`redirect: 'manual'`) so each hop is
+ * validated with {@link validateDownloadUrl} *before* it is requested. Relying
+ * on the default `redirect: 'follow'` would issue the request to a redirect
+ * target (e.g. an internal address) before we ever see its URL, defeating the
+ * SSRF guard.
+ *
+ * A `redirect: 'manual'` request yields an unreadable opaque response in the
+ * browser (and in other spec-compliant fetch implementations), so the redirect
+ * target cannot be validated here. In a real browser this is safe to follow
+ * natively because SSRF is not reachable (fetch is constrained by CORS and
+ * cannot reach a server's internal network or cloud-metadata). On any other
+ * runtime we cannot validate the hop, so we fail closed rather than follow it
+ * blindly and bypass the SSRF guard.
+ *
+ * The returned response is the final (non-redirect) response. The caller is
+ * responsible for checking `response.ok` and reading the body.
+ *
+ * @throws DownloadError if a hop is unsafe, the redirect limit is exceeded, or
+ * a redirect cannot be validated on a non-browser runtime.
+ */
+export async function fetchWithValidatedRedirects({
+  url,
+  headers,
+  abortSignal,
+  maxRedirects = MAX_DOWNLOAD_REDIRECTS,
+}: {
+  url: string;
+  headers?: HeadersInit;
+  abortSignal?: AbortSignal;
+  maxRedirects?: number;
+}): Promise<Response> {
+  // Per-hop request options. Only the `redirect` mode varies between hops, so
+  // the rest is assembled once. `headers` is omitted entirely when not provided
+  // so callers that send none issue a bare request.
+  const baseInit: RequestInit = { signal: abortSignal };
+  if (headers !== undefined) {
+    baseInit.headers = headers;
+  }
+
+  let currentUrl = url;
+  // The bound also acts as a backstop against an unterminated redirect chain.
+  for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
+    validateDownloadUrl(currentUrl);
+
+    const response = await fetch(currentUrl, {
+      ...baseInit,
+      redirect: 'manual',
+    });
+
+    if (response.type === 'opaqueredirect') {
+      if (!isBrowserRuntime()) {
+        throw new DownloadError({
+          url,
+          message: `Redirect from ${currentUrl} could not be validated and was blocked`,
+        });
+      }
+      return await fetch(currentUrl, { ...baseInit, redirect: 'follow' });
+    }
+
+    const location = response.headers.get('location');
+    if (response.status >= 300 && response.status < 400 && location) {
+      // Release the redirect response's connection before moving to the next
+      // hop. Whether that hop is followed or rejected by the SSRF guard, an
+      // unconsumed 3xx body would leak the underlying socket.
+      await cancelResponseBody(response);
+      currentUrl = new URL(location, currentUrl).toString();
+      continue;
+    }
+
+    return response;
+  }
+
+  throw new DownloadError({
+    url,
+    message: `Too many redirects (max ${maxRedirects})`,
+  });
+}

package/src/filter-nullable.ts

@@ -0,0 +1,11 @@
+/**
+ * Filters `null` and `undefined` values out of a list of values.
+ *
+ * @param values - The values to filter.
+ * @returns A new array containing only non-nullish values.
+ */
+export function filterNullable<T>(
+  ...values: Array<T | undefined | null>
+): Array<T> {
+  return values.filter((value): value is NonNullable<T> => value != null);
+}

package/src/get-error-message.ts

@@ -1,15 +1 @@
-export function getErrorMessage(error: unknown | undefined) {
-  if (error == null) {
-    return 'unknown error';
-  }
-
-  if (typeof error === 'string') {
-    return error;
-  }
-
-  if (error instanceof Error) {
-    return error.message;
-  }
-
-  return JSON.stringify(error);
-}
+export { getErrorMessage } from '@ai-sdk/provider';

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/has-required-key.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks if an object has required keys.
+ * @param OBJECT - The object to check.
+ * @returns True if the object has required keys, false otherwise.
+ */
+export type HasRequiredKey<OBJECT> = {} extends OBJECT ? false : true;

package/src/index.ts

@@ -1,32 +1,49 @@
+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 {
   createToolNameMapping,
   type ToolNameMapping,
 } from './create-tool-name-mapping';
 export * from './delay';
 export { DelayedPromise } from './delayed-promise';
-export * from './extract-response-headers';
-export { convertImageModelFileToDataUri } from './convert-image-model-file-to-data-uri';
-export { convertToFormData } from './convert-to-form-data';
+export {
+  detectMediaType,
+  getTopLevelMediaType,
+  isFullMediaType,
+} from './detect-media-type';
 export { downloadBlob } from './download-blob';
 export { DownloadError } from './download-error';
-export {
-  readResponseWithSizeLimit,
-  DEFAULT_MAX_DOWNLOAD_SIZE,
-} from './read-response-with-size-limit';
+export { fetchWithValidatedRedirects } from './fetch-with-validated-redirects';
+export { extractLines } from './extract-lines';
+export * from './extract-response-headers';
 export * from './fetch-function';
+export { filterNullable } from './filter-nullable';
 export { createIdGenerator, generateId, type IdGenerator } from './generate-id';
 export * from './get-error-message';
 export * from './get-from-api';
 export { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';
+export type { HasRequiredKey } from './has-required-key';
 export { injectJsonInstructionIntoMessages } from './inject-json-instruction';
 export * from './is-abort-error';
+export { isBrowserRuntime } from './is-browser-runtime';
+export { isBuffer } from './is-buffer';
+export { isSameOrigin } from './is-same-origin';
 export { isNonNullable } from './is-non-nullable';
+export { isProviderReference } from './is-provider-reference';
 export { isUrlSupported } from './is-url-supported';
 export * from './load-api-key';
 export { loadOptionalSetting } from './load-optional-setting';
 export { loadSetting } from './load-setting';
+export {
+  isCustomReasoning,
+  mapReasoningToProviderBudget,
+  mapReasoningToProviderEffort,
+} from './map-reasoning-to-provider';
 export { type MaybePromiseLike } from './maybe-promise-like';
 export { mediaTypeToExtension } from './media-type-to-extension';
 export { normalizeHeaders } from './normalize-headers';
@@ -35,13 +52,24 @@ export { parseJsonEventStream } from './parse-json-event-stream';
 export { parseProviderOptions } from './parse-provider-options';
 export * from './post-to-api';
 export {
-  createProviderToolFactory,
-  createProviderToolFactoryWithOutputSchema,
-  type ProviderToolFactory,
-  type ProviderToolFactoryWithOutputSchema,
-} from './provider-tool-factory';
+  createProviderDefinedToolFactory,
+  createProviderDefinedToolFactoryWithOutputSchema,
+  type ProviderDefinedToolFactory,
+  type ProviderDefinedToolFactoryWithOutputSchema,
+} from './provider-defined-tool-factory';
+export {
+  createProviderExecutedToolFactory,
+  type ProviderExecutedToolFactory,
+} from './provider-executed-tool-factory';
+export { cancelResponseBody } from './cancel-response-body';
+export {
+  DEFAULT_MAX_DOWNLOAD_SIZE,
+  readResponseWithSizeLimit,
+} 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 {
   asSchema,
@@ -54,6 +82,12 @@ export {
   type Schema,
   type ValidationResult,
 } from './schema';
+export { serializeModelOptions } from './serialize-model-options';
+export {
+  StreamingToolCallTracker,
+  type StreamingToolCallDelta,
+  type StreamingToolCallTrackerOptions,
+} from './streaming-tool-call-tracker';
 export { stripFileExtension } from './strip-file-extension';
 export * from './uint8-utils';
 export { validateDownloadUrl } from './validate-download-url';
@@ -67,6 +101,7 @@ export * from './types';
 
 // external re-exports
 export type * from '@standard-schema/spec';
+export { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
 export {
   EventSourceParserStream,
   type EventSourceMessage,

package/src/inject-json-instruction.ts

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

package/src/is-browser-runtime.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns `true` when running in a browser.
+ *
+ * Detection keys on the presence of a global `window`, matching the browser
+ * check used elsewhere in this package (see `getRuntimeEnvironmentUserAgent`)
+ * so the SDK has a single, consistent definition of "browser". Server runtimes
+ * (Node.js, Deno, Bun, edge/workers) do not define `window`.
+ */
+export function isBrowserRuntime(
+  globalThisAny: any = globalThis as any,
+): boolean {
+  return globalThisAny.window != null;
+}

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

@@ -0,0 +1,29 @@
+import type { JSONValue } from '@ai-sdk/provider';
+
+/**
+ * Checks whether a value can cross a workflow serialization boundary.
+ *
+ * The check accepts JSON-like primitives, arrays, and plain objects whose
+ * nested values are also serializable. It rejects functions, symbols,
+ * bigints, and non-plain objects such as class instances, dates, and regexes.
+ */
+export function isJSONSerializable(value: unknown): value is JSONValue {
+  if (value === null || value === undefined) return true;
+
+  const type = typeof value;
+  if (type === 'string' || type === 'number' || type === 'boolean') return true;
+  if (type === 'function' || type === 'symbol' || type === 'bigint')
+    return false;
+
+  if (Array.isArray(value)) {
+    return value.every(isJSONSerializable);
+  }
+
+  if (Object.getPrototypeOf(value) === Object.prototype) {
+    return Object.values(value as Record<string, unknown>).every(
+      isJSONSerializable,
+    );
+  }
+
+  return false;
+}

package/src/is-provider-reference.ts

@@ -0,0 +1,21 @@
+import type { SharedV4ProviderReference } from '@ai-sdk/provider';
+import { isBuffer } from './is-buffer';
+
+/**
+ * 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: unknown,
+): data is SharedV4ProviderReference {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    !(data instanceof Uint8Array) &&
+    !(data instanceof URL) &&
+    !(data instanceof ArrayBuffer) &&
+    !isBuffer(data) &&
+    !('type' in data)
+  );
+}

package/src/is-same-origin.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns true when `url` has the same origin (scheme + host + port) as
+ * `baseUrl`.
+ *
+ * Used to decide whether provider credentials may be attached to a request to a
+ * URL taken from a provider response (e.g. a polling or media-download URL).
+ * Credentials must only be sent to the provider's own origin; a response that
+ * names a foreign host (a CDN, or an attacker-controlled host if the response
+ * is tampered with) must not receive the API key.
+ *
+ * Returns false if either value is not a valid absolute URL (fail-closed).
+ */
+export function isSameOrigin(url: string, baseUrl: string): boolean {
+  try {
+    return new URL(url).origin === new URL(baseUrl).origin;
+  } catch {
+    return false;
+  }
+}

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/load-api-key.ts

@@ -23,7 +23,7 @@ export function loadApiKey({
 
   if (typeof process === 'undefined') {
     throw new LoadAPIKeyError({
-      message: `${description} API key is missing. Pass it using the '${apiKeyParameterName}' parameter. Environment variables is not supported in this environment.`,
+      message: `${description} API key is missing. Pass it using the '${apiKeyParameterName}' parameter. Environment variables are not supported in this environment.`,
     });
   }
 

package/src/load-setting.ts

@@ -35,7 +35,7 @@ export function loadSetting({
       message:
         `${description} setting is missing. ` +
         `Pass it using the '${settingName}' parameter. ` +
-        `Environment variables is not supported in this environment.`,
+        `Environment variables are not supported in this environment.`,
     });
   }
 

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

@@ -0,0 +1,108 @@
+import type {
+  LanguageModelV4CallOptions,
+  SharedV4Warning,
+} from '@ai-sdk/provider';
+
+export type ReasoningLevel = Exclude<
+  LanguageModelV4CallOptions['reasoning'],
+  'none' | 'provider-default' | undefined
+>;
+
+export function isCustomReasoning(
+  reasoning: LanguageModelV4CallOptions['reasoning'],
+): reasoning is Exclude<
+  LanguageModelV4CallOptions['reasoning'],
+  'provider-default' | undefined
+> {
+  return reasoning !== undefined && reasoning !== 'provider-default';
+}
+
+/**
+ * Maps a top-level reasoning level to a provider-specific effort string using
+ * the given effort map. Pushes a compatibility warning if the reasoning level
+ * maps to a different string, or an unsupported warning if the level is not
+ * present in the map.
+ *
+ * @returns The mapped effort string, or `undefined` if the level is not
+ *   supported.
+ */
+export function mapReasoningToProviderEffort<T extends string>({
+  reasoning,
+  effortMap,
+  warnings,
+}: {
+  reasoning: ReasoningLevel;
+  effortMap: Partial<Record<ReasoningLevel, T>>;
+  warnings: SharedV4Warning[];
+}): T | undefined {
+  const mapped = effortMap[reasoning];
+
+  if (mapped == null) {
+    warnings.push({
+      type: 'unsupported',
+      feature: 'reasoning',
+      details: `reasoning "${reasoning}" is not supported by this model.`,
+    });
+    return undefined;
+  }
+
+  if (mapped !== reasoning) {
+    warnings.push({
+      type: 'compatibility',
+      feature: 'reasoning',
+      details: `reasoning "${reasoning}" is not directly supported by this model. mapped to effort "${mapped}".`,
+    });
+  }
+
+  return mapped;
+}
+
+const DEFAULT_REASONING_BUDGET_PERCENTAGES: Record<ReasoningLevel, number> = {
+  minimal: 0.02,
+  low: 0.1,
+  medium: 0.3,
+  high: 0.6,
+  xhigh: 0.9,
+};
+
+/**
+ * Maps a top-level reasoning level to an absolute token budget by multiplying
+ * the model's max output tokens by a percentage from the budget percentages
+ * map. The result is clamped between `minReasoningBudget` (default 1024) and
+ * `maxReasoningBudget`. Pushes an unsupported warning if the level is not
+ * present in the budget percentages map.
+ *
+ * @returns The computed token budget, or `undefined` if the level is not
+ *   supported.
+ */
+export function mapReasoningToProviderBudget({
+  reasoning,
+  maxOutputTokens,
+  maxReasoningBudget,
+  minReasoningBudget = 1024,
+  budgetPercentages = DEFAULT_REASONING_BUDGET_PERCENTAGES,
+  warnings,
+}: {
+  reasoning: ReasoningLevel;
+  maxOutputTokens: number;
+  maxReasoningBudget: number;
+  minReasoningBudget?: number;
+  budgetPercentages?: Partial<Record<ReasoningLevel, number>>;
+  warnings: SharedV4Warning[];
+}): number | undefined {
+  const pct = budgetPercentages[reasoning];
+
+  if (pct == null) {
+    warnings.push({
+      type: 'unsupported',
+      feature: 'reasoning',
+      details: `reasoning "${reasoning}" is not supported by this model.`,
+    });
+    return undefined;
+  }
+
+  return Math.min(
+    maxReasoningBudget,
+    Math.max(minReasoningBudget, Math.round(maxOutputTokens * pct)),
+  );
+}

package/src/maybe-promise-like.ts

@@ -1,3 +1,6 @@
+/**
+ * A value that can be provided either synchronously or as a promise-like.
+ */
 export type MaybePromiseLike<T> =
   | T // Raw value
   | PromiseLike<T>; // Promise of value

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.
@@ -43,7 +43,7 @@ export async function parseJSON<T>({
       return value;
     }
 
-    return validateTypes<T>({ value, schema });
+    return await validateTypes<T>({ value, schema });
   } catch (error) {
     if (
       JSONParseError.isInstance(error) ||

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';
@@ -28,7 +28,7 @@ export const postJsonToApi = async <T>({
   abortSignal?: AbortSignal;
   fetch?: FetchFunction;
 }) =>
-  postToApi({
+  await postToApi({
     url,
     headers: {
       'Content-Type': 'application/json',
@@ -61,7 +61,7 @@ export const postFormDataToApi = async <T>({
   abortSignal?: AbortSignal;
   fetch?: FetchFunction;
 }) =>
-  postToApi({
+  await postToApi({
     url,
     headers,
     body: {