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

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

@@ -1,5 +1,4 @@
 const Boom = require('@hapi/boom');
-const { CANONICAL_COUNTERS } = require('../../telemetry/canonical-counters');
 
 const SCHEMA_VERSION = 1;
 const SERVICE = 'frigg-core-api';
@@ -17,19 +16,11 @@ const KNOWN_STATUSES = [
 ];
 
 class ListIntegrationsReport {
-    constructor({
-        reportingRepository,
-        usageRepository,
-        typeLabels = {},
-    } = {}) {
+    constructor({ reportingRepository, typeLabels = {} } = {}) {
         if (!reportingRepository) {
             throw new Error('reportingRepository is required');
         }
         this.reportingRepository = reportingRepository;
-        // Optional usage store (the ADR-010 hand-off). When present, the
-        // report's byType buckets are enriched with feature-usage columns read
-        // ONLY from this store — never an external APM.
-        this.usageRepository = usageRepository || null;
         this.typeLabels = typeLabels;
     }
 
@@ -76,8 +67,7 @@ class ListIntegrationsReport {
             if (!byTypeMap.has(integration.type)) {
                 byTypeMap.set(integration.type, {
                     type: integration.type,
-                    label:
-                        this.typeLabels[integration.type] || integration.type,
+                    label: this.typeLabels[integration.type] || integration.type,
                     total: 0,
                     byStatus: emptyStatusCounts(),
                 });
@@ -87,13 +77,6 @@ class ListIntegrationsReport {
             bucket.byStatus[statusKey] = (bucket.byStatus[statusKey] ?? 0) + 1;
         }
 
-        // Additive usage columns. Read per-type totals for each
-        // canonical counter; a type with no rows reads as 0. Guarded so a usage
-        // store failure never breaks the structural report.
-        if (this.usageRepository) {
-            await this._attachUsageColumns(byTypeMap);
-        }
-
         return {
             schemaVersion: SCHEMA_VERSION,
             service: SERVICE,
@@ -113,47 +96,9 @@ class ListIntegrationsReport {
         };
     }
 
-    async _attachUsageColumns(byTypeMap) {
-        const metrics = Object.keys(CANONICAL_COUNTERS);
-        try {
-            const totalsByMetric = await Promise.all(
-                metrics.map(async (metric) => {
-                    const totals = await this.usageRepository.totals({
-                        metric,
-                        groupBy: 'integrationType',
-                    });
-                    const map = new Map(
-                        (totals || []).map((t) => [t.integrationType, t.value])
-                    );
-                    return [metric, map];
-                })
-            );
-
-            for (const bucket of byTypeMap.values()) {
-                bucket.usage = {};
-                for (const [metric, map] of totalsByMetric) {
-                    bucket.usage[metric] = map.get(bucket.type) ?? 0;
-                }
-            }
-        } catch (error) {
-            // Usage is a supplement; a read failure must not fail the report,
-            // but it is worth surfacing (silent all-zeros usage columns hide
-            // data-quality issues).
-            console.warn(
-                `[Frigg][reporting] usage columns unavailable: ${
-                    error && error.message
-                }`
-            );
-        }
-    }
-
     _validateQuery({ status, type, userId } = {}) {
         for (const [key, value] of Object.entries({ status, type, userId })) {
-            if (
-                value !== undefined &&
-                value !== null &&
-                typeof value !== 'string'
-            ) {
+            if (value !== undefined && value !== null && typeof value !== 'string') {
                 throw Boom.badRequest(
                     `Invalid query parameter '${key}': expected a string`
                 );
@@ -167,9 +112,9 @@ class ListIntegrationsReport {
         };
         if (normalized.status && !KNOWN_STATUSES.includes(normalized.status)) {
             throw Boom.badRequest(
-                `Invalid status '${
-                    normalized.status
-                }'. Expected one of: ${KNOWN_STATUSES.join(', ')}`
+                `Invalid status '${normalized.status}'. Expected one of: ${KNOWN_STATUSES.join(
+                    ', '
+                )}`
             );
         }
         return normalized;

package/application/commands/usage-commands.js

@@ -1,77 +0,0 @@
-/**
- * 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' });
- */
-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 } = {}) {
-    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.
-         */
-        async recordUsageCounter({
-            integrationId,
-            integrationType,
-            metric,
-            value = 1,
-            at = new Date(),
-        }) {
-            const windows = computeUsageWindows(at);
-            for (const window of windows) {
-                await repository.increment({
-                    integrationId,
-                    integrationType,
-                    metric,
-                    window,
-                    value,
-                });
-            }
-        },
-
-        async totals(args) {
-            return repository.totals(args);
-        },
-
-        async series(args) {
-            return repository.series(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 } = {}) {
-            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 };
-        },
-    };
-}
-
-module.exports = { createUsageCommands };

package/prisma-postgresql/migrations/20260705000000_create_usage_counter/migration.sql

@@ -1,26 +0,0 @@
--- CreateTable
--- ADR-011 durable usage counters. Deliberately isolated from the
--- user/integration-scoped tables (no userId, no FK to Integration) so usage
--- history survives integration deletion and can never surface in a user-scoped
--- query. "window" is quoted throughout — it is a reserved SQL keyword.
-CREATE TABLE "UsageCounter" (
-    "id" SERIAL NOT NULL,
-    "integrationId" TEXT NOT NULL,
-    "integrationType" TEXT NOT NULL,
-    "metric" TEXT NOT NULL,
-    "window" TEXT NOT NULL,
-    "value" BIGINT NOT NULL DEFAULT 0,
-    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    "updatedAt" TIMESTAMP(3) NOT NULL,
-
-    CONSTRAINT "UsageCounter_pkey" PRIMARY KEY ("id")
-);
-
--- CreateIndex
-CREATE UNIQUE INDEX "UsageCounter_integrationId_integrationType_metric_window_key" ON "UsageCounter"("integrationId", "integrationType", "metric", "window");
-
--- CreateIndex
-CREATE INDEX "UsageCounter_metric_window_idx" ON "UsageCounter"("metric", "window");
-
--- CreateIndex
-CREATE INDEX "UsageCounter_metric_integrationType_window_idx" ON "UsageCounter"("metric", "integrationType", "window");

package/telemetry/README.md

@@ -1,317 +0,0 @@
-# Frigg Telemetry & Usage Tracking
-
-Vendor-neutral observability (traces + metrics) and durable, per-integration
-feature-usage counters for `@friggframework/core`, built on OpenTelemetry.
-Implements [ADR-011](../../../docs/architecture-decisions/011-integration-telemetry-and-usage-tracking.md).
-
-## Overview
-
-Two capabilities ride the same primitive:
-
-1. **Observability** — spans + low-cardinality metrics across handlers, API
-   modules, queues and webhooks, per integration, exported to any OTLP backend
-   (Honeycomb, Datadog, Grafana, an OTel Collector, …).
-2. **Usage tracking** — durable per-integration counters (records synced,
-   webhooks received, API requests, user actions, …) folded into a Frigg-owned
-   store that the reporting endpoint reads for apples-to-apples comparison.
-
-### Key properties
-
-- **Rides for free.** Framework seams are auto-instrumented — integrations get
-  handler/API-module/webhook metrics with zero code.
-- **No-op by default.** With no exporter configured the service emits nothing and
-  loads **zero** OpenTelemetry modules — no cold-start cost. Integration code can
-  always call `this.telemetry.*`.
-- **Vendor-neutral.** Integration code never imports a backend SDK. Swap exporters
-  in the app definition.
-- **Usage store ≠ APM.** Reports read the durable Frigg store, never an external
-  APM.
-
-## Configuration (app definition)
-
-```js
-// backend/index.js
-const Definition = {
-    name: 'my-app',
-    integrations: [HubSpotIntegration, SalesforceIntegration],
-
-    telemetry: {
-        // none | console | otlp | honeycomb | datadog
-        exporter: {
-            type: 'otlp',
-            endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
-            // headers: { 'x-honeycomb-team': process.env.HONEYCOMB_KEY }, // or use type:'honeycomb' + apiKey
-        },
-        sampleRatio: 1.0, // parent-based trace sampling (0..1)
-        northStar: {
-            default: { name: 'records.synced' },
-        },
-    },
-};
-```
-
-**Exporter default (no `telemetry.exporter` set):** `console` only when
-`STAGE=local` (a genuinely local run); every deployed stage — including `dev` —
-defaults to `none` (no per-event cost, no data written to CloudWatch). Point
-`exporter` at an OTLP backend to turn export on.
-
-### Environment variables
-
-| Variable | Purpose |
-| --- | --- |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP backend URL (referenced from `telemetry.exporter.endpoint`). Auto-passed through to Lambda when an OTLP-family exporter is configured. |
-| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP headers (e.g. auth). |
-| `OTEL_FLUSH_TIMEOUT_MS` | Max time the handler waits to flush telemetry before returning (default `500`). Bounds tail latency if the backend is unreachable. |
-| `OTEL_METRIC_EXPORT_INTERVAL_MS` | Metric reader interval (default `60000`). |
-| `STAGE` | `local` enables the `console` default. |
-
-> **VPC note:** a Lambda in a private subnet needs a NAT gateway or VPC endpoint
-> to reach an external OTLP backend. Without egress the exporter fails silently
-> within `OTEL_FLUSH_TIMEOUT_MS`.
-
-## What you get for free (auto-instrumentation)
-
-No integration code required — every emission carries `{integration_type, event,
-status, ...}` bounded labels, with high-cardinality ids on span baggage / the bus
-context only.
-
-| Seam | Span | Metric |
-| --- | --- | --- |
-| Handler dispatch (USER_ACTION / CRON / QUEUE / WEBHOOK / lifecycle) | `frigg.handler.<type>` | `frigg.handler.invocations{integration_type, event, status}` |
-| Outbound API-module request | `frigg.apimodule.request` | `frigg.apimodule.requests{module, method, status}` |
-
-Request URLs are redacted (query string + userinfo stripped) before they touch a
-span, so credentials in query params never leak.
-
-> **Usage-attribution boundary.** The OTel metrics above fire for *every* seam
-> invocation. The durable per-integration **usage** rollup, though, only counts
-> emissions that carry an integration context — set by the handler seams. Requests
-> an API module makes *before an integration exists* (OAuth/token exchange, entity
-> discovery during connection setup) are observable in traces but not attributed to
-> an `api.requests` usage counter (there is no integration to attribute them to).
-
-## Custom metrics (integration code)
-
-Every integration instance carries `this.telemetry` (auto-tagged with its
-`integration_type`):
-
-```js
-class HubSpotIntegration extends IntegrationBase {
-    async deltaSync() {
-        // A span wraps the operation (nested under the handler span):
-        await this.telemetry.span('delta_sync', async () => {
-            const batch = await this.hubspot.api.getContacts();
-
-            // A counter — declare 'records.synced' in Definition.usage to persist it:
-            this.telemetry.count('records.synced', batch.length, {
-                entity: 'contact',
-            });
-
-            // A one-off event (attached to the active span):
-            this.telemetry.event('workflow_invoked', { workflow: 'lead_route' });
-        });
-    }
-}
-```
-
-## Usage counters (durable, comparable)
-
-### 1. Declare which counters an integration reports
-
-```js
-class HubSpotIntegration extends IntegrationBase {
-    static Definition = {
-        name: 'hubspot',
-        usage: {
-            // Canonical keys → comparable ACROSS integration types (reporting):
-            canonical: ['records.synced', 'webhooks.received', 'api.requests'],
-            // Custom keys → comparable only WITHIN this integration type:
-            custom: { 'deals.enriched': { unit: 'count', label: 'Deals enriched' } },
-        },
-    };
-}
-```
-
-**Canonical vocabulary** (core-owned, versioned):
-
-| Key | Source |
-| --- | --- |
-| `api.requests` | auto — every outbound API-module request |
-| `user_actions` | auto — every `USER_ACTION` handler |
-| `webhooks.received` | auto — the `ON_WEBHOOK` queue dispatch (per-integration, DB-connected) |
-| `records.synced` | explicit — `this.telemetry.count('records.synced', n, { entity })` |
-| `workflows.invoked` | explicit — `this.telemetry.count('workflows.invoked', 1, { workflow })` |
-
-Only **declared** keys are persisted. Declaring a canonical key opts the
-integration into the comparison report.
-
-### 2. Read the usage store
-
-`frigg.usage.*` (via `createFriggCommands`) reads the durable store — never an APM:
-
-```js
-const { createFriggCommands } = require('@friggframework/core');
-const frigg = createFriggCommands({ integrationClass: HubSpotIntegration });
-
-// Apples-to-apples comparison across integration types:
-await frigg.usage.totals({
-    metric: 'records.synced',
-    groupBy: 'integrationType', // or 'metric'
-    since: daysAgo(30),
-    bucket: 'day', // 'day' (default) | 'hour'
-});
-// → [{ integrationType: 'hubspot', value: 4200 }, { integrationType: 'salesforce', value: 1180 }]
-
-// Trend series for one type (aggregated across its instances):
-await frigg.usage.series({
-    metric: 'records.synced',
-    integrationType: 'hubspot',
-    from: daysAgo(7),
-    to: new Date(),
-    bucket: 'day',
-});
-// → [{ bucket: 'day:2026-07-04', value: 610 }, { bucket: 'day:2026-07-05', value: 720 }]
-
-// Manual write (day + hour windows derived from `at`):
-await frigg.usage.recordUsageCounter({
-    integrationId: 'int_1',
-    integrationType: 'hubspot',
-    metric: 'deals.enriched',
-    value: 3,
-    at: new Date(),
-});
-```
-
-The [reporting endpoint](../reporting/README.md) surfaces these as additive
-`usage` columns on each `byType` bucket.
-
-## North Star metric
-
-Declare an adopter North Star that reports/snapshots read as a first-class
-counter — populated by direct emission, or derived from a trace signal with no
-integration code:
-
-```js
-telemetry: {
-    northStar: {
-        default: { name: 'records.synced' },
-        byType: {
-            hubspot: {
-                name: 'contacts_synced',
-                // derive from an auto-emitted signal:
-                deriveFrom: { apiRequest: { endpoint: '/contacts', method: 'POST' } },
-                // or: deriveFrom: { userAction: { action: 'route_lead' } }
-            },
-        },
-    },
-}
-```
-
-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 })`.
-
-> `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`.
-
-## Plugin / extension tap
-
-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');
-
-const off = getTelemetry().on('metric', ({ name, value, attributes, context }) => {
-    // `attributes` = bounded metric labels; `context` = high-cardinality ids
-    // (integrationId, integrationType, userId, url, …). Never throws upstream.
-});
-// off() to unsubscribe
-```
-
-> The bus payload shape (`{ name, value, attributes, context? }` for `'metric'`,
-> `{ name, attributes, context? }` for `'event'`) is a stable contract.
-
-## Cardinality rule
-
-High-cardinality identifiers (`integrationId`, `userId`, request `url`, action
-names) ride **span baggage / the bus `context`** — never OTel **metric** labels.
-Metric labels stay bounded (`integration_type`, `event`, `status`, `method`,
-`module`). The usage rollup derives per-integration counts from the bus context,
-not from metric labels.
-
-## How it works
-
-```
-this.telemetry.count / auto-instrumented seam
-        │  (bounded metric labels → OTel; ids → bus context via AsyncLocalStorage)
-        ├──────────────► OTel exporter (traces + metrics)   [observability]
-        └──────────────► TelemetryEventBus ('metric'/'event')
-                              │
-                              ├─ UsageRollupSubscriber ── buffers per invocation,
-                              │     flushes to the UsageCounter store on handler exit
-                              │     (discards on SQS redelivery — approximate contract)
-                              └─ your plugin taps
-
-frigg.usage.totals / series ◄── UsageCounter store ──► reporting usage columns
-```
-
-- **Flush is Lambda-safe:** `create-handler` awaits a bounded `forceFlush` in a
-  `finally` (background timers can't fire once the container freezes).
-- **Usage accuracy is approximate:** at-least-once delivery means a retried
-  handler could double-count. The invocation buffer is discarded only when the
-  **whole** SQS batch is a redelivery (`ApproximateReceiveCount > 1`); a mixed
-  batch flushes so a redelivered sibling never drops a fresh record's counts.
-
-## Caveats / current limitations
-
-- **Usage persistence requires a DB-connected handler.** DB-free handlers (e.g.
-  the raw webhook-receipt route) can't write; `webhooks.received` is counted at
-  the DB-connected `ON_WEBHOOK` queue dispatch instead.
-- **DocumentDB** uses a raw-command adapter (`$runCommandRaw`) for increment and
-  aggregate; command shapes are unit-tested but not yet run against a real cluster.
-- **Retention:** the `UsageCounter` table has no pruning yet — hour-grain rows
-  accumulate. Add a scheduled prune for high-volume deployments. (Read paths are
-  covered by composite indexes `(metric, window)` and `(metric, integrationType,
-  window)`.)
-- Metric `value` is a `BigInt` per `(integrationId, integrationType, metric,
-  window)` row; reads coerce the sum to a JS Number (safe below 2^53).
-
-## See also
-
-- Architecture: [ADR-011](../../../docs/architecture-decisions/011-integration-telemetry-and-usage-tracking.md)
-- Reporting hand-off: [`reporting/README.md`](../reporting/README.md)
-- Encryption (same repository-triad pattern): [`database/encryption/README.md`](../database/encryption/README.md)

package/telemetry/bind-telemetry-context.js

@@ -1,51 +0,0 @@
-/**
- * Wrap a telemetry service so an integration instance's emissions automatically
- * carry its `integration_type`. This lets developers write
- * `this.telemetry.count('records.synced', n, { entity })` with no per-call
- * boilerplate, while the usage rollup still attributes the counter to the right
- * integration type.
- *
- * Only the bounded `integration_type` is injected onto attributes — high-
- * cardinality ids stay off metric labels (Cardinality note). All other methods
- * delegate unchanged.
- *
- * @param {object} base The underlying telemetry service.
- * @param {() => {integrationType?: string}} getContext Lazy context accessor.
- */
-function bindTelemetryContext(base, getContext) {
-    if (!base) return base;
-
-    const withType = (attributes = {}) => {
-        let integrationType;
-        try {
-            integrationType = getContext && getContext().integrationType;
-        } catch (_) {
-            integrationType = undefined;
-        }
-        if (!integrationType || 'integration_type' in attributes) {
-            return attributes;
-        }
-        return { integration_type: integrationType, ...attributes };
-    };
-
-    return {
-        count(name, value = 1, attributes = {}, context) {
-            return base.count(name, value, withType(attributes), context);
-        },
-        event(name, attributes = {}, context) {
-            return base.event(name, withType(attributes), context);
-        },
-        span: (...args) => base.span(...args),
-        startSpan: (...args) => base.startSpan(...args),
-        withContext: (...args) => base.withContext(...args),
-        on: (...args) => base.on(...args),
-        forceFlush: (...args) => base.forceFlush(...args),
-        shutdown: (...args) =>
-            typeof base.shutdown === 'function'
-                ? base.shutdown(...args)
-                : undefined,
-        isEnabled: (...args) => base.isEnabled(...args),
-    };
-}
-
-module.exports = { bindTelemetryContext };

package/telemetry/canonical-counters.js

@@ -1,52 +0,0 @@
-/**
- * Canonical usage-counter vocabulary.
- *
- * These core-owned, versioned keys are the ONLY metrics guaranteed comparable
- * *across* integration types — they power ADR-010's apples-to-apples comparison
- * report. Custom keys (declared in an integration's `Definition.usage.custom`)
- * are comparable only *within* an integration type.
- *
- * The registry is **additive**: new keys may be added, existing keys never
- * change or are removed, so existing reports never break.
- *
- * `dims` are the bounded dimensions a counter may carry (Cardinality note) —
- * high-cardinality ids (integrationId, userId) never appear here.
- */
-const CANONICAL_COUNTERS = {
-    'records.synced': {
-        unit: 'count',
-        label: 'Records synced',
-        dims: ['entity'],
-    },
-    'webhooks.received': {
-        unit: 'count',
-        label: 'Webhooks received',
-        dims: ['event'],
-    },
-    'workflows.invoked': {
-        unit: 'count',
-        label: 'Workflows invoked',
-        dims: ['workflow'],
-    },
-    'api.requests': {
-        unit: 'count',
-        label: 'API requests',
-        dims: ['endpoint', 'status'],
-    },
-    user_actions: { unit: 'count', label: 'User actions', dims: ['action'] },
-};
-
-// NOTE: the framework-signal → canonical mapping lives in the usage rollup
-// subscriber (METRIC_TO_CANONICAL, keyed by the actual emitted metric names).
-// `records.synced` / `workflows.invoked` have no auto-signal — they are
-// explicit-only (`this.telemetry.count(...)`), so a canonical counter is never
-// shipped that silently stays at zero.
-
-function isCanonicalCounter(name) {
-    return Object.prototype.hasOwnProperty.call(CANONICAL_COUNTERS, name);
-}
-
-module.exports = {
-    CANONICAL_COUNTERS,
-    isCanonicalCounter,
-};