Client Contract

JazzmineChat works with any backend client that matches IJazzmineClient. No runtime lock-in to a specific SDK.

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

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;
    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 the 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 a paginated conversation list for a user.	During initial load and sidebar pagination.
`searchConversations`	Returns paginated conversation search results.	When users search chats.
`updateConversation`	Updates conversation metadata (title).	When rename actions are triggered.
`getConversationMessages`	Fetches paginated historical messages.	When a conversation is opened and history is loaded.
`getHealth`	Returns service health and agent name.	Used for assistant naming fallback behavior.

Core types

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;
};

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.

Why this contract exists

IJazzmineClient interface

Method-by-method notes

Core types

History mapping rules in JazzmineChat

On this page