kd-cli 2.0.4__py3-none-any.whl

kd/models/article.py

@@ -0,0 +1,64 @@
+"""Article models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kd.models.common import IdEntity, NamedEntity
+from kd.models.tag import Tag
+
+
+class ArticleRef(IdEntity):
+    """Lightweight cross-reference to an article.
+
+    Carries ``id_readable`` because articles are addressed by their
+    readable id (e.g. ``FB-A-1``) in the CLI. ``NamedEntity`` only has
+    ``id`` and ``name`` and is reused for leaders, reporters, authors —
+    entities that do not have a human-readable id — so a dedicated type
+    keeps the shared base clean.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id_readable: str | None = Field(default=None, alias="idReadable")
+    name: str | None = None
+
+
+class Article(IdEntity):
+    """Knowledge base article.
+
+    The ``content`` field is populated only when detail fields are
+    requested (get, create, update responses). List responses omit it
+    to keep payloads lightweight.
+    """
+
+    id_readable: str = Field(alias="idReadable")
+    summary: str
+    content: str | None = None
+    project: NamedEntity | None = None
+    reporter: NamedEntity | None = None
+    created: int | None = None
+    updated: int | None = None
+    has_children: bool = Field(default=False, alias="hasChildren")
+    parent_article: ArticleRef | None = Field(default=None, alias="parentArticle")
+    tags: list[Tag] = Field(default_factory=list)
+
+
+class ArticleCreate(BaseModel):
+    """Input for creating an article."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    project: IdEntity
+    summary: str
+    content: str | None = None
+    parent_article: IdEntity | None = Field(default=None, alias="parentArticle")
+
+
+class ArticleUpdate(BaseModel):
+    """Input for updating an article."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    summary: str | None = None
+    content: str | None = None

kd/models/assist.py

@@ -0,0 +1,47 @@
+"""Query and command assist models.
+
+Used for ``/api/search/assist`` and ``/api/commands/assist`` — YouTrack's
+autocomplete helpers for search queries and issue-command strings.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AssistSuggestion(BaseModel):
+    """One suggestion returned by an assist endpoint.
+
+    ``option`` is the replacement string; the caret position fields describe
+    where the replacement should be inserted and which part of the current
+    input it matched. ``prefix``/``suffix`` are the characters to wrap around
+    ``option`` when inserting (e.g. ``{`` / ``}`` for project keys with
+    spaces).
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    option: str
+    description: str | None = None
+    prefix: str | None = None
+    suffix: str | None = None
+    completion_start: int | None = Field(default=None, alias="completionStart")
+    completion_end: int | None = Field(default=None, alias="completionEnd")
+    matching_start: int | None = Field(default=None, alias="matchingStart")
+    matching_end: int | None = Field(default=None, alias="matchingEnd")
+    group: str | None = None
+
+
+class AssistResponse(BaseModel):
+    """Envelope returned by both assist endpoints.
+
+    ``query`` and ``caret`` echo the caller's input when requested in the
+    field set; ``commands/assist`` does not always return ``caret``. Both are
+    optional to accommodate the partial shape.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    query: str | None = None
+    caret: int | None = None
+    suggestions: list[AssistSuggestion] = Field(default_factory=list)

kd/models/attachment.py

@@ -0,0 +1,20 @@
+"""Attachment models."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from kd.models.common import IdEntity, NamedEntity
+
+
+class Attachment(IdEntity):
+    """Issue or article attachment metadata."""
+
+    name: str
+    size: int | None = None
+    mime_type: str | None = Field(default=None, alias="mimeType")
+    extension: str | None = None
+    author: NamedEntity | None = None
+    created: int | None = None
+    updated: int | None = None
+    url: str | None = None

kd/models/comment.py

@@ -0,0 +1,25 @@
+"""Comment models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from kd.models.common import IdEntity, NamedEntity
+
+
+class Comment(IdEntity):
+    """Issue or article comment."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    text: str
+    author: NamedEntity | None = None
+    created: int | None = None
+    updated: int | None = None
+    pinned: bool | None = None
+
+
+class CommentCreate(BaseModel):
+    """Input for adding a comment."""
+
+    text: str

kd/models/common.py

