hotmail-cli 0.1.0__tar.gz

hotmail_cli-0.1.0/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/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.zh-CN.md
+

hotmail_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,125 @@
+# 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/README.zh-CN.md

@@ -0,0 +1,125 @@
+# Hotmail CLI
+
+一个小型只读命令行工具，用于读取 Hotmail 和 Outlook.com 邮箱。它通过 Microsoft Graph 搜索邮件，并下载邮件里的文件附件。
+
+English documentation: [README.md](README.md)
+
+## 为什么用它
+
+- 支持 Hotmail、Outlook.com 等个人 Microsoft 账号。
+- 使用 Microsoft device code 登录，CLI 不会接触你的密码。
+- 只申请 `Mail.Read` 权限。
+- 可以下载匹配邮件里的附件。
+- OAuth token 保存在本地，并使用 `0600` 文件权限。
+
+这个工具刻意保持窄范围。它不会发邮件、删除邮件、标记已读，也不会管理日历。
+
+## 安装
+
+```bash
+uvx hotmail-cli --help
+```
+
+或者安装到本地工具环境：
+
+```bash
+uv tool install hotmail-cli
+hotmail --help
+```
+
+## 创建 Microsoft 应用
+
+你需要创建一个自己的 Microsoft Entra app registration。这个过程免费，也能让 Microsoft 明确展示 CLI 被授权访问哪些内容。
+
+1. 打开 [Microsoft Entra admin center](https://entra.microsoft.com/)。
+2. 进入 **App registrations** -> **New registration**。
+3. 名称可以填 `hotmail-cli`，也可以用你自己的名称。
+4. **Supported account types** 选择 **Personal Microsoft accounts only**。
+5. **Redirect URI** 留空。
+6. 创建应用。
+7. 打开 **Authentication** -> **Settings**。
+8. 启用 **Allow public client flows** 并保存。
+9. 复制 **Application (client) ID**。
+
+## 登录授权
+
+```bash
+export HOTMAIL_CLIENT_ID="你的 Microsoft app client id"
+hotmail auth
+```
+
+命令会输出一个 URL 和验证码。用浏览器打开 URL，输入验证码，登录 Microsoft，并批准 `Mail.Read` 权限。
+
+token 缓存会保存到：
+
+```text
+~/.hotmail-cli/token.json
+```
+
+也可以直接传入 client id：
+
+```bash
+hotmail --client-id "你的 Microsoft app client id" auth
+```
+
+## 搜索邮件
+
+按主题搜索：
+
+```bash
+hotmail search --subject "statement" --top 10
+```
+
+按主题、发件人和日期范围搜索：
+
+```bash
+hotmail search \
+  --subject "invoice" \
+  --sender "billing@example.com" \
+  --since 2026-06-01 \
+  --until 2026-06-27 \
+  --top 10
+```
+
+输出是 Microsoft Graph message JSON。每封邮件都有一个 `id`，可以继续用于 `fetch` 和 `attachments` 命令。
+
+Microsoft Graph 的邮件 `$search` 不能稳定地和 `$filter` 或 `$orderby` 混用，所以 Hotmail CLI 会先在服务端按主题搜索，再在本地按发件人和日期过滤。
+
+## 获取单封邮件
+
+```bash
+hotmail fetch MESSAGE_ID
+```
+
+## 下载附件
+
+```bash
+hotmail attachments MESSAGE_ID --output-dir downloads
+```
+
+当前只保存 Microsoft Graph 的 `fileAttachment`。内联附件和引用附件会被忽略。
+
+## 本地开发
+
+```bash
+uv sync
+uv run pytest
+uv run hotmail --help
+```
+
+构建包：
+
+```bash
+uv build
+```
+
+## 安全说明
+
+- 不要提交 `~/.hotmail-cli/token.json`。
+- 不要公开分享邮件 ID 或下载的附件。
+- 可以随时在 Microsoft 账号安全页面或 app registration 中撤销访问。
+
+## License
+
+MIT
+

hotmail_cli-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "hotmail-cli"
+version = "0.1.0"
+description = "CLI for fetching Hotmail/Outlook messages and attachments via Microsoft Graph."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "kadaliao" },
+]
+keywords = ["hotmail", "outlook", "microsoft-graph", "email", "attachments", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Topic :: Office/Business",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "msal>=1.30.0",
+    "requests>=2.32.0",
+]
+
+[project.scripts]
+hotmail = "hotmail_cli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/kadaliao/hotmail-cli"
+Repository = "https://github.com/kadaliao/hotmail-cli"
+Issues = "https://github.com/kadaliao/hotmail-cli/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.2.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

hotmail_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hotmail_cli-0.1.0/src/hotmail_cli/__init__.py

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

hotmail_cli-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/hotmail_cli.egg-info/PKG-INFO

@@ -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/src/hotmail_cli.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+README.zh-CN.md
+pyproject.toml
+src/hotmail_cli/__init__.py
+src/hotmail_cli/auth.py
+src/hotmail_cli/cli.py
+src/hotmail_cli/graph.py
+src/hotmail_cli.egg-info/PKG-INFO
+src/hotmail_cli.egg-info/SOURCES.txt
+src/hotmail_cli.egg-info/dependency_links.txt
+src/hotmail_cli.egg-info/entry_points.txt
+src/hotmail_cli.egg-info/requires.txt
+src/hotmail_cli.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_graph.py
+tests/test_token_cache.py

