cupt 0.6.1__py3-none-any.whl

cupt/__init__.py

@@ -0,0 +1,39 @@
+"""
+CUPT — ClickUp Task Management CLI and Python library.
+
+Use as a CLI:
+    $ cupt list --tag urgent
+
+Use as a library:
+    from cupt import ClickUpClient, TaskService
+
+    client = ClickUpClient("pk_xxxxx")              # personal API token
+    service = TaskService(client)
+    tasks = service.list_tasks(team_id="123", tags=["urgent"])
+
+Public exports are intentionally limited to the API client, services, and
+typed exceptions. Internal helpers (config, CLI commands, formatting) are
+not part of the public API and may change between releases.
+"""
+
+from cupt.api import ClickUpClient
+from cupt.exceptions import APIError, AuthError, ConfigError, CuptError
+from cupt.services.note_service import NoteService
+from cupt.services.task_service import TaskService
+from cupt.services.time_service import TimeService
+
+__version__ = "0.6.1"
+__author__ = "Matthew Nuzum"
+__email__ = "matthew@nuzum.com"
+
+__all__ = [
+    "ClickUpClient",
+    "TaskService",
+    "TimeService",
+    "NoteService",
+    "CuptError",
+    "APIError",
+    "AuthError",
+    "ConfigError",
+    "__version__",
+]

cupt/ai.py

@@ -0,0 +1,82 @@
+"""
+Local AI backend abstraction for CUPT.
+
+Provider priority:
+  1. Apple Intelligence (apple-fm-sdk, macOS 26+)
+
+Future providers (not yet implemented):
+  2. Windows Copilot+ (WinRT Microsoft.Windows.AI)
+  3. Ollama (http://localhost:11434)
+"""
+
+import asyncio
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_SYSTEM_INSTRUCTIONS = (
+    "You are a concise assistant helping a professional complete task management notes. "
+    "Write clear, brief, first-person completion notes. No preamble or explanation."
+)
+
+
+def get_ai_suggestion(prompt: str) -> Optional[str]:
+    """
+    Try available local AI backends and return a suggestion, or None if unavailable.
+
+    Returns None silently when no provider is found — callers are responsible
+    for surfacing a user-facing message.
+    """
+    result = _try_apple_intelligence(prompt)
+    if result is not None:
+        return result
+
+    # Future: _try_windows_copilot(prompt)
+    # Future: _try_ollama(prompt)
+
+    return None
+
+
+def is_ai_available() -> bool:
+    """Return True if at least one local AI provider is available."""
+    return _apple_intelligence_available()
+
+
+# ------------------------------------------------------------------
+# Apple Intelligence
+# ------------------------------------------------------------------
+
+
+def _apple_intelligence_available() -> bool:
+    try:
+        import apple_fm_sdk as fm
+
+        available, _ = fm.SystemLanguageModel().is_available()
+        return available
+    except ImportError:
+        return False
+    except Exception:
+        return False
+
+
+def _try_apple_intelligence(prompt: str) -> Optional[str]:
+    try:
+        import apple_fm_sdk as fm
+
+        model = fm.SystemLanguageModel()
+        available, reason = model.is_available()
+        if not available:
+            logger.debug("Apple Intelligence not available: %s", reason)
+            return None
+
+        session = fm.LanguageModelSession(instructions=_SYSTEM_INSTRUCTIONS)
+        result = asyncio.run(session.respond(prompt))
+        return result.strip() if result else None
+
+    except ImportError:
+        logger.debug("apple-fm-sdk not installed")
+        return None
+    except Exception as e:
+        logger.debug("Apple Intelligence error: %s", e)
+        return None

cupt/api.py

