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

# TypeScript SDK

> Reference for the server-only @biqli/sdk client.

`@biqli/sdk` runs on Node.js 18 or newer. It must never be bundled into browser code.

```bash theme={null}
npm install @biqli/sdk
```

```ts theme={null}
import {Biqli} from '@biqli/sdk';

const biqli = new Biqli({
  apiKey: process.env.BIQLI_API_KEY!,
});
```

`BiqliClient` is an alias of `Biqli`.

## Configuration

| Option              | Type                      | Default              | Description                                                         |
| :------------------ | :------------------------ | :------------------- | :------------------------------------------------------------------ |
| `apiKey`            | `string`                  | Required             | Secret workspace key beginning with `biqli_`, excluding `biqli_pk_` |
| `baseUrl`           | `string`                  | `https://biq.li/api` | API base without credentials, query, or hash                        |
| `timeoutMs`         | `number`                  | `10000`              | Per-attempt timeout, up to 120 seconds                              |
| `clientName`        | `string`                  | `@biqli/sdk`         | Diagnostic client header, up to 64 characters                       |
| `clientVersion`     | `string`                  | SDK version          | Diagnostic version header, up to 64 characters                      |
| `retry.maxRetries`  | `number`                  | `2`                  | Retries after the first attempt, up to 8                            |
| `retry.baseDelayMs` | `number`                  | `250`                | Initial retry delay                                                 |
| `retry.maxDelayMs`  | `number`                  | `5000`               | Maximum retry delay, up to 60 seconds                               |
| `retry.jitter`      | `boolean`                 | `true`               | Randomize retry delays to reduce synchronized retries               |
| `fetch`             | Fetch-compatible function | Global `fetch`       | Custom server transport                                             |

## Methods

```ts theme={null}
await biqli.track.lead(input, options);
await biqli.track.sale(input, options);
```

Inputs match the public [lead](/docs/api-reference/conversions/track-lead) and [sale](/docs/api-reference/conversions/track-sale) schemas.

### Request options

| Option           | Description                                                  |
| :--------------- | :----------------------------------------------------------- |
| `idempotencyKey` | Stable transport identity; defaults to the prepared event ID |
| `requestId`      | Trace identifier up to 100 safe characters                   |
| `signal`         | `AbortSignal` controlled by your application                 |

The SDK creates a stable request ID, event ID, and idempotency key before its first attempt. For durable replay across processes, supply a lead `eventId` or sale `paymentProcessor` plus `invoiceId`.

## Errors

```ts theme={null}
import {BiqliError} from '@biqli/sdk';
```

| Property    | Type             | Meaning                                      |
| :---------- | :--------------- | :------------------------------------------- |
| `code`      | `string`         | Machine-readable API or SDK error code       |
| `status`    | `number`         | HTTP status, or `0` before a response exists |
| `requestId` | `string \| null` | Biqli trace identifier                       |
| `details`   | `unknown`        | Structured validation details when available |
| `retryable` | `boolean`        | Whether the failure class is temporary       |
| `attempts`  | `number`         | Number of attempted requests                 |

The SDK retries network errors and HTTP `408`, `425`, `429`, and `5xx`. It honors a valid `Retry-After` header up to 60 seconds.

See [Node.js and TypeScript](/developers/server/node) and [Next.js](/developers/server/nextjs) for complete implementations.