npm package: @jazzmine-ui/sdk
Description: Framework-agnostic TypeScript client for Jazzmine agentic backends
Latest version: 0.1.5

# @jazzmine-ui/sdk

Framework-agnostic TypeScript client for Jazzmine agentic backends.

## Install

```bash
npm install @jazzmine-ui/sdk
```

## Quick Start

### 1) Basic chat

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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`.

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