slack-cleaner 0.1.0

package/src/domain/cleanup.js

@@ -0,0 +1,149 @@
+const { fetchConversationHistory } = require('../slack/history');
+const { formatSlackTs } = require('../utils/time');
+
+/** @typedef {import('../types').MatchedMessage} MatchedMessage */
+const PERMISSION_ERRORS = new Set([
+  'cant_delete_message',
+  'missing_scope',
+  'no_permission',
+  'not_allowed',
+  'not_authed',
+  'invalid_auth',
+  'account_inactive',
+  'token_revoked',
+]);
+
+/**
+ * @param {import('../types').SlackApiFn} api
+ * @param {Array<{id: string, name: string}>} conversations
+ * @param {(message: any) => boolean} matcher
+ * @param {import('../types').ParsedArgs} args
+ * @returns {Promise<{matches: MatchedMessage[], totalScanned: number}>}
+ */
+async function collectMatches(api, conversations, matcher, args) {
+  let totalScanned = 0;
+  /** @type {MatchedMessage[]} */
+  const matches = [];
+
+  for (const conversation of conversations) {
+    const history = await fetchConversationHistory(api, conversation.id, args);
+    totalScanned += history.length;
+
+    for (const message of history) {
+      if (matcher(message)) {
+        matches.push({ conversation, message });
+      }
+    }
+  }
+
+  return { matches, totalScanned };
+}
+
+/**
+ * @param {Array<import('../types').SlackApiFn>} deleteApis
+ * @param {MatchedMessage[]} items
+ * @param {import('../types').DeletionReporter} reporter
+ * @returns {Promise<{deleted: number, failed: number}>}
+ */
+async function deleteMatches(deleteApis, items, reporter) {
+  if (!Array.isArray(deleteApis) || deleteApis.length === 0) {
+    throw new Error('deleteMatches requires at least one API client');
+  }
+
+  let deleted = 0;
+  let failed = 0;
+  let processed = 0;
+
+  reporter.start();
+  try {
+    for (const item of items) {
+      const result = await deleteWithFallback(deleteApis, item);
+
+      if (!result.ok) {
+        failed += 1;
+        reporter.log(
+          `Failed to delete ${item.conversation.name}#${formatSlackTs(item.message.ts)}: ${result.error || 'unknown_error'}`
+        );
+      } else {
+        deleted += 1;
+      }
+
+      processed += 1;
+      const stats = getAggregateStats(deleteApis);
+      reporter.update({
+        processed,
+        deleted,
+        failed,
+        retryRateLimit: stats.rateLimitRetries,
+        retryTotal: stats.totalRetries,
+        retryWaitSeconds: 0,
+        conversationName: item.conversation.name,
+        ts: item.message.ts,
+      });
+    }
+  } finally {
+    reporter.finish();
+  }
+
+  return { deleted, failed };
+}
+
+/**
+ * @param {Array<import('../types').SlackApiFn>} deleteApis
+ * @param {MatchedMessage} item
+ * @returns {Promise<any>}
+ */
+async function deleteWithFallback(deleteApis, item) {
+  for (let i = 0; i < deleteApis.length; i += 1) {
+    const api = deleteApis[i];
+    const result = await api('chat.delete', {
+      channel: item.conversation.id,
+      ts: item.message.ts,
+    });
+
+    if (result.ok || i === deleteApis.length - 1) {
+      return result;
+    }
+
+    if (!shouldTryFallback(result.error)) {
+      return result;
+    }
+  }
+
+  return { ok: false, error: 'unknown_error' };
+}
+
+/**
+ * @param {string | undefined} errorCode
+ * @returns {boolean}
+ */
+function shouldTryFallback(errorCode) {
+  return typeof errorCode === 'string' && PERMISSION_ERRORS.has(errorCode);
+}
+
+/**
+ * @param {Array<import('../types').SlackApiFn>} apis
+ * @returns {{rateLimitRetries: number, totalRetries: number}}
+ */
+function getAggregateStats(apis) {
+  let rateLimitRetries = 0;
+  let totalRetries = 0;
+
+  for (const api of apis) {
+    const stats =
+      typeof api.getStats === 'function'
+        ? api.getStats()
+        : { rateLimitRetries: 0, totalRetries: 0 };
+    rateLimitRetries += stats.rateLimitRetries || 0;
+    totalRetries += stats.totalRetries || 0;
+  }
+
+  return { rateLimitRetries, totalRetries };
+}
+
+module.exports = {
+  collectMatches,
+  deleteMatches,
+  shouldTryFallback,
+  getAggregateStats,
+};

package/src/domain/filters.js

