@friggframework/core 2.0.0--canary.5ff5209.0 → 2.0.0--canary.590.094a71b.0

package/integrations/EXTENSIONS.md

@@ -0,0 +1,172 @@
+# Integration Extensions Quick Start
+
+Tier 3 **Integration Extensions** let an API module ship reusable handler bundles — receiver routes, event handlers, queues, workers — that an integration consumes declaratively via `Definition.extensions`. See [ADR-EXTENSIONS](../../../docs/architecture/ADR-EXTENSIONS.md) for the full taxonomy.
+
+## When to use this vs `Definition.webhooks: true`
+
+| Use `webhooks: true` ([WEBHOOK-QUICKSTART](./WEBHOOK-QUICKSTART.md)) | Use `extensions: {...}` |
+|---|---|
+| Per-account webhooks scoped to one integration record | App-level webhooks fanned out to many account records by external ID lookup |
+| You'll write the receiver, signature check, and queue dispatch yourself | The API module ships the receiver, signature check, and queue dispatch already |
+| One pattern, one endpoint | Multiple bundles (webhooks + CRM cards + timeline) declared together |
+
+## Step 1: Bind the extension on your Integration's Definition
+
+```javascript
+const hubspot = require('@friggframework/api-module-hubspot');
+
+class HubSpotIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'hubspot',
+        version: '1.0.0',
+        modules: { hubspot: { definition: hubspot.Definition } },
+        extensions: {
+            hubspotWebhooks: {
+                extension: hubspot.extensions.webhooks,
+                handlers: { HUBSPOT_WEBHOOK: 'onHubSpotEvent' },
+            },
+        },
+    };
+
+    async onHubSpotEvent({ data }) {
+        // pure business logic — signature verification, portalId lookup,
+        // and queue dispatch are all done by the extension's default handlers
+        const { subscriptionType, objectId } = data.body;
+        if (subscriptionType === 'contact.creation') {
+            await this.upsertContact(objectId);
+        }
+    }
+}
+```
+
+The binding key (`hubspotWebhooks`) is your local name. The extension reference (`hubspot.extensions.webhooks`) is whatever the API module exports.
+
+## Step 2: Deploy
+
+The framework auto-mounts each extension's routes at the integration's base path. Boot logs show:
+
+```
+│ Configuring routes for hubspot Integration:
+│ POST /api/hubspot-integration/webhooks  (extension: hubspot-webhooks)
+│
+```
+
+Hit that URL and the bound method (`onHubSpotEvent`) fires on the resolved per-account integration instance.
+
+## How handler binding works
+
+Each binding can map extension event names to method names on your integration:
+
+```javascript
+extensions: {
+    hubspotWebhooks: {
+        extension: hubspot.extensions.webhooks,
+        handlers: {
+            HUBSPOT_WEBHOOK: 'onHubSpotEvent',          // method on `this`
+        },
+    },
+},
+```
+
+Resolution priority per event:
+
+1. `binding.handlers[eventName]` → resolves to `this[methodName]`, bound to the instance
+2. Extension's own default handler from `extension.events[eventName].handler`, bound to the instance
+3. Otherwise → `initialize()` throws with a message naming the integration, binding, and event
+
+Strings (not function refs) are intentional: it dodges the `this`-in-static-Definition bootstrapping problem and centralizes binding inside the framework. The framework resolves the method against the live integration instance at startup.
+
+## Event-name conflicts (and binding the same extension twice)
+
+If two bindings in your integration's `extensions` map declare the same event name, the framework **throws at `initialize()`** with a clear conflict error — no silent first/last-writer pick, no surprise routing. The fix is to use distinct event names per binding.
+
+This means **binding the same extension twice only works if the extension itself defines disjoint event sets per use-case** (rare). For the common "two webhooks, two handlers" pattern, an API module should ship two distinct extensions instead — for example `hubspot.extensions.webhooks` and `hubspot.extensions.sandboxWebhooks`, each with its own event names.
+
+Subclass overrides via `this.events[eventName]` (set in the constructor) take precedence over extension-declared events. If a binding tried to wire a handler that's now shadowed, the framework logs a warning naming the integration, binding, and ignored method.
+
+Route path conflicts (two extensions declaring the same `method + path`, or an extension colliding with a `Definition.routes` entry) also throw at boot.
+
+## Authoring an extension (for API module authors)
+
+An extension bundle is a plain object exported from your api-module:
+
+```javascript
+// @friggframework/api-module-hubspot/extensions/webhooks/index.js
+module.exports = {
+    name: 'hubspot-webhooks',
+    routes: [
+        { path: '/webhooks', method: 'POST', event: 'HUBSPOT_WEBHOOK_RECEIVED' },
+    ],
+    events: {
+        HUBSPOT_WEBHOOK_RECEIVED: {
+            type: 'LIFE_CYCLE_EVENT',
+            handler: async function ({ req, res }) {
+                // verify signature, look up integration by portalId, queue
+                await verifyHubSpotSignature(req);
+                for (const evt of req.body) {
+                    const integrationId = await this.findIntegrationByPortalId(
+                        evt.portalId,
+                        'hubspot'
+                    );
+                    if (!integrationId) continue;
+                    await this.queueWebhook({
+                        integrationId,
+                        body: evt,
+                        event: 'HUBSPOT_WEBHOOK',
+                    });
+                }
+                res.status(200).json({ received: req.body.length });
+            },
+        },
+        HUBSPOT_WEBHOOK: {
+            type: 'LIFE_CYCLE_EVENT',
+            handler: async function ({ data }) {
+                // default no-op; integrations override via binding.handlers
+            },
+        },
+    },
+};
+```
+
+Then expose it on your api-module's index:
+
+```javascript
+// @friggframework/api-module-hubspot/index.js
+module.exports = {
+    Definition: require('./api-module-definition'),
+    extensions: {
+        webhooks: require('./extensions/webhooks'),
+        crmCards: require('./extensions/crm-cards'),
+        timeline: require('./extensions/timeline'),
+    },
+};
+```
+
+## Contract enforced by the framework
+
+At `initialize()`, the framework validates each binding:
+
+- `extension` must be an object with a `name`
+- `extension.events` must be an object keyed by event name (if present)
+- `extension.routes` must be an array (if present)
+- Every route's `event` must exist in `extension.events`
+- Every route's `method` must be a known HTTP verb
+- For each event, either `binding.handlers[eventName]` resolves to an instance method, OR `extension.events[eventName].handler` is a function
+
+Validation failures throw at boot with a message identifying the integration, binding, and field.
+
+## Reverse-lookup helper
+
+For app-level webhooks (HubSpot, Slack, etc.) where one URL serves many accounts, extension default handlers commonly need to resolve the inbound external ID (portalId, team_id, workspace_id) to a Frigg integration record. Use the inherited helper:
+
+```javascript
+const integrationId = await this.findIntegrationByPortalId(externalId, 'hubspot');
+```
+
+Returns the integration ID (or `null`) for the first matching entity. The second arg disambiguates when multiple modules in the same app could carry colliding external IDs.
+
+## See also
+
+- [ADR-EXTENSIONS](../../../docs/architecture/ADR-EXTENSIONS.md) — the three-tier taxonomy (Core Plugins / Application Extensions / Integration Extensions)
+- [WEBHOOK-QUICKSTART](./WEBHOOK-QUICKSTART.md) — per-account `Definition.webhooks: true` pattern
+- `extension.js` — the validation + flattening helpers (`validateExtensionBinding`, `getExtensionRoutes`, `getExtensionWorkers`)

