TypeScript SDK

@lithoblocks/sdk 0.1.0 is implemented as a monorepo package and is not yet published to npm. It defaults to https://next.api.lithoblocks.com. Production cutover and a 1.0 release are separate steps. Node 22 is the tested baseline. Keep organization API keys in server code.

Install a build

From a checkout, run pnpm install --frozen-lockfile, then pnpm --filter @lithoblocks/sdk build and pnpm --filter @lithoblocks/sdk pack. Install the resulting archive into your application with npm install /path/to/lithoblocks-sdk-0.1.0.tgz. The package exports ESM, CommonJS and TypeScript declarations and has no runtime dependencies.

Compile and send

import { LithoBlocks, bulkFailures } from '@lithoblocks/sdk';

const client = new LithoBlocks(); // reads LITHOBLOCKS_API_KEY
const template_id = 'YOUR_TEMPLATE_ID';
const schema = await client.templates.inputSchema(template_id);
const data = { title: 'Build finished' }; // match the selected template's inputs
const preview = await client.templates.compile({ template_id, data });
console.log(preview.compiled_message);

const sent = await client.templates.send({ template_id, data, channel_id: 'YOUR_DEV_CHANNEL_ID' });
console.log(sent.message_ts);

Send accepts exactly one of channel_id, recipient_email, or recipient_slack_id. TypeScript and runtime checks reject mixed destinations. Bulk accepts 1–100 such objects and returns every result, including failures within HTTP 200 responses. Use bulkFailures(result) to select failures without re-sending successful entries.

Intentional duplicates and retries

Each supported POST gets a fresh idempotency key per SDK call. Two intentional calls can send the same message twice. For a retry of one intended operation, supply the same key and identical serialized JSON body, including property order:

const idempotencyKey = 'YOUR_STABLE_OPERATION_ID';
const result = await client.templates.send(
  { template_id, data, channel_id: 'YOUR_DEV_CHANNEL_ID' },
  { idempotencyKey },
).withResponse();
console.log(result.requestId, result.idempotency);

Acknowledgment requires the server to echo the exact key and Idempotency-Replayed: true|false. No write is retried automatically, including compile, send, authoring, flush, update and delete. A missing response, retained 5xx or in-progress claim can mean the write already happened. Keep the original key and body, inspect the outcome, and reconcile before another attempt. The error exposes idempotency and reconciliationRequired. Do not rotate a key to bypass an uncertain outcome. GET requests retry connection errors, 429 and 5xx twice by default with bounded backoff and Retry-After handling. Set maxRetries: 0 to disable this. timeout defaults to 60 seconds per attempt; each call accepts an AbortSignal and a timeout override.

Errors and pagination

APIError carries status, code, request_id, raw, validation issues and scope details. Subclasses distinguish authentication, permission, validation, credits, rate limits and idempotency. Connection, abort and protocol errors preserve the idempotency key and uncertain-write guidance. Legacy envelopes are normalized; unknown machine codes and the raw response remain available.

const firstPage = await client.templates.list({ limit: 20 });
for await (const template of client.templates.list({ limit: 20 })) {
  console.log(template.id);
}

Iteration fetches subsequent pages lazily and stops on an empty page or total exhaustion. Offset pagination is not a snapshot: changing data between requests can shift results. Operations that return bare arrays, such as organization members, remain arrays.

Coverage and release status

All 69 current v1 operations have typed bindings, including templates/versions, queues, schedules, destinations, interactions, modals/versions/submissions, credits, organizations, users, entities and search. Method names use camelCase; request and response properties keep API snake_case. client.request(method, path, parameters) provides a typed low-level interface to the same operations. The package README contains the full method list and options. CI checks OpenAPI generation, all operation bindings, transport behavior and installation of the package archive. Live staging tests are opt-in; registry publishing and recurring live tests are not enabled by this implementation.

Low-code platforms

AI agents

SDKs

Install a build

Compile and send

Intentional duplicates and retries

Coverage and release status

​Install a build

​Compile and send

​Intentional duplicates and retries

​Errors and pagination

​Coverage and release status

Install a build

Compile and send

Intentional duplicates and retries

Errors and pagination

Coverage and release status