dpodstavek/slack-app
Tag 0
No description field found in package.json
  Published by dpodstavek on Friday, June 9th, 2017, 11:37:46 AM
  # Your StdLib Slack App Welcome to your StdLib Slack template! If you're not sure what StdLib ("Standard Library") is, please check out https://stdlib.com. Here we'll walk you through how StdLib works, your Slack App endpoints, and how to handle Slack Slash Commands, Events, and Actions from interactive messages. # Your Project The first thing you'll probably notice is your `functions/` directory. This is your StdLib function directory which maps directly to HTTP endpoints. There are four main functions in your Slack App: - `__main__.js` - `auth.js` - `commands/__main__.js` - `events/__main__.js` We'll go through these in the order listed here. ## Function: `functions/__main__.js` This is your main endpoint, corresponding to `https://username.stdlib.com/service/`. This is, of course, where `username` is your username and `service` is your service name. Any time a function has the filename `__main__.js`, the enclosing folder is used as the route name over HTTP. You can think of it like the default function for a specific directory. Note that when pushing to a development environment (or if you want to access a specific version), this should be reached via: `https://username.stdlib.com/service@dev/main` (if your dev environment is called `dev`, also the default local environment name) or `https://username.stdlib.com/service@0.0.0/main` (if your version is 0.0.0). ### Usage This endpoint generates a template based on the contents of `pages/index.ejs`, which is modifiable and contains your "Add to Slack" button. It is the easiest way to distribute your app to other users. ## Function: `functions/auth.js` This is the OAuth endpoint for your Slack App that verifies another team (or your own) has properly validated the slack app. ### Usage This endpoint processes an OAuth request and returns the contents of `slack/pages/auth.ejs`. (Typically "Success!" if successful.) ## Function: `functions/commands/__main__.js` This is the main **Command Handler** function for handling Slack Slash Commands. You can read more about them here: https://api.slack.com/slash-commands This function is triggered by slack at the following URL: `https://<username>.stdlib.com/<service>@<ver>/commands/:bg` Where `<username>` is your username, `<service>` is the service name and `<ver>` is the environment or semver release of your service. The `:bg` indicates you'd like this function to return an HTTP 2XX code as quickly as possible and do all processing behind the scenes. (Ideal for Slack.) ### Usage To add or modify Slash commands, you'll want to look in the directory `functions/commands/` and create files with the name `functions/commands/NAME.js` where `NAME` is your intended command, and also add them to your Slash Commands list via Slack's Slash Command interface. For the default "hello" command (should be added as `/hello` to your app) you'll notice the following boilerplate code: ```javascript module.exports = (user, channel, text = '', command = {}, botToken = null, callback) => { callback(null, { response_type: 'in_channel', text: `Hello, <@${user}>...\nYou said: ${text}` }); }; ``` In this function, `user` and `channel` are strings representing the user and channel the command was called from. The contents of the command (text) are available in `text`, a full `command` object is available that contains all data passed from slack (https://api.slack.com/slash-commands), and a botToken for your Slack App's bot is passed in (if you want to use it to post additional messages, upload files, etc.). The first parameter passed to `callback` is an error (if present), use `new Error()` when possible. The second parameter is a `chat.postMessage` object, more details can be found here: https://api.slack.com/methods/chat.postMessage. You can test the sample hello command on the command line by running ```shell $ lib .commands.hello test_user general "some text" ``` ## Function: `functions/events/__main__.js` This is the main **Event Handler** function for handling public channel events from Slack's Event API: https://api.slack.com/events This function is triggered by slack at the following URL: `https://<username>.stdlib.com/<service>@<ver>/commands/:bg` Where `<username>` is your username, `<service>` is the service name and `<ver>` is the environment or semver release of your service. The `:bg` indicates you'd like this function to return an HTTP 2XX code as quickly You'll notice an `* @bg params` line in the comments for this function. This means, when executed as a background function, it will return a JSON object mapping to the parameters passed to it (which also passes Slack's `challenge` litmus test). ### Usage This function will delegate incoming commands to their appropriate handler, which can be placed in `functions/events/TYPE.js` or `functions/events/TYPE/__main__.js` as these are functionally equivalent. If there is a subtype involved, `functions/events/TYPE/SUBTYPE.js` or `functions/events/TYPE/SUBTYPE/__main__.js` will be invoked. By default your `functions/events/message/__main__.js` should look like this: ```javascript module.exports = (user, channel, text = '', event = {}, botToken = null, callback) => { // Only send a response to certain messages if (text.match(/hey|hello|hi|sup/i)) { callback(null, { text: `Hey there! <@${user}> said ${text}` }); } else { callback(null, {}); } }; ``` In this function, `user` and `channel` are strings representing the user and channel the event was triggered by. The contents of the command (text) are available in `text`, a full `event` object is available that contains all data passed from slack (https://api.slack.com/events), and a botToken for your Slack App's bot is passed in (if you want to use it to post additional messages, upload files, etc.). The first parameter passed to `callback` is an error (if present), use `new Error()` when possible. The second parameter is a `chat.postMessage` object, more details can be found here: https://api.slack.com/methods/chat.postMessage. You can test the sample message event on the command line by running: ```shell $ lib .events.message test_user general "hello" ``` # Utilities This Slack App template comes with some utility function in `slack/utils`. We'll go over a few of them; - message.js - update_message.js - respond.js - upload.js ## Utility: `utils/message.js` This function has a fingerprint of: ```javascript module.exports = (token, channel, text, callback) => {} ``` Where `token` is your bot token (the token used for the bot response), `channel` as the channel where the response is expected, `text` being a string or `channel.postMessage` object (for more granular control), and `callback` being a function expecting one parameter (an `error`, if applicable) that executes the call. Use this function to get your bot to send messages to users or channels --- that's it. The `token` field should be passed in any `slack/commands` or `slack/events` handlers. ## Utility: `utils/update_message.js` This function has a fingerprint of: ```javascript module.exports = (token, channel, ts, message, callback) => {} ``` Where `token` is your bot token (the token used for the bot response), `channel` as the channel where the response is expected, `ts` as the timestamp of the message being updated, `message` being a string or `chat.update` object (for more granular control) that will replace the original message, and `callback` being a function expecting one parameter (an `error`, if applicable) that executes the call. Use this function to get your bot to update messages in channels. ## Utility: `utils/respond.js` Very similar to `message.js`, this is a Slash Command response that `HTTP POST`s a message to a webhook endpoint instead of creating a new bot message directly. The benefits this has over `message.js`, is that Slash Commands can be used in private channels (or globally, within a team) where applicable. ## Utility: `utils/upload.js` Similar to `message.js`, this function has a fingerprint of: ```javascript module.exports = (token, channel, filename, contentType, file, callback) => {} ``` Where `token` is your bot token, `channel` is the channel to upload a file to, `filename` is the desired filename, `contentType` is the desired content type (i.e. a string like `image/png`), file is a `Buffer` of file contents and `callback` is a function that can handle an optional `err` parameter. # Helpers There are a few helper functions for message formatting, etc. Feel free to look at them at your leisure, we've documented `storage.js` to better understand how team data is stored. ## Helper: `helpers/storage.js` This is a storage helper based upon https://stdlib.com/utils/storage. It is a basic key-value store that saves crucial team (including bot) details about each and every team its installed on, specific to the `SLACK_APP_NAME` field in your `env.json` and your StdLib (https://stdlib.com) account. You should probably avoid interfacing with this function directly, but it should be noted that it is *critical* for the ability to install your app on multiple teams. # That's it! We hope this has served as a welcoming introduction to your Slack App project scaffold on [StdLib](https://stdlib.com) --- happy building!