package/integrations/extension.js

@@ -0,0 +1,233 @@
+/**
+ * Tier 3 — Integration Extensions
+ *
+ * An Integration Extension is a reusable bundle exported by an API module (or a
+ * shared extensions library) that contributes routes, events, queues, and workers
+ * to a consumer integration. The integration binds the bundle declaratively via
+ * `static Definition.extensions` and the framework merges its contributions into
+ * the integration's effective definition at instantiation time.
+ *
+ * Extension bundle shape:
+ *
+ *     {
+ *         name: string,                       // required, unique within the API module
+ *         routes?: Array<{                    // optional, mounted alongside Definition.routes
+ *             path: string,
+ *             method: 'GET' | 'POST' | 'PUT' | 'DELETE' | ...,
+ *             event: string                   // must exist in `events` below
+ *         }>,
+ *         events?: {                          // optional, merged into instance.events
+ *             [eventName]: {
+ *                 type?: string,              // e.g. 'LIFE_CYCLE_EVENT'
+ *                 handler: Function           // default handler; integration may override per-binding
+ *             }
+ *         },
+ *         queues?: Array<Object>,             // reserved — Phase 2
+ *         workers?: Array<Object>             // reserved — Phase 2
+ *     }
+ *
+ * Integration binding shape (on the integration's static Definition.extensions):
+ *
+ *     extensions: {
+ *         hubspotWebhooks: {                  // local binding name (developer's choice)
+ *             extension: hubspot.extensions.webhooks,
+ *             handlers: {                     // optional override map
+ *                 HUBSPOT_WEBHOOK: 'onHubSpotEvent'  // event → method name on the integration
+ *             }
+ *         }
+ *     }
+ *
+ * The same extension may be bound multiple times under different local names; the
+ * binding key is the developer-controlled local handle, not a global registry key.
+ */
+
+const KNOWN_HTTP_METHODS = new Set([
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'options',
+    'head',
+]);
+
+/**
+ * Validate the shape of an extension bundle and its binding.
+ *
+ * @param {Object} extension - The extension bundle to validate.
+ * @param {string} bindingName - The local binding key (for error context).
+ * @param {string} integrationName - The integration's Definition.name (for error context).
+ * @param {Object} [binding] - Optional full binding object; if provided, also validates binding.handlers.
+ * @throws {Error} If the extension is missing required fields or is internally inconsistent.
+ */
+function validateExtensionBinding(extension, bindingName, integrationName, binding) {
+    const ctx = `Integration "${integrationName}" extension binding "${bindingName}"`;
+
+    if (!extension || typeof extension !== 'object') {
+        throw new Error(`${ctx}: extension must be an object`);
+    }
+    if (!extension.name || typeof extension.name !== 'string') {
+        throw new Error(`${ctx}: extension is missing required "name" field`);
+    }
+
+    const events = extension.events || {};
+    if (typeof events !== 'object' || Array.isArray(events)) {
+        throw new Error(
+            `${ctx}: extension "${extension.name}" "events" must be an object keyed by event name`
+        );
+    }
+
+    // Validate each event's shape — handler, when present, must be a function.
+    for (const [eventName, eventDef] of Object.entries(events)) {
+        if (!eventDef || typeof eventDef !== 'object') {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" event "${eventName}" must be an object`
+            );
+        }
+        if (
+            eventDef.handler !== undefined &&
+            typeof eventDef.handler !== 'function'
+        ) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" event "${eventName}" "handler" must be a function`
+            );
+        }
+    }
+
+    const routes = extension.routes || [];
+    if (!Array.isArray(routes)) {
+        throw new Error(
+            `${ctx}: extension "${extension.name}" "routes" must be an array`
+        );
+    }
+
+    for (const route of routes) {
+        if (!route || typeof route !== 'object') {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" has a malformed route entry`
+            );
+        }
+        if (typeof route.path !== 'string' || route.path.length === 0) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route is missing "path"`
+            );
+        }
+        if (typeof route.method !== 'string') {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route "${route.path}" is missing "method"`
+            );
+        }
+        if (!KNOWN_HTTP_METHODS.has(route.method.toLowerCase())) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route "${route.path}" has unsupported method "${route.method}"`
+            );
+        }
+        if (typeof route.event !== 'string' || route.event.length === 0) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route "${route.path}" is missing "event"`
+            );
+        }
+        if (!Object.prototype.hasOwnProperty.call(events, route.event)) {
+            throw new Error(
+                `${ctx}: extension "${extension.name}" route "${route.path}" references event "${route.event}" which is not declared in extension.events`
+            );
+        }
+    }
+
+    // Validate binding.handlers if a binding was supplied.
+    if (binding && binding.handlers !== undefined) {
+        if (
+            typeof binding.handlers !== 'object' ||
+            Array.isArray(binding.handlers) ||
+            binding.handlers === null
+        ) {
+            throw new Error(
+                `${ctx}: "handlers" must be an object keyed by event name`
+            );
+        }
+        for (const [eventName, methodRef] of Object.entries(binding.handlers)) {
+            if (typeof methodRef !== 'string' || methodRef.length === 0) {
+                throw new Error(
+                    `${ctx}: handler for event "${eventName}" must be a non-empty method name string (got ${typeof methodRef})`
+                );
+            }
+            if (!Object.prototype.hasOwnProperty.call(events, eventName)) {
+                throw new Error(
+                    `${ctx}: binding.handlers references event "${eventName}" which is not declared in extension "${extension.name}".events — check for typos`
+                );
+            }
+        }
+    }
+}
+
+/**
+ * Get the flattened list of extension-contributed routes for an integration class.
+ * Each route carries the binding name and extension name alongside the route fields
+ * so the router builder can produce useful boot-time logs.
+ *
+ * @param {Function} IntegrationClass - A class extending IntegrationBase.
+ * @returns {Array<{bindingName: string, extensionName: string, path: string, method: string, event: string}>}
+ */
+function getExtensionRoutes(IntegrationClass) {
+    const extensions = IntegrationClass?.Definition?.extensions || {};
+    const integrationName = IntegrationClass?.Definition?.name;
+    const flat = [];
+    for (const [bindingName, binding] of Object.entries(extensions)) {
+        // Fail fast: surface bad bindings at boot, not at first request.
+        // Mirrors the validation that _mergeExtensions does at instance time.
+        validateExtensionBinding(
+            binding && binding.extension,
+            bindingName,
+            integrationName,
+            binding
+        );
+        const routes = binding.extension.routes || [];
+        for (const route of routes) {
+            flat.push({
+                bindingName,
+                extensionName: binding.extension.name,
+                path: route.path,
+                method: route.method,
+                event: route.event,
+            });
+        }
+    }
+    return flat;
+}
+
+/**
+ * Get the flattened list of extension-contributed workers for an integration class.
+ * Reserved for Phase 2 — today the per-integration QueueWorker handles all events
+ * by name, so extension-contributed events flow through it without a dedicated worker.
+ *
+ * @param {Function} IntegrationClass - A class extending IntegrationBase.
+ * @returns {Array<Object>}
+ */
+function getExtensionWorkers(IntegrationClass) {
+    const extensions = IntegrationClass?.Definition?.extensions || {};
+    const integrationName = IntegrationClass?.Definition?.name;
+    const flat = [];
+    for (const [bindingName, binding] of Object.entries(extensions)) {
+        validateExtensionBinding(
+            binding && binding.extension,
+            bindingName,
+            integrationName,
+            binding
+        );
+        const workers = binding.extension.workers || [];
+        for (const worker of workers) {
+            flat.push({
+                bindingName,
+                extensionName: binding.extension.name,
+                ...worker,
+            });
+        }
+    }
+    return flat;
+}
+
+module.exports = {
+    validateExtensionBinding,
+    getExtensionRoutes,
+    getExtensionWorkers,
+};

