@ai-sdk/provider-utils 4.0.4 → 4.0.6

package/src/parse-json.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect } from 'vitest';
+import { parseJSON, safeParseJSON, isParsableJson } from './parse-json';
+import { z } from 'zod/v4';
+import { JSONParseError, TypeValidationError } from '@ai-sdk/provider';
+
+describe('parseJSON', () => {
+  it('should parse basic JSON without schema', async () => {
+    const result = await parseJSON({ text: '{"foo": "bar"}' });
+    expect(result).toEqual({ foo: 'bar' });
+  });
+
+  it('should parse JSON with schema validation', async () => {
+    const schema = z.object({ foo: z.string() });
+    const result = await parseJSON({ text: '{"foo": "bar"}', schema });
+    expect(result).toEqual({ foo: 'bar' });
+  });
+
+  it('should throw JSONParseError for invalid JSON', async () => {
+    await expect(() => parseJSON({ text: 'invalid json' })).rejects.toThrow(
+      JSONParseError,
+    );
+  });
+
+  it('should throw TypeValidationError for schema validation failures', async () => {
+    const schema = z.object({ foo: z.number() });
+    await expect(() =>
+      parseJSON({ text: '{"foo": "bar"}', schema }),
+    ).rejects.toThrow(TypeValidationError);
+  });
+});
+
+describe('safeParseJSON', () => {
+  it('should safely parse basic JSON without schema and include rawValue', async () => {
+    const result = await safeParseJSON({ text: '{"foo": "bar"}' });
+    expect(result).toEqual({
+      success: true,
+      value: { foo: 'bar' },
+      rawValue: { foo: 'bar' },
+    });
+  });
+
+  it('should preserve rawValue even after schema transformation', async () => {
+    const schema = z.object({
+      count: z.coerce.number(),
+    });
+    const result = await safeParseJSON({
+      text: '{"count": "42"}',
+      schema,
+    });
+
+    expect(result).toEqual({
+      success: true,
+      value: { count: 42 },
+      rawValue: { count: '42' },
+    });
+  });
+
+  it('should handle failed parsing with error details', async () => {
+    const result = await safeParseJSON({ text: 'invalid json' });
+    expect(result).toEqual({
+      success: false,
+      error: expect.any(JSONParseError),
+    });
+  });
+
+  it('should handle schema validation failures', async () => {
+    const schema = z.object({ age: z.number() });
+    const result = await safeParseJSON({
+      text: '{"age": "twenty"}',
+      schema,
+    });
+
+    expect(result).toEqual({
+      success: false,
+      error: expect.any(TypeValidationError),
+      rawValue: { age: 'twenty' },
+    });
+  });
+
+  it('should handle nested objects and preserve raw values', async () => {
+    const schema = z.object({
+      user: z.object({
+        id: z.string().transform(val => parseInt(val, 10)),
+        name: z.string(),
+      }),
+    });
+
+    const result = await safeParseJSON({
+      text: '{"user": {"id": "123", "name": "John"}}',
+      schema: schema as any,
+    });
+
+    expect(result).toEqual({
+      success: true,
+      value: { user: { id: 123, name: 'John' } },
+      rawValue: { user: { id: '123', name: 'John' } },
+    });
+  });
+
+  it('should handle arrays and preserve raw values', async () => {
+    const schema = z.array(z.string().transform(val => val.toUpperCase()));
+    const result = await safeParseJSON({
+      text: '["hello", "world"]',
+      schema,
+    });
+
+    expect(result).toEqual({
+      success: true,
+      value: ['HELLO', 'WORLD'],
+      rawValue: ['hello', 'world'],
+    });
+  });
+
+  it('should handle discriminated unions in schema', async () => {
+    const schema = z.discriminatedUnion('type', [
+      z.object({ type: z.literal('text'), content: z.string() }),
+      z.object({ type: z.literal('number'), value: z.number() }),
+    ]);
+
+    const result = await safeParseJSON({
+      text: '{"type": "text", "content": "hello"}',
+      schema,
+    });
+
+    expect(result).toEqual({
+      success: true,
+      value: { type: 'text', content: 'hello' },
+      rawValue: { type: 'text', content: 'hello' },
+    });
+  });
+
+  it('should handle nullable fields in schema', async () => {
+    const schema = z.object({
+      id: z.string().nullish(),
+      data: z.string(),
+    });
+
+    const result = await safeParseJSON({
+      text: '{"id": null, "data": "test"}',
+      schema,
+    });
+
+    expect(result).toEqual({
+      success: true,
+      value: { id: null, data: 'test' },
+      rawValue: { id: null, data: 'test' },
+    });
+  });
+
+  it('should handle union types in schema', async () => {
+    const schema = z.object({
+      value: z.union([z.string(), z.number()]),
+    });
+
+    const result1 = await safeParseJSON({
+      text: '{"value": "test"}',
+      schema,
+    });
+
+    const result2 = await safeParseJSON({
+      text: '{"value": 123}',
+      schema,
+    });
+
+    expect(result1).toEqual({
+      success: true,
+      value: { value: 'test' },
+      rawValue: { value: 'test' },
+    });
+
+    expect(result2).toEqual({
+      success: true,
+      value: { value: 123 },
+      rawValue: { value: 123 },
+    });
+  });
+});
+
+describe('isParsableJson', () => {
+  it('should return true for valid JSON', () => {
+    expect(isParsableJson('{"foo": "bar"}')).toBe(true);
+    expect(isParsableJson('[1, 2, 3]')).toBe(true);
+    expect(isParsableJson('"hello"')).toBe(true);
+  });
+
+  it('should return false for invalid JSON', () => {
+    expect(isParsableJson('invalid')).toBe(false);
+    expect(isParsableJson('{foo: "bar"}')).toBe(false);
+    expect(isParsableJson('{"foo": }')).toBe(false);
+  });
+});

