add offers v2 compatibility

Author: sergioteula

amazon_paapi/models/item_result.py

@@ -340,6 +340,99 @@ class ApiBrowseNodeInfo(sdk_models.BrowseNodeInfo):
     website_sales_rank: ApiWebsiteSalesRank
 
 
+class ApiMoney(sdk_models.Money):
+    """Money representation for OffersV2 price fields."""
+
+    amount: float
+    currency: str
+    display_amount: str
+
+
+class ApiOfferAvailabilityV2(sdk_models.OfferAvailabilityV2):
+    """OffersV2 availability information."""
+
+    max_order_quantity: int
+    message: str
+    min_order_quantity: int
+    type: str
+
+
+class ApiOfferConditionV2(sdk_models.OfferConditionV2):
+    """OffersV2 condition information."""
+
+    condition_note: str
+    sub_condition: str
+    value: str
+
+
+class ApiDealDetails(sdk_models.DealDetails):
+    """Deal details for OffersV2 listings."""
+
+    access_type: str
+    badge: str
+    early_access_duration_in_milliseconds: int
+    end_time: str
+    percent_claimed: int
+    start_time: str
+
+
+class ApiOfferLoyaltyPointsV2(sdk_models.OfferLoyaltyPointsV2):
+    """OffersV2 loyalty points information."""
+
+    points: int
+
+
+class ApiOfferMerchantInfoV2(sdk_models.OfferMerchantInfoV2):
+    """OffersV2 merchant information."""
+
+    id: str
+    name: str
+
+
+class ApiOfferSavingBasis(sdk_models.OfferSavingBasis):
+    """Saving basis information for OffersV2."""
+
+    money: ApiMoney
+    saving_basis_type: str
+    saving_basis_type_label: str
+
+
+class ApiOfferSavingsV2(sdk_models.OfferSavingsV2):
+    """OffersV2 savings information."""
+
+    money: ApiMoney
+    percentage: int
+
+
+class ApiOfferPriceV2(sdk_models.OfferPriceV2):
+    """OffersV2 price information."""
+
+    money: ApiMoney
+    price_per_unit: ApiMoney
+    saving_basis: ApiOfferSavingBasis
+    savings: ApiOfferSavingsV2
+
+
+class ApiListingsV2(sdk_models.OfferListingV2):
+    """OffersV2 listing with all details."""
+
+    availability: ApiOfferAvailabilityV2
+    condition: ApiOfferConditionV2
+    deal_details: ApiDealDetails
+    is_buy_box_winner: bool
+    loyalty_points: ApiOfferLoyaltyPointsV2
+    merchant_info: ApiOfferMerchantInfoV2
+    price: ApiOfferPriceV2
+    type: sdk_models.OfferType
+    violates_map: bool
+
+
+class ApiOffersV2(sdk_models.OffersV2):
+    """Container for OffersV2 listings."""
+
+    listings: list[ApiListingsV2]
+
+
 class Item(sdk_models.Item):
     """Amazon product item with all details."""
 
@@ -350,6 +443,7 @@ class Item(sdk_models.Item):
     images: ApiImages
     item_info: ApiItemInfo
     offers: ApiOffers
+    offers_v2: ApiOffersV2
     parent_asin: str
     rental_offers: sdk_models.RentalOffers
     score: float

pyproject.toml

@@ -42,7 +42,13 @@ build-backend = "hatchling.build"
 packages = ["amazon_paapi"]
 
 [dependency-groups]
-dev = ["pre-commit>=2.21.0", "pytest>=7.4.4", "pytest-cov>=4.1.0"]
+dev = [
+    "mypy>=1.19.1",
+    "pre-commit>=2.21.0",
+    "pytest>=7.4.4",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.14.11",
+]
 
 [tool.ruff]
 target-version = "py39"

tests/integration_test.py

@@ -3,36 +3,165 @@
 from __future__ import annotations
 
 import os
+from typing import TYPE_CHECKING, ClassVar, cast
 from unittest import TestCase, skipUnless
 
 from amazon_paapi.api import AmazonApi
 
+if TYPE_CHECKING:
+    from amazon_paapi.models import BrowseNode, CountryCode
+    from amazon_paapi.models.item_result import Item
+    from amazon_paapi.models.search_result import SearchResult
+    from amazon_paapi.models.variations_result import VariationsResult
 
-def get_api_credentials() -> tuple[str | None, str | None, str | None, str | None]:
-    api_key = os.environ.get("API_KEY")
-    api_secret = os.environ.get("API_SECRET")
-    affiliate_tag = os.environ.get("AFFILIATE_TAG")
-    country_code = os.environ.get("COUNTRY_CODE")
 
-    return api_key, api_secret, affiliate_tag, country_code
+def get_api_credentials() -> tuple[str, str, str, CountryCode]:
+    """Get API credentials from environment variables.
 
+    Raises:
+        ValueError: If any required credential is missing.
+    """
+    credentials = {
+        "API_KEY": os.environ.get("API_KEY"),
+        "API_SECRET": os.environ.get("API_SECRET"),
+        "AFFILIATE_TAG": os.environ.get("AFFILIATE_TAG"),
+        "COUNTRY_CODE": os.environ.get("COUNTRY_CODE"),
+    }
 
