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

Author: p141592

README.md

@@ -131,7 +131,7 @@ 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` с подсказкой, как вызвать метод правильно.
+`user_id` можно передать явно, задать через `AVITO_USER_ID` или оставить пустым для read-only вызовов, где SDK может определить пользователя через `account().get_self()`. Если идентификатор не удалось определить, SDK поднимает `ValidationError` с подсказкой, как вызвать метод правильно. Для OAuth secret поддерживаются `AVITO_CLIENT_SECRET` и alias `AVITO_SECRET`.
 
 Статистические методы принимают `date`, `datetime` и ISO-строки, а в Avito API отправляют дату в формате `YYYY-MM-DD`. Модель `Listing` нормализует основные поля объявления: `title`, `price`, `status`, `description`, `url`, `category`, `city`, `published_at`, `updated_at`, `is_moderated`, `is_visible`.
 
@@ -270,7 +270,7 @@ with AvitoClient.from_env() as avito:
     tariff = avito.tariff().get_tariff_info()
 ```
 
-`review().list()` по умолчанию запрашивает первую страницу отзывов (`page=1`). Для явной пагинации передайте `ReviewsQuery(page=...)`.
+`review().list()` по умолчанию запрашивает первую страницу отзывов (`page=1`, `limit=50`). Для явной пагинации передайте `ReviewsQuery(page=..., limit=...)`.
 
 ## Пагинация
 
@@ -291,13 +291,15 @@ with AvitoClient.from_env() as avito:
 from avito import AvitoClient
 
 with AvitoClient.from_env() as avito:
