higherdata-sdk 0.2.0

package/LICENSE

@@ -0,0 +1 @@
+Copyright HigherOps Inc. You may install and use this software with a HigherData account. You may not redistribute modified copies.

package/README.md

@@ -0,0 +1,89 @@
+# HigherData SDK
+
+Node 24+ TypeScript client for HigherData. Install with:
+
+```sh
+npm install higherdata-sdk
+```
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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.