@skrr-ai/signals

CloudEvents-native public contracts and a small, transport-only publisher for the OverSky Signal Plane.

This package submits immutable facts to POST /v1/signals. It does not create a Commitment, select a Monitor, wake an Agent, or grant any execution authority. Those are server-owned control-plane decisions.

import { SignalPublisher } from '@skrr-ai/signals';

const signals = new SignalPublisher({
  endpoint: 'https://api.oversky.ai/v1/signals',
  source: 'urn:oversky:signal-source:src_payments_production',
  token: process.env.OVERSKY_SIGNAL_TOKEN!,
});

await signals.emit({
  type: 'io.acme.payments.http-request-failed.v1',
  subject: 'service/payments-api',
  dataschema:
    'https://schemas.acme.example/signals/http-request-failed/1.0.0.json',
  data: {
    'service.name': 'payments-api',
    'deployment.environment.name': 'production',
    'http.route': 'POST /payments',
    'http.response.status_code': 500,
    'error.type': 'db-connection-timeout',
  },
});

Use the versioned JSON Schema and AsyncAPI files under contracts/ to integrate non-JavaScript producers. The package serializes structured-mode CloudEvents (application/cloudevents+json) and keeps the CloudEvents id stable across retries.

The Signal Source credential determines the tenant and allowed source. Never put workspace, Commitment, Agent, authorization, request bodies, cookies, access tokens, or arbitrary stack traces in an event payload.