otpilot 2.0.0__tar.gz

otpilot-2.0.0/LICENSE

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

otpilot-2.0.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: otpilot
+Version: 2.0.0
+Summary: Background CLI utility that copies OTPs from Gmail to clipboard on hotkey trigger
+Author: Jenil
+Author-email: Jenil <mail2jenil.pokar19@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 OTPilot 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.
+        
+Project-URL: Homepage, https://github.com/CodeWithJenil/otpilot
+Project-URL: Documentation, https://github.com/CodeWithJenil/otpilot/tree/main/docs
+Project-URL: Repository, https://github.com/CodeWithJenil/otpilot
+Project-URL: Issues, https://github.com/CodeWithJenil/otpilot/issues
+Keywords: otp,gmail,clipboard,hotkey,automation,2fa
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-api-python-client>=2.100.0
+Requires-Dist: google-auth-oauthlib>=1.1.0
+Requires-Dist: google-auth>=2.23.0
+Requires-Dist: pynput>=1.7.6
+Requires-Dist: pystray>=0.19.5
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: plyer>=2.1.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+![OTPilot Demo](assets/demo.gif)
+
+# OTPilot
+
+> Press a hotkey. Your OTP is already copied.
+```bash
+pip install otpilot
+```
+
+---
+
+<p align="center">
+  <strong>✈ OTPilot v2.0</strong>
+</p>
+
+<p align="center">
+  <em>The new era of private OTP fetching. Background utility that copies OTPs from Gmail to your clipboard with a single hotkey.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/codewithjenil/otpilot">GitHub</a> •
+  <a href="#installation">Install</a> •
+  <a href="#quickstart">Quickstart</a> •
+  <a href="SETUP.md">OAuth Setup</a> •
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+---
+
+## How It Works
+
+1. **OTPilot sits silently in your system tray** — no windows, no polling, zero CPU usage.
+2. **Press your hotkey** (e.g. `Ctrl+Shift+O`) — OTPilot fetches your last 10 emails from Gmail and extracts the OTP.
+3. **OTP is copied to your clipboard** — just paste it. A desktop notification confirms the action.
+
+## Installation
+
+```bash
+pip install otpilot
+```
+
+### Requirements
+
+- **Python 3.8+**
+- **Gmail account**
+- **Google Cloud project** with Gmail API enabled (free — [setup guide](SETUP.md))
+- **OS**: macOS, Windows, or Linux
+
+> **Linux users**: Make sure `xclip` or `xsel` is installed for clipboard support.
+> ```bash
+> sudo apt install xclip  # Debian/Ubuntu
+> ```
+
+## Quickstart
+
+### 1. Get Your Credentials
+
+Follow the steps above (or the [full guide](SETUP.md)) to download your `credentials.json` file.
+
+### 2. Run Setup
+
+```bash
+otpilot setup
+```
+
+The wizard will:
+- Ask for the path to your `credentials.json` file
+- Open your browser for Google sign-in (one-time authorization)
+- Let you set your preferred hotkey
+- Save your configuration
+
+### 3. Start OTPilot
+
+```bash
+otpilot start
+```
+
+OTPilot runs in the background with a system tray icon. Press your hotkey whenever you need an OTP.
+
+### 4. Daily Use
+
+1. Receive an OTP email in Gmail
+2. Press your hotkey (default: `Ctrl+Shift+O`)
+3. Paste the OTP — done!
+
+## Getting Your credentials.json
+
+Before using OTPilot, you need to download a `credentials.json` file from Google Cloud Console. This is a one-time, ~5 minute process.
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Create a new project (or use an existing one)
+3. Enable the **Gmail API**
+4. Go to **APIs & Services → Credentials**
+5. Create an **OAuth 2.0 Client ID** (Application type: **Desktop app**)
+6. Click **Download JSON** to save the `credentials.json` file
+
+> **Your credentials never leave your machine.** The file is stored locally at `~/.otpilot/credentials.json`.
+
+For detailed, step-by-step instructions with screenshots, see [**SETUP.md**](SETUP.md).
+
+## CLI Commands
+
+| Command            | Description                              |
+| ------------------ | ---------------------------------------- |
+| `otpilot setup`    | Run or re-run the interactive setup      |
+| `otpilot start`    | Start the background service             |
+| `otpilot status`   | Show auth state, hotkey, and config path |
+| `otpilot version`  | Print the version number                 |
+
+## Configuration
+
+OTPilot stores its configuration at `~/.otpilot/config.json`:
+
+```json
+{
+  "hotkey": "ctrl+shift+o",
+  "notify_on_copy": true,
+  "otp_max_age_minutes": 10,
+  "email_fetch_count": 10
+}
+```
+
+| Field                 | Type   | Default          | Description                                    |
+| --------------------- | ------ | ---------------- | ---------------------------------------------- |
+| `hotkey`              | string | `ctrl+shift+o`   | Global hotkey combination                      |
+| `notify_on_copy`      | bool   | `true`           | Show desktop notification when OTP is copied   |
+| `otp_max_age_minutes` | int    | `10`             | Ignore emails older than this (minutes)        |
+| `email_fetch_count`   | int    | `10`             | Number of recent emails to scan                |
+
+### Files Stored Locally
+
+| File                             | Purpose                              |
+| -------------------------------- | ------------------------------------ |
+| `~/.otpilot/config.json`        | Your hotkey and settings             |
+| `~/.otpilot/credentials.json`   | Your Google OAuth credentials        |
+| `~/.otpilot/token.json`         | OAuth session token (auto-generated) |
+
+## Platform Support
+
+| Platform | Status | Notes                                  |
+| -------- | ------ | -------------------------------------- |
+| macOS    | ✅     | Full support                           |
+| Windows  | ✅     | Full support                           |
+| Linux    | ✅     | Requires `xclip`/`xsel` for clipboard  |
+
+## How OTP Extraction Works
+
+OTPilot scans the subject line and body of your recent emails for:
+
+- **4–8 digit standalone numbers** near context words like *OTP*, *code*, *verify*, *verification*, *one-time*, *passcode*, *authentication*
+- Only emails within the configured time window are considered
+- If multiple OTPs are found, the most recent one wins
+
+## Security & Privacy
+
+- **Your credentials stay local**: `credentials.json` is stored on your machine at `~/.otpilot/` and is never uploaded anywhere.
+- **Read-only access**: OTPilot only reads your emails — it cannot send, delete, or modify anything.
+- **Local storage only**: Your OAuth token is stored locally at `~/.otpilot/token.json`. Nothing is sent to any third-party server.
+- **On-demand only**: Emails are fetched only when you press the hotkey. There is no background polling.
+
+## Troubleshooting
+
+| Issue                             | Solution                                                       |
+| --------------------------------- | -------------------------------------------------------------- |
+| "credentials.json not found"      | Run `otpilot setup` and provide your credentials file          |
+| "Invalid credentials file"        | Re-download credentials.json from Google Cloud Console         |
+| "Not authenticated" error         | Run `otpilot setup` to re-authenticate                         |
+| No OTP found                      | Check `otp_max_age_minutes` — the email might be too old       |
+| Clipboard not working (Linux)     | Install `xclip`: `sudo apt install xclip`                      |
+| Hotkey not working                | Run `otpilot setup` to reconfigure the hotkey                  |
+| Tray icon not visible             | Check your system tray / menu bar settings                     |
+
+## Contributing
+
+Contributions are welcome! See [**CONTRIBUTING.md**](CONTRIBUTING.md) for guidelines on setting up the development environment, running tests, and submitting pull requests.
+
+## License
+
+[MIT](../LICENSE) — use it freely.

