@friggframework/core 2.0.0--canary.622.5e1352f.0 → 2.0.0--canary.622.16ee19d.0

package/application/commands/usage-commands.js

@@ -14,8 +14,9 @@ const {
     createUsageRepository,
 } = require('../../usage/repositories/usage-repository-factory');
 const { computeUsageWindows } = require('../../telemetry/usage-windows');
+const { resolveNorthStarEntry } = require('../../telemetry/north-star');
 
-function createUsageCommands({ usageRepository } = {}) {
+function createUsageCommands({ usageRepository, northStar = null } = {}) {
     const repository = usageRepository || createUsageRepository();
 
     return {
@@ -50,6 +51,25 @@ function createUsageCommands({ usageRepository } = {}) {
         async series(args) {
             return repository.series(args);
         },
+
+        /**
+         * First-class North Star read (ADR-011 Decision 5). 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 } = {}) {
+            const entry = resolveNorthStarEntry(northStar, integrationType);
+            if (!entry) return null;
+            const totals = await repository.totals({
+                metric: entry.name,
+                groupBy,
+                since,
+                bucket,
+            });
+            return { metric: entry.name, totals };
+        },
     };
 }
 

package/application/index.js

@@ -8,6 +8,21 @@ const { createCredentialCommands } = require('./commands/credential-commands');
 const { createProcessCommands } = require('./commands/process-commands');
 const { createSchedulerCommands } = require('./commands/scheduler-commands');
 const { createUsageCommands } = require('./commands/usage-commands');
+const { loadAppDefinition } = require('../handlers/app-definition-loader');
+
+/**
+ * Resolve the adopter's North Star config from the app definition so
+ * `frigg.usage.northStar(...)` can read it (ADR-011 Decision 5). Guarded: a
+ * missing/unloadable app definition (e.g. in unit tests) must never break the
+ * command factory — usage reads simply have no North Star.
+ */
+function resolveNorthStarConfig() {
+    try {
+        return loadAppDefinition().telemetry?.northStar ?? null;
+    } catch (_) {
+        return null;
+    }
+}
 
 /**
  * Create a unified command factory with all CRUD operations
@@ -53,7 +68,7 @@ function createFriggCommands({ integrationClass }) {
         ...processCommands,
 
         // Usage read/write (ADR-011) — nested to match `frigg.usage.*`
-        usage: createUsageCommands(),
+        usage: createUsageCommands({ northStar: resolveNorthStarConfig() }),
     };
 }
 

package/core/create-handler.js

@@ -8,6 +8,9 @@ const { getTelemetry } = require('../telemetry/telemetry-singleton');
 const {
     getUsageRollupSubscriber,
 } = require('../telemetry/usage-rollup-singleton');
+const {
+    getPluginTelemetrySubscribers,
+} = require('../telemetry/plugin-subscribers-singleton');
 
 // Bounds the tail latency telemetry adds to every warm invocation. Kept low so
 // an unreachable OTLP endpoint (e.g. a VPC Lambda with no NAT/egress) costs at
@@ -139,6 +142,11 @@ const createHandler = (optionByName = {}) => {
                 ? usageRollup
                 : getUsageRollupSubscriber();
 
+        // Wire adopter-declared telemetry subscribers once per cold start
+        // (ADR-011 Decision 6). Memoized in the singleton, so this is a cheap
+        // no-op after the first invocation.
+        getPluginTelemetrySubscribers();
+
         try {
             console.info(`[createHandler] ${eventName}: handler entry`, {
                 eventName,

package/handlers/app-definition-loader.js

@@ -54,6 +54,7 @@ function loadAppDefinition() {
             exporter: { type: 'none' },
             northStar: null,
             sampleRatio: 1,
+            subscribers: [],
         };
     }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.622.5e1352f.0",
+    "version": "2.0.0--canary.622.16ee19d.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.5e1352f.0",
-        "@friggframework/prettier-config": "2.0.0--canary.622.5e1352f.0",
-        "@friggframework/test": "2.0.0--canary.622.5e1352f.0",
+        "@friggframework/eslint-config": "2.0.0--canary.622.16ee19d.0",
+        "@friggframework/prettier-config": "2.0.0--canary.622.16ee19d.0",
+        "@friggframework/test": "2.0.0--canary.622.16ee19d.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": "5e1352f5b615a8d48df800bcb9559d3fa9b0178b"
+    "gitHead": "16ee19d11c975c256a996503bafc70c062440ff0"
 }

package/telemetry/README.md

@@ -200,12 +200,45 @@ telemetry: {
 }
 ```
 
-Read it like any counter: `frigg.usage.totals({ metric: 'contacts_synced' })`.
+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) });
+// → { metric: 'contacts_synced', totals: [{ integrationType: 'hubspot', value: 900 }] }
+// → null when no North Star is configured (caller branches without knowing keys)
+```
+
+Or read it like any counter once you know the key:
+`frigg.usage.totals({ metric: 'contacts_synced' })`; trends via `frigg.usage.series({ metric })`.
 
 ## Plugin / extension tap
 
-Telemetry flows onto an internal event stream. Subscribe to forward to a custom
-sink or compute aggregates:
+Telemetry flows onto an internal event stream (independent of OTel export, so
+taps fire even with `exporter: none`). Two ways to subscribe:
+
+**Declarative (app definition)** — the framework wires these once per cold start,
+each guarded so a bad subscriber can't break emission or its siblings:
+
+```js
+// backend/index.js
+const Definition = {
+    telemetry: {
+        subscribers: [
+            // (a) declarative object — `event` optional; omit to receive both:
+            { event: 'metric', handler: ({ name, value, attributes, context }) => {
+                forwardToStatsd(name, value, attributes);
+            } },
+            // (b) factory — gets the telemetry service, registers itself, may
+            //     return an unsubscribe:
+            (telemetry) => telemetry.on('event', (payload) => auditSink.write(payload)),
+        ],
+    },
+};
+```
+
+**Imperative** — subscribe from anywhere that runs at startup:
 
 ```js
 const { getTelemetry } = require('@friggframework/core');

package/telemetry/index.js

@@ -24,6 +24,11 @@ const {
     CANONICAL_COUNTERS,
     isCanonicalCounter,
 } = require('./canonical-counters');
+const { wireTelemetrySubscribers } = require('./plugin-subscribers');
+const {
+    getPluginTelemetrySubscribers,
+    resetPluginTelemetrySubscribersForTests,
+} = require('./plugin-subscribers-singleton');
 
 module.exports = {
     createTelemetry,
@@ -45,4 +50,7 @@ module.exports = {
     createNorthStarDerivationSubscriber,
     CANONICAL_COUNTERS,
     isCanonicalCounter,
+    wireTelemetrySubscribers,
+    getPluginTelemetrySubscribers,
+    resetPluginTelemetrySubscribersForTests,
 };

package/telemetry/plugin-subscribers-singleton.js

@@ -0,0 +1,51 @@
+const { wireTelemetrySubscribers } = require('./plugin-subscribers');
+
+/**
+ * Process-wide wiring of adopter-declared telemetry subscribers (ADR-011
+ * Decision 6). Built once per cold start and reused for the life of the Lambda
+ * container, mirroring the usage-rollup singleton. Independent of the usage
+ * rollup: adopter taps wire even when no integration declares `Definition.usage`.
+ * Never throws — a bad/absent app definition just means no adopter taps.
+ */
+let wired = null;
+let initialized = false;
+
+function getPluginTelemetrySubscribers() {
+    if (initialized) return wired;
+    initialized = true;
+    try {
+        const {
+            loadAppDefinition,
+        } = require('../handlers/app-definition-loader');
+        const { telemetry = {} } = loadAppDefinition();
+        const subscribers = telemetry.subscribers || [];
+        if (subscribers.length === 0) {
+            wired = [];
+            return wired;
+        }
+
+        const { getTelemetry } = require('./telemetry-singleton');
+        wired = wireTelemetrySubscribers({
+            telemetry: getTelemetry(),
+            subscribers,
+        });
+    } catch (error) {
+        console.warn(
+            `[Frigg][telemetry] plugin subscribers disabled: ${
+                error && error.message
+            }`
+        );
+        wired = [];
+    }
+    return wired;
+}
+
+function resetPluginTelemetrySubscribersForTests() {
+    wired = null;
+    initialized = false;
+}
+
+module.exports = {
+    getPluginTelemetrySubscribers,
+    resetPluginTelemetrySubscribersForTests,
+};

package/telemetry/plugin-subscribers.js

@@ -0,0 +1,77 @@
+/**
+ * Declarative plugin/extension telemetry taps (ADR-011 Decision 6).
+ *
+ * The built-in usage rollup and North Star derivation subscribe to the telemetry
+ * bus in framework code; this lets an ADOPTER subscribe declaratively from the
+ * app definition (`Definition.telemetry.subscribers: [...]`) — forward to a
+ * custom sink, compute aggregates, persist counters — without writing wiring code.
+ *
+ * A subscriber is one of:
+ *   - a **factory** `fn(telemetry)` that registers itself (e.g. calls
+ *     `telemetry.on('metric', ...)`) and MAY return an unsubscribe function; or
+ *   - a **declarative object** `{ event?: 'metric'|'event', handler(payload, eventType) }`
+ *     — when `event` is omitted the handler receives both metric and event payloads.
+ *
+ * Every attach and every handler invocation is guarded so a misbehaving
+ * subscriber can never break emission, its siblings, or a handler (mirrors the
+ * bus's own per-subscriber isolation).
+ *
+ * @param {object} params
+ * @param {object} params.telemetry Telemetry service exposing `on(eventType, cb)`.
+ * @param {Array<Function|{event?: string, handler: Function}>} [params.subscribers]
+ * @returns {Array<Function>} unsubscribe functions for the wired subscribers.
+ */
+const EVENT_TYPES = ['metric', 'event'];
+
+function wireTelemetrySubscribers({ telemetry, subscribers = [] } = {}) {
+    if (
+        !telemetry ||
+        typeof telemetry.on !== 'function' ||
+        !Array.isArray(subscribers)
+    ) {
+        return [];
+    }
+
+    const unsubscribes = [];
+
+    for (const subscriber of subscribers) {
+        try {
+            if (typeof subscriber === 'function') {
+                const off = subscriber(telemetry);
+                if (typeof off === 'function') unsubscribes.push(off);
+                continue;
+            }
+
+            if (subscriber && typeof subscriber.handler === 'function') {
+                const events = subscriber.event
+                    ? [subscriber.event]
+                    : EVENT_TYPES;
+                for (const eventType of events) {
+                    const off = telemetry.on(eventType, (payload) => {
+                        try {
+                            subscriber.handler(payload, eventType);
+                        } catch (error) {
+                            console.warn(
+                                `[Frigg][telemetry] subscriber handler for "${eventType}" threw: ${
+                                    error && error.message
+                                }`
+                            );
+                        }
+                    });
+                    if (typeof off === 'function') unsubscribes.push(off);
+                }
+            }
+        } catch (error) {
+            // A single bad subscriber must never break wiring of the others.
+            console.warn(
+                `[Frigg][telemetry] failed to wire a telemetry subscriber: ${
+                    error && error.message
+                }`
+            );
+        }
+    }
+
+    return unsubscribes;
+}
+
+module.exports = { wireTelemetrySubscribers };

package/telemetry/telemetry-config.js

@@ -60,6 +60,31 @@ function validateNorthStarEntry(entry, where) {
     }
 }
 
+/**
+ * Adopter-declared telemetry subscribers (Decision 6). 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.
+ */
+function resolveSubscribers(subscribers) {
+    if (subscribers === undefined || subscribers === null) return [];
+    if (!Array.isArray(subscribers)) {
+        throw new Error(
+            '[Frigg][telemetry] subscribers must be an array of functions or { handler } objects'
+        );
+    }
+    for (const subscriber of subscribers) {
+        const ok =
+            typeof subscriber === 'function' ||
+            (subscriber && typeof subscriber.handler === 'function');
+        if (!ok) {
+            throw new Error(
+                '[Frigg][telemetry] each subscriber must be a function or an object with a handler function'
+            );
+        }
+    }
+    return subscribers;
+}
+
 function resolveNorthStar(northStar) {
     if (!northStar) return null;
     if (northStar.default) validateNorthStarEntry(northStar.default, 'default');
@@ -86,6 +111,7 @@ function resolveTelemetryConfig(appDefinition = {}, ctx = {}) {
         exporter: resolveExporter(telemetry.exporter, stage),
         northStar: resolveNorthStar(telemetry.northStar),
         sampleRatio: resolveSampleRatio(telemetry.sampleRatio),
+        subscribers: resolveSubscribers(telemetry.subscribers),
     };
 }