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

package/telemetry/plugin-subscribers.js

@@ -1,77 +0,0 @@
-/**
- * Declarative plugin/extension telemetry taps.
- *
- * 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

@@ -1,118 +0,0 @@
-/**
- * Resolves and validates the telemetry section of an app definition
- * into a normalized config the TelemetryService and
- * usage rollup consume: `{ exporter, northStar, sampleRatio }`.
- *
- * Exporter default is keyed off STAGE: only a genuinely LOCAL run (STAGE=local)
- * gets `console` (visible, free); every deployed stage — including `dev` —
- * defaults to `none`. `dev` is a deployed AWS stage, and `console` there would
- * write full spans to CloudWatch by default (cost + a data-exposure surface).
- * Adopters opt into `console`/`otlp` explicitly for deployed stages.
- */
-const VALID_EXPORTER_TYPES = [
-    'none',
-    'noop',
-    'console',
-    'otlp',
-    'honeycomb',
-    'datadog',
-];
-
-function resolveExporter(exporter, stage) {
-    if (!exporter) {
-        return stage === 'local' ? { type: 'console' } : { type: 'none' };
-    }
-
-    // Pre-built exporter instances (tests / advanced adopters) bypass type checks.
-    if (exporter.traceExporter || exporter.metricExporter) {
-        return exporter;
-    }
-
-    if (!VALID_EXPORTER_TYPES.includes(exporter.type)) {
-        throw new Error(
-            `[Frigg][telemetry] invalid exporter type "${exporter.type}". ` +
-                `Supported: ${VALID_EXPORTER_TYPES.join(', ')}`
-        );
-    }
-    return exporter;
-}
-
-function resolveSampleRatio(sampleRatio) {
-    if (sampleRatio === undefined || sampleRatio === null) return 1;
-    if (
-        typeof sampleRatio !== 'number' ||
-        Number.isNaN(sampleRatio) ||
-        sampleRatio < 0 ||
-        sampleRatio > 1
-    ) {
-        throw new Error(
-            `[Frigg][telemetry] sampleRatio must be a number in [0,1], got ${sampleRatio}`
-        );
-    }
-    return sampleRatio;
-}
-
-function validateNorthStarEntry(entry, where) {
-    if (!entry || typeof entry.name !== 'string' || !entry.name) {
-        throw new Error(
-            `[Frigg][telemetry] northStar.${where} must reference a counter { name }`
-        );
-    }
-}
-
-/**
- * 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');
-    if (northStar.byType) {
-        for (const [type, entry] of Object.entries(northStar.byType)) {
-            validateNorthStarEntry(entry, `byType.${type}`);
-        }
-    }
-    return northStar;
-}
-
-/**
- * @param {object} appDefinition The backend `Definition` export.
- * @param {object} [ctx]
- * @param {string} [ctx.stage] Deployment stage (defaults to STAGE/NODE_ENV).
- * @returns {{ exporter: object, northStar: object|null, sampleRatio: number }}
- */
-function resolveTelemetryConfig(appDefinition = {}, ctx = {}) {
-    const stage =
-        ctx.stage || process.env.STAGE || process.env.NODE_ENV || 'production';
-    const telemetry = appDefinition.telemetry || {};
-
-    return {
-        exporter: resolveExporter(telemetry.exporter, stage),
-        northStar: resolveNorthStar(telemetry.northStar),
-        sampleRatio: resolveSampleRatio(telemetry.sampleRatio),
-        subscribers: resolveSubscribers(telemetry.subscribers),
-    };
-}
-
-module.exports = { resolveTelemetryConfig };

package/telemetry/telemetry-context.js

