ktr-cli 0.1.0__py3-none-any.whl

kantree_cli/services/cards.py

@@ -0,0 +1,726 @@
+from dataclasses import dataclass
+from typing import Any
+
+from kantree_cli.core.client import KantreeClient
+from kantree_cli.core.errors import AmbiguityError, NotFoundError, ValidationError
+from kantree_cli.core.response import (
+    extract_object,
+    extract_object_list,
+    next_page_header_value,
+)
+
+JsonObject = dict[str, Any]
+CARD_STATES = (
+    "undecided",
+    "accepted",
+    "waiting",
+    "in_progress",
+    "completed",
+    "closed",
+    "dropped",
+)
+
+
+@dataclass(slots=True)
+class ResolvedField:
+    id: int
+    name: str
+    definition: JsonObject
+
+
+@dataclass(slots=True)
+class ResolvedGroup:
+    id: int
+    name: str
+    definition: JsonObject
+
+
+def list_cards(
+    client: KantreeClient,
+    workspace_id: int,
+    *,
+    filter_text: str | None = None,
+    archived: bool = False,
+    limit: int | None = None,
+    page: int | None = None,
+    per_page: int | None = None,
+    all_pages: bool = False,
+) -> list[JsonObject]:
+    if limit is not None and limit < 1:
+        raise ValidationError("`--limit` expects a positive integer.")
+
+    params: dict[str, str] = {}
+    if filter_text is not None:
+        normalized_filter = filter_text.strip()
+        if not normalized_filter:
+            raise ValidationError("`--filter` expects a non-empty value.")
+        params["filter"] = normalized_filter
+
+    if archived:
+        params["with_archived"] = "true"
+    if all_pages:
+        if page is not None:
+            raise ValidationError("`--all` cannot be combined with `--page`.")
+
+        merged_cards: list[JsonObject] = []
+        next_page = 1
+        while True:
+            request_params = dict(params)
+            request_params["page"] = str(next_page)
+            if per_page is not None:
+                request_params["per_page"] = str(per_page)
+
+            response = client.request(
+                method="GET",
+                path=f"/projects/{workspace_id}/cards",
+                params=request_params,
+            )
+            page_cards = extract_object_list(
+                response.data,
+                context=f"`GET /projects/{workspace_id}/cards`",
+                preferred_keys=("cards", "data", "items", "results"),
+            )
+            merged_cards.extend(page_cards)
+
+            if limit is not None and len(merged_cards) >= limit:
+                return merged_cards[:limit]
+
+            parsed_next_page = next_page_header_value(response.headers)
+            if parsed_next_page is None:
+                break
+            next_page = parsed_next_page
+
+        return merged_cards
+
+    if page is not None:
+        params["page"] = str(page)
+    if per_page is not None:
+        params["per_page"] = str(per_page)
+
+    response = client.request(
+        method="GET",
+        path=f"/projects/{workspace_id}/cards",
+        params=params or None,
+    )
+    cards = extract_object_list(
+        response.data,
+        context=f"`GET /projects/{workspace_id}/cards`",
+        preferred_keys=("cards", "data", "items", "results"),
+    )
+    if limit is not None:
+        return cards[:limit]
+    return cards
+
+
+def get_card(client: KantreeClient, card_id: int) -> JsonObject:
+    payload = client.get_json(f"/cards/{card_id}")
+    return extract_object(
+        payload,
+        context=f"`GET /cards/{card_id}`",
+        preferred_keys=("card", "data", "item", "result"),
+    )
+
+
+def get_workspace_card_by_ref(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    card_ref: int,
+) -> JsonObject:
+    payload = client.get_json(f"/projects/{workspace_id}/cards/{card_ref}")
+    return extract_object(
+        payload,
+        context=f"`GET /projects/{workspace_id}/cards/{card_ref}`",
+        preferred_keys=("card", "data", "item", "result"),
+    )
+
+
+def list_card_children(
+    client: KantreeClient, card_id: int, *, archived: bool = False
+) -> list[JsonObject]:
+    endpoint = f"/cards/{card_id}/children/archived" if archived else f"/cards/{card_id}/children"
+    payload = client.get_json(endpoint)
+    return extract_object_list(
+        payload,
+        context=f"`GET {endpoint}`",
+        preferred_keys=("cards", "children", "data", "items", "results"),
+    )
+
+
+def list_card_stream(client: KantreeClient, card_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/cards/{card_id}/stream")
+    return extract_object_list(
+        payload,
+        context=f"`GET /cards/{card_id}/stream`",
+        preferred_keys=("stream", "events", "data", "items", "results"),
+    )
+
+
+def list_card_reminders(client: KantreeClient, card_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/cards/{card_id}/reminders")
+    return extract_object_list(
+        payload,
+        context=f"`GET /cards/{card_id}/reminders`",
+        preferred_keys=("reminders", "data", "items", "results"),
+    )
+
+
+def create_card_reminder(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    targets: list[str],
+    reminding_date: str,
+) -> JsonObject:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/reminders",
+        json_body={"targets": targets, "reminding_date": reminding_date},
+    )
+    return extract_object(
+        response.data,
+        context=f"`POST /cards/{card_id}/reminders`",
+        preferred_keys=("reminder", "data", "item", "result"),
+    )
+
+
+def delete_card_reminder(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    reminder_id: int,
+) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/cards/{card_id}/reminders/{reminder_id}",
+    )
+    return response.data
+
+
+def comment_card(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    message: str,
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/comments",
+        json_body={"message": message},
+    )
+    return response.data
+
+
+def archive_card(client: KantreeClient, *, card_id: int) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/archive",
+    )
+    return response.data
+
+
+def restore_card(client: KantreeClient, *, card_id: int) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/cards/{card_id}/archive",
+    )
+    return response.data
+
+
+def delete_card(client: KantreeClient, *, card_id: int) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/cards/{card_id}",
+    )
+    return response.data
+
+
+def create_card(
+    client: KantreeClient,
+    *,
+    parent_id: int,
+    title: str,
+    group_id: int | None = None,
+    model_id: int | None = None,
+    attributes: dict[int, object] | None = None,
+) -> JsonObject:
+    json_body: dict[str, object] = {"title": title}
+    if group_id is not None:
+        json_body["group_id"] = group_id
+    if model_id is not None:
+        json_body["model_id"] = model_id
+    if attributes is not None:
+        json_body["attributes"] = {str(field_id): value for field_id, value in attributes.items()}
+    response = client.request(
+        method="POST",
+        path=f"/cards/{parent_id}/children",
+        json_body=json_body,
+    )
+    return extract_object(
+        response.data,
+        context=f"`POST /cards/{parent_id}/children`",
+        preferred_keys=("card", "data", "item", "result"),
+    )
+
+
+def update_card(
+    client: KantreeClient,
+    card_id: int,
+    *,
+    title: str | None = None,
+    state: str | None = None,
+    default_child_card_model_id: int | None = None,
+    image_cover_url: str | None = None,
+) -> Any:
+    payload: dict[str, object] = {}
+    if title is not None:
+        payload["title"] = title
+    if state is not None:
+        payload["state"] = state
+    if default_child_card_model_id is not None:
+        payload["default_child_card_model_id"] = default_child_card_model_id
+    if image_cover_url is not None:
+        payload["image_cover_url"] = image_cover_url
+    if not payload:
+        raise ValidationError("Card update requires at least one field.")
+    response = client.request(
+        method="PUT",
+        path=f"/cards/{card_id}",
+        json_body=payload,
+    )
+    return response.data
+
+
+def set_card_attributes(
+    client: KantreeClient,
+    card_id: int,
+    *,
+    attributes: dict[int, object],
+) -> Any:
+    if not attributes:
+        raise ValidationError("Card attribute update requires at least one field.")
+    encoded = {str(field_id): value for field_id, value in attributes.items()}
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/attributes",
+        json_body={"attributes": encoded},
+    )
+    return response.data
+
+
+def append_card_attribute(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    field_id: int,
+    value: object,
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/attributes/{field_id}/append",
+        json_body={"value": value},
+    )
+    return response.data
+
+
+def pop_card_attribute(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    field_id: int,
+    value: object,
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/attributes/{field_id}/pop",
+        json_body={"value": value},
+    )
+    return response.data
+
+
+def clear_card_attribute(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    field_id: int,
+) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/cards/{card_id}/attributes/{field_id}",
+    )
+    return response.data
+
+
+def set_card_model(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    model_id: int | None,
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/model",
+        json_body={"model_id": model_id},
+    )
+    return response.data
+
+
+def relocate_card(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    group_id: int,
+    parent_id: int | None = None,
+    position: int | None = None,
+) -> Any:
+    payload: dict[str, object] = {"group_id": group_id}
+    if parent_id is not None:
+        payload["parent_id"] = parent_id
+    if position is not None:
+        payload["position"] = position
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/relocate",
+        json_body=payload,
+    )
+    return response.data
+
+
+def add_card_to_group(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    group_id: int,
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/add-to-group",
+        json_body={"group_id": group_id},
+    )
+    return response.data
+
+
+def remove_card_from_group(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    group_id: int,
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/remove-from-group",
+        json_body={"group_id": group_id},
+    )
+    return response.data
+
+
+def clear_card_group_type(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    type_id: int,
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{card_id}/remove-from-group-type",
+        json_body={"type_id": type_id},
+    )
+    return response.data
+
+
+def copy_card(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    parent_id: int | None = None,
+    group_id: int | None = None,
+    position: int | None = None,
+) -> Any:
+    payload: dict[str, object] = {}
+    if parent_id is not None:
+        payload["parent_id"] = parent_id
+    if group_id is not None:
+        payload["group_id"] = group_id
+    if position is not None:
+        payload["position"] = position
+    response = client.request(
+        method="POST", path=f"/cards/{card_id}/copy", json_body=payload or None
+    )
+    return response.data
+
+
+def list_card_states(client: KantreeClient, *, card_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/cards/{card_id}/states")
+    return extract_object_list(
+        payload,
+        context=f"`GET /cards/{card_id}/states`",
+        preferred_keys=("states", "data", "items", "results"),
+    )
+
+
+def get_card_hierarchy(client: KantreeClient, *, card_id: int) -> Any:
+    return client.get_json(f"/cards/{card_id}/hierarchy")
+
+
+def list_card_descendants(
+    client: KantreeClient,
+    *,
+    card_id: int,
+    reversed_order: bool = False,
+) -> list[JsonObject]:
+    params: dict[str, str] = {}
+    if reversed_order:
+        params["reverse"] = "true"
+    response = client.request(
+        method="GET",
+        path=f"/cards/{card_id}/descendants",
+        params=params or None,
+    )
+    return extract_object_list(
+        response.data,
+        context=f"`GET /cards/{card_id}/descendants`",
+        preferred_keys=("cards", "descendants", "data", "items", "results"),
+    )
+
+
+def batch_operation(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    operation: str,
+    params: dict[str, object],
+    card_ids: list[int] | None = None,
+    filter_text: str | None = None,
+    parent_id: int | None = None,
+    group_id: int | None = None,
+    with_archived: bool = False,
+) -> Any:
+    """Execute a batch operation server-side."""
+    payload: dict[str, object] = {"operation": operation, "params": params}
+    if card_ids is not None:
+        payload["card_ids"] = card_ids
+    if filter_text is not None:
+        payload["filter"] = filter_text
+    if parent_id is not None:
+        payload["parent_id"] = parent_id
+    if group_id is not None:
+        payload["group_id"] = group_id
+    if with_archived:
+        payload["with_archived"] = True
+    response = client.request(
+        method="POST",
+        path=f"/projects/{workspace_id}/batch",
+        json_body=payload,
+    )
+    return response.data
+
+
+def get_async_job(client: KantreeClient, job_id: int | str) -> Any:
+    response = client.request(method="GET", path=f"/async/{job_id}")
+    return response.data
+
+
+def batch_dates(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    cards: dict[str, list[dict[str, Any]]],
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/projects/{workspace_id}/batch/dates",
+        json_body={"cards": cards},
+    )
+    return response.data
+
+
+def favorite_card(client: KantreeClient, *, card_id: int) -> Any:
+    response = client.request(method="POST", path=f"/cards/{card_id}/favorite")
+    return response.data
+
+
+def unfavorite_card(client: KantreeClient, *, card_id: int) -> Any:
+    response = client.request(method="DELETE", path=f"/cards/{card_id}/favorite")
+    return response.data
+
+
+def resolve_field_selector(fields: list[JsonObject], selector: str) -> ResolvedField:
+    normalized_selector = selector.strip()
+    if not normalized_selector:
+        raise ValidationError("Field selector must not be empty.")
+
+    parsed_id = _parse_int(normalized_selector)
+    if parsed_id is not None:
+        matches = [field for field in fields if field_id(field, context="Field list") == parsed_id]
+        if not matches:
+            raise NotFoundError(f"Field id `{parsed_id}` was not found in this workspace.")
+        return _single_field_match(matches, selector=f"id `{parsed_id}`")
+
+    matches = [
+        field for field in fields if field_name(field, context="Field list") == normalized_selector
+    ]
+    if not matches:
+        raise NotFoundError(f"Field `{normalized_selector}` was not found in this workspace.")
+    return _single_field_match(matches, selector=f"`{normalized_selector}`")
+
+
+def resolve_group_selector(groups: list[JsonObject], selector: str) -> ResolvedGroup:
+    normalized_selector = selector.strip()
+    if not normalized_selector:
+        raise ValidationError("Group selector must not be empty.")
+
+    parsed_id = _parse_int(normalized_selector)
+    if parsed_id is not None:
+        if parsed_id < 1:
+            raise ValidationError(
+                f"Group selector expects a positive integer id, got `{normalized_selector}`."
+            )
+        return ResolvedGroup(
+            id=parsed_id,
+            name=normalized_selector,
+            definition={"id": parsed_id},
+        )
+
+    matches = [
+        group for group in groups if group_name(group, context="Group list") == normalized_selector
+    ]
+    if not matches:
+        raise NotFoundError(f"Group `{normalized_selector}` was not found under this parent.")
+    if len(matches) > 1:
+        ids = ", ".join(str(group_id(match, context="Group lookup")) for match in matches)
+        raise AmbiguityError(
+            f"Group `{normalized_selector}` is ambiguous under this parent "
+            f"({len(matches)} matches: {ids}). Use a group id."
+        )
+
+    match = matches[0]
+    return ResolvedGroup(
+        id=group_id(match, context="Group lookup"),
+        name=group_name(match, context="Group lookup"),
+        definition=match,
+    )
+
+
+def field_id(field: JsonObject, *, context: str) -> int:
+    parsed = _parse_int(field.get("id"))
+    if parsed is None:
+        raise ValidationError(f"{context} does not contain a usable integer `id`.")
+    return parsed
+
+
+def field_name(field: JsonObject, *, context: str) -> str:
+    for key in ("name", "title"):
+        value = field.get(key)
+        if isinstance(value, str):
+            normalized = value.strip()
+            if normalized:
+                return normalized
+    raise ValidationError(f"{context} does not contain a usable field name.")
+
+
+def field_is_group_type(field: JsonObject) -> bool:
+    for raw_token in _field_type_tokens(field):
+        normalized = raw_token.strip().lower().replace("-", "_").replace(" ", "_")
+        if normalized == "group_type":
+            return True
+    return False
+
+
+def group_id(group: JsonObject, *, context: str) -> int:
+    parsed = _parse_int(group.get("id"))
+    if parsed is None:
+        raise ValidationError(f"{context} does not contain a usable integer `id`.")
+    return parsed
+
+
+def group_name(group: JsonObject, *, context: str) -> str:
+    for key in ("title", "name"):
+        value = group.get(key)
+        if isinstance(value, str):
+            normalized = value.strip()
+            if normalized:
+                return normalized
+    raise ValidationError(f"{context} does not contain a usable group name.")
+
+
+def card_parent_id(card: JsonObject, *, context: str) -> int:
+    parsed_parent = _parse_int(card.get("parent_id"))
+    if parsed_parent is not None:
+        return parsed_parent
+
+    parent = card.get("parent")
+    if isinstance(parent, dict):
+        parsed_parent = _parse_int(parent.get("id"))
+        if parsed_parent is not None:
+            return parsed_parent
+
+    raise ValidationError(f"{context} does not contain a usable `parent_id`.")
+
+
+def card_workspace_id(card: JsonObject, *, context: str) -> int:
+    for key in ("project_id", "workspace_id"):
+        parsed = _parse_int(card.get(key))
+        if parsed is not None:
+            return parsed
+
+    for key in ("project", "workspace"):
+        nested = card.get(key)
+        if isinstance(nested, dict):
+            parsed = _parse_int(nested.get("id"))
+            if parsed is not None:
+                return parsed
+
+    raise ValidationError(f"{context} does not contain a usable workspace id.")
+
+
+def card_id(card: JsonObject, *, context: str) -> int:
+    parsed = _parse_int(card.get("id"))
+    if parsed is None:
+        raise ValidationError(f"{context} does not contain a usable integer `id`.")
+    return parsed
+
+
+def _single_field_match(matches: list[JsonObject], *, selector: str) -> ResolvedField:
+    if len(matches) > 1:
+        ids = ", ".join(str(field_id(match, context="Field lookup")) for match in matches)
+        raise AmbiguityError(
+            f"Field {selector} is ambiguous in this workspace "
+            f"({len(matches)} matches: {ids}). Use a field id."
+        )
+
+    match = matches[0]
+    return ResolvedField(
+        id=field_id(match, context="Field lookup"),
+        name=field_name(match, context="Field lookup"),
+        definition=match,
+    )
+
+
+def _field_type_tokens(field: JsonObject) -> list[str]:
+    tokens: list[str] = []
+    for key in ("type", "attribute_type", "field_type", "kind", "attribute_type_name", "type_name"):
+        value = field.get(key)
+        if isinstance(value, str):
+            tokens.append(value)
+        elif isinstance(value, dict):
+            for nested_key in ("name", "slug", "key", "code", "type"):
+                nested_value = value.get(nested_key)
+                if isinstance(nested_value, str):
+                    tokens.append(nested_value)
+    return tokens
+
+
+def _parse_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return None
+        try:
+            return int(stripped)
+        except ValueError:
+            return None
+    return None