Installation

npm install @stdiolabs/provenance-sdk

Quick Start

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

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

// Queue-based ingestion (high throughput, async delivery)
await provenance.log({
  resourceType: "user",
  resourceId: "user-123",
  action: "login",
  uowId: "550e8400-e29b-41d4-a716-446655440000",
  interaction: { email: "[email protected]" },
});

// REST API client (read data, manage config, analytics)
const api = await provenance.api();
const actions = await api.actions.list();
const trace = await api.traces.get("user-123");

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.

Queue Ingestion

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: "create",
  uowId: "550e8400-e29b-41d4-a716-446655440000",
  interaction: { email: "[email protected]" },
});

REST API Client

The api() method returns a client covering all Provenance API endpoints. The API URL is resolved from the platform automatically (or can be set explicitly).

const api = await provenance.api();

// CRUD
const action = await api.actions.create({
  title: "Deploy",
  mnemonic: "DEPLOY",
});
await api.actions.update(action.id, { title: "Deploy v2" });
await api.actions.delete(action.id);

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

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

// Traces
const trace = await api.traces.get("user-123");

Auto-Pagination

CRUD resources include a listAll() async generator that handles pagination automatically:

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

Available Resources

| Namespace | Methods | | ------------------------ | ---------------------------------------------------------------------------------------- | | api.actions | list, get, create, update, delete, listAll | | api.origins | list, get, create, update, delete, listAll | | api.resourceTypes | list, get, create, update, delete, listAll | | api.interactions | list, get, delete | | api.activity | search | | api.traces | get, timeline, summary | | api.analytics | query, discover | | api.dashboards | list, get, create, update, delete, listAll | | api.widgets | list, get, create, update, delete, listAll, getData, previewData | | api.subscribers | list, get, create, update, delete, listAll, stats | | api.subscriptions | list, get, create, update, delete, listAll, pause, resume | | api.alerts | list, get, create, update, delete, listAll, states, evaluate | | api.interactionMetrics | list, get, create, update, delete, listAll, types, discover, calculate | | api.queue | stats, process | | api.secrets | list, get, create, update, delete, listAll, test | | api.secretProviders | list, get, create, update, delete, listAll, types | | api.inboundSources | list, get, create, update, delete, listAll | | api.inboundMappings | list, get, create, update, delete, listAll, test | | api.home | dashboard | | api.health() | Health check |

Context Layering

Set shared context once, override per call:

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

await scoped.log({
  resourceId: "order-789",
  action: "create",
  uowId: "...",
  interaction: { total: 99.99 },
});

addContext() is synchronous — no extra network calls.

Span Hierarchy

log() returns the generated spanId — a UUID that identifies the interaction in a span tree. Pass it as parentSpanId to link child interactions:

const parentSpanId = await provenance.log({
  resourceType: "order",
  resourceId: "order-789",
  action: "create",
  uowId,
  interaction: { total: 99.99 },
});

await provenance.log({
  resourceType: "payment",
  resourceId: "payment-456",
  action: "process",
  uowId,
  parentSpanId,
  interaction: { method: "card" },
});

You can also propagate parentSpanId via context:

const child = provenance.addContext({ parentSpanId });
await child.log({
  resourceId: "item-1",
  action: "reserve",
  uowId,
  interaction: {},
});

See the full docs for more details.

Winston Transport

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: "[email protected]" },
});

Auto-Instrumentation

Zero-code provenance tracking for Express, Fastify, Prisma, and Sequelize:

const { instrument } = require("@stdiolabs/provenance-sdk/auto");

instrument({
  apiKey: process.env.PROVENANCE_API_KEY,
  origin: "order-service",
});

Every inbound HTTP request, database mutation, and outbound HTTP call is tracked automatically — with UOW propagation across async boundaries and service calls.

Fastify

const {
  instrument,
  instrumentFastify,
} = require("@stdiolabs/provenance-sdk/auto");
instrument({ apiKey: "...", origin: "my-service" });
instrumentFastify(fastify);

Prisma

const {
  instrument,
  instrumentPrisma,
} = require("@stdiolabs/provenance-sdk/auto");
instrument({ apiKey: "...", origin: "my-service" });
instrumentPrisma(prisma);

Sequelize

const {
  instrument,
  instrumentSequelize,
} = require("@stdiolabs/provenance-sdk/auto");
instrument({ apiKey: "...", origin: "my-service" });
instrumentSequelize(sequelize);

Configuration

| Option | Required | Description | | ------------- | -------- | --------------------------------------------------------- | | apiKey | Yes | Your Provenance API key | | origin | Yes | Name of the source system | | platformUrl | No | Platform URL (default: https://platform.provenance.dev) | | apiUrl | No | Override API URL (resolved from platform by default) |

Self-Hosted

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

Resilience

• Lazy resolution — Config fetched on first use, not at create() time
• Retry with backoff — 429/5xx retried up to 3× with exponential backoff
• Auto-refresh — On 401/403, credentials force-refreshed and retried
• 5-minute cache — Platform config cached per API key
• Shared instances — API client shared across addContext() children

Licenses

Proprietary — STDIO Labs