@modainteract/moda-interact-shared 0.2.0 → 0.4.0

package/dist/logging/node.d.ts

@@ -0,0 +1,103 @@
+type NodeLokiLoggingOptions = {
+    serviceName: string;
+    environment: string;
+    serviceNamespace?: string;
+    /**
+     * Explicit Loki base URL.
+     *
+     * Production normally supplies LOKI_URL.
+     */
+    host?: string;
+    /**
+     * Optional Basic Auth override in `username:password` format.
+     *
+     * Prefer separate LOKI_USERNAME/LOKI_PASSWORD environment variables in
+     * deployed services so the composed value never needs to be committed.
+     */
+    basicAuth?: string;
+    /**
+     * Optional additional static headers.
+     *
+     * Never include these in log payloads or error messages.
+     */
+    headers?: Record<string, string>;
+    batching?: boolean;
+    intervalSeconds?: number;
+    timeoutMs?: number;
+    clearOnError?: boolean;
+    /**
+     * Test-only override. In normal service bootstrap, the presence of a Loki
+     * host is sufficient to enable the transport.
+     */
+    forceEnable?: boolean;
+};
+type NodeLokiLoggingRuntime = {
+    enabled: boolean;
+    host: string | null;
+    labels: Readonly<Record<string, string>>;
+    forceFlush: () => Promise<void>;
+    shutdown: () => Promise<void>;
+};
+/**
+ * Installs the direct Grafana Loki destination exactly once per Node process.
+ *
+ * IMPORTANT:
+ * - This module is Node-only.
+ * - It is reached through @modainteract/moda-interact-shared/logging/node.
+ * - Do not import it from Vite/browser/application module graphs.
+ * - The normal ./logging entry contains no Winston/winston-loki imports.
+ */
+declare function initNodeLokiLogging(options: NodeLokiLoggingOptions): NodeLokiLoggingRuntime;
+declare function getNodeLokiLoggingRuntime(): NodeLokiLoggingRuntime | null;
+
+type NodeOpenTelemetryLoggingOptions = {
+    serviceName: string;
+    environment: string;
+    serviceNamespace?: string;
+    /**
+     * Explicit endpoint override. Intended mainly for tests.
+     *
+     * Production normally uses:
+     *   OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
+     * or:
+     *   OTEL_EXPORTER_OTLP_ENDPOINT
+     */
+    endpoint?: string;
+    /** Optional explicit OTLP headers override. */
+    headers?: Record<string, string>;
+    /** Test-only switch. Production should rely on environment configuration. */
+    forceEnable?: boolean;
+};
+type NodeOpenTelemetryLoggingRuntime = {
+    enabled: boolean;
+    endpoint: string | null;
+    forceFlush: () => Promise<void>;
+    shutdown: () => Promise<void>;
+};
+/**
+ * Installs the Node OpenTelemetry LoggerProvider exactly once for this process.
+ *
+ * IMPORTANT:
+ * This module is Node-only. Import and initialize it from the process bootstrap
+ * before framework/application modules are loaded. Do not import this module
+ * through Vite/React/browser bundles.
+ *
+ * Application modules should import only:
+ *
+ *   @modainteract/moda-interact-shared/logging
+ *
+ * Once this provider is installed, createLogger(...) automatically fans safe
+ * canonical log records out to stdout and the OpenTelemetry Logs API.
+ *
+ * Direct Loki delivery, when desired, is independently enabled with:
+ *
+ *   initNodeLokiLogging(...)
+ *
+ * from this same Node-only package entry.
+ */
+declare function initNodeOpenTelemetryLogging(options: NodeOpenTelemetryLoggingOptions): NodeOpenTelemetryLoggingRuntime;
+declare function getNodeOpenTelemetryLoggingRuntime(): NodeOpenTelemetryLoggingRuntime | null;
+declare function resolveLogsEndpoint(explicitEndpoint?: string): string | undefined;
+declare function parseOtlpHeaders(value: string | undefined): Record<string, string> | undefined;
+
+export { type NodeLokiLoggingOptions, type NodeLokiLoggingRuntime, type NodeOpenTelemetryLoggingOptions, type NodeOpenTelemetryLoggingRuntime, getNodeLokiLoggingRuntime, getNodeOpenTelemetryLoggingRuntime, initNodeLokiLogging, initNodeOpenTelemetryLogging, parseOtlpHeaders, resolveLogsEndpoint };

