HigherData SDK

Node 24+ TypeScript client for HigherData. Install with:

npm install higherdata-sdk

import { HigherData, HigherDataError } from "higherdata-sdk";

const client = new HigherData({
  apiKey: process.env.HIGHERDATA_API_KEY,
  space: "default",
});
const companies = await client.call("search.companies", {
  countryCodes: ["CA"], limit: 25,
});
const preview = await client.call("enrich.company", {
  domain: "cedar.example",
}, { execute: false });

Every registered tool name, input and output is generated from the registry's OpenAPI document using pinned openapi-typescript 7.13.0. ToolName, ToolInput<Name>, ToolOutput<Name>, operations, and components are exported. The small shared transport is handwritten. The server validates inputs, authorization and scope; a client cannot choose a tenant. execute: false sets the API dry-run flag. API-key and space headers stay on the configured origin; redirects are refused. HTTPS is required except HTTP loopback for tests.

Errors and retries

try {
  await client.call("account.whoami", {});
} catch (error) {
  if (error instanceof HigherDataError) {
    console.log(error.code, error.status, error.retryAfter);
  }
}

API errors retain the API's code, HTTP status and public message. Transport failures use status 0 with codes such as network_error, invalid_response, response_too_large and request_aborted; transport details are not exposed. Only HTTP 429 and 503 are retried, twice by default. Retry-After seconds or HTTP dates take precedence over the error body's retry_after; absent either, waits are one then two seconds. A requested wait above maxRetryDelayMs (default 30 seconds) returns the error to the caller rather than retrying early. Network errors and other statuses are never retried. Set maxRetries: 0 to turn retries off. The CLI uses that setting to preserve its existing behavior.

Each tool call has one idempotency key reused across its retries. Supply idempotencyKey in call options to retain a key across your own attempts. The server returns only a receipt for a replayed write; the SDK throws HigherDataReplayError with requestId instead of returning a value with the wrong tool output type. Read replays still return the normal result.

Requests have a 30-second timeout per attempt and an 8 MiB response bound. timeoutMs and an AbortSignal may be supplied in call options. Constructor options include apiUrl, fetch, maxRetries (0 to 5), maxRetryDelayMs, timeoutMs, sleep, and now for deterministic tests.

Streaming downloads

for await (const content of client.downloadJob({ jobId, format: "csv" })) {
  await destination.write(content);
}

The API returns bounded JSON pages; the helper yields content one page at a time and fetches the next page only when the consumer asks. It retains the CSV header from the first page, follows cursors and stops repeated cursors. Breaking out of the loop stops fetching. downloadJobPages also yields each page's content type, next cursor and suppression count. Every page goes through the authenticated job tool, so current suppression applies. Results may change between pages when suppression changes. Pass a cursor to resume a paged download.

Development

From the repository root, npm run sdk:generate regenerates the checked-in contract and npm run sdk:check fails if it is stale. The SDK build regenerates it; CI checks for drift before any build can overwrite it. Generation imports server tool definitions under the react-server condition but never invokes tools or uses hosted credentials. None of the server implementation is bundled. The SDK and CLI publish together through publish-cli.yml; see docs/RELEASE-CLI.md for the release procedure and unresolved B16 prerequisites.