@fondation-io/ai 7.0.0-beta.45

package/src/ui/use-completion.ts

@@ -0,0 +1,84 @@
+import { FetchFunction } from '@ai-sdk/provider-utils';
+
+export type CompletionRequestOptions = {
+  /**
+   * An optional object of headers to be passed to the API endpoint.
+   */
+  headers?: Record<string, string> | Headers;
+
+  /**
+   * An optional object to be passed to the API endpoint.
+   */
+  body?: object;
+};
+
+export type UseCompletionOptions = {
+  /**
+   * The API endpoint that accepts a `{ prompt: string }` object and returns
+   * a stream of tokens of the AI completion response. Defaults to `/api/completion`.
+   */
+  api?: string;
+  /**
+   * A unique identifier for the completion. If not provided, a random one will be
+   * generated. When provided, the `useCompletion` hook with the same `id` will
+   * have shared states across components.
+   */
+  id?: string;
+
+  /**
+   * Initial prompt input of the completion.
+   */
+  initialInput?: string;
+
+  /**
+   * Initial completion result. Useful to load an existing history.
+   */
+  initialCompletion?: string;
+
+  /**
+   * Callback function to be called when the completion is finished streaming.
+   */
+  onFinish?: (prompt: string, completion: string) => void;
+
+  /**
+   * Callback function to be called when an error is encountered.
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * The credentials mode to be used for the fetch request.
+   * Possible values are: 'omit', 'same-origin', 'include'.
+   * Defaults to 'same-origin'.
+   */
+  credentials?: RequestCredentials;
+
+  /**
+   * HTTP headers to be sent with the API request.
+   */
+  headers?: Record<string, string> | Headers;
+
+  /**
+   * Extra body object to be sent with the API request.
+   * @example
+   * Send a `sessionId` to the API along with the prompt.
+   * ```js
+   * useCompletion({
+   *   body: {
+   *     sessionId: '123',
+   *   }
+   * })
+   * ```
+   */
+  body?: object;
+
+  /**
+   * Streaming protocol that is used. Defaults to `data`.
+   */
+  streamProtocol?: 'data' | 'text';
+
+  /**
+   * Custom fetch implementation. You can use it as a middleware to intercept requests,
+   * or to provide a custom fetch implementation for e.g. testing.
+   */
+  fetch?: FetchFunction;
+};

package/src/ui/validate-ui-messages.ts