otpilot-2.0.0/docs/README.md

@@ -0,0 +1,179 @@
+![OTPilot Demo](assets/demo.gif)
+
+# OTPilot
+
+> Press a hotkey. Your OTP is already copied.
+```bash
+pip install otpilot
+```
+
+---
+
+<p align="center">
+  <strong>✈ OTPilot v2.0</strong>
+</p>
+
+<p align="center">
+  <em>The new era of private OTP fetching. Background utility that copies OTPs from Gmail to your clipboard with a single hotkey.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/codewithjenil/otpilot">GitHub</a> •
+  <a href="#installation">Install</a> •
+  <a href="#quickstart">Quickstart</a> •
+  <a href="SETUP.md">OAuth Setup</a> •
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+---
+
+## How It Works
+
+1. **OTPilot sits silently in your system tray** — no windows, no polling, zero CPU usage.
+2. **Press your hotkey** (e.g. `Ctrl+Shift+O`) — OTPilot fetches your last 10 emails from Gmail and extracts the OTP.
+3. **OTP is copied to your clipboard** — just paste it. A desktop notification confirms the action.
+
+## Installation
+
+```bash
+pip install otpilot
+```
+
+### Requirements
+
+- **Python 3.8+**
+- **Gmail account**
+- **Google Cloud project** with Gmail API enabled (free — [setup guide](SETUP.md))
+- **OS**: macOS, Windows, or Linux
+
+> **Linux users**: Make sure `xclip` or `xsel` is installed for clipboard support.
+> ```bash
+> sudo apt install xclip  # Debian/Ubuntu
+> ```
+
+## Quickstart
+
+### 1. Get Your Credentials
+
+Follow the steps above (or the [full guide](SETUP.md)) to download your `credentials.json` file.
+
+### 2. Run Setup
+
+```bash
+otpilot setup
+```
+
+The wizard will:
+- Ask for the path to your `credentials.json` file
+- Open your browser for Google sign-in (one-time authorization)
+- Let you set your preferred hotkey
+- Save your configuration
+
+### 3. Start OTPilot
+
+```bash
+otpilot start
+```
+
+OTPilot runs in the background with a system tray icon. Press your hotkey whenever you need an OTP.
+
+### 4. Daily Use
+
+1. Receive an OTP email in Gmail
+2. Press your hotkey (default: `Ctrl+Shift+O`)
+3. Paste the OTP — done!
+
+## Getting Your credentials.json
+
+Before using OTPilot, you need to download a `credentials.json` file from Google Cloud Console. This is a one-time, ~5 minute process.
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Create a new project (or use an existing one)
+3. Enable the **Gmail API**
+4. Go to **APIs & Services → Credentials**
+5. Create an **OAuth 2.0 Client ID** (Application type: **Desktop app**)
+6. Click **Download JSON** to save the `credentials.json` file
+
+> **Your credentials never leave your machine.** The file is stored locally at `~/.otpilot/credentials.json`.
+
+For detailed, step-by-step instructions with screenshots, see [**SETUP.md**](SETUP.md).
+
+## CLI Commands
+
+| Command            | Description                              |
+| ------------------ | ---------------------------------------- |
+| `otpilot setup`    | Run or re-run the interactive setup      |
+| `otpilot start`    | Start the background service             |
+| `otpilot status`   | Show auth state, hotkey, and config path |
+| `otpilot version`  | Print the version number                 |
+
+## Configuration
+
+OTPilot stores its configuration at `~/.otpilot/config.json`:
+
+```json
+{
+  "hotkey": "ctrl+shift+o",
+  "notify_on_copy": true,
+  "otp_max_age_minutes": 10,
+  "email_fetch_count": 10
+}
+```
+
+| Field                 | Type   | Default          | Description                                    |
+| --------------------- | ------ | ---------------- | ---------------------------------------------- |
+| `hotkey`              | string | `ctrl+shift+o`   | Global hotkey combination                      |
+| `notify_on_copy`      | bool   | `true`           | Show desktop notification when OTP is copied   |
+| `otp_max_age_minutes` | int    | `10`             | Ignore emails older than this (minutes)        |
+| `email_fetch_count`   | int    | `10`             | Number of recent emails to scan                |
+
+### Files Stored Locally
+
+| File                             | Purpose                              |
+| -------------------------------- | ------------------------------------ |
+| `~/.otpilot/config.json`        | Your hotkey and settings             |
+| `~/.otpilot/credentials.json`   | Your Google OAuth credentials        |
+| `~/.otpilot/token.json`         | OAuth session token (auto-generated) |
+
+## Platform Support
+
+| Platform | Status | Notes                                  |
+| -------- | ------ | -------------------------------------- |
+| macOS    | ✅     | Full support                           |
+| Windows  | ✅     | Full support                           |
+| Linux    | ✅     | Requires `xclip`/`xsel` for clipboard  |
+
+## How OTP Extraction Works
+
+OTPilot scans the subject line and body of your recent emails for:
+
+- **4–8 digit standalone numbers** near context words like *OTP*, *code*, *verify*, *verification*, *one-time*, *passcode*, *authentication*
+- Only emails within the configured time window are considered
+- If multiple OTPs are found, the most recent one wins
+
+## Security & Privacy
+
+- **Your credentials stay local**: `credentials.json` is stored on your machine at `~/.otpilot/` and is never uploaded anywhere.
+- **Read-only access**: OTPilot only reads your emails — it cannot send, delete, or modify anything.
+- **Local storage only**: Your OAuth token is stored locally at `~/.otpilot/token.json`. Nothing is sent to any third-party server.
+- **On-demand only**: Emails are fetched only when you press the hotkey. There is no background polling.
+
+## Troubleshooting
+
+| Issue                             | Solution                                                       |
+| --------------------------------- | -------------------------------------------------------------- |
+| "credentials.json not found"      | Run `otpilot setup` and provide your credentials file          |
+| "Invalid credentials file"        | Re-download credentials.json from Google Cloud Console         |
+| "Not authenticated" error         | Run `otpilot setup` to re-authenticate                         |
+| No OTP found                      | Check `otp_max_age_minutes` — the email might be too old       |
+| Clipboard not working (Linux)     | Install `xclip`: `sudo apt install xclip`                      |
+| Hotkey not working                | Run `otpilot setup` to reconfigure the hotkey                  |
+| Tray icon not visible             | Check your system tray / menu bar settings                     |
+
+## Contributing
+
+Contributions are welcome! See [**CONTRIBUTING.md**](CONTRIBUTING.md) for guidelines on setting up the development environment, running tests, and submitting pull requests.
+
+## License
+
+[MIT](../LICENSE) — use it freely.

