@syntrologie/runtime-sdk 2.17.0 → 2.18.0

package/dist/observability/healthReporter.d.ts

@@ -0,0 +1,40 @@
+import type { CounterSignal, HealthReporterConfig, HistogramSignal, ReporterRuntimeBinding } from './types';
+export declare class HealthReporter {
+    private readonly config;
+    private readonly resource;
+    private readonly flushIntervalMs;
+    private readonly counters;
+    private readonly histograms;
+    private windowStartMs;
+    private timer;
+    private pagehideHandler;
+    private runtime;
+    constructor(config: HealthReporterConfig);
+    /**
+     * Bind runtime-derived attribute resolvers. Called after the canvas/telemetry
+     * are fully initialized. Must never throw — resolvers are wrapped in
+     * null-safe access at flush time.
+     */
+    bindRuntime(binding: ReporterRuntimeBinding): void;
+    increment(signal: CounterSignal, by?: number): void;
+    /**
+     * @internal — exposed for test inspection only. Mid-window state is intentionally
+     * unstable; consumers should subscribe to flush payloads instead.
+     */
+    snapshotCounters(): Partial<Record<CounterSignal, number>>;
+    recordHistogram(signal: HistogramSignal, valueMs: number): void;
+    /**
+     * @internal — exposed for test inspection only. Mid-window state is intentionally
+     * unstable; consumers should subscribe to flush payloads instead.
+     */
+    snapshotHistograms(): Partial<Record<HistogramSignal, {
+        count: number;
+        p50: number;
+        p95: number;
+    }>>;
+    flush(): Promise<void>;
+    start(): void;
+    stop(): void;
+}
+export declare function initHealthReporter(config: HealthReporterConfig): HealthReporter;
+export declare function getHealthReporter(): HealthReporter | null;

package/dist/observability/index.d.ts

@@ -0,0 +1,3 @@
+export { getHealthReporter, HealthReporter, initHealthReporter } from './healthReporter';
+export { createOtlpEmitter } from './otlpEmitter';
+export type { CounterSignal, FlushPayload, HealthReporterConfig, HistogramSignal, ReporterResource, } from './types';

package/dist/observability/otlpEmitter.d.ts

@@ -0,0 +1,39 @@
+import type { FlushPayload } from './types';
+interface AnyValue {
+    stringValue?: string;
+    intValue?: number;
+    doubleValue?: number;
+}
+interface KV {
+    key: string;
+    value: AnyValue;
+}
+interface OtlpEnvelope {
+    resourceLogs: Array<{
+        resource: {
+            attributes: KV[];
+        };
+        scopeLogs: Array<{
+            scope: {
+                name: string;
+            };
+            logRecords: Array<{
+                timeUnixNano: string;
+                observedTimeUnixNano: string;
+                severityText: 'INFO';
+                body: AnyValue;
+                attributes: KV[];
+            }>;
+        }>;
+    }>;
+}
+/**
+ * @internal — exposed for unit testing only. Production code should use createOtlpEmitter.
+ */
+export declare function buildOtlpPayload(flush: FlushPayload): OtlpEnvelope;
+export interface OtlpEmitterConfig {
+    endpoint: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function createOtlpEmitter(cfg: OtlpEmitterConfig): (p: FlushPayload) => Promise<void>;
+export {};

package/dist/observability/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Names of signals the SDK emits. Add new entries as the taxonomy grows.
+ * Counter signals are unbounded integers; histogram signals are millisecond floats.
+ */
+export type CounterSignal = 'bootstrap_ok' | 'bootstrap_errors' | 'flag_fetch_count' | 'flag_fetch_errors';
+export type HistogramSignal = 'flag_fetch_latency_ms';
+/**
+ * Resource attributes for the OTLP payload. The static fields are set at
+ * reporter init; the dynamic fields are resolved at flush time via runtime
+ * binding (see HealthReporter.bindRuntime).
+ */
+export interface ReporterResource {
+    serviceName: 'syntro-runtime-sdk';
+    serviceVersion: string;
+    /** Customer's PostHog project SDK key. Identifies which PostHog project
+     *  this telemetry corresponds to. The exporter joins on this. */
+    posthogKey: string;
+    /** Page origin where the SDK booted (e.g. https://customer.com). */
+    hostOrigin: string;
+}
+/**
+ * Runtime-derived attributes resolved at flush time. The HealthReporter
+ * binds resolvers via bindRuntime() once the canvas/telemetry are ready.
+ * Before bindRuntime is called, defaults apply.
+ */
+export interface ReporterRuntimeBinding {
+    /** PostHog session ID. Returns empty string before telemetry is ready. */
+    getSessionId(): string;
+    /** Surface context snapshot. Returns null before context is ready. */
+    getSurface(): {
+        type: 'web' | 'telegram' | 'mcp-app';
+        host: string;
+        device: 'mobile' | 'tablet' | 'desktop';
+        mode: 'agent' | 'mobile' | 'desktop';
+    } | null;
+}
+/**
+ * In-memory aggregate produced at flush time. Resource is the snapshot
+ * of static + runtime-bound fields at flush moment.
+ */
+export interface FlushPayload {
+    resource: ReporterResource & {
+        sessionId: string;
+        surfaceType: 'web' | 'telegram' | 'mcp-app' | 'unknown';
+        surfaceHost: string;
+        surfaceDevice: 'mobile' | 'tablet' | 'desktop' | 'unknown';
+        surfaceMode: 'agent' | 'mobile' | 'desktop' | 'unknown';
+    };
+    windowSeconds: number;
+    windowStartUnixMs: number;
+    counters: Partial<Record<CounterSignal, number>>;
+    /** Histograms expose count, p50, p95 — raw samples are NOT shipped. */
+    histograms: Partial<Record<HistogramSignal, {
+        count: number;
+        p50: number;
+        p95: number;
+    }>>;
+}
+/** Configuration for the reporter singleton. */
+export interface HealthReporterConfig {
+    resource: ReporterResource;
+    flushIntervalMs?: number;
+    emit: (payload: FlushPayload) => Promise<void>;
+}