@umituz/web-ai-groq-provider 1.1.13 → 2.0.0

package/dist/domains/chat/index.d.cts

@@ -0,0 +1,322 @@
+import { k as GroqMessage, T as TextGenerationService } from '../../text-generation.service-BP4Q_SH0.cjs';
+
+/**
+ * Chat Domain Entities
+ * @description Core chat message and conversation types.
+ *              All fields are readonly: consumers must not mutate
+ *              messages that are in-flight or persisted.
+ */
+type ChatMessageSender = "user" | "assistant" | "system";
+type ChatMessageType = "text" | "image" | "audio" | "sticker";
+/**
+ * Chat message structure.
+ * Use the `metadata` field for provider-specific or app-specific data
+ * (e.g., model name, token usage, reactions, or any other extension).
+ */
+interface ChatMessage {
+    readonly id: string;
+    readonly sender: ChatMessageSender;
+    readonly content: string;
+    readonly timestamp: string;
+    readonly type?: ChatMessageType;
+    readonly imageUrl?: string;
+    readonly reaction?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Conversation metadata, derived from the message history of a conversation.
+ */
+interface ChatConversation {
+    readonly id: string;
+    readonly companionId: string;
+    readonly companionName: string;
+    readonly lastMessage?: ChatMessage;
+    readonly messageCount: number;
+    readonly updatedAt: string;
+}
+/**
+ * Input for a single chat turn.
+ * The companionId is the addressable identifier for the chat partner
+ * (e.g., a character, agent, or session).
+ */
+interface SendMessageInput {
+    readonly companionId: string;
+    readonly text: string;
+    readonly type?: ChatMessageType;
+    readonly imageUrl?: string;
+}
+/**
+ * Result of a single chat turn: the user message that was sent
+ * and the assistant's reply (if generation succeeded).
+ */
+interface SendMessageResult {
+    readonly userMessage: ChatMessage;
+    readonly aiResponse?: ChatMessage;
+}
+/**
+ * Chat configuration.
+ *
+ * @example
+ * ```typescript
+ * const config: ChatConfig = {
+ *   systemPrompt: "You are a helpful assistant.",
+ *   temperature: 0.7,
+ *   maxTokens: 800,
+ * };
+ * ```
+ */
+interface ChatConfig {
+    /** System prompt prepended to the conversation. */
+    readonly systemPrompt?: string;
+    /** Sampling temperature (0.0 - 2.0). */
+    readonly temperature?: number;
+    /** Maximum number of tokens to generate per response. */
+    readonly maxTokens?: number;
+}
+/**
+ * Storage contract for persisting chat messages.
+ * The host application provides an implementation; the library never
+ * persists on its own.
+ */
+interface IChatStorage {
+    saveMessage(conversationId: string, message: ChatMessage): Promise<void>;
+    getMessages(conversationId: string): Promise<ChatMessage[]>;
+    updateMessage(messageId: string, updates: Partial<ChatMessage>): Promise<void>;
+    deleteMessage(messageId: string): Promise<void>;
+}
+/**
+ * Token usage information returned by the model, normalized to the chat layer.
+ */
+interface ChatTokenUsage {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+}
+
+/**
+ * System Prompt Strategy
+ * @description Resolves the system prompt to use for a chat session.
+ *              Allows library consumers to plug in their own prompts
+ *              without hardcoded language defaults.
+ *
+ * @example
+ * ```typescript
+ * const customStrategy: SystemPromptStrategy = {
+ *   resolve: (config) =>
+ *     config.language === "tr"
+ *       ? "Sen yardimsever bir asistansin."
+ *       : "You are a helpful assistant.",
+ * };
+ * chatService.setPromptStrategy(customStrategy);
+ * ```
+ */
+
+interface SystemPromptStrategy {
+    /**
+     * Resolve the system prompt for the given config.
+     * Returning `undefined` omits the system message entirely.
+     */
+    resolve(config: ChatConfig): string | undefined;
+}
+/**
+ * Default strategy: use the user-supplied `systemPrompt` if present,
+ * otherwise return undefined (no system message sent).
+ */
+declare const DEFAULT_PROMPT_STRATEGY: SystemPromptStrategy;
+
+/**
+ * Chat Service Interfaces
+ * @description Contracts for chat functionality.
+ */
+
+/**
+ * Chat service contract. The high-level service used by `useChat`
+ * and any other consumer (e.g., CLI, server, scripts).
+ */
+interface IChatService {
+    /** Send a single turn and get the user message + AI response back. */
+    sendMessage(input: SendMessageInput): Promise<SendMessageResult>;
+    /** Get a single conversation summary by id. */
+    getConversation(conversationId: string): Promise<ChatConversation | null>;
+    /** List conversations. The default implementation returns an empty list. */
+    getConversations(): Promise<ChatConversation[]>;
+    /** Generate the AI response for a single turn given context. */
+    generateAIResponse(companionId: string, userMessage: string, context?: ReadonlyArray<ChatMessage>): Promise<ChatMessage>;
+    /** Generate a streaming AI response, emitting chunks via the callback. */
+    generateStreamingResponse(userMessage: string, context: ReadonlyArray<ChatMessage>, onChunk: (chunk: string) => void): Promise<string>;
+}
+/**
+ * Options for the `useChat` hook.
+ *
+ * @example
+ * ```typescript
+ * const opts: UseChatOptions = {
+ *   conversationId: "session-1",
+ *   stream: true,
+ *   storage: myStorageImpl,
+ *   config: { systemPrompt: "You are a helpful assistant.", temperature: 0.7 },
+ * };
+ * ```
+ */
+interface UseChatOptions {
+    /** Conversation identifier; also used as the storage key. */
+    readonly conversationId: string;
+    /** Optional storage implementation. When omitted, the hook is in-memory only. */
+    readonly storage?: IChatStorage;
+    /** Chat configuration (system prompt, temperature, max tokens). */
+    readonly config?: ChatConfig;
+    /** When true (default), messages are persisted to storage automatically. */
+    readonly autoSave?: boolean;
+    /** When true, AI responses are streamed. Default: false. */
+    readonly stream?: boolean;
+    readonly onMessageSent?: (message: ChatMessage) => void;
+    readonly onAIResponse?: (message: ChatMessage) => void;
+    readonly onError?: (error: string) => void;
+}
+/**
+ * Return value of the `useChat` hook.
+ */
+interface UseChatReturn {
+    /** Messages in the current conversation. */
+    readonly messages: ReadonlyArray<ChatMessage>;
+    /** True while a request is in flight (any turn). */
+    readonly isLoading: boolean;
+    /** True while the assistant is producing a response (including streaming). */
+    readonly isTyping: boolean;
+    /** Last error message; null when there is no error. */
+    readonly error: string | null;
+    /** Send a message; resolves with the AI response (or null on cancel/error). */
+    sendMessage: (text: string, type?: ChatMessage["type"]) => Promise<ChatMessage | null>;
+    /** Regenerate the most recent assistant response. */
+    regenerate: () => Promise<ChatMessage | null>;
+    /** Cancel any in-flight request issued by this hook instance. */
+    cancel: () => void;
+    /** Clear all messages and the error state. */
+    clearMessages: () => void;
+    /** Clear the error state only. */
+    clearError: () => void;
+    /** Reset transient state (loading/typing/error). Keeps messages. */
+    reset: () => void;
+    /** Update the chat configuration. */
+    updateConfig: (config: Partial<ChatConfig>) => void;
+}
+interface IMessageFormatter {
+    toGroqMessages(messages: ReadonlyArray<ChatMessage>, systemPrompt?: string): GroqMessage[];
+    toChatMessage(content: string, sender: ChatMessage["sender"]): ChatMessage;
+}
+
+/**
+ * Chat Service
+ * @description Core chat logic. Composes:
+ *              - text generation (from groq domain)
+ *              - message formatting
+ *              - system prompt resolution (via injected strategy)
+ *
+ *              Does NOT hardcode any language or fallback content.
+ *              Errors propagate to the caller; the consumer decides
+ *              how to render a user-friendly message.
+ */
+
+declare class ChatService implements IChatService {
+    private readonly textGeneration;
+    private config;
+    private promptStrategy;
+    private storage;
+    constructor(textGeneration: TextGenerationService);
+    initialize(config: ChatConfig): void;
+    updateConfig(config: Partial<ChatConfig>): void;
+    setPromptStrategy(strategy: SystemPromptStrategy): void;
+    setStorage(storage: IChatStorage): void;
+    getConversation(conversationId: string): Promise<ChatConversation | null>;
+    getConversations(): Promise<ChatConversation[]>;
+    sendMessage(input: SendMessageInput): Promise<SendMessageResult>;
+    generateAIResponse(companionId: string, userMessage: string, context?: ReadonlyArray<ChatMessage>): Promise<ChatMessage>;
+    /**
+     * Generate a streaming AI response. Emits content chunks via the
+     * `onChunk` callback. Resolves once the stream completes.
+     *
+     * @param userMessage - The latest user message.
+     * @param context - The message history to send as context.
+     * @param onChunk - Called for each content chunk.
+     */
+    generateStreamingResponse(userMessage: string, context: ReadonlyArray<ChatMessage>, onChunk: (chunk: string) => void): Promise<string>;
+    private requireStorage;
+}
+/**
+ * Helper to extract a `ChatTokenUsage` from a ChatMessage's metadata,
+ * if the model used reported it.
+ *
+ * @param message - The chat message to inspect.
+ * @returns The token usage, or `null` when not present.
+ */
+declare function extractTokenUsage(message: ChatMessage): ChatTokenUsage | null;
+
+/**
+ * Chat ID Generator
+ * @description Generates unique message IDs. Delegates randomness
+ *              to calculations/random-base36-suffix so the random
+ *              source is configurable (and the ID format is unit-testable).
+ *
+ *              Format: `msg-{timestamp}-{sender}-{counter}-{random}`
+ */
+declare class ChatIdGenerator {
+    private counter;
+    private readonly randomLength;
+    constructor(randomLength?: number);
+    /**
+     * Generate a new unique message ID.
+     */
+    next(sender: string): string;
+}
+declare const chatIdGenerator: ChatIdGenerator;
+
+/**
+ * Message Formatter
+ * @description Converts between ChatMessage (domain) and GroqMessage (transport).
+ *              Does NOT include any prompts or fallback content; those are
+ *              injected by the consumer (see prompt-strategy.ts).
+ */
+
+declare class MessageFormatter implements IMessageFormatter {
+    private readonly idGenerator;
+    constructor(idGenerator?: ChatIdGenerator);
+    toGroqMessages(messages: ReadonlyArray<ChatMessage>, systemPrompt?: string): GroqMessage[];
+    toChatMessage(content: string, sender: ChatMessage["sender"]): ChatMessage;
+}
+declare const messageFormatter: MessageFormatter;
+
+/**
+ * useChat Hook
+ * @description React hook for chat sessions with AI integration.
+ *
+ *              Features:
+ *              - Per-conversation message list with optional storage
+ *              - Streaming AI responses (opt-in via `stream: true`)
+ *              - Per-component AbortController: cancel in-flight requests
+ *                without affecting other consumers
+ *              - Errors surface through `onError` (no silent swallowing)
+ *              - Storage errors propagate the same way as generation errors
+ *
+ *              Requires an injected ChatService via the second argument
+ *              (typically obtained from `getProvider().chat`).
+ *
+ * @example
+ * ```tsx
+ * import { useChat, getProvider } from "@umituz/web-ai-groq-provider";
+ *
+ * function ChatScreen() {
+ *   const { messages, sendMessage, isLoading, isTyping, error } = useChat(
+ *     { conversationId: "demo-1" },
+ *     { chatService: getProvider()!.chat },
+ *   );
+ *   // ...
+ * }
+ * ```
+ */
+
+interface UseChatDeps {
+    readonly chatService: ChatService;
+}
+declare function useChat(options: UseChatOptions, deps?: UseChatDeps): UseChatReturn;
+
+export { type ChatConfig, type ChatConversation, ChatIdGenerator, type ChatMessage, type ChatMessageSender, type ChatMessageType, ChatService, type ChatTokenUsage, DEFAULT_PROMPT_STRATEGY, type IChatService, type IChatStorage, type IMessageFormatter, type SendMessageInput, type SendMessageResult, type SystemPromptStrategy, type UseChatDeps, type UseChatOptions, type UseChatReturn, chatIdGenerator, extractTokenUsage, messageFormatter, useChat };

package/dist/domains/chat/index.d.ts

@@ -0,0 +1,322 @@
+import { k as GroqMessage, T as TextGenerationService } from '../../text-generation.service-BP4Q_SH0.js';
+
+/**
+ * Chat Domain Entities
+ * @description Core chat message and conversation types.
+ *              All fields are readonly: consumers must not mutate
+ *              messages that are in-flight or persisted.
+ */
+type ChatMessageSender = "user" | "assistant" | "system";
+type ChatMessageType = "text" | "image" | "audio" | "sticker";
+/**
+ * Chat message structure.
+ * Use the `metadata` field for provider-specific or app-specific data
+ * (e.g., model name, token usage, reactions, or any other extension).
+ */
+interface ChatMessage {
+    readonly id: string;
+    readonly sender: ChatMessageSender;
+    readonly content: string;
+    readonly timestamp: string;
+    readonly type?: ChatMessageType;
+    readonly imageUrl?: string;
+    readonly reaction?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Conversation metadata, derived from the message history of a conversation.
+ */
+interface ChatConversation {
+    readonly id: string;
+    readonly companionId: string;
+    readonly companionName: string;
+    readonly lastMessage?: ChatMessage;
+    readonly messageCount: number;
+    readonly updatedAt: string;
+}
+/**
+ * Input for a single chat turn.
+ * The companionId is the addressable identifier for the chat partner
+ * (e.g., a character, agent, or session).
+ */
+interface SendMessageInput {
+    readonly companionId: string;
+    readonly text: string;
+    readonly type?: ChatMessageType;
+    readonly imageUrl?: string;
+}
+/**
+ * Result of a single chat turn: the user message that was sent
+ * and the assistant's reply (if generation succeeded).
+ */
+interface SendMessageResult {
+    readonly userMessage: ChatMessage;
+    readonly aiResponse?: ChatMessage;
+}
+/**
+ * Chat configuration.
+ *
+ * @example
+ * ```typescript
+ * const config: ChatConfig = {
+ *   systemPrompt: "You are a helpful assistant.",
+ *   temperature: 0.7,
+ *   maxTokens: 800,
+ * };
+ * ```
+ */
+interface ChatConfig {
+    /** System prompt prepended to the conversation. */
+    readonly systemPrompt?: string;
+    /** Sampling temperature (0.0 - 2.0). */
+    readonly temperature?: number;
+    /** Maximum number of tokens to generate per response. */
+    readonly maxTokens?: number;
+}
+/**
+ * Storage contract for persisting chat messages.
+ * The host application provides an implementation; the library never
+ * persists on its own.
+ */
+interface IChatStorage {
+    saveMessage(conversationId: string, message: ChatMessage): Promise<void>;
+    getMessages(conversationId: string): Promise<ChatMessage[]>;
+    updateMessage(messageId: string, updates: Partial<ChatMessage>): Promise<void>;
+    deleteMessage(messageId: string): Promise<void>;
+}
+/**
+ * Token usage information returned by the model, normalized to the chat layer.
+ */
+interface ChatTokenUsage {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+}
+
+/**
+ * System Prompt Strategy
+ * @description Resolves the system prompt to use for a chat session.
+ *              Allows library consumers to plug in their own prompts
+ *              without hardcoded language defaults.
+ *
+ * @example
+ * ```typescript
+ * const customStrategy: SystemPromptStrategy = {
+ *   resolve: (config) =>
+ *     config.language === "tr"
+ *       ? "Sen yardimsever bir asistansin."
+ *       : "You are a helpful assistant.",
+ * };
+ * chatService.setPromptStrategy(customStrategy);
+ * ```
+ */
+
+interface SystemPromptStrategy {
+    /**
+     * Resolve the system prompt for the given config.
+     * Returning `undefined` omits the system message entirely.
+     */
+    resolve(config: ChatConfig): string | undefined;
+}
+/**
+ * Default strategy: use the user-supplied `systemPrompt` if present,
+ * otherwise return undefined (no system message sent).
+ */
+declare const DEFAULT_PROMPT_STRATEGY: SystemPromptStrategy;
+
+/**
+ * Chat Service Interfaces
+ * @description Contracts for chat functionality.
+ */
+
+/**
+ * Chat service contract. The high-level service used by `useChat`
+ * and any other consumer (e.g., CLI, server, scripts).
+ */
+interface IChatService {
+    /** Send a single turn and get the user message + AI response back. */
+    sendMessage(input: SendMessageInput): Promise<SendMessageResult>;
+    /** Get a single conversation summary by id. */
+    getConversation(conversationId: string): Promise<ChatConversation | null>;
+    /** List conversations. The default implementation returns an empty list. */
+    getConversations(): Promise<ChatConversation[]>;
+    /** Generate the AI response for a single turn given context. */
+    generateAIResponse(companionId: string, userMessage: string, context?: ReadonlyArray<ChatMessage>): Promise<ChatMessage>;
+    /** Generate a streaming AI response, emitting chunks via the callback. */
+    generateStreamingResponse(userMessage: string, context: ReadonlyArray<ChatMessage>, onChunk: (chunk: string) => void): Promise<string>;
+}
+/**
+ * Options for the `useChat` hook.
+ *
+ * @example
+ * ```typescript
+ * const opts: UseChatOptions = {
+ *   conversationId: "session-1",
+ *   stream: true,
+ *   storage: myStorageImpl,
+ *   config: { systemPrompt: "You are a helpful assistant.", temperature: 0.7 },
+ * };
+ * ```
+ */
+interface UseChatOptions {
+    /** Conversation identifier; also used as the storage key. */
+    readonly conversationId: string;
+    /** Optional storage implementation. When omitted, the hook is in-memory only. */
+    readonly storage?: IChatStorage;
+    /** Chat configuration (system prompt, temperature, max tokens). */
+    readonly config?: ChatConfig;
+    /** When true (default), messages are persisted to storage automatically. */
+    readonly autoSave?: boolean;
+    /** When true, AI responses are streamed. Default: false. */
+    readonly stream?: boolean;
+    readonly onMessageSent?: (message: ChatMessage) => void;
+    readonly onAIResponse?: (message: ChatMessage) => void;
+    readonly onError?: (error: string) => void;
+}
+/**
+ * Return value of the `useChat` hook.
+ */
+interface UseChatReturn {
+    /** Messages in the current conversation. */
+    readonly messages: ReadonlyArray<ChatMessage>;
+    /** True while a request is in flight (any turn). */
+    readonly isLoading: boolean;
+    /** True while the assistant is producing a response (including streaming). */
+    readonly isTyping: boolean;
+    /** Last error message; null when there is no error. */
+    readonly error: string | null;
+    /** Send a message; resolves with the AI response (or null on cancel/error). */
+    sendMessage: (text: string, type?: ChatMessage["type"]) => Promise<ChatMessage | null>;
+    /** Regenerate the most recent assistant response. */
+    regenerate: () => Promise<ChatMessage | null>;
+    /** Cancel any in-flight request issued by this hook instance. */
+    cancel: () => void;
+    /** Clear all messages and the error state. */
+    clearMessages: () => void;
+    /** Clear the error state only. */
+    clearError: () => void;
+    /** Reset transient state (loading/typing/error). Keeps messages. */
+    reset: () => void;
+    /** Update the chat configuration. */
+    updateConfig: (config: Partial<ChatConfig>) => void;
+}
+interface IMessageFormatter {
+    toGroqMessages(messages: ReadonlyArray<ChatMessage>, systemPrompt?: string): GroqMessage[];
+    toChatMessage(content: string, sender: ChatMessage["sender"]): ChatMessage;
+}
+
+/**
+ * Chat Service
+ * @description Core chat logic. Composes:
+ *              - text generation (from groq domain)
+ *              - message formatting
+ *              - system prompt resolution (via injected strategy)
+ *
+ *              Does NOT hardcode any language or fallback content.
+ *              Errors propagate to the caller; the consumer decides
+ *              how to render a user-friendly message.
+ */
+
+declare class ChatService implements IChatService {
+    private readonly textGeneration;
+    private config;
+    private promptStrategy;
+    private storage;
+    constructor(textGeneration: TextGenerationService);
+    initialize(config: ChatConfig): void;
+    updateConfig(config: Partial<ChatConfig>): void;
+    setPromptStrategy(strategy: SystemPromptStrategy): void;
+    setStorage(storage: IChatStorage): void;
+    getConversation(conversationId: string): Promise<ChatConversation | null>;
+    getConversations(): Promise<ChatConversation[]>;
+    sendMessage(input: SendMessageInput): Promise<SendMessageResult>;
+    generateAIResponse(companionId: string, userMessage: string, context?: ReadonlyArray<ChatMessage>): Promise<ChatMessage>;
+    /**
+     * Generate a streaming AI response. Emits content chunks via the
+     * `onChunk` callback. Resolves once the stream completes.
+     *
+     * @param userMessage - The latest user message.
+     * @param context - The message history to send as context.
+     * @param onChunk - Called for each content chunk.
+     */
+    generateStreamingResponse(userMessage: string, context: ReadonlyArray<ChatMessage>, onChunk: (chunk: string) => void): Promise<string>;
+    private requireStorage;
+}
+/**
+ * Helper to extract a `ChatTokenUsage` from a ChatMessage's metadata,
+ * if the model used reported it.
+ *
+ * @param message - The chat message to inspect.
+ * @returns The token usage, or `null` when not present.
+ */
+declare function extractTokenUsage(message: ChatMessage): ChatTokenUsage | null;
+
+/**
+ * Chat ID Generator
+ * @description Generates unique message IDs. Delegates randomness
+ *              to calculations/random-base36-suffix so the random
+ *              source is configurable (and the ID format is unit-testable).
+ *
+ *              Format: `msg-{timestamp}-{sender}-{counter}-{random}`
+ */
+declare class ChatIdGenerator {
+    private counter;
+    private readonly randomLength;
+    constructor(randomLength?: number);
+    /**
+     * Generate a new unique message ID.
+     */
+    next(sender: string): string;
+}
+declare const chatIdGenerator: ChatIdGenerator;
+
+/**
+ * Message Formatter
+ * @description Converts between ChatMessage (domain) and GroqMessage (transport).
+ *              Does NOT include any prompts or fallback content; those are
+ *              injected by the consumer (see prompt-strategy.ts).
+ */
+
+declare class MessageFormatter implements IMessageFormatter {
+    private readonly idGenerator;
+    constructor(idGenerator?: ChatIdGenerator);
+    toGroqMessages(messages: ReadonlyArray<ChatMessage>, systemPrompt?: string): GroqMessage[];
+    toChatMessage(content: string, sender: ChatMessage["sender"]): ChatMessage;
+}
+declare const messageFormatter: MessageFormatter;
+
+/**
+ * useChat Hook
+ * @description React hook for chat sessions with AI integration.
+ *
+ *              Features:
+ *              - Per-conversation message list with optional storage
+ *              - Streaming AI responses (opt-in via `stream: true`)
+ *              - Per-component AbortController: cancel in-flight requests
+ *                without affecting other consumers
+ *              - Errors surface through `onError` (no silent swallowing)
+ *              - Storage errors propagate the same way as generation errors
+ *
+ *              Requires an injected ChatService via the second argument
+ *              (typically obtained from `getProvider().chat`).
+ *
+ * @example
+ * ```tsx
+ * import { useChat, getProvider } from "@umituz/web-ai-groq-provider";
+ *
+ * function ChatScreen() {
+ *   const { messages, sendMessage, isLoading, isTyping, error } = useChat(
+ *     { conversationId: "demo-1" },
+ *     { chatService: getProvider()!.chat },
+ *   );
+ *   // ...
+ * }
+ * ```
+ */
+
+interface UseChatDeps {
+    readonly chatService: ChatService;
+}
+declare function useChat(options: UseChatOptions, deps?: UseChatDeps): UseChatReturn;
+
+export { type ChatConfig, type ChatConversation, ChatIdGenerator, type ChatMessage, type ChatMessageSender, type ChatMessageType, ChatService, type ChatTokenUsage, DEFAULT_PROMPT_STRATEGY, type IChatService, type IChatStorage, type IMessageFormatter, type SendMessageInput, type SendMessageResult, type SystemPromptStrategy, type UseChatDeps, type UseChatOptions, type UseChatReturn, chatIdGenerator, extractTokenUsage, messageFormatter, useChat };