@friggframework/core 2.0.0-next.102 → 2.0.0-next.103

package/modules/requester/requester.js

@@ -2,6 +2,7 @@ const fetch = require('node-fetch');
 const { Delegate } = require('../../core');
 const { FetchError } = require('../../errors');
 const { get } = require('../../assertions');
+const { getTelemetry } = require('../../telemetry/telemetry-runtime');
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 const MAX_AUTH_RETRIES = 3;
@@ -44,6 +45,40 @@ class Requester extends Delegate {
         // Allow passing in the fetch function
         // Instance methods can use this.fetch without differentiating
         this.fetch = get(params, 'fetch', fetch);
+
+        // Defaults to the process singleton. Pass an integration's bound
+        // `this.telemetry` to attribute out-of-band requests — setup/OAuth calls
+        // made before an integration context exists aren't rolled up otherwise.
+        this.telemetry = (params && params.telemetry) || getTelemetry();
+    }
+
+    /**
+     * Redact secrets/PII from a URL before it touches telemetry. Many API
+     * modules embed credentials in the query string (?api_key=, ?token=,
+     * presigned signatures) or in userinfo — those must never reach a span,
+     * the bus, or an exporter. Keep only protocol + host + path (enough for
+     * North Star endpoint matching).
+     */
+    _sanitizeUrl(url) {
+        const raw = String(url);
+        try {
+            const u = new URL(raw);
+            return `${u.protocol}//${u.host}${u.pathname}`;
+        } catch (_) {
+            // Relative/opaque URL: drop the query string at minimum.
+            return raw.split('?')[0];
+        }
+    }
+
+    /** Bounded module label for the apimodule.requests metric. */
+    _telemetryModuleLabel() {
+        return (
+            this.moduleName ||
+            this.delegate?.name ||
+            this.delegate?.constructor?.name ||
+            this.constructor?.name ||
+            'unknown'
+        );
     }
 
     parsedBody = async (resp) => {
@@ -61,15 +96,81 @@ class Requester extends Delegate {
     };
 
     /**
+     * Instrumenting entry point. Wraps the whole logical request —
+     * including retry/refresh recursion — in a single span + one
+     * `frigg.apimodule.requests` counter, emitted on the `attempt === 0`
+     * boundary so retries are never double-counted. The full URL rides the
+     * span only; the metric carries bounded labels {module, method, status}
+     * — never endpoint.
+     *
      * @param {string} url - The request URL, relative or absolute.
      * @param {Object} options - Fetch options (method, headers, body, query,
      *   returnFullRes, etc.) built by the `_get`/`_post`/`_patch`/`_put`/
      *   `_delete` wrappers.
      * @param {number} attempt - 0-based count of retries already made for
+     *   this call. Non-zero only if a caller re-enters directly; normal
+     *   retries recurse through `_rawRequest` instead (see below).
+     */
+    async _request(url, options = {}, attempt = 0) {
+        if (attempt !== 0) {
+            return this._rawRequest(url, options, attempt);
+        }
+
+        const telemetry = this.telemetry;
+        if (!telemetry || typeof telemetry.span !== 'function') {
+            return this._rawRequest(url, options, 0);
+        }
+
+        const module = this._telemetryModuleLabel();
+        const method = (options.method || 'GET').toUpperCase();
+        const safeUrl = this._sanitizeUrl(url);
+
+        return telemetry.span('frigg.apimodule.request', async (span) => {
+            if (span && typeof span.setAttributes === 'function') {
+                span.setAttributes({
+                    'frigg.module': module,
+                    'http.request.method': method,
+                    // Redacted (no query/userinfo) — never emit raw URLs.
+                    'url.path': safeUrl,
+                });
+            }
+            // Redacted url (unbounded) rides the bus-only context for North Star
+            // derived-from-trace matching — never a metric label.
+            const busContext = { url: safeUrl };
+            try {
+                const result = await this._rawRequest(url, options, 0);
+                telemetry.count(
+                    'frigg.apimodule.requests',
+                    1,
+                    { module, method, status: 'ok' },
+                    busContext
+                );
+                return result;
+            } catch (err) {
+                const code = err?.status ?? err?.statusCode;
+                const status = code ? String(code) : 'error';
+                if (span && typeof span.setAttribute === 'function' && code) {
+                    span.setAttribute('http.response.status_code', code);
+                }
+                telemetry.count(
+                    'frigg.apimodule.requests',
+                    1,
+                    { module, method, status },
+                    busContext
+                );
+                throw err;
+            }
+        });
+    }
+
+    /**
+     * @param {string} url - The request URL, relative or absolute.
+     * @param {Object} options - Fetch options, as built by `_request`.
+     * @param {number} attempt - 0-based count of retries already made for
      *   this call. Indexes `this.backOff` for the next delay and is passed
      *   back in on each recursive retry.
      */
-    async _request(url, options, attempt = 0) {
+    async _rawRequest(url, options, attempt = 0) {
         let encodedUrl = encodeURI(url);
         if (options.query) {
             let queryBuild = '?';
@@ -131,7 +232,7 @@ class Requester extends Delegate {
                     clearRequestTimer();
                     const delay = this.backOff[attempt] * 1000;
                     await new Promise((resolve) => setTimeout(resolve, delay));
-                    return this._request(url, options, attempt + 1);
+                    return this._rawRequest(url, options, attempt + 1);
                 }
                 const fetchError = await FetchError.create({
                     resource: encodedUrl,
@@ -161,7 +262,7 @@ class Requester extends Delegate {
                 clearRequestTimer();
                 const delay = this.backOff[attempt] * 1000;
                 await new Promise((resolve) => setTimeout(resolve, delay));
-                return this._request(url, options, attempt + 1);
+                return this._rawRequest(url, options, attempt + 1);
             }
 
             if (status === 401) {
@@ -179,7 +280,7 @@ class Requester extends Delegate {
                         await new Promise((resolve) =>
                             setTimeout(resolve, delay)
                         );
-                        return this._request(url, options, attempt + 1);
+                        return this._rawRequest(url, options, attempt + 1);
                     }
 
                     throw await this._invalidateAuth(
@@ -194,7 +295,7 @@ class Requester extends Delegate {
                     const refreshSucceeded = await this.refreshAuth();
                     if (refreshSucceeded) {
                         clearRequestTimer();
-                        return this._request(url, options, attempt + 1);
+                        return this._rawRequest(url, options, attempt + 1);
                     }
 
                     throw await this._invalidateAuth(

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.102",
+    "version": "2.0.0-next.103",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -9,6 +9,13 @@
         "@aws-sdk/client-sqs": "^3.588.0",
         "@aws-sdk/client-ssm": "^3.588.0",
         "@hapi/boom": "^10.0.1",
+        "@opentelemetry/api": "^1.9.1",
+        "@opentelemetry/context-async-hooks": "^2.9.0",
+        "@opentelemetry/exporter-metrics-otlp-http": "^0.220.0",
+        "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
+        "@opentelemetry/resources": "^2.9.0",
+        "@opentelemetry/sdk-metrics": "^2.9.0",
+        "@opentelemetry/sdk-trace-base": "^2.9.0",
         "bcryptjs": "^2.4.3",
         "body-parser": "^1.20.5",
         "bson": "^4.7.2",
@@ -39,9 +46,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.102",
-        "@friggframework/prettier-config": "2.0.0-next.102",
-        "@friggframework/test": "2.0.0-next.102",
+        "@friggframework/eslint-config": "2.0.0-next.103",
+        "@friggframework/prettier-config": "2.0.0-next.103",
+        "@friggframework/test": "2.0.0-next.103",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -81,5 +88,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "88c3879ce502f9a5eb0e08d41ec55e2559e1fca8"
+    "gitHead": "9fc434b0c6e1323bd16be165d311b6880a23de12"
 }

package/prisma-mongodb/schema.prisma

@@ -430,3 +430,26 @@ model ScriptSchedule {
   @@index([enabled])
   @@map("ScriptSchedule")
 }
+
+/// Durable usage counters, deliberately isolated: no userId and no foreign key
+/// to Integration, so a user-scoped query can never return a usage row and usage
+/// history survives integration deletion.
+model UsageCounter {
+  id String @id @default(auto()) @map("_id") @db.ObjectId
+
+  integrationId   String
+  integrationType String
+  metric          String
+  window          String // e.g. "day:2026-07-05" or "hour:2026-07-05T14"
+  value           BigInt @default(0) // BigInt: a busy day/hour counter can exceed 32-bit
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([integrationId, integrationType, metric, window])
+  // Covers totals() (metric + window prefix/range, no integrationType filter).
+  @@index([metric, window])
+  // Covers series() (metric + integrationType + window range).
+  @@index([metric, integrationType, window])
+  @@map("UsageCounter")
+}

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

@@ -0,0 +1,26 @@
+-- CreateTable
+-- Durable usage counters, 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/prisma-postgresql/schema.prisma

@@ -412,3 +412,25 @@ model ScriptSchedule {
 
   @@index([enabled])
 }
+
+/// Durable usage counters, deliberately isolated: no userId and no foreign key
+/// to Integration, so a user-scoped query can never return a usage row and usage
+/// history survives integration deletion.
+model UsageCounter {
+  id Int @id @default(autoincrement())
+
+  integrationId   String
+  integrationType String
+  metric          String
+  window          String // e.g. "day:2026-07-05" or "hour:2026-07-05T14"
+  value           BigInt @default(0) // BigInt: a busy day/hour counter can exceed 32-bit
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([integrationId, integrationType, metric, window])
+  // Covers totals() (metric + window prefix/range, no integrationType filter).
+  @@index([metric, window])
+  // Covers series() (metric + integrationType + window range).
+  @@index([metric, integrationType, window])
+}

package/reporting/README.md

@@ -52,8 +52,15 @@ Optional query params (all strings): `status` (an `IntegrationStatus`), `type`
 - `filters` — echoes the applied filters (nulls when omitted).
 - `metrics.total` — count of integrations matching the filters.
 - `metrics.byStatus` — counts keyed by `IntegrationStatus` value.
-- `metrics.byType[]` — per `type` breakdown: `{ type, label, total, byStatus }`.
+- `metrics.byType[]` — per `type` breakdown: `{ type, label, total, byStatus, usage? }`.
   - `type` — the `config.type` slug. Integrations with no type bucket as `"unknown"`.
+  - `usage` — **additive** (ADR-011): present only when the deployment has the
+    usage store configured. A map of canonical counter → total for that type,
+    e.g. `{ "records.synced": 4200, "webhooks.received": 118, "api.requests": 9004 }`
+    (`0` when a type has no data). Read only from the Frigg usage store, never an
+    external APM; a usage-store read failure never fails the structural report.
+    Populated by the counters an integration opts into via `Definition.usage` —
+    see [`../telemetry/README.md`](../telemetry/README.md).
   - `label` — human-readable name from the integration class's
     `Definition.display.label`. Falls back to the `type` slug when no registered
     class supplies a label (e.g. an integration that was removed, or run on an

package/reporting/reporting-router.js

@@ -3,7 +3,12 @@ const catchAsyncError = require('express-async-handler');
 const {
     createReportingRepository,
 } = require('./repositories/reporting-repository-factory');
-const { ListIntegrationsReport } = require('./use-cases/list-integrations-report');
+const {
+    createUsageRepository,
+} = require('../usage/repositories/usage-repository-factory');
+const {
+    ListIntegrationsReport,
+} = require('./use-cases/list-integrations-report');
 const { loadAppDefinition } = require('../handlers/app-definition-loader');
 
 // IntegrationBase.Definition default — skip it so the slug is used instead.
@@ -35,8 +40,10 @@ function buildTypeLabels() {
 
 function createReportingRouter() {
     const reportingRepository = createReportingRepository();
+    const usageRepository = createUsageRepository();
     const listIntegrationsReport = new ListIntegrationsReport({
         reportingRepository,
+        usageRepository,
         typeLabels: buildTypeLabels(),
     });
 

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

@@ -1,4 +1,5 @@
 const Boom = require('@hapi/boom');
+const { CANONICAL_COUNTERS } = require('../../telemetry/canonical-counters');
 
 const SCHEMA_VERSION = 1;
 const SERVICE = 'frigg-core-api';
@@ -16,11 +17,19 @@ const KNOWN_STATUSES = [
 ];
 
 class ListIntegrationsReport {
-    constructor({ reportingRepository, typeLabels = {} } = {}) {
+    constructor({
+        reportingRepository,
+        usageRepository,
+        typeLabels = {},
+    } = {}) {
         if (!reportingRepository) {
             throw new Error('reportingRepository is required');
         }
+        if (!usageRepository) {
+            throw new Error('usageRepository is required');
+        }
         this.reportingRepository = reportingRepository;
+        this.usageRepository = usageRepository;
         this.typeLabels = typeLabels;
     }
 
@@ -67,7 +76,8 @@ 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(),
                 });
@@ -77,6 +87,8 @@ class ListIntegrationsReport {
             bucket.byStatus[statusKey] = (bucket.byStatus[statusKey] ?? 0) + 1;
         }
 
+        await this._attachUsageColumns(byTypeMap);
+
         return {
             schemaVersion: SCHEMA_VERSION,
             service: SERVICE,
@@ -96,9 +108,44 @@ 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.getTotalsByDimension({
+                        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) {
+            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`
                 );
@@ -112,9 +159,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;