termicord 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dilukshan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+<div align="center">
+
+<img src="public/termicord.jpg" alt="termicord logo">
+<br />
+<h2>A beautiful, terminal-native Discord attachment downloader</h2>
+<p>Built with TypeScript · Powered by Bun · UI rendered by OpenTUI</p>
+
+---
+
+[![Bun](https://img.shields.io/badge/Runtime-Bun-f9a8d4?style=for-the-badge&logo=bun&logoColor=white)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/Language-TypeScript-8b5cf6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![OpenTUI](https://img.shields.io/badge/UI-OpenTUI-e879f9?style=for-the-badge&logo=zig&logoColor=white)](https://github.com/anomalyco/opentui)
+[![Discord API](https://img.shields.io/badge/Discord-API%20v10-c4b5fd?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/developers/docs/intro)
+
+</div>
+
+---
+
+## Overview
+
+`termicord` is a sleek, fully terminal-native tool to **bulk-download all attachments from any Discord channel** you have access to. It talks directly to the Discord REST API v10, handles rate-limiting gracefully, and wraps everything in a gorgeous animated TUI — no browser, no Electron, no nonsense.
+
+The interface is powered by **[OpenTUI](https://github.com/anomalyco/opentui)**, a Zig-native terminal UI library exposed to the JavaScript ecosystem via `@opentui/core`. This means pixel-perfect box rendering, smooth animations, mouse support, and focus management — all at near-native speed.
+
+---
+
+## Features
+
+| Feature | Details |
+|---|---|
+| **Animated TUI** | Staggered banner + cascading panel reveal on startup |
+| **Bulk Attachment Download** | Fetches every attachment from an entire channel history |
+| **Auto Rate-Limit Handling** | Detects Discord 429 responses and backs off automatically |
+| **Per-Message Folders** | Optional mode to create one folder per message, named by date + author + snippet |
+| **Extension Filtering** | Skip specific file types (e.g. `.jpg .png .gif`) before any download begins |
+| **Abort Support** | Press `Esc` at any time to cleanly cancel an in-flight download |
+| **Live Log Tab** | Real-time timestamped log output in a scrollable panel |
+| **Responsive Layout** | Full-width banner on wide terminals, compact mode on narrow ones |
+| **Mouse Support** | Click the Download button directly |
+| **Duplicate Detection** | Skips files that already exist on disk |
+
+---
+
+## UI Powered by OpenTUI + Zig
+
+The entire terminal interface is driven by **`@opentui/core`**, which is built on top of a **Zig**-native rendering engine. This gives the TUI:
+
+- **Sub-millisecond render cycles** via Zig's zero-overhead abstractions
+- **True-color (24-bit) support** — every hex color you see (`#c4b5fd`, `#f0abfc`, etc.) is rendered natively
+- **Composable renderables** — `BoxRenderable`, `TextRenderable`, `InputRenderable` — each a self-contained layout node
+- **Event-driven input** — keyboard and mouse events propagate through a typed event bus backed by native I/O
+- **Flex-style layout engine** — `flexDirection`, `justifyContent`, `alignItems`, `overflow: scroll` — a real layout system, not ASCII hacks
+
+> Zig's `comptime` and manual memory model allow OpenTUI to avoid GC pauses entirely, making the UI feel instant even on low-spec hardware.
+
+---
+
+## Architecture
+
+```
+termicord/
+├── index.ts        # TUI shell — all UI logic, layout, key bindings, animation
+├── middleware.ts   # Thin adapter — bridges raw config from the UI to the backend
+├── backend.ts      # Core engine — Discord API calls, download logic, abort support
+├── package.json    # Bun project manifest
+└── tsconfig.json   # TypeScript config
+```
+
+### Data Flow
+
+```
+[ User Input (TUI) ]
+        │
+        ▼
+[ middleware.ts: startDownloadTask() ]
+   ↳ Parses raw string config (extensions, paths)
+   ↳ Creates AbortController
+        │
+        ▼
+[ backend.ts: runDownload() ]
+   ↳ Authenticates with Discord API v10
+   ↳ Paginates all messages (100/page, cursor-based)
+   ↳ Filters attachments by extension
+   ↳ Downloads binaries with timeout + retry
+   ↳ Emits typed DownloadProgress events
+        │
+        ▼
+[ index.ts: addLog() → logsText.content ]
+   ↳ Timestamped lines rendered live in the Logs tab
+```
+
+---
+
+## Requirements
+
+| Dependency | Version |
+|---|---|
+| [Bun](https://bun.sh) | `>= 1.3.10` |
+| [TypeScript](https://www.typescriptlang.org) | `^5.x` |
+| [`@opentui/core`](https://www.npmjs.com/package/@opentui/core) | `^0.1.87` |
+
+> **Node.js is not required.** This project runs exclusively on Bun.
+
+---
+
+## Installation
+
+```
+# 1. Clone the repository
+git clone https://github.com/dilukshann7/termicord.git
+cd termicord
+
+# 2. Install dependencies
+bun install
+
+# 3. Launch
+bun run index.ts
+```
+
+---
+
+## Usage
+
+When the TUI launches, you will see four input fields and a checkbox:
+
+| Field | Description |
+|---|---|
+| **Discord Token** | Your user or bot token (`Authorization` header value) |
+| **Channel ID** | The numeric ID of the target channel |
+| **Download Location** | Local path where files will be saved (default: `./downloads`) |
+| **Extensions to Skip** | Space or comma-separated extensions to ignore (e.g. `.jpg .gif`) |
+| **Folder per message** | When checked, each message gets its own named subfolder |
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|---|---|
+| `Tab` | Focus next field |
+| `Shift + Tab` | Focus previous field |
+| `Space` | Toggle the folder-per-message checkbox |
+| `Enter` | Start download (from any field) |
+| `Ctrl + E` | Switch to Logs tab |
+| `Ctrl + Q` | Switch to Config tab |
+| `Esc` | Abort an in-progress download |
+| `Ctrl + C` | Exit the application |
+
+---
+
+## How It Works
+
+### Message Pagination
+
+Discord's API returns a maximum of **100 messages per request**. The backend uses a cursor-based pagination loop — each batch uses the snowflake ID of the last message as the `before` parameter — until an empty page signals the end of history.
+
+### Rate Limiting
+
+When Discord returns a `429 Too Many Requests` response, the backend parses the `retry_after` field from the JSON body and sleeps for exactly that duration before retrying the same request. A 500ms inter-page sleep is also applied proactively.
+
+### Abort / Cancellation
+
+Every download task receives a standard [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). The inner loop checks `signal.aborted` before each message and before each file download, so cancellation is clean and immediate.
+
+### File Safety
+
+Before writing any file, the engine checks `fs.existsSync(destPath)`. If the file already exists, it is skipped with a `↩ Already exists` log line, preventing duplicate downloads across multiple runs.
+
+---
+
+## Security Notes
+
+> ⚠️ **Your Discord token is sensitive.** Treat it like a password.
+
+- Your token is **never written to disk** by this tool.
+- It is held only in the in-memory TUI input field for the duration of the session.
+- It is transmitted exclusively to `discord.com` over HTTPS.
+- The token field displays characters as-entered (not masked) — run this tool in a private terminal session.
+
+**Do not share your token.** Account tokens grant full access to your Discord account. Bot tokens should be scoped to only the required permissions.
+
+---
+
+## Contributing
+
+Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change.
+
+```
+# Fork → clone your fork → create a branch
+git checkout -b feat/my-improvement
+
+# Make changes, then push
+git push origin feat/my-improvement
+
+# Open a PR on GitHub
+```
+
+---
+
+## License
+
+Released under the [MIT License](./LICENSE).  
+Developed & maintained with ♡ by **[@dilukshann7](https://github.com/dilukshann7)**
+
+---
+
+<div align="center">
+
+*Built with* ♡ *using* **TypeScript** · **Bun** · **OpenTUI** · **Zig**
+
+</div>

package/backend.ts

@@ -0,0 +1,428 @@
+import fs from "fs";
+import path from "path";
+import https from "https";
+import http from "http";
+import { URL } from "url";
+
+export interface DownloadConfig {
+  token: string;
+  channelId: string;
+  outputDir: string;
+  skipExtensions: string[]; // e.g. [".jpg", ".png"]
+  foldersPerMessage: boolean;
+}
+
+export interface DownloadProgress {
+  type:
+    | "log"
+    | "progress"
+    | "done"
+    | "error"
+    | "fetching"
+    | "rate_limit"
+    | "file_skip"
+    | "file_start"
+    | "file_done"
+    | "file_fail";
+  message: string;
+  totalMessages?: number;
+  messagesWithAttachments?: number;
+  filesDownloaded?: number;
+  filesTotal?: number;
+  currentFile?: string;
+  outputDir?: string;
+}
+
+export type ProgressCallback = (progress: DownloadProgress) => void;
+
+function sanitize(name: string, maxLen = 60): string {
+  const cleaned = name
+    .replace(/[\\/*?:"<>|]/g, "")
+    .trim()
+    .replace(/\n/g, " ");
+  return cleaned.slice(0, maxLen) || "untitled";
+}
+
+function parseSkipExtensions(raw: string): string[] {
+  return raw
+    .split(/[\s,]+/)
+    .map((e) => e.trim().toLowerCase())
+    .filter((e) => e.length > 0)
+    .map((e) => (e.startsWith(".") ? e : `.${e}`));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+interface HttpResponse {
+  statusCode: number;
+  body: string;
+  headers: Record<string, string | string[] | undefined>;
+}
+
+function httpGet(
+  urlStr: string,
+  headers: Record<string, string>,
+): Promise<HttpResponse> {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlStr);
+    const mod = parsed.protocol === "https:" ? https : http;
+
+    const req = mod.get(
+      {
+        hostname: parsed.hostname,
+        path: parsed.pathname + parsed.search,
+        headers,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("end", () =>
+          resolve({
+            statusCode: res.statusCode ?? 0,
+            body: Buffer.concat(chunks).toString("utf8"),
+            headers: res.headers as Record<
+              string,
+              string | string[] | undefined
+            >,
+          }),
+        );
+        res.on("error", reject);
+      },
+    );
+    req.on("error", reject);
+    req.setTimeout(30_000, () => {
+      req.destroy(new Error("Request timed out"));
+    });
+  });
+}
+
+function downloadBinaryFile(
+  urlStr: string,
+  destPath: string,
+  headers: Record<string, string>,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlStr);
+    const mod = parsed.protocol === "https:" ? https : http;
+
+    const req = mod.get(
+      {
+        hostname: parsed.hostname,
+        path: parsed.pathname + parsed.search,
+        headers,
+      },
+      (res) => {
+        if (res.statusCode !== 200) {
+          reject(new Error(`HTTP ${res.statusCode}`));
+          return;
+        }
+        const stream = fs.createWriteStream(destPath);
+        res.pipe(stream);
+        stream.on("finish", () => resolve());
+        stream.on("error", reject);
+      },
+    );
+    req.on("error", reject);
+    req.setTimeout(60_000, () => {
+      req.destroy(new Error("Download timed out"));
+    });
+  });
+}
+
+interface DiscordAttachment {
+  id: string;
+  filename: string;
+  size: number;
+  url: string;
+}
+
+interface DiscordMessage {
+  id: string;
+  timestamp: string;
+  content: string;
+  author: { username: string };
+  attachments: DiscordAttachment[];
+}
+
+async function fetchAllMessages(
+  channelId: string,
+  headers: Record<string, string>,
+  onProgress: ProgressCallback,
+): Promise<DiscordMessage[]> {
+  const messages: DiscordMessage[] = [];
+  let lastId: string | null = null;
+
+  onProgress({
+    type: "fetching",
+    message: "Fetching messages from Discord...",
+  });
+
+  while (true) {
+    let url = `https://discord.com/api/v10/channels/${channelId}/messages?limit=100`;
+    if (lastId) url += `&before=${lastId}`;
+
+    let resp: HttpResponse;
+    try {
+      resp = await httpGet(url, headers);
+    } catch (err) {
+      onProgress({
+        type: "error",
+        message: `Network error: ${(err as Error).message}`,
+      });
+      break;
+    }
+
+    if (resp.statusCode === 429) {
+      let retryAfter = 5;
+      try {
+        const json = JSON.parse(resp.body);
+        retryAfter = json.retry_after ?? 5;
+      } catch {}
+      onProgress({
+        type: "rate_limit",
+        message: `Rate limited — waiting ${retryAfter}s...`,
+      });
+      await sleep(retryAfter * 1000);
+      continue;
+    }
+
+    if (resp.statusCode === 401) {
+      onProgress({
+        type: "error",
+        message: "Invalid token (401 Unauthorized).",
+      });
+      break;
+    }
+
+    if (resp.statusCode === 403) {
+      onProgress({
+        type: "error",
+        message: "Missing access to channel (403 Forbidden).",
+      });
+      break;
+    }
+
+    if (resp.statusCode !== 200) {
+      onProgress({
+        type: "error",
+        message: `Discord API error ${resp.statusCode}: ${resp.body.slice(0, 120)}`,
+      });
+      break;
+    }
+
+    let batch: DiscordMessage[];
+    try {
+      batch = JSON.parse(resp.body);
+    } catch {
+      onProgress({
+        type: "error",
+        message: "Failed to parse Discord API response.",
+      });
+      break;
+    }
+
+    if (!batch.length) break;
+
+    messages.push(...batch);
+    lastId = batch[batch.length - 1]!.id;
+
+    onProgress({
+      type: "log",
+      message: `  Fetched ${messages.length} messages so far...`,
+      totalMessages: messages.length,
+    });
+
+    await sleep(500);
+  }
+
+  return messages;
+}
+
+export async function runDownload(
+  config: DownloadConfig,
+  onProgress: ProgressCallback,
+  signal?: AbortSignal,
+): Promise<void> {
+  const { token, channelId, outputDir, skipExtensions, foldersPerMessage } =
+    config;
+
+  // Validate
+  if (!token.trim()) {
+    onProgress({ type: "error", message: "✗ Discord token is required." });
+    return;
+  }
+  if (!channelId.trim()) {
+    onProgress({ type: "error", message: "✗ Channel ID is required." });
+    return;
+  }
+
+  const headers: Record<string, string> = { Authorization: token.trim() };
+
+  try {
+    fs.mkdirSync(outputDir, { recursive: true });
+  } catch (err) {
+    onProgress({
+      type: "error",
+      message: `✗ Cannot create output directory: ${(err as Error).message}`,
+    });
+    return;
+  }
+
+  const messages = await fetchAllMessages(channelId, headers, onProgress);
+
+  if (signal?.aborted) {
+    onProgress({ type: "log", message: "⊘ Download aborted." });
+    return;
+  }
+
+  const withAttachments = messages.filter((m) => m.attachments?.length > 0);
+
+  onProgress({
+    type: "log",
+    message: `\n  Found ${messages.length} messages total.`,
+    totalMessages: messages.length,
+  });
+  onProgress({
+    type: "log",
+    message: `  ${withAttachments.length} messages have attachments.`,
+    messagesWithAttachments: withAttachments.length,
+  });
+  onProgress({
+    type: "log",
+    message: "  ──────────────────────────────────────────",
+  });
+
+  if (withAttachments.length === 0) {
+    onProgress({
+      type: "done",
+      message: "✓ No attachments found.",
+      filesDownloaded: 0,
+      outputDir,
+    });
+    return;
+  }
+
+  let filesTotal = 0;
+  for (const msg of withAttachments) {
+    for (const att of msg.attachments) {
+      const ext = path.extname(att.filename).toLowerCase();
+      if (!skipExtensions.includes(ext)) filesTotal++;
+    }
+  }
+
+  onProgress({
+    type: "log",
+    message: `  ${filesTotal} file(s) to download (after skip filter).`,
+    filesTotal,
+  });
+  onProgress({
+    type: "log",
+    message: "  ──────────────────────────────────────────",
+  });
+
+  let downloaded = 0;
+  let skippedExt = 0;
+
+  for (const msg of withAttachments) {
+    if (signal?.aborted) {
+      onProgress({ type: "log", message: "⊘ Download aborted by user." });
+      break;
+    }
+
+    const ts = msg.timestamp.slice(0, 10); // "2025-10-31"
+    const author = sanitize(msg.author.username);
+    const snippet = sanitize(msg.content.slice(0, 40)) || "no-text";
+
+    let folderPath: string;
+
+    if (foldersPerMessage) {
+      const folderName = `${ts}_${author}_${snippet}`;
+      folderPath = path.join(outputDir, folderName);
+      onProgress({ type: "log", message: `\n  📁  ${folderName}` });
+    } else {
+      folderPath = outputDir;
+    }
+
+    try {
+      fs.mkdirSync(folderPath, { recursive: true });
+    } catch (err) {
+      onProgress({
+        type: "error",
+        message: `  ✗ Cannot create folder: ${(err as Error).message}`,
+      });
+      continue;
+    }
+
+    for (const att of msg.attachments) {
+      if (signal?.aborted) break;
+
+      const ext = path.extname(att.filename).toLowerCase();
+
+      if (skipExtensions.includes(ext)) {
+        skippedExt++;
+        onProgress({
+          type: "file_skip",
+          message: `    ↷ Skipped (${ext}): ${att.filename}`,
+          currentFile: att.filename,
+        });
+        continue;
+      }
+
+      const destPath = path.join(folderPath, att.filename);
+
+      if (fs.existsSync(destPath)) {
+        onProgress({
+          type: "file_skip",
+          message: `    ↩ Already exists: ${att.filename}`,
+          currentFile: att.filename,
+        });
+        continue;
+      }
+
+      const sizeKb = Math.round(att.size / 1024);
+      onProgress({
+        type: "file_start",
+        message: `    ↓ ${att.filename} (${sizeKb} KB)`,
+        currentFile: att.filename,
+      });
+
+      try {
+        await downloadBinaryFile(att.url, destPath, headers);
+        downloaded++;
+        onProgress({
+          type: "file_done",
+          message: `    ✓ Saved: ${att.filename}`,
+          currentFile: att.filename,
+          filesDownloaded: downloaded,
+          filesTotal,
+          progress: Math.round((downloaded / filesTotal) * 100),
+        } as DownloadProgress & { progress: number });
+      } catch (err) {
+        onProgress({
+          type: "file_fail",
+          message: `    ✗ Failed: ${att.filename} — ${(err as Error).message}`,
+          currentFile: att.filename,
+        });
+      }
+
+      await sleep(200);
+    }
+  }
+
+  const absPath = path.resolve(outputDir);
+  onProgress({
+    type: "log",
+    message: "  ──────────────────────────────────────────",
+  });
+  onProgress({
+    type: "done",
+    message: `  ✓ Done! Downloaded ${downloaded} file(s) → ${absPath}`,
+    filesDownloaded: downloaded,
+    filesTotal,
+    outputDir: absPath,
+  });
+}
+
+export { parseSkipExtensions };