-@skipUnless(all(get_api_credentials()), "Needs Amazon API credentials")
+    missing = [key for key, value in credentials.items() if value is None]
+    if missing:
+        msg = f"Missing environment variables: {', '.join(missing)}"
+        raise ValueError(msg)
+
+    return (
+        cast("str", credentials["API_KEY"]),
+        cast("str", credentials["API_SECRET"]),
+        cast("str", credentials["AFFILIATE_TAG"]),
+        cast("CountryCode", credentials["COUNTRY_CODE"]),
+    )
+
+
+def has_api_credentials() -> bool:
+    """Check if all API credentials are available."""
+    try:
+        get_api_credentials()
+    except ValueError:
+        return False
+    return True
+
+
+@skipUnless(has_api_credentials(), "Needs Amazon API credentials")
 class IntegrationTest(TestCase):
+    """Integration tests that make real API calls to Amazon.
+
+    All API results are cached at class level to minimize the number of
+    requests. This reduces costs and avoids rate limiting.
+    """
+
+    api: ClassVar[AmazonApi]
+    affiliate_tag: ClassVar[str]
+    search_result: ClassVar[SearchResult]
+    item_with_offers: ClassVar[Item]
+    get_items_result: ClassVar[list[Item]]
+    variations_result: ClassVar[VariationsResult]
+    browse_nodes_result: ClassVar[list[BrowseNode]]
+
     @classmethod
-    def setUpClass(cls):
+    def setUpClass(cls) -> None:
+        """Set up API client and make shared API calls once for all tests."""
         api_key, api_secret, affiliate_tag, country_code = get_api_credentials()
+
         cls.api = AmazonApi(api_key, api_secret, affiliate_tag, country_code)
         cls.affiliate_tag = affiliate_tag
 
-    def test_search_items_and_get_information_for_the_first_one(self):
-        search_result = self.api.search_items(keywords="zapatillas")
-        searched_item = search_result.items[0]
+        cls.search_result = cls.api.search_items(keywords="laptop")
+
+        cls.item_with_offers = next(
+            (item for item in cls.search_result.items if item.offers_v2 is not None),
+            cls.search_result.items[0],
+        )
+        cls.get_items_result = cls.api.get_items(cls.item_with_offers.asin)
+
+        item_with_variations = next(
+            (item for item in cls.search_result.items if item.parent_asin),
+            cls.search_result.items[0],
+        )
+        cls.variations_result = cls.api.get_variations(
+            item_with_variations.parent_asin or item_with_variations.asin
+        )
+
+        item_with_browse_nodes = next(
+            (
+                item
+                for item in cls.search_result.items
+                if item.browse_node_info and item.browse_node_info.browse_nodes
+            ),
+            None,
+        )
+        if item_with_browse_nodes:
+            browse_node_id = item_with_browse_nodes.browse_node_info.browse_nodes[0].id
+            cls.browse_nodes_result = cls.api.get_browse_nodes([browse_node_id])
+        else:
+            cls.browse_nodes_result = []
 
-        self.assertEqual(10, len(search_result.items))
+    def test_search_items_returns_expected_count(self) -> None:
+        """Test that search returns the default number of items."""
+        self.assertEqual(10, len(self.search_result.items))
+
+    def test_search_items_includes_affiliate_tag(self) -> None:
+        """Test that search results include the affiliate tag in URLs."""
+        searched_item = self.search_result.items[0]
         self.assertIn(self.affiliate_tag, searched_item.detail_page_url)
 
-        get_results = self.api.get_items(searched_item.asin)
+    def test_search_items_returns_offers_v2(self) -> None:
+        """Test that search results include OffersV2 data."""
+        self.assertGreater(len(self.search_result.items), 0)
+
+        item = self.item_with_offers
+        self.assertIsNotNone(item.offers_v2)
+
+        if item.offers_v2.listings:
+            listing = item.offers_v2.listings[0]
+            self.assertIsNotNone(listing)
+
+    def test_get_items_returns_single_result(self) -> None:
+        """Test that get_items returns exactly one item when given one ASIN."""
+        self.assertEqual(1, len(self.get_items_result))
+
+    def test_get_items_includes_affiliate_tag(self) -> None:
+        """Test that get_items results include the affiliate tag in URLs."""
+        self.assertIn(self.affiliate_tag, self.get_items_result[0].detail_page_url)
+
+    def test_get_items_returns_offers_v2(self) -> None:
+        """Test that get_items returns OffersV2 data."""
+        item = self.get_items_result[0]
+        self.assertIsNotNone(item.offers_v2)
+
+        if item.offers_v2.listings:
+            listing = item.offers_v2.listings[0]
+            self.assertIsNotNone(listing)
+
+    def test_get_variations_returns_items(self) -> None:
+        """Test that get_variations returns a list of variation items."""
+        self.assertIsNotNone(self.variations_result)
+        self.assertGreater(len(self.variations_result.items), 0)
+
+    def test_get_variations_returns_variation_summary(self) -> None:
+        """Test that get_variations returns variation summary."""
+        self.assertIsNotNone(self.variations_result.variation_summary)
+        self.assertGreater(self.variations_result.variation_summary.variation_count, 0)
+
+    def test_get_variations_items_include_affiliate_tag(self) -> None:
+        """Test that variation items include the affiliate tag in URLs."""
+        item = self.variations_result.items[0]
+        self.assertIn(self.affiliate_tag, item.detail_page_url)
+
+    def test_get_browse_nodes_returns_results(self) -> None:
+        """Test that get_browse_nodes returns browse node information."""
+        self.assertGreater(len(self.browse_nodes_result), 0)
 
