@jazzmine-ui/sdk

Framework-agnostic TypeScript client for Jazzmine agentic backends.

Install

npm install @jazzmine-ui/sdk

Quick Start

1) Basic chat

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

const client = new JazzmineClient("https://your-jazzmine-api.example.com", {
  apiKey: "your-api-key",
});

const reply = await client.chat({ message: "Summarize this dataset." });
console.log(reply.response);

2) Streaming chat

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

const client = new JazzmineClient("https://your-jazzmine-api.example.com");

const final = await client.chatStream(
  { message: "Plan a 5-day trip to Tokyo." },
  {
    onIntermediate: (event) => {
      console.log("intermediate", event);
    },
    onDone: (response) => {
      console.log("done", response.response);
    },
    onErrorEvent: (event) => {
      console.error("stream error event", event);
    },
  },
);

console.log(final.conversation_id);

3) Convenience sendMessage flow

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

const client = new JazzmineClient("https://your-jazzmine-api.example.com", {
  defaultUserId: "alice",
});

const { response, conversationId } = await client.sendMessage("Start a new thread", {
  autoCreateConversation: true,
  conversationTitle: "Project planning",
});

console.log(conversationId, response.response);

Constructor

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

Constructor options

| Option | Type | Default | Description | | --- | --- | --- | --- | | apiKey | string | undefined | Bearer token added as Authorization: Bearer <apiKey>. | | timeoutMs | number | 20000 | 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

getHealth(requestOptions?: RequestOptions): Promise<HealthResponse>
getInfo(requestOptions?: RequestOptions): Promise<InfoResponse>
createConversation(payload?: ConversationCreateRequest, requestOptions?: RequestOptions): Promise<ConversationCreateResponse>
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;
}>

Error Handling

Errors thrown by the client are instances of JazzmineClientError.

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 a fetch implementation via fetchImpl (for example from undici or cross-fetch).