@ai-sdk/provider-utils 4.0.4 → 4.0.6

package/src/is-url-supported.test.ts

@@ -0,0 +1,282 @@
+import { isUrlSupported } from './is-url-supported';
+import { describe, expect, it } from 'vitest';
+
+describe('isUrlSupported', () => {
+  describe('when the model does not support any URLs', () => {
+    it('should return false', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://example.com',
+          supportedUrls: {},
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('when the model supports specific media types and URLs', () => {
+    it('should return true for exact media type and exact URL match', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://example.com',
+          supportedUrls: { 'text/plain': [/https:\/\/example\.com/] },
+        }),
+      ).toBe(true);
+    });
+
+    it('should return true for exact media type and regex URL match', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'image/png',
+          url: 'https://images.example.com/cat.png',
+          supportedUrls: {
+            'image/png': [/https:\/\/images\.example\.com\/.+/],
+          },
+        }),
+      ).toBe(true);
+    });
+
+    it('should return true for exact media type and one of multiple regex URLs match', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'image/png',
+          url: 'https://another.com/img.png',
+          supportedUrls: {
+            'image/png': [
+              /https:\/\/images\.example\.com\/.+/,
+              /https:\/\/another\.com\/img\.png/,
+            ],
+          },
+        }),
+      ).toBe(true);
+    });
+
+    it('should return false for exact media type but URL mismatch', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://another.com',
+          supportedUrls: { 'text/plain': [/https:\/\/example\.com/] },
+        }),
+      ).toBe(false);
+    });
+
+    it('should return false for URL match but media type mismatch', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'image/png', // Different media type
+          url: 'https://example.com',
+          supportedUrls: { 'text/plain': [/https:\/\/example\.com/] },
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('when the model supports URLs via wildcard media type (*)', () => {
+    it('should return true for wildcard media type and exact URL match', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://example.com',
+          supportedUrls: { '*': [/https:\/\/example\.com/] },
+        }),
+      ).toBe(true);
+    });
+
+    it('should return true for wildcard media type and regex URL match', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'image/jpeg',
+          url: 'https://images.example.com/dog.jpg',
+          supportedUrls: { '*': [/https:\/\/images\.example\.com\/.+/] },
+        }),
+      ).toBe(true);
+    });
+
+    it('should return false for wildcard media type but URL mismatch', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'video/mp4',
+          url: 'https://another.com',
+          supportedUrls: { '*': [/https:\/\/example\.com/] },
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('when both specific and wildcard media types are defined', () => {
+    const supportedUrls = {
+      'text/plain': [/https:\/\/text\.com/],
+      '*': [/https:\/\/any\.com/],
+    };
+
+    it('should return true if URL matches under specific media type', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://text.com',
+          supportedUrls,
+        }),
+      ).toBe(true);
+    });
+
+    it('should return true if URL matches under wildcard media type even if specific exists', async () => {
+      // Assumes the logic checks specific first, then falls back to wildcard
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain', // Specific type exists
+          url: 'https://any.com', // Matches wildcard
+          supportedUrls,
+        }),
+      ).toBe(true);
+    });
+
+    it('should return true if URL matches under wildcard for a non-specified media type', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'image/png', // No specific entry for this type
+          url: 'https://any.com', // Matches wildcard
+          supportedUrls,
+        }),
+      ).toBe(true);
+    });
+
+    it('should return false if URL matches neither specific nor wildcard', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://other.com',
+          supportedUrls,
+        }),
+      ).toBe(false);
+    });
+
+    it('should return false if URL does not match wildcard for a non-specified media type', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'image/png',
+          url: 'https://other.com',
+          supportedUrls,
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should return true if an empty URL matches a pattern', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: '',
+          supportedUrls: { 'text/plain': [/.*/] }, // Matches any string, including empty
+        }),
+      ).toBe(true);
+    });
+
+    it('should return false if an empty URL does not match a pattern', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: '',
+          supportedUrls: { 'text/plain': [/https:\/\/.+/] }, // Requires non-empty string
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('case sensitivity', () => {
+    it('should be case-insensitive for media types', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'TEXT/PLAIN', // Uppercase
+          url: 'https://example.com',
+          supportedUrls: { 'text/plain': [/https:\/\/example\.com/] }, // Lowercase
+        }),
+      ).toBe(true);
+    });
+
+    it('should handle case-insensitive regex for URLs if specified', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://EXAMPLE.com/path', // Uppercase domain
+          supportedUrls: { 'text/plain': [/https:\/\/example\.com\/path/] },
+        }),
+      ).toBe(true);
+    });
+
+    it('should be case-insensitive for URL paths by default regex', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://example.com/PATH', // Uppercase path
+          supportedUrls: { 'text/plain': [/https:\/\/example\.com\/path/] }, // Lowercase path in regex
+        }),
+      ).toBe(true);
+    });
+  });
+
+  describe('wildcard subtypes in media types', () => {
+    it('should return true for wildcard subtype match', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'image/png',
+          url: 'https://example.com',
+          supportedUrls: { 'image/*': [/https:\/\/example\.com/] },
+        }),
+      ).toBe(true);
+    });
+
+    it('should use full wildcard "*" if subtype wildcard is not matched or supported', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'image/png',
+          url: 'https://any.com',
+          supportedUrls: {
+            'image/*': [/https:\/\/images\.com/], // Doesn't match URL
+            '*': [/https:\/\/any\.com/], // Matches URL
+          },
+        }),
+      ).toBe(true);
+    });
+  });
+
+  describe('empty URL arrays for a media type', () => {
+    it('should return false if the specific media type has an empty URL array', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://example.com',
+          supportedUrls: { 'text/plain': [] },
+        }),
+      ).toBe(false);
+    });
+
+    it('should fall back to wildcard "*" if specific media type has empty array but wildcard matches', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://any.com',
+          supportedUrls: {
+            'text/plain': [],
+            '*': [/https:\/\/any\.com/],
+          },
+        }),
+      ).toBe(true);
+    });
+
+    it('should return false if specific media type has empty array and wildcard does not match', async () => {
+      expect(
+        isUrlSupported({
+          mediaType: 'text/plain',
+          url: 'https://another.com',
+          supportedUrls: {
+            'text/plain': [],
+            '*': [/https:\/\/any\.com/],
+          },
+        }),
+      ).toBe(false);
+    });
+  });
+});

