fix(api): Map update order/collapsed to API field names

Keep SDK parameters ergonomic by handling the mapping internally:

- Map task/project update `order` -> `child_order`
- Map section update `order` -> `section_order`
- Map update `collapsed` -> `is_collapsed` (task/project/section)

Author: goncalossilva

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Breaking**: Async paginated return types now use `AsyncIterator[...]` instead of `AsyncGenerator[...]`.
 - **Breaking**: API errors now raise `httpx.HTTPStatusError` instead of `requests.exceptions.HTTPError`.
 - **Breaking**: Authentication helpers now accept optional `httpx.Client` / `httpx.AsyncClient` instances instead of `session: requests.Session`.
+- **Breaking**: `update_section` now accepts only keyword arguments after `section_id`; any one of `name`, `order`, or `collapsed` can be updated in the same call.
 
 ## [3.2.1] - 2026-01-22
 

tests/test_api_projects.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from typing import TYPE_CHECKING, Any
 
 import pytest
@@ -202,35 +203,83 @@ async def test_update_project(
     todoist_api_async: TodoistAPIAsync,
     respx_mock: respx.MockRouter,
     default_project: Project,
+    default_project_response: dict[str, Any],
 ) -> None:
     args: dict[str, Any] = {
         "name": "An updated project",
         "color": "red",
         "is_favorite": False,
     }
-    updated_project_dict = default_project.to_dict() | args
+    updated_project_response = dict(default_project_response) | args
 
     mock_route(
         respx_mock,
         method="POST",
         url=f"{DEFAULT_API_URL}/projects/{default_project.id}",
         request_headers=api_headers(),
         request_json=args,
-        response_json=updated_project_dict,
+        response_json=updated_project_response,
+        response_status=200,
+    )
+
+    response = todoist_api.update_project(project_id=default_project.id, **args)
+
+    assert len(respx_mock.calls) == 1
+    assert response == Project.from_dict(updated_project_response)
+
+    response = await todoist_api_async.update_project(
+        project_id=default_project.id, **args
+    )
+
+    assert len(respx_mock.calls) == 2
+    assert response == Project.from_dict(updated_project_response)
+
+
+@pytest.mark.asyncio
+async def test_update_project_payload_mapping(
+    todoist_api: TodoistAPI,
+    todoist_api_async: TodoistAPIAsync,
+    respx_mock: respx.MockRouter,
+    default_project: Project,
+    default_project_response: dict[str, Any],
+) -> None:
+    args: dict[str, Any] = {
+        "order": 3,
+        "collapsed": True,
+    }
+    expected_payload: dict[str, Any] = {
+        "child_order": 3,
+        "is_collapsed": True,
+    }
+    updated_project_response = dict(default_project_response) | {
+        "child_order": args["order"],
+        "is_collapsed": args["collapsed"],
+    }
+
+    mock_route(
+        respx_mock,
+        method="POST",
+        url=f"{DEFAULT_API_URL}/projects/{default_project.id}",
+        request_headers=api_headers(),
+        response_json=updated_project_response,
         response_status=200,
     )
 
     response = todoist_api.update_project(project_id=default_project.id, **args)
 
     assert len(respx_mock.calls) == 1
-    assert response == Project.from_dict(updated_project_dict)
+    assert response == Project.from_dict(updated_project_response)
+    actual_payload = json.loads(respx_mock.calls[0].request.content)
+    assert actual_payload == expected_payload
 
     response = await todoist_api_async.update_project(
         project_id=default_project.id, **args
     )
 
     assert len(respx_mock.calls) == 2
-    assert response == Project.from_dict(updated_project_dict)
+    assert response == Project.from_dict(updated_project_response)
+    actual_payload = json.loads(respx_mock.calls[1].request.content)
+    assert actual_payload == expected_payload
 
 
 @pytest.mark.asyncio

tests/test_api_sections.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from typing import TYPE_CHECKING, Any
 
 import pytest
@@ -259,33 +260,81 @@ async def test_update_section(
     todoist_api_async: TodoistAPIAsync,
     respx_mock: respx.MockRouter,
     default_section: Section,
+    default_section_response: dict[str, Any],
 ) -> None:
