# Hanzo JavaScript SDK - TypeScript Client Library

**Category**: Hanzo Ecosystem
**Related Skills**: `hanzo/hanzo-chat.md`, `hanzo/python-sdk.md`, `hanzo/go-sdk.md`

## Overview

Hanzo JS SDK is a **TypeScript-first client library** for the Hanzo AI API. Generated from our OpenAPI spec for complete type safety and API coverage. Works in Node.js, Bun, Deno, and browsers with tree-shaking support.

### Why Hanzo JS SDK?

- **Full type safety**: Generated from our OpenAPI spec
- **OpenAI compatible**: Same interface patterns, easy migration
- **Universal JS**: Node.js, Bun, Deno, and browser support
- **Streaming**: First-class SSE streaming with async iterators
- **Tree-shakable**: Only import what you need
- **Auto-retry**: Configurable retry with exponential backoff
- **Pagination**: Auto-pagination helpers for list endpoints

### OSS Base

Generated by **openapi-generator**. Repo: `hanzoai/js-sdk`.

## When to use

- TypeScript/JavaScript applications calling Hanzo API
- Next.js, React, Vue, or Node.js projects
- Browser-based AI applications
- Replacing OpenAI SDK with Hanzo
- Server-side API integration

## Hard requirements

1. **Node.js 18+** (or Bun/Deno)
2. **HANZO_API_KEY** for authentication
3. TypeScript 4.7+ recommended

## Quick reference

| Item | Value |
|------|-------|
| Package | `hanzoai` (npm) |
| Version | 0.1.0-alpha.2 |
| Repo | `github.com/hanzoai/js-sdk` |
| Generated by | openapi-generator |
| License | Apache-2.0 |
| Node.js | 18+ |
| TypeScript | 4.7+ |
| Base URL | `https://api.hanzo.ai` |

## Installation

```bash
# npm
npm install hanzoai

# pnpm (preferred)
pnpm add hanzoai

# yarn
yarn add hanzoai

# bun
bun add hanzoai
```

## One-file quickstart

### Chat Completion

```typescript
import Hanzo from "hanzoai"

const client = new Hanzo({
 apiKey: process.env.HANZO_API_KEY, // defaults to HANZO_API_KEY env var
 // baseURL: "https://api.hanzo.ai", // default
})

const response = await client.chat.completions.create({
 model: "zen-70b",
 messages: [{ role: "user", content: "Hello, Hanzo!" }],
})
console.log(response.choices[0].message.content)
```

### Streaming

```typescript
const stream = await client.chat.completions.create({
 model: "zen-70b",
 messages: [{ role: "user", content: "Write a poem about code" }],
 stream: true,
})

for await (const chunk of stream) {
 const content = chunk.choices[0]?.delta?.content
 if (content) process.stdout.write(content)
}
```

### Embeddings

```typescript
const embedding = await client.embeddings.create({
 model: "zen-embedding",
 input: "Hello world",
})
console.log(embedding.data[0].embedding.length) // dimension count
```

### Function Calling / Tools

```typescript
const response = await client.chat.completions.create({
 model: "zen-70b",
 messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
 tools: [{
 type: "function",
 function: {
 name: "get_weather",
 description: "Get current weather for a location",
 parameters: {
 type: "object",
 properties: {
 location: { type: "string", description: "City name" },
 },
 required: ["location"],
 },
 },
 }],
})

const toolCall = response.choices[0].message.tool_calls?.[0]
if (toolCall) {
 console.log(toolCall.function.name) // "get_weather"
 console.log(toolCall.function.arguments) // '{"location":"Tokyo"}'
}
```

### Vision (Multimodal)

```typescript
const response = await client.chat.completions.create({
 model: "zen-vision",
 messages: [{
 role: "user",
 content: [
 { type: "text", text: "What's in this image?" },
 { type: "image_url", image_url: { url: "https://example.com/photo.jpg" } },
 ],
 }],
})
```

## API Surface

The SDK provides **187 endpoints** across **51 resource namespaces**, generated from our OpenAPI spec.

### Core Resources

| Resource | Method | Description |
|----------|--------|-------------|
| `client.chat.completions.create()` | POST | Chat completion (streaming optional) |
| `client.completions.create()` | POST | Text completion (legacy) |
| `client.embeddings.create()` | POST | Generate embeddings |
| `client.models.list()` | GET | List available models |
| `client.models.retrieve(id)` | GET | Get model details |

### File Management

| Method | Description |
|--------|-------------|
| `client.files.create()` | Upload a file |
| `client.files.retrieve(id)` | Get file metadata |
| `client.files.list()` | List uploaded files |
| `client.files.del(id)` | Delete a file |
| `client.files.content(id)` | Get file content |

