@friggframework/core 2.0.0-next.97 → 2.0.0-next.99

package/integrations/integration-base.js

@@ -11,6 +11,12 @@ const {
 const {
     UpdateIntegrationMessages,
 } = require('./use-cases/update-integration-messages');
+const {
+    PatchIntegrationConfig,
+} = require('./use-cases/patch-integration-config');
+const {
+    UpdateIntegrationConfig,
+} = require('./use-cases/update-integration-config');
 const { validateExtensionBinding } = require('./extension');
 
 const constantsToBeMigrated = {
@@ -43,6 +49,12 @@ class IntegrationBase {
     updateIntegrationMessages = new UpdateIntegrationMessages({
         integrationRepository: this.integrationRepository,
     });
+    patchIntegrationConfig = new PatchIntegrationConfig({
+        integrationRepository: this.integrationRepository,
+    });
+    updateIntegrationConfig = new UpdateIntegrationConfig({
+        integrationRepository: this.integrationRepository,
+    });
 
     static getOptionDetails() {
         const options = new Options({
@@ -266,41 +278,57 @@ class IntegrationBase {
         return modules;
     }
 
+    /**
+     * Check the current config against the required fields declared by
+     * `getConfigOptions()`. Config options use the react-jsonschema-form shape,
+     * so the required top-level keys live in `jsonSchema.required`. Records a
+     * warning for each missing field. Does not change integration status —
+     * the caller decides the consequence (see `onCreate`/`onUpdate`), the same
+     * separation `testAuth`/`reconcileAuthStatus` use for the auth axis.
+     * @returns {Promise<boolean>} True when a required field is missing.
+     */
     async validateConfig() {
-        const configOptions = await this.getConfigOptions();
-        const currentConfig = this.getConfig();
+        const { jsonSchema } = await this.getConfigOptions();
+        const currentConfig = this.getConfig() || {};
+        const requiredKeys = Array.isArray(jsonSchema?.required)
+            ? jsonSchema.required
+            : [];
         let needsConfig = false;
-        for (const option of configOptions) {
-            if (option.required) {
-                // For now, just make sure the key exists. We should add more dynamic/better validation later.
-                if (
-                    !Object.prototype.hasOwnProperty.call(
-                        currentConfig,
-                        option.key
-                    )
-                ) {
-                    needsConfig = true;
-                    await this.updateIntegrationMessages.execute(
-                        this.id,
-                        'warnings',
-                        'Config Validation Error',
-                        `Missing required field of ${option.label}`,
-                        Date.now()
-                    );
-                }
+        for (const key of requiredKeys) {
+            if (!Object.prototype.hasOwnProperty.call(currentConfig, key)) {
+                needsConfig = true;
+                const label = jsonSchema?.properties?.[key]?.title || key;
+                await this.updateIntegrationMessages.execute(
+                    this.id,
+                    'warnings',
+                    'Config Validation Error',
+                    `Missing required field of ${label}`,
+                    Date.now()
+                );
             }
         }
-        if (needsConfig) {
-            await this.updateIntegrationStatus.execute(this.id, 'NEEDS_CONFIG');
-        }
+        return needsConfig;
     }
 
+    /**
+     * Verify every module's credentials. Records a diagnostic error message
+     * per failing module and returns whether all passed. Does not directly
+     * change integration status — the caller decides the consequence (see
+     * reconcileAuthStatus), so a passive check and an active reconnect can
+     * react differently. (A module can still fire a credential-invalidated
+     * delegate that flips status via receiveNotification, independent of this
+     * return value.)
+     * @returns {Promise<boolean>} True when every module authenticated.
+     */
     async testAuth() {
         let didAuthPass = true;
 
         for (const module of Object.keys(this.constructor.Definition.modules)) {
             try {
-                await this[module].testAuth();
+                const authPassed = await this[module].testAuth();
+                if (!authPassed) {
+                    throw new Error(`testAuth returned false for module ${module}`);
+                }
             } catch {
                 didAuthPass = false;
                 await this.updateIntegrationMessages.execute(
@@ -309,15 +337,35 @@ class IntegrationBase {
                     'Authentication Error',
                     `There was an error with your ${this[
                         module
-                    ].constructor.getName()} Entity.
+                    ].getName()} Entity.
                 Please reconnect/re-authenticate, or reach out to Support for assistance.`,
                     Date.now()
                 );
             }
         }
 
-        if (!didAuthPass) {
-            await this.updateIntegrationStatus.execute(this.id, 'ERROR');
+        return didAuthPass;
+    }
+
+    /**
+     * Reconcile the auth-health axis (ERROR ↔ ENABLED) from a testAuth result.
+     * On success it never clears DISABLED — a user pause is not an auth-health
+     * state, so it is only lifted by a deliberate reconnect. On failure the
+     * integration is marked ERROR regardless of its prior status.
+     * @param {boolean} authPassed - The result of testAuth().
+     */
+    async reconcileAuthStatus(authPassed) {
+        if (!authPassed) {
+            console.log(
+                `[Frigg] Integration ${this.id} failed to authenticate`
+            );
+            await this.persistStatus('ERROR');
+        }
+        if (authPassed && this.status === 'ERROR') {
+            console.log(
+                `[Frigg] auth confirmed for integration ${this.id} — clearing ERROR → ENABLED`
+            );
+            await this.persistStatus('ENABLED');
         }
     }
 
@@ -344,12 +392,39 @@ class IntegrationBase {
     /**
      * CHILDREN CAN OVERRIDE THESE CONFIGURATION METHODS
      */
-    async onCreate({ integrationId }) {
-        await this.updateIntegrationStatus.execute(integrationId, 'ENABLED');
+    /**
+     * Default post-create lifecycle hook. The integration is born IN_CREATION;
+     * moved to NEEDS_CONFIG when validateConfig finds a required field
+     * missing, otherwise enabled. If this hook throws, the integration is
+     * left IN_CREATION — a visibly incomplete create rather than a healthy
+     * looking one. Children can override to run their own setup (and then own
+     * their status transition, calling `super.onCreate()` to keep this default).
+     */
+    async onCreate() {
+        const needsConfig = await this.validateConfig();
+        await this.persistStatus(needsConfig ? 'NEEDS_CONFIG' : 'ENABLED');
     }
 
+    /**
+     * Default post-update lifecycle hook: merges any submitted config in as a
+     * patch, then re-validates. A NEEDS_CONFIG integration moves to ENABLED
+     * once nothing required is missing — other statuses (DISABLED, ERROR,
+     * IN_CREATION, IN_DELETION) are left alone; a config edit shouldn't
+     * silently un-pause or auto-heal those. Children can override to run
+     * their own update logic.
+     * @param {Object} [params]
+     * @param {Object} [params.config] - Keys to merge into the existing config.
+     */
     async onUpdate(params) {
-        return this.validateConfig();
+        if (params?.config) {
+            await this.patchConfig(params.config);
+        }
+        const needsConfig = await this.validateConfig();
+        if (needsConfig) {
+            await this.persistStatus('NEEDS_CONFIG');
+        } else if (this.status === 'NEEDS_CONFIG') {
+            await this.persistStatus('ENABLED');
+        }
     }
 
     async onDelete(params) {}
@@ -500,6 +575,48 @@ class IntegrationBase {
         this.messages.warnings.push(warning);
     }
 
+    /**
+     * Persist a status change and keep the in-memory field in sync. The
+     * single place that couples both writes, so no caller can update the
+     * database while leaving `this.status` stale.
+     * @param {string} status - The new integration status.
+     */
+    async persistStatus(status) {
+        await this.updateIntegrationStatus.execute(this.id, status);
+        this.status = status;
+        console.log(`[Frigg] Integration ${this.id} status changed to ${status}`);
+    }
+
+    /**
+     * Merge a partial update into config and keep the in-memory field in
+     * sync with what was actually persisted — not a local `{...this.config,
+     * ...patch}` guess, which would silently drop keys a concurrent writer
+     * already landed. Throws if the merge fails.
+     * @param {Object} patch - Keys to merge into the existing config.
+     */
+    async patchConfig(patch) {
+        const updated = await this.patchIntegrationConfig.execute(
+            this.id,
+            patch
+        );
+        this.config = updated.config;
+        return this.config;
+    }
+
+    /**
+     * Replace config entirely and keep the in-memory field in sync. Keys
+     * omitted from the new config are deleted. Throws if the write fails.
+     * @param {Object} config - The new configuration object.
+     */
+    async updateConfig(config) {
+        const updated = await this.updateIntegrationConfig.execute(
+            this.id,
+            config
+        );
+        this.config = updated.config;
+        return this.config;
+    }
+
     isActive() {
         return this.status === 'ENABLED' || this.status === 'ACTIVE';
     }
@@ -655,7 +772,7 @@ class IntegrationBase {
      * Receives notifications from modules (the Delegate pattern) when
      * something integration-level needs attention. Today this catches the
      * `CREDENTIAL_INVALIDATED` event Module fires from `markCredentialsInvalid`
-     * and flips this integration's status to DISABLED so the queue worker
+     * and flips this integration's status to ERROR so the queue worker
      * stops processing further webhooks until the user re-authorizes.
      *
      * Modules are wired to this delegate in `_appendModules()`, which runs
@@ -677,8 +794,7 @@ class IntegrationBase {
             console.log(
                 `[Frigg] Module ${notifier?.name || '?'} reported invalid credentials for integration ${this.id} — marking ERROR`
             );
-            await this.updateIntegrationStatus.execute(this.id, 'ERROR');
-            this.status = 'ERROR';
+            await this.persistStatus('ERROR');
             return;
         }
 
@@ -687,8 +803,7 @@ class IntegrationBase {
             console.log(
                 `[Frigg] Module ${notifier?.name || '?'} reported valid credentials for integration ${this.id} — clearing ERROR → ENABLED`
             );
-            await this.updateIntegrationStatus.execute(this.id, 'ENABLED');
-            this.status = 'ENABLED';
+            await this.persistStatus('ENABLED');
         }
     }
 }

package/integrations/integration-router.js

@@ -468,7 +468,8 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             }
 
             const start = Date.now();
-            await instance.testAuth();
+            const authPassed = await instance.testAuth();
+            await instance.reconcileAuthStatus(authPassed);
             const errors = instance.record.messages?.errors?.filter(
                 ({ timestamp }) => timestamp >= start
             );

package/integrations/repositories/config-patch-shared.js

@@ -0,0 +1,43 @@
+/**
+ * Shared validation for IntegrationRepository.patchIntegrationConfig().
+ *
+ * A patch is an atomic shallow merge into Integration.config: every key in
+ * the patch is written, every other existing key is left untouched. This
+ * contract is enforced here, before any adapter emits a query, so a bug fix
+ * (or a tighter rule) fixes all three backends in one place.
+ *
+ * Keys may not contain '.' or start with '$' — both are reserved by the
+ * MongoDB/DocumentDB update-command syntax the mongo and documentdb adapters
+ * use to address `config.<key>` paths. A value of `null` is allowed and sets
+ * the key to null — the only way to clear a config field over the PATCH HTTP
+ * endpoint (it sets the value, it does not remove the key). `undefined` is
+ * rejected: it can't arrive over JSON and signals a programming error, not an
+ * intent. Removing a key entirely still requires a full replace via updateConfig.
+ */
+function validateConfigPatch(patch) {
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+        throw new Error('patchIntegrationConfig: patch must be a non-null object');
+    }
+
+    const keys = Object.keys(patch);
+    if (keys.length === 0) {
+        throw new Error(
+            'patchIntegrationConfig: patch must contain at least one key'
+        );
+    }
+
+    for (const key of keys) {
+        if (key.includes('.') || key.startsWith('$')) {
+            throw new Error(
+                `patchIntegrationConfig: patch key '${key}' cannot contain '.' or start with '$'`
+            );
+        }
+        if (patch[key] === undefined) {
+            throw new Error(
+                `patchIntegrationConfig: patch['${key}'] cannot be undefined`
+            );
+        }
+    }
+}
+
+module.exports = { validateConfigPatch };

package/integrations/repositories/integration-repository-documentdb.js

@@ -12,6 +12,7 @@ const {
 const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
+const { validateConfigPatch } = require('./config-patch-shared');
 
 class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
     constructor() {
@@ -124,7 +125,7 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
             userId: toObjectId(userId) || null,
             config,
             version: '0.0.0',
-            status: 'ENABLED',
+            status: 'IN_CREATION',
             entityIds: toObjectIdArray(entities),
             messages: { errors: [], warnings: [], info: [], logs: [] },
             errors: [],
@@ -190,6 +191,57 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
         return this._mapIntegration(updated);
     }
 
+    /**
+     * Atomically merge a patch into the existing config with a per-key
+     * $set (config.<k> for each patch key), then re-read to shape the
+     * return value — DocumentDB's raw update command doesn't return the
+     * post-update document directly.
+     *
+     * @param {string} integrationId - Integration ID
+     * @param {Object} patch - Keys to merge into the existing config
+     * @returns {Promise<Object>} Updated integration object
+     */
+    async patchIntegrationConfig(integrationId, patch) {
+        validateConfigPatch(patch);
+        const objectId = toObjectId(integrationId);
+        if (!objectId) {
+            throw new Error(`Integration with id ${integrationId} not found`);
+        }
+
+        const $set = { updatedAt: new Date() };
+        for (const [key, value] of Object.entries(patch)) {
+            $set[`config.${key}`] = value;
+        }
+
+        const result = await updateOne(
+            this.prisma,
+            'Integration',
+            { _id: objectId },
+            { $set }
+        );
+        if (result.writeErrors?.length) {
+            throw new Error(
+                `Failed to patch integration config: ${result.writeErrors[0].errmsg}`
+            );
+        }
+        if (!result.n) {
+            throw new Error(`Integration with id ${integrationId} not found`);
+        }
+
+        const updated = await findOne(this.prisma, 'Integration', { _id: objectId });
+        if (!updated) {
+            console.error('[IntegrationRepositoryDocumentDB] Integration not found after update', {
+                integrationId: fromObjectId(objectId),
+                patch,
+            });
+            throw new Error(
+                'Failed to update integration: Document not found after update. ' +
+                'This indicates a database consistency issue.'
+            );
+        }
+        return this._mapIntegration(updated);
+    }
+
     _mapIntegration(doc) {
         const messages = this._extractMessages(doc);
         return {
@@ -200,6 +252,7 @@ class IntegrationRepositoryDocumentDB extends IntegrationRepositoryInterface {
             version: doc?.version ?? null,
             status: doc?.status ?? null,
             messages,
+            createdAt: doc?.createdAt ?? null,
         };
     }
 

package/integrations/repositories/integration-repository-interface.js

@@ -123,6 +123,21 @@ class IntegrationRepositoryInterface {
         throw new Error('Method updateIntegrationConfig must be implemented by subclass');
     }
 
+    /**
+     * Atomically merge a partial update into an integration's config. Keys
+     * not present in the patch are left untouched; concurrent patches with
+     * disjoint keys must both persist. Patch values may not be null or
+     * undefined — key deletion is only supported via updateIntegrationConfig.
+     *
+     * @param {string|number} integrationId - Integration ID
+     * @param {Object} patch - Keys to merge into the existing config
+     * @returns {Promise<Object>} Updated integration object
+     * @abstract
+     */
+    async patchIntegrationConfig(integrationId, patch) {
+        throw new Error('Method patchIntegrationConfig must be implemented by subclass');
+    }
+
     /**
      * Find all integrations whose entity set includes the given entity ID.
      *

package/integrations/repositories/integration-repository-mongo.js

@@ -2,6 +2,7 @@ const { prisma } = require('../../database/prisma');
 const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
+const { validateConfigPatch } = require('./config-patch-shared');
 
 /**
  * MongoDB Integration Repository Adapter
@@ -48,6 +49,7 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
             version: integration.version,
             status: integration.status,
             messages: integration.messages,
+            createdAt: integration.createdAt,
         }));
     }
 
@@ -325,6 +327,52 @@ class IntegrationRepositoryMongo extends IntegrationRepositoryInterface {
             messages: integration.messages,
         };
     }
+
+    /**
+     * Atomically merge a patch into the existing config via findAndModify,
+     * so the write and the post-write read happen in one server-side round
+     * trip with no JS-side read-modify-write to race on. entityIds is a
+     * scalar array directly on the Integration document in Mongo, so the
+     * raw document already carries everything needed to shape the return
+     * value — no follow-up findUnique.
+     *
+     * @param {string} integrationId - Integration ID
+     * @param {Object} patch - Keys to merge into the existing config
+     * @returns {Promise<Object>} Updated integration object
+     */
+    async patchIntegrationConfig(integrationId, patch) {
+        validateConfigPatch(patch);
+
+        const $set = {};
+        for (const [key, value] of Object.entries(patch)) {
+            $set[`config.${key}`] = value;
+        }
+        $set.updatedAt = new Date();
+
+        const result = await this.prisma.$runCommandRaw({
+            findAndModify: 'Integration',
+            query: { _id: { $oid: integrationId } },
+            update: { $set },
+            new: true,
+        });
+
+        const doc = result && result.value;
+        if (!doc) {
+            throw new Error(`Integration with id ${integrationId} not found`);
+        }
+
+        return {
+            id: doc._id.$oid ?? doc._id,
+            entitiesIds: (doc.entityIds || []).map(
+                (entityId) => entityId.$oid ?? entityId
+            ),
+            userId: doc.userId?.$oid ?? doc.userId ?? null,
+            config: doc.config,
+            version: doc.version,
+            status: doc.status,
+            messages: doc.messages,
+        };
+    }
 }
 
 module.exports = { IntegrationRepositoryMongo };

package/integrations/repositories/integration-repository-postgres.js

@@ -2,6 +2,7 @@ const { prisma } = require('../../database/prisma');
 const {
     IntegrationRepositoryInterface,
 } = require('./integration-repository-interface');
+const { validateConfigPatch } = require('./config-patch-shared');
 
 /**
  * PostgreSQL Integration Repository Adapter
@@ -84,6 +85,7 @@ class IntegrationRepositoryPostgres extends IntegrationRepositoryInterface {
                 version: converted.version,
                 status: converted.status,
                 messages: converted.messages,
+                createdAt: converted.createdAt,
             };
         });
     }
@@ -348,6 +350,32 @@ class IntegrationRepositoryPostgres extends IntegrationRepositoryInterface {
         };
     }
 
+    /**
+     * Atomically merge a patch into the existing config with a single
+     * jsonb concatenation — the database does the merge, so there is no
+     * JS-side read-modify-write for concurrent callers to race on.
+     *
+     * @param {string} integrationId - Integration ID (string from application layer)
+     * @param {Object} patch - Keys to merge into the existing config
+     * @returns {Promise<Object>} Updated integration object with string IDs
+     */
+    async patchIntegrationConfig(integrationId, patch) {
+        validateConfigPatch(patch);
+
+        const intId = this._convertId(integrationId);
+        const affectedCount = await this.prisma.$executeRawUnsafe(
+            'UPDATE "Integration" SET "config" = COALESCE("config", \'{}\'::jsonb) || $1::jsonb, "updatedAt" = NOW() WHERE "id" = $2',
+            JSON.stringify(patch),
+            intId
+        );
+
+        if (!affectedCount) {
+            throw new Error(`Integration with id ${integrationId} not found`);
+        }
+
+        return this.findIntegrationById(integrationId);
+    }
+
     /**
      * Find all integrations whose entity set includes the given entity ID.
      *

package/integrations/tests/doubles/dummy-integration-class.js

@@ -32,6 +32,7 @@ class DummyIntegration extends IntegrationBase {
     constructor(params) {
         super(params);
         this.sendSpy = jest.fn();
+        this.testAuthSpy = jest.fn();
         this.eventCallHistory = [];
         this.events = {};
 
@@ -59,6 +60,9 @@ class DummyIntegration extends IntegrationBase {
         if (event === 'ON_UPDATE') {
             await this.onUpdate(data);
         }
+        if (event === 'ON_DELETE') {
+            await this.onDelete(data);
+        }
         return { event, data };
     }
 
@@ -66,6 +70,10 @@ class DummyIntegration extends IntegrationBase {
         return;
     }
 
+    async testAuth() {
+        this.testAuthSpy();
+    }
+
     async onCreate({ integrationId }) {
         return;
     }

package/integrations/tests/doubles/test-integration-repository.js

@@ -1,4 +1,5 @@
 const { v4: uuid } = require('uuid');
+const { validateConfigPatch } = require('../../repositories/config-patch-shared');
 
 class TestIntegrationRepository {
     constructor() {
@@ -15,8 +16,9 @@ class TestIntegrationRepository {
             userId: userId,
             config,
             version: '0.0.0',
-            status: 'NEW',
+            status: 'IN_CREATION',
             messages: {},
+            createdAt: new Date(),
         };
         this.store.set(id, record);
         this.operationHistory.push({ operation: 'create', id, userId, config });
@@ -72,6 +74,9 @@ class TestIntegrationRepository {
     }
 
     async updateIntegrationConfig(id, config) {
+        if (config === null || config === undefined) {
+            throw new Error('Config parameter is required');
+        }
         const rec = this.store.get(id);
         if (!rec) {
             this.operationHistory.push({ operation: 'updateConfig', id, success: false });
@@ -82,6 +87,24 @@ class TestIntegrationRepository {
         return rec;
     }
 
+    async patchIntegrationConfig(id, patch) {
+        validateConfigPatch(patch);
+        if (!this.store.has(id)) {
+            this.operationHistory.push({ operation: 'patchConfig', id, success: false });
+            throw new Error(`Integration with id ${id} not found`);
+        }
+        // Simulates the DB round trip real adapters make: the merge reads
+        // the record fresh at write time rather than off a snapshot taken
+        // before the await, so concurrent patches to the same id can't lose
+        // each other's keys — same guarantee as `config || $1::jsonb` in
+        // postgres or a mongo/documentdb findAndModify.
+        await Promise.resolve();
+        const rec = this.store.get(id);
+        rec.config = { ...rec.config, ...patch };
+        this.operationHistory.push({ operation: 'patchConfig', id, success: true });
+        return rec;
+    }
+
     async deleteIntegrationById(id) {
         const existed = this.store.has(id);
         const result = this.store.delete(id);