@@ -1,40 +0,0 @@
-const { AsyncLocalStorage } = require('node:async_hooks');
-
-/**
- * Ambient telemetry context. A single process-wide AsyncLocalStorage
- * holds the standard identifiers ({integrationId, integrationType, userId,
- * version, ...}) for the duration of a handler, set once at the handler seam via
- * `telemetry.withContext(...)`. Any emission during that async scope — including
- * deep calls like an API-module request — reads the ambient context, so the
- * usage rollup can attribute counters per-integration WITHOUT threading context
- * through every call and WITHOUT relying on OTel baggage (which does not exist
- * on the no-op path). This is the propagation mechanism the plan intended.
- *
- * Only bus-payload `context` is populated from here; high-cardinality ids never
- * touch OTel metric labels.
- */
-const store = new AsyncLocalStorage();
-
-function runWithTelemetryContext(context, fn) {
-    return store.run(context || {}, fn);
-}
-
-function getTelemetryContextStore() {
-    return store.getStore() || null;
-}
-
-/**
- * Merge the ambient context with an explicit per-call context (explicit keys
- * win, e.g. a request `url`). Returns undefined when there is nothing to attach.
- */
-function mergeTelemetryContext(explicit) {
-    const ambient = store.getStore();
-    if (!ambient && !explicit) return undefined;
-    return { ...(ambient || {}), ...(explicit || {}) };
-}
-
-module.exports = {
-    runWithTelemetryContext,
-    getTelemetryContextStore,
-    mergeTelemetryContext,
-};

package/telemetry/telemetry-event-bus.js

@@ -1,58 +0,0 @@
-/**
- * TelemetryEventBus — the internal event stream telemetry flows onto.
- * Plugins/extensions and the built-in usage rollup
- * subscribe here; it is deliberately independent of OTel export (Decision 7),
- * so usage counters persist even when the OTel exporter is a no-op.
- *
- * This is intentionally a **synchronous** in-process fan-out (Frigg runs one
- * invocation per Lambda container): a plain subscriber list with per-subscriber
- * `try/catch` so a misbehaving subscriber can never break emission or its
- * siblings. No queue/backpressure machinery — emission volume is bounded by a
- * single invocation's work.
- *
- * ## Public event contract (semver-stable)
- * Event types and their payload shapes:
- *   - `'metric'` → `{ name: string, value: number, attributes: object, context?: object }`
- *   - `'event'`  → `{ name: string, attributes: object, context?: object }`
- * `attributes` are the bounded OTel metric labels. `context` (present when an
- * ambient telemetry context is active) carries the high-cardinality identifiers
- * — {integrationId, integrationType, userId, version, ...} plus per-call extras
- * like a request `url` — which the usage rollup reads for attribution. Those ids
- * NEVER appear in `attributes` (Cardinality note).
- */
-function createTelemetryEventBus() {
-    /** @type {Map<string, Set<Function>>} */
-    const subscribers = new Map();
-
-    function on(eventType, callback) {
-        if (!subscribers.has(eventType)) {
-            subscribers.set(eventType, new Set());
-        }
-        const set = subscribers.get(eventType);
-        set.add(callback);
-        return function off() {
-            set.delete(callback);
-        };
-    }
-
-    function emit(eventType, payload) {
-        const set = subscribers.get(eventType);
-        if (!set || set.size === 0) return;
-        for (const callback of set) {
-            try {
-                callback(payload);
-            } catch (error) {
-                // A subscriber must never break emission or its siblings.
-                console.warn(
-                    `[Frigg][telemetry] subscriber for "${eventType}" threw: ${
-                        error && error.message
-                    }`
-                );
-            }
-        }
-    }
-
-    return { on, emit };
-}
-
-module.exports = { createTelemetryEventBus };

package/telemetry/telemetry-service.js

