slack-term 1.42.0 → 1.44.0

package/ts/newlines.ts

@@ -0,0 +1,158 @@
+// Line breaks for messages Slack stored flattened.
+//
+// WHY: `send`/`edit`/`schedule` attach a `markdown` block so Slack renders
+// markdown. Whenever a message has blocks, Slack stores its top-level `text`
+// with every newline turned into a space. The rendered message looks right,
+// but every reader of `.text` sees one long line: `read --format jsonl`, ask's
+// parser, and any script on conversations.history.
+// Measured 2026-10-07:
+// - 126 of 127 multi-line sends were stored that way;
+// - the stored text is the source with `\n` → ` ` plus Slack's escaping;
+// - a live send with our own rich_text blocks was flattened the same way, so
+//   no blocks keep `.text`, only a plain post does (`ask`, `poll`).
+//
+// The blocks still carry the breaks. Readers use them to put the breaks back.
+
+import type { Json } from "./slack.ts";
+
+const ESC: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;" };
+
+/** What must appear, in order, in the message's stored `text`: one character,
+ *  or (an emoji) any one of several spellings. */
+type Anchor = string | string[];
+
+/** The glyph forms of an emoji element (`unicode: "2705-fe0f"`), with and
+ *  without the variation selector — the stored text may hold either. */
+function emojiGlyphs(unicode: Json | undefined): string[] {
+  if (typeof unicode !== "string" || !/^[0-9a-f]+(-[0-9a-f]+)*$/i.test(unicode)) return [];
+  const cps = unicode.split("-").map((h) => parseInt(h, 16));
+  const full = String.fromCodePoint(...cps);
+  const bare = String.fromCodePoint(...cps.filter((c) => c !== 0xfe0f));
+  return full === bare ? [full] : [full, bare];
+}
+
+/** The anchors of `blocks`, with `null` wherever the blocks put a line break. */
+function anchors(blocks: Json[]): Array<Anchor | null> {
+  const out: Array<Anchor | null> = [];
+  const chars = (s: string) => { for (const ch of s) { if (ch === "\n") out.push(null); else if (!/\s/u.test(ch)) out.push(...(ESC[ch] ?? ch)); } };
+  const inline = (e: Record<string, Json>) => {
+    switch (e.type) {
+      case "text": chars(String(e.text ?? "")); break;
+      case "link": case "message_mention": chars(String(e.url ?? "")); break;
+      case "user": chars(String(e.user_id ?? "")); break;
+      case "channel": chars(String(e.channel_id ?? "")); break;
+      case "usergroup": chars(String(e.usergroup_id ?? "")); break;
+      case "broadcast": chars(String(e.range ?? "")); break;
+      // `:name:` in most stored texts, but a literal glyph in some.
+      case "emoji": out.push([`:${String(e.name ?? "")}:`, ...emojiGlyphs(e.unicode)].filter((x) => x !== "::")); break;
+      default: break;
+    }
+  };
+  const container = (b: Record<string, Json>) => {
+    const els = Array.isArray(b.elements) ? (b.elements as Record<string, Json>[]) : [];
+    if (b.type === "rich_text_list" || b.type === "rich_text") {
+      els.forEach((x, k) => { if (k > 0) out.push(null); container(x); });
+    } else {
+      els.forEach(inline);
+    }
+  };
+  blocks.forEach((b, k) => {
+    if (k > 0) out.push(null);
+    const r = b as Record<string, Json>;
+    if (r.type === "rich_text") container(r);
+  });
+  return out;
+}
+
+/** Earliest position at or after `from` where `a` (any of its spellings)
+ *  occurs in `chars`, and its length in code points; [-1, 0] if nowhere. */
+function find(chars: string[], a: Anchor, from: number): [number, number] {
+  if (typeof a === "string") {
+    let q = from;
+    while (q < chars.length && chars[q] !== a) q++;
+    return q < chars.length ? [q, 1] : [-1, 0];
+  }
+  let best: [number, number] = [-1, 0];
+  for (const alt of a) {
+    const cps = [...alt];
+    for (let q = from; q + cps.length <= chars.length && (best[0] < 0 || q < best[0]); q++) {
+      if (cps.every((c, k) => chars[q + k] === c)) { best = [q, cps.length]; break; }
+    }
+  }
+  return best;
+}
+
+/** `text` with its line breaks put back, for a message Slack stored flattened
+ *  (it had blocks — see the top of this file). Slack replaced
+ *  every `\n` of the source with one space; the `rich_text` blocks still carry
+ *  the breaks. Walk the blocks' visible characters through `text` and, at each
+ *  place the blocks break a line, turn the spaces there back into newlines.
+ *
+ *  Only ever turns spaces into newlines, so the result is the stored text when
+ *  breaks are ignored — what a reader saw before, never anything new. Returns
+ *  `text` unchanged unless it is single-line and the blocks are multi-line,
+ *  or when the two cannot be aligned. */
+export function restoreNewlines(text: string, blocks: Json | undefined): string {
+  if (text.includes("\n") || !Array.isArray(blocks) || !blocks.some((b) => (b as Record<string, Json>)?.type === "rich_text")) return text;
+  const seq = anchors(blocks);
+  if (!seq.includes(null)) return text;
+  const chars = [...text];
+  // Map each anchor to its position in `text`; a code block at either end
+  // also has a break between its fence and its first/last character.
+  const elems = (blocks[0] as Record<string, Json>).elements;
+  const lastBlock = blocks[blocks.length - 1] as Record<string, Json>;
+  const lastElems = lastBlock.elements;
+  const startsPre = Array.isArray(elems) && (elems[0] as Record<string, Json>)?.type === "rich_text_preformatted";
+  const endsPre = Array.isArray(lastElems) && (lastElems[lastElems.length - 1] as Record<string, Json>)?.type === "rich_text_preformatted";
+  // `last` = -1 before the first anchor, so a leading break covers the gap
+  // from the start of the text.
+  let p = 0, last = -1, pendingBreak = startsPre;
+  const breaks: Array<[number, number]> = [];
+  for (const a of seq) {
+    if (a === null) { pendingBreak = true; continue; }
+    const [q, len] = find(chars, a, p);
+    if (q < 0) return text;
+    if (pendingBreak) { breaks.push([last + 1, q]); pendingBreak = false; }
+    last = q + len - 1; p = q + len;
+  }
+  if ((pendingBreak || endsPre) && last >= 0) breaks.push([last + 1, chars.length]);
+  const MARKER = /^(?:[-*+•]|\d{1,9}[.)]|&gt;|>)$/;
+  for (const [gapFrom, to] of breaks) {
+    // The gap between two visible characters holds the old newline(s) as
+    // spaces plus markup: the rest of a `<url|label>` (skip past its `>`),
+    // emphasis, `- `/`1. `/`&gt; ` markers, code fences. A space after a
+    // marker that itself starts a line is the marker's own, not a break.
+    let k = gapFrom;
+    // Inside a `<url|label>` token (its `<` opened before the gap and is not
+    // yet closed) the rest of the token up to its `>` is not a line break.
+    if (chars.lastIndexOf("<", gapFrom - 1) > chars.lastIndexOf(">", gapFrom - 1)) {
+      const close = chars.indexOf(">", gapFrom);
+      if (close !== -1 && close < to) k = close + 1;
+    }
+    let word = "", lineStart = gapFrom === 0;
+    while (k < to) {
+      if (chars[k] === " ") {
+        let e = k; while (e < to && chars[e] === " ") e++;
+        if (lineStart && MARKER.test(word)) {
+          lineStart = false;
+        } else {
+          // One space per old newline — but three or more are a newline
+          // followed by indentation (`\n   - nested`), not a run of blank lines.
+          const n = e - k <= 2 ? e - k : 1;
+          for (let x = k; x < k + n; x++) chars[x] = "\n";
+          lineStart = true;
+        }
+        word = ""; k = e;
+      } else { word += chars[k]; k++; }
+    }
+  }
+  return chars.join("");
+}
+
+/** `restoreNewlines` applied in place to a conversations.history /
+ *  conversations.replies message, so every reader of `.text` sees the breaks. */
+export function repairMessageText(m: Json): void {
+  if (!m || typeof m !== "object" || Array.isArray(m)) return;
+  const r = m as Record<string, Json>;
+  if (typeof r.text === "string") r.text = restoreNewlines(r.text, r.blocks);
+}

