@friggframework/core 2.0.0--canary.690.08cd07e.0 → 2.0.0--canary.693.d8859c2.0

package/integrations/data-defined/webhooks.js

@@ -0,0 +1,119 @@
+/**
+ * Turning a provider's webhook delivery into the module events a definition listens for. Pure; no I/O.
+ *
+ * Providers disagree about everything: where the topic is (a body field, a header, two fields combined), whether one
+ * POST carries one event or a batch (HubSpot sends an array, QuickBooks nests entities inside notifications), which
+ * account it is about, and whether the first request is a handshake to answer synchronously (Slack url_verification,
+ * Asana X-Hook-Secret). A manifest says so in its `webhook` block, with the same template expressions definitions
+ * use, so none of it is code:
+ *
+ *   "webhook": {
+ *     "scope": "app",                                   // one URL for every account ("installation": one per install)
+ *     "batch": "body",                                  // path to the array of events; [outer, inner] for two levels
+ *     "topic": "{{item.subscriptionType}}",             // the provider's topic; a list tries each until one is non-empty
+ *     "eventId": "{{item.eventId}}",                    // dedupe id
+ *     "account": "{{item.portalId}}",                   // the connected account (entity externalId) the event is about
+ *     "verify": "verifyWebhookSignature",               // optional Api method: ({ headers, body, query }) -> boolean
+ *     "handshake": { "when": "...", "status": 200, "headers": {...}, "body": {...} },
+ *     "unwrap": "payload"                               // a form-encoded field holding the JSON body (Slack interactivity)
+ *   }
+ *
+ * and each event says which provider topic it is (`match`, default: the event key) and optionally a condition on the
+ * record (`when`): a phone module reports a missed call as call.completed with status missed.
+ *
+ * Template context: { body, headers, query, item, parent }. `item` is the event (the body itself when there is no
+ * batch); `parent` is the outer item of a two-level batch (a QuickBooks notification, which carries the realmId).
+ */
+const { resolve, evaluate, getPath } = require('./expressions');
+
+const list = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+const str = (v) => (v == null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v));
+
+/** The first template in `tpls` that renders to a non-empty string. */
+function renderFirst(tpls, ctx) {
+    for (const t of list(tpls)) {
+        const v = str(resolve(t, ctx)).trim();
+        if (v) return v;
+    }
+    return '';
+}
+
+/** Lower-case header names, as Express and Lambda deliver them, so manifests can always write headers.x-shopify-topic. */
+function normaliseHeaders(headers = {}) {
+    return Object.fromEntries(Object.entries(headers || {}).map(([k, v]) => [k.toLowerCase(), Array.isArray(v) ? v[0] : v]));
+}
+
+/** The delivery as the manifest sees it: lower-case headers, and the JSON body unwrapped from a form field if declared. */
+function prepare(webhook = {}, delivery) {
+    let body = delivery.body;
+    if (webhook.unwrap && body && typeof body[webhook.unwrap] === 'string') {
+        try { body = JSON.parse(body[webhook.unwrap]); } catch { /* not JSON: leave the body as delivered */ }
+    }
+    return { body, headers: normaliseHeaders(delivery.headers), query: delivery.query || {} };
+}
+
+/** Split one delivery into events: [{ item, parent }]. */
+function splitBatch(webhook = {}, input) {
+    const paths = list(webhook.batch);
+    const at = (obj, p) => (p === 'body' ? obj.body : p === '$' ? obj : getPath(obj, '$.' + p));
+    if (!paths.length) return [{ item: input.body, parent: null }];
+    const outer = at(input, paths[0]);
+    const outerItems = Array.isArray(outer) ? outer : outer == null ? [] : [outer];
+    if (paths.length === 1) return outerItems.map((item) => ({ item, parent: null }));
+    return outerItems.flatMap((parent) => {
+        const inner = getPath(parent, '$.' + paths[1]);
+        return (Array.isArray(inner) ? inner : inner == null ? [] : [inner]).map((item) => ({ item, parent }));
+    });
+}
+
+/**
+ * Every module event in one delivery.
+ * @param {object} manifest   the module's capability manifest
+ * @param {{ body, headers?, query? }} delivery
+ * @returns {Array<{ topic: string, providerTopic: string, eventId: string|null, account: string|null, event: object, record: any }>}
+ *          topic is the manifest's event key (what definitions name); event is the item the workflow sees as $.event.
+ */
+function eventsIn(manifest, delivery) {
+    const webhook = manifest?.webhook;
+    if (!webhook) return [];
+    const input = prepare(webhook, delivery);
+    const out = [];
+    for (const { item, parent } of splitBatch(webhook, input)) {
+        const ctx = { ...input, item, parent };
+        const providerTopic = renderFirst(webhook.topic, ctx);
+        if (!providerTopic) continue;
+        const eventId = renderFirst(webhook.eventId, ctx) || null;
+        const account = webhook.account ? renderFirst(webhook.account, ctx) || null : null;
+        for (const [key, ev] of Object.entries(manifest.events || {})) {
+            if (ev.delivery && ev.delivery !== 'webhook') continue;
+            if ((ev.match ?? key) !== providerTopic) continue;
+            const record = ev.record ? getPath(item, '$.' + ev.record) : item;
+            if (ev.when && !evaluate(ev.when, { event: item, record, headers: input.headers, parent })) continue;
+            out.push({ topic: key, providerTopic, eventId, account, event: item, record });
+        }
+    }
+    return out;
+}
+
+/** A handshake to answer at receipt, before anything is queued: { status, headers, body } or null. */
+function handshakeFor(manifest, delivery) {
+    const h = manifest?.webhook?.handshake;
+    if (!h) return null;
+    const ctx = prepare(manifest.webhook, delivery);
+    if (!evaluate(h.when, ctx)) return null;
+    return { status: h.status || 200, headers: resolve(h.headers || {}, ctx), body: h.body === undefined ? '' : resolve(h.body, ctx) };
+}
+
+/**
+ * Which module of a definition a delivery came from. The URL names it (?module=<module name>); without that, the one
+ * module whose manifest recognises an event in the body. Returns module keys of the definition (usually one).
+ */
+function modulesFor(def, manifests, delivery) {
+    const named = delivery.query?.module;
+    const keys = Object.entries(def.modules || {}).filter(([, m]) => (named ? m.module === named : true)).map(([k]) => k);
+    if (named) return keys;
+    const recognised = keys.filter((k) => eventsIn(manifests[def.modules[k].module], delivery).length > 0);
+    return recognised.length === 1 ? recognised : [];
+}
+
+module.exports = { eventsIn, handshakeFor, modulesFor, splitBatch, renderFirst, normaliseHeaders };

