Skip to navigation
SDKs

TypeScript SDK

Installation

npm install @virtuous/sdk

Usage

import { Virtuous } from "@virtuous/sdk";
const client = new Virtuous({
  token: "YOUR_API_KEY",
});
// List contacts with auto-pagination
const contacts = await client.contactsAndIndividuals.searchContacts({
  search: "John",
  skip: 0,
  take: 25,
});
for await (const contact of contacts) {
  console.log(contact);
}
// Get a specific contact
const contact = await client.contactsAndIndividuals.getAContact("12345");

Auto-pagination

All list endpoints support auto-pagination. The SDK handles skip/take parameters automatically:

const allGifts = await client.giving.queryGifts({
  groups: [{ columnName: "Amount", operator: "GreaterThan", value: "100" }],
});
for await (const gift of allGifts) {
  console.log(gift);
}

Retries

The SDK automatically retries failed requests with exponential backoff. You can configure retry behavior:

const client = new Virtuous({
  token: "YOUR_API_KEY",
  maxRetries: 5,
});

Error handling

import { VirtuousError } from "@virtuous/sdk";
try {
  const contact = await client.contactsAndIndividuals.getAContact("invalid-id");
} catch (error) {
  if (error instanceof VirtuousError) {
    console.log(error.statusCode);
    console.log(error.message);
  }
}

Extensibility

The SDK supports custom fetch implementations for advanced use cases:

const client = new Virtuous({
  token: "YOUR_API_KEY",
  fetcher: myCustomFetcher,
});

GitHub repository

View the source and contribute: virtuous-ts-sdk