woltapi 0.3.0__tar.gz → 0.4.1__tar.gz

{woltapi-0.3.0/src/woltapi.egg-info → woltapi-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: woltapi
-Version: 0.3.0
+Version: 0.4.1
 Summary: A small synchronous client for observed Wolt ordering flows.
 License-Expression: AGPL-3.0-only
 Project-URL: Repository, https://github.com/skorokithakis/woltapi
@@ -243,6 +243,7 @@ longer use this path; prefer `RefreshTokenCredentials`.
 | `client.get_venue_dynamic(slug, latitude, longitude)` | Current opening and delivery information. |
 | `client.get_orders_page()` | A dictionary containing the current page of order history. |
 | `client.list_delivery_targets()` | References to your saved delivery addresses, with saved labels and address details. |
+| `client.get_venue_checkout_context(slug)` | The `VenueCheckoutContext` for a restaurant, read from its static page. Needed for `create_selection` and `save_basket_items`. |
 | `client.get_order_status(purchase_id)` | An order's status and some price information. |
 | `derive_checkout_fields(assortment, item)` | The checkout metadata fields for one menu item, derived from the assortment. Raises an error for items in zero or multiple categories. |
 
@@ -301,12 +302,65 @@ baskets you see in the Wolt app. The library can read and replace them:
 
 | Call | What it does |
 | --- | --- |
-| `client.save_basket(selection)` | Replaces the server basket for that restaurant with your selection. This does not place an order. |
+| `client.save_basket_items(assortment, venue=..., items=...)` | Replaces the whole server basket for that restaurant. Needs only the menu, a venue context, and items. This does not place an order. |
+| `client.save_basket(selection)` | Also replaces the whole server basket, but takes a full `OrderSelection`. |
 | `client.get_basket_count()` | The number of baskets stored on the server. |
-| `client.get_venue_basket(venue_id)` | The server basket for one restaurant, or `None` if there is none. |
 | `client.get_baskets_page(latitude, longitude)` | The full baskets page as a dictionary. It can contain personal data; do not log it raw. |
+| `client.get_venue_checkout_context(slug)` | The `VenueCheckoutContext` for a restaurant, read from its static page. |
 
-Deleting a server basket is not supported.
+There are two ways to save. `save_basket_items()` needs no saved address and no
+card, because a basket costs nothing. Use it when you only want to change a
+basket. `save_basket()` takes an `OrderSelection`, which you can only build
+after `list_delivery_targets()` and `get_payment_methods()` on the same client,
+so it needs a saved delivery address and an enabled card. That cost is worth
+paying only when you go on to request a checkout quote with the same selection.
+
+Deleting a server basket is not supported. There is also no call that adds or
+removes a single item: every save replaces the whole basket.
+
+#### Change a saved basket
+
+Editing means four steps: read the saved basket, rebuild it locally, apply
+your change, and save the result.
+
+Read with `get_baskets_page()`. It returns each basket with its restaurant's
+slug and the selected options, which is what a rebuild needs.
+
+```python
+page = client.get_baskets_page(60.17, 24.94)
+saved = next(
+    entry for entry in page["baskets"]
+    if entry["venue"]["slug"] == "<restaurant slug>"
+)
+
+menu = client.get_assortment("<restaurant slug>")
+basket = Basket.from_saved_basket(menu, saved, "en")
+
+basket.set_count("<item id>", 3)
+
+client.save_basket_items(
+    menu,
+    venue=client.get_venue_checkout_context("<restaurant slug>"),
+    items=basket.item_selections(),
+)
+```
+
+`Basket.from_saved_basket()` handles the response quirks for you. A saved item
+lists every option configuration it has, including ones you did not choose
+from; those come back with an empty `values` list and are skipped. Option
+values read back from the server carry no price; this does not matter, because
+`Basket` recomputes every price from the menu you pass in. Substitution
+settings are restored as saved.
+
+Three caveats:
+
+- The rebuild raises `SelectionError` naming the item ID when a saved item is
+  no longer on the restaurant's menu. Remove that item from the saved data or
+  start a fresh `Basket`.
+- The rebuild raises `ResponseShapeError` when a saved basket entry does not
+  match the shape the server has been observed to return.
+- A save sends only the restaurant, the currency, and the items. A customer
+  comment attached to the basket in the Wolt app may not survive a save.
 
 ## Can it order food?
 

{woltapi-0.3.0 → woltapi-0.4.1}/README.md

@@ -225,6 +225,7 @@ longer use this path; prefer `RefreshTokenCredentials`.
 | `client.get_venue_dynamic(slug, latitude, longitude)` | Current opening and delivery information. |
 | `client.get_orders_page()` | A dictionary containing the current page of order history. |
 | `client.list_delivery_targets()` | References to your saved delivery addresses, with saved labels and address details. |
+| `client.get_venue_checkout_context(slug)` | The `VenueCheckoutContext` for a restaurant, read from its static page. Needed for `create_selection` and `save_basket_items`. |
 | `client.get_order_status(purchase_id)` | An order's status and some price information. |
 | `derive_checkout_fields(assortment, item)` | The checkout metadata fields for one menu item, derived from the assortment. Raises an error for items in zero or multiple categories. |
 
@@ -283,12 +284,65 @@ baskets you see in the Wolt app. The library can read and replace them:
 
 | Call | What it does |
 | --- | --- |
-| `client.save_basket(selection)` | Replaces the server basket for that restaurant with your selection. This does not place an order. |
+| `client.save_basket_items(assortment, venue=..., items=...)` | Replaces the whole server basket for that restaurant. Needs only the menu, a venue context, and items. This does not place an order. |
+| `client.save_basket(selection)` | Also replaces the whole server basket, but takes a full `OrderSelection`. |
 | `client.get_basket_count()` | The number of baskets stored on the server. |
-| `client.get_venue_basket(venue_id)` | The server basket for one restaurant, or `None` if there is none. |
 | `client.get_baskets_page(latitude, longitude)` | The full baskets page as a dictionary. It can contain personal data; do not log it raw. |
+| `client.get_venue_checkout_context(slug)` | The `VenueCheckoutContext` for a restaurant, read from its static page. |
 
-Deleting a server basket is not supported.
+There are two ways to save. `save_basket_items()` needs no saved address and no
+card, because a basket costs nothing. Use it when you only want to change a
+basket. `save_basket()` takes an `OrderSelection`, which you can only build
+after `list_delivery_targets()` and `get_payment_methods()` on the same client,
+so it needs a saved delivery address and an enabled card. That cost is worth
+paying only when you go on to request a checkout quote with the same selection.
+
+Deleting a server basket is not supported. There is also no call that adds or
+removes a single item: every save replaces the whole basket.
+
+#### Change a saved basket
+
+Editing means four steps: read the saved basket, rebuild it locally, apply
+your change, and save the result.
+
+Read with `get_baskets_page()`. It returns each basket with its restaurant's
+slug and the selected options, which is what a rebuild needs.
+
+```python
+page = client.get_baskets_page(60.17, 24.94)
+saved = next(
+    entry for entry in page["baskets"]
+    if entry["venue"]["slug"] == "<restaurant slug>"
+)
+
+menu = client.get_assortment("<restaurant slug>")
+basket = Basket.from_saved_basket(menu, saved, "en")
+
+basket.set_count("<item id>", 3)
+
+client.save_basket_items(
+    menu,
+    venue=client.get_venue_checkout_context("<restaurant slug>"),
+    items=basket.item_selections(),
+)
+```
+
+`Basket.from_saved_basket()` handles the response quirks for you. A saved item
+lists every option configuration it has, including ones you did not choose
+from; those come back with an empty `values` list and are skipped. Option
+values read back from the server carry no price; this does not matter, because
+`Basket` recomputes every price from the menu you pass in. Substitution
+settings are restored as saved.
+
+Three caveats:
+
+- The rebuild raises `SelectionError` naming the item ID when a saved item is
+  no longer on the restaurant's menu. Remove that item from the saved data or
+  start a fresh `Basket`.
+- The rebuild raises `ResponseShapeError` when a saved basket entry does not
+  match the shape the server has been observed to return.
+- A save sends only the restaurant, the currency, and the items. A customer
+  comment attached to the basket in the Wolt app may not survive a save.
 
 ## Can it order food?
 

{woltapi-0.3.0 → woltapi-0.4.1}/examples/order.py

@@ -2,7 +2,6 @@
 """Interactively test checkout quotes. Never submits a purchase or charges a card."""
 
 import argparse
-import json
 import math
 from pathlib import Path
 
@@ -14,7 +13,6 @@ from woltapi import (
     HTTPStatusError,
     OptionSelection,
     OptionValueSelection,
-    VenueCheckoutContext,
     WoltApiError,
     WoltClient,
 )
@@ -74,25 +72,6 @@ def card_description(card):
     )
 
 