package/integrations/index.js

@@ -10,6 +10,11 @@ const {
 const {
     LoadIntegrationContextUseCase,
 } = require('./use-cases/load-integration-context');
+const {
+    validateExtensionBinding,
+    getExtensionRoutes,
+    getExtensionWorkers,
+} = require('./extension');
 
 module.exports = {
     IntegrationBase,
@@ -18,4 +23,7 @@ module.exports = {
     checkRequiredParams,
     getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
+    validateExtensionBinding,
+    getExtensionRoutes,
+    getExtensionWorkers,
 };

package/integrations/integration-base.js

@@ -11,6 +11,7 @@ const {
 const {
     UpdateIntegrationMessages,
 } = require('./use-cases/update-integration-messages');
+const { validateExtensionBinding } = require('./extension');
 
 const constantsToBeMigrated = {
     defaultEvents: {
@@ -60,6 +61,9 @@ class IntegrationBase {
         supportedVersions: [], // Eventually usable for deprecation and future test version purposes
 
         modules: {},
+        // Tier 3 Integration Extensions — see packages/core/integrations/EXTENSIONS.md
+        // Shape: { [bindingName]: { extension, handlers?: { [eventName]: methodName } } }
+        extensions: {},
         display: {
             name: 'Integration Name',
             logo: '',
@@ -504,6 +508,158 @@ class IntegrationBase {
         };
     }
 
+    /**
+     * Merge Tier 3 Integration Extension events into `this.events`.
+     *
+     * For each binding declared on `static Definition.extensions`, this method:
+     *   1. Validates the extension bundle shape and binding handlers
+     *   2. For each event the extension declares, resolves the handler in priority order:
+     *      a. Subclass-defined `this.events[eventName]` (set in the constructor) — wins; if a
+     *         binding tried to override that event with `handlers`, we log a warning so the
+     *         author knows their override is shadowed.
+     *      b. A method-name string in `binding.handlers[eventName]` → method on this instance
+     *      c. The extension's own default `handler` function
+     *      d. Otherwise throw — neither side provided a handler
+     *   3. Binds the resolved function to this instance and writes it to `this.events[eventName]`
+     *
+     * Two bindings declaring the same event throw a deterministic conflict error — silent
+     * "first/last writer wins" makes routing bugs nearly impossible to diagnose.
+     *
+     * @private
+     */
+    _mergeExtensions() {
+        const extensions = this.constructor.Definition?.extensions || {};
+        const integrationName = this.constructor.Definition?.name;
+        // Tracks which event names have been claimed by an extension binding during
+        // this merge — distinct from subclass-defined events on `this.events`.
+        const mergedByExtension = new Map();
+
+        for (const [bindingName, binding] of Object.entries(extensions)) {
+            if (!binding || typeof binding !== 'object') {
+                throw new Error(
+                    `Integration "${integrationName}" extension binding "${bindingName}" must be an object`
+                );
+            }
+            const { extension, handlers = {} } = binding;
+            validateExtensionBinding(
+                extension,
+                bindingName,
+                integrationName,
+                binding
+            );
+
+            const extEvents = extension.events || {};
+            for (const [eventName, eventDef] of Object.entries(extEvents)) {
+                // Conflict detection: another extension binding already claimed this event name.
+                if (mergedByExtension.has(eventName)) {
+                    const prev = mergedByExtension.get(eventName);
+                    throw new Error(
+                        `Integration "${integrationName}" extension event conflict: ` +
+                            `event "${eventName}" is declared by both binding "${prev}" and binding "${bindingName}" — ` +
+                            `use distinct event names per binding or omit duplicates`
+                    );
+                }
+
+                // Subclass shadowing: if the subclass set this.events[eventName] before initialize(),
+                // it wins. Warn if the binding tried to wire an override that's now ignored.
+                if (this.events[eventName]) {
+                    if (typeof handlers[eventName] === 'string') {
+                        console.warn(
+                            `[Frigg] Integration "${integrationName}" binding "${bindingName}": ` +
+                                `handler "${handlers[eventName]}" for event "${eventName}" is ignored because ` +
+                                `this.events["${eventName}"] was already set (subclass constructor or earlier merge)`
+                        );
+                    }
+                    continue;
+                }
+
+                let fn;
+                const override = handlers[eventName];
+                if (typeof override === 'string') {
+                    if (typeof this[override] !== 'function') {
+                        throw new Error(
+                            `Integration "${integrationName}" extension binding "${bindingName}": handler method "${override}" not found on instance`
+                        );
+                    }
+                    fn = this[override];
+                } else if (typeof eventDef.handler === 'function') {
+                    fn = eventDef.handler;
+                } else {
+                    throw new Error(
+                        `Extension "${extension.name}" event "${eventName}" has no default handler and binding "${bindingName}" did not provide one`
+                    );
+                }
+
+                this.events[eventName] = {
+                    type: eventDef.type,
+                    handler: fn.bind(this),
+                };
+                mergedByExtension.set(eventName, bindingName);
+            }
+        }
+    }
+
+    /**
+     * Reverse-lookup helper: find an integration ID by a module entity's externalId.
+     *
+     * Used by extension default handlers (e.g. HubSpot webhook receiver) that need
+     * to resolve an incoming app-level event to a specific per-account integration
+     * record. The external ID is provided by the upstream system (HubSpot portalId,
+     * Slack team_id, etc.) — this helper looks up which Frigg integration owns the
+     * entity carrying that external ID.
+     *
+     * Throws on ambiguous resolution. A single externalId mapping to multiple
+     * integrations is a cross-tenant routing risk (e.g. two users connecting the
+     * same HubSpot portal): we refuse to silently pick `[0]`. Callers that
+     * legitimately need to fan out to multiple integrations should use the
+     * lower-level repository call directly.
+     *
+     * @param {string} externalId - The provider's stable identifier for the account/portal/workspace.
+     * @param {string} [moduleName] - Optional module name to disambiguate when multiple modules in the same app could carry colliding externalIds.
+     * @returns {Promise<string|null>} The integration ID, or null if no match.
+     * @throws {Error} If more than one integration is found for the (externalId, moduleName) tuple.
+     */
+    async findIntegrationByPortalId(externalId, moduleName) {
+        if (!externalId) return null;
+        const {
+            createModuleRepository,
+        } = require('../modules/repositories/module-repository-factory');
+        const moduleRepository = createModuleRepository();
+
+        const filter = { externalId: String(externalId) };
+        if (moduleName) filter.moduleName = moduleName;
+
+        const entity = await moduleRepository.findEntity(filter);
+        if (!entity) {
+            console.log(
+                `[Frigg] findIntegrationByPortalId: no entity for externalId=${externalId}${
+                    moduleName ? ` moduleName=${moduleName}` : ''
+                }`
+            );
+            return null;
+        }
+
+        const integrations =
+            await this.integrationRepository.findIntegrationsByEntityId(
+                entity.id
+            );
+        if (!integrations || integrations.length === 0) {
+            console.log(
+                `[Frigg] findIntegrationByPortalId: entity ${entity.id} has no owning integrations (orphan)`
+            );
+            return null;
+        }
+        if (integrations.length > 1) {
+            const ids = integrations.map((i) => i.id).join(', ');
+            throw new Error(
+                `findIntegrationByPortalId: ambiguous resolution — externalId=${externalId}` +
+                    `${moduleName ? ` moduleName=${moduleName}` : ''} maps to ${integrations.length} integrations [${ids}]. ` +
+                    `Refusing to pick one to avoid cross-tenant routing.`
+            );
+        }
+        return integrations[0].id;
+    }
+
     async initialize() {
         try {
             const additionalUserActions = await this.loadDynamicUserActions();
@@ -512,6 +668,7 @@ class IntegrationBase {
             this.addError(e);
         }
 
+        this._mergeExtensions();
         this.registerEventHandlers();
     }
 
@@ -560,13 +717,25 @@ class IntegrationBase {
      * @returns {Promise<void>}
      */
     async receiveNotification(notifier, delegateString, object = null) {
-        if (delegateString !== 'CREDENTIAL_INVALIDATED') return;
         if (!this.id) return;
-        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';
+
+        if (delegateString === 'CREDENTIAL_INVALIDATED') {
+            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';
+            return;
+        }
+
+        if (delegateString === 'CREDENTIAL_VALIDATED') {
+            if (this.status !== 'ERROR') return;
+            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';
+        }
     }
 }
 

package/integrations/integration-router.js

@@ -531,13 +531,33 @@ function setEntityRoutes(router, authenticateUser, useCases) {
                 'data',
             ]);
 
-            const entityDetails = await processAuthorizationCallback.execute(
-                userId,
-                params.entityType,
-                params.data
+            const dataKeys =
+                params.data && typeof params.data === 'object'
+                    ? Object.keys(params.data)
+                    : [];
+            console.log(
+                `[Frigg] POST /api/authorize userId=${userId} entityType=${params.entityType} dataKeys=${JSON.stringify(dataKeys)}`
             );
 
-            res.json(entityDetails);
+            try {
+                const entityDetails =
+                    await processAuthorizationCallback.execute(
+                        userId,
+                        params.entityType,
+                        params.data
+                    );
+
+                console.log(
+                    `[Frigg] POST /api/authorize success userId=${userId} entityType=${params.entityType} credentialId=${entityDetails?.credential_id} entityId=${entityDetails?.entity_id}`
+                );
+
+                res.json(entityDetails);
+            } catch (err) {
+                console.error(
+                    `[Frigg] POST /api/authorize failed userId=${userId} entityType=${params.entityType} error=${err?.message || err}`
+                );
+                throw err;
+            }
         })
     );