@iii-dev/helpers 0.19.4-alpha.2 → 0.19.4-alpha.3

package/dist/index-CEjPaG4S.d.cts

@@ -0,0 +1,177 @@
+import { AttributeValue, Attributes, Context, Meter as Meter$1, Span as Span$1, SpanKind, Tracer as Tracer$1 } from "@opentelemetry/api";
+import { Logger, SeverityNumber } from "@opentelemetry/api-logs";
+import { Instrumentation } from "@opentelemetry/instrumentation";
+import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+//#region src/observability/telemetry-system/types.d.ts
+/** Configuration for WebSocket reconnection behavior */
+interface ReconnectionConfig {
+  /** Starting delay in milliseconds (default: 1000ms) */
+  initialDelayMs: number;
+  /** Maximum delay cap in milliseconds (default: 30000ms) */
+  maxDelayMs: number;
+  /** Exponential backoff multiplier (default: 2) */
+  backoffMultiplier: number;
+  /** Random jitter factor 0-1 (default: 0.3) */
+  jitterFactor: number;
+  /** Maximum retry attempts, -1 for infinite (default: -1) */
+  maxRetries: number;
+}
+/** Configuration for OpenTelemetry initialization. */
+interface OtelConfig {
+  /** Whether OpenTelemetry export is enabled. Defaults to true. Set to false or OTEL_ENABLED=false/0/no/off to disable. */
+  enabled?: boolean;
+  /** The service name to report. Defaults to OTEL_SERVICE_NAME or "iii-node". */
+  serviceName?: string;
+  /** The service version to report. Defaults to SERVICE_VERSION env var or "unknown". */
+  serviceVersion?: string;
+  /** The service namespace to report. Defaults to SERVICE_NAMESPACE env var. */
+  serviceNamespace?: string;
+  /** The service instance ID to report. Defaults to SERVICE_INSTANCE_ID env var or auto-generated UUID. */
+  serviceInstanceId?: string;
+  /** III Engine WebSocket URL. Defaults to III_URL or "ws://localhost:49134". */
+  engineWsUrl?: string;
+  /** OpenTelemetry instrumentations to register (e.g., PrismaInstrumentation). */
+  instrumentations?: Instrumentation[];
+  /** Whether OpenTelemetry metrics export is enabled. Defaults to true. Set to false or OTEL_METRICS_ENABLED=false/0/no/off to disable. */
+  metricsEnabled?: boolean;
+  /** Metrics export interval in milliseconds. Defaults to 60000 (60 seconds). */
+  metricsExportIntervalMs?: number;
+  /**
+   * Span processor flush delay in milliseconds. Defaults to 100ms. This is how
+   * long an ended span waits in the batch buffer before it is flushed to the
+   * engine — the OpenTelemetry default of 5000ms is what makes traces appear
+   * seconds after the action. Env override: OTEL_SPANS_FLUSH_INTERVAL_MS.
+   */
+  spansFlushIntervalMs?: number;
+  /** Log processor flush delay in milliseconds. Defaults to 100ms. Env override: OTEL_LOGS_FLUSH_INTERVAL_MS. */
+  logsFlushIntervalMs?: number;
+  /** Maximum number of log records exported per batch. Defaults to 1. */
+  logsBatchSize?: number;
+  /** Whether to auto-instrument globalThis.fetch calls. Defaults to true. Works on Node.js, Bun, and Deno. Set to false to disable. */
+  fetchInstrumentationEnabled?: boolean;
+  /** Optional reconnection configuration for the WebSocket connection. */
+  reconnectionConfig?: Partial<ReconnectionConfig>;
+}
+//#endregion
+//#region src/observability/telemetry-system/context.d.ts
+/**
+ * Extract the current trace ID from the active span context.
+ */
+declare function currentTraceId(): string | undefined;
+/**
+ * Extract the current span ID from the active span context.
+ */
+declare function currentSpanId(): string | undefined;
+/**
+ * Inject the current trace context into a W3C traceparent header string.
+ */
+declare function injectTraceparent(): string | undefined;
+/**
+ * Extract a trace context from a W3C traceparent header string.
+ */
+declare function extractTraceparent(traceparent: string): Context;
+/**
+ * Inject the current baggage into a W3C baggage header string.
+ */
+declare function injectBaggage(): string | undefined;
+/**
+ * Extract baggage from a W3C baggage header string.
+ */
+declare function extractBaggage(baggage: string): Context;
+/**
+ * Extract both trace context and baggage from their respective headers.
+ */
+declare function extractContext(traceparent?: string, baggage?: string): Context;
+/**
+ * Get a baggage entry from the current context.
+ */
+declare function getBaggageEntry(key: string): string | undefined;
+/**
+ * Set a baggage entry in the current context.
+ */
+declare function setBaggageEntry(key: string, value: string): Context;
+/**
+ * Remove a baggage entry from the current context.
+ */
+declare function removeBaggageEntry(key: string): Context;
+/**
+ * Get all baggage entries from the current context.
+ */
+declare function getAllBaggage(): Record<string, string>;
+//#endregion
+//#region src/observability/telemetry-system/baggage-span-processor.d.ts
+/** DEFAULT_ALLOWLIST drift across languages would break worker chains;
+ * lockstep tests in each SDK pin this constant at CI time. */
+declare const DEFAULT_ALLOWLIST: readonly string[];
+declare class BaggageSpanProcessor implements SpanProcessor {
+  private readonly allowlist;
+  constructor(allowlist?: readonly string[]);
+  onStart(span: Span, parentContext: Context): void;
+  onEnd(_span: ReadableSpan): void;
+  shutdown(): Promise<void>;
+  forceFlush(): Promise<void>;
+}
+//#endregion
+//#region src/observability/telemetry-system/span-ops.d.ts
+/** Returns `false` when there is no active span or the sampler dropped it. */
+declare function currentSpanIsRecording(): boolean;
+/** No-op when the current span is not recording. */
+declare function setCurrentSpanAttribute(key: string, value: AttributeValue): void;
+/** No-op when there is no active span. */
+declare function setCurrentSpanError(message: string): void;
+/** No-op when the current span is not recording. */
+declare function recordSpanEvent(name: string, attrs?: Attributes): void;
+//#endregion
+//#region src/observability/telemetry-system/payload.d.ts
+/** Payload redaction + truncation for invocation event capture. */
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+declare function resolveMaxBytesFromEnv(): number | null;
+/** Recursively redact values of sensitive keys. Returns a new value. */
+declare function redact(value: unknown): unknown;
+/** Redact then serialize to JSON, optionally capped at `maxBytes`. */
+declare function redactAndTruncate(value: unknown, maxBytes?: number | null): {
+  json: string;
+  truncated: boolean;
+};
+//#endregion
+//#region src/observability/telemetry-system/index.d.ts
+/**
+ * Initialize OpenTelemetry with the given configuration.
+ * This should be called once at application startup.
+ */
+declare function initOtel(config?: OtelConfig): void;
+/**
+ * Shutdown OpenTelemetry, flushing any pending data.
+ */
+declare function shutdownOtel(): Promise<void>;
+/**
+ * Force-flush all OTel providers without tearing them down.
+ *
+ * Counterpart to {@link shutdownOtel}. Use before short-lived process exits
+ * where you want pending spans/metrics/logs delivered but plan to keep using
+ * OTel afterwards.
+ */
+declare function flushOtel(): Promise<void>;
+/**
+ * Get the OpenTelemetry tracer instance.
+ */
+declare function getTracer(): Tracer$1 | null;
+/**
+ * Get the OpenTelemetry meter instance.
+ */
+declare function getMeter(): Meter$1 | null;
+/**
+ * Get the OpenTelemetry logger instance.
+ */
+declare function getLogger(): Logger | null;
+/**
+ * Start a new span with the given name and run the callback within it.
+ */
+declare function withSpan<T>(name: string, options: {
+  kind?: SpanKind;
+  traceparent?: string;
+}, fn: (span: Span$1) => Promise<T>): Promise<T>;
+//#endregion
+export { injectTraceparent as A, currentTraceId as C, getAllBaggage as D, extractTraceparent as E, setBaggageEntry as M, OtelConfig as N, getBaggageEntry as O, ReconnectionConfig as P, currentSpanId as S, extractContext as T, recordSpanEvent as _, flushOtel as a, BaggageSpanProcessor as b, getTracer as c, withSpan as d, REDACTED_PLACEHOLDER as f, currentSpanIsRecording as g, resolveMaxBytesFromEnv as h, Span$1 as i, removeBaggageEntry as j, injectBaggage as k, initOtel as l, redactAndTruncate as m, Meter$1 as n, getLogger as o, redact as p, SeverityNumber as r, getMeter as s, Logger as t, shutdownOtel as u, setCurrentSpanAttribute as v, extractBaggage as w, DEFAULT_ALLOWLIST as x, setCurrentSpanError as y };
+//# sourceMappingURL=index-CEjPaG4S.d.cts.map

