@maroonedsoftware/slack 1.9.0 → 2.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Marooned Software
+Copyright (c) 2026 Marooned Software
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -295,6 +295,35 @@ if (isPolicyResultDenied(result)) throw httpError(401).withInternalDetails(resul
 
 The context (`rawBody` + a case-insensitive `getHeader` + `options`) is structurally compatible with `@maroonedsoftware/koa`'s `SignaturePolicyContext<SlackSignatureOptions>`, so the koa `requireSignature` middleware can drive this policy when it's registered under the signature policy name — no koa dependency in this package.
 
+## Use with `@maroonedsoftware/comms`
+
+The `@maroonedsoftware/slack/comms` subpath adapts this package to the channel-agnostic
+[`@maroonedsoftware/comms`](../comms) router, so a `command` / `action` / `message` handler written
+once runs on Slack and every other wired channel. It declares `@maroonedsoftware/comms` as an
+**optional peer** — the slack core doesn't depend on it.
+
+```ts
+import { SlackClient, SlackConfig, verifySlackSignature } from '@maroonedsoftware/slack';
+import { dispatchSlackCommand, dispatchSlackInteraction, dispatchSlackEvent, createSlackNotifier } from '@maroonedsoftware/slack/comms';
+import { router } from './router.js'; // a shared ChannelRouter
+
+router.post('/slack/commands', async (ctx) => {
+  const raw = await rawBody(ctx.req, { encoding: 'utf8' });
+  verifySlackSignature({ signingSecret: ctx.container.get(SlackConfig).signingSecret, rawBody: raw,
+    timestamp: ctx.get('x-slack-request-timestamp'), signature: ctx.get('x-slack-signature') });
+  await dispatchSlackCommand(router, ctx.container.get(SlackClient), Object.fromEntries(new URLSearchParams(raw)) as never);
+  ctx.status = 200; ctx.body = '';
+});
+```
+
+- `dispatchSlackEvent` (→ `message`/`app_mention`, replies via `chat.postMessage`; also returns the
+  `url_verification` challenge), `dispatchSlackCommand` (→ `command`, replies via `response_url`),
+  `dispatchSlackInteraction` (→ `action` for `block_actions`). `view_submission`/modals stay on the
+  native `SlackInteractionHandlerMap`.
+- `createSlackNotifier(client, router.templates)` sends proactively. Buttons render as a Block Kit
+  `actions` block; `reply.sendTemplate(name, data)` renders a registered Slack template;
+  `reply.sendNative(payload)` posts raw Block Kit.
+
 ## Limitations
 
 - v1 supports a single workspace via the bot token in `SlackConfig`. Multi-workspace OAuth install is out of scope.

package/dist/chunk-7QVYU63E.js

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+export {
+  __name
+};
+//# sourceMappingURL=chunk-7QVYU63E.js.map

package/dist/chunk-7QVYU63E.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/comms.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@maroonedsoftware/slack/comms` — adapter binding the Slack package to the
+ * channel-agnostic `@maroonedsoftware/comms` router. Importing this subpath
+ * pulls in `@maroonedsoftware/comms` (an optional peer); the slack core does not.
+ */
+import { type ChannelRouter, type Notifier, type TemplateRegistry } from '@maroonedsoftware/comms';
+import { SlackClient } from './client/slack.client.js';
+import type { SlackCommandPayload } from './slack.command.handler.js';
+import type { SlackInteractionPayload } from './slack.interaction.handler.js';
+import type { SlackEventsRequest } from './slack.dispatcher.js';
+/**
+ * Builds a {@link Notifier} that sends portable messages and registered templates
+ * through {@link SlackClient}. The recipient string is either a `response_url`
+ * (used as an incoming webhook) or a channel id (`chat.postMessage`).
+ */
+export declare const createSlackNotifier: (client: SlackClient, templates: TemplateRegistry) => Notifier;
+/**
+ * Dispatches a parsed Slack Events API body. Returns the `url_verification`
+ * challenge for the handshake; for `message` / `app_mention` events it routes a
+ * normalized `message` event to the {@link ChannelRouter} (replying via
+ * `chat.postMessage` to the event's channel). Returns `undefined` otherwise.
+ */
+export declare const dispatchSlackEvent: (router: ChannelRouter, client: SlackClient, body: SlackEventsRequest) => Promise<{
+    challenge: string;
+} | undefined>;
+/** Dispatches a parsed slash-command payload as a normalized `command` event (reply via `response_url`). */
+export declare const dispatchSlackCommand: (router: ChannelRouter, client: SlackClient, payload: SlackCommandPayload) => Promise<void>;
+/**
+ * Dispatches a parsed interactive payload. Only `block_actions` is normalized
+ * (to an `action` event keyed by the first action's `action_id`); other types
+ * (e.g. `view_submission`) stay on the slack package's native handlers.
+ */
+export declare const dispatchSlackInteraction: (router: ChannelRouter, client: SlackClient, payload: SlackInteractionPayload) => Promise<void>;
+//# sourceMappingURL=comms.d.ts.map

package/dist/comms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms.d.ts","sourceRoot":"","sources":["../src/comms.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAyB,KAAK,aAAa,EAAsB,KAAK,QAAQ,EAAwB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACpK,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAyBhE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,WAAW,EAAE,WAAW,gBAAgB,KAAG,QASrF,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAU,QAAQ,aAAa,EAAE,QAAQ,WAAW,EAAE,MAAM,kBAAkB,KAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAYxJ,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,GAAU,QAAQ,aAAa,EAAE,QAAQ,WAAW,EAAE,SAAS,mBAAmB,KAAG,OAAO,CAAC,IAAI,CAYjI,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAU,QAAQ,aAAa,EAAE,QAAQ,WAAW,EAAE,SAAS,uBAAuB,KAAG,OAAO,CAAC,IAAI,CAgBzI,CAAC"}

package/dist/comms.js

@@ -0,0 +1,129 @@
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/comms.ts
+import { bindReply, CommsError } from "@maroonedsoftware/comms";
+var render = /* @__PURE__ */ __name((message) => {
+  if (!message.buttons?.length) return {
+    text: message.text
+  };
+  return {
+    text: message.text,
+    blocks: [
+      {
+        type: "section",
+        text: {
+          type: "mrkdwn",
+          text: message.text
+        }
+      },
+      {
+        type: "actions",
+        elements: message.buttons.map((b) => ({
+          type: "button",
+          action_id: b.id,
+          text: {
+            type: "plain_text",
+            text: b.label
+          },
+          value: b.value ?? b.id
+        }))
+      }
+    ]
+  };
+}, "render");
+var deliver = /* @__PURE__ */ __name((client, to, payload) => to.startsWith("http") ? client.postWebhook(payload, to) : client.postMessage({
+  channel: to,
+  ...payload
+}), "deliver");
+var createSlackNotifier = /* @__PURE__ */ __name((client, templates) => ({
+  channel: "slack",
+  send: /* @__PURE__ */ __name(async (to, message) => void await deliver(client, to, render(message)), "send"),
+  sendTemplate: /* @__PURE__ */ __name(async (to, name, data) => {
+    const resolved = templates.render(name, "slack", data);
+    if (!resolved) throw new CommsError(`No comms template registered for "${name}"`).withInternalDetails({
+      channel: "slack",
+      name
+    });
+    await deliver(client, to, resolved.kind === "native" ? resolved.payload : render(resolved.message));
+  }, "sendTemplate"),
+  sendNative: /* @__PURE__ */ __name(async (to, payload) => void await deliver(client, to, payload), "sendNative")
+}), "createSlackNotifier");
+var dispatchSlackEvent = /* @__PURE__ */ __name(async (router, client, body) => {
+  if (body.type === "url_verification") return {
+    challenge: body.challenge
+  };
+  if (body.type !== "event_callback") return void 0;
+  const envelope = body;
+  const ev = envelope.event;
+  if ((ev.type === "message" || ev.type === "app_mention") && ev.user && !ev.bot_id && ev.subtype !== "bot_message") {
+    const channel = ev.channel ?? "";
+    const event = {
+      channel: "slack",
+      kind: "message",
+      user: {
+        id: ev.user
+      },
+      conversation: {
+        id: channel
+      },
+      text: ev.text,
+      raw: envelope
+    };
+    await router.dispatch(event, bindReply(createSlackNotifier(client, router.templates), channel));
+  }
+  return void 0;
+}, "dispatchSlackEvent");
+var dispatchSlackCommand = /* @__PURE__ */ __name(async (router, client, payload) => {
+  const event = {
+    channel: "slack",
+    kind: "command",
+    user: {
+      id: payload.user_id,
+      username: payload.user_name
+    },
+    conversation: {
+      id: payload.channel_id
+    },
+    text: `${payload.command} ${payload.text}`.trim(),
+    command: {
+      name: payload.command,
+      args: payload.text
+    },
+    raw: payload
+  };
+  const to = payload.response_url || payload.channel_id;
+  await router.dispatch(event, bindReply(createSlackNotifier(client, router.templates), to));
+}, "dispatchSlackCommand");
+var dispatchSlackInteraction = /* @__PURE__ */ __name(async (router, client, payload) => {
+  if (payload.type !== "block_actions") return;
+  const first = payload.actions?.[0];
+  if (!first) return;
+  const channel = payload.channel?.id ?? "";
+  const event = {
+    channel: "slack",
+    kind: "action",
+    user: {
+      id: payload.user?.id ?? "",
+      username: payload.user?.name
+    },
+    conversation: {
+      id: channel
+    },
+    action: {
+      id: first.action_id,
+      value: first.value
+    },
+    raw: payload
+  };
+  const to = payload.response_url || channel;
+  await router.dispatch(event, bindReply(createSlackNotifier(client, router.templates), to));
+}, "dispatchSlackInteraction");
+export {
+  createSlackNotifier,
+  dispatchSlackCommand,
+  dispatchSlackEvent,
+  dispatchSlackInteraction
+};
+//# sourceMappingURL=comms.js.map

package/dist/comms.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/comms.ts"],"sourcesContent":["/**\n * `@maroonedsoftware/slack/comms` — adapter binding the Slack package to the\n * channel-agnostic `@maroonedsoftware/comms` router. Importing this subpath\n * pulls in `@maroonedsoftware/comms` (an optional peer); the slack core does not.\n */\nimport { bindReply, CommsError, type ChannelRouter, type IncomingEvent, type Notifier, type OutgoingMessage, type TemplateRegistry } from '@maroonedsoftware/comms';\nimport { SlackClient } from './client/slack.client.js';\nimport type { SlackCommandPayload } from './slack.command.handler.js';\nimport type { SlackInteractionPayload } from './slack.interaction.handler.js';\nimport type { SlackEventCallback } from './slack.event.handler.js';\nimport type { SlackEventsRequest } from './slack.dispatcher.js';\n\ntype SlackPayload = Record<string, unknown>;\n\n/** Renders a portable message to a Slack chat payload (`text`, or `text` + Block Kit `actions`). */\nconst render = (message: OutgoingMessage): SlackPayload => {\n  if (!message.buttons?.length) return { text: message.text };\n  return {\n    text: message.text,\n    blocks: [\n      { type: 'section', text: { type: 'mrkdwn', text: message.text } },\n      {\n        type: 'actions',\n        elements: message.buttons.map(b => ({ type: 'button', action_id: b.id, text: { type: 'plain_text', text: b.label }, value: b.value ?? b.id })),\n      },\n    ],\n  };\n};\n\n/** Delivers a Slack payload: to a `response_url` (http) via webhook, otherwise to a channel id. */\nconst deliver = (client: SlackClient, to: string, payload: SlackPayload): Promise<unknown> =>\n  to.startsWith('http')\n    ? client.postWebhook(payload as Parameters<SlackClient['postWebhook']>[0], to)\n    : client.postMessage({ channel: to, ...payload } as Parameters<SlackClient['postMessage']>[0]);\n\n/**\n * Builds a {@link Notifier} that sends portable messages and registered templates\n * through {@link SlackClient}. The recipient string is either a `response_url`\n * (used as an incoming webhook) or a channel id (`chat.postMessage`).\n */\nexport const createSlackNotifier = (client: SlackClient, templates: TemplateRegistry): Notifier => ({\n  channel: 'slack',\n  send: async (to, message) => void (await deliver(client, to, render(message))),\n  sendTemplate: async (to, name, data) => {\n    const resolved = templates.render(name, 'slack', data);\n    if (!resolved) throw new CommsError(`No comms template registered for \"${name}\"`).withInternalDetails({ channel: 'slack', name });\n    await deliver(client, to, resolved.kind === 'native' ? (resolved.payload as SlackPayload) : render(resolved.message));\n  },\n  sendNative: async (to, payload) => void (await deliver(client, to, payload as SlackPayload)),\n});\n\n/**\n * Dispatches a parsed Slack Events API body. Returns the `url_verification`\n * challenge for the handshake; for `message` / `app_mention` events it routes a\n * normalized `message` event to the {@link ChannelRouter} (replying via\n * `chat.postMessage` to the event's channel). Returns `undefined` otherwise.\n */\nexport const dispatchSlackEvent = async (router: ChannelRouter, client: SlackClient, body: SlackEventsRequest): Promise<{ challenge: string } | undefined> => {\n  if (body.type === 'url_verification') return { challenge: (body as { challenge: string }).challenge };\n  if (body.type !== 'event_callback') return undefined;\n\n  const envelope = body as SlackEventCallback;\n  const ev = envelope.event as { type: string; channel?: string; user?: string; text?: string; bot_id?: string; subtype?: string };\n  if ((ev.type === 'message' || ev.type === 'app_mention') && ev.user && !ev.bot_id && ev.subtype !== 'bot_message') {\n    const channel = ev.channel ?? '';\n    const event: IncomingEvent = { channel: 'slack', kind: 'message', user: { id: ev.user }, conversation: { id: channel }, text: ev.text, raw: envelope };\n    await router.dispatch(event, bindReply(createSlackNotifier(client, router.templates), channel));\n  }\n  return undefined;\n};\n\n/** Dispatches a parsed slash-command payload as a normalized `command` event (reply via `response_url`). */\nexport const dispatchSlackCommand = async (router: ChannelRouter, client: SlackClient, payload: SlackCommandPayload): Promise<void> => {\n  const event: IncomingEvent = {\n    channel: 'slack',\n    kind: 'command',\n    user: { id: payload.user_id, username: payload.user_name },\n    conversation: { id: payload.channel_id },\n    text: `${payload.command} ${payload.text}`.trim(),\n    command: { name: payload.command, args: payload.text },\n    raw: payload,\n  };\n  const to = payload.response_url || payload.channel_id;\n  await router.dispatch(event, bindReply(createSlackNotifier(client, router.templates), to));\n};\n\n/**\n * Dispatches a parsed interactive payload. Only `block_actions` is normalized\n * (to an `action` event keyed by the first action's `action_id`); other types\n * (e.g. `view_submission`) stay on the slack package's native handlers.\n */\nexport const dispatchSlackInteraction = async (router: ChannelRouter, client: SlackClient, payload: SlackInteractionPayload): Promise<void> => {\n  if (payload.type !== 'block_actions') return;\n  const first = payload.actions?.[0];\n  if (!first) return;\n\n  const channel = (payload as { channel?: { id?: string } }).channel?.id ?? '';\n  const event: IncomingEvent = {\n    channel: 'slack',\n    kind: 'action',\n    user: { id: payload.user?.id ?? '', username: payload.user?.name },\n    conversation: { id: channel },\n    action: { id: first.action_id, value: first.value },\n    raw: payload,\n  };\n  const to = payload.response_url || channel;\n  await router.dispatch(event, bindReply(createSlackNotifier(client, router.templates), to));\n};\n"],"mappings":"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","names":["bindReply","CommsError","render","message","buttons","length","text","blocks","type","elements","map","b","action_id","id","label","value","deliver","client","to","payload","startsWith","postWebhook","postMessage","channel","createSlackNotifier","templates","send","sendTemplate","name","data","resolved","CommsError","withInternalDetails","kind","sendNative","dispatchSlackEvent","router","body","challenge","undefined","envelope","ev","event","user","bot_id","subtype","conversation","raw","dispatch","bindReply","dispatchSlackCommand","user_id","username","user_name","channel_id","command","trim","args","response_url","dispatchSlackInteraction","first","actions","action"]}