> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Official Zavu SDK for Node.js and TypeScript

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

The official Zavu SDK for TypeScript provides a type-safe way to interact with the Zavu API.

## Installation

```bash theme={null}
npm add @zavudev/sdk
# or
bun add @zavudev/sdk
# or
yarn add @zavudev/sdk
```

## Requirements

* Node.js 18 or higher
* TypeScript 4.7+ (optional, for type definitions)

## Quick Start

```typescript theme={null}
import Zavudev from '@zavudev/sdk';

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

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

console.log("Message sent:", result.message.id);
```

## Configuration

### Initialize the Client

```typescript theme={null}
import Zavudev from '@zavudev/sdk';

// Basic initialization
const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'],
});

// With custom base URL
const zavu = new Zavudev({
  apiKey: "zv_live_xxx",
  baseURL: "https://api.zavu.dev",
});
```

### Environment Variables

We recommend storing your API key in environment variables:

```typescript theme={null}
const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'],
});
```

## Accessing Response Headers

Use `.withResponse()` to access the full HTTP response including headers (useful for rate limiting):

```typescript theme={null}
const { response, result } = await zavu.messages.send.withResponse({
  to: "+14155551234",
  text: "Hello!",
});

const remaining = response.headers.get("X-RateLimit-Remaining");
console.log(`Remaining requests: ${remaining}`);

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

## Error Handling

```typescript theme={null}
import Zavudev, { ZavudevError, APIError } from '@zavudev/sdk';

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

try {
  await zavu.messages.send({
    to: "invalid-number",
    text: "Hello",
  });
} catch (error) {
  if (error instanceof APIError) {
    console.error("Status:", error.status);
    console.error("Message:", error.message);
  } else if (error instanceof ZavudevError) {
    console.error("Error:", error.message);
  } else {
    throw error;
  }
}
```

### Error Types

| Error Code | Description                |
| ---------- | -------------------------- |
| `400`      | Invalid request parameters |
| `401`      | Invalid or missing API key |
| `403`      | Insufficient permissions   |
| `404`      | Resource not found         |
| `429`      | Rate limit exceeded        |

## Retries

The SDK supports automatic retries with configurable backoff:

```typescript theme={null}
const result = await zavu.messages.send(
  {
    to: "+14155551234",
    text: "Hello!",
  },
  {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  }
);
```

## TypeScript Support

The SDK includes full TypeScript definitions:

```typescript theme={null}
import Zavudev from '@zavudev/sdk';
import type { MessageSendParams } from '@zavudev/sdk/resources/messages';

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

const request: MessageSendParams = {
  to: "+14155551234",
  text: "Hello!",
};

const result = await zavu.messages.send(request);
```

## CommonJS Support

```javascript theme={null}
const Zavudev = require("@zavudev/sdk").default;

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