Welcome to Frigg Framework Documentation. Frigg is an open source serverless framework for developing integrations at scale. This documentation will help you get started with Frigg, understand its core concepts, and contribute effectively.

Integrations shouldn't be that hard to build and maintain...

Frigg was built with the core principles that user-facing self-serve software integrations should be:

• Easy to Develop

• Inexpensive to run

• Modular and Extensible

• Easy to Scale

• Easy to maintain

This is our answer to the question "hasn't this already been done before?"

Modern stack; easy to understand; fast to develop and deploy; comprehensive enough to cover any use case; fully open source. Interoperability, the way it should be.

Navigating the Docs

These docs should be your go-to resource for all things Frigg related. Secondary are GitHub READMEs and Slack community channels.

We are attempting to embrace a Diátaxis approach to documenting Frigg. Any recommendations are welcome!

In general, there are four main areas of the docs, and four supplemental sections

Main Documentation Areas

Supplemental Documentation Areas

Before you go any further, some quick FAQs

Frigg Explained to Developers

Frigg is the framework you would have built to develop integrations, if you had unlimited resources and time. The added difference is the promise of Open Source-- i.e. a community of developers collaborating to solve the same core set of problems over and over again. This is something you could never do internally.

The Frigg Framework is an opinionated set of development tools, modules, classes, and plugins built with modern software development teams in mind. Frigg will have you up and running out-of-the-box with a flexible set of tools to help rapidly add integrations that your end users can self-serve.

Frigg handles integration listing, authentication, and configuration out-of-the-box, built on a scalable serverless architecture. It includes a growing library of prebuilt API Modules to greatly reduce time to "wow." Along with the core "out of the box" features, the framework contains primitives to help address and flex to any use case.

Getting Started

Aloha! Ready to dive into using Frigg? Let’s get a HubSpot integration (or what HubSpot calls an "app") up and running quickly. This exercise will guide you through setting up a Frigg app locally, integrating it with HubSpot, and experiencing the magic in real-time.

IMPORTANT: Running Create Frigg App requires several software development packages to be installed locally on your computer. While each prerequisite tool is fairly easy to install and configure, you may want to have an engineer available for troubleshooting.

Prerequisites

Before we start, make sure you have:

• Node.js and npm installed

• Git installed

• Docker installed and running on your machine

• A HubSpot Developer Account

• Your favorite IDE installed and ready to use

Overview

Running the create-frigg-app command will generate a Frigg application that is deployable to your own infrastructure accounts in minutes.

Let's get started with Create Frigg App and unpack the magic as we go.

Ready to see Frigg in action? Let's start it up!

Make sure you're in the root directory of your application, then use:

npm run start

Your browser should open to http://localhost:3000 and you should see your Login screen.

Before you continue, make sure that both your frontend and backend are running. An easy way to know is to check if your terminal looks something like this:

If your terminal shows that the backend is also running, you can now experience with your app as an end-user and connect it to see live data coming through!

We've streamlined the setup process to make it as smooth as possible. We've pre-configured several environment variables that apply universally to all Frigg users upon installation. All that's left for you to do is to add your personal HubSpot credentials to connect to your app:

Set up your HubSpot App

