Merge pull request #428 from stevengill/shortcutV2

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,9 +36,18 @@ 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, or legacy action
+app.action({ callback_id: callbackId }, fn);
+
+// Listen for a global shortcut, or message shortcut
+app.shortcut(callbackId, fn);
+
+// Listen for modal view requests
+app.view(callbackId, fn);
+
 // Listen for a slash command
 app.command(commandName, fn);
 
@@ -139,7 +148,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,9 +159,6 @@ 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
-errors](#handling-errors) for more details.
-
 The following is an example of acknowledging a dialog submission:
 
 ```js
@@ -296,7 +302,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,18 @@ 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 sending it to the app, so that the app can add context and pass the event to your 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 Bolt for JavaScript app is created. This method gives the receiver a reference to an `App` to store so that it 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/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, and menu selects, 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">