@@ -0,0 +1,28 @@
+/**
+ * @param {string[]} filters
+ * @param {Map<string, {id: string, name: string}>} users
+ * @returns {Map<string, string>}
+ */
+function resolveUserFilters(filters, users) {
+  const result = new Map();
+
+  for (const filter of filters) {
+    if (filter.startsWith('U')) {
+      result.set(filter, filter);
+      continue;
+    }
+
+    const user = users.get(filter.toLowerCase());
+    if (!user) {
+      throw new Error(`Unknown user filter: ${filter}`);
+    }
+
+    result.set(user.id, user.id);
+  }
+
+  return result;
+}
+
+module.exports = {
+  resolveUserFilters,
+};

package/src/domain/matcher.js

@@ -0,0 +1,141 @@
+/**
+ * @param {import('../types').ParsedArgs} args
+ * @param {Map<string, string>} userFilterIds
+ * @returns {(message: any) => boolean}
+ */
+function createMessageMatcher(args, userFilterIds) {
+  const regex = args.pattern ? new RegExp(args.pattern) : null;
+
+  return (message) => {
+    if (!message || typeof message !== 'object') return false;
+    if (message.subtype === 'message_deleted') return false;
+    if (!message.ts) return false;
+
+    if (args.messageType === 'bot') {
+      const isBot = message.subtype === 'bot_message' || Boolean(message.bot_id);
+      if (!isBot) return false;
+    }
+
+    if (args.messageType === 'user') {
+      const isUser = Boolean(message.user);
+      if (!isUser) return false;
+    }
+
+    if (userFilterIds.size > 0) {
+      if (!message.user || !userFilterIds.has(message.user)) {
+        return false;
+      }
+    }
+
+    if (regex) {
+      const searchableText = extractSearchableMessageText(message);
+      if (!regex.test(searchableText)) {
+        return false;
+      }
+    }
+
+    return true;
+  };
+}
+
+/**
+ * Builds searchable text from message text plus attachments and block structures.
+ * @param {any} message
+ * @returns {string}
+ */
+function extractSearchableMessageText(message) {
+  const parts = [];
+  const seen = new Set();
+
+  pushText(parts, seen, message?.text);
+  collectTextLikeValues(parts, seen, message?.attachments);
+  collectTextLikeValues(parts, seen, message?.blocks);
+  collectTextLikeValues(parts, seen, message?.files);
+  collectTextLikeValues(parts, seen, message?.metadata);
+
+  return parts.join('\n');
+}
+
+/**
+ * Recursively collects string values from text-like keys.
+ * @param {string[]} parts
+ * @param {Set<string>} seen
+ * @param {any} value
+ * @param {number} depth
+ */
+function collectTextLikeValues(parts, seen, value, depth = 0) {
+  if (depth > 12 || value === null || value === undefined) {
+    return;
+  }
+
+  if (typeof value === 'string') {
+    pushText(parts, seen, value);
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectTextLikeValues(parts, seen, item, depth + 1);
+    }
+    return;
+  }
+
+  if (typeof value !== 'object') {
+    return;
+  }
+
+  for (const [key, nested] of Object.entries(value)) {
+    if (typeof nested === 'string' && isTextLikeKey(key)) {
+      pushText(parts, seen, nested);
+      continue;
+    }
+
+    if (typeof nested === 'object' && nested !== null) {
+      collectTextLikeValues(parts, seen, nested, depth + 1);
+    }
+  }
+}
+
+/**
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isTextLikeKey(key) {
+  return (
+    key === 'text' ||
+    key === 'title' ||
+    key === 'value' ||
+    key === 'fallback' ||
+    key === 'pretext' ||
+    key === 'alt_text' ||
+    key === 'plain_text' ||
+    key.endsWith('_text')
+  );
+}
+
+/**
+ * @param {string[]} parts
+ * @param {Set<string>} seen
+ * @param {any} value
+ */
+function pushText(parts, seen, value) {
+  if (typeof value !== 'string') {
+    return;
+  }
+
+  const normalized = value.trim();
+  if (!normalized || seen.has(normalized)) {
+    return;
+  }
+
+  parts.push(normalized);
+  seen.add(normalized);
+}
+
+module.exports = {
+  createMessageMatcher,
+  extractSearchableMessageText,
+  collectTextLikeValues,
+  isTextLikeKey,
+  pushText,
+};

package/src/output/preview.js

