@friggframework/core 2.0.0--canary.622.faffe5f.0 → 2.0.0--canary.622.ce0381c.0

package/README.md

@@ -232,7 +232,7 @@ class HubSpotIntegration extends IntegrationBase {
 
 // Read the durable usage store (never an APM):
 const frigg = createFriggCommands({ integrationClass: HubSpotIntegration });
-await frigg.usage.totals({ metric: 'records.synced', groupBy: 'integrationType' });
+await frigg.usage.getTotalsByDimension({ metric: 'records.synced', groupBy: 'integrationType' });
 ```
 
 **See:** [`telemetry/README.md`](telemetry/README.md) for the full guide

package/application/commands/usage-commands.js

@@ -1,31 +1,15 @@
-/**
- * Usage Commands
- *
- * Application Layer — the read/write surface over the durable usage store.
- * Exposed as `frigg.usage.*` on the unified command object so
- * reports and integration code query usage without touching the repository.
- *
- * @example
- * const frigg = createFriggCommands({ integrationClass: MyIntegration });
- * await frigg.usage.totals({ metric: 'records.synced', groupBy: 'integrationType', since });
- * await frigg.usage.series({ metric: 'records.synced', integrationType: 'hubspot', bucket: 'day' });
- */
+// `frigg.usage.*` — the read/write surface over the durable usage store.
 const {
     createUsageRepository,
 } = require('../../usage/repositories/usage-repository-factory');
 const { computeUsageWindows } = require('../../telemetry/usage-windows');
 const { resolveNorthStarEntry } = require('../../telemetry/north-star');
 
-function createUsageCommands({ usageRepository, northStar = null } = {}) {
+function createUsageCommands({ usageRepository } = {}) {
     const repository = usageRepository || createUsageRepository();
 
     return {
-        /**
-         * Record a usage counter for a point in time. Callers pass `at` (a Date,
-         * default now) — NOT a raw window key — and both the day and hour windows
-         * are derived, matching how the auto-rollup persists so series() reads
-         * back consistently at either granularity.
-         */
+        // Increments both the day and hour window rows for `at`.
         async recordUsageCounter({
             integrationId,
             integrationType,
@@ -45,25 +29,20 @@ function createUsageCommands({ usageRepository, northStar = null } = {}) {
             }
         },
 
-        async totals(args) {
-            return repository.totals(args);
+        async getTotalsByDimension(args) {
+            return repository.getTotalsByDimension(args);
         },
 
-        async series(args) {
-            return repository.series(args);
+        async getTimeSeries(args) {
+            return repository.getTimeSeries(args);
         },
 
-        /**
-         * First-class North Star read. Resolves the
-         * configured counter for an integration type (byType wins over default),
-         * then returns its totals from the durable usage store. Returns `null`
-         * when no North Star is configured, so callers can branch without
-         * knowing the counter key. Trends read via `series({ metric })`.
-         */
-        async northStar({ integrationType, since, groupBy = 'integrationType', bucket } = {}) {
+        // Caller supplies the North Star config (Definition.telemetry.northStar);
+        // resolves the counter for the type (byType > default), null if none.
+        async getNorthStarTotals({ northStar, integrationType, since, groupBy = 'integrationType', bucket } = {}) {
             const entry = resolveNorthStarEntry(northStar, integrationType);
             if (!entry) return null;
-            const totals = await repository.totals({
+            const totals = await repository.getTotalsByDimension({
                 metric: entry.name,
                 groupBy,
                 since,

package/application/index.js

@@ -17,11 +17,6 @@ const { createUsageCommands } = require('./commands/usage-commands');
  *
  * @param {Object} params
  * @param {Object} params.integrationClass - Integration class (required)
- * @param {Object} [params.northStar] - Resolved North Star config
- *   (`Definition.telemetry.northStar`) so `frigg.usage.northStar(...)` can read
- *   it. Injected by the caller that owns the app definition
- *   (the handler/report runner) — the application layer never reaches up to load
- *   it. Omitted → usage reads report no North Star.
  * @returns {Object} Unified commands object with all CRUD operations
  *
  * @example
@@ -29,7 +24,7 @@ const { createUsageCommands } = require('./commands/usage-commands');
  * const user = await commands.createUser({ username: 'user@example.com' });
  * const credential = await commands.createCredential({ userId: user.id, ... });
  */
-function createFriggCommands({ integrationClass, northStar = null }) {
+function createFriggCommands({ integrationClass }) {
     // All commands use Frigg's default repositories and use cases
     const integrationCommands = createIntegrationCommands({ integrationClass });
 
@@ -57,9 +52,10 @@ function createFriggCommands({ integrationClass, northStar = null }) {
         // Process commands
         ...processCommands,
 
-        // Usage read/write — nested to match `frigg.usage.*`.
-        // northStar injected by the caller (composition root), not loaded here.
-        usage: createUsageCommands({ northStar }),
+        // Usage read/write — nested to match `frigg.usage.*`. The North Star
+        // read takes its config as a call argument, so nothing telemetry-specific
+        // is threaded through this general factory.
+        usage: createUsageCommands(),
     };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.622.faffe5f.0",
+    "version": "2.0.0--canary.622.ce0381c.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -45,9 +45,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.622.faffe5f.0",
-        "@friggframework/prettier-config": "2.0.0--canary.622.faffe5f.0",
-        "@friggframework/test": "2.0.0--canary.622.faffe5f.0",
+        "@friggframework/eslint-config": "2.0.0--canary.622.ce0381c.0",
+        "@friggframework/prettier-config": "2.0.0--canary.622.ce0381c.0",
+        "@friggframework/test": "2.0.0--canary.622.ce0381c.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -87,5 +87,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "faffe5ff8b3fea6bbb46a52502cbd5b5ecb35559"
+    "gitHead": "ce0381c83a8fdebf49352eb9cd6b38b360130025"
 }

package/reporting/use-cases/list-integrations-report.js

@@ -118,7 +118,7 @@ class ListIntegrationsReport {
         try {
             const totalsByMetric = await Promise.all(
                 metrics.map(async (metric) => {
-                    const totals = await this.usageRepository.totals({
+                    const totals = await this.usageRepository.getTotalsByDimension({
                         metric,
                         groupBy: 'integrationType',
                     });

package/telemetry/README.md

@@ -55,6 +55,15 @@ const Definition = {
 defaults to `none` (no per-event cost, no data written to CloudWatch). Point
 `exporter` at an OTLP backend to turn export on.
 
+**Sampling (`sampleRatio`, `0..1`, default `1`):** the fraction of **traces**
+exported — a cost knob for high-traffic fleets (`0.1` ≈ keep 10%). Whole traces
+are sampled (trace-ID-based + parent-based, so a distributed trace is never
+half-kept), and it does **not** thin the durable **usage counters** — those stay
+exact at any ratio (they ride the event bus, not the sampled trace pipeline). It
+is **not** error-aware: a low ratio drops failed-run traces too, so for "keep all
+errors, sample the rest" use tail-based sampling at an OTel Collector, not this
+knob. Typical: `1.0` in dev, lower (e.g. `0.1`) in high-volume prod.
+
 ### Environment variables
 
 | Variable | Purpose |
@@ -154,7 +163,7 @@ const { createFriggCommands } = require('@friggframework/core');
 const frigg = createFriggCommands({ integrationClass: HubSpotIntegration });
 
 // Apples-to-apples comparison across integration types:
-await frigg.usage.totals({
+await frigg.usage.getTotalsByDimension({
     metric: 'records.synced',
     groupBy: 'integrationType', // or 'metric'
     since: daysAgo(30),
@@ -163,7 +172,7 @@ await frigg.usage.totals({
 // → [{ integrationType: 'hubspot', value: 4200 }, { integrationType: 'salesforce', value: 1180 }]
 
 // Trend series for one type (aggregated across its instances):
-await frigg.usage.series({
+await frigg.usage.getTimeSeries({
     metric: 'records.synced',
     integrationType: 'hubspot',
     from: daysAgo(7),
@@ -211,19 +220,24 @@ Read it as a first-class metric without knowing the configured key — the North
 Star resolves per integration type (`byType` wins over `default`):
 
 ```js
-// Resolves the configured counter for the type, then returns its totals.
-await frigg.usage.northStar({ integrationType: 'hubspot', since: daysAgo(30) });
+// The caller passes the North Star config it already holds (from the app
+// definition); this resolves the counter for the type and returns its totals.
+await frigg.usage.getNorthStarTotals({
+    northStar: definition.telemetry.northStar,
+    integrationType: 'hubspot',
+    since: daysAgo(30),
+});
 // → { metric: 'contacts_synced', totals: [{ integrationType: 'hubspot', value: 900 }] }
-// → null when no North Star is configured (caller branches without knowing keys)
+// → null when `northStar` is absent or has no entry for the type
 ```
 
 Or read it like any counter once you know the key:
-`frigg.usage.totals({ metric: 'contacts_synced' })`; trends via `frigg.usage.series({ metric })`.
+`frigg.usage.getTotalsByDimension({ metric: 'contacts_synced' })`; trends via `frigg.usage.getTimeSeries({ metric })`.
 
-> `northStar` config is injected at the composition root — the caller that owns
-> the app definition passes it in: `createFriggCommands({ integrationClass, northStar })`
-> (the application layer never reaches up to load it). Omitted → `northStar()`
-> returns `null`.
+> The North Star read takes its config as a **call argument** — nothing
+> telemetry-specific is threaded through `createFriggCommands`. The caller that
+> owns the app definition (e.g. a report runner) passes `telemetry.northStar` in;
+> omit it and `getNorthStarTotals()` returns `null`.
 
 ## Plugin / extension tap
 
@@ -286,7 +300,7 @@ this.telemetry.count / auto-instrumented seam
                               │     (discards on SQS redelivery — approximate contract)
                               └─ your plugin taps
 
-frigg.usage.totals / series ◄── UsageCounter store ──► reporting usage columns
+frigg.usage.getTotalsByDimension / getTimeSeries ◄── UsageCounter store ──► reporting usage columns
 ```
 
 - **Flush is Lambda-safe:** `create-handler` awaits a bounded `forceFlush` in a

package/telemetry/exporters/console-exporter.js

@@ -0,0 +1,19 @@
+const {
+    TelemetryExporterInterface,
+} = require('./telemetry-exporter-interface');
+
+/** Console span/metric exporters — local-dev visibility, no network. */
+class ConsoleExporter extends TelemetryExporterInterface {
+    build() {
+        const {
+            ConsoleSpanExporter,
+        } = require('@opentelemetry/sdk-trace-base');
+        const { ConsoleMetricExporter } = require('@opentelemetry/sdk-metrics');
+        return {
+            traceExporter: new ConsoleSpanExporter(),
+            metricExporter: new ConsoleMetricExporter(),
+        };
+    }
+}
+
+module.exports = { ConsoleExporter };

package/telemetry/exporters/datadog-exporter.js

@@ -0,0 +1,11 @@
+const { OtlpExporter } = require('./otlp-exporter');
+
+/**
+ * Datadog ingests OTLP/HTTP directly, so today it behaves exactly like
+ * `OtlpExporter` (endpoint + headers). It is its own class so Datadog-specific
+ * presets (e.g. a default `DD-API-KEY` header) can be added later without
+ * touching the OTLP exporter or the registry.
+ */
+class DatadogExporter extends OtlpExporter {}
+
+module.exports = { DatadogExporter };

package/telemetry/exporters/honeycomb-exporter.js

@@ -0,0 +1,13 @@
+const { OtlpExporter } = require('./otlp-exporter');
+
+/** Honeycomb: an OTLP preset — default endpoint + `x-honeycomb-team` from apiKey. */
+class HoneycombExporter extends OtlpExporter {
+    constructor({ endpoint, apiKey, headers } = {}) {
+        super({
+            endpoint: endpoint || 'https://api.honeycomb.io',
+            headers: apiKey ? { 'x-honeycomb-team': apiKey } : headers,
+        });
+    }
+}
+
+module.exports = { HoneycombExporter };

package/telemetry/exporters/otlp-exporter.js

@@ -0,0 +1,42 @@
+const {
+    TelemetryExporterInterface,
+} = require('./telemetry-exporter-interface');
+
+/**
+ * OTLP/HTTP exporter to a configured endpoint (+ optional headers). With no
+ * endpoint the OTel SDK falls back to the standard `OTEL_EXPORTER_OTLP_ENDPOINT`
+ * env var, so `url` is left unset in that case.
+ */
+class OtlpExporter extends TelemetryExporterInterface {
+    constructor({ endpoint, headers } = {}) {
+        super();
+        this.endpoint = endpoint;
+        this.headers = headers;
+    }
+
+    build() {
+        const {
+            OTLPTraceExporter,
+        } = require('@opentelemetry/exporter-trace-otlp-http');
+        const {
+            OTLPMetricExporter,
+        } = require('@opentelemetry/exporter-metrics-otlp-http');
+        return {
+            traceExporter: new OTLPTraceExporter(this._options('/v1/traces')),
+            metricExporter: new OTLPMetricExporter(this._options('/v1/metrics')),
+        };
+    }
+
+    _options(path) {
+        return {
+            ...(this.endpoint ? { url: joinPath(this.endpoint, path) } : {}),
+            ...(this.headers ? { headers: this.headers } : {}),
+        };
+    }
+}
+
+function joinPath(base, path) {
+    return `${String(base).replace(/\/$/, '')}${path}`;
+}
+
+module.exports = { OtlpExporter };

package/telemetry/exporters/passthrough-exporter.js

@@ -0,0 +1,25 @@
+const {
+    TelemetryExporterInterface,
+} = require('./telemetry-exporter-interface');
+
+/**
+ * Adopter/test-supplied exporter instances, used as-is (e.g. in-memory exporters
+ * in tests, or an advanced adopter wiring its own OTel exporter). Pre-built
+ * instances win over a `type`.
+ */
+class PassthroughExporter extends TelemetryExporterInterface {
+    constructor({ traceExporter = null, metricExporter = null } = {}) {
+        super();
+        this.traceExporter = traceExporter;
+        this.metricExporter = metricExporter;
+    }
+
+    build() {
+        return {
+            traceExporter: this.traceExporter,
+            metricExporter: this.metricExporter,
+        };
+    }
+}
+
+module.exports = { PassthroughExporter };

package/telemetry/exporters/resolve-exporter.js

@@ -0,0 +1,39 @@
+const { PassthroughExporter } = require('./passthrough-exporter');
+const { ConsoleExporter } = require('./console-exporter');
+const { OtlpExporter } = require('./otlp-exporter');
+const { HoneycombExporter } = require('./honeycomb-exporter');
+const { DatadogExporter } = require('./datadog-exporter');
+
+// type → exporter adapter. Add a destination by adding a class + one entry.
+const EXPORTERS = {
+    console: ConsoleExporter,
+    otlp: OtlpExporter,
+    datadog: DatadogExporter,
+    honeycomb: HoneycombExporter,
+};
+
+/**
+ * Resolve the exporter adapter for a telemetry descriptor. Pre-built exporter
+ * instances (tests / advanced adopters) win over `type`; an unknown or absent
+ * type falls back to plain OTLP (which itself falls back to the standard OTLP
+ * env var). Replaces the former switch-based factory with polymorphic adapters.
+ *
+ * @returns {import('./telemetry-exporter-interface').TelemetryExporterInterface}
+ */
+function resolveExporter(descriptor = {}) {
+    if (descriptor.traceExporter || descriptor.metricExporter) {
+        return new PassthroughExporter(descriptor);
+    }
+    // Own-property check so a `type` matching an Object.prototype member
+    // ('constructor', 'toString', …) can't resolve an inherited key — unknown
+    // types must fall through to plain OTLP.
+    const Exporter = Object.prototype.hasOwnProperty.call(
+        EXPORTERS,
+        descriptor.type
+    )
+        ? EXPORTERS[descriptor.type]
+        : OtlpExporter;
+    return new Exporter(descriptor);
+}
+
+module.exports = { resolveExporter, EXPORTERS };

package/telemetry/exporters/telemetry-exporter-interface.js

@@ -0,0 +1,17 @@
+/**
+ * Port for a telemetry exporter: builds the OTel trace + metric exporter
+ * instances for one destination. Adapters (console, otlp, honeycomb, datadog, a
+ * passthrough for pre-built instances) implement `build()`. OpenTelemetry SDK
+ * packages are `require`d lazily inside `build()` so merely loading an adapter
+ * pulls in no OTel modules.
+ */
+class TelemetryExporterInterface {
+    /** @returns {{ traceExporter: object|null, metricExporter: object|null }} */
+    build() {
+        throw new Error(
+            'build() must be implemented by a TelemetryExporter subclass'
+        );
+    }
+}
+
+module.exports = { TelemetryExporterInterface };

package/telemetry/index.js

@@ -1,12 +1,15 @@
 const { createTelemetry, isNoOpExporter } = require('./telemetry-service');
-const { createNoOpTelemetry } = require('./no-op-telemetry');
+const {
+    TelemetryServiceInterface,
+} = require('./telemetry-service-interface');
+const { NoOpTelemetry } = require('./no-op-telemetry');
 const { createTelemetryEventBus } = require('./telemetry-event-bus');
 const { resolveTelemetryConfig } = require('./telemetry-config');
 const {
     getTelemetry,
     resetTelemetryForTests,
 } = require('./telemetry-singleton');
-const { buildExporters } = require('./exporters/exporter-factory');
+const { resolveExporter } = require('./exporters/resolve-exporter');
 const { instrumentHandler } = require('./instrument-handler');
 const { bindTelemetryContext } = require('./bind-telemetry-context');
 const { createUsageRollupSubscriber } = require('./usage-rollup-subscriber');
@@ -32,13 +35,14 @@ const {
 
 module.exports = {
     createTelemetry,
-    createNoOpTelemetry,
+    TelemetryServiceInterface,
+    NoOpTelemetry,
     createTelemetryEventBus,
     resolveTelemetryConfig,
     getTelemetry,
     resetTelemetryForTests,
     isNoOpExporter,
-    buildExporters,
+    resolveExporter,
     instrumentHandler,
     bindTelemetryContext,
     createUsageRollupSubscriber,

package/telemetry/no-op-telemetry.js

@@ -1,3 +1,6 @@
+const {
+    TelemetryServiceInterface,
+} = require('./telemetry-service-interface');
 const { createTelemetryEventBus } = require('./telemetry-event-bus');
 const {
     runWithTelemetryContext,
@@ -5,62 +8,64 @@ const {
 } = require('./telemetry-context');
 
 /**
- * No-op telemetry implementation.
- *
- * This is the default when no OTel exporter is configured, so telemetry "rides
- * for free": integration code can call `this.telemetry.*`
- * unconditionally and it costs nothing on the OTel side. Critically, this module
- * imports **zero** OpenTelemetry packages — the no-op path never loads the OTel
- * SDK (guarded by a require-graph test), protecting Lambda cold-start.
- *
- * The internal event bus is still active here (Decision 7): `count`/`event` are
- * mirrored onto it so the durable usage rollup and plugin/extension taps work
- * even with OTel export disabled. Emitting to a bus with no subscribers is a
- * cheap no-op.
- *
- * @param {object} [options]
- * @param {object} [options.bus] Event bus to mirror emissions onto.
+ * No-op telemetry adapter: the default when no exporter is configured, so
+ * telemetry "rides for free". Imports **zero** OpenTelemetry packages (guarded by
+ * a require-graph test) — the no-op path never loads the OTel SDK, protecting
+ * Lambda cold-start. The internal event bus is still active: `count`/`event` are
+ * mirrored onto it so the durable usage rollup + plugin taps work even with
+ * export off (emitting to a bus with no subscribers is cheap).
  */
-function createNoOpTelemetry({ bus = createTelemetryEventBus() } = {}) {
-    const noop = {
-        count(name, value = 1, attributes = {}, context) {
-            const merged = mergeTelemetryContext(context);
-            const payload = { name, value, attributes };
-            if (merged) payload.context = merged;
-            bus.emit('metric', payload);
-        },
-        event(name, attributes = {}, context) {
-            const merged = mergeTelemetryContext(context);
-            const payload = { name, attributes };
-            if (merged) payload.context = merged;
-            bus.emit('event', payload);
-        },
-        async span(_name, fn) {
-            return typeof fn === 'function' ? fn() : undefined;
-        },
-        startSpan() {
-            return {
-                setAttributes() {},
-                setAttribute() {},
-                recordException() {},
-                setStatus() {},
-                end() {},
-            };
-        },
-        async withContext(context, fn) {
-            return runWithTelemetryContext(context, () =>
-                typeof fn === 'function' ? fn() : undefined
-            );
-        },
-        on(eventType, callback) {
-            return bus.on(eventType, callback);
-        },
-        async forceFlush() {},
-        isEnabled() {
-            return false;
-        },
-    };
-    return noop;
+class NoOpTelemetry extends TelemetryServiceInterface {
+    constructor({ bus = createTelemetryEventBus() } = {}) {
+        super();
+        this._bus = bus;
+    }
+
+    count(name, value = 1, attributes = {}, context) {
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, value, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('metric', payload);
+    }
+
+    event(name, attributes = {}, context) {
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('event', payload);
+    }
+
+    async span(_name, fn) {
+        return typeof fn === 'function' ? fn() : undefined;
+    }
+
+    startSpan() {
+        return {
+            setAttributes() {},
+            setAttribute() {},
+            recordException() {},
+            setStatus() {},
+            end() {},
+        };
+    }
+
+    async withContext(context, fn) {
+        return runWithTelemetryContext(context, () =>
+            typeof fn === 'function' ? fn() : undefined
+        );
+    }
+
+    on(eventType, callback) {
+        return this._bus.on(eventType, callback);
+    }
+
+    async forceFlush() {}
+
+    async shutdown() {}
+
+    isEnabled() {
+        return false;
+    }
 }
 
-module.exports = { createNoOpTelemetry };
+module.exports = { NoOpTelemetry };

package/telemetry/north-star.js

@@ -1,7 +1,7 @@
 /**
  * Adopter North Star metric. A North Star simply references
  * a usage-counter key (canonical or custom); its value is then read like any
- * other counter via `frigg.usage.totals({ metric: northStarKey })`. It is
+ * other counter via `frigg.usage.getTotalsByDimension({ metric: northStarKey })`. It is
  * populated either by (a) direct emission of that counter, or (b) derived from a
  * framework trace signal — this module implements (b) as a small bus subscriber
  * that emits the North Star counter when a configured signal matches.

package/telemetry/otel-telemetry.js

@@ -11,7 +11,10 @@ const {
     PeriodicExportingMetricReader,
 } = require('@opentelemetry/sdk-metrics');
 const { resourceFromAttributes } = require('@opentelemetry/resources');
-const { buildExporters } = require('./exporters/exporter-factory');
+const {
+    TelemetryServiceInterface,
+} = require('./telemetry-service-interface');
+const { resolveExporter } = require('./exporters/resolve-exporter');
 const { createTelemetryEventBus } = require('./telemetry-event-bus');
 const {
     runWithTelemetryContext,
@@ -47,169 +50,169 @@ function ensureContextManager() {
 }
 
 /**
- * The OpenTelemetry-backed telemetry service. Reached only
- * when a real exporter is configured; `createTelemetry` returns the no-op
- * otherwise. `BatchSpanProcessor` is used uniformly — spans are delivered by the
- * bounded `forceFlush()` the Lambda handler awaits before the container freezes
- * (`callbackWaitsForEmptyEventLoop=false`), never by background timers.
+ * OpenTelemetry-backed telemetry adapter. Constructed only when a real exporter
+ * is configured (`createTelemetry` returns the no-op otherwise). `BatchSpanProcessor`
+ * is used uniformly — spans are delivered by the bounded `forceFlush()` the Lambda
+ * handler awaits before the container freezes (`callbackWaitsForEmptyEventLoop=false`),
+ * never by background timers.
  */
-function createOtelTelemetry({
-    exporter,
-    resource = {},
-    sampleRatio,
-    bus = createTelemetryEventBus(),
-} = {}) {
-    ensureContextManager();
-    const { traceExporter, metricExporter } = buildExporters(exporter);
-
-    const resourceAttrs = {
-        'service.name': resource.service || 'frigg',
-    };
-    if (resource.stage) {
-        resourceAttrs['deployment.environment'] = resource.stage;
-        resourceAttrs.stage = resource.stage;
+class OtelTelemetry extends TelemetryServiceInterface {
+    constructor({
+        exporter,
+        resource = {},
+        sampleRatio,
+        bus = createTelemetryEventBus(),
+    } = {}) {
+        super();
+        ensureContextManager();
+        const { traceExporter, metricExporter } =
+            resolveExporter(exporter).build();
+
+        const resourceAttrs = { 'service.name': resource.service || 'frigg' };
+        if (resource.stage) {
+            resourceAttrs['deployment.environment'] = resource.stage;
+            resourceAttrs.stage = resource.stage;
+        }
+        if (resource.appName) resourceAttrs.appName = resource.appName;
+        const res = resourceFromAttributes(resourceAttrs);
+
+        const sampler =
+            typeof sampleRatio === 'number' && sampleRatio < 1
+                ? new ParentBasedSampler({
+                      root: new TraceIdRatioBasedSampler(sampleRatio),
+                  })
+                : new AlwaysOnSampler();
+
+        this._tracerProvider = new BasicTracerProvider({
+            resource: res,
+            sampler,
+            spanProcessors: traceExporter
+                ? [new BatchSpanProcessor(traceExporter)]
+                : [],
+        });
+
+        const metricReader = metricExporter
+            ? new PeriodicExportingMetricReader({
+                  exporter: metricExporter,
+                  exportIntervalMillis: METRIC_EXPORT_INTERVAL_MS,
+              })
+            : null;
+        this._meterProvider = new MeterProvider({
+            resource: res,
+            readers: metricReader ? [metricReader] : [],
+        });
+
+        this._bus = bus;
+        this._tracer = this._tracerProvider.getTracer(TRACER_NAME);
+        this._meter = this._meterProvider.getMeter(TRACER_NAME);
+        // One instrument instance per metric name — OTel requires it, and
+        // re-creating a counter would drop data points.
+        this._counters = new Map();
     }
-    if (resource.appName) resourceAttrs.appName = resource.appName;
-    const res = resourceFromAttributes(resourceAttrs);
 
-    const sampler =
-        typeof sampleRatio === 'number' && sampleRatio < 1
-            ? new ParentBasedSampler({
-                  root: new TraceIdRatioBasedSampler(sampleRatio),
-              })
-            : new AlwaysOnSampler();
-
-    const tracerProvider = new BasicTracerProvider({
-        resource: res,
-        sampler,
-        spanProcessors: traceExporter
-            ? [new BatchSpanProcessor(traceExporter)]
-            : [],
-    });
-
-    const metricReader = metricExporter
-        ? new PeriodicExportingMetricReader({
-              exporter: metricExporter,
-              exportIntervalMillis: METRIC_EXPORT_INTERVAL_MS,
-          })
-        : null;
-    const meterProvider = new MeterProvider({
-        resource: res,
-        readers: metricReader ? [metricReader] : [],
-    });
-
-    const tracer = tracerProvider.getTracer(TRACER_NAME);
-    const meter = meterProvider.getMeter(TRACER_NAME);
-
-    // Counters/UpDownCounters are cached — OTel requires one instrument instance
-    // per metric name, and re-creating them would drop data points.
-    const counters = new Map();
-    function getCounter(name) {
-        if (!counters.has(name)) counters.set(name, meter.createCounter(name));
-        return counters.get(name);
+    _getCounter(name) {
+        if (!this._counters.has(name)) {
+            this._counters.set(name, this._meter.createCounter(name));
+        }
+        return this._counters.get(name);
     }
 
-    const service = {
-        count(name, value = 1, attributes = {}, context) {
+    count(name, value = 1, attributes = {}, context) {
+        try {
+            this._getCounter(name).add(value, attributes);
+        } catch (_) {
+            // Telemetry must never break the wrapped path.
+        }
+        // Mirror onto the internal stream for the usage rollup + plugin taps; the
+        // bus context (incl. high-cardinality ids) rides the bus only, never the
+        // OTel metric attributes.
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, value, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('metric', payload);
+    }
+
+    event(name, attributes = {}, context) {
+        try {
+            const active = otelApi.trace.getActiveSpan();
+            if (active) active.addEvent(name, attributes);
+        } catch (_) {}
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('event', payload);
+    }
+
+    startSpan(name, options) {
+        return this._tracer.startSpan(name, options);
+    }
+
+    async span(name, fn, options = {}) {
+        return this._tracer.startActiveSpan(name, options, async (span) => {
             try {
-                getCounter(name).add(value, attributes);
-            } catch (_) {
-                // Telemetry must never break the wrapped path.
+                const result =
+                    typeof fn === 'function' ? await fn(span) : undefined;
+                span.setStatus({ code: otelApi.SpanStatusCode.OK });
+                return result;
+            } catch (err) {
+                span.recordException(err);
+                span.setStatus({
+                    code: otelApi.SpanStatusCode.ERROR,
+                    message: err && err.message,
+                });
+                throw err;
+            } finally {
+                span.end();
             }
-            // Mirror onto the internal stream for the usage rollup + plugin taps.
-            // The bus `context` merges the ambient handler context (incl.
-            // high-cardinality ids) with any explicit per-call context — it rides
-            // the bus only, never the OTel metric attributes (Cardinality note).
-            const merged = mergeTelemetryContext(context);
-            const payload = { name, value, attributes };
-            if (merged) payload.context = merged;
-            bus.emit('metric', payload);
-        },
-
-        event(name, attributes = {}, context) {
-            try {
-                const active = otelApi.trace.getActiveSpan();
-                if (active) active.addEvent(name, attributes);
-            } catch (_) {}
-            const merged = mergeTelemetryContext(context);
-            const payload = { name, attributes };
-            if (merged) payload.context = merged;
-            bus.emit('event', payload);
-        },
-
-        startSpan(name, options) {
-            return tracer.startSpan(name, options);
-        },
-
-        async span(name, fn, options = {}) {
-            return tracer.startActiveSpan(name, options, async (span) => {
-                try {
-                    const result =
-                        typeof fn === 'function' ? await fn(span) : undefined;
-                    span.setStatus({ code: otelApi.SpanStatusCode.OK });
-                    return result;
-                } catch (err) {
-                    span.recordException(err);
-                    span.setStatus({
-                        code: otelApi.SpanStatusCode.ERROR,
-                        message: err && err.message,
-                    });
-                    throw err;
-                } finally {
-                    span.end();
-                }
-            });
-        },
-
-        /**
-         * Run `fn` with the given identifiers on (a) the AsyncLocalStorage
-         * telemetry context — which the usage rollup reads to attribute emissions
-         * per-integration on ANY path — and (b) OTel baggage for trace
-         * propagation. High-cardinality ids ride here, never on metric labels.
-         */
-        async withContext(attributes = {}, fn) {
-            const entries = {};
-            for (const [key, value] of Object.entries(attributes)) {
-                if (value !== undefined && value !== null) {
-                    entries[key] = { value: String(value) };
-                }
+        });
+    }
+
+    /**
+     * Run `fn` with the given identifiers on (a) the AsyncLocalStorage telemetry
+     * context — which the usage rollup reads to attribute emissions per-integration
+     * on ANY path — and (b) OTel baggage for trace propagation. High-cardinality
+     * ids ride here, never on metric labels.
+     */
+    async withContext(attributes = {}, fn) {
+        const entries = {};
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value !== undefined && value !== null) {
+                entries[key] = { value: String(value) };
             }
-            const baggage = otelApi.propagation.createBaggage(entries);
-            const ctx = otelApi.propagation.setBaggage(
-                otelApi.context.active(),
-                baggage
-            );
-            return runWithTelemetryContext(attributes, () =>
-                otelApi.context.with(ctx, () =>
-                    typeof fn === 'function' ? fn() : undefined
-                )
-            );
-        },
-
-        on(eventType, callback) {
-            return bus.on(eventType, callback);
-        },
-
-        async forceFlush() {
-            await Promise.allSettled([
-                tracerProvider.forceFlush(),
-                meterProvider.forceFlush(),
-            ]);
-        },
-
-        async shutdown() {
-            await Promise.allSettled([
-                tracerProvider.shutdown(),
-                meterProvider.shutdown(),
-            ]);
-        },
-
-        isEnabled() {
-            return true;
-        },
-    };
-
-    return service;
+        }
+        const baggage = otelApi.propagation.createBaggage(entries);
+        const ctx = otelApi.propagation.setBaggage(
+            otelApi.context.active(),
+            baggage
+        );
+        return runWithTelemetryContext(attributes, () =>
+            otelApi.context.with(ctx, () =>
+                typeof fn === 'function' ? fn() : undefined
+            )
+        );
+    }
+
+    on(eventType, callback) {
+        return this._bus.on(eventType, callback);
+    }
+
+    async forceFlush() {
+        await Promise.allSettled([
+            this._tracerProvider.forceFlush(),
+            this._meterProvider.forceFlush(),
+        ]);
+    }
+
+    async shutdown() {
+        await Promise.allSettled([
+            this._tracerProvider.shutdown(),
+            this._meterProvider.shutdown(),
+        ]);
+    }
+
+    isEnabled() {
+        return true;
+    }
 }
 
-module.exports = { createOtelTelemetry };
+module.exports = { OtelTelemetry };

package/telemetry/telemetry-config.js

@@ -37,6 +37,8 @@ function resolveExporter(exporter, stage) {
     return exporter;
 }
 
+// Fraction of TRACES exported (0..1, default 1) — a cost knob wired to the OTel
+// sampler in otel-telemetry. Does NOT thin usage counters; those stay exact.
 function resolveSampleRatio(sampleRatio) {
     if (sampleRatio === undefined || sampleRatio === null) return 1;
     if (
@@ -61,7 +63,7 @@ function validateNorthStarEntry(entry, where) {
 }
 
 /**
- * Adopter-declared telemetry subscribers (Decision 6). Each is either a factory
+ * Adopter-declared telemetry subscribers. Each is either a factory
  * function `fn(telemetry)` or a declarative `{ event?, handler }` object. Kept as
  * an array so `wireTelemetrySubscribers` can attach them to the bus at runtime.
  */

package/telemetry/telemetry-service-interface.js

@@ -0,0 +1,49 @@
+/**
+ * Telemetry service port. Application code uses this contract via `this.telemetry`;
+ * adapters implement it — `OtelTelemetry` (real OTLP export) and `NoOpTelemetry`
+ * (default, zero OTel). Kept free of OpenTelemetry imports so the no-op path
+ * loads no OTel modules.
+ *
+ * `count`/`event` mirror onto the internal event bus (for the usage rollup +
+ * plugin taps); `span`/`startSpan`/`withContext` handle tracing + context
+ * propagation; `forceFlush`/`shutdown` drain before the Lambda container freezes.
+ */
+class TelemetryServiceInterface {
+    count(/* name, value, attributes, context */) {
+        throw new Error('count must be implemented by subclass');
+    }
+
+    event(/* name, attributes, context */) {
+        throw new Error('event must be implemented by subclass');
+    }
+
+    startSpan(/* name, options */) {
+        throw new Error('startSpan must be implemented by subclass');
+    }
+
+    async span(/* name, fn, options */) {
+        throw new Error('span must be implemented by subclass');
+    }
+
+    async withContext(/* attributes, fn */) {
+        throw new Error('withContext must be implemented by subclass');
+    }
+
+    on(/* eventType, callback */) {
+        throw new Error('on must be implemented by subclass');
+    }
+
+    async forceFlush() {
+        throw new Error('forceFlush must be implemented by subclass');
+    }
+
+    async shutdown() {
+        throw new Error('shutdown must be implemented by subclass');
+    }
+
+    isEnabled() {
+        throw new Error('isEnabled must be implemented by subclass');
+    }
+}
+
+module.exports = { TelemetryServiceInterface };

package/telemetry/telemetry-service.js

@@ -1,4 +1,4 @@
-const { createNoOpTelemetry } = require('./no-op-telemetry');
+const { NoOpTelemetry } = require('./no-op-telemetry');
 const { createTelemetryEventBus } = require('./telemetry-event-bus');
 
 /**
@@ -12,12 +12,10 @@ function isNoOpExporter(exporter) {
 }
 
 /**
- * Create the vendor-neutral telemetry service.
- *
- * Integration code uses the returned object (`this.telemetry`) and never imports
- * a backend SDK. When no exporter is configured the service is a pure no-op that
- * loads zero OpenTelemetry modules; a real exporter lazily initialises the OTel
- * SDK (see `./otel-telemetry`).
+ * Create the vendor-neutral telemetry service — the adapter selector. Integration
+ * code uses the returned instance (`this.telemetry`) and never imports a backend
+ * SDK. With no exporter configured it returns `NoOpTelemetry` (loads zero OTel);
+ * a real exporter lazily constructs `OtelTelemetry`.
  *
  * @param {object} [options]
  * @param {object} [options.exporter] Exporter descriptor, e.g. `{ type: 'otlp', endpoint }`.
@@ -33,12 +31,12 @@ function createTelemetry(options = {}) {
     const bus = options.bus || createTelemetryEventBus();
 
     if (isNoOpExporter(options.exporter)) {
-        return createNoOpTelemetry({ bus });
+        return new NoOpTelemetry({ bus });
     }
 
     // Lazy-required so the no-op path never loads the OTel SDK.
-    const { createOtelTelemetry } = require('./otel-telemetry');
-    return createOtelTelemetry({ ...options, bus });
+    const { OtelTelemetry } = require('./otel-telemetry');
+    return new OtelTelemetry({ ...options, bus });
 }
 
 module.exports = { createTelemetry, isNoOpExporter };

package/telemetry/telemetry-singleton.js

@@ -1,5 +1,5 @@
 const { createTelemetry } = require('./telemetry-service');
-const { createNoOpTelemetry } = require('./no-op-telemetry');
+const { NoOpTelemetry } = require('./no-op-telemetry');
 
 /**
  * Process-wide telemetry singleton. Created lazily on first use and
@@ -28,7 +28,7 @@ function getTelemetry() {
             },
         });
     } catch (_) {
-        instance = createNoOpTelemetry();
+        instance = new NoOpTelemetry();
     }
     return instance;
 }

package/usage/README.md

@@ -32,21 +32,21 @@ const { createUsageRepository } = require('@friggframework/core'); // usage-repo
 
 class UsageRepositoryInterface {
     async increment({ integrationId, integrationType, metric, window, value }) {} // atomic upsert
-    async totals({ metric, groupBy, since, bucket }) {}   // comparison (one window granularity)
-    async series({ metric, integrationType, from, to, bucket }) {} // trend (aggregated across instances)
+    async getTotalsByDimension({ metric, groupBy, since, bucket }) {}   // comparison (one window granularity)
+    async getTimeSeries({ metric, integrationType, from, to, bucket }) {} // trend (aggregated across instances)
 }
 ```
 
 - **`increment`** is atomic: PostgreSQL uses Prisma `upsert` with
   `{ value: { increment } }`; a concurrent first-insert race (`P2002`) retries
   once onto the atomic update path.
-- **`totals`** filters to a single window granularity (default `day`) so day and
+- **`getTotalsByDimension`** filters to a single window granularity (default `day`) so day and
   hour rows are never double-summed. Requires a `metric`; `groupBy` is
   allow-listed to `integrationType` / `metric`.
-- **`series`** aggregates across integration instances (`groupBy(window) + sum`)
+- **`getTimeSeries`** aggregates across integration instances (`groupBy(window) + sum`)
   and range-filters on the window key. Requires an `integrationType`.
 
-> **DocumentDB:** the adapter overrides increment/totals/series with raw commands
+> **DocumentDB:** the adapter overrides increment/getTotalsByDimension/getTimeSeries with raw commands
 > (`$runCommandRaw`: a `$inc` upsert via `documentdb-utils.updateOne`, and a
 > cursor-drained `$aggregate` `$group/$sum`) — matching every other DocumentDB
 > adapter, since Prisma's Mongo engine emits upsert/groupBy shapes DocumentDB

package/usage/repositories/usage-repository-documentdb.js

@@ -14,7 +14,7 @@ const VALID_BUCKETS = new Set(['day', 'hour']);
  * and `groupBy({ _sum })`, and cursor reads truncate at ~101 docs — so, like
  * every other DocumentDB adapter in this repo, these operations are issued as
  * raw commands (`$runCommandRaw`) via the validated documentdb-utils helpers and
- * a drained aggregate cursor. No timestamps are managed: totals/series filter on
+ * a drained aggregate cursor. No timestamps are managed: getTotalsByDimension/getTimeSeries filter on
  * the window KEY (not write-time), so createdAt/updatedAt are unnecessary here.
  */
 class UsageRepositoryDocumentDB extends UsageRepositoryMongo {
@@ -44,20 +44,20 @@ class UsageRepositoryDocumentDB extends UsageRepositoryMongo {
         );
     }
 
-    async totals({
+    async getTotalsByDimension({
         metric,
         groupBy = 'integrationType',
         since,
         bucket = 'day',
     } = {}) {
         if (!metric) {
-            throw new Error('totals requires a metric (units are per-metric)');
+            throw new Error('getTotalsByDimension requires a metric (units are per-metric)');
         }
         assertGroupBy(groupBy);
         assertBucket(bucket);
 
         // Single window granularity (day: OR hour:) — never sum across both.
-        // `since` bounds on the window KEY (mirrors series / the Prisma adapter).
+        // `since` bounds on the window KEY (mirrors getTimeSeries / the Prisma adapter).
         const rows = await this._aggregateDrained([
             {
                 $match: {
@@ -76,10 +76,10 @@ class UsageRepositoryDocumentDB extends UsageRepositoryMongo {
         }));
     }
 
-    async series({ metric, integrationType, from, to, bucket = 'day' } = {}) {
+    async getTimeSeries({ metric, integrationType, from, to, bucket = 'day' } = {}) {
         assertBucket(bucket);
         if (!integrationType) {
-            throw new Error('series requires an integrationType');
+            throw new Error('getTimeSeries requires an integrationType');
         }
 
         const rows = await this._aggregateDrained([

package/usage/repositories/usage-repository-interface.js

@@ -21,16 +21,16 @@ class UsageRepositoryInterface {
      * Sum a metric grouped by a bounded dimension since an optional timestamp.
      * @returns {Promise<Array<{[groupBy]: string, value: number}>>}
      */
-    async totals(/* { metric, groupBy, since } */) {
-        throw new Error('totals must be implemented by subclass');
+    async getTotalsByDimension(/* { metric, groupBy, since } */) {
+        throw new Error('getTotalsByDimension must be implemented by subclass');
     }
 
     /**
      * Time series of a metric for one integration type.
      * @returns {Promise<Array<{bucket: string, value: number}>>}
      */
-    async series(/* { metric, integrationType, from, to, bucket } */) {
-        throw new Error('series must be implemented by subclass');
+    async getTimeSeries(/* { metric, integrationType, from, to, bucket } */) {
+        throw new Error('getTimeSeries must be implemented by subclass');
     }
 }
 

package/usage/repositories/usage-repository-postgres.js

@@ -52,14 +52,14 @@ class UsageRepositoryPostgres extends UsageRepositoryInterface {
         }
     }
 
-    async totals({
+    async getTotalsByDimension({
         metric,
         groupBy = 'integrationType',
         since,
         bucket = 'day',
     } = {}) {
         if (!metric) {
-            throw new Error('totals requires a metric (units are per-metric)');
+            throw new Error('getTotalsByDimension requires a metric (units are per-metric)');
         }
         assertGroupBy(groupBy);
         assertBucket(bucket);
@@ -67,7 +67,7 @@ class UsageRepositoryPostgres extends UsageRepositoryInterface {
         // Filter to ONE window granularity — every event is written to both a
         // day: and an hour: row, so summing across granularities would double
         // (or worse) the true count.
-        // Bound `since` on the WINDOW key (mirrors series) — write-time
+        // Bound `since` on the WINDOW key (mirrors getTimeSeries) — write-time
         // updatedAt would misplace a late/redelivered increment for an earlier
         // window, over- or under-counting the time-bounded total.
         const where = { metric, window: { startsWith: `${bucket}:` } };
@@ -87,10 +87,10 @@ class UsageRepositoryPostgres extends UsageRepositoryInterface {
         }));
     }
 
-    async series({ metric, integrationType, from, to, bucket = 'day' } = {}) {
+    async getTimeSeries({ metric, integrationType, from, to, bucket = 'day' } = {}) {
         assertBucket(bucket);
         if (!integrationType) {
-            throw new Error('series requires an integrationType');
+            throw new Error('getTimeSeries requires an integrationType');
         }
 
         // Range-filter on the WINDOW key (write-time `updatedAt` would misplace a

package/telemetry/exporters/exporter-factory.js

@@ -1,79 +0,0 @@
-/**
- * Builds OpenTelemetry span/metric exporters from an app-definition descriptor.
- * All OTel packages are lazy-`require`d here so the no-op
- * path (which never calls this) loads zero OTel modules.
- *
- * Supported descriptor `type`s:
- *   - 'console'            → ConsoleSpanExporter / ConsoleMetricExporter (local dev)
- *   - 'otlp'               → OTLP/HTTP to descriptor.endpoint (+ headers)
- *   - 'honeycomb'          → OTLP preset (api.honeycomb.io, x-honeycomb-team header)
- *   - 'datadog'            → OTLP preset (descriptor.endpoint required)
- *
- * A descriptor may also carry pre-built exporter instances
- * (`traceExporter` / `metricExporter`) — used by tests (in-memory exporters) and
- * advanced adopters. Instances win over `type`.
- *
- * @returns {{ traceExporter: object|null, metricExporter: object|null }}
- */
-function buildExporters(descriptor = {}) {
-    if (descriptor.traceExporter || descriptor.metricExporter) {
-        return {
-            traceExporter: descriptor.traceExporter || null,
-            metricExporter: descriptor.metricExporter || null,
-        };
-    }
-
-    const type = descriptor.type;
-
-    if (type === 'console') {
-        const {
-            ConsoleSpanExporter,
-        } = require('@opentelemetry/sdk-trace-base');
-        const { ConsoleMetricExporter } = require('@opentelemetry/sdk-metrics');
-        return {
-            traceExporter: new ConsoleSpanExporter(),
-            metricExporter: new ConsoleMetricExporter(),
-        };
-    }
-
-    const { endpoint, headers } = resolveOtlpTarget(descriptor);
-    const {
-        OTLPTraceExporter,
-    } = require('@opentelemetry/exporter-trace-otlp-http');
-    const {
-        OTLPMetricExporter,
-    } = require('@opentelemetry/exporter-metrics-otlp-http');
-
-    // When no endpoint is set the exporters fall back to the standard
-    // OTEL_EXPORTER_OTLP_ENDPOINT env var, so leave `url` undefined in that case.
-    return {
-        traceExporter: new OTLPTraceExporter({
-            ...(endpoint ? { url: joinPath(endpoint, '/v1/traces') } : {}),
-            ...(headers ? { headers } : {}),
-        }),
-        metricExporter: new OTLPMetricExporter({
-            ...(endpoint ? { url: joinPath(endpoint, '/v1/metrics') } : {}),
-            ...(headers ? { headers } : {}),
-        }),
-    };
-}
-
-/** Resolve endpoint + headers for OTLP and its vendor presets. */
-function resolveOtlpTarget(descriptor) {
-    if (descriptor.type === 'honeycomb') {
-        return {
-            endpoint: descriptor.endpoint || 'https://api.honeycomb.io',
-            headers: descriptor.apiKey
-                ? { 'x-honeycomb-team': descriptor.apiKey }
-                : descriptor.headers,
-        };
-    }
-    // 'otlp' and 'datadog' both use a plain OTLP endpoint + optional headers.
-    return { endpoint: descriptor.endpoint, headers: descriptor.headers };
-}
-
-function joinPath(base, path) {
-    return `${String(base).replace(/\/$/, '')}${path}`;
-}
-
-module.exports = { buildExporters };