ktr-cli 0.1.0__py3-none-any.whl

kantree_cli/services/workspaces.py

@@ -0,0 +1,1300 @@
+from dataclasses import dataclass
+from typing import Any
+
+from kantree_cli.core.client import KantreeClient
+from kantree_cli.core.errors import NotFoundError, ValidationError
+from kantree_cli.core.response import (
+    extract_object,
+    extract_object_list,
+    next_page_header_value,
+)
+
+JsonObject = dict[str, Any]
+
+
+@dataclass(slots=True)
+class OrganizationContext:
+    id: int
+    title: str | None
+
+
+def list_organizations(client: KantreeClient) -> list[JsonObject]:
+    payload = client.get_json("/organizations")
+    return extract_object_list(
+        payload,
+        context="`GET /organizations`",
+        preferred_keys=("organizations", "data", "items", "results"),
+    )
+
+
+def get_organization(client: KantreeClient, organization_id: int) -> JsonObject:
+    response = client.get_json(f"/organizations/{organization_id}/")
+    return extract_object(
+        response,
+        context=f"`GET /organizations/{organization_id}/`",
+        preferred_keys=("organization", "data", "item", "result"),
+    )
+
+
+def delete_organization(client: KantreeClient, organization_id: int) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/organizations/{organization_id}/",
+    )
+    return response.data
+
+
+def create_organization(client: KantreeClient, *, title: str) -> JsonObject:
+    response = client.request(
+        method="POST",
+        path="/organizations/",
+        json_body={"name": title},
+    )
+    return extract_object(
+        response.data,
+        context="`POST /organizations/`",
+        preferred_keys=("organization", "data", "item", "result"),
+    )
+
+
+def list_teams_for_org(client: KantreeClient, organization_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/organizations/{organization_id}/teams")
+    return extract_object_list(
+        payload,
+        context=f"`GET /organizations/{organization_id}/teams`",
+        preferred_keys=("teams", "data", "items", "results"),
+    )
+
+
+def create_team(client: KantreeClient, *, organization_id: int, name: str) -> JsonObject:
+    response = client.request(
+        method="POST",
+        path=f"/organizations/{organization_id}/teams/",
+        json_body={"name": name},
+    )
+    return extract_object(
+        response.data,
+        context=f"`POST /organizations/{organization_id}/teams/`",
+        preferred_keys=("team", "data", "item", "result"),
+    )
+
+
+def get_team(
+    client: KantreeClient,
+    *,
+    organization_id: int,
+    team_id: int,
+    with_members: bool = False,
+) -> JsonObject:
+    params: dict[str, str] = {}
+    if with_members:
+        params["with_members"] = "true"
+
+    response = client.request(
+        method="GET",
+        path=f"/organizations/{organization_id}/teams/{team_id}",
+        params=params or None,
+    )
+    return extract_object(
+        response.data,
+        context=f"`GET /organizations/{organization_id}/teams/{team_id}`",
+        preferred_keys=("team", "data", "item", "result"),
+    )
+
+
+def delete_team(
+    client: KantreeClient,
+    *,
+    organization_id: int,
+    team_id: int,
+) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/organizations/{organization_id}/teams/{team_id}",
+    )
+    return response.data
+
+
+def list_workspaces_for_org(client: KantreeClient, organization_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/organizations/{organization_id}/projects")
+    return extract_object_list(
+        payload,
+        context=f"`GET /organizations/{organization_id}/projects`",
+        preferred_keys=("projects", "data", "items", "results"),
+    )
+
+
+def list_team_workspaces(
+    client: KantreeClient,
+    *,
+    organization_id: int,
+    team_id: int,
+) -> list[JsonObject]:
+    payload = client.get_json(f"/organizations/{organization_id}/teams/{team_id}/projects")
+    return extract_object_list(
+        payload,
+        context=f"`GET /organizations/{organization_id}/teams/{team_id}/projects`",
+        preferred_keys=("projects", "data", "items", "results"),
+    )
+
+
+def list_workspaces_for_org_with_teams(
+    client: KantreeClient,
+    organization_id: int,
+) -> list[JsonObject]:
+    workspaces = [
+        _workspace_with_context(workspace, organization_id=organization_id, team=None)
+        for workspace in list_workspaces_for_org(client, organization_id)
+    ]
+    seen_ids = {
+        workspace_id
+        for workspace_id in (_parse_positive_int(workspace.get("id")) for workspace in workspaces)
+        if workspace_id is not None
+    }
+
+    for team in list_teams_for_org(client, organization_id):
+        team_id = _parse_positive_int(team.get("id"))
+        if team_id is None:
+            continue
+        for workspace in list_team_workspaces(
+            client,
+            organization_id=organization_id,
+            team_id=team_id,
+        ):
+            workspace_id = _parse_positive_int(workspace.get("id"))
+            if workspace_id is not None and workspace_id in seen_ids:
+                continue
+            if workspace_id is not None:
+                seen_ids.add(workspace_id)
+            workspaces.append(
+                _workspace_with_context(workspace, organization_id=organization_id, team=team)
+            )
+
+    return workspaces
+
+
+def list_workspaces(
+    client: KantreeClient,
+    organization_id: int | None = None,
+    *,
+    include_team_projects: bool = False,
+) -> list[JsonObject]:
+    if organization_id is not None:
+        if include_team_projects:
+            return list_workspaces_for_org_with_teams(client, organization_id)
+        return list_workspaces_for_org(client, organization_id)
+
+    organizations = list_organizations(client)
+    workspaces: list[JsonObject] = []
+    for org in organizations:
+        org_context = _organization_context(org)
+        org_workspaces = (
+            list_workspaces_for_org_with_teams(client, org_context.id)
+            if include_team_projects
+            else list_workspaces_for_org(client, org_context.id)
+        )
+        for workspace in org_workspaces:
+            workspaces.append(
+                _workspace_with_context(
+                    workspace,
+                    organization_id=org_context.id,
+                    organization_title=org_context.title,
+                    team=None,
+                )
+            )
+    return workspaces
+
+
+def get_workspace(client: KantreeClient, workspace_id: int) -> JsonObject:
+    payload = client.get_json(f"/projects/{workspace_id}")
+    return extract_object(
+        payload,
+        context=f"`GET /projects/{workspace_id}`",
+        preferred_keys=("project", "data", "item", "result"),
+        require_id_field=False,
+        object_check=_looks_like_workspace,
+    )
+
+
+def list_workspace_reminders(client: KantreeClient, workspace_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/projects/{workspace_id}/reminders")
+    return extract_object_list(
+        payload,
+        context=f"`GET /projects/{workspace_id}/reminders`",
+        preferred_keys=("reminders", "data", "items", "results"),
+    )
+
+
+def list_workspace_export_templates(
+    client: KantreeClient,
+    workspace_id: int,
+) -> list[JsonObject]:
+    payload = client.get_json(f"/projects/{workspace_id}/export-templates")
+    return extract_object_list(
+        payload,
+        context=f"`GET /projects/{workspace_id}/export-templates`",
+        preferred_keys=("export_templates", "templates", "data", "items", "results"),
+    )
+
+
+def list_workspace_email_templates(
+    client: KantreeClient,
+    workspace_id: int,
+) -> list[JsonObject]:
+    payload = client.get_json(f"/projects/{workspace_id}/email-templates")
+    return extract_object_list(
+        payload,
+        context=f"`GET /projects/{workspace_id}/email-templates`",
+        preferred_keys=("email_templates", "templates", "data", "items", "results"),
+    )
+
+
+def get_workspace_email_template(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    template_id: int,
+) -> JsonObject:
+    payload = client.get_json(f"/projects/{workspace_id}/email-templates/{template_id}")
+    return extract_object(
+        payload,
+        context=f"`GET /projects/{workspace_id}/email-templates/{template_id}`",
+        preferred_keys=("email_template", "template", "data", "item", "result"),
+    )
+
+
+def create_workspace_email_template(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    name: str,
+    subject: str,
+    body: str | None = None,
+) -> JsonObject:
+    payload: JsonObject = {"name": name, "subject": subject}
+    if body is not None:
+        payload["body"] = body
+
+    response = client.request(
+        method="POST",
+        path=f"/projects/{workspace_id}/email-templates",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`POST /projects/{workspace_id}/email-templates`",
+        preferred_keys=("email_template", "template", "data", "item", "result"),
+    )
+
+
+def update_workspace_email_template(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    template_id: int,
+    name: str | None = None,
+    subject: str | None = None,
+    body: str | None = None,
+) -> JsonObject:
+    changes: JsonObject = {}
+    if name is not None:
+        changes["name"] = name
+    if subject is not None:
+        changes["subject"] = subject
+    if body is not None:
+        changes["body"] = body
+    if not changes:
+        raise ValidationError(
+            "Workspace email-template update requires at least one mutation option."
+        )
+
+    current_template = get_workspace_email_template(
+        client,
+        workspace_id=workspace_id,
+        template_id=template_id,
+    )
+    payload = {
+        "name": _required_email_template_value(
+            current_template,
+            key="name",
+            workspace_id=workspace_id,
+            template_id=template_id,
+        ),
+        "subject": _required_email_template_value(
+            current_template,
+            key="subject",
+            workspace_id=workspace_id,
+            template_id=template_id,
+        ),
+        "body": _required_email_template_value(
+            current_template,
+            key="body",
+            workspace_id=workspace_id,
+            template_id=template_id,
+        ),
+        **changes,
+    }
+
+    response = client.request(
+        method="PUT",
+        path=f"/projects/{workspace_id}/email-templates/{template_id}",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`PUT /projects/{workspace_id}/email-templates/{template_id}`",
+        preferred_keys=("email_template", "template", "data", "item", "result"),
+    )
+
+
+def delete_workspace_email_template(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    template_id: int,
+) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/projects/{workspace_id}/email-templates/{template_id}",
+    )
+    return response.data
+
+
+def create_workspace_export_template(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    name: str,
+    format_name: str,
+    attributes: list[str],
+) -> JsonObject:
+    response = client.request(
+        method="POST",
+        path=f"/projects/{workspace_id}/export-templates",
+        json_body={
+            "name": name,
+            "format": format_name,
+            "attributes": attributes,
+        },
+    )
+    return extract_object(
+        response.data,
+        context=f"`POST /projects/{workspace_id}/export-templates`",
+        preferred_keys=("export_template", "template", "data", "item", "result"),
+    )
+
+
+def update_workspace_export_template(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    template_id: int,
+    name: str | None = None,
+    format_name: str | None = None,
+    attributes: list[str] | None = None,
+) -> JsonObject:
+    payload: JsonObject = {}
+    if name is not None:
+        payload["name"] = name
+    if format_name is not None:
+        payload["format"] = format_name
+    if attributes is not None:
+        payload["attributes"] = attributes
+    if not payload:
+        raise ValidationError(
+            "Workspace export-template update requires at least one mutation option."
+        )
+
+    current_template = _find_workspace_export_template(
+        list_workspace_export_templates(client, workspace_id),
+        workspace_id=workspace_id,
+        template_id=template_id,
+    )
+    payload = {
+        "name": _required_export_template_value(
+            current_template,
+            key="name",
+            workspace_id=workspace_id,
+            template_id=template_id,
+        ),
+        "format": _required_export_template_value(
+            current_template,
+            key="format",
+            workspace_id=workspace_id,
+            template_id=template_id,
+        ),
+        "attributes": _required_export_template_value(
+            current_template,
+            key="attributes",
+            workspace_id=workspace_id,
+            template_id=template_id,
+        ),
+        **payload,
+    }
+
+    response = client.request(
+        method="PUT",
+        path=f"/projects/{workspace_id}/export-templates/{template_id}",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`PUT /projects/{workspace_id}/export-templates/{template_id}`",
+        preferred_keys=("export_template", "template", "data", "item", "result"),
+    )
+
+
+def delete_workspace_export_template(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    template_id: int,
+) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/projects/{workspace_id}/export-templates/{template_id}",
+    )
+    return response.data
+
+
+def _find_workspace_export_template(
+    templates: list[JsonObject],
+    *,
+    workspace_id: int,
+    template_id: int,
+) -> JsonObject:
+    for template in templates:
+        parsed_template_id = _parse_positive_int(template.get("id"))
+        if parsed_template_id == template_id:
+            return template
+    raise NotFoundError(
+        f"Workspace export-template id `{template_id}` was not found in workspace `{workspace_id}`."
+    )
+
+
+def _required_export_template_value(
+    template: JsonObject,
+    *,
+    key: str,
+    workspace_id: int,
+    template_id: int,
+) -> Any:
+    if key not in template:
+        raise ValidationError(
+            "Workspace export-template id "
+            f"`{template_id}` in workspace `{workspace_id}` does not include `{key}`."
+        )
+    return template[key]
+
+
+def _required_email_template_value(
+    template: JsonObject,
+    *,
+    key: str,
+    workspace_id: int,
+    template_id: int,
+) -> Any:
+    if key not in template:
+        raise ValidationError(
+            "Workspace email-template id "
+            f"`{template_id}` in workspace `{workspace_id}` does not include `{key}`."
+        )
+    return template[key]
+
+
+def create_workspace(
+    client: KantreeClient,
+    *,
+    title: str,
+    organization_id: int | None = None,
+    team_id: int | None = None,
+    include_cards: bool | None = None,
+) -> JsonObject:
+    if team_id is not None and organization_id is None:
+        raise ValidationError("Workspace creation with a team requires an organization.")
+
+    payload: JsonObject = {"title": title}
+    if include_cards is not None:
+        payload["include_cards"] = include_cards
+    if team_id is not None:
+        payload["team_id"] = team_id
+
+    if organization_id is None:
+        endpoint = "/projects"
+        context = "`POST /projects`"
+    else:
+        endpoint = f"/organizations/{organization_id}/projects"
+        context = f"`POST /organizations/{organization_id}/projects`"
+
+    response = client.request(
+        method="POST",
+        path=endpoint,
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=context,
+        preferred_keys=("project", "workspace", "data", "item", "result"),
+        require_id_field=False,
+        object_check=_looks_like_workspace,
+    )
+
+
+def delete_workspace(client: KantreeClient, *, workspace_id: int) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/projects/{workspace_id}",
+    )
+    return response.data
+
+
+def relocate_workspace(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    organization_id: int,
+    team_id: int | None = None,
+) -> Any:
+    payload: JsonObject = {"org_id": organization_id}
+    if team_id is not None:
+        payload["team_id"] = team_id
+
+    response = client.request(
+        method="POST",
+        path=f"/projects/{workspace_id}/relocate-to-other-org",
+        json_body=payload,
+    )
+    return response.data
+
+
+def list_workspace_fields(client: KantreeClient, workspace_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/projects/{workspace_id}/attributes")
+    return extract_object_list(
+        payload,
+        context=f"`GET /projects/{workspace_id}/attributes`",
+        preferred_keys=("attributes", "data", "items", "results"),
+    )
+
+
+def list_workspace_views(client: KantreeClient, workspace_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/projects/{workspace_id}/views")
+    return extract_object_list(
+        payload,
+        context=f"`GET /projects/{workspace_id}/views`",
+        preferred_keys=("views", "data", "items", "results"),
+    )
+
+
+def get_workspace_view(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    view_id: int,
+) -> JsonObject:
+    payload = client.get_json(f"/projects/{workspace_id}/views/{view_id}")
+    return extract_object(
+        payload,
+        context=f"`GET /projects/{workspace_id}/views/{view_id}`",
+        preferred_keys=("view", "data", "item", "result"),
+    )
+
+
+def create_workspace_view(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    name: str,
+    mode: str | None = None,
+    filter_text: str | None = None,
+    include_archived: bool | None = None,
+    include_descendants: bool | None = None,
+    public: bool | None = None,
+) -> JsonObject:
+    payload = _workspace_view_payload(
+        name=name,
+        mode=mode,
+        filter_text=filter_text,
+        include_archived=include_archived,
+        include_descendants=include_descendants,
+        public=public,
+    )
+    response = client.request(
+        method="POST",
+        path=f"/projects/{workspace_id}/views",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`POST /projects/{workspace_id}/views`",
+        preferred_keys=("view", "data", "item", "result"),
+    )
+
+
+def update_workspace_view(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    view_id: int,
+    name: str | None = None,
+    mode: str | None = None,
+    filter_text: str | None = None,
+    clear_filter: bool = False,
+    include_archived: bool | None = None,
+    include_descendants: bool | None = None,
+    icon: str | None = None,
+    card_ref: int | None = None,
+    clear_card_ref: bool = False,
+    limit_to_ref: bool | None = None,
+    public: bool | None = None,
+) -> JsonObject:
+    if filter_text is not None and clear_filter:
+        raise ValidationError("Use either `--filter` or `--clear-filter`, not both.")
+    if card_ref is not None and clear_card_ref:
+        raise ValidationError("Use either `--card-ref` or `--clear-card-ref`, not both.")
+
+    payload = _workspace_view_payload(
+        name=name,
+        mode=mode,
+        filter_text=None if clear_filter else filter_text,
+        include_filter=filter_text is not None or clear_filter,
+        include_archived=include_archived,
+        include_descendants=include_descendants,
+        icon=icon,
+        card_ref=None if clear_card_ref else card_ref,
+        include_card_ref=card_ref is not None or clear_card_ref,
+        limit_to_ref=limit_to_ref,
+        public=public,
+    )
+    if not payload:
+        raise ValidationError("Workspace view update requires at least one mutation option.")
+
+    response = client.request(
+        method="PUT",
+        path=f"/projects/{workspace_id}/views/{view_id}",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`PUT /projects/{workspace_id}/views/{view_id}`",
+        preferred_keys=("view", "data", "item", "result"),
+    )
+
+
+def delete_workspace_view(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    view_id: int,
+) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/projects/{workspace_id}/views/{view_id}",
+    )
+    return response.data
+
+
+def list_project_automations(client: KantreeClient, workspace_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/projects/{workspace_id}/automations/")
+    return extract_object_list(
+        payload,
+        context=f"`GET /projects/{workspace_id}/automations/`",
+        preferred_keys=("automations", "data", "items", "results"),
+    )
+
+
+def get_project_automation(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    rule_id: int,
+) -> JsonObject:
+    response = client.get_json(f"/projects/{workspace_id}/automations/{rule_id}")
+    return extract_object(
+        response,
+        context=f"`GET /projects/{workspace_id}/automations/{rule_id}`",
+        preferred_keys=("automation", "data", "item", "result"),
+    )
+
+
+def create_project_automation(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    payload: JsonObject,
+) -> JsonObject:
+    response = client.request(
+        method="POST",
+        path=f"/projects/{workspace_id}/automations/",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`POST /projects/{workspace_id}/automations/`",
+        preferred_keys=("automation", "data", "item", "result"),
+    )
+
+
+def update_project_automation(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    rule_id: int,
+    payload: JsonObject,
+) -> JsonObject:
+    response = client.request(
+        method="PUT",
+        path=f"/projects/{workspace_id}/automations/{rule_id}",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`PUT /projects/{workspace_id}/automations/{rule_id}`",
+        preferred_keys=("automation", "data", "item", "result"),
+    )
+
+
+def delete_project_automation(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    rule_id: int,
+) -> Any:
+    response = client.request(
+        method="DELETE",
+        path=f"/projects/{workspace_id}/automations/{rule_id}",
+    )
+    return response.data
+
+
+def list_automation_type_events(client: KantreeClient) -> list[JsonObject]:
+    payload = client.get_json("/automation-types/events")
+    return extract_object_list(
+        payload,
+        context="`GET /automation-types/events`",
+        preferred_keys=("events", "data", "items", "results"),
+    )
+
+
+def list_automation_type_actions(client: KantreeClient) -> list[JsonObject]:
+    payload = client.get_json("/automation-types/actions")
+    return extract_object_list(
+        payload,
+        context="`GET /automation-types/actions`",
+        preferred_keys=("actions", "data", "items", "results"),
+    )
+
+
+def list_automation_type_queries(client: KantreeClient) -> list[JsonObject]:
+    payload = client.get_json("/automation-types/queries")
+    return extract_object_list(
+        payload,
+        context="`GET /automation-types/queries`",
+        preferred_keys=("queries", "data", "items", "results"),
+    )
+
+
+def list_field_types(client: KantreeClient) -> list[JsonObject]:
+    payload = client.get_json("/attribute-types")
+    return extract_object_list(
+        payload,
+        context="`GET /attribute-types`",
+        preferred_keys=("attribute_types", "types", "data", "items", "results"),
+    )
+
+
+def list_workspace_group_types(client: KantreeClient, workspace_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/projects/{workspace_id}/group-types")
+    return extract_object_list(
+        payload,
+        context=f"`GET /projects/{workspace_id}/group-types`",
+        preferred_keys=("group_types", "types", "data", "items", "results"),
+    )
+
+
+def list_card_groups(
+    client: KantreeClient,
+    parent_id: int,
+    *,
+    type_id: int | None = None,
+) -> list[JsonObject]:
+    params: dict[str, str] | None = None
+    if type_id is not None:
+        params = {"type_id": str(type_id)}
+
+    response = client.request(
+        method="GET",
+        path=f"/cards/{parent_id}/groups",
+        params=params,
+    )
+    payload = response.data
+    return extract_object_list(
+        payload,
+        context=f"`GET /cards/{parent_id}/groups`",
+        preferred_keys=("groups", "data", "items", "results"),
+    )
+
+
+def create_card_group(
+    client: KantreeClient,
+    *,
+    parent_id: int,
+    title: str,
+    type_id: int,
+    card_state: str | None = None,
+    description: str | None = None,
+    color: str | None = None,
+    max_cards_limit: int | None = None,
+) -> JsonObject:
+    payload: dict[str, object] = {
+        "title": title,
+        "type_id": type_id,
+    }
+    if card_state is not None:
+        payload["card_state"] = card_state
+    if description is not None:
+        payload["description"] = description
+    if color is not None:
+        payload["color"] = color
+    if max_cards_limit is not None:
+        payload["max_cards_limit"] = max_cards_limit
+
+    response = client.request(
+        method="POST",
+        path=f"/cards/{parent_id}/groups/",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`POST /cards/{parent_id}/groups/`",
+        preferred_keys=("group", "data", "item", "result"),
+    )
+
+
+def update_card_group(
+    client: KantreeClient,
+    *,
+    parent_id: int,
+    group_id: int,
+    title: str | None = None,
+    card_state: str | None = None,
+    description: str | None = None,
+    color: str | None = None,
+    max_cards_limit: int | None = None,
+) -> JsonObject:
+    payload: dict[str, object] = {}
+    if title is not None:
+        payload["title"] = title
+    if card_state is not None:
+        payload["card_state"] = card_state
+    if description is not None:
+        payload["description"] = description
+    if color is not None:
+        payload["color"] = color
+    if max_cards_limit is not None:
+        payload["max_cards_limit"] = max_cards_limit
+
+    response = client.request(
+        method="PUT",
+        path=f"/cards/{parent_id}/groups/{group_id}/",
+        json_body=payload,
+    )
+    return extract_object(
+        response.data,
+        context=f"`PUT /cards/{parent_id}/groups/{group_id}/`",
+        preferred_keys=("group", "data", "item", "result"),
+    )
+
+
+def set_cards_state(
+    client: KantreeClient,
+    *,
+    parent_id: int,
+    group_id: int,
+    state: str,
+) -> Any:
+    response = client.request(
+        method="POST",
+        path=f"/cards/{parent_id}/groups/{group_id}/set-cards-state",
+        json_body={"state": state},
+    )
+    return response.data
+
+
+def export_workspace_json(
+    client: KantreeClient,
+    workspace_id: int,
+    *,
+    kql_filter: str | None = None,
+) -> Any:
+    params: dict[str, str] = {}
+    if kql_filter is not None:
+        normalized_filter = kql_filter.strip()
+        if not normalized_filter:
+            raise ValidationError("`--filter` expects a non-empty KQL value.")
+        params["filter"] = normalized_filter
+
+    merged_payload: Any = None
+    next_page = 1
+    while True:
+        request_params = dict(params)
+        request_params["page"] = str(next_page)
+
+        response = client.request(
+            method="GET",
+            path=f"/projects/{workspace_id}/export/json",
+            params=request_params,
+        )
+        if merged_payload is None:
+            merged_payload = response.data
+        else:
+            merged_payload = _merge_export_page(
+                merged_payload,
+                response.data,
+                context=f"`GET /projects/{workspace_id}/export/json`",
+            )
+
+        parsed_next_page = next_page_header_value(response.headers)
+        if parsed_next_page is None:
+            break
+        next_page = parsed_next_page
+
+    return merged_payload
+
+
+def start_workspace_export_artifact(
+    client: KantreeClient,
+    workspace_id: int,
+    *,
+    export_format: str,
+    kql_filter: str | None = None,
+    include_descendants: bool | None = None,
+    notify: bool = False,
+) -> Any:
+    payload: JsonObject = {
+        "format": export_format,
+        "notify": notify,
+    }
+    if kql_filter is not None:
+        normalized_filter = kql_filter.strip()
+        if not normalized_filter:
+            raise ValidationError("`--filter` expects a non-empty KQL value.")
+        payload["filter"] = normalized_filter
+    if include_descendants is not None:
+        payload["include_descendants"] = include_descendants
+
+    response = client.request(
+        method="POST",
+        path=f"/projects/{workspace_id}/export",
+        json_body=payload,
+    )
+    return response.data
+
+
+def workspace_summary(workspace: JsonObject) -> JsonObject:
+    summary: JsonObject = {
+        "id": workspace.get("id"),
+        "title": workspace.get("title"),
+        "top_level_card_id": workspace.get("top_level_card_id"),
+    }
+
+    organization_id = workspace.get("organization_id")
+    if organization_id is not None:
+        summary["organization_id"] = organization_id
+
+    organization_title = workspace.get("organization_title")
+    if organization_title is not None:
+        summary["organization_title"] = organization_title
+
+    team_id = workspace.get("team_id")
+    if team_id is not None:
+        summary["team_id"] = team_id
+
+    team_name = workspace.get("team_name")
+    if team_name is not None:
+        summary["team_name"] = team_name
+
+    return summary
+
+
+def workspace_view_summary(view: JsonObject) -> JsonObject:
+    summary: JsonObject = {
+        "id": view.get("id"),
+        "title": view.get("title", view.get("name")),
+    }
+    view_type = view.get("type")
+    if view_type is not None:
+        summary["type"] = view_type
+    return summary
+
+
+def _workspace_view_payload(
+    *,
+    name: str | None = None,
+    mode: str | None = None,
+    filter_text: str | None = None,
+    include_filter: bool = False,
+    include_archived: bool | None = None,
+    include_descendants: bool | None = None,
+    icon: str | None = None,
+    card_ref: int | None = None,
+    include_card_ref: bool = False,
+    limit_to_ref: bool | None = None,
+    public: bool | None = None,
+) -> JsonObject:
+    payload: JsonObject = {}
+    if name is not None:
+        payload["name"] = name
+    if mode is not None:
+        payload["mode"] = mode
+    if include_filter or filter_text is not None:
+        payload["filter"] = filter_text
+    if include_archived is not None:
+        payload["include_archived"] = include_archived
+    if include_descendants is not None:
+        payload["include_descendants"] = include_descendants
+    if icon is not None:
+        payload["icon"] = icon
+    if include_card_ref or card_ref is not None:
+        payload["card_ref"] = card_ref
+    if limit_to_ref is not None:
+        payload["limit_to_ref"] = limit_to_ref
+    if public is not None:
+        payload["public"] = public
+    return payload
+
+
+def list_workspace_models(client: KantreeClient, workspace_id: int) -> list[JsonObject]:
+    payload = client.get_json(f"/projects/{workspace_id}/models")
+    return extract_object_list(
+        payload,
+        context=f"`GET /projects/{workspace_id}/models`",
+        preferred_keys=("models", "data", "items", "results"),
+    )
+
+
+def get_workspace_model(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    model_id: int,
+) -> JsonObject:
+    return _find_workspace_model(
+        list_workspace_models(client, workspace_id),
+        workspace_id=workspace_id,
+        model_id=model_id,
+    )
+
+
+def create_workspace_model(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    name: str,
+    color: str | None = None,
+    only_show_own_attributes: bool | None = None,
+    hide_children_attributes: bool | None = None,
+) -> JsonObject:
+    payload: JsonObject = {"name": name, "project_id": workspace_id}
+    if color is not None:
+        payload["card_color"] = color
+    if only_show_own_attributes is not None:
+        payload["only_show_own_attributes"] = only_show_own_attributes
+    if hide_children_attributes is not None:
+        payload["hide_children_attributes"] = hide_children_attributes
+
+    response = client.request(method="POST", path="/models/", json_body=payload)
+    return extract_object(
+        response.data,
+        context="`POST /models/`",
+        preferred_keys=("model", "data", "item", "result"),
+    )
+
+
+def update_workspace_model(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    model_id: int,
+    changes: JsonObject,
+) -> JsonObject:
+    _find_workspace_model(
+        list_workspace_models(client, workspace_id),
+        workspace_id=workspace_id,
+        model_id=model_id,
+    )
+    response = client.request(method="PUT", path=f"/models/{model_id}", json_body=changes)
+    return extract_object(
+        response.data,
+        context=f"`PUT /models/{model_id}`",
+        preferred_keys=("model", "data", "item", "result"),
+    )
+
+
+def delete_workspace_model(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    model_id: int,
+) -> Any:
+    _find_workspace_model(
+        list_workspace_models(client, workspace_id),
+        workspace_id=workspace_id,
+        model_id=model_id,
+    )
+    response = client.request(method="DELETE", path=f"/projects/{workspace_id}/models/{model_id}")
+    return response.data
+
+
+def list_workspace_model_fields(
+    client: KantreeClient,
+    *,
+    workspace_id: int,
+    model_id: int,
+) -> list[JsonObject]:
+    models = list_workspace_models(client, workspace_id)
+    for model in models:
+        parsed_model_id = _parse_int(model.get("id"))
+        if parsed_model_id == model_id:
+            return _extract_model_fields(
+                model,
+                context=f"Model id `{model_id}` from `GET /projects/{workspace_id}/models`",
+            )
+    raise NotFoundError(f"Card type/model id `{model_id}` was not found in this workspace.")
+
+
+def _find_workspace_model(
+    models: list[JsonObject],
+    *,
+    workspace_id: int,
+    model_id: int,
+) -> JsonObject:
+    for model in models:
+        parsed_model_id = _parse_int(model.get("id"))
+        if parsed_model_id == model_id:
+            return model
+    raise NotFoundError(
+        f"Card type/model id `{model_id}` was not found in workspace `{workspace_id}`."
+    )
+
+
+def workspace_id(workspace: JsonObject) -> int:
+    parsed = _parse_int(workspace.get("id"))
+    if parsed is None:
+        raise ValidationError(
+            "Workspace payload does not contain a usable integer `id` for this operation."
+        )
+    return parsed
+
+
+def _organization_context(org: JsonObject) -> OrganizationContext:
+    org_id = _parse_int(org.get("id"))
+    if org_id is None:
+        raise ValidationError("Organization payload is missing integer `id`.")
+    title = org.get("name")
+    if title is None:
+        title = org.get("title")
+    return OrganizationContext(id=org_id, title=title if isinstance(title, str) else None)
+
+
+def _workspace_with_context(
+    workspace: JsonObject,
+    *,
+    organization_id: int,
+    organization_title: str | None = None,
+    team: JsonObject | None,
+) -> JsonObject:
+    with_context = dict(workspace)
+    with_context.setdefault("organization_id", organization_id)
+    if organization_title is not None:
+        with_context.setdefault("organization_title", organization_title)
+    if team is not None:
+        team_id = _parse_positive_int(team.get("id"))
+        if team_id is not None:
+            with_context.setdefault("team_id", team_id)
+        team_title = _team_title(team)
+        if team_title is not None:
+            with_context.setdefault("team_name", team_title)
+    return with_context
+
+
+def _team_title(team: JsonObject) -> str | None:
+    for key in ("name", "title"):
+        value = team.get(key)
+        if isinstance(value, str):
+            normalized = value.strip()
+            if normalized:
+                return normalized
+    return None
+
+
+def _looks_like_workspace(payload: JsonObject) -> bool:
+    return "id" in payload and ("title" in payload or "top_level_card_id" in payload)
+
+
+def _extract_model_fields(model: JsonObject, *, context: str) -> list[JsonObject]:
+    saw_field_container = False
+    for key in ("attributes", "fields"):
+        maybe_fields = model.get(key)
+        if isinstance(maybe_fields, (dict, list)):
+            saw_field_container = True
+            try:
+                return extract_object_list(
+                    maybe_fields,
+                    context=context,
+                    preferred_keys=("attributes", "fields", "data", "items", "results"),
+                )
+            except ValidationError:
+                continue
+
+    if saw_field_container:
+        raise ValidationError(f"{context} does not include usable model-scoped fields.")
+    raise ValidationError(f"{context} does not include model-scoped fields.")
+
+
+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
+
+
+def _parse_positive_int(value: Any) -> int | None:
+    parsed = _parse_int(value)
+    if parsed is None or parsed < 1:
+        return None
+    return parsed
+
+
+def _merge_export_page(base_payload: Any, page_payload: Any, *, context: str) -> Any:
+    if not isinstance(base_payload, dict) or not isinstance(page_payload, dict):
+        raise ValidationError(
+            f"Unexpected paginated response payload for {context}: expected objects."
+        )
+
+    merged = dict(base_payload)
+    for key, page_value in page_payload.items():
+        if key not in merged:
+            merged[key] = page_value
+            continue
+
+        base_value = merged[key]
+        if isinstance(base_value, list) and isinstance(page_value, list):
+            merged[key] = [*base_value, *page_value]
+            continue
+
+        if page_value != base_value:
+            raise ValidationError(
+                f"Unexpected paginated response payload for {context}: "
+                f"conflicting `{key}` values across pages."
+            )
+
+    return merged