@kortyx/usage-telemetry 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,720 @@
+"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, {
+  classifyUsageError: () => classifyUsageError,
+  createCollectorTransport: () => createCollectorTransport,
+  createPostHogTransport: () => createPostHogTransport,
+  createUsageTelemetry: () => createUsageTelemetry,
+  publicCatalog: () => publicCatalog,
+  sanitizeProperties: () => sanitizeProperties,
+  scale: () => scale
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/catalog.ts
+var operations = [
+  "sdk.initialize",
+  "sdk.registry",
+  "sdk.execute",
+  "sdk.resume",
+  "sdk.chat.admission",
+  "sdk.execution",
+  "sdk.response",
+  "sdk.model",
+  "sdk.tool",
+  "sdk.node",
+  "sdk.parallel",
+  "sdk.child",
+  "sdk.structured",
+  "sdk.complete_response",
+  "sdk.prompt.resolve",
+  "sdk.prompt.refresh",
+  "sdk.eval",
+  "sdk.mcp.connect",
+  "sdk.mcp.discover",
+  "sdk.mcp.close",
+  "sdk.checkpoint.read",
+  "sdk.checkpoint.list",
+  "sdk.checkpoint.fork",
+  "sdk.checkpoint.rollback",
+  "sdk.export",
+  "studio.setup",
+  "studio.connection",
+  "studio.read",
+  "studio.render",
+  "studio.navigation",
+  "studio.inspect",
+  "studio.filter",
+  "studio.saved_view",
+  "studio.live",
+  "studio.prompt",
+  "studio.eval",
+  "studio.review",
+  "studio.settings",
+  "studio.update",
+  "studio.ingest",
+  "cli.topology",
+  "cli.eval"
+];
+var outcomes = [
+  "success",
+  "failed",
+  "cancelled",
+  "suspended",
+  "denied",
+  "limit_reached",
+  "quality_failed",
+  "ungraded"
+];
+var publicCatalog = {
+  products: ["sdk", "oss_studio"],
+  operations,
+  properties: {
+    phase: [
+      "admission",
+      "execution",
+      "delivery",
+      "parse",
+      "network",
+      "http",
+      "configuration",
+      "preflight",
+      "state",
+      "pull",
+      "ports",
+      "compose",
+      "rollback",
+      "backup",
+      "migration",
+      "health"
+    ],
+    source: [
+      "memory",
+      "file",
+      "custom",
+      "local",
+      "studio",
+      "cache",
+      "fallback",
+      "eval",
+      "mcp",
+      "native"
+    ],
+    storage: ["in-memory", "redis", "postgres", "custom"],
+    calling_mode: ["direct", "model"],
+    provider: [
+      "openai",
+      "anthropic",
+      "google",
+      "mistral",
+      "groq",
+      "deepseek",
+      "openrouter"
+    ],
+    transport: ["stdio", "sse", "http", "custom"],
+    format: [
+      "text",
+      "json",
+      "json_schema",
+      "set",
+      "append",
+      "text-delta",
+      "final"
+    ],
+    resource: [
+      "runs",
+      "sessions",
+      "interrupts",
+      "workflows",
+      "prompts",
+      "evals",
+      "diagnostics",
+      "settings",
+      "home"
+    ],
+    surface: [
+      "runs",
+      "sessions",
+      "interrupts",
+      "workflows",
+      "prompts",
+      "evals",
+      "settings",
+      "other"
+    ],
+    action: [
+      "view",
+      "select",
+      "retry",
+      "first_use",
+      "observed",
+      "copy",
+      "create",
+      "draft",
+      "save",
+      "discard-draft",
+      "update",
+      "promote",
+      "review",
+      "policy",
+      "tag-set",
+      "tag-remove",
+      "bulk-update",
+      "category-create",
+      "category-update",
+      "category-delete",
+      "group-create",
+      "group-update",
+      "group-delete",
+      "import",
+      "export",
+      "launch",
+      "cancel",
+      "compare",
+      "inspect",
+      "clear",
+      "apply",
+      "delete",
+      "enable",
+      "disable",
+      "manual_refresh",
+      "fallback_refresh",
+      "refresh",
+      "change"
+    ],
+    tab: [
+      "overview",
+      "trace",
+      "events",
+      "model-io",
+      "calls",
+      "feedback",
+      "content",
+      "versions",
+      "reviews",
+      "usage",
+      "diff",
+      "cases",
+      "results",
+      "definition"
+    ],
+    origin: ["foreground", "background", "server", "browser", "cli"],
+    status: [
+      "empty",
+      "nonempty",
+      "off",
+      "connecting",
+      "live",
+      "reconnecting",
+      "paused",
+      "running",
+      "completed",
+      "failed",
+      "interrupted",
+      "pending",
+      "expired"
+    ],
+    filter: [
+      "search",
+      "status",
+      "provider",
+      "model",
+      "environment",
+      "version",
+      "duration",
+      "cost",
+      "tokens",
+      "time",
+      "sort",
+      "other"
+    ],
+    scale: ["1", "2-5", "6-20", "21-100", "101+"],
+    error_category: [
+      "configuration",
+      "provider",
+      "validation",
+      "domain",
+      "workflow",
+      "persistence",
+      "request",
+      "transport",
+      "internal",
+      "unknown"
+    ],
+    http_status: [
+      "400",
+      "401",
+      "403",
+      "404",
+      "409",
+      "413",
+      "422",
+      "429",
+      "500",
+      "502",
+      "503",
+      "504"
+    ],
+    prompts: "boolean",
+    observability: "boolean",
+    tools: "boolean",
+    streaming: "boolean",
+    requested_streaming: "boolean",
+    executed: "boolean",
+    cache: "boolean",
+    reused: "boolean",
+    continue_on_disconnect: "boolean",
+    write_available: "boolean"
+  },
+  // Built-in contracts only; application codes and provider response text are excluded.
+  errorCodes: [
+    "EXECUTION_FAILED",
+    "INVALID_REQUEST",
+    "INVALID_RESUME",
+    "INVALID_RESPONSE",
+    "INVALID_SESSION",
+    "RESUME_MISMATCH",
+    "RESUME_FAILED",
+    "CONTRACT_MISMATCH",
+    "INVALID_INPUT",
+    "INVALID_OUTPUT",
+    "MISSING_CONTRACT",
+    "UNKNOWN_WORKFLOW",
+    "DOMAIN_ERROR",
+    "PERSISTENCE_ERROR",
+    "WORKFLOW_CONTRACT_ERROR",
+    "PROVIDER_REFUSAL",
+    "PROVIDER_HTTP_ERROR",
+    "PROVIDER_INVALID_RESPONSE",
+    "PROVIDER_TRANSPORT_ERROR",
+    "PROVIDER_REQUEST_FAILED",
+    "INVALID_MODEL_JSON",
+    "MODEL_OUTPUT_SCHEMA",
+    "OUTPUT_TRUNCATED",
+    "SCHEMA_VALIDATION",
+    "PARALLEL_FAILED",
+    "EVAL_TIMEOUT",
+    "EVAL_HOOK_FAILED",
+    "EVAL_INTERRUPT_CLEANUP_FAILED",
+    "PROMPT_SOURCE_NOT_CONFIGURED",
+    "PROMPT_REASON_CONFLICT",
+    "PROMPT_REASON_INVALID",
+    "REASON_OUTPUT_BUDGET_EXHAUSTED",
+    "REASON_OUTPUT_CONTRACT_CORRECTION_EXHAUSTED",
+    "PROMPT_CACHE_INVALID",
+    "PROMPT_ENVIRONMENT_MISMATCH",
+    "PROMPT_EVAL_PIN_CONFLICT",
+    "PROMPT_EVAL_SNAPSHOT_INVALID",
+    "PROMPT_NOT_ASSIGNED",
+    "PROMPT_NOT_FOUND",
+    "PROMPT_NOT_REGISTERED",
+    "PROMPT_PIN_MISMATCH",
+    "PROMPT_REFERENCE_DUPLICATE",
+    "PROMPT_SNAPSHOT_INVALID",
+    "PROMPT_SNAPSHOT_LIMIT",
+    "PROMPT_SOURCE_HTTP",
+    "PROMPT_SOURCE_INVALID",
+    "PROMPT_TAG_MISMATCH",
+    "PROMPT_CONTRACT_MISMATCH",
+    "PROMPT_REFERENCE_INVALID",
+    "PROMPT_SCHEMA_INVALID",
+    "PROMPT_VARIABLE_CONFIG_OVERLAP",
+    "PROMPT_VARIABLE_MISSING",
+    "PROMPT_VARIABLE_UNKNOWN",
+    "PROMPT_DEPENDENCY_CYCLE",
+    "PROMPT_DEPENDENCY_MISMATCH",
+    "PROMPT_HASH_MISMATCH",
+    "PROMPT_REFERENCE_LIMIT",
+    "PROMPT_REFERENCE_MISSING",
+    "PROMPT_REFERENCE_ROLE",
+    "STUDIO_PROTOCOL_MISMATCH"
+  ]
+};
+function scale(value) {
+  return value <= 1 ? "1" : value <= 5 ? "2-5" : value <= 20 ? "6-20" : value <= 100 ? "21-100" : "101+";
+}
+
+// src/client.ts
+function property(value, key) {
+  try {
+    if (!value || typeof value !== "object") return void 0;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor && "value" in descriptor ? descriptor.value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function classifyUsageError(error, catalog = publicCatalog) {
+  const name = property(error, "name");
+  const code = property(error, "code") ?? property(property(error, "failure"), "code");
+  if (name === "AbortError" || code === "EXECUTION_CANCELLED")
+    return { outcome: "cancelled", properties: {} };
+  if (code === "EXECUTION_LIMIT_REACHED" || name === "ExecutionLimitReached")
+    return { outcome: "limit_reached", properties: {} };
+  if (name === "GraphInterrupt" || name === "NodeInterrupt" || name === "Interrupt")
+    return { outcome: "suspended", properties: {} };
+  const known = typeof code === "string" && catalog.errorCodes.includes(code);
+  const category = known && code !== "EXECUTION_FAILED" ? property(error, "category") ?? property(property(error, "failure"), "category") ?? "unknown" : "unknown";
+  const status = property(error, "status") ?? property(property(error, "failure"), "status");
+  return {
+    outcome: "failed",
+    properties: {
+      error_code: known ? code : "other",
+      error_category: category,
+      ...typeof status === "number" ? { http_status: String(status) } : {}
+    }
+  };
+}
+function sanitizeProperties(input, catalog = publicCatalog) {
+  const safe = {};
+  for (const [key, rule] of Object.entries(catalog.properties)) {
+    const value = property(input, key);
+    if (value === void 0) continue;
+    if (rule === "boolean") {
+      if (typeof value === "boolean") safe[key] = value;
+    } else if (typeof value === "string")
+      safe[key] = rule.includes(value) ? value : "other";
+  }
+  const code = property(input, "error_code");
+  if (typeof code === "string")
+    safe.error_code = catalog.errorCodes.includes(code) ? code : "other";
+  return safe;
+}
+var durationBounds = [10, 100, 1e3, 1e4, 6e4];
+var noopOperation = { end() {
+}, fail() {
+} };
+function schedule(callback, ms) {
+  const timer = setTimeout(callback, ms);
+  timer.unref?.();
+  return { cancel: () => clearTimeout(timer) };
+}
+function createUsageTelemetry(options) {
+  const catalog = options.catalog ?? publicCatalog;
+  const now = options.now ?? Date.now;
+  const pending = /* @__PURE__ */ new Map();
+  let timer;
+  let flight;
+  let disposed = false;
+  let dropped = 0;
+  let delivered = 0;
+  let hour = Math.floor(now() / 36e5);
+  let sent = 0;
+  const active = () => {
+    try {
+      return !disposed && (options.enabled?.() ?? true);
+    } catch {
+      return false;
+    }
+  };
+  const clear = () => {
+    pending.clear();
+    try {
+      timer?.cancel();
+    } catch {
+    }
+    timer = void 0;
+  };
+  const configured = catalog.products.includes(options.context.product) && /^[a-z][a-z0-9_]{0,31}$/.test(options.context.component) && /^(?:\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?|development|unknown)$/.test(
+    options.context.version
+  ) && options.context.version.length <= 64;
+  const flush = async () => {
+    if (flight) return flight;
+    if (!active() || !configured) {
+      clear();
+      return;
+    }
+    try {
+      timer?.cancel();
+    } catch {
+    }
+    timer = void 0;
+    const records = [...pending.values()];
+    pending.clear();
+    if (!records.length) return;
+    let attempted = records.length;
+    flight = (async () => {
+      try {
+        if (options.debug?.()) {
+          options.inspect?.(records);
+          return;
+        }
+        const currentHour = Math.floor(now() / 36e5);
+        if (hour !== currentHour) {
+          hour = currentHour;
+          sent = 0;
+        }
+        const allowance = Math.max(
+          0,
+          (options.maxRecordsPerHour ?? 120) - sent
+        );
+        const batch = records.slice(0, allowance);
+        dropped += records.length - batch.length;
+        attempted = batch.length;
+        if (!batch.length || !active()) return;
+        const identified = await options.identity();
+        const identity = typeof identified === "string" ? identified : identified.id;
+        if (typeof identified !== "string")
+          for (const record2 of batch) record2.identity_scope = identified.scope;
+        if (!active() || options.debug?.()) return;
+        if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(
+          identity
+        )) {
+          dropped += batch.length;
+          return;
+        }
+        sent += batch.length;
+        await options.transport(batch, identity);
+        delivered += batch.length;
+      } catch {
+        dropped += attempted;
+      }
+    })().finally(() => {
+      flight = void 0;
+      try {
+        if (pending.size && active() && !timer)
+          timer = (options.schedule ?? schedule)(
+            () => void flush(),
+            options.flushIntervalMs ?? 6e4
+          );
+      } catch {
+        clear();
+      }
+    });
+    return flight;
+  };
+  const record = (event, operation, outcome, duration, input) => {
+    try {
+      if (!active()) {
+        clear();
+        return;
+      }
+      if (!configured || !catalog.operations.includes(operation) || !outcomes.includes(outcome))
+        return;
+      const properties = sanitizeProperties(input, catalog);
+      const key = JSON.stringify([event, operation, outcome, properties]);
+      let existing = pending.get(key);
+      if (!existing) {
+        if (pending.size >= (options.maxGroups ?? 64)) {
+          dropped++;
+          return;
+        }
+        existing = {
+          schema_version: 1,
+          event_id: crypto.randomUUID(),
+          timestamp: new Date(now()).toISOString(),
+          event,
+          product: options.context.product,
+          component: options.context.component,
+          version: options.context.version,
+          analytics_environment: options.context.environment ?? "production",
+          runtime_mode: options.context.runtimeMode ?? "unknown",
+          identity_scope: options.context.identityScope ?? "installation",
+          operation,
+          outcome,
+          properties,
+          count: 0,
+          duration_total_ms: 0,
+          duration_buckets: [0, 0, 0, 0, 0, 0]
+        };
+        pending.set(key, existing);
+      }
+      const elapsed = Math.max(
+        0,
+        Math.min(864e5, Number.isFinite(duration) ? duration : 0)
+      );
+      existing.count = Math.min(Number.MAX_SAFE_INTEGER, existing.count + 1);
+      existing.duration_total_ms = Math.min(
+        Number.MAX_SAFE_INTEGER,
+        existing.duration_total_ms + elapsed
+      );
+      const index = durationBounds.findIndex((bound) => elapsed <= bound);
+      const bucket = index === -1 ? durationBounds.length : index;
+      existing.duration_buckets[bucket] = (existing.duration_buckets[bucket] ?? 0) + 1;
+      if (!timer)
+        timer = (options.schedule ?? schedule)(
+          () => void flush(),
+          options.flushIntervalMs ?? 6e4
+        );
+    } catch {
+    }
+  };
+  const start = (operation, properties = {}) => {
+    if (!active()) {
+      clear();
+      return noopOperation;
+    }
+    try {
+      const initial = sanitizeProperties(properties, catalog);
+      const began = now();
+      let ended = false;
+      return {
+        end(outcome = "success", extra = {}) {
+          if (ended) return;
+          ended = true;
+          try {
+            record("usage.operation", operation, outcome, now() - began, {
+              ...initial,
+              ...sanitizeProperties(extra, catalog)
+            });
+          } catch {
+          }
+        },
+        fail(error, extra = {}) {
+          if (ended) return;
+          try {
+            const failure = classifyUsageError(error, catalog);
+            this.end(failure.outcome, {
+              ...sanitizeProperties(extra, catalog),
+              ...failure.properties
+            });
+          } catch {
+          }
+        }
+      };
+    } catch {
+      return noopOperation;
+    }
+  };
+  return {
+    start,
+    feature(operation, properties = {}) {
+      record("usage.feature", operation, "success", 0, properties);
+    },
+    async measure(operation, callback, properties = {}, outcome) {
+      const operationScope = start(operation, properties);
+      try {
+        const result = await callback();
+        let status = "success";
+        try {
+          status = outcome?.(result) ?? status;
+        } catch {
+        }
+        operationScope.end(status);
+        return result;
+      } catch (error) {
+        operationScope.fail(error);
+        throw error;
+      }
+    },
+    flush,
+    dispose() {
+      disposed = true;
+      clear();
+    },
+    stats: () => ({ pending: pending.size, dropped, delivered })
+  };
+}
+
+// src/transport.ts
+function createPostHogTransport(options) {
+  if (!/^phc_[a-zA-Z0-9]+$/.test(options.key))
+    throw new Error("Usage telemetry requires a public PostHog capture key.");
+  const host = new URL(options.host ?? "https://eu.i.posthog.com");
+  if (host.username || host.password || host.search || host.hash)
+    throw new Error(
+      "Usage endpoint must not contain credentials or query parameters."
+    );
+  if (host.protocol !== "https:" && host.hostname !== "localhost" && host.hostname !== "127.0.0.1")
+    throw new Error("Usage telemetry requires HTTPS.");
+  return async (records, identity) => {
+    const batch = records.map((record) => ({
+      event: record.event,
+      timestamp: record.timestamp,
+      distinct_id: identity,
+      uuid: record.event_id,
+      properties: {
+        ...record.properties,
+        schema_version: record.schema_version,
+        product: record.product,
+        component: record.component,
+        version: record.version,
+        analytics_environment: record.analytics_environment,
+        runtime_mode: record.runtime_mode,
+        identity_scope: record.identity_scope,
+        operation: record.operation,
+        outcome: record.outcome,
+        count: record.count,
+        duration_total_ms: record.duration_total_ms,
+        duration_buckets: record.duration_buckets,
+        $process_person_profile: false,
+        $geoip_disable: true,
+        $ip: null
+      }
+    }));
+    const controller = new AbortController();
+    const timeout = setTimeout(
+      () => controller.abort(),
+      options.timeoutMs ?? 2e3
+    );
+    timeout.unref?.();
+    try {
+      const response = await (options.fetch ?? globalThis.fetch)(
+        new URL("/batch/", host),
+        {
+          method: "POST",
+          credentials: "omit",
+          referrerPolicy: "no-referrer",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ api_key: options.key, batch }),
+          signal: controller.signal
+        }
+      );
+      await response.body?.cancel();
+      if (!response.ok) throw new Error("Usage delivery failed.");
+    } finally {
+      clearTimeout(timeout);
+    }
+  };
+}
+function createCollectorTransport(options) {
+  const endpoint = new URL(options.endpoint);
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash)
+    throw new Error(
+      "Usage endpoint must not contain credentials or query parameters."
+    );
+  if (endpoint.protocol !== "https:" && !["localhost", "127.0.0.1"].includes(endpoint.hostname))
+    throw new Error("Usage telemetry requires HTTPS.");
+  return async (records, identity) => {
+    const response = await (options.fetch ?? globalThis.fetch)(endpoint, {
+      method: "POST",
+      credentials: "omit",
+      referrerPolicy: "no-referrer",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ identity, records }),
+      signal: AbortSignal.timeout(2e3)
+    });
+    await response.body?.cancel();
+    if (!response.ok) throw new Error("Usage delivery failed.");
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  classifyUsageError,
+  createCollectorTransport,
+  createPostHogTransport,
+  createUsageTelemetry,
+  publicCatalog,
+  sanitizeProperties,
+  scale
+});
+//# sourceMappingURL=index.js.map