@extrachill/chat 0.2.0

package/src/types/message.ts

@@ -0,0 +1,66 @@
+/**
+ * Normalized message model for the chat package.
+ *
+ * This model is backend-agnostic. Adapters map their native message
+ * format into these types before the UI sees them.
+ */
+
+/**
+ * The role that produced a message.
+ *
+ * - `user` — sent by the human
+ * - `assistant` — sent by the AI / bot
+ * - `system` — system-level context (usually hidden from UI)
+ * - `tool_call` — the assistant requesting a tool execution
+ * - `tool_result` — the result of a tool execution
+ */
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool_call' | 'tool_result';
+
+/**
+ * A single tool call requested by the assistant.
+ */
+export interface ToolCall {
+	/** Unique ID for this tool call (used to pair with result). */
+	id: string;
+	/** Tool function name. */
+	name: string;
+	/** Arguments passed to the tool. */
+	parameters: Record<string, unknown>;
+}
+
+/**
+ * Metadata for a tool result message.
+ */
+export interface ToolResultMeta {
+	/** The tool that produced this result. */
+	toolName: string;
+	/** Whether the tool call succeeded. */
+	success: boolean;
+}
+
+/**
+ * A single message in a chat conversation.
+ */
+export interface ChatMessage {
+	/** Unique message ID. */
+	id: string;
+	/** Who produced this message. */
+	role: MessageRole;
+	/** Text content (may be markdown, HTML, or plain text depending on adapter). */
+	content: string;
+	/** ISO 8601 timestamp. */
+	timestamp: string;
+	/** Tool calls requested by the assistant (only on assistant messages). */
+	toolCalls?: ToolCall[];
+	/** Tool result metadata (only on tool_result messages). */
+	toolResult?: ToolResultMeta;
+}
+
+/**
+ * Content format hint for how message content should be rendered.
+ *
+ * - `markdown` — render with a markdown renderer (default)
+ * - `html` — render as raw HTML (dangerouslySetInnerHTML)
+ * - `text` — render as plain text
+ */
+export type ContentFormat = 'markdown' | 'html' | 'text';

package/src/types/session.ts

@@ -0,0 +1,50 @@
+/**
+ * Chat session types.
+ *
+ * Sessions are optional — adapters that don't support sessions
+ * operate in single-conversation mode.
+ */
+
+import type { ChatMessage } from './message.ts';
+
+/**
+ * A chat session — a distinct conversation thread.
+ */
+export interface ChatSession {
+	/** Unique session identifier. */
+	id: string;
+	/** Human-readable title (may be auto-generated from first message). */
+	title?: string;
+	/** ISO 8601 timestamp of session creation. */
+	createdAt: string;
+	/** ISO 8601 timestamp of last activity. */
+	updatedAt: string;
+	/** Number of messages in the session (optional, for display). */
+	messageCount?: number;
+}
+
+/**
+ * Availability state of the chat service.
+ *
+ * Adapters surface this so the UI can render appropriate states
+ * without knowing the business logic behind them.
+ */
+export type ChatAvailability =
+	| { status: 'ready' }
+	| { status: 'login-required'; loginUrl?: string }
+	| { status: 'unavailable'; reason?: string }
+	| { status: 'provisioning'; message?: string }
+	| { status: 'upgrade-required'; upgradeUrl?: string; message?: string }
+	| { status: 'error'; message: string };
+
+/**
+ * The initial state returned by an adapter on mount.
+ */
+export interface ChatInitialState {
+	/** Current availability of the chat service. */
+	availability: ChatAvailability;
+	/** Active session (if resuming). */
+	session?: ChatSession;
+	/** Messages for the active session (if resuming). */
+	messages?: ChatMessage[];
+}