@cursor/july 0.1.1

package/src/channels/slack/api.ts

@@ -0,0 +1,580 @@
+/**
+ * Slack Web API helpers used by the channel pack (`@slack/web-api`).
+ */
+
+import { ErrorCode, type WebAPIPlatformError, WebClient } from "@slack/web-api";
+import type { HostContext } from "../../types.js";
+import {
+  SLACK_DEFAULT_LOADING_MESSAGES,
+  SLACK_LOADING_MESSAGE_MAX_LEN,
+  SLACK_STATUS_MAX_LEN,
+  SLACK_TITLE_MAX_LEN,
+  SLACK_UNSUPPORTED_ERRORS,
+} from "./constants.js";
+import { tryResolveAppToken, tryResolveBotToken } from "./credentials.js";
+import { defaultSlackLog, type SlackLog } from "./log.js";
+import type { StreamTaskChunk } from "./stream.js";
+import type {
+  SlackApiTransport,
+  SlackBinding,
+  SlackBotToken,
+  SlackCredentials,
+  SlackSuggestedPrompt,
+  SoftSlackResult,
+} from "./types.js";
+
+/** Whether a bot token slot holds an API transport instead of a token. */
+export function isSlackApiTransport(
+  token: SlackBotToken | undefined
+): token is SlackApiTransport {
+  return (
+    typeof token === "object" &&
+    token !== null &&
+    (token as SlackApiTransport).kind === "api-transport"
+  );
+}
+
+export async function resolveBotToken(
+  credentials: SlackCredentials | undefined
+): Promise<string> {
+  const token = await tryResolveBotToken(credentials);
+  if (token === undefined) {
+    throw new Error(
+      "SLACK_BOT_TOKEN is required (set credentials.botToken, envPrefix, or the env var)."
+    );
+  }
+  return token;
+}
+
+/** Resolve the Socket Mode app-level token (`xapp-…`). */
+export async function resolveAppToken(
+  credentials: SlackCredentials | undefined
+): Promise<string> {
+  const token = await tryResolveAppToken(credentials);
+  if (token === undefined) {
+    throw new Error(
+      "SLACK_APP_TOKEN is required for Socket Mode (set credentials.appToken, envPrefix, or the env var)."
+    );
+  }
+  return token;
+}
+
+/** Channel-local continuation key: `<slackChannelId>:<threadTs>`. */
+export function slackContinuationKey(
+  channelId: string,
+  threadTs: string
+): string {
+  return `${channelId}:${threadTs}`;
+}
+
+function isPlatformError(error: unknown): error is WebAPIPlatformError {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code: unknown }).code === ErrorCode.PlatformError &&
+    "data" in error
+  );
+}
+
+async function createWebClient(
+  botToken: SlackBotToken | undefined
+): Promise<WebClient> {
+  return new WebClient(await resolveBotToken({ botToken }));
+}
+
+/**
+ * Call a Slack Web API method. Platform errors (`ok: false`) are returned as
+ * the response body (not thrown) so callers can soft-fail cleanly. When the
+ * bot token slot holds a {@link SlackApiTransport} (e.g. the Cursor account
+ * proxy), the call is executed by the transport instead of `@slack/web-api`.
+ */
+export async function callSlackApi(args: {
+  botToken: SlackBotToken | undefined;
+  operation: string;
+  body: Record<string, unknown>;
+}): Promise<Record<string, unknown>> {
+  if (isSlackApiTransport(args.botToken)) {
+    return args.botToken.call(args.operation, args.body);
+  }
+  const client = await createWebClient(args.botToken);
+  try {
+    const result = await client.apiCall(args.operation, args.body);
+    return result as unknown as Record<string, unknown>;
+  } catch (error) {
+    if (isPlatformError(error)) {
+      return error.data as unknown as Record<string, unknown>;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Soft-fail wrapper: never throws for Slack API errors. Network/throw
+ * errors become `{ ok: false, error }`. Unsupported feature errors set
+ * `unsupported: true`.
+ */
+export async function callSlackApiSoft(args: {
+  botToken: SlackBotToken | undefined;
+  operation: string;
+  body: Record<string, unknown>;
+}): Promise<SoftSlackResult> {
+  try {
+    const response = await callSlackApi(args);
+    if (response.ok === true) {
+      return { ok: true, ...response };
+    }
+    const error =
+      typeof response.error === "string" ? response.error : "unknown_error";
+    return {
+      ok: false,
+      error,
+      ...(SLACK_UNSUPPORTED_ERRORS.has(error) ? { unsupported: true } : {}),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function truncateTypingStatus(status: string, max?: number): string {
+  const limit = max ?? SLACK_STATUS_MAX_LEN;
+  const trimmed = status.trim().replace(/\s+/g, " ");
+  if (trimmed.length <= limit) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, limit - 1)}…`;
+}
+
+function truncateLoadingMessages(messages: string[]): string[] {
+  return messages
+    .map((message) =>
+      truncateTypingStatus(message, SLACK_LOADING_MESSAGE_MAX_LEN)
+    )
+    .filter((message) => message.length > 0)
+    .slice(0, 5);
+}
+
+export function truncateTitle(title: string, max?: number): string {
+  const limit = max ?? SLACK_TITLE_MAX_LEN;
+  const trimmed = title.trim().replace(/\s+/g, " ");
+  if (trimmed.length <= limit) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, limit - 1)}…`;
+}
+
+// ---------------------------------------------------------------------------
+// Assistant / stream helpers
+// ---------------------------------------------------------------------------
+
+export async function setThreadStatus(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  status: string;
+  loadingMessages?: string[];
+}): Promise<SoftSlackResult> {
+  if (args.channelId === "" || args.threadTs === "") {
+    return { ok: false, error: "missing_channel_or_thread" };
+  }
+  const status = truncateTypingStatus(args.status);
+  const loadingRaw =
+    args.loadingMessages !== undefined && args.loadingMessages.length > 0
+      ? args.loadingMessages
+      : status.length > 0
+        ? [
+            status,
+            ...SLACK_DEFAULT_LOADING_MESSAGES.filter((m) => m !== status),
+          ]
+        : [...SLACK_DEFAULT_LOADING_MESSAGES];
+  const loading_messages = truncateLoadingMessages(loadingRaw);
+  return callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "assistant.threads.setStatus",
+    body: {
+      channel_id: args.channelId,
+      thread_ts: args.threadTs,
+      status,
+      ...(loading_messages.length > 0 ? { loading_messages } : {}),
+    },
+  });
+}
+
+export async function setThreadTitle(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  title: string;
+}): Promise<SoftSlackResult> {
+  return callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "assistant.threads.setTitle",
+    body: {
+      channel_id: args.channelId,
+      thread_ts: args.threadTs,
+      title: truncateTitle(args.title),
+    },
+  });
+}
+
+export async function setSuggestedPrompts(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  prompts: SlackSuggestedPrompt[];
+  title?: string;
+}): Promise<SoftSlackResult> {
+  const body: Record<string, unknown> = {
+    channel_id: args.channelId,
+    thread_ts: args.threadTs,
+    prompts: args.prompts.map((p) => ({
+      title: p.title,
+      message: p.message,
+    })),
+  };
+  if (args.title !== undefined && args.title !== "") {
+    body.title = args.title;
+  }
+  return callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "assistant.threads.setSuggestedPrompts",
+    body,
+  });
+}
+
+export async function startChatStream(args: {
+  botToken: SlackBotToken | undefined;
+  channel: string;
+  thread_ts?: string;
+  markdown_text?: string;
+}): Promise<SoftSlackResult<{ ts: string; channel: string }>> {
+  const body: Record<string, unknown> = {
+    channel: args.channel,
+  };
+  if (args.thread_ts !== undefined && args.thread_ts !== "") {
+    body.thread_ts = args.thread_ts;
+  }
+  if (args.markdown_text !== undefined) {
+    body.markdown_text = args.markdown_text;
+  }
+  const result = await callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "chat.startStream",
+    body,
+  });
+  if (!result.ok) {
+    return result;
+  }
+  const ts = typeof result.ts === "string" ? result.ts : "";
+  const channel =
+    typeof result.channel === "string" ? result.channel : args.channel;
+  if (ts === "") {
+    return { ok: false, error: "missing_ts" };
+  }
+  return { ok: true, ts, channel };
+}
+
+export async function appendChatStream(args: {
+  botToken: SlackBotToken | undefined;
+  channel: string;
+  ts: string;
+  markdown_text?: string;
+  chunks?: StreamTaskChunk[];
+}): Promise<SoftSlackResult> {
+  const body: Record<string, unknown> = {
+    channel: args.channel,
+    ts: args.ts,
+  };
+  if (args.markdown_text !== undefined) {
+    body.markdown_text = args.markdown_text;
+  }
+  if (args.chunks !== undefined && args.chunks.length > 0) {
+    body.chunks = args.chunks;
+  }
+  return callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "chat.appendStream",
+    body,
+  });
+}
+
+export async function stopChatStream(args: {
+  botToken: SlackBotToken | undefined;
+  channel: string;
+  ts: string;
+  markdown_text?: string;
+  blocks?: unknown[];
+}): Promise<SoftSlackResult> {
+  const body: Record<string, unknown> = {
+    channel: args.channel,
+    ts: args.ts,
+  };
+  if (args.markdown_text !== undefined) {
+    body.markdown_text = args.markdown_text;
+  }
+  if (args.blocks !== undefined && args.blocks.length > 0) {
+    body.blocks = args.blocks;
+  }
+  return callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "chat.stopStream",
+    body,
+  });
+}
+
+export async function postMessage(args: {
+  botToken: SlackBotToken | undefined;
+  channel: string;
+  text: string;
+  threadTs?: string;
+  blocks?: unknown[];
+}): Promise<{ ts: string }> {
+  // Slack treats markdown_text as mutually exclusive with text and blocks
+  // (error: markdown_text_conflict). Prefer markdown when we have no
+  // blocks; with Block Kit, use text as body/fallback.
+  const base: Record<string, unknown> = {
+    channel: args.channel,
+    unfurl_links: false,
+    unfurl_media: false,
+  };
+  if (args.threadTs !== undefined && args.threadTs !== "") {
+    base.thread_ts = args.threadTs;
+  }
+  const hasBlocks = args.blocks !== undefined && args.blocks.length > 0;
+
+  let response: Record<string, unknown>;
+  if (hasBlocks) {
+    response = await callSlackApi({
+      botToken: args.botToken,
+      operation: "chat.postMessage",
+      body: {
+        ...base,
+        text: args.text,
+        blocks: args.blocks,
+      },
+    });
+  } else {
+    response = await callSlackApi({
+      botToken: args.botToken,
+      operation: "chat.postMessage",
+      body: {
+        ...base,
+        markdown_text: args.text,
+      },
+    });
+    // Older workspaces / scopes may not accept markdown_text — retry with text.
+    if (
+      response.ok !== true &&
+      (response.error === "markdown_text_conflict" ||
+        response.error === "invalid_arguments" ||
+        response.error === "invalid_blocks" ||
+        SLACK_UNSUPPORTED_ERRORS.has(String(response.error ?? "")))
+    ) {
+      response = await callSlackApi({
+        botToken: args.botToken,
+        operation: "chat.postMessage",
+        body: {
+          ...base,
+          text: args.text,
+        },
+      });
+    }
+  }
+  if (response.ok !== true) {
+    throw new Error(
+      `Slack chat.postMessage failed: ${String(response.error ?? "unknown_error")}`
+    );
+  }
+  const ts = typeof response.ts === "string" ? response.ts : "";
+  return { ts };
+}
+
+/** Replace an existing message (e.g. strip Approve/Deny after a decision). */
+export async function updateMessage(args: {
+  botToken: SlackBotToken | undefined;
+  channel: string;
+  ts: string;
+  text: string;
+  blocks?: unknown[];
+}): Promise<SoftSlackResult> {
+  const base: Record<string, unknown> = {
+    channel: args.channel,
+    ts: args.ts,
+  };
+  if (args.blocks !== undefined) {
+    // Blocks force the legacy text path (same as postMessage).
+    return callSlackApiSoft({
+      botToken: args.botToken,
+      operation: "chat.update",
+      body: {
+        ...base,
+        text: args.text,
+        blocks: args.blocks,
+      },
+    });
+  }
+  let result = await callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "chat.update",
+    body: {
+      ...base,
+      markdown_text: args.text,
+    },
+  });
+  // Older workspaces / scopes may not accept markdown_text — retry with text.
+  if (
+    !result.ok &&
+    (result.error === "markdown_text_conflict" ||
+      result.error === "invalid_arguments" ||
+      result.error === "invalid_blocks" ||
+      SLACK_UNSUPPORTED_ERRORS.has(String(result.error ?? "")))
+  ) {
+    result = await callSlackApiSoft({
+      botToken: args.botToken,
+      operation: "chat.update",
+      body: {
+        ...base,
+        text: args.text,
+      },
+    });
+  }
+  return result;
+}
+
+/**
+ * Delete a message (`chat.delete`). Soft-fails — used best-effort to remove an
+ * orphaned skeleton before falling back to a fresh post, so a failed delete
+ * never blocks delivery of the reply.
+ */
+export async function deleteMessage(args: {
+  botToken: SlackBotToken | undefined;
+  channel: string;
+  ts: string;
+}): Promise<SoftSlackResult> {
+  if (args.channel === "" || args.ts === "") {
+    return { ok: false, error: "missing_channel_or_ts" };
+  }
+  return callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "chat.delete",
+    body: {
+      channel: args.channel,
+      ts: args.ts,
+    },
+  });
+}
+
+export function buildSlackBinding(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  teamId?: string;
+  host: HostContext;
+  onThreadTsChanged?: (threadTs: string) => void;
+  log?: SlackLog;
+}): SlackBinding {
+  let threadTs = args.threadTs;
+  const log = args.log ?? defaultSlackLog;
+
+  const thread = {
+    async post(
+      text: string,
+      options?: { blocks?: unknown[] }
+    ): Promise<{ ts: string }> {
+      const result = await postMessage({
+        botToken: args.botToken,
+        channel: args.channelId,
+        text,
+        threadTs,
+        ...(options?.blocks === undefined ? {} : { blocks: options.blocks }),
+      });
+      if (result.ts !== "" && threadTs === "") {
+        threadTs = result.ts;
+        args.onThreadTsChanged?.(result.ts);
+      }
+      log.info("postMessage ok", {
+        channel: args.channelId,
+        thread_ts: threadTs,
+        message_ts: result.ts,
+      });
+      return { ts: result.ts };
+    },
+    async startTyping(
+      status: string,
+      loadingMessages?: string[]
+    ): Promise<void> {
+      if (args.channelId === "" || threadTs === "") {
+        return;
+      }
+      const result = await setThreadStatus({
+        botToken: args.botToken,
+        channelId: args.channelId,
+        threadTs,
+        status,
+        ...(loadingMessages === undefined ? {} : { loadingMessages }),
+      });
+      if (!result.ok) {
+        log.warn("assistant.threads.setStatus not-ok", {
+          error: result.error,
+          channel: args.channelId,
+          thread_ts: threadTs,
+        });
+      }
+    },
+    async setTitle(title: string): Promise<void> {
+      if (args.channelId === "" || threadTs === "") {
+        return;
+      }
+      const result = await setThreadTitle({
+        botToken: args.botToken,
+        channelId: args.channelId,
+        threadTs,
+        title,
+      });
+      if (!result.ok) {
+        log.warn("assistant.threads.setTitle not-ok", {
+          error: result.error,
+          channel: args.channelId,
+          thread_ts: threadTs,
+        });
+      }
+    },
+    async setSuggestedPrompts(
+      prompts: SlackSuggestedPrompt[],
+      title?: string
+    ): Promise<void> {
+      if (args.channelId === "" || threadTs === "" || prompts.length === 0) {
+        return;
+      }
+      const result = await setSuggestedPrompts({
+        botToken: args.botToken,
+        channelId: args.channelId,
+        threadTs,
+        prompts,
+        ...(title === undefined ? {} : { title }),
+      });
+      if (!result.ok) {
+        log.warn("assistant.threads.setSuggestedPrompts not-ok", {
+          error: result.error,
+          channel: args.channelId,
+          thread_ts: threadTs,
+        });
+      }
+    },
+  };
+
+  return {
+    thread,
+    slack: {
+      channelId: args.channelId,
+      get threadTs() {
+        return threadTs;
+      },
+      ...(args.teamId === undefined ? {} : { teamId: args.teamId }),
+    },
+    host: args.host,
+  };
+}