otpilot-2.0.0/otpilot/__init__.py

@@ -0,0 +1,4 @@
+"""OTPilot — Background desktop utility that copies OTPs from Gmail to clipboard on hotkey trigger."""
+
+__version__ = "2.0.0"
+__app_name__ = "OTPilot"

otpilot-2.0.0/otpilot/clipboard.py

@@ -0,0 +1,38 @@
+"""Clipboard operations for OTPilot.
+
+Wraps ``pyperclip`` with error handling so clipboard failures never crash
+the application.
+"""
+
+import pyperclip
+
+
+class ClipboardError(Exception):
+    """Raised when a clipboard operation fails."""
+
+    def __init__(self, message: str = "Could not access the clipboard.") -> None:
+        super().__init__(message)
+
+
+def copy_to_clipboard(text: str) -> None:
+    """Copy text to the system clipboard.
+
+    Args:
+        text: The string to copy.
+
+    Raises:
+        ClipboardError: If the clipboard is unavailable (e.g. no display
+            server on Linux, or missing clipboard utilities).
+    """
+    try:
+        pyperclip.copy(text)
+    except pyperclip.PyperclipException as exc:
+        raise ClipboardError(
+            "Could not copy to clipboard. "
+            "On Linux, make sure xclip or xsel is installed. "
+            f"Details: {exc}"
+        ) from exc
+    except Exception as exc:
+        raise ClipboardError(
+            f"Unexpected clipboard error: {exc}"
+        ) from exc