package/src/is-url-supported.ts

@@ -0,0 +1,40 @@
+/**
+ * Checks if the given URL is supported natively by the model.
+ *
+ * @param mediaType - The media type of the URL. Case-sensitive.
+ * @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.
+ *
+ * @returns `true` if the URL matches a pattern under the specific media type
+ *          or the wildcard '*', `false` otherwise.
+ */
+export function isUrlSupported({
+  mediaType,
+  url,
+  supportedUrls,
+}: {
+  mediaType: string;
+  url: string;
+  supportedUrls: Record<string, RegExp[]>;
+}): boolean {
+  // standardize media type and url to lower case
+  url = url.toLowerCase();
+  mediaType = mediaType.toLowerCase();
+
+  return (
+    Object.entries(supportedUrls)
+      // standardize supported url map into lowercase prefixes:
+      .map(([key, value]) => {
+        const mediaType = key.toLowerCase();
+        return mediaType === '*' || mediaType === '*/*'
+          ? { mediaTypePrefix: '', regexes: value }
+          : { mediaTypePrefix: mediaType.replace(/\*/, ''), regexes: value };
+      })
+      // gather all regexp pattern from matched media type prefixes:
+      .filter(({ mediaTypePrefix }) => mediaType.startsWith(mediaTypePrefix))
+      .flatMap(({ regexes }) => regexes)
+      // check if any pattern matches the url:
+      .some(pattern => pattern.test(url))
+  );
+}

package/src/load-api-key.ts

