README.md

Goodchat API

GoodChat API is a standalone node.js web service allowing easy integration with smooch.io

• Design notes
  • Features
• Documentation
• Prerequisites
  • System requirements
  • Dependencies
  • Sunshine Conversations
    • Credentials
    • Terminology
    • Guides
      • Steps
    • Steps
• Running the server
  • Manually
  • Using the ready-made CLI script
  • Running in development mode (with autoreload)
  • Running with docker
    • Building the docker image
    • Running the container
    • Automatic db migrations
  • Docker Registry
  • Ngrok
• CLI Configuration
  • Environment variables
• GraphQL
  • Using the playground
• Testing
• Authentication Modes
  • Webhook
• Database
  • Migrations
  • Diagram
    • How to update the database diagram
• Overall Architecture
• License

Design notes

The main purpose of Goodchat's is to integrate multiple chat channels to the GoodCity Project, allowing people to donate goods directly via their existing channels.

That said, GoodChat was designed as a generic and reusable product and therefore holds no shared business logic with the GoodCity. We intend this project, and therefore the code to be:

• Generic
• Reusable
• Configurable

Features

• Integration with Sunshine Conversations
• Webhooks support
• GraphQL Server
• GraphQL Subscriptions
• Configurable authentication methods (allowing easy integration with existing systems)
• Configurable Push Notification support

Documentation

The code-generated documentation can be accessed here

You can re-generate the documentation using the following npm script:

$> npm run document

Updating the README table of contents:

$> npm run doctoc

Prerequisites

System requirements

• Node 14.x
• NPM 7+

NPM 7 or above is required in order to handle peer-dependencies of the apollo server. An older version of NPM can be used but it may require you to install some modules manually

Dependencies

Install the node dependencies using

$> npm install

Sunshine Conversations

Credentials

Running GoodChat requires the following Sunshine Conversation credentials:

• An APP ID - Identifying which Sunshine app this is
• A Key ID - Acts as a username when authenticating to Sunshine
• A Key Secret - Acts as a password when authenticating to Sunshine

Terminology

• Smooch: The omnichat api used was previously known as Smooch, you may see that name in some places as it hasn't been fully renamed to "Sunshine Conversations" yet
• An integration: A chat service which connects to and integrates with Sunshine. e.g Whatsapp, Messenger, ...
• A custom integration: A chat service of our own which connects and integrates with Sunshine. GoodChat is a custom integration (it will auto-register itself)

Guides

How to create a Sunshine Application

Steps

1. Login to your Sunshine Conversations account
2. Head to your dashboard (https://app.smooch.io)
3. On the right side click on the Create new app button

How to create a Sunshine ID/Secret Key pair

Steps

1. Once your app is created, click on it from your dashboard view
2. On the app header bar, click on Settings
3. At the bottom of the settings page, you will find your api keys. Use the Create new API key action for a new one
4. Write down the ID/Secret key pair, as well as the APP ID

Running the server

Manually

You may create an instance of GoodChat, and start it manually as shown below

import goodchat from '@goodcity/api.goodchat'

const [koa, apollo] = await goodchat()

koa.listen(8000, () => {
  console.info('Goodchat is running');
})

Using the ready-made CLI script

An pre-written startup script exists under the /bin folder to run the server. It can be used easily thanks to the following npm scripts:

Build the project

$> npm run build

Run it

$> npm run start

Running in development mode (with autoreload)

$> npm run dev

Running with docker

Building the docker image

docker build . -t goodchat/goodchat

Running the container

docker run -p 8000:8000 -t \
  -e NODE_ENV=<env> \
  -e SMOOCH_APP_ID=<appId> \
  -e SMOOCH_API_KEY_ID=<apiKey> \
  -e SMOOCH_API_KEY_SECRET=<apiSecret> \
  -e DB_HOST=<dbHost> \
  -e DB_NAME=<dbName> \
  -e DB_CREDENTIALS=<dbUsername:dbPassword> \
  -e ENABLE_MIGRATIONS=<true|false> \
  -e REDIS_URL=<redisUrl> \
  goodchat/goodchat

e.g Running in development mode on a Mac with a local postgres and redis

docker run -p 8000:8000 --rm -t \
  -e NODE_ENV=development \
  -e SMOOCH_APP_ID=<appId> \
  -e SMOOCH_API_KEY_ID=<apiKey> \
  -e SMOOCH_API_KEY_SECRET=<apiSecret> \
  -e DB_HOST=host.docker.internal \
  -e ENABLE_MIGRATIONS=true \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  goodchat/goodchat

Automatic db migrations

Setting the ENABLE_MIGRATIONS environment variable to true, will in turn cause the docker container to trigger a database migration on boot.

Docker Registry

Github Actions will automatically push new builds to our registry according to the following rules:

• For the main branch
  • push a latest tag to the registry
  • push a main tag to the registry
• For the live branch
  • push a live tag to the registry
• For new tags
  • push a v<tag> tag to the registry

Ngrok

When running the server in a development environment (NODE_ENV=development), the startup script will initiate an ngrok tunnel in order to have callable webhooks.

CLI Configuration

Environment variables

When running the server from an NPM script, the server can be configured using the following environment variables

Variable	Default	Description
NODE_ENV	<required>	The environment to run the server in
SMOOCH_APP_ID	<required>	Sunshine conversations app id (see guide)
SMOOCH_API_KEY_ID	<required>	Sunshine conversations api key (see guide)
SMOOCH_API_KEY_SECRET	<required>	Sunshine conversations api secret guide
GOODCHAT_HOST	<required>	The hostname of the server (can be omitted in dev mode)
GOODCHAT_AUTH_URL	<required>	The authentication server's endpoint
REDIS_URL	<required>	Redis connection string
DB_NAME	<required>	Postgres database name
DB_HOST	"localhost"	Postgres host
DB_PORT	5432	Postgres port
PORT	8000	The server port
GOODCHAT_APP_NAME	"GoodChat"	The name of the app

NOTE: Some of the required fields are pre-populated for the development environments

GraphQL

Using the playground

• Open on your browser to view the playground
• Make sure the Auth API is running, the default DEV environment will use localhost:3000 as an auth endpoint
• At the bottom of the playground, set the HTTP Headers to include an Authorization header
• Write your queries
• Press play

Here's an example query to get you started

query Conversations {
  conversations {
    id
    type
    messages {
      id
      content
    }
  }
}

Testing

Goodchat specs are written using Mocha, they are all located under the spec/ folder.

Run the specs using the following command:

$> npm run test

Authentication Modes

Webhook

Database

Migrations

Please refer to the Pristma Migrate Flow

A set of npm scripts are available for the common actions:

• db:migrate:new Creates a new migration (without applying it)
• db:migrate:dev Applies migrations to the dev environment
• db:migrate:prod Applies migrations on production (to be used in CD)

Diagram

How to update the database diagram

Step 1: Update the design/schema.dbml file

npm run prisma:generate

Step 2: Copy the DBML to dbdiagram

Step 3: Export into a PNG file and replace the design/dbdiagram.png file

Overall Architecture

License

Copyright © 2020 by Crossroads Foundation Ltd

All rights reserved. No part of this software may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of Crossroads Foundation Ltd. For permission requests, write to Crossroads Foundation Ltd., addressed “Attention: CTO” using the general contact details found on www.crossroads.org.hk.