otpilot-2.0.0/otpilot/config.py

@@ -0,0 +1,111 @@
+"""Configuration management for OTPilot.
+
+Handles reading and writing of ~/.otpilot/config.json.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+# Default configuration directory and file paths
+CONFIG_DIR: Path = Path.home() / ".otpilot"
+CONFIG_FILE: Path = CONFIG_DIR / "config.json"
+TOKEN_FILE: Path = CONFIG_DIR / "token.json"
+
+# Default configuration values
+DEFAULT_CONFIG: Dict[str, Any] = {
+    "hotkey": "ctrl+shift+o",
+    "notify_on_copy": True,
+    "otp_max_age_minutes": 10,
+    "email_fetch_count": 10,
+}
+
+
+def _ensure_config_dir() -> None:
+    """Create the configuration directory if it doesn't exist."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_config() -> Dict[str, Any]:
+    """Load and return the current configuration.
+
+    If the config file doesn't exist, creates it with default values.
+
+    Returns:
+        Dictionary containing all configuration values.
+    """
+    _ensure_config_dir()
+
+    if not CONFIG_FILE.exists():
+        save_config(DEFAULT_CONFIG)
+        return DEFAULT_CONFIG.copy()
+
+    try:
+        with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+            stored_config: Dict[str, Any] = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        # If config is corrupted, reset to defaults
+        save_config(DEFAULT_CONFIG)
+        return DEFAULT_CONFIG.copy()
+
+    # Merge with defaults so new keys are always present
+    merged = DEFAULT_CONFIG.copy()
+    merged.update(stored_config)
+    return merged
+
+
+def save_config(data: Dict[str, Any]) -> None:
+    """Save configuration data to disk.
+
+    Args:
+        data: Dictionary of configuration values to persist.
+    """
+    _ensure_config_dir()
+
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, sort_keys=True)
+
+
+def config_exists() -> bool:
+    """Check whether a configuration file already exists.
+
+    Returns:
+        True if config.json is present, False otherwise.
+    """
+    return CONFIG_FILE.exists()
+
+
+def token_exists() -> bool:
+    """Check whether an OAuth token file already exists.
+
+    Returns:
+        True if token.json is present, False otherwise.
+    """
+    return TOKEN_FILE.exists()
+
+
+def get_value(key: str, default: Optional[Any] = None) -> Any:
+    """Retrieve a single configuration value.
+
+    Args:
+        key: The config key to look up.
+        default: Fallback value if the key is missing.
+
+    Returns:
+        The configuration value, or *default* if not found.
+    """
+    config = get_config()
+    return config.get(key, default)
+
+
+def set_value(key: str, value: Any) -> None:
+    """Update a single configuration value and persist to disk.
+
+    Args:
+        key: The config key to update.
+        value: The new value.
+    """
+    config = get_config()
+    config[key] = value
+    save_config(config)

