Jazzmine

Why this contract exists

JazzmineChat is managed UI, not a backend SDK. It needs a predictable client interface so it can create/list/search/update/delete conversations and load/send messages.

If your backend client has the same method signatures and return shapes as IJazzmineClient, it is compatible.

No SDK lock-in

You can use the official SDK or your own client implementation as long as it matches the contract.

IJazzmineClient interface

ijazzmine-client.ts

interface IJazzmineClient {
  sendMessage(
    message: string,
    options?: {
      conversationId?: string;
      autoCreateConversation?: boolean;
      conversationTitle?: string;
      explicitContext?: string[];
    }
  ): Promise<{
    response: {
      response: string;
      response_markdown: string;
      conversation_id: string;
      message_id: string;
      is_blocked: boolean;
      errors: string[];
    };
    conversationId: string;
  }>;

  createConversation(payload?: { title?: string; user_id?: string }): Promise<{
    conversation_id: string;
    title: string;
  }>;

  deleteConversation(conversationId: string): Promise<{
    conversation_id: string;
    deleted: boolean;
  }>;

  listConversations(params: {
    userId: string;
    limit?: number;
    offset?: number;
  }): Promise<{
    conversations: Array<{
      conversation_id: string;
      title: string;
      last_updated_at: number;
    }>;
    total: number;
    hasMore: boolean;
    offset: number;
    limit: number;
  }>;

  searchConversations(params: {
    userId: string;
    query: string;
    limit?: number;
    offset?: number;
  }): Promise<{
    conversations: Array<{
      conversation_id: string;
      title: string;
      last_updated_at: number;
    }>;
    total: number;
    hasMore: boolean;
    offset: number;
    limit: number;
    query?: string;
  }>;

  updateConversation(
    conversationId: string,
    payload: { title: string }
  ): Promise<{
    conversation_id: string;
    title: string;
    last_updated_at: number;
  }>;

  getConversationMessages(params: {
    conversationId: string;
    limit?: number;
    offset?: number;
  }): Promise<{
    conversation_id: string;
    messages: Array<{
      id: string;
      role: 'user' | 'assistant' | 'colleague_assistant' | 'system';
      original_content: string;
      enhanced_message: string;
      explicit_context?: string[] | null;
      timestamp: number;
    }>;
    total: number;
    hasMore: boolean;
  }>;

  getHealth(): Promise<{
    status: string;
    agent_name: string;
  }>;
}

Method-by-method notes

Method	What it does	When JazzmineChat uses it
sendMessage	Sends a user message and returns assistant response payload.	Whenever the user submits a new prompt.
createConversation	Creates a new conversation record.	When starting a fresh chat flow.
deleteConversation	Deletes one conversation by id.	When a user deletes a chat from sidebar actions.
listConversations	Returns paginated conversation list for a user.	During initial load and pagination of sidebar chats.
searchConversations	Returns paginated conversation search results.	When users search chats in the modal/sidebar flow.
updateConversation	Updates conversation metadata (title).	When rename actions are triggered.
getConversationMessages	Fetches paginated historical messages for one conversation.	When a conversation is opened and history is loaded.
getHealth	Returns service health and agent name.	Used for assistant naming fallback behavior.

Core types

These are the core data shapes used across component APIs and history/context mapping.

core-types.ts

type Context = string;

type Message = {
  id: string;
  text: string;
  sender: 'user' | 'assistant';
  timestamp: string;
  contexts?: Context[];
};

type Chat = {
  conversation_id: string;
  title: string;
  last_updated_at: number;
};

Context: a selected context snippet forwarded with send operations.

Message: the UI message model used by chat components for rendering sender, text, timestamp, and optional contexts.

Chat: a conversation list/search item containing conversation_id, title, and last update timestamp.

History mapping rules in JazzmineChat

Only user and assistant roles are rendered.
Message text is sourced from original_content.
explicit_context is mapped into Message.contexts when non-empty.
If explicit_context is missing or empty, contexts is omitted.