hotmail-cli 0.1.0__py3-none-any.whl

hotmail_cli/__init__.py

@@ -0,0 +1,2 @@
+"""Hotmail/Outlook Microsoft Graph CLI helpers."""
+

hotmail_cli/auth.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import msal
+
+
+DEFAULT_AUTHORITY = "https://login.microsoftonline.com/consumers"
+DEFAULT_SCOPES = ["https://graph.microsoft.com/Mail.Read"]
+CLIENT_ID_ENV = "HOTMAIL_CLIENT_ID"
+
+
+class TokenStore:
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or default_token_path()
+
+    def load(self) -> dict[str, Any] | None:
+        if not self.path.exists():
+            return None
+        return json.loads(self.path.read_text())
+
+    def save(self, token: dict[str, Any]) -> None:
+        self.save_text(json.dumps(token, indent=2, sort_keys=True))
+
+    def load_text(self) -> str | None:
+        if not self.path.exists():
+            return None
+        return self.path.read_text()
+
+    def save_text(self, value: str) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = self.path.with_suffix(self.path.suffix + ".tmp")
+        tmp_path.write_text(value)
+        os.chmod(tmp_path, 0o600)
+        tmp_path.replace(self.path)
+        os.chmod(self.path, 0o600)
+
+
+class DeviceCodeAuthenticator:
+    def __init__(
+        self,
+        *,
+        client_id: str | None = None,
+        authority: str = DEFAULT_AUTHORITY,
+        scopes: list[str] | None = None,
+        store: TokenStore | None = None,
+    ) -> None:
+        self.client_id = client_id or os.environ.get(CLIENT_ID_ENV)
+        if not self.client_id:
+            raise RuntimeError(
+                f"Missing Microsoft app client id. Pass --client-id or set {CLIENT_ID_ENV}."
+            )
+        self.authority = authority
+        self.scopes = scopes or DEFAULT_SCOPES
+        self.store = store or TokenStore()
+        self.cache = msal.SerializableTokenCache()
+        cached = self.store.load_text()
+        if cached:
+            self.cache.deserialize(cached)
+        self.app = msal.PublicClientApplication(self.client_id, authority=authority, token_cache=self.cache)
+
+    def get_access_token(self) -> str:
+        accounts = self.app.get_accounts()
+        if accounts:
+            result = self.app.acquire_token_silent(self.scopes, account=accounts[0])
+            if result and "access_token" in result:
+                self._persist_cache()
+                return result["access_token"]
+        return self.login()["access_token"]
+
+    def login(self) -> dict[str, Any]:
+        flow = self.app.initiate_device_flow(scopes=self.scopes)
+        if "user_code" not in flow:
+            raise RuntimeError(f"Failed to create device flow: {flow}")
+        print(flow["message"])
+        result = self.app.acquire_token_by_device_flow(flow)
+        if "access_token" not in result:
+            error = result.get("error_description") or result
+            raise RuntimeError(f"Microsoft login failed: {error}")
+        self._persist_cache()
+        return result
+
+    def _persist_cache(self) -> None:
+        if self.cache.has_state_changed:
+            self.store.save_text(self.cache.serialize())
+
+
+def default_token_path() -> Path:
+    return Path.home() / ".hotmail-cli" / "token.json"