package/dist/logging/node.js

@@ -0,0 +1,18 @@
+import {
+  getNodeLokiLoggingRuntime,
+  getNodeOpenTelemetryLoggingRuntime,
+  initNodeLokiLogging,
+  initNodeOpenTelemetryLogging,
+  parseOtlpHeaders,
+  resolveLogsEndpoint
+} from "../chunk-5JNEZEKV.js";
+import "../chunk-XU4XX7SD.js";
+export {
+  getNodeLokiLoggingRuntime,
+  getNodeOpenTelemetryLoggingRuntime,
+  initNodeLokiLogging,
+  initNodeOpenTelemetryLogging,
+  parseOtlpHeaders,
+  resolveLogsEndpoint
+};
+//# sourceMappingURL=node.js.map

package/dist/logging/node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/observability/bullmq.d.ts

@@ -0,0 +1,10 @@
+import { BullMQOtel } from 'bullmq-otel';
+
+type BullMQTelemetryOptions = {
+    serviceName: string;
+    version?: string;
+    enableMetrics?: boolean;
+};
+declare function createBullMQTelemetry(options: BullMQTelemetryOptions): BullMQOtel;
+
+export { type BullMQTelemetryOptions, createBullMQTelemetry };

package/dist/observability/bullmq.js

@@ -0,0 +1,14 @@
+// src/observability/bullmq.ts
+import { BullMQOtel } from "bullmq-otel";
+function createBullMQTelemetry(options) {
+  return new BullMQOtel({
+    tracerName: options.serviceName,
+    meterName: options.serviceName,
+    version: options.version ?? "unknown",
+    enableMetrics: options.enableMetrics ?? true
+  });
+}
+export {
+  createBullMQTelemetry
+};
+//# sourceMappingURL=bullmq.js.map

package/dist/observability/bullmq.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/observability/bullmq.ts"],"sourcesContent":["import { BullMQOtel } from \"bullmq-otel\";\n\nexport type BullMQTelemetryOptions = {\n  serviceName: string;\n  version?: string;\n  enableMetrics?: boolean;\n};\n\nexport function createBullMQTelemetry(\n  options: BullMQTelemetryOptions,\n): BullMQOtel {\n  return new BullMQOtel({\n    tracerName: options.serviceName,\n    meterName: options.serviceName,\n    version: options.version ?? \"unknown\",\n    enableMetrics: options.enableMetrics ?? true,\n  });\n}"],"mappings":";AAAA,SAAS,kBAAkB;AAQpB,SAAS,sBACd,SACY;AACZ,SAAO,IAAI,WAAW;AAAA,IACpB,YAAY,QAAQ;AAAA,IACpB,WAAW,QAAQ;AAAA,IACnB,SAAS,QAAQ,WAAW;AAAA,IAC5B,eAAe,QAAQ,iBAAiB;AAAA,EAC1C,CAAC;AACH;","names":[]}

package/dist/observability/genai.d.ts

@@ -0,0 +1,10 @@
+type AgentObservation = {
+    agentName: string;
+    provider?: string;
+    model?: string;
+};
+declare function observeConversationTurn<T>(channel: "whatsapp" | "other", work: () => Promise<T>): Promise<T>;
+declare function observeAgentInvocation<T>(observation: AgentObservation, work: () => Promise<T>): Promise<T>;
+declare function observeAgentTool<T>(toolName: string, work: () => Promise<T>): Promise<T>;
+
+export { type AgentObservation, observeAgentInvocation, observeAgentTool, observeConversationTurn };

package/dist/observability/genai.js