@@ -0,0 +1,290 @@
+"""
+ClickUp API client
+"""
+
+import json
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from cupt.exceptions import APIError
+
+logger = logging.getLogger(__name__)
+
+
+class ClickUpClient:
+    """ClickUp API client with connection pooling, retry logic, and request timeout."""
+
+    BASE_URL = "https://api.clickup.com/api/v2"
+    TIMEOUT = 10  # seconds — prevents the CLI from hanging on a slow/unresponsive API
+
+    def __init__(self, access_token: str):
+        self.access_token = access_token
+        self.session = requests.Session()
+        # Only Authorization on the session. Content-Type is set per-request
+        # inside _make_request so it never leaks into multipart uploads
+        # (which generate their own Content-Type with a boundary).
+        self.session.headers.update({"Authorization": self.access_token})
+
+        # Retry transient server errors with exponential backoff.
+        # 429 included so ClickUp rate limits trigger backoff (urllib3's
+        # Retry honors the Retry-After header automatically).
+        _retry = Retry(
+            total=3,
+            backoff_factor=0.5,
+            status_forcelist=[429, 500, 502, 503, 504],
+            respect_retry_after_header=True,
+            raise_on_status=False,
+        )
+        # Pool keeps persistent TCP connections open across requests in the
+        # same process (the default pool size of 10 is fine here).
+        _adapter = HTTPAdapter(max_retries=_retry)
+        self.session.mount("https://", _adapter)
+        self.session.mount("http://", _adapter)
+
+    def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[Dict] = None,
+        params: Optional[Dict] = None,
+    ) -> Dict[str, Any]:
+        """Make an API request with error handling, timeout, and retry."""
+        url = f"{self.BASE_URL}/{endpoint.lstrip('/')}"
+        logger.debug("%s %s params=%s", method.upper(), url, params)
+
+        # Per-request JSON header only on methods that carry a JSON body.
+        json_headers = {"Content-Type": "application/json"}
+        try:
+            if method.upper() == "GET":
+                response = self.session.get(url, params=params, timeout=self.TIMEOUT)
+            elif method.upper() == "POST":
+                response = self.session.post(
+                    url, json=data, headers=json_headers, timeout=self.TIMEOUT
+                )
+            elif method.upper() == "PUT":
+                response = self.session.put(
+                    url, json=data, headers=json_headers, timeout=self.TIMEOUT
+                )
+            elif method.upper() == "DELETE":
+                response = self.session.delete(url, timeout=self.TIMEOUT)
+            else:
+                raise ValueError(f"Unsupported HTTP method: {method}")
+
+            response.raise_for_status()
+            return response.json()
+
+        except requests.exceptions.HTTPError as e:
+            error_msg = f"HTTP {e.response.status_code}"
+            if e.response.text:
+                try:
+                    error_data = e.response.json()
+                    error_msg += f": {error_data.get('err', '')}"
+                except json.JSONDecodeError:
+                    error_msg += f": {e.response.text[:200]}"
+            logger.debug("API error on %s %s: %s", method, endpoint, error_msg)
+            raise APIError(error_msg)
+        except requests.exceptions.Timeout:
+            msg = f"Request timed out after {self.TIMEOUT}s: {endpoint}"
+            logger.debug(msg)
+            raise APIError(msg)
+        except requests.exceptions.RequestException as e:
+            msg = f"Request failed: {e}"
+            logger.debug(msg)
+            raise APIError(msg)
+        except json.JSONDecodeError as e:
+            msg = f"Invalid JSON response: {e}"
+            logger.debug(msg)
+            raise APIError(msg)
+
+    # ------------------------------------------------------------------
+    # Auth / user
+    # ------------------------------------------------------------------
+
+    def get_user(self) -> Dict[str, Any]:
+        return self._make_request("GET", "/user")
+
+    def get_teams(self) -> List[Dict[str, Any]]:
+        return self._make_request("GET", "/team").get("teams", [])
+
+    # ------------------------------------------------------------------
+    # Tasks
+    # ------------------------------------------------------------------
+
+    def get_team_tasks(
+        self, team_id: str, filters: Optional[Dict] = None
+    ) -> List[Dict[str, Any]]:
+        params: Dict = {}
+        if filters:
+            params.update(filters)
+        return self._make_request("GET", f"/team/{team_id}/task", params=params).get(
+            "tasks", []
+        )
+
+    def get_tasks_by_ids(
+        self, team_id: str, task_ids: List[str]
+    ) -> List[Dict[str, Any]]:
+        """Bulk-fetch up to 100 tasks by ID."""
+        if not task_ids:
+            return []
+        params = {"ids[]": task_ids[:100], "include_subtasks": "true"}
+        return self._make_request("GET", f"/team/{team_id}/task", params=params).get(
+            "tasks", []
+        )
+
+    def get_task(self, task_id: str) -> Dict[str, Any]:
+        return self._make_request("GET", f"/task/{task_id}")
+
+    def get_task_children(
+        self, team_id: str, parent_id: str, params: Optional[Dict] = None
+    ) -> List[Dict[str, Any]]:
+        """Fetch direct subtasks of a task."""
+        p: Dict = {"parent": parent_id}
+        if params:
+            p.update(params)
+        return self._make_request("GET", f"/team/{team_id}/task", params=p).get(
+            "tasks", []
+        )
+
+    def update_task(self, task_id: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        return self._make_request("PUT", f"/task/{task_id}", data=data)
+
+    def add_task_tag(self, task_id: str, tag_name: str) -> Dict[str, Any]:
+        return self._make_request("POST", f"/task/{task_id}/tag/{tag_name}")
+
+    def remove_task_tag(self, task_id: str, tag_name: str) -> Dict[str, Any]:
+        return self._make_request("DELETE", f"/task/{task_id}/tag/{tag_name}")
+
+    def upload_task_attachment(
+        self, task_id: str, file_path: str, filename: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Upload a file as a task attachment.
+
+        Bypasses the shared session because that session sets
+        Content-Type: application/json, which prevents `requests` from
+        generating the multipart boundary header and causes the server to
+        receive a malformed body (resulting in corrupted attachments).
+        """
+        import os
+
+        url = f"{self.BASE_URL}/task/{task_id}/attachment"
+        name = filename or os.path.basename(file_path)
+        headers = {"Authorization": self.access_token}
+
+        try:
+            with open(file_path, "rb") as fh:
+                response = requests.post(
+                    url,
+                    headers=headers,
+                    files={"attachment": (name, fh)},
+                    timeout=60,  # uploads can legitimately take longer than reads
+                )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as e:
+            msg = f"HTTP {e.response.status_code}: {e.response.text[:200]}"
+            raise APIError(msg)
+        except requests.exceptions.RequestException as e:
+            raise APIError(f"Upload failed: {e}")
+
+    # ------------------------------------------------------------------
+    # Statuses
+    # ------------------------------------------------------------------
+
+    def get_list_statuses(self, list_id: str) -> List[Dict[str, Any]]:
+        return self._make_request("GET", f"/list/{list_id}").get("statuses", [])
+
+    def get_space_statuses(self, space_id: str) -> List[Dict[str, Any]]:
+        return self._make_request("GET", f"/space/{space_id}").get("statuses", [])
+
+    # ------------------------------------------------------------------
+    # Comments / notes
+    # ------------------------------------------------------------------
+
+    def get_task_comments(self, task_id: str) -> List[Dict[str, Any]]:
+        return self._make_request("GET", f"/task/{task_id}/comment").get("comments", [])
+
+    def add_task_comment(
+        self, task_id: str, comment_text: str, notify_all: bool = False
+    ) -> Dict[str, Any]:
+        data = {
+            "comment_text": comment_text,
+            "notify_all": notify_all,
+            "assignee": None,
+        }
+        return self._make_request("POST", f"/task/{task_id}/comment", data=data)
+
+    # ------------------------------------------------------------------
+    # Time tracking
+    # ------------------------------------------------------------------
+
+    def start_timer(
+        self, team_id: str, task_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        data: Dict = {}
+        if task_id:
+            data["task_id"] = task_id
+            data["tid"] = task_id
+        return self._make_request(
+            "POST", f"/team/{team_id}/time_entries/start", data=data
+        )
+
+    def stop_timer(self, team_id: str) -> Dict[str, Any]:
+        return self._make_request("POST", f"/team/{team_id}/time_entries/stop")
+
+    def get_running_timer(self, team_id: str) -> Optional[Dict[str, Any]]:
+        try:
+            return self._make_request(
+                "GET", f"/team/{team_id}/time_entries/current"
+            ).get("data")
+        except Exception:
+            return None
+
+    def get_time_entries(
+        self,
+        team_id: str,
+        start_date: int,
+        end_date: int,
+        user_id: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """Fetch time entries within a date range (timestamps in ms)."""
+        params: Dict = {"start_date": start_date, "end_date": end_date}
+        if user_id:
+            params["assignee"] = user_id
+        return self._make_request(
+            "GET", f"/team/{team_id}/time_entries", params=params
+        ).get("data", [])
+
+    def add_time_entry(
+        self,
+        team_id: str,
+        task_id: str,
+        duration: int,
+        description: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        now_ms = int(datetime.now().timestamp() * 1000)
+        data: Dict = {
+            "task_id": task_id,
+            "tid": task_id,
+            "duration": duration,
+            "start": now_ms - duration,
+            "end": now_ms,
+        }
+        if description:
+            data["description"] = description
+        return self._make_request("POST", f"/team/{team_id}/time_entries", data=data)
+
+    # ------------------------------------------------------------------
+    # Hierarchy
+    # ------------------------------------------------------------------
+
+    def get_spaces(self, team_id: str) -> List[Dict[str, Any]]:
+        return self._make_request("GET", f"/team/{team_id}/space").get("spaces", [])
+
+    def get_lists(self, space_id: str) -> List[Dict[str, Any]]:
+        return self._make_request("GET", f"/space/{space_id}/list").get("lists", [])

cupt/attachments.py

@@ -0,0 +1,145 @@
+import os
+
+import click
+import requests
+
+from cupt.context import get_client_context
+from cupt.utils import print_error, print_success, print_warning
+
+
+def _human_size(n_bytes):
+    if not n_bytes:
+        return "-"
+    n = float(n_bytes)
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.1f}{unit}" if unit != "B" else f"{int(n)}B"
+        n /= 1024
+    return f"{n:.1f}GB"
+
+
+def _resolve(attachments, selector):
+    """Find an attachment by 1-based index or substring of title."""
+    if selector.isdigit():
+        idx = int(selector) - 1
+        if 0 <= idx < len(attachments):
+            return attachments[idx]
+        return None
+    needle = selector.lower()
+    matches = [a for a in attachments if needle in (a.get("title", "")).lower()]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        raise click.ClickException(
+            f"'{selector}' matches {len(matches)} attachments — be more specific or use an index"
+        )
+    return None
+
+
+@click.group(name="attach")
+def attach_group():
+    """List, download, and upload task attachments"""
+    pass
+
+
+@attach_group.command("list")
+@click.argument("task_id")
+def list_attachments(task_id):
+    """List attachments on a task"""
+    _, client, _ = get_client_context(need_team=False)
+    if not client:
+        return
+
+    try:
+        task = client.get_task(task_id)
+    except Exception as e:
+        print_error(f"Failed to fetch task: {e}")
+        return
+
+    attachments = task.get("attachments") or []
+    if not attachments:
+        print_warning(f"No attachments on {task_id}.")
+        return
+
+    click.echo(f"\n{'#':<4} {'Size':<10} {'Name'}")
+    click.echo("-" * 60)
+    for i, a in enumerate(attachments, start=1):
+        click.echo(
+            f"{i:<4} {_human_size(a.get('size')):<10} {a.get('title', '(untitled)')}"
+        )
+
+
+@attach_group.command("get")
+@click.argument("task_id")
+@click.argument("selector")
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(),
+    help="Save path (default: original filename in current dir)",
+)
+def get_attachment(task_id, selector, output):
+    """Download an attachment by 1-based index or filename substring"""
+    _, client, _ = get_client_context(need_team=False)
+    if not client:
+        return
+
+    try:
+        task = client.get_task(task_id)
+    except Exception as e:
+        print_error(f"Failed to fetch task: {e}")
+        return
+
+    attachments = task.get("attachments") or []
+    if not attachments:
+        print_warning(f"No attachments on {task_id}.")
+        return
+
+    target = _resolve(attachments, selector)
+    if not target:
+        print_error(f"No attachment matches '{selector}'.")
+        return
+
+    url = target.get("url")
+    if not url:
+        print_error("Attachment has no download URL.")
+        return
+
+    # No auth header — these are pre-signed S3 URLs; sending Authorization
+    # can invalidate the signature.
+    try:
+        response = requests.get(url, timeout=60, stream=True)
+        response.raise_for_status()
+    except requests.exceptions.RequestException as e:
+        print_error(f"Download failed: {e}")
+        return
+
+    out_path = output or target.get("title") or "attachment.bin"
+    try:
+        with open(out_path, "wb") as fh:
+            for chunk in response.iter_content(chunk_size=64 * 1024):
+                if chunk:
+                    fh.write(chunk)
+    except OSError as e:
+        print_error(f"Could not write to {out_path}: {e}")
+        return
+
+    print_success(f"Downloaded {target.get('title')} -> {out_path}")
+
+
+@attach_group.command("add")
+@click.argument("task_id")
+@click.argument("file_path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--name", help="Override the filename stored on ClickUp")
+def add_attachment(task_id, file_path, name):
+    """Upload a file as a task attachment"""
+    _, client, _ = get_client_context(need_team=False)
+    if not client:
+        return
+
+    try:
+        result = client.upload_task_attachment(task_id, file_path, name)
+        title = result.get("title") or name or os.path.basename(file_path)
+        print_success(f"Attached '{title}' to {task_id}")
+    except Exception as e:
+        print_error(f"Failed to upload attachment: {e}")