slack-term 1.39.2 → 1.41.0

package/ts/slack.ts

@@ -1,12 +1,30 @@
 // Slack Web API client (user token, Authorization: Bearer)
 import { resolveCookie } from "./profiles.ts";
+import { linkifyRichText } from "./urlGuard.ts";
 
 export class RateLimitError extends Error {
   retryAfter: number;
-  constructor(retryAfter: number) {
-    super(`Slack rate limited — retry after ${retryAfter}s`);
+  /**
+   * The Web API method that was throttled ("conversations.history", ...).
+   *
+   * Slack's limits are PER METHOD, so "retry after 30s" alone cannot say whether
+   * a caller's own polling caused the 429 or something else sharing the token
+   * did. The method name is already in scope at every throw site below; not
+   * passing it was the only reason the question was unanswerable.
+   *
+   * Optional because callers (and tests) constructed this with one argument
+   * before, and a required field would break them for no diagnostic gain.
+   */
+  method?: string;
+  constructor(retryAfter: number, method?: string) {
+    super(
+      method
+        ? `Slack rate limited on ${method} — retry after ${retryAfter}s`
+        : `Slack rate limited — retry after ${retryAfter}s`,
+    );
     this.name = "RateLimitError";
     this.retryAfter = retryAfter;
+    if (method) this.method = method;
   }
 }
 
@@ -36,12 +54,12 @@ async function call(token: string, method: string, init: RequestInit, cookie?: s
   });
   if (res.status === 429) {
     const retryAfter = parseInt(res.headers.get("retry-after") ?? "60", 10);
-    throw new RateLimitError(isNaN(retryAfter) ? 60 : retryAfter);
+    throw new RateLimitError(isNaN(retryAfter) ? 60 : retryAfter, method);
   }
   const body = (await res.json()) as { ok?: boolean; error?: string } & Record<string, Json>;
   if (body.ok !== true) {
     const err = body.error ?? "unknown";
-    if (err === "ratelimited") throw new RateLimitError(60);
+    if (err === "ratelimited") throw new RateLimitError(60, method);
     // A desktop session token (xoxc-) is only accepted by the public Web API when
     // paired with its xoxd session cookie — without one, point at the xoxp fallback.
     if (err === "invalid_auth" && token.startsWith("xoxc-") && !cookie) {
@@ -89,21 +107,21 @@ async function callSession(token: string, method: string, init: RequestInit, coo
   });
   if (res.status === 429) {
     const retryAfter = parseInt(res.headers.get("retry-after") ?? "60", 10);
-    throw new RateLimitError(isNaN(retryAfter) ? 60 : retryAfter);
+    throw new RateLimitError(isNaN(retryAfter) ? 60 : retryAfter, method);
   }
   const body = (await res.json()) as { ok?: boolean; error?: string } & Record<string, Json>;
   if (body.ok !== true) {
     const err = body.error ?? "unknown";
-    if (err === "ratelimited") throw new RateLimitError(60);
+    if (err === "ratelimited") throw new RateLimitError(60, method);
     if ((err === "invalid_auth" || err === "not_authed") && !token.startsWith("xoxc-")) {
       throw new Error(
-        `The draft API requires a desktop app session token (xoxc-).\n` +
+        `${method} requires a desktop app session token (xoxc-).\n` +
         `Import from Slack desktop:  slack auth login`,
       );
     }
     if ((err === "invalid_auth" || err === "not_authed") && !cookie) {
       throw new Error(
-        `drafts.list also requires the xoxd session cookie.\n` +
+        `${method} also requires the xoxd session cookie.\n` +
         `Attach it with:  slack auth firefox   (Linux/macOS/Windows)   or   slack auth chrome   (macOS/Linux)`,
       );
     }
@@ -185,7 +203,7 @@ export async function authScopes(token: string, cookie?: string): Promise<{
   const res = await fetch(`${base()}/auth.test`, { method: "GET", headers });
   if (res.status === 429) {
     const retryAfter = parseInt(res.headers.get("retry-after") ?? "60", 10);
-    throw new RateLimitError(isNaN(retryAfter) ? 60 : retryAfter);
+    throw new RateLimitError(isNaN(retryAfter) ? 60 : retryAfter, "auth.test");
   }
   const scopesHeader = res.headers.get("x-oauth-scopes") ?? "";
   const body = (await res.json()) as {
@@ -594,6 +612,20 @@ export async function createChannel(
   return { id: resp.channel?.id ?? "", name: resp.channel?.name ?? name };
 }
 
+// Rename a channel via conversations.rename. Needs channels:manage (public) or
+// groups:write (private) — and, for a user token, rights to rename it.
+export async function renameChannel(
+  token: string,
+  channel: string,
+  name: string,
+  cookie?: string,
+): Promise<{ id: string; name: string }> {
+  const resp = (await post(token, "conversations.rename", { channel, name }, cookie)) as {
+    channel?: { id?: string; name?: string };
+  };
+  return { id: resp.channel?.id ?? channel, name: resp.channel?.name ?? name };
+}
+
 // Invite users to a channel via conversations.invite (up to ~1000 ids).
 export async function inviteToChannel(
   token: string,
@@ -1025,6 +1057,19 @@ export async function listConversationMembers(token: string, channel: string, co
   return all;
 }
 
+// To-dos tab (internal — requires xoxc session token + xoxd cookie). The
+// desktop client's own read of Slack's personal To-dos; see slackTodos.ts.
+export async function savedList(
+  token: string,
+  opts: { filter?: string; limit?: number; cursor?: string | undefined } = {},
+  cookie?: string,
+): Promise<Json> {
+  const params: Record<string, string> = { limit: String(opts.limit ?? 50) };
+  if (opts.filter) params.filter = opts.filter;
+  if (opts.cursor) params.cursor = opts.cursor;
+  return postSession(token, "saved.list", params, cookie);
+}
+
 // Draft API (internal — requires xoxc session token + xoxd cookie)
 export async function listDrafts(token: string, cookie?: string): Promise<Json> {
   return postSession(token, "drafts.list", {}, cookie);
@@ -1039,7 +1084,7 @@ export async function createDraft(
   const { randomUUID } = await import("node:crypto");
   const blocks = JSON.stringify([{
     type: "rich_text",
-    elements: [{ type: "rich_text_section", elements: [{ type: "text", text }] }],
+    elements: [{ type: "rich_text_section", elements: linkifyRichText(text) }],
   }]);
   return postSession(token, "drafts.create", {
     client_msg_id: randomUUID(),
@@ -1059,7 +1104,7 @@ export async function updateDraft(
 ): Promise<Json> {
   const blocks = JSON.stringify([{
     type: "rich_text",
-    elements: [{ type: "rich_text_section", elements: [{ type: "text", text }] }],
+    elements: [{ type: "rich_text_section", elements: linkifyRichText(text) }],
   }]);
   // client_last_updated_ts must be the current time (server uses it as new stored ts)
   const nowTs = (Date.now() / 1000).toFixed(6);
@@ -1081,6 +1126,18 @@ export async function userInfo(token: string, userId: string, cookie?: string):
   return get(token, "users.info", { user: userId }, cookie);
 }
 
+/** A person's Slack UI locale (`ja-JP`, `en-US`), or undefined when it cannot
+ *  be read. Fail-soft: it only picks the language of `ask`'s copy, and a lookup
+ *  failure must never stop a question from being asked. */
+export async function userLocale(token: string, userId: string, cookie?: string): Promise<string | undefined> {
+  try {
+    const r = (await get(token, "users.info", { user: userId, include_locale: "true" }, cookie)) as { user?: { locale?: unknown } };
+    return typeof r.user?.locale === "string" ? r.user.locale : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function conversationInfo(token: string, channelId: string, cookie?: string): Promise<Json> {
   return get(token, "conversations.info", { channel: channelId }, cookie);
 }

package/ts/slackTodos.ts

@@ -0,0 +1,85 @@
+// Slack's To-dos tab (app.slack.com/client/<team>/to-dos) — read-only helpers.
+//
+// Not to be confused with `slack todo` (todo.ts), which tracks tasks as
+// reactions on messages. To-dos are Slack's own PERSONAL list: it replaced
+// "Later" in Oct 2026, and there is no public API for it. The desktop client
+// reads it through the internal `saved.list` (xoxc session token + d cookie),
+// which is what `slack todos` calls — so it is per-user, and bot tokens cannot
+// see it at all.
+//
+// A saved item points at a message: `item_id` is the channel id, `ts` the
+// message ts. `todo_state` is "to_do" for a to-do and "saved" for a plain
+// saved item; `state` is "in_progress" until it is checked off. Dates are
+// epoch seconds, 0 when unset. The shape is undocumented, so every field is
+// read defensively.
+
+import type { Json } from "./slack.ts";
+
+/** `--filter` values `saved.list` accepts (verified against the live API). */
+export const TODO_FILTERS = ["todo", "saved", "completed", "archived"] as const;
+export type TodoFilter = (typeof TODO_FILTERS)[number];
+
+export type TodoItem = {
+  channel: string;
+  ts: string;
+  /** Epoch seconds; 0 = no due date. */
+  due: number;
+  /** Epoch seconds; 0 = not completed. */
+  completed: number;
+  /** "to_do" | "saved" (as Slack reports it). */
+  todoState: string;
+  state: string;
+  archived: boolean;
+  itemType: string;
+};
+
+const str = (v: Json | undefined): string => (typeof v === "string" ? v : "");
+const num = (v: Json | undefined): number => {
+  const n = typeof v === "number" || typeof v === "string" ? Number(v) : 0;
+  return Number.isFinite(n) ? n : 0;
+};
+
+/** The items of one `saved.list` page, normalized. Non-message items are kept
+ *  (their `itemType` says what they are) but carry no channel/ts to read. */
+export function parseSavedItems(resp: Json): TodoItem[] {
+  const r = (resp && typeof resp === "object" && !Array.isArray(resp) ? resp : {}) as Record<string, Json>;
+  const items = Array.isArray(r.saved_items) ? r.saved_items : [];
+  return items
+    .filter((x): x is Record<string, Json> => !!x && typeof x === "object" && !Array.isArray(x))
+    .map((x) => ({
+      channel: str(x.item_id),
+      ts: str(x.ts),
+      due: num(x.date_due),
+      completed: num(x.date_completed),
+      todoState: str(x.todo_state),
+      state: str(x.state),
+      archived: x.is_archived === true,
+      itemType: str(x.item_type),
+    }));
+}
+
+/** Soonest due first; items without a due date last, newest message first among them. */
+export function sortTodos(items: TodoItem[]): TodoItem[] {
+  return [...items].sort((a, b) => {
+    if (a.due && b.due) return a.due - b.due;
+    if (a.due !== b.due) return a.due ? -1 : 1;
+    return Number(b.ts) - Number(a.ts);
+  });
+}
+
+export function isDone(t: TodoItem): boolean {
+  return t.completed > 0 || t.state === "completed";
+}
+
+/** The status column: a checkbox, plus the due date (and OVERDUE when past it). */
+export function todoStatus(t: TodoItem, nowSec: number, fmt: (epochSec: number) => string): string {
+  const box = isDone(t) ? "☑" : t.todoState === "to_do" ? "☐" : "·";
+  if (!t.due) return `${box} no due date`;
+  const overdue = !isDone(t) && t.due < nowSec ? "  OVERDUE" : "";
+  return `${box} due ${fmt(t.due)}${overdue}`;
+}
+
+/** A message permalink built from the workspace URL — no API call per item. */
+export function messagePermalink(teamUrl: string, channel: string, ts: string): string {
+  return `${teamUrl.replace(/\/+$/, "")}/archives/${channel}/p${ts.replace(".", "")}`;
+}

package/ts/urlGuard.ts

@@ -1,20 +1,172 @@
 /** Bare Unicode URL text has an ambiguous boundary for Slack's autolinker.
  * Explicit Slack links delimit the URL, including intentional Unicode paths.
  * ASCII whitespace (especially newlines) is a safe boundary; Unicode spaces
- * should be made explicit too. Do not rewrite the message or its newlines. */
+ * should be made explicit too. Do not rewrite the message or its newlines.
+ *
+ * Both ends matter. A URL glued to the text AFTER it (`https://x/内容`) gets the
+ * text swallowed into the link; a URL glued to the text BEFORE it
+ * (`说明：https://x/`) is not autolinked at all — Slack stores it as a plain
+ * `text` element and every client shows it as dead text. The markdown
+ * autolinker (GFM rules) only starts a link at the start of a line, after
+ * ASCII whitespace, or after one of `( * _ ~`. */
+
+// `\x00` is maskCode's filler: a bare URL stops at a masked span, so a URL
+// on the far side of one is its own token with its own left boundary.
+const URL_TOKEN = /<https?:\/\/[^\s<>|]+(?:\|[^<>\r\n]*)?>|https?:\/\/[^\t\n\v\f\r <\x00]+/gi;
+/** What may sit right before a bare URL and still let it autolink. */
+const SAFE_BEFORE = /[\t\n\v\f\r (*_~]/;
+
+export type UrlBoundaryIssue = { url: string; side: "before" | "after"; char: string };
+
+/** Code spans and fences are shown verbatim and never autolinked, so a URL in
+ *  one is not a boundary problem; neither is a `[label](url)` link, which is
+ *  explicit. Blanked (length-preserving, newlines kept) rather than removed so
+ *  indices still line up with the original text; the filler is a non-space so a
+ *  URL glued to the END of a span is still caught.
+ *
+ *  A small CommonMark-shaped scanner, not a regex: a backslash escapes the
+ *  next character (`\`` is a literal backtick, not a span opener), a span
+ *  opened by a run of N backticks closes only at the next run of exactly N,
+ *  and an unclosed run is literal text. A fence is ``` or ~~~ at line start
+ *  and runs to a matching fence line, or to the end. */
+function maskCode(text: string): string {
+  const out = text.split("");
+  const blank = (from: number, to: number) => {
+    for (let k = from; k < to; k++) if (out[k] !== "\n") out[k] = "\x00";
+  };
+  let i = 0;
+  while (i < text.length) {
+    const lineStart = i === 0 || text[i - 1] === "\n";
+    // A backtick fence's info string may not contain a backtick (```x``` on
+    // one line is an inline span, not a fence opener).
+    const fence = lineStart ? /^ {0,3}(?:(`{3,})[^`\n]*|(~{3,})[^\n]*)(?=\n|$)/.exec(text.slice(i)) : null;
+    if (fence) {
+      const marker = fence[1] ?? fence[2]!;
+      const close = new RegExp(`\n {0,3}${marker[0] === "`" ? "`" : "~"}{${marker.length},}[ \t]*\r?(?=\n|$)`, "g");
+      close.lastIndex = i + fence[0].length;
+      const m = close.exec(text);
+      const end = m ? m.index + m[0].length : text.length;
+      blank(i, end);
+      i = end;
+      continue;
+    }
+    const ch = text[i]!;
+    if (ch === "\\") { i += 2; continue; }
+    if (ch === "`") {
+      let n = 0;
+      while (text[i + n] === "`") n++;
+      let j = i + n;
+      let end = -1;
+      while (j < text.length) {
+        // A blank line ends the paragraph, and a span cannot cross it.
+        if (text[j] === "\n" && /^\n[ \t\r]*(?:\n|$)/.test(text.slice(j))) break;
+        if (text[j] !== "`") { j++; continue; }
+        let r = 0;
+        while (text[j + r] === "`") r++;
+        if (r === n) { end = j + r; break; }
+        j += r;
+      }
+      if (end < 0) { i += n; continue; }
+      blank(i, end);
+      i = end;
+      continue;
+    }
+    if (ch === "[") {
+      // Escape-aware: `\]` does not close the label.
+      const link = /^\[(?:\\.|[^\]\\\n])*\]\([^()\s]*\)/.exec(text.slice(i));
+      if (link) { blank(i, i + link[0].length); i += link[0].length; continue; }
+    }
+    i++;
+  }
+  return out.join("");
+}
+
+/** `markdown: false` is for text that is NOT parsed as markdown (drafts, whose
+ *  rich_text is built by `linkifyRichText`): there a backtick or `[label](url)`
+ *  hides nothing, so nothing is masked. */
+export function urlBoundaryIssues(text: string, { markdown = true }: { markdown?: boolean } = {}): UrlBoundaryIssue[] {
+  const masked = markdown ? maskCode(text) : text;
+  const issues: UrlBoundaryIssue[] = [];
+  for (const m of masked.matchAll(URL_TOKEN)) {
+    const url = m[0];
+    if (url.startsWith("<")) continue;
+    const at = m.index ?? 0;
+    const before = at > 0 ? masked[at - 1]! : "";
+    if (before && !SAFE_BEFORE.test(before)) {
+      issues.push({ url, side: "before", char: text[at - 1]! });
+    }
+    const after = url.match(/[^\x00-\x7f]|>/);
+    if (after) issues.push({ url, side: "after", char: after[0] });
+  }
+  return issues;
+}
+
 export function adjacentUrls(text: string): string[] {
-  const tokens = text.matchAll(/<https?:\/\/[^\s<>|]+(?:\|[^<>\r\n]*)?>|https?:\/\/[^\t\n\v\f\r <]+/gi);
-  return [...tokens]
-    .map(([token]) => token)
-    .filter((token) => !token.startsWith("<") && (/[^\x00-\x7f]/.test(token) || token.includes(">")));
+  return [...new Set(urlBoundaryIssues(text).map((i) => i.url))];
 }
 
-export function guardUrlBoundaries(text: string, allow = false, warn: (message: string) => void = console.error): void {
-  const urls = adjacentUrls(text);
-  if (!urls.length) return;
-  const message = `Ambiguous URL boundary: ${urls.map((url) => JSON.stringify(url)).join(", ")}. ` +
-    "Put the URL on its own line, or wrap it as <url> / <url|label>. " +
+export function guardUrlBoundaries(
+  text: string, allow = false, warn: (message: string) => void = console.error,
+  { sides = ["before", "after"], markdown = true }: {
+    sides?: ReadonlyArray<UrlBoundaryIssue["side"]>; markdown?: boolean;
+  } = {},
+): void {
+  const issues = urlBoundaryIssues(text, { markdown }).filter((i) => sides.includes(i.side));
+  if (!issues.length) return;
+  const described = issues.map((i) => i.side === "before"
+    ? `${JSON.stringify(i.url)} (glued to ${JSON.stringify(i.char)} before it — Slack will NOT make it a link)`
+    : `${JSON.stringify(i.url)} (runs into ${JSON.stringify(i.char)} after it)`);
+  const fixes = issues.some((i) => i.side === "before")
+    ? "Put an ASCII space (or a newline) before the URL, " : "";
+  const message = `Ambiguous URL boundary: ${described.join(", ")}. ` +
+    `${fixes}Put the URL on its own line, or wrap it as <url> / <url|label>. ` +
     "Use --allow-url-adjacent to warn only.";
   if (!allow) throw new Error(message);
   warn(`Warning: ${message}`);
 }
+
+type RichTextElement =
+  | { type: "text"; text: string }
+  | { type: "link"; url: string; text?: string };
+
+/** Elements for a `rich_text_section` with every URL as a real `link` element.
+ *  Drafts are posted as raw rich_text, which Slack never autolinks: a URL left
+ *  in a `text` element stays dead text however it is spaced. A bare URL ends at
+ *  whitespace, `<`, or the first non-ASCII character (`https://x/内容` links
+ *  `https://x/` only), and trailing sentence punctuation is left outside it.
+ *  Whether that cut is the intended one is ambiguous, so callers gate it with
+ *  `guardUrlBoundaries(text, allow, warn, { sides: ["after"], markdown: false })`
+ *  first. */
+export function linkifyRichText(text: string): RichTextElement[] {
+  const out: RichTextElement[] = [];
+  const pushText = (s: string) => {
+    if (!s) return;
+    const last = out[out.length - 1];
+    if (last?.type === "text") last.text += s;
+    else out.push({ type: "text", text: s });
+  };
+  const re = /<(https?:\/\/[^\s<>|]+)(?:\|([^<>\r\n]*))?>|https?:\/\/[\x21-\x3b\x3d\x3f-\x7e]+/gi;
+  let pos = 0;
+  for (const m of text.matchAll(re)) {
+    const at = m.index ?? 0;
+    pushText(text.slice(pos, at));
+    if (m[1]) {
+      out.push(m[2] ? { type: "link", url: m[1], text: m[2] } : { type: "link", url: m[1] });
+      pos = at + m[0].length;
+      continue;
+    }
+    let url = m[0];
+    // GFM-style trailing trim: sentence punctuation, and `)` with no `(` to match.
+    while (/[.,:;!?'"*_~]$/.test(url) || (url.endsWith(")") && count(url, "(") < count(url, ")"))) {
+      url = url.slice(0, -1);
+    }
+    out.push({ type: "link", url });
+    pos = at + url.length;
+  }
+  pushText(text.slice(pos));
+  return out;
+}
+
+function count(s: string, ch: string): number {
+  return s.split(ch).length - 1;
+}