TypeScript SDK Overview

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

Installation

terminal
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
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
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
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
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
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
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
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
const Zavudev = require("@zavudev/sdk").default;

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