ccal 0.1.4__py3-none-any.whl

ccal-0.1.4.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: ccal
+Version: 0.1.4
+Summary: CLI tool for adding calendar events
+Requires-Python: >=3.12
+Requires-Dist: google-api-python-client>=2.0
+Requires-Dist: google-auth-oauthlib>=1.0
+Requires-Dist: icalendar>=6.0
+Requires-Dist: keyring>=25.0
+Requires-Dist: litellm>=1.0
+Requires-Dist: pydantic>=2.13.1
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.24.1
+Provides-Extra: ocr
+Requires-Dist: pillow>=11.0; extra == 'ocr'
+Requires-Dist: pytesseract>=0.3.13; extra == 'ocr'
+Description-Content-Type: text/markdown
+
+# ccal
+
+[中文文档](README-zh_cn.md)
+
+A CLI tool that turns natural language text or images into calendar events. Powered by LLMs.
+
+## Features
+
+- **Text input** — describe an event in plain language, ccal parses it into structured fields
+- **Image input** — extract text from screenshots/photos via OCR, then parse
+- **Multi-LLM support** — works with OpenAI, Anthropic, Gemini, OpenRouter, Deepseek, Groq, Mistral, and more (via [litellm](https://github.com/BerriAI/litellm))
+- **ICS export** — generate standard `.ics` files importable by any calendar app
+- **Google Calendar sync** — create events directly on Google Calendar via API
+- **Apple Calendar sync** — add events via AppleScript (macOS only, auto-fallback to ICS on other platforms)
+- **Secure key storage** — API keys stored in your system keyring, never in plain text
+- **Geolocation** — auto-detect timezone and location for accurate event scheduling
+- **Stdin support** — pipe text from other commands
+
+## Requirements
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) (for image input)
+
+## Installation
+
+```bash
+git clone https://github.com/your-username/ccal.git
+cd ccal
+uv sync
+```
+
+## Quick Start
+
+### 1. Setup
+
+```bash
+ccal setup
+```
+
+This will walk you through configuring:
+- LLM provider and model
+- API key (stored securely in system keyring)
+- Default output method (ICS file, Google Calendar, or Apple Calendar)
+- Google Calendar setup, including client type, auth mode, credentials location, and Calendar ID
+
+### 2. Add an event
+
+From text:
+
+```bash
+ccal add "Team meeting tomorrow at 3pm in Conference Room A"
+```
+
+From an image:
+
+```bash
+ccal add flyer.png
+```
+
+From stdin:
+
+```bash
+echo "Lunch with Alice Friday noon" | ccal add
+```
+
+With options:
+
+```bash
+ccal add "Dinner Friday 7pm at Luigi's" -o google       # sync to Google Calendar
+ccal add "Weekly standup Mon 9am" -o apple               # add to Apple Calendar (macOS)
+ccal add "Weekly standup Mon 9am" -o ics                  # export as .ics file
+ccal add "会议明天下午两点" -m anthropic/claude-sonnet-4-20250514  # use a specific model
+ccal add screenshot.png -l chi_sim                        # OCR with Chinese language
+ccal add "Demo at 2pm" -y                                 # skip confirmation
+ccal add "Demo at 2pm" --json                             # output as JSON
+```
+
+### 3. Parse only (no save)
+
+```bash
+ccal parse "Workshop next Wednesday 10am-12pm, Room 301"
+ccal parse "下周一上午10点团队周会" --json
+```
+
+### 4. View config
+
+```bash
+ccal config
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ccal add [text\|image]` | Parse input and create a calendar event |
+| `ccal parse [text\|image]` | Parse and display event fields without saving |
+| `ccal setup` | Interactive configuration wizard |
+| `ccal config` | Show current configuration and platform info |
+
+### `ccal add` options
+
+| Option | Description |
+|--------|-------------|
+| `-o`, `--output` | Output method: `ics`, `google`, or `apple` |
+| `-p`, `--provider` | LLM provider name |
+| `-m`, `--model` | LLM model (e.g. `openai/gpt-4o`) |
+| `-y`, `--yes` | Skip confirmation, output directly |
+| `-l`, `--language` | OCR language (e.g. `chi_sim`, `eng+chi_sim`) |
+| `--json` | Output parsed event as JSON |
+
+## Platform Support
+
+| Feature | macOS | Linux | Windows |
+|---------|-------|-------|---------|
+| ICS export | ✅ | ✅ | ✅ |
+| Google Calendar | ✅ | ✅ | ✅ |
+| Apple Calendar | ✅ | ❌ fallback to ICS | ❌ fallback to ICS |
+
+## Configuration
+
+Config is stored at `~/.config/ccal/config.toml`. API keys are stored in your system's native keyring (macOS Keychain / Linux Secret Service / Windows Credential Locker).
+
+For Google Calendar integration, ccal uses two different local files:
+
+- `google_credentials.json`: the OAuth client credentials JSON downloaded from Google Cloud Console. This contains the client id and client secret. Keep this file around after setup.
+- `google_token_*.json`: the cached login token created after the first successful authorization. The access token inside can expire and refresh automatically, so you usually do not need to touch it. ccal picks the cache file based on the current credentials path and auth mode.
+
+During `ccal setup`, place the credentials JSON in the configured directory, or point setup directly at the JSON file. The setup tutorial also explains:
+
+- `Desktop app` vs `TVs and Limited Input devices`
+- `External` vs `Internal`
+- `Testing` status and `Test users`
+- how to find a Google Calendar ID
+- setup-time validation of the selected Calendar ID
+
+You can also configure Google Calendar during `ccal setup` through the dedicated middle step, even if your default output is not Google.
+
+## Project Structure
+
+```
+src/
+├── main.py                  # CLI entry point (Typer)
+├── config.py                # Configuration & keyring management
+├── models/
+│   ├── model.py             # CalendarEvent Pydantic model
+│   └── llm.py               # LLM parsing via litellm
+├── input/
+│   ├── ocr.py               # Image text extraction (pytesseract)
+│   └── geo.py               # IP-based geolocation for timezone
+└── connections/
+    ├── google_calendar.py   # Google Calendar API integration
+    ├── apple_calendar.py    # Apple Calendar via AppleScript (macOS)
+    └── ics.py               # ICS file export
+```
+
+## License
+
+MIT

ccal-0.1.4.dist-info/RECORD

@@ -0,0 +1,19 @@
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/config.py,sha256=vHVr4HOrkm8sMPzrB4nnZZ91CeOGKk4cF2ZtkDSls9c,4227
+src/event_workflow.py,sha256=8KzuAVtFhNSVo1QMa1oOQkuTFUdCTtV07qY2jtbdsJY,15978
+src/google_setup.py,sha256=h98BqPPl-P_gs59x2bQcw5XbOmVsqpI00z7YJi_Jr_w,7686
+src/main.py,sha256=T34bivnMx1QGLh34InMvZ3Y57mmKb4GIL8RUZrQ8szA,15826
+src/connections/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/connections/apple_calendar.py,sha256=PTlBtjU2jNLc-8WXurdYtxXgUJEdF0gM4tdncnjLPAw,2819
+src/connections/google_calendar.py,sha256=Vk60-t2oWnLZfcjgYcRJD8-iXtVqO-U_Ru2SrAOCzLg,8727
+src/connections/ics.py,sha256=R_xwaSofFBz-FCKtal0pCQtylvPgywGxrPozfAbuCdw,524
+src/input/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/input/geo.py,sha256=cT6EPeFlGGJ-D6w86OxGm796Abh0zEL1-qYukdanBm4,1356
+src/input/ocr.py,sha256=Ev83FoBFzcsQmWCyANYR2mhks3l60w0r30OAop_4s58,1402
+src/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/models/llm.py,sha256=T6OZHlb2OzNp3GDriSLbwHmuOzIuoR-1mmTl5OXaA_Y,5445
+src/models/model.py,sha256=jI1p79nIuyssy91CslCzz1RDw8W_yO7V20_Kv9bS7bU,6427
+ccal-0.1.4.dist-info/METADATA,sha256=ojQcGeMcEldLOeWjmYM_Oql008KCSy3jAOl1Zgbwy8I,6083
+ccal-0.1.4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ccal-0.1.4.dist-info/entry_points.txt,sha256=71MfNIq9WuIQmTlEy_N8TOBL3EfEq4FW1Ps_1Tf2uW8,39
+ccal-0.1.4.dist-info/RECORD,,

ccal-0.1.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ccal-0.1.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ccal = src.main:main

src/config.py

@@ -0,0 +1,115 @@
+import hashlib
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import keyring
+
+APP_NAME = "ccal"
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / APP_NAME
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+KEYRING_SERVICE = "ccal"
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "llm": {
+        "provider": "openai",
+        "model": "openai/gpt-4o",
+    },
+    "output": {
+        "default": "ics",  # "ics" or "google"
+    },
+    "google": {
+        "calendar_id": "primary",
+        "credentials_path": str(CONFIG_DIR / "google_credentials.json"),
+        "auth_mode": "desktop",
+    },
+}
+
+
+def load_config() -> dict[str, Any]:
+    """Load config from ~/.config/ccal/config.toml, falling back to defaults."""
+    if CONFIG_FILE.exists():
+        with open(CONFIG_FILE, "rb") as f:
+            user_config = tomllib.load(f)
+        # Merge with defaults
+        config = DEFAULT_CONFIG.copy()
+        for section, values in user_config.items():
+            if section in config and isinstance(config[section], dict):
+                config[section] = {**config[section], **values}
+            else:
+                config[section] = values
+        return config
+    return DEFAULT_CONFIG.copy()
+
+
+def save_config(config: dict[str, Any]) -> None:
+    """Save config to ~/.config/ccal/config.toml."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = []
+    for section, values in config.items():
+        if isinstance(values, dict):
+            lines.append(f"[{section}]")
+            for key, val in values.items():
+                if isinstance(val, str):
+                    lines.append(f'{key} = "{val}"')
+                elif isinstance(val, bool):
+                    lines.append(f"{key} = {'true' if val else 'false'}")
+                elif isinstance(val, int | float):
+                    lines.append(f"{key} = {val}")
+            lines.append("")
+    CONFIG_FILE.write_text("\n".join(lines))
+
+
+def get_api_key(provider: str) -> str | None:
+    """Retrieve an API key from the system keyring."""
+    return keyring.get_password(KEYRING_SERVICE, f"{provider}_api_key")
+
+
+def set_api_key(provider: str, key: str) -> None:
+    """Store an API key in the system keyring."""
+    keyring.set_password(KEYRING_SERVICE, f"{provider}_api_key", key)
+
+
+def get_google_token_path(config: dict[str, Any] | None = None) -> Path:
+    """Path for cached Google OAuth token."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    cache_key = _google_token_cache_key(config)
+    return CONFIG_DIR / f"google_token_{cache_key}.json"
+
+
+def get_google_credentials_dir(config: dict[str, Any] | None = None) -> Path:
+    """Directory containing Google OAuth client credentials."""
+    if config:
+        google_config = config.get("google", {})
+        credentials_path = google_config.get("credentials_path")
+        if credentials_path:
+            return Path(credentials_path).expanduser().parent
+        credentials_dir = google_config.get("credentials_dir")
+        if credentials_dir:
+            return Path(credentials_dir).expanduser()
+    return CONFIG_DIR
+
+
+def get_google_credentials_path(config: dict[str, Any] | None = None) -> Path:
+    """Path for Google OAuth client credentials JSON."""
+    if config:
+        google_config = config.get("google", {})
+        credentials_path = google_config.get("credentials_path")
+        if credentials_path:
+            return Path(credentials_path).expanduser()
+        credentials_dir = google_config.get("credentials_dir")
+        if credentials_dir:
+            return Path(credentials_dir).expanduser() / "google_credentials.json"
+    return CONFIG_DIR / "google_credentials.json"
+
+
+def _google_token_cache_key(config: dict[str, Any] | None = None) -> str:
+    """Derive a stable cache key from the selected Google credentials and auth mode."""
+    credentials_path = get_google_credentials_path(config)
+    auth_mode = "desktop"
+    if config:
+        auth_mode = config.get("google", {}).get("auth_mode", auth_mode)
+    canonical_path = str(credentials_path.expanduser().resolve(strict=False))
+    raw_key = f"{canonical_path}|{auth_mode}"
+    return hashlib.sha256(raw_key.encode("utf-8")).hexdigest()[:16]

