Add an endpoint to invite users to the Slack team (#5)

Author: arku

.env.example

@@ -0,0 +1,6 @@
+PORT=
+SLACK_TEAM_URL=
+SLACK_SIGNING_SECRET=
+SLACK_USER_TOKEN=
+SLACK_BOT_TOKEN=
+CORS_ORIGINS=

README.md

@@ -1,2 +1,60 @@
-# slack-bot
+# cc-slack-bot
+
 A bot for Coding Coach slack workspace
+
+## Getting Started
+
+### Setting up the Slack App
+
+1. [Create a new Slack team](https://slack.com/get-started#create)
+2. [Create a new Slack App](https://api.slack.com/apps?new_app=1)
+3. Navigate to **OAuth & Permissions** on the left sidebar of your app page
+4. Scroll to the **Scopes** section. Add `chat:write`, `chat:write.public`, `users:read`, `channels:history`, and `app_mentions:read` OAuth scopes to the Bot token scopes and add `admin` to the User token scopes (You need a user token to invite users to the team)
+5. Scroll up to the top of the **OAuth & Permissions** page and click the **Install App to Workspace** button. You’ll be led through Slack’s OAuth UI, where you should allow your app to be installed to your workspace. Once this is done, you should be taken back to the **OAuth & Permissions** page and you should be able to find the user and bot OAuth access tokens. We will need these both in a while
+
+### Development
+
+1. Fork and clone the project
+2. Run `yarn` to install dependencies
+3. Run `cp .env.example .env`
+4. Populate `SLACK_TEAM_URL` in `.env` with the team URL (e.g. https://<TEAM_NAME>.slack.com)
+5. Go to your Slack app (from https://api.slack.com/apps/) and grab the **Signing Secret** from the **Basic Information** page. Populate `SLACK_SIGNING_SECRET` in `.env` with the copied signing secret
+6. Navigate to **OAuth & Permissions** on the left sidebar of your app page. Populate `.env` with the tokens
+
+```
+SLACK_USER_TOKEN=<OAuth Access Token>
+SLACK_BOT_TOKEN=<Bot User OAuth Access Token>
+```
+
+6. Install [ngrok](https://ngrok.com/)
+7. Run `yarn start:dev`
+8. Run `ngrok http <PORT>` in another tab
+9. Set up Event Subscriptions
+
+    Follow https://slack.dev/bolt/tutorial/getting-started#setting-up-events until the URL verification step. Once the URL is verified, add the following **bot** events
+      - `app_mention`
+      - `message.channels`
+      - `team_join`
+
+    Save the changes.
+
+10. You're done :tada: Start hacking :computer:
+
+## Setting up auto-invites
+
+To invite users via `users.admin.invite` method, you need a user token with the `client` scope. Without it, you will receive the following error response when trying to invite a user.
+
+```json
+{"ok":false,"error":"missing_scope","needed":"client","provided":"admin,identify"}
+```
+
+Since the `client` scope is deprecated (legacy), visit https://slack.com/oauth/authorize?&client_id=CLIENT_ID&team=TEAM_ID&install_redirect=install-on-team&scope=admin+client in your browser and authorize your app.
+
+- `TEAM_ID` is the subdomain for your slack team, e.g. coding-coach.slack.com - your `TEAM_ID` is **coding-coach**
+- `CLIENT_ID` can be found in **Basic Information** section for your app
+
+## References
+
+- [Getting started with Bolt](https://slack.dev/bolt/tutorial/getting-started)
+- [Slack Invite Automation](https://github.com/outsideris/slack-invite-automation)
+- [slackApiDoc for `users.admin.invite`](https://github.com/ErikKalkoken/slackApiDoc/blob/master/users.admin.invite.md)

app.js

@@ -1,13 +1,21 @@
-const {App} = require("@slack/bolt")
+const { App } = require("@slack/bolt")
+require('dotenv').config()
+const Receiver = require('./receiver')
+const { inviteUser } = require('./slack')
 const welcomeMsg = require('./messages.json')
 
 const BOT_ICON_URL = `https://raw.githubusercontent.com/Coding-Coach/find-a-mentor/master/public/codingcoach-logo-512.png`
+
 const SLACK_BOT_TOKEN =  process.env.SLACK_BOT_TOKEN
 const SLACK_SIGNING_SECRET  =  process.env.SLACK_SIGNING_SECRET
 
+const receiver = new Receiver({
+  signingSecret: SLACK_SIGNING_SECRET,
+})
+
 const app = new App({
   token: SLACK_BOT_TOKEN,
-  signingSecret: SLACK_SIGNING_SECRET
+  receiver,
 })
 
 const formatMsgForUser = (user) => {
@@ -51,6 +59,22 @@ app.event("team_join", async ({ event, context }) => {
 
 app.message('badger', ({ say }) => say('Badgers? BADGERS? WE DON’T NEED NO STINKIN BADGERS'));
 
+receiver.app.post('/invites', async (req, res) => {
+  try {
+    const response = await inviteUser({
+      email: req.body.email,
+      token: process.env.SLACK_USER_TOKEN
+    })
+    res.json(response)
+  } catch (err) {
+    res.json({
+      ok: false,
+      error: 'server_error',
+      message: err.message,
+    })
+  }
+});
+
 (async () => {
   const server = await app.start(process.env.PORT || 3000);
   console.log('⚡️ CC app is running!', server.address());

package.json

@@ -7,9 +7,17 @@
   "author": "Mohit Tater",
   "license": "MIT",
   "dependencies": {
-    "@slack/bolt": "^1.4.1"
+    "@slack/bolt": "^1.4.1",
+    "body-parser": "^1.19.0",
+    "cors": "^2.8.5",
+    "dotenv": "^8.2.0",
+    "qs": "^6.9.3"
   },
   "scripts": {
-    "start": "node app.js"
+    "start": "node app.js",
+    "start:dev": "nodemon app.js"
+  },
+  "devDependencies": {
+    "nodemon": "^2.0.2"
   }
 }

receiver.js

@@ -0,0 +1,19 @@
+const { ExpressReceiver } = require('@slack/bolt')
+const bodyParser = require('body-parser')
+const cors = require('cors')
+
+class Receiver extends ExpressReceiver {
+  constructor(options) {
+    super(options)
+    this.app.use(bodyParser.json())
+    const corsOrigins = process.env.CORS_ORIGINS
+      ? process.env.CORS_ORIGINS.trim().replace(/\s+/g, '').split(',')
+      : '*'
+    const corsOptions = {
+      origin: corsOrigins
+    }
+    this.app.use(cors(corsOptions))
+  }
+}
+
+module.exports = Receiver

slack.js

@@ -0,0 +1,36 @@
+const axios = require('axios').default
+const qs = require('qs')
+
+const errorMessages = {
+  // Ref: https://github.com/ErikKalkoken/slackApiDoc/blob/master/users.admin.invite.md
+  // When you try to send an invite to an already invited user, Slack returns
+  // "already_in_team_invited_user" error and not "already_invited". Not sure
+  // about the case where it is returned but adding it here just in case.
+  already_invited: 'You have already been invited to join the Slack team. Please check your inbox',
+  already_in_team_invited_user: 'You have already been invited to join the Slack team. Please check your inbox',
+  already_in_team: `You are already a member. Log in to ${process.env.SLACK_TEAM_URL}`,
+  invalid_email: 'Invalid email address',
+  user_disabled: 'Your account has been deactivated',
+}
+
+const inviteUser = async ({
+  email,
+  token,
+}) => {
+  const url = `${process.env.SLACK_TEAM_URL}/api/users.admin.invite`
+  const { data } = await axios.post(url, qs.stringify({ email, token }), {
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+    }
+  })
+
+  if (data.ok) {
+    return { ...data, message: 'Success! Check your email inbox for an invitation' }
+  }
+
+  return { ...data, message: errorMessages[data.error] || data.error }
+}
+
+module.exports = {
+  inviteUser,
+}