@@ -0,0 +1,109 @@
+import {
+  withObservedSpan
+} from "../chunk-XH6XHKXC.js";
+
+// src/observability/genai.ts
+import { metrics } from "@opentelemetry/api";
+var MAX_ATTRIBUTE_LENGTH = 80;
+var meter = metrics.getMeter(
+  "@modainteract/moda-interact-shared/observability/genai"
+);
+var agentDuration = meter.createHistogram(
+  "moda.agent.invocation.duration_ms",
+  { unit: "ms" }
+);
+var agentOperations = meter.createCounter("moda.agent.invocation.operations");
+var toolDuration = meter.createHistogram("moda.agent.tool.duration_ms", {
+  unit: "ms"
+});
+var toolOperations = meter.createCounter("moda.agent.tool.operations");
+var turnDuration = meter.createHistogram(
+  "moda.conversation.turn.duration_ms",
+  { unit: "ms" }
+);
+var turnOperations = meter.createCounter("moda.conversation.turn.operations");
+async function observeConversationTurn(channel, work) {
+  return observeOperation(
+    turnDuration,
+    turnOperations,
+    { channel },
+    () => withObservedSpan(
+      `conversation.turn ${channel}`,
+      { "moda.messaging.channel": channel },
+      work
+    )
+  );
+}
+async function observeAgentInvocation(observation, work) {
+  const agentName = boundedSpanValue(observation.agentName) ?? "unknown";
+  return observeOperation(
+    agentDuration,
+    agentOperations,
+    {},
+    () => withObservedSpan(
+      `invoke_agent ${agentName}`,
+      compact({
+        "gen_ai.operation.name": "invoke_agent",
+        "gen_ai.agent.name": agentName,
+        "gen_ai.provider.name": boundedSpanValue(observation.provider),
+        "gen_ai.request.model": boundedSpanValue(observation.model)
+      }),
+      work
+    )
+  );
+}
+async function observeAgentTool(toolName, work) {
+  const safeToolName = boundedSpanValue(toolName) ?? "unknown";
+  return observeOperation(
+    toolDuration,
+    toolOperations,
+    {},
+    () => withObservedSpan(
+      `execute_tool ${safeToolName}`,
+      {
+        "gen_ai.operation.name": "execute_tool",
+        "gen_ai.tool.name": safeToolName
+      },
+      work
+    )
+  );
+}
+async function observeOperation(duration, operations, attributes, work) {
+  const started = performance.now();
+  let outcome = "error";
+  try {
+    const result = await work();
+    outcome = "success";
+    return result;
+  } finally {
+    recordMetrics(duration, operations, performance.now() - started, {
+      ...attributes,
+      outcome
+    });
+  }
+}
+function recordMetrics(duration, operations, elapsedMilliseconds, attributes) {
+  try {
+    duration.record(elapsedMilliseconds, attributes);
+    operations.add(1, attributes);
+  } catch {
+  }
+}
+function boundedSpanValue(value) {
+  if (value === void 0) return void 0;
+  const bounded = value.trim().slice(0, MAX_ATTRIBUTE_LENGTH);
+  return bounded || void 0;
+}
+function compact(attributes) {
+  return Object.fromEntries(
+    Object.entries(attributes).filter(
+      (entry) => entry[1] !== void 0
+    )
+  );
+}
+export {
+  observeAgentInvocation,
+  observeAgentTool,
+  observeConversationTurn
+};
+//# sourceMappingURL=genai.js.map