-    args = {
+    args: dict[str, Any] = {
         "name": "An updated section",
     }
-    updated_section_dict = default_section.to_dict() | args
+    updated_section_response = dict(default_section_response) | args
 
     mock_route(
         respx_mock,
         method="POST",
         url=f"{DEFAULT_API_URL}/sections/{default_section.id}",
         request_headers=api_headers(),
         request_json=args,
-        response_json=updated_section_dict,
+        response_json=updated_section_response,
+        response_status=200,
+    )
+
+    response = todoist_api.update_section(section_id=default_section.id, **args)
+
+    assert len(respx_mock.calls) == 1
+    assert response == Section.from_dict(updated_section_response)
+
+    response = await todoist_api_async.update_section(
+        section_id=default_section.id, **args
+    )
+
+    assert len(respx_mock.calls) == 2
+    assert response == Section.from_dict(updated_section_response)
+
+
+@pytest.mark.asyncio
+async def test_update_section_payload_mapping(
+    todoist_api: TodoistAPI,
+    todoist_api_async: TodoistAPIAsync,
+    respx_mock: respx.MockRouter,
+    default_section: Section,
+    default_section_response: dict[str, Any],
+) -> None:
+    args: dict[str, Any] = {
+        "order": 2,
+        "collapsed": False,
+    }
+    expected_payload: dict[str, Any] = {
+        "section_order": 2,
+        "is_collapsed": False,
+    }
+    updated_section_response = dict(default_section_response) | {
+        "section_order": args["order"],
+        "is_collapsed": args["collapsed"],
+    }
+
+    mock_route(
+        respx_mock,
+        method="POST",
+        url=f"{DEFAULT_API_URL}/sections/{default_section.id}",
+        request_headers=api_headers(),
+        response_json=updated_section_response,
         response_status=200,
     )
 
     response = todoist_api.update_section(section_id=default_section.id, **args)
 
     assert len(respx_mock.calls) == 1
-    assert response == Section.from_dict(updated_section_dict)
+    assert response == Section.from_dict(updated_section_response)
+    actual_payload = json.loads(respx_mock.calls[0].request.content)
+    assert actual_payload == expected_payload
 
     response = await todoist_api_async.update_section(
         section_id=default_section.id, **args
     )
 
     assert len(respx_mock.calls) == 2
-    assert response == Section.from_dict(updated_section_dict)
+    assert response == Section.from_dict(updated_section_response)
+    actual_payload = json.loads(respx_mock.calls[1].request.content)
+    assert actual_payload == expected_payload
 
 
 @pytest.mark.asyncio

tests/test_api_tasks.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import sys
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any
@@ -353,35 +354,83 @@ async def test_update_task(
     todoist_api_async: TodoistAPIAsync,
     respx_mock: respx.MockRouter,
     default_task: Task,
+    default_task_response: dict[str, Any],
 ) -> None:
     args: dict[str, Any] = {
         "content": "Updated content",
         "description": "Updated description",
         "labels": ["label1", "label2"],
         "priority": 2,
-        "order": 3,
     }
-    updated_task_dict = default_task.to_dict() | args
+    updated_task_response = dict(default_task_response) | args
 
     mock_route(
         respx_mock,
         method="POST",
         url=f"{DEFAULT_API_URL}/tasks/{default_task.id}",
         request_headers=api_headers(),
         request_json=args,
-        response_json=updated_task_dict,
+        response_json=updated_task_response,
+        response_status=200,
+    )
+
+    response = todoist_api.update_task(task_id=default_task.id, **args)
+
+    assert len(respx_mock.calls) == 1
+    assert response == Task.from_dict(updated_task_response)
+
+    response = await todoist_api_async.update_task(task_id=default_task.id, **args)
+
+    assert len(respx_mock.calls) == 2
+    assert response == Task.from_dict(updated_task_response)
+
+
+@pytest.mark.asyncio
+async def test_update_task_payload_mapping(
+    todoist_api: TodoistAPI,
+    todoist_api_async: TodoistAPIAsync,
+    respx_mock: respx.MockRouter,
+    default_task: Task,
+    default_task_response: dict[str, Any],
+) -> None:
+    args: dict[str, Any] = {
+        "order": 3,
+        "day_order": 2,
+        "collapsed": True,
+    }
+    expected_payload: dict[str, Any] = {
+        "child_order": 3,
+        "day_order": 2,
+        "is_collapsed": True,
+    }
+    updated_task_response = dict(default_task_response) | {
+        "child_order": args["order"],
+        "day_order": args["day_order"],
+        "is_collapsed": args["collapsed"],
+    }
+
+    mock_route(
+        respx_mock,
+        method="POST",
+        url=f"{DEFAULT_API_URL}/tasks/{default_task.id}",
+        request_headers=api_headers(),
+        response_json=updated_task_response,
         response_status=200,
     )
 
     response = todoist_api.update_task(task_id=default_task.id, **args)
 
     assert len(respx_mock.calls) == 1
-    assert response == Task.from_dict(updated_task_dict)
+    assert response == Task.from_dict(updated_task_response)
+    actual_payload = json.loads(respx_mock.calls[0].request.content)
+    assert actual_payload == expected_payload
 
     response = await todoist_api_async.update_task(task_id=default_task.id, **args)
 
     assert len(respx_mock.calls) == 2
-    assert response == Task.from_dict(updated_task_dict)
+    assert response == Task.from_dict(updated_task_response)
+    actual_payload = json.loads(respx_mock.calls[1].request.content)
+    assert actual_payload == expected_payload
 
 
 @pytest.mark.asyncio

todoist_api_python/api.py

@@ -403,9 +403,9 @@ def update_task(
                 format_datetime(due_datetime) if due_datetime is not None else None
             ),
             assignee_id=assignee_id,
-            order=order,
+            child_order=order,
             day_order=day_order,
-            collapsed=collapsed,
+            is_collapsed=collapsed,
             duration=duration,
             duration_unit=duration_unit,
             deadline_date=(
@@ -771,6 +771,8 @@ def update_project(
         color: ColorString | None = None,
         is_favorite: bool | None = None,
         view_style: ViewStyle | None = None,
+        order: int | None = None,
+        collapsed: bool | None = None,
     ) -> Project:
         """
         Update an existing project.
@@ -783,6 +785,8 @@ def update_project(
         :param color: The color of the project icon.
         :param is_favorite: Whether the project is a favorite.
         :param view_style: A string value (either 'list' or 'board').
+        :param order: Position of the project among projects with the same parent.
+        :param collapsed: Whether the project's sub-projects are collapsed.
         :return: the updated Project.
         :raises httpx.HTTPStatusError: If the API request fails.
         """
@@ -794,6 +798,8 @@ def update_project(
             color=color,
             is_favorite=is_favorite,
             view_style=view_style,
+            child_order=order,
+            is_collapsed=collapsed,
         )
 
         response = post(
@@ -1026,25 +1032,35 @@ def add_section(
     def update_section(
         self,
         section_id: str,
-        name: Annotated[str, MinLen(1), MaxLen(2048)],
+        *,
+        name: Annotated[str, MinLen(1), MaxLen(2048)] | None = None,
+        order: int | None = None,
+        collapsed: bool | None = None,
     ) -> Section:
         """
         Update an existing section.
 
-        Currently, only `name` can be updated.
-
         :param section_id: The ID of the section to update.
         :param name: The new name for the section.
+        :param order: Position of the section among sections in the project.
+        :param collapsed: Whether the section's tasks are collapsed.
         :return: the updated Section.
         :raises httpx.HTTPStatusError: If the API request fails.
         """
         endpoint = get_api_url(f"{SECTIONS_PATH}/{section_id}")
+
+        data = kwargs_without_none(
+            name=name,
+            section_order=order,
+            is_collapsed=collapsed,
+        )
+
         response = post(
             self._client,
             endpoint,
             self._token,
             self._request_id_fn() if self._request_id_fn else None,
-            data={"name": name},
+            data=data,
         )
         data = response_json_dict(response)
         return Section.from_dict(data)