ktr-cli 0.1.0__py3-none-any.whl

kantree_cli/services/importers.py

@@ -0,0 +1,304 @@
+import mimetypes
+from pathlib import Path
+from typing import Any
+
+from kantree_cli.core.client import KantreeClient
+from kantree_cli.core.errors import ValidationError
+
+JsonObject = dict[str, Any]
+
+_SUPPORTED_SPREADSHEET_EXTENSIONS = {".csv", ".xlsx", ".ods"}
+
+# Assumption: these field names match the spreadsheet-import REST API payload.
+# They are centralized here so we can adjust quickly if endpoint verification differs.
+_IMPORT_PAYLOAD_PROJECT_KEY = "project_id"
+_IMPORT_PAYLOAD_DISCOVER_FILE_ID_KEY = "discover_file_id"
+_IMPORT_PAYLOAD_MAPPING_KEY = "mapping"
+_IMPORT_PAYLOAD_UPDATE_FIELD_KEY = "update_field"
+_IMPORT_PAYLOAD_UPDATE_ONLY_KEY = "update_only"
+_IMPORT_PAYLOAD_OPTIONS_KEY = "options"
+_IMPORT_PAYLOAD_IGNORE_HEADER_KEY = "ignore_header"
+_IMPORT_PAYLOAD_SUPPRESS_ACTIVITIES_KEY = "suppress_activities"
+_TEMPLATE_WRAPPER_KEYS = {"discover_file_id", "source_columns", "fields"}
+
+
+def discover_spreadsheet_import(
+    client: KantreeClient,
+    *,
+    spreadsheet_path: Path,
+) -> Any:
+    normalized_path = _validate_spreadsheet_path(spreadsheet_path)
+    mime_type = _guess_spreadsheet_mime_type(normalized_path)
+    with normalized_path.open("rb") as stream:
+        response = client.request(
+            method="POST",
+            path="/importers/spreadsheet/discover",
+            files={"file": (normalized_path.name, stream, mime_type)},
+        )
+    return response.data
+
+
+def apply_spreadsheet_import(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    discover_file_id: str,
+    mapping: Any,
+    update_field: str | None,
+    update_only: bool,
+    ignore_header: bool,
+    suppress_activities: bool,
+) -> Any:
+    payload = _build_spreadsheet_import_payload(
+        workspace_id=workspace_id,
+        discover_file_id=discover_file_id,
+        mapping=mapping,
+        update_field=update_field,
+        update_only=update_only,
+        ignore_header=ignore_header,
+        suppress_activities=suppress_activities,
+    )
+    response = client.request(
+        method="POST",
+        path="/importers/spreadsheet/import",
+        json_body=payload,
+    )
+    return response.data
+
+
+def build_template_from_discovery(discovery_payload: Any) -> JsonObject:
+    source_fields = _extract_discovery_fields(discovery_payload)
+    mapping: JsonObject = {}
+    for index, (field_key, field_name) in enumerate(source_fields):
+        if index == 0:
+            mapping[field_key] = {"type": "title"}
+            continue
+        mapping[field_key] = {
+            "type": "attribute",
+            "attr_type": "text",
+            "name": field_name,
+        }
+
+    return {
+        "discover_file_id": _extract_discovery_file_id(discovery_payload),
+        "source_columns": [field_name for _, field_name in source_fields],
+        "fields": [[field_key, field_name] for field_key, field_name in source_fields],
+        "mapping": mapping,
+    }
+
+
+def normalize_spreadsheet_import_mapping(mapping_payload: JsonObject) -> JsonObject:
+    if not (_TEMPLATE_WRAPPER_KEYS & mapping_payload.keys()):
+        return mapping_payload
+
+    nested_mapping = mapping_payload.get(_IMPORT_PAYLOAD_MAPPING_KEY)
+    if not isinstance(nested_mapping, dict):
+        raise ValidationError("`--mapping` template output must contain a JSON object `mapping`.")
+    return nested_mapping
+
+
+def resolve_spreadsheet_update_field(mapping: JsonObject, update_field: str | None) -> str | None:
+    if update_field is None:
+        return None
+
+    normalized = update_field.strip()
+    if not normalized:
+        raise ValidationError("`--update-field` expects a non-empty value.")
+    if normalized in mapping:
+        return normalized
+
+    matches = [
+        key
+        for key, mapinfo in mapping.items()
+        if _mapping_entry_matches_update_field(mapinfo, normalized)
+    ]
+    if len(matches) == 1:
+        return str(matches[0])
+    if len(matches) > 1:
+        raise ValidationError(
+            "`--update-field` matched multiple import mapping entries; use the column key instead."
+        )
+
+    raise ValidationError(
+        "`--update-field` must match an import mapping column key or mapped field name."
+    )
+
+
+def _mapping_entry_matches_update_field(mapinfo: Any, update_field: str) -> bool:
+    if not isinstance(mapinfo, dict):
+        return False
+
+    normalized = update_field.lower()
+    if mapinfo.get("type") in {"title", "ref"} and normalized == mapinfo.get("type"):
+        return True
+
+    for key in ("name", "title", "label", "source_column", "attribute", "attribute_name"):
+        raw_value = mapinfo.get(key)
+        if isinstance(raw_value, str) and raw_value.strip().lower() == normalized:
+            return True
+    return False
+
+
+def _build_spreadsheet_import_payload(
+    *,
+    workspace_id: int,
+    discover_file_id: str,
+    mapping: Any,
+    update_field: str | None,
+    update_only: bool,
+    ignore_header: bool,
+    suppress_activities: bool,
+) -> JsonObject:
+    payload: JsonObject = {
+        _IMPORT_PAYLOAD_PROJECT_KEY: workspace_id,
+        _IMPORT_PAYLOAD_DISCOVER_FILE_ID_KEY: discover_file_id,
+        _IMPORT_PAYLOAD_MAPPING_KEY: mapping,
+    }
+    if update_field is not None:
+        payload[_IMPORT_PAYLOAD_UPDATE_FIELD_KEY] = update_field
+    if update_only:
+        payload[_IMPORT_PAYLOAD_UPDATE_ONLY_KEY] = True
+    if ignore_header:
+        payload[_IMPORT_PAYLOAD_OPTIONS_KEY] = {_IMPORT_PAYLOAD_IGNORE_HEADER_KEY: True}
+    if suppress_activities:
+        payload[_IMPORT_PAYLOAD_SUPPRESS_ACTIVITIES_KEY] = True
+    return payload
+
+
+def _validate_spreadsheet_path(path: Path) -> Path:
+    resolved = path.expanduser()
+    if not resolved.exists():
+        raise ValidationError(f"Spreadsheet path does not exist: `{resolved}`")
+    if not resolved.is_file():
+        raise ValidationError(f"Spreadsheet path is not a file: `{resolved}`")
+    suffix = resolved.suffix.lower()
+    if suffix not in _SUPPORTED_SPREADSHEET_EXTENSIONS:
+        expected = ", ".join(sorted(_SUPPORTED_SPREADSHEET_EXTENSIONS))
+        raise ValidationError(
+            f"Unsupported spreadsheet format `{resolved.suffix}`. Expected one of: {expected}."
+        )
+    return resolved
+
+
+def _guess_spreadsheet_mime_type(path: Path) -> str:
+    guessed, _ = mimetypes.guess_type(str(path))
+    if guessed:
+        return guessed
+    return "application/octet-stream"
+
+
+def _extract_discovery_file_id(payload: Any) -> str | None:
+    candidates: list[Any] = []
+    if isinstance(payload, dict):
+        for key in ("discover_file_id", "file_id", "id"):
+            candidates.append(payload.get(key))
+
+        file_obj = payload.get("file")
+        if isinstance(file_obj, dict):
+            for key in ("discover_file_id", "file_id", "id"):
+                candidates.append(file_obj.get(key))
+
+    for candidate in candidates:
+        if candidate is None:
+            continue
+        if isinstance(candidate, str):
+            normalized = candidate.strip()
+            if normalized:
+                return normalized
+            continue
+        return str(candidate)
+    return None
+
+
+def _extract_discovery_fields(payload: Any) -> list[tuple[str, str]]:
+    if not isinstance(payload, dict):
+        return []
+
+    for key in ("fields", "columns", "headers"):
+        maybe_fields = payload.get(key)
+        parsed_fields = _normalize_discovery_fields(maybe_fields)
+        if parsed_fields:
+            return parsed_fields
+
+    file_obj = payload.get("file")
+    if isinstance(file_obj, dict):
+        for key in ("fields", "columns", "headers"):
+            maybe_fields = file_obj.get(key)
+            parsed_fields = _normalize_discovery_fields(maybe_fields)
+            if parsed_fields:
+                return parsed_fields
+
+    return []
+
+
+def _normalize_discovery_fields(raw_fields: Any) -> list[tuple[str, str]]:
+    if not isinstance(raw_fields, list):
+        return []
+
+    normalized_fields: list[tuple[str, str]] = []
+    seen_keys: set[str] = set()
+    for index, field in enumerate(raw_fields):
+        normalized_field = _normalize_discovery_field(field, index=index)
+        if normalized_field is None:
+            continue
+        field_key, _ = normalized_field
+        if field_key in seen_keys:
+            continue
+        seen_keys.add(field_key)
+        normalized_fields.append(normalized_field)
+    return normalized_fields
+
+
+def _normalize_discovery_field(value: Any, *, index: int) -> tuple[str, str] | None:
+    if isinstance(value, (list, tuple)):
+        if len(value) < 2:
+            return None
+        field_key = _normalize_field_key(value[0])
+        field_name = _normalize_field_name(value[1])
+        if field_key is None or field_name is None:
+            return None
+        return field_key, field_name
+
+    if isinstance(value, dict):
+        field_key = None
+        for key in ("id", "key", "index", "column"):
+            field_key = _normalize_field_key(value.get(key))
+            if field_key is not None:
+                break
+        if field_key is None:
+            field_key = str(index)
+
+        field_name = None
+        for key in ("name", "title", "label"):
+            field_name = _normalize_field_name(value.get(key))
+            if field_name is not None:
+                break
+        if field_name is None:
+            return None
+        return field_key, field_name
+
+    field_name = _normalize_field_name(value)
+    if field_name is None:
+        return None
+    return str(index), field_name
+
+
+def _normalize_field_key(value: Any) -> str | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, str):
+        normalized = value.strip()
+        if normalized:
+            return normalized
+    return None
+
+
+def _normalize_field_name(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    normalized = value.strip()
+    if not normalized:
+        return None
+    return normalized

kantree_cli/services/kql.py

@@ -0,0 +1,43 @@
+from typing import Any
+
+from kantree_cli.core.client import KantreeClient
+from kantree_cli.core.errors import ApiError
+from kantree_cli.core.response import JsonObject, extract_object_list
+
+
+def validate_kql(client: KantreeClient, *, kql_text: str) -> Any:
+    return _query_kql_endpoint(client, endpoint="/kql/validate", kql_text=kql_text)
+
+
+def parse_kql(client: KantreeClient, *, kql_text: str) -> Any:
+    return _query_kql_endpoint(client, endpoint="/kql/parse-filter", kql_text=kql_text)
+
+
+def list_kql_functions(client: KantreeClient) -> list[JsonObject]:
+    payload = client.get_json("/kql/autocomplete/functions")
+    return extract_object_list(
+        payload,
+        context="`GET /kql/autocomplete/functions`",
+        preferred_keys=("functions", "data", "items", "results"),
+    )
+
+
+def _query_kql_endpoint(client: KantreeClient, *, endpoint: str, kql_text: str) -> Any:
+    encoded = _quote_kql(kql_text)
+    try:
+        return client.get_json(f"{endpoint}?source={encoded}")
+    except ApiError as exc:
+        if not _is_q_required_error(exc):
+            raise
+    return client.get_json(f"{endpoint}?q={encoded}")
+
+
+def _is_q_required_error(exc: ApiError) -> bool:
+    message = str(exc).lower()
+    return "q:" in message and "required field" in message
+
+
+def _quote_kql(text: str) -> str:
+    import urllib.parse
+
+    return urllib.parse.quote(text)

kantree_cli/services/resolver.py

@@ -0,0 +1,236 @@
+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.services.cards import card_id as card_identifier
+from kantree_cli.services.cards import get_card, get_workspace_card_by_ref
+from kantree_cli.services.workspaces import get_workspace, list_workspaces
+from kantree_cli.services.workspaces import workspace_id as workspace_identifier
+
+JsonObject = dict[str, Any]
+
+
+@dataclass(slots=True)
+class ResolvedWorkspace:
+    workspace: JsonObject
+    selector_source: str
+    selector_value: str
+
+
+@dataclass(slots=True)
+class ResolvedCard:
+    card: JsonObject
+    selector_source: str
+    selector_value: str
+    workspace: JsonObject | None = None
+
+
+@dataclass(slots=True)
+class ResolvedCardSelector:
+    card_id: int
+    selector_source: str
+    selector_value: str
+    workspace: JsonObject | None = None
+
+
+def resolve_workspace(
+    client: KantreeClient,
+    *,
+    organization_id: int | None = None,
+    workspace_id: int | None = None,
+    workspace_name: str | None = None,
+    default_workspace: str | None = None,
+    default_workspace_source: str | None = None,
+    require_selector: bool = True,
+) -> ResolvedWorkspace | None:
+    if workspace_id is not None:
+        workspace = get_workspace(client, workspace_id)
+        return ResolvedWorkspace(
+            workspace=workspace,
+            selector_source="flag:--workspace-id",
+            selector_value=str(workspace_id),
+        )
+
+    if workspace_name is not None:
+        normalized_name = _normalize_workspace_name(
+            workspace_name,
+            source="flag:--workspace",
+        )
+        return _resolve_workspace_by_name(
+            client,
+            organization_id=organization_id,
+            workspace_name=normalized_name,
+            selector_source="flag:--workspace",
+        )
+
+    if default_workspace:
+        normalized_default = default_workspace.strip()
+        if normalized_default:
+            parsed_default_id = _parse_int(normalized_default)
+            if parsed_default_id is not None:
+                source = default_workspace_source or "runtime:default_workspace"
+                if parsed_default_id < 1:
+                    raise ValidationError(
+                        f"{source} expects a positive integer workspace id when numeric, "
+                        f"got `{normalized_default}`."
+                    )
+                workspace = get_workspace(client, parsed_default_id)
+                return ResolvedWorkspace(
+                    workspace=workspace,
+                    selector_source=source,
+                    selector_value=normalized_default,
+                )
+            source = default_workspace_source or "runtime:default_workspace"
+            return _resolve_workspace_by_name(
+                client,
+                organization_id=organization_id,
+                workspace_name=normalized_default,
+                selector_source=source,
+            )
+
+    if require_selector:
+        raise ValidationError(
+            "Missing workspace selector. Use `--workspace-id`, `--workspace`, or configure a default workspace."
+        )
+
+    return None
+
+
+def resolve_card_for_show(
+    client: KantreeClient,
+    *,
+    card_id_value: int | None,
+    card_ref: int | None,
+    workspace_id_value: int | None,
+    workspace_name_value: str | None,
+    organization_id: int | None = None,
+    default_workspace: str | None = None,
+    default_workspace_source: str | None = None,
+) -> ResolvedCard:
+    selector = resolve_card_selector(
+        client,
+        card_id_value=card_id_value,
+        card_ref=card_ref,
+        workspace_id_value=workspace_id_value,
+        workspace_name_value=workspace_name_value,
+        organization_id=organization_id,
+        default_workspace=default_workspace,
+        default_workspace_source=default_workspace_source,
+    )
+    return ResolvedCard(
+        card=get_card(client, selector.card_id),
+        selector_source=selector.selector_source,
+        selector_value=selector.selector_value,
+        workspace=selector.workspace,
+    )
+
+
+def resolve_card_selector(
+    client: KantreeClient,
+    *,
+    card_id_value: int | None,
+    card_ref: int | None,
+    workspace_id_value: int | None,
+    workspace_name_value: str | None,
+    organization_id: int | None = None,
+    default_workspace: str | None = None,
+    default_workspace_source: str | None = None,
+) -> ResolvedCardSelector:
+    if card_id_value is not None and card_ref is not None:
+        raise ValidationError("Use either `CARD_ID` or `--ref`, not both.")
+
+    if card_id_value is not None:
+        return ResolvedCardSelector(
+            card_id=card_id_value,
+            selector_source="arg:CARD_ID",
+            selector_value=str(card_id_value),
+        )
+
+    if card_ref is None:
+        raise ValidationError("Missing card selector. Provide `CARD_ID` or `--ref`.")
+
+    resolved_workspace = resolve_workspace(
+        client,
+        organization_id=organization_id,
+        workspace_id=workspace_id_value,
+        workspace_name=workspace_name_value,
+        default_workspace=default_workspace,
+        default_workspace_source=default_workspace_source,
+        require_selector=True,
+    )
+
+    workspace = resolved_workspace.workspace
+    resolved_workspace_id = workspace_identifier(workspace)
+    match = get_workspace_card_by_ref(
+        client,
+        workspace_id=resolved_workspace_id,
+        card_ref=card_ref,
+    )
+    resolved_id = card_identifier(match, context="Card lookup response")
+    return ResolvedCardSelector(
+        card_id=resolved_id,
+        selector_source="flag:--ref",
+        selector_value=str(card_ref),
+        workspace=workspace,
+    )
+
+
+def _resolve_workspace_by_name(
+    client: KantreeClient,
+    *,
+    organization_id: int | None,
+    workspace_name: str,
+    selector_source: str,
+) -> ResolvedWorkspace:
+    workspace_pool = list_workspaces(
+        client,
+        organization_id=organization_id,
+        include_team_projects=organization_id is not None,
+    )
+    matches = [
+        workspace for workspace in workspace_pool if workspace.get("title") == workspace_name
+    ]
+    if not matches:
+        if organization_id is None:
+            raise NotFoundError(
+                f"Workspace `{workspace_name}` not found. If it belongs to an organization "
+                "team, retry with root `--org ORG`."
+            )
+        raise NotFoundError(
+            f"Workspace `{workspace_name}` not found in organization `{organization_id}`."
+        )
+    if len(matches) > 1:
+        ids = ", ".join(str(match.get("id")) for match in matches)
+        raise AmbiguityError(
+            f"Workspace `{workspace_name}` is ambiguous ({len(matches)} matches: {ids}). "
+            "Use `--workspace-id`."
+        )
+    return ResolvedWorkspace(
+        workspace=matches[0],
+        selector_source=selector_source,
+        selector_value=workspace_name,
+    )
+
+
+def _normalize_workspace_name(workspace_name: str, *, source: str) -> str:
+    normalized = workspace_name.strip()
+    if not normalized:
+        raise ValidationError(f"{source} expects a non-empty workspace name.")
+    return normalized
+
+
+def _parse_int(value: str) -> int | None:
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _workspace_label(workspace: JsonObject) -> str:
+    title = workspace.get("title")
+    if isinstance(title, str):
+        normalized_title = title.strip()
+        if normalized_title:
+            return normalized_title
+    return str(workspace_identifier(workspace))

kantree_cli/services/search.py

@@ -0,0 +1,67 @@
+from typing import Any
+
+from kantree_cli.core.client import KantreeClient
+from kantree_cli.core.errors import ApiError, ValidationError
+from kantree_cli.core.response import extract_object_list, next_page_header_value
+
+JsonObject = dict[str, Any]
+
+
+def search_cards(
+    client: KantreeClient,
+    *,
+    organization_id: int | None = None,
+    filter_text: str | None = None,
+    limit: int | None = None,
+) -> 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["filters"] = normalized_filter
+
+    path = "/search" if organization_id is None else f"/organizations/{organization_id}/search"
+    merged_cards: list[JsonObject] = []
+    next_page = 1
+    legacy_filter_param = False
+    while True:
+        request_params = dict(params)
+        if legacy_filter_param and "filters" in request_params:
+            request_params["filter"] = request_params.pop("filters")
+        request_params["page"] = str(next_page)
+        try:
+            response = client.request(method="GET", path=path, params=request_params)
+        except ApiError as exc:
+            if not legacy_filter_param and "filters" in params and _is_filter_required_error(exc):
+                legacy_filter_param = True
+                retry_params = dict(params)
+                retry_params["filter"] = retry_params.pop("filters")
+                retry_params["page"] = str(next_page)
+                response = client.request(method="GET", path=path, params=retry_params)
+            else:
+                raise
+        page_cards = extract_object_list(
+            response.data,
+            context=f"`GET {path}`",
+            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
+
+
+def _is_filter_required_error(exc: ApiError) -> bool:
+    message = str(exc).lower()
+    return "filter:" in message and "required field" in message