feat: add web api methods chat.postMessage and blocks.validate with example placeholders

.github/workflows/test.yml

@@ -16,6 +16,7 @@ jobs:
           - "ai/slackbot-mcp-client/rich-responses/mcp-apps"
           - "ai/slackbot-mcp-client/slack-identity"
           - "block-kit"
+          - "methods"
     steps:
       - name: Checkout code
         uses: actions/checkout@v7

README.md

@@ -6,3 +6,4 @@ This collections of examples highlights features of a Slack app in the language
 
 - **[AI in Slack](./ai)**: Agent experiences and MCP features in an interactive conversation interface.
 - **[Block Kit](./block-kit)**: The framework of visual components arranged to create app layouts.
+- **[Methods](./methods)**: Individual Slack Web API method calls with the `@slack/web-api` client.

methods/.gitignore

@@ -0,0 +1 @@
+node_modules

methods/README.md

@@ -0,0 +1,10 @@
+# Methods
+
+Individual Slack Web API method calls with the `@slack/web-api` client.
+
+Read the [docs](https://docs.slack.dev/reference/methods) to explore every method, or explore implementations of specific families.
+
+## What's on display
+
+- **[blocks](blocks/)**: Validate Block Kit payloads. [Implementation](./blocks/).
+- **[chat](chat/)**: Send and manage messages. [Implementation](./chat/).

methods/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

methods/blocks/.slack/.gitignore

@@ -0,0 +1,2 @@
+apps.dev.json
+cache/

methods/blocks/.slack/config.json

@@ -0,0 +1,6 @@
+{
+  "manifest": {
+    "source": "local"
+  },
+  "project_id": "00000000-0000-0000-0000-000000000000"
+}

methods/blocks/.slack/hooks.json

@@ -0,0 +1,5 @@
+{
+  "hooks": {
+    "get-hooks": "npx -q --no-install -p @slack/cli-hooks slack-cli-get-hooks"
+  }
+}

methods/blocks/README.md

@@ -0,0 +1,26 @@
+# blocks
+
+Validate Block Kit payloads.
+
+Read the [docs](https://docs.slack.dev/reference/methods#blocks) to explore more methods in the `blocks` family.
+
+## What's on display
+
+- **[blocks.validate](https://docs.slack.dev/reference/methods/blocks.validate)**: Validates blocks, messages, and views Block Kit JSON payloads. [Implementation](./src/blocks-validate.js).
+
+`blocks.validate` is not yet a typed method in `@slack/web-api`, so the example uses the generic `client.apiCall(...)` escape hatch instead of a typed `client.blocks.validate(...)` call.
+
+## Running an example
+
+This family is a self-contained Slack CLI app whose [`manifest.json`](./manifest.json) requests no scopes (`blocks.validate` requires none). From this directory, install the app and grab a token:
+
+```sh
+slack install
+```
+
+Then set the token and run the example directly:
+
+```sh
+export SLACK_TOKEN="xoxb-your-token"
+node src/blocks-validate.js
+```

methods/blocks/manifest.json

@@ -0,0 +1,22 @@
+{
+  "display_information": {
+    "name": "Slack API Methods",
+    "description": "Example implementations to call \"blocks\" methods"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "Slack API Methods",
+      "always_online": true
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": []
+    }
+  },
+  "settings": {
+    "org_deploy_enabled": true,
+    "socket_mode_enabled": false,
+    "token_rotation_enabled": false
+  }
+}

methods/blocks/src/blocks-validate.js

@@ -0,0 +1,20 @@
+import { WebClient } from "@slack/web-api";
+
+// Read a token from the environment variables
+const token = process.env.SLACK_TOKEN;
+
+// Initialize
+const client = new WebClient(token);
+
+// Call the blocks.validate method
+await client.apiCall("blocks.validate", {
+  blocks: JSON.stringify([
+    {
+      type: "section",
+      text: {
+        type: "plain_text",
+        text: "Hello world",
+      },
+    },
+  ]),
+});

methods/blocks/tests/blocks-validate.test.js

@@ -0,0 +1,43 @@
+import * as assert from "node:assert";
+import { after, describe, it, mock } from "node:test";
+
+describe("blocks.validate", () => {
+  after(() => {
+    mock.restoreAll();
+  });
+
+  it("sends", async () => {
+    process.env.SLACK_TOKEN = "xoxb-test";
+
+    const fetchMock = mock.method(
+      globalThis,
+      "fetch",
+      async () =>
+        new Response(JSON.stringify({ ok: true }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    );
+
+    await import("../src/blocks-validate.js");
+
+    assert.strictEqual(fetchMock.mock.callCount(), 1);
+    const [url, init] = fetchMock.mock.calls[0].arguments;
+    assert.strictEqual(String(url), "https://slack.com/api/blocks.validate");
+    assert.ok(init);
+    assert.deepStrictEqual(
+      Object.fromEntries(new URLSearchParams(String(init.body))),
+      {
+        blocks: JSON.stringify([
+          {
+            type: "section",
+            text: {
+              type: "plain_text",
+              text: "Hello world",
+            },
+          },
+        ]),
+      },
+    );
+  });
+});

methods/chat/.slack/.gitignore

@@ -0,0 +1,2 @@
+apps.dev.json
+cache/

methods/chat/.slack/config.json

@@ -0,0 +1,6 @@
+{
+  "manifest": {
+    "source": "local"
+  },
+  "project_id": "00000000-0000-0000-0000-000000000000"
+}

methods/chat/.slack/hooks.json

@@ -0,0 +1,5 @@
+{
+  "hooks": {
+    "get-hooks": "npx -q --no-install -p @slack/cli-hooks slack-cli-get-hooks"
+  }
+}

methods/chat/README.md

@@ -0,0 +1,24 @@
+# chat
+
+Send and manage messages.
+
+Read the [docs](https://docs.slack.dev/reference/methods#chat) to explore more methods in the `chat` family.
+
+## What's on display
+
+- **[chat.postMessage](https://docs.slack.dev/reference/methods/chat.postmessage)**: Sends a message to a channel. [Implementation](./src/chat-post-message.js).
+
+## Running an example
+
+This family is a self-contained Slack CLI app whose [`manifest.json`](./manifest.json) requests only the scopes it needs (`chat:write`). From this directory, install the app and grab a bot token:
+
+```sh
+slack install
+```
+
+Then set the token and run the example directly:
+
+```sh
+export SLACK_TOKEN="xoxb-your-token"
+node src/chat-post-message.js
+```

methods/chat/manifest.json

@@ -0,0 +1,22 @@
+{
+  "display_information": {
+    "name": "Slack API Methods",
+    "description": "Example implementations to call \"chat\" methods"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "Slack API Methods",
+      "always_online": true
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": ["chat:write"]
+    }
+  },
+  "settings": {
+    "org_deploy_enabled": true,
+    "socket_mode_enabled": false,
+    "token_rotation_enabled": false
+  }
+}

methods/chat/src/chat-post-message.js

@@ -0,0 +1,13 @@
+import { WebClient } from "@slack/web-api";
+
+// Read a token from the environment variables
+const token = process.env.SLACK_TOKEN;
+
+// Initialize
+const client = new WebClient(token);
+
+// Call the chat.postMessage method
+await client.chat.postMessage({
+  channel: "C123ABC456",
+  text: "Here's a message for you",
+});

methods/chat/tests/chat-post-message.test.js

@@ -0,0 +1,36 @@
+import * as assert from "node:assert";
+import { after, describe, it, mock } from "node:test";
+
+describe("chat.postMessage", () => {
+  after(() => {
+    mock.restoreAll();
+  });
+
+  it("sends", async () => {
+    process.env.SLACK_TOKEN = "xoxb-test";
+
+    const fetchMock = mock.method(
+      globalThis,
+      "fetch",
+      async () =>
+        new Response(JSON.stringify({ ok: true }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    );
+
+    await import("../src/chat-post-message.js");
+
+    assert.strictEqual(fetchMock.mock.callCount(), 1);
+    const [url, init] = fetchMock.mock.calls[0].arguments;
+    assert.strictEqual(String(url), "https://slack.com/api/chat.postMessage");
+    assert.ok(init);
+    assert.deepStrictEqual(
+      Object.fromEntries(new URLSearchParams(String(init.body))),
+      {
+        channel: "C123ABC456",
+        text: "Here's a message for you",
+      },
+    );
+  });
+});