trackerkit 0.3.0__py3-none-any.whl

trackerkit/__init__.py

@@ -0,0 +1,81 @@
+"""Public package entrypoint for trackerkit."""
+
+from .contracts.auth import (
+    AsanaAuthConfig,
+    JiraAuthConfig,
+    ProviderAuthConfig,
+    YandexTrackerAuthConfig,
+)
+from .domain import (
+    AuthenticationError,
+    Comment,
+    ConfigurationError,
+    ConnectionDiagnostic,
+    ConnectionErrorKind,
+    CreateCommentInput,
+    CreateProjectInput,
+    CreateRelationInput,
+    CreateTaskInput,
+    JiraContainsMode,
+    JiraLinkTypeMapping,
+    JiraRelationMappingConfig,
+    Project,
+    Provider,
+    ProviderCapabilityError,
+    ProviderError,
+    Relation,
+    RelationMappingConfig,
+    RelationType,
+    Status,
+    Task,
+    TaskQuery,
+    TrackerClientError,
+    TrackerKitError,
+    UpdateProjectInput,
+    UpdateRelationInput,
+    UpdateTaskInput,
+    User,
+    Workspace,
+    YandexTrackerRelationMapping,
+    YandexTrackerRelationMappingConfig,
+)
+from .tracker_client import TrackerClient
+
+__all__ = [
+    "AsanaAuthConfig",
+    "AuthenticationError",
+    "Comment",
+    "ConfigurationError",
+    "ConnectionDiagnostic",
+    "ConnectionErrorKind",
+    "CreateCommentInput",
+    "CreateProjectInput",
+    "CreateRelationInput",
+    "CreateTaskInput",
+    "JiraAuthConfig",
+    "JiraContainsMode",
+    "JiraLinkTypeMapping",
+    "JiraRelationMappingConfig",
+    "Project",
+    "Provider",
+    "ProviderAuthConfig",
+    "ProviderCapabilityError",
+    "ProviderError",
+    "Relation",
+    "RelationMappingConfig",
+    "RelationType",
+    "Status",
+    "Task",
+    "TaskQuery",
+    "TrackerClient",
+    "TrackerClientError",
+    "TrackerKitError",
+    "UpdateProjectInput",
+    "UpdateRelationInput",
+    "UpdateTaskInput",
+    "User",
+    "Workspace",
+    "YandexTrackerAuthConfig",
+    "YandexTrackerRelationMapping",
+    "YandexTrackerRelationMappingConfig",
+]

trackerkit/contracts/__init__.py

@@ -0,0 +1,35 @@
+from trackerkit.contracts.auth import (
+    AsanaAuthConfig,
+    JiraAuthConfig,
+    ProviderAuthConfig,
+    YandexTrackerAuthConfig,
+)
+from trackerkit.contracts.comments import CommentCapability
+from trackerkit.contracts.connection import ConnectionCapability
+from trackerkit.contracts.projects import (
+    ProjectReadCapability,
+    ProjectWriteCapability,
+    WorkspaceCapability,
+)
+from trackerkit.contracts.relations import RelationCapability
+from trackerkit.contracts.task_tracker_client import TaskTrackerClient
+from trackerkit.contracts.tasks import TaskReadCapability, TaskWriteCapability
+from trackerkit.contracts.users import UserCapability
+
+__all__ = [
+    "AsanaAuthConfig",
+    "CommentCapability",
+    "ConnectionCapability",
+    "JiraAuthConfig",
+    "ProjectReadCapability",
+    "ProjectWriteCapability",
+    "ProviderAuthConfig",
+    "RelationCapability",
+    "TaskReadCapability",
+    "TaskTrackerClient",
+    "TaskWriteCapability",
+    "UserCapability",
+    "WorkspaceCapability",
+    "YandexTrackerAuthConfig",
+]
+

trackerkit/contracts/auth.py