package/src/parse-json.ts

@@ -0,0 +1,122 @@
+import {
+  JSONParseError,
+  JSONValue,
+  TypeValidationError,
+} from '@ai-sdk/provider';
+import { secureJsonParse } from './secure-json-parse';
+import { safeValidateTypes, validateTypes } from './validate-types';
+import { FlexibleSchema } from './schema';
+
+/**
+ * Parses a JSON string into an unknown object.
+ *
+ * @param text - The JSON string to parse.
+ * @returns {JSONValue} - The parsed JSON object.
+ */
+export async function parseJSON(options: {
+  text: string;
+  schema?: undefined;
+}): Promise<JSONValue>;
+/**
+ * Parses a JSON string into a strongly-typed object using the provided schema.
+ *
+ * @template T - The type of the object to parse the JSON into.
+ * @param {string} text - The JSON string to parse.
+ * @param {Validator<T>} schema - The schema to use for parsing the JSON.
+ * @returns {Promise<T>} - The parsed object.
+ */
+export async function parseJSON<T>(options: {
+  text: string;
+  schema: FlexibleSchema<T>;
+}): Promise<T>;
+export async function parseJSON<T>({
+  text,
+  schema,
+}: {
+  text: string;
+  schema?: FlexibleSchema<T>;
+}): Promise<T> {
+  try {
+    const value = secureJsonParse(text);
+
+    if (schema == null) {
+      return value;
+    }
+
+    return validateTypes<T>({ value, schema });
+  } catch (error) {
+    if (
+      JSONParseError.isInstance(error) ||
+      TypeValidationError.isInstance(error)
+    ) {
+      throw error;
+    }
+
+    throw new JSONParseError({ text, cause: error });
+  }
+}
+
+export type ParseResult<T> =
+  | { success: true; value: T; rawValue: unknown }
+  | {
+      success: false;
+      error: JSONParseError | TypeValidationError;
+      rawValue: unknown;
+    };
+
+/**
+ * Safely parses a JSON string and returns the result as an object of type `unknown`.
+ *
+ * @param text - The JSON string to parse.
+ * @returns {Promise<object>} Either an object with `success: true` and the parsed data, or an object with `success: false` and the error that occurred.
+ */
+export async function safeParseJSON(options: {
+  text: string;
+  schema?: undefined;
+}): Promise<ParseResult<JSONValue>>;
+/**
+ * Safely parses a JSON string into a strongly-typed object, using a provided schema to validate the object.
+ *
+ * @template T - The type of the object to parse the JSON into.
+ * @param {string} text - The JSON string to parse.
+ * @param {Validator<T>} schema - The schema to use for parsing the JSON.
+ * @returns An object with either a `success` flag and the parsed and typed data, or a `success` flag and an error object.
+ */
+export async function safeParseJSON<T>(options: {
+  text: string;
+  schema: FlexibleSchema<T>;
+}): Promise<ParseResult<T>>;
+export async function safeParseJSON<T>({
+  text,
+  schema,
+}: {
+  text: string;
+  schema?: FlexibleSchema<T>;
+}): Promise<ParseResult<T>> {
+  try {
+    const value = secureJsonParse(text);
+
+    if (schema == null) {
+      return { success: true, value: value as T, rawValue: value };
+    }
+
+    return await safeValidateTypes<T>({ value, schema });
+  } catch (error) {
+    return {
+      success: false,
+      error: JSONParseError.isInstance(error)
+        ? error
+        : new JSONParseError({ text, cause: error }),
+      rawValue: undefined,
+    };
+  }
+}
+
+export function isParsableJson(input: string): boolean {
+  try {
+    secureJsonParse(input);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/parse-provider-options.ts

@@ -0,0 +1,32 @@
+import { InvalidArgumentError } from '@ai-sdk/provider';
+import { safeValidateTypes } from './validate-types';
+import { FlexibleSchema } from './schema';
+
+export async function parseProviderOptions<OPTIONS>({
+  provider,
+  providerOptions,
+  schema,
+}: {
+  provider: string;
+  providerOptions: Record<string, unknown> | undefined;
+  schema: FlexibleSchema<OPTIONS>;
+}): Promise<OPTIONS | undefined> {
+  if (providerOptions?.[provider] == null) {
+    return undefined;
+  }
+
+  const parsedProviderOptions = await safeValidateTypes<OPTIONS | undefined>({
+    value: providerOptions[provider],
+    schema,
+  });
+
+  if (!parsedProviderOptions.success) {
+    throw new InvalidArgumentError({
+      argument: 'providerOptions',
+      message: `invalid ${provider} provider options`,
+      cause: parsedProviderOptions.error,
+    });
+  }
+
+  return parsedProviderOptions.value;
+}

package/src/post-to-api.ts

@@ -0,0 +1,166 @@
+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 postJsonToApi = async <T>({
+  url,
+  headers,
+  body,
+  failedResponseHandler,
+  successfulResponseHandler,
+  abortSignal,
+  fetch,
+}: {
+  url: string;
+  headers?: Record<string, string | undefined>;
+  body: unknown;
+  failedResponseHandler: ResponseHandler<APICallError>;
+  successfulResponseHandler: ResponseHandler<T>;
+  abortSignal?: AbortSignal;
+  fetch?: FetchFunction;
+}) =>
+  postToApi({
+    url,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+    body: {
+      content: JSON.stringify(body),
+      values: body,
+    },
+    failedResponseHandler,
+    successfulResponseHandler,
+    abortSignal,
+    fetch,
+  });
+
+export const postFormDataToApi = async <T>({
+  url,
+  headers,
+  formData,
+  failedResponseHandler,
+  successfulResponseHandler,
+  abortSignal,
+  fetch,
+}: {
+  url: string;
+  headers?: Record<string, string | undefined>;
+  formData: FormData;
+  failedResponseHandler: ResponseHandler<APICallError>;
+  successfulResponseHandler: ResponseHandler<T>;
+  abortSignal?: AbortSignal;
+  fetch?: FetchFunction;
+}) =>
+  postToApi({
+    url,
+    headers,
+    body: {
+      content: formData,
+      values: Object.fromEntries((formData as any).entries()),
+    },
+    failedResponseHandler,
+    successfulResponseHandler,
+    abortSignal,
+    fetch,
+  });
+
+export const postToApi = async <T>({
+  url,
+  headers = {},
+  body,
+  successfulResponseHandler,
+  failedResponseHandler,
+  abortSignal,
+  fetch = getOriginalFetch(),
+}: {
+  url: string;
+  headers?: Record<string, string | undefined>;
+  body: {
+    content: string | FormData | Uint8Array;
+    values: unknown;
+  };
+  failedResponseHandler: ResponseHandler<Error>;
+  successfulResponseHandler: ResponseHandler<T>;
+  abortSignal?: AbortSignal;
+  fetch?: FetchFunction;
+}) => {
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: withUserAgentSuffix(
+        headers,
+        `ai-sdk/provider-utils/${VERSION}`,
+        getRuntimeEnvironmentUserAgent(),
+      ),
+      body: body.content,
+      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: body.values,
+        });
+      } 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: body.values,
+        });
+      }
+
+      throw errorInformation.value;
+    }
+
+    try {
+      return await successfulResponseHandler({
+        response,
+        url,
+        requestBodyValues: body.values,
+      });
+    } 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: body.values,
+      });
+    }
+  } catch (error) {
+    throw handleFetchError({ error, url, requestBodyValues: body.values });
+  }
+};

