taskdog-client 0.18.1__py3-none-any.whl

taskdog_client/__init__.py

@@ -0,0 +1,31 @@
+"""HTTP and WebSocket client for Taskdog server.
+
+This package provides type-safe HTTP and WebSocket clients for communicating with
+the Taskdog API server. It handles authentication, error mapping,
+and response conversion to domain DTOs.
+"""
+
+from taskdog_client.analytics_client import AnalyticsClient
+from taskdog_client.audit_client import AuditClient
+from taskdog_client.base_client import BaseApiClient
+from taskdog_client.lifecycle_client import LifecycleClient
+from taskdog_client.notes_client import NotesClient
+from taskdog_client.query_client import QueryClient
+from taskdog_client.relationship_client import RelationshipClient
+from taskdog_client.task_client import TaskClient
+from taskdog_client.taskdog_api_client import TaskdogApiClient
+from taskdog_client.websocket import ConnectionState, WebSocketClient
+
+__all__ = [
+    "AnalyticsClient",
+    "AuditClient",
+    "BaseApiClient",
+    "ConnectionState",
+    "LifecycleClient",
+    "NotesClient",
+    "QueryClient",
+    "RelationshipClient",
+    "TaskClient",
+    "TaskdogApiClient",
+    "WebSocketClient",
+]

taskdog_client/analytics_client.py

@@ -0,0 +1,97 @@
+"""Analytics and optimization client."""
+
+from datetime import datetime
+
+from taskdog_client.base_client import BaseApiClient
+from taskdog_client.converters import (
+    convert_to_optimization_output,
+    convert_to_statistics_output,
+)
+from taskdog_core.application.dto.optimization_output import OptimizationOutput
+from taskdog_core.application.dto.statistics_output import StatisticsOutput
+
+
+class AnalyticsClient:
+    """Client for analytics and schedule optimization.
+
+    Operations:
+    - Calculate statistics
+    - Optimize schedules
+    - Get algorithm metadata
+    """
+
+    def __init__(self, base_client: BaseApiClient):
+        """Initialize analytics client.
+
+        Args:
+            base_client: Base API client for HTTP operations
+        """
+        self._base = base_client
+
+    def calculate_statistics(self, period: str = "all") -> StatisticsOutput:
+        """Calculate task statistics.
+
+        Args:
+            period: Time period (all, 7d, 30d)
+
+        Returns:
+            StatisticsOutput with statistics data
+
+        Raises:
+            TaskValidationError: If period is invalid
+        """
+        data = self._base._request_json("get", f"/api/v1/statistics?period={period}")
+        return convert_to_statistics_output(data)
+
+    def optimize_schedule(
+        self,
+        algorithm: str,
+        start_date: datetime | None,
+        max_hours_per_day: float,
+        force_override: bool = True,
+        task_ids: list[int] | None = None,
+        include_all_days: bool = False,
+    ) -> OptimizationOutput:
+        """Optimize task schedules.
+
+        Args:
+            algorithm: Algorithm name (required)
+            start_date: Optimization start date (None = server current time)
+            max_hours_per_day: Maximum hours per day (required)
+            force_override: Force override existing schedules
+            task_ids: Specific task IDs to optimize (None means all schedulable tasks)
+            include_all_days: If True, schedule tasks on weekends and holidays too (default: False)
+
+        Returns:
+            OptimizationOutput with optimization results
+
+        Raises:
+            TaskValidationError: If validation fails
+            TaskNotFoundException: If any specified task_id does not exist
+            NoSchedulableTasksError: If no tasks can be scheduled
+        """
+        payload: dict[str, str | float | bool | list[int] | None] = {
+            "algorithm": algorithm,
+            "start_date": start_date.isoformat() if start_date else None,
+            "max_hours_per_day": max_hours_per_day,
+            "force_override": force_override,
+            "include_all_days": include_all_days,
+        }
+
+        # Only include task_ids if it's not None
+        if task_ids is not None:
+            payload["task_ids"] = task_ids
+
+        data = self._base._request_json("post", "/api/v1/optimize", json=payload)
+        return convert_to_optimization_output(data)
+
+    def get_algorithm_metadata(self) -> list[tuple[str, str, str]]:
+        """Get available optimization algorithms.
+
+        Returns:
+            List of (name, display_name, description) tuples
+        """
+        data = self._base._request_json("get", "/api/v1/algorithms")
+        return [
+            (algo["name"], algo["display_name"], algo["description"]) for algo in data
+        ]

taskdog_client/audit_client.py