@@ -0,0 +1,91 @@
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from trackerkit.domain.enums import Provider
+from trackerkit.domain.errors import ConfigurationError
+
+
+class ProviderAuthConfig(BaseModel):
+    """Base auth config shared by all provider-specific auth models."""
+
+    # `extra="ignore"` lets the facade pass provider-agnostic kwargs
+    # (e.g. `max_retries`) without leaking provider checks into it.
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    provider: Provider
+    timeout_seconds: float = Field(default=5.0, gt=0)
+
+
+class JiraAuthConfig(ProviderAuthConfig):
+    """Jira auth data.
+
+    Expected fields:
+    - `base_url`
+    - exactly one of `access_token` or `api_token`
+    - optional `max_retries`
+    """
+
+    provider: Provider = Provider.JIRA
+    base_url: str
+    email: str | None = None
+    api_token: str | None = None
+    access_token: str | None = None
+    max_retries: int = Field(default=2, ge=0)
+
+    @model_validator(mode="after")
+    def validate_auth(self) -> "JiraAuthConfig":
+        if not self.api_token and not self.access_token:
+            raise ConfigurationError(
+                "JiraAuthConfig requires either api_token or access_token."
+            )
+        if self.api_token and self.access_token:
+            raise ConfigurationError(
+                "JiraAuthConfig expects only one of api_token or access_token."
+            )
+        return self
+
+
+class YandexTrackerAuthConfig(ProviderAuthConfig):
+    """Yandex Tracker auth data.
+
+    Expected fields:
+    - exactly one of `token` or `iam_token`
+    - exactly one of `org_id` or `cloud_org_id`
+    """
+
+    provider: Provider = Provider.YANDEX_TRACKER
+    token: str | None = None
+    iam_token: str | None = None
+    org_id: str | None = None
+    cloud_org_id: str | None = None
+
+    @model_validator(mode="after")
+    def validate_auth(self) -> "YandexTrackerAuthConfig":
+        if not self.token and not self.iam_token:
+            raise ConfigurationError(
+                "YandexTrackerAuthConfig requires either token or iam_token."
+            )
+        if self.token and self.iam_token:
+            raise ConfigurationError(
+                "YandexTrackerAuthConfig expects only one of token or iam_token."
+            )
+        if not self.org_id and not self.cloud_org_id:
+            raise ConfigurationError(
+                "YandexTrackerAuthConfig requires either org_id or cloud_org_id."
+            )
+        if self.org_id and self.cloud_org_id:
+            raise ConfigurationError(
+                "YandexTrackerAuthConfig expects only one of org_id or cloud_org_id."
+            )
+        return self
+
+
+class AsanaAuthConfig(ProviderAuthConfig):
+    """Asana auth data.
+
+    Expected fields:
+    - `access_token`
+    """
+
+    provider: Provider = Provider.ASANA
+    access_token: str
+

trackerkit/contracts/comments.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+
+from trackerkit.domain.models import Comment, CreateCommentInput
+
+
+class CommentCapability(ABC):
+    @abstractmethod
+    async def list_comments(self, task_id: str) -> list[Comment]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def create_comment(self, payload: CreateCommentInput) -> Comment:
+        raise NotImplementedError
+

trackerkit/contracts/connection.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+
+from trackerkit.domain.models import ConnectionDiagnostic
+
+
+class ConnectionCapability(ABC):
+    @abstractmethod
+    async def check_connection(self) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_connection_diagnostic(self) -> ConnectionDiagnostic:
+        raise NotImplementedError
+

trackerkit/contracts/projects.py

@@ -0,0 +1,43 @@
+from abc import ABC, abstractmethod
+
+from trackerkit.domain.models import (
+    CreateProjectInput,
+    Project,
+    UpdateProjectInput,
+    Workspace,
+)
+
+
+class WorkspaceCapability(ABC):
+    @abstractmethod
+    async def list_workspaces(self) -> list[Workspace]:
+        raise NotImplementedError
+
+
+class ProjectReadCapability(ABC):
+    @abstractmethod
+    async def get_project(self, project_id: str) -> Project:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def list_projects(self, workspace_id: str | None = None) -> list[Project]:
+        raise NotImplementedError
+
+
+class ProjectWriteCapability(ABC):
+    @abstractmethod
+    async def create_project(self, payload: CreateProjectInput) -> Project:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def update_project(
+        self,
+        project_id: str,
+        payload: UpdateProjectInput,
+    ) -> Project:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_project(self, project_id: str) -> None:
+        raise NotImplementedError
+

trackerkit/contracts/relations.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+
+from trackerkit.domain.models import (
+    CreateRelationInput,
+    Relation,
+    UpdateRelationInput,
+)
+
+
+class RelationCapability(ABC):
+    @abstractmethod
+    async def list_relations(self, task_id: str) -> list[Relation]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def create_relation(self, payload: CreateRelationInput) -> Relation:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def update_relation(
+        self,
+        relation_id: str,
+        payload: UpdateRelationInput,
+    ) -> Relation:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_relation(self, relation_id: str) -> None:
+        raise NotImplementedError
+

trackerkit/contracts/task_tracker_client.py

