@trustpipelines/sdk

First-party server-side SDK for the Trust Pipelines Management API. Typed access to pipelines, checkpoints, webhooks, analytics, and audit logs from any Node.js 18+ runtime.

This is the server SDK (your backend, with a secret tp_... key). For in-browser verification (signup / vote / review widgets) use @trustpipelines/js instead — never put a Management API key in a browser.

• Zero runtime dependencies (uses the platform fetch)
• Dual ESM + CommonJS, full TypeScript types generated from the OpenAPI spec
• Cursor-pagination helpers (for await)
• Automatic rate-limit retry (respects Retry-After)
• Typed error hierarchy

Install

npm install @trustpipelines/sdk
# or: pnpm add @trustpipelines/sdk / yarn add @trustpipelines/sdk

Quickstart (5 minutes)

import { TrustPipelines } from '@trustpipelines/sdk';

const client = new TrustPipelines({
  apiKey: process.env.TP_API_KEY!, // a secret tp_... Management API key
});

// 1. Create a pipeline
const pipeline = await client.pipelines.create({ name: 'Signup Guard' });

// 2. Publish its draft as the active version
await client.pipelines.publishVersion(pipeline.id);

// 3. List versions (single page)
const versions = await client.pipelines.versions.list(pipeline.id, { limit: 10 });
console.log(versions.data);

// 4. Iterate every pipeline in the workspace (auto-pagination)
for await (const p of client.pipelines.iterate()) {
  console.log(p.id, p.name, p.status);
}

Configuration

new TrustPipelines({
  apiKey: 'tp_...',                       // required
  baseUrl: 'https://app.trustpipelines.com', // optional (default)
  maxRetries: 3,                          // optional — automatic 429 retries (default 3)
  fetchImpl: customFetch,                 // optional — inject a fetch (proxy/agent/tests)
});

Resources

Every namespace mirrors the Management API. List endpoints return one cursor page ({ data, next_cursor }); the matching iterate(...) walks all pages lazily.

| Namespace | Methods | |---|---| | client.pipelines | list · iterate · get · create · update · delete · publishVersion · lock · unlock | | client.pipelines.versions | list · iterate | | client.checkpoints | list · iterate · get · create · update · delete | | client.webhooks | list · iterate · get · create · update · delete · test · replay · deliveries · iterateDeliveries | | client.analytics | checks · pipelines · iteratePipelines · pipeline · checkpoint | | client.auditLogs | list · iterate |

Pagination

// Single page — pass the previous next_cursor to advance manually:
const page = await client.checkpoints.list({ limit: 50 });
if (page.next_cursor) {
  const next = await client.checkpoints.list({ cursor: page.next_cursor });
}

// Or just iterate — the SDK follows the cursor for you:
for await (const checkpoint of client.checkpoints.iterate()) {
  // ...
}

Error handling

Every non-2xx response is thrown as a typed error. All extend TrustPipelinesError.

import {
  TrustPipelinesNotFoundError,
  TrustPipelinesRateLimitError,
  TrustPipelinesError,
} from '@trustpipelines/sdk';

try {
  await client.pipelines.get('pl_does_not_exist');
} catch (err) {
  if (err instanceof TrustPipelinesNotFoundError) {
    // 404 — no such pipeline in this workspace
  } else if (err instanceof TrustPipelinesRateLimitError) {
    // 429 after retries were exhausted — err.retryAfterSeconds
  } else if (err instanceof TrustPipelinesError) {
    console.error(err.status, err.code, err.requestId);
  }
}

| Class | Status | |---|---| | TrustPipelinesAuthError | 401 | | TrustPipelinesPermissionError | 403 (missing scope) | | TrustPipelinesNotFoundError | 404 | | TrustPipelinesConflictError | 409 | | TrustPipelinesValidationError | 422 | | TrustPipelinesRateLimitError | 429 (after retries) | | TrustPipelinesServerError | 5xx | | TrustPipelinesConnectionError | transport failure (no response) |

Rate limits & retries

The API enforces a per-minute and a per-second (burst) limit per workspace. On a 429 the SDK automatically retries up to maxRetries times, honoring the Retry-After header when present (and falling back to capped exponential backoff otherwise). Only 429s are retried — 5xx and transport errors surface immediately so non-idempotent writes are never silently re-applied.

License

MIT