hotmail_cli/cli.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from .auth import DeviceCodeAuthenticator, TokenStore
+from .graph import GraphClient, MessageSearch
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "auth":
+        authenticator = _authenticator(args)
+        token = authenticator.login()
+        print(json.dumps({"token_type": token.get("token_type"), "expires_in": token.get("expires_in")}))
+        return 0
+
+    client = GraphClient(_authenticator(args).get_access_token())
+
+    if args.command == "search":
+        messages = client.search_messages(
+            MessageSearch(
+                subject=args.subject,
+                sender=args.sender,
+                since=args.since,
+                until=args.until,
+                top=args.top,
+            )
+        )
+        print(json.dumps(messages, ensure_ascii=False, indent=2))
+        return 0
+
+    if args.command == "fetch":
+        message = client.get_message(args.message_id)
+        print(json.dumps(message, ensure_ascii=False, indent=2))
+        return 0
+
+    if args.command == "attachments":
+        saved = client.download_attachments(args.message_id, Path(args.output_dir))
+        print(json.dumps([str(path) for path in saved], ensure_ascii=False, indent=2))
+        return 0
+
+    parser.error("missing command")
+    return 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hotmail", description="Fetch Hotmail/Outlook mail via Microsoft Graph.")
+    parser.add_argument("--token-file", help="Token cache path. Defaults to ~/.hotmail-cli/token.json.")
+    parser.add_argument("--client-id", help="Microsoft app client id. Or set HOTMAIL_CLIENT_ID.")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("auth", help="Sign in with Microsoft device code flow.")
+
+    search = subparsers.add_parser("search", help="Search messages.")
+    search.add_argument("--subject", help="Subject keyword.")
+    search.add_argument("--sender", help="Sender email address.")
+    search.add_argument("--since", help="Start date in YYYY-MM-DD.")
+    search.add_argument("--until", help="End date in YYYY-MM-DD.")
+    search.add_argument("--top", type=int, default=10, help="Maximum messages to return.")
+
+    fetch = subparsers.add_parser("fetch", help="Fetch one message by id.")
+    fetch.add_argument("message_id")
+
+    attachments = subparsers.add_parser("attachments", help="Download file attachments for one message.")
+    attachments.add_argument("message_id")
+    attachments.add_argument("--output-dir", default="downloads")
+
+    return parser
+
+
+def _authenticator(args: argparse.Namespace) -> DeviceCodeAuthenticator:
+    token_path = Path(args.token_file).expanduser() if args.token_file else None
+    return DeviceCodeAuthenticator(client_id=args.client_id, store=TokenStore(token_path))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hotmail_cli/graph.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import base64
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import requests
+
+
+GRAPH_ROOT = "https://graph.microsoft.com/v1.0"
+
+
+@dataclass(frozen=True)
+class MessageSearch:
+    subject: str | None = None
+    sender: str | None = None
+    since: str | None = None
+    until: str | None = None
+    top: int = 10
+
+
+class GraphClient:
+    def __init__(self, access_token: str, *, session: requests.Session | None = None) -> None:
+        self.access_token = access_token
+        self.session = session or requests.Session()
+
+    def search_messages(self, search: MessageSearch) -> list[dict[str, Any]]:
+        params = {
+            "$top": str(search.top),
+            "$select": "id,subject,receivedDateTime,from,hasAttachments,webLink",
+        }
+        if search.subject:
+            params["$search"] = f'"subject:{search.subject}"'
+        else:
+            params["$orderby"] = "receivedDateTime desc"
+        if not search.subject:
+            filters = _build_filters(search)
+            if filters:
+                params["$filter"] = " and ".join(filters)
+        response = self.session.get(
+            f"{GRAPH_ROOT}/me/messages",
+            headers=self._headers(),
+            params=params,
+        )
+        response.raise_for_status()
+        messages = response.json().get("value", [])
+        if search.subject:
+            messages = _filter_messages_locally(messages, search)
+        return messages
+
+    def get_message(self, message_id: str) -> dict[str, Any]:
+        response = self.session.get(
+            f"{GRAPH_ROOT}/me/messages/{message_id}",
+            headers=self._headers(),
+            params={"$select": "id,subject,receivedDateTime,from,body,hasAttachments,webLink"},
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def list_attachments(self, message_id: str) -> list[dict[str, Any]]:
+        response = self.session.get(
+            f"{GRAPH_ROOT}/me/messages/{message_id}/attachments",
+            headers=self._headers(),
+        )
+        response.raise_for_status()
+        return response.json().get("value", [])
+
+    def download_attachments(self, message_id: str, output_dir: Path) -> list[Path]:
+        attachments = self.list_attachments(message_id)
+        saved: list[Path] = []
+        for attachment in attachments:
+            if attachment.get("@odata.type") == "#microsoft.graph.fileAttachment":
+                saved.append(self.save_attachment(attachment, output_dir))
+        return saved
+
+    @staticmethod
+    def save_attachment(attachment: dict[str, Any], output_dir: Path) -> Path:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        filename = _safe_filename(attachment["name"])
+        path = _unique_path(output_dir / filename)
+        path.write_bytes(base64.b64decode(attachment["contentBytes"]))
+        return path
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.access_token}"}
+
+
+def _build_filters(search: MessageSearch) -> list[str]:
+    filters: list[str] = []
+    if search.sender:
+        filters.append(f"from/emailAddress/address eq '{_odata_quote(search.sender)}'")
+    if search.since:
+        filters.append(f"receivedDateTime ge {search.since}T00:00:00Z")
+    if search.until:
+        filters.append(f"receivedDateTime le {search.until}T23:59:59Z")
+    return filters
+
+
+def _odata_quote(value: str) -> str:
+    return value.replace("'", "''")
+
+
+def _safe_filename(filename: str) -> str:
+    cleaned = re.sub(r"[/\\:\0]", "_", filename).strip()
+    return cleaned or "attachment"
+
+
+def _unique_path(path: Path) -> Path:
+    if not path.exists():
+        return path
+    stem = path.stem
+    suffix = path.suffix
+    parent = path.parent
+    counter = 2
+    while True:
+        candidate = parent / f"{stem}-{counter}{suffix}"
+        if not candidate.exists():
+            return candidate
+        counter += 1
+
+
+def _filter_messages_locally(messages: list[dict[str, Any]], search: MessageSearch) -> list[dict[str, Any]]:
+    filtered = messages
+    if search.sender:
+        sender = search.sender.lower()
+        filtered = [
+            message
+            for message in filtered
+            if message.get("from", {}).get("emailAddress", {}).get("address", "").lower() == sender
+        ]
+    if search.since:
+        lower = f"{search.since}T00:00:00Z"
+        filtered = [message for message in filtered if message.get("receivedDateTime", "") >= lower]
+    if search.until:
+        upper = f"{search.until}T23:59:59Z"
+        filtered = [message for message in filtered if message.get("receivedDateTime", "") <= upper]
+    return filtered

