kd-cli 2.0.4__py3-none-any.whl

kd/api/tags.py

@@ -0,0 +1,107 @@
+"""Tags REST API wrapper.
+
+Covers three endpoint groups:
+- ``/api/tags`` — tag CRUD and tagged-issue listing
+- ``/api/issues/{id}/tags`` — add/remove tags on issues
+- ``/api/articles/{id}/tags`` — add/remove tags on articles
+"""
+
+from __future__ import annotations
+
+from kd.api.http import HttpClient
+from kd.models import FieldSet, Issue, Tag
+
+_TAG_LIST_FIELDS = str(
+    FieldSet(
+        "id",
+        "name",
+        "untagOnResolve",
+        owner=FieldSet("id", "name"),
+        color=FieldSet("id", "background", "foreground"),
+    )
+)
+
+_TAG_DETAIL_FIELDS = str(
+    FieldSet(
+        "id",
+        "name",
+        "untagOnResolve",
+        owner=FieldSet("id", "name"),
+        color=FieldSet("id", "background", "foreground"),
+    )
+)
+
+_TAGGED_ISSUE_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        project=FieldSet("id", "name", "shortName"),
+    )
+)
+
+
+class TagsAPI:
+    """Tags REST API wrapper (/api/tags, /api/issues/*/tags, /api/articles/*/tags)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    # --- Tag CRUD ---
+
+    def list_tags(self, top: int = 50, skip: int = 0) -> list[Tag]:
+        data = self._http.get(
+            "/tags",
+            fields=_TAG_LIST_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Tag.model_validate(t) for t in data]
+
+    def get_tag(self, tag_id: str) -> Tag:
+        data = self._http.get(f"/tags/{tag_id}", fields=_TAG_DETAIL_FIELDS)
+        return Tag.model_validate(data)
+
+    def create_tag(self, name: str) -> Tag:
+        data = self._http.post(
+            "/tags",
+            json={"name": name},
+            fields=_TAG_DETAIL_FIELDS,
+        )
+        return Tag.model_validate(data)
+
+    def update_tag(self, tag_id: str, name: str) -> Tag:
+        data = self._http.post(
+            f"/tags/{tag_id}",
+            json={"name": name},
+            fields=_TAG_DETAIL_FIELDS,
+        )
+        return Tag.model_validate(data)
+
+    def delete_tag(self, tag_id: str) -> None:
+        self._http.delete(f"/tags/{tag_id}")
+
+    # --- Tagged issues ---
+
+    def list_tag_issues(self, tag_id: str, top: int = 50, skip: int = 0) -> list[Issue]:
+        data = self._http.get(
+            f"/tags/{tag_id}/issues",
+            fields=_TAGGED_ISSUE_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Issue.model_validate(i) for i in data]
+
+    # --- Issue tags ---
+
+    def add_tag_to_issue(self, issue_id: str, tag_id: str) -> None:
+        self._http.post(f"/issues/{issue_id}/tags", json={"id": tag_id})
+
+    def remove_tag_from_issue(self, issue_id: str, tag_id: str) -> None:
+        self._http.delete(f"/issues/{issue_id}/tags/{tag_id}")
+
+    # --- Article tags ---
+
+    def add_tag_to_article(self, article_id: str, tag_id: str) -> None:
+        self._http.post(f"/articles/{article_id}/tags", json={"id": tag_id})
+
+    def remove_tag_from_article(self, article_id: str, tag_id: str) -> None:
+        self._http.delete(f"/articles/{article_id}/tags/{tag_id}")

kd/api/youtrack.py

@@ -0,0 +1,414 @@
+"""YouTrack REST API wrapper.
+
+Covers ``/api/...`` endpoints:
+- Projects: list, get, create, delete, configure time tracking
+- Issues: create, get, update, search (YT query language)
+- Comments: list, add
+- Work items: list, add
+- Work item types: list
+- Custom fields: list bundles
+- Issue links: list, list types
+- Users: search (for ringId resolution)
+
+Each method maps to a single REST endpoint. One method per operation.
+Uses HttpClient for transport and Pydantic models for serialization.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kd.api.http import HttpClient
+from kd.models import (
+    AssistResponse,
+    Attachment,
+    Comment,
+    CommentCreate,
+    FieldSet,
+    Issue,
+    IssueCreate,
+    IssueUpdate,
+    Project,
+    ProjectCreate,
+    TimeTrackingSettings,
+    User,
+    WorkItem,
+    WorkItemCreate,
+    WorkItemUpdate,
+    WorkItemType,
+)
+
+# Default field selections for common queries
+_PROJECT_LIST_FIELDS = str(
+    FieldSet(
+        "id",
+        "name",
+        "shortName",
+        "archived",
+        "description",
+        "ringId",
+        leader=FieldSet("id", "name"),
+    )
+)
+_PROJECT_DETAIL_FIELDS = str(
+    FieldSet(
+        "id",
+        "name",
+        "shortName",
+        "description",
+        "archived",
+        "ringId",
+        leader=FieldSet("id", "name"),
+    )
+)
+_ISSUE_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "description",
+        "created",
+        project=FieldSet("id", "name", "shortName"),
+        reporter=FieldSet("id", "login", "name"),
+        customFields=FieldSet("name", value=FieldSet("name")),
+    )
+)
+_ISSUE_RICH_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "description",
+        "created",
+        project=FieldSet("id", "name", "shortName"),
+        reporter=FieldSet("id", "login", "name"),
+        customFields=FieldSet("name", value=FieldSet("name")),
+        comments=FieldSet("id", "text", "created", author=FieldSet("id", "login", "name")),
+        links=FieldSet(
+            "id",
+            "direction",
+            linkType=FieldSet("name"),
+            issues=FieldSet("id", "idReadable", "summary"),
+        ),
+        attachments=FieldSet(
+            "id", "name", "size", "mimeType", "created", author=FieldSet("id", "login", "name")
+        ),
+    )
+)
+_COMMENT_FIELDS = "id,text,author(id,login,name),created,updated"
+_WORK_ITEM_FIELDS = (
+    "id,duration(minutes),text,type(id,name,autoAttached),author(id,login,name),date"
+)
+_ATTACHMENT_FIELDS = "id,name,size,mimeType,author(id,login,name),created,url"
+_USER_FIELDS = "id,login,name,email,ringId"
+_ASSIST_FIELDS = str(
+    FieldSet(
+        "query",
+        "caret",
+        suggestions=FieldSet(
+            "option",
+            "description",
+            "prefix",
+            "suffix",
+            "completionStart",
+            "completionEnd",
+            "matchingStart",
+            "matchingEnd",
+            "group",
+        ),
+    )
+)
+_PROJECT_CUSTOM_FIELDS_PARAM = (
+    "customFields("
+    "field(name,fieldType(id)),"
+    "$type,"
+    "bundle(values(name,ordinal,isResolved)),"
+    "canBeEmpty,emptyFieldText"
+    ")"
+)
+
+
+class YouTrackAPI:
+    """YouTrack REST API wrapper (/api/...)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    # --- Projects ---
+
+    def list_projects(self, top: int = 50, skip: int = 0) -> list[Project]:
+        data = self._http.get(
+            "/admin/projects",
+            fields=_PROJECT_LIST_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Project.model_validate(p) for p in data]
+
+    def get_project(self, project_id: str) -> Project:
+        data = self._http.get(f"/admin/projects/{project_id}", fields=_PROJECT_DETAIL_FIELDS)
+        return Project.model_validate(data)
+
+    def create_project(self, project: ProjectCreate) -> Project:
+        data = self._http.post(
+            "/admin/projects",
+            json=project.model_dump(by_alias=True, exclude_none=True),
+            fields=_PROJECT_LIST_FIELDS,
+        )
+        return Project.model_validate(data)
+
+    def delete_project(self, project_id: str) -> None:
+        self._http.delete(f"/admin/projects/{project_id}")
+
+    def list_project_custom_fields(self, project_id: str) -> list[dict[str, Any]]:
+        """Fetch custom fields for a project with bundle values."""
+        data: dict[str, Any] = self._http.get(
+            f"/admin/projects/{project_id}",
+            fields=_PROJECT_CUSTOM_FIELDS_PARAM,
+        )
+        result: list[dict[str, Any]] = data.get("customFields", [])
+        return result
+
+    # --- Time Tracking ---
+
+    def get_time_tracking_settings(self, project_id: str) -> TimeTrackingSettings:
+        data = self._http.get(
+            f"/admin/projects/{project_id}/timeTrackingSettings",
+            fields="enabled,estimate(field(name)),timeSpent(field(name)),workItemTypes(id,name)",
+        )
+        return TimeTrackingSettings.model_validate(data)
+
+    def update_time_tracking_settings(self, project_id: str, enabled: bool) -> TimeTrackingSettings:
+        data = self._http.post(
+            f"/admin/projects/{project_id}/timeTrackingSettings",
+            json={"enabled": enabled},
+        )
+        if data:
+            return TimeTrackingSettings.model_validate(data)
+        return TimeTrackingSettings(enabled=enabled)
+
+    # --- Issues ---
+
+    def list_issues(self, query: str = "", top: int = 50, skip: int = 0) -> list[Issue]:
+        params: dict[str, Any] = {"$top": top, "$skip": skip}
+        if query:
+            params["query"] = query
+        data = self._http.get("/issues", fields=_ISSUE_FIELDS, params=params)
+        return [Issue.model_validate(i) for i in data]
+
+    def get_issue(self, issue_id: str, rich: bool = False) -> Issue:
+        fields = _ISSUE_RICH_FIELDS if rich else _ISSUE_FIELDS
+        data = self._http.get(f"/issues/{issue_id}", fields=fields)
+        return Issue.model_validate(data)
+
+    def create_issue(self, issue: IssueCreate) -> Issue:
+        data = self._http.post(
+            "/issues",
+            json=issue.model_dump(by_alias=True, exclude_none=True),
+            fields=_ISSUE_FIELDS,
+        )
+        return Issue.model_validate(data)
+
+    def update_issue(self, issue_id: str, update: IssueUpdate) -> Issue:
+        data = self._http.post(
+            f"/issues/{issue_id}",
+            json=update.model_dump(by_alias=True, exclude_none=True),
+            fields=_ISSUE_FIELDS,
+        )
+        return Issue.model_validate(data)
+
+    def delete_issue(self, issue_id: str) -> None:
+        self._http.delete(f"/issues/{issue_id}")
+
+    # --- Comments ---
+
+    def list_comments(self, issue_id: str) -> list[Comment]:
+        data = self._http.get(f"/issues/{issue_id}/comments", fields=_COMMENT_FIELDS)
+        return [Comment.model_validate(c) for c in data]
+
+    def create_comment(self, issue_id: str, comment: CommentCreate) -> Comment:
+        data = self._http.post(
+            f"/issues/{issue_id}/comments",
+            json=comment.model_dump(exclude_none=True),
+            fields=_COMMENT_FIELDS,
+        )
+        return Comment.model_validate(data)
+
+    # --- Work Items ---
+
+    def list_work_items(self, issue_id: str) -> list[WorkItem]:
+        data = self._http.get(
+            f"/issues/{issue_id}/timeTracking/workItems",
+            fields=_WORK_ITEM_FIELDS,
+        )
+        return [WorkItem.model_validate(w) for w in data]
+
+    def create_work_item(self, issue_id: str, work_item: WorkItemCreate) -> WorkItem:
+        data = self._http.post(
+            f"/issues/{issue_id}/timeTracking/workItems",
+            json=work_item.model_dump(by_alias=True, exclude_none=True),
+            fields=_WORK_ITEM_FIELDS,
+        )
+        return WorkItem.model_validate(data)
+
+    def get_work_item(self, issue_id: str, work_item_id: str) -> WorkItem:
+        data = self._http.get(
+            f"/issues/{issue_id}/timeTracking/workItems/{work_item_id}",
+            fields=_WORK_ITEM_FIELDS,
+        )
+        return WorkItem.model_validate(data)
+
+    def update_work_item(
+        self, issue_id: str, work_item_id: str, update: WorkItemUpdate
+    ) -> WorkItem:
+        data = self._http.post(
+            f"/issues/{issue_id}/timeTracking/workItems/{work_item_id}",
+            json=update.model_dump(by_alias=True, exclude_none=True),
+            fields=_WORK_ITEM_FIELDS,
+        )
+        return WorkItem.model_validate(data)
+
+    def delete_work_item(self, issue_id: str, work_item_id: str) -> None:
+        self._http.delete(f"/issues/{issue_id}/timeTracking/workItems/{work_item_id}")
+
+    # --- Work Item Types ---
+
+    def list_work_item_types(self) -> list[WorkItemType]:
+        data = self._http.get(
+            "/admin/timeTrackingSettings/workItemTypes",
+            fields="id,name,autoAttached",
+            params={"$top": 50},
+        )
+        return [WorkItemType.model_validate(t) for t in data]
+
+    # --- Custom Field Bundles ---
+
+    def list_enum_bundles(self) -> list[dict[str, Any]]:
+        data: list[dict[str, Any]] = self._http.get(
+            "/admin/customFieldSettings/bundles/enum",
+            fields="id,name,values(name,ordinal)",
+            params={"$top": 50},
+        )
+        return data
+
+    def list_state_bundles(self) -> list[dict[str, Any]]:
+        data: list[dict[str, Any]] = self._http.get(
+            "/admin/customFieldSettings/bundles/state",
+            fields="id,name,values(name,isResolved,ordinal)",
+            params={"$top": 50},
+        )
+        return data
+
+    # --- Issue Links ---
+
+    def list_issue_links(self, issue_id: str) -> list[dict[str, Any]]:
+        data: list[dict[str, Any]] = self._http.get(
+            f"/issues/{issue_id}/links",
+            fields="id,direction,linkType(name),issues(id,idReadable,summary)",
+        )
+        return data
+
+    def apply_command(self, issue_id: str, command: str) -> None:
+        """Apply a command to an issue via the commands API.
+
+        Uses ``POST /commands`` which accepts YT command language strings
+        like ``"subtask of FB-2"`` or ``"State: Open"``.
+        """
+        self._http.post(
+            "/commands",
+            json={
+                "query": command,
+                "issues": [{"idReadable": issue_id}],
+            },
+        )
+
+    # --- Attachments ---
+
+    def list_attachments(self, issue_id: str) -> list[Attachment]:
+        data = self._http.get(f"/issues/{issue_id}/attachments", fields=_ATTACHMENT_FIELDS)
+        return [Attachment.model_validate(a) for a in data]
+
+    def get_attachment(self, issue_id: str, attachment_id: str) -> Attachment:
+        data = self._http.get(
+            f"/issues/{issue_id}/attachments/{attachment_id}",
+            fields=_ATTACHMENT_FIELDS,
+        )
+        return Attachment.model_validate(data)
+
+    def create_attachment(self, issue_id: str, file_name: str, file_content: bytes) -> Attachment:
+        data = self._http.post_file(
+            f"/issues/{issue_id}/attachments",
+            file_name=file_name,
+            file_content=file_content,
+            fields=_ATTACHMENT_FIELDS,
+        )
+        # YouTrack returns a list of created attachments
+        if isinstance(data, list):
+            return Attachment.model_validate(data[0])
+        return Attachment.model_validate(data)
+
+    def delete_attachment(self, issue_id: str, attachment_id: str) -> None:
+        self._http.delete(f"/issues/{issue_id}/attachments/{attachment_id}")
+
+    def download_attachment(self, issue_id: str, attachment_id: str) -> bytes:
+        """Download attachment content.
+
+        Fetches the attachment metadata first to get the signed download URL,
+        then downloads the binary content from that URL.
+        """
+        meta = self.get_attachment(issue_id, attachment_id)
+        if not meta.url:
+            raise ValueError(f"Attachment {attachment_id} has no download URL")
+        return self._http.get_bytes(meta.url)
+
+    def list_link_types(self) -> list[dict[str, Any]]:
+        data: list[dict[str, Any]] = self._http.get(
+            "/issueLinkTypes",
+            fields="id,name,sourceToTarget,targetToSource,directed",
+            params={"$top": 50},
+        )
+        return data
+
+    # --- Current User ---
+
+    def get_me(self) -> dict[str, Any]:
+        """Get the currently authenticated user. Used for connectivity check."""
+        data: dict[str, Any] = self._http.get("/users/me", fields=_USER_FIELDS)
+        return data
+
+    # --- Users (for ringId resolution) ---
+
+    def search_users(self, query: str) -> list[User]:
+        """Search users via YT API. Used to resolve login -> ringId."""
+        data = self._http.get("/users", fields=_USER_FIELDS, params={"query": query})
+        return [User.model_validate(u) for u in data]
+
+    # --- Query / Command Assist ---
+
+    def search_assist(self, query: str, caret: int | None = None) -> AssistResponse:
+        """Autocomplete for YouTrack search queries (``POST /api/search/assist``)."""
+        body: dict[str, Any] = {"query": query}
+        if caret is not None:
+            body["caret"] = caret
+        data = self._http.post("/search/assist", json=body, fields=_ASSIST_FIELDS)
+        return AssistResponse.model_validate(data)
+
+    def commands_assist(
+        self,
+        query: str,
+        caret: int | None = None,
+        issue_ids: list[str] | None = None,
+    ) -> AssistResponse:
+        """Autocomplete for YT command-language strings (``POST /api/commands/assist``).
+
+        ``issue_ids`` is the list of issue readable IDs the command would apply to;
+        when empty, the assist still returns field/value suggestions that work for
+        any issue.
+        """
+        body: dict[str, Any] = {
+            "query": query,
+            "issues": [{"idReadable": i} for i in (issue_ids or [])],
+        }
+        if caret is not None:
+            body["caret"] = caret
+        data = self._http.post("/commands/assist", json=body, fields=_ASSIST_FIELDS)
+        return AssistResponse.model_validate(data)