woltapi 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: woltapi
-Version: 0.2.0
+Version: 0.3.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
@@ -261,6 +261,53 @@ Responses can contain personal information. Avoid printing entire responses or
 sending them to shared logs. The examples print saved addresses and card labels
 to the local terminal only. The browsing example prints only selected fields.
 
+### Baskets
+
+A basket is your list of chosen items at one restaurant. The `Basket` class
+builds that list locally, with no network requests. It reads names, option
+prices, and totals from the restaurant's menu, so you do not type any prices:
+
+```python
+from woltapi import Basket, OptionSelection, OptionValueSelection
+
+menu = client.get_assortment(restaurant.slug)
+basket = Basket(menu, "en")
+
+basket.add_item("<item id>", count=2)
+basket.add_item(
+    "<other item id>",
+    options=[
+        OptionSelection(
+            "<item option configuration id>", [OptionValueSelection("<value id>", 1)]
+        ),
+    ],
+)
+basket.set_count("<item id>", 1)
+basket.set_options("<item id>", [])
+basket.remove_item("<other item id>")
+
+items = basket.item_selections()
+```
+
+Item, option, and value IDs come from the assortment dictionary. For
+`OptionSelection`, use the configuration ID from the catalog item's own
+`options` list, not the root option ID from the assortment's top-level
+`options`. Pass the result of `item_selections()` to
+`client.create_selection(...)`, which validates the whole selection against the
+current menu.
+
+Wolt also stores one basket per restaurant on its servers. These are the
+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.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. |
+
+Deleting a server basket is not supported.
+
 ## Can it order food?
 
 Not as a simple, ready-to-use feature yet. There is no `order("pizza")` method.
@@ -274,23 +321,22 @@ python examples/order.py --latitude 60.17 --longitude 24.94 --query pizza \
 ```
 
 Use your own coordinates. It reads and saves your refresh token as described in
-[Get a token](#get-a-token), guides you through selecting an item and a saved
-delivery target/card, then asks before requesting a price. It never submits a
-purchase. Basket saving is off by default and needs a separate confirmation if
-enabled.
-
-The checkout example derives `category_id`, `category_ids`, and the three
-checkout exclusion flags from the assortment, so those fields do not need a
-browser context file. It only supports items in exactly one category and stops
-rather than guessing for zero or multiple categories. If it stops, you can
-supply the missing values yourself with `--context-file <path>`, a JSON object
-whose `checkout_fields` entries were copied from your own browser's checkout
-request for the same item. It may still stop if other required catalog data is
-missing. Run `python examples/order.py --help` for available options.
-
-The library has methods to choose items, save a basket, ask Wolt for a price,
-and submit a purchase. But some required inputs still need to come from your
-own code, including browser/device information and detailed item data.
+[Get a token](#get-a-token), guides you through selecting one or more items with
+their options and a saved delivery target/card, then asks before requesting a
+price. Line totals come from the menu through the local basket builder; you do
+not type any amounts. It never submits a purchase. Basket saving is off by
+default and needs a separate confirmation if enabled.
+
+The basket builder derives `category_id`, `category_ids`, and the three checkout
+exclusion flags from the assortment. It only supports items in exactly one
+category and stops rather than guessing for zero or multiple categories. It may
+also stop if required catalog data is missing. Run
+`python examples/order.py --help` for available options.
+
+The library has methods to build and manage a basket, save it, ask Wolt for a
+price, and submit a purchase. But some purchase inputs still need to come from
+your own code, including browser/device information and a few purchase-only
+item fields.
 
 Order-history and saved-address reads have worked in live checks. **Payment and
 purchase handling have not been verified with a real order.** The purchase code

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

@@ -243,6 +243,53 @@ Responses can contain personal information. Avoid printing entire responses or
 sending them to shared logs. The examples print saved addresses and card labels
 to the local terminal only. The browsing example prints only selected fields.
 
+### Baskets
+
+A basket is your list of chosen items at one restaurant. The `Basket` class
+builds that list locally, with no network requests. It reads names, option
+prices, and totals from the restaurant's menu, so you do not type any prices:
+
+```python
+from woltapi import Basket, OptionSelection, OptionValueSelection
+
+menu = client.get_assortment(restaurant.slug)
+basket = Basket(menu, "en")
+
+basket.add_item("<item id>", count=2)
+basket.add_item(
+    "<other item id>",
+    options=[
+        OptionSelection(
+            "<item option configuration id>", [OptionValueSelection("<value id>", 1)]
+        ),
+    ],
+)
+basket.set_count("<item id>", 1)
+basket.set_options("<item id>", [])
+basket.remove_item("<other item id>")
+
+items = basket.item_selections()
+```
+
+Item, option, and value IDs come from the assortment dictionary. For
+`OptionSelection`, use the configuration ID from the catalog item's own
+`options` list, not the root option ID from the assortment's top-level
+`options`. Pass the result of `item_selections()` to
+`client.create_selection(...)`, which validates the whole selection against the
+current menu.
+
+Wolt also stores one basket per restaurant on its servers. These are the
+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.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. |
+
+Deleting a server basket is not supported.
+
 ## Can it order food?
 
 Not as a simple, ready-to-use feature yet. There is no `order("pizza")` method.
@@ -256,23 +303,22 @@ python examples/order.py --latitude 60.17 --longitude 24.94 --query pizza \
 ```
 
 Use your own coordinates. It reads and saves your refresh token as described in
