Добавил более метод общей информации

Author: p141592

README.md

@@ -131,6 +131,10 @@ with AvitoClient.from_env() as avito:
     stats = avito.ad_stats(item_id=42, user_id=123).get_item_stats()
 ```
 
+`user_id` можно передать явно, задать через `AVITO_USER_ID` или оставить пустым для read-only вызовов, где SDK может определить пользователя через `account().get_self()`. Если идентификатор не удалось определить, SDK поднимает `ValidationError` с подсказкой, как вызвать метод правильно.
+
+Статистические методы принимают `date`, `datetime` и ISO-строки, а в Avito API отправляют дату в формате `YYYY-MM-DD`. Модель `Listing` нормализует основные поля объявления: `title`, `price`, `status`, `description`, `url`, `category`, `city`, `published_at`, `updated_at`, `is_moderated`, `is_visible`.
+
 ### Автозагрузка
 
 ```python
@@ -266,6 +270,8 @@ with AvitoClient.from_env() as avito:
     tariff = avito.tariff().get_tariff_info()
 ```
 
+`review().list()` по умолчанию запрашивает первую страницу отзывов (`page=1`). Для явной пагинации передайте `ReviewsQuery(page=...)`.
+
 ## Пагинация
 
 Публичные list-операции, которые поддерживают lazy pagination, возвращают обычные SDK-результаты, а поле `items` в них типизировано как `PaginatedList[T]` и ведёт себя как list-like коллекция.
@@ -307,6 +313,8 @@ with AvitoClient.from_env() as avito:
 
 `AuthenticationError` (401) и `AuthorizationError` (403) — семантически разные ошибки и **не** состоят в отношении наследования. Тексты сообщений написаны на русском языке. Секреты (access token, `client_secret`, `Authorization`) автоматически санитайзятся из сообщений и metadata.
 
+Для диагностики доступны структурированные поля `operation`, `status` / `status_code`, `error_code`, `message`, `details`, `retry_after`, `request_id`, `metadata`, `payload` и `headers`. Например, у `RateLimitError` можно прочитать `retry_after`, а у ошибок валидации — `details`, если upstream вернул подробности по параметрам.
+
 ## Отладка интеграции
 
 SDK не раскрывает сырой transport в основном API, но даёт безопасный debug snapshot без секретов:

avito/accounts/domain.py

@@ -17,7 +17,7 @@
     EmployeesResult,
     OperationRecord,
 )
-from avito.core import PaginatedList, ValidationError
+from avito.core import PaginatedList
 from avito.core.domain import DomainObject
 
 
@@ -45,9 +45,7 @@ def get_balance(self, user_id: int | None = None) -> AccountBalance:
         Raises: AvitoError с полями operation, status, request_id, attempt, method и endpoint.
         """
 
-        resolved_user_id = user_id or (int(self.user_id) if self.user_id is not None else None)
-        if resolved_user_id is None:
-            raise ValidationError("Для операции требуется `user_id`.")
+        resolved_user_id = self._resolve_user_id(user_id or self.user_id)
         return AccountsClient(self.transport).get_balance(user_id=resolved_user_id)
 
     def get_operations_history(

avito/ads/domain.py

@@ -4,7 +4,7 @@
 
 from collections.abc import Sequence
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import date, datetime
 
 from avito.ads.client import (
     AdsClient,
@@ -63,8 +63,26 @@ def _preview_result(
     )
 
 
-def _serialize_datetime(value: datetime | None) -> str | None:
-    return value.isoformat() if value is not None else None
+StatsDate = date | datetime | str
+
+
+def _serialize_stats_date(value: StatsDate | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value.date().isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    normalized = value.strip()
+    if not normalized:
+        raise ValidationError("Дата статистики не должна быть пустой строкой.")
+    try:
+        return datetime.fromisoformat(normalized.replace("Z", "+00:00")).date().isoformat()
+    except ValueError:
+        try:
+            return date.fromisoformat(normalized).isoformat()
+        except ValueError as exc:
+            raise ValidationError("Дата статистики должна быть в ISO-формате.") from exc
 
 
 @dataclass(slots=True, frozen=True)
@@ -97,7 +115,7 @@ def list(
         Raises: AvitoError с полями operation, status, request_id, attempt, method и endpoint.
         """
 
-        user_id = int(self.user_id) if self.user_id is not None else None
+        user_id = self._resolve_user_id(self.user_id)
         return AdsClient(self.transport).list_items(
             user_id=user_id, status=status, limit=limit, offset=offset
         )
@@ -128,9 +146,9 @@ def _require_item_id(self) -> int:
         return int(self.item_id)
 
     def _require_ids(self) -> tuple[int, int]:
-        if self.item_id is None or self.user_id is None:
-            raise ValidationError("Для операции требуются `item_id` и `user_id`.")
-        return int(self.item_id), int(self.user_id)
+        if self.item_id is None:
+            raise ValidationError("Для операции требуется `item_id`.")
+        return int(self.item_id), self._resolve_user_id(self.user_id)
 
 
 @dataclass(slots=True, frozen=True)
@@ -144,8 +162,8 @@ def get_calls_stats(
         self,
         *,
         item_ids: list[int] | None = None,
-        date_from: datetime | None = None,
-        date_to: datetime | None = None,
+        date_from: StatsDate | None = None,
+        date_to: StatsDate | None = None,
     ) -> CallsStatsResult:
         """Получает статистику звонков.
 
@@ -157,16 +175,16 @@ def get_calls_stats(
         return StatsClient(self.transport).get_calls_stats(
             user_id=user_id,
             item_ids=resolved_item_ids,
-            date_from=_serialize_datetime(date_from),
-            date_to=_serialize_datetime(date_to),
+            date_from=_serialize_stats_date(date_from),
+            date_to=_serialize_stats_date(date_to),
         )
 
     def get_item_stats(
         self,
         *,
         item_ids: list[int] | None = None,
-        date_from: datetime | None = None,
-        date_to: datetime | None = None,
+        date_from: StatsDate | None = None,
+        date_to: StatsDate | None = None,
         fields: list[str] | None = None,
     ) -> ItemStatsResult:
         """Получает статистику по списку объявлений.
@@ -179,17 +197,17 @@ def get_item_stats(
         return StatsClient(self.transport).get_item_stats(
             user_id=user_id,
             item_ids=resolved_item_ids,
-            date_from=_serialize_datetime(date_from),
-            date_to=_serialize_datetime(date_to),
+            date_from=_serialize_stats_date(date_from),
+            date_to=_serialize_stats_date(date_to),
             fields=fields or [],
         )
 
     def get_item_analytics(
         self,
         *,
         item_ids: list[int] | None = None,
-        date_from: datetime | None = None,
-        date_to: datetime | None = None,
+        date_from: StatsDate | None = None,
+        date_to: StatsDate | None = None,
         fields: list[str] | None = None,
     ) -> ItemAnalyticsResult:
         """Получает аналитику по профилю.
@@ -202,17 +220,17 @@ def get_item_analytics(
         return StatsClient(self.transport).get_item_analytics(
             user_id=user_id,
             item_ids=resolved_item_ids,
-            date_from=_serialize_datetime(date_from),
-            date_to=_serialize_datetime(date_to),
+            date_from=_serialize_stats_date(date_from),
+            date_to=_serialize_stats_date(date_to),
             fields=fields or [],
         )
 
     def get_account_spendings(
         self,
         *,
         item_ids: list[int] | None = None,
-        date_from: datetime | None = None,
-        date_to: datetime | None = None,
+        date_from: StatsDate | None = None,
+        date_to: StatsDate | None = None,
         fields: list[str] | None = None,
     ) -> AccountSpendings:
         """Получает статистику расходов профиля.
@@ -225,15 +243,13 @@ def get_account_spendings(
         return StatsClient(self.transport).get_account_spendings(
             user_id=user_id,
             item_ids=resolved_item_ids,
-            date_from=_serialize_datetime(date_from),
-            date_to=_serialize_datetime(date_to),
+            date_from=_serialize_stats_date(date_from),
+            date_to=_serialize_stats_date(date_to),
             fields=fields or [],
         )
 
     def _require_user_id(self) -> int:
-        if self.user_id is None:
-            raise ValidationError("Для операции требуется `user_id`.")
-        return int(self.user_id)
+        return self._resolve_user_id(self.user_id)
 
 
 @dataclass(slots=True, frozen=True)
@@ -360,9 +376,7 @@ def _require_item_id(self) -> int:
         return int(self.item_id)
 
     def _require_user_id(self) -> int:
-        if self.user_id is None:
-            raise ValidationError("Для операции требуется `user_id`.")
-        return int(self.user_id)
+        return self._resolve_user_id(self.user_id)
 
     def _require_ids(self) -> tuple[int, int]:
         return self._require_item_id(), self._require_user_id()

avito/ads/mappers.py

@@ -58,6 +58,14 @@ def _list(payload: Payload, *keys: str) -> list[Payload]:
     return []
 
 
+def _mapping(payload: Payload, *keys: str) -> Payload | None:
+    for key in keys:
+        value = payload.get(key)
+        if isinstance(value, Mapping):
+            return cast(Payload, value)
+    return None
+
+
 def _str(payload: Payload, *keys: str) -> str | None:
     for key in keys:
         value = payload.get(key)
@@ -66,6 +74,20 @@ def _str(payload: Payload, *keys: str) -> str | None:
     return None
 
 
+def _nested_str(payload: Payload, *keys: str) -> str | None:
+    value = _str(payload, *keys)
+    if value is not None:
+        return value
+    for key in keys:
+        nested = _mapping(payload, key)
+        if nested is None:
+            continue
+        nested_value = _str(nested, "value", "name", "title", "slug", "status")
+        if nested_value is not None:
+            return nested_value
+    return None
+
+
 def _datetime(payload: Payload, *keys: str) -> datetime | None:
     for key in keys:
         value = payload.get(key)
@@ -95,6 +117,11 @@ def _float(payload: Payload, *keys: str) -> float | None:
             continue
         if isinstance(value, (int, float)):
             return float(value)
+        if isinstance(value, Mapping):
+            nested = cast(Payload, value)
+            nested_value = _float(nested, "value", "amount", "current", "price")
+            if nested_value is not None:
+                return nested_value
     return None
 
 
@@ -106,6 +133,16 @@ def _bool(payload: Payload, *keys: str) -> bool | None:
     return None
 
 
+def _visibility(payload: Payload) -> bool | None:
+    visible = _bool(payload, "is_visible", "isVisible", "visible")
+    if visible is not None:
+        return visible
+    status = _nested_str(payload, "status")
+    if status is None:
+        return None
+    return status in {"active", "published", "visible"}
+
+
 def map_ad_item(payload: object) -> Listing:
     """Преобразует объявление в dataclass."""
 
@@ -114,14 +151,20 @@ def map_ad_item(payload: object) -> Listing:
         item_id=_int(data, "id", "item_id", "itemId"),
         user_id=_int(data, "user_id", "userId"),
         title=_str(data, "title"),
-        description=_str(data, "description"),
+        description=_str(data, "description", "descriptionHtml"),
         status=map_enum_or_unknown(
-            _str(data, "status"),
+            _nested_str(data, "status"),
             ListingStatus,
             enum_name="ads.listing_status",
         ),
         price=_float(data, "price"),
         url=_str(data, "url", "link"),
+        category=_nested_str(data, "category", "categoryName"),
+        city=_nested_str(data, "city", "location"),
+        published_at=_datetime(data, "published_at", "publishedAt", "created_at", "createdAt"),
+        updated_at=_datetime(data, "updated_at", "updatedAt"),
+        is_moderated=_bool(data, "is_moderated", "isModerated", "moderated"),
+        is_visible=_visibility(data),
     )
 
 

avito/ads/models.py

@@ -20,6 +20,12 @@ class Listing(SerializableModel):
     status: ListingStatus | None
     price: float | None
     url: str | None
+    category: str | None = None
+    city: str | None = None
+    published_at: datetime | None = None
+    updated_at: datetime | None = None
+    is_moderated: bool | None = None
+    is_visible: bool | None = None
 
 
 @dataclass(slots=True, frozen=True)

avito/core/domain.py

@@ -5,6 +5,8 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from avito.core.exceptions import ValidationError
+
 if TYPE_CHECKING:
     from avito.core.transport import Transport
 
@@ -15,5 +17,25 @@ class DomainObject:
 
     transport: Transport
 
+    def _resolve_user_id(self, user_id: int | str | None = None) -> int:
+        """Возвращает user_id из аргумента, настроек SDK или профиля текущего пользователя."""
+
+        if user_id is not None:
+            return int(user_id)
+
+        configured_user_id = self.transport.debug_info().user_id
+        if configured_user_id is not None:
+            return configured_user_id
+
+        from avito.accounts.client import AccountsClient
+
+        profile = AccountsClient(self.transport).get_self()
+        if profile.user_id is None:
+            raise ValidationError(
+                "Для операции требуется `user_id`: передайте его в фабрику клиента, "
+                "в метод операции или задайте `AVITO_USER_ID`."
+            )
+        return profile.user_id
+
 
 __all__ = ("DomainObject",)

avito/core/exceptions.py

@@ -48,21 +48,32 @@ class AvitoError(Exception):
     status_code: int | None = None
     error_code: str | None = None
     operation: str | None = None
+    details: object | None = None
+    retry_after: float | None = None
+    request_id: str | None = None
     metadata: Mapping[str, object] = field(default_factory=dict)
     payload: object | None = None
     headers: Mapping[str, str] | None = None
 
     def __post_init__(self) -> None:
         sanitized_payload = sanitize_metadata(self.payload)
+        sanitized_details = sanitize_metadata(self.details)
         sanitized_headers = (
             sanitize_metadata(dict(self.headers)) if self.headers is not None else None
         )
         sanitized_metadata = sanitize_metadata(dict(self.metadata))
         Exception.__init__(self, self.message)
         object.__setattr__(self, "payload", sanitized_payload)
+        object.__setattr__(self, "details", sanitized_details)
         object.__setattr__(self, "headers", sanitized_headers)
         object.__setattr__(self, "metadata", sanitized_metadata)
 
+    @property
+    def status(self) -> int | None:
+        """HTTP-статус ответа API."""
+
+        return self.status_code
+
     def __str__(self) -> str:
         details: list[str] = [self.message]
         if self.operation is not None:
@@ -71,6 +82,10 @@ def __str__(self) -> str:
             details.append(f"status={self.status_code}")
         if self.error_code is not None:
             details.append(f"code={self.error_code}")
+        if self.retry_after is not None:
+            details.append(f"retry_after={self.retry_after}")
+        if self.request_id is not None:
+            details.append(f"request_id={self.request_id}")
         return " ".join(details)