@vennyx/solitrace

Official TypeScript SDK for the SoliTrace API — typed, ergonomic, dependency-free access to your projects, endpoints, rules, captured requests and usage.

• Zero runtime dependencies — built on the platform fetch.
• ESM + CJS — ships both, plus .d.ts / .d.cts type declarations.
• Node 18+ and modern browsers — anywhere fetch exists.
• Type-safe — hand-authored ergonomic types plus machine-generated OpenAPI path types (OpenApiPaths) for drift detection.

Installation

npm install @vennyx/solitrace

Authentication

The SDK authenticates with a programmatic API key (stk_live_*). Create one in the SoliTrace dashboard under API Keys, then pass it to the client. It is sent as Authorization: Bearer <apiKey> on every request.

Keep API keys secret. Prefer environment variables over hard-coding.

Quick start

import { SoliTrace } from '@vennyx/solitrace';

const solitrace = new SoliTrace({
  apiKey: process.env.SOLITRACE_API_KEY!,
  // baseUrl defaults to https://api.solitrace.com
});

// List projects
const projects = await solitrace.projects.list();

// Create an endpoint
const endpoint = await solitrace.endpoints.create(projects[0]!.id, {
  slug: 'checkout-webhook',
  retentionDays: 14,
});

// Add a rule that returns a canned 200 response
await solitrace.rules.create(endpoint.id, {
  conditions: [{ kind: 'method', op: 'equals', value: 'POST' }],
  action: { type: 'http', status: 200, body: '{"ok":true}' },
});

// Query captured requests (phase K1 filters)
const page = await solitrace.requests.list(endpoint.id, {
  method: 'POST',
  status: 200,
  from: '2026-07-01T00:00:00Z',
  limit: 50,
});
console.log(page.items, page.nextCursor);

// Check usage against plan limits
const usage = await solitrace.usage.get(projects[0]!.orgId);
console.log(usage.usage.requestsThisMonth, '/', usage.limits.requestsPerMonth);

A functional factory is also exported:

import { createClient } from '@vennyx/solitrace';
const solitrace = createClient({ apiKey: '...' });

Client options

new SoliTrace({
  apiKey: 'stk_live_...',        // required
  baseUrl: 'https://api.solitrace.com', // optional (default)
  orgId: 'org-uuid',             // optional; sent as X-Org-Id on every request
  fetch: customFetch,            // optional; defaults to globalThis.fetch
  headers: { 'x-trace': 'demo' } // optional; merged into every request
});

Every resource method also accepts a final CallOptions argument for per-call overrides:

await solitrace.projects.list({ orgId: 'other-org', signal: controller.signal });

Resources

| Namespace | Methods | | ---------------------- | ------- | | solitrace.projects | list, create, get, update, delete | | solitrace.endpoints | list, create, get, update, delete | | solitrace.rules | list, create, update, reorder, delete | | solitrace.requests | list, get, getBody, listStreamEvents | | solitrace.usage | get |

Need a route that isn't wrapped yet? Use the low-level HTTP core:

const data = await solitrace.http.request<MyType>('GET', '/some/path', {
  query: { limit: 10 },
});

Error handling

Non-2xx responses throw SoliTraceApiError (a subclass of SoliTraceError); network failures throw SoliTraceError.

import { SoliTraceApiError, SoliTraceError } from '@vennyx/solitrace';

try {
  await solitrace.projects.get('missing');
} catch (err) {
  if (err instanceof SoliTraceApiError) {
    console.error(err.status, err.body, err.requestId);
  } else if (err instanceof SoliTraceError) {
    console.error('Network/SDK error:', err.message);
  }
}

Maintainer notes

The type surface is derived from the API's OpenAPI document (single source of truth, no drift):

# Regenerate openapi.json from the api (requires the api workspace, no DB needed)
npm run openapi:refresh

# Regenerate src/generated/types.ts from openapi.json
npm run openapi:types

# Type-check, test, build (ESM + CJS + d.ts)
npm run typecheck
npm run test
npm run build   # also runs openapi:types via prebuild

The API's OpenAPI describes routes and path params but not request/response body schemas (its DTOs are validated with zod, not decorated classes), so the ergonomic request/response types in src/types.ts are maintained by hand to mirror the API. The generated OpenApiPaths type is exported for advanced consumers and to detect route-level drift at compile time.

License

MIT © Vennyx A.Ş.