package/ts/relay.ts

@@ -0,0 +1,105 @@
+// Client for the slack-term relay (worker/): a Cloudflare Worker that receives
+// Slack's Events API and serves "doorbells" — {channel, ts, thread_ts}, never
+// message text — as a resumable Server-Sent Events stream. `slack stream` uses
+// it to scan the one channel a bell names within a second of the post, instead
+// of waiting for its next poll.
+//
+// SSE over fetch (not WebSocket) so the bearer token travels in a header on
+// both bun and node, and never in a URL.
+
+/** A bell: where a message just appeared. */
+export type Doorbell = {
+  channel: string; ts: string; thread_ts?: string;
+  /** The relay app's bot user id, on that bot's own posts only. */
+  self?: string;
+};
+
+/** First frame of every connection. `seq` is the resume point the relay
+ *  starts from; `gap` means bells after the requested seq are gone (expired,
+ *  or the relay was reset), so the client must catch up by polling. `epoch`
+ *  names the relay's storage: a new one means its numbering restarted. */
+export type Hello = { seq: number; gap: boolean; retention_sec: number; epoch?: string };
+
+/** Where to resume: the last seq taken, in the numbering of `epoch`. */
+export type Cursor = { seq: number; epoch?: string };
+
+export type RelayHandlers = {
+  hello(h: Hello): void;
+  bell(seq: number, b: Doorbell): void;
+};
+
+/** Subscribe from `after` (undefined = from now). Resolves when the server
+ *  closes the stream; rejects on HTTP errors, network errors and silence
+ *  longer than `idleMs` (the relay sends a keepalive every 25 s). */
+export type Subscribe = (after: Cursor | undefined, signal: AbortSignal, on: RelayHandlers) => Promise<void>;
+
+export class RelayAuthError extends Error {}
+
+/** Parse SSE frames out of a growing buffer; returns the unparsed tail. */
+export function parseSse(buf: string, emit: (event: string, data: string, id: string | undefined) => void): string {
+  let i: number;
+  while ((i = buf.indexOf("\n\n")) >= 0) {
+    const frame = buf.slice(0, i);
+    buf = buf.slice(i + 2);
+    let event = "message";
+    let id: string | undefined;
+    const data: string[] = [];
+    for (const line of frame.split("\n")) {
+      if (!line || line.startsWith(":")) continue; // keepalive / comment
+      const c = line.indexOf(":");
+      const field = c < 0 ? line : line.slice(0, c);
+      const value = c < 0 ? "" : line.slice(c + 1).replace(/^ /, "");
+      if (field === "event") event = value;
+      else if (field === "data") data.push(value);
+      else if (field === "id") id = value;
+    }
+    if (data.length) emit(event, data.join("\n"), id);
+  }
+  return buf;
+}
+
+export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000): Subscribe {
+  const base = baseUrl.replace(/\/+$/, "");
+  return async (after, signal, on) => {
+    const ac = new AbortController();
+    const stop = (): void => ac.abort();
+    signal.addEventListener("abort", stop, { once: true });
+    let idle: ReturnType<typeof setTimeout> | undefined;
+    let silent = false;
+    const arm = (): void => {
+      clearTimeout(idle);
+      idle = setTimeout(() => { silent = true; ac.abort(); }, idleMs);
+    };
+    try {
+      arm();
+      const q = after === undefined ? "" : `?after=${after.seq}${after.epoch ? `&epoch=${encodeURIComponent(after.epoch)}` : ""}`;
+      const res = await fetch(`${base}/stream${q}`, {
+        headers: { authorization: `Bearer ${token}`, accept: "text/event-stream" },
+        signal: ac.signal,
+      });
+      if (res.status === 401) throw new RelayAuthError("relay rejected the token (401)");
+      if (!res.ok || !res.body) throw new Error(`relay: HTTP ${res.status}`);
+      const reader = res.body.getReader();
+      const dec = new TextDecoder();
+      let buf = "";
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        arm();
+        // CRLF is normalised on the whole buffer: a \r\n pair can straddle chunks.
+        buf = parseSse((buf + dec.decode(value, { stream: true })).replace(/\r\n/g, "\n"), (event, data, id) => {
+          const j = JSON.parse(data) as unknown;
+          if (event === "hello") on.hello(j as Hello);
+          else if (event === "bell" && id !== undefined) on.bell(Number(id), j as Doorbell);
+        });
+      }
+    } catch (e) {
+      if (signal.aborted) return;
+      if (silent) throw new Error(`relay: no data for ${Math.round(idleMs / 1000)}s`);
+      throw e;
+    } finally {
+      clearTimeout(idle);
+      signal.removeEventListener("abort", stop);
+    }
+  };
+}

