Jazzmine

Constructor

constructor.ts

new JazzmineClient(baseEndpoint: string, options?: JazzmineClientOptions)

Framework-agnostic client

The same client works in React, Vue, Svelte, Next.js, and vanilla TypeScript apps.

Constructor options

Prop	Type	Default	Description
apiKey	string	undefined	Bearer token added as Authorization: Bearer <apiKey>.
timeoutMs	number	300000	Request timeout in milliseconds.
retries	number	2	Default retry attempts for retryable requests.
retryBackoffMs	number	350	Linear backoff base in milliseconds.
autoDiscoverEndpoints	boolean	true	Auto-load endpoint routes from /info when available.
defaultUserId	string	"user"	Fallback user_id for requests.
fetchImpl	typeof fetch	runtime fetch	Custom fetch implementation for non-browser runtimes.

Public API

public-api.ts

getHealth(requestOptions?: RequestOptions): Promise<HealthResponse>
getInfo(requestOptions?: RequestOptions): Promise<InfoResponse>
createConversation(payload?: ConversationCreateRequest, requestOptions?: RequestOptions): Promise<ConversationCreateResponse>
listConversations(params: ConversationListParams, requestOptions?: RequestOptions): Promise<ConversationPage>
searchConversations(params: ConversationSearchParams, requestOptions?: RequestOptions): Promise<ConversationPage>
updateConversation(conversationId: string, payload: ConversationUpdateRequest, requestOptions?: RequestOptions): Promise<ConversationUpdateResponse>
getConversationMessages(params: ConversationMessagesParams, requestOptions?: RequestOptions): Promise<ConversationMessagesPage>
deleteConversation(conversationId: string, requestOptions?: RequestOptions): Promise<ConversationDeleteResponse>
chat(payload: ChatRequestPayload, requestOptions?: RequestOptions): Promise<ChatResponse>
chatStream(payload: ChatRequestPayload, handlers?: StreamHandlers, requestOptions?: RequestOptions): Promise<ChatResponse>
sendMessage(message: string, options?: {
  conversationId?: string;
  userId?: string;
  explicitContext?: string[];
  metadata?: Record<string, unknown>;
  autoCreateConversation?: boolean;
  conversationTitle?: string;
  requestOptions?: RequestOptions;
}): Promise<{ response: ChatResponse; conversationId: string }>
resolveServerEndpoints(requestOptions?: RequestOptions): Promise<{
  chat: string;
  stream: string;
  conversations: string;
  health: string;
  info: string;
}>

Conversation endpoint examples

List conversations

list-conversations.ts

// Request: fetch the first page for one user.
const page = await client.listConversations({
  userId: "alice",
  limit: 20,
  offset: 0,
});

console.log(page.total, page.hasMore);
console.log(page.conversations[0]?.title);

list-conversations-response.json

{
  "conversations": [
    {
      "conversation_id": "conv_123",
      "user_id": "alice",
      "agent_id": "agent_main",
      "title": "Project planning",
      "created_at": 1712500000,
      "last_updated_at": 1712500600
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0,
  "hasMore": true
}

Search conversations

search-conversations.ts

// Request: search by title/content keyword for one user.
const result = await client.searchConversations({
  userId: "alice",
  query: "planning",
  limit: 10,
  offset: 0,
});

console.log(result.query); // "planning"
console.log(result.conversations.length);

search-conversations-response.json

{
  "conversations": [
    {
      "conversation_id": "conv_123",
      "user_id": "alice",
      "agent_id": "agent_main",
      "title": "Project planning",
      "created_at": 1712500000,
      "last_updated_at": 1712500600
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0,
  "hasMore": false,
  "query": "planning"
}

Update conversation title

update-conversation.ts

// Request: rename an existing conversation.
const updated = await client.updateConversation("conv_123", {
  title: "Project planning (Q2)",
});

console.log(updated.conversation_id, updated.title);

update-conversation-response.json

{
  "conversation_id": "conv_123",
  "user_id": "alice",
  "agent_id": "agent_main",
  "title": "Project planning (Q2)",
  "created_at": 1712500000,
  "last_updated_at": 1712501200
}

Get conversation messages

get-conversation-messages.ts

// Request: fetch paginated messages for a single conversation.
const messagesPage = await client.getConversationMessages({
  conversationId: "conv_123",
  limit: 50,
  offset: 0,
});

console.log(messagesPage.total, messagesPage.hasMore);
console.log(messagesPage.messages[0]?.role, messagesPage.messages[0]?.original_content);

get-conversation-messages-response.json

{
  "conversation_id": "conv_123",
  "messages": [
    {
      "id": "msg_1",
      "conversation_id": "conv_123",
      "user_id": "alice",
      "role": "user",
      "original_content": "Start a plan for this week",
      "enhanced_message": "",
      "explicit_context": null,
      "timestamp": 1712500001,
      "invoked_flows": null,
      "invoked_tools": null,
      "errors": null,
      "is_flagged": false
    },
    {
      "id": "msg_2",
      "conversation_id": "conv_123",
      "user_id": "alice",
      "role": "assistant",
      "original_content": "Here is a focused weekly plan...",
      "enhanced_message": "",
      "explicit_context": null,
      "timestamp": 1712500003,
      "invoked_flows": ["weekly_planner"],
      "invoked_tools": ["calendar"],
      "errors": null,
      "is_flagged": false
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

Error handling

Errors thrown by the client are instances of JazzmineClientError.

errors.ts

class JazzmineClientError extends Error {
  status?: number;
  code?: string;
  details?: unknown;
}

status: HTTP status code when available.
code: Optional semantic code, for example stream error event codes.
details: Parsed response payload or low-level details when available.

Framework compatibility

@jazzmine-ui/sdk is framework-agnostic and can be used from React, Vue, Svelte, Next.js, and vanilla JavaScript/TypeScript apps.

Node.js note

Node.js 18+ includes fetch globally and works out of the box.
For Node.js versions below 18, provide fetchImpl (for example from undici or cross-fetch).

node-polyfill.ts

import JazzmineClient from "@jazzmine-ui/sdk";
import fetch from "cross-fetch";

const client = new JazzmineClient("https://your-jazzmine-api.example.com", {
  fetchImpl: fetch as unknown as typeof globalThis.fetch,
});

Client Reference