hotmail_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: hotmail-cli
+Version: 0.1.0
+Summary: CLI for fetching Hotmail/Outlook messages and attachments via Microsoft Graph.
+Author: kadaliao
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kadaliao/hotmail-cli
+Project-URL: Repository, https://github.com/kadaliao/hotmail-cli
+Project-URL: Issues, https://github.com/kadaliao/hotmail-cli/issues
+Keywords: hotmail,outlook,microsoft-graph,email,attachments,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: msal>=1.30.0
+Requires-Dist: requests>=2.32.0
+Dynamic: license-file
+
+# Hotmail CLI
+
+A small read-only CLI for Hotmail and Outlook.com mailboxes. It uses Microsoft Graph to search messages and download file attachments from your mailbox.
+
+中文文档: [README.zh-CN.md](README.zh-CN.md)
+
+## Why Use This
+
+- Works with personal Microsoft accounts such as Hotmail and Outlook.com.
+- Uses Microsoft device code login, so the CLI never sees your password.
+- Requests only `Mail.Read`.
+- Downloads attachments from matching messages.
+- Stores the OAuth token locally with `0600` file permissions.
+
+This tool is intentionally narrow. It does not send email, delete messages, mark messages, or manage calendars.
+
+## Installation
+
+```bash
+uvx hotmail-cli --help
+```
+
+Or install it into an environment:
+
+```bash
+uv tool install hotmail-cli
+hotmail --help
+```
+
+## Microsoft App Setup
+
+You need your own Microsoft Entra app registration. This is free and lets Microsoft show you exactly what the CLI is allowed to access.
+
+1. Open the [Microsoft Entra admin center](https://entra.microsoft.com/).
+2. Go to **App registrations** -> **New registration**.
+3. Name it `hotmail-cli` or any name you prefer.
+4. For **Supported account types**, choose **Personal Microsoft accounts only** for Hotmail/Outlook.com.
+5. Leave **Redirect URI** empty.
+6. Create the app.
+7. Open **Authentication** -> **Settings**.
+8. Enable **Allow public client flows** and save.
+9. Copy the **Application (client) ID**.
+
+## Sign In
+
+```bash
+export HOTMAIL_CLIENT_ID="your Microsoft app client id"
+hotmail auth
+```
+
+The command prints a URL and code. Open the URL in your browser, enter the code, sign in to Microsoft, and approve the requested `Mail.Read` access.
+
+The token cache is saved to:
+
+```text
+~/.hotmail-cli/token.json
+```
+
+You can also pass the client id directly:
+
+```bash
+hotmail --client-id "your Microsoft app client id" auth
+```
+
+## Search Messages
+
+Search by subject:
+
+```bash
+hotmail search --subject "statement" --top 10
+```
+
+Search by subject, sender, and date range:
+
+```bash
+hotmail search \
+  --subject "invoice" \
+  --sender "billing@example.com" \
+  --since 2026-06-01 \
+  --until 2026-06-27 \
+  --top 10
+```
+
+The output is Microsoft Graph message JSON. Each message includes an `id` that can be used with `fetch` and `attachments`.
+
+Microsoft Graph message `$search` cannot be reliably combined with `$filter` or `$orderby`, so Hotmail CLI searches by subject server-side first, then applies sender and date filters locally.
+
+## Fetch One Message
+
+```bash
+hotmail fetch MESSAGE_ID
+```
+
+## Download Attachments
+
+```bash
+hotmail attachments MESSAGE_ID --output-dir downloads
+```
+
+Only Microsoft Graph `fileAttachment` items are saved. Inline items and reference attachments are ignored.
+
+## Local Development
+
+```bash
+uv sync
+uv run pytest
+uv run hotmail --help
+```
+
+Build the package:
+
+```bash
+uv build
+```
+
+## Security Notes
+
+- Do not commit `~/.hotmail-cli/token.json`.
+- Do not share message IDs or downloaded attachments publicly.
+- Revoke access anytime from your Microsoft account security page or from the app registration.
+
+## License
+
+MIT
+

hotmail_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+hotmail_cli/__init__.py,sha256=_AUqt91_zX4p6W9CoNhBNNUy6XUZ5cQYnQdn19YD7ts,52
+hotmail_cli/auth.py,sha256=jwmL-1Id4xZVoHgYzcAsN3oVZFrAJwjy1v9V21h2xug,3137
+hotmail_cli/cli.py,sha256=OK-cGlL2ZBN3ifsM-fq_iYNl3inAWYy62SsNgNtkAz4,3063
+hotmail_cli/graph.py,sha256=Yim8EeoyMa211x5Z0lDciiWXyhqkkVWpeP159yEJaBU,4701
+hotmail_cli-0.1.0.dist-info/licenses/LICENSE,sha256=WMFW9C4Vc4tX0sIXCfV3gfLvvoWpO6LSR_SSFiA6iIc,1066
+hotmail_cli-0.1.0.dist-info/METADATA,sha256=tDELWz2epX8tLzdu75uHIVhHqXfglASsl4GAy2YuZzg,4172
+hotmail_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hotmail_cli-0.1.0.dist-info/entry_points.txt,sha256=589M26PvvDb8ObFhKOcYiCHdzhjH_Okh6RhxLu7pV6A,49
+hotmail_cli-0.1.0.dist-info/top_level.txt,sha256=8NxXv88RqLHNlVkNQGo7i1NHQ2LP2Laxg_K03m1D0PE,12
+hotmail_cli-0.1.0.dist-info/RECORD,,

hotmail_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hotmail_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hotmail = hotmail_cli.cli:main

hotmail_cli-0.1.0.dist-info/licenses/LICENSE

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

hotmail_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hotmail_cli