### Fine-Tuning

| Method | Description |
|--------|-------------|
| `client.fineTuning.jobs.create()` | Create fine-tuning job |
| `client.fineTuning.jobs.retrieve(id)` | Get job status |
| `client.fineTuning.jobs.list()` | List all jobs |
| `client.fineTuning.jobs.cancel(id)` | Cancel a job |
| `client.fineTuning.jobs.listEvents(id)` | List job events |

### Images

| Method | Description |
|--------|-------------|
| `client.images.generate()` | Generate images |
| `client.images.edit()` | Edit images |

### Audio

| Method | Description |
|--------|-------------|
| `client.audio.transcriptions.create()` | Speech-to-text |
| `client.audio.translations.create()` | Audio translation |
| `client.audio.speech.create()` | Text-to-speech |

### Additional Resource Namespaces

The SDK also includes namespaces for: assistants, threads, runs, batches, vector stores, model management, key management, team management, organization, budget, guardrails, credentials, and more (51 total).

## Configuration

```typescript
const client = new Hanzo({
 apiKey: "your-key", // Required (or HANZO_API_KEY env)
 baseURL: "https://api.hanzo.ai", // Default
 timeout: 60_000, // Request timeout (ms)
 maxRetries: 2, // Auto-retry count
 defaultHeaders: { "X-Custom": "val" }, // Extra headers
 defaultQuery: { version: "2" }, // Extra query params
})
```

### Environment Variables

```bash
HANZO_API_KEY=your-api-key # Required
HANZO_BASE_URL=https://... # Override base URL
HANZO_LOG=debug # Enable debug logging
```

### Auth Header

The gateway accepts the API key via:
- `x-litellm-api-key: <key>` (used by the SDK internally)

### Sandbox Environment

```typescript
// Use sandbox for testing
const client = new Hanzo({
 apiKey: process.env.HANZO_SANDBOX_KEY,
 baseURL: "https://api.sandbox.hanzo.ai",
})
```

## OpenAI Drop-In Replacement

```typescript
import OpenAI from "openai"

const client = new OpenAI({
 baseURL: "https://api.hanzo.ai/v1",
 apiKey: process.env.HANZO_API_KEY,
})
// Everything works — same API shape
const response = await client.chat.completions.create({
 model: "zen-70b",
 messages: [{ role: "user", content: "Hello" }],
})
```

## Framework Integration

### Next.js (App Router)

```typescript
// app/api/chat/route.ts
import Hanzo from "hanzoai"

const client = new Hanzo()

export async function POST(req: Request) {
 const { messages } = await req.json()

 const stream = await client.chat.completions.create({
 model: "zen-70b",
 messages,
 stream: true,
 })

 return new Response(stream.toReadableStream(), {
 headers: { "Content-Type": "text/event-stream" },
 })
}
```

### Vercel AI SDK

```typescript
import { createOpenAI } from "@ai-sdk/openai"
import { streamText } from "ai"

const hanzo = createOpenAI({
 baseURL: "https://api.hanzo.ai/v1",
 apiKey: process.env.HANZO_API_KEY,
})

const result = await streamText({
 model: hanzo("zen-70b"),
 prompt: "Write a haiku",
})
```

## Error Handling

```typescript
import Hanzo, { APIError, RateLimitError } from "hanzoai"

try {
 const response = await client.chat.completions.create({ ... })
} catch (err) {
 if (err instanceof RateLimitError) {
 console.log("Rate limited, retry after:", err.headers?.["retry-after"])
 } else if (err instanceof APIError) {
 console.log("API error:", err.status, err.message)
 }
}
```

## Pagination

```typescript
// Auto-pagination
for await (const model of client.models.list()) {
 console.log(model.id)
}

// Manual pagination
const page = await client.models.list()
console.log(page.data)
if (page.hasNextPage()) {
 const next = await page.getNextPage()
}
```

## Runtime Support

| Runtime | Support | Notes |
|---------|---------|-------|
| Node.js 18+ | Full | Primary target |
| Bun | Full | Native fetch |
| Deno | Full | npm: specifier |
| Browser | Full | Tree-shakable |
| Edge Runtime | Full | Cloudflare Workers, Vercel Edge |

## Related Skills

- `hanzo/hanzo-chat.md` - API reference and model catalog
- `hanzo/python-sdk.md` - Python equivalent
- `hanzo/go-sdk.md` - Go equivalent
- `hanzo/rust-sdk.md` - Rust equivalent (infrastructure SDK)

---

**Last Updated**: 2026-03-13
**Category**: Hanzo Ecosystem
**Related**: sdk, typescript, javascript, client
**Prerequisites**: TypeScript/JavaScript, Node.js