-def fields(source, supplied, names, section):
-    if not isinstance(source, dict) or not isinstance(supplied, dict):
-        raise CheckoutInputError(f"Expected an object for {section}.")
-    missing = [name for name in names if name not in source and name not in supplied]
-    if missing:
-        raise CheckoutInputError(
-            f"Missing {section}: {', '.join(missing)}. "
-            "Supply current browser values using --context-file; no defaults were invented."
-        )
-    if any(
-        name in source and name in supplied and source[name] != supplied[name]
-        for name in names
-    ):
-        raise CheckoutInputError(
-            f"The {section} context conflicts with current server data."
-        )
-    return {name: source[name] if name in source else supplied[name] for name in names}
-
-
 def select_options(item, assortment, language):
     configurations = item.get("options")
     roots = assortment.get("options")
@@ -152,27 +131,19 @@ def select_options(item, assortment, language):
     return selected, descriptions
 
 
-def checkout(client, args, context):
+def checkout(client, args):
     found = client.search_venues(args.query, args.latitude, args.longitude)
     venue = choose("restaurant", found, lambda v: text(v.title or v.slug))
-    static = client.get_venue_static(venue.slug).get("venue")
-    if not isinstance(static, dict) or static.get("id") != venue.id:
+    venue_context = client.get_venue_checkout_context(venue.slug)
+    if venue_context.id != venue.id:
         raise CheckoutInputError(
             "Static venue response does not match the selected restaurant."
         )
