Merge pull request #67 from shanedewael/fix-export-issues

Fix export issues

Author: Shane DeWael

.github/maintainers_guide.md

@@ -46,16 +46,21 @@ documentation is written manually in markdown in `docs/reference.md`.
 ### Releasing
 
 1.  Create the commit for the release:
+    *  Create and checkout a new branch for the release, for example `rel-v1.0.8`.
     *  Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in `package.json`.
     *  Commit with a message including the new version number. For example `v1.0.8`.
-    *  Tag the commit with the version number. For example `v1.0.8`.
+    *  Push the branch to your fork (`git push username rel-v1.0.8`).
+    *  Open the PR from your fork to the origin repo. Get code review. Merge the PR.
 
 2.  Distribute the release
-    *  Publish to the appropriate package manager. Once you have permission to publish on npm, you
-       can run `npm publish`.
-    *  Create a GitHub Release. This will also serve as a Changelog for the project. Add a
-       description of changes to the Changelog. Mention Issue and PR #'s and @-mention
-       contributors.
+    *  In your local working copy, make sure you fetch from the repo, checkout and update your master branch.
+    *  Make sure the project has been built locally (`npm run build`). It is a good idea to reset the
+       `/node_modules` directory and use a low LTS version of node (e.g. v4.x).
+    *  Publish to npm. Once you have permission to publish on npm, you can run `npm publish`.
+    *  Create a GitHub Release and the associated git tag. When creating a new release, make sure to
+       select the commit with the version number as the commit messsage (e.g. `v1.0.8`). This will also
+       serve as a Changelog for the project. Add a description of changes to the Changelog. Mention Issue
+       and PR #'s and @-mention contributors.
 
 3.  (Slack Internal) Communicate the release internally. Include a link to the GitHub Release.
 

README.md