To add your HubSpot credentials, open the .env file located in backend/*.env with your IDE and have it ready to paste the information we'll gather in the next steps.

Go to your HubSpot account and create a new HubSpot App, and explore HubSpot if you're not familiar with it. Inside your HubSpot App, head to the "Auth" Tab, next to "App Info," where your can find your app settings.

Now copy your Client ID and Client Secret into the HUBSPOT_CLIENT_ID and HUBSPOT_CLIENT_SECRET fields in the .env file. In the same file, add oauth to the HUBSPOT_SCOPE array.\

In HubSpot's tab, click the +Add new scope button, search for and add the scopes listed in your .env file.

Next, under the "Redirect URLs" section in the "Auth" tab, add http://localhost:3000/redirect/hubspot as a redirect URI.

Save your changes in both the .env file and HubSpot Auth settings.

Finally, from HubSpot's Developer home, create a new developer test account. This will prepare your app for integration and testing.

With all these settings configured, you're now ready to start your Frigg application.

Understanding these core concepts will help you get the most out of the Frigg framework:

Integration

Extends @friggframework/integration-base. An "integration" is how Frigg connects (usually 2) modules for the connection of data and actions. Each service has its own API Module to represent its API to the middleware; use case-specific business logic will also be required.

API Module

Composed of an API Class (generally extending a subclass of @friggframework/requester) and a Module Definition. The API Class handles the requests to external APIs, i.e. authentication, identification, and data retrieval. The Module Definition lets the @friggframework know how to use this API Class as an API Module, such that tokens and other metadata the connection to an external api, can be stored (and refreshed).

Entity (authorizing entity)

A mongoose model extending @friggframework/module-plugin/entity: For a given API Module, the entity is a kind of handle, linking to the relevant credentials, and storing metadata about who/what is authorizing. Retrieving these for a given user is an important gateway to accessing an integration, as most integration actions require one or more authorized API Modules. Most generally, an API Module will be instantiated by passing in an Entity.

Credential

A mongoose model extending @friggframework/module-plugin/credential: For a given API Module, the credential generally stores the tokens or data necessary for making authenticated requests. Multiple Entities can reference the same credential, although 1:1:1 User:Entity:Credential is common.

Data Handling

Frigg manages data securely and efficiently, ensuring it can scale as needed without compromising performance.

Customization

Frigg is highly customizable, letting you tailor modules and integrations to fit your specific needs.

Testing

Frigg supports automated testing with tools like Jest to maintain reliability and performance.

Contribution

Frigg is open-source and thrives on community contributions. Whether you're fixing bugs, writing documentation, or developing new modules, your input is valuable. We encourage users to get involved through our GitHub repository, participate in discussions, and submit pull requests. Every bit of help makes Frigg better for everyone.

Use npx to Create the App

Be sure to double-check that you have all the prerequisite tools installed before attempting this tutorial.

Open your terminal and cd to a location where you want to install your Frigg application. Then run the following command to create a new Frigg app, replacing [my-app-integrations] with your desired app name:

npx create-frigg-app [my-app-integrations]

This process might take a couple of minutes to complete, but at the end of it you should see something like this in your terminal:

Now navigate to your newly created app directory using the following command:

cd [my-app-integrations]

Congrats! You've just successfully scaffolded and installed your Frigg app. Continue with further configuration and customization.

API Modules are the Lego bricks that make Frigg-powered integrations develop faster. An API Module is the code that wraps your target partner's API and represents that API back to Frigg.

Frigg's API Modules are available for free under the MIT license. Translation: if your target partner's logo is in this library already, Frigg just saved you many hours of work.

View our library of v1-ready API Modules.

Read our API Module Definition and Functions reference doc.

If you haven't already, select the "Create account (demo user)" option from the Login menu. A new user will be created for you with the pre-populated data you see on screen.

After receiving a successful confirmation message, you're now able to log in as the Demo User.

You will see a directory with HubSpot as an available connection.

Click on the "Connect" button and complete HubSpot's authorization flow.

When finished, you should see a connected HubSpot card. Now it's time to see your app in action with live data from HubSpot!

"No Data Available" error

Select "Get Sample Data" from the HubSpot app dropdown menu to see live data fetched from your test account.

Note that you might receive a "No data available" message. This is totally normal, given that we didn't add any info to your HubSpot account. There's nothing for our integration to fetch (yet).

Adding Test Data to HubSpot

To fix this, let's add some test data to your HubSpot account. From your HubSpot dashboard, you should go to the "Deals" section in the CRM menu.

Click "Create Deal" to manually add details and save, or use the "Import" option to upload a CSV file with test data.

Once you've added test data, refresh the page and select "Get Sample Data" again. Now you should see Deals data displayed in your app. This confirms that everything is connected and working correctly!

And that’s it! You’ve successfully created and configured your Frigg app with HubSpot. Time to explore and have fun with your new setup!

Now that your Frigg app is installed fresh out-of-the-box and your data is returning from your connected HubSpot account, let's pull data from another section within the same HubSpot account.

Roll up your sleeves- now it’s time to get your hands in the code and customize your integration.

Getting Started

Open your Frigg app project in your IDE. In the backend folder, look for the /src/integrations directory and open your HubSpotIntegration.js file.

Understanding HubSpotIntegration.js

This file is where all the integration magic happens. It tells Frigg which API modules should be connected to use the integration and contains all of the integration logic. Here’s a simple breakdown:

• API Modules: Specifies which API modules are part of the integration.

• Display Information: Defines the display (description, label, categories, etc.) for the frontend.

• Lifecycle Event Handlers: Provides code/handlers for the lifecycle events of the integration (onCreate, onUpdate, onDelete).

• Configuration Options: Determines what users can configure for the integration (getConfigOptions).

• Event Handlers: Expands on the events that should trigger flows in the integration and defines handlers for those events.

• User Actions: Defines user actions available for leveraging the integration.

The power of this file lies in its ability to manage all aspects of the integration from a single point of entry. This allows for quicker development and easier maintenance.

Swapping the Data Source

In the HubSpotIntegration.js file, find the getSampleData method. This is where the backend route fetches the data to display in the frontend. Update the code inside to fetch data from HubSpot’s "Companies" instead of "Deals" by replacing the original code with the following and saving the changes:

async getSampleData() {
        const res = await this.target.api.listCompanies()
        console.log(res.results.length)
        const formatted = res.results.map(company => {
            const formattedCompany = {
                id: company.id,
                createdAt: company.createdAt,
                ...company.properties
            }


            return formattedCompany
        })
        return {data: formatted}

    }

To apply these changes, restart your Frigg app by terminating the backend process (command or ctrl & C) and running:

npm run start

This ensures the Frigg app backend service is updated with the new data fetching logic.

Testing Your Changes

Go to your HubSpot account and add some company data manually or by importing a CSV file. For detailed steps, refer to the Connecting and Seeing Live Data section. Now refresh your app to see the new data displayed.

In our next section, we'll show how easy it is to get up and running with a fully new integration.

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people

• Being respectful of differing opinions, viewpoints, and experiences

• Giving and gracefully accepting constructive feedback

• Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience

• Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind

• Trolling, insulting or derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others' private information, such as a physical or email address, without their explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [INSERT CONTACT METHOD]. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Frigg began as many products and open source projects do- a group of developers trying to solve their own or their clients needs saw common patterns and wanted to memorialize and publish the code they were re-using across projects.

As such, the first few years of Frigg development were largely driven by client projects needs, and we (Left Hook) were only able to move Frigg along in between critical paths for those individual projects. So, we're still working out the kinks in inviting contributing developers.

If you find something you need fixed:

• Go to the relevant repo (Core, API Module Library, Example Apps, Create Frigg App, etc.)

• Create a branch or fork from main

• Make your tweaks

• Submit a PR

Someone from the core maintainer team will review your code and ask questions where needed, as well as provide some guidance if any additional guidance is warranted.

There will be many more instructions in the coming months, especially as we ramp up the ability for folks to add their own API Modules to the mix, or other Frigg Adapters and Extensions.

As always, just ask, and we'll be happy to chat!

We have two ways to interact with Frigg's maintainer team:

1.Github Discussions, the official Frigg message board

2.Invite yourself to the Frigg Community Slack Channel

Module Definition

const API = require('./api');
const authDef = {
    API: API,
    getName: function() {return config.name},
	   moduleName: config.name,
    requiredAuthMethods: {
        // oauth methods
        getToken: async function(api, params) {},
        // for all Auth methods
	 apiPropertiesToPersist: {
            credential: ['access_token', 'refresh_token'],
            entity: []
        },
        getCredentialDetails: async function(api) {}, 
        getEntityDetails: async function(api, callbackParams, tokenResponse, userId) {},
        testAuthRequest: 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`,
    }
};

getToken

For OAuth2, this function typically looks like this:

const code = get(params.data, 'code'); 
 await api.getTokenFromCode(code);

The getTokenFromCode method will make the token request and set the token on the API class.

apiPropertiesToPersist

Named arrays of properties to persist on either the entity or credential. Upon API class instantiation, these will be retrieved from the entity/credential and passed into the API class. Typically, the entity won't need to store anything, and the credential will suffice to persist tokens and other connection metadata.

getEntityDetails

Retrieve and return details about the user/organization that is authorizing requests to this API. Should return something like:

 const userDetails = await api.getUserDetails();
return {
        identifiers: { externalId: userDetails.portalId, user: api.userId },
        details: { name: userDetails.hub_domain },
}

The identifiers define the uniqueness of the entity and how it is looked up. It will automatically be linked to the created credential.

getCredentialDetails

Similar to getEntityDetails, returns:

 const userDetails = await api.getUserDetails();
return {
        identifiers: { externalId: userDetails.portalId },
        details: {}
};

Generally, the entity is looked up first, and the credential is found through that reference.

Requirements

• Filling out the template is required. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion.

• All new code requires tests to ensure against regressions

Description of the Change

Alternate Designs

Benefits

Possible Drawbacks

Applicable Issues