package/integrations/index.js

@@ -21,7 +21,6 @@ module.exports = {
     Options,
     createIntegrationRouter,
     checkRequiredParams,
-    // Deprecated (ADR-059): a wrapper over getEntityTypeRegistry.
     getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
     validateExtensionBinding,

package/integrations/integration-base.js

@@ -457,6 +457,35 @@ class IntegrationBase {
         );
     }
 
+    /**
+     * Insert-only mapping write; usable as an atomic claim/lock row.
+     * @throws {MappingAlreadyExistsError} If a mapping for sourceId exists
+     */
+    async createMapping(sourceId, mapping) {
+        if (!sourceId) {
+            throw new Error(`sourceId must be set`);
+        }
+        return await this.integrationMappingRepository.createMapping(
+            this.id,
+            sourceId,
+            mapping
+        );
+    }
+
+    /**
+     * Deletes the mapping for sourceId. A missing mapping is not an error
+     * (resolves with deletedCount 0).
+     */
+    async deleteMapping(sourceId) {
+        if (!sourceId) {
+            throw new Error(`sourceId must be set`);
+        }
+        return await this.integrationMappingRepository.deleteMapping(
+            this.id,
+            sourceId
+        );
+    }
+
     /**
      * CHILDREN CAN OVERRIDE THESE CONFIGURATION METHODS
      */

