CheckboxDocs
Tools

Node.js SDK

View as Markdown Open in Claude

The official TypeScript/JavaScript client — zero dependencies, typed responses, automatic retries and idempotency, auto-pagination and webhook verification. Node 20+, Bun, Deno and edge runtimes.

Install

Shell
npm install @checkbox-site/cli
Node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const account = await checkbox.account.retrieve();
console.log(checkbox.mode, account.activation.status);

new Checkbox() without an argument reads CHECKBOX_API_KEY. Options: apiVersion, baseUrl (or CHECKBOX_API_BASE), maxNetworkRetries (default 2), timeout (ms, default 80 000), fetch, appInfo, headers.

Methods

Every API operation is a method: checkbox.<resource>.<action>(). The API reference shows the method for each operation (createSite → checkbox.sites.create(), checkStripeCheckoutSession → checkbox.checks.stripeCheckoutSession()). Path parameters come first, then one params object (query and body together), then request options. Responses are typed objects generated from the OpenAPI document.

Agents and tools that work with operation ids can call any operation by name with flat arguments:

Node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const site = await checkbox.call('createSite', { url: 'https://joybox.example' });
const plan = await checkbox.call('retrieveCompliancePlan', { site: site.id });
console.log(plan.status, plan.next_action.type);

Pagination

list() returns one page when awaited, and walks every page with for await:

Node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const page = await checkbox.sites.list({ limit: 10 });
console.log(page.data.length, page.has_more);

for await (const finding of checkbox.findings.list({ status: 'fail', limit: 100 })) {
  console.log(finding.check_id, finding.severity);
}

Errors

Errors are typed (CheckboxInvalidRequestError, CheckboxAuthenticationError, CheckboxPermissionError, CheckboxRateLimitError, CheckboxIdempotencyError, CheckboxAPIError, CheckboxConnectionError) and carry the API's stable code, param, statusCode, requestId, docUrl and nextAction:

Node
import Checkbox, { CheckboxInvalidRequestError } from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

try {
  await checkbox.sites.retrieve('site_00000000000000000000000000000000');
} catch (err) {
  if (err instanceof CheckboxInvalidRequestError && err.code === 'resource_missing') {
    console.log('No such site:', err.docUrl);
  } else {
    throw err;
  }
}

Retries and idempotency

Network errors, 429 and 5xx responses are retried with exponential backoff. Every POST is sent with an Idempotency-Key (generated and reused across retries), so a retried create never creates twice. Pass your own to make a create idempotent across processes:

Node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const site = await checkbox.sites.create(
  { url: 'https://joybox.example' },
  { idempotencyKey: 'site-joybox-example' },
);
console.log(site.id);

Webhooks

Verify Checkbox-Signature with the raw request body and the endpoint's secret. constructEvent throws CheckboxSignatureVerificationError when the signature is wrong or older than 5 minutes. (constructEventAsync uses WebCrypto for edge runtimes.)

Node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);
const secret = 'whsec_test_secret';

// In a test: build a signed delivery the way Checkbox does.
const payload = JSON.stringify({ id: 'evt_123', object: 'event', type: 'site.compliant', data: { object: { id: 'site_123' } } });
const header = checkbox.webhooks.generateTestHeaderString({ payload, secret });

const event = checkbox.webhooks.constructEvent(payload, header, secret);
console.log(event.type);

See Webhooks for a complete handler.

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.