@@ -0,0 +1,39 @@
+"""Shared model types."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class IdEntity(BaseModel):
+    """Base for all entities with an id field."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+
+
+class NamedEntity(IdEntity):
+    """Entity with id and name — used for nested references (leader, reporter, author)."""
+
+    name: str | None = None
+
+
+class FieldSet:
+    """Helper for building YouTrack's explicit field selection strings.
+
+    Usage::
+
+        str(FieldSet("id", "name", leader=FieldSet("id", "name")))
+        # => "id,name,leader(id,name)"
+    """
+
+    def __init__(self, *fields: str, **nested: FieldSet) -> None:
+        self._fields = fields
+        self._nested = nested
+
+    def __str__(self) -> str:
+        parts: list[str] = list(self._fields)
+        for name, subset in self._nested.items():
+            parts.append(f"{name}({subset})")
+        return ",".join(parts)

kd/models/issue.py

@@ -0,0 +1,67 @@
+"""Issue models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kd.models.attachment import Attachment
+from kd.models.comment import Comment
+from kd.models.common import IdEntity, NamedEntity
+
+
+class CustomField(BaseModel):
+    """Custom field value representation.
+
+    ``value`` is Any because YouTrack custom fields can be dicts with
+    a ``name`` key, primitives, or lists depending on field type.
+    ``field_type`` serializes as ``$type`` — required by YouTrack for
+    create/update operations on enum custom fields.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    name: str
+    value: Any = None
+    field_type: str | None = Field(default=None, alias="$type")
+
+
+class Issue(IdEntity):
+    """Full issue representation.
+
+    The ``comments``, ``links``, and ``attachments`` fields are populated
+    only when a rich field set is requested from the API.
+    """
+
+    id_readable: str = Field(alias="idReadable")
+    summary: str
+    description: str | None = None
+    project: NamedEntity | None = None
+    reporter: NamedEntity | None = None
+    created: int | None = None
+    custom_fields: list[CustomField] = Field(default_factory=list, alias="customFields")
+    comments: list[Comment] | None = None
+    links: list[dict[str, Any]] | None = None
+    attachments: list[Attachment] | None = None
+
+
+class IssueCreate(BaseModel):
+    """Input for creating an issue."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    project: IdEntity
+    summary: str
+    description: str | None = None
+    custom_fields: list[CustomField] | None = Field(default=None, alias="customFields")
+
+
+class IssueUpdate(BaseModel):
+    """Input for updating an issue."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    summary: str | None = None
+    description: str | None = None
+    custom_fields: list[CustomField] | None = Field(default=None, alias="customFields")

kd/models/project.py

@@ -0,0 +1,60 @@
+"""Project models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kd.models.common import IdEntity, NamedEntity
+
+
+class Project(IdEntity):
+    """Full project representation."""
+
+    name: str
+    short_name: str = Field(alias="shortName")
+    description: str | None = None
+    archived: bool = False
+    ring_id: str | None = Field(default=None, alias="ringId")
+    leader: NamedEntity | None = None
+
+
+class BundleValue(BaseModel):
+    """A single allowed value within an enum or state bundle."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    name: str
+    ordinal: int = 0
+    is_resolved: bool | None = Field(default=None, alias="isResolved")
+
+
+class ProjectCustomField(BaseModel):
+    """Custom field attached to a project (flattened from nested API shape).
+
+    Constructed by the SDK from the raw API response, not parsed directly.
+    """
+
+    name: str
+    field_type_id: str
+    project_field_type: str
+    can_be_empty: bool = True
+    empty_field_text: str | None = None
+    bundle_values: list[BundleValue] = Field(default_factory=list)
+
+
+class ProjectCreate(BaseModel):
+    """Input for creating a project."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    name: str
+    short_name: str = Field(alias="shortName")
+    leader: IdEntity | None = None  # Create only needs id
+
+
+class TimeTrackingSettings(BaseModel):
+    """Time tracking configuration per project."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    enabled: bool = False

kd/models/saved_query.py

