@pi-unipi/notify 0.1.1

package/tui/settings-overlay.ts

@@ -0,0 +1,251 @@
+/**
+ * @pi-unipi/notify — Settings TUI Component
+ *
+ * Interactive settings editor for notification configuration.
+ * Allows toggling platforms, configuring credentials, and per-event settings.
+ */
+
+import type { Component } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import {
+  loadConfig,
+  saveConfig,
+  validateConfig,
+} from "../settings.js";
+import type { NotifyConfig } from "../types.js";
+
+/** Section types */
+type Section = "platforms" | "events";
+
+/**
+ * Settings overlay component.
+ */
+export class NotifySettingsOverlay implements Component {
+  private config: NotifyConfig;
+  private section: Section = "platforms";
+  private selectedIndex = 0;
+  private error: string | null = null;
+  private saved = false;
+  onClose?: () => void;
+  requestRender?: () => void;
+  private theme: Theme | null = null;
+
+  constructor() {
+    this.config = loadConfig();
+  }
+
+  setTheme(theme: Theme): void {
+    this.theme = theme;
+  }
+
+  invalidate(): void {}
+
+  handleInput(data: string): void {
+    switch (data) {
+      case "\x1b[A": // Up
+      case "k":
+        this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+        break;
+      case "\x1b[B": // Down
+      case "j":
+        this.selectedIndex = Math.min(this.maxItems - 1, this.selectedIndex + 1);
+        break;
+      case " ": // Space - toggle
+        this.toggleCurrent();
+        break;
+      case "\t": // Tab - switch section
+        this.section = this.section === "platforms" ? "events" : "platforms";
+        this.selectedIndex = 0;
+        break;
+      case "\r": // Enter - save
+        this.save();
+        break;
+      case "\x1b": // Escape - close
+        this.onClose?.();
+        break;
+    }
+  }
+
+  private get maxItems(): number {
+    if (this.section === "platforms") return 3; // native, gotify, telegram
+    return Object.keys(this.config.events).length;
+  }
+
+  private toggleCurrent(): void {
+    if (this.section === "platforms") {
+      const platforms: Array<"native" | "gotify" | "telegram"> = [
+        "native",
+        "gotify",
+        "telegram",
+      ];
+      const key = platforms[this.selectedIndex];
+      if (key) {
+        this.config[key].enabled = !this.config[key].enabled;
+      }
+    } else {
+      const eventKeys = Object.keys(this.config.events);
+      const key = eventKeys[this.selectedIndex];
+      if (key && this.config.events[key]) {
+        this.config.events[key].enabled = !this.config.events[key].enabled;
+      }
+    }
+  }
+
+  private save(): void {
+    const errors = validateConfig(this.config);
+    if (errors.length > 0) {
+      this.error = errors.join("; ");
+      return;
+    }
+    this.error = null;
+    saveConfig(this.config);
+    this.saved = true;
+    setTimeout(() => this.onClose?.(), 500);
+  }
+
+  // ─── Theme helpers ───────────────────────────────────────────────────
+
+  private fg(color: string, text: string): string {
+    if (this.theme) return this.theme.fg(color as any, text);
+    const c: Record<string, string> = {
+      accent: "\x1b[36m", success: "\x1b[32m", warning: "\x1b[33m",
+      error: "\x1b[31m", dim: "\x1b[2m", borderMuted: "\x1b[90m",
+    };
+    return `${c[color] ?? ""}${text}\x1b[0m`;
+  }
+
+  private bold(text: string): string {
+    return this.theme ? this.theme.bold(text) : `\x1b[1m${text}\x1b[0m`;
+  }
+
+  private frameLine(content: string, innerWidth: number): string {
+    const truncated = truncateToWidth(content, innerWidth, "");
+    const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+    return `${this.fg("borderMuted", "│")}${truncated}${" ".repeat(padding)}${this.fg("borderMuted", "│")}`;
+  }
+
+  private ruleLine(innerWidth: number): string {
+    return this.fg("borderMuted", `├${"─".repeat(innerWidth)}┤`);
+  }
+
+  private borderLine(innerWidth: number, edge: "top" | "bottom"): string {
+    const left = edge === "top" ? "┌" : "└";
+    const right = edge === "top" ? "┐" : "┘";
+    return this.fg("borderMuted", `${left}${"─".repeat(innerWidth)}${right}`);
+  }
+
+  private getDialogHeight(): number {
+    const terminalRows = process.stdout.rows ?? 30;
+    return Math.max(14, Math.min(24, Math.floor(terminalRows * 0.65)));
+  }
+
+  render(width: number): string[] {
+    const innerWidth = Math.max(22, width - 2);
+    const lines: string[] = [];
+
+    lines.push(this.borderLine(innerWidth, "top"));
+    lines.push(this.frameLine(this.fg("accent", this.bold("🔔 Notify Settings")), innerWidth));
+    lines.push(this.frameLine(this.fg("dim", "Configure notification platforms and events"), innerWidth));
+    lines.push(this.ruleLine(innerWidth));
+
+    // Section tabs
+    const platformTab =
+      this.section === "platforms"
+        ? this.fg("accent", this.bold("[Platforms]"))
+        : this.fg("dim", "Platforms");
+    const eventsTab =
+      this.section === "events"
+        ? this.fg("accent", this.bold("[Events]"))
+        : this.fg("dim", "Events");
+    lines.push(this.frameLine(`  ${platformTab}  ${eventsTab}`, innerWidth));
+    lines.push(this.ruleLine(innerWidth));
+
+    if (this.section === "platforms") {
+      this.renderPlatforms(lines, innerWidth);
+    } else {
+      this.renderEvents(lines, innerWidth);
+    }
+
+    // Status messages
+    if (this.error) {
+      lines.push(this.ruleLine(innerWidth));
+      lines.push(this.frameLine(`  ${this.fg("error", `⚠ ${this.error}`)}`, innerWidth));
+    }
+    if (this.saved) {
+      lines.push(this.ruleLine(innerWidth));
+      lines.push(this.frameLine(`  ${this.fg("success", "✓ Settings saved")}`, innerWidth));
+    }
+
+    // Footer
+    lines.push(this.ruleLine(innerWidth));
+    lines.push(this.frameLine(this.fg("dim", "↑↓ navigate · Space toggle · Tab switch · Enter save · Esc cancel"), innerWidth));
+    lines.push(this.borderLine(innerWidth, "bottom"));
+
+    return lines;
+  }
+
+  private renderPlatforms(lines: string[], innerWidth: number): void {
+    const platforms: Array<{
+      key: "native" | "gotify" | "telegram";
+      label: string;
+      detail: string;
+    }> = [
+      {
+        key: "native",
+        label: "Native OS",
+        detail: "Desktop notifications (node-notifier)",
+      },
+      {
+        key: "gotify",
+        label: "Gotify",
+        detail: this.config.gotify.serverUrl
+          ? `Server: ${this.config.gotify.serverUrl}`
+          : "Self-hosted push server",
+      },
+      {
+        key: "telegram",
+        label: "Telegram",
+        detail: this.config.telegram.botToken
+          ? "Bot configured"
+          : "Bot API notifications",
+      },
+    ];
+
+    for (let i = 0; i < platforms.length; i++) {
+      const p = platforms[i];
+      const isSelected = i === this.selectedIndex;
+      const toggleOn = this.fg("success", "●");
+      const toggleOff = this.fg("dim", "○");
+      const toggle = this.config[p.key].enabled ? toggleOn : toggleOff;
+      const label = isSelected ? this.bold(p.label) : this.fg("dim", p.label);
+
+      lines.push(
+        this.frameLine(
+          `${isSelected ? this.fg("accent", "▸") : " "} ${toggle} ${label}  ${this.fg("dim", p.detail)}`,
+          innerWidth
+        )
+      );
+    }
+  }
+
+  private renderEvents(lines: string[], innerWidth: number): void {
+    const events = Object.entries(this.config.events);
+
+    for (let i = 0; i < events.length; i++) {
+      const [key, cfg] = events[i];
+      const isSelected = i === this.selectedIndex;
+      const toggleOn = this.fg("success", "●");
+      const toggleOff = this.fg("dim", "○");
+      const toggle = cfg.enabled ? toggleOn : toggleOff;
+      const label = isSelected ? this.bold(key) : this.fg("dim", key);
+
+      lines.push(
+        this.frameLine(
+          `${isSelected ? this.fg("accent", "▸") : " "} ${toggle} ${label}`,
+          innerWidth
+        )
+      );
+    }
+  }
+}

