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

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

@@ -1,199 +0,0 @@
-const { prisma } = require('../../database/prisma');
-const { updateOne } = require('../../database/documentdb-utils');
-const { UsageRepositoryMongo } = require('./usage-repository-mongo');
-
-const COLLECTION = 'UsageCounter';
-const DRAIN_BATCH_SIZE = 1000;
-const MAX_BATCHES = 100000;
-const VALID_GROUP_BY = new Set(['integrationType', 'metric']);
-const VALID_BUCKETS = new Set(['day', 'hour']);
-
-/**
- * DocumentDB usage store. Amazon DocumentDB does not accept the command shapes
- * Prisma's Mongo engine emits for `upsert({ update: { value: { increment } } })`
- * and `groupBy({ _sum })`, and cursor reads truncate at ~101 docs — so, like
- * every other DocumentDB adapter in this repo, these operations are issued as
- * raw commands (`$runCommandRaw`) via the validated documentdb-utils helpers and
- * a drained aggregate cursor. No timestamps are managed: totals/series filter on
- * the window KEY (not write-time), so createdAt/updatedAt are unnecessary here.
- */
-class UsageRepositoryDocumentDB extends UsageRepositoryMongo {
-    constructor() {
-        super();
-        this.prisma = prisma;
-    }
-
-    async increment({ integrationId, integrationType, metric, window, value = 1 }) {
-        // Atomic upsert-increment: $inc creates the field at the increment value
-        // on insert; $setOnInsert stamps the identity on first write. The compound
-        // filter is the unique key, so concurrent writers converge on one row.
-        await updateOne(
-            this.prisma,
-            COLLECTION,
-            { integrationId, integrationType, metric, window },
-            {
-                $inc: { value },
-                $setOnInsert: {
-                    integrationId,
-                    integrationType,
-                    metric,
-                    window,
-                },
-            },
-            { upsert: true }
-        );
-    }
-
-    async totals({
-        metric,
-        groupBy = 'integrationType',
-        since,
-        bucket = 'day',
-    } = {}) {
-        if (!metric) {
-            throw new Error('totals requires a metric (units are per-metric)');
-        }
-        assertGroupBy(groupBy);
-        assertBucket(bucket);
-
-        // Single window granularity (day: OR hour:) — never sum across both.
-        // `since` bounds on the window KEY (mirrors series / the Prisma adapter).
-        const rows = await this._aggregateDrained([
-            {
-                $match: {
-                    metric,
-                    window: windowMatch(bucket, {
-                        gte: since ? windowKey(bucket, since) : undefined,
-                    }),
-                },
-            },
-            { $group: { _id: `$${groupBy}`, value: { $sum: '$value' } } },
-        ]);
-
-        return rows.map((row) => ({
-            [groupBy]: row._id,
-            value: toNumber(row.value),
-        }));
-    }
-
-    async series({ metric, integrationType, from, to, bucket = 'day' } = {}) {
-        assertBucket(bucket);
-        if (!integrationType) {
-            throw new Error('series requires an integrationType');
-        }
-
-        const rows = await this._aggregateDrained([
-            {
-                $match: {
-                    metric,
-                    integrationType,
-                    window: windowMatch(bucket, {
-                        gte: from ? windowKey(bucket, from) : undefined,
-                        lte: to ? windowKey(bucket, to) : undefined,
-                    }),
-                },
-            },
-            { $group: { _id: '$window', value: { $sum: '$value' } } },
-            { $sort: { _id: 1 } },
-        ]);
-
-        return rows.map((row) => ({
-            bucket: row._id,
-            value: toNumber(row.value),
-        }));
-    }
-
-    async _aggregateDrained(pipeline) {
-        const first = await this.prisma.$runCommandRaw({
-            aggregate: COLLECTION,
-            pipeline,
-            cursor: { batchSize: DRAIN_BATCH_SIZE },
-        });
-        return drainCursor(this.prisma, COLLECTION, first);
-    }
-}
-
-/** A `$match` window clause: prefix by granularity, optionally range-bounded. */
-function windowMatch(bucket, { gte, lte } = {}) {
-    const clause = { $regex: `^${bucket}:` };
-    if (gte) clause.$gte = gte;
-    if (lte) clause.$lte = lte;
-    return clause;
-}
-
-/** Window key for a date at a granularity (mirrors telemetry/usage-windows). */
-function windowKey(bucket, date) {
-    const iso = new Date(date).toISOString();
-    return `${bucket}:${bucket === 'hour' ? iso.slice(0, 13) : iso.slice(0, 10)}`;
-}
-
-/**
- * Coerce an aggregate `$sum` result to a JS Number. Prisma $runCommandRaw returns
- * extended JSON, so a 64-bit sum can arrive as { $numberLong: "..." } (or
- * $numberInt/$numberDouble); counts never approach 2^53.
- */
-function toNumber(value) {
-    if (value === null || value === undefined) return 0;
-    if (typeof value === 'number') return value;
-    if (typeof value === 'bigint') return Number(value);
-    if (typeof value === 'object') {
-        const raw =
-            value.$numberLong ?? value.$numberInt ?? value.$numberDouble;
-        if (raw !== undefined) return Number(raw);
-    }
-    return Number(value) || 0;
-}
-
-async function drainCursor(client, collection, firstResult) {
-    const cursor = firstResult?.cursor || {};
-    const docs = [...(cursor.firstBatch || [])];
-    let cursorId = cursor.id;
-    let batches = 0;
-
-    while (isCursorOpen(cursorId) && batches < MAX_BATCHES) {
-        batches += 1;
-        const next = await client.$runCommandRaw({
-            getMore: cursorId,
-            collection,
-            batchSize: DRAIN_BATCH_SIZE,
-        });
-        const nextCursor = next?.cursor || {};
-        const nextBatch = nextCursor.nextBatch || [];
-        docs.push(...nextBatch);
-        cursorId = nextCursor.id;
-        if (nextBatch.length === 0) break;
-    }
-    return docs;
-}
-
-function isCursorOpen(id) {
-    if (id === undefined || id === null) return false;
-    if (typeof id === 'number') return id !== 0;
-    if (typeof id === 'bigint') return id !== 0n;
-    if (typeof id === 'object' && id.$numberLong !== undefined) {
-        return id.$numberLong !== '0';
-    }
-    return String(id) !== '0';
-}
-
-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 = { UsageRepositoryDocumentDB };

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

