Node.js SDK

Install and create a client

Install @chadwin/sdk with npm, pnpm, or Bun:

npm install @chadwin/sdk
pnpm add @chadwin/sdk
bun add @chadwin/sdk

The SDK requires Node.js 22 or newer.

import { Chadwin } from "@chadwin/sdk";

const apiKey = process.env.CHADWIN_API_KEY;
if (!apiKey) throw new Error("CHADWIN_API_KEY is not set");

const client = new Chadwin({ apiKey });
const { company } = await client.companies.get({ ticker: "AAPL" });

console.log(company.name);

Responses and types

JSON responses keep the API's documented snake-case fields and envelopes. companyReports.getHtml returns the report body as a string rather than a JSON object.

Every request returns a native PromiseWithResponse<T>. Call .withResponse() on the same request when you also need the native Response. It resolves to an inline { data, response } object and does not make a second request.

const { data, response } = await client.companies
  .get({ ticker: "AAPL" })
  .withResponse();

const remaining = response.headers.get(
  "x-billing-period-quota-remaining",
);

Quota values remain in the native headers: x-billing-period-quota-limit, x-billing-period-quota-remaining, and x-billing-period-quota-reset.

The package exports Chadwin, ClientOptions, APIError, PromiseWithResponse<T>, the four feed filter types and their form or transaction-code unions, plus InstitutionalHolding, InstitutionalManager, and InstitutionalPosition. Other method inputs and results are available through TypeScript inference. Generated OpenAPI maps remain internal.

Errors and retries

Failed API requests throw APIError. Its optional status, code, and headers fields provide safe error context. Error objects exclude the API key, cookies, and response bodies.

import { APIError } from "@chadwin/sdk";

try {
  await client.companies.get({ ticker: "AAPL" });
} catch (error) {
  if (error instanceof APIError) {
    console.error(error.status, error.code);
  } else {
    throw error;
  }
}

Each attempt has an internal 30-second limit. The SDK retries a safe GET request at most twice after a network failure, timeout, rate-limit response, or HTTP 502, 503, or 504 response. It honors Retry-After, caps that delay at 30 seconds, and does not retry billing-period quota exhaustion or other permanent client errors. Retries can consume quota.

Pagination

list, listHoldings, and listPositions methods return one finite page and its next_cursor. Pass that cursor to the same method with the same filters when your application needs page-level control.

The four iterate helpers request each finite page and yield its items until no continuation cursor remains:

for await (const holding of client.institutionalFilings.iterateHoldings({
  accessionNumber: "0000320193-24-000123",
  limit: 500,
})) {
  await saveHolding(holding);
}

Feed cursors use customer-controlled processing and storage, so feed resources do not provide iterators.

Advanced configuration

ClientOptions requires apiKey. Its only optional field is baseURL, intended for local testing or another explicit deployment:

const apiKey = process.env.CHADWIN_API_KEY;
if (!apiKey) throw new Error("CHADWIN_API_KEY is not set");

const client = new Chadwin({
  apiKey,
  baseURL: "http://127.0.0.1:8787/api/",
});

The SDK preserves a path prefix in baseURL. It accepts only HTTP or HTTPS URLs and rejects credentials, query strings, and fragments. Timeout and retry settings are internal and cannot be overridden in the initial public interface.