@friggframework/devtools 1.2.0-canary.293.50b9cd8.0 → 1.2.0

package/frigg-cli/installCommand.js

@@ -0,0 +1,57 @@
+const { installPackage } = require('./installPackage');
+const { createIntegrationFile } = require('./integrationFile');
+const { resolve } = require('node:path');
+const { updateBackendJsFile } = require('./backendJs');
+const { logInfo, logError } = require('./logger');
+const { commitChanges } = require('./commitChanges');
+const {
+    findNearestBackendPackageJson,
+    validateBackendPath,
+} = require('./backendPath');
+const { handleEnvVariables } = require('./environmentVariables');
+const {
+    validatePackageExists,
+    searchAndSelectPackage,
+} = require('./validatePackage');
+
+const installCommand = async (apiModuleName) => {
+    try {
+        const packageNames = await searchAndSelectPackage(apiModuleName);
+        if (!packageNames || packageNames.length === 0) return;
+
+        const backendPath = findNearestBackendPackageJson();
+        validateBackendPath(backendPath);
+
+        for (const packageName of packageNames) {
+            await validatePackageExists(packageName);
+            installPackage(backendPath, packageName);
+
+            const modulePath = resolve(
+                backendPath,
+                `../../node_modules/${packageName}`
+            );
+            const {
+                Config: { label },
+                Api: ApiClass,
+            } = require(modulePath);
+
+            const sanitizedLabel = label.replace(
+                /[<>:"/\\|?*\x00-\x1F\s]/g,
+                ''
+            ); // Remove invalid characters and spaces            console.log('Installing integration for:', sanitizedLabel);
+            createIntegrationFile(backendPath, sanitizedLabel, ApiClass);
+            updateBackendJsFile(backendPath, sanitizedLabel);
+            commitChanges(backendPath, sanitizedLabel);
+            logInfo(
+                `Successfully installed ${packageName} and updated the project.`
+            );
+
+            await handleEnvVariables(backendPath, modulePath);
+        }
+    } catch (error) {
+        logError('An error occurred:', error);
+        process.exit(1);
+    }
+};
+
+module.exports = { installCommand };

package/frigg-cli/installPackage.js

@@ -0,0 +1,13 @@
+const { execSync } = require('child_process');
+const path = require('path');
+
+function installPackage(backendPath, packageName) {
+    execSync(`npm install ${packageName}`, {
+        cwd: path.dirname(backendPath),
+        stdio: 'inherit',
+    });
+}
+
+module.exports = {
+    installPackage,
+};

package/frigg-cli/integrationFile.js

@@ -0,0 +1,30 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { logInfo } = require('./logger');
+const { getIntegrationTemplate } = require('./template');
+const INTEGRATIONS_DIR = 'src/integrations';
+
+function createIntegrationFile(backendPath, apiModuleName, ApiClass) {
+    const integrationDir = path.join(
+        path.dirname(backendPath),
+        INTEGRATIONS_DIR
+    );
+    logInfo(`Ensuring directory exists: ${integrationDir}`);
+    fs.ensureDirSync(integrationDir);
+
+    const integrationFilePath = path.join(
+        integrationDir,
+        `${apiModuleName}Integration.js`
+    );
+    logInfo(`Writing integration file: ${integrationFilePath}`);
+    const integrationTemplate = getIntegrationTemplate(
+        apiModuleName,
+        backendPath,
+        ApiClass
+    );
+    fs.writeFileSync(integrationFilePath, integrationTemplate);
+}
+
+module.exports = {
+    createIntegrationFile,
+};

package/frigg-cli/logger.js

@@ -0,0 +1,12 @@
+function logInfo(message) {
+    console.log(message);
+}
+
+function logError(message, error) {
+    console.error(message, error);
+}
+
+module.exports = {
+    logInfo,
+    logError,
+};

package/frigg-cli/template.js

@@ -0,0 +1,90 @@
+const path = require('path');
+
+function getIntegrationTemplate(apiModuleName, backendPath, ApiClass) {
+    // Find the sample data method
+    const apiMethods = Object.getOwnPropertyNames(ApiClass.prototype);
+    const sampleDataMethod =
+        apiMethods.find(
+            (method) =>
+                method.toLowerCase().includes('search') ||
+                method.toLowerCase().includes('list') ||
+                method.toLowerCase().includes('get')
+        ) || 'searchDeals';
+
+    return `const { get, IntegrationBase, Options } = require('@friggframework/core');
+const { Definition: ${apiModuleName}Module, Config: defaultConfig } = require('@friggframework/api-module-${apiModuleName.toLowerCase()}');
+
+class ${apiModuleName}Integration extends IntegrationBase {
+    static Config = {
+        name: defaultConfig.name || '${apiModuleName.toLowerCase()}',
+        version: '1.0.0',
+        supportedVersions: ['1.0.0'],
+        events: ['SEARCH_DEALS'],
+    };
+
+    static Options =
+        new Options({
+            module: ${apiModuleName}Module,
+            integrations: [${apiModuleName}Module],
+            display: {
+                name: defaultConfig.displayName || '${apiModuleName}',
+                description: defaultConfig.description || 'Sales & CRM, Marketing',
+                category: defaultConfig.category || 'Sales & CRM, Marketing',
+                detailsUrl: defaultConfig.detailsUrl || 'https://www.${apiModuleName.toLowerCase()}.com',
+                icon: defaultConfig.icon || 'https://friggframework.org/assets/img/${apiModuleName.toLowerCase()}.jpeg',
+            },
+            hasUserConfig: true,
+        });
+
+    static modules = {
+        ${apiModuleName.toLowerCase()}: ${apiModuleName}Module,
+    }
+
+    /**
+     * HANDLE EVENTS
+     */
+    async receiveNotification(notifier, event, object = null) {
+        if (event === 'SEARCH_DEALS') {
+            return this.target.api.searchDeals(object);
+        }
+    }
+
+    /**
+     * ALL CUSTOM/OPTIONAL METHODS FOR AN INTEGRATION MANAGER
+     */
+    async getSampleData() {
+        const res = await this.target.api.${sampleDataMethod}();
+        return { data: res };
+    }
+
+    /**
+     * ALL REQUIRED METHODS FOR AN INTEGRATION MANAGER
+     */
+    async onCreate(params) {
+        // Validate that we have all of the data we need
+        // Set integration status as makes sense. Default ENABLED
+        // TODO turn this into a validateConfig method/function
+        this.record.status = 'ENABLED';
+        await this.record.save();
+        return this.record;
+    }
+
+    async onUpdate(params) {
+        const newConfig = get(params, 'config');
+        const oldConfig = this.record.config;
+        // Just save whatever
+        this.record.markModified('config');
+        await this.record.save();
+        return this.validateConfig();
+    }
+
+    async getConfigOptions() {
+        const options = {}
+        return options;
+    }
+}
+
+module.exports = ${apiModuleName}Integration;`;
+}
+
+module.exports = { getIntegrationTemplate };

package/frigg-cli/validatePackage.js

@@ -0,0 +1,79 @@
+const { execSync } = require('child_process');
+const axios = require('axios');
+const { logError } = require('./logger');
+const inquirer = require('inquirer');
+
+async function searchPackages(apiModuleName) {
+    const searchCommand = `npm search @friggframework/api-module-${apiModuleName} --json`;
+    const result = execSync(searchCommand, { encoding: 'utf8' });
+    return JSON.parse(result);
+}
+
+async function checkPackageExists(packageName) {
+    try {
+        const response = await axios.get(
+            `https://registry.npmjs.org/${packageName}`
+        );
+        return response.status === 200;
+    } catch (error) {
+        return false;
+    }
+}
+
+async function validatePackageExists(packageName) {
+    const packageExists = await checkPackageExists(packageName);
+    if (!packageExists) {
+        throw new Error(`Package ${packageName} does not exist on npm.`);
+    }
+}
+
+const searchAndSelectPackage = async (apiModuleName) => {
+    const searchResults = await searchPackages(apiModuleName || '');
+
+    if (searchResults.length === 0) {
+        logError(`No packages found matching ${apiModuleName}`);
+        process.exit(1);
+    }
+
+    const filteredResults = searchResults.filter((pkg) => {
+        const version = pkg.version
+            ? pkg.version.split('.').map(Number)
+            : [];
+        return version[0] >= 1;
+    });
+
+    if (filteredResults.length === 0) {
+        const earlierVersions = searchResults
+            .map((pkg) => `${pkg.name} (${pkg.version})`)
+            .join(', ');
+        logError(
+            `No packages found with version 1.0.0 or above for ${apiModuleName}. Found earlier versions: ${earlierVersions}`
+        );
+        process.exit(1);
+    }
+
+    const choices = filteredResults.map((pkg) => {
+        return {
+            name: `${pkg.name} (${pkg.version})`,
+            checked: filteredResults.length === 1, // Automatically select if only one result
+        };
+    });
+
+    const { selectedPackages } = await inquirer.prompt([
+        {
+            type: 'checkbox',
+            name: 'selectedPackages',
+            message: 'Select the packages to install:',
+            choices,
+        },
+    ]);
+
+    return selectedPackages.map(choice => choice.split(' ')[0]);
+};
+
+module.exports = {
+    validatePackageExists,
+    checkPackageExists,
+    searchPackages,
+    searchAndSelectPackage,
+};

package/index.js

@@ -1,9 +1,5 @@
-const eslintConfig = require('../../../utils/eslint-config')
-const prettierConfig = require('../../../utils/prettier-config')
-const testEnvironment = require('./test-environment/index');
+const test = require('./test');
 
 module.exports = {
-    eslintConfig,
-    prettierConfig,
-    ...testEnvironment
+    ...test
 }

package/package.json

@@ -1,27 +1,36 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "1.2.0-canary.293.50b9cd8.0",
+  "version": "1.2.0",
   "dependencies": {
     "@babel/eslint-parser": "^7.18.9",
+    "@babel/parser": "^7.25.3",
+    "@babel/traverse": "^7.25.3",
+    "@friggframework/core": "^1.2.0",
+    "@friggframework/test": "^1.2.0",
+    "axios": "^1.7.2",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
     "eslint": "^8.22.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-json": "^3.1.0",
     "eslint-plugin-markdown": "^3.0.0",
     "eslint-plugin-no-only-tests": "^3.0.0",
     "eslint-plugin-yaml": "^0.5.0",
-    "jest-runner-groups": "^2.2.0",
-    "mongodb-memory-server": "^8.9.0"
+    "fs-extra": "^11.2.0",
+    "inquirer": "^10.1.6"
   },
   "devDependencies": {
-    "@friggframework/core": "1.2.0-canary.293.50b9cd8.0",
-    "jest": "^28.1.3",
-    "prettier": "^2.7.1"
+    "@friggframework/eslint-config": "^1.2.0",
+    "@friggframework/prettier-config": "^1.2.0"
   },
   "scripts": {
     "lint:fix": "prettier --write --loglevel error . && eslint . --fix",
     "test": "jest --passWithNoTests # TODO"
   },
+  "bin": {
+    "frigg": "./frigg-cli/index.js"
+  },
   "author": "",
   "license": "MIT",
   "main": "index.js",
@@ -37,5 +46,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "50b9cd8324cb94af601837fcd4661276613ecd47"
+  "gitHead": "9bc9921fe6892cf48ce91702fbf1691646085061"
 }