# Your StdLib Slack App Welcome to your StdLib Slack template! If you're not sure what StdLib ("Standard Library") is, please check out https://stdlib.com. Here we'll walk you through how StdLib works, your Slack App endpoints, and how to handle Slack Slash Commands, Events, and Actions from interactive messages. # Your Project The first thing you'll probably notice is your `functions/` directory. This is your StdLib function directory which maps directly to HTTP endpoints. There are four main functions in your Slack App: - `__main__.js` - `auth.js` - `commands/__main__.js` - `events/__main__.js` We'll go through these in the order listed here. ## Function: `functions/__main__.js` This is your main endpoint, corresponding to `https://username.stdlib.com/service/`. This is, of course, where `username` is your username and `service` is your service name. Any time a function has the filename `__main__.js`, the enclosing folder is used as the route name over HTTP. You can think of it like the default function for a specific directory. Note that when pushing to a development environment (or if you want to access a specific version), this should be reached via: `https://username.stdlib.com/service@dev/main` (if your dev environment is called `dev`, also the default local environment name) or `https://username.stdlib.com/service@0.0.0/main` (if your version is 0.0.0). ### Usage This endpoint generates a template based on the contents of `pages/index.ejs`, which is modifiable and contains your "Add to Slack" button. It is the easiest way to distribute your app to other users. ## Function: `functions/auth.js` This is the OAuth endpoint for your Slack App that verifies another team (or your own) has properly validated the slack app. ### Usage This endpoint processes an OAuth request and returns the contents of `slack/pages/auth.ejs`. (Typically "Success!" if successful.) ## Function: `functions/commands/__main__.js` This is the main **Command Handler** function for handling Slack Slash Commands. You can read more about them here: https://api.slack.com/slash-commands This function is triggered by slack at the following URL: `https://<username>.stdlib.com/<service>@<ver>/commands/:bg` Where `<username>` is your username, `<service>` is the service name and `<ver>` is the environment or semver release of your service. The `:bg` indicates you'd like this function to return an HTTP 2XX code as quickly as possible and do all processing behind the scenes. (Ideal for Slack.) ### Usage To add or modify Slash commands, you'll want to look in the directory `functions/commands/` and create files with the name `functions/commands/NAME.js` where `NAME` is your intended command, and also add them to your Slash Commands list via Slack's Slash Command interface. For the default "hello" command (should be added as `/hello` to your app) you'll notice the following boilerplate code: ```javascript module.exports = (user, channel, text = '', command = {}, botToken = null, callback) => { callback(null, { response_type: 'in_channel', text: `Hello, <@${user}>...\nYou said: ${text}` }); }; ``` In this function, `user` and `channel` are strings representing the user and channel the command was called from. The contents of the command (text) are available in `text`, a full `command` object is available that contains all data passed from slack (https://api.slack.com/slash-commands), and a botToken for your Slack App's bot is passed in (if you want to use it to post additional messages, upload files, etc.). The first parameter passed to `callback` is an error (if present), use `new Error()` when possible. The second parameter is a `chat.postMessage` object, more details can be found here: https://api.slack.com/methods/chat.postMessage. You can test the sample hello command on the command line by running ```shell $ lib .commands.hello test_user general "some text" ``` ## Function: `functions/events/__main__.js` This is the main **Event Handler** function for handling public channel events from Slack's Event API: https://api.slack.com/events This function is triggered by slack at the following URL: `https://<username>.stdlib.com/<service>@<ver>/commands/:bg` Where `<username>` is your username, `<service>` is the service name and `<ver>` is the environment or semver release of your service. The `:bg` indicates you'd like this function to return an HTTP 2XX code as quickly You'll notice an `* @bg params` line in the comments for this function. This means, when executed as a background function, it will return a JSON object mapping to the parameters passed to it (which also passes Slack's `challenge` litmus test). ### Usage This function will delegate incoming commands to their appropriate handler, which can be placed in `functions/events/TYPE.js` or `functions/events/TYPE/__main__.js` as these are functionally equivalent. If there is a subtype involved, `functions/events/TYPE/SUBTYPE.js` or `functions/events/TYPE/SUBTYPE/__main__.js` will be invoked. By default your `functions/events/message/__main__.js` should look like this: ```javascript module.exports = (user, channel, text = '', event = {}, botToken = null, callback) => { // Only send a response to certain messages if (text.match(/hey|hello|hi|sup/i)) { callback(null, { text: `Hey there! <@${user}> said ${text}` }); } else { callback(null, {}); } }; ``` In this function, `user` and `channel` are strings representing the user and channel the event was triggered by. The contents of the command (text) are available in `text`, a full `event` object is available that contains all data passed from slack (https://api.slack.com/events), and a botToken for your Slack App's bot is passed in (if you want to use it to post additional messages, upload files, etc.). The first parameter passed to `callback` is an error (if present), use `new Error()` when possible. The second parameter is a `chat.postMessage` object, more details can be found here: https://api.slack.com/methods/chat.postMessage. You can test the sample message event on the command line by running: ```shell $ lib .events.message test_user general "hello" ``` # Utilities This Slack App template comes with some utility function in `slack/utils`. We'll go over a few of them; - message.js - update_message.js - respond.js - upload.js ## Utility: `utils/message.js` This function has a fingerprint of: ```javascript module.exports = (token, channel, text, callback) => {} ``` Where `token` is your bot token (the token used for the bot response), `channel` as the channel where the response is expected, `text` being a string or `channel.postMessage` object (for more granular control), and `callback` being a function expecting one parameter (an `error`, if applicable) that executes the call. Use this function to get your bot to send messages to users or channels --- that's it. The `token` field should be passed in any `slack/commands` or `slack/events` handlers. ## Utility: `utils/update_message.js` This function has a fingerprint of: ```javascript module.exports = (token, channel, ts, message, callback) => {} ``` Where `token` is your bot token (the token used for the bot response), `channel` as the channel where the response is expected, `ts` as the timestamp of the message being updated, `message` being a string or `chat.update` object (for more granular control) that will replace the original message, and `callback` being a function expecting one parameter (an `error`, if applicable) that executes the call. Use this function to get your bot to update messages in channels. ## Utility: `utils/respond.js` Very similar to `message.js`, this is a Slash Command response that `HTTP POST`s a message to a webhook endpoint instead of creating a new bot message directly. The benefits this has over `message.js`, is that Slash Commands can be used in private channels (or globally, within a team) where applicable. ## Utility: `utils/upload.js` Similar to `message.js`, this function has a fingerprint of: ```javascript module.exports = (token, channel, filename, contentType, file, callback) => {} ``` Where `token` is your bot token, `channel` is the channel to upload a file to, `filename` is the desired filename, `contentType` is the desired content type (i.e. a string like `image/png`), file is a `Buffer` of file contents and `callback` is a function that can handle an optional `err` parameter. # Helpers There are a few helper functions for message formatting, etc. Feel free to look at them at your leisure, we've documented `storage.js` to better understand how team data is stored. ## Helper: `helpers/storage.js` This is a storage helper based upon https://stdlib.com/utils/storage. It is a basic key-value store that saves crucial team (including bot) details about each and every team its installed on, specific to the `SLACK_APP_NAME` field in your `env.json` and your StdLib (https://stdlib.com) account. You should probably avoid interfacing with this function directly, but it should be noted that it is *critical* for the ability to install your app on multiple teams. # That's it! We hope this has served as a welcoming introduction to your Slack App project scaffold on [StdLib](https://stdlib.com) --- happy building!
The "Add to Slack" landing page for your app. To modify the template, check out /pages/index.ejs.
  info
