@ai-sdk/provider-utils 4.0.5 → 4.0.7

package/src/download-error.ts

@@ -0,0 +1,39 @@
+import { AISDKError } from '@ai-sdk/provider';
+
+const name = 'AI_DownloadError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class DownloadError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly url: string;
+  readonly statusCode?: number;
+  readonly statusText?: string;
+
+  constructor({
+    url,
+    statusCode,
+    statusText,
+    cause,
+    message = cause == null
+      ? `Failed to download ${url}: ${statusCode} ${statusText}`
+      : `Failed to download ${url}: ${cause}`,
+  }: {
+    url: string;
+    statusCode?: number;
+    statusText?: string;
+    message?: string;
+    cause?: unknown;
+  }) {
+    super({ name, message, cause });
+
+    this.url = url;
+    this.statusCode = statusCode;
+    this.statusText = statusText;
+  }
+
+  static isInstance(error: unknown): error is DownloadError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/extract-response-headers.ts

@@ -0,0 +1,9 @@
+/**
+Extracts the headers from a response object and returns them as a key-value object.
+
+@param response - The response object to extract headers from.
+@returns The headers as a key-value object.
+*/
+export function extractResponseHeaders(response: Response) {
+  return Object.fromEntries<string>([...response.headers]);
+}

package/src/fetch-function.ts

@@ -0,0 +1,4 @@
+/**
+ * Fetch function type (standardizes the version of fetch used).
+ */
+export type FetchFunction = typeof globalThis.fetch;

package/src/generate-id.test.ts

@@ -0,0 +1,31 @@
+import { InvalidArgumentError } from '@ai-sdk/provider';
+import { expect, it } from 'vitest';
+import { createIdGenerator, generateId } from './generate-id';
+import { describe } from 'vitest';
+
+describe('createIdGenerator', () => {
+  it('should generate an ID with the correct length', () => {
+    const idGenerator = createIdGenerator({ size: 10 });
+    expect(idGenerator()).toHaveLength(10);
+  });
+
+  it('should generate an ID with the correct default length', () => {
+    const idGenerator = createIdGenerator();
+    expect(idGenerator()).toHaveLength(16);
+  });
+
+  it('should throw an error if the separator is part of the alphabet', () => {
+    expect(() => createIdGenerator({ separator: 'a', prefix: 'b' })).toThrow(
+      InvalidArgumentError,
+    );
+  });
+});
+
+describe('generateId', () => {
+  it('should generate unique IDs', () => {
+    const id1 = generateId();
+    const id2 = generateId();
+
+    expect(id1).not.toBe(id2);
+  });
+});

package/src/generate-id.ts

@@ -0,0 +1,57 @@
+import { InvalidArgumentError } from '@ai-sdk/provider';
+
+/**
+Creates an ID generator.
+The total length of the ID is the sum of the prefix, separator, and random part length.
+Not cryptographically secure.
+
+@param alphabet - The alphabet to use for the ID. Default: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'.
+@param prefix - The prefix of the ID to generate. Optional.
+@param separator - The separator between the prefix and the random part of the ID. Default: '-'.
+@param size - The size of the random part of the ID to generate. Default: 16.
+ */
+export const createIdGenerator = ({
+  prefix,
+  size = 16,
+  alphabet = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+  separator = '-',
+}: {
+  prefix?: string;
+  separator?: string;
+  size?: number;
+  alphabet?: string;
+} = {}): IdGenerator => {
+  const generator = () => {
+    const alphabetLength = alphabet.length;
+    const chars = new Array(size);
+    for (let i = 0; i < size; i++) {
+      chars[i] = alphabet[(Math.random() * alphabetLength) | 0];
+    }
+    return chars.join('');
+  };
+
+  if (prefix == null) {
+    return generator;
+  }
+
+  // check that the prefix is not part of the alphabet (otherwise prefix checking can fail randomly)
+  if (alphabet.includes(separator)) {
+    throw new InvalidArgumentError({
+      argument: 'separator',
+      message: `The separator "${separator}" must not be part of the alphabet "${alphabet}".`,
+    });
+  }
+
+  return () => `${prefix}${separator}${generator()}`;
+};
+
+/**
+A function that generates an ID.
+ */
+export type IdGenerator = () => string;
+
+/**
+Generates a 16-character random string to use for IDs.
+Not cryptographically secure.
+ */
+export const generateId = createIdGenerator();

package/src/get-error-message.ts

@@ -0,0 +1,15 @@
+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);
+}

