TypeScript SDK: authenticate, send and verify events

@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 the Conversion API, including cursor-based event listing. The current npm release is 0.6.0 and targets signed API contract 0.5.0. The source is in plainrouter/sdk. Review release notes before upgrading while the SDK remains in the 0.x series.

Version 0.6.0 includes the required event consent fields and verifySignalIngestion.

Requirements

Node.js 22.22.2 or newer.
A Signals workspace secret.
Server-side code. Do not use the secret in a browser bundle.

Install

npm install @plainrouter/sdk@0.6.0

Configure the client

Configure the shared client once when your server starts:

import {
  configurePlainrouter,
  listEvents,
} from "@plainrouter/sdk";

const token = process.env.PLAINROUTER_TOKEN;
if (!token) throw new Error("PLAINROUTER_TOKEN is required");

configurePlainrouter({ signalTrackerSecret: token });

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

if (!result.response?.ok || !result.data) {
  throw new Error(`Plainrouter request failed (HTTP ${result.response?.status ?? "no response"})`);
}

console.log({ returnedEvents: result.data.events.data.length });

The client sends the Signals workspace secret as a bearer token. The signalTrackerSecret property keeps its compatibility name in 0.6.0. The client 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:

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 an identity-free ingestion diagnostic that does not complete onboarding.
`getEvent`	Retrieve an event, lineage, and delivery state.
`listEvents`	List recent events and delivery metrics.
`listEventsByCursor`	Page through retained events with an opaque cursor.
`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

import {
  configurePlainrouter,
  verifySignalIngestion,
} from "@plainrouter/sdk";

const token = process.env.PLAINROUTER_TOKEN;
if (!token) throw new Error("PLAINROUTER_TOKEN is required");

configurePlainrouter({ signalTrackerSecret: token });

const result = await verifySignalIngestion();
if (!result.response?.ok || !result.data) {
  throw new Error(`Verification failed (HTTP ${result.response?.status ?? "no response"})`);
}

console.log({
  status: result.response.status,
  eventId: result.data.event_id,
  duplicate: result.data.duplicate,
});

The first successful call returns the accepted verification result. Repeating it is safe and returns duplicate: true. The event confirms ledger receipt but is not real arrival evidence and does not complete onboarding.

Send a purchase and inspect its delivery

Follow the Node.js and TypeScript purchase recipe for a complete createEvent request, recorded consent checks, stable retry IDs, and a typed getEvent delivery check. It sends through Plainrouter; it is not a direct Meta Graph API tutorial. By default, operations return data, error, and response; an HTTP failure must be checked before using data. A transport failure may have no response; check it before reading the status. Code using throwOnError: true must also catch thrown failures. Stop on 401, inspect field errors on 422, and retry an uncertain purchase timeout only with its original persisted ID and payload. Avoid logging entire request or error objects. See the API error table.

Handle credentials safely

The SDK accepts only a Signals workspace secret for Conversion API calls. It does not accept an MCP OAuth token or workspace execution 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.

Overview

SDKs

Recipes

TypeScript SDK: authenticate, send and verify events

Requirements

Install

Configure the client

Configure another API origin

Available methods

Verify Signal ingestion

Send a purchase and inspect its delivery

Handle credentials safely

​Requirements

​Install

​Configure the client

​Configure another API origin

​Available methods

​Verify Signal ingestion

​Send a purchase and inspect its delivery

​Handle credentials safely

Requirements

Install

Configure the client

Configure another API origin

Available methods

Verify Signal ingestion

Send a purchase and inspect its delivery

Handle credentials safely