@friggframework/core 0.2.31-v1-alpha.6 → 1.0.1-canary.278.7b20420.0

package/logs/logger.test.js

@@ -0,0 +1,76 @@
+const { debug, initDebugLog, flushDebugLog } = require('./logger');
+const sinon = require('sinon');
+const {
+    overrideEnvironment,
+    restoreEnvironment,
+} = require('@friggframework/devtools');
+
+/* eslint-disable no-console */
+
+describe('Logger', () => {
+    beforeEach(() => {
+        sinon.stub(console, 'debug');
+        sinon.stub(console, 'error');
+    });
+
+    afterEach(() => {
+        console.debug.restore();
+        console.error.restore();
+        restoreEnvironment();
+    });
+
+    it('runs', () => {
+        initDebugLog('Test Event', { test: true });
+        debug('Add a message', 'or two', { or: 3 });
+        flushDebugLog(new Error());
+
+        expect(console.debug).toHaveProperty('callCount', 2);
+        expect(console.error).toHaveProperty('callCount', 1);
+    });
+
+    it('logs immediately when environment variable set', () => {
+        overrideEnvironment({ DEBUG_VERBOSE: '1' });
+
+        debug('Add a message', 'or two', { or: 3 });
+        debug('And another');
+
+        expect(console.debug).toHaveProperty('callCount', 2);
+        expect(console.error).toHaveProperty('callCount', 0);
+    });
+
+    it('is resilient to missing parameters', () => {
+        initDebugLog();
+        debug();
+        flushDebugLog();
+
+        expect(console.debug).toHaveProperty('callCount', 0);
+        expect(console.error).toHaveProperty('callCount', 1);
+    });
+
+    it('outputs parent errors', () => {
+        initDebugLog();
+
+        const error = new Error();
+        error.cause = new Error();
+        error.cause.cause = new Error();
+        error.cause.cause.cause = new Error();
+
+        flushDebugLog(error);
+
+        expect(console.debug).toHaveProperty('callCount', 0);
+        expect(console.error).toHaveProperty('callCount', 7); // 1 + 2 for each cause
+    });
+
+    it('adds a debug message if more than 1 error encountered', () => {
+        initDebugLog();
+        flushDebugLog(new Error());
+
+        expect(console.debug).toHaveProperty('callCount', 0);
+        expect(console.error).toHaveProperty('callCount', 1);
+
+        flushDebugLog(new Error());
+
+        expect(console.debug).toHaveProperty('callCount', 1);
+        expect(console.error).toHaveProperty('callCount', 2);
+    });
+});

package/module-plugin/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+    "extends": "@friggframework/eslint-config"
+}

package/module-plugin/CHANGELOG.md