@@ -0,0 +1,24 @@
+const { formatSlackTs } = require('../utils/time');
+
+/**
+ * @param {Array<{conversation: {id: string, name: string}, message: any}>} matches
+ * @param {number} limit
+ */
+function printPreview(matches, limit) {
+  const preview = limit > 0 ? matches.slice(0, limit) : matches;
+
+  for (const item of preview) {
+    const text = String(item.message.text || '')
+      .replace(/\s+/g, ' ')
+      .slice(0, 120);
+    console.log(`- ${item.conversation.name} | ${formatSlackTs(item.message.ts)} | ${text}`);
+  }
+
+  if (preview.length < matches.length) {
+    console.log(`... ${matches.length - preview.length} additional matches not shown`);
+  }
+}
+
+module.exports = {
+  printPreview,
+};

package/src/output/progress.js

@@ -0,0 +1,106 @@
+const { formatSlackTs } = require('../utils/time');
+
+/**
+ * Creates a live progress reporter for deletion runs.
+ * @param {number} total
+ * @returns {import('../types').DeletionReporter}
+ */
+function createDeletionProgressReporter(total) {
+  const useLiveLine = Boolean(process.stdout.isTTY);
+  const startedAt = Date.now();
+  let lineLength = 0;
+  let latestState = {
+    processed: 0,
+    deleted: 0,
+    failed: 0,
+    retryRateLimit: 0,
+    retryTotal: 0,
+    retryWaitSeconds: 0,
+    conversationName: '',
+    ts: '',
+  };
+
+  /**
+   * @param {import('../types').DeletionProgressState} state
+   * @returns {string}
+   */
+  function renderLine(state) {
+    const elapsedSec = Math.max(1, Math.floor((Date.now() - startedAt) / 1000));
+    const rate = (state.processed / elapsedSec).toFixed(1);
+    const percent = ((state.processed / total) * 100).toFixed(1);
+    const last =
+      state.processed > 0 ? ` last=${state.conversationName}@${formatSlackTs(state.ts)}` : '';
+    const wait = state.retryWaitSeconds > 0 ? ` wait=${state.retryWaitSeconds}s` : '';
+    return `Deleting ${state.processed}/${total} (${percent}%) ok=${state.deleted} fail=${state.failed} retries_total=${state.retryTotal} retries_rate_limit=${state.retryRateLimit}${wait} rate=${rate}/s${last}`;
+  }
+
+  return {
+    start() {
+      if (!useLiveLine) {
+        console.log(`Deleting ${total} message(s)...`);
+      }
+    },
+    /**
+     * @param {import('../types').DeletionProgressState} state
+     */
+    update(state) {
+      latestState = {
+        ...latestState,
+        ...state,
+      };
+      const line = renderLine(latestState);
+
+      if (useLiveLine) {
+        const padding = Math.max(0, lineLength - line.length);
+        process.stdout.write(`\r${line}${' '.repeat(padding)}`);
+        lineLength = line.length;
+        return;
+      }
+
+      if (state.processed === total || state.processed === 1 || state.processed % 25 === 0) {
+        console.log(line);
+      }
+    },
+    /**
+     * @param {string} message
+     */
+    log(message) {
+      if (useLiveLine) {
+        process.stdout.write('\n');
+        lineLength = 0;
+      }
+      console.error(message);
+      if (useLiveLine && latestState.processed > 0) {
+        const line = renderLine(latestState);
+        process.stdout.write(line);
+        lineLength = line.length;
+      }
+    },
+    /**
+     * @param {number} seconds
+     */
+    setRetryWaitSeconds(seconds) {
+      latestState = {
+        ...latestState,
+        retryWaitSeconds: Math.max(0, Math.floor(seconds)),
+      };
+      const line = renderLine(latestState);
+
+      if (useLiveLine) {
+        const padding = Math.max(0, lineLength - line.length);
+        process.stdout.write(`\r${line}${' '.repeat(padding)}`);
+        lineLength = line.length;
+        return;
+      }
+    },
+    finish() {
+      if (useLiveLine) {
+        process.stdout.write('\n');
+      }
+    },
+  };
+}
+
+module.exports = {
+  createDeletionProgressReporter,
+};

package/src/slack/client.js

