From ad351b26928ce04d22be3ca77a2acc0fe82f659d Mon Sep 17 00:00:00 2001 From: Clayton Nummer Date: Sun, 15 Nov 2026 17:57:28 -0500 Subject: [PATCH] feat: add get_user_plan_limits Todoist only exposes plan limits through the Sync API, so callers that need to know what the user's plan includes, such as whether it allows reminders, had to build that request themselves. Add get_user_plan_limits to both clients, returning the current plan's limits and those of the available upgrade. Every limit except plan_name is optional, because the API leaves out some documented limits, such as workspace_filters. --- CHANGELOG.md | 1 + tests/conftest.py | 14 ++++++++ tests/data/test_defaults.py | 52 +++++++++++++++++++++++++++ tests/test_api_user_plan_limits.py | 49 +++++++++++++++++++++++++ tests/test_models.py | 27 ++++++++++++++ todoist_api_python/_core/endpoints.py | 1 + todoist_api_python/api.py | 24 +++++++++++++ todoist_api_python/api_async.py | 24 +++++++++++++ todoist_api_python/models.py | 47 ++++++++++++++++++++++++ 9 files changed, 239 insertions(+) create mode 100644 tests/test_api_user_plan_limits.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 340142d..d34ccbc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `TodoistAPIAsync` now performs true async HTTP I/O with `httpx2.AsyncClient`. - Support for Python 3.14. - `add_project` and `update_project` accept the `table` view style. +- `get_user_plan_limits` to get the features and limits of the user's plan, such as whether it includes reminders. ### Removed diff --git a/tests/conftest.py b/tests/conftest.py index e15d724..cc3d209 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -26,6 +26,7 @@ DEFAULT_TASK_RESPONSE, DEFAULT_TASKS_RESPONSE, DEFAULT_TOKEN, + DEFAULT_USER_PLAN_LIMITS_SYNC_RESPONSE, PaginatedItems, PaginatedResults, ) @@ -41,6 +42,7 @@ Reminder, Section, Task, + UserPlanLimits, ) if TYPE_CHECKING: @@ -269,6 +271,18 @@ def default_location_reminders_list() -> list[list[LocationReminder]]: ] +@pytest.fixture +def default_user_plan_limits_sync_response() -> dict[str, Any]: + return DEFAULT_USER_PLAN_LIMITS_SYNC_RESPONSE + + +@pytest.fixture +def default_user_plan_limits() -> UserPlanLimits: + return UserPlanLimits.from_dict( + DEFAULT_USER_PLAN_LIMITS_SYNC_RESPONSE["user_plan_limits"] + ) + + @pytest.fixture def default_quick_add_response() -> dict[str, Any]: return DEFAULT_TASK_RESPONSE diff --git a/tests/data/test_defaults.py b/tests/data/test_defaults.py index 1ecbf19..f63fcfa 100644 --- a/tests/data/test_defaults.py +++ b/tests/data/test_defaults.py @@ -338,3 +338,55 @@ class PaginatedItems(TypedDict): "access_token": "123456789", "state": "somestate", } + +DEFAULT_PLAN_LIMITS_RESPONSE: dict[str, Any] = { + "activity_log": True, + "activity_log_limit": 7, + "advanced_permissions": False, + "automatic_backups": False, + "calendar_feeds": True, + "calendar_layout": False, + "comments": True, + "completed_tasks": True, + "custom_app_icon": False, + "customization_color": False, + "deadlines": False, + "durations": False, + "email_forwarding": True, + "filters": True, + "labels": True, + "max_calendar_accounts": 1, + "max_collaborators": 5, + "max_filters": 3, + "max_labels": 500, + "max_projects": 5, + "max_reminders_location": 300, + "max_reminders_time": 700, + "max_sections": 20, + "max_tasks": 300, + "plan_name": "free", + "project_icons": True, + "reminders": False, + "reminders_at_due": True, + "table_layout": False, + "templates": True, + "upload_limit_mb": 5, + "uploads": True, + "weekly_trends": True, +} + +DEFAULT_NEXT_PLAN_LIMITS_RESPONSE = dict(DEFAULT_PLAN_LIMITS_RESPONSE) +DEFAULT_NEXT_PLAN_LIMITS_RESPONSE.update( + {"plan_name": "pro", "max_projects": 300, "reminders": True} +) + +DEFAULT_USER_PLAN_LIMITS_SYNC_RESPONSE: dict[str, Any] = { + "full_sync": True, + "sync_status": {}, + "sync_token": "TnYUZEpuzf2FMA9qzyY3j4xky6dXiYejmSO85S5paZ_a9y1FI85mBbIWZGpW", + "temp_id_mapping": {}, + "user_plan_limits": { + "current": DEFAULT_PLAN_LIMITS_RESPONSE, + "next": DEFAULT_NEXT_PLAN_LIMITS_RESPONSE, + }, +} diff --git a/tests/test_api_user_plan_limits.py b/tests/test_api_user_plan_limits.py new file mode 100644 index 0000000..7566181 --- /dev/null +++ b/tests/test_api_user_plan_limits.py @@ -0,0 +1,49 @@ +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +import pytest + +from tests.data.test_defaults import DEFAULT_API_URL +from tests.utils.test_utils import api_headers, mock_route + +if TYPE_CHECKING: + import respx + + from todoist_api_python.api import TodoistAPI + from todoist_api_python.api_async import TodoistAPIAsync + from todoist_api_python.models import UserPlanLimits + + +@pytest.mark.asyncio +async def test_get_user_plan_limits( + todoist_api: TodoistAPI, + todoist_api_async: TodoistAPIAsync, + respx_mock: respx.MockRouter, + default_user_plan_limits_sync_response: dict[str, Any], + default_user_plan_limits: UserPlanLimits, +) -> None: + endpoint = f"{DEFAULT_API_URL}/sync" + + mock_route( + respx_mock, + method="POST", + url=endpoint, + request_headers=api_headers(), + request_json={"sync_token": "*", "resource_types": ["user_plan_limits"]}, + response_json=default_user_plan_limits_sync_response, + response_status=200, + ) + + plan_limits = todoist_api.get_user_plan_limits() + + assert len(respx_mock.calls) == 1 + assert plan_limits == default_user_plan_limits + assert plan_limits.current.reminders is False + assert plan_limits.next is not None + assert plan_limits.next.reminders is True + + plan_limits = await todoist_api_async.get_user_plan_limits() + + assert len(respx_mock.calls) == 2 + assert plan_limits == default_user_plan_limits diff --git a/tests/test_models.py b/tests/test_models.py index ea6baf4..4afea01 100644 --- a/tests/test_models.py +++ b/tests/test_models.py @@ -9,6 +9,7 @@ DEFAULT_DUE_RESPONSE, DEFAULT_DURATION_RESPONSE, DEFAULT_LABEL_RESPONSE, + DEFAULT_PLAN_LIMITS_RESPONSE, DEFAULT_PROJECT_RESPONSE, DEFAULT_PROJECT_RESPONSE_2, DEFAULT_SECTION_RESPONSE, @@ -23,9 +24,11 @@ Due, Duration, Label, + PlanLimits, Project, Section, Task, + UserPlanLimits, ) unexpected_data = {"unexpected_key": "some value"} @@ -210,3 +213,27 @@ def test_auth_result_from_dict() -> None: assert auth_result.access_token == token assert auth_result.state == state + + +def test_plan_limits_from_dict() -> None: + sample_data = dict(DEFAULT_PLAN_LIMITS_RESPONSE) + sample_data.update(unexpected_data) + + plan_limits = PlanLimits.from_dict(sample_data) + + assert plan_limits.plan_name == sample_data["plan_name"] + assert plan_limits.reminders == sample_data["reminders"] + assert plan_limits.max_reminders_location == sample_data["max_reminders_location"] + assert plan_limits.max_projects == sample_data["max_projects"] + + +def test_user_plan_limits_from_dict_without_upgrade() -> None: + plan_limits = UserPlanLimits.from_dict( + {"current": {"plan_name": "business", "reminders": True}, "next": None} + ) + + assert plan_limits.next is None + assert plan_limits.current.plan_name == "business" + assert plan_limits.current.reminders is True + # The API leaves out some documented limits. + assert plan_limits.current.workspace_filters is None diff --git a/todoist_api_python/_core/endpoints.py b/todoist_api_python/_core/endpoints.py index 435264f..9b37ede 100644 --- a/todoist_api_python/_core/endpoints.py +++ b/todoist_api_python/_core/endpoints.py @@ -32,6 +32,7 @@ SHARED_LABELS_REMOVE_PATH = f"{SHARED_LABELS_PATH}/remove" REMINDERS_PATH = "reminders" LOCATION_REMINDERS_PATH = "location_reminders" +SYNC_PATH = "sync" AUTHORIZE_PATH = "authorize" ACCESS_TOKEN_PATH = "access_token" # noqa: S105 diff --git a/todoist_api_python/api.py b/todoist_api_python/api.py index a0c4af3..48e026e 100644 --- a/todoist_api_python/api.py +++ b/todoist_api_python/api.py @@ -24,6 +24,7 @@ SHARED_LABELS_PATH, SHARED_LABELS_REMOVE_PATH, SHARED_LABELS_RENAME_PATH, + SYNC_PATH, TASKS_COMPLETED_BY_COMPLETION_DATE_PATH, TASKS_COMPLETED_BY_DUE_DATE_PATH, TASKS_FILTER_PATH, @@ -53,6 +54,7 @@ Reminder, Section, Task, + UserPlanLimits, ) if TYPE_CHECKING: @@ -1856,6 +1858,28 @@ def delete_location_reminder(self, location_reminder_id: str) -> bool: ) return response.is_success + def get_user_plan_limits(self) -> UserPlanLimits: + """ + Get the features and limits of the user's plan. + + Todoist only exposes plan limits through the Sync API, so this reads them + from there. + + :return: The limits of the user's current plan, and of the plan available + as an upgrade, if any. + :raises httpx2.HTTPStatusError: If the API request fails. + """ + endpoint = get_api_url(SYNC_PATH) + response = post( + self._client, + endpoint, + self._token, + self._request_id_fn() if self._request_id_fn else None, + data={"sync_token": "*", "resource_types": ["user_plan_limits"]}, + ) + data = response_json_dict(response) + return UserPlanLimits.from_dict(data["user_plan_limits"]) + T = TypeVar("T") diff --git a/todoist_api_python/api_async.py b/todoist_api_python/api_async.py index 8f3e106..b688d24 100644 --- a/todoist_api_python/api_async.py +++ b/todoist_api_python/api_async.py @@ -24,6 +24,7 @@ SHARED_LABELS_PATH, SHARED_LABELS_REMOVE_PATH, SHARED_LABELS_RENAME_PATH, + SYNC_PATH, TASKS_COMPLETED_BY_COMPLETION_DATE_PATH, TASKS_COMPLETED_BY_DUE_DATE_PATH, TASKS_FILTER_PATH, @@ -53,6 +54,7 @@ Reminder, Section, Task, + UserPlanLimits, ) if TYPE_CHECKING: @@ -1878,6 +1880,28 @@ async def delete_location_reminder(self, location_reminder_id: str) -> bool: ) return response.is_success + async def get_user_plan_limits(self) -> UserPlanLimits: + """ + Get the features and limits of the user's plan. + + Todoist only exposes plan limits through the Sync API, so this reads them + from there. + + :return: The limits of the user's current plan, and of the plan available + as an upgrade, if any. + :raises httpx2.HTTPStatusError: If the API request fails. + """ + endpoint = get_api_url(SYNC_PATH) + response = await post_async( + self._client, + endpoint, + self._token, + self._request_id_fn() if self._request_id_fn else None, + data={"sync_token": "*", "resource_types": ["user_plan_limits"]}, + ) + data = response_json_dict(response) + return UserPlanLimits.from_dict(data["user_plan_limits"]) + T = TypeVar("T") diff --git a/todoist_api_python/models.py b/todoist_api_python/models.py index a6ec851..fad9ceb 100644 --- a/todoist_api_python/models.py +++ b/todoist_api_python/models.py @@ -257,3 +257,50 @@ class _(JSONPyWizard.Meta): # noqa:N801 radius: int type: str is_deleted: bool + + +@dataclass +class PlanLimits(JSONPyWizard): + class _(JSONPyWizard.Meta): # noqa:N801 + v1 = True + + plan_name: str + + # The API omits some documented limits, such as `workspace_filters`. + activity_log: bool | None = None + activity_log_limit: int | None = None + automatic_backups: bool | None = None + calendar_feeds: bool | None = None + comments: bool | None = None + completed_tasks: bool | None = None + custom_app_icon: bool | None = None + customization_color: bool | None = None + email_forwarding: bool | None = None + filters: bool | None = None + labels: bool | None = None + max_collaborators: int | None = None + max_filters: int | None = None + max_labels: int | None = None + max_projects: int | None = None + max_reminders_location: int | None = None + max_reminders_time: int | None = None + max_sections: int | None = None + max_tasks: int | None = None + max_workspace_filters: int | None = None + project_icons: bool | None = None + reminders: bool | None = None + table_layout: bool | None = None + templates: bool | None = None + upload_limit_mb: int | None = None + uploads: bool | None = None + weekly_trends: bool | None = None + workspace_filters: bool | None = None + + +@dataclass +class UserPlanLimits(JSONPyWizard): + class _(JSONPyWizard.Meta): # noqa:N801 + v1 = True + + current: PlanLimits + next: PlanLimits | None = None