@@ -0,0 +1,521 @@
+import { TypeValidationContext, TypeValidationError } from '@ai-sdk/provider';
+import {
+  FlexibleSchema,
+  lazySchema,
+  StandardSchemaV1,
+  Tool,
+  validateTypes,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { InvalidArgumentError } from '../error';
+import { providerMetadataSchema } from '../types/provider-metadata';
+import {
+  DataUIPart,
+  InferUIMessageData,
+  InferUIMessageTools,
+  ToolUIPart,
+  UIMessage,
+} from './ui-messages';
+
+const uiMessagesSchema = lazySchema(() =>
+  zodSchema(
+    z
+      .array(
+        z.object({
+          id: z.string(),
+          role: z.enum(['system', 'user', 'assistant']),
+          metadata: z.unknown().optional(),
+          parts: z
+            .array(
+              z.union([
+                z.object({
+                  type: z.literal('text'),
+                  text: z.string(),
+                  state: z.enum(['streaming', 'done']).optional(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('reasoning'),
+                  text: z.string(),
+                  state: z.enum(['streaming', 'done']).optional(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('custom'),
+                  kind: z.string(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('source-url'),
+                  sourceId: z.string(),
+                  url: z.string(),
+                  title: z.string().optional(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('source-document'),
+                  sourceId: z.string(),
+                  mediaType: z.string(),
+                  title: z.string(),
+                  filename: z.string().optional(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('file'),
+                  mediaType: z.string(),
+                  filename: z.string().optional(),
+                  url: z.string(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('reasoning-file'),
+                  mediaType: z.string(),
+                  url: z.string(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('step-start'),
+                }),
+                z.object({
+                  type: z.string().startsWith('data-'),
+                  id: z.string().optional(),
+                  data: z.unknown(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('input-streaming'),
+                  input: z.unknown().optional(),
+                  providerExecuted: z.boolean().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  approval: z.never().optional(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('input-available'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.never().optional(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('approval-requested'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.never().optional(),
+                    reason: z.never().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('approval-responded'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.boolean(),
+                    reason: z.string().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('output-available'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.unknown(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  resultProviderMetadata: providerMetadataSchema.optional(),
+                  preliminary: z.boolean().optional(),
+                  approval: z
+                    .object({
+                      id: z.string(),
+                      approved: z.literal(true),
+                      reason: z.string().optional(),
+                    })
+                    .optional(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('output-error'),
+                  input: z.unknown(),
+                  rawInput: z.unknown().optional(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.string(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  resultProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z
+                    .object({
+                      id: z.string(),
+                      approved: z.literal(true),
+                      reason: z.string().optional(),
+                    })
+                    .optional(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('output-denied'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.literal(false),
+                    reason: z.string().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('input-streaming'),
+                  providerExecuted: z.boolean().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  input: z.unknown().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  approval: z.never().optional(),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('input-available'),
+                  providerExecuted: z.boolean().optional(),
+                  input: z.unknown(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.never().optional(),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('approval-requested'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.never().optional(),
+                    reason: z.never().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('approval-responded'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.boolean(),
+                    reason: z.string().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('output-available'),
+                  providerExecuted: z.boolean().optional(),
+                  input: z.unknown(),
+                  output: z.unknown(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  resultProviderMetadata: providerMetadataSchema.optional(),
+                  preliminary: z.boolean().optional(),
+                  approval: z
+                    .object({
+                      id: z.string(),
+                      approved: z.literal(true),
+                      reason: z.string().optional(),
+                    })
+                    .optional(),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('output-error'),
+                  providerExecuted: z.boolean().optional(),
+                  input: z.unknown(),
+                  rawInput: z.unknown().optional(),
+                  output: z.never().optional(),
+                  errorText: z.string(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  resultProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z
+                    .object({
+                      id: z.string(),
+                      approved: z.literal(true),
+                      reason: z.string().optional(),
+                    })
+                    .optional(),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('output-denied'),
+                  providerExecuted: z.boolean().optional(),
+                  input: z.unknown(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.literal(false),
+                    reason: z.string().optional(),
+                  }),
+                }),
+              ]),
+            )
+            .nonempty('Message must contain at least one part'),
+        }),
+      )
+      .nonempty('Messages array must not be empty'),
+  ),
+);
+
+export type SafeValidateUIMessagesResult<UI_MESSAGE extends UIMessage> =
+  | {
+      success: true;
+      data: Array<UI_MESSAGE>;
+    }
+  | {
+      success: false;
+      error: Error;
+    };
+
+/**
+ * Validates a list of UI messages like `validateUIMessages`,
+ * but instead of throwing it returns `{ success: true, data }`
+ * or `{ success: false, error }`.
+ */
+export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
+  messages,
+  metadataSchema,
+  dataSchemas,
+  tools,
+}: {
+  messages: unknown;
+  metadataSchema?: FlexibleSchema<UIMessage['metadata']>;
+  dataSchemas?: {
+    [NAME in keyof InferUIMessageData<UI_MESSAGE> & string]?: FlexibleSchema<
+      InferUIMessageData<UI_MESSAGE>[NAME]
+    >;
+  };
+  tools?: {
+    [NAME in keyof InferUIMessageTools<UI_MESSAGE> & string]?: Tool<
+      InferUIMessageTools<UI_MESSAGE>[NAME]['input'],
+      InferUIMessageTools<UI_MESSAGE>[NAME]['output']
+    >;
+  };
+}): Promise<SafeValidateUIMessagesResult<UI_MESSAGE>> {
+  try {
+    if (messages == null) {
+      return {
+        success: false,
+        error: new InvalidArgumentError({
+          parameter: 'messages',
+          value: messages,
+          message: 'messages parameter must be provided',
+        }),
+      };
+    }
+
+    const validatedMessages = await validateTypes({
+      value: messages,
+      schema: uiMessagesSchema,
+    });
+
+    if (metadataSchema) {
+      for (const [msgIdx, message] of validatedMessages.entries()) {
+        await validateTypes({
+          value: message.metadata,
+          schema: metadataSchema,
+          context: {
+            field: `messages[${msgIdx}].metadata`,
+            entityId: message.id,
+          },
+        });
+      }
+    }
+
+    if (dataSchemas || tools) {
+      for (const [msgIdx, message] of validatedMessages.entries()) {
+        for (const [partIdx, part] of message.parts.entries()) {
+          // Data part validation
+          if (dataSchemas && part.type.startsWith('data-')) {
+            const dataPart = part as DataUIPart<InferUIMessageData<UI_MESSAGE>>;
+            const dataName = dataPart.type.slice(5);
+            const dataSchema = dataSchemas[dataName];
+
+            if (!dataSchema) {
+              return {
+                success: false,
+                error: new TypeValidationError({
+                  value: dataPart.data,
+                  cause: `No data schema found for data part ${dataName}`,
+                  context: {
+                    field: `messages[${msgIdx}].parts[${partIdx}].data`,
+                    entityName: dataName,
+                    entityId: dataPart.id,
+                  },
+                }),
+              };
+            }
+
+            await validateTypes({
+              value: dataPart.data,
+              schema: dataSchema,
+              context: {
+                field: `messages[${msgIdx}].parts[${partIdx}].data`,
+                entityName: dataName,
+                entityId: dataPart.id,
+              },
+            });
+          }
+
+          // Tool part validation
+          if (tools && part.type.startsWith('tool-')) {
+            const toolPart = part as ToolUIPart<
+              InferUIMessageTools<UI_MESSAGE>
+            >;
+            const toolName = toolPart.type.slice(5);
+            const tool = tools[toolName];
+
+            // TODO support dynamic tools
+            if (!tool) {
+              return {
+                success: false,
+                error: new TypeValidationError({
+                  value: toolPart.input,
+                  cause: `No tool schema found for tool part ${toolName}`,
+                  context: {
+                    field: `messages[${msgIdx}].parts[${partIdx}].input`,
+                    entityName: toolName,
+                    entityId: toolPart.toolCallId,
+                  },
+                }),
+              };
+            }
+
+            // Tool input validation
+            if (
+              toolPart.state === 'input-available' ||
+              toolPart.state === 'output-available' ||
+              (toolPart.state === 'output-error' &&
+                toolPart.input !== undefined)
+            ) {
+              await validateTypes({
+                value: toolPart.input,
+                schema: tool.inputSchema,
+                context: {
+                  field: `messages[${msgIdx}].parts[${partIdx}].input`,
+                  entityName: toolName,
+                  entityId: toolPart.toolCallId,
+                },
+              });
+            }
+
+            // Tool output validation
+            if (toolPart.state === 'output-available' && tool.outputSchema) {
+              await validateTypes({
+                value: toolPart.output,
+                schema: tool.outputSchema,
+                context: {
+                  field: `messages[${msgIdx}].parts[${partIdx}].output`,
+                  entityName: toolName,
+                  entityId: toolPart.toolCallId,
+                },
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      success: true,
+      data: validatedMessages as Array<UI_MESSAGE>,
+    };
+  } catch (error) {
+    const err = error as Error;
+
+    return {
+      success: false,
+      error: err,
+    };
+  }
+}
+
+/**
+ * Validates a list of UI messages.
+ *
+ * Metadata, data parts, and generic tool call structures are only validated if
+ * the corresponding schemas are provided. Otherwise, they are assumed to be
+ * valid.
+ */
+export async function validateUIMessages<UI_MESSAGE extends UIMessage>({
+  messages,
+  metadataSchema,
+  dataSchemas,
+  tools,
+}: {
+  messages: unknown;
+  metadataSchema?: FlexibleSchema<UIMessage['metadata']>;
+  dataSchemas?: {
+    [NAME in keyof InferUIMessageData<UI_MESSAGE> & string]?: FlexibleSchema<
+      InferUIMessageData<UI_MESSAGE>[NAME]
+    >;
+  };
+  tools?: {
+    [NAME in keyof InferUIMessageTools<UI_MESSAGE> & string]?: Tool<
+      InferUIMessageTools<UI_MESSAGE>[NAME]['input'],
+      InferUIMessageTools<UI_MESSAGE>[NAME]['output']
+    >;
+  };
+}): Promise<Array<UI_MESSAGE>> {
+  const response = await safeValidateUIMessages({
+    messages,
+    metadataSchema,
+    dataSchemas,
+    tools,
+  });
+
+  if (!response.success) throw response.error;
+
+  return response.data;
+}

package/src/ui-message-stream/create-ui-message-stream-response.ts

@@ -0,0 +1,44 @@
+import { prepareHeaders } from '../util/prepare-headers';
+import { JsonToSseTransformStream } from './json-to-sse-transform-stream';
+import { UI_MESSAGE_STREAM_HEADERS } from './ui-message-stream-headers';
+import { UIMessageChunk } from './ui-message-chunks';
+import { UIMessageStreamResponseInit } from './ui-message-stream-response-init';
+
+/**
+ * Creates a Response object from a UI message stream.
+ * The stream is transformed to Server-Sent Events (SSE) format.
+ *
+ * @param options.status - The HTTP status code for the response.
+ * @param options.statusText - The HTTP status text for the response.
+ * @param options.headers - Additional HTTP headers to include in the response.
+ * @param options.stream - The UI message chunk stream to send.
+ * @param options.consumeSseStream - Optional callback to consume a copy of the SSE stream independently.
+ *
+ * @returns A `Response` object with the UI message stream as the body.
+ */
+export function createUIMessageStreamResponse({
+  status,
+  statusText,
+  headers,
+  stream,
+  consumeSseStream,
+}: UIMessageStreamResponseInit & {
+  stream: ReadableStream<UIMessageChunk>;
+}): Response {
+  let sseStream = stream.pipeThrough(new JsonToSseTransformStream());
+
+  // when the consumeSseStream is provided, we need to tee the stream
+  // and send the second part to the consumeSseStream function
+  // so that it can be consumed by the client independently
+  if (consumeSseStream) {
+    const [stream1, stream2] = sseStream.tee();
+    sseStream = stream1;
+    consumeSseStream({ stream: stream2 }); // no await (do not block the response)
+  }
+
+  return new Response(sseStream.pipeThrough(new TextEncoderStream()), {
+    status,
+    statusText,
+    headers: prepareHeaders(headers, UI_MESSAGE_STREAM_HEADERS),
+  });
+}