From 94a77b348f4ebd607bd0eb61bd04ba212a6a2662 Mon Sep 17 00:00:00 2001 From: Aaron <7063649+ahcodedev@users.noreply.github.com> Date: Mon, 9 Nov 2026 22:37:16 -0800 Subject: [PATCH] Marketplace - Offer Feedback API endpoint --- README.md | 4 +- docs/index.md | 19 ++++- src/pypricecharting/asyncpricecharting.py | 36 ++++++++-- src/pypricecharting/pricecharting.py | 36 ++++++++-- tests/test_asyncpricecharting_marketplace.py | 75 ++++++++++++++++++-- tests/test_pricecharting_marketplace.py | 69 ++++++++++++++++-- 6 files changed, 217 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 3642704..ae2bd34 100644 --- a/README.md +++ b/README.md @@ -73,8 +73,8 @@ See [RELEASE.md](RELEASE.md) for how releases and release labels work. ## Usage Under development: the Prices API methods (`product`, `products`) and the Marketplace `offers`, -`offer_details`, and `offer_publish` methods are implemented; the other Marketplace API methods -are not yet. +`offer_details`, `offer_publish`, and `offer_feedback` methods are implemented; the other +Marketplace API methods are not yet. ```python from pypricecharting import AsyncPriceCharting, PriceCharting diff --git a/docs/index.md b/docs/index.md index c0a55f3..b2a49f2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,8 +6,8 @@ It provides a synchronous client, `PriceCharting`, and an asynchronous client, `AsyncPriceCharting`, both authenticated with a 40-character API token. Under development: the Prices API methods (`product`, `products`) and the Marketplace `offers`, -`offer_details`, and `offer_publish` methods are implemented; the other Marketplace API methods -are not yet. +`offer_details`, `offer_publish`, and `offer_feedback` methods are implemented; the other +Marketplace API methods are not yet. ## Authentication @@ -123,6 +123,21 @@ with PriceCharting() as client: Set `offer_id` instead of a product identifier to edit an existing offer. Set `price_min` to make the offer a reverse auction that drops from `price_max` over 30 days. +## Leaving feedback + +`offer_feedback` rates the other party of an offer. It takes the offer ID, a `Rating`, and an +optional comment: + +```python +from pypricecharting import PriceCharting, Rating + +with PriceCharting() as client: + feedback = client.offer_feedback("vtdsww72uyslgooawzyyijsllm", Rating.GREAT, "Great buyer") + print(feedback.offer_id, feedback.rating, feedback.comment) +``` + +An empty or whitespace-only offer ID raises `ParameterError`. + ## Errors All errors subclass `PriceChartingError`: diff --git a/src/pypricecharting/asyncpricecharting.py b/src/pypricecharting/asyncpricecharting.py index 99a18b1..a851aa2 100644 --- a/src/pypricecharting/asyncpricecharting.py +++ b/src/pypricecharting/asyncpricecharting.py @@ -11,6 +11,7 @@ from pypricecharting.requests import OfferPublishRequestParams, OffersRequestParams from pypricecharting.responses import ( OfferDetailsResponse, + OfferFeedbackResponse, OfferPublishResponse, OffersResponse, ProductResponse, @@ -18,13 +19,14 @@ _parse, ) from pypricecharting.route import BASE_URL, Route +from pypricecharting.types import Rating class AsyncPriceCharting: """Asynchronous PriceCharting API client. Reuse one client for all requests and close it when done (`async with` or `aclose()`). The Marketplace - methods other than `offers`, `offer_details`, and `offer_publish` are not implemented yet and return `None`. + methods `offer_ship`, `offer_end`, and `offer_refund` are not implemented yet and return `None`. """ TOKEN_KEY = "PRICECHARTING_TOKEN" @@ -198,9 +200,35 @@ async def offer_publish(self, params: OfferPublishRequestParams) -> OfferPublish ) return _parse(response, OfferPublishResponse) - async def offer_feedback(self): - """Leave feedback on a marketplace offer.""" - pass + async def offer_feedback( + self, offer_id: str, rating: Rating, comment: str | None = None + ) -> OfferFeedbackResponse: + """Leave feedback on a marketplace offer. + + Args: + offer_id: The offer ID. Surrounding whitespace is stripped. + rating: How the transaction went. + comment: Text explaining the rating. + + Returns: + The feedback left. + + Raises: + ParameterError: If `offer_id` is empty or only whitespace. + APIError: If the API returns an error. + + """ + offer_id = offer_id.strip() + + if len(offer_id) == 0: + raise ParameterError("Invalid parameter; offer_id was empty.") + + data: dict[str, str | int] = {"offer-id": offer_id, "rating": rating.value} + if comment is not None: + data["comment"] = comment + + response = await self._client.post(Route.Marketplace.OFFER_FEEDBACK, data=data) + return _parse(response, OfferFeedbackResponse) async def offer_ship(self): """Mark a marketplace offer as shipped.""" diff --git a/src/pypricecharting/pricecharting.py b/src/pypricecharting/pricecharting.py index b59e358..649098a 100644 --- a/src/pypricecharting/pricecharting.py +++ b/src/pypricecharting/pricecharting.py @@ -11,6 +11,7 @@ from pypricecharting.requests import OfferPublishRequestParams, OffersRequestParams from pypricecharting.responses import ( OfferDetailsResponse, + OfferFeedbackResponse, OfferPublishResponse, OffersResponse, ProductResponse, @@ -18,13 +19,14 @@ _parse, ) from pypricecharting.route import BASE_URL, Route +from pypricecharting.types import Rating class PriceCharting: """Synchronous PriceCharting API client. Reuse one client for all requests and close it when done (`with` or `close()`). The Marketplace - methods other than `offers`, `offer_details`, and `offer_publish` are not implemented yet and return `None`. + methods `offer_ship`, `offer_end`, and `offer_refund` are not implemented yet and return `None`. """ TOKEN_KEY = "PRICECHARTING_TOKEN" @@ -195,9 +197,35 @@ def offer_publish(self, params: OfferPublishRequestParams) -> OfferPublishRespon ) return _parse(response, OfferPublishResponse) - def offer_feedback(self): - """Leave feedback on a marketplace offer.""" - pass + def offer_feedback( + self, offer_id: str, rating: Rating, comment: str | None = None + ) -> OfferFeedbackResponse: + """Leave feedback on a marketplace offer. + + Args: + offer_id: The offer ID. Surrounding whitespace is stripped. + rating: How the transaction went. + comment: Text explaining the rating. + + Returns: + The feedback left. + + Raises: + ParameterError: If `offer_id` is empty or only whitespace. + APIError: If the API returns an error. + + """ + offer_id = offer_id.strip() + + if len(offer_id) == 0: + raise ParameterError("Invalid parameter; offer_id was empty.") + + data: dict[str, str | int] = {"offer-id": offer_id, "rating": rating.value} + if comment is not None: + data["comment"] = comment + + response = self._client.post(Route.Marketplace.OFFER_FEEDBACK, data=data) + return _parse(response, OfferFeedbackResponse) def offer_ship(self): """Mark a marketplace offer as shipped.""" diff --git a/tests/test_asyncpricecharting_marketplace.py b/tests/test_asyncpricecharting_marketplace.py index 2ed8dc3..0310fb3 100644 --- a/tests/test_asyncpricecharting_marketplace.py +++ b/tests/test_asyncpricecharting_marketplace.py @@ -6,10 +6,16 @@ from pypricecharting.asyncpricecharting import AsyncPriceCharting from pypricecharting.error import APIError, ParameterError from pypricecharting.requests import OfferPublishRequestParams, OffersRequestParams, OffersStatus -from pypricecharting.responses import OfferDetailsResponse, OfferPublishResponse, OffersResponse -from pypricecharting.types import Condition, Status +from pypricecharting.responses import ( + OfferDetailsResponse, + OfferFeedbackResponse, + OfferPublishResponse, + OffersResponse, +) +from pypricecharting.types import Condition, Rating, Status from tests.mocks.json import ( OFFER_DETAILS_JSON, + OFFER_FEEDBACK_JSON, OFFER_PUBLISH_REQUEST_JSON, OFFER_PUBLISH_RESPONSE_JSON, OFFERS_JSON, @@ -166,9 +172,68 @@ async def test_offer_publish_raises_api_error(): async def test_offer_feedback(): - client = AsyncPriceCharting(TOKEN) - assert await client.offer_feedback() is None - await client.aclose() + requests: list[Request] = [] + + async with mocked_async_client( + TOKEN, Response(200, json=OFFER_FEEDBACK_JSON), requests + ) as client: + response = await client.offer_feedback( + "vtdsww72uyslgooawzyyijsllm", Rating.GREAT, "Great buyer" + ) + + assert isinstance(response, OfferFeedbackResponse) + assert response.status == Status.SUCCESS + assert response.offer_id == "vtdsww72uyslgooawzyyijsllm" + assert response.rating == Rating.GREAT + assert response.comment == "Great buyer" + + assert len(requests) == 1 + assert requests[0].method == "POST" + assert requests[0].url.path == "/api/offer-feedback" + assert "t" not in requests[0].url.params + assert dict(parse_qsl(requests[0].content.decode())) == { + "offer-id": "vtdsww72uyslgooawzyyijsllm", + "rating": "2", + "comment": "Great buyer", + "t": TOKEN, + } + + +async def test_offer_feedback_without_comment(): + requests: list[Request] = [] + + async with mocked_async_client( + TOKEN, Response(200, json=OFFER_FEEDBACK_JSON), requests + ) as client: + await client.offer_feedback(" testofferid ", Rating.AWFUL) + + assert dict(parse_qsl(requests[0].content.decode())) == { + "offer-id": "testofferid", + "rating": "-2", + "t": TOKEN, + } + + +@pytest.mark.parametrize("offer_id", ["", " "]) +async def test_offer_feedback_empty_offer_id_raises_parameter_error(offer_id: str): + requests: list[Request] = [] + + async with mocked_async_client( + TOKEN, Response(200, json=OFFER_FEEDBACK_JSON), requests + ) as client: + with pytest.raises(ParameterError, match="offer_id was empty"): + await client.offer_feedback(offer_id, Rating.GOOD) + + assert requests == [] + + +async def test_offer_feedback_raises_api_error(): + requests: list[Request] = [] + async with mocked_async_client( + TOKEN, Response(404, json=error_body("No such offer")), requests + ) as client: + with pytest.raises(APIError, match="404: No such offer"): + await client.offer_feedback("missing", Rating.OK) async def test_offer_ship(): diff --git a/tests/test_pricecharting_marketplace.py b/tests/test_pricecharting_marketplace.py index ec3874d..16201c6 100644 --- a/tests/test_pricecharting_marketplace.py +++ b/tests/test_pricecharting_marketplace.py @@ -6,10 +6,16 @@ from pypricecharting.error import APIError, ParameterError from pypricecharting.pricecharting import PriceCharting from pypricecharting.requests import OfferPublishRequestParams, OffersRequestParams, OffersStatus -from pypricecharting.responses import OfferDetailsResponse, OfferPublishResponse, OffersResponse -from pypricecharting.types import Condition, Status +from pypricecharting.responses import ( + OfferDetailsResponse, + OfferFeedbackResponse, + OfferPublishResponse, + OffersResponse, +) +from pypricecharting.types import Condition, Rating, Status from tests.mocks.json import ( OFFER_DETAILS_JSON, + OFFER_FEEDBACK_JSON, OFFER_PUBLISH_REQUEST_JSON, OFFER_PUBLISH_RESPONSE_JSON, OFFERS_JSON, @@ -158,9 +164,62 @@ def test_offer_publish_raises_api_error(): def test_offer_feedback(): - client = PriceCharting(TOKEN) - assert client.offer_feedback() is None - client.close() + requests: list[Request] = [] + + with mocked_client(TOKEN, Response(200, json=OFFER_FEEDBACK_JSON), requests) as client: + response = client.offer_feedback("vtdsww72uyslgooawzyyijsllm", Rating.GREAT, "Great buyer") + + assert isinstance(response, OfferFeedbackResponse) + assert response.status == Status.SUCCESS + assert response.offer_id == "vtdsww72uyslgooawzyyijsllm" + assert response.rating == Rating.GREAT + assert response.comment == "Great buyer" + + assert len(requests) == 1 + assert requests[0].method == "POST" + assert requests[0].url.path == "/api/offer-feedback" + assert "t" not in requests[0].url.params + assert dict(parse_qsl(requests[0].content.decode())) == { + "offer-id": "vtdsww72uyslgooawzyyijsllm", + "rating": "2", + "comment": "Great buyer", + "t": TOKEN, + } + + +def test_offer_feedback_without_comment(): + requests: list[Request] = [] + + with mocked_client(TOKEN, Response(200, json=OFFER_FEEDBACK_JSON), requests) as client: + client.offer_feedback(" testofferid ", Rating.AWFUL) + + assert dict(parse_qsl(requests[0].content.decode())) == { + "offer-id": "testofferid", + "rating": "-2", + "t": TOKEN, + } + + +@pytest.mark.parametrize("offer_id", ["", " "]) +def test_offer_feedback_empty_offer_id_raises_parameter_error(offer_id: str): + requests: list[Request] = [] + + with ( + mocked_client(TOKEN, Response(200, json=OFFER_FEEDBACK_JSON), requests) as client, + pytest.raises(ParameterError, match="offer_id was empty"), + ): + client.offer_feedback(offer_id, Rating.GOOD) + + assert requests == [] + + +def test_offer_feedback_raises_api_error(): + requests: list[Request] = [] + with ( + mocked_client(TOKEN, Response(404, json=error_body("No such offer")), requests) as client, + pytest.raises(APIError, match="404: No such offer"), + ): + client.offer_feedback("missing", Rating.OK) def test_offer_ship():