package/dist/observability/genai.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/observability/genai.ts"],"sourcesContent":["import { metrics, type Attributes, type Counter, type Histogram } from \"@opentelemetry/api\";\nimport { withObservedSpan } from \"./index.js\";\n\nconst MAX_ATTRIBUTE_LENGTH = 80;\nconst meter = metrics.getMeter(\n  \"@modainteract/moda-interact-shared/observability/genai\",\n);\nconst agentDuration = meter.createHistogram(\n  \"moda.agent.invocation.duration_ms\",\n  { unit: \"ms\" },\n);\nconst agentOperations = meter.createCounter(\"moda.agent.invocation.operations\");\nconst toolDuration = meter.createHistogram(\"moda.agent.tool.duration_ms\", {\n  unit: \"ms\",\n});\nconst toolOperations = meter.createCounter(\"moda.agent.tool.operations\");\nconst turnDuration = meter.createHistogram(\n  \"moda.conversation.turn.duration_ms\",\n  { unit: \"ms\" },\n);\nconst turnOperations = meter.createCounter(\"moda.conversation.turn.operations\");\n\ntype Outcome = \"success\" | \"error\";\n\nexport type AgentObservation = {\n  agentName: string;\n  provider?: string;\n  model?: string;\n};\n\nexport async function observeConversationTurn<T>(\n  channel: \"whatsapp\" | \"other\",\n  work: () => Promise<T>,\n): Promise<T> {\n  return observeOperation(\n    turnDuration,\n    turnOperations,\n    { channel },\n    () => withObservedSpan(\n      `conversation.turn ${channel}`,\n      { \"moda.messaging.channel\": channel },\n      work,\n    ),\n  );\n}\n\nexport async function observeAgentInvocation<T>(\n  observation: AgentObservation,\n  work: () => Promise<T>,\n): Promise<T> {\n  const agentName = boundedSpanValue(observation.agentName) ?? \"unknown\";\n\n  return observeOperation(\n    agentDuration,\n    agentOperations,\n    {},\n    () => withObservedSpan(\n      `invoke_agent ${agentName}`,\n      compact({\n        \"gen_ai.operation.name\": \"invoke_agent\",\n        \"gen_ai.agent.name\": agentName,\n        \"gen_ai.provider.name\": boundedSpanValue(observation.provider),\n        \"gen_ai.request.model\": boundedSpanValue(observation.model),\n      }),\n      work,\n    ),\n  );\n}\n\nexport async function observeAgentTool<T>(\n  toolName: string,\n  work: () => Promise<T>,\n): Promise<T> {\n  const safeToolName = boundedSpanValue(toolName) ?? \"unknown\";\n\n  return observeOperation(\n    toolDuration,\n    toolOperations,\n    {},\n    () => withObservedSpan(\n      `execute_tool ${safeToolName}`,\n      {\n        \"gen_ai.operation.name\": \"execute_tool\",\n        \"gen_ai.tool.name\": safeToolName,\n      },\n      work,\n    ),\n  );\n}\n\nasync function observeOperation<T>(\n  duration: Histogram,\n  operations: Counter,\n  attributes: Attributes,\n  work: () => Promise<T>,\n): Promise<T> {\n  const started = performance.now();\n  let outcome: Outcome = \"error\";\n\n  try {\n    const result = await work();\n    outcome = \"success\";\n    return result;\n  } finally {\n    recordMetrics(duration, operations, performance.now() - started, {\n      ...attributes,\n      outcome,\n    });\n  }\n}\n\nfunction recordMetrics(\n  duration: Histogram,\n  operations: Counter,\n  elapsedMilliseconds: number,\n  attributes: Attributes,\n): void {\n  try {\n    duration.record(elapsedMilliseconds, attributes);\n    operations.add(1, attributes);\n  } catch {\n    // Telemetry must not replace an application result or error.\n  }\n}\n\nfunction boundedSpanValue(value: string | undefined): string | undefined {\n  if (value === undefined) return undefined;\n  const bounded = value.trim().slice(0, MAX_ATTRIBUTE_LENGTH);\n  return bounded || undefined;\n}\n\nfunction compact(\n  attributes: Record<string, string | undefined>,\n): Record<string, string> {\n  return Object.fromEntries(\n    Object.entries(attributes).filter((entry): entry is [string, string] =>\n      entry[1] !== undefined\n    ),\n  );\n}"],"mappings":";;;;;AAAA,SAAS,eAA8D;AAGvE,IAAM,uBAAuB;AAC7B,IAAM,QAAQ,QAAQ;AAAA,EACpB;AACF;AACA,IAAM,gBAAgB,MAAM;AAAA,EAC1B;AAAA,EACA,EAAE,MAAM,KAAK;AACf;AACA,IAAM,kBAAkB,MAAM,cAAc,kCAAkC;AAC9E,IAAM,eAAe,MAAM,gBAAgB,+BAA+B;AAAA,EACxE,MAAM;AACR,CAAC;AACD,IAAM,iBAAiB,MAAM,cAAc,4BAA4B;AACvE,IAAM,eAAe,MAAM;AAAA,EACzB;AAAA,EACA,EAAE,MAAM,KAAK;AACf;AACA,IAAM,iBAAiB,MAAM,cAAc,mCAAmC;AAU9E,eAAsB,wBACpB,SACA,MACY;AACZ,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,EAAE,QAAQ;AAAA,IACV,MAAM;AAAA,MACJ,qBAAqB,OAAO;AAAA,MAC5B,EAAE,0BAA0B,QAAQ;AAAA,MACpC;AAAA,IACF;AAAA,EACF;AACF;AAEA,eAAsB,uBACpB,aACA,MACY;AACZ,QAAM,YAAY,iBAAiB,YAAY,SAAS,KAAK;AAE7D,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,CAAC;AAAA,IACD,MAAM;AAAA,MACJ,gBAAgB,SAAS;AAAA,MACzB,QAAQ;AAAA,QACN,yBAAyB;AAAA,QACzB,qBAAqB;AAAA,QACrB,wBAAwB,iBAAiB,YAAY,QAAQ;AAAA,QAC7D,wBAAwB,iBAAiB,YAAY,KAAK;AAAA,MAC5D,CAAC;AAAA,MACD;AAAA,IACF;AAAA,EACF;AACF;AAEA,eAAsB,iBACpB,UACA,MACY;AACZ,QAAM,eAAe,iBAAiB,QAAQ,KAAK;AAEnD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,CAAC;AAAA,IACD,MAAM;AAAA,MACJ,gBAAgB,YAAY;AAAA,MAC5B;AAAA,QACE,yBAAyB;AAAA,QACzB,oBAAoB;AAAA,MACtB;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAEA,eAAe,iBACb,UACA,YACA,YACA,MACY;AACZ,QAAM,UAAU,YAAY,IAAI;AAChC,MAAI,UAAmB;AAEvB,MAAI;AACF,UAAM,SAAS,MAAM,KAAK;AAC1B,cAAU;AACV,WAAO;AAAA,EACT,UAAE;AACA,kBAAc,UAAU,YAAY,YAAY,IAAI,IAAI,SAAS;AAAA,MAC/D,GAAG;AAAA,MACH;AAAA,IACF,CAAC;AAAA,EACH;AACF;AAEA,SAAS,cACP,UACA,YACA,qBACA,YACM;AACN,MAAI;AACF,aAAS,OAAO,qBAAqB,UAAU;AAC/C,eAAW,IAAI,GAAG,UAAU;AAAA,EAC9B,QAAQ;AAAA,EAER;AACF;AAEA,SAAS,iBAAiB,OAA+C;AACvE,MAAI,UAAU,OAAW,QAAO;AAChC,QAAM,UAAU,MAAM,KAAK,EAAE,MAAM,GAAG,oBAAoB;AAC1D,SAAO,WAAW;AACpB;AAEA,SAAS,QACP,YACwB;AACxB,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,UAAU,EAAE;AAAA,MAAO,CAAC,UACjC,MAAM,CAAC,MAAM;AAAA,IACf;AAAA,EACF;AACF;","names":[]}

