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

# TypeScript SDK

> Use the generated @plainrouter/sdk client and Zod schemas with the Signals Conversion API.

`@plainrouter/sdk` is the generated TypeScript client for the signed PlainRouter OpenAPI contract. It exposes typed request and response models, API methods, and Zod schemas for all ten Conversion API operations.

The current [npm release](https://www.npmjs.com/package/@plainrouter/sdk) is `0.5.0` and targets signed API contract `0.5.0`. The source is in [`plainrouter/sdk`](https://github.com/plainrouter/sdk/tree/main/packages/sdk). Review release notes before upgrading while the SDK remains in the `0.x` series.

<Note>
  Version `0.5.0` includes the required event consent fields and `verifySignalIngestion`.
</Note>

## Requirements

* Node.js `22.22.2` or later in the Node 22 release line.
* A per-Signal tracker secret.
* Server-side code. Do not use the tracker secret in a browser bundle.

## Install

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

## Configure the client

Configure the shared client once when your server starts:

```ts theme={null}
import {
  configurePlainrouter,
  listEvents,
} from "@plainrouter/sdk";

configurePlainrouter({
  signalTrackerSecret: process.env.PLAINROUTER_TOKEN!,
});

const result = await listEvents({
  query: { per_page: 25 },
});

if (result.error) {
  console.error(result.error);
} else {
  console.log(result.data);
}
```

The client sends the tracker secret as a bearer token. It does not read credentials from the environment automatically.

## Configure another API origin

The default API base URL is `https://plainrouter.com/api/v1`. Override it only for a PlainRouter-provided region or a controlled test environment:

```ts theme={null}
configurePlainrouter({
  baseUrl: "https://example.test/api/v1",
  signalTrackerSecret: process.env.PLAINROUTER_TOKEN!,
});
```

You can also inject a compatible `fetch` implementation through the same configuration object.

## Available methods

| Method                    | Purpose                                                |
| ------------------------- | ------------------------------------------------------ |
| `createEvent`             | Submit an idempotent conversion event.                 |
| `verifySignalIngestion`   | Write the identity-free onboarding verification event. |
| `getEvent`                | Retrieve an event, lineage, and delivery state.        |
| `listEvents`              | List recent events and delivery metrics.               |
| `setDestinationTestMode`  | Enable or disable destination test mode.               |
| `sendTestPurchase`        | Send a controlled test purchase.                       |
| `replayDeliveries`        | Replay eligible recent deliveries.                     |
| `getReconciliationReport` | Retrieve reconciliation results for a date.            |
| `getEmqReport`            | Retrieve recent Event Match Quality snapshots.         |
| `deleteUserData`          | Delete data matching a hashed identifier.              |

The package also exports the generated TypeScript models and Zod schemas. Use the schemas when you need runtime validation at an application boundary.

## Verify Signal ingestion

```ts theme={null}
import {
  configurePlainrouter,
  verifySignalIngestion,
} from "@plainrouter/sdk";

configurePlainrouter({
  signalTrackerSecret: process.env.PLAINROUTER_TOKEN!,
});

const result = await verifySignalIngestion();
```

The first successful call returns the accepted verification result. Repeating it is safe and returns `duplicate: true`.

## Handle credentials safely

The SDK accepts only a Signal tracker secret for Conversion API calls. It does not accept an MCP OAuth token or workspace token.

Keep the secret in a server-side secret manager. Never include it in client-side JavaScript, prompts, URLs, logs, or source control.

For request and response fields, use the [API reference](/docs/reference/conversion-api).