@superblocksteam/telemetry 2.0.173-next.4 → 2.0.174

package/dist-esm/testing/test-init.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Test Telemetry Initialization
+ *
+ * Initialize telemetry for testing with in-memory exporters.
+ * No external connections are made.
+ */
+import { trace } from "@opentelemetry/api";
+import { TelemetryPolicyEvaluator } from "../common/policy-evaluator.js";
+import type { BaseTelemetryConfig } from "../types/index.js";
+import { InMemorySpanExporter, InMemoryMetricExporter, InMemoryLogExporter } from "./in-memory-exporter.js";
+/**
+ * Test telemetry instance with in-memory exporters.
+ */
+export interface TestTelemetryInstance {
+    /** In-memory span exporter */
+    spanExporter: InMemorySpanExporter;
+    /** In-memory metric exporter */
+    metricExporter: InMemoryMetricExporter;
+    /** In-memory log exporter */
+    logExporter: InMemoryLogExporter;
+    /** Policy evaluator */
+    policyEvaluator: TelemetryPolicyEvaluator;
+    /** Reset all exporters (call in beforeEach) */
+    reset: () => void;
+    /** Shutdown (call in afterAll) */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Initialize telemetry for testing.
+ *
+ * Uses in-memory exporters, no external connections.
+ * Call once per test file, use reset() in beforeEach.
+ *
+ * @param config - Optional test configuration
+ * @returns Test telemetry instance
+ *
+ * @example
+ * ```typescript
+ * import { initTestTelemetry } from '@superblocksteam/telemetry/testing';
+ *
+ * describe('MyService', () => {
+ *   const { spanExporter, reset } = initTestTelemetry();
+ *
+ *   beforeEach(() => reset());
+ *
+ *   it('creates expected spans', async () => {
+ *     // ... test code ...
+ *     expect(spanExporter.getSpans()).toHaveLength(1);
+ *   });
+ * });
+ * ```
+ */
+export declare function initTestTelemetry(config?: Partial<BaseTelemetryConfig>): TestTelemetryInstance;
+/**
+ * Get the test telemetry instance.
+ *
+ * @throws Error if not initialized
+ */
+export declare function getTestTelemetryInstance(): TestTelemetryInstance;
+/**
+ * Reset the test telemetry (for cleanup between test files).
+ */
+export declare function resetTestTelemetry(): Promise<void>;
+/**
+ * Get a tracer for tests.
+ *
+ * @param name - Tracer name
+ * @returns Tracer instance
+ */
+export declare function getTestTracer(name?: string): ReturnType<typeof trace.getTracer>;
+/**
+ * Run a function within a test span.
+ * Useful for testing span creation.
+ *
+ * @param name - Span name
+ * @param fn - Function to run
+ * @returns Function result
+ */
+export declare function withTestSpan<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+//# sourceMappingURL=test-init.d.ts.map

package/dist-esm/testing/test-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-init.d.ts","sourceRoot":"","sources":["../../src/testing/test-init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAM3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,yBAAyB,CAAC;AAEjC;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,YAAY,EAAE,oBAAoB,CAAC;IACnC,gCAAgC;IAChC,cAAc,EAAE,sBAAsB,CAAC;IACvC,6BAA6B;IAC7B,WAAW,EAAE,mBAAmB,CAAC;IACjC,uBAAuB;IACvB,eAAe,EAAE,wBAAwB,CAAC;IAC1C,+CAA+C;IAC/C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAeD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GACpC,qBAAqB,CA2CvB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,qBAAqB,CAOhE;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIxD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,SAAS,GACZ,UAAU,CAAC,OAAO,KAAK,CAAC,SAAS,CAAC,CAEpC;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/dist-esm/testing/test-init.js

@@ -0,0 +1,137 @@
+/**
+ * Test Telemetry Initialization
+ *
+ * Initialize telemetry for testing with in-memory exporters.
+ * No external connections are made.
+ */
+import { trace } from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { TelemetryPolicyEvaluator } from "../common/policy-evaluator.js";
+import { buildResource } from "../common/resource.js";
+import { CLOUD_DEFAULT_POLICY } from "../types/policy.js";
+import { InMemorySpanExporter, InMemoryMetricExporter, InMemoryLogExporter, } from "./in-memory-exporter.js";
+// Singleton for tests
+let testInstance;
+let tracerProvider;
+/**
+ * Default test configuration.
+ */
+const DEFAULT_TEST_CONFIG = {
+    serviceName: "test-service",
+    serviceVersion: "0.0.0-test",
+    environment: "test",
+};
+/**
+ * Initialize telemetry for testing.
+ *
+ * Uses in-memory exporters, no external connections.
+ * Call once per test file, use reset() in beforeEach.
+ *
+ * @param config - Optional test configuration
+ * @returns Test telemetry instance
+ *
+ * @example
+ * ```typescript
+ * import { initTestTelemetry } from '@superblocksteam/telemetry/testing';
+ *
+ * describe('MyService', () => {
+ *   const { spanExporter, reset } = initTestTelemetry();
+ *
+ *   beforeEach(() => reset());
+ *
+ *   it('creates expected spans', async () => {
+ *     // ... test code ...
+ *     expect(spanExporter.getSpans()).toHaveLength(1);
+ *   });
+ * });
+ * ```
+ */
+export function initTestTelemetry(config) {
+    if (testInstance) {
+        return testInstance;
+    }
+    const mergedConfig = { ...DEFAULT_TEST_CONFIG, ...config };
+    const resource = buildResource(mergedConfig);
+    const spanExporter = new InMemorySpanExporter();
+    const metricExporter = new InMemoryMetricExporter();
+    const logExporter = new InMemoryLogExporter();
+    const policyEvaluator = new TelemetryPolicyEvaluator(CLOUD_DEFAULT_POLICY);
+    // Create provider with span processors in constructor (OTEL v2.x API)
+    tracerProvider = new NodeTracerProvider({
+        resource,
+        spanProcessors: [new SimpleSpanProcessor(spanExporter)],
+    });
+    // Register the provider
+    tracerProvider.register({
+        propagator: new W3CTraceContextPropagator(),
+        contextManager: new AsyncLocalStorageContextManager(),
+    });
+    testInstance = {
+        spanExporter,
+        metricExporter,
+        logExporter,
+        policyEvaluator,
+        reset: () => {
+            spanExporter.reset();
+            metricExporter.reset();
+            logExporter.reset();
+        },
+        shutdown: async () => {
+            await tracerProvider?.shutdown();
+            testInstance = undefined;
+            tracerProvider = undefined;
+        },
+    };
+    return testInstance;
+}
+/**
+ * Get the test telemetry instance.
+ *
+ * @throws Error if not initialized
+ */
+export function getTestTelemetryInstance() {
+    if (!testInstance) {
+        throw new Error("[TestTelemetry] Not initialized. Call initTestTelemetry() first.");
+    }
+    return testInstance;
+}
+/**
+ * Reset the test telemetry (for cleanup between test files).
+ */
+export async function resetTestTelemetry() {
+    if (testInstance) {
+        await testInstance.shutdown();
+    }
+}
+/**
+ * Get a tracer for tests.
+ *
+ * @param name - Tracer name
+ * @returns Tracer instance
+ */
+export function getTestTracer(name = "test") {
+    return trace.getTracer(name);
+}
+/**
+ * Run a function within a test span.
+ * Useful for testing span creation.
+ *
+ * @param name - Span name
+ * @param fn - Function to run
+ * @returns Function result
+ */
+export async function withTestSpan(name, fn) {
+    const tracer = getTestTracer();
+    return tracer.startActiveSpan(name, async (span) => {
+        try {
+            return await fn();
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+//# sourceMappingURL=test-init.js.map

package/dist-esm/testing/test-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-init.js","sourceRoot":"","sources":["../../src/testing/test-init.ts"],"names":[],"mappings":"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"}

package/dist-esm/types/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Telemetry Types
+ *
+ * Re-exports policy types and config interfaces.
+ */
+export * from "./policy.js";
+/**
+ * Base configuration for telemetry initialization.
+ */
+export interface BaseTelemetryConfig {
+    /** Service name (e.g., 'superblocks-server') */
+    serviceName: string;
+    /** Service version (e.g., '1.0.0') */
+    serviceVersion: string;
+    /** Deployment environment (e.g., 'production', 'staging', 'development') */
+    environment: string;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string>;
+}
+/**
+ * Configuration for keyed HMAC hashing of Tier 2 span attributes (e.g. organization-id).
+ * When not provided, hashed attributes are redacted instead of hashed.
+ */
+export interface TraceSanitizerHashConfig {
+    secretKey: Buffer;
+    salt: string;
+    algorithm: "sha256" | "sha384" | "sha512";
+    outputLengthBytes: number;
+}
+/**
+ * Node.js specific telemetry configuration.
+ */
+export interface NodeTelemetryConfig extends BaseTelemetryConfig {
+    /** OTLP collector URL (e.g., http://localhost:4318) */
+    otlpUrl?: string;
+    /** Headers sent to each OTLP exporter, such as proxy authentication. */
+    otlpHeaders?: Record<string, string> | (() => Promise<Record<string, string>>);
+    /** OpenTelemetry instrumentations to enable */
+    instrumentations?: unknown[];
+    /** Whether to enable metrics collection */
+    metricsEnabled?: boolean;
+    /** Whether to enable log collection */
+    logsEnabled?: boolean;
+    /**
+     * Optional hash config for Tier 2 trace sanitization (organization-id, session.id, etc.).
+     * When omitted, hashed attributes are redacted. For cloud-prem, supply from secrets.
+     */
+    traceSanitizerHashConfig?: TraceSanitizerHashConfig | null;
+    /**
+     * Optional structured logger (e.g. safe logger) for telemetry internal messages
+     * (e.g. init, span export failures). When set, logs are structured and ingested into Datadog.
+     */
+    logger?: {
+        error?(obj: object, msg?: string): void;
+        error?(msg: string): void;
+        info?(obj: object, msg?: string): void;
+        info?(msg: string): void;
+        warn(obj: object, msg?: string): void;
+        warn(msg: string): void;
+    };
+    /**
+     * Optional provider for attributes that are only known after telemetry is
+     * initialized (e.g. the application/user/org identity a dev-server learns at
+     * connect time, when the SDK must already be running to instrument startup).
+     * Called on every span start and every log-record emit and merged onto the
+     * signal, so late-known identity lands on spans and logs without
+     * re-initializing the SDK. Metrics deliberately do not pick it up (identity
+     * would multiply time-series cardinality). Omit for a static resource only;
+     * the server and other services do not set it.
+     */
+    dynamicAttributes?: () => Record<string, string>;
+}
+/**
+ * Browser specific telemetry configuration.
+ */
+export interface BrowserTelemetryConfig extends BaseTelemetryConfig {
+    /** OTLP base URL (e.g. "http://localhost:4318"). Signal-specific paths (/v1/traces, /v1/metrics, /v1/logs) are appended automatically. */
+    otlpUrl: string;
+    /** URL patterns to inject traceparent header into (for cross-origin propagation) */
+    propagateTraceUrls?: RegExp[];
+    /** URL patterns to skip instrumenting entirely */
+    ignoreUrls?: RegExp[];
+}
+//# sourceMappingURL=index.d.ts.map

package/dist-esm/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,aAAa,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IAEpB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IAEvB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IAEpB,qCAAqC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,wEAAwE;IACxE,WAAW,CAAC,EACR,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAE5C,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC;IAE7B,2CAA2C;IAC3C,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,uCAAuC;IACvC,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,wBAAwB,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAE3D;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxC,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvC,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,CAAC;IAEF;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,0IAA0I;IAC1I,OAAO,EAAE,MAAM,CAAC;IAEhB,oFAAoF;IACpF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB"}

package/dist-esm/types/index.js

@@ -0,0 +1,7 @@
+/**
+ * Telemetry Types
+ *
+ * Re-exports policy types and config interfaces.
+ */
+export * from "./policy.js";
+//# sourceMappingURL=index.js.map

package/dist-esm/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,aAAa,CAAC"}

package/dist-esm/types/policy.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Telemetry Policy Types
+ *
+ * NOTE: In the hybrid tier architecture, the OTEL Collector handles
+ * sanitization, hashing, and routing. The SDK just emits full-fidelity data.
+ * See obs/otel-collector/config-tiered.yaml for Collector configuration.
+ */
+import { DeploymentTypeEnum } from "@superblocksteam/shared";
+export { DeploymentTypeEnum as DeploymentType };
+/**
+ * Telemetry tier definitions.
+ *
+ * Tier 1 (Local): Full fidelity data for debugging. Stored in customer LGTM.
+ * Tier 2 (Operational): Sanitized metrics/traces for ops. Exported to Superblocks.
+ * Tier 3 (Analytics): AI experience telemetry. Exported with content controls.
+ *
+ * In the hybrid architecture:
+ * - SDK emits all data to the Collector
+ * - Collector transforms and routes to appropriate tier pipelines
+ * - Tier tagging, hashing, and filtering happen at Collector level
+ */
+export declare enum TelemetryTier {
+    /** Full fidelity debugging data - prompts, code, tool IO, stack traces */
+    TIER_1_LOCAL = "tier_1_local",
+    /** Sanitized operational metrics and traces for dashboards/billing */
+    TIER_2_OPERATIONAL = "tier_2_operational",
+    /** AI experience telemetry - prompts, responses, quality signals (no tool outputs) */
+    TIER_3_AI_EXPERIENCE = "tier_3_ai_experience"
+}
+export declare enum EnforcementMode {
+    /** Log violations but allow */
+    AUDIT = "audit",
+    /** Block violations */
+    ENFORCE = "enforce"
+}
+/**
+ * Tier 3 content export policy for runtime control during incidents.
+ */
+export interface Tier3ContentPolicy {
+    /** Export AI prompts/responses. Kill switch for incidents. */
+    contentExportEnabled: boolean;
+    /** Redact detected secrets (JWTs, API keys, PEM blocks) from content */
+    secretRedactionEnabled: boolean;
+    /** Block export if tool output patterns detected in response */
+    toolOutputFilteringEnabled: boolean;
+    /** Max prompt length in bytes */
+    maxPromptBytes: number;
+    /** Max response length in bytes */
+    maxResponseBytes: number;
+}
+export interface TierConfig {
+    /** Is this tier enabled for local retention? */
+    enabled: boolean;
+    /** Is this tier enabled for export? */
+    exportEnabled: boolean;
+    /** Sampling rate for this tier (0.0 - 1.0) */
+    sampleRate: number;
+}
+export interface TelemetryPolicy {
+    /** Deployment context */
+    deploymentType: DeploymentTypeEnum;
+    /** Per-tier configuration */
+    tiers: {
+        [TelemetryTier.TIER_1_LOCAL]: TierConfig;
+        [TelemetryTier.TIER_2_OPERATIONAL]: TierConfig;
+        [TelemetryTier.TIER_3_AI_EXPERIENCE]: TierConfig;
+    };
+    /** Tier 3 content export controls (prompts, responses). */
+    tier3Content: Tier3ContentPolicy;
+    /** Enforcement behavior */
+    enforcementMode: EnforcementMode;
+    /** Optional org-specific overrides */
+    orgOverrides?: Record<string, Partial<TelemetryPolicy>>;
+}
+/** Default Tier 3 content policy (enabled with all guardrails) */
+export declare const TIER3_CONTENT_POLICY_DEFAULT: Tier3ContentPolicy;
+/** Tier 3 content policy: disabled (kill switch) */
+export declare const TIER3_CONTENT_POLICY_DISABLED: Tier3ContentPolicy;
+/**
+ * Cloud deployment: all tiers enabled and exported.
+ */
+export declare const CLOUD_DEFAULT_POLICY: TelemetryPolicy;
+/**
+ * Cloud-Prem deployment: Tier 1 local only, Tier 2/3 exported.
+ * Hashing/sanitization handled by OTEL Collector.
+ */
+export declare const CLOUD_PREM_DEFAULT_POLICY: TelemetryPolicy;
+/**
+ * Get the default policy for a deployment type.
+ */
+export declare function getDefaultPolicy(deploymentType: DeploymentTypeEnum): TelemetryPolicy;
+//# sourceMappingURL=policy.d.ts.map

package/dist-esm/types/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/types/policy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,EAAE,kBAAkB,IAAI,cAAc,EAAE,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,oBAAY,aAAa;IACvB,0EAA0E;IAC1E,YAAY,iBAAiB;IAE7B,sEAAsE;IACtE,kBAAkB,uBAAuB;IAEzC,sFAAsF;IACtF,oBAAoB,yBAAyB;CAC9C;AAED,oBAAY,eAAe;IACzB,+BAA+B;IAC/B,KAAK,UAAU;IACf,uBAAuB;IACvB,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,oBAAoB,EAAE,OAAO,CAAC;IAC9B,wEAAwE;IACxE,sBAAsB,EAAE,OAAO,CAAC;IAChC,gEAAgE;IAChE,0BAA0B,EAAE,OAAO,CAAC;IACpC,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,aAAa,EAAE,OAAO,CAAC;IACvB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,cAAc,EAAE,kBAAkB,CAAC;IAEnC,6BAA6B;IAC7B,KAAK,EAAE;QACL,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,UAAU,CAAC;QACzC,CAAC,aAAa,CAAC,kBAAkB,CAAC,EAAE,UAAU,CAAC;QAC/C,CAAC,aAAa,CAAC,oBAAoB,CAAC,EAAE,UAAU,CAAC;KAClD,CAAC;IAEF,2DAA2D;IAC3D,YAAY,EAAE,kBAAkB,CAAC;IAEjC,2BAA2B;IAC3B,eAAe,EAAE,eAAe,CAAC;IAEjC,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;CACzD;AAMD,kEAAkE;AAClE,eAAO,MAAM,4BAA4B,EAAE,kBAM1C,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,6BAA6B,EAAE,kBAM3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,eAqBlC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,eAqBvC,CAAC;AAEF;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,kBAAkB,GACjC,eAAe,CASjB"}

package/dist-esm/types/policy.js

@@ -0,0 +1,122 @@
+/**
+ * Telemetry Policy Types
+ *
+ * NOTE: In the hybrid tier architecture, the OTEL Collector handles
+ * sanitization, hashing, and routing. The SDK just emits full-fidelity data.
+ * See obs/otel-collector/config-tiered.yaml for Collector configuration.
+ */
+import { DeploymentTypeEnum } from "@superblocksteam/shared";
+// Re-export DeploymentTypeEnum as DeploymentType for backwards compatibility
+export { DeploymentTypeEnum as DeploymentType };
+/**
+ * Telemetry tier definitions.
+ *
+ * Tier 1 (Local): Full fidelity data for debugging. Stored in customer LGTM.
+ * Tier 2 (Operational): Sanitized metrics/traces for ops. Exported to Superblocks.
+ * Tier 3 (Analytics): AI experience telemetry. Exported with content controls.
+ *
+ * In the hybrid architecture:
+ * - SDK emits all data to the Collector
+ * - Collector transforms and routes to appropriate tier pipelines
+ * - Tier tagging, hashing, and filtering happen at Collector level
+ */
+export var TelemetryTier;
+(function (TelemetryTier) {
+    /** Full fidelity debugging data - prompts, code, tool IO, stack traces */
+    TelemetryTier["TIER_1_LOCAL"] = "tier_1_local";
+    /** Sanitized operational metrics and traces for dashboards/billing */
+    TelemetryTier["TIER_2_OPERATIONAL"] = "tier_2_operational";
+    /** AI experience telemetry - prompts, responses, quality signals (no tool outputs) */
+    TelemetryTier["TIER_3_AI_EXPERIENCE"] = "tier_3_ai_experience";
+})(TelemetryTier || (TelemetryTier = {}));
+export var EnforcementMode;
+(function (EnforcementMode) {
+    /** Log violations but allow */
+    EnforcementMode["AUDIT"] = "audit";
+    /** Block violations */
+    EnforcementMode["ENFORCE"] = "enforce";
+})(EnforcementMode || (EnforcementMode = {}));
+// ============================================================================
+// Default Policies
+// ============================================================================
+/** Default Tier 3 content policy (enabled with all guardrails) */
+export const TIER3_CONTENT_POLICY_DEFAULT = {
+    contentExportEnabled: true,
+    secretRedactionEnabled: true,
+    toolOutputFilteringEnabled: true,
+    maxPromptBytes: 32768,
+    maxResponseBytes: 65536,
+};
+/** Tier 3 content policy: disabled (kill switch) */
+export const TIER3_CONTENT_POLICY_DISABLED = {
+    contentExportEnabled: false,
+    secretRedactionEnabled: true,
+    toolOutputFilteringEnabled: true,
+    maxPromptBytes: 32768,
+    maxResponseBytes: 65536,
+};
+/**
+ * Cloud deployment: all tiers enabled and exported.
+ */
+export const CLOUD_DEFAULT_POLICY = {
+    deploymentType: DeploymentTypeEnum.CLOUD,
+    tiers: {
+        [TelemetryTier.TIER_1_LOCAL]: {
+            enabled: true,
+            exportEnabled: true,
+            sampleRate: 1.0,
+        },
+        [TelemetryTier.TIER_2_OPERATIONAL]: {
+            enabled: true,
+            exportEnabled: true,
+            sampleRate: 1.0,
+        },
+        [TelemetryTier.TIER_3_AI_EXPERIENCE]: {
+            enabled: true,
+            exportEnabled: true,
+            sampleRate: 1.0,
+        },
+    },
+    tier3Content: TIER3_CONTENT_POLICY_DEFAULT,
+    enforcementMode: EnforcementMode.ENFORCE,
+};
+/**
+ * Cloud-Prem deployment: Tier 1 local only, Tier 2/3 exported.
+ * Hashing/sanitization handled by OTEL Collector.
+ */
+export const CLOUD_PREM_DEFAULT_POLICY = {
+    deploymentType: DeploymentTypeEnum.CLOUD_PREM,
+    tiers: {
+        [TelemetryTier.TIER_1_LOCAL]: {
+            enabled: true,
+            exportEnabled: false,
+            sampleRate: 1.0,
+        },
+        [TelemetryTier.TIER_2_OPERATIONAL]: {
+            enabled: true,
+            exportEnabled: true,
+            sampleRate: 1.0,
+        },
+        [TelemetryTier.TIER_3_AI_EXPERIENCE]: {
+            enabled: true,
+            exportEnabled: true,
+            sampleRate: 1.0,
+        },
+    },
+    tier3Content: TIER3_CONTENT_POLICY_DEFAULT,
+    enforcementMode: EnforcementMode.ENFORCE,
+};
+/**
+ * Get the default policy for a deployment type.
+ */
+export function getDefaultPolicy(deploymentType) {
+    switch (deploymentType) {
+        case DeploymentTypeEnum.CLOUD:
+            return CLOUD_DEFAULT_POLICY;
+        case DeploymentTypeEnum.CLOUD_PREM:
+            return CLOUD_PREM_DEFAULT_POLICY;
+        default:
+            return CLOUD_DEFAULT_POLICY;
+    }
+}
+//# sourceMappingURL=policy.js.map

package/dist-esm/types/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/types/policy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,6EAA6E;AAC7E,OAAO,EAAE,kBAAkB,IAAI,cAAc,EAAE,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,aASX;AATD,WAAY,aAAa;IACvB,0EAA0E;IAC1E,8CAA6B,CAAA;IAE7B,sEAAsE;IACtE,0DAAyC,CAAA;IAEzC,sFAAsF;IACtF,8DAA6C,CAAA;AAC/C,CAAC,EATW,aAAa,KAAb,aAAa,QASxB;AAED,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,+BAA+B;IAC/B,kCAAe,CAAA;IACf,uBAAuB;IACvB,sCAAmB,CAAA;AACrB,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAgDD,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,kEAAkE;AAClE,MAAM,CAAC,MAAM,4BAA4B,GAAuB;IAC9D,oBAAoB,EAAE,IAAI;IAC1B,sBAAsB,EAAE,IAAI;IAC5B,0BAA0B,EAAE,IAAI;IAChC,cAAc,EAAE,KAAK;IACrB,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAEF,oDAAoD;AACpD,MAAM,CAAC,MAAM,6BAA6B,GAAuB;IAC/D,oBAAoB,EAAE,KAAK;IAC3B,sBAAsB,EAAE,IAAI;IAC5B,0BAA0B,EAAE,IAAI;IAChC,cAAc,EAAE,KAAK;IACrB,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAoB;IACnD,cAAc,EAAE,kBAAkB,CAAC,KAAK;IACxC,KAAK,EAAE;QACL,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE;YAC5B,OAAO,EAAE,IAAI;YACb,aAAa,EAAE,IAAI;YACnB,UAAU,EAAE,GAAG;SAChB;QACD,CAAC,aAAa,CAAC,kBAAkB,CAAC,EAAE;YAClC,OAAO,EAAE,IAAI;YACb,aAAa,EAAE,IAAI;YACnB,UAAU,EAAE,GAAG;SAChB;QACD,CAAC,aAAa,CAAC,oBAAoB,CAAC,EAAE;YACpC,OAAO,EAAE,IAAI;YACb,aAAa,EAAE,IAAI;YACnB,UAAU,EAAE,GAAG;SAChB;KACF;IACD,YAAY,EAAE,4BAA4B;IAC1C,eAAe,EAAE,eAAe,CAAC,OAAO;CACzC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAoB;IACxD,cAAc,EAAE,kBAAkB,CAAC,UAAU;IAC7C,KAAK,EAAE;QACL,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE;YAC5B,OAAO,EAAE,IAAI;YACb,aAAa,EAAE,KAAK;YACpB,UAAU,EAAE,GAAG;SAChB;QACD,CAAC,aAAa,CAAC,kBAAkB,CAAC,EAAE;YAClC,OAAO,EAAE,IAAI;YACb,aAAa,EAAE,IAAI;YACnB,UAAU,EAAE,GAAG;SAChB;QACD,CAAC,aAAa,CAAC,oBAAoB,CAAC,EAAE;YACpC,OAAO,EAAE,IAAI;YACb,aAAa,EAAE,IAAI;YACnB,UAAU,EAAE,GAAG;SAChB;KACF;IACD,YAAY,EAAE,4BAA4B;IAC1C,eAAe,EAAE,eAAe,CAAC,OAAO;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,cAAkC;IAElC,QAAQ,cAAc,EAAE,CAAC;QACvB,KAAK,kBAAkB,CAAC,KAAK;YAC3B,OAAO,oBAAoB,CAAC;QAC9B,KAAK,kBAAkB,CAAC,UAAU;YAChC,OAAO,yBAAyB,CAAC;QACnC;YACE,OAAO,oBAAoB,CAAC;IAChC,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/telemetry",
-  "version": "2.0.173-next.4",
+  "version": "2.0.174",
   "description": "Superblocks Telemetry - Canonical OTEL bootstrap with tier-aware policy enforcement",
   "license": "Superblocks Community Software License",
   "repository": {
@@ -10,31 +10,37 @@
   "files": [
     "LICENSE.txt",
     "dist",
+    "dist-esm",
     "README.md"
   ],
-  "type": "module",
   "main": "dist/index.js",
+  "module": "dist-esm/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "import": "./dist-esm/index.js",
+      "require": "./dist/index.js"
     },
     "./node": {
       "types": "./dist/node/index.d.ts",
-      "default": "./dist/node/index.js"
+      "import": "./dist-esm/node/index.js",
+      "require": "./dist/node/index.js"
     },
     "./browser": {
       "types": "./dist/browser/index.d.ts",
-      "default": "./dist/browser/index.js"
+      "import": "./dist-esm/browser/index.js",
+      "require": "./dist/browser/index.js"
     },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
-      "default": "./dist/testing/index.js"
+      "import": "./dist-esm/testing/index.js",
+      "require": "./dist/testing/index.js"
     },
     "./lint": {
       "types": "./dist/lint/index.d.ts",
-      "default": "./dist/lint/index.js"
+      "import": "./dist-esm/lint/index.js",
+      "require": "./dist/lint/index.js"
     }
   },
   "publishConfig": {
@@ -62,7 +68,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
-    "@superblocksteam/shared": "0.9619.4",
+    "@superblocksteam/shared": "0.9618.4",
     "@types/node": "^24",
     "chokidar-cli": "^3.0.0",
     "eslint": "^9.39.1",
@@ -75,15 +81,15 @@
     "vitest": "^4.1.11"
   },
   "peerDependencies": {
-    "@superblocksteam/shared": "0.9619.4"
+    "@superblocksteam/shared": "0.9618.4"
   },
   "engines": {
     "node": ">=24"
   },
   "scripts": {
-    "build": "tsc --build",
+    "build": "tsc --build && tsc --build tsconfig.browser.json && printf '{\"type\":\"module\"}\n' > dist-esm/package.json",
     "check": "npm run typecheck && npm run lint",
-    "clean": "premove ./dist *tsbuildinfo",
+    "clean": "premove ./dist ./dist-esm *tsbuildinfo",
     "dev": "chokidar \"**/*.ts\" -c \"npm run build\"",
     "lint": "eslint --max-warnings 0 --concurrency=2",
     "lint:fix": "eslint --fix --concurrency=2",