@zhin.js/adapter-slack 1.0.78 → 1.1.0

package/lib/protocol.js

@@ -0,0 +1,272 @@
+/**
+ * Slack protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { mrkdwnToMarkdown } from './mrkdwn-to-markdown.js';
+const logger = getLogger('slack');
+/** 无 canonical MediaRef 或不可投递时留痕（对齐 QQ `*_outbound_media_dropped` 风格）。 */
+function dropOutboundMedia(type, reason) {
+    logger.warn(formatCompact({ op: 'slack_outbound_media_dropped', type, reason }));
+}
+const SLACK_SIG_VERSION = 'v0';
+const MAX_TIMESTAMP_DRIFT_SECONDS = 300;
+export function resolveSlackConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'slack');
+    const token = config.token
+        ?? entry?.token
+        ?? process.env.SLACK_BOT_TOKEN
+        ?? process.env.SLACK_TOKEN;
+    if (!token) {
+        throw new TypeError('Slack adapter requires token (plugins.<key>.token or endpoints with context: slack)');
+    }
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
+        || process.env.SLACK_BOT_NAME
+        || 'slack-bot';
+    const socketMode = config.socketMode ?? entry?.socketMode;
+    // Prefer Socket Mode (default true) — no public URL required.
+    const mode = socketMode === false ? 'http' : 'socket';
+    const signingSecret = config.signingSecret
+        ?? entry?.signingSecret
+        ?? process.env.SLACK_SIGNING_SECRET
+        ?? '';
+    const appToken = config.appToken
+        ?? entry?.appToken
+        ?? process.env.SLACK_APP_TOKEN
+        ?? undefined;
+    if (mode === 'socket' && !appToken) {
+        throw new TypeError('Slack Socket Mode requires appToken (xapp-...); set socketMode: false for HTTP Events API');
+    }
+    if (mode === 'http' && !signingSecret) {
+        throw new TypeError('Slack HTTP Events API requires signingSecret');
+    }
+    return {
+        context: 'slack',
+        id,
+        token,
+        mode,
+        signingSecret,
+        appToken,
+        webhookPath: normalizeWebhookPath(config.webhookPath ?? entry?.webhookPath ?? '/slack/events'),
+        clientPingTimeout: config.clientPingTimeout
+            ?? entry?.clientPingTimeout
+            ?? 15_000,
+    };
+}
+export function normalizeWebhookPath(path) {
+    const trimmed = path.trim() || '/slack/events';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function resolveSlackChannelType(event) {
+    return event.channel_type === 'im' ? 'private' : 'group';
+}
+/**
+ * 入站归一化 → ConversationRef：channel_type `im` → private，其余（channel/group/mpim）
+ * → group；交互/斜杠命令无 channel_type 时按平台 id 前缀推断（D* 为 DM）。Slack 无
+ * guild 容器概念（team 为 workspace 级，不进 parent）；线程根 ts 进 `threadId`。
+ */
+export function slackInboundConversation(endpointKey, opts) {
+    const kind = opts.channelType != null
+        ? (opts.channelType === 'im' ? 'private' : 'group')
+        : (opts.channelId.startsWith('D') ? 'private' : 'group');
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind,
+        id: opts.channelId,
+        ...(opts.threadId ? { threadId: opts.threadId } : {}),
+    };
+}
+/** Build inbound text for OutboundMessageService.receive. */
+export function formatInboundContent(event) {
+    const text = typeof event.text === 'string' ? event.text : '';
+    if (text)
+        return mrkdwnToMarkdown(text);
+    if ('files' in event && Array.isArray(event.files) && event.files.length > 0) {
+        return '[file]';
+    }
+    return '';
+}
+export function formatInteractionContent(payload) {
+    const action = payload.actions?.[0];
+    if (!action)
+        return '[action]';
+    const label = action.text?.text ?? action.value ?? action.action_id;
+    return `[action: ${action.action_id}${label ? ` ${label}` : ''}]`;
+}
+export function formatSlashContent(cmd) {
+    return `${cmd.command} ${cmd.text}`.trim();
+}
+/**
+ * Wire-encode an already-rendered outbound payload into Slack text + Block Kit blocks.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundWire(payload) {
+    if (typeof payload === 'string') {
+        return { text: payload, blocks: [], attachments: [], files: [] };
+    }
+    const items = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (items.length === 0) {
+        const text = payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+        return { text, blocks: [], attachments: [], files: [] };
+    }
+    let text = '';
+    const blocks = [];
+    const attachments = [];
+    const files = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            text += item;
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                text += String(data.text ?? data.content ?? '');
+                break;
+            case 'at':
+            case 'mention':
+                text += `<@${String(data.id ?? data.target ?? '')}>`;
+                break;
+            case 'channel_mention':
+                text += `<#${String(data.id ?? '')}>`;
+                break;
+            case 'link':
+                if (data.text && data.text !== data.url) {
+                    text += `<${String(data.url)}|${String(data.text)}>`;
+                }
+                else {
+                    text += `<${String(data.url ?? '')}>`;
+                }
+                break;
+            case 'image': {
+                // canonical MediaRef 唯一来源；kind=url 走 attachment 直发，其余物化后 files.uploadV2 上传
+                const media = data.media;
+                if (!isMediaRef(media)) {
+                    dropOutboundMedia(item.type, 'missing_media_ref');
+                    break;
+                }
+                if (media.kind === 'url') {
+                    attachments.push({
+                        image_url: media.value,
+                        title: String(data.alt ?? data.title ?? media.file_name ?? ''),
+                    });
+                    break;
+                }
+                const imageFile = resolveMediaToFile(media, String(data.alt ?? media.file_name ?? 'image'));
+                if (imageFile)
+                    files.push(imageFile);
+                else
+                    dropOutboundMedia(item.type, 'unsupported_media_kind');
+                break;
+            }
+            case 'audio':
+            case 'video':
+            case 'file': {
+                const media = data.media;
+                if (!isMediaRef(media)) {
+                    dropOutboundMedia(item.type, 'missing_media_ref');
+                    break;
+                }
+                const mediaFile = resolveMediaToFile(media, String(data.name ?? media.file_name ?? item.type));
+                if (mediaFile)
+                    files.push(mediaFile);
+                else
+                    dropOutboundMedia(item.type, 'unsupported_media_kind');
+                break;
+            }
+            case 'keyboard':
+                blocks.push(...keyboardToBlockKitBlocks(data));
+                break;
+            default:
+                text += String(data.text ?? `[${item.type}]`);
+        }
+    }
+    return { text, blocks, attachments, files };
+}
+export function keyboardToBlockKitBlocks(data) {
+    const rows = data.rows;
+    if (!rows?.length)
+        return [];
+    const blocks = [];
+    for (const row of rows) {
+        const elements = row.slice(0, 5).map((btn, index) => ({
+            type: 'button',
+            text: { type: 'plain_text', text: String(btn.label ?? btn.text ?? 'button').slice(0, 75) },
+            action_id: String(btn.id ?? btn.action_id ?? `btn_${blocks.length}_${index}`),
+            ...(btn.value != null ? { value: String(btn.value) } : {}),
+            ...(btn.style === 'primary' ? { style: 'primary' } : {}),
+            ...(btn.style === 'danger' ? { style: 'danger' } : {}),
+        }));
+        if (elements.length > 0) {
+            blocks.push({ type: 'actions', elements });
+        }
+    }
+    return blocks;
+}
+/**
+ * MediaRef → 待上传文件描述：
+ * - kind=url → 记录 URL，由 files.uploadV2 前拉取物化；
+ * - kind=base64 → 解码为 buffer 直传；
+ * - kind=path → 记录本地路径，上传前读盘；
+ * - kind=file → Slack 无平台不透明文件引用可直发，返回 undefined 由调用方丢弃留痕。
+ */
+function resolveMediaToFile(media, name) {
+    switch (media.kind) {
+        case 'base64':
+            return {
+                buffer: Buffer.from(media.value.replace(/^base64:\/\//, ''), 'base64'),
+                name,
+            };
+        case 'url':
+            return { url: media.value, name };
+        case 'path':
+            return { path: media.value, name };
+        default:
+            return undefined;
+    }
+}
+export function verifySlackSignature(signingSecret, rawBody, timestamp, signature) {
+    const now = Math.floor(Date.now() / 1000);
+    const ts = parseInt(timestamp, 10);
+    if (Number.isNaN(ts) || Math.abs(now - ts) > MAX_TIMESTAMP_DRIFT_SECONDS) {
+        return false;
+    }
+    const baseString = `${SLACK_SIG_VERSION}:${timestamp}:${rawBody}`;
+    const hmac = createHmac('sha256', signingSecret).update(baseString).digest('hex');
+    const expected = `${SLACK_SIG_VERSION}=${hmac}`;
+    if (expected.length !== signature.length)
+        return false;
+    return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+}
+export async function readTextBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function headerValue(headers, name) {
+    const raw = headers[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return raw[0] ?? '';
+    return raw ?? '';
+}

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,4 @@
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
+import { type getAdapterLogger } from '@zhin.js/logger';
+import type { SlackEvent } from './protocol.js';
+export declare function receiveSlackSideEvent(emit: EndpointEventEmitter, endpointKey: string, configId: string, event: SlackEvent, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -0,0 +1,45 @@
+import { buildNotice, mapNoticeParts, senderFromId, SLACK_NOTICE_PARTS_MAP } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+export function receiveSlackSideEvent(emit, endpointKey, configId, event, logger) {
+    if (!emit)
+        return;
+    const eventType = String(event.type ?? '');
+    if (!Object.prototype.hasOwnProperty.call(SLACK_NOTICE_PARTS_MAP, eventType))
+        return;
+    const record = event;
+    const parts = mapNoticeParts('slack', eventType);
+    const channel = typeof record.channel === 'string' ? record.channel : undefined;
+    const user = typeof record.user === 'string' ? record.user : undefined;
+    const sceneId = channel ?? user ?? configId;
+    const dedupeKey = [
+        eventType,
+        channel ?? '',
+        user ?? '',
+        String(record.ts ?? record.event_ts ?? ''),
+    ].join(':');
+    void emit('notice.receive', buildNotice(record, {
+        $id: `slack:${dedupeKey}`,
+        $adapter: 'slack',
+        $endpoint: configId,
+        $type: 'notice',
+        $scene_id: sceneId,
+        $scene_type: parts.scene_type,
+        $sub_type: parts.sub_type,
+        $actor: senderFromId(user),
+        $target: senderFromId(typeof record.item_user === 'string' ? record.item_user : undefined),
+        $timestamp: toMillis(record.event_ts ?? record.ts),
+    })).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'slack_side_event_failed',
+            endpoint: configId,
+            event: eventType,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+}
+function toMillis(time) {
+    const value = Number(time);
+    if (!Number.isFinite(value) || value <= 0)
+        return Date.now();
+    return value < 1e12 ? Math.round(value * 1000) : Math.round(value);
+}

package/lib/slack-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const slackEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/slack-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `slack.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { slackRuntimeStateToken } from './slack-runtime-state.js';
+export const slackEndpointCommands = createEndpointCommands({
+    adapterKey: 'slack',
+    adapterDisplayName: 'Slack',
+    fields: [
+        { key: 'token', required: true, env: true, description: 'Bot User OAuth Token（xoxb-...）' },
+        { key: 'signingSecret', env: true, description: '签名密钥（HTTP Events，socketMode: false 必填）' },
+        { key: 'appToken', env: true, description: 'App-Level Token（xapp-...，Socket Mode）' },
+    ],
+    running: (use) => use(slackRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/lib/slack-inbound-filter.d.ts

@@ -0,0 +1,12 @@
+import type { SlackMessageEvent } from './protocol.js';
+export interface SlackInboundFilterState {
+    seenInbound: Map<string, number>;
+}
+export declare function createSlackInboundFilterState(): SlackInboundFilterState;
+/**
+ * 过滤不应进入 IM 管道的 Slack 入站消息。
+ * - 跳过 Bot 自身消息
+ * - 频道内 @Bot：只保留 app_mention，丢弃重复的 message 事件
+ * - channel:ts 去重（message + app_mention 等同一条）
+ */
+export declare function shouldDropSlackInboundMessage(event: SlackMessageEvent, state: SlackInboundFilterState, botUserId?: string): boolean;

package/lib/slack-inbound-filter.js

@@ -0,0 +1,46 @@
+const DEDUPE_TTL_MS = 60_000;
+export function createSlackInboundFilterState() {
+    return { seenInbound: new Map() };
+}
+function pruneSeen(state, now) {
+    if (state.seenInbound.size < 512)
+        return;
+    for (const [key, at] of state.seenInbound) {
+        if (now - at > DEDUPE_TTL_MS) {
+            state.seenInbound.delete(key);
+        }
+    }
+}
+/**
+ * 过滤不应进入 IM 管道的 Slack 入站消息。
+ * - 跳过 Bot 自身消息
+ * - 频道内 @Bot：只保留 app_mention，丢弃重复的 message 事件
+ * - channel:ts 去重（message + app_mention 等同一条）
+ */
+export function shouldDropSlackInboundMessage(event, state, botUserId) {
+    if (event.subtype === 'bot_message' || event.subtype === 'message_changed') {
+        return true;
+    }
+    if (event.bot_id)
+        return true;
+    if (botUserId && event.user === botUserId)
+        return true;
+    const channelType = event.channel_type ?? 'channel';
+    const text = event.text ?? '';
+    if (event.type === 'message' && channelType !== 'im' && botUserId) {
+        if (text.includes(`<@${botUserId}>`)) {
+            return true;
+        }
+    }
+    if (!event.channel || !event.ts)
+        return true;
+    const key = `${event.channel}:${event.ts}`;
+    const now = Date.now();
+    const seenAt = state.seenInbound.get(key);
+    if (seenAt != null && now - seenAt < DEDUPE_TTL_MS) {
+        return true;
+    }
+    state.seenInbound.set(key, now);
+    pruneSeen(state, now);
+    return false;
+}

package/lib/slack-message-ref.d.ts

@@ -0,0 +1,7 @@
+/** Slack 消息定位：channel + ts（Activity Feedback / recall / reaction 共用） */
+export declare function formatSlackMessageRef(channel: string, ts: string): string;
+export declare function parseSlackMessageRef(ref: string): {
+    channel: string;
+    ts: string;
+} | null;
+export declare function slackMessageTs(ref: string): string;

package/lib/slack-message-ref.js

@@ -0,0 +1,17 @@
+/** Slack 消息定位：channel + ts（Activity Feedback / recall / reaction 共用） */
+export function formatSlackMessageRef(channel, ts) {
+    return `${channel}:${ts}`;
+}
+export function parseSlackMessageRef(ref) {
+    const sep = ref.indexOf(':');
+    if (sep <= 0)
+        return null;
+    const channel = ref.slice(0, sep);
+    const ts = ref.slice(sep + 1);
+    if (!channel || !ts)
+        return null;
+    return { channel, ts };
+}
+export function slackMessageTs(ref) {
+    return parseSlackMessageRef(ref)?.ts ?? ref;
+}

package/lib/slack-outbound.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Slack outbound — chat.postMessage + Block Kit + files.uploadV2
+ */
+import type { Logger } from '@zhin.js/logger';
+import { keyboardToBlockKitBlocks } from './protocol.js';
+export interface SlackOutboundResult {
+    ts: string;
+}
+export interface SlackSendOptions {
+    channel: string;
+    threadTs?: string;
+}
+export interface SlackChatClient {
+    chat: {
+        postMessage(opts: Record<string, unknown>): Promise<{
+            ts?: string;
+        }>;
+        update(opts: Record<string, unknown>): Promise<unknown>;
+    };
+    filesUploadV2?(opts: Record<string, unknown>): Promise<unknown>;
+}
+export declare function sendSlackContent(client: SlackChatClient, content: unknown, opts: SlackSendOptions, logger: Logger): Promise<SlackOutboundResult>;
+export declare function editSlackContent(client: SlackChatClient, channel: string, ts: string, content: unknown): Promise<void>;
+export { keyboardToBlockKitBlocks };

package/lib/slack-outbound.js

@@ -0,0 +1,111 @@
+import { markdownToMrkdwn, mrkdwnToPlainFallback, splitMrkdwnText } from './markdown-to-mrkdwn.js';
+import { formatOutboundWire, keyboardToBlockKitBlocks } from './protocol.js';
+const SLACK_MAX_BLOCKS_PER_MESSAGE = 48;
+export async function sendSlackContent(client, content, opts, logger) {
+    const wire = formatOutboundWire(content);
+    const blocks = [...wire.blocks];
+    const textDelivery = applyTextMrkdwnBlocks(wire.text, blocks);
+    for (const pf of wire.files) {
+        try {
+            await uploadFile(client, opts.channel, pf, opts.threadTs);
+        }
+        catch (e) {
+            logger.error('Failed to upload file:', e);
+            throw e;
+        }
+    }
+    return postSlackMessage(client, {
+        channel: opts.channel,
+        threadTs: opts.threadTs,
+        blocks,
+        attachments: wire.attachments,
+        fallbackText: textDelivery.fallbackText,
+    });
+}
+export async function editSlackContent(client, channel, ts, content) {
+    const wire = formatOutboundWire(content);
+    const blocks = [...wire.blocks];
+    const textDelivery = applyTextMrkdwnBlocks(wire.text, blocks);
+    const payloadBlocks = blocks.slice(0, SLACK_MAX_BLOCKS_PER_MESSAGE);
+    const updateOpts = {
+        channel,
+        ts,
+        text: textDelivery.fallbackText || ' ',
+    };
+    if (payloadBlocks.length > 0)
+        updateOpts.blocks = payloadBlocks;
+    await client.chat.update(updateOpts);
+}
+function applyTextMrkdwnBlocks(textContent, blocks) {
+    const trimmed = textContent.trim();
+    if (!trimmed)
+        return { fallbackText: '' };
+    const mrkdwn = markdownToMrkdwn(trimmed);
+    const sections = splitMrkdwnText(mrkdwn).map((chunk) => ({
+        type: 'section',
+        text: { type: 'mrkdwn', text: chunk },
+    }));
+    if (blocks.length > 0) {
+        blocks.unshift(...sections);
+        return { fallbackText: '' };
+    }
+    blocks.push(...sections);
+    return { fallbackText: mrkdwnToPlainFallback(mrkdwn) };
+}
+async function postSlackMessage(client, opts) {
+    const { channel, blocks, attachments, fallbackText } = opts;
+    let threadTs = opts.threadTs;
+    let firstTs = '';
+    if (blocks.length === 0) {
+        const result = await client.chat.postMessage({
+            channel,
+            text: fallbackText || 'Message',
+            ...(threadTs ? { thread_ts: threadTs } : {}),
+            ...(attachments.length > 0 ? { attachments } : {}),
+        });
+        return { ts: requireMessageTimestamp(result) };
+    }
+    for (let offset = 0; offset < blocks.length; offset += SLACK_MAX_BLOCKS_PER_MESSAGE) {
+        const chunk = blocks.slice(offset, offset + SLACK_MAX_BLOCKS_PER_MESSAGE);
+        const result = await client.chat.postMessage({
+            channel,
+            text: offset === 0 ? (fallbackText || ' ') : ' ',
+            blocks: chunk,
+            ...(threadTs ? { thread_ts: threadTs } : {}),
+            ...(offset === 0 && attachments.length > 0 ? { attachments } : {}),
+        });
+        const ts = requireMessageTimestamp(result);
+        if (!firstTs)
+            firstTs = ts;
+        if (!threadTs)
+            threadTs = ts;
+    }
+    return { ts: firstTs };
+}
+function requireMessageTimestamp(result) {
+    if (typeof result?.ts !== 'string' || !result.ts.trim()) {
+        throw new Error('Slack chat.postMessage returned no valid ts; delivery is unconfirmed');
+    }
+    return result.ts;
+}
+async function uploadFile(client, channel, file, threadTs) {
+    if (!client.filesUploadV2)
+        throw new Error('Slack client does not support file uploads');
+    let buffer = file.buffer;
+    if (!buffer && file.path) {
+        const { readFile } = await import('node:fs/promises');
+        buffer = await readFile(file.path);
+    }
+    if (!buffer && file.url) {
+        const res = await fetch(file.url);
+        if (!res.ok)
+            throw new Error(`fetch ${file.url}: ${res.status}`);
+        buffer = Buffer.from(await res.arrayBuffer());
+    }
+    if (!buffer)
+        throw new Error('Slack file contains no uploadable content');
+    await client.filesUploadV2(threadTs
+        ? { channel_id: channel, file: buffer, filename: file.name ?? 'file', thread_ts: threadTs }
+        : { channel_id: channel, file: buffer, filename: file.name ?? 'file' });
+}
+export { keyboardToBlockKitBlocks };

package/lib/slack-reaction.d.ts

@@ -0,0 +1 @@
+export declare function normalizeSlackReactionName(emoji: string): string;

package/lib/slack-reaction.js

@@ -0,0 +1,26 @@
+/** 将 activity-feedback / 工具入参规范为 Slack reactions.add 的 name（不含冒号） */
+const UNICODE_TO_SLACK = {
+    '⏳': 'hourglass_flowing_sand',
+    '✅': 'white_check_mark',
+    '❌': 'x',
+    '⏰': 'alarm_clock',
+    '🤔': 'thinking_face',
+    '👀': 'eyes',
+};
+export function normalizeSlackReactionName(emoji) {
+    const trimmed = emoji.trim();
+    if (!trimmed)
+        return 'hourglass_flowing_sand';
+    if (UNICODE_TO_SLACK[trimmed])
+        return UNICODE_TO_SLACK[trimmed];
+    if (trimmed.startsWith(':') && trimmed.endsWith(':') && trimmed.length > 2) {
+        return trimmed.slice(1, -1);
+    }
+    let start = 0;
+    let end = trimmed.length;
+    while (start < end && trimmed[start] === ':')
+        start++;
+    while (end > start && trimmed[end - 1] === ':')
+        end--;
+    return trimmed.slice(start, end);
+}

package/lib/slack-response-url.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Slack response_url 即时 ephemeral 反馈（斜杠命令 / 按钮交互）
+ */
+import type { Logger } from '@zhin.js/logger';
+export declare function postSlackEphemeral(responseUrl: string, text: string, logger?: Logger): void;

package/lib/slack-response-url.js

@@ -0,0 +1,16 @@
+export function postSlackEphemeral(responseUrl, text, logger) {
+    if (!responseUrl?.trim())
+        return;
+    const body = JSON.stringify({
+        response_type: 'ephemeral',
+        text,
+        replace_original: false,
+    });
+    fetch(responseUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+    }).catch((err) => {
+        logger?.debug(`Slack response_url failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
+}

package/lib/slack-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const slackRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/slack-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * Slack 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `slack.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const slackRuntimeStateToken = defineEndpointRuntimeStateToken('slack');

package/lib/webhook.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Slack webhook HTTP: signature → parse → admit.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type ResolvedSlackConfig, type SlackInteractionPayload, type SlackSlashCommand } from './protocol.js';
+export interface SlackWebhookHandler {
+    readonly config: ResolvedSlackConfig;
+    handleEnvelope(body: unknown): void;
+    admitInteraction(payload: SlackInteractionPayload): void;
+    admitSlashCommand(cmd: SlackSlashCommand): void;
+}
+export declare function registerSlackWebhookRoutes(http: HttpHost, handler: SlackWebhookHandler): HttpRouteRegistration[];
+export declare function handleSlackWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: SlackWebhookHandler): Promise<void>;