package/src/get-from-api.test.ts

@@ -0,0 +1,199 @@
+import { APICallError } from '@ai-sdk/provider';
+import { describe, it, expect, vi } from 'vitest';
+import { getFromApi } from './get-from-api';
+import {
+  createJsonResponseHandler,
+  createStatusCodeErrorResponseHandler,
+} from './response-handler';
+import { z } from 'zod/v4';
+import { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';
+import { withUserAgentSuffix } from './with-user-agent-suffix';
+
+vi.mock('./get-runtime-environment-user-agent', async () => {
+  const actual = await vi.importActual('./get-runtime-environment-user-agent');
+  return {
+    ...actual,
+    getRuntimeEnvironmentUserAgent: () => 'runtime/test-env',
+  };
+});
+
+describe('getFromApi', () => {
+  const mockSuccessResponse = {
+    name: 'test',
+    value: 123,
+  };
+
+  const mockResponseSchema = z.object({
+    name: z.string(),
+    value: z.number(),
+  });
+
+  const mockHeaders = {
+    'Content-Type': 'application/json',
+    Authorization: 'Bearer test',
+    'user-agent': 'runtime/test-env',
+  };
+
+  it('should successfully fetch and parse data', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify(mockSuccessResponse), {
+        status: 200,
+        headers: withUserAgentSuffix(
+          mockHeaders,
+          getRuntimeEnvironmentUserAgent(),
+        ),
+      }),
+    );
+
+    const result = await getFromApi({
+      url: 'https://api.test.com/data',
+      headers: { Authorization: 'Bearer test' },
+      successfulResponseHandler: createJsonResponseHandler(mockResponseSchema),
+      failedResponseHandler: createStatusCodeErrorResponseHandler(),
+      fetch: mockFetch,
+    });
+
+    expect(result.value).toEqual(mockSuccessResponse);
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.test.com/data',
+      expect.objectContaining({
+        method: 'GET',
+        headers: {
+          authorization: 'Bearer test',
+          'user-agent': 'ai-sdk/provider-utils/0.0.0-test runtime/test-env',
+        },
+      }),
+    );
+  });
+
+  it('should handle API errors', async () => {
+    const errorResponse = { error: 'Not Found' };
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify(errorResponse), {
+        status: 404,
+        statusText: 'Not Found',
+        headers: mockHeaders,
+      }),
+    );
+
+    await expect(
+      getFromApi({
+        url: 'https://api.test.com/data',
+        successfulResponseHandler:
+          createJsonResponseHandler(mockResponseSchema),
+        failedResponseHandler: createStatusCodeErrorResponseHandler(),
+        fetch: mockFetch,
+      }),
+    ).rejects.toThrow(APICallError);
+  });
+
+  it('should handle network errors', async () => {
+    const mockFetch = vi.fn().mockRejectedValue(
+      Object.assign(new TypeError('fetch failed'), {
+        cause: new Error('Failed to connect'),
+      }),
+    );
+
+    await expect(
+      getFromApi({
+        url: 'https://api.test.com/data',
+        successfulResponseHandler:
+          createJsonResponseHandler(mockResponseSchema),
+        failedResponseHandler: createStatusCodeErrorResponseHandler(),
+        fetch: mockFetch,
+      }),
+    ).rejects.toThrow('Cannot connect to API: Failed to connect');
+  });
+
+  it('should handle abort signals', async () => {
+    const abortController = new AbortController();
+    const mockFetch = vi.fn().mockImplementation(() => {
+      abortController.abort();
+      return Promise.reject(new DOMException('Aborted', 'AbortError'));
+    });
+
+    await expect(
+      getFromApi({
+        url: 'https://api.test.com/data',
+        successfulResponseHandler:
+          createJsonResponseHandler(mockResponseSchema),
+        failedResponseHandler: createStatusCodeErrorResponseHandler(),
+        fetch: mockFetch,
+        abortSignal: abortController.signal,
+      }),
+    ).rejects.toThrow('Aborted');
+  });
+
+  it('should remove undefined header entries', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify(mockSuccessResponse), {
+        status: 200,
+        headers: mockHeaders,
+      }),
+    );
+
+    await getFromApi({
+      url: 'https://api.test.com/data',
+      headers: {
+        Authorization: 'Bearer test',
+        'X-Custom-Header': undefined,
+      },
+      successfulResponseHandler: createJsonResponseHandler(mockResponseSchema),
+      failedResponseHandler: createStatusCodeErrorResponseHandler(),
+      fetch: mockFetch,
+    });
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.test.com/data',
+      expect.objectContaining({
+        headers: {
+          authorization: 'Bearer test',
+          'user-agent': 'ai-sdk/provider-utils/0.0.0-test runtime/test-env',
+        },
+      }),
+    );
+  });
+
+  it('should handle errors in response handlers', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response('invalid json', {
+        status: 200,
+        headers: mockHeaders,
+      }),
+    );
+
+    await expect(
+      getFromApi({
+        url: 'https://api.test.com/data',
+        successfulResponseHandler:
+          createJsonResponseHandler(mockResponseSchema),
+        failedResponseHandler: createStatusCodeErrorResponseHandler(),
+        fetch: mockFetch,
+      }),
+    ).rejects.toThrow(APICallError);
+  });
+
+  it('should use default fetch when not provided', async () => {
+    const originalFetch = global.fetch;
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify(mockSuccessResponse), {
+        status: 200,
+        headers: mockHeaders,
+      }),
+    );
+    global.fetch = mockFetch;
+
+    try {
+      await getFromApi({
+        url: 'https://api.test.com/data',
+        successfulResponseHandler:
+          createJsonResponseHandler(mockResponseSchema),
+        failedResponseHandler: createStatusCodeErrorResponseHandler(),
+      });
+
+      expect(mockFetch).toHaveBeenCalled();
+    } finally {
+      global.fetch = originalFetch;
+    }
+  });
+});