-        self.assertEqual(1, len(get_results))
-        self.assertIn(self.affiliate_tag, get_results[0].detail_page_url)
+    def test_get_browse_nodes_returns_node_info(self) -> None:
+        """Test that browse nodes contain expected information."""
+        node = self.browse_nodes_result[0]
+        self.assertIsNotNone(node.id)
+        self.assertIsNotNone(node.display_name)

tests/offersv2_test.py

@@ -0,0 +1,79 @@
+"""Tests for OffersV2 functionality."""
+
+import unittest
+
+from amazon_paapi.helpers import requests
+from amazon_paapi.models.item_result import (
+    ApiDealDetails,
+    ApiListingsV2,
+    ApiOfferPriceV2,
+    ApiOfferSavingBasis,
+    Item,
+)
+from amazon_paapi.sdk.models.get_items_resource import GetItemsResource
+from amazon_paapi.sdk.models.get_variations_resource import GetVariationsResource
+from amazon_paapi.sdk.models.search_items_resource import SearchItemsResource
+
+EXPECTED_OFFERSV2_RESOURCES = [
+    "OffersV2.Listings.Availability",
+    "OffersV2.Listings.Condition",
+    "OffersV2.Listings.DealDetails",
+    "OffersV2.Listings.IsBuyBoxWinner",
+    "OffersV2.Listings.LoyaltyPoints",
+    "OffersV2.Listings.MerchantInfo",
+    "OffersV2.Listings.Price",
+    "OffersV2.Listings.Type",
+]
+
+
+class TestOffersV2Resources(unittest.TestCase):
+    """Test cases for OffersV2 resource constants."""
+
+    def test_get_items_resources_include_all_offersv2(self) -> None:
+        """Verify _get_request_resources includes all OffersV2 resources."""
+        resources = requests._get_request_resources(GetItemsResource)
+        for resource in EXPECTED_OFFERSV2_RESOURCES:
+            self.assertIn(resource, resources)
+
+    def test_search_items_resources_include_all_offersv2(self) -> None:
+        """Verify _get_request_resources includes all OffersV2 resources for search."""
+        resources = requests._get_request_resources(SearchItemsResource)
+        for resource in EXPECTED_OFFERSV2_RESOURCES:
+            self.assertIn(resource, resources)
+
+    def test_get_variations_resources_include_all_offersv2(self) -> None:
+        """Verify _get_request_resources includes OffersV2 resources."""
+        resources = requests._get_request_resources(GetVariationsResource)
+        for resource in EXPECTED_OFFERSV2_RESOURCES:
+            self.assertIn(resource, resources)
+
+
+class TestOffersV2Models(unittest.TestCase):
+    """Test cases for OffersV2 model structure."""
+
+    def test_item_has_offers_v2_attribute(self) -> None:
+        """Verify Item class has offers_v2 typed as ApiOffersV2."""
+        self.assertIn("offers_v2", Item.__annotations__)
+        self.assertEqual(Item.__annotations__["offers_v2"], "ApiOffersV2")
+
+    def test_api_listings_v2_has_required_attributes(self) -> None:
+        """Verify ApiListingsV2 has violates_map and deal_details."""
+        annotations = ApiListingsV2.__annotations__
+        self.assertIn("violates_map", annotations)
+        self.assertIn("deal_details", annotations)
+
+    def test_api_deal_details_has_required_attributes(self) -> None:
+        """Verify ApiDealDetails has badge and access_type."""
+        annotations = ApiDealDetails.__annotations__
+        self.assertIn("badge", annotations)
+        self.assertIn("access_type", annotations)
+
+    def test_api_offer_price_v2_has_required_attributes(self) -> None:
+        """Verify ApiOfferPriceV2 has money and savings."""
+        annotations = ApiOfferPriceV2.__annotations__
+        self.assertIn("money", annotations)
+        self.assertIn("savings", annotations)
+
+    def test_api_offer_saving_basis_has_saving_basis_type(self) -> None:
+        """Verify ApiOfferSavingBasis has saving_basis_type."""
+        self.assertIn("saving_basis_type", ApiOfferSavingBasis.__annotations__)