package/tui/telegram-setup.ts

@@ -0,0 +1,301 @@
+/**
+ * @pi-unipi/notify — Telegram Setup TUI Component
+ *
+ * Interactive overlay for setting up Telegram bot notifications.
+ * Guides user through BotFather flow and auto-detects chat ID.
+ */
+
+import type { Component } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { pollForChatId } from "../platforms/telegram.js";
+import { updateConfig } from "../settings.js";
+
+type SetupPhase = "instructions" | "token" | "polling" | "success" | "error" | "timeout";
+
+/** Spinner frames */
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * Telegram setup overlay component.
+ */
+export class TelegramSetupOverlay implements Component {
+  private phase: SetupPhase = "instructions";
+  private botToken = "";
+  private chatId: string | null = null;
+  private error: string | null = null;
+  private spinnerFrame = 0;
+  private spinnerTimer: ReturnType<typeof setInterval> | null = null;
+  private pollAbort: AbortController | null = null;
+  private pollTimer: ReturnType<typeof setTimeout> | null = null;
+  private startTime = Date.now();
+  private readonly TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+  private isInPaste = false;
+  private pasteBuffer = "";
+  onClose?: () => void;
+  requestRender?: () => void;
+  private theme: Theme | null = null;
+
+  setTheme(theme: Theme): void {
+    this.theme = theme;
+  }
+
+  invalidate(): void {}
+
+  handleInput(data: string): void {
+    switch (this.phase) {
+      case "instructions":
+        if (data === "\r" || data === " ") {
+          this.phase = "token";
+        } else if (data === "\x1b") {
+          this.cleanup();
+          this.onClose?.();
+        }
+        break;
+      case "token":
+        // Handle bracketed paste mode
+        if (this.isInPaste) {
+          this.pasteBuffer += data;
+          const endIndex = this.pasteBuffer.indexOf("\x1b[201~");
+          if (endIndex !== -1) {
+            // Extract pasted content and process it
+            const pasteContent = this.pasteBuffer.substring(0, endIndex);
+            this.processTokenInput(pasteContent);
+            this.isInPaste = false;
+            this.pasteBuffer = "";
+          }
+          return;
+        }
+        // Detect start of bracketed paste
+        if (data.includes("\x1b[200~")) {
+          this.isInPaste = true;
+          this.pasteBuffer = data.replace("\x1b[200~", "");
+          return;
+        }
+        if (data === "\r" && this.botToken.length > 0) {
+          this.startPolling();
+        } else if (data === "\x1b") {
+          this.cleanup();
+          this.onClose?.();
+        } else if (data === "\x7f" || data === "\b") {
+          this.botToken = this.botToken.slice(0, -1);
+        } else {
+          this.processTokenInput(data);
+        }
+        break;
+      case "polling":
+        if (data === "\x1b") {
+          this.cleanup();
+          this.onClose?.();
+        }
+        break;
+      case "success":
+      case "error":
+      case "timeout":
+        if (data === "\r" || data === " " || data === "\x1b") {
+          this.cleanup();
+          this.onClose?.();
+        }
+        break;
+    }
+  }
+
+  private processTokenInput(data: string): void {
+    // Ignore escape sequences (arrow keys, function keys, etc.)
+    if (data.startsWith("\x1b[")) return;
+    // Filter to valid bot token characters only
+    const cleaned = data.replace(/[^0-9:A-Za-z_-]/g, "");
+    if (cleaned.length > 0) {
+      this.botToken += cleaned;
+    }
+  }
+
+  private startPolling(): void {
+    this.phase = "polling";
+    this.startTime = Date.now();
+    this.pollAbort = new AbortController();
+
+    // Start spinner animation
+    this.spinnerTimer = setInterval(() => {
+      this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
+      this.requestRender?.();
+    }, 80);
+
+    // Start polling
+    this.doPoll();
+  }
+
+  private async doPoll(): Promise<void> {
+    if (this.phase !== "polling" || !this.pollAbort) return;
+
+    try {
+      const chatId = await pollForChatId(
+        this.botToken,
+        this.pollAbort.signal
+      );
+
+      if (chatId) {
+        this.chatId = chatId;
+        this.phase = "success";
+        this.saveConfig();
+        this.cleanup();
+        this.requestRender?.();
+        // Auto-close after brief delay to show success
+        setTimeout(() => this.onClose?.(), 1000);
+        return;
+      }
+
+      // Check timeout
+      if (Date.now() - this.startTime > this.TIMEOUT_MS) {
+        this.phase = "timeout";
+        this.error = "Timed out after 5 minutes";
+        this.cleanup();
+        this.requestRender?.();
+        return;
+      }
+
+      // Schedule next poll
+      this.pollTimer = setTimeout(() => this.doPoll(), 2000);
+    } catch (err) {
+      if (this.pollAbort?.signal.aborted) return;
+      this.phase = "error";
+      this.error = err instanceof Error ? err.message : String(err);
+      this.cleanup();
+      this.requestRender?.();
+    }
+  }
+
+  private saveConfig(): void {
+    if (this.botToken && this.chatId) {
+      updateConfig({
+        telegram: {
+          enabled: true,
+          botToken: this.botToken,
+          chatId: this.chatId,
+        },
+      });
+    }
+  }
+
+  private cleanup(): void {
+    if (this.spinnerTimer) {
+      clearInterval(this.spinnerTimer);
+      this.spinnerTimer = null;
+    }
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+    if (this.pollAbort) {
+      this.pollAbort.abort();
+      this.pollAbort = null;
+    }
+  }
+
+  // ─── Theme helpers ───────────────────────────────────────────────────
+
+  private fg(color: string, text: string): string {
+    if (this.theme) return this.theme.fg(color as any, text);
+    const c: Record<string, string> = {
+      accent: "\x1b[36m", success: "\x1b[32m", warning: "\x1b[33m",
+      error: "\x1b[31m", dim: "\x1b[2m", borderMuted: "\x1b[90m",
+    };
+    return `${c[color] ?? ""}${text}\x1b[0m`;
+  }
+
+  private bold(text: string): string {
+    return this.theme ? this.theme.bold(text) : `\x1b[1m${text}\x1b[0m`;
+  }
+
+  private frameLine(content: string, innerWidth: number): string {
+    const truncated = truncateToWidth(content, innerWidth, "");
+    const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+    return `${this.fg("borderMuted", "│")}${truncated}${" ".repeat(padding)}${this.fg("borderMuted", "│")}`;
+  }
+
+  private ruleLine(innerWidth: number): string {
+    return this.fg("borderMuted", `├${"─".repeat(innerWidth)}┤`);
+  }
+
+  private borderLine(innerWidth: number, edge: "top" | "bottom"): string {
+    const left = edge === "top" ? "┌" : "└";
+    const right = edge === "top" ? "┐" : "┘";
+    return this.fg("borderMuted", `${left}${"─".repeat(innerWidth)}${right}`);
+  }
+
+  render(width: number): string[] {
+    const innerWidth = Math.max(22, width - 2);
+    const lines: string[] = [];
+
+    lines.push(this.borderLine(innerWidth, "top"));
+    lines.push(this.frameLine(this.fg("accent", this.bold("🤖 Telegram Bot Setup")), innerWidth));
+    lines.push(this.ruleLine(innerWidth));
+
+    switch (this.phase) {
+      case "instructions":
+        lines.push(this.frameLine(this.fg("dim", "Set up Telegram notifications in 3 steps:"), innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        lines.push(this.frameLine(`  ${this.bold("1.")} Open Telegram and message ${this.fg("accent", "@BotFather")}`, innerWidth));
+        lines.push(this.frameLine(`     Send /newbot and follow the prompts to create a bot`, innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        lines.push(this.frameLine(`  ${this.bold("2.")} Copy the bot token from BotFather`, innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        lines.push(this.frameLine(`  ${this.bold("3.")} Send any message to your new bot`, innerWidth));
+        lines.push(this.frameLine(`     (We'll detect your chat ID automatically)`, innerWidth));
+        lines.push(this.ruleLine(innerWidth));
+        lines.push(this.frameLine(this.fg("dim", "Press Enter to continue, Esc to cancel"), innerWidth));
+        break;
+
+      case "token":
+        lines.push(this.frameLine(this.fg("dim", "Paste your bot token from BotFather:"), innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        const display = this.fg("accent", this.bold(this.botToken || " "));
+        lines.push(this.frameLine(`  ${display}${this.fg("dim", "█")}`, innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        lines.push(this.frameLine(this.fg("dim", "Enter to start polling · Esc to cancel"), innerWidth));
+        break;
+
+      case "polling": {
+        const frame = SPINNER_FRAMES[this.spinnerFrame] || "⠋";
+        const elapsed = Math.floor((Date.now() - this.startTime) / 1000);
+        const remaining = Math.max(0, 300 - elapsed);
+        lines.push(this.frameLine(`  ${this.fg("accent", frame)} ${this.bold("Waiting for first message...")}`, innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        lines.push(this.frameLine(`  ${this.fg("dim", "Send any message to your bot in Telegram")}`, innerWidth));
+        lines.push(this.frameLine(`  ${this.fg("dim", `Timeout: ${Math.floor(remaining / 60)}:${String(remaining % 60).padStart(2, "0")}`)}`, innerWidth));
+        lines.push(this.ruleLine(innerWidth));
+        lines.push(this.frameLine(this.fg("dim", "Esc to cancel"), innerWidth));
+        break;
+      }
+
+      case "success":
+        lines.push(this.frameLine(`  ${this.fg("success", "✓ Telegram bot configured!")}`, innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        lines.push(this.frameLine(`  ${this.fg("dim", `Chat ID: ${this.chatId}`)}`, innerWidth));
+        lines.push(this.frameLine(`  ${this.fg("dim", "Notifications will be sent to this chat")}`, innerWidth));
+        lines.push(this.ruleLine(innerWidth));
+        lines.push(this.frameLine(this.fg("dim", "Press Enter to close"), innerWidth));
+        break;
+
+      case "error":
+        lines.push(this.frameLine(`  ${this.fg("error", "✗ Setup failed")}`, innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        lines.push(this.frameLine(`  ${this.fg("dim", this.error || "Unknown error")}`, innerWidth));
+        lines.push(this.ruleLine(innerWidth));
+        lines.push(this.frameLine(this.fg("dim", "Press Enter to close"), innerWidth));
+        break;
+
+      case "timeout":
+        lines.push(this.frameLine(`  ${this.fg("warning", "⏰ Timed out after 5 minutes")}`, innerWidth));
+        lines.push(this.frameLine("", innerWidth));
+        lines.push(this.frameLine(`  ${this.fg("dim", "Make sure you sent a message to your bot in Telegram")}`, innerWidth));
+        lines.push(this.frameLine(`  ${this.fg("dim", "You can try again with /unipi:notify-set-tg")}`, innerWidth));
+        lines.push(this.ruleLine(innerWidth));
+        lines.push(this.frameLine(this.fg("dim", "Press Enter to close"), innerWidth));
+        break;
+    }
+
+    lines.push(this.borderLine(innerWidth, "bottom"));
+    return lines;
+  }
+}

package/types.ts

@@ -0,0 +1,88 @@
+/**
+ * @pi-unipi/notify — TypeScript type definitions
+ */
+
+/** Supported notification platforms */
+export type NotifyPlatform = "native" | "gotify" | "telegram";
+
+/** Per-event notification configuration */
+export interface EventNotifyConfig {
+  /** Whether this event type is enabled */
+  enabled: boolean;
+  /** Platforms to send to (empty = use global defaults) */
+  platforms: NotifyPlatform[];
+}
+
+/** Native notification platform config */
+export interface NativeConfig {
+  /** Whether native notifications are enabled */
+  enabled: boolean;
+  /** Windows appID to show instead of "SnoreToast" */
+  windowsAppId?: string;
+}
+
+/** Gotify notification platform config */
+export interface GotifyConfig {
+  /** Whether Gotify is enabled */
+  enabled: boolean;
+  /** Gotify server URL */
+  serverUrl?: string;
+  /** Gotify app token */
+  appToken?: string;
+  /** Priority level (1-10) */
+  priority: number;
+}
+
+/** Telegram notification platform config */
+export interface TelegramConfig {
+  /** Whether Telegram is enabled */
+  enabled: boolean;
+  /** Telegram bot token */
+  botToken?: string;
+  /** Telegram chat ID */
+  chatId?: string;
+}
+
+/** Full notification configuration */
+export interface NotifyConfig {
+  /** Global default platforms for all events */
+  defaultPlatforms: NotifyPlatform[];
+  /** Per-event type overrides */
+  events: Record<string, EventNotifyConfig>;
+  /** Native platform settings */
+  native: NativeConfig;
+  /** Gotify settings */
+  gotify: GotifyConfig;
+  /** Telegram settings */
+  telegram: TelegramConfig;
+}
+
+/** Parameters for the notify_user agent tool */
+export interface NotifyUserParams {
+  /** Notification message body */
+  message: string;
+  /** Notification title (default: "Pi Notification") */
+  title?: string;
+  /** Priority level */
+  priority?: "low" | "normal" | "high";
+  /** Override platforms for this notification */
+  platforms?: NotifyPlatform[];
+}
+
+/** Result of sending a notification to a single platform */
+export interface NotifyResult {
+  /** Platform that was targeted */
+  platform: NotifyPlatform;
+  /** Whether the send succeeded */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+}
+
+/** Notification dispatch summary */
+export interface NotifyDispatchResult {
+  /** Results per platform */
+  results: NotifyResult[];
+  /** Whether all platforms succeeded */
+  allSuccess: boolean;
+}