package/integrations/integration-router.js

@@ -31,6 +31,9 @@ const {
     GetIntegrationInstance,
 } = require('./use-cases/get-integration-instance');
 const { UpdateIntegration } = require('./use-cases/update-integration');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('./utils/map-integration-dto');
 const {
     GetModuleInstanceFromType,
 } = require('../modules/use-cases/get-module-instance-from-type');
@@ -51,51 +54,47 @@ const {
 const {
     createUserRepository,
 } = require('../user/repositories/user-repository-factory');
+const {
+    GetUserFromBearerToken,
+} = require('../user/use-cases/get-user-from-bearer-token');
+const {
+    GetUserFromXFriggHeaders,
+} = require('../user/use-cases/get-user-from-x-frigg-headers');
+const {
+    GetUserFromAdopterJwt,
+} = require('../user/use-cases/get-user-from-adopter-jwt');
 const {
     AuthenticateWithSharedSecret,
 } = require('../user/use-cases/authenticate-with-shared-secret');
 const { AuthenticateUser } = require('../user/use-cases/authenticate-user');
-const {
-    buildUserAuthentication,
-} = require('../user/create-user-authentication');
 const {
     ProcessAuthorizationCallback,
 } = require('../modules/use-cases/process-authorization-callback');
-const { createScopePolicy } = require('../modules/scope-policy');
-const {
-    AuthorizeEntityForUser,
-} = require('../modules/use-cases/authorize-entity-for-user');
-const {
-    CreateEntityFromCredential,
-} = require('../modules/use-cases/create-entity-from-credential');
-const {
-    ResolveIntegrationOwnership,
-} = require('./use-cases/resolve-integration-ownership');
-const { GetOwnedIntegrationRecord } = require('./use-cases/integration-operations-for-user');
 
 const log = getLogger('frigg.integrations');
 
 function createIntegrationRouter() {
-    // moduleDefinitions is the app registry's definitions (ADR-059), so
-    // /api/authorize and friends accept a type no integration binds.
-    const {
-        integrations: integrationClasses,
-        userConfig,
-        moduleDefinitions,
-        ownership,
-        entityTypeRegistry,
-    } = loadAppDefinition();
-    // Ownership by scope (ADR-056 §3): one object every use case asks.
-    const scopePolicy = createScopePolicy({ ownership, entityTypeRegistry });
+    const { integrations: integrationClasses, userConfig } =
+        loadAppDefinition();
     const moduleRepository = createModuleRepository();
     const integrationRepository = createIntegrationRepository();
     const credentialRepository = createCredentialRepository();
     const userRepository = createUserRepository();
-    const {
-        getUserFromBearerToken,
-        getUserFromXFriggHeaders,
-        getUserFromAdopterJwt,
-    } = buildUserAuthentication({ userConfig, userRepository });
+
+    const getUserFromBearerToken = new GetUserFromBearerToken({
+        userRepository,
+        userConfig,
+    });
+
+    const getUserFromXFriggHeaders = new GetUserFromXFriggHeaders({
+        userRepository,
+        userConfig,
+    });
+
+    const getUserFromAdopterJwt = new GetUserFromAdopterJwt({
+        userRepository,
+        userConfig,
+    });
 
     const authenticateWithSharedSecret = new AuthenticateWithSharedSecret();
 
@@ -109,7 +108,8 @@ function createIntegrationRouter() {
 
     const moduleFactory = new ModuleFactory({
         moduleRepository,
-        moduleDefinitions,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
     const deleteIntegrationForUser = new DeleteIntegrationForUser({
         integrationRepository,
@@ -122,19 +122,6 @@ function createIntegrationRouter() {
         integrationClasses,
         moduleFactory,
         moduleRepository,
-        scopePolicy,
-    });
-
-    // Decides who owns a new integration and which entities the caller may bind
-    // (the v1 create used to check neither), and who may reach an existing one.
-    const resolveIntegrationOwnership = new ResolveIntegrationOwnership({
-        moduleRepository,
-        integrationClasses,
-        scopePolicy,
-    });
-    const getOwnedIntegrationRecord = new GetOwnedIntegrationRecord({
-        integrationRepository,
-        scopePolicy,
     });
 
     const getCredentialForUser = new GetCredentialForUser({
@@ -149,8 +136,8 @@ function createIntegrationRouter() {
 
     const getEntitiesForUser = new GetEntitiesForUser({
         moduleRepository,
-        moduleDefinitions,
-        scopePolicy,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
     const getIntegrationInstance = new GetIntegrationInstance({
@@ -166,65 +153,54 @@ function createIntegrationRouter() {
     });
 
     const getModuleInstanceFromType = new GetModuleInstanceFromType({
-        moduleDefinitions,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
     const getEntityOptionsByType = new GetEntityOptionsByType({
-        moduleDefinitions,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
     const testModuleAuth = new TestModuleAuth({
         moduleRepository,
-        moduleDefinitions,
-        scopePolicy,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
     const getModule = new GetModule({
         moduleRepository,
-        moduleDefinitions,
-        scopePolicy,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
     const getEntityOptionsById = new GetEntityOptionsById({
         moduleRepository,
-        moduleDefinitions,
-        scopePolicy,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
     const refreshEntityOptions = new RefreshEntityOptions({
         moduleRepository,
-        moduleDefinitions,
-        scopePolicy,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
     const getPossibleIntegrations = new GetPossibleIntegrations({
         integrationClasses,
     });
 
-    // The owner of what an authorization creates follows its scope (ADR-056 §3.2).
     const processAuthorizationCallback = new ProcessAuthorizationCallback({
         moduleRepository,
         credentialRepository,
         integrationRepository,
-        moduleDefinitions,
-    });
-    const authorizeEntityForUser = new AuthorizeEntityForUser({
-        scopePolicy,
-        processAuthorizationCallback,
-    });
-    // v1 POST /api/entity: same owner resolution as /api/authorize.
-    const createEntityFromCredential = new CreateEntityFromCredential({
-        authorizeEntityForUser,
-        processAuthorizationCallback,
-        credentialRepository,
-        moduleDefinitions,
+        moduleDefinitions:
+            getModulesDefinitionFromIntegrationClasses(integrationClasses),
     });
 
     const router = express();
 
     setIntegrationRoutes(router, authenticateUser, {
-        resolveIntegrationOwnership,
-        getOwnedIntegrationRecord,
         createIntegration,
         deleteIntegrationForUser,
         getIntegrationsForUser,
@@ -233,6 +209,11 @@ function createIntegrationRouter() {
         updateIntegration,
         getPossibleIntegrations,
     });
+    // Data-defined integrations (ADR-063): only mounted when the app registers a data-defined class.
+    require('./data-defined/router').setDataDefinedRoutes(router, authenticateUser, {
+        getIntegrationInstance,
+        integrationClasses,
+    });
     setEntityRoutes(router, authenticateUser, {
         getCredentialForUser,
         getModuleInstanceFromType,
@@ -241,8 +222,7 @@ function createIntegrationRouter() {
         getModule,
         getEntityOptionsById,
         refreshEntityOptions,
-        authorizeEntityForUser,
-        createEntityFromCredential,
+        processAuthorizationCallback,
     });
     return router;
 }
@@ -279,8 +259,6 @@ function checkRequiredParams(params, requiredKeys) {
  */
 function setIntegrationRoutes(router, authenticateUser, useCases) {
     const {
-        resolveIntegrationOwnership,
-        getOwnedIntegrationRecord,
         createIntegration,
         deleteIntegrationForUser,
         getIntegrationsForUser,
@@ -289,22 +267,15 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
         updateIntegration,
         getPossibleIntegrations,
     } = useCases;
-
-    // The owner of an integration the caller may reach (404 otherwise), which is
-    // what the id-and-owner use cases below expect. `manage: true` is for
-    // changing or deleting: an organization's integration needs an admin (403).
-    const ownerOf = async (integrationId, user, options) =>
-        (await getOwnedIntegrationRecord.execute(integrationId, user, options))
-            .userId;
-
     router.route('/api/integrations').get(
         catchAsyncError(async (req, res) => {
             const user = await authenticateUser.execute(req);
-            const integrations = await getIntegrationsForUser.execute(user);
+            const userId = user.getId();
+            const integrations = await getIntegrationsForUser.execute(userId);
             const results = {
                 entities: {
                     options: await getPossibleIntegrations.execute(),
-                    authorized: await getEntitiesForUser.execute(user),
+                    authorized: await getEntitiesForUser.execute(userId),
                 },
                 integrations: integrations,
             };
@@ -316,6 +287,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
     router.route('/api/integrations').post(
         catchAsyncError(async (req, res) => {
             const user = await authenticateUser.execute(req);
+            const userId = user.getId();
             const params = checkRequiredParams(req.body, [
                 'entities',
                 'config',
@@ -323,17 +295,10 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
 
             get(params.config, 'type');
 
-            const { ownerId, organizationId, adoptUnscoped } =
-                await resolveIntegrationOwnership.execute({
-                    entityIds: params.entities,
-                    config: params.config,
-                    user,
-                });
             const integration = await createIntegration.execute(
                 params.entities,
-                ownerId,
-                params.config,
-                { organizationId, adoptUnscoped }
+                userId,
+                params.config
             );
 
             res.status(201).json(integration);
@@ -343,11 +308,12 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
     router.route('/api/integrations/:integrationId').patch(
         catchAsyncError(async (req, res) => {
             const user = await authenticateUser.execute(req);
+            const userId = user.getId();
             const params = checkRequiredParams(req.body, ['config']);
 
             const integration = await updateIntegration.execute(
                 req.params.integrationId,
-                await ownerOf(req.params.integrationId, user, { manage: true }),
+                userId,
                 params.config
             );
             res.json(integration);
@@ -360,7 +326,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             const params = checkRequiredParams(req.params, ['integrationId']);
             await deleteIntegrationForUser.execute(
                 params.integrationId,
-                await ownerOf(params.integrationId, user, { manage: true })
+                user.getId()
             );
             res.status(204).json({});
         })
@@ -372,7 +338,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             const params = checkRequiredParams(req.params, ['integrationId']);
             const integration = await getIntegrationInstance.execute(
                 params.integrationId,
-                await ownerOf(params.integrationId, user)
+                user.getId()
             );
             res.json(await integration.send('GET_CONFIG_OPTIONS'));
         })
@@ -388,7 +354,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
                 ]);
                 const integration = await getIntegrationInstance.execute(
                     params.integrationId,
-                    await ownerOf(params.integrationId, user)
+                    user.getId()
                 );
 
                 res.json(
@@ -402,7 +368,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             const params = checkRequiredParams(req.params, ['integrationId']);
             const integration = await getIntegrationInstance.execute(
                 params.integrationId,
-                await ownerOf(params.integrationId, user)
+                user.getId()
             );
             res.json(await integration.send('GET_USER_ACTIONS', req.body));
         })
@@ -419,7 +385,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
                 ]);
                 const integration = await getIntegrationInstance.execute(
                     params.integrationId,
-                    await ownerOf(params.integrationId, user)
+                    user.getId()
                 );
 
                 res.json(
@@ -444,7 +410,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
                 ]);
                 const integration = await getIntegrationInstance.execute(
                     params.integrationId,
-                    await ownerOf(params.integrationId, user)
+                    user.getId()
                 );
 
                 res.json(
@@ -465,7 +431,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             ]);
             const integration = await getIntegrationInstance.execute(
                 params.integrationId,
-                await ownerOf(params.integrationId, user)
+                user.getId()
             );
             res.json(await integration.send(params.actionId, req.body));
         })
@@ -482,7 +448,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             const params = checkRequiredParams(req.params, ['integrationId']);
             const integration = await getIntegrationInstance.execute(
                 params.integrationId,
-                await ownerOf(params.integrationId, user)
+                user.getId()
             );
 
             // We could perhaps augment router with dynamic options? Haven't decided yet, but here may be the place
@@ -502,7 +468,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             const params = checkRequiredParams(req.params, ['integrationId']);
             const instance = await getIntegrationInstance.execute(
                 params.integrationId,
-                await ownerOf(params.integrationId, user)
+                user.getId()
             );
 
             if (!instance) {
@@ -540,21 +506,16 @@ function setEntityRoutes(router, authenticateUser, useCases) {
         getModule,
         getEntityOptionsById,
         refreshEntityOptions,
-        authorizeEntityForUser,
-        createEntityFromCredential,
+        processAuthorizationCallback,
     } = useCases;
 
     router.route('/api/authorize').get(
         catchAsyncError(async (req, res) => {
             const user = await authenticateUser.execute(req);
+            const userId = user.getId();
             const params = checkRequiredParams(req.query, ['entityType']);
-            // The owner POST stores under, so GET and POST describe one connection.
-            const { ownerId } = authorizeEntityForUser.resolveOwnership({
-                user,
-                entityType: params.entityType,
-            });
             const module = await getModuleInstanceFromType.execute(
-                ownerId,
+                userId,
                 params.entityType,
                 { state: req.query.state }
             );
@@ -573,15 +534,11 @@ function setEntityRoutes(router, authenticateUser, useCases) {
     router.route('/api/authorize').post(
         catchAsyncError(async (req, res) => {
             const user = await authenticateUser.execute(req);
+            const userId = user.getId();
             const params = checkRequiredParams(req.body, [
                 'entityType',
                 'data',
             ]);
-            const ownership = authorizeEntityForUser.resolveOwnership({
-                user,
-                entityType: params.entityType,
-            });
-            const userId = ownership.ownerId;
 
             const dataKeys =
                 params.data && typeof params.data === 'object'
@@ -593,13 +550,11 @@ function setEntityRoutes(router, authenticateUser, useCases) {
                 dataKeys,
             });
 
-            const { result: entityDetails } =
-                await authorizeEntityForUser.execute({
-                    user,
-                    entityType: params.entityType,
-                    data: params.data,
-                    ownership,
-                });
+            const entityDetails = await processAuthorizationCallback.execute(
+                userId,
+                params.entityType,
+                params.data
+            );
 
             log.info('Entity authorized', {
                 eventName: 'frigg.integrations.authorized',
@@ -616,20 +571,35 @@ function setEntityRoutes(router, authenticateUser, useCases) {
     router.route('/api/entity').post(
         catchAsyncError(async (req, res) => {
             const user = await authenticateUser.execute(req);
+            const userId = user.getId();
             const params = checkRequiredParams(req.body, [
                 'entityType',
                 'data',
             ]);
             checkRequiredParams(req.body.data, ['credential_id']);
 
-            // The owner follows the entity type's scope, as /api/authorize.
-            res.json(
-                await createEntityFromCredential.execute({
-                    user,
-                    entityType: params.entityType,
-                    credentialId: params.data.credential_id,
-                })
+            // May want to pass along the user ID as well so credential ID's can't be fished???
+            const credential = await getCredentialForUser.execute(
+                params.data.credential_id,
+                userId
+            );
+
+            if (!credential) {
+                throw Boom.badRequest('Invalid credential ID');
+            }
+
+            const module = await getModuleInstanceFromType.execute(
+                userId,
+                params.entityType
+            );
+            const entityDetails = await module.getEntityDetails(
+                module.api,
+                null,
+                null,
+                userId
             );
+
+            res.json(await module.findOrCreateEntity(entityDetails));
         })
     );