> ## 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.

# Node.js and TypeScript

> Track conversions with the server-only @biqli/sdk package.

`@biqli/sdk` is a server-only TypeScript SDK for Node.js 18 or newer. It provides typed inputs, structured errors, timeouts, retries, and stable request identifiers.

## Install and initialize

```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!,
  clientName: 'acme-api',
  clientVersion: '1.0.0',
});
```

Create one reusable client for your process.

## Track a lead

```ts theme={null}
const lead = await biqli.track.lead({
  clickId: 'qPa4lSpsKj3B',
  eventId: 'signup:customer_1842',
  eventName: 'Signed up',
  customerExternalId: 'customer_1842',
  customerName: 'Ada Lovelace',
  customerEmail: 'ada@example.com',
});
```

## Track a sale

```ts theme={null}
const sale = await biqli.track.sale({
  customerExternalId: 'customer_1842',
  amount: 4999,
  currency: 'usd',
  paymentProcessor: 'stripe',
  invoiceId: 'in_1842',
});
```

The SDK derives a deterministic event ID when both `paymentProcessor` and `invoiceId` are present.

## Per-request options

```ts theme={null}
await biqli.track.lead(input, {
  idempotencyKey: 'signup:customer_1842',
  requestId: 'req_signup_customer_1842',
  signal: abortController.signal,
});
```

## Handle errors

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

try {
  await biqli.track.sale(input);
} catch (error) {
  if (error instanceof BiqliError) {
    console.error({
      code: error.code,
      status: error.status,
      requestId: error.requestId,
      retryable: error.retryable,
      attempts: error.attempts,
      details: error.details,
    });
  }
}
```

The SDK retries network errors and HTTP `408`, `425`, `429`, and `5xx` responses. It does not retry validation, permission, authentication, or idempotency conflicts.

See the complete [TypeScript SDK reference](/docs/api-reference/sdks/typescript).