Installation

npm install @stdiolabs/provenance-sdk-ts

Quick Start

import { create } from "@stdiolabs/provenance-sdk-ts";

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

// Queue-based ingestion
await provenance.log({
  resourceType: "user",
  resourceId: "user-123",
  action: "login",
  uowId: crypto.randomUUID(),
  interaction: { email: "[email protected]" },
});

// REST API client
const api = await provenance.api();
const actions = await api.actions.list();
const trace = await api.traces.get("user-123");

REST API Client

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 & Analytics
const results = await api.activity.search({ filters: { action: "CREATE" } });
const data = await api.analytics.query({
  metrics: ["count"],
  dimensions: ["action"],
  timeRange: { type: "relative", value: "7d" },
});

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

Context Layering

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

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

Span Hierarchy

log() returns a Promise<string> — the generated spanId. 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', ... });

See the full docs for more details.

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) |

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
• Zero dependencies — Pure TypeScript, no runtime deps

License

Proprietary — STDIO Labs