@@ -0,0 +1,120 @@
+"""Audit log client."""
+
+from datetime import datetime
+from typing import Any
+
+from taskdog_client.base_client import BaseApiClient
+from taskdog_core.application.dto.audit_log_dto import (
+    AuditLogListOutput,
+    AuditLogOutput,
+)
+
+
+class AuditClient:
+    """Client for audit log operations.
+
+    Operations:
+    - List audit logs with filtering
+    - Get single audit log by ID
+    """
+
+    def __init__(self, base_client: BaseApiClient):
+        """Initialize audit client.
+
+        Args:
+            base_client: Base API client for HTTP operations
+        """
+        self._base = base_client
+
+    def list_audit_logs(
+        self,
+        client_filter: str | None = None,
+        operation: str | None = None,
+        resource_type: str | None = None,
+        resource_id: int | None = None,
+        success: bool | None = None,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> AuditLogListOutput:
+        """List audit logs with optional filtering.
+
+        Args:
+            client_filter: Filter by client name
+            operation: Filter by operation type
+            resource_type: Filter by resource type
+            resource_id: Filter by resource ID
+            success: Filter by success status
+            start_date: Filter logs after this datetime
+            end_date: Filter logs before this datetime
+            limit: Maximum number of logs to return
+            offset: Number of logs to skip for pagination
+
+        Returns:
+            AuditLogListOutput with logs and pagination info
+        """
+        params: dict[str, str | int] = {"limit": limit, "offset": offset}
+
+        if client_filter is not None:
+            params["client"] = client_filter
+        if operation is not None:
+            params["operation"] = operation
+        if resource_type is not None:
+            params["resource_type"] = resource_type
+        if resource_id is not None:
+            params["resource_id"] = resource_id
+        if success is not None:
+            params["success"] = str(success).lower()
+        if start_date is not None:
+            params["start_date"] = start_date.isoformat()
+        if end_date is not None:
+            params["end_date"] = end_date.isoformat()
+
+        data = self._base._request_json("get", "/api/v1/audit-logs", params=params)
+        return self._convert_to_list_output(data)
+
+    def get_audit_log(self, log_id: int) -> AuditLogOutput:
+        """Get a single audit log entry by ID.
+
+        Args:
+            log_id: ID of the audit log entry to retrieve
+
+        Returns:
+            AuditLogOutput with the audit log details
+        """
+        data = self._base._request_json("get", f"/api/v1/audit-logs/{log_id}")
+        return self._convert_to_output(data)
+
+    def _convert_to_output(self, data: dict[str, Any]) -> AuditLogOutput:
+        """Convert API response to AuditLogOutput DTO."""
+        # Parse timestamp with error handling for malformed data
+        try:
+            timestamp = datetime.fromisoformat(data["timestamp"])
+        except (ValueError, KeyError):
+            # Fallback to current time if timestamp is invalid or missing
+            timestamp = datetime.now()
+
+        return AuditLogOutput(
+            id=data["id"],
+            timestamp=timestamp,
+            client_name=data.get("client_name"),
+            operation=data["operation"],
+            resource_type=data["resource_type"],
+            resource_id=data.get("resource_id"),
+            resource_name=data.get("resource_name"),
+            old_values=data.get("old_values"),
+            new_values=data.get("new_values"),
+            success=data["success"],
+            error_message=data.get("error_message"),
+        )
+
+    def _convert_to_list_output(self, data: dict[str, Any]) -> AuditLogListOutput:
+        """Convert API response to AuditLogListOutput DTO."""
+        logs = [self._convert_to_output(log) for log in data["logs"]]
+        return AuditLogListOutput(
+            logs=logs,
+            total_count=data["total_count"],
+            limit=data["limit"],
+            offset=data["offset"],
+        )

taskdog_client/base_client.py

@@ -0,0 +1,205 @@
+"""Base HTTP client infrastructure for Taskdog API."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from taskdog_core.application.dto.task_operation_output import TaskOperationOutput
+
+import httpx  # type: ignore[import-not-found]
+
+from taskdog_core.domain.exceptions.task_exceptions import (
+    AuthenticationError,
+    ServerConnectionError,
+    ServerError,
+    TaskNotFoundException,
+    TaskValidationError,
+)
+
+
+class BaseApiClient:
+    """Base HTTP client with error handling and lifecycle management.
+
+    Provides:
+    - HTTP client initialization and lifecycle
+    - Context manager support
+    - Error mapping to domain exceptions
+    - Safe request execution with connection handling
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:8000",
+        timeout: float = 30.0,
+        api_key: str | None = None,
+    ):
+        """Initialize base API client.
+
+        Args:
+            base_url: Base URL of the API server
+            timeout: Request timeout in seconds
+            api_key: API key for authentication (sent as X-Api-Key header)
+        """
+        self.base_url = base_url.rstrip("/")
+        self.client = httpx.Client(base_url=self.base_url, timeout=timeout)
+        self.client_id: str | None = None  # Set by WebSocket connection
+        self.api_key = api_key
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self.client.close()
+
+    def __enter__(self) -> BaseApiClient:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit."""
+        self.close()
+
+    def _extract_validation_error_detail(self, response: httpx.Response) -> str:
+        """Extract validation error detail from response.
+
+        Handles both simple {"detail": "message"} and FastAPI's Pydantic format:
+        {"detail": [{"loc": [...], "msg": "...", "type": "..."}]}
+
+        Args:
+            response: HTTP response with validation error
+
+        Returns:
+            Human-readable error message
+        """
+        try:
+            data = response.json()
+            detail = data.get("detail", "Validation error")
+
+            # Handle FastAPI's Pydantic validation error format (list of errors)
+            if isinstance(detail, list) and len(detail) > 0:
+                messages = []
+                for error in detail:
+                    if isinstance(error, dict):
+                        msg = error.get("msg", "")
+                        loc = error.get("loc", [])
+                        # Format: "field: message"
+                        field = loc[-1] if loc else "field"
+                        messages.append(f"{field}: {msg}")
+                    else:
+                        messages.append(str(error))
+                return "; ".join(messages)
+
+            return str(detail)
+        except (KeyError, TypeError, ValueError):
+            return "Validation error"
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Handle HTTP error responses.
+
+        Args:
+            response: HTTP response
+
+        Raises:
+            TaskNotFoundException: If status is 404
+            TaskValidationError: If status is 400 or 422
+            Exception: For other errors
+        """
+        if response.status_code == 404:
+            detail = response.json().get("detail", "Task not found")
+            raise TaskNotFoundException(detail)
+        if response.status_code in (400, 422):
+            detail = self._extract_validation_error_detail(response)
+            raise TaskValidationError(detail)
+        if response.status_code == 401:
+            raise AuthenticationError("Authentication failed. Check your API key.")
+        if response.status_code >= 500:
+            detail = "Server error occurred"
+            with contextlib.suppress(Exception):
+                detail = response.json().get("detail", detail)
+            raise ServerError(response.status_code, detail)
+        response.raise_for_status()
+
+    def lifecycle_operation(self, task_id: int, operation: str) -> TaskOperationOutput:
+        """Execute a lifecycle operation on a task.
+
+        Generic helper for lifecycle operations (start, complete, pause, etc.)
+        that follow the same pattern: POST to /api/v1/tasks/{id}/{operation}.
+
+        Args:
+            task_id: Task ID
+            operation: Operation name (e.g., "start", "complete", "archive")
+
+        Returns:
+            TaskOperationOutput with updated task data
+
+        Raises:
+            TaskNotFoundException: If task not found
+            TaskValidationError: If validation fails
+        """
+        from taskdog_client.converters import convert_to_task_operation_output
+
+        data = self._request_json("post", f"/api/v1/tasks/{task_id}/{operation}")
+        return convert_to_task_operation_output(data)
+
+    def _request_json(self, method: str, *args: Any, **kwargs: Any) -> Any:
+        """Execute HTTP request and return JSON response, handling errors.
+
+        Combines _safe_request + error check + JSON parsing into one call.
+
+        Args:
+            method: HTTP method name ('get', 'post', 'patch', 'delete', 'put')
+            *args: Positional arguments for the request
+            **kwargs: Keyword arguments for the request
+
+        Returns:
+            Parsed JSON response (dict, list, or primitive)
+
+        Raises:
+            ServerConnectionError: If connection to server fails
+            TaskNotFoundException: If status is 404
+            TaskValidationError: If status is 400 or 422
+            AuthenticationError: If status is 401
+            ServerError: If status >= 500
+        """
+        response = self._safe_request(method, *args, **kwargs)
+        if not response.is_success:
+            self._handle_error(response)
+        return response.json()
+
+    def _safe_request(self, method: str, *args: Any, **kwargs: Any) -> httpx.Response:
+        """Execute HTTP request with connection error handling.
+
+        Args:
+            method: HTTP method name ('get', 'post', 'patch', 'delete', 'put')
+            *args: Positional arguments for the request
+            **kwargs: Keyword arguments for the request
+
+        Returns:
+            HTTP response
+
+        Raises:
+            ServerConnectionError: If connection to server fails
+            TaskNotFoundException: If status is 404
+            TaskValidationError: If status is 400
+            Exception: For other errors
+        """
+        try:
+            headers = kwargs.get("headers", {})
+
+            # Add X-Client-ID header if client_id is set
+            if self.client_id:
+                headers["X-Client-ID"] = self.client_id
+
+            # Add X-Api-Key header if api_key is set
+            if self.api_key:
+                headers["X-Api-Key"] = self.api_key
+
+            if headers:
+                kwargs["headers"] = headers
+
+            request_method: Callable[..., httpx.Response] = getattr(self.client, method)
+            return request_method(*args, **kwargs)
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.RequestError) as e:
+            raise ServerConnectionError(self.base_url, e) from e

