From 5a7a3f2b56cdeedc51251274bdbd849a5c47b6ee Mon Sep 17 00:00:00 2001 From: Aaron <7063649+ahcodedev@users.noreply.github.com> Date: Mon, 9 Nov 2026 22:39:39 -0800 Subject: [PATCH] Marketplace API - Offers Ship endpoint --- README.md | 4 +- docs/index.md | 21 ++++++- src/pypricecharting/asyncpricecharting.py | 35 ++++++++++-- src/pypricecharting/pricecharting.py | 33 +++++++++-- tests/test_asyncpricecharting_marketplace.py | 57 ++++++++++++++++++- tests/test_pricecharting_marketplace.py | 59 +++++++++++++++++++- 6 files changed, 191 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ae2bd34..69efbec 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`, `offer_publish`, and `offer_feedback` methods are implemented; the other -Marketplace API methods are not yet. +`offer_details`, `offer_publish`, `offer_feedback`, and `offer_ship` methods are implemented; +`offer_end` and `offer_refund` are not yet. ```python from pypricecharting import AsyncPriceCharting, PriceCharting diff --git a/docs/index.md b/docs/index.md index b2a49f2..6ebd9d8 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`, `offer_publish`, and `offer_feedback` methods are implemented; the other -Marketplace API methods are not yet. +`offer_details`, `offer_publish`, `offer_feedback`, and `offer_ship` methods are implemented; +`offer_end` and `offer_refund` are not yet. ## Authentication @@ -138,6 +138,23 @@ with PriceCharting() as client: An empty or whitespace-only offer ID raises `ParameterError`. +## Marking an offer as shipped + +`offer_ship` tells PriceCharting a sold offer has shipped. It takes the offer ID and an optional +tracking number: + +```python +from pypricecharting import PriceCharting + +with PriceCharting() as client: + shipped = client.offer_ship("vtdsww72uyslgooawzyyijsllm", "901234567890000") + print(shipped.offer_id, shipped.is_shipped, shipped.shipped_time) +``` + +A valid tracking number can earn you positive feedback if the buyer leaves none, as long as it +shows shipment within 3 days and delivery to the buyer's address. 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 a851aa2..dce3578 100644 --- a/src/pypricecharting/asyncpricecharting.py +++ b/src/pypricecharting/asyncpricecharting.py @@ -13,6 +13,7 @@ OfferDetailsResponse, OfferFeedbackResponse, OfferPublishResponse, + OfferShipResponse, OffersResponse, ProductResponse, ProductsResponse, @@ -26,7 +27,7 @@ class AsyncPriceCharting: """Asynchronous PriceCharting API client. Reuse one client for all requests and close it when done (`async with` or `aclose()`). The Marketplace - methods `offer_ship`, `offer_end`, and `offer_refund` are not implemented yet and return `None`. + methods `offer_end` and `offer_refund` are not implemented yet and return `None`. """ TOKEN_KEY = "PRICECHARTING_TOKEN" @@ -230,9 +231,35 @@ async def offer_feedback( 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.""" - pass + async def offer_ship( + self, offer_id: str, tracking_number: str | None = None + ) -> OfferShipResponse: + """Mark a sold marketplace offer as shipped. + + Args: + offer_id: The offer ID. Surrounding whitespace is stripped. + tracking_number: USPS, FedEx, UPS, or other tracking number. A valid one can earn + positive feedback if the buyer leaves none. + + Returns: + The shipped offer. + + 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 = {"offer-id": offer_id} + if tracking_number is not None: + data["tracking-number"] = tracking_number + + response = await self._client.post(Route.Marketplace.OFFER_SHIP, data=data) + return _parse(response, OfferShipResponse) async def offer_end(self): """End a marketplace offer.""" diff --git a/src/pypricecharting/pricecharting.py b/src/pypricecharting/pricecharting.py index 649098a..1e37b92 100644 --- a/src/pypricecharting/pricecharting.py +++ b/src/pypricecharting/pricecharting.py @@ -13,6 +13,7 @@ OfferDetailsResponse, OfferFeedbackResponse, OfferPublishResponse, + OfferShipResponse, OffersResponse, ProductResponse, ProductsResponse, @@ -26,7 +27,7 @@ class PriceCharting: """Synchronous PriceCharting API client. Reuse one client for all requests and close it when done (`with` or `close()`). The Marketplace - methods `offer_ship`, `offer_end`, and `offer_refund` are not implemented yet and return `None`. + methods `offer_end` and `offer_refund` are not implemented yet and return `None`. """ TOKEN_KEY = "PRICECHARTING_TOKEN" @@ -227,9 +228,33 @@ def offer_feedback( response = self._client.post(Route.Marketplace.OFFER_FEEDBACK, data=data) return _parse(response, OfferFeedbackResponse) - def offer_ship(self): - """Mark a marketplace offer as shipped.""" - pass + def offer_ship(self, offer_id: str, tracking_number: str | None = None) -> OfferShipResponse: + """Mark a sold marketplace offer as shipped. + + Args: + offer_id: The offer ID. Surrounding whitespace is stripped. + tracking_number: USPS, FedEx, UPS, or other tracking number. A valid one can earn + positive feedback if the buyer leaves none. + + Returns: + The shipped offer. + + 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 = {"offer-id": offer_id} + if tracking_number is not None: + data["tracking-number"] = tracking_number + + response = self._client.post(Route.Marketplace.OFFER_SHIP, data=data) + return _parse(response, OfferShipResponse) def offer_end(self): """End a marketplace offer.""" diff --git a/tests/test_asyncpricecharting_marketplace.py b/tests/test_asyncpricecharting_marketplace.py index 0310fb3..32d2748 100644 --- a/tests/test_asyncpricecharting_marketplace.py +++ b/tests/test_asyncpricecharting_marketplace.py @@ -10,6 +10,7 @@ OfferDetailsResponse, OfferFeedbackResponse, OfferPublishResponse, + OfferShipResponse, OffersResponse, ) from pypricecharting.types import Condition, Rating, Status @@ -18,6 +19,7 @@ OFFER_FEEDBACK_JSON, OFFER_PUBLISH_REQUEST_JSON, OFFER_PUBLISH_RESPONSE_JSON, + OFFER_SHIP_JSON, OFFERS_JSON, OFFERS_REQUEST_JSON, ) @@ -237,9 +239,58 @@ async def test_offer_feedback_raises_api_error(): async def test_offer_ship(): - client = AsyncPriceCharting(TOKEN) - assert await client.offer_ship() is None - await client.aclose() + requests: list[Request] = [] + + async with mocked_async_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client: + response = await client.offer_ship("vtdsww72uyslgooawzyyijsllm", "901234567890000") + + assert isinstance(response, OfferShipResponse) + assert response.status == Status.SUCCESS + assert response.offer_id == "vtdsww72uyslgooawzyyijsllm" + assert response.is_shipped is True + assert response.tracking_number == "901234567890000" + + assert len(requests) == 1 + assert requests[0].method == "POST" + assert requests[0].url.path == "/api/offer-ship" + assert "t" not in requests[0].url.params + assert dict(parse_qsl(requests[0].content.decode())) == { + "offer-id": "vtdsww72uyslgooawzyyijsllm", + "tracking-number": "901234567890000", + "t": TOKEN, + } + + +async def test_offer_ship_without_tracking_number(): + requests: list[Request] = [] + + async with mocked_async_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client: + await client.offer_ship(" testofferid ") + + assert dict(parse_qsl(requests[0].content.decode())) == { + "offer-id": "testofferid", + "t": TOKEN, + } + + +@pytest.mark.parametrize("offer_id", ["", " "]) +async def test_offer_ship_empty_offer_id_raises_parameter_error(offer_id: str): + requests: list[Request] = [] + + async with mocked_async_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client: + with pytest.raises(ParameterError, match="offer_id was empty"): + await client.offer_ship(offer_id) + + assert requests == [] + + +async def test_offer_ship_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_ship("missing") async def test_offer_end(): diff --git a/tests/test_pricecharting_marketplace.py b/tests/test_pricecharting_marketplace.py index 16201c6..7f84daf 100644 --- a/tests/test_pricecharting_marketplace.py +++ b/tests/test_pricecharting_marketplace.py @@ -10,6 +10,7 @@ OfferDetailsResponse, OfferFeedbackResponse, OfferPublishResponse, + OfferShipResponse, OffersResponse, ) from pypricecharting.types import Condition, Rating, Status @@ -18,6 +19,7 @@ OFFER_FEEDBACK_JSON, OFFER_PUBLISH_REQUEST_JSON, OFFER_PUBLISH_RESPONSE_JSON, + OFFER_SHIP_JSON, OFFERS_JSON, OFFERS_REQUEST_JSON, ) @@ -223,9 +225,60 @@ def test_offer_feedback_raises_api_error(): def test_offer_ship(): - client = PriceCharting(TOKEN) - assert client.offer_ship() is None - client.close() + requests: list[Request] = [] + + with mocked_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client: + response = client.offer_ship("vtdsww72uyslgooawzyyijsllm", "901234567890000") + + assert isinstance(response, OfferShipResponse) + assert response.status == Status.SUCCESS + assert response.offer_id == "vtdsww72uyslgooawzyyijsllm" + assert response.is_shipped is True + assert response.tracking_number == "901234567890000" + + assert len(requests) == 1 + assert requests[0].method == "POST" + assert requests[0].url.path == "/api/offer-ship" + assert "t" not in requests[0].url.params + assert dict(parse_qsl(requests[0].content.decode())) == { + "offer-id": "vtdsww72uyslgooawzyyijsllm", + "tracking-number": "901234567890000", + "t": TOKEN, + } + + +def test_offer_ship_without_tracking_number(): + requests: list[Request] = [] + + with mocked_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client: + client.offer_ship(" testofferid ") + + assert dict(parse_qsl(requests[0].content.decode())) == { + "offer-id": "testofferid", + "t": TOKEN, + } + + +@pytest.mark.parametrize("offer_id", ["", " "]) +def test_offer_ship_empty_offer_id_raises_parameter_error(offer_id: str): + requests: list[Request] = [] + + with ( + mocked_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client, + pytest.raises(ParameterError, match="offer_id was empty"), + ): + client.offer_ship(offer_id) + + assert requests == [] + + +def test_offer_ship_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_ship("missing") def test_offer_end():