@@ -0,0 +1,25 @@
+from trackerkit.contracts.comments import CommentCapability
+from trackerkit.contracts.connection import ConnectionCapability
+from trackerkit.contracts.projects import (
+    ProjectReadCapability,
+    ProjectWriteCapability,
+    WorkspaceCapability,
+)
+from trackerkit.contracts.relations import RelationCapability
+from trackerkit.contracts.tasks import TaskReadCapability, TaskWriteCapability
+from trackerkit.contracts.users import UserCapability
+
+
+class TaskTrackerClient(
+    ConnectionCapability,
+    TaskReadCapability,
+    TaskWriteCapability,
+    WorkspaceCapability,
+    ProjectReadCapability,
+    ProjectWriteCapability,
+    UserCapability,
+    CommentCapability,
+    RelationCapability,
+):
+    """Unified async port composed from small capability contracts."""
+

trackerkit/contracts/tasks.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+
+from trackerkit.domain.models import CreateTaskInput, Task, TaskQuery, UpdateTaskInput
+
+
+class TaskReadCapability(ABC):
+    @abstractmethod
+    async def get_task(self, task_id: str) -> Task:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def list_tasks(self, query: TaskQuery | None = None) -> list[Task]:
+        raise NotImplementedError
+
+
+class TaskWriteCapability(ABC):
+    @abstractmethod
+    async def create_task(self, payload: CreateTaskInput) -> Task:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def update_task(self, task_id: str, payload: UpdateTaskInput) -> Task:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_task(self, task_id: str) -> None:
+        raise NotImplementedError
+

trackerkit/contracts/users.py

@@ -0,0 +1,10 @@
+from abc import ABC, abstractmethod
+
+from trackerkit.domain.models import User
+
+
+class UserCapability(ABC):
+    @abstractmethod
+    async def list_users(self) -> list[User]:
+        raise NotImplementedError
+

trackerkit/domain/__init__.py

@@ -0,0 +1,70 @@
+from trackerkit.domain.enums import ConnectionErrorKind, Provider, RelationType
+from trackerkit.domain.errors import (
+    AuthenticationError,
+    ConfigurationError,
+    ProviderCapabilityError,
+    ProviderError,
+    TrackerClientError,
+    TrackerKitError,
+)
+from trackerkit.domain.models import (
+    Comment,
+    ConnectionDiagnostic,
+    CreateCommentInput,
+    CreateProjectInput,
+    CreateRelationInput,
+    CreateTaskInput,
+    Project,
+    Relation,
+    Status,
+    Task,
+    TaskQuery,
+    UpdateProjectInput,
+    UpdateRelationInput,
+    UpdateTaskInput,
+    User,
+    Workspace,
+)
+from trackerkit.domain.relation_mapping import (
+    JiraContainsMode,
+    JiraLinkTypeMapping,
+    JiraRelationMappingConfig,
+    RelationMappingConfig,
+    YandexTrackerRelationMapping,
+    YandexTrackerRelationMappingConfig,
+)
+
+__all__ = [
+    "AuthenticationError",
+    "Comment",
+    "ConfigurationError",
+    "ConnectionDiagnostic",
+    "ConnectionErrorKind",
+    "CreateCommentInput",
+    "CreateProjectInput",
+    "CreateRelationInput",
+    "CreateTaskInput",
+    "JiraContainsMode",
+    "JiraLinkTypeMapping",
+    "JiraRelationMappingConfig",
+    "Project",
+    "Provider",
+    "ProviderCapabilityError",
+    "ProviderError",
+    "Relation",
+    "RelationMappingConfig",
+    "RelationType",
+    "Status",
+    "Task",
+    "TaskQuery",
+    "TrackerClientError",
+    "TrackerKitError",
+    "UpdateProjectInput",
+    "UpdateRelationInput",
+    "UpdateTaskInput",
+    "User",
+    "Workspace",
+    "YandexTrackerRelationMapping",
+    "YandexTrackerRelationMappingConfig",
+]
+

trackerkit/domain/enums.py

@@ -0,0 +1,28 @@
+from enum import Enum
+
+
+class Provider(str, Enum):
+    JIRA = "jira"
+    YANDEX_TRACKER = "yandex_tracker"
+    ASANA = "asana"
+
+
+class RelationType(str, Enum):
+    RELATES = "relates"
+    BLOCKS = "blocks"
+    CONTAINS = "contains"
+
+
+class ConnectionErrorKind(str, Enum):
+    """Stable taxonomy of connection-check failure reasons.
+
+    `ConnectionDiagnostic.error_kind` uses these values; the string base
+    keeps backward compatibility with callers that compare against literals
+    like ``"authentication"``.
+    """
+
+    AUTHENTICATION = "authentication"
+    CONFIGURATION = "configuration"
+    CAPABILITY = "capability"
+    PROVIDER = "provider"
+