-    if context and context.get("venue_id") != venue.id:
-        raise CheckoutInputError("Context venue_id must match the selected restaurant.")
-    venue_fields = fields(
-        static,
-        context.get("venue", {}),
-        ("country", "currency", "self_delivery"),
-        "venue",
-    )
-    if venue.currency is not None and venue_fields["currency"] != venue.currency:
+    if venue.currency is not None and venue_context.currency != venue.currency:
         raise CheckoutInputError(
             "Venue currency changed; start again with current data."
         )
-    currency = venue_fields["currency"]
+    currency = venue_context.currency
     assortment = client.get_assortment(venue.slug)
     catalog_items = assortment.get("items")
     if not isinstance(catalog_items, list) or not all(
@@ -218,7 +189,7 @@ def checkout(client, args, context):
         return
     card_context = {
         "venue_id": venue.id,
-        "country": venue_fields["country"],
+        "country": venue_context.country,
         "delivery_method": "homedelivery",
         "available_methods": ["card"],
         "items": [
@@ -237,7 +208,7 @@ def checkout(client, args, context):
     )
     selection = client.create_selection(
         assortment,
-        venue=VenueCheckoutContext(id=venue.id, preorder_config=None, **venue_fields),
+        venue=venue_context,
         delivery=DeliverySelection(delivery.id, args.latitude, args.longitude),
         payment_method={"id": card.id, "type": card.type},
         courier_tip=tip,
@@ -317,11 +288,6 @@ def main():
     parser.add_argument("--token-file", type=Path, required=True)
     parser.add_argument("--query", default="pizza")
     parser.add_argument("--language", default="en")
-    parser.add_argument(
-        "--context-file",
-        type=Path,
-        help="Optional current browser metadata for venue fields missing from static data",
-    )
     parser.add_argument(
         "--save-basket",
         action="store_true",
@@ -337,11 +303,8 @@ def main():
         parser.error("Provide valid latitude and longitude.")
     check_token_file(parser, args.token_file)
     try:
-        context = json.loads(args.context_file.read_text()) if args.context_file else {}
-        if not isinstance(context, dict):
-            raise CheckoutInputError("The context file must contain a JSON object.")
         client = WoltClient(refresh_credentials(args.language, args.token_file))
-        checkout(client, args, context)
+        checkout(client, args)
     except CheckoutInputError as exc:
         print(f"Checkout stopped: {exc}")
         return 1

woltapi-0.4.1/examples/verify_saved_basket_rebuild.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Verify saved baskets can be rebuilt from their current assortments.
+
+Read-only: this script only reads saved baskets and assortments. Its output is
+restricted to venue slugs, item counts, and integer cent totals.
+"""
+
+import argparse
+import math
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from browse import TokenFileError, check_token_file, refresh_credentials
+
+from woltapi import Basket, WoltApiError, WoltClient
+
+
+class VerificationInputError(ValueError):
+    """A local saved-basket shape problem safe to report to the owner."""
+
+
+def venue_slug(saved_basket):
+    """Return the saved basket's public venue slug without exposing other fields."""
+    if not isinstance(saved_basket, Mapping):
+        raise VerificationInputError("Saved basket is not an object.")
+    venue = saved_basket.get("venue")
+    if not isinstance(venue, Mapping):
+        raise VerificationInputError("Saved basket venue is not an object.")
+    slug = venue.get("slug")
+    if not isinstance(slug, str) or re.fullmatch(r"[a-z0-9][a-z0-9-]*", slug) is None:
+        raise VerificationInputError("Saved basket venue has no usable slug.")
+    return slug
+
+
+def failure_line(slug, error):
+    """Format only local static error messages, never response-derived data."""
+    if isinstance(error, VerificationInputError):
+        message = str(error)
+    else:
+        message = "Details omitted."
+    return f"FAIL venue={slug}: {type(error).__name__}: {message}"
+
+
+def verify_baskets(client, args):
+    """Read, rebuild, and report each saved basket; return whether all passed."""
+    try:
+        page = client.get_baskets_page(args.latitude, args.longitude)
+        baskets = page.get("baskets") if isinstance(page, Mapping) else None
+        if not isinstance(baskets, list):
+            raise VerificationInputError("Saved baskets page has no baskets list.")
+    except (VerificationInputError, WoltApiError, TypeError, ValueError) as exc:
+        print(failure_line("unknown", exc))
+        return False
+
+    if not baskets:
+        # Keep the zero-basket note in the same privacy-safe output format.
+        print("PASS venue=no-saved-baskets items=0 total=0")
+        return True
+
+    passed = True
+    for saved_basket in baskets:
+        slug = "unknown"
+        try:
+            slug = venue_slug(saved_basket)
+            assortment = client.get_assortment(slug)
+            basket = Basket.from_saved_basket(assortment, saved_basket, args.language)
+            selections = basket.item_selections()
+            item_count = sum(selection.count for selection in selections)
+            total = sum(selection.basket_price for selection in selections)
+            print(f"PASS venue={slug} items={item_count} total={total}")
+        except (VerificationInputError, WoltApiError, TypeError, ValueError) as exc:
+            print(failure_line(slug, exc))
+            passed = False
+    return passed
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--latitude", type=float, required=True)
+    parser.add_argument("--longitude", type=float, required=True)
+    parser.add_argument("--token-file", type=Path, required=True)
+    parser.add_argument("--language", default="en")
+    args = parser.parse_args()
+    if not (
+        math.isfinite(args.latitude)
+        and -90 <= args.latitude <= 90
+        and math.isfinite(args.longitude)
+        and -180 <= args.longitude <= 180
+    ):
+        parser.error("Provide finite latitude [-90, 90] and longitude [-180, 180].")
+    check_token_file(parser, args.token_file)
+    try:
+        client = WoltClient(refresh_credentials(args.language, args.token_file))
+        return 0 if verify_baskets(client, args) else 1
+    except TokenFileError:
+        print("FAIL venue=unknown: TokenFileError: Could not save the refresh token.")
+        return 1
+    except (EOFError, KeyboardInterrupt) as exc:
+        print(f"FAIL venue=unknown: {type(exc).__name__}: Cancelled.")
+        return 1
+    except (OSError, UnicodeError, ValueError, WoltApiError) as exc:
+        print(failure_line("unknown", exc))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{woltapi-0.3.0 → woltapi-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "woltapi"
-version = "0.3.0"
+version = "0.4.1"
 description = "A small synchronous client for observed Wolt ordering flows."
 readme = "README.md"
 requires-python = ">=3.10"

{woltapi-0.3.0 → woltapi-0.4.1}/src/woltapi/basket.py

@@ -8,7 +8,7 @@ from collections.abc import Mapping, Sequence
 from types import MappingProxyType
 from typing import Any
 
-from .errors import SelectionError
+from .errors import ResponseShapeError, SelectionError
 from .selection import (
     ItemSelection,
     OptionSelection,
@@ -66,6 +66,30 @@ class Basket:
         self._default_substitution_allowed = substitution_allowed
         self._items: dict[str, _BasketItem] = {}
 
+    @classmethod
+    def from_saved_basket(
+        cls,
+        assortment: Mapping[str, Any],
+        saved_basket: Mapping[str, Any],
+        language: str,
+    ) -> Basket:
+        """Rebuild a local basket from one saved consumer-basket entry."""
+
+        saved_items = _saved_basket_items(saved_basket)
+        basket = cls(assortment, language)
+        for item_id, count, options, substitution_allowed in saved_items:
+            if item_id not in basket._catalog_items:
+                raise SelectionError(
+                    f"Saved basket item {item_id!r} is absent from the assortment."
+                )
+            basket.add_item(
+                item_id,
+                count,
+                options,
+                substitution_allowed=substitution_allowed,
+            )
+        return basket
+
     @property
     def contents(self) -> Mapping[str, ItemSelection]:
         """Return a detached, read-only view of the current basket contents."""
@@ -241,6 +265,10 @@ def _index_by_id(value: Any) -> dict[str, Mapping[str, Any]]:
 
 
 def _translated_name(value: Any, language: str) -> str:
+    # Catalog/read endpoints return strings; only restaurant-api purchase payloads
+    # (/v2/purchases, /v1/post-checkout-config) use list-of-{lang, value} names.
+    if _is_nonempty_text(value):
+        return value
     if not _is_array(value):
         raise SelectionError("The selected item is missing translated names.")
     for translation in value:
@@ -250,7 +278,12 @@ def _translated_name(value: Any, language: str) -> str:
         name = translation.get("value")
         if translation_language == language and _is_nonempty_text(name):
             return name
-    raise SelectionError("The selected item has no name for the basket language.")
+    for translation in value:
+        if isinstance(translation, Mapping) and _is_nonempty_text(
+            name := translation.get("value")
+        ):
+            return name
+    raise SelectionError("The selected item has no usable name.")
 
 
 def _required_fields(
@@ -267,6 +300,94 @@ def _copy_options(value: Any) -> tuple[OptionSelection, ...]:
     return tuple(deepcopy(value))
 
 
+def _saved_basket_items(
+    value: Any,
+) -> tuple[tuple[str, int, tuple[OptionSelection, ...], bool], ...]:
+    if not isinstance(value, Mapping):
+        _saved_basket_shape_error()
+    _validate_saved_venue(value.get("venue"))
+    saved_items = value.get("items")
+    if not _is_array(saved_items):
+        _saved_basket_shape_error()
+
+    items = []
+    for saved_item in saved_items:
+        if not isinstance(saved_item, Mapping):
+            _saved_basket_shape_error()
+        item_id = _saved_nonempty_text(saved_item, "id")
+        _saved_nonempty_text(saved_item, "name")
+        if "price" not in saved_item:
+            _saved_basket_shape_error()
+        count = saved_item.get("count")
+        if not _is_integer(count) or count <= 0:
+            _saved_basket_shape_error()
+        substitution_allowed = _saved_substitution_allowed(
+            saved_item.get("substitution_settings")
+        )
+        if "options" not in saved_item:
+            _saved_basket_shape_error()
+        options = _saved_item_options(saved_item["options"])
+        items.append((item_id, count, options, substitution_allowed))
+    return tuple(items)
+
+
+def _validate_saved_venue(value: Any) -> None:
+    if not isinstance(value, Mapping):
+        _saved_basket_shape_error()
+    for field_name in ("id", "name", "slug", "country"):
+        _saved_nonempty_text(value, field_name)
+    if not isinstance(value.get("available"), bool):
+        _saved_basket_shape_error()
+
+
+def _saved_substitution_allowed(value: Any) -> bool:
+    if not isinstance(value, Mapping):
+        _saved_basket_shape_error()
+    is_allowed = value.get("is_allowed")
+    if not isinstance(is_allowed, bool):
+        _saved_basket_shape_error()
+    return is_allowed
+
+
+def _saved_item_options(value: Any) -> tuple[OptionSelection, ...]:
+    if value is None:
+        return ()
+    if not _is_array(value):
+        _saved_basket_shape_error()
+
+    options = []
+    for option in value:
+        if not isinstance(option, Mapping):
+            _saved_basket_shape_error()
+        configuration_id = _saved_nonempty_text(option, "id")
+        saved_values = option.get("values")
+        if not _is_array(saved_values):
+            _saved_basket_shape_error()
+        values = []
+        for saved_value in saved_values:
+            if not isinstance(saved_value, Mapping):
+                _saved_basket_shape_error()
+            value_id = _saved_nonempty_text(saved_value, "id")
+            count = saved_value.get("count")
+            if not _is_integer(count) or count <= 0:
+                _saved_basket_shape_error()
+            values.append(OptionValueSelection(value_id, count))
+        if values:
+            options.append(OptionSelection(configuration_id, values))
+    return tuple(options)
+
+
+def _saved_nonempty_text(value: Mapping[str, Any], field_name: str) -> str:
+    field_value = value.get(field_name)
+    if not _is_nonempty_text(field_value):
+        _saved_basket_shape_error()
+    return field_value
+
+
+def _saved_basket_shape_error() -> None:
+    raise ResponseShapeError("consumer")
+
+
 def _item_id(value: Any) -> str:
     if not _is_nonempty_text(value):
         raise SelectionError("An item ID is required.")

{woltapi-0.3.0 → woltapi-0.4.1}/src/woltapi/client.py

@@ -10,7 +10,7 @@ from typing import Any
 from urllib.parse import quote
 
 from .credentials import SessionCredentials
-from .errors import HTTPStatusError, ResponseShapeError, SelectionError
+from .errors import ResponseShapeError, SelectionError
 from .models import DeliveryTarget, OrderStatus, PaymentMethod, Venue
 from .purchase import (
     PurchaseAttemptStore,
@@ -29,6 +29,7 @@ from .selection import (
     QuoteSnapshot,
     SavedBasket,
     VenueCheckoutContext,
+    _build_basket_payload,
 )
 from .services import ServiceHost
 from .transport import DEFAULT_TIMEOUT_SECONDS, WoltTransport
@@ -131,22 +132,6 @@ class WoltClient:
             raise ResponseShapeError(ServiceHost.CONSUMER.value)
         return count
 
-    def get_venue_basket(self, venue_id: str) -> dict[str, Any] | None:
-        """Read a venue's server basket, returning ``None`` when it is absent."""
-
-        venue_id = _required_text(venue_id, "venue_id")
-        try:
-            return self._transport.request(
-                ServiceHost.CONSUMER,
-                "GET",
-                "/order-xp/v1/baskets/venue",
-                query={"venue_id": venue_id},
-            )
-        except HTTPStatusError as error:
-            if error.status_code == 404:
-                return None
-            raise
-
     def get_baskets_page(
         self, latitude: int | float, longitude: int | float
     ) -> dict[str, Any]:
@@ -174,6 +159,32 @@ class WoltClient:
             f"/order-xp/web/v1/pages/venue/slug/{slug}/static",
         )
 
+    def get_venue_checkout_context(self, venue_slug: str) -> VenueCheckoutContext:
+        """Read the checkout fields supplied by a venue's static page."""
+
+        response = self.get_venue_static(venue_slug)
+        venue = response.get("venue")
+        if not isinstance(venue, Mapping):
+            raise ResponseShapeError(ServiceHost.CONSUMER.value)
+        venue_id = venue.get("id")
+        country = venue.get("country")
+        currency = venue.get("currency")
+        self_delivery = venue.get("self_delivery")
+        if (
+            not _is_nonempty_string(venue_id)
+            or not _is_nonempty_string(country)
+            or not _is_nonempty_string(currency)
+            or not isinstance(self_delivery, bool)
+        ):
+            raise ResponseShapeError(ServiceHost.CONSUMER.value)
+        return VenueCheckoutContext(
+            id=venue_id,
+            country=country,
+            currency=currency,
+            self_delivery=self_delivery,
+            preorder_config=None,
+        )
+
     def get_venue_dynamic(
         self,
         venue_slug: str,
@@ -394,6 +405,27 @@ class WoltClient:
             raise ResponseShapeError(ServiceHost.CONSUMER.value)
         return SavedBasket(id=basket_id, venue_id=venue_id)
 
+    def save_basket_items(
+        self,
+        assortment: Mapping[str, Any],
+        *,
+        venue: VenueCheckoutContext,
+        items: Sequence[ItemSelection],
+    ) -> SavedBasket:
+        """Explicitly upsert a per-venue basket without delivery or payment data."""
+
+        response = self._transport.request(
+            ServiceHost.CONSUMER,
+            "POST",
+            "/order-xp/v1/baskets",
+            json_body=_build_basket_payload(assortment, venue=venue, items=items),
+        )
+        basket_id = response.get("id")
+        venue_id = response.get("venue_id")
+        if not _is_nonempty_string(basket_id) or not _is_nonempty_string(venue_id):
+            raise ResponseShapeError(ServiceHost.CONSUMER.value)
+        return SavedBasket(id=basket_id, venue_id=venue_id)
+
     def quote_checkout(self, selection: OrderSelection) -> QuoteSnapshot:
         """Request one checkout quote and capture independent plan/response snapshots."""
 

{woltapi-0.3.0 → woltapi-0.4.1}/src/woltapi/purchase.py

@@ -937,6 +937,7 @@ def _purchase_option_summary(option: Mapping[str, Any]) -> PurchaseOptionSummary
 
 
 def _purchase_name_summaries(names: Any, label: str) -> tuple[PurchaseNameSummary, ...]:
+    # This list shape is correct for /v2/purchases; do not accept strings (verified by capture).
     if not _is_array(names) or not names:
         raise PurchasePreparationError(f"{label} are incomplete.")
     summaries: list[PurchaseNameSummary] = []