otpilot-2.0.0/otpilot/credentials.py

@@ -0,0 +1,53 @@
+"""OAuth2 credential paths and scopes for OTPilot.
+
+Users provide their own ``credentials.json`` downloaded from the
+Google Cloud Console.  The file is stored at ``~/.otpilot/credentials.json``
+and never leaves the user's machine.
+"""
+
+from pathlib import Path
+
+
+# OAuth2 configuration
+SCOPES: list = ["https://www.googleapis.com/auth/gmail.readonly"]
+
+# Paths
+CREDENTIALS_FILE: Path = Path.home() / ".otpilot" / "credentials.json"
+
+
+def credentials_exist() -> bool:
+    """Check whether a user-provided credentials.json file exists.
+
+    Returns:
+        True if ``~/.otpilot/credentials.json`` is present, False otherwise.
+    """
+    return CREDENTIALS_FILE.exists()
+
+
+def validate_credentials_file(path: Path) -> bool:
+    """Validate that a file looks like a Google OAuth2 credentials JSON.
+
+    Performs a basic structural check — verifies the file is valid JSON
+    and contains either an ``installed`` or ``web`` top-level key with
+    a ``client_id`` field.
+
+    Args:
+        path: Path to the credentials JSON file.
+
+    Returns:
+        True if the file appears valid, False otherwise.
+    """
+    import json
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return False
+
+    # Google credentials JSON has either "installed" or "web" as a top key
+    for key in ("installed", "web"):
+        if key in data and "client_id" in data[key]:
+            return True
+
+    return False