/*
 * Runtime Web – Unified Serverless Framework for Full-Stack TypeScript Applications
 * Documentation: https://runtimeweb.com/docs/getting-started
 *
 * @template: ai-chat
 */

/**
 * Chat Types
 *
 * Type definitions for the AI Chat microservice.
 * These types define the data structures used for chat requests,
 * responses, streaming chunks, conversation history, and session management.
 */

/**
 * Request payload for the chat endpoint.
 * Contains the session identifier, user message, and optional behavior mode.
 */
export interface ChatRequest {
    /** Unique identifier for the conversation session */
    sessionId: string;
    /** User's message to send to the AI */
    message: string;
    /** Optional behavior mode to control AI response style */
    behavior?: 'precise' | 'balanced' | 'creative';
}

/**
 * Response payload from the chat endpoint.
 * Contains the AI's response and metadata.
 */
export interface ChatResponse {
    /** Unique identifier for the conversation session */
    sessionId: string;
    /** AI-generated response to the user's message */
    response: string;
    /** ISO timestamp of when the response was generated */
    timestamp: string;
}

/**
 * A chunk of data from a streaming response.
 * Used for incremental rendering of AI responses.
 */
export interface StreamChunk {
    /** A token/text fragment from the streaming response */
    token?: string;
    /** Indicates whether the stream has completed */
    done?: boolean;
}

/**
 * A single message in a conversation.
 * Used to track the conversation history between user and assistant.
 */
export interface ConversationMessage {
    /** The role of the message sender */
    role: 'user' | 'assistant';
    /** The content of the message */
    content: string;
    /** ISO timestamp of when the message was created */
    timestamp: string;
}

/**
 * A complete turn in a conversation.
 * Represents a user message paired with the assistant's response.
 */
export interface ConversationTurn {
    /** The user's message */
    user: string;
    /** The assistant's response */
    assistant: string;
}

/**
 * A session record stored in DynamoDB.
 * Contains the full conversation history and session metadata.
 */
export interface SessionRecord {
    /** Unique identifier for the session */
    sessionId: string;
    /** Array of all messages in the conversation */
    messages: ConversationMessage[];
    /** ISO timestamp of when the session was created */
    createdAt: string;
    /** ISO timestamp of the last update to the session */
    updatedAt: string;
    /** Optional TTL for automatic session expiration (Unix timestamp) */
    ttl?: number;
}