trackerkit/domain/errors.py

@@ -0,0 +1,37 @@
+from trackerkit.domain.enums import ConnectionErrorKind
+
+
+class TrackerClientError(Exception):
+    """Base exception for the package."""
+
+
+class ConfigurationError(TrackerClientError):
+    """Raised when client configuration is invalid."""
+
+
+class AuthenticationError(TrackerClientError):
+    """Raised when provider authentication fails."""
+
+
+class ProviderError(TrackerClientError):
+    """Raised when a provider-specific operation fails."""
+
+
+class ProviderCapabilityError(TrackerClientError):
+    """Raised when a provider does not support a requested capability."""
+
+
+TrackerKitError = TrackerClientError
+
+
+def get_error_kind(error: Exception) -> ConnectionErrorKind:
+    if isinstance(error, AuthenticationError):
+        return ConnectionErrorKind.AUTHENTICATION
+    if isinstance(error, ConfigurationError):
+        return ConnectionErrorKind.CONFIGURATION
+    if isinstance(error, ProviderCapabilityError):
+        return ConnectionErrorKind.CAPABILITY
+    if isinstance(error, ProviderError):
+        return ConnectionErrorKind.PROVIDER
+    return ConnectionErrorKind.PROVIDER
+

trackerkit/domain/models.py

@@ -0,0 +1,131 @@
+from datetime import datetime
+
+from pydantic import BaseModel
+
+from trackerkit.domain.enums import ConnectionErrorKind, Provider, RelationType
+
+
+class User(BaseModel):
+    id: str
+    display_name: str
+    email: str | None = None
+
+
+class Workspace(BaseModel):
+    id: str
+    name: str
+    key: str | None = None
+
+
+class ConnectionDiagnostic(BaseModel):
+    provider: Provider
+    is_connected: bool
+    # Pydantic accepts both the enum and its string value (it's a `str` enum),
+    # so existing callers passing literals like ``"authentication"`` keep working.
+    error_kind: ConnectionErrorKind | None = None
+    message: str | None = None
+    error_type: str | None = None
+
+
+class Project(BaseModel):
+    id: str
+    name: str
+    key: str | None = None
+    description: str | None = None
+    workspace_id: str | None = None
+
+
+class Status(BaseModel):
+    id: str
+    name: str
+    category: str | None = None
+
+
+class Task(BaseModel):
+    id: str
+    key: str | None = None
+    title: str
+    description: str | None = None
+    project_id: str | None = None
+    status: Status | None = None
+    assignee: User | None = None
+    reporter: User | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    due_date: datetime | None = None
+    url: str | None = None
+
+
+class Comment(BaseModel):
+    id: str
+    task_id: str
+    body: str
+    author: User | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class Relation(BaseModel):
+    id: str | None = None
+    source_task_id: str
+    target_task_id: str
+    relation_type: RelationType
+
+
+class TaskQuery(BaseModel):
+    project_id: str | None = None
+    assignee_id: str | None = None
+    status_id: str | None = None
+    updated_since: datetime | None = None
+    # Soft cap on the number of items the adapter materializes from a paginated
+    # provider response. Currently honored by Asana (`list_tasks`); Jira/Yandex
+    # ignore it because they already use bounded server-side queries.
+    limit: int | None = None
+
+
+class CreateTaskInput(BaseModel):
+    title: str
+    description: str | None = None
+    project_id: str | None = None
+    assignee_id: str | None = None
+    status_id: str | None = None
+    due_date: datetime | None = None
+
+
+class UpdateTaskInput(BaseModel):
+    title: str | None = None
+    description: str | None = None
+    assignee_id: str | None = None
+    status_id: str | None = None
+    due_date: datetime | None = None
+
+
+class CreateCommentInput(BaseModel):
+    task_id: str
+    body: str
+
+
+class CreateProjectInput(BaseModel):
+    name: str
+    key: str | None = None
+    description: str | None = None
+    workspace_id: str | None = None
+
+
+class UpdateProjectInput(BaseModel):
+    name: str | None = None
+    key: str | None = None
+    description: str | None = None
+
+
+class CreateRelationInput(BaseModel):
+    source_task_id: str
+    target_task_id: str
+    relation_type: RelationType
+
+
+class UpdateRelationInput(BaseModel):
+    source_task_id: str
+    target_task_id: str
+    relation_type: RelationType
+