Merge pull request #39 from aoberoi/docs-and-example

README rewrite and initial version of express-all-interactions example

Author: aoberoi

.github/maintainers_guide.md

@@ -11,6 +11,12 @@ All you need to work with this project is a recent version of Node.js (current L
 
 ## Tasks
 
+### Debugging
+
+This package uses [`debug`](https://github.com/visionmedia/debug) to log interesting data while
+running. This is a good first step in trying to diagnose an issue. To enable the output, set the
+following environment variable: `DEBUG=@slack/interactive-messages:*`.
+
 ### Building
 
 The source of this project is written in ES2016, a modern JavaScript syntax. In order to allow the
@@ -40,8 +46,12 @@ using the following command: `./node_modules/.bin/mocha test/unit/{test-name}.js
 
 ### Generating Documentation
 
-There is no generated documentation for this project. The README serves as a guide and the reference
-documentation is written manually in markdown in `docs/reference.md`.
+The documentation is generated using the `npm run build:docs` task and output as a single file in
+`docs/reference.md`. The documentation is generated from [JSDoc](http://usejsdoc.org) markup syntax
+(with slight variation for support of the underlying
+[`jsdoc2md`](https://github.com/jsdoc2md/jsdoc-to-markdown) tool). This means that anytime an API
+changes (new methods or changes to existing methods) you must run the above command to output
+changes and commit those changes in git.
 
 ### Releasing
 

.gitignore

@@ -4,3 +4,5 @@ coverage
 .nyc_output
 *.lcov
 *.log
+package-lock.json
+.env

README.md

@@ -0,0 +1,6 @@
+# Required
+SLACK_VERIFICATION_TOKEN=
+SLACK_ACCESS_TOKEN=
+
+# Optional
+PORT=

docs/reference.md

@@ -0,0 +1 @@
+lts/carbon

examples/express-all-interactions/.env.sample

@@ -0,0 +1,48 @@
+# Express All Interacttions Example
+
+This example shows a fully functioning app using the
+[Slack Interactive Messages](https://github.com/slackapi/node-slack-interactive-messages) package.
+
+## Setup
+
+### Create a Slack app
+
+1. Create an app at <https://api.slack.com/apps> (don't close this window, you'll need it later).
+
+### Run the code
+
+1. Choose where you want to run:
+  *  Either clone this repo, navigate to this directory, and run `npm install`
+  *  Or, <a href="https://glitch.com/edit/#!/remix/slack-express-all-interactions-example"><img src="https://cdn.glitch.com/2bdfb3f8-05ef-4035-a06e-2043962a3a13%2Fremix%402x.png?1513093958726" alt="remix button" aria-label="remix" height="33"></a>
+
+2. Set the following environment variables
+  *  `SLACK_VERIFICATION_TOKEN`: Available on your app's _Basic Information_ page in Slack.
+  *  `SLACK_ACCESS_TOKEN`: Available on your app's _Install App_ page in Slack (after installing on your Development Workspace).
+  *  `PORT`: _ONLY_ if you are running locally
+
+3. _ONLY_ If you're running the app locally:
+  *  Make sure you're on a supported version of node (see `.nvmrc` or if you have nvm run `nvm use`)
+  *  Start the app (`npm start`)
+  *  In another terminal window, start ngrok on the same port as the webserver (`ngrok http $PORT`)
+
+### Enable Interactive Components
+
+1. Open your app's _Interactive Components_ page in Slack.
+2. Enable interactive components and enter the Request URL and Options URL (use the same URL for both)
+  *  ngrok URL or Glitch URL + '/slack/actions'
+
+### Create a Slash Command
+
+1. Open your app's _Slash Commands_ page in Slack.
+2. Click "Create New Command"
+  *  In command use: `/interactive-example`
+  *  In request URL use: ngrok URL or Glitch URL + `/slack/commands`
+  *  Click Save
+3. On the _Install App_ page, reinstall in your Development Workspace.
+
+## Usage
+
+The slash command can be triggered in three ways:
+*  `/interactive-example button`: Creates a message with message butons. When you click one, the message updates.
+*  `/interactive-example menu`: Creates a message with a dynamic menu. When you begin typing, the options are narrowed down. Selecting an option updates the message.
+*  `/interactive-exmaple dialog`: Creates a dialog with a user menu input and text input. Sends a confirmation message after submission.

examples/express-all-interactions/.nvmrc

@@ -0,0 +1,53 @@
+const axios = require('axios');
+
+// Create a Promise that resolves after a full turn of the event loop
+// Used since Promise.resolve() will resolve too early
+function resolveLater(value, ms = 0) {
+  return new Promise((resolve) => setTimeout(() => resolve(value), ms));
+}
+
+// A fake users model that resembles what you might have for a database-backed application
+exports.users = {
+  staticUser: {
+    agreedToPolicy: false,
+    setPolicyAgreementAndSave(isAgreed) {
+      this.agreedToPolicy = isAgreed;
+      return resolveLater(this);
+    },
+    kudosCount: 0,
+    incrementKudosAndSave(reason) {
+      this.kudosCount += 1;
+      return resolveLater(this);
+    }
+  },
+  findBySlackId() {
+    return resolveLater(this.staticUser, 50);
+  }
+}
+
+exports.neighborhoods = {
+  apiUrl: 'https://data.sfgov.org/resource/6ia5-2f8k.json',
+  fuzzyFind(text) {
+    return axios({
+      url: this.apiUrl,
+      params: {
+        '$query': `SELECT name WHERE lower(name) LIKE '%${text.toLowerCase()}%'`,
+      },
+    }).then(response => response.data);
+  },
+  find(name) {
+    return axios({
+      url: this.apiUrl,
+      params: {
+        'name': name,
+      },
+    })
+    .then((response) => {
+      const result = response.data[0];
+      if (!result.link) {
+        result.link = `http://www.google.com/search?q=${encodeURIComponent(result.name)}`;
+      }
+      return result;
+    });
+  }
+}

examples/express-all-interactions/README.md

@@ -0,0 +1,21 @@
+{
+  "name": "express-all-interactions",
+  "private": true,
+  "version": "1.0.0",
+  "description": "An example of using Slack Interactive Messages for Node",
+  "main": "index.js",
+  "scripts": {
+    "start": "node -r dotenv/config server",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Ankur Oberoi <[email protected]>",
+  "license": "MIT",
+  "dependencies": {
+    "@slack/client": "^4.1.0",
+    "@slack/interactive-messages": "*",
+    "axios": "^0.18.0",
+    "body-parser": "^1.18.2",
+    "dotenv": "^5.0.1",
+    "express": "^4.16.3"
+  }
+}