context
disabled
bg
info
  parameters
(no parameters expected)
  code
Authorization HTML page to grant Slack App OAuth Permission To modify the template, check out /pages/auth.ejs.
  info
context
disabled
bg
info
  parameters (click to modify)
{string}
code
= null
Slack-provided authorization code
{string}
error
= ""
Slack-provided error
  code
Slack Slash Command Handler: This function receives slash command from Slack and dispatches the appropriate handler. You should use this function as the endpoint for all commands, and place commands in /functions/commands/NAME.js, where NAME is the name of your command. You can test individual slash commands from the command line with: $ lib .commands.NAME [username] [channel] [text]
  info
context
enabled
bg
info
  parameters
(no parameters expected)
  code
/hello Basic "Hello World" command. All Commands use this template, simply create additional files with different names to add commands. See https://api.slack.com/slash-commands for more details.
  info
  parameters (click to modify)
{string}
user
(required)
The user id of the user that invoked this command (name is usable as well)
{string}
channel
(required)
The channel id the command was executed in (name is usable as well)
{string}
text
= ""
The text contents of the command
{object}
command
= {}
The full Slack command object
{string}
botToken
= null
The bot token for the Slack bot you have activated
  code
/late You are late
  info
  parameters (click to modify)
{string}
user
= "somebot"
(no description)
{integer}
delay
(required)
(no description)
{string}
reason
(required)
(no description)
  code
