> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://virtuous.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://virtuous.ferndocs.com/_mcp/server.

# TypeScript SDK

## Installation

```bash
npm install @virtuous/sdk
```

## Usage

```typescript
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:

```typescript
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:

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

## Error handling

```typescript
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:

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

## GitHub repository

View the source and contribute: [virtuous-ts-sdk](https://github.com/fern-demo/virtuous-ts-sdk)