SnoozePlus-Intercom-Integration

Snooze+ is an inbox app for Intercom used to automate sending delayed responses to customers.

Table of Contents

• Local Development
• Development Tools
  • Code Quality
  • Debugging
  • Testing
• Database
  • Setup
  • Migrations
  • Schema Overview
  • Database Access
• Project Structure
• Scripts
• Steps To Deploy Application
• Application Hosting - Opalstack Node.js
  • Controlling the app
    • Starting the app
    • Stopping the app
• Authentication
• Required Environment Variables
• Tools and Dependencies

Local Development

1. Install Node.js and npm: Ensure that Node.js (version 20.x or higher) and npm (version 6.x or higher) are installed on your machine download Node.js
2. Clone the Repository: Clone this repo to your machine:
3. Navigate to the Project Directory: Navigate to the root directory of the application:
4. Create Environment Variables File: Create an .env.local file with the required environment variables
5. Install Dependencies: Run the command npm install to install dependencies
6. Setup Database: Setup a PostgreSQL database and run the migrations
7. Start the Application: Run the command npm run dev to start the application
8. Access the Application: Access the application at http://localhost:8706
9. Intercom: Ensure that you have an Intercom account with an Inbox App created

Development Tools

Code Quality

The following tools are used to maintain code quality:

• ESLint for code linting
• Prettier for code formatting
• TypeScript for static type checking

Debugging

VS Code launch configurations are provided for:

• Debugging the application
• Debugging tests

Testing

Jest is configured for testing with:

• TypeScript support
• Environment variables from .env.test
• Watch mode for development

Database

The application uses PostgreSQL as its relational database to store user and message data.

Setup

1. Install PostgreSQL: Ensure that PostgreSQL is installed on your system (download PostgreSQL)
2. Create a Database: Create a new PostgreSQL database for the application
3. Configure Environment Variables: Update your .env file with your database connection details
4. Run Migrations: Apply the database migrations to create the necessary tables

Migrations

The application uses Flyway for database migrations. Migration scripts are located in the database/migrations/ directory. To apply migrations, navigate to the database/ directory and run:

cd database
flyway migrate

Schema Overview

The database consists of two main tables:

• users: Stores user authentication and authorization data
• messages: Stores scheduled messages to be sent to customers

Database Access

Database interactions are handled using the pg library.

Project Structure

database/
  migrations/        # Database migrations
  schema-model/      # Database schema models
scripts/             # Deployment scripts
src/
  config/            # Configuration files
  controllers/       # Controllers for handling HTTP requests
  middleware/        # Custom middleware functions
  models/            # Database models or schemas
  routes/            # Route definitions
  services/          # Business logic and data access logic
  types/             # TypeScript type definitions
  utilities/         # Utility functions and helpers
  app.ts             # Main application file

Scripts

Script	Description
npm start	Start the application
npm run dev	Start the application in development mode
npm run type-check	Check for type errors
npm run dev-build	Build for development
npm run prod-build	Build for production with tests
npm run copy-files	Copy additional files to dist
npm run lint	Run linter and fix issues
npm run test	Run tests in watch mode

Steps To Deploy Application

1. Clone this repo to your local machine
2. Navigate to the root directory of the application
3. Create a .env.production file with the required environment variables
4. Run the command npm run prod-build to get the application files ready for deployment
5. Start a SSH session with the server
6. On the server, run the stop script
7. Start a SFTP session with the server
8. Upload files from your local machine to the server
   • Local file path: ./SnoozePlus-Intercom-Integration/dist/
   • Remote server path: /home/activelabs/apps/snoozeplus/
9. Go back to the SSH session and on the server, run the start script

Application Hosting - Opalstack Node.js

Application server: opal7.opalstack.com Database server: opal7.opalstack.com

Controlling the app

The app can be controlled using the start and stop scripts. Each script takes a single argument for the app name (e.g. snoozeplus_dev, snoozeplus). If no argument is passed the default app name is snoozeplus.

1. Navigate to the directory ~/apps/snoozeplus/
2. Run the start or stop script with the app name

Starting the app

To start the app, run:

./start [app_name]

Stopping the app

Stop the app by running:

./stop [app_name]

Authentication

The application uses OAuth 2.0 for authentication with Intercom utilizing Passport with the Intercom Strategy. Here is an overview of how the authentication process works:

1. Login: When a user attempts to access a protected route, they are redirected to the Intercom login page
2. Authorization: The user logs in to their Intercom account and authorizes the application to access their Intercom data
3. Callback: After authorization, Intercom redirects the user back to the application with an authorization code
4. Token Exchange: The application exchanges the authorization code for an access token
5. Session Management: The access token is encrypted and stored in the user's session, with the session being managed using express-session
6. Authenticated Requests: The access token is used to make authenticated requests to the Intercom API on behalf of the user

IP Validation

The application validates incoming requests to ensure they originate from allowed Intercom Canvas Kit IP addresses or Intercom Webhook Notification IP addresses. The allowed IP addresses are specified in the IP_ALLOWLIST environment variable, which should be a comma-separated list of IP addresses.

Signature Validation

The application validates the signatures of incoming requests to ensure they are sent by Intercom. This is done using the X-Body-Signature header for Canvas Kit requests and the X-Hub-Signature header for Webhook Notification requests.

Required Environment Variables

The environment variables for this application can be found in the .env.sample file.

All of the environment variables are required for the application to run correctly. Note that NODE_ENV must be set to production in the .env.production file.

Tools and Dependencies

The application uses the following tools:

• Node.js: JavaScript runtime environment
• TypeScript: Typed superset of JavaScript that compiles to plain JavaScript
• ESLint: Linting utility for JavaScript and TypeScript
• Prettier: Opinionated code formatter
• Jest: JavaScript testing framework
• PostgreSQL: Open-source relational database
• Flyway: Database schema migration and versioning tool

The application leverages the following packages:

• Express: Web framework for Node.js
• Express Session: Session middleware for Express
• Morgan: HTTP request logger middleware for Node.js
• Winston: Logging library for Node.js
• Logtail: Cloud-based logging solution
• Passport: Authentication middleware for Node.js
• Passport-Intercom: Intercom authentication strategy for Passport
• Node.js Crypto Module: Provides cryptographic functionality
• Node Fetch: A light-weight module that brings Fetch API to Node.js
• Node Schedule: Cron-like and not-cron-like job scheduler for Node.js
• Retry: Abstraction for exponential and custom retry strategies
• pg: PostgreSQL client for Node.js