package/dist/index-KWqP5kbF.d.mts

@@ -0,0 +1,177 @@
+import { Logger, SeverityNumber as SeverityNumber$1 } from "@opentelemetry/api-logs";
+import { AttributeValue, Attributes, Context, Meter as Meter$1, Span as Span$1, SpanKind as SpanKind$1, Tracer as Tracer$1 } from "@opentelemetry/api";
+import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { Instrumentation } from "@opentelemetry/instrumentation";
+
+//#region src/observability/telemetry-system/types.d.ts
+/** Configuration for WebSocket reconnection behavior */
+interface ReconnectionConfig {
+  /** Starting delay in milliseconds (default: 1000ms) */
+  initialDelayMs: number;
+  /** Maximum delay cap in milliseconds (default: 30000ms) */
+  maxDelayMs: number;
+  /** Exponential backoff multiplier (default: 2) */
+  backoffMultiplier: number;
+  /** Random jitter factor 0-1 (default: 0.3) */
+  jitterFactor: number;
+  /** Maximum retry attempts, -1 for infinite (default: -1) */
+  maxRetries: number;
+}
+/** Configuration for OpenTelemetry initialization. */
+interface OtelConfig {
+  /** Whether OpenTelemetry export is enabled. Defaults to true. Set to false or OTEL_ENABLED=false/0/no/off to disable. */
+  enabled?: boolean;
+  /** The service name to report. Defaults to OTEL_SERVICE_NAME or "iii-node". */
+  serviceName?: string;
+  /** The service version to report. Defaults to SERVICE_VERSION env var or "unknown". */
+  serviceVersion?: string;
+  /** The service namespace to report. Defaults to SERVICE_NAMESPACE env var. */
+  serviceNamespace?: string;
+  /** The service instance ID to report. Defaults to SERVICE_INSTANCE_ID env var or auto-generated UUID. */
+  serviceInstanceId?: string;
+  /** III Engine WebSocket URL. Defaults to III_URL or "ws://localhost:49134". */
+  engineWsUrl?: string;
+  /** OpenTelemetry instrumentations to register (e.g., PrismaInstrumentation). */
+  instrumentations?: Instrumentation[];
+  /** Whether OpenTelemetry metrics export is enabled. Defaults to true. Set to false or OTEL_METRICS_ENABLED=false/0/no/off to disable. */
+  metricsEnabled?: boolean;
+  /** Metrics export interval in milliseconds. Defaults to 60000 (60 seconds). */
+  metricsExportIntervalMs?: number;
+  /**
+   * Span processor flush delay in milliseconds. Defaults to 100ms. This is how
+   * long an ended span waits in the batch buffer before it is flushed to the
+   * engine — the OpenTelemetry default of 5000ms is what makes traces appear
+   * seconds after the action. Env override: OTEL_SPANS_FLUSH_INTERVAL_MS.
+   */
+  spansFlushIntervalMs?: number;
+  /** Log processor flush delay in milliseconds. Defaults to 100ms. Env override: OTEL_LOGS_FLUSH_INTERVAL_MS. */
+  logsFlushIntervalMs?: number;
+  /** Maximum number of log records exported per batch. Defaults to 1. */
+  logsBatchSize?: number;
+  /** Whether to auto-instrument globalThis.fetch calls. Defaults to true. Works on Node.js, Bun, and Deno. Set to false to disable. */
+  fetchInstrumentationEnabled?: boolean;
+  /** Optional reconnection configuration for the WebSocket connection. */
+  reconnectionConfig?: Partial<ReconnectionConfig>;
+}
+//#endregion
+//#region src/observability/telemetry-system/context.d.ts
+/**
+ * Extract the current trace ID from the active span context.
+ */
+declare function currentTraceId(): string | undefined;
+/**
+ * Extract the current span ID from the active span context.
+ */
+declare function currentSpanId(): string | undefined;
+/**
+ * Inject the current trace context into a W3C traceparent header string.
+ */
+declare function injectTraceparent(): string | undefined;
+/**
+ * Extract a trace context from a W3C traceparent header string.
+ */
+declare function extractTraceparent(traceparent: string): Context;
+/**
+ * Inject the current baggage into a W3C baggage header string.
+ */
+declare function injectBaggage(): string | undefined;
+/**
+ * Extract baggage from a W3C baggage header string.
+ */
+declare function extractBaggage(baggage: string): Context;
+/**
+ * Extract both trace context and baggage from their respective headers.
+ */
+declare function extractContext(traceparent?: string, baggage?: string): Context;
+/**
+ * Get a baggage entry from the current context.
+ */
+declare function getBaggageEntry(key: string): string | undefined;
+/**
+ * Set a baggage entry in the current context.
+ */
+declare function setBaggageEntry(key: string, value: string): Context;
+/**
+ * Remove a baggage entry from the current context.
+ */
+declare function removeBaggageEntry(key: string): Context;
+/**
+ * Get all baggage entries from the current context.
+ */
+declare function getAllBaggage(): Record<string, string>;
+//#endregion
+//#region src/observability/telemetry-system/baggage-span-processor.d.ts
+/** DEFAULT_ALLOWLIST drift across languages would break worker chains;
+ * lockstep tests in each SDK pin this constant at CI time. */
+declare const DEFAULT_ALLOWLIST: readonly string[];
+declare class BaggageSpanProcessor implements SpanProcessor {
+  private readonly allowlist;
+  constructor(allowlist?: readonly string[]);
+  onStart(span: Span, parentContext: Context): void;
+  onEnd(_span: ReadableSpan): void;
+  shutdown(): Promise<void>;
+  forceFlush(): Promise<void>;
+}
+//#endregion
+//#region src/observability/telemetry-system/span-ops.d.ts
+/** Returns `false` when there is no active span or the sampler dropped it. */
+declare function currentSpanIsRecording(): boolean;
+/** No-op when the current span is not recording. */
+declare function setCurrentSpanAttribute(key: string, value: AttributeValue): void;
+/** No-op when there is no active span. */
+declare function setCurrentSpanError(message: string): void;
+/** No-op when the current span is not recording. */
+declare function recordSpanEvent(name: string, attrs?: Attributes): void;
+//#endregion
+//#region src/observability/telemetry-system/payload.d.ts
+/** Payload redaction + truncation for invocation event capture. */
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+declare function resolveMaxBytesFromEnv(): number | null;
+/** Recursively redact values of sensitive keys. Returns a new value. */
+declare function redact(value: unknown): unknown;
+/** Redact then serialize to JSON, optionally capped at `maxBytes`. */
+declare function redactAndTruncate(value: unknown, maxBytes?: number | null): {
+  json: string;
+  truncated: boolean;
+};
+//#endregion
+//#region src/observability/telemetry-system/index.d.ts
+/**
+ * Initialize OpenTelemetry with the given configuration.
+ * This should be called once at application startup.
+ */
+declare function initOtel(config?: OtelConfig): void;
+/**
+ * Shutdown OpenTelemetry, flushing any pending data.
+ */
+declare function shutdownOtel(): Promise<void>;
+/**
+ * Force-flush all OTel providers without tearing them down.
+ *
+ * Counterpart to {@link shutdownOtel}. Use before short-lived process exits
+ * where you want pending spans/metrics/logs delivered but plan to keep using
+ * OTel afterwards.
+ */
+declare function flushOtel(): Promise<void>;
+/**
+ * Get the OpenTelemetry tracer instance.
+ */
+declare function getTracer(): Tracer$1 | null;
+/**
+ * Get the OpenTelemetry meter instance.
+ */
+declare function getMeter(): Meter$1 | null;
+/**
+ * Get the OpenTelemetry logger instance.
+ */
+declare function getLogger(): Logger | null;
+/**
+ * Start a new span with the given name and run the callback within it.
+ */
+declare function withSpan<T>(name: string, options: {
+  kind?: SpanKind$1;
+  traceparent?: string;
+}, fn: (span: Span$1) => Promise<T>): Promise<T>;
+//#endregion
+export { injectTraceparent as A, currentTraceId as C, getAllBaggage as D, extractTraceparent as E, setBaggageEntry as M, OtelConfig as N, getBaggageEntry as O, ReconnectionConfig as P, currentSpanId as S, extractContext as T, recordSpanEvent as _, flushOtel as a, BaggageSpanProcessor as b, getTracer as c, withSpan as d, REDACTED_PLACEHOLDER as f, currentSpanIsRecording as g, resolveMaxBytesFromEnv as h, Span$1 as i, removeBaggageEntry as j, injectBaggage as k, initOtel as l, redactAndTruncate as m, Meter$1 as n, getLogger as o, redact as p, SeverityNumber$1 as r, getMeter as s, Logger as t, shutdownOtel as u, setCurrentSpanAttribute as v, extractBaggage as w, DEFAULT_ALLOWLIST as x, setCurrentSpanError as y };
+//# sourceMappingURL=index-KWqP5kbF.d.mts.map