@zhin.js/adapter-slack 1.0.78 → 1.1.2

package/src/protocol.ts

@@ -0,0 +1,406 @@
+/**
+ * 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 type { IncomingMessage } from 'node:http';
+import { isMediaRef, type MediaRef, type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
+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: string, reason: string): void {
+  logger.warn(formatCompact({ op: 'slack_outbound_media_dropped', type, reason }));
+}
+
+const SLACK_SIG_VERSION = 'v0';
+const MAX_TIMESTAMP_DRIFT_SECONDS = 300;
+
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface SlackEndpointConfig {
+  readonly id: string;
+  readonly token: string;
+  readonly signingSecret?: string;
+  readonly appToken?: string;
+  /** Default true (Socket Mode). Set false for HTTP Events API via httpHostToken. */
+  readonly socketMode?: boolean;
+  readonly webhookPath?: string;
+  readonly clientPingTimeout?: number;
+}
+
+export interface ResolvedSlackConfig {
+  readonly context: 'slack';
+  readonly id: string;
+  readonly token: string;
+  readonly mode: 'socket' | 'http';
+  readonly signingSecret: string;
+  readonly appToken?: string;
+  readonly webhookPath: string;
+  readonly clientPingTimeout: number;
+}
+
+export interface SlackEventEnvelope {
+  readonly token?: string;
+  readonly team_id?: string;
+  readonly api_app_id?: string;
+  readonly event: SlackEvent;
+  readonly type: 'event_callback';
+  readonly event_id?: string;
+  readonly event_time?: number;
+}
+
+export interface SlackUrlVerification {
+  readonly type: 'url_verification';
+  readonly token: string;
+  readonly challenge: string;
+}
+
+export interface SlackInteractionPayload {
+  readonly type: 'block_actions' | 'message_action' | 'shortcut' | 'view_submission' | 'view_closed';
+  readonly trigger_id?: string;
+  readonly user: { id: string; username?: string; name?: string; team_id?: string };
+  readonly channel?: { id: string; name?: string };
+  readonly message?: { ts: string; text?: string; [key: string]: unknown };
+  readonly actions?: SlackBlockAction[];
+  readonly response_url?: string;
+  readonly [key: string]: unknown;
+}
+
+export interface SlackBlockAction {
+  readonly type: string;
+  readonly action_id: string;
+  readonly block_id: string;
+  readonly value?: string;
+  readonly text?: { type: string; text: string };
+  readonly action_ts?: string;
+  readonly [key: string]: unknown;
+}
+
+export interface SlackSlashCommand {
+  readonly token: string;
+  readonly team_id: string;
+  readonly channel_id: string;
+  readonly channel_name: string;
+  readonly user_id: string;
+  readonly user_name: string;
+  readonly command: string;
+  readonly text: string;
+  readonly response_url: string;
+  readonly trigger_id: string;
+  readonly api_app_id?: string;
+}
+
+export interface SlackEvent {
+  readonly type: string;
+  readonly ts?: string;
+  readonly event_ts?: string;
+  readonly user?: string;
+  readonly channel?: string;
+  readonly channel_type?: string;
+  readonly text?: string;
+  readonly thread_ts?: string;
+  readonly subtype?: string;
+  readonly bot_id?: string;
+  readonly [key: string]: unknown;
+}
+
+export type SlackMessageEvent = SlackEvent & {
+  readonly type: 'message' | 'app_mention';
+  readonly ts: string;
+  readonly channel: string;
+};
+
+export interface SlackWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export function resolveSlackConfig(config: SlackEndpointConfig): ResolvedSlackConfig {
+  const id = requiredEndpointField(config.id, 'id');
+  const token = requiredEndpointField(config.token, 'token');
+  const socketMode = config.socketMode;
+  // Prefer Socket Mode (default true) — no public URL required.
+  const mode: 'socket' | 'http' = socketMode === false ? 'http' : 'socket';
+
+  const signingSecret = mode === 'http'
+    ? requiredEndpointField(config.signingSecret, 'signingSecret')
+    : config.signingSecret?.trim() ?? '';
+  const appToken = mode === 'socket'
+    ? requiredEndpointField(config.appToken, 'appToken')
+    : config.appToken?.trim();
+
+  return {
+    context: 'slack',
+    id,
+    token,
+    mode,
+    signingSecret,
+    appToken,
+    webhookPath: normalizeWebhookPath(
+      config.webhookPath ?? '/slack/events',
+    ),
+    clientPingTimeout: config.clientPingTimeout ?? 15_000,
+  };
+}
+
+function requiredEndpointField(
+  value: unknown,
+  field: 'id' | 'token' | 'signingSecret' | 'appToken',
+): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError(`Slack endpoint requires a non-empty ${field}`);
+  }
+  return value.trim();
+}
+
+export function normalizeWebhookPath(path: string): string {
+  const trimmed = path.trim() || '/slack/events';
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+
+export function resolveSlackChannelType(event: Pick<SlackEvent, 'channel_type'>): 'private' | 'group' {
+  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: string,
+  opts: {
+    readonly channelId: string;
+    readonly channelType?: string;
+    readonly threadId?: string;
+  },
+): ConversationRef {
+  const kind: ConversationKind = 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: SlackMessageEvent | SlackEvent): string {
+  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: SlackInteractionPayload): string {
+  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: SlackSlashCommand): string {
+  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: unknown): {
+  text: string;
+  blocks: Record<string, unknown>[];
+  attachments: Record<string, unknown>[];
+  files: Array<{ buffer?: Buffer; url?: string; path?: string; name?: string }>;
+} {
+  if (typeof payload === 'string') {
+    return { text: payload, blocks: [], attachments: [], files: [] };
+  }
+
+  const items: Array<string | SlackWireSegment> = Array.isArray(payload)
+    ? payload as Array<string | SlackWireSegment>
+    : payload && typeof payload === 'object' && 'type' in (payload as object)
+      ? [payload as SlackWireSegment]
+      : [];
+
+  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: Record<string, unknown>[] = [];
+  const attachments: Record<string, unknown>[] = [];
+  const files: Array<{ buffer?: Buffer; url?: string; path?: string; name?: string }> = [];
+
+  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: Record<string, unknown>): Record<string, unknown>[] {
+  const rows = data.rows as Array<Array<Record<string, unknown>>> | undefined;
+  if (!rows?.length) return [];
+
+  const blocks: Record<string, unknown>[] = [];
+  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: MediaRef,
+  name: string,
+): { buffer?: Buffer; url?: string; path?: string; name: string } | undefined {
+  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: string,
+  rawBody: string,
+  timestamp: string,
+  signature: string,
+): boolean {
+  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: IncomingMessage,
+  options: { readonly limit?: number } = {},
+): Promise<string> {
+  const limit = options.limit ?? 1_048_576;
+  const chunks: Buffer[] = [];
+  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: IncomingMessage['headers'],
+  name: string,
+): string {
+  const raw = headers[name.toLowerCase()];
+  if (Array.isArray(raw)) return raw[0] ?? '';
+  return raw ?? '';
+}

package/src/side-event-dispatch.ts

@@ -0,0 +1,54 @@
+import { buildNotice, mapNoticeParts, senderFromId, SLACK_NOTICE_PARTS_MAP } from '@zhin.js/core';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
+import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
+import type { SlackEvent } from './protocol.js';
+
+export function receiveSlackSideEvent(
+  emit: EndpointEventEmitter,
+  endpointKey: string,
+  configId: string,
+  event: SlackEvent,
+  logger: ReturnType<typeof getAdapterLogger>,
+): void {
+  if (!emit) return;
+  const eventType = String(event.type ?? '');
+  if (!Object.prototype.hasOwnProperty.call(SLACK_NOTICE_PARTS_MAP, eventType)) return;
+  const record = event as Record<string, unknown>;
+  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' as never,
+    $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: unknown): number {
+  const value = Number(time);
+  if (!Number.isFinite(value) || value <= 0) return Date.now();
+  return value < 1e12 ? Math.round(value * 1000) : Math.round(value);
+}

package/src/slack-inbound-filter.ts

@@ -0,0 +1,60 @@
+import type { SlackMessageEvent } from './protocol.js';
+
+const DEDUPE_TTL_MS = 60_000;
+
+export interface SlackInboundFilterState {
+  seenInbound: Map<string, number>;
+}
+
+export function createSlackInboundFilterState(): SlackInboundFilterState {
+  return { seenInbound: new Map() };
+}
+
+function pruneSeen(state: SlackInboundFilterState, now: number): void {
+  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: SlackMessageEvent,
+  state: SlackInboundFilterState,
+  botUserId?: string,
+): boolean {
+  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/src/slack-message-ref.ts

@@ -0,0 +1,18 @@
+/** Slack 消息定位：channel + ts（Activity Feedback / recall / reaction 共用） */
+
+export function formatSlackMessageRef(channel: string, ts: string): string {
+  return `${channel}:${ts}`;
+}
+
+export function parseSlackMessageRef(ref: string): { channel: string; ts: string } | null {
+  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: string): string {
+  return parseSlackMessageRef(ref)?.ts ?? ref;
+}

package/src/slack-outbound.ts

@@ -0,0 +1,170 @@
+/**
+ * Slack outbound — chat.postMessage + Block Kit + files.uploadV2
+ */
+import type { Logger } from '@zhin.js/logger';
+import { markdownToMrkdwn, mrkdwnToPlainFallback, splitMrkdwnText } from './markdown-to-mrkdwn.js';
+import { formatOutboundWire, 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>;
+}
+
+const SLACK_MAX_BLOCKS_PER_MESSAGE = 48;
+
+export async function sendSlackContent(
+  client: SlackChatClient,
+  content: unknown,
+  opts: SlackSendOptions,
+  logger: Logger,
+): Promise<SlackOutboundResult> {
+  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: SlackChatClient,
+  channel: string,
+  ts: string,
+  content: unknown,
+): Promise<void> {
+  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: Record<string, unknown> = {
+    channel,
+    ts,
+    text: textDelivery.fallbackText || ' ',
+  };
+  if (payloadBlocks.length > 0) updateOpts.blocks = payloadBlocks;
+  await client.chat.update(updateOpts);
+}
+
+function applyTextMrkdwnBlocks(
+  textContent: string,
+  blocks: Record<string, unknown>[],
+): { fallbackText: string } {
+  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: SlackChatClient,
+  opts: {
+    channel: string;
+    threadTs?: string;
+    blocks: Record<string, unknown>[];
+    attachments: Record<string, unknown>[];
+    fallbackText: string;
+  },
+): Promise<SlackOutboundResult> {
+  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: { ts?: string } | null | undefined): string {
+  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: SlackChatClient,
+  channel: string,
+  file: { buffer?: Buffer; url?: string; path?: string; name?: string },
+  threadTs?: string,
+): Promise<void> {
+  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 };