@@ -0,0 +1,224 @@
+# v1.1.0 (Wed Sep 06 2023)
+
+#### 🚀 Enhancement
+
+- Slack lookup by externalId, remove the user requirement from Mongoose DB models [#218](https://github.com/friggframework/frigg/pull/218) ([@seanspeaks](https://github.com/seanspeaks))
+
+#### 🐛 Bug Fix
+
+- Looking good ([@seanspeaks](https://github.com/seanspeaks))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 1
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.27 (Thu Jun 08 2023)
+
+#### 🐛 Bug Fix
+
+- Fr/gdrive lef 280 [#175](https://github.com/friggframework/frigg/pull/175) (michael.webber@lefthook.com [@seanspeaks](https://github.com/seanspeaks))
+- Google Drive update ([@seanspeaks](https://github.com/seanspeaks))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 2
+
+- Michael Webber (michael.webber@lefthook.com)
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.26 (Thu May 25 2023)
+
+#### 🐛 Bug Fix
+
+- Support calling localhost for ironclad api [#160](https://github.com/friggframework/frigg/pull/160) ([@debbie-yu](https://github.com/debbie-yu))
+- remove agent at method call level ([@debbie-yu](https://github.com/debbie-yu))
+- address feedback to put agent in requester class ([@debbie-yu](https://github.com/debbie-yu))
+- support calling localhost for ironclad api ([@debbie-yu](https://github.com/debbie-yu))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 2
+
+- [@debbie-yu](https://github.com/debbie-yu)
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.25 (Tue Apr 04 2023)
+
+:tada: This release contains work from a new contributor! :tada:
+
+Thank you, null[@debbie-yu](https://github.com/debbie-yu), for all your work!
+
+#### 🐛 Bug Fix
+
+- Adding new IntegrationMapping collection [#142](https://github.com/friggframework/frigg/pull/142) ([@debbie-yu](https://github.com/debbie-yu))
+- Merge branch 'main' of https://github.com/friggframework/frigg into debbie.yu/integration-mapping ([@debbie-yu](https://github.com/debbie-yu))
+- addressing PR feedback and adding unit tests around IntegrationMapping ([@debbie-yu](https://github.com/debbie-yu))
+- adding new IntegrationMapping collection to better handle keeping track of mappings for integrations ([@debbie-yu](https://github.com/debbie-yu))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 2
+
+- [@debbie-yu](https://github.com/debbie-yu)
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.24 (Tue Feb 21 2023)
+
+#### 🐛 Bug Fix
+
+- Updates to HubSpot Module [#132](https://github.com/friggframework/frigg/pull/132) ([@seanspeaks](https://github.com/seanspeaks))
+- Merge branch 'main' into hubspot-updates ([@seanspeaks](https://github.com/seanspeaks))
+- WIP Updates... cleanup, simplify, and fix ([@seanspeaks](https://github.com/seanspeaks))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 1
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.23 (Wed Feb 08 2023)
+
+#### 🐛 Bug Fix
+
+- Fixed a Slack bug via requester improvement [#125](https://github.com/friggframework/frigg/pull/125) ([@seanspeaks](https://github.com/seanspeaks))
+- Fixed a Slack bug via requester improvement ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 1
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.22 (Tue Jan 31 2023)
+
+#### 🐛 Bug Fix
+
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 1
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.21 (Wed Jan 18 2023)
+
+#### 🐛 Bug Fix
+
+- Ironclad and slack updates [#96](https://github.com/friggframework/frigg/pull/96) ([@seanspeaks](https://github.com/seanspeaks))
+- Refresh Auth attempt only once, instead of potential for infinite loop [#95](https://github.com/friggframework/frigg/pull/95) ([@seanspeaks](https://github.com/seanspeaks))
+- Refresh Auth attempt only once, instead of potential for infinite loop ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 1
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.20 (Wed Jan 11 2023)
+
+#### 🐛 Bug Fix
+
+- Ironclad updates and sub type [#91](https://github.com/friggframework/frigg/pull/91) ([@JonathanEdMoore](https://github.com/JonathanEdMoore) [@seanspeaks](https://github.com/seanspeaks))
+- subType support for ironclad ([@seanspeaks](https://github.com/seanspeaks))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 2
+
+- Jonathan Moore ([@JonathanEdMoore](https://github.com/JonathanEdMoore))
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.19 (Tue Jan 10 2023)
+
+:tada: This release contains work from a new contributor! :tada:
+
+Thank you, Jonathan O'Donnell ([@joncodo](https://github.com/joncodo)), for all your work!
+
+#### 🐛 Bug Fix
+
+- Merge branch 'main' of github.com:friggframework/frigg into doc-updates ([@joncodo](https://github.com/joncodo))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 2
+
+- Jonathan O'Donnell ([@joncodo](https://github.com/joncodo))
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.18 (Mon Jan 09 2023)
+
+#### 🐛 Bug Fix
+
+- Merge remote-tracking branch 'origin/main' into gitbook-updates [#48](https://github.com/friggframework/frigg/pull/48) ([@seanspeaks](https://github.com/seanspeaks))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+- Updates to managers [#24](https://github.com/friggframework/frigg/pull/24) ([@seanspeaks](https://github.com/seanspeaks))
+- Update integrationManager createIntegration function to accept EntityManager param (WIP) (Could be improved) ([@seanspeaks](https://github.com/seanspeaks))
+- module-plugin manager file uses MO instead of just Entity ([@seanspeaks](https://github.com/seanspeaks))
+- A lot of changes all rolled into one [#21](https://github.com/friggframework/frigg/pull/21) ([@seanspeaks](https://github.com/seanspeaks))
+- Bumped versions with patches ([@seanspeaks](https://github.com/seanspeaks))
+- Mongoose models tweak for sls offline as per https://nesin.io/blog/fix-mongoose-cannot-overwrite-model-once-compiled-error ([@seanspeaks](https://github.com/seanspeaks))
+- Continued updating of references and refactoring API modules ([@seanspeaks](https://github.com/seanspeaks))
+- Merge remote-tracking branch 'origin/main' into simplify-mongoose-models ([@seanspeaks](https://github.com/seanspeaks))
+- Change references to the module instead of local file reference ([@seanspeaks](https://github.com/seanspeaks))
+- Added core as a dependency of module-plugin ([@seanspeaks](https://github.com/seanspeaks))
+- Add READMEs for all packages and api-modules [#20](https://github.com/friggframework/frigg/pull/20) ([@seanspeaks](https://github.com/seanspeaks))
+- Add READMEs for all packages and api-modules ([@seanspeaks](https://github.com/seanspeaks))
+- Begin tweaks for mongo/mongoose models ([@seanspeaks](https://github.com/seanspeaks))
+
+#### ⚠️ Pushed to `main`
+
+- Merge branch 'main' into gitbook-updates ([@seanspeaks](https://github.com/seanspeaks))
+- Refactored for more conventional naming (at least for packages) ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 1
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.17 (Fri Dec 23 2022)
+
+#### 🐛 Bug Fix
+
+- this may break folks' implementations, but that's what unit tests are… [#81](https://github.com/friggframework/frigg/pull/81) ([@seanspeaks](https://github.com/seanspeaks))
+- this may break folks' implementations, but that's what unit tests are for. ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 1
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+
+---
+
+# v1.0.15 (Tue Dec 06 2022)
+
+#### 🐛 Bug Fix
+
+- fix modules to @friggframework [#74](https://github.com/friggframework/frigg/pull/74) ([@sheehantoufiq](https://github.com/sheehantoufiq))
+- Bump independent versions \[skip ci\] ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 2
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))
+- Sheehan Toufiq Khan ([@sheehantoufiq](https://github.com/sheehantoufiq))
+
+---
+
+# v1.0.12 (Mon Sep 19 2022)
+
+#### 🐛 Bug Fix
+
+- Merge remote-tracking branch 'origin/main' into gitbook-updates [#48](https://github.com/friggframework/frigg/pull/48) ([@seanspeaks](https://github.com/seanspeaks))
+
+#### Authors: 1
+
+- Sean Matthews ([@seanspeaks](https://github.com/seanspeaks))

package/module-plugin/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2022 Left Hook Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/module-plugin/ModuleConstants.js

@@ -0,0 +1,10 @@
+const ModuleConstants = {
+    authType: {
+        oauth2: 'oauth2',
+        oauth1: 'oauth1',
+        basic: 'basic',
+        apiKey: 'apiKey',
+    },
+};
+
+module.exports = { ModuleConstants };

package/module-plugin/README.md

@@ -0,0 +1,3 @@
+# module-plugin
+
+This package exports the `module-plugin` library of models, classes, and functions used in [Frigg](https://friggframework.org). You can find its documentation [on Frigg's website](https://docs.friggframework.org/packages/module-plugin).

package/module-plugin/auther.js

@@ -0,0 +1,342 @@
+// Manages authorization and credential persistence
+// Instantiation of an API Class
+// Expects input object like this:
+// const authDef = {
+//     API: class anAPI{},
+//     moduleName: 'anAPI', //maybe not required
+//     requiredAuthMethods: {
+//         // oauth methods, how to handle these being required/not?
+//         getToken: async function(params, callbackParams, tokenResponse) {},
+//         // required for all Auth methods
+//         getEntityDetails: async function(params) {}, //probably calls api method
+//         getCredentialDetails: async function(params) {}, // might be same as above
+//         apiParamsFromCredential: function(params) {},
+//         testAuth: async function() {}, // basic request to testAuth
+//     },
+//     env: {
+//         client_id: process.env.HUBSPOT_CLIENT_ID,
+//         client_secret: process.env.HUBSPOT_CLIENT_SECRET,
+//         scope: process.env.HUBSPOT_SCOPE,
+//         redirect_uri: `${process.env.REDIRECT_URI}/an-api`,
+//     }
+// };
+
+//TODO:
+// 1. Add definition of expected params to API Class (or could just be credential?)
+// 2.
+
+
+const { Delegate } = require('../core');
+const { get } = require('../assertions');
+const _ = require('lodash');
+const {flushDebugLog} = require('../logs');
+const { Credential } = require('./credential');
+const { Entity } = require('./entity');
+const { mongoose } = require('../database/mongoose');
+const {ModuleConstants} = require("./ModuleConstants");
+
+class Auther extends Delegate {
+    static validateDefinition(definition) {
+        if (!definition) {
+            throw new Error('Auther definition is required');
+        }
+        if (!definition.moduleName) {
+            throw new Error('Auther definition requires moduleName');
+        }
+        if (!definition.API) {
+            throw new Error('Auther definition requires API class');
+        }
+        // if (!definition.Credential) {
+        //     throw new Error('Auther definition requires Credential class');
+        // }
+        // if (!definition.Entity) {
+        //     throw new Error('Auther definition requires Entity class');
+        // }
+        if (!definition.requiredAuthMethods) {
+            throw new Error('Auther definition requires requiredAuthMethods');
+        } else {
+            if (definition.API.requesterType === ModuleConstants.authType.oauth2 &&
+                !definition.requiredAuthMethods.getToken) {
+                throw new Error('Auther definition requires requiredAuthMethods.getToken');
+            }
+            if (!definition.requiredAuthMethods.getEntityDetails) {
+                throw new Error('Auther definition requires requiredAuthMethods.getEntityDetails');
+            }
+            if (!definition.requiredAuthMethods.getCredentialDetails) {
+                throw new Error('Auther definition requires requiredAuthMethods.getCredentialDetails');
+            }
+            if (!definition.requiredAuthMethods.apiPropertiesToPersist) {
+                throw new Error('Auther definition requires requiredAuthMethods.apiPropertiesToPersist');
+            } else if (definition.Credential){
+                for (const prop of definition.requiredAuthMethods.apiPropertiesToPersist?.credential) {
+                    if (!definition.Credential.schema.paths.hasOwnProperty(prop)) {
+                        throw new Error(
+                            `Auther definition requires Credential schema to have property ${prop}`
+                        );
+                    }
+                }
+            }
+            if (!definition.requiredAuthMethods.testAuthRequest) {
+                throw new Error('Auther definition requires requiredAuthMethods.testAuth');
+            }
+        }
+    }
+
+    constructor(params) {
+        super(params);
+        this.userId = get(params, 'userId', null); // Making this non-required
+        const definition = get(params, 'definition');
+        Auther.validateDefinition(definition);
+        Object.assign(this, definition.requiredAuthMethods);
+        this.name = definition.moduleName;
+        this.modelName = definition.modelName;
+        this.apiClass = definition.API;
+        this.CredentialModel = definition.Credential || this.getCredentialModel();
+        this.EntityModel = definition.Entity || this.getEntityModel();
+    }
+
+    static async getInstance(params) {
+        const instance = new this(params);
+        if (params.entityId) {
+            instance.entity = await instance.EntityModel.findById(params.entityId);
+            instance.credential = await instance.CredentialModel.findById(
+                instance.entity.credential
+            );
+        } else if (params.credentialId) {
+            instance.credential = await instance.CredentialModel.findById(
+                params.credentialId
+            );
+        }
+        let credential = {};
+        let entity = {};
+        if (instance.credential) {
+            credential = instance.credential.toObject();
+        }
+        if (instance.entity) {
+            entity = instance.entity.toObject();
+        }
+        const apiParams = {
+            ...params.definition.env,
+            delegate: instance,
+            ...instance.apiParamsFromCredential(credential),
+            ...instance.apiParamsFromEntity(entity),
+        };
+        instance.api = new instance.apiClass(apiParams);
+        return instance;
+    }
+
+    static getEntityModelFromDefinition(definition) {
+        const partialModule = new this({definition});
+        return partialModule.getEntityModel();
+    }
+
+    getName() {
+        return this.name;
+    }
+
+    apiParamsFromCredential(credential) {
+        return _.pick(credential, ...this.apiPropertiesToPersist?.credential);
+    }
+
+    apiParamsFromEntity(entity) {
+        return _.pick(entity, ...this.apiPropertiesToPersist?.entity);
+    }
+
+    getEntityModel() {
+        if (!this.EntityModel) {
+            const prefix = this.modelName ?? _.upperFirst(this.getName());
+            const arrayToDefaultObject = (array, defaultValue) => _.mapValues(_.keyBy(array), () => defaultValue);
+            const schema = new mongoose.Schema(arrayToDefaultObject(this.apiPropertiesToPersist.entity, {
+                type: mongoose.Schema.Types.Mixed,
+                trim: true,
+            }));
+            const name = `${prefix}Entity`;
+            this.EntityModel =
+                Entity.discriminators?.[name] || Entity.discriminator(name, schema);
+        }
+        return this.EntityModel;
+    }
+
+    getCredentialModel() {
+        if (!this.CredentialModel) {
+            const arrayToDefaultObject = (array, defaultValue) => _.mapValues(_.keyBy(array), () => defaultValue);
+            const schema = new mongoose.Schema(arrayToDefaultObject(this.apiPropertiesToPersist.credential, {
+                type: mongoose.Schema.Types.Mixed,
+                trim: true,
+                lhEncrypt: true
+            }));
+            const prefix = this.modelName ?? _.upperFirst(this.getName());
+            const name = `${prefix}Credential`;
+            this.CredentialModel =
+                Credential.discriminators?.[name] || Credential.discriminator(name, schema);
+        }
+        return this.CredentialModel;
+    }
+
+    async getEntitiesForUserId(userId) {
+        // Only return non-internal fields. Leverages "select" and "options" to non-excepted fields and a pure object.
+        const list = await this.EntityModel.find(
+            { user: userId },
+            '-dateCreated -dateUpdated -user -credentials -credential -__t -__v',
+            { lean: true }
+        );
+        console.log('getEntitiesForUserId list', list, userId);
+        return list.map((entity) => ({
+            id: entity._id,
+            type: this.getName(),
+            ...entity,
+        }));
+    }
+
+    async validateAuthorizationRequirements() {
+        const requirements = await this.getAuthorizationRequirements();
+        let valid = true;
+        if (['oauth1', 'oauth2'].includes(requirements.type) && !requirements.url) {
+            valid = false;
+        }
+        return valid;
+    }
+
+    getAuthorizationRequirements(params) {
+        // TODO: How can this be more helpful both to implement and consume
+        // this function must return a dictionary with the following format
+        // node only url key is required. Data would be used for Base Authentication
+        // let returnData = {
+        //     url: "callback url for the data or teh redirect url for login",
+        //     type: one of the types defined in modules/Constants.js
+        //     data: ["required", "fields", "we", "may", "need"]
+        // }
+        return this.api.getAuthorizationRequirements();
+    }
+
+    async testAuth(params) {
+        let validAuth = false;
+        try {
+            if (await this.testAuthRequest(this.api)) validAuth = true;
+        } catch (e) {
+            flushDebugLog(e);
+        }
+        return validAuth;
+    }
+
+    async processAuthorizationCallback(params) {
+        let tokenResponse;
+        if (this.apiClass.requesterType === ModuleConstants.authType.oauth2) {
+            tokenResponse = await this.getToken(this.api, params);
+        } else {
+            tokenResponse = await this.setAuthParams(this.api, params);
+            await this.onTokenUpdate();
+        }
+        const authRes = await this.testAuth();
+        if (!authRes) {
+            throw new Error('Authorization failed');
+        }
+        const entityDetails = await this.getEntityDetails(
+            this.api, params, tokenResponse, this.userId
+        );
+        Object.assign(entityDetails.details, this.apiParamsFromEntity(this.api));
+        await this.findOrCreateEntity(entityDetails);
+        return {
+            credential_id: this.credential.id,
+            entity_id: this.entity.id,
+            type: this.getName(),
+        }
+    }
+
+    async onTokenUpdate() {
+        const credentialDetails = await this.getCredentialDetails(this.api, this.userId);
+        Object.assign(credentialDetails.details, this.apiParamsFromCredential(this.api));
+        credentialDetails.details.auth_is_valid = true;
+        await this.updateOrCreateCredential(credentialDetails);
+    }
+
+    async receiveNotification(notifier, delegateString, object = null) {
+        if (delegateString === this.api.DLGT_TOKEN_UPDATE) {
+            await this.onTokenUpdate();
+        }
+        else if (delegateString === this.api.DLGT_TOKEN_DEAUTHORIZED) {
+            await this.deauthorize();
+        }
+        else if (delegateString === this.api.DLGT_INVALID_AUTH) {
+            await this.markCredentialsInvalid();
+        }
+    }
+
+    async getEntityOptions() {
+        // May not be needed if the callback already creates the entity, such as in situations
+        // like HubSpot where the account is determined in the authorization flow.
+        // This should only be used in situations such as FreshBooks where the user needs to make
+        // an account decision on the front end.
+        throw new Error(
+            'Entity requirement method getEntityOptions() is not defined in the class'
+        );
+    }
+
+    async findOrCreateEntity(entityDetails) {
+        const identifiers = get(entityDetails, 'identifiers');
+        const details = get(entityDetails, 'details');
+        const search = await this.EntityModel.find(identifiers);
+        if (search.length > 1) {
+            throw new Error(
+                'Multiple entities found with the same identifiers: ' + JSON.stringify(identifiers)
+            );
+        }
+        else if (search.length === 0) {
+            this.entity = await this.EntityModel.create({
+                credential: this.credential.id,
+                ...details,
+                ...identifiers,
+            });
+        } else if (search.length === 1) {
+            this.entity = search[0];
+        }
+        if (this.entity.credential === undefined) {
+            this.entity.credential = this.credential.id;
+            await this.entity.save();
+        }
+    }
+
+    async updateOrCreateCredential(credentialDetails) {
+        const identifiers = get(credentialDetails, 'identifiers');
+        const details = get(credentialDetails, 'details');
+
+        if (!this.credential){
+            const credentialSearch = await this.CredentialModel.find(identifiers);
+            if (credentialSearch.length > 1) {
+                throw new Error(`Multiple credentials found with same identifiers: ${identifiers}`);
+            }
+            else if (credentialSearch.length === 1) {
+                // found exactly one credential with these identifiers
+                this.credential = credentialSearch[0];
+            }
+            else {
+                // found no credential with these identifiers (match none for insert)
+                this.credential = {$exists: false};
+            }
+        }
+        // update credential or create if none was found
+        this.credential = await this.CredentialModel.findOneAndUpdate(
+            {_id: this.credential},
+            {$set: {...identifiers, ...details}},
+            {useFindAndModify: true, new: true, upsert: true}
+        );
+    }
+
+    async markCredentialsInvalid() {
+        if (this.credential) {
+            this.credential.auth_is_valid = false;
+            await this.credential.save();
+        }
+    }
+
+    async deauthorize() {
+        this.api = new this.apiClass();
+        if (this.entity?.credential) {
+            await this.CredentialModel.deleteOne({ _id: this.entity.credential });
+            this.entity.credential = undefined;
+            await this.entity.save();
+        }
+    }
+}
+
+module.exports = { Auther };