A client that retries.
The SDK for JavaScript and TypeScript wraps the API with the parts every integration ends up writing: retries, idempotency keys, pagination, typed errors, deprecation notices and webhook verification. It needs Node 20 or later, or any runtime with fetch and WebCrypto.
Type the paths.
The package is not on npm yet, so there is no install command to run. Its types come from the contract: download the OpenAPI file from the reference and generate them, and a path, its parameters and its answer are all checked as you write.
curl -O <the file you downloaded from the reference page>
npx openapi-typescript ./openapi.json -o ./generated.d.tsThe file is the whole contract, one OpenAPI 3.1 document. Without generated types the client still works, with untyped paths.
Make a client.
A key is made in the app by an administrator of the books. Keep it in a secret manager and read it at start-up.
import { createLedgerClient } from "@eternify-labs/ledger";
import type { paths } from "./generated";
const ledger = createLedgerClient<paths>({ apiKey: process.env.ETERNIFY_API_KEY! });
const { data: bill } = await ledger.POST("/v1/bills", {
body: { entityId, billDate: "2026-10-31", lines },
});| Option | Default | What it does |
|---|---|---|
apiKey | required | Sent as a bearer token in the Authorization header. |
baseUrl | https://api.eternifylabs.com | Point it at another address, for example a test double. |
version | 2026-08-31, the version the SDK was written against | Sent as Eternify-Version. Pinned, so a change in the wire version never reaches you by surprise. |
retry | 2 retries | maxRetries, baseDelayMs, maxDelayMs and maxRetryAfterMs, or false to turn retries off. |
throwOnError | true | A non-2xx answer throws LedgerApiError. With false you get data, error and response. |
onDeprecation | one Node warning per operation | A function to route the notice, or false to silence it. |
fetch | globalThis.fetch | Any function from a Request to a Promise of a Response. |
A first call in each area.
Each of these lists records and needs nothing in its path, so it is the quickest way to see an area answer.
| Area | Call | Operation |
|---|---|---|
| Purchases | ledger.GET("/v1/bill-approval-stages") | listBillApprovalStages |
| Sales | ledger.GET("/v1/contracts") | listContracts |
| Accounting | ledger.GET("/v1/accounts") | listAccounts |
| Banking and payments | ledger.GET("/v1/bank-accounts") | listBankAccounts |
| Tax | ledger.GET("/v1/compliance/deadlines") | listDeadlines |
| Reports | ledger.GET("/v1/analysis/measures") | listMeasures |
| Close | ledger.GET("/v1/close") | closeChecklist |
| Settings | ledger.GET("/v1/api-keys") | listApiKeys |
| Documents | ledger.GET("/v1/document-search/sources") | listSearchSources |
| People | ledger.GET("/v1/people") | listLedgerPeople |
| Platform | ledger.GET("/v1/access-log") | accessLog |
Retries and idempotency.
Every request that changes something carries an Idempotency-Key, a UUID chosen before the first attempt, and a retry sends the same one. A bill the server created whose answer was lost is returned once, not created twice. Keys are kept for 7 days.
await ledger.POST("/v1/bills", {
body,
headers: { "Idempotency-Key": "import-2026-10-31-row-7" },
});- Retried: 429, 502, 503, 504 and requests that never got an answer.
- Not retried: 500 and every other 4xx.
- The wait grows with jitter, and a Retry-After from the server is honoured.
- If the server asks for more than 60 seconds, the 429 comes back to you instead of holding the call open.
- Abort with a signal and the retry loop stops.
Pages and errors.
A list answers one page of up to 200 records, the cursor for the next and the total. paginate walks them for you. A failed call throws LedgerApiError with the status, the code, the remedy and the request identifier to quote when you write to us.
import { paginate } from "@eternify-labs/ledger";
for await (const bill of paginate((cursor) =>
ledger.GET("/v1/bills", { params: { query: { cursor } } }),
)) {
console.log(bill.id);
}import { LedgerApiError } from "@eternify-labs/ledger";
try {
await ledger.POST("/v1/bills", { body });
} catch (error) {
if (error instanceof LedgerApiError) {
console.log(error.code, error.remedy, error.requestId);
} else throw error;
}Every code is explained on the errors page.
Webhooks and versions.
verifyWebhook checks a delivery's signature and returns its body parsed, or throws WebhookVerificationError with the reason. The SDK pins the wire version it was written against and warns once per operation when you call one that is being retired.
import { verifyWebhook } from "@eternify-labs/ledger/webhooks";
const event = await verifyWebhook(rawBody, request.headers, process.env.WEBHOOK_SECRET!);The webhooks page has the events and a test vector. Stable operations carry 365 days’ notice before a change and beta operations 30; see the changelog.
Build against a real ledger.
Book a demo and we walk you through the books your key would reach.