Node.js SDK

The official Node.js SDK for the CaviusConnect API.

Status: v0.1.0 (pre-release). The public API may change before 1.0.

Install

npm install @cavius/sdk

Requires Node.js 18+ (uses native fetch).

Quickstart

import { Cavius } from "@cavius/sdk";

const client = new Cavius({
  apiKey: process.env.CAVIUS_API_KEY!,
  // Optional; defaults to https://core.caviusconnect.com
  baseUrl: process.env.CAVIUS_BASE_URL,
});

// List contacts
const page = await client.contacts.list({ pageSize: 50 });
console.log(`Got ${page.content.length} contacts`);

// Send an SMS
await client.messages.send({
  to: "+15555550100",
  channel: "SMS",
  body: "Hello from Cavius!",
});

// Subscribe to webhooks
const sub = await client.webhooks.subscriptions.create({
  url: "https://your.app/cavius-webhook",
  eventTypes: ["message.delivered", "message.failed"],
});
console.log("Save this secret somewhere safe:", sub.signingSecret);

Resources

Resource	Endpoints	Notes
`contacts`	`/api/contacts/`, `/api/v1/contacts/imports/`	CRUD + import + activity
`messages`	`/api/messages/*`	send, threads, SSE stream, media upload
`campaigns`	`/api/campaigns/*`	CRUD + launch / cancel / reschedule + stats
`forms`	`/api/v1/forms/*`	CRUD + submissions
`webhooks`	`/api/v1/webhooks/subscriptions/`, `…/deliveries/`	split into `.subscriptions` and `.deliveries`
`apiKeys`	`/api/v1/api-keys/*`	create / revoke / whoami
`verify`	`/api/v1/verify/*`	OTP start + check
`macros`	`/api/v1/macros/*`	CRUD + preview
`notes`	`/api/v1/conversations/{cid}/notes/*`	conversation-scoped notes
`segments`	`/api/v1/segments/*`	CRUD + materialize + list contacts
`brandKit`	`/api/v1/brand-kit/*`	singleton-per-org + logo upload URL
`workflows`	`/api/workflows/*`	CRUD

Error handling

All API failures throw a subclass of CaviusError:

import {
  CaviusError,
  CaviusAuthError,
  CaviusNotFoundError,
  CaviusValidationError,
  CaviusRateLimitError,
} from "@cavius/sdk";

try {
  await client.contacts.get(id);
} catch (e) {
  if (e instanceof CaviusNotFoundError) {
    /* 404: not found */
  } else if (e instanceof CaviusValidationError) {
    console.error(e.fieldErrors); // [{ field, message }, ...]
  } else if (e instanceof CaviusRateLimitError) {
    console.warn(`rate-limited; retry after ${e.retryAfterSeconds}s`);
  } else if (e instanceof CaviusAuthError) {
    /* 401: bad/missing API key */
  } else if (e instanceof CaviusError) {
    /* generic API error: e.status, e.body, e.requestId */
  }
}

Status-to-class map:

HTTP	Class
400/422	`CaviusValidationError`
401	`CaviusAuthError`
403	`CaviusForbiddenError`
404	`CaviusNotFoundError`
409	`CaviusConflictError`
429	`CaviusRateLimitError`
5xx	`CaviusServerError`
network	`CaviusNetworkError`
other	`CaviusError`

Retries

Built-in retries with exponential backoff + jitter on:

5xx server errors
429 rate-limit responses (honors Retry-After if present, capped at 30s)
network errors

Default: 3 retry attempts, base delay 250ms, capped at 8s per attempt. Configure via maxRetries / retryBaseDelayMs / timeoutMs, or disable per-request with noRetry: true.

Configuration

new Cavius({
  apiKey: "ck_live_...",
  baseUrl: "https://core.caviusconnect.com", // default
  timeoutMs: 30_000,                          // per-request timeout
  maxRetries: 3,                              // retries on 5xx/429/network
  retryBaseDelayMs: 250,                      // exponential backoff base
  userAgent: "my-app/1.0",                    // optional UA suffix
  defaultHeaders: { "X-My-Header": "foo" },
  fetch: customFetch,                         // injectable fetch impl
});