@friggframework/core 2.0.0-next.11 → 2.0.0-next.110

package/telemetry/telemetry-service.js

@@ -0,0 +1,51 @@
+const { NoOpTelemetry } = require('./no-op-telemetry');
+const { createTelemetryEventBus } = require('./telemetry-event-bus');
+
+/**
+ * @typedef {object} TelemetryService The vendor-neutral telemetry port. Both
+ * NoOpTelemetry and OtelTelemetry implement it (duck-typed; the bound wrapper
+ * from bindTelemetryContext is a plain object that also satisfies it):
+ *   count(name, value?, attributes?, context?) · event(name, attributes?, context?)
+ *   span(name, fn) · startSpan(name?) · withContext(context, fn)
+ *   on(eventType, cb) · forceFlush() · shutdown() · isEnabled()
+ */
+
+/**
+ * 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 — the adapter selector. Integration
+ * code uses the returned instance (`this.telemetry`) and never imports a backend
+ * SDK. With no exporter configured it returns `NoOpTelemetry` (loads zero OTel);
+ * a real exporter lazily constructs `OtelTelemetry`.
+ *
+ * @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 new NoOpTelemetry({ bus });
+    }
+
+    // Lazy-required so the no-op path never loads the OTel SDK.
+    const { OtelTelemetry } = require('./otel-telemetry');
+    return new OtelTelemetry({ ...options, bus });
+}
+
+module.exports = { createTelemetry, isNoOpExporter };

package/telemetry/usage-rollup-subscriber.js

@@ -0,0 +1,116 @@
+const { computeUsageWindows } = require('../usage/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/token/repositories/token-repository-documentdb.js

@@ -0,0 +1,137 @@
+const { prisma } = require('../../database/prisma');
+const bcrypt = require('bcryptjs');
+const {
+    toObjectId,
+    fromObjectId,
+    findMany,
+    findOne,
+    insertOne,
+    deleteOne,
+    deleteMany,
+} = require('../../database/documentdb-utils');
+const { TokenRepositoryInterface } = require('./token-repository-interface');
+const { ClientSafeError } = require('../../errors');
+
+const BCRYPT_ROUNDS = 10;
+
+class TokenRepositoryDocumentDB extends TokenRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async createTokenWithExpire(userId, rawToken, minutes) {
+        const tokenHash = await bcrypt.hash(rawToken, BCRYPT_ROUNDS);
+        const expires = new Date(Date.now() + minutes * 60000);
+        const now = new Date();
+        const document = {
+            token: tokenHash,
+            expires,
+            userId: toObjectId(userId),
+            created: now,
+        };
+        const insertedId = await insertOne(this.prisma, 'Token', document);
+        const created = await findOne(this.prisma, 'Token', {
+            _id: insertedId,
+        });
+        return this._mapToken(created);
+    }
+
+    async validateAndGetToken(tokenObj) {
+        const objectId = toObjectId(tokenObj.id);
+        if (!objectId) {
+            throw new ClientSafeError(
+                'Invalid Token: Token does not exist',
+                401
+            );
+        }
+        const record = await findOne(this.prisma, 'Token', { _id: objectId });
+        if (!record) {
+            throw new ClientSafeError(
+                'Invalid Token: Token does not exist',
+                401
+            );
+        }
+        const isValid = await bcrypt.compare(tokenObj.token, record.token);
+        if (!isValid) {
+            throw new ClientSafeError(
+                'Invalid Token: Token does not match',
+                401
+            );
+        }
+        if (record.expires && new Date(record.expires) < new Date()) {
+            throw new ClientSafeError('Invalid Token: Token is expired', 401);
+        }
+        return this._mapToken(record);
+    }
+
+    async findTokenById(tokenId) {
+        const objectId = toObjectId(tokenId);
+        if (!objectId) return null;
+        const record = await findOne(this.prisma, 'Token', { _id: objectId });
+        return record ? this._mapToken(record) : null;
+    }
+
+    async findTokensByUserId(userId) {
+        const objectId = toObjectId(userId);
+        const filter = objectId ? { userId: objectId } : {};
+        const records = await findMany(this.prisma, 'Token', filter);
+        return records.map((record) => this._mapToken(record));
+    }
+
+    async deleteToken(tokenId) {
+        const objectId = toObjectId(tokenId);
+        if (!objectId) return { acknowledged: true, deletedCount: 0 };
+        const result = await deleteOne(this.prisma, 'Token', { _id: objectId });
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    async deleteExpiredTokens() {
+        const result = await deleteMany(this.prisma, 'Token', {
+            expires: { $lt: new Date() },
+        });
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    async deleteTokensByUserId(userId) {
+        const objectId = toObjectId(userId);
+        if (!objectId) return { acknowledged: true, deletedCount: 0 };
+        const result = await deleteMany(this.prisma, 'Token', {
+            userId: objectId,
+        });
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    createJSONToken(token, rawToken) {
+        return JSON.stringify({
+            id: token.id,
+            token: rawToken,
+        });
+    }
+
+    createBase64BufferToken(token, rawToken) {
+        const jsonVal = this.createJSONToken(token, rawToken);
+        return Buffer.from(jsonVal).toString('base64');
+    }
+
+    getJSONTokenFromBase64BufferToken(buffer) {
+        const tokenStr = Buffer.from(buffer.trim(), 'base64').toString('ascii');
+        return JSON.parse(tokenStr);
+    }
+
+    _mapToken(record) {
+        if (!record) return null;
+        return {
+            id: fromObjectId(record._id),
+            token: record.token,
+            expires: record.expires ? new Date(record.expires) : null,
+            userId: fromObjectId(record.userId),
+            created: record.created ? new Date(record.created) : null,
+        };
+    }
+}
+
+module.exports = { TokenRepositoryDocumentDB };

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

@@ -0,0 +1,40 @@
+const { TokenRepositoryMongo } = require('./token-repository-mongo');
+const { TokenRepositoryPostgres } = require('./token-repository-postgres');
+const {
+    TokenRepositoryDocumentDB,
+} = require('./token-repository-documentdb');
+const config = require('../../database/config');
+
+/**
+ * Token Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * @returns {TokenRepositoryInterface} Configured repository adapter
+ */
+function createTokenRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new TokenRepositoryMongo();
+
+        case 'postgresql':
+            return new TokenRepositoryPostgres();
+
+        case 'documentdb':
+            return new TokenRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createTokenRepository,
+    // Export adapters for direct testing
+    TokenRepositoryMongo,
+    TokenRepositoryPostgres,
+    TokenRepositoryDocumentDB,
+};

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

