@pellux/goodvibes-tui 0.24.1 → 0.26.0

package/src/daemon/handlers/triage/scorer.ts

@@ -0,0 +1,287 @@
+// ---------------------------------------------------------------------------
+// Daemon-internal email auto-tag / spam triage SCORER.
+//
+// Pure, dependency-free heuristic + naive-Bayes-style spam/priority scoring
+// over an InboundChannelItem's textual surface (subject + snippet). No I/O,
+// no credentials, no network — safe to run on every polled item.
+//
+// The score is a normalized 0..1 confidence in the assigned label. The label
+// is one of 'spam' | 'priority' | 'normal'. Scoring is deterministic so the
+// pipeline can persist stable triageScore/triageTags values across polls.
+// ---------------------------------------------------------------------------
+
+import type { InboundChannelItem, TriageLabel } from './types.ts';
+
+export type { TriageLabel } from './types.ts';
+
+export interface TriageScore {
+  /** Confidence in the assigned label, 0..1 (2-decimal rounded). */
+  score: number;
+  label: TriageLabel;
+  /** Raw component probabilities (for diagnostics / tests). */
+  signals: {
+    spam: number; // 0..1 P(spam)
+    priority: number; // 0..1 P(priority)
+  };
+}
+
+export interface TriageScorerOptions {
+  /** Minimum P(spam) to label an item 'spam'. Default 0.65. */
+  spamThreshold?: number;
+  /** Minimum P(priority) to label an item 'priority'. Default 0.6. */
+  priorityThreshold?: number;
+  /** Extra spam lexicon terms (lowercased) merged with the defaults. */
+  extraSpamTerms?: readonly string[];
+  /** Extra priority lexicon terms (lowercased) merged with the defaults. */
+  extraPriorityTerms?: readonly string[];
+}
+
+const DEFAULT_SPAM_THRESHOLD = 0.65;
+const DEFAULT_PRIORITY_THRESHOLD = 0.6;
+
+// Tokens that, when present, push toward spam. Weighted log-likelihoods.
+const SPAM_TERMS: ReadonlyMap<string, number> = new Map([
+  ['viagra', 3.2],
+  ['lottery', 2.8],
+  ['winner', 2.0],
+  ['congratulations', 1.4],
+  ['prize', 2.2],
+  ['free', 1.1],
+  ['cash', 1.6],
+  ['bitcoin', 1.5],
+  ['crypto', 1.2],
+  ['investment', 1.0],
+  ['guarantee', 1.3],
+  ['guaranteed', 1.5],
+  ['risk-free', 2.0],
+  ['click', 1.2],
+  ['unsubscribe', 0.9],
+  ['limited', 0.9],
+  ['offer', 1.0],
+  ['act now', 2.2],
+  ['urgent', 0.7],
+  ['wire transfer', 2.6],
+  ['nigerian', 2.6],
+  ['inheritance', 2.4],
+  ['million', 1.4],
+  ['pharmacy', 2.2],
+  ['pills', 2.0],
+  ['loan', 1.4],
+  ['debt', 1.2],
+  ['refinance', 1.6],
+  ['casino', 2.4],
+  ['earn money', 2.2],
+  ['work from home', 1.8],
+  ['100% free', 2.4],
+  ['no cost', 1.6],
+  ['cheap', 1.2],
+  ['discount', 0.8],
+  ['weight loss', 2.0],
+  ['verify your account', 2.6],
+  ['suspended', 1.4],
+  ['password', 1.0],
+  ['confirm your identity', 2.4],
+]);
+
+// Tokens that push toward priority/important.
+const PRIORITY_TERMS: ReadonlyMap<string, number> = new Map([
+  ['urgent', 2.4],
+  ['asap', 2.4],
+  ['immediately', 2.0],
+  ['deadline', 2.0],
+  ['today', 1.2],
+  ['eod', 1.6],
+  ['important', 1.6],
+  ['action required', 2.2],
+  ['action needed', 2.2],
+  ['please respond', 1.8],
+  ['please reply', 1.8],
+  ['waiting', 1.0],
+  ['follow up', 1.2],
+  ['follow-up', 1.2],
+  ['reminder', 1.0],
+  ['overdue', 2.2],
+  ['blocker', 2.0],
+  ['blocked', 1.6],
+  ['escalation', 2.2],
+  ['escalate', 2.0],
+  ['critical', 2.4],
+  ['emergency', 2.6],
+  ['payment due', 2.0],
+  ['invoice', 1.2],
+  ['signature', 1.0],
+  ['approval', 1.4],
+  ['approve', 1.4],
+  ['meeting', 0.8],
+  ['call me', 1.6],
+]);
+
+const URL_PATTERN = /https?:\/\/[^\s]+/gi;
+const MONEY_PATTERN = /(?:[$£€]\s?\d|(?:\d[\d,]*)\s?(?:usd|eur|gbp|dollars|euros))/i;
+const EXCESSIVE_PUNCT = /[!?]{2,}/;
+
+function normalizeText(item: InboundChannelItem): string {
+  const subject = typeof item.subject === 'string' ? item.subject : '';
+  const snippet = typeof item.snippet === 'string' ? item.snippet : '';
+  // Subject is weighted more heavily by duplicating it once.
+  return `${subject} ${subject} ${snippet}`.trim();
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function countLexicon(text: string, lexicon: ReadonlyMap<string, number>): number {
+  let total = 0;
+  for (const [term, weight] of lexicon) {
+    if (term.includes(' ')) {
+      // Phrase match: count non-overlapping occurrences.
+      let from = 0;
+      let idx = text.indexOf(term, from);
+      while (idx !== -1) {
+        total += weight;
+        from = idx + term.length;
+        idx = text.indexOf(term, from);
+      }
+    } else {
+      // Word-boundary match for single tokens.
+      const re = new RegExp(`\\b${escapeRegExp(term)}\\b`, 'g');
+      const matches = text.match(re);
+      if (matches) total += weight * matches.length;
+    }
+  }
+  return total;
+}
+
+function upperCaseRatio(text: string): number {
+  const letters = text.replace(/[^a-zA-Z]/g, '');
+  if (letters.length < 8) return 0;
+  let upper = 0;
+  for (const ch of letters) {
+    if (ch >= 'A' && ch <= 'Z') upper += 1;
+  }
+  return upper / letters.length;
+}
+
+function urlDensity(text: string): number {
+  const urls = text.match(URL_PATTERN);
+  const urlCount = urls ? urls.length : 0;
+  const words = text.split(/\s+/).filter((w) => w.length > 0).length || 1;
+  return urlCount / words;
+}
+
+/** Logistic squash of an accumulated log-likelihood into 0..1. */
+function sigmoid(x: number): number {
+  return 1 / (1 + Math.exp(-x));
+}
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function clamp01(value: number): number {
+  if (Number.isNaN(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+function mergeLexicon(
+  base: ReadonlyMap<string, number>,
+  extra: readonly string[] | undefined,
+  extraWeight: number,
+): ReadonlyMap<string, number> {
+  if (!extra || extra.length === 0) return base;
+  const merged = new Map(base);
+  for (const term of extra) {
+    const key = term.trim().toLowerCase();
+    if (key.length === 0) continue;
+    merged.set(key, Math.max(merged.get(key) ?? 0, extraWeight));
+  }
+  return merged;
+}
+
+/**
+ * Score a single inbound item for spam likelihood and priority likelihood,
+ * then resolve a single label. Deterministic and side-effect free.
+ */
+export function scoreInboundItem(
+  item: InboundChannelItem,
+  options: TriageScorerOptions = {},
+): TriageScore {
+  const spamThreshold = options.spamThreshold ?? DEFAULT_SPAM_THRESHOLD;
+  const priorityThreshold = options.priorityThreshold ?? DEFAULT_PRIORITY_THRESHOLD;
+
+  const spamLexicon = mergeLexicon(SPAM_TERMS, options.extraSpamTerms, 1.5);
+  const priorityLexicon = mergeLexicon(PRIORITY_TERMS, options.extraPriorityTerms, 1.5);
+
+  const raw = normalizeText(item);
+  const text = raw.toLowerCase();
+
+  // ---- Spam evidence -----------------------------------------------------
+  // Bias term tuned so a clean message lands well below the threshold.
+  let spamLL = -2.4;
+  spamLL += countLexicon(text, spamLexicon);
+
+  const caps = upperCaseRatio(raw);
+  if (caps > 0.6) spamLL += 1.8;
+  else if (caps > 0.4) spamLL += 0.9;
+
+  const density = urlDensity(text);
+  if (density > 0.25) spamLL += 1.6;
+  else if (density > 0.1) spamLL += 0.8;
+
+  if (MONEY_PATTERN.test(raw)) spamLL += 0.8;
+  if (EXCESSIVE_PUNCT.test(raw)) spamLL += 0.6;
+  if (raw.length === 0) spamLL -= 1.0; // empty/no-text items are not spam
+
+  const spam = clamp01(sigmoid(spamLL));
+
+  // ---- Priority evidence -------------------------------------------------
+  let priorityLL = -2.2;
+  priorityLL += countLexicon(text, priorityLexicon);
+
+  // Direct conversations (1:1 DMs) are inherently more likely to be priority.
+  if (item.conversationKind === 'direct') priorityLL += 0.8;
+  if (item.unread === true) priorityLL += 0.3;
+  // A trailing question mark suggests an awaited answer.
+  if (/\?\s*$/.test(raw)) priorityLL += 0.5;
+
+  // Spam strongly suppresses priority — promotional text is rarely urgent.
+  priorityLL -= spam * 2.5;
+
+  const priority = clamp01(sigmoid(priorityLL));
+
+  // ---- Label resolution --------------------------------------------------
+  let label: TriageLabel = 'normal';
+  let score: number;
+  if (spam >= spamThreshold && spam >= priority) {
+    label = 'spam';
+    score = spam;
+  } else if (priority >= priorityThreshold) {
+    label = 'priority';
+    score = priority;
+  } else {
+    label = 'normal';
+    // Confidence in 'normal' is how far both signals sit below their gates.
+    score = clamp01(1 - Math.max(spam, priority));
+  }
+
+  return {
+    score: round2(score),
+    label,
+    signals: { spam: round2(spam), priority: round2(priority) },
+  };
+}
+
+/** Map a label to the canonical provider-side tag string applied by the tagger. */
+export function labelToTag(label: TriageLabel): string {
+  switch (label) {
+    case 'spam':
+      return 'GoodVibes/Spam';
+    case 'priority':
+      return 'GoodVibes/Priority';
+    default:
+      return 'GoodVibes/Normal';
+  }
+}

package/src/daemon/handlers/triage/tagger/discord.ts

@@ -0,0 +1,186 @@
+// ---------------------------------------------------------------------------
+// Triage tagger — Discord provider.
+//
+// Two paths, in priority order:
+//   1. REAL thread tags: when the item targets a forum/media-channel thread and
+//      a forum-tag mapping resolves >=1 tag id, PATCH the thread's applied_tags
+//      (read-then-merge — never blind overwrite). Exact fidelity to the
+//      contract's "Discord thread tags".
+//   2. Reaction analog: Discord has no arbitrary per-message tags, so otherwise
+//      add a unicode reaction (PUT .../reactions/{emoji}/@me).
+//
+// The bot token is resolved per-apply from the daemon credential store and is
+// never logged or returned.
+// ---------------------------------------------------------------------------
+
+import type { HandlerContext } from '../../context.ts';
+import type { DaemonCredentialStore } from '../../credentials.ts';
+import { HandlerError } from '../../errors.ts';
+import type { InboundChannelItem } from '../types.ts';
+import type { ApplyTagsResult, TaggerProviderConfig } from './shared.ts';
+import { discordEmojiForTag, stringMeta } from './shared.ts';
+
+export async function applyDiscord(
+  item: InboundChannelItem,
+  tags: string[],
+  providers: TaggerProviderConfig,
+  credentials: DaemonCredentialStore,
+  fetchImpl: typeof fetch,
+  ctx: HandlerContext,
+  base: ApplyTagsResult,
+): Promise<ApplyTagsResult> {
+  const cfg = providers.discord;
+  if (!cfg) return { ...base, reason: 'discord-not-configured' };
+  const channelId = stringMeta(item, 'channelId') ?? item.conversationId;
+  const messageId = stringMeta(item, 'messageId') ?? item.id;
+  if (!channelId || !messageId) return { ...base, reason: 'discord-missing-target' };
+  if (tags.length === 0) return { ...base, reason: 'no-tags' };
+
+  const token = await credentials.resolveConfigSecret(cfg.tokenConfigKey);
+  if (!token) return { ...base, reason: 'discord-no-credentials' };
+
+  // Exact-fidelity path: when the item targets a forum/media-channel thread and
+  // a forum-tag mapping resolves at least one tag, apply REAL Discord thread
+  // tags (PATCH the thread's applied_tags). A forum post's thread id is the
+  // thread's own channel id; accept an explicit metadata.threadId or fall back
+  // to channelId for that case.
+  const threadId = stringMeta(item, 'threadId') ?? channelId;
+  const tagIds = resolveDiscordTagIds(tags, cfg.forumTagIds);
+  if (tagIds.length > 0) {
+    return applyDiscordThreadTags(item, threadId, tags, tagIds, token, fetchImpl, ctx);
+  }
+
+  // Analog fallback: Discord has no arbitrary per-message tags, so apply a
+  // unicode reaction on the source message instead.
+  const applied: string[] = [];
+  for (const tag of tags) {
+    const emoji = encodeURIComponent(discordEmojiForTag(tag));
+    const url = `https://discord.com/api/v10/channels/${channelId}/messages/${messageId}/reactions/${emoji}/@me`;
+    const response = await fetchImpl(url, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bot ${token}`,
+        'Content-Length': '0',
+      },
+    });
+    // 204 No Content is the success case for adding a reaction.
+    if (response.status !== 204 && response.status !== 200) {
+      const detail = await response.text().catch(() => '');
+      ctx.logger.warn('triage: discord reaction rejected', { status: response.status });
+      throw new HandlerError(
+        `Discord reaction HTTP ${response.status}${detail ? `: ${detail.slice(0, 120)}` : ''}`,
+        'TRIAGE_DISCORD_TAG_FAILED',
+        502,
+      );
+    }
+    applied.push(tag);
+  }
+  return { surface: item.surface, itemId: item.id, appliedTags: applied, skipped: false };
+}
+
+/**
+ * Map GoodVibes triage tags to configured Discord forum-tag snowflake ids,
+ * preserving order and dropping unmapped tags. De-duplicates ids.
+ */
+function resolveDiscordTagIds(
+  tags: readonly string[],
+  forumTagIds: Record<string, string> | undefined,
+): string[] {
+  if (!forumTagIds) return [];
+  const ids: string[] = [];
+  for (const tag of tags) {
+    const id = forumTagIds[tag];
+    if (typeof id === 'string' && id.length > 0 && !ids.includes(id)) ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Apply real Discord thread tags by merging the resolved forum-tag ids into the
+ * thread's existing applied_tags via PATCH /channels/{thread.id}. Idempotent:
+ * already-present tag ids are kept and not duplicated.
+ */
+async function applyDiscordThreadTags(
+  item: InboundChannelItem,
+  threadId: string,
+  tags: readonly string[],
+  tagIds: readonly string[],
+  token: string,
+  fetchImpl: typeof fetch,
+  ctx: HandlerContext,
+): Promise<ApplyTagsResult> {
+  const url = `https://discord.com/api/v10/channels/${threadId}`;
+  // DATA-LOSS GUARD: we PATCH the thread's full applied_tags array, so we must
+  // first read the EXISTING tags and merge. If that read fails (network error
+  // OR a non-ok HTTP status), we have no idea what tags are currently on the
+  // thread — PATCHing with only our new ids would silently destroy whatever
+  // forum tags were already applied. Abort instead of overwriting.
+  const existing = await fetchDiscordAppliedTags(url, token, fetchImpl, ctx);
+  if (existing === null) {
+    throw new HandlerError(
+      'Discord thread tag read failed; aborting to avoid overwriting existing applied_tags.',
+      'TRIAGE_DISCORD_TAG_FAILED',
+      502,
+    );
+  }
+  const merged = [...new Set([...existing, ...tagIds])];
+  const response = await fetchImpl(url, {
+    method: 'PATCH',
+    headers: {
+      Authorization: `Bot ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ applied_tags: merged }),
+  });
+  if (response.status !== 200 && response.status !== 204) {
+    const detail = await response.text().catch(() => '');
+    ctx.logger.warn('triage: discord thread tag rejected', { status: response.status });
+    throw new HandlerError(
+      `Discord thread tag HTTP ${response.status}${detail ? `: ${detail.slice(0, 120)}` : ''}`,
+      'TRIAGE_DISCORD_TAG_FAILED',
+      502,
+    );
+  }
+  return { surface: item.surface, itemId: item.id, appliedTags: [...tags], skipped: false };
+}
+
+/**
+ * Read a thread's current applied_tags.
+ *
+ * Returns:
+ *   - string[]  -> the read SUCCEEDED; the array is the current applied_tags
+ *                  (possibly empty when the thread genuinely has no tags, or
+ *                  when applied_tags is absent/malformed in a 2xx body).
+ *   - null      -> the read FAILED (thrown error OR non-ok HTTP status). The
+ *                  caller MUST NOT proceed with a PATCH in this case, because a
+ *                  failed read means the existing tag set is unknown and a
+ *                  PATCH would overwrite it (data loss).
+ */
+async function fetchDiscordAppliedTags(
+  url: string,
+  token: string,
+  fetchImpl: typeof fetch,
+  ctx: HandlerContext,
+): Promise<string[] | null> {
+  try {
+    const response = await fetchImpl(url, {
+      method: 'GET',
+      headers: { Authorization: `Bot ${token}` },
+    });
+    if (!response.ok) {
+      ctx.logger.warn('triage: discord thread tag read failed', { status: response.status });
+      return null;
+    }
+    const payload = (await response.json().catch(() => null)) as
+      | { applied_tags?: unknown }
+      | null;
+    const current = payload?.applied_tags;
+    if (!Array.isArray(current)) return [];
+    return current.filter((t): t is string => typeof t === 'string');
+  } catch (error) {
+    ctx.logger.warn('triage: discord thread tag read errored', {
+      message: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}