@@ -0,0 +1,54 @@
+"""Saved query models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from kd.models.common import IdEntity, NamedEntity
+
+
+class SavedQuery(IdEntity):
+    """YouTrack saved query (saved search).
+
+    Minimal field set: id, name, query text, owner reference. Sharing settings
+    (``readSharingSettings`` / ``updateSharingSettings``) are intentionally
+    excluded from the default field parameter — personal CRUD works without
+    them, and modelling them pulls in a permissions surface that belongs to
+    a future milestone.
+    """
+
+    name: str
+    query: str
+    owner: NamedEntity | None = None
+
+
+class SavedQueryCreate(BaseModel):
+    """Input for creating a saved query."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    name: str
+    query: str
+
+
+class SavedQueryUpdate(BaseModel):
+    """Partial update for a saved query.
+
+    All fields optional. Dump with ``exclude_none=True`` so the POST body only
+    carries the fields the caller actually wants to change; YouTrack preserves
+    omitted fields (live-verified on ``vod.youtrack.cloud`` 2026-04-05).
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    name: str | None = None
+    query: str | None = None
+
+
+class QueryValidationResult(BaseModel):
+    """Result of validating a query string against the YouTrack search API."""
+
+    valid: bool
+    query: str
+    error: str | None = None
+    suggestion: str | None = None

kd/models/search.py

@@ -0,0 +1,20 @@
+"""Search result model for cross-entity search."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class SearchResult(BaseModel):
+    """Normalized result from cross-entity search.
+
+    Each result carries a type discriminator so consumers can identify
+    the source entity kind without inspecting the id format.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: str
+    id: str
+    title: str
+    project: str

kd/models/tag.py

@@ -0,0 +1,30 @@
+"""Tag models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kd.models.common import IdEntity, NamedEntity
+
+
+class TagColor(BaseModel):
+    """Tag color with hex foreground/background values."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    background: str | None = None
+    foreground: str | None = None
+
+
+class Tag(IdEntity):
+    """YouTrack tag.
+
+    Tags are shared entities that can be applied to both issues and articles.
+    The ``owner`` field is populated when detail fields are requested.
+    """
+
+    name: str
+    owner: NamedEntity | None = None
+    color: TagColor | None = None
+    untag_on_resolve: bool = Field(default=False, alias="untagOnResolve")

kd/models/user.py

@@ -0,0 +1,42 @@
+"""User models (Hub API entities)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kd.models.common import IdEntity, NamedEntity
+
+
+class User(IdEntity):
+    """User representation (works for both YT and Hub API responses)."""
+
+    login: str
+    name: str
+    email: str | None = None
+    ring_id: str | None = Field(default=None, alias="ringId")
+    banned: bool = False
+    guest: bool = False
+
+
+class UserCreate(BaseModel):
+    """Input for creating a user via Hub API."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    login: str
+    name: str
+    email: str
+
+
+class Group(IdEntity):
+    """User group representation."""
+
+    name: str
+    users_count: int | None = Field(default=None, alias="usersCount")
+
+
+class ProjectTeam(IdEntity):
+    """Project team (auto-created group per project)."""
+
+    name: str
+    project: NamedEntity | None = None

kd/models/work_item.py

@@ -0,0 +1,59 @@
+"""Work item (time tracking) models.
+
+Note: REST API requires type ID, not name. The SDK resolves names to IDs.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kd.models.common import IdEntity, NamedEntity
+
+
+class WorkItemType(IdEntity):
+    """Work item type (Development, Testing, Documentation, etc.)."""
+
+    name: str
+    auto_attached: bool = Field(default=False, alias="autoAttached")
+
+
+class Duration(BaseModel):
+    """Duration in minutes, matching the API's duration object."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    minutes: int
+
+
+class WorkItem(IdEntity):
+    """Time entry on an issue."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    duration: Duration
+    text: str | None = None
+    type: WorkItemType | None = None
+    author: NamedEntity | None = None
+    date: int | None = None
+
+
+class WorkItemCreate(BaseModel):
+    """Input for logging work."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    duration: Duration
+    text: str | None = None
+    type: IdEntity | None = None
+    date: int | None = None
+
+
+class WorkItemUpdate(BaseModel):
+    """Input for editing a work item. All fields optional."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    duration: Duration | None = None
+    text: str | None = None
+    type: IdEntity | None = None
+    date: int | None = None