@@ -0,0 +1,131 @@
+/**
+ * Token Repository Interface
+ * Abstract base class defining the contract for token persistence adapters
+ *
+ * This follows the Port in Hexagonal Architecture:
+ * - Domain layer depends on this abstraction
+ * - Concrete adapters implement this interface
+ * - Use cases receive repositories via dependency injection
+ *
+ * Note: Currently, Token model has identical structure across MongoDB and PostgreSQL,
+ * so TokenRepository serves both. This interface exists for consistency and
+ * future-proofing if database-specific implementations become needed.
+ *
+ * @abstract
+ */
+class TokenRepositoryInterface {
+    /**
+     * Create token with expiration
+     *
+     * @param {string|number} userId - User ID
+     * @param {string} rawToken - Raw unhashed token
+     * @param {number} minutes - Minutes until expiration
+     * @returns {Promise<Object>} Created token object
+     * @abstract
+     */
+    async createTokenWithExpire(userId, rawToken, minutes) {
+        throw new Error(
+            'Method createTokenWithExpire must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Validate and get token
+     *
+     * @param {Object} tokenObj - Token object with id and token
+     * @returns {Promise<Object>} Validated token object
+     * @abstract
+     */
+    async validateAndGetToken(tokenObj) {
+        throw new Error(
+            'Method validateAndGetToken must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Find token by ID
+     *
+     * @param {string|number} tokenId - Token ID
+     * @returns {Promise<Object|null>} Token object or null
+     * @abstract
+     */
+    async findTokenById(tokenId) {
+        throw new Error('Method findTokenById must be implemented by subclass');
+    }
+
+    /**
+     * Find all tokens for a user
+     *
+     * @param {string|number} userId - User ID
+     * @returns {Promise<Array>} Array of token objects
+     * @abstract
+     */
+    async findTokensByUserId(userId) {
+        throw new Error(
+            'Method findTokensByUserId must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Delete token by ID
+     *
+     * @param {string|number} tokenId - Token ID
+     * @returns {Promise<boolean>} True if deleted
+     * @abstract
+     */
+    async deleteToken(tokenId) {
+        throw new Error('Method deleteToken must be implemented by subclass');
+    }
+
+    /**
+     * Delete expired tokens
+     *
+     * @returns {Promise<number>} Number of deleted tokens
+     * @abstract
+     */
+    async deleteExpiredTokens() {
+        throw new Error(
+            'Method deleteExpiredTokens must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Delete all tokens for a user
+     *
+     * @param {string|number} userId - User ID
+     * @returns {Promise<number>} Number of deleted tokens
+     * @abstract
+     */
+    async deleteTokensByUserId(userId) {
+        throw new Error(
+            'Method deleteTokensByUserId must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Create base64 buffer token
+     *
+     * @param {Object} token - Token object
+     * @param {string} rawToken - Raw token
+     * @returns {string} Base64 encoded token
+     */
+    createBase64BufferToken(token, rawToken) {
+        throw new Error(
+            'Method createBase64BufferToken must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Get JSON token from base64 buffer token
+     *
+     * @param {string} base64Token - Base64 encoded token
+     * @returns {Object} Decoded token object
+     */
+    getJSONTokenFromBase64BufferToken(base64Token) {
+        throw new Error(
+            'Method getJSONTokenFromBase64BufferToken must be implemented by subclass'
+        );
+    }
+}
+
+module.exports = { TokenRepositoryInterface };

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

@@ -0,0 +1,219 @@
+const { prisma } = require('../../database/prisma');
+const bcrypt = require('bcryptjs');
+const { TokenRepositoryInterface } = require('./token-repository-interface');
+const { ClientSafeError } = require('../../errors');
+
+const BCRYPT_ROUNDS = 10;
+
+/**
+ * MongoDB Token Repository Adapter
+ * Handles persistence of authentication tokens with bcrypt hashing
+ *
+ * MongoDB-specific characteristics:
+ * - Uses String IDs (ObjectId)
+ * - No ID conversion needed (IDs are already strings)
+ * - Bcrypt hashing handled in repository layer
+ */
+class TokenRepositoryMongo extends TokenRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Create a token with expiration
+     * Replaces: Token.createTokenWithExpire(userId, rawToken, minutes)
+     *
+     * @param {string} userId - The user ID
+     * @param {string} rawToken - The raw (unhashed) token string
+     * @param {number} minutes - Minutes until expiration
+     * @returns {Promise<Object>} The created token record with string IDs
+     */
+    async createTokenWithExpire(userId, rawToken, minutes) {
+        // Hash the token with bcrypt
+        const tokenHash = await bcrypt.hash(rawToken, BCRYPT_ROUNDS);
+
+        // Calculate expiration time
+        const expires = new Date(Date.now() + minutes * 60000);
+
+        return await this.prisma.token.create({
+            data: {
+                token: tokenHash,
+                expires,
+                userId,
+            },
+        });
+    }
+
+    /**
+     * Validate and retrieve token from JSON token object
+     * Replaces: Token.validateAndGetTokenFromJSONToken(tokenObj)
+     *
+     * @param {Object} tokenObj - Object with id and token properties
+     * @returns {Promise<Object>} The validated token record with string IDs
+     * @throws {Error} If token is invalid, expired, or doesn't exist
+     */
+    async validateAndGetToken(tokenObj) {
+        const sessionToken = await this.prisma.token.findUnique({
+            where: { id: tokenObj.id },
+        });
+
+        if (!sessionToken) {
+            throw new ClientSafeError(
+                'Invalid Token: Token does not exist',
+                401
+            );
+        }
+
+        // Verify token hash matches
+        const isValid = await bcrypt.compare(
+            tokenObj.token,
+            sessionToken.token
+        );
+        if (!isValid) {
+            throw new ClientSafeError(
+                'Invalid Token: Token does not match',
+                401
+            );
+        }
+
+        // Check if token is expired
+        if (
+            sessionToken.expires &&
+            new Date(sessionToken.expires) < new Date()
+        ) {
+            throw new ClientSafeError('Invalid Token: Token is expired', 401);
+        }
+
+        return sessionToken;
+    }
+
+    /**
+     * Find a token by ID
+     * Replaces: Token.findById(tokenId)
+     *
+     * @param {string} tokenId - The token ID
+     * @returns {Promise<Object|null>} The token record with string IDs or null
+     */
+    async findTokenById(tokenId) {
+        return await this.prisma.token.findUnique({
+            where: { id: tokenId },
+        });
+    }
+
+    /**
+     * Find tokens by user ID
+     * Replaces: Token.find({ user: userId })
+     *
+     * @param {string} userId - The user ID
+     * @returns {Promise<Array>} Array of token records with string IDs
+     */
+    async findTokensByUserId(userId) {
+        return await this.prisma.token.findMany({
+            where: { userId },
+        });
+    }
+
+    /**
+     * Delete a token by ID
+     * Replaces: Token.deleteOne({ _id: tokenId })
+     *
+     * @param {string} tokenId - The token ID
+     * @returns {Promise<Object>} The deletion result
+     */
+    async deleteToken(tokenId) {
+        try {
+            await this.prisma.token.delete({
+                where: { id: tokenId },
+            });
+            return { acknowledged: true, deletedCount: 1 };
+        } catch (error) {
+            if (error.code === 'P2025') {
+                // Record not found
+                return { acknowledged: true, deletedCount: 0 };
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Delete expired tokens
+     * Replaces: Token.deleteMany({ expires: { $lt: new Date() } })
+     *
+     * @returns {Promise<Object>} The deletion result with count
+     */
+    async deleteExpiredTokens() {
+        const result = await this.prisma.token.deleteMany({
+            where: {
+                expires: {
+                    lt: new Date(),
+                },
+            },
+        });
+
+        return {
+            acknowledged: true,
+            deletedCount: result.count,
+        };
+    }
+
+    /**
+     * Delete all tokens for a user
+     * Replaces: Token.deleteMany({ user: userId })
+     *
+     * @param {string} userId - The user ID
+     * @returns {Promise<Object>} The deletion result
+     */
+    async deleteTokensByUserId(userId) {
+        const result = await this.prisma.token.deleteMany({
+            where: { userId },
+        });
+
+        return {
+            acknowledged: true,
+            deletedCount: result.count,
+        };
+    }
+
+    /**
+     * Create JSON token string from token object and raw token
+     * Replaces: Token.createJSONToken(token, rawToken)
+     *
+     * @param {Object} token - The token record
+     * @param {string} rawToken - The raw token string
+     * @returns {string} JSON string with id and token
+     */
+    createJSONToken(token, rawToken) {
+        return JSON.stringify({
+            id: token.id,
+            token: rawToken,
+        });
+    }
+
+    /**
+     * Create base64 encoded buffer token
+     * Replaces: Token.createBase64BufferToken(token, rawToken)
+     *
+     * @param {Object} token - The token record
+     * @param {string} rawToken - The raw token string
+     * @returns {string} Base64 encoded token
+     */
+    createBase64BufferToken(token, rawToken) {
+        const jsonVal = this.createJSONToken(token, rawToken);
+        return Buffer.from(jsonVal).toString('base64');
+    }
+
+    /**
+     * Parse JSON token from base64 buffer
+     * Replaces: Token.getJSONTokenFromBase64BufferToken(buffer)
+     *
+     * @param {string} buffer - Base64 encoded token string
+     * @returns {Object} Parsed token object with id and token
+     */
+    getJSONTokenFromBase64BufferToken(buffer) {
+        const tokenStr = Buffer.from(buffer.trim(), 'base64').toString('ascii');
+        return JSON.parse(tokenStr);
+    }
+}
+
+module.exports = { TokenRepositoryMongo };