@@ -0,0 +1,45 @@
+import { LoadAPIKeyError } from '@ai-sdk/provider';
+
+export function loadApiKey({
+  apiKey,
+  environmentVariableName,
+  apiKeyParameterName = 'apiKey',
+  description,
+}: {
+  apiKey: string | undefined;
+  environmentVariableName: string;
+  apiKeyParameterName?: string;
+  description: string;
+}): string {
+  if (typeof apiKey === 'string') {
+    return apiKey;
+  }
+
+  if (apiKey != null) {
+    throw new LoadAPIKeyError({
+      message: `${description} API key must be a string.`,
+    });
+  }
+
+  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.`,
+    });
+  }
+
+  apiKey = process.env[environmentVariableName];
+
+  if (apiKey == null) {
+    throw new LoadAPIKeyError({
+      message: `${description} API key is missing. Pass it using the '${apiKeyParameterName}' parameter or the ${environmentVariableName} environment variable.`,
+    });
+  }
+
+  if (typeof apiKey !== 'string') {
+    throw new LoadAPIKeyError({
+      message: `${description} API key must be a string. The value of the ${environmentVariableName} environment variable is not a string.`,
+    });
+  }
+
+  return apiKey;
+}

package/src/load-optional-setting.ts

@@ -0,0 +1,30 @@
+/**
+ * Loads an optional `string` setting from the environment or a parameter.
+ *
+ * @param settingValue - The setting value.
+ * @param environmentVariableName - The environment variable name.
+ * @returns The setting value.
+ */
+export function loadOptionalSetting({
+  settingValue,
+  environmentVariableName,
+}: {
+  settingValue: string | undefined;
+  environmentVariableName: string;
+}): string | undefined {
+  if (typeof settingValue === 'string') {
+    return settingValue;
+  }
+
+  if (settingValue != null || typeof process === 'undefined') {
+    return undefined;
+  }
+
+  settingValue = process.env[environmentVariableName];
+
+  if (settingValue == null || typeof settingValue !== 'string') {
+    return undefined;
+  }
+
+  return settingValue;
+}

package/src/load-setting.ts

@@ -0,0 +1,62 @@
+import { LoadSettingError } from '@ai-sdk/provider';
+
+/**
+ * Loads a `string` setting from the environment or a parameter.
+ *
+ * @param settingValue - The setting value.
+ * @param environmentVariableName - The environment variable name.
+ * @param settingName - The setting name.
+ * @param description - The description of the setting.
+ * @returns The setting value.
+ */
+export function loadSetting({
+  settingValue,
+  environmentVariableName,
+  settingName,
+  description,
+}: {
+  settingValue: string | undefined;
+  environmentVariableName: string;
+  settingName: string;
+  description: string;
+}): string {
+  if (typeof settingValue === 'string') {
+    return settingValue;
+  }
+
+  if (settingValue != null) {
+    throw new LoadSettingError({
+      message: `${description} setting must be a string.`,
+    });
+  }
+
+  if (typeof process === 'undefined') {
+    throw new LoadSettingError({
+      message:
+        `${description} setting is missing. ` +
+        `Pass it using the '${settingName}' parameter. ` +
+        `Environment variables is not supported in this environment.`,
+    });
+  }
+
+  settingValue = process.env[environmentVariableName];
+
+  if (settingValue == null) {
+    throw new LoadSettingError({
+      message:
+        `${description} setting is missing. ` +
+        `Pass it using the '${settingName}' parameter ` +
+        `or the ${environmentVariableName} environment variable.`,
+    });
+  }
+
+  if (typeof settingValue !== 'string') {
+    throw new LoadSettingError({
+      message:
+        `${description} setting must be a string. ` +
+        `The value of the ${environmentVariableName} environment variable is not a string.`,
+    });
+  }
+
+  return settingValue;
+}

package/src/maybe-promise-like.ts

@@ -0,0 +1,3 @@
+export type MaybePromiseLike<T> =
+  | T // Raw value
+  | PromiseLike<T>; // Promise of value

package/src/media-type-to-extension.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { mediaTypeToExtension } from './media-type-to-extension';
+
+describe('mediaTypeToExtension()', () => {
+  it.each([
+    // most common
+    ['audio/mpeg', 'mp3'],
+    ['audio/mp3', 'mp3'],
+    ['audio/wav', 'wav'],
+    ['audio/x-wav', 'wav'],
+    ['audio/webm', 'webm'],
+    ['audio/ogg', 'ogg'],
+    ['audio/opus', 'ogg'],
+    ['audio/mp4', 'm4a'],
+    ['audio/x-m4a', 'm4a'],
+    ['audio/flac', 'flac'],
+    ['audio/aac', 'aac'],
+    // upper case
+    ['AUDIO/MPEG', 'mp3'],
+    ['AUDIO/MP3', 'mp3'],
+    // invalid
+    ['nope', ''],
+  ])('should map %s to %s', (mediaType, expectedExtension) => {
+    expect(mediaTypeToExtension(mediaType)).toBe(expectedExtension);
+  });
+});

package/src/media-type-to-extension.ts

@@ -0,0 +1,22 @@
+/**
+ * Maps a media type to its corresponding file extension.
+ * It was originally introduced to set a filename for audio file uploads
+ * in https://github.com/vercel/ai/pull/8159.
+ *
+ * @param mediaType The media type to map.
+ * @returns The corresponding file extension
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types
+ */
+export function mediaTypeToExtension(mediaType: string) {
+  const [_type, subtype = ''] = mediaType.toLowerCase().split('/');
+
+  return (
+    {
+      mpeg: 'mp3',
+      'x-wav': 'wav',
+      opus: 'ogg',
+      mp4: 'm4a',
+      'x-m4a': 'm4a',
+    }[subtype] ?? subtype
+  );
+}

package/src/normalize-headers.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeHeaders } from './normalize-headers';
+
+describe('normalizeHeaders', () => {
+  it('returns empty object for undefined', () => {
+    expect(normalizeHeaders(undefined)).toEqual({});
+  });
+
+  it('converts Headers instance to record', () => {
+    const headers = new Headers({
+      Authorization: 'Bearer token',
+      'X-Feature': 'beta',
+    });
+
+    expect(normalizeHeaders(headers)).toEqual({
+      authorization: 'Bearer token',
+      'x-feature': 'beta',
+    });
+  });
+
+  it('converts tuple array', () => {
+    const headers: HeadersInit = [
+      ['Authorization', 'Bearer token'],
+      ['X-Feature', 'beta'],
+      ['X-Ignore', undefined as unknown as string],
+    ];
+
+    expect(normalizeHeaders(headers)).toEqual({
+      authorization: 'Bearer token',
+      'x-feature': 'beta',
+    });
+  });
+
+  it('converts plain record and filters nullish values', () => {
+    expect(
+      normalizeHeaders({
+        Authorization: 'Bearer token',
+        'X-Feature': undefined,
+        'Content-Type': 'application/json',
+      }),
+    ).toEqual({
+      authorization: 'Bearer token',
+      'content-type': 'application/json',
+    });
+  });
+
+  it('handles empty Headers instance', () => {
+    const headers = new Headers();
+    expect(normalizeHeaders(headers)).toEqual({});
+  });
+
+  it('converts uppercase keys to lowercase', () => {
+    expect(
+      normalizeHeaders({
+        'CONTENT-TYPE': 'application/json',
+        'X-CUSTOM-HEADER': 'test-value',
+      }),
+    ).toEqual({
+      'content-type': 'application/json',
+      'x-custom-header': 'test-value',
+    });
+  });
+});

package/src/normalize-headers.ts

@@ -0,0 +1,38 @@
+/**
+ * Normalizes different header inputs into a plain record with lower-case keys.
+ * Entries with `undefined` or `null` values are removed.
+ *
+ * @param headers - Input headers (`Headers`, tuples array, plain record) to normalize.
+ * @returns A record containing the normalized header entries.
+ */
+export function normalizeHeaders(
+  headers:
+    | HeadersInit
+    | Record<string, string | undefined>
+    | Array<[string, string | undefined]>
+    | undefined,
+): Record<string, string> {
+  if (headers == null) {
+    return {};
+  }
+
+  const normalized: Record<string, string> = {};
+
+  if (headers instanceof Headers) {
+    headers.forEach((value, key) => {
+      normalized[key.toLowerCase()] = value;
+    });
+  } else {
+    if (!Array.isArray(headers)) {
+      headers = Object.entries(headers);
+    }
+
+    for (const [key, value] of headers) {
+      if (value != null) {
+        normalized[key.toLowerCase()] = value;
+      }
+    }
+  }
+
+  return normalized;
+}

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

@@ -0,0 +1,33 @@
+import {
+  EventSourceMessage,
+  EventSourceParserStream,
+} from 'eventsource-parser/stream';
+import { ParseResult, safeParseJSON } from './parse-json';
+import { FlexibleSchema } from './schema';
+
+/**
+ * Parses a JSON event stream into a stream of parsed JSON objects.
+ */
+export function parseJsonEventStream<T>({
+  stream,
+  schema,
+}: {
+  stream: ReadableStream<Uint8Array>;
+  schema: FlexibleSchema<T>;
+}): ReadableStream<ParseResult<T>> {
+  return stream
+    .pipeThrough(new TextDecoderStream())
+    .pipeThrough(new EventSourceParserStream())
+    .pipeThrough(
+      new TransformStream<EventSourceMessage, ParseResult<T>>({
+        async transform({ data }, controller) {
+          // ignore the 'DONE' event that e.g. OpenAI sends:
+          if (data === '[DONE]') {
+            return;
+          }
+
+          controller.enqueue(await safeParseJSON({ text: data, schema }));
+        },
+      }),
+    );
+}