src/connections/apple_calendar.py

@@ -0,0 +1,92 @@
+import platform
+import subprocess
+from datetime import datetime, timedelta
+
+from src.models.model import CalendarEvent
+
+
+def is_macos() -> bool:
+    return platform.system() == "Darwin"
+
+
+def create_event(event: CalendarEvent, calendar_name: str = "Home") -> None:
+    """Create an event in Apple Calendar via AppleScript. macOS only."""
+    if not is_macos():
+        raise RuntimeError(
+            "Apple Calendar integration is only available on macOS. "
+            "Use 'ics' output instead (the .ics file can be opened by any calendar app)."
+        )
+
+    start = _format_applescript_date(event.start_time)
+
+    if event.end_time:
+        end = _format_applescript_date(event.end_time)
+    else:
+        end = _format_applescript_date(event.start_time + timedelta(hours=1))
+
+    props = f'summary:"{_escape(event.title)}", start date:{start}, end date:{end}'
+    if event.location:
+        props += f', location:"{_escape(event.location)}"'
+    if event.description:
+        props += f', description:"{_escape(event.description)}"'
+
+    script = f'''
+    tell application "Calendar"
+        tell calendar "{_escape(calendar_name)}"
+            make new event at end with properties {{{props}}}
+        end tell
+        reload calendars
+    end tell
+    '''
+
+    result = subprocess.run(
+        ["osascript", "-e", script],
+        capture_output=True,
+        text=True,
+        timeout=15,
+    )
+
+    if result.returncode != 0:
+        error = result.stderr.strip()
+        if "Calendar" in error and "doesn't understand" in error:
+            raise RuntimeError("Apple Calendar app is not available or not responding.")
+        raise RuntimeError(f"AppleScript error: {error}")
+
+
+def list_calendars() -> list[str]:
+    """List available Apple Calendar names. macOS only."""
+    if not is_macos():
+        raise RuntimeError("Apple Calendar is only available on macOS.")
+
+    script = '''
+    tell application "Calendar"
+        set calNames to {}
+        repeat with c in calendars
+            set end of calNames to name of c
+        end repeat
+        return calNames
+    end tell
+    '''
+    result = subprocess.run(
+        ["osascript", "-e", script],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Failed to list calendars: {result.stderr.strip()}")
+
+    raw = result.stdout.strip()
+    if not raw:
+        return []
+    return [name.strip() for name in raw.split(",")]
+
+
+def _format_applescript_date(dt: datetime) -> str:
+    """Format a datetime for AppleScript: date "April 16, 2026 3:00:00 PM"."""
+    return f'date "{dt.strftime("%B %d, %Y %I:%M:%S %p")}"'
+
+
+def _escape(s: str) -> str:
+    """Escape a string for use inside AppleScript double quotes."""
+    return s.replace("\\", "\\\\").replace('"', '\\"')

src/connections/google_calendar.py

@@ -0,0 +1,215 @@
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+
+from src.config import get_google_credentials_path, get_google_token_path, load_config
+from src.models.model import CalendarEvent
+
+SCOPES = ["https://www.googleapis.com/auth/calendar"]
+
+
+def authenticate(config: dict | None = None):
+    """Authenticate with Google Calendar API and return the service object."""
+    if config is None:
+        config = load_config()
+    token_path = get_google_token_path(config)
+    creds_path = get_google_credentials_path(config)
+    auth_mode = config.get("google", {}).get("auth_mode", "desktop")
+
+    creds = None
+    if token_path.exists():
+        creds = Credentials.from_authorized_user_file(str(token_path), SCOPES)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            if not creds_path.exists():
+                raise FileNotFoundError(
+                    f"Google OAuth credentials not found at {creds_path}. "
+                    "Download your OAuth client credentials JSON from Google Cloud Console "
+                    "and save it there, then run 'ccal setup' again."
+                )
+            client_config = _load_client_config(creds_path)
+            if auth_mode == "device":
+                creds = _run_device_flow(client_config)
+            else:
+                if _should_use_device_flow():
+                    raise RuntimeError(
+                        "This machine has no browser available for Google desktop OAuth. "
+                        "Either run setup on a machine with a browser, or create a "
+                        "'TVs and Limited Input devices' OAuth client and use device mode."
+                    )
+                flow = InstalledAppFlow.from_client_secrets_file(str(creds_path), SCOPES)
+                try:
+                    creds = flow.run_local_server(port=0)
+                except Exception as e:
+                    if _looks_like_browser_error(e):
+                        raise RuntimeError(
+                            "No runnable browser detected for Google desktop OAuth. "
+                            "Use a machine with a browser, or switch to device mode with a "
+                            "'TVs and Limited Input devices' OAuth client."
+                        ) from e
+                    else:
+                        raise
+
+        token_path.write_text(creds.to_json())
+
+    return build("calendar", "v3", credentials=creds)
+
+
+def create_event(service, event: CalendarEvent, calendar_id: str | None = None) -> dict:
+    """Create an event on Google Calendar. Returns the created event."""
+    if calendar_id is None:
+        config = load_config()
+        calendar_id = config["google"]["calendar_id"]
+
+    google_event = event.to_google_event()
+    result = service.events().insert(calendarId=calendar_id, body=google_event).execute()
+    return result
+
+
+def list_calendars(service) -> list[dict]:
+    """List all calendars accessible by the authenticated user."""
+    result = service.calendarList().list().execute()
+    return result.get("items", [])
+
+
+def _load_client_config(creds_path) -> dict:
+    """Load the OAuth client configuration from the downloaded JSON file."""
+    with open(creds_path) as f:
+        data = json.load(f)
+    if "installed" in data:
+        return data["installed"]
+    if "web" in data:
+        return data["web"]
+    raise ValueError("Google credentials JSON must contain an 'installed' or 'web' client configuration.")
+
+
+def _should_use_device_flow() -> bool:
+    """Prefer device flow on headless Linux environments."""
+    return not (os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+
+def _looks_like_browser_error(error: Exception) -> bool:
+    """Detect browser-launch errors from the OAuth helper."""
+    message = str(error).lower()
+    return "browser" in message or "xdg-open" in message or "open a web browser" in message
+
+
+def _extract_error_name(exc: urllib.error.HTTPError) -> str | None:
+    """Best-effort extraction of Google OAuth error names from an HTTPError body."""
+    try:
+        body = exc.read().decode()
+        if not body:
+            return None
+        payload = json.loads(body)
+        if isinstance(payload, dict):
+            return payload.get("error")
+    except Exception:
+        return None
+    return None
+
+
+def _run_device_flow(client_config: dict) -> Credentials:
+    """Authenticate using Google's device authorization flow."""
+    client_id = client_config.get("client_id")
+    client_secret = client_config.get("client_secret")
+    token_uri = client_config.get("token_uri", "https://oauth2.googleapis.com/token")
+
+    if not client_id:
+        raise ValueError("Google credentials JSON does not include a client_id.")
+
+    request_data = urllib.parse.urlencode({
+        "client_id": client_id,
+        "scope": " ".join(SCOPES),
+    }).encode()
+    request = urllib.request.Request(
+        "https://oauth2.googleapis.com/device/code",
+        data=request_data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+
+    try:
+        with urllib.request.urlopen(request) as response:
+            payload = json.load(response)
+    except urllib.error.HTTPError as exc:
+        error_name = _extract_error_name(exc)
+        if exc.code == 401:
+            raise RuntimeError(
+                "Google rejected the device authorization request. "
+                "This usually means the JSON came from a Desktop app OAuth client, "
+                "but device mode requires a 'TVs and Limited Input devices' OAuth client."
+            ) from exc
+        if exc.code == 403 and error_name == "org_internal":
+            raise RuntimeError(
+                "Google blocked this OAuth client because the project is restricted to an organization. "
+                "Set the OAuth consent screen user type to External, or sign in with an account in that organization."
+            ) from exc
+        raise
+
+    device_code = payload["device_code"]
+    user_code = payload["user_code"]
+    verification_url = payload.get("verification_url") or payload.get("verification_uri")
+    interval = int(payload.get("interval", 5))
+    expires_in = int(payload.get("expires_in", 1800))
+
+    print("\n[yellow]Headless login mode:[/yellow]")
+    print(f"  Visit: {verification_url}")
+    print(f"  Code:  {user_code}")
+
+    deadline = time.time() + expires_in
+    poll_data = {
+        "client_id": client_id,
+        "client_secret": client_secret or "",
+        "device_code": device_code,
+        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+    }
+
+    while time.time() < deadline:
+        time.sleep(interval)
+        token_request = urllib.request.Request(
+            token_uri,
+            data=urllib.parse.urlencode(poll_data).encode(),
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        try:
+            with urllib.request.urlopen(token_request) as response:
+                token_payload = json.load(response)
+            access_token = token_payload["access_token"]
+            refresh_token = token_payload.get("refresh_token")
+            token = Credentials(
+                token=access_token,
+                refresh_token=refresh_token,
+                token_uri=token_uri,
+                client_id=client_id,
+                client_secret=client_secret,
+                scopes=SCOPES,
+            )
+            return token
+        except urllib.error.HTTPError as exc:
+            error_name = _extract_error_name(exc)
+
+            if error_name in {"authorization_pending", "slow_down"}:
+                if error_name == "slow_down":
+                    interval += 5
+                continue
+            if error_name == "access_denied":
+                raise RuntimeError(
+                    "Google blocked the authorization request. "
+                    "If the OAuth consent screen is in Testing, add this Google account to the Test users list. "
+                    "If the project is Internal, switch it to External or use an account inside the organization."
+                ) from exc
+            if error_name == "expired_token":
+                raise RuntimeError("Google device authorization expired. Please run setup again.")
+            raise RuntimeError(f"Google device authorization failed: {error_name or exc}")
+
+    raise RuntimeError("Google device authorization timed out. Please run setup again.")

src/connections/ics.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+
+from src.models.model import CalendarEvent
+
+
+def export_to_ics(event: CalendarEvent, output_path: str | None = None) -> str:
+    """Export a CalendarEvent to an .ics file. Returns the output file path."""
+    cal = event.to_ical()
+
+    if output_path is None:
+        safe_title = "".join(c if c.isalnum() or c in " -_" else "_" for c in event.title)
+        output_path = f"{safe_title.strip()}.ics"
+
+    path = Path(output_path)
+    path.write_bytes(cal.to_ical())
+    return str(path.resolve())