package/src/get-from-api.ts

@@ -0,0 +1,97 @@
+import { APICallError } from '@ai-sdk/provider';
+import { extractResponseHeaders } from './extract-response-headers';
+import { FetchFunction } from './fetch-function';
+import { handleFetchError } from './handle-fetch-error';
+import { isAbortError } from './is-abort-error';
+import { ResponseHandler } from './response-handler';
+import { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';
+import { withUserAgentSuffix } from './with-user-agent-suffix';
+import { VERSION } from './version';
+
+// use function to allow for mocking in tests:
+const getOriginalFetch = () => globalThis.fetch;
+
+export const getFromApi = async <T>({
+  url,
+  headers = {},
+  successfulResponseHandler,
+  failedResponseHandler,
+  abortSignal,
+  fetch = getOriginalFetch(),
+}: {
+  url: string;
+  headers?: Record<string, string | undefined>;
+  failedResponseHandler: ResponseHandler<Error>;
+  successfulResponseHandler: ResponseHandler<T>;
+  abortSignal?: AbortSignal;
+  fetch?: FetchFunction;
+}) => {
+  try {
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: withUserAgentSuffix(
+        headers,
+        `ai-sdk/provider-utils/${VERSION}`,
+        getRuntimeEnvironmentUserAgent(),
+      ),
+      signal: abortSignal,
+    });
+
+    const responseHeaders = extractResponseHeaders(response);
+
+    if (!response.ok) {
+      let errorInformation: {
+        value: Error;
+        responseHeaders?: Record<string, string> | undefined;
+      };
+
+      try {
+        errorInformation = await failedResponseHandler({
+          response,
+          url,
+          requestBodyValues: {},
+        });
+      } catch (error) {
+        if (isAbortError(error) || APICallError.isInstance(error)) {
+          throw error;
+        }
+
+        throw new APICallError({
+          message: 'Failed to process error response',
+          cause: error,
+          statusCode: response.status,
+          url,
+          responseHeaders,
+          requestBodyValues: {},
+        });
+      }
+
+      throw errorInformation.value;
+    }
+
+    try {
+      return await successfulResponseHandler({
+        response,
+        url,
+        requestBodyValues: {},
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        if (isAbortError(error) || APICallError.isInstance(error)) {
+          throw error;
+        }
+      }
+
+      throw new APICallError({
+        message: 'Failed to process successful response',
+        cause: error,
+        statusCode: response.status,
+        url,
+        responseHeaders,
+        requestBodyValues: {},
+      });
+    }
+  } catch (error) {
+    throw handleFetchError({ error, url, requestBodyValues: {} });
+  }
+};

