Shortcut v2

.github/maintainers_guide.md

@@ -32,6 +32,8 @@ To build the docs locally, you can run `bundle exec jekyll serve`.
 
 1.  Create the commit for the release:
     *  Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in `package.json`.
+    *  Update any dependency versions 
+    *  Confirm tests pass by running `npm test`
     *  Commit with a message including the new version number. For example `v1.5.0`.
     *  Tag the commit with the version number. For example `@slack/[email protected]`.
 

README.md

@@ -1,9 +1,9 @@
-# Slack ⚡️ Bolt
+# Slack ⚡️ Bolt for JavaScript
 
 [![Build Status](https://travis-ci.org/slackapi/bolt.svg?branch=master)](https://travis-ci.org/slackapi/bolt)
 [![codecov](https://codecov.io/gh/slackapi/bolt/branch/master/graph/badge.svg)](https://codecov.io/gh/slackapi/bolt)
 
-A framework to build Slack apps, _fast_.
+A JavaScript framework to build Slack apps _in a flash_.
 
 ## Initialization
 
@@ -36,14 +36,22 @@ event, there's a method to attach a listener function.
 // Listen for an event from the Events API
 app.event(eventType, fn);
 
-// Listen for an action from a block element (buttons, menus, etc), dialog submission, message action, or legacy action
+// Listen for an action from a block element (buttons, menus, etc)
 app.action(actionId, fn);
+// Listen for dialog submission, message shortcut, or legacy action
+app.action({ callback_id: callbackId }, fn);
+
+// Listen for a global shortcut
+app.shortcut(callbackId, fn);
 
 // Listen for a slash command
 app.command(commandName, fn);
 
 // Listen for options requests (from menus with an external data source)
 app.options(actionId, fn);
+
+// Listen for modal view requests
+app.view(callbackId, fn);
 ```
 
 There's a special method that's provided as a convenience to handle Events API events with the type `message`. Also, you
@@ -139,7 +147,7 @@ soon as possible.
 
 Depending on the type of incoming event a listener is meant for, `ack()` should be called with a parameter:
 
-*  Block actions and message actions: Call `ack()` with no parameters.
+*  Block actions, global shortcuts, and message shortcuts: Call `ack()` with no parameters.
 
 *  Dialog submissions: Call `ack()` with no parameters when the inputs are all valid, or an object describing the
    validation errors if any inputs are not valid.
@@ -150,7 +158,7 @@ Depending on the type of incoming event a listener is meant for, `ack()` should
    to to update the message with a simple message, or an `object` to replace it with a complex message. Replacing the
    message to remove the interactive elements is a best practice for any action that should only be performed once.
 
-If an app does not call `ack()` within the time limit, Bolt will generate an error. See [handling
+If an app does not call `ack()` within the time limit, Bolt for JavaScript will generate an error. See [handling
 errors](#handling-errors) for more details.
 
 The following is an example of acknowledging a dialog submission:
@@ -296,7 +304,7 @@ app.message(noBotMessages, ({ message }) => console.log(
 ));
 ```
 
-Message subtype matching is common, so Bolt ships with a builtin listener middleware that filters all messages that
+Message subtype matching is common, so Bolt for JavaScript ships with a builtin listener middleware that filters all messages that
 match a given subtype. The following is an example of the opposite of the one above - the listener only sees messages
 that _are_ `bot_message`s.
 

docs/_advanced/conversation_store.md

@@ -6,7 +6,7 @@ order: 3
 ---
 
 <div class="section-content">
-Bolt includes support for a store, which sets and retrieves state related to a conversation. Conversation stores have two methods:
+Bolt for JavaScript includes support for a store, which sets and retrieves state related to a conversation. Conversation stores have two methods:
 * `set()` modifies conversation state. `set()` requires a `conversationId` of type string, `value` of any type, and an optional `expiresAt` of type number. `set()` returns a `Promise`.
 * `get()` fetches conversation state from the store. `get()` requires a `conversationId` of type string and returns a Promise with the conversation’s state.
 

docs/_advanced/logging.md

@@ -6,7 +6,7 @@ order: 7
 ---
 
 <div class="section-content">
-By default, Bolt will log information from your app to the console. You can customize how much logging occurs by passing a `logLevel` in the constructor. The available log levels in order of most to least logs are `DEBUG`, `INFO`, `WARN`, and `ERROR`. 
+By default, Bolt for JavaScript will log information from your app to the console. You can customize how much logging occurs by passing a `logLevel` in the constructor. The available log levels in order of most to least logs are `DEBUG`, `INFO`, `WARN`, and `ERROR`. 
 </div>
 
 ```javascript

docs/_advanced/receiver.md

@@ -6,19 +6,19 @@ order: 8
 ---
 
 <div class="section-content">
-A receiver is responsible for handling and parsing any incoming events from Slack, then sending the event to the Bolt app so it can add context and pass it to your app’s listeners. Receivers must conform to the Receiver interface:
+A receiver is responsible for handling and parsing any incoming events from Slack, then emitting the event so the Bolt for JavaScript app can add context and pass it to your app’s listeners. Receivers must conform to the Receiver interface:
 
 | Method       | Parameters                       | Return type |
 |--------------|----------------------------------|-------------|
 | `init()`     | `app: App`                       | `unknown`   |
 | `start()`    | None                             | `Promise`   |
 | `stop()`     | None                             | `Promise`   |
 
-`init()` is called after it's been passed to a created Bolt app, it's purpose is to give you an instance of bolt so that you can call:
+`init()` is called after it's been passed to a created Bolt for JavaScript app, it's purpose is to give you an instance of bolt so that you can call:
 * `await app.processEvent(event)` whenever your app receives an event from Slack. It will reject if there is an unhandled error.
 * `await app.handleError` whenever you need to route errors to the global error handler. This gives the developer a chance to handle it.
 
-To use a custom receiver, you can pass it into the constructor when initializing your Bolt app. Here is what a basic custom receiver might look like.
+To use a custom receiver, you can pass it into the constructor when initializing your Bolt for JavaScript app. Here is what a basic custom receiver might look like.
 
 For a more in-depth look at a receiver, [read the source code for the built-in Express receiver](https://github.com/slackapi/bolt/blob/master/src/ExpressReceiver.ts)
 </div>

docs/_basic/acknowledging_requests.md

@@ -1,5 +1,5 @@
 ---
-title: Acknowledging events
+title: Acknowledging incoming events
 lang: en
 slug: acknowledge
 order: 7

docs/_basic/ja_ listening_responding_shortcuts.md

@@ -0,0 +1,65 @@
+---
+title: グローバルショートカットのリスニング
+lang: ja-jp
+slug: shortcuts
+order: 8
+---
+
+<div class="section-content">
+[グローバルショートカット](https://api.slack.com/interactivity/shortcuts/using#global_shortcuts)は、テキスト入力エリアや検索バーから起動できる Slack クライアント内の UI エレメントです。`shortcut()` メソッドを使って、グローバルショートカットのイベントをリスニングすることができます。このメソッドには `callback_id` を文字列または正規表現のデータ型で設定します。
+
+グローバルショートカットのイベントは Slack へイベントを受信したことを知らせるために `ack()` メソッドで確認する必要があります。
+
+グローバルショートカットのペイロードは、ユーザーの実行アクションの確認のために[モーダルを開く](#creating-modals)などの用途に使用できる `trigger_id` を含んでいます。グローバルショートカットのペイロードは **チャンネル ID は含んでいない** ことに注意してください。もしあなたのアプリがチャンネル ID を知る必要があれば、モーダル内で [`conversations_select`](https://api.slack.com/reference/block-kit/block-elements#conversation_select) エレメントを使用できます。
+
+⚠️ [メッセージショートカット](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts)は引き続き[`action()` メソッド](#action-listening)を使用するので注意してください。**Bolt の次のメジャーバージョンからはグローバルショートカットもメッセージショートカットも両方とも `shortcut()` メソッドを使用します。**
+</div>
+
+```javascript
+// open_modal というグローバルショートカットはシンプルなモーダルを開く
+app.shortcut('open_modal', async ({ payload, ack, context }) => {
+  // グローバルショートカットリクエストの確認
+  ack();
+  try {
+    // 組み込みの WebClient を使って views.open API メソッドを呼び出す
+    const result = await app.client.views.open({
+      // `context` オブジェクトに保持されたトークンを使用
+      token: context.botToken,
+      trigger_id: payload.trigger_id,
+      view: {
+        "type": "modal",
+        "title": {
+          "type": "plain_text",
+          "text": "My App"
+        },
+        "close": {
+          "type": "plain_text",
+          "text": "Close"
+        },
+        "blocks": [
+          {
+            "type": "section",
+            "text": {
+              "type": "mrkdwn",
+              "text": "About the simplest modal you could conceive of :smile:\n\nMaybe <https://api.slack.com/reference/block-kit/interactive-components|*make the modal interactive*> or <https://api.slack.com/surfaces/modals/using#modifying|*learn more advanced modal use cases*>."
+            }
+          },
+          {
+            "type": "context",
+            "elements": [
+              {
+                "type": "mrkdwn",
+                "text": "Psssst this modal was designed using <https://api.slack.com/tools/block-kit-builder|*Block Kit Builder*>"
+              }
+            ]
+          }
+        ]
+      }
+    });
+    console.log(result);
+  }
+  catch (error) {
+    console.error(error);
+  }
+});
+```

docs/_basic/ja_listening_actions.md

@@ -6,7 +6,7 @@ order: 5
 ---
 
 <div class="section-content">
-アプリでは、ボタンのクリック、メニューの選択、メッセージアクションなどのユーザーアクションを、 `action` メソッドを使用してリスニングすることができます。
+アプリでは、ボタンのクリック、メニューの選択、メッセージショートカットなどのユーザーアクションを、 `action` メソッドを使用してリスニングすることができます。
 
 アクションは文字列型の `action_id` または RegExp オブジェクトでフィルタリングできます。 `action_id` は、Slack プラットフォーム上のインタラクティブコンポーネントの一意の識別子として機能します。 
 

docs/_basic/ja_listening_modals.md

@@ -2,7 +2,7 @@
 title: モーダルビューでの送信のリスニング
 lang: ja-jp
 slug: view_submissions
-order: 11
+order: 12
 ---
 
 <div class="section-content">

docs/_basic/ja_listening_responding_commands.md

@@ -2,7 +2,7 @@
 title: コマンドのリスニングと応答
 lang: ja-jp
 slug: commands
-order: 8
+order: 9
 ---
 
 <div class="section-content">

docs/_basic/ja_listening_responding_options.md

@@ -2,7 +2,7 @@
 title: オプションのリスニングと応答
 lang: ja-jp
 slug: options
-order: 12
+order: 13
 ---
 
 <div class="section-content">

docs/_basic/ja_opening_modals.md

@@ -1,8 +1,8 @@
 ---
-title: モーダルビューのオープン
+title: views.open を使ったモーダルビューのオープン
 lang: ja-jp
 slug: creating-modals
-order: 9
+order: 10
 ---
 
 <div class="section-content">

docs/_basic/ja_updating_pushing_modals.md

@@ -2,7 +2,7 @@
 title: モーダルビューの更新と多重表示
 lang: ja-jp
 slug: updating-pushing-views
-order: 10
+order: 11
 ---
 
 <div class="section-content">

docs/_basic/listening_actions.md

@@ -6,7 +6,7 @@ order: 5
 ---
 
 <div class="section-content">
-Your app can listen to user actions like button clicks, menu selects, and message actions using the `action` method.
+Your app can listen to user actions like button clicks, menu selects, and message shortcuts using the `action` method.
 
 Actions can be filtered on an `action_id` of type string or RegExp object. `action_id`s act as unique identifiers for interactive components on the Slack platform. 
 

docs/_basic/listening_modals.md

@@ -2,7 +2,7 @@
 title: Listening for view submissions
 lang: en
 slug: view_submissions
-order: 11
+order: 12
 ---
 
 <div class="section-content">

docs/_basic/listening_responding_commands.md

@@ -2,7 +2,7 @@
 title: Listening and responding to commands
 lang: en
 slug: commands
-order: 8
+order: 9
 ---
 
 <div class="section-content">

docs/_basic/listening_responding_options.md

@@ -2,7 +2,7 @@
 title: Listening and responding to options
 lang: en
 slug: options
-order: 12
+order: 13
 ---
 
 <div class="section-content">

docs/_basic/listening_responding_shortcuts.md

@@ -0,0 +1,67 @@
+---
+title: Listening and responding to global shortcuts
+lang: en
+slug: shortcuts
+order: 8
+---
+
+<div class="section-content">
+[Global shortcuts](https://api.slack.com/interactivity/shortcuts/using#global_shortcuts) are invokable UI elements within Slack clients, available in the composer and search menus. Your app can use the `shortcut()` method to listen to incoming global shortcut events. The method requires a `callback_id` parameter of type `string` or `RegExp`.
+
+Global shortcuts must be acknowledged with `ack()` to inform Slack that your app has received the event.
+
+Global shortcut payloads include a `trigger_id` which an app can use to [open a modal](#creating-modals) that confirms the action the user is taking. Note that global shortcut payloads do **not** include a channel ID. If your app needs access to a channel ID, you may use a [`conversations_select`](https://api.slack.com/reference/block-kit/block-elements#conversation_select) element within a modal.
+
+⚠️ Note that [message shortcuts](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts) still require apps to use the [`action()` method](#action-listening). **In the next major version of Bolt, both global and message shortcuts will use the `shortcut()` method.**
+</div>
+
+```javascript
+// The open_modal shortcut opens a plain old modal
+app.shortcut('open_modal', async ({ payload, ack, context }) => {
+  // Acknowledge global shortcut request
+  ack();
+
+  try {
+    // Call the views.open method using the built-in WebClient
+    const result = await app.client.views.open({
+      // The token you used to initialize your app is stored in the `context` object
+      token: context.botToken,
+      trigger_id: payload.trigger_id,
+      view: {
+        "type": "modal",
+        "title": {
+          "type": "plain_text",
+          "text": "My App"
+        },
+        "close": {
+          "type": "plain_text",
+          "text": "Close"
+        },
+        "blocks": [
+          {
+            "type": "section",
+            "text": {
+              "type": "mrkdwn",
+              "text": "About the simplest modal you could conceive of :smile:\n\nMaybe <https://api.slack.com/reference/block-kit/interactive-components|*make the modal interactive*> or <https://api.slack.com/surfaces/modals/using#modifying|*learn more advanced modal use cases*>."
+            }
+          },
+          {
+            "type": "context",
+            "elements": [
+              {
+                "type": "mrkdwn",
+                "text": "Psssst this modal was designed using <https://api.slack.com/tools/block-kit-builder|*Block Kit Builder*>"
+              }
+            ]
+          }
+        ]
+      }
+    });
+
+    console.log(result);
+  }
+  catch (error) {
+    console.error(error);
+  }
+});
+```

docs/_basic/opening_modals.md

@@ -1,8 +1,8 @@
 ---
-title: Opening modals
+title: Opening modals using views.open
 lang: en
 slug: creating-modals
-order: 9
+order: 10
 ---
 
 <div class="section-content">

docs/_basic/updating_pushing_modals.md

@@ -2,7 +2,7 @@
 title: Updating and pushing views
 lang: en
 slug: updating-pushing-views
-order: 10
+order: 11
 ---
 
 <div class="section-content">