@@ -1,44 +0,0 @@
-const { createNoOpTelemetry } = require('./no-op-telemetry');
-const { createTelemetryEventBus } = require('./telemetry-event-bus');
-
-/**
- * Determine whether an exporter descriptor means "emit nothing".
- * Absent config or `{ type: 'none' }` (or `'noop'`) → no-op.
- */
-function isNoOpExporter(exporter) {
-    if (!exporter) return true;
-    const type = exporter.type;
-    return !type || type === 'none' || type === 'noop';
-}
-
-/**
- * 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`).
- *
- * @param {object} [options]
- * @param {object} [options.exporter] Exporter descriptor, e.g. `{ type: 'otlp', endpoint }`.
- * @param {object} [options.resource] Resource attributes, e.g. `{ service, stage }`.
- * @param {number} [options.sampleRatio] Parent-based sampling ratio (0..1).
- * @param {object} [options.bus] Event bus to reuse (defaults to a fresh one).
- */
-function createTelemetry(options = {}) {
-    // The internal event stream is always on and independent of OTel export:
-    // the usage rollup + plugin taps must work even when
-    // the OTel exporter is a no-op. The bus is pure JS, so this does not load
-    // any OTel module on the no-op path.
-    const bus = options.bus || createTelemetryEventBus();
-
-    if (isNoOpExporter(options.exporter)) {
-        return createNoOpTelemetry({ bus });
-    }
-
-    // Lazy-required so the no-op path never loads the OTel SDK.
-    const { createOtelTelemetry } = require('./otel-telemetry');
-    return createOtelTelemetry({ ...options, bus });
-}
-
-module.exports = { createTelemetry, isNoOpExporter };

package/telemetry/telemetry-singleton.js

@@ -1,41 +0,0 @@
-const { createTelemetry } = require('./telemetry-service');
-const { createNoOpTelemetry } = require('./no-op-telemetry');
-
-/**
- * Process-wide telemetry singleton. Created lazily on first use and
- * reused for the life of the Lambda container, so the OTel SDK initialises at
- * most once per cold start. Building it never throws — any failure (e.g. no app
- * definition on disk in a unit test) falls back to the no-op so a handler is
- * never broken by telemetry setup.
- */
-let instance = null;
-
-function getTelemetry() {
-    if (instance) return instance;
-    try {
-        // Lazy-required to avoid a load-time cycle with the handlers layer.
-        const {
-            loadAppDefinition,
-        } = require('../handlers/app-definition-loader');
-        const { telemetry = {} } = loadAppDefinition();
-        const stage = process.env.STAGE || process.env.NODE_ENV || 'production';
-        instance = createTelemetry({
-            exporter: telemetry.exporter,
-            sampleRatio: telemetry.sampleRatio,
-            resource: {
-                service: process.env.FRIGG_STACK || 'frigg',
-                stage,
-            },
-        });
-    } catch (_) {
-        instance = createNoOpTelemetry();
-    }
-    return instance;
-}
-
-/** Test-only: drop the cached instance so the next getTelemetry rebuilds it. */
-function resetTelemetryForTests() {
-    instance = null;
-}
-
-module.exports = { getTelemetry, resetTelemetryForTests };

package/telemetry/usage-rollup-singleton.js

@@ -1,74 +0,0 @@
-const { createUsageRollupSubscriber } = require('./usage-rollup-subscriber');
-
-/**
- * Process-wide usage-rollup subscriber. Built once per cold start,
- * subscribed to the telemetry singleton's bus, and reused across invocations.
- * Returns null when usage is disabled (no integration declares Definition.usage)
- * or when the app definition can't be loaded — the handler then skips the flush.
- * Never throws.
- */
-let subscriber = null;
-let initialized = false;
-
-function getUsageRollupSubscriber() {
-    if (initialized) return subscriber;
-    initialized = true;
-    try {
-        const {
-            loadAppDefinition,
-        } = require('../handlers/app-definition-loader');
-        const { computeTrackedMetrics } = require('../usage/tracked-metrics');
-        const {
-            northStarKeys,
-            createNorthStarDerivationSubscriber,
-        } = require('./north-star');
-        const { integrations = [], telemetry = {} } = loadAppDefinition();
-
-        // Track both Definition.usage opt-ins and any North Star counter keys,
-        // so a derived North Star persists even without an explicit usage decl.
-        const trackedMetrics = computeTrackedMetrics(integrations);
-        for (const key of northStarKeys(telemetry.northStar)) {
-            trackedMetrics.add(key);
-        }
-        if (trackedMetrics.size === 0) {
-            subscriber = null;
-            return subscriber;
-        }
-
-        const { getTelemetry } = require('./telemetry-singleton');
-        const {
-            createUsageRepository,
-        } = require('../usage/repositories/usage-repository-factory');
-        const telemetryService = getTelemetry();
-
-        subscriber = createUsageRollupSubscriber({
-            telemetry: telemetryService,
-            usageRepository: createUsageRepository(),
-            trackedMetrics,
-        });
-
-        // North Star derived-from-trace: emits the North Star counter when a
-        // configured signal matches; the emission flows to the rollup above.
-        if (telemetry.northStar) {
-            createNorthStarDerivationSubscriber({
-                telemetry: telemetryService,
-                northStar: telemetry.northStar,
-            });
-        }
-    } catch (error) {
-        // Usage disabled for this process — surface it so operators can tell
-        // "usage off" from "usage broken" (e.g. unresolved DB_TYPE).
-        console.warn(
-            `[Frigg][usage] rollup disabled: ${error && error.message}`
-        );
-        subscriber = null;
-    }
-    return subscriber;
-}
-
-function resetUsageRollupForTests() {
-    subscriber = null;
-    initialized = false;
-}
-
-module.exports = { getUsageRollupSubscriber, resetUsageRollupForTests };

