3. Set your Recurly private API key as an environment variable:

RECURLY_API_KEY=your_private_key_here

4. Instantiate the client once at application startup and reuse it:

import { Client } from 'recurly';
const client = new Client(process.env.RECURLY_API_KEY!);

5. TypeScript users: ensure recurly.d.ts is included in compilation. If using the path alias above it will be picked up automatically. Otherwise add it to include in tsconfig.json.

Public API

Client

import { Client } from 'recurly';
const client = new Client(apiKey: string);

// Representative methods (see recurly.d.ts for the full surface):
client.getAccount(accountId: string): Promise<Account>
client.createAccount(body: AccountCreate): Promise<Account>
client.listAccounts(params?: object): Pager<Account>
client.createSubscription(body: SubscriptionCreate): Promise<Subscription>
client.getInvoice(invoiceId: string): Promise<Invoice>

Client is the single entry point for all API calls. Instantiate it with your private API key and call the relevant method for each operation. Every method returns a Promise resolving to a typed resource or throws an ApiError subclass on failure.

ApiError

import { ApiError } from 'recurly';

try {
  await client.getAccount('code-missing');
} catch (err) {
  if (err instanceof ApiError) {
    console.log(err.message);   // human-readable message
    console.log(err.type);      // e.g. "not_found"
    console.log(err.params);    // field-level validation errors
  }
}

ApiError and its subclasses (exported from recurly/api_errors.js) represent every error the API can return. Use instanceof checks against specific subclasses (e.g. errors.NotFoundError, errors.ValidationError) for fine-grained error handling.

Pager

import { Client } from 'recurly';
const client = new Client(process.env.RECURLY_API_KEY!);
const pager = client.listAccounts({ limit: 200 });

for await (const account of pager.each()) {
  console.log(account.code);
}

// Or fetch one page at a time:
const firstPage = await pager.first();

Pager wraps paginated list endpoints and exposes an async iterator via .each(). It handles cursor-based pagination automatically, making it safe to iterate arbitrarily large collections without manually managing page tokens.

Working examples

Scenario - Create a new account and attach billing info

Creates a Recurly account for a new user, then stores a tokenized payment method (token obtained client-side via RecurlyJS).

import { Client, ApiError } from './src/vendor/recurly/recurly.js';

const client = new Client(process.env.RECURLY_API_KEY!);

async function provisionUser(email: string, recurlyJsToken: string) {
  const account = await client.createAccount({
    code: `user-${Date.now()}`,
    email,
    billingInfo: { tokenId: recurlyJsToken },
  });

  console.log('Created account:', account.id, account.code);
  return account;
}

provisionUser('buyer@example.com', 'tok_abc123').catch((err) => {
  if (err instanceof ApiError) {
    console.error('Recurly error:', err.type, err.message);
  }
});

Scenario - Create a subscription

Signs an existing account up for a plan.

import { Client } from './src/vendor/recurly/recurly.js';

const client = new Client(process.env.RECURLY_API_KEY!);

async function subscribe(accountCode: string, planCode: string, currency = 'USD') {
  const subscription = await client.createSubscription({
    planCode,
    currency,
    account: { code: accountCode },
  });

  console.log('Subscription id:', subscription.id);
  console.log('State:', subscription.state);
  console.log('Next billing:', subscription.currentPeriodEndsAt);
  return subscription;
}

subscribe('user-123', 'basic-monthly');

Scenario - List and process open invoices with pagination

Iterates all open invoices across the site using the async Pager iterator.

import { Client, ApiError } from './src/vendor/recurly/recurly.js';

const client = new Client(process.env.RECURLY_API_KEY!);

async function auditOpenInvoices() {
  const pager = client.listInvoices({ state: 'open', limit: 200 });
  let count = 0;

  for await (const invoice of pager.each()) {
    count++;
    console.log(`${invoice.number} | ${invoice.currency} ${invoice.total} | due: ${invoice.dueAt}`);
  }

  console.log(`Total open invoices: ${count}`);
}

