@skrr-ai/signals 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,254 @@
+/** CloudEvents structured-mode media type accepted by the Signal API. */
+declare const SIGNAL_CLOUDEVENTS_CONTENT_TYPE = "application/cloudevents+json";
+declare const SIGNAL_API_VERSION = "v1";
+declare const CLOUD_EVENTS_V1: "1.0";
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * Extension attributes are intentionally limited to normal CloudEvents extension
+ * names. They cannot carry source identity, authorization, Monitor, Commitment,
+ * or Agent selection data.
+ */
+type SignalExtensions = Record<string, JsonPrimitive>;
+/**
+ * The public v1 Signal envelope. It is CloudEvents 1.0 in structured JSON mode.
+ * `source + id` is the occurrence identity used for deduplication.
+ */
+interface SignalEnvelope<TData extends JsonValue = JsonValue> {
+    specversion: typeof CLOUD_EVENTS_V1;
+    id: string;
+    source: string;
+    type: string;
+    subject?: string;
+    time: string;
+    datacontenttype: 'application/json';
+    /** Immutable URI for the source-reviewed payload schema. Required because
+     * server acceptance is bound to a registered (type, dataschema) pair. */
+    dataschema: string;
+    data: TData;
+    traceparent?: string;
+    tracestate?: string;
+    [extension: string]: unknown;
+}
+/** A trace context is evidence correlation only; it is never authorization. */
+interface SignalTraceContext {
+    traceparent: string;
+    tracestate?: string;
+}
+interface SignalEmitInput<TData extends JsonValue = JsonValue> {
+    /** Stable across a caller's retries. A UUID is generated when omitted. */
+    id?: string;
+    type: string;
+    subject?: string;
+    /** Defaults to the publisher's current UTC time. */
+    time?: string | Date;
+    /** Immutable schema URI registered for this Signal type. */
+    dataschema: string;
+    data: TData;
+    extensions?: SignalExtensions;
+}
+interface SignalValidationIssue {
+    path: string;
+    code: 'required' | 'type' | 'format' | 'value' | 'unsupported' | 'reserved_attribute' | 'unsafe_extension';
+    message: string;
+}
+interface SignalValidationSuccess<T> {
+    ok: true;
+    value: T;
+}
+interface SignalValidationFailure {
+    ok: false;
+    issues: SignalValidationIssue[];
+}
+type SignalValidationResult<T> = SignalValidationSuccess<T> | SignalValidationFailure;
+declare class SignalContractError extends TypeError {
+    readonly issues: readonly SignalValidationIssue[];
+    constructor(message: string, issues: readonly SignalValidationIssue[]);
+}
+/**
+ * Validates the generic public envelope only. Source credential binding,
+ * registered type/schema checks, redaction, quotas, and payload limits are
+ * server-owned policies and intentionally do not live in the publisher SDK.
+ */
+declare function validateSignalEnvelope<TData extends JsonValue = JsonValue>(input: unknown): SignalValidationResult<SignalEnvelope<TData>>;
+declare function parseSignalEnvelope<TData extends JsonValue = JsonValue>(input: unknown): SignalEnvelope<TData>;
+declare function createSignalEnvelope<TData extends JsonValue = JsonValue>(source: string, input: SignalEmitInput<TData>, traceContext?: SignalTraceContext): SignalEnvelope<TData>;
+type SignalSourceTransport = 'sdk' | 'direct_api' | 'webhook' | 'oauth_connector' | 'otel' | 'pull_connector';
+type SignalSourceStatus = 'active' | 'paused' | 'disabled';
+type SignalCredentialKind = 'bearer_token' | 'webhook_hmac';
+type SignalCredentialStatus = 'active' | 'revoked' | 'expired';
+type SignalFieldDataType = 'string' | 'number' | 'integer' | 'boolean' | 'timestamp' | 'uri';
+type SignalFieldClassification = 'filterable' | 'groupable' | 'displayable' | 'sensitive' | 'evidence_only';
+type SignalCardinality = 'low' | 'bounded' | 'high';
+/** A safe, schema-declared field. The field name is not an arbitrary JSONPath. */
+interface SignalFieldDefinition {
+    name: string;
+    displayName: string;
+    dataType: SignalFieldDataType;
+    classifications: readonly SignalFieldClassification[];
+    required?: boolean;
+    cardinality: SignalCardinality;
+    maxLength?: number;
+    description?: string;
+}
+interface SignalTypeDefinition {
+    type: string;
+    dataschema: string;
+    displayName: string;
+    description: string;
+    subjectKinds: readonly string[];
+    fields: readonly SignalFieldDefinition[];
+    /** Existing Monitors pin to this range; breaking changes require a new type major. */
+    compatibility: 'backward_compatible_additions';
+    deprecatedAt?: string;
+    migrationGuide?: string;
+}
+/**
+ * Size and shape limits applied to an accepted Signal. These are returned by
+ * the management API so a producer can adapt before the delivery endpoint
+ * rejects an oversized payload.
+ */
+interface SignalSchemaPolicy {
+    maxEventBytes: number;
+    maxDataBytes: number;
+    maxDataDepth: number;
+    maxDataFields: number;
+}
+/** The per-source delivery allowance enforced by the Signal API. */
+interface SignalSourceRateLimit {
+    maxPerMinute: number;
+}
+/** The retention boundary advertised for normalized Signal records. */
+interface SignalSourceRetentionPolicy {
+    normalizedSignalDays: number;
+    residency?: string;
+}
+interface PublicSignalSourcePolicy {
+    limits: SignalSchemaPolicy;
+    rateLimit: SignalSourceRateLimit;
+    redaction: {
+        additionalSensitiveKeys: readonly string[];
+        retainTracestate: boolean;
+    };
+    retention: SignalSourceRetentionPolicy;
+}
+/** Safe credential metadata returned by normal source reads. It never includes secret material. */
+interface PublicSignalSourceCredential {
+    id: string;
+    credentialId: string;
+    sourceId: string;
+    kind: SignalCredentialKind;
+    status: SignalCredentialStatus;
+    label: string;
+    algorithm: 'bearer-token' | 'hmac-sha256';
+    notBefore: string;
+    createdAt: string;
+    lastUsedAt?: string;
+    expiresAt?: string;
+    revokedAt?: string;
+    revokeReason?: string;
+    lastRotatedAt?: string;
+}
+/**
+ * Secret material appears only on credential creation or rotation. Do not
+ * persist or log this object; retrieve future state through the public shape.
+ */
+interface SignalSourceCredentialGrant {
+    credential: PublicSignalSourceCredential;
+    secret: string;
+    secretKind: 'bearer_token' | 'webhook_hmac';
+    shownOnce: true;
+}
+interface PublicSignalSource {
+    sourceId: string;
+    workspaceId: string;
+    label: string;
+    cloudEventSource: string;
+    transport: SignalSourceTransport;
+    status: SignalSourceStatus;
+    typeDefinitions: readonly (SignalTypeDefinition & {
+        schemaVersion: string;
+        enabled: boolean;
+    })[];
+    credentialCount: number;
+    policy: PublicSignalSourcePolicy;
+    health: {
+        lastAcceptedAt?: string;
+        lastRejectedAt?: string;
+        lastErrorCode?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateSignalSourceResult {
+    source: PublicSignalSource;
+    credential?: SignalSourceCredentialGrant;
+}
+interface RotateSignalSourceCredentialResult {
+    credential: SignalSourceCredentialGrant;
+}
+declare function validateSignalTypeDefinition(input: unknown): SignalValidationResult<SignalTypeDefinition>;
+declare function parseSignalTypeDefinition(input: unknown): SignalTypeDefinition;
+
+interface SignalPublisherOptions {
+    /** The full ingestion URL, normally `https://api.oversky.ai/v1/signals`. */
+    endpoint: string;
+    /** The Signal Source's canonical CloudEvents source URI. */
+    source: string;
+    /** Source-scoped bearer token. Do not reuse a user API key. */
+    token: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    maxRetries?: number;
+    defaultHeaders?: Record<string, string>;
+    /** Optional bridge to OpenTelemetry or another W3C Trace Context provider. */
+    traceContextProvider?: () => SignalTraceContext | undefined;
+}
+interface SignalReceipt {
+    receiptId: string;
+    sourceId: string;
+    canonicalSource: string;
+    eventId: string;
+    outcome: 'accepted' | 'duplicate';
+    processingStatus: 'pending' | 'processing' | 'completed';
+    receivedAt: string;
+    requestId?: string;
+}
+interface SignalAPIErrorBody {
+    error?: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+declare class SignalAPIError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | null;
+    readonly details: unknown;
+    constructor(message: string, status: number, code: string, requestId: string | null, details?: unknown);
+    get isRetriable(): boolean;
+}
+/**
+ * A generic, source-scoped publisher. It emits facts only; it cannot name a
+ * Monitor, Commitment, Agent, workspace, or execution policy.
+ */
+declare class SignalPublisher {
+    readonly endpoint: string;
+    readonly source: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly defaultHeaders: Record<string, string>;
+    private readonly token;
+    private readonly fetchImplementation;
+    private readonly traceContextProvider?;
+    constructor(options: SignalPublisherOptions);
+    create<TData extends JsonValue>(input: SignalEmitInput<TData>): SignalEnvelope<TData>;
+    emit<TData extends JsonValue>(input: SignalEmitInput<TData>): Promise<SignalReceipt>;
+    publish<TData extends JsonValue>(event: SignalEnvelope<TData>): Promise<SignalReceipt>;
+}
+
+export { type CreateSignalSourceResult, type JsonObject, type JsonPrimitive, type JsonValue, type PublicSignalSource, type PublicSignalSourceCredential, type RotateSignalSourceCredentialResult, SIGNAL_API_VERSION, SIGNAL_CLOUDEVENTS_CONTENT_TYPE, SignalAPIError, type SignalAPIErrorBody, type SignalCardinality, SignalContractError, type SignalCredentialKind, type SignalCredentialStatus, type SignalEmitInput, type SignalEnvelope, type SignalExtensions, type SignalFieldClassification, type SignalFieldDataType, type SignalFieldDefinition, SignalPublisher, type SignalPublisherOptions, type SignalReceipt, type SignalSchemaPolicy, type SignalSourceCredentialGrant, type SignalSourceRateLimit, type SignalSourceRetentionPolicy, type SignalSourceStatus, type SignalSourceTransport, type SignalTraceContext, type SignalTypeDefinition, type SignalValidationFailure, type SignalValidationIssue, type SignalValidationResult, type SignalValidationSuccess, createSignalEnvelope, parseSignalEnvelope, parseSignalTypeDefinition, validateSignalEnvelope, validateSignalTypeDefinition };

package/dist/index.d.ts

@@ -0,0 +1,254 @@
+/** CloudEvents structured-mode media type accepted by the Signal API. */
+declare const SIGNAL_CLOUDEVENTS_CONTENT_TYPE = "application/cloudevents+json";
+declare const SIGNAL_API_VERSION = "v1";
+declare const CLOUD_EVENTS_V1: "1.0";
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * Extension attributes are intentionally limited to normal CloudEvents extension
+ * names. They cannot carry source identity, authorization, Monitor, Commitment,
+ * or Agent selection data.
+ */
+type SignalExtensions = Record<string, JsonPrimitive>;
+/**
+ * The public v1 Signal envelope. It is CloudEvents 1.0 in structured JSON mode.
+ * `source + id` is the occurrence identity used for deduplication.
+ */
+interface SignalEnvelope<TData extends JsonValue = JsonValue> {
+    specversion: typeof CLOUD_EVENTS_V1;
+    id: string;
+    source: string;
+    type: string;
+    subject?: string;
+    time: string;
+    datacontenttype: 'application/json';
+    /** Immutable URI for the source-reviewed payload schema. Required because
+     * server acceptance is bound to a registered (type, dataschema) pair. */
+    dataschema: string;
+    data: TData;
+    traceparent?: string;
+    tracestate?: string;
+    [extension: string]: unknown;
+}
+/** A trace context is evidence correlation only; it is never authorization. */
+interface SignalTraceContext {
+    traceparent: string;
+    tracestate?: string;
+}
+interface SignalEmitInput<TData extends JsonValue = JsonValue> {
+    /** Stable across a caller's retries. A UUID is generated when omitted. */
+    id?: string;
+    type: string;
+    subject?: string;
+    /** Defaults to the publisher's current UTC time. */
+    time?: string | Date;
+    /** Immutable schema URI registered for this Signal type. */
+    dataschema: string;
+    data: TData;
+    extensions?: SignalExtensions;
+}
+interface SignalValidationIssue {
+    path: string;
+    code: 'required' | 'type' | 'format' | 'value' | 'unsupported' | 'reserved_attribute' | 'unsafe_extension';
+    message: string;
+}
+interface SignalValidationSuccess<T> {
+    ok: true;
+    value: T;
+}
+interface SignalValidationFailure {
+    ok: false;
+    issues: SignalValidationIssue[];
+}
+type SignalValidationResult<T> = SignalValidationSuccess<T> | SignalValidationFailure;
+declare class SignalContractError extends TypeError {
+    readonly issues: readonly SignalValidationIssue[];
+    constructor(message: string, issues: readonly SignalValidationIssue[]);
+}
+/**
+ * Validates the generic public envelope only. Source credential binding,
+ * registered type/schema checks, redaction, quotas, and payload limits are
+ * server-owned policies and intentionally do not live in the publisher SDK.
+ */
+declare function validateSignalEnvelope<TData extends JsonValue = JsonValue>(input: unknown): SignalValidationResult<SignalEnvelope<TData>>;
+declare function parseSignalEnvelope<TData extends JsonValue = JsonValue>(input: unknown): SignalEnvelope<TData>;
+declare function createSignalEnvelope<TData extends JsonValue = JsonValue>(source: string, input: SignalEmitInput<TData>, traceContext?: SignalTraceContext): SignalEnvelope<TData>;
+type SignalSourceTransport = 'sdk' | 'direct_api' | 'webhook' | 'oauth_connector' | 'otel' | 'pull_connector';
+type SignalSourceStatus = 'active' | 'paused' | 'disabled';
+type SignalCredentialKind = 'bearer_token' | 'webhook_hmac';
+type SignalCredentialStatus = 'active' | 'revoked' | 'expired';
+type SignalFieldDataType = 'string' | 'number' | 'integer' | 'boolean' | 'timestamp' | 'uri';
+type SignalFieldClassification = 'filterable' | 'groupable' | 'displayable' | 'sensitive' | 'evidence_only';
+type SignalCardinality = 'low' | 'bounded' | 'high';
+/** A safe, schema-declared field. The field name is not an arbitrary JSONPath. */
+interface SignalFieldDefinition {
+    name: string;
+    displayName: string;
+    dataType: SignalFieldDataType;
+    classifications: readonly SignalFieldClassification[];
+    required?: boolean;
+    cardinality: SignalCardinality;
+    maxLength?: number;
+    description?: string;
+}
+interface SignalTypeDefinition {
+    type: string;
+    dataschema: string;
+    displayName: string;
+    description: string;
+    subjectKinds: readonly string[];
+    fields: readonly SignalFieldDefinition[];
+    /** Existing Monitors pin to this range; breaking changes require a new type major. */
+    compatibility: 'backward_compatible_additions';
+    deprecatedAt?: string;
+    migrationGuide?: string;
+}
+/**
+ * Size and shape limits applied to an accepted Signal. These are returned by
+ * the management API so a producer can adapt before the delivery endpoint
+ * rejects an oversized payload.
+ */
+interface SignalSchemaPolicy {
+    maxEventBytes: number;
+    maxDataBytes: number;
+    maxDataDepth: number;
+    maxDataFields: number;
+}
+/** The per-source delivery allowance enforced by the Signal API. */
+interface SignalSourceRateLimit {
+    maxPerMinute: number;
+}
+/** The retention boundary advertised for normalized Signal records. */
+interface SignalSourceRetentionPolicy {
+    normalizedSignalDays: number;
+    residency?: string;
+}
+interface PublicSignalSourcePolicy {
+    limits: SignalSchemaPolicy;
+    rateLimit: SignalSourceRateLimit;
+    redaction: {
+        additionalSensitiveKeys: readonly string[];
+        retainTracestate: boolean;
+    };
+    retention: SignalSourceRetentionPolicy;
+}
+/** Safe credential metadata returned by normal source reads. It never includes secret material. */
+interface PublicSignalSourceCredential {
+    id: string;
+    credentialId: string;
+    sourceId: string;
+    kind: SignalCredentialKind;
+    status: SignalCredentialStatus;
+    label: string;
+    algorithm: 'bearer-token' | 'hmac-sha256';
+    notBefore: string;
+    createdAt: string;
+    lastUsedAt?: string;
+    expiresAt?: string;
+    revokedAt?: string;
+    revokeReason?: string;
+    lastRotatedAt?: string;
+}
+/**
+ * Secret material appears only on credential creation or rotation. Do not
+ * persist or log this object; retrieve future state through the public shape.
+ */
+interface SignalSourceCredentialGrant {
+    credential: PublicSignalSourceCredential;
+    secret: string;
+    secretKind: 'bearer_token' | 'webhook_hmac';
+    shownOnce: true;
+}
+interface PublicSignalSource {
+    sourceId: string;
+    workspaceId: string;
+    label: string;
+    cloudEventSource: string;
+    transport: SignalSourceTransport;
+    status: SignalSourceStatus;
+    typeDefinitions: readonly (SignalTypeDefinition & {
+        schemaVersion: string;
+        enabled: boolean;
+    })[];
+    credentialCount: number;
+    policy: PublicSignalSourcePolicy;
+    health: {
+        lastAcceptedAt?: string;
+        lastRejectedAt?: string;
+        lastErrorCode?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateSignalSourceResult {
+    source: PublicSignalSource;
+    credential?: SignalSourceCredentialGrant;
+}
+interface RotateSignalSourceCredentialResult {
+    credential: SignalSourceCredentialGrant;
+}
+declare function validateSignalTypeDefinition(input: unknown): SignalValidationResult<SignalTypeDefinition>;
+declare function parseSignalTypeDefinition(input: unknown): SignalTypeDefinition;
+
+interface SignalPublisherOptions {
+    /** The full ingestion URL, normally `https://api.oversky.ai/v1/signals`. */
+    endpoint: string;
+    /** The Signal Source's canonical CloudEvents source URI. */
+    source: string;
+    /** Source-scoped bearer token. Do not reuse a user API key. */
+    token: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    maxRetries?: number;
+    defaultHeaders?: Record<string, string>;
+    /** Optional bridge to OpenTelemetry or another W3C Trace Context provider. */
+    traceContextProvider?: () => SignalTraceContext | undefined;
+}
+interface SignalReceipt {
+    receiptId: string;
+    sourceId: string;
+    canonicalSource: string;
+    eventId: string;
+    outcome: 'accepted' | 'duplicate';
+    processingStatus: 'pending' | 'processing' | 'completed';
+    receivedAt: string;
+    requestId?: string;
+}
+interface SignalAPIErrorBody {
+    error?: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+declare class SignalAPIError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | null;
+    readonly details: unknown;
+    constructor(message: string, status: number, code: string, requestId: string | null, details?: unknown);
+    get isRetriable(): boolean;
+}
+/**
+ * A generic, source-scoped publisher. It emits facts only; it cannot name a
+ * Monitor, Commitment, Agent, workspace, or execution policy.
+ */
+declare class SignalPublisher {
+    readonly endpoint: string;
+    readonly source: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly defaultHeaders: Record<string, string>;
+    private readonly token;
+    private readonly fetchImplementation;
+    private readonly traceContextProvider?;
+    constructor(options: SignalPublisherOptions);
+    create<TData extends JsonValue>(input: SignalEmitInput<TData>): SignalEnvelope<TData>;
+    emit<TData extends JsonValue>(input: SignalEmitInput<TData>): Promise<SignalReceipt>;
+    publish<TData extends JsonValue>(event: SignalEnvelope<TData>): Promise<SignalReceipt>;
+}
+
+export { type CreateSignalSourceResult, type JsonObject, type JsonPrimitive, type JsonValue, type PublicSignalSource, type PublicSignalSourceCredential, type RotateSignalSourceCredentialResult, SIGNAL_API_VERSION, SIGNAL_CLOUDEVENTS_CONTENT_TYPE, SignalAPIError, type SignalAPIErrorBody, type SignalCardinality, SignalContractError, type SignalCredentialKind, type SignalCredentialStatus, type SignalEmitInput, type SignalEnvelope, type SignalExtensions, type SignalFieldClassification, type SignalFieldDataType, type SignalFieldDefinition, SignalPublisher, type SignalPublisherOptions, type SignalReceipt, type SignalSchemaPolicy, type SignalSourceCredentialGrant, type SignalSourceRateLimit, type SignalSourceRetentionPolicy, type SignalSourceStatus, type SignalSourceTransport, type SignalTraceContext, type SignalTypeDefinition, type SignalValidationFailure, type SignalValidationIssue, type SignalValidationResult, type SignalValidationSuccess, createSignalEnvelope, parseSignalEnvelope, parseSignalTypeDefinition, validateSignalEnvelope, validateSignalTypeDefinition };