@friggframework/core 2.0.0--canary.679.a2bcc2f.0 → 2.0.0--canary.686.219e1e7.0

package/database/config.js

@@ -3,6 +3,39 @@
  * Manages configuration for Prisma ORM operations
  */
 
+/**
+ * Maps an app definition's `database` block to a Prisma database type.
+ *
+ * @param {Object|undefined} database - `Definition.database`
+ * @param {string} where - where the definition lives, for the error message
+ * @returns {'mongodb'|'postgresql'|'documentdb'}
+ */
+function databaseTypeFromConfig(database, where) {
+    if (!database) {
+        throw new Error(
+            '[Frigg] App definition missing database configuration. ' +
+            `Add database: { postgres: { enable: true } } (or mongoDB/documentDB) to ${where}`
+        );
+    }
+
+    // Determine database type from enabled database
+    // Priority order: postgres > mongoDB > documentDB
+    if (database.postgres?.enable === true) {
+        return 'postgresql';
+    }
+    if (database.mongoDB?.enable === true) {
+        return 'mongodb';
+    }
+    if (database.documentDB?.enable === true) {
+        return 'documentdb';
+    }
+
+    throw new Error(
+        '[Frigg] No database enabled in app definition. ' +
+        'Set one of: database.postgres.enable, database.mongoDB.enable, or database.documentDB.enable to true'
+    );
+}
+
 /**
  * Determines database type from environment or app definition
  * 
@@ -21,6 +54,20 @@ function getDatabaseType() {
 
     // Fallback: Load app definition
     try {
+        // A definition preset with setAppDefinition() (provider-netlify's
+        // function preamble) wins: on Netlify process.cwd() is the function
+        // root at runtime, so discovery cannot find the backend.
+        const {
+            getPresetAppDefinition,
+        } = require('../handlers/app-definition-loader');
+        const preset = getPresetAppDefinition();
+        if (preset) {
+            return databaseTypeFromConfig(
+                preset.database,
+                'your backend/index.js'
+            );
+        }
+
         const path = require('node:path');
         const fs = require('node:fs');
         const { findNearestBackendPackageJson } = require('../utils');
@@ -76,30 +123,7 @@ function getDatabaseType() {
         }
 
         database = backendModule?.Definition?.database;
-
-        if (!database) {
-            throw new Error(
-                '[Frigg] App definition missing database configuration. ' +
-                `Add database: { postgres: { enable: true } } (or mongoDB/documentDB) to ${backendIndexPath}`
-            );
-        }
-
-        // Determine database type from enabled database
-        // Priority order: postgres > mongoDB > documentDB
-        if (database.postgres?.enable === true) {
-            return 'postgresql';
-        }
-        if (database.mongoDB?.enable === true) {
-            return 'mongodb';
-        }
-        if (database.documentDB?.enable === true) {
-            return 'documentdb';
-        }
-
-        throw new Error(
-            '[Frigg] No database enabled in app definition. ' +
-            'Set one of: database.postgres.enable, database.mongoDB.enable, or database.documentDB.enable to true'
-        );
+        return databaseTypeFromConfig(database, backendIndexPath);
     } catch (error) {
         // Re-throw with context if it's our error
         if (error.message.includes('[Frigg]')) {

package/database/documentdb-utils.js

@@ -58,7 +58,12 @@ async function insertOne(client, collection, document) {
 
         // Provide helpful context for common errors
         if (error.code === 11000) {
-            throw new Error(`${errorMsg} - Duplicate key violation`);
+            // `code` lets callers recognise a lost race without parsing text
+            // (see database/unique-violation.js).
+            throw Object.assign(
+                new Error(`${errorMsg} - Duplicate key violation`),
+                { code: 11000 }
+            );
         }
         throw new Error(errorMsg);
     }

package/database/encryption/encryption-schema-registry.js

@@ -218,22 +218,80 @@ function loadModuleEncryptionSchemas(integrations) {
  *
  * Used by both Prisma (MongoDB/PostgreSQL) and DocumentDB encryption services.
  */