package/dist/observability/index.d.ts

@@ -0,0 +1,6 @@
+import { Attributes } from '@opentelemetry/api';
+
+declare function getActiveTraceId(): string | undefined;
+declare function withObservedSpan<T>(name: string, attributes: Attributes, work: () => Promise<T>): Promise<T>;
+
+export { getActiveTraceId, withObservedSpan };

package/dist/observability/index.js

@@ -0,0 +1,9 @@
+import {
+  getActiveTraceId,
+  withObservedSpan
+} from "../chunk-XH6XHKXC.js";
+export {
+  getActiveTraceId,
+  withObservedSpan
+};
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/observability/node.d.ts

@@ -0,0 +1,29 @@
+import { Sampler } from '@opentelemetry/sdk-trace-base';
+
+type NodeInstrumentProfile = {
+    http?: boolean;
+    fetch?: boolean;
+    prisma?: boolean;
+};
+type NodeObservabilityOptions = {
+    serviceName: string;
+    environment?: string;
+    serviceNamespace?: string;
+    instrument?: NodeInstrumentProfile;
+    traceSampleRatio?: number;
+    forceEnable?: boolean;
+};
+type NodeObservabilityRuntime = {
+    enabled: boolean;
+    serviceName: string;
+    environment: string;
+    error?: string;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+};
+declare function resolveDeploymentEnvironmentName(): string;
+declare function initNodeObservability(options: NodeObservabilityOptions): NodeObservabilityRuntime;
+declare function getNodeObservabilityRuntime(): NodeObservabilityRuntime | undefined;
+declare function resolveSampler(explicitRatio: number | undefined, environment: string): Sampler;
+
+export { type NodeInstrumentProfile, type NodeObservabilityOptions, type NodeObservabilityRuntime, getNodeObservabilityRuntime, initNodeObservability, resolveDeploymentEnvironmentName, resolveSampler };