package/telemetry/usage-rollup-subscriber.js

@@ -1,116 +0,0 @@
-const { computeUsageWindows } = require('./usage-windows');
-
-const WEBHOOK_EVENT_NAMES = new Set(['ON_WEBHOOK']);
-
-/**
- * Framework auto-signal metric names → the canonical usage key they feed.
- * Resolvers receive (attributes, context) and may return null to
- * decline. Handler invocations map by event: USER_ACTION → user_actions; the
- * DB-connected `ON_WEBHOOK` queue dispatch → webhooks.received (per-integration,
- * and where a durable write is actually possible — the HTTP receipt handler is
- * DB-free so its buffer is discarded).
- */
-const METRIC_TO_CANONICAL = {
-    'frigg.apimodule.requests': () => 'api.requests',
-    'frigg.handler.invocations': (attrs, ctx) => {
-        if (attrs && attrs.event === 'USER_ACTION') return 'user_actions';
-        if (ctx && WEBHOOK_EVENT_NAMES.has(ctx.event_name)) {
-            return 'webhooks.received';
-        }
-        return null;
-    },
-};
-
-/**
- * The built-in usage-rollup subscriber. Subscribes to the
- * telemetry event bus and folds *declared* counters (canonical or custom) into
- * the durable usage store. It buffers within an invocation and writes on
- * `flush()` (no timers — Lambda-safe), or drops the buffer on `discard()` for an
- * SQS redelivery so at-least-once delivery does not double-count (approximate
- * accuracy contract).
- *
- * Attribution: high-cardinality ids never ride metric labels, so integrationId
- * comes from the bus-only `context` (populated from the ambient handler context)
- * and otherwise falls back to the bounded integration_type.
- */
-function createUsageRollupSubscriber({
-    telemetry,
-    usageRepository,
-    trackedMetrics = new Set(),
-    now = () => new Date(),
-}) {
-    // Buffer key is a JSON tuple [integrationId, integrationType, metric, window]
-    // — collision-proof for developer-defined custom keys / names.
-    let buffer = new Map();
-
-    function resolveUsageKey(name, attributes, context) {
-        if (trackedMetrics.has(name)) return name;
-        const resolver = METRIC_TO_CANONICAL[name];
-        const canonical = resolver ? resolver(attributes || {}, context) : null;
-        return canonical && trackedMetrics.has(canonical) ? canonical : null;
-    }
-
-    function onMetric(payload) {
-        try {
-            const { name, value = 1, attributes = {}, context } = payload;
-            const metric = resolveUsageKey(name, attributes, context);
-            if (!metric) return;
-
-            const integrationType =
-                context?.integrationType || attributes.integration_type || null;
-            if (!integrationType) return; // cannot attribute — skip
-
-            const integrationId = context?.integrationId || integrationType;
-
-            for (const window of computeUsageWindows(now())) {
-                const key = JSON.stringify([
-                    integrationId,
-                    integrationType,
-                    metric,
-                    window,
-                ]);
-                buffer.set(key, (buffer.get(key) || 0) + value);
-            }
-        } catch (_) {
-            // Rollup must never break emission.
-        }
-    }
-
-    const unsubscribe = telemetry.on('metric', onMetric);
-
-    async function flush() {
-        if (buffer.size === 0) return;
-        const pending = buffer;
-        buffer = new Map();
-        for (const [key, value] of pending) {
-            const [integrationId, integrationType, metric, window] =
-                JSON.parse(key);
-            try {
-                await usageRepository.increment({
-                    integrationId,
-                    integrationType,
-                    metric,
-                    window,
-                    value,
-                });
-            } catch (_) {
-                // A single failed write must not abort the rest of the flush.
-            }
-        }
-    }
-
-    function discard() {
-        buffer = new Map();
-    }
-
-    return {
-        flush,
-        discard,
-        unsubscribe,
-        get bufferSize() {
-            return buffer.size;
-        },
-    };
-}
-
-module.exports = { createUsageRollupSubscriber, METRIC_TO_CANONICAL };

