@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/messaging/providers/slack/client.ts

@@ -1,9 +1,9 @@
 /**
- * Low-level Slack Web API wrapper.
+ * Typed Slack Web API method wrappers.
  *
  * All methods accept either an OAuthConnection or a raw token string.
- * Throws SlackApiError on failures, with status: 401 on auth errors
- * for withValidToken compatibility.
+ * Transport (retries, envelope checking, the unified `SlackApiError`) lives
+ * in `web-api-transport.ts`.
  *
  * String overloads are retained for non-OAuth callers (e.g. slack/share.ts)
  * that pass raw bot tokens via resolveSlackToken(). These bypass the
@@ -16,6 +16,7 @@ import type {
   SlackAuthTestResponse,
   SlackBotsInfoResponse,
   SlackConversationHistoryResponse,
+  SlackConversationInfoResponse,
   SlackConversationMarkResponse,
   SlackConversationRepliesResponse,
   SlackConversationsListResponse,
@@ -26,250 +27,7 @@ import type {
   SlackUserInfoResponse,
   SlackUsersListResponse,
 } from "./types.js";
-
-const SLACK_API_BASE = "https://slack.com/api";
-const MAX_RATE_LIMIT_RETRIES = 3;
-const DEFAULT_RETRY_AFTER_S = 1;
-
-export class SlackApiError extends Error {
-  constructor(
-    public readonly status: number,
-    public readonly slackError: string,
-    message: string,
-  ) {
-    super(message);
-    this.name = "SlackApiError";
-  }
-}
-
-/**
- * Sleep helper that respects Slack's Retry-After header value.
- */
-function sleepMs(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * Check a Slack API response envelope for errors and map to SlackApiError.
- * Returns the data if ok, throws otherwise.
- */
-function checkSlackEnvelope<T extends SlackApiResponse>(data: T): T {
-  if (!data.ok) {
-    const slackError = data.error ?? "unknown_error";
-    const status = [
-      "invalid_auth",
-      "token_expired",
-      "token_revoked",
-      "not_authed",
-    ].includes(slackError)
-      ? 401
-      : 400;
-    throw new SlackApiError(
-      status,
-      slackError,
-      `Slack API error: ${slackError}`,
-    );
-  }
-  return data;
-}
-
-/**
- * Build a Slack API request using a raw token (for retry via `connection.withToken`).
- */
-async function rawSlackRequest<T extends SlackApiResponse>(
-  token: string,
-  method: string,
-  query: Record<string, string> | undefined,
-  body: Record<string, unknown> | undefined,
-): Promise<T> {
-  let url = `${SLACK_API_BASE}/${method}`;
-  const headers: Record<string, string> = {
-    Authorization: `Bearer ${token}`,
-  };
-
-  let init: RequestInit;
-  if (body) {
-    headers["Content-Type"] = "application/json; charset=utf-8";
-    init = { method: "POST", headers, body: JSON.stringify(body) };
-  } else {
-    if (query && Object.keys(query).length > 0) {
-      url += `?${new URLSearchParams(query)}`;
-    }
-    init = { method: "GET", headers };
-  }
-
-  const resp = await fetch(url, init);
-  if (resp.status === 429) {
-    throw new SlackApiError(429, "rate_limited", "Slack API rate limited");
-  }
-  if (!resp.ok) {
-    throw new SlackApiError(
-      resp.status,
-      `http_${resp.status}`,
-      `Slack API HTTP ${resp.status}`,
-    );
-  }
-  return checkSlackEnvelope((await resp.json()) as T);
-}
-
-/**
- * Execute a Slack API request via OAuthConnection with rate-limit retry.
- *
- * Slack returns HTTP 200 with `{ ok: false, error: "invalid_auth" }` for
- * auth errors. Because `connection.request()` delegates to `withValidToken`
- * which only retries on HTTP-level 401s, we catch Slack envelope auth
- * errors (mapped to SlackApiError with status 401) and perform a single
- * retry via `connection.withToken()` which forces a token refresh before
- * giving us the new token.
- */
-async function requestViaConnection<T extends SlackApiResponse>(
-  connection: OAuthConnection,
-  method: string,
-  params?: Record<string, string | undefined>,
-  body?: Record<string, unknown>,
-): Promise<T> {
-  const query: Record<string, string> | undefined = params
-    ? Object.fromEntries(
-        Object.entries(params).filter(
-          (entry): entry is [string, string] => entry[1] !== undefined,
-        ),
-      )
-    : undefined;
-
-  for (let attempt = 0; attempt <= MAX_RATE_LIMIT_RETRIES; attempt++) {
-    const resp = await connection.request({
-      method: body ? "POST" : "GET",
-      path: `/${method}`,
-      query: query && Object.keys(query).length > 0 ? query : undefined,
-      body,
-    });
-
-    // Handle 429 rate limits with Retry-After backoff
-    if (resp.status === 429) {
-      if (attempt >= MAX_RATE_LIMIT_RETRIES) {
-        throw new SlackApiError(429, "rate_limited", "Slack API rate limited");
-      }
-      const retryAfter =
-        parseInt(
-          resp.headers["retry-after"] ?? resp.headers["Retry-After"] ?? "",
-          10,
-        ) || DEFAULT_RETRY_AFTER_S;
-      await sleepMs(retryAfter * 1000);
-      continue;
-    }
-
-    if (resp.status >= 400) {
-      throw new SlackApiError(
-        resp.status,
-        `http_${resp.status}`,
-        `Slack API HTTP ${resp.status}`,
-      );
-    }
-
-    const data = resp.body as T;
-
-    // Handle rate_limited error in response body (some Slack APIs return 200 with error)
-    if (
-      !data.ok &&
-      data.error === "rate_limited" &&
-      attempt < MAX_RATE_LIMIT_RETRIES
-    ) {
-      await sleepMs(DEFAULT_RETRY_AFTER_S * 1000);
-      continue;
-    }
-
-    try {
-      return checkSlackEnvelope(data);
-    } catch (err) {
-      // Slack envelope auth errors (invalid_auth, token_expired, etc.) come
-      // back as HTTP 200, so they escape withValidToken's retry scope inside
-      // connection.request(). Catch them here and retry once with a freshly-
-      // refreshed token via connection.withToken().
-      if (err instanceof SlackApiError && err.status === 401) {
-        return connection.withToken((freshToken) =>
-          rawSlackRequest<T>(freshToken, method, query, body),
-        );
-      }
-      throw err;
-    }
-  }
-
-  // Unreachable, but TypeScript needs this
-  throw new SlackApiError(429, "rate_limited", "Slack API rate limited");
-}
-
-/**
- * Execute a Slack API request via raw token with rate-limit retry.
- */
-async function requestViaToken<T extends SlackApiResponse>(
-  token: string,
-  method: string,
-  params?: Record<string, string | undefined>,
-  body?: Record<string, unknown>,
-): Promise<T> {
-  let url = `${SLACK_API_BASE}/${method}`;
-  const headers: Record<string, string> = {
-    Authorization: `Bearer ${token}`,
-  };
-
-  let init: RequestInit;
-  if (body) {
-    headers["Content-Type"] = "application/json; charset=utf-8";
-    init = { method: "POST", headers, body: JSON.stringify(body) };
-  } else {
-    if (params) {
-      const searchParams = new URLSearchParams();
-      for (const [k, v] of Object.entries(params)) {
-        if (v !== undefined) {
-          searchParams.set(k, v);
-        }
-      }
-      url += `?${searchParams}`;
-    }
-    init = { method: "GET", headers };
-  }
-
-  for (let attempt = 0; attempt <= MAX_RATE_LIMIT_RETRIES; attempt++) {
-    const resp = await fetch(url, init);
-
-    // Handle 429 rate limits with Retry-After backoff
-    if (resp.status === 429) {
-      if (attempt >= MAX_RATE_LIMIT_RETRIES) {
-        throw new SlackApiError(429, "rate_limited", "Slack API rate limited");
-      }
-      const retryAfter =
-        parseInt(resp.headers.get("Retry-After") ?? "", 10) ||
-        DEFAULT_RETRY_AFTER_S;
-      await sleepMs(retryAfter * 1000);
-      continue;
-    }
-
-    if (!resp.ok) {
-      throw new SlackApiError(
-        resp.status,
-        `http_${resp.status}`,
-        `Slack API HTTP ${resp.status}`,
-      );
-    }
-
-    const data = (await resp.json()) as T;
-
-    // Handle rate_limited error in response body (some Slack APIs return 200 with error)
-    if (
-      !data.ok &&
-      data.error === "rate_limited" &&
-      attempt < MAX_RATE_LIMIT_RETRIES
-    ) {
-      await sleepMs(DEFAULT_RETRY_AFTER_S * 1000);
-      continue;
-    }
-
-    return checkSlackEnvelope(data);
-  }
-
-  // Unreachable, but TypeScript needs this
-  throw new SlackApiError(429, "rate_limited", "Slack API rate limited");
-}
+import { slackRequest } from "./web-api-transport.js";
 
 async function request<T extends SlackApiResponse>(
   connectionOrToken: OAuthConnection | string,
@@ -277,10 +35,10 @@ async function request<T extends SlackApiResponse>(
   params?: Record<string, string | undefined>,
   body?: Record<string, unknown>,
 ): Promise<T> {
-  if (typeof connectionOrToken === "string") {
-    return requestViaToken<T>(connectionOrToken, method, params, body);
-  }
-  return requestViaConnection<T>(connectionOrToken, method, params, body);
+  return slackRequest<T>(connectionOrToken, method, {
+    ...(params ? { query: params } : {}),
+    ...(body ? { body } : {}),
+  });
 }
 
 export async function authTest(
@@ -397,6 +155,17 @@ export async function conversationsOpen(
   );
 }
 
+export async function conversationInfo(
+  connectionOrToken: OAuthConnection | string,
+  channel: string,
+): Promise<SlackConversationInfoResponse> {
+  return request<SlackConversationInfoResponse>(
+    connectionOrToken,
+    "conversations.info",
+    { channel },
+  );
+}
+
 export async function userInfo(
   connectionOrToken: OAuthConnection | string,
   userId: string,

package/src/messaging/providers/slack/send.test.ts

@@ -15,14 +15,6 @@ mock.module("./api.js", () => ({
     callSlackApiMock(method, body),
   callSlackApiForm: async () => ({}),
   completeSlackUpload: async () => {},
-  SlackApiError: class SlackApiError extends Error {
-    readonly slackError: string | undefined;
-
-    constructor(slackError: string | undefined) {
-      super(slackError ?? "unknown");
-      this.slackError = slackError;
-    }
-  },
   uploadToSlackUrl: async () => {},
   startSlackStream: (params: { markdownText?: string }) =>
     callSlackApiMock("chat.startStream", { ...params }),
@@ -32,7 +24,10 @@ mock.module("./api.js", () => ({
     callSlackApiMock("chat.stopStream", { ...params }),
 }));
 
-const { SlackApiError } = await import("./api.js");
+// The real error class: send.ts branches on `instanceof SlackApiError` from
+// the (unmocked) shared transport, so thrown test errors must be real
+// instances or every branch under test would silently take the generic path.
+const { SlackApiError } = await import("./web-api-transport.js");
 const { sendSlackAssistantThreadStatus, sendSlackReply } =
   await import("./send.js");
 

package/src/messaging/providers/slack/send.ts

@@ -20,12 +20,12 @@ import {
   callSlackApi,
   callSlackApiForm,
   completeSlackUpload,
-  SlackApiError,
   startSlackStream,
   stopSlackStream,
   uploadToSlackUrl,
 } from "./api.js";
 import { renderSlackBlocks } from "./render.js";
+import { SlackApiError } from "./web-api-transport.js";
 
 const log = getLogger("slack-send");
 

package/src/messaging/providers/slack/types.ts

@@ -27,6 +27,7 @@ export interface SlackBotsInfoResponse extends SlackApiResponse {
 export interface SlackConversation {
   id: string;
   name?: string;
+  name_normalized?: string;
   is_channel?: boolean;
   is_group?: boolean;
   is_im?: boolean;
@@ -45,6 +46,10 @@ export interface SlackConversation {
   is_user_deleted?: boolean;
 }
 
+export interface SlackConversationInfoResponse extends SlackApiResponse {
+  channel: SlackConversation;
+}
+
 export interface SlackConversationsListResponse extends SlackApiResponse {
   channels: SlackConversation[];
   response_metadata?: { next_cursor?: string };

package/src/messaging/providers/slack/web-api-transport.test.ts

@@ -0,0 +1,181 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import {
+  checkSlackEnvelope,
+  classifySlackError,
+  rawSlackRequest,
+  SlackApiError,
+} from "./web-api-transport.js";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** Await a promise expected to reject with SlackApiError and return it. */
+async function captureSlackApiError(
+  promise: Promise<unknown>,
+): Promise<SlackApiError> {
+  try {
+    await promise;
+  } catch (err) {
+    if (err instanceof SlackApiError) {
+      return err;
+    }
+    throw err;
+  }
+  throw new Error("expected the promise to reject with SlackApiError");
+}
+
+describe("SlackApiError", () => {
+  test("derives status from category when not explicit", () => {
+    expect(new SlackApiError("invalid_auth").status).toBe(401);
+    expect(new SlackApiError("token_expired").status).toBe(401);
+    expect(new SlackApiError("rate_limited").status).toBe(429);
+    expect(new SlackApiError("ratelimited").status).toBe(429);
+    expect(new SlackApiError("channel_not_found").status).toBe(400);
+    expect(new SlackApiError("invalid_blocks").status).toBe(400);
+  });
+
+  test("explicit status wins over the derived one", () => {
+    expect(new SlackApiError("http_503", { status: 503 }).status).toBe(503);
+  });
+
+  test("normalizes a missing error code to unknown_error", () => {
+    const err = new SlackApiError(undefined);
+    expect(err.slackError).toBe("unknown_error");
+    expect(err.category).toBe("unknown");
+    expect(err.message).toBe("Slack API error: unknown_error");
+  });
+
+  test("classifies known Slack error codes", () => {
+    expect(new SlackApiError("missing_scope").category).toBe("permission");
+    expect(new SlackApiError("is_archived").category).toBe("channel_not_found");
+    expect(new SlackApiError("message_not_found").category).toBe("not_found");
+    expect(classifySlackError("some_new_code")).toBe("unknown");
+  });
+});
+
+describe("checkSlackEnvelope", () => {
+  test("passes ok envelopes through", () => {
+    const data = { ok: true as const };
+    expect(checkSlackEnvelope(data)).toBe(data);
+  });
+
+  test("throws a classified SlackApiError on ok: false", () => {
+    expect(() =>
+      checkSlackEnvelope({ ok: false, error: "invalid_auth" }),
+    ).toThrow(SlackApiError);
+    try {
+      checkSlackEnvelope({ ok: false, error: "invalid_auth" });
+    } catch (err) {
+      expect((err as SlackApiError).status).toBe(401);
+      expect((err as SlackApiError).category).toBe("auth");
+    }
+  });
+});
+
+describe("rawSlackRequest", () => {
+  test("retries HTTP 429 honoring Retry-After, then succeeds", async () => {
+    let calls = 0;
+    globalThis.fetch = mock(async () => {
+      calls++;
+      if (calls === 1) {
+        return new Response("", {
+          status: 429,
+          headers: { "Retry-After": "0" },
+        });
+      }
+      return jsonResponse({ ok: true });
+    }) as unknown as typeof fetch;
+
+    const data = await rawSlackRequest("xoxb-t", "conversations.info", {
+      query: { channel: "C1" },
+    });
+    expect(data.ok).toBe(true);
+    expect(calls).toBe(2);
+  });
+
+  test("retries 5xx and reports SlackApiError after exhausting retries", async () => {
+    let calls = 0;
+    globalThis.fetch = mock(async () => {
+      calls++;
+      return new Response("", { status: 503 });
+    }) as unknown as typeof fetch;
+
+    // The fixed 1s backoff between 5xx retries is real time, so this test
+    // runs ~3s (3 retries); the timeout below gives it headroom.
+    const promise = rawSlackRequest("xoxb-t", "chat.postMessage", {
+      body: { channel: "C1", text: "hi" },
+    });
+    const err = await captureSlackApiError(promise);
+    expect(err.status).toBe(503);
+    expect(err.slackError).toBe("http_503");
+    expect(calls).toBe(4);
+  }, 10_000);
+
+  test("throws classified SlackApiError for non-retryable envelope errors", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({ ok: false, error: "channel_not_found" }),
+    ) as unknown as typeof fetch;
+
+    const promise = rawSlackRequest("xoxb-t", "conversations.info", {
+      query: { channel: "C_MISSING" },
+    });
+    const err = await captureSlackApiError(promise);
+    expect(err.category).toBe("channel_not_found");
+  });
+
+  test("throws http_<status> SlackApiError for non-JSON 4xx responses", async () => {
+    globalThis.fetch = mock(
+      async () => new Response("forbidden", { status: 403 }),
+    ) as unknown as typeof fetch;
+
+    const promise = rawSlackRequest("xoxb-t", "conversations.info", {});
+    const err = await captureSlackApiError(promise);
+    expect(err.status).toBe(403);
+    expect(err.slackError).toBe("http_403");
+  });
+
+  test("rejects form bodies dispatched over an OAuth connection", async () => {
+    const connection = {
+      request: async () => {
+        throw new Error("connection.request must not be reached for forms");
+      },
+      withToken: async () => {
+        throw new Error("withToken must not be reached for forms");
+      },
+    };
+    const { slackRequest } = await import("./web-api-transport.js");
+    const err = await captureSlackApiError(
+      slackRequest(connection as never, "files.getUploadURLExternal", {
+        form: new URLSearchParams({ filename: "a.png" }),
+      }),
+    );
+    expect(err.slackError).toBe("form_unsupported_over_oauth");
+  });
+
+  test("sends form bodies as x-www-form-urlencoded POSTs", async () => {
+    let capturedInit: RequestInit | undefined;
+    globalThis.fetch = mock(async (_input, init) => {
+      capturedInit = init;
+      return jsonResponse({ ok: true });
+    }) as unknown as typeof fetch;
+
+    await rawSlackRequest("xoxb-t", "files.getUploadURLExternal", {
+      form: new URLSearchParams({ filename: "a.png", length: "10" }),
+    });
+    expect(capturedInit?.method).toBe("POST");
+    expect(
+      (capturedInit?.headers as Record<string, string>)["Content-Type"],
+    ).toBe("application/x-www-form-urlencoded");
+  });
+});