hotmail_cli-0.1.0/src/hotmail_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hotmail_cli-0.1.0/src/hotmail_cli.egg-info/entry_points.txt

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

hotmail_cli-0.1.0/src/hotmail_cli.egg-info/requires.txt

@@ -0,0 +1,2 @@
+msal>=1.30.0
+requests>=2.32.0

hotmail_cli-0.1.0/src/hotmail_cli.egg-info/top_level.txt

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

hotmail_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,30 @@
+import json
+
+from hotmail_cli import cli
+
+
+class FakeAuthenticator:
+    def __init__(self, access_token="token"):
+        self.access_token = access_token
+
+    def get_access_token(self):
+        return self.access_token
+
+
+class FakeGraphClient:
+    def __init__(self, access_token):
+        self.access_token = access_token
+
+    def search_messages(self, search):
+        return [{"id": "m1", "subject": search.subject, "top": search.top}]
+
+
+def test_search_command_outputs_json(monkeypatch, capsys):
+    monkeypatch.setattr(cli, "_authenticator", lambda args: FakeAuthenticator())
+    monkeypatch.setattr(cli, "GraphClient", FakeGraphClient)
+
+    exit_code = cli.main(["search", "--subject", "invoice", "--top", "3"])
+
+    assert exit_code == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload == [{"id": "m1", "subject": "invoice", "top": 3}]

hotmail_cli-0.1.0/tests/test_graph.py

@@ -0,0 +1,86 @@
+import base64
+from pathlib import Path
+
+from hotmail_cli.graph import GraphClient, MessageSearch
+
+
+class FakeSession:
+    def __init__(self):
+        self.calls = []
+
+    def get(self, url, **kwargs):
+        self.calls.append((url, kwargs))
+        return FakeResponse(
+            {
+                "value": [
+                    {
+                        "id": "m1",
+                        "subject": "Monthly Statement",
+                        "receivedDateTime": "2026-06-26T10:00:00Z",
+                        "from": {"emailAddress": {"address": "noreply@example.com"}},
+                        "hasAttachments": True,
+                    }
+                ]
+            }
+        )
+
+
+class FakeResponse:
+    def __init__(self, payload):
+        self.payload = payload
+
+    def raise_for_status(self):
+        return None
+
+    def json(self):
+        return self.payload
+
+
+def test_search_messages_builds_graph_filter_and_select():
+    session = FakeSession()
+    client = GraphClient("token", session=session)
+
+    messages = client.search_messages(
+        MessageSearch(
+            subject="Statement",
+            sender="noreply@example.com",
+            since="2026-06-01",
+            until="2026-06-27",
+            top=5,
+        )
+    )
+
+    assert messages[0]["id"] == "m1"
+    url, kwargs = session.calls[0]
+    assert url == "https://graph.microsoft.com/v1.0/me/messages"
+    assert kwargs["headers"]["Authorization"] == "Bearer token"
+    assert kwargs["params"]["$top"] == "5"
+    assert kwargs["params"]["$search"] == '"subject:Statement"'
+    assert "$filter" not in kwargs["params"]
+    assert "subject" in kwargs["params"]["$select"]
+    assert messages[0]["from"]["emailAddress"]["address"] == "noreply@example.com"
+
+
+def test_search_messages_uses_graph_search_for_subject_only():
+    session = FakeSession()
+    client = GraphClient("token", session=session)
+
+    client.search_messages(MessageSearch(subject="invoice", top=5))
+
+    _, kwargs = session.calls[0]
+    assert kwargs["params"]["$search"] == '"subject:invoice"'
+    assert "$filter" not in kwargs["params"]
+    assert "$orderby" not in kwargs["params"]
+
+
+def test_download_file_attachments_writes_base64_content(tmp_path: Path):
+    attachment = {
+        "@odata.type": "#microsoft.graph.fileAttachment",
+        "name": "statement.pdf",
+        "contentBytes": base64.b64encode(b"pdf bytes").decode("ascii"),
+    }
+
+    saved = GraphClient.save_attachment(attachment, tmp_path)
+
+    assert saved == tmp_path / "statement.pdf"
+    assert saved.read_bytes() == b"pdf bytes"

hotmail_cli-0.1.0/tests/test_token_cache.py

@@ -0,0 +1,23 @@
+import json
+
+import pytest
+
+from hotmail_cli import auth
+from hotmail_cli.auth import TokenStore
+
+
+def test_token_store_writes_private_json_file(tmp_path):
+    path = tmp_path / "token.json"
+    store = TokenStore(path)
+
+    store.save({"access_token": "abc", "refresh_token": "def"})
+
+    assert json.loads(path.read_text())["access_token"] == "abc"
+    assert oct(path.stat().st_mode & 0o777) == "0o600"
+
+
+def test_authenticator_requires_client_id(monkeypatch, tmp_path):
+    monkeypatch.delenv(auth.CLIENT_ID_ENV, raising=False)
+
+    with pytest.raises(RuntimeError, match="client id"):
+        auth.DeviceCodeAuthenticator(store=TokenStore(tmp_path / "token.json"))