megaplan-sdk 0.2.2__tar.gz → 0.2.3__tar.gz

{megaplan_sdk-0.2.2/src/megaplan_sdk.egg-info → megaplan_sdk-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: megaplan-sdk
-Version: 0.2.2
+Version: 0.2.3
 Summary: Professional Python SDK for Megaplan API v3
 Author-email: Maxim Borzov <max@borzov.com>
 License-Expression: MIT
@@ -73,6 +73,7 @@ Dynamic: license-file
 - [Глобальные дефолтные лимиты](#глобальные-дефолтные-лимиты)
 - [Автоматическая подгрузка связанных сущностей](#автоматическая-подгрузка-связанных-сущностей)
 - [Работа с фильтрами](#работа-с-фильтрами)
+- [Работа с комментариями](#работа-с-комментариями)
 - [Настройка HTTP-клиента](#настройка-http-клиента)
 - [Работа через прокси](#работа-через-прокси)
 - [Ручное управление токенами](#ручное-управление-токенами)
@@ -429,7 +430,7 @@ print(details.deal.name)      # для сделок
 # Связанные данные
 if details.comments:
     for comment in details.comments:
-        print(comment.text)
+        print(comment.content)
 
 if details.history:
     print(f"Записей в истории: {len(details.history)}")
@@ -519,6 +520,37 @@ tasks = await client.tasks.list(filter=filter_obj)
 - `todos: list[BaseEntity]` - Подзадачи-чеклисты
 - `time_created: str` - Дата создания (API поле `timeCreated`)
 - `time_updated: str` - Дата обновления (API поле `timeUpdated`)
+- `activity: str | None` - Дата последней активности (API поле `activity`)
+- `last_comment_time_created: str | None` - Время последнего комментария (API поле `lastCommentTimeCreated`)
+- `status_change_time: str | None` - Время смены статуса (API поле `statusChangeTime`)
+- `actual_start: str | None` - Фактическое время начала (API поле `actualStart`)
+- `last_view: str | None` - Время последнего просмотра (API поле `lastView`)
+
+### Фильтрация задач по временным полям
+
+Временны́е поля (`activity`, `lastCommentTimeCreated` и др.) не возвращаются в `tasks.list()` по умолчанию.
+Используйте константу `DEFAULT_TASK_LIST_FIELDS`, чтобы запросить их явно:
+
+```python
+from megaplan_sdk import DEFAULT_TASK_LIST_FIELDS
+
+# Запросить задачи с временными полями (activity, lastCommentTimeCreated и др.)
+tasks = await client.tasks.list(
+    limit=50,
+    fields=list(DEFAULT_TASK_LIST_FIELDS),
+)
+for task in tasks:
+    print(f"{task.name}: активность {task.activity}")
+```
+
+> **Примечание:** Сортировка по `"timeUpdated"` не поддерживается API — используйте `"activity"`:
+>
+> ```python
+> tasks = await client.tasks.list(
+>     sort_by=[{"fieldName": "activity", "order": "desc"}],
+>     fields=list(DEFAULT_TASK_LIST_FIELDS),
+> )
+> ```
 
 ### Упрощенные методы создания
 
@@ -1502,6 +1534,56 @@ updated = await client.filters.update("task", filter_id=123, filter_config={...}
 export_data = await client.filters.export("task", filter_id=123)
 ```
 
+### Работа с комментариями
+
+Комментарии доступны для задач, проектов и сделок через `client.comments`.
+
+#### Получение комментариев
+
+```python
+# Комментарии задачи (entity_type по умолчанию "task")
+comments = await client.comments.list(entity_id=42)
+
+# Комментарии проекта
+comments = await client.comments.list(entity_id=5, entity_type="project")
+
+# Комментарии сделки
+comments = await client.comments.list(entity_id=200, entity_type="deal")
+
+# Автоматическая пагинация
+async for comment in client.comments.iterate(entity_id=42):
+    print(comment.content)
+```
+
+#### Подгрузка авторов через expand
+
+API Мегаплана не раскрывает поле `owner` (автор комментария) в списке комментариев.
+Используйте `expand=["owner"]`, чтобы SDK дозагрузил авторов отдельными запросами (с кэшированием):
+
+```python
+# Комментарии задачи с именами авторов
+comments = await client.comments.list(entity_id=42, expand=["owner"])
+for comment in comments:
+    author_name = comment.owner.name if comment.owner else "неизвестен"
+    print(f"{author_name}: {comment.content}")
+```
+
+#### Создание комментария
+
+```python
+# Комментарий к задаче
+comment = await client.comments.create(entity_id=42, comment_data={"text": "Текст комментария"})
+
+# Комментарий к проекту
+comment = await client.comments.create(entity_id=5, comment_data={"text": "Текст"}, entity_type="project")
+
+# Комментарий к сделке
+comment = await client.comments.create(entity_id=200, comment_data={"text": "Текст"}, entity_type="deal")
+```
+
+> **Ограничение:** Комментарии контрагентов не поддерживаются API (возвращает 500).
+> Используйте комментарии в связанных сделках или задачах.
+
 ### Настройка HTTP-клиента
 
 ```python

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/README.md

@@ -41,6 +41,7 @@
 - [Глобальные дефолтные лимиты](#глобальные-дефолтные-лимиты)
 - [Автоматическая подгрузка связанных сущностей](#автоматическая-подгрузка-связанных-сущностей)
 - [Работа с фильтрами](#работа-с-фильтрами)
+- [Работа с комментариями](#работа-с-комментариями)
 - [Настройка HTTP-клиента](#настройка-http-клиента)
 - [Работа через прокси](#работа-через-прокси)
 - [Ручное управление токенами](#ручное-управление-токенами)
@@ -397,7 +398,7 @@ print(details.deal.name)      # для сделок
 # Связанные данные
 if details.comments:
     for comment in details.comments:
-        print(comment.text)
+        print(comment.content)
 
 if details.history:
     print(f"Записей в истории: {len(details.history)}")
@@ -487,6 +488,37 @@ tasks = await client.tasks.list(filter=filter_obj)
 - `todos: list[BaseEntity]` - Подзадачи-чеклисты
 - `time_created: str` - Дата создания (API поле `timeCreated`)
 - `time_updated: str` - Дата обновления (API поле `timeUpdated`)
+- `activity: str | None` - Дата последней активности (API поле `activity`)
+- `last_comment_time_created: str | None` - Время последнего комментария (API поле `lastCommentTimeCreated`)
+- `status_change_time: str | None` - Время смены статуса (API поле `statusChangeTime`)
+- `actual_start: str | None` - Фактическое время начала (API поле `actualStart`)
+- `last_view: str | None` - Время последнего просмотра (API поле `lastView`)
+
+### Фильтрация задач по временным полям
+
+Временны́е поля (`activity`, `lastCommentTimeCreated` и др.) не возвращаются в `tasks.list()` по умолчанию.
+Используйте константу `DEFAULT_TASK_LIST_FIELDS`, чтобы запросить их явно:
+
+```python
+from megaplan_sdk import DEFAULT_TASK_LIST_FIELDS
+
+# Запросить задачи с временными полями (activity, lastCommentTimeCreated и др.)
+tasks = await client.tasks.list(
+    limit=50,
+    fields=list(DEFAULT_TASK_LIST_FIELDS),
+)
+for task in tasks:
+    print(f"{task.name}: активность {task.activity}")
+```
+
+> **Примечание:** Сортировка по `"timeUpdated"` не поддерживается API — используйте `"activity"`:
+>
+> ```python
+> tasks = await client.tasks.list(
+>     sort_by=[{"fieldName": "activity", "order": "desc"}],
+>     fields=list(DEFAULT_TASK_LIST_FIELDS),
+> )
+> ```
 
 ### Упрощенные методы создания
 
@@ -1470,6 +1502,56 @@ updated = await client.filters.update("task", filter_id=123, filter_config={...}
 export_data = await client.filters.export("task", filter_id=123)
 ```
 
+### Работа с комментариями
+
+Комментарии доступны для задач, проектов и сделок через `client.comments`.
+
+#### Получение комментариев
+
+```python
+# Комментарии задачи (entity_type по умолчанию "task")
+comments = await client.comments.list(entity_id=42)
+
+# Комментарии проекта
+comments = await client.comments.list(entity_id=5, entity_type="project")
+
+# Комментарии сделки
+comments = await client.comments.list(entity_id=200, entity_type="deal")
+
+# Автоматическая пагинация
+async for comment in client.comments.iterate(entity_id=42):
+    print(comment.content)
+```
+
+#### Подгрузка авторов через expand
+
+API Мегаплана не раскрывает поле `owner` (автор комментария) в списке комментариев.
+Используйте `expand=["owner"]`, чтобы SDK дозагрузил авторов отдельными запросами (с кэшированием):
+
+```python
+# Комментарии задачи с именами авторов
+comments = await client.comments.list(entity_id=42, expand=["owner"])
+for comment in comments:
+    author_name = comment.owner.name if comment.owner else "неизвестен"
+    print(f"{author_name}: {comment.content}")
+```
+
+#### Создание комментария
+
+```python
+# Комментарий к задаче
+comment = await client.comments.create(entity_id=42, comment_data={"text": "Текст комментария"})
+
+# Комментарий к проекту
+comment = await client.comments.create(entity_id=5, comment_data={"text": "Текст"}, entity_type="project")
+
+# Комментарий к сделке
+comment = await client.comments.create(entity_id=200, comment_data={"text": "Текст"}, entity_type="deal")
+```
+
+> **Ограничение:** Комментарии контрагентов не поддерживаются API (возвращает 500).
+> Используйте комментарии в связанных сделках или задачах.
+
 ### Настройка HTTP-клиента
 
 ```python

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "megaplan-sdk"
-version = "0.2.2"
+version = "0.2.3"
 description = "Professional Python SDK for Megaplan API v3"
 readme = "README.md"
 requires-python = ">=3.11"

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/src/megaplan_sdk/__init__.py

@@ -1,6 +1,7 @@
 """Megaplan Python SDK - Professional SDK for Megaplan API v3."""
 
 from megaplan_sdk.client import MegaplanClient
+from megaplan_sdk.constants import DEFAULT_TASK_LIST_FIELDS
 from megaplan_sdk.exceptions import (
     AuthenticationError,
     AuthorizationError,
@@ -101,6 +102,8 @@ __all__ = [
     "TaskFilterBuilder",
     "TradeFilterBuilder",
     "ProjectFilterBuilder",
+    # Constants
+    "DEFAULT_TASK_LIST_FIELDS",
 ]
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

megaplan_sdk-0.2.3/src/megaplan_sdk/constants.py

@@ -0,0 +1,42 @@
+"""Constants for Megaplan SDK."""
+
+
+class ContentType:
+    """Content type constants for Megaplan API entities."""
+
+    TASK = "Task"
+    PROJECT = "Project"
+    DEAL = "Deal"
+    EMPLOYEE = "Employee"
+    CONTRACTOR = "Contractor"
+    CONTRACTOR_COMPANY = "ContractorCompany"
+    CONTRACTOR_HUMAN = "ContractorHuman"
+    CONTRACTOR_CATEGORY = "ContractorCategory"
+    DEPARTMENT = "Department"
+    COMMENT = "Comment"
+    GROUP = "Group"
+
+
+# Task fields users commonly try to sort by that the Megaplan API rejects (422).
+# Maps the unsupported field name to the supported replacement to suggest.
+UNSUPPORTED_TASK_SORT_FIELDS: dict[str, str] = {
+    "timeUpdated": "activity",
+    "updatedAt": "activity",
+}
+
+# Recommended `fields` set for tasks.list() so that date fields are populated.
+# Megaplan list endpoints omit these unless explicitly requested, which makes
+# client-side time-window filtering silently return nothing (#8).
+# Only fields confirmed to exist on Task are included (no "timeUpdated" — see #7).
+DEFAULT_TASK_LIST_FIELDS: tuple[str, ...] = (
+    "name",
+    "status",
+    "timeCreated",
+    "activity",
+    "lastCommentTimeCreated",
+    "statusChangeTime",
+    "actualStart",
+    "owner",
+    "responsible",
+    "commentsCount",
+)

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/src/megaplan_sdk/models/task.py

@@ -44,6 +44,13 @@ class Task(TimestampMixin):
     tags: list[BaseEntity] | None = None
     attaches: list[BaseEntity] | None = None
     todos: list[BaseEntity] | None = None
+    activity: str | DateTime | None = None
+    last_comment_time_created: str | DateTime | None = Field(
+        alias="lastCommentTimeCreated", default=None
+    )
+    status_change_time: str | DateTime | None = Field(alias="statusChangeTime", default=None)
+    actual_start: str | DateTime | None = Field(alias="actualStart", default=None)
+    last_view: str | DateTime | None = Field(alias="lastView", default=None)
 
     model_config = ConfigDict(populate_by_name=True, extra="allow")
 

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/src/megaplan_sdk/resources/comments.py

@@ -12,7 +12,12 @@ from megaplan_sdk.resources.base import BaseResource
 class CommentsResource(BaseResource):
     """Resource for working with comments."""
 
-    async def create(self, entity_id: int, comment_data: dict[str, Any]) -> Comment:
+    async def create(
+        self,
+        entity_id: int,
+        comment_data: dict[str, Any],
+        entity_type: str = "task",
+    ) -> Comment:
         """Create a new comment for an entity.
 
         Args:
@@ -20,6 +25,9 @@ class CommentsResource(BaseResource):
             comment_data: Comment data dictionary.
                 Required: text
                 Optional: work (hours), attaches (file IDs)
+            entity_type: Entity type segment for the API path.
+                Allowed values: ``"task"`` | ``"project"`` | ``"deal"``.
+                Defaults to ``"task"``.
 
         Returns:
             Created comment.
@@ -30,14 +38,21 @@ class CommentsResource(BaseResource):
             ...     entity_id=123,
             ...     comment_data={"text": "Comment text", "work": 2.5}
             ... )
+            >>> # Create comment for project #55
+            >>> comment = await client.comments.create(
+            ...     entity_id=55,
+            ...     comment_data={"text": "Project note"},
+            ...     entity_type="project",
+            ... )
         """
-        path = self._build_path("api", "v3", "todo", str(entity_id), "comments")
+        path = self._build_path("api", "v3", entity_type, str(entity_id), "comments")
         response = await self._http.post(path, json_data=comment_data)
         return Comment(**response["data"])
 
     async def list(
         self,
         entity_id: int,
+        entity_type: str = "task",
         limit: int | None = None,
         page_after: dict[str, Any] | None = None,
         page_before: dict[str, Any] | None = None,
@@ -45,11 +60,15 @@ class CommentsResource(BaseResource):
         fields: Any | None = None,
         sort_by: list[dict[str, str]] | None = None,
         only_requested_fields: bool | None = None,
+        expand: list[str] | None = None,
     ) -> list[Comment]:
         """Get list of comments for an entity.
 
         Args:
             entity_id: Parent entity ID (task, project, deal, etc.).
+            entity_type: Entity type segment for the API path.
+                Allowed values: ``"task"`` | ``"project"`` | ``"deal"``.
+                Defaults to ``"task"``.
             limit: Number of items per page.
             page_after: Load page starting from this entity.
             page_before: Load page strictly before this entity.
@@ -57,6 +76,11 @@ class CommentsResource(BaseResource):
             fields: Additional fields to include.
             sort_by: Sort fields.
             only_requested_fields: Return only requested fields.
+            expand: Fields to expand. Supported values: ``"owner"``.
+                When ``"owner"`` is included, resolves Employee comment authors
+                to full Employee objects via batch parallel requests (cached).
+                The API never returns populated owners, so this is the only
+                resolution path.
 
         Returns:
             List of comments.
@@ -64,8 +88,13 @@ class CommentsResource(BaseResource):
         Examples:
             >>> # Get all comments for task #123
             >>> comments = await client.comments.list(entity_id=123)
+            >>> # Get all comments for project #55
+            >>> comments = await client.comments.list(entity_id=55, entity_type="project")
+            >>> # Resolve comment authors to full Employee objects
+            >>> comments = await client.comments.list(entity_id=123, expand=["owner"])
+            >>> print(comments[0].owner.name)  # "Иван Петров"
         """
-        path = self._build_path("api", "v3", "todo", str(entity_id), "comments")
+        path = self._build_path("api", "v3", entity_type, str(entity_id), "comments")
 
         # Use base method to build params (DRY)
         params = self._build_list_params(
@@ -78,7 +107,27 @@ class CommentsResource(BaseResource):
             only_requested_fields=only_requested_fields,
         )
 
-        return await self._get_list(path, Comment, params)
+        comments = await self._get_list(path, Comment, params)
+
+        if not expand or "owner" not in expand or not comments:
+            return comments
+
+        from megaplan_sdk.models.employee import Employee
+
+        # Only Employee owners are resolvable via the employee endpoint.
+        employee_owners = [
+            c.owner for c in comments if c.owner is not None and c.owner.content_type == "Employee"
+        ]
+        owner_map = await self._load_related_entities(employee_owners, "employee", Employee)
+        for comment in comments:
+            if (
+                comment.owner is not None
+                and comment.owner.content_type == "Employee"
+                and comment.owner.id in owner_map
+            ):
+                comment.owner = owner_map[comment.owner.id]
+
+        return comments
 
     async def get(self, comment_id: int) -> Comment:
         """Get comment by ID.
@@ -119,6 +168,7 @@ class CommentsResource(BaseResource):
     async def iterate(
         self,
         entity_id: int,
+        entity_type: str = "task",
         limit: int = 100,
         **kwargs: Any,
     ) -> AsyncIterator[Comment]:
@@ -126,6 +176,9 @@ class CommentsResource(BaseResource):
 
         Args:
             entity_id: Parent entity ID (task, project, deal, etc.).
+            entity_type: Entity type segment for the API path.
+                Allowed values: ``"task"`` | ``"project"`` | ``"deal"``.
+                Defaults to ``"task"``.
             limit: Number of items per page.
             **kwargs: Additional parameters to pass to list().
 
@@ -136,6 +189,9 @@ class CommentsResource(BaseResource):
             >>> # Iterate over all comments for task #123
             >>> async for comment in client.comments.iterate(entity_id=123):
             ...     print(comment.content)
+            >>> # Iterate over all comments for project #55
+            >>> async for comment in client.comments.iterate(entity_id=55, entity_type="project"):
+            ...     print(comment.content)
         """
         comment: Comment
         async for comment in self._iterate_generic(  # type: ignore[valid-type]
@@ -143,6 +199,7 @@ class CommentsResource(BaseResource):
             self.list,
             limit,
             entity_id=entity_id,
+            entity_type=entity_type,
             **kwargs,
         ):
             yield comment

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/src/megaplan_sdk/resources/deals.py

@@ -710,10 +710,17 @@ class DealsResource(BaseResource, FullDetailsMixin):
                 None = use global default (from MegaplanClient) or API default.
                 Explicit value overrides global default.
                 Example: comments_limit=50 returns max 50 comments.
+                Requires the matching include_* flag to be True; passing a
+                limit without it raises ValueError.
+                Note: the API caps a single comments page (~100); requesting
+                more returns at most one server page. Use client.comments.iterate
+                for full pagination.
             history_limit: Limit for history (if included).
                 None = use global default (from MegaplanClient) or API default.
                 Explicit value overrides global default.
                 Example: history_limit=100 returns max 100 history entries.
+                Requires the matching include_* flag to be True; passing a
+                limit without it raises ValueError.
 
         Returns:
             DealFullDetails object with all requested data.

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/src/megaplan_sdk/resources/full_details.py

@@ -71,6 +71,21 @@ class FullDetailsMixin:
         getter = getattr(self, entity_getter)
         main_entity = await getter(entity_id)
 
+        # Guard: a *_limit without its include_* flag silently does nothing (#2).
+        # Reject it with a clear error instead of returning empty/stub data.
+        # This guard runs BEFORE the global-defaults block so that a client-level
+        # default (injected below) never triggers a false-positive error here.
+        for item_config in config:
+            limit_param = item_config.limit_param
+            if limit_param is None:
+                continue
+            if kwargs.get(limit_param) is not None and not kwargs.get(item_config.include_flag):
+                raise ValueError(
+                    f"'{limit_param}' was provided but '{item_config.include_flag}' is False. "
+                    f"Pass '{item_config.include_flag}=True' to load this data, "
+                    f"or omit '{limit_param}'."
+                )
+
         # Apply global defaults for limit parameters if not explicitly provided
         # Note: parameters are always in kwargs (even if None), so check value instead of presence
         if hasattr(self, "_default_comments_limit") and kwargs.get("comments_limit") is None:

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/src/megaplan_sdk/resources/projects.py

@@ -852,10 +852,17 @@ class ProjectsResource(BaseResource, FullDetailsMixin):
                 None = use global default (from MegaplanClient) or API default.
                 Explicit value overrides global default.
                 Example: comments_limit=50 returns max 50 comments.
+                Requires the matching include_* flag to be True; passing a
+                limit without it raises ValueError.
+                Note: the API caps a single comments page (~100); requesting
+                more returns at most one server page. Use client.comments.iterate
+                for full pagination.
             history_limit: Limit for history (if included).
                 None = use global default (from MegaplanClient) or API default.
                 Explicit value overrides global default.
                 Example: history_limit=100 returns max 100 history entries.
+                Requires the matching include_* flag to be True; passing a
+                limit without it raises ValueError.
 
         Returns:
             ProjectFullDetails object with all requested data.

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3}/src/megaplan_sdk/resources/tasks.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING, Any, overload
 
-from megaplan_sdk.constants import ContentType
+from megaplan_sdk.constants import UNSUPPORTED_TASK_SORT_FIELDS, ContentType
 from megaplan_sdk.models.comment import Comment
 from megaplan_sdk.models.task import Task, TaskFullDetails
 from megaplan_sdk.resources.base import BaseResource
@@ -219,6 +219,13 @@ class TasksResource(BaseResource, FullDetailsMixin):
             page_before: Load page strictly before this entity.
             page_with: Load page containing this entity.
             fields: Additional fields to include.
+                **Important:** list endpoints do NOT return date fields
+                (timeCreated, activity, lastCommentTimeCreated, ...) unless
+                requested here. To filter by a time window, pass:
+                    from megaplan_sdk import DEFAULT_TASK_LIST_FIELDS
+                    tasks = await client.tasks.list(fields=list(DEFAULT_TASK_LIST_FIELDS))
+                Without this, those fields are None and time-window filters
+                silently match nothing.
             sort_by: Sort fields.
             only_requested_fields: Return only requested fields.
             expand: List of fields to expand (e.g., ["responsible", "owner"]).
@@ -260,6 +267,18 @@ class TasksResource(BaseResource, FullDetailsMixin):
                     f"Valid values: {sorted(VALID_TASK_STATUSES)}"
                 )
 
+        # Validate sort_by against fields the API rejects with a raw 422 (#7).
+        if sort_by:
+            for rule in sort_by:
+                field_name = rule.get("fieldName")
+                if field_name in UNSUPPORTED_TASK_SORT_FIELDS:
+                    suggestion = UNSUPPORTED_TASK_SORT_FIELDS[field_name]
+                    raise ValueError(
+                        f"Task cannot be sorted by '{field_name}' (API returns 422). "
+                        f"Use '{suggestion}' instead — e.g. "
+                        f'sort_by=[{{"fieldName": "{suggestion}", "desc": True}}].'
+                    )
+
         # Convert filter ID to object format if needed
         processed_filter = filter
         if filter is not None and isinstance(filter, int | str) and not isinstance(filter, dict):
@@ -1064,10 +1083,17 @@ class TasksResource(BaseResource, FullDetailsMixin):
                 None = use global default (from MegaplanClient) or API default.
                 Explicit value overrides global default.
                 Example: comments_limit=50 returns max 50 comments.
+                Requires the matching include_* flag to be True; passing a
+                limit without it raises ValueError.
+                Note: the API caps a single comments page (~100); requesting
+                more returns at most one server page. Use client.comments.iterate
+                for full pagination.
             history_limit: Limit for history (if included).
                 None = use global default (from MegaplanClient) or API default.
                 Explicit value overrides global default.
                 Example: history_limit=100 returns max 100 history entries.
+                Requires the matching include_* flag to be True; passing a
+                limit without it raises ValueError.
 
         Returns:
             TaskFullDetails object with all requested data.

{megaplan_sdk-0.2.2 → megaplan_sdk-0.2.3/src/megaplan_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: megaplan-sdk
-Version: 0.2.2
+Version: 0.2.3
 Summary: Professional Python SDK for Megaplan API v3
 Author-email: Maxim Borzov <max@borzov.com>
 License-Expression: MIT
@@ -73,6 +73,7 @@ Dynamic: license-file
 - [Глобальные дефолтные лимиты](#глобальные-дефолтные-лимиты)
 - [Автоматическая подгрузка связанных сущностей](#автоматическая-подгрузка-связанных-сущностей)
 - [Работа с фильтрами](#работа-с-фильтрами)
+- [Работа с комментариями](#работа-с-комментариями)
 - [Настройка HTTP-клиента](#настройка-http-клиента)
 - [Работа через прокси](#работа-через-прокси)
 - [Ручное управление токенами](#ручное-управление-токенами)
@@ -429,7 +430,7 @@ print(details.deal.name)      # для сделок
 # Связанные данные
 if details.comments:
     for comment in details.comments:
-        print(comment.text)
+        print(comment.content)
 
 if details.history:
     print(f"Записей в истории: {len(details.history)}")
@@ -519,6 +520,37 @@ tasks = await client.tasks.list(filter=filter_obj)
 - `todos: list[BaseEntity]` - Подзадачи-чеклисты
 - `time_created: str` - Дата создания (API поле `timeCreated`)
 - `time_updated: str` - Дата обновления (API поле `timeUpdated`)
+- `activity: str | None` - Дата последней активности (API поле `activity`)
+- `last_comment_time_created: str | None` - Время последнего комментария (API поле `lastCommentTimeCreated`)
+- `status_change_time: str | None` - Время смены статуса (API поле `statusChangeTime`)
+- `actual_start: str | None` - Фактическое время начала (API поле `actualStart`)
+- `last_view: str | None` - Время последнего просмотра (API поле `lastView`)
+
+### Фильтрация задач по временным полям
+
+Временны́е поля (`activity`, `lastCommentTimeCreated` и др.) не возвращаются в `tasks.list()` по умолчанию.
+Используйте константу `DEFAULT_TASK_LIST_FIELDS`, чтобы запросить их явно:
+
+```python
+from megaplan_sdk import DEFAULT_TASK_LIST_FIELDS
+
+# Запросить задачи с временными полями (activity, lastCommentTimeCreated и др.)
+tasks = await client.tasks.list(
+    limit=50,
+    fields=list(DEFAULT_TASK_LIST_FIELDS),
+)
+for task in tasks:
+    print(f"{task.name}: активность {task.activity}")
+```
+
+> **Примечание:** Сортировка по `"timeUpdated"` не поддерживается API — используйте `"activity"`:
+>
+> ```python
+> tasks = await client.tasks.list(
+>     sort_by=[{"fieldName": "activity", "order": "desc"}],
+>     fields=list(DEFAULT_TASK_LIST_FIELDS),
+> )
+> ```
 
 ### Упрощенные методы создания
 
@@ -1502,6 +1534,56 @@ updated = await client.filters.update("task", filter_id=123, filter_config={...}
 export_data = await client.filters.export("task", filter_id=123)
 ```
 
+### Работа с комментариями
+
+Комментарии доступны для задач, проектов и сделок через `client.comments`.
+
+#### Получение комментариев
+
+```python
+# Комментарии задачи (entity_type по умолчанию "task")
+comments = await client.comments.list(entity_id=42)
+
+# Комментарии проекта
+comments = await client.comments.list(entity_id=5, entity_type="project")
+
+# Комментарии сделки
+comments = await client.comments.list(entity_id=200, entity_type="deal")
+
+# Автоматическая пагинация
+async for comment in client.comments.iterate(entity_id=42):
+    print(comment.content)
+```
+
+#### Подгрузка авторов через expand
+
+API Мегаплана не раскрывает поле `owner` (автор комментария) в списке комментариев.
+Используйте `expand=["owner"]`, чтобы SDK дозагрузил авторов отдельными запросами (с кэшированием):
+
+```python
+# Комментарии задачи с именами авторов
+comments = await client.comments.list(entity_id=42, expand=["owner"])
+for comment in comments:
+    author_name = comment.owner.name if comment.owner else "неизвестен"
+    print(f"{author_name}: {comment.content}")
+```
+
+#### Создание комментария
+
+```python
+# Комментарий к задаче
+comment = await client.comments.create(entity_id=42, comment_data={"text": "Текст комментария"})
+
+# Комментарий к проекту
+comment = await client.comments.create(entity_id=5, comment_data={"text": "Текст"}, entity_type="project")
+
+# Комментарий к сделке
+comment = await client.comments.create(entity_id=200, comment_data={"text": "Текст"}, entity_type="deal")
+```
+
+> **Ограничение:** Комментарии контрагентов не поддерживаются API (возвращает 500).
+> Используйте комментарии в связанных сделках или задачах.
+
 ### Настройка HTTP-клиента
 
 ```python

megaplan_sdk-0.2.2/src/megaplan_sdk/constants.py

@@ -1,17 +0,0 @@
-"""Constants for Megaplan SDK."""
-
-
-class ContentType:
-    """Content type constants for Megaplan API entities."""
-
-    TASK = "Task"
-    PROJECT = "Project"
-    DEAL = "Deal"
-    EMPLOYEE = "Employee"
-    CONTRACTOR = "Contractor"
-    CONTRACTOR_COMPANY = "ContractorCompany"
-    CONTRACTOR_HUMAN = "ContractorHuman"
-    CONTRACTOR_CATEGORY = "ContractorCategory"
-    DEPARTMENT = "Department"
-    COMMENT = "Comment"
-    GROUP = "Group"