package/src/provider-tool-factory.ts

@@ -0,0 +1,125 @@
+import { tool, Tool, ToolExecuteFunction } from './types/tool';
+import { FlexibleSchema } from './schema';
+
+export type ProviderToolFactory<INPUT, ARGS extends object> = <OUTPUT>(
+  options: ARGS & {
+    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
+    needsApproval?: Tool<INPUT, OUTPUT>['needsApproval'];
+    toModelOutput?: Tool<INPUT, OUTPUT>['toModelOutput'];
+    onInputStart?: Tool<INPUT, OUTPUT>['onInputStart'];
+    onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
+    onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
+  },
+) => Tool<INPUT, OUTPUT>;
+
+export function createProviderToolFactory<INPUT, ARGS extends object>({
+  id,
+  inputSchema,
+}: {
+  id: `${string}.${string}`;
+  inputSchema: FlexibleSchema<INPUT>;
+}): ProviderToolFactory<INPUT, ARGS> {
+  return <OUTPUT>({
+    execute,
+    outputSchema,
+    needsApproval,
+    toModelOutput,
+    onInputStart,
+    onInputDelta,
+    onInputAvailable,
+    ...args
+  }: ARGS & {
+    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
+    outputSchema?: FlexibleSchema<OUTPUT>;
+    needsApproval?: Tool<INPUT, OUTPUT>['needsApproval'];
+    toModelOutput?: Tool<INPUT, OUTPUT>['toModelOutput'];
+    onInputStart?: Tool<INPUT, OUTPUT>['onInputStart'];
+    onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
+    onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
+  }): Tool<INPUT, OUTPUT> =>
+    tool({
+      type: 'provider',
+      id,
+      args,
+      inputSchema,
+      outputSchema,
+      execute,
+      needsApproval,
+      toModelOutput,
+      onInputStart,
+      onInputDelta,
+      onInputAvailable,
+    });
+}
+
+export type ProviderToolFactoryWithOutputSchema<
+  INPUT,
+  OUTPUT,
+  ARGS extends object,
+> = (
+  options: ARGS & {
+    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
+    needsApproval?: Tool<INPUT, OUTPUT>['needsApproval'];
+    toModelOutput?: Tool<INPUT, OUTPUT>['toModelOutput'];
+    onInputStart?: Tool<INPUT, OUTPUT>['onInputStart'];
+    onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
+    onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
+  },
+) => Tool<INPUT, OUTPUT>;
+
+export function createProviderToolFactoryWithOutputSchema<
+  INPUT,
+  OUTPUT,
+  ARGS extends object,
+>({
+  id,
+  inputSchema,
+  outputSchema,
+  supportsDeferredResults,
+}: {
+  id: `${string}.${string}`;
+  inputSchema: FlexibleSchema<INPUT>;
+  outputSchema: FlexibleSchema<OUTPUT>;
+  /**
+   * Whether this provider-executed tool supports deferred results.
+   *
+   * When true, the tool result may not be returned in the same turn as the
+   * tool call (e.g., when using programmatic tool calling where a server tool
+   * triggers a client-executed tool, and the server tool's result is deferred
+   * until the client tool is resolved).
+   *
+   * @default false
+   */
+  supportsDeferredResults?: boolean;
+}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS> {
+  return ({
+    execute,
+    needsApproval,
+    toModelOutput,
+    onInputStart,
+    onInputDelta,
+    onInputAvailable,
+    ...args
+  }: ARGS & {
+    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
+    needsApproval?: Tool<INPUT, OUTPUT>['needsApproval'];
+    toModelOutput?: Tool<INPUT, OUTPUT>['toModelOutput'];
+    onInputStart?: Tool<INPUT, OUTPUT>['onInputStart'];
+    onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
+    onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
+  }): Tool<INPUT, OUTPUT> =>
+    tool({
+      type: 'provider',
+      id,
+      args,
+      inputSchema,
+      outputSchema,
+      execute,
+      needsApproval,
+      toModelOutput,
+      onInputStart,
+      onInputDelta,
+      onInputAvailable,
+      supportsDeferredResults,
+    });
+}

package/src/remove-undefined-entries.test.ts

@@ -0,0 +1,57 @@
+import { expect, it } from 'vitest';
+import { removeUndefinedEntries } from './remove-undefined-entries';
+
+it('should remove undefined entries from record', () => {
+  const input = {
+    a: 1,
+    b: undefined,
+    c: 'test',
+    d: undefined,
+  };
+
+  expect(removeUndefinedEntries(input)).toEqual({
+    a: 1,
+    c: 'test',
+  });
+});
+
+it('should handle empty object', () => {
+  const input = {};
+  expect(removeUndefinedEntries(input)).toEqual({});
+});
+
+it('should handle object with all undefined values', () => {
+  const input = {
+    a: undefined,
+    b: undefined,
+  };
+  expect(removeUndefinedEntries(input)).toEqual({});
+});
+
+it('should remove null values', () => {
+  // Both null and undefined will be removed.
+  const input = {
+    a: null,
+    b: undefined,
+    c: 'test',
+  };
+  expect(removeUndefinedEntries(input)).toEqual({
+    c: 'test',
+  });
+});
+
+it('should preserve falsy values except null and undefined', () => {
+  // Only false, 0, and '' are preserved.
+  const input = {
+    a: false,
+    b: 0,
+    c: '',
+    d: undefined,
+    e: null,
+  };
+  expect(removeUndefinedEntries(input)).toEqual({
+    a: false,
+    b: 0,
+    c: '',
+  });
+});

package/src/remove-undefined-entries.ts

@@ -0,0 +1,12 @@
+/**
+ * Removes entries from a record where the value is null or undefined.
+ * @param record - The input object whose entries may be null or undefined.
+ * @returns A new object containing only entries with non-null and non-undefined values.
+ */
+export function removeUndefinedEntries<T>(
+  record: Record<string, T | undefined>,
+): Record<string, T> {
+  return Object.fromEntries(
+    Object.entries(record).filter(([_key, value]) => value != null),
+  ) as Record<string, T>;
+}