SDKs

Provenance SDKs provide a native interface for recording interactions via managed queues and querying the full REST API — with type safety, automatic retries, credential caching, and auto-pagination.

Available SDKs

All SDKs follow the same pattern: a create() initializer that resolves credentials from the platform, a log() method for queue-based ingestion, and an api() method for the full REST client. Java uses a builder pattern instead of options objects.

Installation

npm install @stdiolabs/provenance-sdk

Quick start

Initialize

const { create } = require('@stdiolabs/provenance-sdk');

const provenance = await create({
  apiKey: 'your-api-key',
  origin: 'my-service',
});

The SDK resolves queue credentials and API URL automatically from the platform using your API key. Both are cached for 5 minutes and auto-refresh on token rotation.

Record interactions (queue)

The log() method pushes interactions through a managed queue for reliable async delivery with automatic retries. This is the recommended path for recording interactions in production.

await provenance.log({
  resourceType: 'user',
  resourceId: 'user-123',
  action: 'login',
  uowId: crypto.randomUUID(),
  interaction: { email: 'user@example.com' },
});

Query the API

The api() method returns a client covering all Provenance API endpoints — CRUD operations, analytics, traces, subscriptions, alerts, and more.

const api = await provenance.api();

// List actions
const actions = await api.actions.list();

// Get a trace
const trace = await api.traces.get('user-123');

// Run an analytics query
const data = await api.analytics.query({
  metrics: ['count'],
  dimensions: ['action'],
  timeRange: { type: 'relative', value: '7d' },
});

// Search activity
const results = await api.activity.search({
  filters: { action: 'CREATE', resourceType: 'USER' },
});

REST API client

The api() method is lazy — the API URL is resolved on first call and cached. The client covers every endpoint in the Provenance API.

CRUD resources

Resources like actions, origins, resource types, dashboards, widgets, subscribers, subscriptions, alerts, and adapter settings all share the same interface:

const api = await provenance.api();

// List (paginated)
const { data, pagination } = await api.actions.list({ page: 1, limit: 25 });

// Get by ID
const action = await api.actions.get('action-uuid');

// Create
const newAction = await api.actions.create({ title: 'Deploy', mnemonic: 'DEPLOY' });

// Update
await api.actions.update('action-uuid', { title: 'Deploy v2' });

// Delete
await api.actions.delete('action-uuid');

Auto-pagination

Every CRUD resource includes an async generator that handles pagination automatically:

for await (const action of api.actions.listAll()) {
  console.log(action.title);
}

// Custom page size
for await (const origin of api.origins.listAll({}, { pageSize: 50 })) {
  console.log(origin.mnemonic);
}

Available namespaces

Node.js, TypeScript, and Java use camelCase. Python uses snake_case. Java uses method calls (e.g., api.actions()) instead of property access.

Context layering

Set shared context once, override per call:

const scoped = provenance.addContext({
  resourceType: 'order',
  userId: 'user-456',
});

// Only provide what's different
await scoped.log({
  resourceId: 'order-789',
  action: 'create',
  uowId: crypto.randomUUID(),
  interaction: { total: 99.99 },
});

// api() is shared across parent and children — no extra resolution
const api = await scoped.api();

addContext() / add_context() is synchronous and reuses the same queue credentials and API client — no extra network calls.

Winston transport (Node.js only)

The Node.js SDK includes a Winston transport for drop-in logging integration:

const winston = require('winston');
const { ProvenanceTransport } = require('@stdiolabs/provenance-sdk');

const logger = winston.createLogger({
  transports: [
    new ProvenanceTransport({
      level: 'info',
      apiKey: 'your-api-key',
      config: { origin: 'my-service' },
    })
  ]
});

logger.info({
  resourceType: 'user',
  resourceId: 'user-123',
  action: 'login',
  uowId: '550e8400-e29b-41d4-a716-446655440000',
  interaction: { email: 'user@example.com' },
});

Self-hosted mode

If you're running Provenance self-hosted with your own queue infrastructure:

const { create } = require('@stdiolabs/provenance-sdk');

const provenance = await create(
  { origin: 'my-service', apiUrl: 'https://your-api.com/api' },
  'https://your-queue-url/v2/enqueue/queue-name/destination',
  'your-queue-token',
  'your-api-key'
);

await provenance.log({ ... });
const api = await provenance.api();

In manual mode, apiUrl / api_url is required for the REST client.

Resilience

All SDKs implement the same resilience patterns:

• Lazy resolution — Queue config and API URL fetched on first use, not at create() time. Your app starts even if the platform is temporarily unreachable.
• Retry with backoff — Transient failures (429, 5xx) retried up to 3 times with exponential backoff — for both queue ingestion and REST API calls.
• Auto-refresh — On 401/403 from the queue, credentials are force-refreshed from the platform and the request retried once.
• 5-minute cache — Platform config cached to avoid per-call lookups.
• Shared instances — The API client is shared across addContext() / add_context() children.

Configuration

SDK differences

Auto-instrumentation (Node.js)

The Node.js SDK includes zero-code auto-instrumentation that patches http, http.request/https.request, express, fastify, fetch, prisma, and sequelize to record interactions automatically — with UOW propagation across async boundaries and service calls.

require('@stdiolabs/provenance-sdk/auto').instrument({
  apiKey: process.env.PROVENANCE_API_KEY,
  origin: 'order-service',
});

One line at the top of your app. No changes to application code. See Auto-Instrumentation for the full guide.