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

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

/**
 * Request payload for the chat endpoint.
 * Contains the session identifier and user message.
 */
export interface ChatRequest {
    /** Unique identifier for the conversation session */
    sessionId: string;
    /** User's message to send to the AI */
    message: string;
}

/**
 * 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 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 document retrieved from the knowledge base via vector search.
 * Used in RAG (Retrieval-Augmented Generation) to provide context.
 */
export interface RelevantDocument {
    /** Unique identifier for the document */
    id: string;
    /** The text content of the document */
    content: string;
    /** Similarity score from the vector search (0-1) */
    score: number;
    /** Optional metadata associated with the document */
    metadata?: Record<string, unknown>;
}

/**
 * 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;
}
