@od-oneapp/ai-platform 0.1.0

package/src/server/messages/types.ts

@@ -0,0 +1,355 @@
+/**
+ * @fileoverview Message types for AI SDK v6 message handling.
+ * @module @od-oneapp/ai-platform/messages
+ *
+ * Provides type definitions for message conversion, data part extraction,
+ * and message window management. Types are aligned with AI SDK v6 where possible.
+ *
+ * @example
+ * ```ts
+ * import type {
+ *   UIMessage,
+ *   ModelMessage,
+ *   MessageConverterConfig,
+ *   DataPartExtractorConfig,
+ *   MessageWindowConfig,
+ * } from '@od-oneapp/ai-platform/messages';
+ *
+ * const config: MessageConverterConfig = {
+ *   maxMessages: 50,
+ *   stripSystemMessages: false,
+ * };
+ * ```
+ */
+
+import { type z } from 'zod';
+
+import type {
+  SDKTextPart,
+  SDKToolCallPart,
+  SDKToolResultPart,
+  SDKUIMessage,
+  SDKModelMessage,
+  MessageRole,
+} from '../../shared';
+
+// =============================================================================
+// Message Types (SDK-Aligned)
+// =============================================================================
+
+/**
+ * Role for messages in a conversation.
+ * Re-exported from ai-types.ts for convenience.
+ */
+export type { MessageRole };
+
+type UIMessageRole = Exclude<MessageRole, 'tool'>;
+
+/**
+ * Data part attached to a message.
+ * Generic structure for custom streaming data.
+ * This is a OneApp-specific extension for custom data streaming.
+ */
+export interface DataPart<TType extends string = string, TData = unknown> {
+  /** Type identifier for the data part. */
+  readonly type: TType;
+  /** Data payload for the data part. */
+  readonly data: TData;
+}
+
+/**
+ * Tool call part in a message.
+ * Represents an AI tool invocation.
+ *
+ * @remarks
+ * This type is compatible with AI SDK v6's ToolCallPart.
+ * @see SDKToolCallPart for the SDK's native type
+ */
+export type ToolCallPart = SDKToolCallPart;
+
+/**
+ * Tool result part in a message.
+ * Represents the result of a tool execution.
+ *
+ * @remarks
+ * This type is compatible with AI SDK v6's ToolResultPart.
+ * @see SDKToolResultPart for the SDK's native type
+ */
+export type ToolResultPart = SDKToolResultPart;
+
+/**
+ * Text content part in a message.
+ *
+ * @remarks
+ * This type is compatible with AI SDK v6's TextPart.
+ * @see SDKTextPart for the SDK's native type
+ */
+export type TextPart = SDKTextPart;
+
+/**
+ * Message part types union.
+ * Combines SDK-compatible parts with OneApp's custom DataPart.
+ */
+export type MessagePart = TextPart | ToolCallPart | ToolResultPart | DataPart;
+
+/**
+ * UI Message format used in chat interfaces.
+ * Extended format with metadata and parts for rich rendering.
+ *
+ * @remarks
+ * This extends AI SDK v6's UIMessage with additional OneApp-specific fields.
+ * The base structure is compatible with SDKUIMessage.
+ *
+ * @example
+ * ```ts
+ * const message: UIMessage = {
+ *   id: 'msg_123',
+ *   role: 'assistant',
+ *   content: 'Hello!',
+ *   createdAt: new Date(),
+ *   parts: [{ type: 'text', text: 'Hello!' }],
+ * };
+ * ```
+ */
+export interface UIMessage {
+  /** Unique message identifier. */
+  readonly id?: string;
+  /** Role of the message sender. */
+  readonly role: UIMessageRole;
+  /** Text content of the message. */
+  readonly content: string;
+  /** Message creation timestamp. */
+  readonly createdAt?: Date;
+  /** Structured parts of the message (for rich content). */
+  readonly parts?: MessagePart[];
+  /** Custom data attached to the message (OneApp extension). */
+  readonly data?: DataPart[];
+  /** Additional metadata (OneApp extension). */
+  readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Model Message format used for AI model API calls.
+ * Simplified format for model consumption.
+ *
+ * @remarks
+ * This type is compatible with AI SDK v6's ModelMessage.
+ * @see SDKModelMessage for the SDK's native type
+ *
+ * @example
+ * ```ts
+ * const message: ModelMessage = {
+ *   role: 'user',
+ *   content: 'What is the weather?',
+ * };
+ * ```
+ */
+export interface ModelMessage {
+  /** Role of the message sender. */
+  readonly role: MessageRole;
+  /** Text content of the message. */
+  readonly content: string;
+}
+
+// Re-export SDK types for convenience
+export type { SDKTextPart, SDKToolCallPart, SDKToolResultPart, SDKUIMessage, SDKModelMessage };
+
+// =============================================================================
+// Converter Configuration
+// =============================================================================
+
+/**
+ * Configuration for message converter factory.
+ *
+ * @example
+ * ```ts
+ * const config: MessageConverterConfig = {
+ *   maxMessages: 50,
+ *   stripSystemMessages: false,
+ *   transform: (msg) => ({
+ *     ...msg,
+ *     content: msg.content.trim(),
+ *   }),
+ * };
+ * ```
+ */
+export interface MessageConverterConfig {
+  /** Strip system messages before conversion. */
+  readonly stripSystemMessages?: boolean;
+  /** Maximum number of messages to include (sliding window from end). */
+  readonly maxMessages?: number;
+  /**
+   * Custom message transformer.
+   * Return null to filter out a message.
+   */
+  readonly transform?: (msg: UIMessage) => UIMessage | null;
+}
+
+/**
+ * Message converter instance returned by factory.
+ */
+export interface MessageConverter {
+  /**
+   * Converts UI messages to model messages.
+   * @param messages - Array of UI messages to convert.
+   * @returns Promise resolving to array of model messages.
+   */
+  toModelMessages(messages: readonly UIMessage[]): Promise<readonly ModelMessage[]>;
+
+  /**
+   * Converts UI messages to model messages synchronously.
+   * @param messages - Array of UI messages to convert.
+   * @returns Array of model messages.
+   */
+  toModelMessagesSync(messages: readonly UIMessage[]): readonly ModelMessage[];
+}
+
+// =============================================================================
+// Data Part Extractor Configuration
+// =============================================================================
+
+/**
+ * Schema map for typed data part extraction.
+ * Maps type strings to Zod schemas.
+ */
+export type DataPartSchemaMap = Record<string, z.ZodType>;
+
+/**
+ * Configuration for data part extractor factory.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ *
+ * const ProgressSchema = z.object({
+ *   current: z.number(),
+ *   total: z.number(),
+ * });
+ *
+ * const config: DataPartExtractorConfig<{ progress: typeof ProgressSchema }> = {
+ *   schemas: { progress: ProgressSchema },
+ *   onUnknownType: (type, data) => console.warn(`Unknown type: ${type}`),
+ * };
+ * ```
+ */
+export interface DataPartExtractorConfig<T extends DataPartSchemaMap = DataPartSchemaMap> {
+  /** Schema map for typed extraction. */
+  readonly schemas: T;
+  /** Callback for unknown data part types. */
+  readonly onUnknownType?: (type: string, data: unknown) => void;
+}
+
+/**
+ * Result of data part extraction.
+ * Contains validated data parts with proper typing.
+ */
+export type ExtractedDataParts<T extends DataPartSchemaMap> = {
+  [K in keyof T]: z.infer<T[K]>[];
+};
+
+/**
+ * Data part extractor instance returned by factory.
+ */
+export interface DataPartExtractor<T extends DataPartSchemaMap> {
+  /**
+   * Extracts data parts of a specific type from messages.
+   * @param messages - Array of messages to extract from.
+   * @param type - Type of data parts to extract.
+   * @returns Array of extracted and validated data.
+   */
+  extract<K extends keyof T & string>(messages: readonly UIMessage[], type: K): z.infer<T[K]>[];
+
+  /**
+   * Extracts all data parts grouped by type.
+   * @param messages - Array of messages to extract from.
+   * @returns Object with arrays of data parts grouped by type.
+   */
+  extractAll(messages: readonly UIMessage[]): Partial<ExtractedDataParts<T>>;
+
+  /**
+   * Checks if a data part type is known to this extractor.
+   * @param type - Type to check.
+   * @returns True if the type has a schema.
+   */
+  hasSchema(type: string): type is keyof T & string;
+}
+
+// =============================================================================
+// Message Window Configuration
+// =============================================================================
+
+/**
+ * Tokenizer type for message window.
+ * Can be a preset name or a custom function.
+ */
+export type TokenizerType = 'cl100k_base' | 'p50k_base' | ((text: string) => number);
+
+/**
+ * Truncation strategy for message window.
+ * - 'fifo': Remove oldest messages first (default)
+ * - 'summarize': Summarize older messages (requires summarizer)
+ */
+export type TruncationStrategy = 'fifo' | 'summarize';
+
+/**
+ * Configuration for message window factory.
+ *
+ * @example
+ * ```ts
+ * const config: MessageWindowConfig = {
+ *   maxTokens: 8000,
+ *   tokenizer: 'cl100k_base',
+ *   preserveSystemMessage: true,
+ *   strategy: 'fifo',
+ * };
+ * ```
+ */
+export interface MessageWindowConfig {
+  /** Maximum tokens allowed in the window. */
+  readonly maxTokens: number;
+  /** Tokenizer to use for counting. Defaults to simple word-based estimate. */
+  readonly tokenizer?: TokenizerType;
+  /** Preserve system message regardless of window constraints. */
+  readonly preserveSystemMessage?: boolean;
+  /** Truncation strategy when window is exceeded. */
+  readonly strategy?: TruncationStrategy;
+  /**
+   * Summarizer function for 'summarize' strategy.
+   * @param messages - Messages to summarize.
+   * @returns Promise resolving to summary message.
+   */
+  readonly summarizer?: (messages: readonly UIMessage[]) => Promise<UIMessage>;
+}
+
+/**
+ * Message window instance returned by factory.
+ */
+export interface MessageWindow {
+  /**
+   * Applies the window to a message array, truncating if needed.
+   * @param messages - Array of messages to process.
+   * @returns Array of messages within the token window.
+   */
+  apply(messages: readonly UIMessage[]): Promise<readonly UIMessage[]>;
+
+  /**
+   * Applies the window synchronously (only for FIFO strategy).
+   * @param messages - Array of messages to process.
+   * @returns Array of messages within the token window.
+   */
+  applySync(messages: readonly UIMessage[]): readonly UIMessage[];
+
+  /**
+   * Estimates the token count for an array of messages.
+   * @param messages - Array of messages to estimate.
+   * @returns Estimated token count.
+   */
+  estimateTokens(messages: readonly UIMessage[]): number;
+
+  /**
+   * Estimates the token count for a single message.
+   * @param message - Message to estimate.
+   * @returns Estimated token count.
+   */
+  estimateMessageTokens(message: UIMessage): number;
+}