@syntrologie/runtime-sdk 2.17.0 → 2.19.0

package/dist/observability/healthReporter.d.ts

@@ -0,0 +1,51 @@
+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;
+    /** Cleanup function for adapters that registered side effects (e.g. the
+     *  web-vitals long-task observer). Called from `stop()` so SPA re-init
+     *  via `initHealthReporter` doesn't accumulate observers. */
+    private adapterCleanup;
+    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;
+    /**
+     * Register a cleanup function to run on `stop()`. Used by adapters
+     * (e.g. webVitalsAdapter) that need to release per-bind resources
+     * like PerformanceObservers. Replaces any prior cleanup — only one
+     * adapter cleanup is tracked.
+     */
+    attachAdapterCleanup(cleanup: () => void): 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,5 @@
+export { getHealthReporter, HealthReporter, initHealthReporter } from './healthReporter';
+export { createOtlpEmitter } from './otlpEmitter';
+export { getSdkScriptUrl, getSdkScriptUrlPrefix } from './sdkScriptUrl';
+export type { CounterSignal, FlushPayload, HealthReporterConfig, HistogramSignal, ReporterResource, } from './types';
+export { bindWebVitals } from './webVitalsAdapter';

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/sdkScriptUrl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The full URL of the SDK script, captured at module load. Returns
+ * `undefined` when the SDK is bundled into the host app (no separate
+ * `<script>` tag) or when running outside a browser.
+ */
+export declare function getSdkScriptUrl(): string | undefined;
+/**
+ * Directory prefix of the SDK script URL — useful for matching attribution
+ * entries from `PerformanceLongTaskTiming` against the SDK bundle and any
+ * sibling chunks (source maps, lazy-loaded adaptives) served from the same
+ * directory.
+ *
+ * Example: `https://cdn.syntrologie.com/runtime-sdk/v2/canary/smart-canvas.min.js`
+ *       → `https://cdn.syntrologie.com/runtime-sdk/v2/canary/`
+ */
+export declare function getSdkScriptUrlPrefix(): string | undefined;

package/dist/observability/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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' | 'longtasks_self_count'
+/** Cumulative blocking time (ms) from long tasks attributed to the SDK
+ *  script. Counter rather than histogram so HogQL sum() across windows
+ *  gives the total — which is what alerts/dashboards actually want. */
+ | 'longtasks_self_blocking_ms';
+/**
+ * Histogram signals. Web vitals are field-RUM measurements from the customer's
+ * browser, not synthetic Lighthouse audits — same metrics Lighthouse reports
+ * as "Core Web Vitals from CrUX," but measured live.
+ *
+ * - lcp_ms       — Largest Contentful Paint
+ * - inp_ms       — Interaction to Next Paint
+ * - cls_score    — Cumulative Layout Shift (unitless 0..1+)
+ * - fcp_ms       — First Contentful Paint
+ * - ttfb_ms      — Time to First Byte
+ */
+export type HistogramSignal = 'flag_fetch_latency_ms' | 'lcp_ms' | 'inp_ms' | 'cls_score' | 'fcp_ms' | 'ttfb_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>;
+}

package/dist/observability/webVitalsAdapter.d.ts

@@ -0,0 +1,22 @@
+import type { HealthReporter } from './healthReporter';
+/**
+ * Bind the web-vitals callbacks to the given HealthReporter. Each metric
+ * fires once per session per metric (with possible BFCache reactivations).
+ *
+ * Idempotent across `Syntro.init()` re-calls: web-vitals subscriptions are
+ * registered once per page; later binds re-route to the most recent
+ * reporter via a window-scoped pointer. Long-task observers are per-bind
+ * and disposed via the returned cleanup function.
+ *
+ * Long-task tracking is opt-in via `attributedScriptUrlPrefix`: when the
+ * browser exposes long-task attribution and the offending script's URL
+ * starts with this prefix, the long task is counted toward the SDK's own
+ * blocking time. Pass the SDK script URL prefix (typically the CDN
+ * directory the bundle was loaded from).
+ *
+ * Safe to call in non-browser environments — returns a no-op cleanup
+ * function when `window` is unavailable.
+ */
+export declare function bindWebVitals(reporter: HealthReporter, options?: {
+    attributedScriptUrlPrefix?: string;
+}): () => void;