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

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

@@ -0,0 +1,146 @@
+const { prisma } = require('../../database/prisma');
+const { UsageRepositoryInterface } = require('./usage-repository-interface');
+const { windowKey } = require('../usage-windows');
+
+/**
+ * Prisma-backed usage store — the single implementation for both mongodb and
+ * postgresql (Prisma abstracts the store; integrationId is a plain string in
+ * both). DocumentDB extends this but overrides the write/read ops with raw
+ * commands. All queries touch only the isolated `UsageCounter` model — never
+ * user/integration-scoped tables.
+ */
+class UsageRepositoryPrisma extends UsageRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async increment({
+        integrationId,
+        integrationType,
+        metric,
+        window,
+        value = 1,
+    }) {
+        const where = {
+            integrationId_integrationType_metric_window: {
+                integrationId,
+                integrationType,
+                metric,
+                window,
+            },
+        };
+        const upsertArgs = {
+            where,
+            create: { integrationId, integrationType, metric, window, value },
+            update: { value: { increment: value } },
+        };
+
+        // Concurrent first-insert race: two workers both INSERT and one hits the
+        // unique constraint (P2002). After the winner's insert the row exists, so
+        // a retry takes the atomic UPDATE (increment) path. Bounded so a
+        // pathological repeated race can't throw unexpectedly out of the public
+        // `recordUsageCounter` write; non-conflict errors surface immediately.
+        for (let attempt = 1; ; attempt++) {
+            try {
+                await this.prisma.usageCounter.upsert(upsertArgs);
+                return;
+            } catch (err) {
+                if (err && err.code === 'P2002' && attempt < MAX_UPSERT_ATTEMPTS) {
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+
+    async getTotalsByDimension({
+        metric,
+        groupBy = 'integrationType',
+        since,
+        bucket = 'day',
+    } = {}) {
+        if (!metric) {
+            throw new Error('getTotalsByDimension requires a metric (units are per-metric)');
+        }
+        assertGroupBy(groupBy);
+        assertBucket(bucket);
+
+        // 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 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}:` } };
+        if (since) where.window.gte = windowKey(bucket, since);
+
+        const groups = await this.prisma.usageCounter.groupBy({
+            by: [groupBy],
+            where,
+            _sum: { value: true },
+        });
+
+        // value is a BigInt column — coerce the sum to a JSON-safe Number
+        // (JSON.stringify throws on BigInt; counts never approach 2^53).
+        return groups.map((group) => ({
+            [groupBy]: group[groupBy],
+            value: Number(group._sum?.value ?? 0),
+        }));
+    }
+
+    async getTimeSeries({ metric, integrationType, from, to, bucket = 'day' } = {}) {
+        assertBucket(bucket);
+        if (!integrationType) {
+            throw new Error('getTimeSeries requires an integrationType');
+        }
+
+        // Range-filter on the WINDOW key (write-time `updatedAt` would misplace a
+        // late increment for an earlier window). Window keys are ISO-lexicographic
+        // within a granularity, so string gte/lte gives the correct range.
+        const window = { startsWith: `${bucket}:` };
+        if (from) window.gte = windowKey(bucket, from);
+        if (to) window.lte = windowKey(bucket, to);
+
+        // Aggregate ACROSS integration instances: there is one row per
+        // (integrationId, integrationType, metric, window), so a type with many
+        // instances has many rows per window — sum them into one point.
+        const groups = await this.prisma.usageCounter.groupBy({
+            by: ['window'],
+            where: { metric, integrationType, window },
+            _sum: { value: true },
+            orderBy: { window: 'asc' },
+        });
+
+        return groups.map((group) => ({
+            bucket: group.window,
+            value: Number(group._sum?.value ?? 0),
+        }));
+    }
+}
+
+const MAX_UPSERT_ATTEMPTS = 3;
+const VALID_GROUP_BY = new Set(['integrationType', 'metric']);
+const VALID_BUCKETS = new Set(['day', 'hour']);
+
+function assertGroupBy(groupBy) {
+    if (!VALID_GROUP_BY.has(groupBy)) {
+        throw new Error(
+            `Invalid groupBy "${groupBy}". Allowed: ${[...VALID_GROUP_BY].join(
+                ', '
+            )}`
+        );
+    }
+}
+
+function assertBucket(bucket) {
+    if (!VALID_BUCKETS.has(bucket)) {
+        throw new Error(
+            `Invalid bucket "${bucket}". Allowed: ${[...VALID_BUCKETS].join(
+                ', '
+            )}`
+        );
+    }
+}
+
+module.exports = { UsageRepositoryPrisma };

package/usage/tracked-metrics.js

@@ -0,0 +1,38 @@
+const { isCanonicalCounter } = require('../telemetry/canonical-counters');
+
+/**
+ * Compute the set of usage-counter keys the rollup should persist, from each
+ * integration's `Definition.usage` opt-in.
+ * Declaring a canonical key opts into cross-type comparison + the rollup; custom
+ * keys are tracked per integration type. Unknown canonical keys are dropped with
+ * a warning (lazy validation, matching how Definition is treated elsewhere).
+ */
+function computeTrackedMetrics(integrationClasses = []) {
+    const tracked = new Set();
+    if (!Array.isArray(integrationClasses)) return tracked;
+
+    for (const IntegrationClass of integrationClasses) {
+        const usage = IntegrationClass?.Definition?.usage;
+        if (!usage) continue;
+        const name = IntegrationClass.Definition?.name || 'integration';
+
+        for (const key of usage.canonical || []) {
+            if (!isCanonicalCounter(key)) {
+                console.warn(
+                    `[Frigg][usage] "${name}" declares unknown canonical counter "${key}" — ignored. ` +
+                        `Use a key from CANONICAL_COUNTERS or declare it under usage.custom.`
+                );
+                continue;
+            }
+            tracked.add(key);
+        }
+
+        for (const key of Object.keys(usage.custom || {})) {
+            tracked.add(key);
+        }
+    }
+
+    return tracked;
+}
+
+module.exports = { computeTrackedMetrics };

package/usage/usage-windows.js

@@ -0,0 +1,24 @@
+/**
+ * Rollup window keys. A window key is `<granularity>:<UTC-truncated-timestamp>`
+ * (e.g. `day:2026-07-05`, `hour:2026-07-05T14`), prefixed by granularity so the
+ * store can filter a series by bucket (`window startsWith 'day:'`) and range on
+ * the ISO-lexicographic keys. Shared by the rollup writer and the read
+ * repositories so the write/read formats can never drift.
+ */
+function windowKey(bucket, date = new Date()) {
+    const iso = new Date(date).toISOString();
+    return `${bucket}:${
+        bucket === 'hour' ? iso.slice(0, 13) : iso.slice(0, 10)
+    }`;
+}
+
+/**
+ * The window keys a usage event falls into — one per granularity.
+ * @param {Date} [date] Defaults to now.
+ * @returns {string[]} e.g. ['day:2026-07-05', 'hour:2026-07-05T14']
+ */
+function computeUsageWindows(date = new Date()) {
+    return [windowKey('day', date), windowKey('hour', date)];
+}
+
+module.exports = { computeUsageWindows, windowKey };