@@ -0,0 +1,169 @@
+const { sleep } = require('../utils/time');
+
+const SLACK_API_BASE = 'https://slack.com/api';
+const DEFAULT_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 30000;
+
+/**
+ * @param {string} token
+ * @param {{minRequestIntervalMs: number, maxRetries: number, verbose: boolean}} options
+ * @returns {import('../types').SlackApiFn & {getStats: () => {rateLimitRetries: number, totalRetries: number}, setRetryObserver: (observer: ((seconds: number) => void) | null | undefined) => void}}
+ */
+function createSlackApi(token, options) {
+  let nextRequestAt = 0;
+  let rateLimitRetries = 0;
+  let totalRetries = 0;
+  /** @type {((seconds: number) => void) | null} */
+  let retryObserver = null;
+
+  /**
+   * @param {number} attempt
+   * @returns {number}
+   */
+  function computeBackoffMs(attempt) {
+    const base = DEFAULT_BACKOFF_MS * 2 ** Math.max(0, attempt - 1);
+    const jitter = Math.floor(Math.random() * 200);
+    return Math.min(MAX_BACKOFF_MS, base + jitter);
+  }
+
+  /**
+   * Sleeps while reporting countdown seconds for retry wait windows.
+   * @param {number} waitMs
+   * @returns {Promise<void>}
+   */
+  async function waitWithRetryObserver(waitMs) {
+    let remainingMs = Math.max(0, Math.floor(waitMs));
+
+    while (remainingMs > 0) {
+      if (retryObserver) {
+        retryObserver(Math.ceil(remainingMs / 1000));
+      }
+      const chunkMs = Math.min(1000, remainingMs);
+      await sleep(chunkMs);
+      remainingMs -= chunkMs;
+    }
+
+    if (retryObserver) {
+      retryObserver(0);
+    }
+  }
+
+  /**
+   * Writes verbose retry logs without clobbering live progress lines.
+   * @param {string} message
+   */
+  function logVerboseRetry(message) {
+    if (!options.verbose) {
+      return;
+    }
+
+    if (retryObserver && process.stdout.isTTY) {
+      if (typeof process.stdout.clearLine === 'function') {
+        process.stdout.clearLine(0);
+      }
+      if (typeof process.stdout.cursorTo === 'function') {
+        process.stdout.cursorTo(0);
+      } else {
+        process.stdout.write('\r');
+      }
+    }
+
+    console.log(message);
+  }
+
+  /**
+   * @param {string} method
+   * @param {Record<string, string>} [params]
+   */
+  const api = async (method, params = {}) => {
+    for (let attempt = 0; attempt <= options.maxRetries; attempt += 1) {
+      const now = Date.now();
+      if (nextRequestAt > now) {
+        await sleep(nextRequestAt - now);
+      }
+
+      const url = `${SLACK_API_BASE}/${method}`;
+      const body = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null && value !== '') {
+          body.set(key, value);
+        }
+      }
+
+      let response;
+      try {
+        response = await fetch(url, {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/x-www-form-urlencoded',
+          },
+          body,
+        });
+      } catch (error) {
+        if (attempt >= options.maxRetries) {
+          throw error;
+        }
+
+        totalRetries += 1;
+        const backoffMs = computeBackoffMs(attempt + 1);
+        logVerboseRetry(`Retrying ${method} after network error in ${backoffMs}ms`);
+        await waitWithRetryObserver(backoffMs);
+        continue;
+      }
+
+      if (response.status === 429) {
+        if (attempt >= options.maxRetries) {
+          throw new Error(`Slack API rate limit exceeded for ${method} after retries`);
+        }
+
+        totalRetries += 1;
+        rateLimitRetries += 1;
+        const retryAfterHeader = response.headers.get('retry-after');
+        const retryAfterSeconds = Number.parseFloat(retryAfterHeader || '');
+        const retryAfterMs =
+          Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+            ? Math.ceil(retryAfterSeconds * 1000)
+            : computeBackoffMs(attempt + 1);
+        const jitterMs = Math.floor(Math.random() * 250);
+        const waitMs = retryAfterMs + jitterMs;
+
+        logVerboseRetry(`Slack 429 on ${method}; retrying in ${waitMs}ms`);
+        await waitWithRetryObserver(waitMs);
+        continue;
+      }
+
+      if (response.status >= 500) {
+        if (attempt >= options.maxRetries) {
+          throw new Error(`Slack API HTTP ${response.status} on ${method} after retries`);
+        }
+
+        totalRetries += 1;
+        const backoffMs = computeBackoffMs(attempt + 1);
+        logVerboseRetry(`Slack API HTTP ${response.status} on ${method}; retrying in ${backoffMs}ms`);
+        await waitWithRetryObserver(backoffMs);
+        continue;
+      }
+
+      if (!response.ok) {
+        throw new Error(`Slack API HTTP ${response.status} on ${method}`);
+      }
+
+      nextRequestAt = Date.now() + options.minRequestIntervalMs;
+      return response.json();
+    }
+
+    throw new Error(`Slack API call failed for ${method} after retries`);
+  };
+
+  api.getStats = () => ({ rateLimitRetries, totalRetries });
+  api.setRetryObserver = (observer) => {
+    retryObserver = typeof observer === 'function' ? observer : null;
+  };
+  return api;
+}
+
+module.exports = {
+  createSlackApi,
+  SLACK_API_BASE,
+};