package/ts/slack.ts

@@ -1,6 +1,7 @@
 // Slack Web API client (user token, Authorization: Bearer)
 import { resolveCookie } from "./profiles.ts";
 import { linkifyRichText } from "./urlGuard.ts";
+import { repairMessageText } from "./newlines.ts";
 
 export class RateLimitError extends Error {
   retryAfter: number;
@@ -248,7 +249,21 @@ export async function history(
   if (oldest !== undefined) params.oldest = oldest;
   if (cursor !== undefined) params.cursor = cursor;
   if (inclusive) params.inclusive = "true";
-  return get(token, "conversations.history", params, cookie);
+  return repairMessages(await get(token, "conversations.history", params, cookie));
+}
+
+/** Give every message in a history/replies/search response its line breaks
+ *  back when Slack stored its text flattened (see newlines.ts). Done here, at
+ *  the fetch, so `read`, `--format jsonl`, `ask`'s parser and every other
+ *  reader of `.text` agree on one text. */
+function repairMessages(resp: Json): Json {
+  const r = resp as { messages?: Json };
+  const msgs = Array.isArray(r.messages) ? r.messages
+    : r.messages && typeof r.messages === "object" && Array.isArray((r.messages as { matches?: Json }).matches)
+      ? (r.messages as { matches: Json[] }).matches
+      : [];
+  for (const m of msgs) repairMessageText(m);
+  return resp;
 }
 
 export async function replies(
@@ -258,7 +273,40 @@ export async function replies(
   limit = 50,
   cookie?: string,
 ): Promise<Json> {
-  return get(token, "conversations.replies", { channel, ts, limit: String(limit) }, cookie);
+  return repairMessages(await get(token, "conversations.replies", { channel, ts, limit: String(limit) }, cookie));
+}
+
+// One page of a thread's replies newer than `oldest` (exclusive). Slack returns
+// the parent first on every page regardless of `oldest`; callers drop it.
+export async function repliesPage(
+  token: string,
+  channel: string,
+  ts: string,
+  opts: { oldest?: string; cursor?: string; limit?: number } = {},
+  cookie?: string,
+): Promise<Json> {
+  const params: Record<string, string> = { channel, ts, limit: String(opts.limit ?? 200) };
+  if (opts.oldest !== undefined) params.oldest = opts.oldest;
+  if (opts.cursor !== undefined) params.cursor = opts.cursor;
+  return repairMessages(await get(token, "conversations.replies", params, cookie));
+}
+
+// Conversations the token's OWN identity is a member of (users.conversations),
+// unlike conversations.list, which also returns public channels it is not in.
+export async function userConversations(token: string, types: string, cookie?: string): Promise<Json[]> {
+  const out: Json[] = [];
+  let cursor = "";
+  do {
+    const params: Record<string, string> = { limit: "200", types, exclude_archived: "true" };
+    if (cursor) params.cursor = cursor;
+    const resp = (await get(token, "users.conversations", params, cookie)) as {
+      channels?: Json[];
+      response_metadata?: { next_cursor?: string };
+    };
+    out.push(...(resp.channels ?? []));
+    cursor = resp.response_metadata?.next_cursor ?? "";
+  } while (cursor);
+  return out;
 }
 
 // Metadata for a single uploaded file (files.info). Carries url_private_download,
@@ -368,13 +416,13 @@ export async function searchPage(
   page: number,
   cookie?: string,
 ): Promise<Json> {
-  return get(token, "search.messages", {
+  return repairMessages(await get(token, "search.messages", {
     query,
     sort: "timestamp",
     sort_dir: "desc",
     count: String(Math.min(Math.max(count, 1), 100)),
     page: String(Math.max(page, 1)),
-  }, cookie);
+  }, cookie));
 }
 
 export async function search(token: string, query: string, cookie?: string): Promise<Json> {