tmail-cli 0.1.0__tar.gz

tmail_cli-0.1.0/.gitattributes

@@ -0,0 +1,18 @@
+# Auto-detect text files
+* text=auto
+
+# Python source
+*.py text diff=python
+
+# Markdown
+*.md text
+
+# JSON
+*.json text
+
+# Config
+*.txt text
+*.cfg text
+*.ini text
+*.yml text
+*.yaml text

tmail_cli-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Runtime data
+.tmail_data/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.venv/
+venv/
+env/
+
+# Agent / plan files
+AGENTS.md
+PLAN.md
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store

tmail_cli-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,54 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders of the tmail community pledge to
+make participation in our project a harassment-free experience for everyone,
+regardless of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer. All complaints will be reviewed and
+investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

tmail_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for your interest in contributing to tmail.
+
+## Getting started
+
+```bash
+git clone https://github.com/rkriad585/tmail.git
+cd tmail
+pip install uv
+uv sync
+tmail
+```
+
+## Development
+
+See the [Development Guide](docs/development.md) for architecture, code
+examples, and guidance on adding features.
+
+## Guidelines
+
+- Follow the existing code style in the module you're editing.
+- No test framework is configured yet — test manually with `uv run tmail`.
+- Update docs if adding or changing user-facing features.
+
+## Pull requests
+
+- Open an issue first to discuss significant changes.
+- Keep PRs focused on a single concern.

tmail_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rkriad585
+
+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.