taskdog_client/bulk_client.py

@@ -0,0 +1,90 @@
+"""Bulk operations client for batch task processing."""
+
+from typing import Any
+
+from taskdog_client.base_client import BaseApiClient
+from taskdog_client.converters import convert_to_task_operation_output
+from taskdog_core.application.dto.bulk_operation_output import (
+    BulkOperationOutput,
+    BulkTaskResultOutput,
+)
+
+
+class BulkClient:
+    """Client for bulk task operations.
+
+    Sends multiple task IDs in a single request for batch processing.
+    """
+
+    def __init__(self, base_client: BaseApiClient):
+        self._base = base_client
+
+    def _bulk_operation(
+        self, task_ids: list[int], operation: str
+    ) -> BulkOperationOutput:
+        """Execute a bulk operation.
+
+        Args:
+            task_ids: List of task IDs to operate on
+            operation: Operation name (e.g., "start", "complete", "archive")
+
+        Returns:
+            BulkOperationOutput with per-task results
+        """
+        data = self._base._request_json(
+            "post",
+            f"/api/v1/tasks/bulk/{operation}",
+            json={"task_ids": task_ids},
+        )
+        return self._parse_bulk_response(data)
+
+    def _parse_bulk_response(self, data: dict[str, Any]) -> BulkOperationOutput:
+        """Parse bulk operation response JSON into DTO."""
+        if "results" not in data:
+            raise ValueError("Invalid bulk operation response: missing 'results' key")
+        results: list[BulkTaskResultOutput] = []
+        for item in data["results"]:
+            task = None
+            if item.get("task") is not None:
+                task = convert_to_task_operation_output(item["task"])
+            results.append(
+                BulkTaskResultOutput(
+                    task_id=item["task_id"],
+                    success=item["success"],
+                    task=task,
+                    error=item.get("error"),
+                )
+            )
+        return BulkOperationOutput(results=results)
+
+    def bulk_start(self, task_ids: list[int]) -> BulkOperationOutput:
+        """Start multiple tasks."""
+        return self._bulk_operation(task_ids, "start")
+
+    def bulk_complete(self, task_ids: list[int]) -> BulkOperationOutput:
+        """Complete multiple tasks."""
+        return self._bulk_operation(task_ids, "complete")
+
+    def bulk_pause(self, task_ids: list[int]) -> BulkOperationOutput:
+        """Pause multiple tasks."""
+        return self._bulk_operation(task_ids, "pause")
+
+    def bulk_cancel(self, task_ids: list[int]) -> BulkOperationOutput:
+        """Cancel multiple tasks."""
+        return self._bulk_operation(task_ids, "cancel")
+
+    def bulk_reopen(self, task_ids: list[int]) -> BulkOperationOutput:
+        """Reopen multiple tasks."""
+        return self._bulk_operation(task_ids, "reopen")
+
+    def bulk_archive(self, task_ids: list[int]) -> BulkOperationOutput:
+        """Archive multiple tasks."""
+        return self._bulk_operation(task_ids, "archive")
+
+    def bulk_restore(self, task_ids: list[int]) -> BulkOperationOutput:
+        """Restore multiple tasks."""
+        return self._bulk_operation(task_ids, "restore")
+
+    def bulk_delete(self, task_ids: list[int]) -> BulkOperationOutput:
+        """Delete multiple tasks permanently."""
+        return self._bulk_operation(task_ids, "delete")

taskdog_client/converters/__init__.py

@@ -0,0 +1,31 @@
+"""DTO converters for API responses.
+
+Converts JSON responses from API to taskdog-core DTOs.
+Single source of truth for all API-to-DTO transformations.
+"""
+
+from .exceptions import ConversionError
+from .gantt_converters import convert_to_gantt_output
+from .optimization_converters import convert_to_optimization_output
+from .statistics_converters import convert_to_statistics_output
+from .tag_converters import convert_to_tag_statistics_output
+from .task_converters import (
+    convert_to_get_task_by_id_output,
+    convert_to_get_task_detail_output,
+    convert_to_task_list_output,
+    convert_to_task_operation_output,
+    convert_to_update_task_output,
+)
+
+__all__ = [
+    "ConversionError",
+    "convert_to_gantt_output",
+    "convert_to_get_task_by_id_output",
+    "convert_to_get_task_detail_output",
+    "convert_to_optimization_output",
+    "convert_to_statistics_output",
+    "convert_to_tag_statistics_output",
+    "convert_to_task_list_output",
+    "convert_to_task_operation_output",
+    "convert_to_update_task_output",
+]