> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lithoblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Use the LithoBlocks 0.x SDK against the verified staging API.

`@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

```typescript theme={null}
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:

```typescript theme={null}
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.

```typescript theme={null}
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.