@zksecurity/slack-events 0.2.0 → 0.2.2

package/README.md

@@ -18,6 +18,10 @@ Pairing does not start a listener. On the same machine, run:
 npx @zksecurity/slack-events listen
 ```
 
+The server filters events, including backlog, to conversations you have joined. Membership is cached for one minute, but new events from channels absent from the snapshot trigger a fresh check before filtering. Events without an identifiable joined channel are omitted.
+
+`listen` retries temporary feed failures with exponential backoff from one to thirty seconds and honors longer `Retry-After` delays. Retries do not advance the read cursor or ACK events. Invalid or revoked feed credentials stop the listener. Other commands do not retry automatically.
+
 `listen` stays running and prints one JSON object per event from your personal
 feed, including available backlog and new arrivals. It uses the saved credential;
 no URL or browser login is needed. Stop with Ctrl+C and run `listen` again later
@@ -73,7 +77,7 @@ slack-events history C012345 --limit 50 --cursor NEXT_CURSOR
 slack-events thread C012345 1788881468.871969 --limit 50
 slack-events file F012345
 slack-events download F012345 ./attachment.pdf
-slack-events listen --resolve
+slack-events listen
 ```
 
 Use `users` and `channels` to discover IDs before making individual reads. They return Slack JSON with `members` or `channels` arrays containing IDs and names. `channels` includes public/private channels and direct/group conversations available to your user grant. Follow `response_metadata.next_cursor` with `--cursor` until it is empty; each call returns one page, and `--limit` accepts 1-200. The existing `list` command lists feed subscriptions, not Slack conversations.
@@ -87,7 +91,7 @@ subscriber's user grant, refuses to overwrite existing paths, and writes mode
 0600. External files without a Slack-hosted download are unsupported. A failed
 transfer may leave a partial output file; remove that file before retrying.
 
-`listen --resolve` adds `context.users` / `context.channels` name maps while preserving the original event and cursor. It fetches a complete user and conversation name snapshot in the background at startup and every six hours, caching the entire snapshot in memory until the next successful refresh. Failed refreshes keep the previous snapshot; unknown names fall back to IDs without blocking delivery. Restarting the listener fetches a fresh snapshot. Standalone file shares also get `context.files` metadata, fetched separately with a two-second deadline; failure leaves the original event intact and the files list empty. Use `file` or `download` to retry retrieving the file.
+`listen` adds `context.users` / `context.channels` name maps while preserving the original event and cursor. The listener waits for the initial user/channel snapshot before polling events, then refreshes it in the background every six hours. Missing names use individual `user` / `channel` lookups with a two-second deadline per request. Successful lookups are cached for six hours; failed lookups and directory refreshes retry after a minute. Failed refreshes retain the previous snapshot. Inaccessible names can remain unresolved; original IDs stay in the JSON. Standalone file shares also get `context.files` metadata, fetched separately with a two-second deadline; failure leaves the original event intact and the files list empty. Use `file` or `download` to retry retrieving the file.
 No read command changes the ACK cursor. The CLI uses its existing paired feed
 credential; Slack user tokens stay on the server. No bot credential is used.
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { chmodSync, mkdirSync, readFileSync, writeFileSync, createWriteStream }
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 export async function runSlackEventsCli(args) {
-    const usage = `Usage: slack-events pair <server> [code] | listen [--resolve] | ack <committed-cursor> | list | revoke <subscription-id>
+    const usage = `Usage: slack-events pair <server> [code] | listen | ack <committed-cursor> | list | revoke <subscription-id>
   users [--limit N] [--cursor C]      List users and their IDs
   channels [--limit N] [--cursor C]   List conversations and their IDs
   user USER_ID                       Get user profile/name
@@ -100,9 +100,9 @@ Read commands print Slack JSON including pagination cursors. They never ACK even
         return;
     }
     if (command === "listen") {
-        if (args.length > 2 || (args[1] && args[1] !== "--resolve"))
+        if (args.length !== 1)
             throw new Error(usage);
-        await listen(credential, args[1] === "--resolve");
+        await listen(credential);
         return;
     }
     throw new Error(usage);
@@ -136,27 +136,37 @@ async function pairDevice(server) {
     }
     throw new Error("Pairing expired. Run the pairing command again for a new link.");
 }
