Merge branch 'master' into fix-member_joined/left_channel-event-not-f…

…iring-for-own-bot

.github/maintainers_guide.md

@@ -0,0 +1,93 @@
+# Maintainers Guide
+
+This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain
+this project. If you use this package within your own software as is but don't plan on modifying it, this guide is
+**not** for you.
+
+## Tools
+
+All you need to work with this project is a supported version of [Node.js](https://nodejs.org/en/)
+(see `package.json` field "engines") and npm (which is distributed with Node.js).
+
+## Tasks
+
+### Testing
+
+This package has unit tests for most files in the same directory the code is in with the suffix `.spec` (i.e. `exampleFile.spec.ts`). You can run the entire test suite using the npm script `npm test`. This command is also executed by Travis, the continuous integration service, for every Pull Request and branch. The coverage is computed with the `codecode` package. The tests themselves are run using the `mocha` test runner.
+
+Test code should be written in syntax that runs on the oldest supported Node.js version. This ensures that backwards compatibility is tested and the APIs look reasonable in versions of Node.js that do not support the most modern syntax.
+
+A useful trick for debugging inside tests is to use the Chrome Debugging Protocol feature of Node.js to set breakpoints and interactively debug. In order to do this you must run mocha directly. This means that you should have already linted the source (`npm run lint`), manually. You then run the tests using the following command: `./node_modules/.bin/mocha test/{test-name}.js --debug-brk --inspect` (replace {test-name} with an actual test file).
+
+### Generating Documentation
+
+The documentation is built using [Jekyll](https://jekyllrb.com/) and hosted with GitHub Pages.
+The source files are contained in the `docs` directory. They are broken up into the `_basic`, `_advanced`, and `_tutorials` directories depending on content's nature.
+
+All documentation contains [front matter](https://jekyllrb.com/docs/front-matter/) that indicates the section's title, slug (for header), respective language, and if it's not a tutorial it contains the order it should appear within it's respective section (basic or advanced).
+
+To build the docs locally, you can run `bundle exec jekyll serve`.
+
+### Releasing
+
+1. Create the commit for the release:
+ * 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`.
+
+2. Merge into master repository
+ * Create a pull request with the commit that was just made. Be certain to include the tag. For
+ example: `git push username master:rel-v1.0.8 && git push --tags username`.
+ * Once tests pass and a reviewer has approved, merge the pull request. You will also want to
+ update your local `master` branch.
+
+3. Distribute the release
+ * Publish to the package manager. Once you have permission to publish on npm, you can run `npm publish`.
+ * Create a GitHub Release with release notes. Release notes should mention contributors (@-mentions) and issues/PRs (#-mentions) for the release.
+
+4. (Slack Internal) Communicate the release internally. Include a link to the GitHub Release.
+
+5. Announce on community.slack.com in #slack-api
+
+## Workflow
+
+### Versioning and Tags
+
+This project is versioned using [Semantic Versioning](http://semver.org/), particularly in the
+[npm flavor](https://docs.npmjs.com/getting-started/semantic-versioning). Each release is tagged
+using git.
+
+### Branches
+
+`master` is where active development occurs. Long running named feature branches are occasionally
+created for collaboration on a feature that has a large scope (because everyone cannot push commits
+to another person's open Pull Request). At some point in the future after a major version increment,
+there may be maintenance branches for older major versions.
+
+### Issue Management
+
+Labels are used to run issues through an organized workflow. Here are the basic definitions:
+
+* `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been
+ documented and the issue has been reproduced.
+* `enhancement`: A feature request for something this package might not already do.
+* `docs`: An issue that is purely about documentation work.
+* `tests`: An issue that is purely about testing work.
+* `needs feedback`: An issue that may have claimed to be a bug but was not reproducible, or was otherwise missing some information.
+* `discussion`: An issue that is purely meant to hold a discussion. Typically the maintainers are looking for feedback in this issues.
+* `question`: An issue that is like a support request because the user's usage was not correct.
+* `semver:major|minor|patch`: Metadata about how resolving this issue would affect the version number.
+* `security`: An issue that has special consideration for security reasons.
+* `good first contribution`: An issue that has a well-defined relatively-small scope, with clear expectations. It helps when the testing approach is also known.
+* `duplicate`: An issue that is functionally the same as another issue. Apply this only if you've linked the other issue by number.
+
+**Triage** is the process of taking new issues that aren't yet "seen" and marking them with a basic
+level of information with labels. An issue should have **one** of the following labels applied:
+`bug`, `enhancement`, `question`, `needs feedback`, `docs`, `tests`, or `discussion`.
+
+Issues are closed when a resolution has been reached. If for any reason a closed issue seems
+relevant once again, reopening is great and better than creating a duplicate issue.
+
+## Everything else
+
+When in doubt, find the other maintainers and ask.

docs/_advanced/ja_logging.md

@@ -32,6 +32,7 @@ const app = new App({
 | メソッド | パラメーター | 戻り値の型 |
 |--------------|-------------------|-------------|
 | `setLevel()` | `level: LogLevel` | `void` |
+| `getLevel()` | なし | `string` (値は `error`, `warn`, `info`, `debug` のいずれか) |
 | `setName()` | `name: string` | `void` |
 | `debug()` | `...msgs: any[]` | `void` |
 | `info()` | `...msgs: any[]` | `void` |

docs/_advanced/logging.md

@@ -32,6 +32,7 @@ If you want to send logs to somewhere besides the console or want more control o
 | Method | Parameters | Return type |
 |--------------|-------------------|-------------|
 | `setLevel()` | `level: LogLevel` | `void` |
+| `getLevel()` | None | `string` with value `error`, `warn`, `info`, or `debug` |
 | `setName()` | `name: string` | `void` |
 | `debug()` | `...msgs: any[]` | `void` |
 | `info()` | `...msgs: any[]` | `void` |

docs/_basic/ja_listening_modals.md

@@ -0,0 +1,55 @@
+---
+title: モーダルビューでの送信のリスニング
+lang: ja-jp
+slug: view_submissions
+order: 11
+---
+
+<div class="section-content">
+<a href="https://api.slack.com/reference/block-kit/views">モーダルビューのペイロード</a>が入力のブロックを含む場合、その入力値を受け取るために <code>view_submission</code> のイベントをリスニングする必要があります。<code>view_submission</code> イベントをリスニングするためには、組み込みの <code>view()</code> メソッドを使用します。
+
+<code>view()</code> メソッドは、文字列型または <code>RegeExp</code>型 の <code>callback_id</code> を必要とします。
+
+<code>input</code> ブロックの値は <code>state</code> オブジェクトを参照することで取得できます。<code>state</code> 内には <code>values</code> というオブジェクトがあり、これは <code>block_id</code> と一意な <code>action_id</code> に紐づける形で入力値を保持しています。
+
+より詳細な情報は <a href="https://api.slack.com/block-kit/surfaces/modals#handling_submissions">API ドキュメント</a>を参照してください。
+</div>
+
+```javascript
+// モーダルビューでのデータ送信イベントを処理します
+app.view('view_b', async ({ ack, body, view, context }) => {
+ // モーダルビューでのデータ送信イベントを確認
+ ack();
+
+ // 入力値を使ってやりたいことをここで実装 - ここでは DB に保存して送信内容の確認を送っている
+
+ // block_id: block_1 という input ブロック内で action_id: input_a の場合の入力
+ const val = view['state']['values']['block_1']['input_a'];
+ const user = body['user']['id'];
+
+ // ユーザーに対して送信するメッセージ
+ let msg = '';
+ // DB に保存
+ const results = await db.set(user.input, val);
+
+ if (results) {
+ // DB への保存が成功
+ msg = 'Your submission was successful';
+ } else {
+ msg = 'There was an error with your submission';
+ }
+
+ // ユーザーにメッセージを送信
+ try {
+ app.client.chat.postMessage({
+ token: context.botToken,
+ channel: user,
+ text: msg
+ });
+ }
+ catch (error) {
+ console.error(error);
+ }
+
+});
+```

docs/_basic/ja_listening_responding_options.md

@@ -2,15 +2,15 @@
 title: オプションのリスニングと応答
 lang: ja-jp
 slug: options
-order: 9
+order: 12
 ---
 
 <div class="section-content">
 `option()` メソッドは、Slack からの着信オプションリクエストペイロードをリッスンします。 [`actions()` と同様](#action-listening)に、 `action_id` オブジェクトまたは制約付きオブジェクトが必要です。
 
 `external_select` メニューには `action_id` を使用することをお勧めしますが、ダイアログはまだ Block Kit をサポートしていないため、制約オブジェクトを用いて `callback_id` でフィルタリングする必要があります。
 
-オプションリクエストに応答するためには、適切なオプションを指定して `ack()` を実行する必要があります。[external_select の応答の例](https://api.slack.com/reference/messaging/block-elements#external-select)も[ダイアログ応答の例](https://api.slack.com/dialogs#dynamic_select_elements_external)も API サイトで参照できます
+オプションリクエストに応答するためには、適切なオプションを指定して `ack()` を実行する必要があります。[external_select の応答の例](https://api.slack.com/reference/messaging/block-elements#external-select)も[ダイアログ応答の例](https://api.slack.com/dialogs#dynamic_select_elements_external)も API サイトで参照できます。
 </div>
 
 ```javascript

docs/_basic/ja_opening_modals.md

@@ -0,0 +1,79 @@
+---
+title: モーダルビューのオープン
+lang: ja-jp
+slug: creating-modals
+order: 9
+---
+
+<div class="section-content">
+
+<a href="https://api.slack.com/block-kit/surfaces/modals">モーダルビュー</a>は、ユーザー情報を収集したり、情報の動的な表示を実現するためのインタフェースです。モーダルビューは、適切な <code>trigger_id</code> と <a href="https://api.slack.com/reference/block-kit/views">ビュー部分のペイロード</a> を組み込みの API クライアントによる <a href="https://api.slack.com/methods/views.open"><code>views.open</code></a> メソッドの呼び出しに渡すことでオープンすることができます。
+
+<code>trigger_id</code> はコマンド、ボタンの押下、メニューの選択などによって Request URL に送信されたペイロードの項目として入手することができます。
+
+モーダルビューの作成についてのより詳細な情報は <a href="https://api.slack.com/block-kit/surfaces/modals#composing_modal">API ドキュメント</a>を参照してください。
+</div>
+
+```javascript
+// コマンド起動をリッスン
+app.command('/ticket', ({ ack, payload, context }) => {
+ // コマンドのリクエストを確認
+ ack();
+
+ try {
+ const result = app.client.views.open({
+ token: context.botToken,
+ type: 'modal',
+ // 適切な trigger_id を受け取ってから 3 秒以内に渡す
+ trigger_id: payload.trigger_id,
+ // view の値をペイロードに含む
+ view: {
+ // callback_id が view を特定するための識別子
+ callback_id: 'view_1',
+ title: {
+ type: 'plain_text',
+ text: 'Modal title'
+ },
+ blocks: [
+ {
+ type: 'section',
+ text: {
+ type: 'mrkdwn',
+ text: 'Welcome to a modal with _blocks_'
+ },
+ accessory: {
+ type: 'button',
+ text: {
+ type: 'plain_text',
+ text: 'Click me!'
+ },
+ action_id: 'button_abc'
+ }
+ },
+ {
+ type: 'input',
+ block_id: 'input_c',
+ label: {
+ type: 'plain_text',
+ text: 'What are your hopes and dreams?'
+ },
+ element: {
+ type: 'plain_text_input',
+ action_id: 'dreamy_input',
+ multiline: true
+ }
+ }
+ ],
+ submit: {
+ type: 'plain_text',
+ text: 'Submit'
+ }
+ }
+ });
+ console.log(result);
+ }
+ catch (error) {
+ console.error(error);
+ }
+});
+```

docs/_basic/ja_updating_pushing_modals.md

@@ -0,0 +1,62 @@
+---
+title: モーダルビューの更新と多重表示
+lang: ja-jp
+slug: updating-pushing-views
+order: 10
+---
+
+<div class="section-content">
+モーダルビューの表示は、複数のビューをスタックとして保持する場合があります。<a href="https://api.slack.com/methods/views.open">`views.open`</a> という API を呼び出すと、まずルートのモーダルビューが生成されます。その最初の呼び出しの後で、<a href="https://api.slack.com/methods/views.update">`views.update`</a> によって動的にそのビューを書き換えたり、<a href="https://api.slack.com/methods/views.push">`views.push`</a> で新しいビューをその上に積み重ねて表示したりといったことができます。
+
+<strong><code>views.update</code></strong><br>
+モーダルビューを更新するには組み込みの API クライアントを使って <code>views.update</code> を呼び出します。この API 呼び出しにはそのビューをオープンしたときに生成された <code>view_id</code> と、書き換えられた <code>blocks</code> の配列を渡します。ユーザーが既存のビューの中にある要素とインタラクションを行なったことをきっかけにビューを更新する場合は、そのリクエストの <code>body</code> に <code>view_id</code> が含まれています。
+
+<strong><code>views.push</code></strong><br>
+ビューのスタックに新しいビューを積み重ねるには、組み込みの API クライアントを使って <code>views.push</code> を呼び出します。この API 呼び出しには、適切な <code>trigger_id</code> と新しく生成する <a href="https://api.slack.com/reference/block-kit/views">ビュー部分のペイロード</a>を渡します。`views.push` の引数は <a href="#creating-modals">ビューをオープンするとき</a>と同様です。最初のモーダルビューをオープンした後、その上にさらに二つまで追加のビューをスタックに積み重ねることができます。
+
+より詳細な情報は <a href="https://api.slack.com/block-kit/surfaces/modals#updating_views">API ドキュメント</a>を参照してください。
+</div>
+
+```javascript
+// action_id: button_abc のボタンを押すイベントをリッスン
+// （そのボタンはモーダルビューの中にあるという想定）
+app.action('button_abc', ({ ack, body, context }) => {
+ // ボタンを押したイベントを確認
+ ack();
+
+ try {
+ const result = app.client.views.update({
+ token: context.botToken,
+ // リクエストに含まれる view_id を渡す
+ view_id: body.view.id,
+ // 更新された view の値をペイロードに含む
+ view: {
+ // callback_id が view を特定するための識別子
+ callback_id: 'view_1',
+ title: {
+ type: 'plain_text',
+ text: 'Updated modal'
+ },
+ blocks: [
+ {
+ type: 'section',
+ text: {
+ type: 'plain_text',
+ text: 'You updated the modal!'
+ }
+ },
+ {
+ type: 'image',
+ image_url: 'https://media.giphy.com/media/SVZGEcYt7brkFUyU90/giphy.gif',
+ alt_text: 'Yay! The modal was updated'
+ }
+ ]
+ }
+ });
+ console.log(result);
+ }
+ catch (error) {
+ console.error(error);
+ }
+});
+```

docs/_basic/updating_pushing_modals.md

@@ -6,7 +6,7 @@ order: 10
 ---
 
 <div class="section-content">
-Modals contain a stack of views. When you call `views.open`, you add the root view to the modal. After the initial call, you can dynamically update a view by calling <a href="https://api.slack.com/methods/views.update">`views.update`</a>, or stack a new view on top of the root view by calling <a href="https://api.slack.com/methods/views.push">`views.push`</a>.
+Modals contain a stack of views. When you call <a href="https://api.slack.com/methods/views.open">`views.open`</a>, you add the root view to the modal. After the initial call, you can dynamically update a view by calling <a href="https://api.slack.com/methods/views.update">`views.update`</a>, or stack a new view on top of the root view by calling <a href="https://api.slack.com/methods/views.push">`views.push`</a>.
 
 <strong><code>views.update</code></strong><br>
 To update a view, you can use the built-in client to call <code>views.update</code> with the <code>view_id</code> that was generated when you opened the view, and the updated <code>blocks</code> array. If you're updating the view when a user interacts with an element inside of an existing view, the <code>view_id</code> will be available in the <code>body</code> of the request.