Slack Event Handler: This function receives events from Slack and dispatches the appropriate handler. If an event has no subtype, it will invoke /functions/events/TYPE.js or /functions/events/TYPE/__main__.js, otherwise it will invoke /functions/events/TYPE/SUBTYPE.js. You can test individual events from the command line with: $ lib .events.TYPE.SUBTYPE [username] [channel] [text] The "@bg params" line below tells StdLib that when this function is invoked as a background function over HTTP it should just respond with whatever parameters were passed in as a JSON object. (This handles Slack's "challenge" parameter.)
  info
context
enabled
bg
params
  parameters
(no parameters expected)
  code
message event All events use this template, simply create additional files with different names to add event responses See https://api.slack.com/events-api for more details.
  info
  parameters (click to modify)
{string}
user
(required)
The user id of the user that invoked this event (name is usable as well)
{string}
channel
(required)
The channel id the event was executed in (name is usable as well)
{string}
text
= ""
The text contents of the event
{object}
event
= {}
The full Slack event object
{string}
botToken
= null
The bot token for the Slack bot you have activated
  code
channel_join event See https://api.slack.com/events-api for more details.
  parameters (click to modify)
{string}
user
(required)
The user id of the user that invoked this event (name is usable as well)
{string}
channel
(required)
The channel id the event was executed in (name is usable as well)
{string}
text
= ""
The text contents of the event
{object}
event
= {}
The full Slack event object
{string}
botToken
= null
The bot token for the Slack bot you have activated
  code