cre-sync/types/control-center.ts

/**
 * Control Center Types
 * CRESyncFlow - Commercial Real Estate CRM
 *
 * Type definitions for the AI-powered Control Center feature
 * that provides an interactive chat interface with tool capabilities.
 */

// =============================================================================
// Message Types
// =============================================================================

/**
 * Role of the message sender in a conversation
 */
export type MessageRole = 'user' | 'assistant' | 'system';

/**
 * Represents a single message in a Control Center conversation
 */
export interface ControlCenterMessage {
  /** Unique identifier for the message */
  id: string;
  /** Role of the message sender */
  role: MessageRole;
  /** Text content of the message */
  content: string;
  /** Tool calls made by the assistant (if any) */
  toolCalls?: ToolCall[];
  /** Results from tool executions (if any) */
  toolResults?: ToolResult[];
  /** Timestamp when the message was created */
  createdAt: string;
}

/**
 * Represents a full conversation in the Control Center
 */
export interface ControlCenterConversation {
  /** Unique identifier for the conversation */
  id: string;
  /** Title/summary of the conversation */
  title: string;
  /** Array of messages in the conversation */
  messages: ControlCenterMessage[];
  /** Timestamp when the conversation was created */
  createdAt: string;
  /** Timestamp when the conversation was last updated */
  updatedAt: string;
}

// =============================================================================
// Tool Types
// =============================================================================

/**
 * JSON Schema for tool input validation
 */
export interface JSONSchema {
  type: string;
  properties?: Record<string, JSONSchema>;
  required?: string[];
  items?: JSONSchema;
  description?: string;
  enum?: (string | number | boolean)[];
  default?: any;
  [key: string]: any;
}

/**
 * Definition of a tool available to the AI assistant
 */
export interface ToolDefinition {
  /** Unique name of the tool */
  name: string;
  /** Human-readable description of what the tool does */
  description: string;
  /** JSON Schema defining the expected input parameters */
  inputSchema: JSONSchema;
}

/**
 * Represents a tool call made by the AI assistant
 */
export interface ToolCall {
  /** Unique identifier for this tool call */
  id: string;
  /** Name of the tool being called */
  name: string;
  /** Input parameters for the tool call */
  input: Record<string, any>;
}

/**
 * Result of executing a tool call
 */
export interface ToolResult {
  /** ID of the tool call this result corresponds to */
  toolCallId: string;
  /** Whether the tool execution was successful */
  success: boolean;
  /** Result data from successful tool execution */
  result?: any;
  /** Error message if tool execution failed */
  error?: string;
}

// =============================================================================
// API Request/Response Types
// =============================================================================

/**
 * Request payload for sending a chat message
 */
export interface ChatRequest {
  /** Optional conversation ID for continuing an existing conversation */
  conversationId?: string;
  /** The user's message content */
  message: string;
  /** Optional model override (defaults to claude-sonnet-4-20250514) */
  model?: string;
}

/**
 * Response from the chat API (non-streaming)
 */
export interface ChatResponse {
  /** The conversation ID (new or existing) */
  conversationId: string;
  /** The assistant's response message */
  message: ControlCenterMessage;
  /** Tool calls made during the response (if any) */
  toolCalls?: ToolCall[];
  /** Results from tool executions (if any) */
  toolResults?: ToolResult[];
}

// =============================================================================
// Server-Sent Events (SSE) Types
// =============================================================================

/**
 * Event indicating the start of a message stream
 */
export interface MessageStartEvent {
  type: 'message_start';
  conversationId: string;
  messageId: string;
}

/**
 * Event containing a text chunk from the streaming response
 */
export interface ContentDeltaEvent {
  type: 'content_delta';
  delta: string;
}

/**
 * Event indicating a tool is being called
 */
export interface ToolCallStartEvent {
  type: 'tool_call_start';
  toolCall: ToolCall;
}

/**
 * Event containing the result of a tool call
 */
export interface ToolResultEvent {
  type: 'tool_result';
  toolResult: ToolResult;
}

/**
 * Event indicating the message stream has completed
 */
export interface MessageCompleteEvent {
  type: 'message_complete';
  message: ControlCenterMessage;
}

/**
 * Event indicating an error occurred during streaming
 */
export interface StreamErrorEvent {
  type: 'error';
  error: string;
  code?: string;
}

/**
 * Union type of all possible SSE events from the Control Center
 */
export type StreamEvent =
  | MessageStartEvent
  | ContentDeltaEvent
  | ToolCallStartEvent
  | ToolResultEvent
  | MessageCompleteEvent
  | StreamErrorEvent;

// =============================================================================
// UI State Types
// =============================================================================

/**
 * Status of the Control Center chat interface
 */
export type ControlCenterStatus = 'idle' | 'loading' | 'streaming' | 'error';

/**
 * State of the Control Center UI
 */
export interface ControlCenterState {
  /** Current conversation (if any) */
  conversation: ControlCenterConversation | null;
  /** Current status of the chat interface */
  status: ControlCenterStatus;
  /** Error message (if in error state) */
  error: string | null;
  /** Whether the input is disabled */
  inputDisabled: boolean;
}