# Zavu SDKs Overview

> The official Zavu SDK for TypeScript and the REST API it wraps. Send SMS, WhatsApp, Email and Voice messages with one typed client, or call the API directly from any language.

> **Warning:**
> **Server-side only** — the SDK is designed for server-side environments (Node.js, Bun, Deno, serverless functions). Never use it in browser/frontend code as this exposes your API key. See [Frontend Integration](https://www.zavu.dev/docs/authentication#frontend-integration) for the proxy pattern.

Zavu ships one official SDK, for TypeScript. It is generated from the same OpenAPI spec as the [API reference](https://www.zavu.dev/docs/api-reference), covers every v1 endpoint, and exposes API v2 as `client.v2`.

From any other language, call the REST API directly: every endpoint is plain JSON over HTTPS with a Bearer token, and each reference page shows the request as `cURL`.

## Available tools

  - [TypeScript SDK](https://www.zavu.dev/docs/sdks/typescript/overview): `@zavudev/sdk` for Node.js, Bun and Deno
  - [REST API](https://www.zavu.dev/docs/api-reference): Any language with an HTTP client
  - [CLI](https://www.zavu.dev/docs/guides/functions/cli): Command-line interface for Zavu

| | TypeScript SDK | REST API |
|---|---|---|
| Package | `@zavudev/sdk` | `https://api.zavu.dev` |
| Runtime | Node 20+, Bun 1.0+, Deno 1.28+, edge runtimes | Any |
| Types | Full TypeScript | [OpenAPI spec](https://www.zavu.dev/docs/openapi.json) |
| Coverage | Every v1 endpoint, plus v2 as `client.v2` | Every endpoint |

## Installation

```bash
npm add @zavudev/sdk
# or: bun add @zavudev/sdk
```

```bash
npx zavudev@latest --version
# or install it globally: npm install -g zavudev
# or grab a standalone binary from
# https://github.com/zavudev/zavu-cli/releases
```

## Basic Usage

```typescript
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev(); // reads ZAVUDEV_API_KEY

const result = await zavu.messages.send({
  to: '+14155551234',
  text: 'Hello from Zavu!',
});

console.log('Message ID:', result.message.id);
```

```bash
zavudev messages send --to "+14155551234" --text "Hello from Zavu!"
```

## Common Operations

### Send a Message

```typescript
const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Your code is 123456",
  channel: "sms",
});
```

```bash
zavudev messages send --to "+14155551234" --text "Your code is 123456" --channel sms
```

### Send with Template

```typescript
const result = await zavu.messages.send({
  to: "+14155551234",
  messageType: "template",
  content: {
    templateId: "tpl_abc123",
    templateVariables: {
      "1": "John",
      "2": "12345",
    },
  },
});
```

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "text": "Hello from Zavu!"}'
```

```bash
zavudev messages get msg_abc123
```

### List Messages

```typescript
const result = await zavu.messages.list({
  status: "delivered",
  limit: 50,
});

for (const message of result.items) {
  console.log(message.id);
}
```

```bash
zavudev messages list --status delivered --limit 50
```

## Error Handling

```typescript
import Zavudev, { APIError } from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env["ZAVUDEV_API_KEY"],
});

try {
  await zavu.messages.send({ to: "invalid", text: "Hello" });
} catch (error) {
  if (error instanceof APIError) {
    console.error("API Error:", error.status, error.message);
  }
}
```

Most errors come back as `{ "code", "message", "details" }` with a meaningful HTTP status. A few on `POST /v1/messages` (the monthly message and email allowances, and the per-recipient SMS rate limit) arrive nested as `{ "error": { "code", "message", "details" } }`. Read the reason as `body.code ?? body.error?.code` and one handler covers both.

### Generate a client from the OpenAPI spec

The specs are public and are the source the TypeScript SDK is generated from:

- API v1: [`https://docs.zavu.dev/openapi.json`](https://www.zavu.dev/docs/openapi.json)
- API v2: [`https://docs.zavu.dev/api-reference/v2/openapi.json`](https://www.zavu.dev/docs/api-reference/v2/openapi.json)

Point any OpenAPI 3 generator at them (for example `openapi-generator` for Python, Go, Java or PHP) to get a typed client for your language. Regenerate when the spec changes.

## Other tools

  - [CLI](https://www.zavu.dev/docs/guides/cli/overview): Command-line access to the API.
  - [Coding agent skills](https://www.zavu.dev/docs/tools/coding-agent-skills): Teach your coding agent how to call Zavu.