-    items = avito.ad(user_id=123).list(status="active", limit=50)
+    items = avito.ad(user_id=123).list(status="active", limit=50, page_size=25)
 
     first = items[0]
     preview = items[:10]
     all_items = items.materialize()
 ```
 
+В `ad().list()` параметр `limit` ограничивает общий максимум элементов результата, а `page_size` задаёт размер страницы upstream API.
+
 ## Ошибки
 
 Все исключения SDK наследуются от `AvitoError` и импортируются из `avito.core.exceptions`. HTTP-коды отображаются в конкретные типы:

avito/__init__.py

@@ -17,19 +17,39 @@
     ValidationError,
 )
 from avito.core.pagination import PaginatedList
+from avito.summary import (
+    AccountHealthSummary,
+    CapabilityDiscoveryResult,
+    CapabilityInfo,
+    ChatSummary,
+    ListingHealthItem,
+    ListingHealthSummary,
+    OrderSummary,
+    PromotionSummary,
+    ReviewSummary,
+)
 
 __all__ = (
+    "AccountHealthSummary",
     "AuthSettings",
     "AuthenticationError",
     "AuthorizationError",
     "AvitoClient",
     "AvitoError",
     "AvitoSettings",
+    "CapabilityDiscoveryResult",
+    "CapabilityInfo",
+    "ChatSummary",
     "ConfigurationError",
     "ConflictError",
+    "ListingHealthItem",
+    "ListingHealthSummary",
+    "OrderSummary",
     "PaginatedList",
+    "PromotionSummary",
     "RateLimitError",
     "ResponseMappingError",
+    "ReviewSummary",
     "TransportError",
     "UnsupportedOperationError",
     "UpstreamApiError",

avito/ads/client.py

@@ -67,6 +67,14 @@
 from avito.promotion.models import PromotionActionResult
 
 
+def _bounded_total(total: int | None, max_items: int | None) -> int | None:
+    if max_items is None:
+        return total
+    if total is None:
+        return max_items
+    return min(total, max_items)
+
+
 @dataclass(slots=True, frozen=True)
 class AdsClient:
     """Выполняет HTTP-операции по разделу объявлений."""
@@ -90,11 +98,13 @@ def list_items(
         user_id: int | None = None,
         status: ListingStatus | str | None = None,
         limit: int | None = None,
+        page_size: int | None = None,
         offset: int | None = None,
     ) -> PaginatedList[Listing]:
         """Получает список объявлений пользователя."""
 
-        start_offset = offset if offset is not None else 0 if limit is not None else None
+        resolved_page_size = page_size or limit
+        start_offset = offset if offset is not None else 0 if resolved_page_size is not None else None
         result = request_public_model(
             self.transport,
             "GET",
@@ -104,16 +114,19 @@ def list_items(
             params={
                 "user_id": user_id,
                 "status": status,
-                "limit": limit,
+                "limit": resolved_page_size,
                 "offset": start_offset,
             },
         )
-        page_size = limit if limit and limit > 0 else len(result.items)
+        page_size = resolved_page_size if resolved_page_size and resolved_page_size > 0 else len(result.items)
+        max_items = limit if limit is not None and limit >= 0 else None
+        first_items = result.items[:max_items] if max_items is not None else result.items
+        total = _bounded_total(result.total, max_items)
         resolved_offset = start_offset or 0
         start_page = resolved_offset // page_size + 1 if page_size > 0 else 1
         first_page = JsonPage(
-            items=list(result.items),
-            total=result.total,
+            items=list(first_items),
+            total=total,
             page=start_page,
             per_page=page_size if page_size > 0 else None,
         )
@@ -123,6 +136,8 @@ def list_items(
                 user_id=user_id,
                 status=status,
                 page_size=page_size,
+                max_items=max_items,
+                base_offset=resolved_offset,
             )
         ).as_list(start_page=start_page, first_page=first_page)
 
@@ -133,11 +148,17 @@ def _fetch_ads_page(
         user_id: int | None,
         status: ListingStatus | str | None,
         page_size: int,
+        max_items: int | None,
+        base_offset: int,
     ) -> JsonPage[Listing]:
         if page is None:
             raise ValidationError("Для операции требуется `page`.")
 
         offset = (page - 1) * page_size
+        already_requested = max(offset - base_offset, 0)
+        remaining = max_items - already_requested if max_items is not None else None
+        if remaining is not None and remaining <= 0:
+            return JsonPage(items=[], total=max_items, page=page, per_page=page_size)
         result = request_public_model(
             self.transport,
             "GET",
@@ -147,13 +168,14 @@ def _fetch_ads_page(
             params={
                 "user_id": user_id,
                 "status": status,
-                "limit": page_size,
+                "limit": min(page_size, remaining) if remaining is not None else page_size,
                 "offset": offset,
             },
         )
+        items = result.items[:remaining] if remaining is not None else result.items
         return JsonPage(
-            items=list(result.items),
-            total=result.total,
+            items=list(items),
+            total=_bounded_total(result.total, max_items),
             page=page,
             per_page=page_size,
         )

avito/ads/domain.py

@@ -106,6 +106,7 @@ def list(
         *,
         status: ListingStatus | str | None = None,
         limit: int | None = None,
+        page_size: int | None = None,
         offset: int | None = None,
     ) -> PaginatedList[Listing]:
         """Получает список объявлений.
@@ -117,7 +118,11 @@ def list(
 
         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
+            user_id=user_id,
+            status=status,
+            limit=limit,
+            page_size=page_size,
+            offset=offset,
         )
 
     def update_price(

avito/ads/enums.py

@@ -10,6 +10,12 @@ class ListingStatus(str, Enum):
 
     UNKNOWN = "__unknown__"
     ACTIVE = "active"
+    REMOVED = "removed"
+    OLD = "old"
+    BLOCKED = "blocked"
+    REJECTED = "rejected"
+    NOT_FOUND = "not_found"
+    ANOTHER_USER = "another_user"
 
 
 class AdsActionStatus(str, Enum):

avito/ads/mappers.py

@@ -107,6 +107,8 @@ def _int(payload: Payload, *keys: str) -> int | None:
             continue
         if isinstance(value, int):
             return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
     return None
 
 
@@ -147,24 +149,25 @@ def map_ad_item(payload: object) -> Listing:
     """Преобразует объявление в dataclass."""
 
     data = _expect_mapping(payload)
+    source = _mapping(data, "item", "resource", "listing", "ad") or data
     return Listing(
-        item_id=_int(data, "id", "item_id", "itemId"),
-        user_id=_int(data, "user_id", "userId"),
-        title=_str(data, "title"),
-        description=_str(data, "description", "descriptionHtml"),
+        item_id=_int(source, "id", "item_id", "itemId", "itemID"),
+        user_id=_int(source, "user_id", "userId"),
+        title=_str(source, "title", "name"),
+        description=_str(source, "description", "descriptionHtml"),
         status=map_enum_or_unknown(
-            _nested_str(data, "status"),
+            _nested_str(source, "status", "state"),
             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),
+        price=_float(source, "price"),
+        url=_str(source, "url", "link", "uri"),
+        category=_nested_str(source, "category", "categoryName"),
+        city=_nested_str(source, "city", "location"),
+        published_at=_datetime(source, "published_at", "publishedAt", "created_at", "createdAt"),
+        updated_at=_datetime(source, "updated_at", "updatedAt"),
+        is_moderated=_bool(source, "is_moderated", "isModerated", "moderated"),
+        is_visible=_visibility(source),
     )
 
 

avito/auth/settings.py

@@ -16,7 +16,7 @@ class AuthSettings:
 
     ENV_ALIASES: ClassVar[dict[str, tuple[str, ...]]] = {
         "client_id": ("AVITO_CLIENT_ID",),
-        "client_secret": ("AVITO_CLIENT_SECRET",),
+        "client_secret": ("AVITO_CLIENT_SECRET", "AVITO_SECRET"),
         "scope": ("AVITO_SCOPE",),
         "refresh_token": ("AVITO_REFRESH_TOKEN",),
         "token_url": ("AVITO_TOKEN_URL",),