slack-term 1.13.0 → 1.15.0

package/ts/slack.ts

@@ -128,6 +128,43 @@ export async function authTest(token: string): Promise<{ team: string; teamId: s
   };
 }
 
+// auth.test plus the token's granted scopes. Slack returns the granted bot/user
+// scopes in the `X-OAuth-Scopes` response header on every Web API call, which is
+// the only way to learn what a token can do without probing each endpoint.
+export async function authScopes(token: string): Promise<{
+  userId: string; botId: string; team: string; url: string; scopes: string[];
+}> {
+  const res = await fetch(`${base()}/auth.test`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (res.status === 429) {
+    const retryAfter = parseInt(res.headers.get("retry-after") ?? "60", 10);
+    throw new RateLimitError(isNaN(retryAfter) ? 60 : retryAfter);
+  }
+  const scopesHeader = res.headers.get("x-oauth-scopes") ?? "";
+  const body = (await res.json()) as {
+    ok?: boolean; error?: string; user_id?: string; bot_id?: string; team?: string; url?: string;
+  };
+  if (body.ok !== true) throw new Error(`Slack error on auth.test: ${body.error ?? "unknown"}`);
+  return {
+    userId: body.user_id ?? "",
+    botId: body.bot_id ?? "",
+    team: body.team ?? "",
+    url: body.url ?? "",
+    scopes: scopesHeader.split(",").map((s) => s.trim()).filter(Boolean),
+  };
+}
+
+// Resolve a bot's app_id (and bot user id) from its bot_id — needed to build the
+// app-settings deep link in messaging diagnostics.
+export async function botsInfo(token: string, botId: string): Promise<{ appId: string; userId: string }> {
+  const resp = (await get(token, "bots.info", { bot: botId })) as {
+    bot?: { app_id?: string; user_id?: string };
+  };
+  return { appId: resp.bot?.app_id ?? "", userId: resp.bot?.user_id ?? "" };
+}
+
 export async function history(token: string, channel: string, limit = 20, oldest?: string, cursor?: string): Promise<Json> {
   const params: Record<string, string> = { channel, limit: String(limit) };
   if (oldest !== undefined) params.oldest = oldest;
@@ -189,6 +226,7 @@ export async function send(
   channel: string,
   text: string,
   threadTs?: string,
+  replyBroadcast?: boolean,
 ): Promise<string> {
   const body: Record<string, Json> = {
     channel,
@@ -196,6 +234,9 @@ export async function send(
     blocks: [{ type: "markdown", text }],
   };
   if (threadTs !== undefined) body.thread_ts = threadTs;
+  // "Also send to channel": broadcast a threaded reply back to the channel.
+  // Only meaningful alongside thread_ts; Slack ignores it on top-level sends.
+  if (replyBroadcast && threadTs !== undefined) body.reply_broadcast = true;
   const resp = (await post(token, "chat.postMessage", body)) as { ts?: string };
   return resp.ts ?? "";
 }
@@ -238,6 +279,18 @@ export async function deleteScheduledMessage(
   });
 }
 
+export async function getPermalink(
+  token: string,
+  channel: string,
+  messageTs: string,
+): Promise<string> {
+  const resp = (await get(token, "chat.getPermalink", {
+    channel,
+    message_ts: messageTs,
+  })) as { permalink?: string };
+  return resp.permalink ?? "";
+}
+
 export async function editMessage(
   token: string,
   channel: string,
@@ -253,6 +306,14 @@ export async function editMessage(
   return resp.ts ?? ts;
 }
 
+export async function deleteMessage(
+  token: string,
+  channel: string,
+  ts: string,
+): Promise<void> {
+  await post(token, "chat.delete", { channel, ts });
+}
+
 export async function listConversations(token: string): Promise<Json> {
   const allChannels: Json[] = [];
   let cursor = "";
@@ -285,19 +346,63 @@ function normName(s: string): string {
   return s.toLowerCase().replace(/[-_\s]/g, "");
 }
 
-/** Parse a Slack permalink, returning channel ID and (optional) message ts.
+/**
+ * Resolve `@name` (or a raw U…/W… id) to a user ID. Used when DMing as a bot:
+ * the lookup runs on a *user* token (which has users:read), then the caller
+ * opens the DM with the bot token — so the bot never needs users:read.
+ */
+export async function resolveUserId(token: string, ref: string, cookie?: string): Promise<string> {
+  if (!ref.startsWith("@")) {
+    if (/^[UW][A-Za-z0-9]{6,}$/.test(ref)) return ref;
+    throw new Error(`Expected @user or a user ID, got: ${ref}`);
+  }
+  const nameNorm = normName(ref.slice(1));
+  const selfInfo = (await get(token, "auth.test", {}, cookie)) as { user_id?: string; user?: string };
+  if (nameNorm === "you" || nameNorm === "me" || normName(selfInfo.user ?? "") === nameNorm) {
+    if (!selfInfo.user_id) throw new Error("auth.test did not return user_id");
+    return selfInfo.user_id;
+  }
+  let cursor = "";
+  while (true) {
+    const params: Record<string, string> = { limit: "200" };
+    if (cursor) params.cursor = cursor;
+    const resp = (await get(token, "users.list", params, cookie)) as {
+      members?: Array<{ id?: string; name?: string; real_name?: string; profile?: { display_name?: string } }>;
+      response_metadata?: { next_cursor?: string };
+    };
+    for (const u of resp.members ?? []) {
+      const n = normName(u.name ?? "");
+      const rn = normName(u.real_name ?? "");
+      const dn = normName(u.profile?.display_name ?? "");
+      if (n === nameNorm || rn === nameNorm || (dn && dn === nameNorm)) return u.id ?? "";
+    }
+    cursor = resp.response_metadata?.next_cursor ?? "";
+    if (!cursor) break;
+  }
+  throw new Error(`User not found: ${ref}`);
+}
+
+/** Parse a Slack permalink, returning channel ID, optional message ts, and optional thread_ts.
  *  Supports both forms:
  *    https://app.slack.com/client/T.../C...[/p1700000000000100]
- *    https://<ws>.slack.com/archives/C...[/p1700000000000100][?thread_ts=...]
+ *    https://<ws>.slack.com/archives/C...[/p1700000000000100][?thread_ts=...][&cid=C...]
  */
-export function parseSlackPermalink(s: string): { channel: string; ts?: string } | undefined {
+export function parseSlackPermalink(s: string): { channel: string; ts?: string; threadTs?: string } | undefined {
   const m = s.match(
     /(?:app\.slack\.com\/client\/T[A-Za-z0-9]+|[A-Za-z0-9-]+\.slack\.com\/archives)\/([A-Za-z0-9]+)(?:\/p(\d{10})(\d{6}))?/,
   );
   if (!m) return undefined;
   const channel = m[1]!;
   const ts = m[2] && m[3] ? `${m[2]}.${m[3]}` : undefined;
-  return ts ? { channel, ts } : { channel };
+  const qsStart = s.indexOf("?");
+  const qs = qsStart >= 0 ? new URLSearchParams(s.slice(qsStart)) : undefined;
+  const threadTs = qs?.get("thread_ts") ?? undefined;
+  const cidFromQs = qs?.get("cid") ?? undefined;
+  const resolvedChannel = cidFromQs ?? channel;
+  const result: { channel: string; ts?: string; threadTs?: string } = { channel: resolvedChannel };
+  if (ts) result.ts = ts;
+  if (threadTs) result.threadTs = threadTs;
+  return result;
 }
 
 function parseSlackUrl(s: string): string | undefined {
@@ -318,6 +423,21 @@ export async function resolveChannel(token: string, ref: string, cookie?: string
   const nameNorm = normName(rawName);
 
   if (isIm) {
+    // Use auth.test to check if @name refers to self (avoids users:read scope requirement).
+    // auth.test is always available; users.list requires users:read which xoxc- tokens lack.
+    const selfInfo = (await get(token, "auth.test", {}, cookie)) as { user_id?: string; user?: string };
+    const isSelf = nameNorm === "you" || nameNorm === "me" || normName(selfInfo.user ?? "") === nameNorm;
+    if (isSelf) {
+      const userId = selfInfo.user_id;
+      if (!userId) throw new Error("auth.test did not return user_id");
+      const dmResp = (await get(token, "conversations.list", { types: "im", limit: "200" }, cookie)) as {
+        channels?: Array<{ id?: string; user?: string }>;
+      };
+      const dm = (dmResp.channels ?? []).find((ch) => ch.user === userId);
+      if (dm?.id) return String(dm.id);
+      return openDm(token, userId);
+    }
+
     // Find user ID first via users.list (batch), then locate existing DM.
     let userId = "";
     let userCursor = "";
@@ -562,6 +682,20 @@ export async function uploadFile(
   return result;
 }
 
+// client.boot — internal endpoint that returns a WebSocket URL for RTM
+export async function clientBoot(token: string, cookie: string): Promise<{ wsUrl: string; selfId: string }> {
+  const resp = (await postSession(token, "client.boot", {}, cookie)) as Record<string, Json>;
+  const wsUrl = typeof resp.url === "string" ? resp.url : undefined;
+  if (!wsUrl) {
+    const keys = Object.keys(resp).join(", ");
+    throw new Error(`client.boot did not return a WebSocket URL. Keys: ${keys}`);
+  }
+  const self_ = resp.self && typeof resp.self === "object" && !Array.isArray(resp.self)
+    ? resp.self as Record<string, Json>
+    : {};
+  return { wsUrl, selfId: typeof self_.id === "string" ? self_.id : "" };
+}
+
 // Safe nested access
 export function getPath(obj: Json, path: readonly (string | number)[]): Json | undefined {
   let cur: Json | undefined = obj;

package/ts/tail.ts

@@ -1,5 +1,6 @@
-import { history, resolveChannel, userInfoPair, authTest, conversationInfo, RateLimitError, type Json } from "./slack.ts";
+import { history, replies, resolveChannel, parseSlackPermalink, userInfoPair, authTest, conversationInfo, RateLimitError, type Json } from "./slack.ts";
 import { resolveDateMarkup, resolveMentions } from "./format.ts";
+import { tailRTMImpl } from "./rtm.ts";
 
 export function parseSince(s: string): number {
   const m = s.match(/^(\d+(?:\.\d+)?)(s|m|h|d)$/);
@@ -17,6 +18,7 @@ export function parseSince(s: string): number {
 export const _internals = {
   sleep: (ms: number): Promise<void> => new Promise((res) => setTimeout(res, ms)),
   now: (): number => Date.now(),
+  tailRTM: tailRTMImpl,
 };
 
 function asRecord(v: Json | undefined): Record<string, Json> {
@@ -27,6 +29,21 @@ function asArray(v: Json | undefined): Json[] {
   return Array.isArray(v) ? v : [];
 }
 
+// Numeric comparison of Slack ts strings ("1700000001.000000"). ts is a
+// per-channel-unique, monotonically increasing message id, so this gives a
+// total order for merging history (top-level) with replies (thread) streams.
+function tsNum(ts: string): number {
+  return Number(ts) || 0;
+}
+
+// A message is a thread reply (not a root/broadcast) when it carries a
+// thread_ts that differs from its own ts.
+function isThreadReply(m: Record<string, Json>): boolean {
+  const ts = typeof m.ts === "string" ? m.ts : "";
+  const tts = typeof m.thread_ts === "string" ? m.thread_ts : "";
+  return tts !== "" && tts !== ts;
+}
+
 function slackTsToIso(tsRaw: string): string {
   const [secStr, fracStr = "000000"] = tsRaw.split(".");
   const d = new Date(Number(secStr) * 1000);
@@ -64,12 +81,18 @@ async function formatTailLine(
   const resolved = resolveDateMarkup(await resolveMentions(token, raw, cache));
   const lines = resolved.split("\n");
   const body = lines[0] + (lines.length > 1 ? "\n" + lines.slice(1).map((l) => `  ${l}`).join("\n") : "");
+  // Annotate thread replies so a merged channel+thread stream stays readable.
+  const mark = isThreadReply(m) ? "↳ " : "";
   const who = chLabel ? `${chLabel}  @${handle}` : `@${handle}`;
-  return `${stamp}  ${who}:  ${body}`;
+  return `${stamp}  ${mark}${who}:  ${body}`;
 }
 
 type PollOpts = {
   thread?: string;
+  // Watch one thread AND the channel's top-level timeline in a single stream.
+  // history() never returns non-broadcast thread replies, so we additionally
+  // pull conversations.replies(watchThread) each cycle and merge.
+  watchThread?: string;
   me?: boolean;
   myUserId?: string;
 };
@@ -82,7 +105,7 @@ export async function pollCycle(
   seen: Set<string>,
   cache: Map<string, string>,
   pageCursor?: string,
-): Promise<{ newCursor: string; lines: string[]; hasMore: boolean; nextPageCursor: string | undefined }> {
+): Promise<{ newCursor: string; lines: string[]; hasMore: boolean; nextPageCursor: string | undefined; emittedOther: boolean }> {
   const histResp = asRecord((await history(
     token,
     channelId,
@@ -91,17 +114,37 @@ export async function pollCycle(
     pageCursor,
   )) as Json);
   // history returns newest-first; reverse to emit oldest-first
-  const msgs = asArray(histResp.messages).map(asRecord).reverse();
+  const histMsgs = asArray(histResp.messages).map(asRecord).reverse();
 
   const meta = asRecord(histResp.response_metadata as Json | undefined);
   const nextPageCursor = (histResp.has_more === true && typeof meta.next_cursor === "string")
     ? meta.next_cursor
     : undefined;
 
+  // --watch-thread: history omits non-broadcast thread replies, so pull the
+  // watched thread separately and merge it into the channel timeline. Only on
+  // the first (non-paginated) page so we fetch it once per cycle. The parent
+  // (ts === watchThread) is also returned by replies() but already lives in
+  // history — drop it to avoid double-emit.
+  let replyMsgs: Record<string, Json>[] = [];
+  if (opts.watchThread && !pageCursor) {
+    const repResp = asRecord((await replies(token, channelId, opts.watchThread, 50)) as Json);
+    replyMsgs = asArray(repResp.messages).map(asRecord)
+      .filter((m) => (typeof m.ts === "string" ? m.ts : "") !== opts.watchThread);
+  }
+
+  // Merge and sort ascending by ts (a total order across both streams).
+  type Entry = { m: Record<string, Json>; fromHistory: boolean };
+  const entries: Entry[] = [
+    ...histMsgs.map((m) => ({ m, fromHistory: true })),
+    ...replyMsgs.map((m) => ({ m, fromHistory: false })),
+  ].sort((a, b) => tsNum(typeof a.m.ts === "string" ? a.m.ts : "") - tsNum(typeof b.m.ts === "string" ? b.m.ts : ""));
+
   const lines: string[] = [];
   let newCursor = cursor;
+  let emittedOther = false;
 
-  for (const m of msgs) {
+  for (const { m, fromHistory } of entries) {
     const ts = typeof m.ts === "string" ? m.ts : "";
     if (!ts || seen.has(ts)) continue;
 
@@ -114,6 +157,14 @@ export async function pollCycle(
       if (parentTs !== opts.thread && ts !== opts.thread) continue;
     }
 
+    // --watch-thread shows all top-level posts plus the watched thread's
+    // replies; drop replies belonging to *other* threads (e.g. a stray
+    // reply_broadcast surfaced by history).
+    if (opts.watchThread && isThreadReply(m)) {
+      const tts = typeof m.thread_ts === "string" ? m.thread_ts : "";
+      if (tts !== opts.watchThread) continue;
+    }
+
     if (opts.me && opts.myUserId) {
       const text = typeof m.text === "string" ? m.text : "";
       if (!text.includes(`<@${opts.myUserId}>`)) continue;
@@ -126,19 +177,44 @@ export async function pollCycle(
     }
 
     lines.push(await formatTailLine(token, m, cache));
-    newCursor = ts;
+    // Advance the history cursor only on top-level messages — thread replies
+    // are never returned by history(), so their ts must not move `oldest`.
+    if (fromHistory) newCursor = ts;
+    // Track whether a message from someone *other than me* arrived, so
+    // --exit-on-message can wait for an actual reply (not my own posts).
+    const u = typeof m.user === "string" ? m.user : "";
+    if (!opts.myUserId || u !== opts.myUserId) emittedOther = true;
   }
 
-  return { newCursor, lines, hasMore: histResp.has_more === true, nextPageCursor };
+  return { newCursor, lines, hasMore: histResp.has_more === true, nextPageCursor, emittedOther };
 }
 
 export type TailOpts = {
   since?: string;
   thread?: string;
+  watchThread?: string;
   me?: boolean;
   interval?: number;
+  timeout?: string;
+  exitOnMessage?: boolean;
+  cookie?: string;
+  noRtm?: boolean;
 };
 
+// Normalize a --watch-thread argument into a Slack ts ("1700000000.000000").
+// Accepts a raw dotted ts, a compact 16-digit ts (no dot), or a permalink.
+export function resolveThreadTs(ref: string): string {
+  if (ref.includes("slack.com")) {
+    const parsed = parseSlackPermalink(ref);
+    const ts = parsed?.threadTs ?? parsed?.ts;
+    if (ts) return ts;
+    throw new Error(`--watch-thread: could not extract a timestamp from "${ref}"`);
+  }
+  if (/^\d{10}\.\d{6}$/.test(ref)) return ref;
+  if (/^\d{16}$/.test(ref)) return `${ref.slice(0, 10)}.${ref.slice(10)}`;
+  throw new Error(`--watch-thread: "${ref}" is not a valid ts or permalink`);
+}
+
 export async function cmdTail(
   token: string,
   target: string | undefined,
@@ -161,6 +237,8 @@ export async function cmdTail(
 
   const channelId = await resolveChannel(token, target);
   const interval = opts.interval ?? 60000;
+  // Optional auto-stop deadline (e.g. wait at most 30m for a reply).
+  const deadline = opts.timeout ? _internals.now() + parseSince(opts.timeout) * 1000 : Infinity;
   const cache = new Map<string, string>();
   const seen = new Set<string>();
 
@@ -206,21 +284,46 @@ export async function cmdTail(
   }
 
   let myUserId: string | undefined;
-  if (opts.me) {
+  if (opts.me || opts.exitOnMessage) {
     const info = await authTest(token);
     myUserId = info.userId || undefined;
   }
 
+  let watchThreadTs: string | undefined;
+  if (opts.watchThread !== undefined) {
+    try {
+      watchThreadTs = resolveThreadTs(opts.watchThread);
+    } catch (e: unknown) {
+      console.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+  }
+
   const pollOpts: PollOpts = {
     ...(opts.thread !== undefined ? { thread: opts.thread } : {}),
+    ...(watchThreadTs !== undefined ? { watchThread: watchThreadTs } : {}),
     ...(opts.me !== undefined ? { me: opts.me } : {}),
     ...(myUserId !== undefined ? { myUserId } : {}),
   };
 
+  // RTM path: xoxc token + cookie + no backfill requested. Skipped when a
+  // deadline or exit-on-message is set so that logic stays in the poll loop.
+  if (
+    token.startsWith("xoxc-") && opts.cookie !== undefined && opts.noRtm !== true &&
+    opts.since === undefined && opts.timeout === undefined && opts.exitOnMessage !== true
+  ) {
+    await _internals.tailRTM(token, opts.cookie, channelId, pollOpts, seen, cache, signal);
+    if (signal?.aborted) return;
+    console.error("RTM unavailable — switching to polling.");
+  }
+
   let isFirstPoll = true;
   let lastPollEndTime = _internals.now();
 
   while (!signal?.aborted) {
+    if (_internals.now() >= deadline) return; // --timeout reached
+
+    let sawOther = false;
     try {
       const now = _internals.now();
       const elapsed = now - lastPollEndTime;
@@ -232,7 +335,7 @@ export async function cmdTail(
       let isFirstPage = true;
 
       do {
-        const { newCursor, lines, nextPageCursor } = await pollCycle(
+        const { newCursor, lines, nextPageCursor, emittedOther } = await pollCycle(
           token,
           channelId,
           cursor,
@@ -249,6 +352,7 @@ export async function cmdTail(
         isFirstPage = false;
 
         for (const line of lines) process.stdout.write(line + "\n");
+        if (emittedOther) sawOther = true;
         pageCursor = shouldPaginate ? nextPageCursor : undefined;
       } while (pageCursor);
 
@@ -262,7 +366,13 @@ export async function cmdTail(
       throw e;
     }
 
+    // Stop as soon as a reply from someone else arrives.
+    if (opts.exitOnMessage && sawOther) return;
+
     lastPollEndTime = _internals.now();
-    await _internals.sleep(interval);
+    // Sleep the poll interval, but never past the deadline.
+    const remaining = deadline - _internals.now();
+    if (remaining <= 0) return;
+    await _internals.sleep(Math.min(interval, remaining));
   }
 }