package/src/get-runtime-environment-user-agent.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Stabilize provider utils version used inside UA string construction
+vi.mock('./version', () => ({
+  VERSION: '0.0.0-test',
+}));
+
+import { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-agent';
+
+describe('getRuntimeEnvironmentUserAgent', () => {
+  it('should return the correct user agent for browsers', () => {
+    expect(
+      getRuntimeEnvironmentUserAgent({
+        window: true,
+      }),
+    ).toBe('runtime/browser');
+  });
+
+  it('should return the correct user agent for test', () => {
+    expect(
+      getRuntimeEnvironmentUserAgent({
+        navigator: {
+          userAgent: 'test',
+        },
+      }),
+    ).toBe('runtime/test');
+  });
+
+  it('should return the correct user agent for Edge Runtime', () => {
+    expect(
+      getRuntimeEnvironmentUserAgent({
+        EdgeRuntime: true,
+      }),
+    ).toBe('runtime/vercel-edge');
+  });
+
+  it('should return the correct user agent for Node.js', () => {
+    expect(
+      getRuntimeEnvironmentUserAgent({
+        process: {
+          versions: { node: 'test' },
+          version: 'test',
+        },
+      }),
+    ).toBe('runtime/node.js/test');
+  });
+});

package/src/get-runtime-environment-user-agent.ts

@@ -0,0 +1,24 @@
+export function getRuntimeEnvironmentUserAgent(
+  globalThisAny: any = globalThis as any,
+): string {
+  // Browsers
+  if (globalThisAny.window) {
+    return `runtime/browser`;
+  }
+
+  // Cloudflare Workers / Deno / Bun / Node.js >= 21.1
+  if (globalThisAny.navigator?.userAgent) {
+    return `runtime/${globalThisAny.navigator.userAgent.toLowerCase()}`;
+  }
+
+  // Nodes.js < 21.1
+  if (globalThisAny.process?.versions?.node) {
+    return `runtime/node.js/${globalThisAny.process.version.substring(0)}`;
+  }
+
+  if (globalThisAny.EdgeRuntime) {
+    return `runtime/vercel-edge`;
+  }
+
+  return 'runtime/unknown';
+}

package/src/handle-fetch-error.ts

@@ -0,0 +1,39 @@
+import { APICallError } from '@ai-sdk/provider';
+import { isAbortError } from './is-abort-error';
+
+const FETCH_FAILED_ERROR_MESSAGES = ['fetch failed', 'failed to fetch'];
+
+export function handleFetchError({
+  error,
+  url,
+  requestBodyValues,
+}: {
+  error: unknown;
+  url: string;
+  requestBodyValues: unknown;
+}) {
+  if (isAbortError(error)) {
+    return error;
+  }
+
+  // unwrap original error when fetch failed (for easier debugging):
+  if (
+    error instanceof TypeError &&
+    FETCH_FAILED_ERROR_MESSAGES.includes(error.message.toLowerCase())
+  ) {
+    const cause = (error as any).cause;
+
+    if (cause != null) {
+      // Failed to connect to server:
+      return new APICallError({
+        message: `Cannot connect to API: ${cause.message}`,
+        cause,
+        url,
+        requestBodyValues,
+        isRetryable: true, // retry when network error
+      });
+    }
+  }
+
+  return error;
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+export * from './combine-headers';
+export { convertAsyncIteratorToReadableStream } from './convert-async-iterator-to-readable-stream';
+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 { downloadBlob } from './download-blob';
+export { DownloadError } from './download-error';
+export * from './fetch-function';
+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 { injectJsonInstructionIntoMessages } from './inject-json-instruction';
+export * from './is-abort-error';
+export { isNonNullable } from './is-non-nullable';
+export { isUrlSupported } from './is-url-supported';
+export * from './load-api-key';
+export { loadOptionalSetting } from './load-optional-setting';
+export { loadSetting } from './load-setting';
+export { type MaybePromiseLike } from './maybe-promise-like';
+export { mediaTypeToExtension } from './media-type-to-extension';
+export { normalizeHeaders } from './normalize-headers';
+export * from './parse-json';
+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';
+export * from './remove-undefined-entries';
+export * from './resolve';
+export * from './response-handler';
+export {
+  asSchema,
+  jsonSchema,
+  lazySchema,
+  zodSchema,
+  type FlexibleSchema,
+  type InferSchema,
+  type LazySchema,
+  type Schema,
+  type ValidationResult,
+} from './schema';
+export * from './uint8-utils';
+export * from './validate-types';
+export { VERSION } from './version';
+export { withUserAgentSuffix } from './with-user-agent-suffix';
+export * from './without-trailing-slash';
+
+// folder re-exports
+export * from './types';
+
+// external re-exports
+export * from '@standard-schema/spec';
+export {
+  EventSourceParserStream,
+  type EventSourceMessage,
+} from 'eventsource-parser/stream';