package/telemetry/usage-windows.js

@@ -1,14 +0,0 @@
-/**
- * Compute the rollup window keys a usage event falls into.
- * Windows are UTC and prefixed by their granularity so the store can filter a
- * series by bucket (`window startsWith 'day:'`).
- *
- * @param {Date} [date] Defaults to now.
- * @returns {string[]} e.g. ['day:2026-07-05', 'hour:2026-07-05T14']
- */
-function computeUsageWindows(date = new Date()) {
-    const iso = date.toISOString(); // 2026-07-05T14:23:00.000Z
-    return [`day:${iso.slice(0, 10)}`, `hour:${iso.slice(0, 13)}`];
-}
-
-module.exports = { computeUsageWindows };

package/usage/README.md

@@ -1,54 +0,0 @@
-# Usage Store
-
-The durable, Frigg-owned store behind ADR-011 feature-usage tracking. Holds
-per-integration counters that the reporting endpoint reads for cross-integration
-comparison and trend series.
-
-Populated by the telemetry usage rollup and read via `frigg.usage.*` — see
-[`telemetry/README.md`](../telemetry/README.md) for the full guide, config, and
-usage examples. This README covers the store internals only.
-
-## Fact row
-
-`UsageCounter { integrationId, integrationType, metric, window, value, updatedAt }`,
-uniquely keyed by `(integrationId, integrationType, metric, window)`. `window` is
-`day:YYYY-MM-DD` or `hour:YYYY-MM-DDTHH` (UTC).
-
-## Isolation (ADR-010 Decision 3)
-
-The store is deliberately isolated from user/integration-scoped data:
-
-- **No `userId`** and **no foreign key** to `Integration` — a user-scoped query
-  can never return a usage row, and usage history survives integration deletion.
-- **Not** in the encryption registry — dimensions are bounded and non-sensitive.
-
-## Repository triad
-
-Mirrors the reporting/process pattern — an interface plus PostgreSQL, MongoDB and
-DocumentDB adapters selected by `DB_TYPE`:
-
-```js
-const { createUsageRepository } = require('@friggframework/core'); // usage-repository-factory
-
-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)
-}
-```
-
-- **`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
-  hour rows are never double-summed. Requires a `metric`; `groupBy` is
-  allow-listed to `integrationType` / `metric`.
-- **`series`** 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
-> (`$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
-> rejects and cursor reads truncate at ~101 docs. Command shapes are unit-tested;
-> run an end-to-end check against a real cluster before GA.

package/usage/index.js

@@ -1,19 +0,0 @@
-const {
-    createUsageRepository,
-    UsageRepositoryMongo,
-    UsageRepositoryPostgres,
-    UsageRepositoryDocumentDB,
-} = require('./repositories/usage-repository-factory');
-const {
-    UsageRepositoryInterface,
-} = require('./repositories/usage-repository-interface');
-const { computeTrackedMetrics } = require('./tracked-metrics');
-
-module.exports = {
-    createUsageRepository,
-    computeTrackedMetrics,
-    UsageRepositoryInterface,
-    UsageRepositoryMongo,
-    UsageRepositoryPostgres,
-    UsageRepositoryDocumentDB,
-};