@@ -1,28 +0,0 @@
-const { UsageRepositoryMongo } = require('./usage-repository-mongo');
-const { UsageRepositoryPostgres } = require('./usage-repository-postgres');
-const { UsageRepositoryDocumentDB } = require('./usage-repository-documentdb');
-const config = require('../../database/config');
-
-function createUsageRepository() {
-    const dbType = config.DB_TYPE;
-
-    switch (dbType) {
-        case 'mongodb':
-            return new UsageRepositoryMongo();
-        case 'postgresql':
-            return new UsageRepositoryPostgres();
-        case 'documentdb':
-            return new UsageRepositoryDocumentDB();
-        default:
-            throw new Error(
-                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
-            );
-    }
-}
-
-module.exports = {
-    createUsageRepository,
-    UsageRepositoryMongo,
-    UsageRepositoryPostgres,
-    UsageRepositoryDocumentDB,
-};

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

@@ -1,37 +0,0 @@
-/**
- * Port for the durable usage-counter store.
- *
- * The store is deliberately isolated (ADR-010 Decision 3): its fact rows carry
- * 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.
- *
- * Fact row: { integrationId, integrationType, metric, window, value, updatedAt }
- * Dimensions must be bounded — high-cardinality ids stay on traces.
- */
-class UsageRepositoryInterface {
-    /**
-     * Atomically add `value` to the counter for
-     * (integrationId, integrationType, metric, window), inserting if absent.
-     */
-    async increment(/* { integrationId, integrationType, metric, window, value } */) {
-        throw new Error('increment must be implemented by subclass');
-    }
-
-    /**
-     * Sum a metric grouped by a bounded dimension since an optional timestamp.
-     * @returns {Promise<Array<{[groupBy]: string, value: number}>>}
-     */
-    async totals(/* { metric, groupBy, since } */) {
-        throw new Error('totals must be implemented by subclass');
-    }
-
-    /**
-     * Time series of a metric for one integration type.
-     * @returns {Promise<Array<{bucket: string, value: number}>>}
-     */
-    async series(/* { metric, integrationType, from, to, bucket } */) {
-        throw new Error('series must be implemented by subclass');
-    }
-}
-
-module.exports = { UsageRepositoryInterface };

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

@@ -1,12 +0,0 @@
-const { UsageRepositoryPostgres } = require('./usage-repository-postgres');
-
-/**
- * Mongo usage store. `UsageCounter` has no encrypted fields and only simple
- * upsert/aggregate operations, and Prisma abstracts the query layer, so the
- * Postgres implementation runs unchanged on the Mongo client (integrationId is
- * stored as a plain string in both). Kept as a distinct class to preserve the
- * repository-triad convention and give a seam if the paths ever diverge.
- */
-class UsageRepositoryMongo extends UsageRepositoryPostgres {}
-
-module.exports = { UsageRepositoryMongo };

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

@@ -1,152 +0,0 @@
-const { prisma } = require('../../database/prisma');
-const { UsageRepositoryInterface } = require('./usage-repository-interface');
-
-/**
- * Prisma-backed usage store. This is the canonical implementation;
- * because Prisma abstracts the underlying database, the Mongo and DocumentDB
- * adapters extend this class unchanged (see their files). All queries touch only
- * the isolated `UsageCounter` model — never user/integration-scoped tables.
- */
-class UsageRepositoryPostgres 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 totals({
-        metric,
-        groupBy = 'integrationType',
-        since,
-        bucket = 'day',
-    } = {}) {
-        if (!metric) {
-            throw new Error('totals 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 series) — 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 series({ metric, integrationType, from, to, bucket = 'day' } = {}) {
-        assertBucket(bucket);
-        if (!integrationType) {
-            throw new Error('series 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(
-                ', '
-            )}`
-        );
-    }
-}
-
-/** Window key for a date at a granularity (mirrors telemetry/usage-windows). */
-function windowKey(bucket, date) {
-    const iso = new Date(date).toISOString();
-    return `${bucket}:${
-        bucket === 'hour' ? iso.slice(0, 13) : iso.slice(0, 10)
-    }`;
-}
-
-module.exports = { UsageRepositoryPostgres };

package/usage/tracked-metrics.js

@@ -1,38 +0,0 @@
-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 };