-async function listen(credential, resolve = false) {
+async function listen(credential) {
     const metadataAbort = new AbortController();
-    const names = createNameResolver((operation, cursor) => request(credential.server, `/v1/events/slack/${operation}?${new URLSearchParams({ limit: "200", cursor })}`, { token: credential.token, signal: metadataAbort.signal }));
+    const names = createNameResolver((operation, cursor) => request(credential.server, `/v1/events/slack/${operation}?${new URLSearchParams({ limit: "200", cursor })}`, { token: credential.token, signal: metadataAbort.signal }), (operation, id) => request(credential.server, `/v1/events/slack/${operation}?${new URLSearchParams({ id })}`, { token: credential.token, timeoutMs: 2_000, signal: metadataAbort.signal }));
     const threadRoot = createThreadResolver((channel, ts) => request(credential.server, `/v1/events/slack/message?${new URLSearchParams({ id: channel, ts })}`, { token: credential.token, timeoutMs: 2_000, signal: metadataAbort.signal }));
     let after;
+    let retryDelayMs = 1_000;
     try {
+        await names.refresh();
         for (;;) {
-            if (resolve)
-                void names.refresh();
+            void names.refresh();
             const path = `/v1/events?wait_ms=30000${after === undefined ? "" : `&after=${after}`}`;
-            const response = await request(credential.server, path, { token: credential.token });
+            let response;
+            try {
+                response = await request(credential.server, path, { token: credential.token });
+                retryDelayMs = 1_000;
+            }
+            catch (error) {
+                if (!(error instanceof RetryableRequestError))
+                    throw error;
+                const delay = Math.max(retryDelayMs, error.retryAfterMs);
+                process.stderr.write(`Event feed unavailable: ${error.message}. Retrying in ${Math.ceil(delay / 1000)} seconds.\n`);
+                await new Promise(resolve => setTimeout(resolve, delay));
+                retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
+                continue;
+            }
             const events = Array.isArray(response.events) ? response.events : [];
             for (const event of events) {
-                if (!resolve) {
-                    await writeStdout(`${JSON.stringify(event)}\n`);
-                    continue;
-                }
-                const enriched = names.enrich(requireObject(event));
+                const enriched = await names.enrich(requireObject(event));
                 const root = await threadRoot(requireObject(event));
                 if (root) {
-                    const rootNames = names.enrich({ event: root }).context.users;
+                    const rootNames = (await names.enrich({ event: root })).context.users;
                     const bot = requireObject(root.bot_profile ?? {});
                     enriched.context.threadRoot = { ts: root.ts, user: root.user, text: root.text,
                         author: typeof root.user === "string" ? rootNames[root.user] ?? bot.name : bot.name };
@@ -189,22 +199,47 @@ async function listen(credential, resolve = false) {
         metadataAbort.abort();
     }
 }
+class RetryableRequestError extends Error {
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
 async function request(server, path, options = {}) {
     const timeout = AbortSignal.timeout(options.timeoutMs ?? 40_000);
-    const response = await fetch(new URL(path, `${normalizeServer(server)}/`), {
-        signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
-        method: options.method || "GET",
-        redirect: "error",
-        headers: {
-            ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
-            ...(options.body ? { "content-type": "application/json" } : {}),
-        },
-        body: options.body ? JSON.stringify(options.body) : undefined,
-    });
-    const body = requireObject(await response.json());
-    if (!response.ok)
-        throw new Error(typeof body.error === "string" ? body.error : `Event server returned ${response.status}`);
-    return body;
+    const url = new URL(path, `${normalizeServer(server)}/`);
+    try {
+        const response = await fetch(url, {
+            signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
+            method: options.method || "GET",
+            redirect: "error",
+            headers: {
+                ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+                ...(options.body ? { "content-type": "application/json" } : {}),
+            },
+            body: options.body ? JSON.stringify(options.body) : undefined,
+        });
+        if (!response.ok) {
+            // Proxies can return HTML errors; the HTTP status still determines retryability.
+            const body = await response.json().catch(() => undefined);
+            const message = typeof body?.error === "string" ? body.error : `Event server returned ${response.status}`;
+            if (response.status === 408 || response.status === 429 || response.status >= 500) {
+                const header = response.headers.get("retry-after") ?? "";
+                const delay = /^\d+$/.test(header) ? Number(header) * 1000 : Date.parse(header) - Date.now();
+                throw new RetryableRequestError(message, Number.isFinite(delay) ? Math.max(0, delay) : 0);
+            }
+            throw new Error(message);
+        }
+        return requireObject(await response.json());
+    }
+    catch (error) {
+        if (error instanceof TypeError || (error instanceof Error &&
+            (error.name === "TimeoutError" || (error.name === "AbortError" && timeout.aborted)))) {
+            throw new RetryableRequestError(error.message, 0);
+        }
+        throw error;
+    }
 }
 function credentialPath() {
     const configRoot = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
@@ -279,11 +314,50 @@ function writeStdout(text) {
     });
 }
 /** A whole-directory snapshot belongs to one listener and its credential. */
-export function createNameResolver(fetchPage) {
+export function createNameResolver(fetchPage, fetchOne) {
     let users = new Map();
     let channels = new Map();
     let refreshing;
     let nextRefresh = 0;
+    const lookups = new Map();
+    async function lookup(operation, id) {
+        if (!fetchOne)
+            return undefined;
+        const key = `${operation}/${id}`;
+        const cached = lookups.get(key);
+        if (cached && cached.until > Date.now())
+            return cached.result;
+        const entry = { until: Infinity, result: Promise.resolve(undefined) };
+        entry.result = (async () => {
+            try {
+                const item = requireObject((await fetchOne(operation, id))[operation]);
+                if (item.id !== id)
+                    throw new Error("Slack lookup returned a different ID");
+                entry.until = Date.now() + 6 * 60 * 60_000;
+                return item;
+            }
+            catch (error) {
+                entry.until = Date.now() + 60_000;
+                process.stderr.write(`Name lookup unavailable: ${error instanceof Error ? error.message : "request failed"}\n`);
+                return undefined;
+            }
+        })();
+        if (lookups.size >= 2_000)
+            lookups.delete(lookups.keys().next().value);
+        lookups.set(key, entry);
+        return entry.result;
+    }
+    async function userName(id) {
+        const known = users.get(id);
+        if (known)
+            return known;
+        const user = await lookup("user", id);
+        if (!user)
+            return undefined;
+        const profile = requireObject(user.profile ?? {});
+        const name = profile.display_name || user.real_name || user.name;
+        return typeof name === "string" && name ? name : undefined;
+    }
     async function readPages(operation, accept) {
         let cursor = "";
         const seen = new Set();
@@ -323,6 +397,7 @@ export function createNameResolver(fetchPage) {
             channels = nextChannels;
         }
         catch (error) {
+            nextRefresh = Date.now() + 60_000;
             process.stderr.write(`Name refresh unavailable: ${error instanceof Error ? error.message : "request failed"}\n`);
         }
     }
@@ -336,12 +411,22 @@ export function createNameResolver(fetchPage) {
             refreshing = refresh().finally(() => { refreshing = undefined; });
             return refreshing;
         },
-        enrich(delivery) {
+        async enrich(delivery) {
             const event = requireObject(delivery.event ?? {});
             const message = requireObject(event.message ?? event.previous_message ?? event);
             const item = requireObject(event.item ?? {});
             const channelId = event.channel ?? item.channel ?? event.channel_id;
-            const channel = typeof channelId === "string" ? channels.get(channelId) : undefined;
+            let channel = typeof channelId === "string" ? channels.get(channelId) : undefined;
+            if (!channel && typeof channelId === "string") {
+                const info = await lookup("channel", channelId);
+                if (info) {
+                    const user = info.is_im && typeof info.user === "string" ? info.user : undefined;
+                    const peer = user ? await userName(user) : undefined;
+                    const name = peer ? `DM with ${peer}` : info.name;
+                    if (typeof name === "string" && name)
+                        channel = { name, user };
+                }
+            }
             const context = { users: {}, channels: {}, files: [] };
             if (channel && typeof channelId === "string")
                 context.channels[channelId] = channel.name;
@@ -350,7 +435,7 @@ export function createNameResolver(fetchPage) {
             for (const id of ids) {
                 if (typeof id !== "string")
                     continue;
-                const name = users.get(id);
+                const name = await userName(id);
                 if (name)
                     context.users[id] = name;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zksecurity/slack-events",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Pair a terminal with a pi-mom Slack event feed",
   "type": "module",
   "bin": { "slack-events": "bin/slack-events.mjs" },

package/skills/slack-events/SKILL.md

@@ -13,17 +13,17 @@ and user reauthorization before they work.
 
 ## Reading incoming events
 
+The server filters the feed to conversations you have joined, including backlog. Membership is cached for one minute, but new events from channels absent from the snapshot trigger a fresh check before filtering. Events without an identifiable joined channel are omitted.
+
+`listen` retries temporary feed failures with exponential backoff from one to thirty seconds and honors longer `Retry-After` delays. Retries do not advance the read cursor or ACK events. Invalid or revoked feed credentials stop the listener. Other commands do not retry automatically.
+
 `listen` emits JSONL with `sequence`, stable `eventId`, `teamId`, `eventType`,
-`eventTime`, `receivedAt`, and the inner Slack `event`. `listen --resolve` adds
+`eventTime`, `receivedAt`, and the inner Slack `event`. `listen` adds
 `context.users`, `context.channels`, and file metadata for `file_shared` events.
 For replies, optional `context.threadRoot` supplies the root timestamp, user,
 author name, and text. Root lookups have a two-second deadline and are cached;
 a missing or inaccessible root leaves that field absent.
-The listener fetches a complete user and
-conversation name snapshot in the background at startup and every six hours,
-keeping the whole snapshot in memory between refreshes. Failed refreshes retain
-the last good snapshot. Names are resolved locally; unknown IDs remain IDs and
-never hold up event delivery. IDs remain in the CLI JSON. Restarting the listener fetches a fresh snapshot.
+The listener waits for the initial user/channel snapshot before polling events, then refreshes it in the background every six hours. Missing names use individual `user` / `channel` lookups with a two-second deadline per request. Successful lookups are cached for six hours; failed lookups and directory refreshes retry after a minute. Failed refreshes retain the previous snapshot. Inaccessible names can remain unresolved; original IDs stay in the JSON.
 Standalone file metadata is fetched separately with a two-second deadline;
 failure leaves the original event intact and `context.files` empty.
 
@@ -95,7 +95,7 @@ use the authenticated CLI download rather than unauthenticated curl.
 
 ```sh
 slack-events pair https://YOUR-EVENT-HOST
-slack-events listen --resolve
+slack-events listen
 slack-events list
 ```