-function loadCustomEncryptionSchema() {
-    try {
-        // Lazy require to avoid circular dependency issues
-        const path = require('node:path');
-        const { findNearestBackendPackageJson } = require('../../utils');
+/**
+ * Registers encryption schemas declared by app-level extensions
+ * (`appDefinition.extensions[].encryption`), e.g. the db-credentials
+ * extension's `OAuthAppCredential.clientSecret`.
+ *
+ * @param {Array<Object>} extensions - Normalized extensions (extension-loader)
+ */
+function loadExtensionEncryptionSchemas(extensions) {
+    if (!extensions || !Array.isArray(extensions) || extensions.length === 0) {
+        return;
+    }
 
-        const backendPackagePath = findNearestBackendPackageJson();
-        if (!backendPackagePath) {
-            return; // No backend found, skip custom schema
+    for (const ext of extensions) {
+        if (!ext.encryption || typeof ext.encryption !== 'object') {
+            continue;
+        }
+
+        const schema = {};
+        for (const [modelName, config] of Object.entries(ext.encryption)) {
+            if (config && Array.isArray(config.fields) && config.fields.length > 0) {
+                schema[modelName] = { fields: config.fields };
+            }
+        }
+
+        if (Object.keys(schema).length > 0) {
+            logger.info(
+                `Registering encryption schema from extension "${ext.name}" for models: ${Object.keys(schema).join(', ')}`
+            );
+            // registerCustomSchema replaces the registered schema, so merge:
+            // an extension adds its models to the app's encryption.schema
+            // rather than dropping it.
+            const merged = { ...customSchema };
+            for (const [modelName, config] of Object.entries(schema)) {
+                const existing = merged[modelName]?.fields || [];
+                merged[modelName] = {
+                    ...merged[modelName],
+                    fields: [...new Set([...existing, ...config.fields])],
+                };
+            }
+            registerCustomSchema(merged);
         }
+    }
+}
+
+function readAppDefinitionForEncryption() {
+    // Lazy require to avoid circular dependency issues
+    const {
+        getPresetAppDefinition,
+    } = require('../../handlers/app-definition-loader');
+    // A definition preset with setAppDefinition() (provider-netlify's
+    // preamble) wins: on Netlify process.cwd() cannot find the backend.
+    const preset = getPresetAppDefinition();
+    if (preset) {
+        return preset;
+    }
+
+    const path = require('node:path');
+    const { findNearestBackendPackageJson } = require('../../utils');
+
+    const backendPackagePath = findNearestBackendPackageJson();
+    if (!backendPackagePath) {
+        return null; // No backend found, skip custom schema
+    }
 
-        const backendDir = path.dirname(backendPackagePath);
-        const backendIndexPath = path.join(backendDir, 'index.js');
+    const backendDir = path.dirname(backendPackagePath);
+    const backendIndexPath = path.join(backendDir, 'index.js');
 
-        const backendModule = require(backendIndexPath);
-        const appDefinition = backendModule?.Definition;
+    const backendModule = require(backendIndexPath);
+    return backendModule?.Definition || null;
+}
+
+function loadCustomEncryptionSchema() {
+    try {
+        const appDefinition = readAppDefinitionForEncryption();
 
         if (!appDefinition) {
             return; // No app definition found
@@ -253,6 +311,15 @@ function loadCustomEncryptionSchema() {
             registerEncryptionOptOut(disable);
         }
 
+        // Load app-level extension encryption schemas. Before the module
+        // schemas: loadModuleEncryptionSchemas currently throws (see the
+        // NOTE inside it) and the throw would skip anything after it.
+        const { loadExtensions } = require('../../extensions/extension-loader');
+        const extensions = loadExtensions(appDefinition);
+        if (extensions.length > 0) {
+            loadExtensionEncryptionSchemas(extensions);
+        }
+
         // Load module-level encryption schemas from integrations
         const integrations = appDefinition.integrations;
         if (integrations && Array.isArray(integrations)) {
@@ -409,6 +476,7 @@ module.exports = {
     registerEncryptionOptOut,
     loadCustomEncryptionSchema,
     loadModuleEncryptionSchemas,
+    loadExtensionEncryptionSchemas,
     extractCredentialFieldsFromModules,
     validateCustomSchema,
     validateOptOut,

package/database/organization-where.js

@@ -0,0 +1,18 @@
+/**
+ * The Prisma `where` fragment for an `organizationId` on MongoDB (ADR-056
+ * §3.6), shared by the entity and integration adapters.
+ *
+ * Prisma on MongoDB: `null` matches only an explicit null and `isSet: false`
+ * only a missing field. A row written before the column existed is the common
+ * "no organization" case, so `null` here means both.
+ */
+function organizationWhere(organizationId) {
+    if (organizationId === null) {
+        return {
+            OR: [{ organizationId: null }, { organizationId: { isSet: false } }],
+        };
+    }
+    return { organizationId };
+}
+
+module.exports = { organizationWhere };

package/database/prisma.js

@@ -67,13 +67,15 @@ const prismaClientSingleton = () => {
         const paths = [
             // Lambda layer location (when using Prisma Lambda layer)
             `/opt/nodejs/node_modules/generated/prisma-${dbType}`,
+            // __dirname-based absolute path (Netlify functions and bundlers)
+            require('node:path').resolve(__dirname, `../generated/prisma-${dbType}`),
             // Local development location (relative to core package)
             `../generated/prisma-${dbType}`,
         ];
 
-        for (const path of paths) {
+        for (const candidate of paths) {
             try {
-                return require(path).PrismaClient;
+                return require(candidate).PrismaClient;
             } catch (err) {
                 // Continue to next path
             }

package/database/unique-violation.js

@@ -0,0 +1,25 @@
+/** Mongo/DocumentDB duplicate-key error code. */
+const DUPLICATE_KEY_CODE = 11000;
+/** Prisma's unique-constraint error code (PostgreSQL and MongoDB). */
+const PRISMA_UNIQUE_CODE = 'P2002';
+
+/**
+ * Whether `error` is a unique-constraint violation, however the database
+ * layer raised it: a Prisma `P2002`, or a duplicate-key `11000`
+ * (`documentdb-utils` `insertOne` sets `code` on the error it throws).
+ * Matches on the code only, never on message text.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isUniqueViolation(error) {
+    return (
+        error?.code === PRISMA_UNIQUE_CODE || error?.code === DUPLICATE_KEY_CODE
+    );
+}
+
+module.exports = {
+    isUniqueViolation,
+    DUPLICATE_KEY_CODE,
+    PRISMA_UNIQUE_CODE,
+};

package/extensions/bootstrap-runner.js

@@ -0,0 +1,43 @@
+/**
+ * Bootstrap Runner
+ *
+ * Runs extension bootstrap functions in sequence.
+ * Bootstrap hooks execute AFTER database connection but BEFORE integration
+ * router creation. This is the right place for extensions to:
+ *
+ * - Load credentials from database into integration definitions
+ * - Register additional middleware or services
+ * - Perform one-time initialization
+ *
+ * @example
+ * await runExtensionBootstraps(extensions, { prisma, appDefinition });
+ */
+
+/**
+ * Runs all extension bootstrap functions in sequence.
+ *
+ * @param {Array<Object>} extensions - Normalized extensions (from extension-loader)
+ * @param {Object} context
+ * @param {Object} context.prisma - Prisma client instance
+ * @param {Object} context.appDefinition - Full app definition
+ * @throws {Error} If any bootstrap function fails (fails fast)
+ */
+async function runExtensionBootstraps(extensions, context = {}) {
+    if (!extensions || extensions.length === 0) return;
+
+    const { prisma, appDefinition } = context;
+
+    for (const ext of extensions) {
+        if (!ext.bootstrap) continue;
+
+        try {
+            await ext.bootstrap(prisma, appDefinition);
+        } catch (error) {
+            throw new Error(
+                `Extension "${ext.name}" bootstrap failed: ${error.message}`
+            );
+        }
+    }
+}
+
+module.exports = { runExtensionBootstraps };

package/extensions/extension-loader.js

@@ -0,0 +1,167 @@
+/**
+ * Extension Loader
+ *
+ * Validates and normalizes extensions from the app definition.
+ * Extensions allow integration developers to add custom Prisma models,
+ * encryption schemas, routes, and bootstrap logic to a Frigg app.
+ *
+ * @example
+ * const extensions = loadExtensions(appDefinition);
+ * // extensions is a normalized array, safe to iterate
+ */
+
+const path = require('path');
+
+/**
+ * Validates a single extension definition.
+ * @param {Object} ext - Raw extension config from app definition
+ * @param {number} index - Position in the extensions array (for error messages)
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+function validateExtension(ext, index) {
+    const prefix = `extensions[${index}]`;
+    const errors = [];
+
+    if (!ext || typeof ext !== 'object') {
+        errors.push(`${prefix}: must be an object`);
+        return { valid: false, errors };
+    }
+
+    if (!ext.name || typeof ext.name !== 'string') {
+        errors.push(`${prefix}.name: required string`);
+    }
+
+    // schema is optional — path to a .prisma file
+    if (ext.schema !== undefined) {
+        if (typeof ext.schema !== 'string') {
+            errors.push(`${prefix}.schema: must be a string (path to .prisma file)`);
+        } else if (!ext.schema.endsWith('.prisma')) {
+            errors.push(`${prefix}.schema: must end with .prisma`);
+        }
+    }
+
+    // encryption is optional — object with model names → { fields: [...] }
+    if (ext.encryption !== undefined) {
+        if (!ext.encryption || typeof ext.encryption !== 'object') {
+            errors.push(`${prefix}.encryption: must be an object`);
+        } else {
+            for (const [model, config] of Object.entries(ext.encryption)) {
+                if (!config || !Array.isArray(config.fields)) {
+                    errors.push(
+                        `${prefix}.encryption.${model}: must have a "fields" array`
+                    );
+                }
+            }
+        }
+    }
+
+    // routes is optional — { path, handler }
+    if (ext.routes !== undefined) {
+        if (!ext.routes || typeof ext.routes !== 'object') {
+            errors.push(`${prefix}.routes: must be an object with { path, handler }`);
+        } else {
+            if (!ext.routes.path || typeof ext.routes.path !== 'string') {
+                errors.push(`${prefix}.routes.path: required string`);
+            }
+            if (!ext.routes.handler) {
+                errors.push(`${prefix}.routes.handler: required (function or module path)`);
+            }
+        }
+    }
+
+    // bootstrap is optional — function or module path
+    if (ext.bootstrap !== undefined) {
+        if (typeof ext.bootstrap !== 'function' && typeof ext.bootstrap !== 'string') {
+            errors.push(
+                `${prefix}.bootstrap: must be a function or a string (module path)`
+            );
+        }
+    }
+
+    return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Loads and validates extensions from the app definition.
+ *
+ * @param {Object} appDefinition - The full app definition
+ * @returns {Array<Object>} Normalized extensions array (empty if none)
+ * @throws {Error} If any extension fails validation
+ */
+function loadExtensions(appDefinition) {
+    if (!appDefinition) return [];
+
+    const raw = appDefinition.extensions;
+    if (!raw) return [];
+
+    if (!Array.isArray(raw)) {
+        throw new Error('appDefinition.extensions must be an array');
+    }
+
+    if (raw.length === 0) return [];
+
+    const allErrors = [];
+
+    const normalized = raw.map((ext, index) => {
+        const { valid, errors } = validateExtension(ext, index);
+        if (!valid) {
+            allErrors.push(...errors);
+            return null;
+        }
+
+        // Normalize bootstrap — resolve string paths to functions
+        let bootstrapFn = null;
+        if (typeof ext.bootstrap === 'function') {
+            bootstrapFn = ext.bootstrap;
+        } else if (typeof ext.bootstrap === 'string') {
+            bootstrapFn = require(ext.bootstrap);
+        }
+
+        // Normalize route handler — resolve string paths to functions
+        let routeHandler = null;
+        if (ext.routes) {
+            if (typeof ext.routes.handler === 'function') {
+                routeHandler = ext.routes.handler;
+            } else if (typeof ext.routes.handler === 'string') {
+                routeHandler = require(ext.routes.handler);
+            } else {
+                routeHandler = ext.routes.handler;
+            }
+        }
+
+        return {
+            name: ext.name,
+            schema: ext.schema || null,
+            encryption: ext.encryption || null,
+            routes: ext.routes
+                ? { path: ext.routes.path, handler: routeHandler }
+                : null,
+            bootstrap: bootstrapFn,
+        };
+    });
+
+    if (allErrors.length > 0) {
+        throw new Error(
+            `Invalid extension configuration:\n- ${allErrors.join('\n- ')}`
+        );
+    }
+
+    return normalized.filter(Boolean);
+}
+
+/**
+ * Get extension schema file paths from loaded extensions.
+ * @param {Array<Object>} extensions - Normalized extensions
+ * @returns {string[]} Array of absolute paths to .prisma schema files
+ */
+function getExtensionSchemaPaths(extensions) {
+    return extensions
+        .filter((ext) => ext.schema)
+        .map((ext) => ext.schema);
+}
+
+module.exports = {
+    loadExtensions,
+    validateExtension,
+    getExtensionSchemaPaths,
+};

package/extensions/index.js

@@ -0,0 +1,41 @@
+/**
+ * Frigg Extension System
+ *
+ * Extensions allow integration developers to extend Frigg Core with:
+ * - Custom Prisma models (schema composition)
+ * - Encrypted fields (encryption registry merge)
+ * - Admin API routes (route mounting)
+ * - Bootstrap lifecycle hooks (credential loading, etc.)
+ *
+ * @module @friggframework/core/extensions
+ */
+
+const { loadExtensions, validateExtension, getExtensionSchemaPaths } = require('./extension-loader');
+const { composeSchemas, extractModelBlocks, getSchemaFilePaths } = require('./schema-composer');
+const {
+    mountExtensionRoutes,
+    createExtensionRoutesRouter,
+} = require('./route-mounter');
+const { runExtensionBootstraps } = require('./bootstrap-runner');
+const { initializeApp, resetInitialization } = require('./initialize-app');
+
+module.exports = {
+    // Extension loading & validation
+    loadExtensions,
+    validateExtension,
+    getExtensionSchemaPaths,
+
+    // Schema composition
+    composeSchemas,
+    extractModelBlocks,
+    getSchemaFilePaths,
+
+    // Route mounting
+    mountExtensionRoutes,
+    createExtensionRoutesRouter,
+
+    // Bootstrap lifecycle
+    runExtensionBootstraps,
+    initializeApp,
+    resetInitialization,
+};

package/extensions/initialize-app.js

@@ -0,0 +1,123 @@
+/**
+ * Application Initialization with Extension Lifecycle
+ *
+ * Provides an async initialization function that runs extension bootstraps
+ * after database connection but before router creation. This is the integration
+ * point for providers (Lambda, Netlify) to hook into the extension lifecycle.
+ *
+ * Call `initializeApp()` during the async startup phase of your handler/function.
+ * It is safe to call multiple times — subsequent calls are no-ops.
+ *
+ * @example
+ * const { initializeApp } = require('@friggframework/core/extensions/initialize-app');
+ *
+ * // In a Lambda handler or Netlify function:
+ * await initializeApp();
+ * // Now extensions are bootstrapped and router can be created
+ */
+
+const { loadExtensions } = require('./extension-loader');
+const { runExtensionBootstraps } = require('./bootstrap-runner');
+
+let _initialized = false;
+let _initPromise = null;
+
+/**
+ * Initializes extensions by running bootstrap hooks.
+ *
+ * This function:
+ * 1. Loads the app definition
+ * 2. Loads and validates extensions
+ * 3. Runs extension bootstrap hooks in sequence
+ *
+ * Bootstrap hooks receive (prisma, appDefinition) and can:
+ * - Load credentials from database into integration Definition.env
+ * - Register services or middleware
+ * - Perform any one-time async initialization
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.appDefinition] - Override app definition (skips loadAppDefinition)
+ * @param {Object} [options.prisma] - Override Prisma client instance
+ * @param {boolean} [options.force=false] - Force re-initialization
+ * @returns {Promise<{extensions: Array}>} The loaded extensions
+ */
+async function initializeApp(options = {}) {
+    const { force = false } = options;
+
+    // Return cached promise if already initializing (prevent race conditions)
+    if (_initPromise && !force) {
+        return _initPromise;
+    }
+
+    if (_initialized && !force) {
+        return { extensions: [] };
+    }
+
+    _initPromise = _doInitialize(options);
+
+    try {
+        const result = await _initPromise;
+        _initialized = true;
+        return result;
+    } catch (error) {
+        _initPromise = null;
+        throw error;
+    }
+}
+
+async function _doInitialize(options = {}) {
+    let { appDefinition, prisma } = options;
+
+    // Load app definition if not provided
+    if (!appDefinition) {
+        try {
+            const { loadAppDefinition } = require('../handlers/app-definition-loader');
+            const loaded = loadAppDefinition();
+            appDefinition = loaded.appDefinition;
+        } catch {
+            // No app definition available — skip extension bootstrap
+            return { extensions: [] };
+        }
+    }
+
+    if (!appDefinition) {
+        return { extensions: [] };
+    }
+
+    // Load extensions
+    const extensions = loadExtensions(appDefinition);
+
+    if (extensions.length === 0) {
+        return { extensions };
+    }
+
+    // Get Prisma client if not provided
+    if (!prisma) {
+        try {
+            const db = require('../database/prisma');
+            prisma = db.prisma;
+        } catch {
+            // Prisma not available — skip bootstrap
+            console.warn('Prisma client not available, skipping extension bootstraps');
+            return { extensions };
+        }
+    }
+
+    // Run bootstrap hooks
+    await runExtensionBootstraps(extensions, { prisma, appDefinition });
+
+    return { extensions };
+}
+
+/**
+ * Reset initialization state (for testing).
+ */
+function resetInitialization() {
+    _initialized = false;
+    _initPromise = null;
+}
+
+module.exports = {
+    initializeApp,
+    resetInitialization,
+};