@skrr-ai/signals 0.1.0

package/dist/index.cjs

@@ -0,0 +1,563 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SIGNAL_API_VERSION: () => SIGNAL_API_VERSION,
+  SIGNAL_CLOUDEVENTS_CONTENT_TYPE: () => SIGNAL_CLOUDEVENTS_CONTENT_TYPE,
+  SignalAPIError: () => SignalAPIError,
+  SignalContractError: () => SignalContractError,
+  SignalPublisher: () => SignalPublisher,
+  createSignalEnvelope: () => createSignalEnvelope,
+  parseSignalEnvelope: () => parseSignalEnvelope,
+  parseSignalTypeDefinition: () => parseSignalTypeDefinition,
+  validateSignalEnvelope: () => validateSignalEnvelope,
+  validateSignalTypeDefinition: () => validateSignalTypeDefinition
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/contracts.ts
+var import_cloudevents = require("cloudevents");
+var SIGNAL_CLOUDEVENTS_CONTENT_TYPE = "application/cloudevents+json";
+var SIGNAL_API_VERSION = "v1";
+var CLOUD_EVENTS_V1 = "1.0";
+var REQUIRED_CLOUDEVENT_ATTRIBUTES = /* @__PURE__ */ new Set(["specversion", "id", "source", "type"]);
+var STANDARD_CLOUDEVENT_ATTRIBUTES = /* @__PURE__ */ new Set([
+  ...REQUIRED_CLOUDEVENT_ATTRIBUTES,
+  "subject",
+  "time",
+  "datacontenttype",
+  "dataschema",
+  "data",
+  "data_base64"
+]);
+var LEGACY_CLOUDEVENT_ATTRIBUTES = /* @__PURE__ */ new Set(["datacontentencoding", "schemaurl"]);
+var TYPE_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9][a-z0-9-]*)+\.v[1-9][0-9]*$/;
+var FIELD_NAME_PATTERN = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/;
+var EXTENSION_NAME_PATTERN = /^[a-z][a-z0-9]{0,19}$/;
+var RFC3339_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+var SignalContractError = class extends TypeError {
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.name = "SignalContractError";
+    this.issues = issues;
+  }
+};
+function validateSignalEnvelope(input) {
+  const issues = [];
+  if (!isRecord(input)) {
+    return invalid([{ path: "$", code: "type", message: "Signal must be a JSON object." }]);
+  }
+  if (input.specversion !== CLOUD_EVENTS_V1) {
+    issues.push({
+      path: "$.specversion",
+      code: "value",
+      message: 'Signal must use CloudEvents specversion "1.0".'
+    });
+  }
+  validateNonEmptyString(input.id, "$.id", issues);
+  validateUriReference(input.source, "$.source", issues);
+  validateTypeName(input.type, "$.type", issues);
+  if (input.datacontenttype !== "application/json") {
+    issues.push({
+      path: "$.datacontenttype",
+      code: "value",
+      message: 'Signal datacontenttype must be "application/json".'
+    });
+  }
+  if (typeof input.subject !== "undefined") {
+    validateNonEmptyString(input.subject, "$.subject", issues);
+  }
+  if (!isRfc3339Timestamp(input.time)) {
+    issues.push({
+      path: "$.time",
+      code: "format",
+      message: "Signal time must be an RFC 3339 timestamp with a timezone."
+    });
+  }
+  validateAbsoluteUri(input.dataschema, "$.dataschema", issues);
+  if (!Object.prototype.hasOwnProperty.call(input, "data")) {
+    issues.push({ path: "$.data", code: "required", message: "Signal data is required." });
+  } else if (!isJsonValue(input.data)) {
+    issues.push({ path: "$.data", code: "type", message: "Signal data must be JSON-compatible." });
+  }
+  if (typeof input.data_base64 !== "undefined") {
+    issues.push({
+      path: "$.data_base64",
+      code: "unsupported",
+      message: "Binary CloudEvents data is not supported by the Signal API."
+    });
+  }
+  for (const key of LEGACY_CLOUDEVENT_ATTRIBUTES) {
+    if (typeof input[key] !== "undefined") {
+      issues.push({
+        path: `$.${key}`,
+        code: "unsupported",
+        message: `${key} is a legacy CloudEvents attribute and is not supported by the Signal API.`
+      });
+    }
+  }
+  for (const [key, value] of Object.entries(input)) {
+    if (STANDARD_CLOUDEVENT_ATTRIBUTES.has(key)) continue;
+    if (typeof value === "undefined") continue;
+    validateExtension(key, value, issues);
+  }
+  if (issues.length > 0) return invalid(issues);
+  try {
+    new import_cloudevents.CloudEvent(input).validate();
+  } catch (error) {
+    const message = error instanceof import_cloudevents.ValidationError ? error.message : "Invalid CloudEvents envelope.";
+    return invalid([{ path: "$", code: "format", message }]);
+  }
+  return {
+    ok: true,
+    value: input
+  };
+}
+function parseSignalEnvelope(input) {
+  const result = validateSignalEnvelope(input);
+  if (result.ok) return result.value;
+  throw new SignalContractError("Invalid Signal envelope.", result.issues);
+}
+function createSignalEnvelope(source, input, traceContext) {
+  const extensions = input.extensions ?? {};
+  for (const key of Object.keys(extensions)) {
+    if (STANDARD_CLOUDEVENT_ATTRIBUTES.has(key) || LEGACY_CLOUDEVENT_ATTRIBUTES.has(key) || key === "traceparent" || key === "tracestate") {
+      throw new SignalContractError("Invalid Signal extension.", [
+        {
+          path: `$.extensions.${key}`,
+          code: "reserved_attribute",
+          message: `${key} is a reserved CloudEvents or trace-context attribute.`
+        }
+      ]);
+    }
+  }
+  const event = new import_cloudevents.CloudEvent({
+    specversion: CLOUD_EVENTS_V1,
+    id: input.id ?? globalThis.crypto.randomUUID(),
+    source,
+    type: input.type,
+    subject: input.subject,
+    time: normalizeTime(input.time),
+    datacontenttype: "application/json",
+    dataschema: input.dataschema,
+    data: input.data,
+    ...extensions,
+    ...traceContext ? { traceparent: traceContext.traceparent } : {},
+    ...traceContext?.tracestate ? { tracestate: traceContext.tracestate } : {}
+  });
+  return parseSignalEnvelope(omitUndefined(event.toJSON()));
+}
+function validateSignalTypeDefinition(input) {
+  const issues = [];
+  if (!isRecord(input)) {
+    return invalid([
+      { path: "$", code: "type", message: "Signal type definition must be an object." }
+    ]);
+  }
+  validateTypeName(input.type, "$.type", issues);
+  validateAbsoluteUri(input.dataschema, "$.dataschema", issues);
+  validateNonEmptyString(input.displayName, "$.displayName", issues);
+  validateNonEmptyString(input.description, "$.description", issues);
+  if (!Array.isArray(input.subjectKinds) || input.subjectKinds.length === 0) {
+    issues.push({
+      path: "$.subjectKinds",
+      code: "required",
+      message: "At least one subject kind is required."
+    });
+  } else {
+    for (const [index, value] of input.subjectKinds.entries()) {
+      validateNonEmptyString(value, `$.subjectKinds[${index}]`, issues);
+    }
+  }
+  if (input.compatibility !== "backward_compatible_additions") {
+    issues.push({
+      path: "$.compatibility",
+      code: "value",
+      message: 'Signal type compatibility must be "backward_compatible_additions".'
+    });
+  }
+  validateTypeFields(input.fields, issues);
+  if (issues.length > 0) return invalid(issues);
+  return { ok: true, value: input };
+}
+function parseSignalTypeDefinition(input) {
+  const result = validateSignalTypeDefinition(input);
+  if (result.ok) return result.value;
+  throw new SignalContractError("Invalid Signal type definition.", result.issues);
+}
+function validateTypeFields(input, issues) {
+  if (!Array.isArray(input) || input.length === 0) {
+    issues.push({ path: "$.fields", code: "required", message: "At least one field is required." });
+    return;
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const [index, field] of input.entries()) {
+    const path = `$.fields[${index}]`;
+    if (!isRecord(field)) {
+      issues.push({ path, code: "type", message: "Field definition must be an object." });
+      continue;
+    }
+    if (typeof field.name !== "string" || !FIELD_NAME_PATTERN.test(field.name)) {
+      issues.push({
+        path: `${path}.name`,
+        code: "format",
+        message: "Field name must be a dot-separated, declared field name, not JSONPath."
+      });
+    } else if (names.has(field.name)) {
+      issues.push({ path: `${path}.name`, code: "value", message: "Field names must be unique." });
+    } else {
+      names.add(field.name);
+    }
+    validateNonEmptyString(field.displayName, `${path}.displayName`, issues);
+    if (!isSignalFieldDataType(field.dataType)) {
+      issues.push({
+        path: `${path}.dataType`,
+        code: "value",
+        message: "Unsupported field data type."
+      });
+    }
+    if (!isSignalCardinality(field.cardinality)) {
+      issues.push({
+        path: `${path}.cardinality`,
+        code: "value",
+        message: "Unsupported cardinality."
+      });
+    }
+    if (!Array.isArray(field.classifications) || field.classifications.length === 0) {
+      issues.push({
+        path: `${path}.classifications`,
+        code: "required",
+        message: "At least one field classification is required."
+      });
+    } else {
+      for (const [classificationIndex, classification] of field.classifications.entries()) {
+        if (!isSignalFieldClassification(classification)) {
+          issues.push({
+            path: `${path}.classifications[${classificationIndex}]`,
+            code: "value",
+            message: "Unsupported field classification."
+          });
+        }
+      }
+      if (field.cardinality === "high" && field.classifications.includes("groupable")) {
+        issues.push({
+          path: `${path}.classifications`,
+          code: "unsafe_extension",
+          message: "High-cardinality fields cannot be groupable."
+        });
+      }
+      if (field.classifications.includes("sensitive") && field.classifications.includes("groupable")) {
+        issues.push({
+          path: `${path}.classifications`,
+          code: "unsafe_extension",
+          message: "Sensitive fields cannot be groupable."
+        });
+      }
+    }
+  }
+}
+function isSignalFieldDataType(value) {
+  return ["string", "number", "integer", "boolean", "timestamp", "uri"].includes(value);
+}
+function isSignalCardinality(value) {
+  return ["low", "bounded", "high"].includes(value);
+}
+function isSignalFieldClassification(value) {
+  return ["filterable", "groupable", "displayable", "sensitive", "evidence_only"].includes(
+    value
+  );
+}
+function validateExtension(key, value, issues) {
+  if (!EXTENSION_NAME_PATTERN.test(key)) {
+    issues.push({
+      path: `$.${key}`,
+      code: "format",
+      message: "CloudEvents extension names must be lowercase alphanumeric identifiers up to 20 characters."
+    });
+  }
+  if (!isJsonPrimitive(value)) {
+    issues.push({
+      path: `$.${key}`,
+      code: "type",
+      message: "Signal extension values must be JSON primitives."
+    });
+  }
+}
+function validateTypeName(value, path, issues) {
+  if (typeof value !== "string" || !TYPE_PATTERN.test(value)) {
+    issues.push({
+      path,
+      code: "format",
+      message: 'Signal type must be reverse-DNS style and end with a major version such as ".v1".'
+    });
+  }
+}
+function validateNonEmptyString(value, path, issues) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    issues.push({ path, code: "required", message: "A non-empty string is required." });
+  }
+}
+function validateUriReference(value, path, issues) {
+  if (typeof value !== "string" || value.trim().length === 0 || /\s/.test(value)) {
+    issues.push({ path, code: "format", message: "A non-empty URI-reference is required." });
+  }
+}
+function validateAbsoluteUri(value, path, issues) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    issues.push({ path, code: "format", message: "An absolute URI is required." });
+    return;
+  }
+  try {
+    const uri = new URL(value);
+    if (!uri.protocol) throw new Error("missing protocol");
+  } catch {
+    issues.push({ path, code: "format", message: "An absolute URI is required." });
+  }
+}
+function isRfc3339Timestamp(value) {
+  return typeof value === "string" && RFC3339_TIMESTAMP_PATTERN.test(value) && !Number.isNaN(Date.parse(value));
+}
+function normalizeTime(value) {
+  if (typeof value === "undefined") return (/* @__PURE__ */ new Date()).toISOString();
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new SignalContractError("Invalid Signal time.", [
+        { path: "$.time", code: "format", message: "Date must be valid." }
+      ]);
+    }
+    return value.toISOString();
+  }
+  return value;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isJsonPrimitive(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isJsonValue(value) {
+  if (isJsonPrimitive(value)) return Number.isFinite(value) || typeof value !== "number";
+  if (Array.isArray(value)) return value.every(isJsonValue);
+  if (!isRecord(value)) return false;
+  return Object.values(value).every(isJsonValue);
+}
+function invalid(issues) {
+  return { ok: false, issues };
+}
+function omitUndefined(input) {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, value]) => typeof value !== "undefined")
+  );
+}
+
+// src/publisher.ts
+var import_cloudevents2 = require("cloudevents");
+var SignalAPIError = class extends Error {
+  status;
+  code;
+  requestId;
+  details;
+  constructor(message, status, code, requestId, details) {
+    super(`[${status} ${code}] ${message}`);
+    this.name = "SignalAPIError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.details = details;
+  }
+  get isRetriable() {
+    return this.status === 0 || this.status === 408 || this.status === 429 || this.status >= 500 && this.status <= 599;
+  }
+};
+var SignalPublisher = class {
+  endpoint;
+  source;
+  timeoutMs;
+  maxRetries;
+  defaultHeaders;
+  token;
+  fetchImplementation;
+  traceContextProvider;
+  constructor(options) {
+    if (!options.endpoint) throw new Error("[OverSky Signals] endpoint is required.");
+    if (!options.source) throw new Error("[OverSky Signals] source is required.");
+    if (!options.token) throw new Error("[OverSky Signals] source-scoped token is required.");
+    this.endpoint = options.endpoint.replace(/\/$/, "");
+    this.source = options.source;
+    this.token = options.token;
+    this.timeoutMs = options.timeoutMs ?? 15e3;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.fetchImplementation = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.traceContextProvider = options.traceContextProvider;
+  }
+  create(input) {
+    return createSignalEnvelope(this.source, input, this.traceContextProvider?.());
+  }
+  async emit(input) {
+    return this.publish(this.create(input));
+  }
+  async publish(event) {
+    if (event.source !== this.source) {
+      throw new SignalAPIError(
+        "The event source must match this publisher source.",
+        0,
+        "source_mismatch",
+        null
+      );
+    }
+    const message = import_cloudevents2.HTTP.structured(new import_cloudevents2.CloudEvent(event));
+    const headers = {
+      Authorization: `Bearer ${this.token}`,
+      Accept: "application/json",
+      "User-Agent": "@skrr-ai/signals/0.1.0",
+      ...toStringHeaders(message.headers),
+      ...this.defaultHeaders
+    };
+    if (event.traceparent) headers.traceparent = event.traceparent;
+    if (event.tracestate) headers.tracestate = event.tracestate;
+    let attempt = 0;
+    for (; ; ) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      let response;
+      try {
+        response = await this.fetchImplementation(this.endpoint, {
+          method: "POST",
+          headers,
+          body: typeof message.body === "string" ? message.body : JSON.stringify(message.body),
+          signal: controller.signal
+        });
+      } catch (error) {
+        clearTimeout(timer);
+        const caught = error;
+        const apiError2 = new SignalAPIError(
+          caught?.message ?? "Network error while publishing Signal.",
+          0,
+          caught?.name === "AbortError" ? "timeout" : "network_error",
+          null
+        );
+        if (apiError2.isRetriable && attempt < this.maxRetries) {
+          await sleep(backoffMs(attempt));
+          attempt += 1;
+          continue;
+        }
+        throw apiError2;
+      } finally {
+        clearTimeout(timer);
+      }
+      if (response.ok) {
+        const body = await response.json();
+        return parseSignalReceipt(body, response.headers.get("x-request-id"));
+      }
+      const apiError = await parseSignalAPIError(response);
+      if (apiError.isRetriable && attempt < this.maxRetries) {
+        const retryAfterMs = retryAfterMilliseconds(response.headers.get("retry-after"));
+        await sleep(retryAfterMs ?? backoffMs(attempt));
+        attempt += 1;
+        continue;
+      }
+      throw apiError;
+    }
+  }
+};
+function parseSignalReceipt(input, requestId) {
+  if (!isRecord2(input)) {
+    throw new SignalAPIError(
+      "Signal API returned an invalid receipt.",
+      502,
+      "invalid_receipt",
+      requestId
+    );
+  }
+  const outcome = input.outcome;
+  const processingStatus = input.processingStatus;
+  if (typeof input.receiptId !== "string" || typeof input.sourceId !== "string" || typeof input.canonicalSource !== "string" || typeof input.eventId !== "string" || outcome !== "accepted" && outcome !== "duplicate" || processingStatus !== "pending" && processingStatus !== "processing" && processingStatus !== "completed" || typeof input.receivedAt !== "string") {
+    throw new SignalAPIError(
+      "Signal API returned an invalid receipt.",
+      502,
+      "invalid_receipt",
+      requestId
+    );
+  }
+  return {
+    receiptId: input.receiptId,
+    sourceId: input.sourceId,
+    canonicalSource: input.canonicalSource,
+    eventId: input.eventId,
+    outcome,
+    processingStatus,
+    receivedAt: input.receivedAt,
+    ...requestId ? { requestId } : {}
+  };
+}
+async function parseSignalAPIError(response) {
+  let body = {};
+  try {
+    body = await response.json();
+  } catch {
+  }
+  return new SignalAPIError(
+    body.error?.message ?? response.statusText ?? "Signal API request failed.",
+    response.status,
+    body.error?.code ?? `http_${response.status}`,
+    response.headers.get("x-request-id"),
+    body.error?.details
+  );
+}
+function toStringHeaders(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).filter((entry) => typeof entry[1] !== "undefined").map(([key, value]) => [key, Array.isArray(value) ? value.join(", ") : value])
+  );
+}
+function retryAfterMilliseconds(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const dateMilliseconds = Date.parse(value);
+  if (Number.isNaN(dateMilliseconds)) return void 0;
+  return Math.max(0, dateMilliseconds - Date.now());
+}
+function backoffMs(attempt) {
+  const base = Math.min(250 * 2 ** attempt, 5e3);
+  return base + Math.floor(Math.random() * 125);
+}
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SIGNAL_API_VERSION,
+  SIGNAL_CLOUDEVENTS_CONTENT_TYPE,
+  SignalAPIError,
+  SignalContractError,
+  SignalPublisher,
+  createSignalEnvelope,
+  parseSignalEnvelope,
+  parseSignalTypeDefinition,
+  validateSignalEnvelope,
+  validateSignalTypeDefinition
+});
+//# sourceMappingURL=index.cjs.map