burnbox 1.0.0__tar.gz

burnbox-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run mypy burnbox/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --python ${{ matrix.python-version }} --extra dev
+      - run: uv run pytest -q
+
+  publish:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

burnbox-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.so

burnbox-1.0.0/LICENSE

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

burnbox-1.0.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: burnbox
+Version: 1.0.0
+Summary: Temporary email that burns after reading
+Author: burnbox contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,disposable-email,otp,temp-mail,temporary-email
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: html2text
+Requires-Dist: httpx
+Requires-Dist: pyperclip
+Requires-Dist: rich
+Requires-Dist: tomli; python_version < '3.11'
+Requires-Dist: typer
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

burnbox-1.0.0/README.md

@@ -0,0 +1,240 @@
+# burnbox
+
+**Temporary email that burns after reading.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+burnbox creates a disposable email address, watches for incoming messages, auto-detects OTP codes, copies them to your clipboard — then burns the account when you're done.
+
+Requires Python >= 3.10.
+
+## Install
+
+```bash
+pip install burnbox
+```
+
+Or with [pipx](https://pypa.github.io/pipx/) (recommended for CLI tools):
+
+```bash
+pipx install burnbox
+```
+
+## How it works
+
+1. **Register** — burnbox creates a temporary email account
+2. **Poll** — watches for incoming messages every few seconds
+3. **Detect** — finds OTP codes, verification links, and copies them to clipboard
+4. **Burn** — deletes the account and session on exit (Ctrl+C)
+
+The `--keep` flag preserves the account for later use with `burnbox resume`.
+
+## Quick start
+
+```bash
+$ burnbox
+```
+
+That's it. You'll get a temp address, it auto-copies to clipboard, and burnbox watches for messages. When a verification code arrives, it's detected and copied. Press Ctrl+C to exit — the account is deleted automatically.
+
+```
+╭─────────── burnbox ───────────╮
+│ Temp email that burns after   │
+│ reading                       │
+╰───────────────────────────────╯
+
+  Provider: mailtm
+  Address:  k7x9m2@example.com
+  Address copied to clipboard
+
+  Ctrl+C to exit and burn · --keep to preserve · burnbox resume
+```
+
+## CLI usage
+
+| Command | Description |
+|---|---|
+| `burnbox` | Create temp email, watch for messages, burn on exit |
+| `burnbox address` | Generate a temp email address and exit (account is burned immediately) |
+| `burnbox resume` | Reconnect to the last saved session |
+
+### Options
+
+```
+--provider       Provider: mailtm, mailgw, 1secmail, guerrillamail
+--poll, -p       Polling interval in seconds (default: 5)
+--timeout, -t    HTTP request timeout (default: 10)
+--keep, -k       Keep account alive after exit
+--version, -v    Show version
+--help, -h       Show help
+```
+
+### Examples
+
+```bash
+# Use a specific provider
+burnbox --provider guerrillamail
+
+# Keep account alive for later resume
+burnbox --keep
+
+# Resume a kept session
+burnbox resume
+
+# One-shot: just get a temp address (burned immediately)
+burnbox address
+```
+
+## Programmatic API
+
+Use burnbox as a Python library:
+
+```python
+import asyncio
+import burnbox
+
+async def main():
+    box = await burnbox.create()
+    async with box:
+        print(f"Address: {box.address}")
+        msg = await box.wait_for_message(timeout=60)
+        if msg:
+            print(f"Code: {msg.best_code}")
+            print(f"From: {msg.sender}")
+        # Account auto-burns on exit
+
+asyncio.run(main())
+```
+
+### API reference
+
+- `burnbox.create(provider=None, config=None)` — Create a `BurnBox` instance (await it first, then use as context manager)
+- `box.address` — The temp email address
+- `box.fetch_new()` — Fetch new messages
+- `box.wait_for_message(timeout=60)` — Wait for the first message (returns `None` on timeout)
+- `box.messages()` — Async iterator yielding messages as they arrive
+- `box.burn()` — Delete the account manually
+- `msg.id`, `msg.sender`, `msg.subject` — Message metadata
+- `msg.content` — Message body as plain text
+- `msg.best_code` — Highest-confidence OTP code detected (string or `None`)
+- `msg.codes` — All detected codes as `CodeMatch` objects (`.value`, `.confidence`, `.kind`)
+- `msg.links` — All detected links
+
+## Configuration
+
+Config file: `~/.config/burnbox.toml`
+
+```toml
+[provider]
+default = "mailtm"             # Preferred provider
+custom_url = "https://..."     # Custom API URL for mailtm/mailgw
+
+[polling]
+interval = 5.0                 # Seconds between polls
+timeout = 10.0                  # HTTP timeout
+
+[output]
+copy_address = true             # Copy address to clipboard
+copy_code = true                # Copy OTP codes to clipboard
+notifications = true            # Desktop notifications on OTP
+```
+
+Environment variables override the config:
+
+```bash
+BURNBOX_PROVIDER=guerrillamail
+BURNBOX_POLL_INTERVAL=3
+BURNBOX_TIMEOUT=15
+BURNBOX_CUSTOM_URL=https://...
+```
+
+## Providers
+
+| Provider | Auth | Delete account | Domains | Custom URL |
+|---|---|---|---|---|
+| **mail.tm** | Register + token | Yes | Multiple | Yes |
+| **mail.gw** | Register + token | Yes | Multiple | Yes |
+| **1secmail** | None (stateless) | Auto-expire | Dynamic (via API) | No |
+| **guerrillamail** | Session-based | Yes | sharklasers.com, grr.la, etc | No |
+
+burnbox automatically selects the first available provider with a health check. If one is down, it falls back to the next.
+
+## OTP Detection
+
+burnbox detects verification codes from incoming emails using a multi-parser engine:
+
+- **Labeled OTP** — "code: 1234", "Your verification code: 8472", "Ваш код: 5531", etc.
+- **Alphanumeric codes** — Recovery codes, backup keys (e.g., `A1B2-C3D4-E5F6`)
+- **URL-embedded codes** — `?code=`, `?token=`, `?otp=` in links
+- **Reset/verify links** — Password reset, account verification URLs
+- **Numeric OTP** — Standalone digit clusters with context-aware confidence boosting
+
+Supports 12 languages for label detection: English, Russian, German, French, Spanish, Portuguese, Chinese, Japanese, Korean, Hindi, Arabic, Turkish. Context-aware confidence boosting is available for English and Russian; other languages use label-matching only.
+
+Each match has a **confidence score** (0–1). The highest-confidence code is auto-copied to your clipboard.
+
+## Plugin system
+
+Add custom providers via Python entry points:
+
+```python
+# my_provider.py
+from burnbox.providers.base import Provider
+from burnbox.models import Session, InboxMessage
+
+class MyProvider:
+    name = "myprovider"
+    supports_custom_url = False
+
+    async def is_alive(self) -> bool:
+        # Check if the provider API is reachable
+
+    async def register(self) -> Session:
+        # Create a new temp email account, return Session
+
+    async def restore(self, session: Session) -> None:
+        # Restore auth state from a saved session
+
+    async def fetch_messages(self, seen_ids: set[str]) -> list[InboxMessage]:
+        # Fetch new (unseen) messages
+
+    async def delete_account(self, account_id: str) -> bool:
+        # Delete the account, return True on success
+
+    async def aclose(self) -> None:
+        # Close the HTTP client
+```
+
+```toml
+# pyproject.toml
+[project.entry-points."burnbox.providers"]
+myprovider = "my_provider:MyProvider"
+```
+
+After `pip install`, burnbox discovers your provider automatically.
+
+## Security considerations
+
+- OTP codes transit through third-party email providers. Only use burnbox for non-sensitive verifications.
+- Session files are stored with 0600 permissions at `~/.config/burnbox/session.json`.
+- Accounts are deleted ("burned") on exit by default. Use `--keep` only if you need persistence.
+
+## Troubleshooting
+
+- **Clipboard not working on Linux**: Install `xclip` or `xsel` (X11) or `wl-clipboard` (Wayland).
+- **All providers down**: burnbox falls back to trying providers even if health checks fail. Check your network.
+- **"Session expired" on resume**: The temp email account has expired. Start a new one with `burnbox`.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run mypy burnbox/
+uv run pytest
+```
+
+## License
+
+MIT

burnbox-1.0.0/burnbox/__init__.py

@@ -0,0 +1,34 @@
+from burnbox.api import BurnBox, Message, create
+from burnbox.client import BurnBoxClient
+from burnbox.config import AppConfig, load_config
+from burnbox.exceptions import (
+    APIError,
+    AuthExpiredError,
+    BurnBoxError,
+    NoDomainsError,
+    ProviderError,
+    SessionError,
+    TokenError,
+)
+from burnbox.models import InboxMessage, MessagePreview, Session
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "BurnBox",
+    "BurnBoxClient",
+    "Message",
+    "AppConfig",
+    "load_config",
+    "create",
+    "BurnBoxError",
+    "Session",
+    "InboxMessage",
+    "MessagePreview",
+    "APIError",
+    "NoDomainsError",
+    "ProviderError",
+    "SessionError",
+    "TokenError",
+    "AuthExpiredError",
+]

burnbox-1.0.0/burnbox/__main__.py

@@ -0,0 +1,4 @@
+from burnbox.cli import app
+
+if __name__ == "__main__":
+    app()

burnbox-1.0.0/burnbox/api.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from typing import AsyncIterator
+
+from burnbox.client import BurnBoxClient
+from burnbox.config import AppConfig, load_config
+from burnbox.detectors.base import CodeMatch, MessageContext
+from burnbox.detectors.engine import ParserEngine
+from burnbox.exceptions import AuthExpiredError, BurnBoxError
+from burnbox.models import InboxMessage, Session
+from burnbox.providers.base import Provider
+from burnbox.providers.registry import select_provider
+from burnbox.providers.utils import build_registry
+from burnbox.session import SessionStore
+
+
+async def _select(config: AppConfig) -> Provider:
+    registry = build_registry(config.custom_url)
+    all_providers = registry.all()
+    provider = await select_provider(all_providers, preferred=config.provider_default)
+    if not provider:
+        for p in all_providers:
+            try:
+                await p.aclose()
+            except Exception:
+                pass
+        raise RuntimeError("No available providers. Check your network.")
+    for p in all_providers:
+        if p is not provider:
+            try:
+                await p.aclose()
+            except Exception:
+                pass
+    return provider
+
+
+class Message:
+    def __init__(self, inner: InboxMessage, engine: ParserEngine) -> None:
+        self._inner = inner
+        self._engine = engine
+        self._codes: list[CodeMatch] | None = None
+
+    @property
+    def id(self) -> str:
+        return self._inner.id
+
+    @property
+    def sender(self) -> str:
+        return self._inner.sender
+
+    @property
+    def subject(self) -> str:
+        return self._inner.subject
+
+    @property
+    def content(self) -> str:
+        return self._inner.content
+
+    @property
+    def codes(self) -> list[CodeMatch]:
+        if self._codes is None:
+            ctx = MessageContext(sender=self.sender, subject=self.subject)
+            self._codes = self._engine.parse(self.content, ctx)
+        return self._codes
+
+    @property
+    def best_code(self) -> str | None:
+        best = self._engine.best_code(self.codes)
+        return best.value if best else None
+
+    @property
+    def links(self) -> list[str]:
+        return self._engine.detect_links(self.content)
+
+
+class BurnBox:
+    """High-level async interface for temporary email.
+
+    Usage::
+
+        async with burnbox.create() as box:
+            print(box.address)
+            msg = await box.wait_for_message(timeout=60)
+            if msg:
+                print(msg.best_code)
+    """
+
+    def __init__(
+        self,
+        provider: Provider,
+        client: BurnBoxClient,
+        config: AppConfig,
+        engine: ParserEngine | None = None,
+    ) -> None:
+        self._provider = provider
+        self._client = client
+        self._config = config
+        self._engine = engine or ParserEngine()
+        self._seen_ids: set[str] = set()
+
+    @property
+    def address(self) -> str | None:
+        s = self._client.session
+        return s.address if s else None
+
+    @property
+    def session(self) -> Session | None:
+        return self._client.session
+
+    async def fetch_new(self) -> list[Message]:
+        raw = await self._client.fetch_new(self._seen_ids)
+        messages = [Message(m, self._engine) for m in raw]
+        for m in raw:
+            self._seen_ids.add(m.id)
+        return messages
+
+    async def wait_for_message(self, timeout: float = 60.0) -> Message | None:
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while True:
+            messages = await self.fetch_new()
+            if messages:
+                return messages[0]
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                return None
+            await asyncio.sleep(min(self._config.poll_interval, remaining))
+
+    _MAX_CONSECUTIVE_ERRORS = 5
+
+    async def messages(self, poll_interval: float | None = None) -> AsyncIterator[Message]:
+        interval = poll_interval or self._config.poll_interval
+        consecutive_errors = 0
+        while True:
+            try:
+                new = await self.fetch_new()
+                consecutive_errors = 0
+                for m in new:
+                    yield m
+            except (AuthExpiredError, BurnBoxError):
+                raise
+            except Exception as exc:
+                consecutive_errors += 1
+                if consecutive_errors >= self._MAX_CONSECUTIVE_ERRORS:
+                    raise BurnBoxError(
+                        f"Too many consecutive errors ({consecutive_errors}). Last: {exc}"
+                    ) from exc
+            await asyncio.sleep(interval)
+
+    async def burn(self) -> bool:
+        return await self._client.burn()
+
+    async def __aenter__(self) -> BurnBox:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        try:
+            await self.burn()
+        except Exception:
+            pass
+        try:
+            await self._provider.aclose()
+        except Exception:
+            pass
+
+
+async def create(
+    provider: str | None = None,
+    config: AppConfig | None = None,
+) -> BurnBox:
+    cfg = config or load_config()
+    if provider:
+        cfg = replace(cfg, provider_default=provider)
+
+    prov = await _select(cfg)
+    store = SessionStore()
+    client = BurnBoxClient(provider=prov, session_store=store, config=cfg)
+    await client.register()
+    return BurnBox(provider=prov, client=client, config=cfg)