wiil-core-js 0.0.82

package/dist/core/conversation/conversation-message.schema.d.ts

@@ -0,0 +1,307 @@
+import z from 'zod';
+/**
+ * @fileoverview Conversation message schema definitions for chat and email messages.
+ *
+ * Message schemas define the structure of individual messages exchanged in conversations between users
+ * and AI agents. Supports multiple message types (chat, email) with distinct schemas for user-originated
+ * and agent-originated messages, enabling proper message threading, context tracking, and channel-specific
+ * formatting.
+ *
+ * @module conversation/conversation-message
+ */
+/**
+ * Message type enum for distinguishing message senders.
+ *
+ * Identifies who sent a message in a conversation to enable proper message
+ * routing, formatting, and context tracking.
+ */
+export declare enum MessageType {
+    /** Message sent by end user/customer */
+    USER = "user",
+    /** Message sent by AI agent */
+    AGENT = "assistant",
+    /** Message sent by human agent (live support) */
+    HUMAN_AGENT = "human_agent",
+    /** System-generated message (events, notifications) */
+    SYSTEM = "system"
+}
+/**
+ * System message event type enum.
+ *
+ * Identifies the type of system event that triggered a system message,
+ * used for handover tracking, agent status, and conversation transfers.
+ */
+export declare enum SystemMessageEventType {
+    /** User or AI requested handover to human agent */
+    HANDOVER_REQUESTED = "handover_requested",
+    /** Human agent accepted the handover request */
+    HANDOVER_ACCEPTED = "handover_accepted",
+    /** Handover to human agent completed successfully */
+    HANDOVER_COMPLETED = "handover_completed",
+    /** Handover attempt failed */
+    HANDOVER_FAILED = "handover_failed",
+    /** Human agent joined the conversation */
+    AGENT_JOINED = "agent_joined",
+    /** Human agent left the conversation */
+    AGENT_LEFT = "agent_left",
+    /** Conversation transferred to another agent or queue */
+    CONVERSATION_TRANSFERRED = "conversation_transferred"
+}
+/**
+ * Base chat message schema.
+ *
+ * Foundation schema for all chat-based messages containing core fields shared by both user and
+ * assistant messages. Extended by UserChatMessageSchema and AssistantChatMessageSchema with
+ * role-specific identifiers for message threading and conversation flow tracking.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extended By**: UserChatMessageSchema, AssistantChatMessageSchema for role-specific messages
+ * - **Relationship**: N:1 - Multiple messages belong to one conversation (via conversation_config_id)
+ * - **Storage**: Stored in conversation message arrays and separate message collections
+ * - **LLM Context**: llm_conversation_id enables multi-turn context tracking with LLM providers
+ *
+ * **Message Flow:**
+ * - User sends message → UserChatMessage created → Agent processes → AssistantChatMessage generated
+ * - Messages linked via user_message_id and assistant_message_id for threading
+ */
+export declare const BaseChatMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Base email message schema extending chat message with email-specific fields.
+ *
+ * Extends BaseChatMessageSchema with email-specific attributes including subject line and email
+ * identifier flag. Used as foundation for user and assistant email messages in email-based
+ * conversation channels.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with email-specific fields
+ * - **Extended By**: UserEmailMessageSchema, AssistantEmailMessageSchema
+ * - **Channel**: Used exclusively for EMAIL conversation type
+ * - **Threading**: Subject line enables email thread grouping and conversation continuity
+ *
+ * **Email Features:**
+ * - Subject line for email clients and threading
+ * - isEmail flag distinguishes email messages from chat messages in unified message stores
+ */
+export declare const BaseEmailMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    subject: z.ZodString;
+    isEmail: z.ZodDefault<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+/**
+ * User chat message schema.
+ *
+ * Represents a message sent by a user/customer in a chat conversation. Contains user-specific
+ * identifiers for message threading and links to the previous assistant message to maintain
+ * conversation context and flow.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with user-specific fields
+ * - **Message Type**: Always 'user' (MessageType.USER)
+ * - **Threading**: Links to previous assistant message via last_assistant_message_id
+ * - **Flow**: User message → Agent processes → AssistantChatMessage generated
+ *
+ * **Message Threading:**
+ * - user_message_id: Unique identifier for this user message
+ * - last_assistant_message_id: References the assistant's previous message being responded to
+ * - Enables tracking conversation turns and maintaining context
+ */
+export declare const UserChatMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    message_type: z.ZodDefault<z.ZodLiteral<MessageType.USER>>;
+    user_message_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    last_assistant_message_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Assistant chat message schema.
+ *
+ * Represents a message generated by the AI agent in a chat conversation. Contains agent-specific
+ * identifiers and links to the user message being responded to, enabling proper conversation
+ * threading and context tracking.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with assistant-specific fields
+ * - **Message Type**: Always 'assistant' (MessageType.AGENT)
+ * - **Threading**: Links to user message being responded to via last_user_message_id
+ * - **Flow**: User message received → Agent generates → AssistantChatMessage created
+ *
+ * **Message Threading:**
+ * - assistant_message_id: Required unique identifier for this assistant message
+ * - last_user_message_id: References the user message being responded to
+ * - Enables conversation turn tracking and response latency measurement
+ */
+export declare const AssistantChatMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    message_type: z.ZodDefault<z.ZodLiteral<MessageType.AGENT>>;
+    assistant_message_id: z.ZodString;
+    last_user_message_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * User email message schema.
+ *
+ * Represents an email message sent by a user/customer. Extends base email schema with user-specific
+ * fields and optional provider message ID for integration with external email services (Gmail, Outlook, etc.).
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseEmailMessageSchema with user-specific fields
+ * - **Message Type**: Always 'user' (MessageType.USER)
+ * - **Channel**: Used exclusively for EMAIL conversation type
+ * - **Provider Integration**: Links to external email service message IDs
+ *
+ * **Email Integration:**
+ * - provider_message_id enables tracking emails across platforms
+ * - Supports Gmail API, Outlook Graph API, SendGrid, etc.
+ * - Used for reply-to threading and email service synchronization
+ */
+export declare const UserEmailMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    subject: z.ZodString;
+    isEmail: z.ZodDefault<z.ZodLiteral<true>>;
+    message_type: z.ZodDefault<z.ZodLiteral<MessageType.USER>>;
+    provider_message_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Assistant email message schema.
+ *
+ * Represents an email message generated by the AI agent in response to a user email. Extends base
+ * email schema with assistant message type, used for automated email responses and email-based
+ * customer support interactions.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseEmailMessageSchema with assistant-specific fields
+ * - **Message Type**: Always 'assistant' (MessageType.AGENT)
+ * - **Channel**: Used exclusively for EMAIL conversation type
+ * - **Use Cases**: Automated customer support replies, FAQ responses, ticket acknowledgments
+ *
+ * **Email Response Features:**
+ * - Inherits subject line from BaseEmailMessageSchema for thread continuity
+ * - Agent-generated content formatted for email clients
+ * - Supports HTML formatting and attachments via message content
+ */
+export declare const AssistantEmailMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    subject: z.ZodString;
+    isEmail: z.ZodDefault<z.ZodLiteral<true>>;
+    message_type: z.ZodDefault<z.ZodLiteral<MessageType.AGENT>>;
+}, z.core.$strip>;
+/**
+ * Human agent chat message schema.
+ *
+ * Represents a message sent by a human support agent in a chat conversation.
+ * Used when conversations are handed over from AI to live agents for complex
+ * issue resolution or customer preference.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with human agent-specific fields
+ * - **Message Type**: Always 'human_agent' (MessageType.HUMAN_AGENT)
+ * - **Triggered By**: Handover from AI agent or direct human agent assignment
+ * - **Session Tracking**: agent_session_id links to workforce management system
+ *
+ * @typedef {Object} HumanAgentChatMessage
+ * @property {string} message_type - Fixed to 'human_agent'
+ * @property {string} agent_message_id - Unique identifier for this human agent message
+ * @property {string} agent_session_id - Agent workforce session ID for tracking
+ * @property {string} [last_user_message_id] - ID of the user message being responded to
+ */
+export declare const HumanAgentChatMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    message_type: z.ZodDefault<z.ZodLiteral<MessageType.HUMAN_AGENT>>;
+    agent_message_id: z.ZodString;
+    agent_session_id: z.ZodString;
+    last_user_message_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Human agent email message schema.
+ *
+ * Represents an email message sent by a human support agent. Used when email
+ * conversations require human intervention for complex issues, escalations,
+ * or sensitive customer interactions.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseEmailMessageSchema with human agent-specific fields
+ * - **Message Type**: Always 'human_agent' (MessageType.HUMAN_AGENT)
+ * - **Channel**: Used exclusively for EMAIL conversation type
+ * - **Session Tracking**: agent_session_id links to workforce management system
+ *
+ * @typedef {Object} HumanAgentEmailMessage
+ * @property {string} message_type - Fixed to 'human_agent'
+ * @property {string} agent_session_id - Agent workforce session ID
+ */
+export declare const HumanAgentEmailMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    subject: z.ZodString;
+    isEmail: z.ZodDefault<z.ZodLiteral<true>>;
+    message_type: z.ZodDefault<z.ZodLiteral<MessageType.HUMAN_AGENT>>;
+    agent_session_id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * System message schema.
+ *
+ * Represents system-generated messages for tracking conversation events such as
+ * handovers, agent joins/leaves, and transfers. Not directly visible to users
+ * but recorded for audit trails and conversation state tracking.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with system-specific fields
+ * - **Message Type**: Always 'system' (MessageType.SYSTEM)
+ * - **Purpose**: Audit trail, conversation state tracking, event logging
+ * - **Visibility**: Typically hidden from end users, visible in admin dashboards
+ *
+ * @typedef {Object} SystemMessage
+ * @property {string} message_type - Fixed to 'system'
+ * @property {string} system_message_id - Unique identifier for this system message
+ * @property {SystemMessageEventType} event_type - Type of system event
+ * @property {Object} [metadata] - Additional event-specific metadata
+ */
+export declare const SystemMessageSchema: z.ZodObject<{
+    conversation_config_id: z.ZodString;
+    message: z.ZodString;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+    llm_conversation_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    message_type: z.ZodDefault<z.ZodLiteral<MessageType.SYSTEM>>;
+    system_message_id: z.ZodString;
+    event_type: z.ZodEnum<typeof SystemMessageEventType>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type UserChatMessage = z.infer<typeof UserChatMessageSchema>;
+export type AssistantChatMessage = z.infer<typeof AssistantChatMessageSchema>;
+export type UserEmailMessage = z.infer<typeof UserEmailMessageSchema>;
+export type AssistantEmailMessage = z.infer<typeof AssistantEmailMessageSchema>;
+export type HumanAgentChatMessage = z.infer<typeof HumanAgentChatMessageSchema>;
+export type HumanAgentEmailMessage = z.infer<typeof HumanAgentEmailMessageSchema>;
+export type SystemMessage = z.infer<typeof SystemMessageSchema>;
+export type ChatMessage = UserChatMessage | AssistantChatMessage | UserEmailMessage | AssistantEmailMessage | HumanAgentChatMessage | HumanAgentEmailMessage | SystemMessage;

package/dist/core/conversation/conversation-message.schema.js

@@ -0,0 +1,275 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemMessageSchema = exports.HumanAgentEmailMessageSchema = exports.HumanAgentChatMessageSchema = exports.AssistantEmailMessageSchema = exports.UserEmailMessageSchema = exports.AssistantChatMessageSchema = exports.UserChatMessageSchema = exports.BaseEmailMessageSchema = exports.BaseChatMessageSchema = exports.SystemMessageEventType = exports.MessageType = void 0;
+const zod_1 = __importDefault(require("zod"));
+/**
+ * @fileoverview Conversation message schema definitions for chat and email messages.
+ *
+ * Message schemas define the structure of individual messages exchanged in conversations between users
+ * and AI agents. Supports multiple message types (chat, email) with distinct schemas for user-originated
+ * and agent-originated messages, enabling proper message threading, context tracking, and channel-specific
+ * formatting.
+ *
+ * @module conversation/conversation-message
+ */
+/**
+ * Message type enum for distinguishing message senders.
+ *
+ * Identifies who sent a message in a conversation to enable proper message
+ * routing, formatting, and context tracking.
+ */
+var MessageType;
+(function (MessageType) {
+    /** Message sent by end user/customer */
+    MessageType["USER"] = "user";
+    /** Message sent by AI agent */
+    MessageType["AGENT"] = "assistant";
+    /** Message sent by human agent (live support) */
+    MessageType["HUMAN_AGENT"] = "human_agent";
+    /** System-generated message (events, notifications) */
+    MessageType["SYSTEM"] = "system";
+})(MessageType || (exports.MessageType = MessageType = {}));
+/**
+ * System message event type enum.
+ *
+ * Identifies the type of system event that triggered a system message,
+ * used for handover tracking, agent status, and conversation transfers.
+ */
+var SystemMessageEventType;
+(function (SystemMessageEventType) {
+    /** User or AI requested handover to human agent */
+    SystemMessageEventType["HANDOVER_REQUESTED"] = "handover_requested";
+    /** Human agent accepted the handover request */
+    SystemMessageEventType["HANDOVER_ACCEPTED"] = "handover_accepted";
+    /** Handover to human agent completed successfully */
+    SystemMessageEventType["HANDOVER_COMPLETED"] = "handover_completed";
+    /** Handover attempt failed */
+    SystemMessageEventType["HANDOVER_FAILED"] = "handover_failed";
+    /** Human agent joined the conversation */
+    SystemMessageEventType["AGENT_JOINED"] = "agent_joined";
+    /** Human agent left the conversation */
+    SystemMessageEventType["AGENT_LEFT"] = "agent_left";
+    /** Conversation transferred to another agent or queue */
+    SystemMessageEventType["CONVERSATION_TRANSFERRED"] = "conversation_transferred";
+})(SystemMessageEventType || (exports.SystemMessageEventType = SystemMessageEventType = {}));
+/**
+ * Base chat message schema.
+ *
+ * Foundation schema for all chat-based messages containing core fields shared by both user and
+ * assistant messages. Extended by UserChatMessageSchema and AssistantChatMessageSchema with
+ * role-specific identifiers for message threading and conversation flow tracking.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extended By**: UserChatMessageSchema, AssistantChatMessageSchema for role-specific messages
+ * - **Relationship**: N:1 - Multiple messages belong to one conversation (via conversation_config_id)
+ * - **Storage**: Stored in conversation message arrays and separate message collections
+ * - **LLM Context**: llm_conversation_id enables multi-turn context tracking with LLM providers
+ *
+ * **Message Flow:**
+ * - User sends message → UserChatMessage created → Agent processes → AssistantChatMessage generated
+ * - Messages linked via user_message_id and assistant_message_id for threading
+ */
+exports.BaseChatMessageSchema = zod_1.default.object({
+    conversation_config_id: zod_1.default.string().describe("ID of the conversation configuration this message belongs to (N:1 relationship, references ServiceConversationConfig for conversation context and metadata)"),
+    message: zod_1.default.string().describe("Text content of the message sent by user or generated by agent, may include plain text or markdown formatting depending on channel capabilities"),
+    timestamp: zod_1.default.number().default(Date.now()).describe("Unix timestamp in milliseconds when the message was created and sent (default: current time, used for chronological ordering and latency analysis)"),
+    llm_conversation_id: zod_1.default.string().optional().nullable().describe("LLM provider conversation thread ID for multi-turn context tracking (OpenAI thread ID, Anthropic conversation ID) enabling context retention across messages"),
+});
+/**
+ * Base email message schema extending chat message with email-specific fields.
+ *
+ * Extends BaseChatMessageSchema with email-specific attributes including subject line and email
+ * identifier flag. Used as foundation for user and assistant email messages in email-based
+ * conversation channels.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with email-specific fields
+ * - **Extended By**: UserEmailMessageSchema, AssistantEmailMessageSchema
+ * - **Channel**: Used exclusively for EMAIL conversation type
+ * - **Threading**: Subject line enables email thread grouping and conversation continuity
+ *
+ * **Email Features:**
+ * - Subject line for email clients and threading
+ * - isEmail flag distinguishes email messages from chat messages in unified message stores
+ */
+exports.BaseEmailMessageSchema = exports.BaseChatMessageSchema.safeExtend({
+    subject: zod_1.default.string().describe("Subject line of the email message used in email clients and for email thread grouping, typically maintained across conversation for proper threading"),
+    isEmail: zod_1.default.literal(true).default(true).describe("Flag indicating this is an email message (always true), distinguishes email messages from chat messages in unified message collections"),
+});
+/**
+ * User chat message schema.
+ *
+ * Represents a message sent by a user/customer in a chat conversation. Contains user-specific
+ * identifiers for message threading and links to the previous assistant message to maintain
+ * conversation context and flow.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with user-specific fields
+ * - **Message Type**: Always 'user' (MessageType.USER)
+ * - **Threading**: Links to previous assistant message via last_assistant_message_id
+ * - **Flow**: User message → Agent processes → AssistantChatMessage generated
+ *
+ * **Message Threading:**
+ * - user_message_id: Unique identifier for this user message
+ * - last_assistant_message_id: References the assistant's previous message being responded to
+ * - Enables tracking conversation turns and maintaining context
+ */
+exports.UserChatMessageSchema = exports.BaseChatMessageSchema.safeExtend({
+    message_type: zod_1.default.literal(MessageType.USER).default(MessageType.USER).describe("Message type identifier fixed to 'user' indicating this message was sent by the customer/end-user"),
+    user_message_id: zod_1.default.string().optional().nullable().describe("Unique identifier for this user message (typically UUID) used for message threading, deduplication, and reference in assistant responses"),
+    last_assistant_message_id: zod_1.default.string().optional().describe("ID of the last assistant message this user message is responding to, creates bidirectional message threading for conversation flow tracking"),
+});
+/**
+ * Assistant chat message schema.
+ *
+ * Represents a message generated by the AI agent in a chat conversation. Contains agent-specific
+ * identifiers and links to the user message being responded to, enabling proper conversation
+ * threading and context tracking.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with assistant-specific fields
+ * - **Message Type**: Always 'assistant' (MessageType.AGENT)
+ * - **Threading**: Links to user message being responded to via last_user_message_id
+ * - **Flow**: User message received → Agent generates → AssistantChatMessage created
+ *
+ * **Message Threading:**
+ * - assistant_message_id: Required unique identifier for this assistant message
+ * - last_user_message_id: References the user message being responded to
+ * - Enables conversation turn tracking and response latency measurement
+ */
+exports.AssistantChatMessageSchema = exports.BaseChatMessageSchema.safeExtend({
+    message_type: zod_1.default.literal(MessageType.AGENT).default(MessageType.AGENT).describe("Message type identifier fixed to 'assistant' indicating this message was generated by the AI agent"),
+    assistant_message_id: zod_1.default.string().describe("Required unique identifier for this assistant message (typically UUID) used for message threading, user response linking, and performance tracking"),
+    last_user_message_id: zod_1.default.string().optional().describe("ID of the user message this assistant message is responding to, creates bidirectional message threading and enables response latency measurement"),
+});
+/**
+ * User email message schema.
+ *
+ * Represents an email message sent by a user/customer. Extends base email schema with user-specific
+ * fields and optional provider message ID for integration with external email services (Gmail, Outlook, etc.).
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseEmailMessageSchema with user-specific fields
+ * - **Message Type**: Always 'user' (MessageType.USER)
+ * - **Channel**: Used exclusively for EMAIL conversation type
+ * - **Provider Integration**: Links to external email service message IDs
+ *
+ * **Email Integration:**
+ * - provider_message_id enables tracking emails across platforms
+ * - Supports Gmail API, Outlook Graph API, SendGrid, etc.
+ * - Used for reply-to threading and email service synchronization
+ */
+exports.UserEmailMessageSchema = exports.BaseEmailMessageSchema.safeExtend({
+    message_type: zod_1.default.literal(MessageType.USER).default(MessageType.USER).describe("Message type identifier fixed to 'user' indicating this email was sent by the customer/end-user"),
+    provider_message_id: zod_1.default.string().optional().nullable().describe("Provider-specific email message ID from external email services (Gmail message ID, Outlook message ID, SendGrid message ID) for email tracking and reply threading"),
+});
+/**
+ * Assistant email message schema.
+ *
+ * Represents an email message generated by the AI agent in response to a user email. Extends base
+ * email schema with assistant message type, used for automated email responses and email-based
+ * customer support interactions.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseEmailMessageSchema with assistant-specific fields
+ * - **Message Type**: Always 'assistant' (MessageType.AGENT)
+ * - **Channel**: Used exclusively for EMAIL conversation type
+ * - **Use Cases**: Automated customer support replies, FAQ responses, ticket acknowledgments
+ *
+ * **Email Response Features:**
+ * - Inherits subject line from BaseEmailMessageSchema for thread continuity
+ * - Agent-generated content formatted for email clients
+ * - Supports HTML formatting and attachments via message content
+ */
+exports.AssistantEmailMessageSchema = exports.BaseEmailMessageSchema.safeExtend({
+    message_type: zod_1.default.literal(MessageType.AGENT).default(MessageType.AGENT).describe("Message type identifier fixed to 'assistant' indicating this email was generated by the AI agent"),
+});
+// ============================================================================
+// HUMAN AGENT MESSAGE SCHEMAS
+// ============================================================================
+/**
+ * Human agent chat message schema.
+ *
+ * Represents a message sent by a human support agent in a chat conversation.
+ * Used when conversations are handed over from AI to live agents for complex
+ * issue resolution or customer preference.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with human agent-specific fields
+ * - **Message Type**: Always 'human_agent' (MessageType.HUMAN_AGENT)
+ * - **Triggered By**: Handover from AI agent or direct human agent assignment
+ * - **Session Tracking**: agent_session_id links to workforce management system
+ *
+ * @typedef {Object} HumanAgentChatMessage
+ * @property {string} message_type - Fixed to 'human_agent'
+ * @property {string} agent_message_id - Unique identifier for this human agent message
+ * @property {string} agent_session_id - Agent workforce session ID for tracking
+ * @property {string} [last_user_message_id] - ID of the user message being responded to
+ */
+exports.HumanAgentChatMessageSchema = exports.BaseChatMessageSchema.safeExtend({
+    message_type: zod_1.default.literal(MessageType.HUMAN_AGENT).default(MessageType.HUMAN_AGENT).describe("Message type identifier fixed to 'human_agent' indicating this message was sent by a human support agent"),
+    agent_message_id: zod_1.default.string().describe("Unique identifier for this human agent message (typically UUID) used for message threading and response tracking"),
+    agent_session_id: zod_1.default.string().describe("Agent workforce session ID linking this message to the human agent's active support session for workload tracking and analytics"),
+    last_user_message_id: zod_1.default.string().optional().describe("ID of the user message this human agent message is responding to, creates bidirectional message threading"),
+});
+/**
+ * Human agent email message schema.
+ *
+ * Represents an email message sent by a human support agent. Used when email
+ * conversations require human intervention for complex issues, escalations,
+ * or sensitive customer interactions.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseEmailMessageSchema with human agent-specific fields
+ * - **Message Type**: Always 'human_agent' (MessageType.HUMAN_AGENT)
+ * - **Channel**: Used exclusively for EMAIL conversation type
+ * - **Session Tracking**: agent_session_id links to workforce management system
+ *
+ * @typedef {Object} HumanAgentEmailMessage
+ * @property {string} message_type - Fixed to 'human_agent'
+ * @property {string} agent_session_id - Agent workforce session ID
+ */
+exports.HumanAgentEmailMessageSchema = exports.BaseEmailMessageSchema.safeExtend({
+    message_type: zod_1.default.literal(MessageType.HUMAN_AGENT).default(MessageType.HUMAN_AGENT).describe("Message type identifier fixed to 'human_agent' indicating this email was sent by a human support agent"),
+    agent_session_id: zod_1.default.string().describe("Agent workforce session ID linking this email to the human agent's active support session"),
+});
+// ============================================================================
+// SYSTEM MESSAGE SCHEMA
+// ============================================================================
+/**
+ * System message schema.
+ *
+ * Represents system-generated messages for tracking conversation events such as
+ * handovers, agent joins/leaves, and transfers. Not directly visible to users
+ * but recorded for audit trails and conversation state tracking.
+ *
+ * @remarks
+ * **Architecture Context:**
+ * - **Extends**: BaseChatMessageSchema with system-specific fields
+ * - **Message Type**: Always 'system' (MessageType.SYSTEM)
+ * - **Purpose**: Audit trail, conversation state tracking, event logging
+ * - **Visibility**: Typically hidden from end users, visible in admin dashboards
+ *
+ * @typedef {Object} SystemMessage
+ * @property {string} message_type - Fixed to 'system'
+ * @property {string} system_message_id - Unique identifier for this system message
+ * @property {SystemMessageEventType} event_type - Type of system event
+ * @property {Object} [metadata] - Additional event-specific metadata
+ */
+exports.SystemMessageSchema = exports.BaseChatMessageSchema.safeExtend({
+    message_type: zod_1.default.literal(MessageType.SYSTEM).default(MessageType.SYSTEM).describe("Message type identifier fixed to 'system' indicating this is a system-generated event message"),
+    system_message_id: zod_1.default.string().describe("Unique identifier for this system message (typically UUID) used for event tracking and audit trail reference"),
+    event_type: zod_1.default.enum(SystemMessageEventType).describe("Type of system event that triggered this message (handover, agent status, transfer events)"),
+    metadata: zod_1.default.record(zod_1.default.string(), zod_1.default.unknown()).optional().describe("Additional event-specific metadata as key-value pairs (agent ID, transfer reason, queue name, etc.)"),
+});

package/dist/core/conversation/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Central export point for conversation schemas.
+ * @module conversation
+ */
+export * from './conversation-config.schema';
+export * from './conversation-message.schema';
+export * from './translation-config.schema';
+export * from './translation-conversation.schema';
+export * from './outbound-call.schema';
+export * from './outbound-email.schema';
+export * from './outbound-sms.schema';
+export * from './outbound-template.schema';

package/dist/core/conversation/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * @fileoverview Central export point for conversation schemas.
+ * @module conversation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./conversation-config.schema"), exports);
+__exportStar(require("./conversation-message.schema"), exports);
+__exportStar(require("./translation-config.schema"), exports);
+__exportStar(require("./translation-conversation.schema"), exports);
+__exportStar(require("./outbound-call.schema"), exports);
+__exportStar(require("./outbound-email.schema"), exports);
+__exportStar(require("./outbound-sms.schema"), exports);
+__exportStar(require("./outbound-template.schema"), exports);