SDKs

npm install @stdiolabs/provenance-sdk

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

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

const spanId = await provenance.log({
  resourceType: 'user',
  resourceId: 'user-123',
  action: 'login',
  uowId: crypto.randomUUID(),
  interaction: { email: 'user@example.com' },
});
// spanId is a UUID string identifying this interaction in the span tree

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' },
});

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' },
});

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

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

const api = await provenance.api();

const subscription = await api.subscriptions.create({
  actionId: 'action-uuid',
  resourceTypeId: 'resource-type-uuid',
  subscriberId: 'subscriber-uuid',
  labels: ['Production', 'Billing Alerts', 'high-priority'],
  delivery_schedule: {
    timezone: 'America/New_York',
    windows: [
      { days: [1, 2, 3, 4, 5], startTime: '09:00', endTime: '17:00' },
      { days: [6], startTime: '10:00', endTime: '14:00' },
    ],
  },
  config: { adapter: 'adapter:slack', webhookUrl: '{{secrets.SLACK_WEBHOOK}}' },
});

// Single label — subscriptions containing "Production"
const result = await api.subscriptions.list({ label: 'Production' });

// Multiple labels — subscriptions containing at least one
const result = await api.subscriptions.list({ labels: 'Production,Security' });

const api = await provenance.api();

const goal = await api.alerts.create({
  title: 'Monthly Revenue Target',
  metricId: 'revenue-metric-uuid',
  operator: 'gte',
  threshold: 100000,
  alertActionId: 'goal-reached-action-uuid',
  resourceTypeId: 'alert-biz-uuid',
  kind: 'goal',
});

const alerts = await api.alerts.list({ kind: 'alert' });
const goals = await api.alerts.list({ kind: 'goal' });

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

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

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

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