Skip to main content

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.

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 for the proxy pattern.
The official Zavu SDK for TypeScript provides a type-safe way to interact with the Zavu API.

​
Installation

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

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

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: 
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): 
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

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 CodeDescription
400Invalid request parameters
401Invalid or missing API key
403Insufficient permissions
404Resource not found
429Rate limit exceeded

​
Retries

The SDK supports automatic retries with configurable backoff: 
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: 
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

const Zavudev = require("@zavudev/sdk").default;

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