-[Get a token](#get-a-token), guides you through selecting an item and a saved
-delivery target/card, then asks before requesting a price. It never submits a
-purchase. Basket saving is off by default and needs a separate confirmation if
-enabled.
-
-The checkout example derives `category_id`, `category_ids`, and the three
-checkout exclusion flags from the assortment, so those fields do not need a
-browser context file. It only supports items in exactly one category and stops
-rather than guessing for zero or multiple categories. If it stops, you can
-supply the missing values yourself with `--context-file <path>`, a JSON object
-whose `checkout_fields` entries were copied from your own browser's checkout
-request for the same item. It may still stop if other required catalog data is
-missing. Run `python examples/order.py --help` for available options.
-
-The library has methods to choose items, save a basket, ask Wolt for a price,
-and submit a purchase. But some required inputs still need to come from your
-own code, including browser/device information and detailed item data.
+[Get a token](#get-a-token), guides you through selecting one or more items with
+their options and a saved delivery target/card, then asks before requesting a
+price. Line totals come from the menu through the local basket builder; you do
+not type any amounts. It never submits a purchase. Basket saving is off by
+default and needs a separate confirmation if enabled.
+
+The basket builder derives `category_id`, `category_ids`, and the three checkout
+exclusion flags from the assortment. It only supports items in exactly one
+category and stops rather than guessing for zero or multiple categories. It may
+also stop if required catalog data is missing. Run
+`python examples/order.py --help` for available options.
+
+The library has methods to build and manage a basket, save it, ask Wolt for a
+price, and submit a purchase. But some purchase inputs still need to come from
+your own code, including browser/device information and a few purchase-only
+item fields.
 
 Order-history and saved-address reads have worked in live checks. **Payment and
 purchase handling have not been verified with a real order.** The purchase code

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

@@ -9,15 +9,14 @@ from pathlib import Path
 from browse import TokenFileError, check_token_file, refresh_credentials, text
 
 from woltapi import (
+    Basket,
     DeliverySelection,
     HTTPStatusError,
-    ItemSelection,
     OptionSelection,
     OptionValueSelection,
     VenueCheckoutContext,
     WoltApiError,
     WoltClient,
-    derive_checkout_fields,
 )
 
 
@@ -101,7 +100,6 @@ def select_options(item, assortment, language):
         raise CheckoutInputError("Missing catalog option lists.")
     selected = []
     descriptions = []
-    option_amount = 0
     for config in configurations:
         if not isinstance(config, dict) or config.get("prerequisite_values") != []:
             raise CheckoutInputError(
@@ -145,19 +143,13 @@ def select_options(item, assortment, language):
                 f"Count for {name} (0 to {single}): ", 0, single, empty_value=0
             )
             if count:
-                price = value.get("price")
-                if type(price) is not int:
-                    raise CheckoutInputError(
-                        "Missing or invalid catalog option value price."
-                    )
                 selections.append(OptionValueSelection(value["id"], count))
                 descriptions.append(f"{count} x {name}")
-                option_amount += price * count
         if not low <= sum(v.count for v in selections) <= high:
             raise CheckoutInputError("Selected options do not meet the catalog limits.")
         if selections:
             selected.append(OptionSelection(config["id"], selections))
-    return selected, descriptions, option_amount
+    return selected, descriptions
 
 
 def checkout(client, args, context):
@@ -168,6 +160,8 @@ def checkout(client, args, context):
         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", {}),
@@ -185,60 +179,32 @@ def checkout(client, args, context):
         isinstance(i, dict) for i in catalog_items
     ):
         raise CheckoutInputError("Missing assortment items.")
-    item = choose(
-        "menu item",
-        catalog_items,
-        lambda i: f"{text(i.get('name'), args.language)} | {money(i.get('price'), currency)}",
-    )
-    if context and (
-        context.get("venue_id") != venue.id or context.get("item_id") != item.get("id")
-    ):
-        raise CheckoutInputError(
-            "Context venue_id and item_id must match the selected restaurant and item."
+    basket = Basket(assortment, args.language)
+    selected_items = []
+    while True:
+        item = choose(
+            "menu item",
+            catalog_items,
+            lambda i: f"{text(i.get('name'), args.language)} | {money(i.get('price'), currency)}",
         )
-    if item.get("restrictions") != []:
-        raise CheckoutInputError("Restricted items are unsupported.")
-    methods = item.get("allowed_delivery_methods")
-    if not isinstance(methods, list) or "homedelivery" not in methods:
-        raise CheckoutInputError("This item does not explicitly support home delivery.")
-    item_price = item.get("price")
-    if type(item_price) is not int:
-        raise CheckoutInputError("Missing or invalid catalog item price.")
-    count = number("Item quantity: ", 1)
-    options, option_names, option_amount = select_options(
-        item, assortment, args.language
-    )
-    checkout_fields = fields(
-        derive_checkout_fields(assortment, item),
-        context.get("checkout_fields", {}),
-        (
-            "category_id",
-            "category_ids",
-            "exclude_from_credits",
-            "exclude_from_discounts",
-            "exclude_from_discounts_min_basket",
-            "alcohol_permille",
-            "restrictions",
-        ),
-        "checkout_fields",
-    )
-    if checkout_fields["alcohol_permille"] != 0:
-        raise CheckoutInputError("Age-restricted items are unsupported.")
-    payment_fields = fields(
-        item,
-        context.get("payment_fields", {}),
-        (
-            "product_hierarchy_tags",
-            "vat_percentage",
-            "vat_percentage_decimal",
-        ),
-        "payment_fields",
-    )
-    unit_amount = item_price + option_amount
-    print(f"Computed configured unit price: {money(unit_amount, currency)}")
-    if input("Does this match the Wolt UI? Type YES: ").strip() != "YES":
-        print("Cancelled before card lookup or quote.")
-        return
+        if item.get("restrictions") != []:
+            raise CheckoutInputError("Restricted items are unsupported.")
+        methods = item.get("allowed_delivery_methods")
+        if not isinstance(methods, list) or "homedelivery" not in methods:
+            raise CheckoutInputError(
+                "This item does not explicitly support home delivery."
+            )
+        count = number("Item quantity: ", 1)
+        options, option_names = select_options(item, assortment, args.language)
+        basket.add_item(item["id"], count, options)
+        selected_item = basket.contents[item["id"]]
+        if selected_item.checkout_fields["alcohol_permille"] != 0:
+            raise CheckoutInputError("Age-restricted items are unsupported.")
+        selected_items.append((selected_item, option_names))
+        if input("Add another menu item? Type YES: ").strip() != "YES":
+            break
+
+    item_selections = basket.item_selections()
     tip = number("Courier tip in cents (0 for none): ")
     delivery = choose(
         "saved delivery target", client.list_delivery_targets(), delivery_description
@@ -257,10 +223,11 @@ def checkout(client, args, context):
         "available_methods": ["card"],
         "items": [
             {
-                "id": item["id"],
-                "alcohol_permille": checkout_fields["alcohol_permille"],
-                **payment_fields,
+                "id": item.id,
+                "alcohol_permille": item.checkout_fields["alcohol_permille"],
+                **item.payment_fields,
             }
+            for item in item_selections
         ],
     }
     card = choose(
@@ -268,31 +235,24 @@ def checkout(client, args, context):
         client.get_payment_methods(card_context),
         card_description,
     )
-    selected_item = ItemSelection(
-        id=item["id"],
-        count=count,
-        basket_name=text(item.get("name"), args.language),
-        basket_price=unit_amount,
-        end_amount=unit_amount,
-        substitution_allowed=False,
-        checkout_fields=checkout_fields,
-        options=options,
-        payment_fields=payment_fields,
-    )
     selection = client.create_selection(
         assortment,
         venue=VenueCheckoutContext(id=venue.id, preorder_config=None, **venue_fields),
         delivery=DeliverySelection(delivery.id, args.latitude, args.longitude),
         payment_method={"id": card.id, "type": card.type},
         courier_tip=tip,
-        items=[selected_item],
-    )
-    print(
-        f"\n{count} x {selected_item.basket_name} at {text(venue.title or venue.slug)}"
+        items=item_selections,
     )
-    for name in option_names:
-        print(f"  Option: {name}")
-    print(f"Configured unit price: {money(unit_amount, currency)}")
+    for selected_item, option_names in selected_items:
+        print(
+            f"\n{selected_item.count} x {selected_item.basket_name} "
+            f"at {text(venue.title or venue.slug)}"
+        )
+        for name in option_names:
+            print(f"  Option: {name}")
+        print(
+            f"Catalog-derived line total: {money(selected_item.basket_price, currency)}"
+        )
     print(
         f"Delivery: {delivery_description(delivery)} | Card: {card_description(card)}"
     )
@@ -360,7 +320,7 @@ def main():
     parser.add_argument(
         "--context-file",
         type=Path,
-        help="Optional current browser metadata for fields missing from the catalog",
+        help="Optional current browser metadata for venue fields missing from static data",
     )
     parser.add_argument(
         "--save-basket",

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

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

{woltapi-0.2.0 → woltapi-0.3.0}/src/woltapi/__init__.py

@@ -1,6 +1,7 @@
 """Synchronous selection and explicit purchase client for observed Wolt hosts."""
 
 from .auth import RefreshTokenCredentials
+from .basket import Basket
 from .client import WoltClient
 from .credentials import SessionCredentials
 from .errors import (
@@ -50,6 +51,7 @@ from .transport import WoltTransport
 __all__ = [
     "DeliveryTarget",
     "DeliverySelection",
+    "Basket",
     "DuplicatePurchaseAttempt",
     "HTTPStatusError",
     "ItemSelection",