@@ -1,14 +1,23 @@
-# Slack Events API adapter for Node and Express
+# Slack Events API adapter for Node
 
 [![Build Status](https://travis-ci.org/slackapi/node-slack-events-api.svg?branch=master)](https://travis-ci.org/slackapi/node-slack-events-api)
 [![codecov](https://codecov.io/gh/slackapi/node-slack-events-api/branch/master/graph/badge.svg)](https://codecov.io/gh/slackapi/node-slack-events-api)
 
-This adapter enhances and simplifies Slack's Events API by incorporating useful best practices,
-patterns, and opportunities to abstract out common tasks.
+Build your Slack apps by reacting to messages, emojis, files, and many more types of interesting
+events in the [Events API](https://api.slack.com/events-api). This package will help you start
+with sensible and secure defaults.
 
-We wrote a blog that [explains how](https://medium.com/@SlackAPI/enhancing-slacks-events-api-7535827829ab)
-the Events API can help you, why we built these tools, and how you can use them to build
-production-ready Slack apps.
+The adapter gives you a simple and highly configurable Node-style [EventEmitter](https://nodejs.org/dist/latest/docs/api/events.html#events_class_eventemitter) to attach functions
+to handle events.
+
+*  [Installation](#installation)
+*  [Configuration](#configuration)
+*  [Usage](#usage)
+*  [Examples](#examples)
+*  [Reference Documentation](#reference_documentation)
+*  [Support](#support)
+
+---
 
 ## Installation
 
@@ -18,58 +27,91 @@ $ npm install --save @slack/events-api
 
 ## Configuration
 
-Before you can use the [Events API](https://api.slack.com/events-api) you must
-[create a Slack App](https://api.slack.com/apps/new), and turn on
-[Event Subscriptions](https://api.slack.com/events-api#subscriptions).
+Get started by [creating a Slack App](https://api.slack.com/apps/new) if you haven't already.
+On the **Basic Information** page, in the section for **App Credentials**, note the
+**Signing Secret**. You will need it to initialize the adapter.
+
+> ⚠️ As of `v2.0.0`, the Events API adapter no longer accepts legacy verification tokens.
+You must pass a signing secret [to verify requests from Slack](https://api.slack.com/docs/verifying-requests-from-slack).
+
+Select the **Event Subscriptions** feature, and enable it. Input a **Request URL**.
+
+![Configuring a request URL](support/event-subscriptions.gif)
+
+<details>
+<summary><strong>What's a request URL? How can I get one for development?</strong></summary>
+
+Slack will send requests to your app server each time an event from a subscription is triggered.
+In order to reach your server, you have to tell Slack where your app is listening for those
+requests. This location is the request URL.
 
-In order to complete the subscription, you will need a **Request URL** that can already respond to a
-verification request. This module, combined with the use of a development proxy, can make this
-easier for you.
+If you're just getting started with development, you may not have a publicly accessible URL for
+your app. We recommend using a development proxy, such as [ngrok](https://ngrok.com/) or
+[localtunnel](https://localtunnel.github.io/www/), to generate a URL that can forward requests to
+your local machine. Once you've installed the development proxy of your choice, run it to begin
+forwarding requests to a specific port (for example, 3000).
 
-0.  Force the generation of a Signing Secret: If you just created your Slack App, the Basic
-Information section of your configuration will not yet have a Signing Secret under App
-Credentials. By visiting the Event Subscriptions section and putting a dummy URL into Request
-URL, you will get a verification failure, but also there will now be a **Signing Secret**
-available in the Basic Information section.
+> ngrok: `ngrok http 3000`
 
-> ⚠️ As of `v2.0.0`, the Events API adapter no longer accepts legacy verification tokens. You must pass a signing secret [to verify requests from Slack](https://api.slack.com/docs/verifying-requests-from-slack).
+> localtunnel: `lt --port 3000`
 
-1.  Start the verification tool:
-`./node_modules/.bin/slack-verify --token <signing-secret> [--path=/slack/events] [--port=3000]`. You will
-need to substitute your own Verification Token for `<signing-secret>`. You may also want to choose your own
-`path` and/or `port`.
+![Starting a development proxy](support/ngrok.gif)
 
-2.  Start your development proxy. We recommend using [ngrok](https://ngrok.com/) for its stability,
-but using a custom subdomain will require a paid plan. Otherwise,
-[localtunnel](https://localtunnel.github.io/www/) is an alternative that gives you custom subdomains
-for free.
+The output should show you a newly generated URL that you can use (ngrok will actually show you two
+and we recommend the one that begins with "https"). Let's call this the base URL (for example,
+`https://e0e88971.ngrok.io`)
 
-  > With ngrok: `ngrok http -subdomain=<projectname> 3000`
+To create the request URL, we add the path where our app listens for events onto the end of
+the base URL. If you are using the built-in HTTP server it is set to `/slack/events`. In this
+example the request URL would be `https://e0e88971.ngrok.io/slack/events`. If you are using the
+Express middlware, you can set whichever path you like, just remember to make the path you mount the
+middleware into the application the same as the one you configure in Slack.
+</details>
 
-  > With localtunnel: `lt --port 3000 --subdomain <projectname>`
+<br/>
 
-3.  Input your Request URL into the Slack App configuration settings, in the Event Subscriptions
-section. This URL depends on how you used the previous two commands. For example, using the
-default path and the subdomain name "mybot":
+<details>
+<summary><strong>I'm getting an error about the `challenge` parameter. Help?</strong></summary>
 
-  > With ngrok: `https://mybot.ngrok.io/slack/events`
+Before you can save the subscription, your app will need to respond to a challenge at your chosen
+request URL. I know what you're thinking: 🤔 _How can I respond if I haven't written my app yet?_
+This package comes with a command line tool which starts a server that can properly respond to the
+challenge. If you're using the development proxy as described above, you can run the tool from
+inside your project directory (after this package has been installed) with the following command:
 
-  > With localtunnel: `https://mybot.localtunnel.me/slack/events`
+```bash
+./node_modules/.bin/slack-verify --secret <signing_secret> [--path=/slack/events] [--port=3000]
+```
+
+You'll need to substitute your own signing secret for `<signing_secret>`. The path and port values
+are optional. If your request URL includes a different path, you should specify it with
+`--path=/my/path/here` (no brackets). Similarly, if your development proxy is forwarding requests to
+a different port, you should specify it with `--port=8888` (no brackets). If you're using the
+defaults, you can ignore everything after `<signing_secret>`. You should **only use the command line
+tool in development**. If your app is up and running, the adapter will automatically respond to
+challenges.
+
+You might need to click "Retry" in the Request URL input to ask Slack to send the challenge
+again. Once the request URL is verified, you can terminate the two processes (command line tool and
+development server) with Ctrl+C.
+</details>
+
+<br/>
 
-4.  Once the verification is complete, you can terminate the two processes (verification tool and
-development server). You can proceed to selecting the event types your App needs.
+Add each event type your app requires. In the tables below, you may add Workspace events and Bot events.
+Once you've selected all the event types, be sure to **Save Changes**.
 
-**NOTE:** This method of responding to the verification request should only be used
-**in development**. After you deploy your application to production, you should come back and modify
-your Request URL appropriately.
+Lastly, if you've added event types that require scopes your app did not previously have, you'll need to
+reinstall the app into the workspace(s) from where you'd like Slack to send your app new events. To quickly
+install the app to your Development Workspace, visit the **Install App** page.
 
 ## Usage
 
 The easiest way to start using the Events API is by using the built-in HTTP server.
 
 ```javascript
-// Initialize using verification token from environment variables
-const createSlackEventAdapter = require('@slack/events-api').createSlackEventAdapter;
+// Initialize using signing secret from environment variables
+const { createSlackEventAdapter } = require('@slack/events-api');
 const slackEvents = createSlackEventAdapter(process.env.SLACK_SIGNING_SECRET);
 const port = process.env.PORT || 3000;
 
@@ -87,7 +129,7 @@ slackEvents.start(port).then(() => {
 });
 ```
 
-**NOTE**: To use the example above, you need to add a Team Event such as `message.im` in the Event
+**NOTE**: To use the example above, you need to add a Workspace Event such as `message.im` in the Event
 Subscriptions section of your Slack App configuration settings.
 
 ### Using with Express
@@ -98,8 +140,8 @@ middleware by calling the `expressMiddleware()` method;
 ```javascript
 const http = require('http');
 
-// Initialize using verification token from environment variables
-const createSlackEventAdapter = require('@slack/events-api').createSlackEventAdapter;
+// Initialize using signing secret from environment variables
+const { createSlackEventAdapter } = require('@slack/events-api');
 const slackEvents = createSlackEventAdapter(process.env.SLACK_SIGNING_SECRET);
 const port = process.env.PORT || 3000;
 
@@ -125,18 +167,24 @@ http.createServer(app).listen(port, () => {
 });
 ```
 
-> ⚠️ As of `v2.0.0`, the Events API adapter parses raw request bodies while performing request signing verification. This means developers no longer need to use `body-parser` middleware to parse JSON-encoded requests.
+> ⚠️ As of `v2.0.0`, the Events API adapter parses raw request bodies while performing request signing verification. This means apps no longer need to use `body-parser` middleware to parse JSON-encoded requests.
 
 **NOTE**: To use the example above, you need to add a Team Event such as `message.im` in the Event
 Subscriptions section of your Slack App configuration settings.
 
-## Documentation
+## Examples
+
+*  [Greet And React](examples/greet-and-react) - A ready to run sample app that listens for messages and
+   emoji reactions, and responds to them. It is built on top of the [Express](https://expressjs.com) web framework. It also implements [OAuth](https://api.slack.com/docs/oauth) to demonstate how an app can handle
+   installation to additional workspaces and be structured to handle events from multiple workspaces.
+
+## Reference Documentation
 
 To learn more, see the [reference documentation](docs/reference.md).
 
 ## Support
 
-Need help? Join the [Bot Developer Hangout](http://dev4slack.xoxco.com/) team and talk to us in
+Need help? Join the [Bot Developer Hangout](https://community.botkit.ai) team and talk to us in
 [#slack-api](https://dev4slack.slack.com/messages/slack-api/).
 
 You can also [create an Issue](https://github.com/slackapi/node-slack-events-api/issues/new)

docs/reference.md

@@ -1,11 +1,11 @@
 # Reference Documentation
 
-#### createSlackEventAdapter(_verificationToken_, [_options_])
+#### createSlackEventAdapter(_signingSecret_, [_options_])
 
 A factory method for creating a new `SlackEventAdapter` instance.
 
-The `verificationToken` is a required String parameter which you can find in your Slack App
-configuration once you've assigned a Request URL.
+The `signingSecret` is a required string parameter which you can find in your Slack app's Basic
+Information.
 
 If `options.waitForResponse` is truthy then your SlackEventAdapter will emit a callback function
 with each event so you can control more details about the HTTP response sent back to Slack. See
@@ -21,20 +21,19 @@ details.
 
 ### SlackEventAdapter
 
-This object is responsible for consuming HTTP requests from the Slack Events API (via middleware or
+This object is responsible for consuming HTTP requests from the Slack Events API (via a request handler or
 by creating its own HTTP Server) and emitting events to your application. It inherits from
 [`EventEmitter`](https://nodejs.org/dist/latest-v4.x/docs/api/events.html#events_class_eventemitter),
-whose methods are used for managing listeners. You can also rely on it to process token verification
+whose methods are used for managing listeners. You can also rely on it to verify request signatures
 and other less interesting tasks so you can just focus on handling the events.
 
 As with any EventEmitter, you should attach a handler for the `'error'` event in order to be
-notified of errors. Each error is identified with a `code` property. The dictionary of error codes
-produced by this module can be found at the top level named export `errorCodes`.
+notified of errors.
 
 All other events come from the Slack Events API [Event Types](https://api.slack.com/events/api).
 The signature for your event handler would be `handler(event, [body, ] [headers, ] [respond])`.
 The first argument your handler receives is the event object as described in documentation linked.
-If you initialized the adapter using the `includeBody` option, the next argument will be the entire
+If you initialized the adapter using the `includeBody` option, then next argument will be the entire
 parsed body of the HTTP request. This can be useful to get additional context such as `team_id`,
 `api_app_id`, and more. Similarly, if you initialized the adapter using the `includeHeaders` option,
 the next argument will be an object with key-value pairs for the headers in the HTTP request.
@@ -47,19 +46,29 @@ to HTTP requests until you have invoked the callback. The callback has a signatu
 that Slack should not retry that request, you should set `responseOptions.failWithNoRetry` to a
 truthy value. If you want Slack to send the request to a different URL, you should set the
 value of `responseOptions.redirectLocation` to the URL you want. Lastly, if you'd like to
-set the body of the response, you should set the `responseOptions.content` value to a String of
+set the body of the response, you should set the `responseOptions.content` value to a string of
 body content. EventEmitters allow you to add many handlers, but it's recommended when using the
-`waitForResponse` option that you only have one handler on each event type. You should always handle
-the `error` event too. It's your application's responsibility to make sure that the `respond()`
-callback is invoked exactly once.
+`waitForResponse` option that you only have one handler on each event type. It's your application's
+responsibility to make sure that the `respond()` callback is invoked exactly once.  You should always
+handle the `error` event too - otherwise unhandled errors will crash your app.
 
-#### expressMiddleware([_options_])
+#### requestListener()
+
+This method returns a function that can be attached to the
+[`request` event of an `http.Server`](https://nodejs.org/dist/latest/docs/api/http.html#http_event_request)
+instance. The function also works as the `requestListener` parameter of
+[`http.createServer()`](https://nodejs.org/dist/latest/docs/api/http.html#http_http_createserver_options_requestlistener). This
+function is the primary way to plug the adapter into your own HTTP server, no matter which framework (or not)
+you choose.
+
+#### expressMiddleware()
 
 This method returns a middleware function that can be mounted into your own Express application.
 Remember to mount it at a path that would resolve to your Slack App's Request URL setting.
 
-If `options.propagateErrors` is truthy then the middleware does not send an HTTP response for
-errors, but instead invokes `next(error)` so that your next route handler can service that request.
+If a request is recieved with a body that has already been parsed, this middleware will forward
+an error to the next middleware in the express app. The error will have its `code` property set
+to the value `errorCodes.BODY_PARSER_NOT_PERMITTED`.
 
 #### start(_port_)
 
@@ -74,3 +83,11 @@ This method returns a Promise for an
 server will already be setup to receive requests from the Slack Events API at the default path of
 `/slack/events`. A specific path can be set using the `path` argument. You can start it by calling
 the `listen()` method on the server.
+
+### errorCodes
+
+A dictionary of values that this package assigns to the `code` property if errors.
+
+*  `errorCodes.BODY_PARSER_NOT_PERMITTED`: An incoming request's body had already been parsed before
+   the adapter's express middleware was able to process it. You should remove the `body-parser` middleware from
+   the app or router.

src/adapter.js

@@ -10,7 +10,7 @@ export const errorCodes = {
   BODY_PARSER_NOT_PERMITTED: 'SLACKADAPTER_BODY_PARSER_NOT_PERMITTED_FAILURE',
 };
 
-export default class SlackEventAdapter extends EventEmitter {
+export class SlackEventAdapter extends EventEmitter {
   constructor(signingSecret, options = {}) {
     if (!isString(signingSecret)) {
       throw new TypeError('SlackEventAdapter needs a verification token');
@@ -84,5 +84,9 @@ export default class SlackEventAdapter extends EventEmitter {
   requestListener(middlewareOptions = {}) {
     return createHTTPHandler(this, middlewareOptions);
   }
-
 }
+
+/**
+ * @alias module:adapter
+ */
+export default SlackEventAdapter;

src/index.js

@@ -1,7 +1,6 @@
-import { errorCodes as requestListenerErrorCodes } from './http-handler';
-import SlackEventAdapter from './adapter';
+import { errorCodes as adapterErrorCodes, SlackEventAdapter } from './adapter';
 
-export const errorCodes = requestListenerErrorCodes;
+export const errorCodes = adapterErrorCodes;
 
 export function createSlackEventAdapter(signingSecret, options) {
   return new SlackEventAdapter(signingSecret, options);