package/{test-environment → test}/auther-definition-tester.js

@@ -1,7 +1,11 @@
-const { Auther } = require('@friggframework/core/module-plugin/auther');
-const { ModuleConstants } = require('@friggframework/core/module-plugin/ModuleConstants');
-const { createObjectId,connectToDatabase, disconnectFromDatabase } = require('@friggframework/core/database');
-const { createMockApiObject } = require("@friggframework/devtools/test-environment/mock-integration");
+const {
+    Auther,
+    ModuleConstants,
+    createObjectId,
+    connectToDatabase,
+    disconnectFromDatabase,
+} = require('@friggframework/core');
+const { createMockApiObject } = require("./mock-integration");
 
 
 function testAutherDefinition(definition, mocks) {
@@ -48,7 +52,7 @@ function testAutherDefinition(definition, mocks) {
             authCallbackParams = mocks.authorizeResponse || mocks.authorizeParams;
             describe('getAuthorizationRequirements() test', () => {
                 it('should return auth requirements', async () => {
-                    requirements = module.getAuthorizationRequirements();
+                    requirements = await module.getAuthorizationRequirements();
                     expect(requirements).toBeDefined();
                     expect(requirements.type).toEqual(ModuleConstants.authType.oauth2);
                     expect(requirements.url).toBeDefined();

package/test/index.js

@@ -0,0 +1,11 @@
+const {testDefinitionRequiredAuthMethods} = require('./auther-definition-method-tester');
+const {createMockIntegration, createMockApiObject} = require('./mock-integration');
+const { testAutherDefinition } = require('./auther-definition-tester');
+
+
+module.exports = {
+    createMockIntegration,
+    createMockApiObject,
+    testDefinitionRequiredAuthMethods,
+    testAutherDefinition,
+};

package/test/mock-api-readme.md

@@ -0,0 +1,102 @@
+# Mocked Requests Set Up for Your API Module
+
+## Add Tooling to the Test File
+
+Example code:
+
+```js
+const Api = require('./Api');
+const { mockApi } = require('../../../../test/utils/mockApi');
+
+const MockedApi = mockApi(Api, {
+    authenticationMode: 'browser',
+});
+
+describe('DemoNock API', async () => {
+    before(async function () {
+        await MockedApi.initialize({ test: this.test });
+    });
+
+    after(async function () {
+        await MockedApi.clean({ test: this.test });
+    });
+
+    it('tests a nice thing', async () => {
+        const api = await MockedApi.mock();
+        const users = await api.getUsers();
+        expect(users).to.have.length(2);
+    });
+});
+```
+
+Api - the LH API class that is being tested/mocked
+
+mockApi - tool to record/playback requests and automate login to API
+
+MockedApi - Api class with wrapper around it to record/playback requests and automate login to API. `authenticationMode` sets how to handle authentication when recording requests. Browser means it will require a manual step in the browser (uses Authenticator). Client credentials mode gets a token automcaitcally with machine-to-machine token. Manual means the developer will handle authentication manually, like setting an API key. By default mockApi will use the class name of the mocked API to name the output file. This can be overidden by passing in `displayName`.
+test/recorded-requests - the directory where recorded API requests are saved
+
+before - make sure to use the `async function` form here, so we can access mocha's `this` object. The call to `initialize` sets up the tooling for recording/playback
+
+after - same here need to use the `async function` form and pass in `this.test` to `clean`. This stops recording/playback and removes all hooks and other tooling from Node's HTTP code.
+
+test - instead of using `new Api` in your tests, use `await MockedApi.mock`. Any parameters you would normally pass into `new Api` will be passed through with the call to `mock`. The instance of the Api class that is returned will already be authenticated (unless using manual mode).
+
+## Creating new API tests
+
+When running your tests while creating them, use `npm --record-apis=demonock test`.
+
+This tells the tooling to record the requests made while running the tests for the DemoNockApi class.
+
+## Finalizing API tests
+
+When satisified with your tests, run `npm test` without adding the `--record-apis` flag to make sure the recorded requests worked. The tests should pass without needing you to perform a login step in the browser.
+
+## Tests that fail...
+
+Sometimes a "finished" test that was previously working starts to fail. Or, a test passes when it should fail (false negative). There are a few reasons this might happen.
+
+### Test fails after code updates
+
+If you made updates to the code, this may cause a test to fail. In this case the developer doesn't need to update mocks. To make the test pass, the updated code should be fixed, or the test should be updated to reflect the new data shape.
+
+One way to test for this scenario is running `npm test` in the main branch, seeing that all tests pass, and then confirming tests fail in your feature branch. This would show that the test is almost certainly failing due to a change in your branch.
+
+### Test should fail but passes
+
+If a test is passing, but in the "real world" the code is failing, the API response may have changed. Re-record mocks by running tests with `--record-apis=nockdemo`. Hopefully, one or more tests will now fail. These tests and related code should be updated to work with the new API response data shape.
+
+When creating the PR for this update, flag that the mocks were re-recorded so the updated mocks will be sure to be reviewed by another team member as part of code review.
+
+### Mocks in error state
+
+If the recorded files get messed up when updating (sometimes unavoidable under certain error conditions) just `git restore test/recorded-requests` or delete the file(s) in that directory and re-record.
+
+## Miscellaneous Notes
+
+More than one API can be set to record mode at a time: `npm --record-apis=activecampaign,hubspot test`
+
+You can use .only when --record-apis is passed, but only for the root level test suite. Otherwise an error will be thrown to prevent partial recording of the mocks. .skip is fine to use to skip tests that should not be recorded.
+
+CAN UPDATE RECORDED REQUESTS:
+
+```js
+describe('Nock Demo API', () => {
+    it('does x');
+    it.skip('does y');
+});
+```
+
+CANNOT UPDATE RECORDED REQUESTS:
+
+```js
+describe('Nock Demo API', () => {
+    it('does x');
+    it('does y');
+});
+```
+
+## Caveats
+
+-   Client credential mode may only work with Crossbeam currently
+-   Puppet mode (browser automation) for login is not yet implemented