slack-term 1.15.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-term",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/slack-term.git"

package/ts/cli.ts

@@ -46,7 +46,7 @@ import {
   getPath,
   type Json,
 } from "./slack.ts";
-import { dayLabel, formatYmdHm, resolveDateMarkup, resolveMentions } from "./format.ts";
+import { dayLabel, encodeMentions, formatYmdHm, resolveDateMarkup, resolveMentions } from "./format.ts";
 
 function loadDotenv(path: string): void {
   if (!existsSync(path)) return;
@@ -188,31 +188,52 @@ async function formatMsgLine(
   return `${stamp}  ${who}:  ${body}${tail}`;
 }
 
+// Slim a raw message down to the fields a script actually needs. Keeps the
+// author's user ID (incl. external / Slack-Connect guests that never appear in
+// users.list) so callers can resolve mentions without scraping history by hand.
+function slimMsg(m: Record<string, Json>): Record<string, Json> {
+  return {
+    ts: m.ts ?? null,
+    user: m.user ?? null,
+    username: m.username ?? null,
+    bot_id: m.bot_id ?? null,
+    thread_ts: m.thread_ts ?? null,
+    text: typeof m.text === "string" ? m.text : "",
+  };
+}
+
 // --- msgs <target> — channel/DM history with timestamps ---
-async function cmdMsgsTarget(token: string, target: string, limit: number): Promise<void> {
+async function cmdMsgsTarget(token: string, target: string, limit: number, format: "text" | "jsonl" = "text"): Promise<void> {
   const parsed = parseSlackPermalink(target);
   const channelId = await resolveChannel(token, target);
   const cache = new Map<string, string>();
-  if (parsed?.threadTs) {
-    const resp = (await replies(token, channelId, parsed.threadTs, limit)) as Record<string, Json>;
-    const msgs = asArray(resp.messages).map(asRecord);
-    for (const m of msgs) {
-      console.log(await formatMsgLine(token, m, cache));
+  const fetchMsgs = async (): Promise<Record<string, Json>[]> => {
+    if (parsed?.threadTs) {
+      const resp = (await replies(token, channelId, parsed.threadTs, limit)) as Record<string, Json>;
+      return asArray(resp.messages).map(asRecord);
     }
-  } else {
     const hist = (await history(token, channelId, limit)) as Record<string, Json>;
-    const msgs = asArray(hist.messages).map(asRecord);
-    for (const m of msgs.reverse()) {
-      console.log(await formatMsgLine(token, m, cache));
-    }
+    return asArray(hist.messages).map(asRecord).reverse();
+  };
+  const msgs = await fetchMsgs();
+  if (format === "jsonl") {
+    for (const m of msgs) console.log(JSON.stringify(slimMsg(m)));
+    return;
+  }
+  for (const m of msgs) {
+    console.log(await formatMsgLine(token, m, cache));
   }
 }
 
 // --- thread ---
-async function cmdThread(token: string, target: string, ts: string, limit: number): Promise<void> {
+async function cmdThread(token: string, target: string, ts: string, limit: number, format: "text" | "jsonl" = "text"): Promise<void> {
   const channelId = await resolveChannel(token, target);
   const resp = (await replies(token, channelId, parseInputTs(ts), limit)) as Record<string, Json>;
   const msgs = asArray(resp.messages).map(asRecord);
+  if (format === "jsonl") {
+    for (const m of msgs) console.log(JSON.stringify(slimMsg(m)));
+    return;
+  }
   const cache = new Map<string, string>();
   for (const m of msgs) {
     console.log(await formatMsgLine(token, m, cache));
@@ -632,6 +653,7 @@ interface EditArgs {
   newText: string;
   code?: string;
   channelId?: string;
+  mentions?: boolean;
 }
 async function cmdEdit(token: string, args: EditArgs): Promise<void> {
   const { ref, ts } = splitRefTs(args.target);
@@ -654,18 +676,23 @@ async function cmdEdit(token: string, args: EditArgs): Promise<void> {
   }
   const originalText = typeof original.text === "string" ? original.text : "";
 
-  const code = safetyCode(originalText, args.newText);
+  // Convert @handle → <@USERID> before hashing/editing (unresolved stay as text).
+  const newText = args.mentions
+    ? await encodeMentions(token, args.newText, channelId)
+    : args.newText;
+
+  const code = safetyCode(originalText, newText);
   if (args.code !== code) {
     requireCode(args.code, code, [
       `--- Original message -------------------------`,
       ...originalText.split("\n").map((l) => `  ${l}`),
       `--- Replacing with ---------------------------`,
-      ...args.newText.split("\n").map((l) => `  ${l}`),
+      ...newText.split("\n").map((l) => `  ${l}`),
       `--------------------------------────────────`,
     ]);
   }
 
-  const newTs = await editMessage(token, channelId, ts, args.newText);
+  const newTs = await editMessage(token, channelId, ts, newText);
   console.log(`✓ Edited (ts: ${newTs})`);
 }
 
@@ -720,6 +747,11 @@ interface SendArgs {
   userId?: string;
   asBot?: boolean;
   broadcast?: boolean;
+  mentions?: boolean;
+  // Token used to resolve @handle mentions (needs users:read). Defaults to the
+  // send token; set to the user token when sending --as-bot so the bot token
+  // need not carry users:read.
+  mentionToken?: string;
 }
 
 // Detect the silent-failure footgun: DMing yourself with your own user token.
@@ -756,6 +788,12 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
   else if (args.userId) channelId = await openDm(token, args.userId);
   else channelId = await resolveChannel(token, ref);
 
+  // Convert @handle tokens to <@USERID> before hashing/sending so the safety
+  // gate covers exactly what will be posted. Unresolved handles stay as text.
+  const message = args.mentions
+    ? await encodeMentions(args.mentionToken ?? token, args.message, channelId)
+    : args.message;
+
   // Fetch last 1 message for context hash. Fail-soft: a bot token without
   // im:history (or channels:history) can still send — only the preview of the
   // prior message is lost, so default to empty rather than blocking the send.
@@ -779,7 +817,7 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
 
   // Hash covers the destination too — a code minted for one channel/thread
   // cannot confirm a send to another.
-  const code = safetyCode(channelId, threadTs ?? "", lastText, args.message);
+  const code = safetyCode(channelId, threadTs ?? "", lastText, message);
 
   if (args.code !== code) {
     const dest = await destLabel(token, channelId, ref);
@@ -791,11 +829,11 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
       `  ${lastUser}: ${lastText.split("\n")[0]?.slice(0, 100) ?? "(empty)"}`,
       `--- Sending ----------------------------------`,
       destLine,
-      `  Message: ${args.message}`,
+      `  Message: ${message}`,
       `--------------------------------────────────`,
     ]);
   }
-  const ts = await slackSend(token, channelId, args.message, threadTs, args.broadcast);
+  const ts = await slackSend(token, channelId, message, threadTs, args.broadcast);
   let permalink = "";
   try {
     permalink = await getPermalink(token, channelId, ts);
@@ -1025,10 +1063,13 @@ async function main(): Promise<void> {
       "Browse messages",
       (y) => y
         .positional("target", { type: "string", describe: "#channel, @user, or URL" })
-        .option("limit", { alias: "n", type: "number", default: 20, describe: "Number of messages" }),
+        .option("limit", { alias: "n", type: "number", default: 20, describe: "Number of messages" })
+        .option("format", { type: "string", choices: ["text", "jsonl"] as const, default: "text", describe: "jsonl exposes raw ts/user/text (incl. external-guest user IDs)" })
+        .option("json", { type: "boolean", default: false, describe: "Alias for --format=jsonl" }),
       async (argv) => {
         const token = tok(argv as W);
-        if (argv.target) await cmdMsgsTarget(token, argv.target, argv.limit);
+        const format = argv.json ? "jsonl" : (argv.format as "text" | "jsonl");
+        if (argv.target) await cmdMsgsTarget(token, argv.target, argv.limit, format);
         else await cmdMsgs(token);
       },
     )
@@ -1038,9 +1079,12 @@ async function main(): Promise<void> {
       (y) => y
         .positional("target", { type: "string", demandOption: true })
         .positional("ts", { type: "string", demandOption: true })
-        .option("limit", { alias: "n", type: "number", default: 100 }),
+        .option("limit", { alias: "n", type: "number", default: 100 })
+        .option("format", { type: "string", choices: ["text", "jsonl"] as const, default: "text", describe: "jsonl exposes raw ts/user/text (incl. external-guest user IDs)" })
+        .option("json", { type: "boolean", default: false, describe: "Alias for --format=jsonl" }),
       async (argv) => {
-        await cmdThread(tok(argv as W), argv.target!, argv.ts!, argv.limit);
+        const format = argv.json ? "jsonl" : (argv.format as "text" | "jsonl");
+        await cmdThread(tok(argv as W), argv.target!, argv.ts!, argv.limit, format);
       },
     )
     .command(
@@ -1219,13 +1263,20 @@ async function main(): Promise<void> {
         .option("channel-id", { type: "string", describe: "Raw channel ID" })
         .option("user-id", { type: "string", describe: "Raw user ID (opens DM)" })
         .option("as-bot", { type: "boolean", default: false, describe: "Send via the bot token (xoxb / SLACK_BOT_TOKEN) so a DM notifies the recipient and can be two-way" })
-        .option("broadcast", { type: "boolean", default: false, describe: "Also send to channel: broadcast a threaded reply back to the channel (Slack's \"Also send to #channel\" checkbox). Only effective with a thread target." }),
+        .option("broadcast", { type: "boolean", default: false, describe: "Also send to channel: broadcast a threaded reply back to the channel (Slack's \"Also send to #channel\" checkbox). Only effective with a thread target." })
+        .option("mentions", { type: "boolean", default: false, describe: "Convert @handle tokens in the message to real <@USERID> mentions (resolves via users.list, then channel members for Slack Connect guests; unresolved handles stay as plain text)" }),
       async (argv) => {
         const args: SendArgs = { target: argv.target!, message: argv.message! };
         if (argv.code) args.code = argv.code;
         if (argv["channel-id"]) args.channelId = argv["channel-id"];
         if (argv["user-id"]) args.userId = argv["user-id"];
         if (argv.broadcast) args.broadcast = true;
+        if (argv.mentions) {
+          args.mentions = true;
+          // Resolve mentions with the user token (has users:read) even when the
+          // message itself is sent via the bot token.
+          args.mentionToken = tok(argv as W);
+        }
         let sendToken: string;
         if (argv["as-bot"]) {
           const botToken = resolveBotToken();
@@ -1342,11 +1393,13 @@ async function main(): Promise<void> {
         .positional("target", { type: "string", demandOption: true, describe: "#chan:ts, @user:ts, or permalink" })
         .positional("newText", { type: "string", demandOption: true })
         .option("code", { type: "string", describe: "Safety hash to confirm edit" })
-        .option("channel-id", { type: "string", describe: "Raw channel ID" }),
+        .option("channel-id", { type: "string", describe: "Raw channel ID" })
+        .option("mentions", { type: "boolean", default: false, describe: "Convert @handle tokens in the new text to real <@USERID> mentions (unresolved handles stay as plain text)" }),
       async (argv) => {
         const args: EditArgs = { target: argv.target!, newText: argv.newText! };
         if (argv.code) args.code = argv.code;
         if (argv["channel-id"]) args.channelId = argv["channel-id"];
+        if (argv.mentions) args.mentions = true;
         await cmdEdit(tok(argv as W), args);
       },
     )

package/ts/format.ts

@@ -1,6 +1,95 @@
 // Text-formatting helpers: mention/date-markup resolution, day grouping.
 
-import { userName } from "./slack.ts";
+import { listConversationMembers, listUsers, userInfo, userName, type Json } from "./slack.ts";
+
+/** Match an `@handle` token at a word boundary, capturing the handle.
+ *  - The negative lookbehind keeps `@` inside emails (`a@b.com`) from matching.
+ *  - Each `.` must be followed by more handle chars, so a trailing sentence dot
+ *    (`thanks @taku.`) is left out of the capture. */
+function mentionRe(): RegExp {
+  return /(?<![A-Za-z0-9._@-])@([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)/g;
+}
+
+/** Lowercase + strip hyphens/underscores/whitespace for loose handle matching. */
+function normHandle(s: string): string {
+  return s.toLowerCase().replace(/[-_\s]/g, "");
+}
+
+function asRecord(v: Json | undefined): Record<string, Json> {
+  return v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, Json>) : {};
+}
+
+/** True when a user record matches `@handle` by name / real_name / display_name / email. */
+function userMatchesHandle(u: Record<string, Json>, handle: string): boolean {
+  const nh = normHandle(handle);
+  const profile = asRecord(u.profile);
+  for (const v of [u.name, u.real_name, profile.display_name, profile.real_name]) {
+    if (typeof v === "string" && v && normHandle(v) === nh) return true;
+  }
+  const email = typeof profile.email === "string" ? profile.email.toLowerCase() : "";
+  return email !== "" && email === handle.toLowerCase();
+}
+
+/**
+ * Rewrite `@handle` tokens in `text` to `<@USERID>` so Slack renders them as
+ * real mentions. Resolution order per handle:
+ *   1. workspace users.list (name / real_name / display_name / email)
+ *   2. the target channel's members (conversations.members → users.info) — this
+ *      reaches Slack Connect guests absent from the workspace users.list
+ * Handles that resolve to nothing are left as plain text (never destroyed) and
+ * reported via `warn`. Lookups are cached so each API call runs at most once.
+ */
+export async function encodeMentions(
+  token: string,
+  text: string,
+  channelId: string | undefined,
+  opts: { warn?: (msg: string) => void } = {},
+): Promise<string> {
+  const warn = opts.warn ?? ((m: string) => process.stderr.write(`${m}\n`));
+
+  const handles = new Set<string>();
+  for (const m of text.matchAll(mentionRe())) handles.add(m[1]!);
+  if (handles.size === 0) return text;
+
+  const resolved = new Map<string, string>(); // handle -> user ID
+
+  // Step 1: workspace users.list (fetched once).
+  const wsResp = (await listUsers(token)) as { members?: Json[] };
+  const wsUsers = (wsResp.members ?? []).map(asRecord);
+  const unresolved: string[] = [];
+  for (const handle of handles) {
+    const hit = wsUsers.find((u) => userMatchesHandle(u, handle));
+    const id = hit && typeof hit.id === "string" ? hit.id : "";
+    if (id) resolved.set(handle, id);
+    else unresolved.push(handle);
+  }
+
+  // Step 2: channel members (fetched once) — covers external/Connect guests.
+  if (unresolved.length > 0 && channelId) {
+    const memberIds = await listConversationMembers(token, channelId);
+    const infos: Record<string, Json>[] = [];
+    for (const uid of memberIds) {
+      const info = asRecord((await userInfo(token, uid)) as Json);
+      const u = asRecord(info.user);
+      if (typeof u.id !== "string") u.id = uid;
+      infos.push(u);
+    }
+    for (const handle of unresolved) {
+      const hit = infos.find((u) => userMatchesHandle(u, handle));
+      const id = hit && typeof hit.id === "string" ? hit.id : "";
+      if (id) resolved.set(handle, id);
+    }
+  }
+
+  for (const handle of handles) {
+    if (!resolved.has(handle)) warn(`warn: unresolved mention @${handle} (left as text)`);
+  }
+
+  return text.replace(mentionRe(), (full, handle: string) => {
+    const id = resolved.get(handle);
+    return id ? `<@${id}>` : full;
+  });
+}
 
 export async function resolveMentions(
   token: string,

package/ts/slack.ts

@@ -558,6 +558,26 @@ export async function listUsers(token: string): Promise<Json> {
   return { members: allMembers };
 }
 
+/** List the member user IDs of a channel/DM (paginated).
+ *  Used by mention encoding to reach members — including Slack Connect guests —
+ *  who do not appear in the workspace-wide users.list. */
+export async function listConversationMembers(token: string, channel: string): Promise<string[]> {
+  const all: string[] = [];
+  let cursor = "";
+  while (true) {
+    const params: Record<string, string> = { channel, limit: "200" };
+    if (cursor) params.cursor = cursor;
+    const resp = (await get(token, "conversations.members", params)) as {
+      members?: string[];
+      response_metadata?: { next_cursor?: string };
+    };
+    all.push(...(resp.members ?? []));
+    cursor = resp.response_metadata?.next_cursor ?? "";
+    if (!cursor) break;
+  }
+  return all;
+}
+
 // 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);