tmail_cli-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: tmail-cli
+Version: 0.1.0
+Summary: CLI tool for generating temporary email addresses and viewing inboxes
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pyfiglet
+Requires-Dist: pyperclip
+Requires-Dist: requests
+Requires-Dist: rich
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://img.shields.io/badge/tmail-v0.1.0-blue" alt="version">
+  <img src="https://img.shields.io/badge/python-%3E%3D3.10-green" alt="python">
+  <img src="https://img.shields.io/badge/license-MIT-yellow" alt="license">
+</p>
+
+<h1 align="center">📧 tmail</h1>
+<p align="center"><em>Disposable email addresses, right from your terminal.</em></p>
+
+---
+
+tmail is a lightweight CLI tool that generates temporary email addresses
+and live-polls their inbox. Built with Python and [Rich](https://github.com/Textualize/rich).
+
+## Quick start
+
+```bash
+pip install uv
+uv tool install tmail
+tmail           # interactive TUI
+```
+
+## CLI flags
+
+| Command | Description |
+|---|---|
+| `tmail` | Open the interactive TUI menu |
+| `tmail -g` | Generate a new email, print it, copy to clipboard |
+| `tmail -g -w` | Generate and immediately watch the new inbox |
+| `tmail -g -i` | Generate and fetch inbox once (one-shot) |
+| `tmail -l` | List saved emails with unread counts |
+| `tmail -i <email>` | Fetch inbox once (plain text, good for scripts) |
+| `tmail -w <email>` | Live-poll inbox (plain text, Ctrl+C to stop) |
+| `tmail -d <email>` | Delete an email from history |
+| `tmail -n <seconds>` | Set poll interval |
+| `tmail -c` | Clear all stored data |
+| `tmail -V` | Show version |
+| `tmail -h` | Show help |
+
+## Documentation
+
+| Doc | What's inside |
+|---|---|
+| [User Guide](docs/guide.md) | Full feature walkthrough, menu reference, settings, clipboard, attachments |
+| [Development Guide](docs/development.md) | Architecture, module breakdown, code examples, adding features |
+
+## Data
+
+All data is stored in `.tmail_data/` as JSON files — no database required.
+
+## License
+
+MIT

tmail_cli-0.1.0/README.md

@@ -0,0 +1,53 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/tmail-v0.1.0-blue" alt="version">
+  <img src="https://img.shields.io/badge/python-%3E%3D3.10-green" alt="python">
+  <img src="https://img.shields.io/badge/license-MIT-yellow" alt="license">
+</p>
+
+<h1 align="center">📧 tmail</h1>
+<p align="center"><em>Disposable email addresses, right from your terminal.</em></p>
+
+---
+
+tmail is a lightweight CLI tool that generates temporary email addresses
+and live-polls their inbox. Built with Python and [Rich](https://github.com/Textualize/rich).
+
+## Quick start
+
+```bash
+pip install uv
+uv tool install tmail
+tmail           # interactive TUI
+```
+
+## CLI flags
+
+| Command | Description |
+|---|---|
+| `tmail` | Open the interactive TUI menu |
+| `tmail -g` | Generate a new email, print it, copy to clipboard |
+| `tmail -g -w` | Generate and immediately watch the new inbox |
+| `tmail -g -i` | Generate and fetch inbox once (one-shot) |
+| `tmail -l` | List saved emails with unread counts |
+| `tmail -i <email>` | Fetch inbox once (plain text, good for scripts) |
+| `tmail -w <email>` | Live-poll inbox (plain text, Ctrl+C to stop) |
+| `tmail -d <email>` | Delete an email from history |
+| `tmail -n <seconds>` | Set poll interval |
+| `tmail -c` | Clear all stored data |
+| `tmail -V` | Show version |
+| `tmail -h` | Show help |
+
+## Documentation
+
+| Doc | What's inside |
+|---|---|
+| [User Guide](docs/guide.md) | Full feature walkthrough, menu reference, settings, clipboard, attachments |
+| [Development Guide](docs/development.md) | Architecture, module breakdown, code examples, adding features |
+
+## Data
+
+All data is stored in `.tmail_data/` as JSON files — no database required.
+
+## License
+
+MIT

tmail_cli-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# tmail Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in tmail, please open an issue on
+GitHub or contact the maintainer directly. Do not disclose it publicly until
+it has been addressed.

tmail_cli-0.1.0/docs/development.md

@@ -0,0 +1,208 @@
+# tmail Development Guide
+
+## Project structure
+
+```
+src/tmail/
+├── __init__.py       # Package marker (empty)
+├── __main__.py       # python -m tmail support
+├── api.py            # HTTP client for temp-mail.io
+├── cli.py            # Entry point, menu loop, orchestration
+├── storage.py        # JSON file persistence
+└── ui.py             # Rich TUI components
+tests/
+└── __init__.py
+```
+
+## Module responsibilities
+
+### api.py — HTTP client
+
+Pure functions that call the temp-mail.io API. No UI, no state.
+
+```python
+from tmail.api import get_random_email, fetch_messages, download_attachment
+
+email = get_random_email()
+messages = fetch_messages(email)
+download_attachment("att_id", Path("/tmp/file.pdf"))
+```
+
+Endpoints:
+
+| Function | Method | Endpoint |
+|---|---|---|
+| `get_random_email()` | POST | `/api/v3/email/new` |
+| `fetch_messages(email)` | GET | `/api/v3/email/{email}/messages` |
+| `get_attachment_url(id)` | — | returns URL string |
+| `download_attachment(id, path)` | GET (stream) | `/api/v3/attachment/{id}?download=1` |
+
+### storage.py — persistence
+
+Read/write JSON files in `.tmail_data/`. Every function is self-contained
+(calls `DATA_DIR.mkdir` when needed).
+
+```python
+from tmail.storage import save_email, get_old_emails, delete_email
+
+save_email("foo@example.com")
+emails = get_old_emails()
+deleted = delete_email("foo@example.com")
+```
+
+Config:
+
+```python
+from tmail.storage import load_config, save_config
+
+cfg = load_config()           # {"poll_interval": 5}
+save_config({"poll_interval": 3})
+```
+
+Unread tracking:
+
+```python
+from tmail.storage import save_unread_count, get_unread_counts, clear_unread_count
+
+save_unread_count("foo@example.com", 3)
+counts = get_unread_counts()          # {"foo@example.com": 3}
+clear_unread_count("foo@example.com")
+```
+
+### ui.py — rendering
+
+Thin wrappers around Rich that format output. No logic, no API calls.
+
+```python
+from tmail.ui import console, show_logo, show_success, show_error, build_inbox_table
+
+show_logo()
+show_success("Email created")
+table, has_new, count = build_inbox_table(messages, seen_ids, get_attachment_url)
+```
+
+Key components:
+
+- `show_logo()` — pyfiglet banner + welcome panel
+- `build_inbox_table()` — returns `(Table, has_new, new_count)`
+- `show_full_message(msg)` — Panel with full body text
+- `show_messages_selection(messages)` — indexed table for picking a message
+- `get_email_actions_panel(email)` — returns the action submenu Panel
+- `get_main_menu_panel()` — returns the main menu Panel
+- `get_settings_panel(interval)` — returns the settings Panel
+
+### cli.py — orchestration
+
+Wires api/storage/ui together. Contains the main loop, inbox poller, all
+submenus, and CLI flag handling via `argparse`. This is the entry point
+(`tmail.cli:main`).
+
+```python
+from tmail.cli import main
+
+main()  # parses sys.argv, dispatches flags or starts TUI
+```
+
+Flow:
+
+```
+main() → argparse → --generate / --list / --inbox / --watch / ...
+                 ↘ main_menu() → email actions → display_inbox()
+                              ↘ settings_menu()
+                              ↘ delete_email_saved()
+```
+
+CLI flags are defined in `main()` using `argparse.ArgumentParser`. Each
+flag calls the same core functions from api/storage/ui but uses plain
+`print()` instead of Rich widgets so output works in pipes and scripts.
+
+Non-interactive helpers:
+
+| Function | Used by |
+|---|---|
+| `_print_messages_plain(messages)` | `--inbox`, `--watch` |
+| `_copy_silent(text)` | `--generate` |
+| (inline handlers) | `--list`, `--delete`, `--interval`, `--clear`, `--version` |
+
+## Adding a new menu option
+
+1. Add the label to `get_main_menu_panel()` in `ui.py`
+2. Add a handler function in `cli.py`
+3. Wire the choice in `main_menu()` switch
+
+Example — adding a "Show Version" option:
+
+```python
+# ui.py — add to panel
+"[5] Show Version\n"
+"[6] Remove All Old Mail's Data\n"
+"[7] Settings\n"
+"[8] Exit",
+
+# cli.py — add handler
+def show_version():
+    console.print("[bold]tmail v0.1.0[/bold]")
+    wait_for_enter()
+
+# cli.py — wire in main_menu
+elif choice == "5":
+    show_version()
+```
+
+## Adding a new email action
+
+1. Add the label to `get_email_actions_panel()` in `ui.py`
+2. Add a handler in `cli.py`
+3. Wire the choice in `email_actions_menu()`
+
+## Testing
+
+No test framework is configured. To test manually:
+
+```bash
+uv run tmail
+```
+
+Or import and call individual modules:
+
+```bash
+uv run python -c "
+from tmail.api import get_random_email
+print(get_random_email())
+"
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `requests` | HTTP client for temp-mail.io API |
+| `rich` | Terminal UI (tables, panels, live view, prompts) |
+| `pyfiglet` | ASCII art banner |
+| `pyperclip` | Clipboard copy (cross-platform) |
+
+## Data format reference
+
+### old_mails.json
+
+```json
+["abc@tempmail.com", "def@tempmail.com"]
+```
+
+### seen_mails.json
+
+```json
+["msg-uuid-1", "msg-uuid-2"]
+```
+
+### config.json
+
+```json
+{"poll_interval": 5}
+```
+
+### unread.json
+
+```json
+{"abc@tempmail.com": 3}
+```

tmail_cli-0.1.0/docs/guide.md

@@ -0,0 +1,169 @@
+# tmail User Guide
+
+## Installation
+
+```bash
+pip install uv
+uv tool install tmail
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/rkriad585/tmail.git
+cd tmail
+pip install uv
+uv sync
+```
+
+## Quick start
+
+```bash
+tmail           # interactive TUI
+tmail -g        # generate email, print, copy to clipboard
+tmail -i foo@example.com   # one-shot inbox check
+```
+
+Press **1** from the TUI to generate a new random email and watch mail
+arrive in real time. Press **Ctrl+C** to return to the email action menu.
+
+## CLI flags
+
+tmail supports non-interative flags for scripting and quick operations:
+
+| Command | Description |
+|---|---|
+| `tmail -g` | Generate a new email, print it, copy to clipboard, exit |
+| `tmail -g -w` | Generate and immediately watch the inbox (plain text) |
+| `tmail -g -i` | Generate and fetch inbox once (one-shot) |
+| `tmail -l` | List all saved emails with unread counts, exit |
+| `tmail -i EMAIL` | Fetch inbox once, print messages as plain text, exit |
+| `tmail -w EMAIL` | Live-poll inbox in plain-text mode, Ctrl+C to stop |
+| `tmail -d EMAIL` | Delete a specific email from history, exit |
+| `tmail -n SECONDS` | Set the poll interval in seconds, exit |
+| `tmail -c` | Clear all stored data, exit |
+| `tmail -V` | Show version and exit |
+| `tmail -h` | Show help message and exit |
+
+The `-i` and `-w` flags accept an optional EMAIL argument. When used
+without an argument together with `-g`, they use the newly generated
+address automatically.
+
+### --inbox example
+
+```bash
+tmail -i abc123@tempmail.com
+```
+
+Output:
+```
+--- Message 1 ---
+From:    sender@example.com
+To:      abc123@tempmail.com
+Subject: Welcome!
+Body:    Thank you for signing up...
+```
+
+### --watch example
+
+```bash
+tmail -w abc123@tempmail.com
+Watching abc123@tempmail.com (poll every 5s, Ctrl+C to stop)...
+```
+
+New messages are printed as they arrive. Useful for tail-like monitoring
+without the Rich TUI.
+
+## Main menu
+
+```
+╭───────────────────────────── Choose Your Option ─────────────────────────────╮
+│ [1] Generate Random Mail                                                     │
+│ [2] See Mails You Created                                                    │
+│ [3] Log In To Old Mails                                                      │
+│ [4] Delete Email From History                                                │
+│ [5] Remove All Old Mail's Data                                               │
+│ [6] Settings                                                                 │
+│ [7] Exit                                                                     │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+| Option | Description |
+|---|---|
+| **1** | Generate a new disposable email address and open its inbox |
+| **2** | List every address you have generated (shows unread counts) |
+| **3** | Re-open the inbox of a previously created address |
+| **4** | Select and delete a specific email from history |
+| **5** | Wipe all stored data (history, seen IDs, config, unread counts) |
+| **6** | Change the inbox polling interval |
+| **7** | Exit |
+
+## Email action submenu
+
+After exiting an inbox (Ctrl+C), you return to this submenu:
+
+```
+╭───────────────────────────── Email: xxxxx@xxxxx.xx ──────────────────────────╮
+│ [1] View Inbox (live)                                                        │
+│ [2] View Full Message                                                        │
+│ [3] Download Attachments                                                     │
+│ [4] Copy Email Address                                                       │
+│ [5] Delete This Email                                                        │
+│ [6] Back to Main Menu                                                        │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+| Option | Description |
+|---|---|
+| **1** | Re-enter the live inbox poller |
+| **2** | List messages by index, pick one to read the full body |
+| **3** | List messages with attachments, pick one to download all files |
+| **4** | Copy the email address to your clipboard |
+| **5** | Remove this email from history |
+| **6** | Return to the main menu |
+
+## Inbox polling
+
+The inbox refreshes every N seconds (default 5). Only new messages trigger a
+screen update — the terminal stays quiet between polls. Configure the interval
+in **Settings** (option 6).
+
+## Settings
+
+```
+╭────────────────────────────────── Settings ──────────────────────────────────╮
+│ Poll interval: 5s                                                            │
+│                                                                              │
+│ [1] Change Poll Interval                                                     │
+│ [2] Back to Main Menu                                                        │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+Choose **1** to enter a new interval in seconds (minimum 1).
+
+## Clipboard
+
+Option **4** in the email action submenu copies the email address to your
+clipboard. On Linux, one of these must be installed:
+
+- **X11:** `sudo apt install xclip` or `xsel`
+- **Wayland:** `sudo apt install wl-clipboard`
+
+Windows and macOS work out of the box.
+
+## Attachments
+
+Option **3** in the email action submenu lists messages that have attachments.
+Pick one and all its files are downloaded to `.tmail_data/attachments/<email>/`.
+
+## Data files
+
+All data is stored in `.tmail_data/`:
+
+| File | Purpose |
+|---|---|
+| `old_mails.json` | List of generated email addresses |
+| `seen_mails.json` | IDs of messages already displayed |
+| `config.json` | User settings (poll interval) |
+| `unread.json` | Per-email unread message counts |
+| `attachments/` | Downloaded attachment files |

tmail_cli-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "tmail-cli"
+version = "0.1.0"
+description = "CLI tool for generating temporary email addresses and viewing inboxes"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "requests",
+    "rich",
+    "pyfiglet",
+    "pyperclip",
+]
+
+[project.scripts]
+tmail = "tmail.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tmail"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

tmail_cli-0.1.0/requirements.txt

@@ -0,0 +1 @@
+.

tmail_cli-0.1.0/src/tmail/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()