TypeScript SDK

The TypeScript SDK is the definite-ts package on npm (Node 20+, zero runtime dependencies, ESM and CommonJS). It wraps the Vault REST API: readiness, report programs, runs, exceptions, and receipts.

npm install definite-ts

Create a client

import { DefiniteClient } from "definite-ts";
 
const client = new DefiniteClient({
  vaultUrl: "https://vault.example.com",
  vaultApiKey: process.env.DEFINITE_VAULT_API_KEY,
});

createVaultConfig() builds the same configuration from the environment:

Field	Type	Required	Description
DEFINITE_VAULT_URL	string	Yes	Vault base URL.
DEFINITE_VAULT_API_KEY	string	Direct mode	Tenant API key, sent as X-Vault-API-Key.
DEFINITE_VAULT_AUTH_MODE	direct \| proxy	No	Default direct. Proxy mode sends X-Vault-Proxy-API-Key and prefixes paths with /proxy/client/{clientId}.
DEFINITE_VAULT_PROXY_API_KEY	string	Proxy mode	Proxy key. Requires DEFINITE_CLIENT_ID.
DEFINITE_CLIENT_ID	string	Proxy mode	Tenant identifier used in proxy paths.
DEFINITE_VAULT_TIMEOUT	number	No	Request timeout in milliseconds. Default 30000.
DEFINITE_MAX_RETRIES	number	No	Retry budget for transient failures. Default 3.

Monitor runs and read receipts

import { DefiniteClient } from "definite-ts";
 
// new DefiniteClient() reads DEFINITE_VAULT_URL and DEFINITE_VAULT_API_KEY
const client = new DefiniteClient();
 
const readiness = await client.getReadiness();
console.log(readiness.verdictCounts);
 
const runs = await client.listRuns({ limit: 10 });
for (const run of runs.items) {
  console.log(run.runId, run.status);
}
 
const completed = await client.waitForRun(runs.items[0].runId);
 
const receipts = await client.listReceipts({ limit: 50 });
for (const receipt of receipts.items) {
  console.log(receipt.ruleId, receipt.verdict);
}

waitForRun polls until the run reaches completed or failed, and throws RunTimeoutError if the timeout elapses first. A completed run can still contain FAIL or CANNOT_VERIFY receipts; run state and rule verdicts are separate.

Runs usually start from the console, a schedule, or a data refresh. To start one programmatically, call POST /v1/programs/{program_id}/runs over REST — the SDK's createProgramRun and listReportPrograms in 1.0.0 still target a retired endpoint path and will be repointed in the next release.

Method reference

Field	Type	Required	Description
getReadiness()	Readiness	—	Verdict counts, open exceptions, and program status. Metadata, never a verdict.
listReportPrograms() / getReportProgram(id)	Programs	—	Configured programs and their bound rule versions. In 1.0.0, targets a retired path — see the note above.
createProgramRun(programId, request)	Runs	—	Start an asynchronous run. In 1.0.0, targets a retired path — use REST /v1/programs/{id}/runs until the next release.
listRuns() / getRun(id) / retryRun(id)	Runs	—	Inspect runs; retry creates a new child run and leaves the original immutable.
waitForRun(id, options?)	Runs	—	Poll until completed or failed.
listExceptions() / getException(id)	Exceptions	—	FAIL and CANNOT_VERIFY findings with their investigation state.
updateException(id, request) / reviewException(id, request, actor)	Exceptions	—	Assign, annotate, and record a human review. Reviews never change the original verdict.
listReceipts() / getReceipt(id)	Receipts	—	Signed, hash-chained rule receipts.

Error types: DefiniteError, VaultApiError, VaultConnectionError, RunTimeoutError, and TrustedProxyRequiredError. Payload helpers toCamelCaseKeys and toSnakeCaseKeys are exported for interop with raw REST responses.

Do not send raw source values in SDK requests. Runs bind to immutable source snapshots that Vault already holds; receipts and evidence responses carry references and hashes, not raw sensitive values.