@company-semantics/contracts 0.60.0 → 0.60.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.60.0",
+  "version": "0.60.2",
   "private": false,
   "repository": {
     "type": "git",
@@ -40,6 +40,10 @@
       "types": "./src/ralph/index.ts",
       "default": "./src/ralph/index.ts"
     },
+    "./chat": {
+      "types": "./src/chat/index.ts",
+      "default": "./src/chat/index.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",

package/src/chat/index.ts

@@ -17,4 +17,15 @@ export type {
   SharedChatMessage,
   CreateShareRequest,
   UpdateShareRequest,
+  // Chat lifecycle types
+  ChatStatus,
+  TitleSource,
+  ChatListFilters,
+  ChatSummaryExtended,
+  TitleGenerationRequest,
+  TitleGenerationResponse,
+  ChatSseEvent,
+  ChatUpdateEvent,
+  // Chat creation event (server-first navigation contract)
+  ChatCreatedEvent,
 } from './types'

package/src/chat/types.ts

@@ -103,3 +103,100 @@ export interface UpdateShareRequest {
   /** If true, update snapshot to include new messages added since share creation */
   updateSnapshot?: boolean
 }
+
+// =============================================================================
+// Chat Lifecycle Types
+// =============================================================================
+
+/**
+ * Chat status for lifecycle management.
+ * - active: Normal visible chat
+ * - archived: Hidden from main list, still searchable
+ */
+export type ChatStatus = 'active' | 'archived'
+
+/**
+ * Title source - tracks how the title was set.
+ * - auto: Generated automatically by LLM
+ * - manual: Set by user (disables future auto-generation)
+ */
+export type TitleSource = 'auto' | 'manual'
+
+/**
+ * Filters for listing chats.
+ */
+export interface ChatListFilters {
+  /** Search query - matches against title */
+  search?: string
+  /** Filter by status. Defaults to 'active' */
+  status?: ChatStatus | 'all'
+  /** Include pinned chats at top */
+  includePinned?: boolean
+  /** Pagination limit */
+  limit?: number
+  /** Pagination offset */
+  offset?: number
+}
+
+/**
+ * Extended chat summary with pin/archive/title status.
+ */
+export interface ChatSummaryExtended extends ChatSummary {
+  status: ChatStatus
+  /** If pinned, when it was pinned */
+  pinnedAt: string | null
+  /** How the title was set: 'auto' or 'manual' */
+  titleSource: TitleSource | null
+  /** When auto-title was generated (null if never auto-generated) */
+  titleGeneratedAt: string | null
+}
+
+/**
+ * Request to generate a title for a chat.
+ */
+export interface TitleGenerationRequest {
+  chatId: string
+  /** First few messages for context */
+  messages: Array<{ role: 'user' | 'assistant'; content: string }>
+}
+
+/**
+ * Response from title generation.
+ */
+export interface TitleGenerationResponse {
+  title: string
+  /** Whether this was auto-generated */
+  isAutoGenerated: boolean
+}
+
+/**
+ * SSE event types for chat updates (convention locked).
+ * Client receives these and handles accordingly.
+ */
+export type ChatSseEvent =
+  | { type: 'chat.invalidated'; chatId: string; timestamp: string }
+  | { type: 'chat.list.invalidated'; timestamp: string }
+  | ChatCreatedEvent
+
+/**
+ * Emitted exactly once after a chat is successfully persisted.
+ * Used to transition the client from /new to /chat/:id.
+ *
+ * INV-EVENT-1: This event is emitted exactly once per successful stream.
+ * INV-PERSIST-1: Chat record + messages are committed atomically before this event.
+ */
+export interface ChatCreatedEvent {
+  type: 'chat.created'
+  /** Canonical server-generated UUID - use this for URLs */
+  chatId: string
+  /** Client-provided ID for correlation (optional) */
+  interactionId?: string
+  /** Auto-generated title from first message */
+  title?: string
+  timestamp: string
+}
+
+/**
+ * Convenience alias for backwards compat.
+ */
+export type ChatUpdateEvent = ChatSseEvent

package/src/index.ts

@@ -149,6 +149,8 @@ export type {
   SharedChatMessage,
   CreateShareRequest,
   UpdateShareRequest,
+  // Chat lifecycle events (server-first navigation)
+  ChatCreatedEvent,
 } from './chat/index'
 
 // Organization domain types