woltapi 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: woltapi
-Version: 0.3.0
+Version: 0.4.0
 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.0}/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.0}/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.3.0 → woltapi-0.4.0}/pyproject.toml

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

{woltapi-0.3.0 → woltapi-0.4.0}/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."""
@@ -267,6 +291,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.0}/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.0}/src/woltapi/selection.py

@@ -354,6 +354,38 @@ class OrderSelection:
         return self._identity
 
 
+def _build_basket_payload(
+    assortment: Mapping[str, Any],
+    *,
+    venue: VenueCheckoutContext,
+    items: Sequence[ItemSelection],
+) -> dict[str, Any]:
+    """Build a basket payload without requiring delivery or payment data."""
+
+    if not isinstance(assortment, Mapping):
+        raise SelectionError("A selection requires an assortment mapping.")
+    if not isinstance(venue, VenueCheckoutContext):
+        raise TypeError("venue must be a VenueCheckoutContext instance.")
+    if not _is_array(items) or not items:
+        raise SelectionError("A selection requires at least one item.")
+
+    catalog_items = _index_by_id(assortment.get("items"))
+    root_options = _index_by_id(assortment.get("options"))
+    normalized_items = [
+        _normalize_item(item, catalog_items, root_options) for item in items
+    ]
+    item_ids = [item["id"] for item in normalized_items]
+    if len(item_ids) != len(set(item_ids)):
+        raise SelectionError("A selection cannot contain duplicate item IDs.")
+
+    normalized_venue = _normalize_venue(venue)
+    return {
+        "venue_id": normalized_venue["id"],
+        "currency": normalized_venue["currency"],
+        "items": [_serialize_basket_item(item) for item in normalized_items],
+    }
+
+
 _CHECKOUT_REQUIRED_FIELDS = {
     "category_id",
     "category_ids",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: woltapi
-Version: 0.3.0
+Version: 0.4.0
 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?