auditOpenInvoices().catch((err) => {
  if (err instanceof ApiError) {
    console.error(err.type, err.message);
  }
});

File walkthrough

• recurly.js - Package entry point; aggregates Client, ApiError, Schema, and all resource constructors into one export object.
• recurly.d.ts - Hand-maintained TypeScript declarations covering every resource class, request body interface, and Client method signature.
• recurly/Client.js - Auto-generated concrete client subclass; contains one method per API endpoint with correct path, HTTP verb, and response type.
• recurly/BaseClient.js - Request construction, authentication header injection, response parsing, and retry handling shared across all client instances.
• recurly/ApiError.js - Base error class; parses Recurly error envelopes into type, message, and params properties.
• recurly/api_errors.js - Specific ApiError subclasses (e.g. NotFoundError, ValidationError, InternalServerError) for instanceof branching.
• recurly/Caster.js - Maps raw API JSON to typed resource instances using the schema registry.
• recurly/Resource.js - Minimal base class all resource objects extend; provides getResponse() for raw HTTP metadata.
• recurly/Pager.js - Cursor-based pagination driver exposing .each() async iterator and .first() convenience.
• recurly/Page.js - Value object for a single page of results plus cursor state.
• recurly/Http.js - Thin wrapper over Node.js https for making raw requests.
• recurly/schemas.js - Schema registry and Schema class used by Caster to resolve resource types by name.
• recurly/utils.js - Utilities for building query strings and coercing date strings to Date objects.
• recurly/resources/ - One module per Recurly domain object (Account, Invoice, Subscription, etc.), each exporting a class extending Resource.

Common pitfalls and fixes

• API key leaked into client-side bundles: The private API key must never be used in browser code; instantiate Client only in server-side modules and gate it behind environment variables.
• Paginator not consumed: Calling client.listAccounts() returns a Pager synchronously; no HTTP request is made until you call .each(), .first(), or .eachPage().
• Date fields are Date objects, not strings: Caster converts ISO strings to Date instances; comparing them to raw strings will always be false.
• ApiError subclass not matched: Import specific error subclasses from recurly/api_errors.js (e.g. errors.NotFoundError); checking err.type === 'not_found' on the base class is an alternative if you do not want to import subclasses.
• TypeScript path alias not resolving .d.ts: Ensure moduleResolution is set to "node" or "bundler" in tsconfig.json; "classic" will not resolve the declaration file next to recurly.js.
• Zero-dependency assumption: This library uses no third-party npm packages; do not attempt to tree-shake or externalize sub-paths like axios or node-fetch - all HTTP is handled by Node's built-in https module.

Vibe-coding prompt template

I have the Recurly Node.js client library source code in `source/lib/` and a
usage guide at `source/USAGE.md`. The upstream package is `user@example.com`.

Please integrate this library into my project step by step:

1. Read `source/USAGE.md` for setup instructions, public API, and examples.
2. Copy `source/lib/` to the appropriate location in my project (ask me where
   if unsure).
3. Add a `Client` instantiation module that reads `RECURLY_API_KEY` from
   environment variables and exports a singleton client.
4. Implement the following feature using the real exports from `source/lib/recurly.js`:
   [DESCRIBE YOUR FEATURE HERE - e.g. "create a subscription when a user
   completes checkout and store the subscription ID in my database"]
5. Add error handling using `ApiError` and its subclasses from
   `source/lib/recurly/api_errors.js`.
6. If the feature involves listing resources, use the `Pager` async iterator.
7. Show me the final TypeScript code and any environment variable additions
   needed.

License and credit

The upstream license is MIT; see source/LICENSE if present in the distributed package. Source: recurly on npm (version 4.74.0), maintained by Recurly, Inc. Full API documentation at https://developers.recurly.com/api/v2019-10-10/.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.