woltapi 0.1.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: woltapi
-Version: 0.1.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
@@ -63,14 +63,18 @@ lists some of its menu items. **It will not order anything or change your basket
 python examples/browse.py \
   --latitude 60.17 \
   --longitude 24.94 \
-  --query "pizza"
+  --query "pizza" \
+  --token-file ~/.wolt-token
 ```
 
 Replace the two numbers with your location. The example numbers are in Helsinki.
 Latitude and longitude are the two numbers that identify a place on a map.
 
-The script asks for your Wolt access token. Paste it and press Enter. Nothing
-will appear while you paste; that is intentional.
+`--token-file` is required. It names the file that holds your Wolt refresh
+token. On the first run the file does not exist yet, so the script asks for the
+token. Paste it and press Enter. Nothing will appear while you paste; that is
+intentional. The script then saves the token to that file, and later runs read
+it from there without asking. See [Get a token](#get-a-token) below.
 
 By default, it shows up to 5 recent orders and 20 menu items from the first
 restaurant in the search results. You can change that:
@@ -80,6 +84,7 @@ python examples/browse.py \
   --latitude 60.17 \
   --longitude 24.94 \
   --query "burger" \
+  --token-file ~/.wolt-token \
   --orders 3 \
   --menu-limit 50 \
   --venue-index 2
@@ -94,46 +99,52 @@ The library keeps the original integer amounts; only the display converts them.
 
 ## Get a token
 
-An **access token** is a temporary key that lets the library use your Wolt
-account. Treat it like a password.
+A **refresh token** is a long-lived key that lets the library sign requests
+for your Wolt account. Treat it like a password.
 
 1. Sign in to Wolt in your browser.
-2. Open Developer Tools and select the **Network** tab.
-3. Open your order history in Wolt.
-4. Select a successful request to `consumer-api.wolt.com`.
-5. Under **Request Headers**, find `authorization: Bearer ...`.
-6. Copy the long token after `Bearer `.
+2. Open Developer Tools and select **Application** (Firefox: **Storage**).
+3. Under **Cookies**, find the cookie named `__wrtoken`.
+4. Copy its value, without surrounding quotes.
 
 Do not share the token, put it in Git, or include it in screenshots.
 
-The browsing script can also read the token from an environment variable named
-`WOLT_ACCESS_TOKEN`. An environment variable is a setting passed to a program
-when it starts. If that variable is set, the script uses it instead of asking
-you to paste a token. No credential file is needed.
+The example scripts read the token from the file named by `--token-file`. If
+that file does not exist, or is empty, they ask with a hidden prompt and then
+save what you paste. The file is created readable only by you.
 
-Access tokens expire. With manually supplied headers, get a current access token
-if you receive **HTTP 401**, and update `WOLT_ACCESS_TOKEN` if you use it. For
-automatic renewal in Python, use a consumer refresh token as described below.
-The library cannot sign you in.
+Wolt may replace your refresh token over time. The scripts save each
+replacement to the same file, so later runs keep working without another visit
+to the browser. Point every run at the same file.
+
+Because of this, the token file holds a live secret and becomes the only copy
+once Wolt has replaced the original. Keep it out of Git and shared folders. Do
+not point two programs that run at the same time at one token file: whichever
+refreshes second will find its own token already replaced.
+
+If a run receives **HTTP 401**, the saved token has expired or was revoked. Put
+a current `__wrtoken` value in the token file, or delete the file and let the
+script ask again. The library cannot sign you in.
+
+The scripts exchange this refresh token for short-lived access tokens
+automatically; you never handle access tokens yourself. If you want to supply
+raw `Authorization` headers instead, use `SessionCredentials` from Python
+directly, as described under
+[Manually supplied headers](#manually-supplied-headers).
 
 ## Use it in Python
 
-Here is a complete browsing example. It asks for your token and location, then
-searches for pizza and loads the first result's menu:
+Here is a complete browsing example. It asks for your refresh token and
+location, then searches for pizza and loads the first result's menu:
 
 ```python
 from getpass import getpass
 
-from woltapi import SessionCredentials, WoltClient
-
-token = getpass("Wolt access token: ").strip()
-token = token.removeprefix("Bearer ")
-headers = {"Authorization": f"Bearer {token}"}
+from woltapi import RefreshTokenCredentials, WoltClient
 
 client = WoltClient(
-    SessionCredentials(
-        restaurant_headers=headers,
-        consumer_headers=headers,
+    RefreshTokenCredentials(
+        getpass("Wolt refresh token: ").strip(),
     )
 )
 
@@ -157,35 +168,17 @@ else:
     print("No restaurants found. Try another search.")
 ```
 
-Wolt uses different servers for different jobs. `restaurant_headers` supplies
-the login token for searches and saved delivery addresses. `consumer_headers`
-supplies it for menus and order history. The library sends each set of headers
-only to its matching server.
-
 **The library does not find your token for you.** Your code passes it into
-`SessionCredentials`. Reading an environment variable or asking for a token is
-the job of your script, not the library.
-
-### Automatic token refresh
+`RefreshTokenCredentials`. Reading a file, an environment variable, or a prompt
+is the job of your script, not the library.
 
-Only a **consumer refresh token** is needed to start: no access token, password,
-client secret, or browser cookies need to accompany the request. In your logged-in
-Wolt browser, find `__wrtoken` under **Developer Tools > Application > Cookies**.
-Use its value, without surrounding quotes. This is not the access token from an
-Authorization header or the refresh token used by the Converse support widget.
-Treat it like a password and do not put it in Git or logs.
+### How token refresh works
 
-```python
-from getpass import getpass
-
-from woltapi import RefreshTokenCredentials, WoltClient
-
-credentials = RefreshTokenCredentials(
-    getpass("Wolt consumer refresh token: ").strip(),
-)
-client = WoltClient(credentials)
-history = client.get_orders_page()
-```
+Only the **consumer refresh token** is needed to start: no access token,
+password, client secret, or browser cookies need to accompany the request. This
+is the `__wrtoken` value from [Get a token](#get-a-token). It is not the access
+token from an Authorization header or the refresh token used by the Converse
+support widget.
 
 The first API call exchanges the refresh token at
 `https://authentication.wolt.com/v1/wauth2/access_token`. Subsequent calls reuse
@@ -208,8 +201,8 @@ exception propagates but the new tokens remain in memory. Later calls retry the
 callback before any further authentication or API request; they remain blocked
 until persistence succeeds. Make your callback safe to repeat with the same token.
 
-Optional `restaurant_headers`, `consumer_headers`, and `payment_headers` still
-scope extra headers to their respective hosts. `Authorization` is managed by
+Optional `restaurant_headers`, `consumer_headers`, and `payment_headers` scope
+extra headers to their respective hosts. `Authorization` is managed by
 `RefreshTokenCredentials`. Its `timeout` controls authentication requests
 separately from `WoltClient`'s API timeout (both default to 10 seconds).
 
@@ -217,8 +210,28 @@ Refresh requests are not retried or redirected, and API requests are never
 automatically replayed after a 401, including purchases. An expired or revoked
 refresh token requires a new browser session credential. Authentication failures
 use the existing exceptions, such as `HTTPStatusError` with
-`service == "authentication"`. The example scripts still accept access tokens;
-automatic renewal is opt-in through this Python API.
+`service == "authentication"`.
+
+### Manually supplied headers
+
+If you already hold a short-lived access token and want to supply raw headers
+yourself, use `SessionCredentials` instead:
+
+```python
+from woltapi import SessionCredentials, WoltClient
+
+headers = {"Authorization": "Bearer <access token>"}
+client = WoltClient(
+    SessionCredentials(restaurant_headers=headers, consumer_headers=headers)
+)
+```
+
+Wolt uses different servers for different jobs. `restaurant_headers` supplies
+the login token for searches and saved delivery addresses. `consumer_headers`
+supplies it for menus and order history. The library sends each set of headers
+only to its matching server. With this class, nothing renews the token: after
+about 30 minutes, requests fail with **HTTP 401**. The example scripts no
+longer use this path; prefer `RefreshTokenCredentials`.
 
 ### Useful methods
 
@@ -229,8 +242,9 @@ automatic renewal is opt-in through this Python API.
 | `client.get_venue_static(slug)` | A dictionary of restaurant details. |
 | `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, without printing the addresses. |
+| `client.list_delivery_targets()` | References to your saved delivery addresses, with saved labels and address details. |
 | `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. |
 
 For example, after creating `client`:
 
@@ -244,7 +258,55 @@ print(f"You have {len(targets)} saved delivery addresses.")
 ```
 
 Responses can contain personal information. Avoid printing entire responses or
-sending them to shared logs. The browsing example prints only selected fields.
+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?
 
@@ -254,20 +316,27 @@ To try **checkout without buying anything**, use the new checkout-only example
 from an editable source installation:
 
 ```bash
-python examples/order.py --latitude 60.17 --longitude 24.94 --query pizza
+python examples/order.py --latitude 60.17 --longitude 24.94 --query pizza \
+  --token-file ~/.wolt-token
 ```
 
-Use your own coordinates. It prompts for your token (or uses `WOLT_ACCESS_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
+Use your own coordinates. It reads and saves your refresh token as described in
+[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.
 
-This is still a test tool: it may stop if the catalog lacks required checkout
-fields. Run `python examples/order.py --help` for available options.
+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 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.
+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.1.0 → woltapi-0.3.0}/README.md

@@ -45,14 +45,18 @@ lists some of its menu items. **It will not order anything or change your basket
 python examples/browse.py \
   --latitude 60.17 \
   --longitude 24.94 \
-  --query "pizza"
+  --query "pizza" \
+  --token-file ~/.wolt-token
 ```
 
 Replace the two numbers with your location. The example numbers are in Helsinki.
 Latitude and longitude are the two numbers that identify a place on a map.
 
-The script asks for your Wolt access token. Paste it and press Enter. Nothing
-will appear while you paste; that is intentional.
+`--token-file` is required. It names the file that holds your Wolt refresh
+token. On the first run the file does not exist yet, so the script asks for the
+token. Paste it and press Enter. Nothing will appear while you paste; that is
+intentional. The script then saves the token to that file, and later runs read
+it from there without asking. See [Get a token](#get-a-token) below.
 
 By default, it shows up to 5 recent orders and 20 menu items from the first
 restaurant in the search results. You can change that:
@@ -62,6 +66,7 @@ python examples/browse.py \
   --latitude 60.17 \
   --longitude 24.94 \
   --query "burger" \
+  --token-file ~/.wolt-token \
   --orders 3 \
   --menu-limit 50 \
   --venue-index 2
@@ -76,46 +81,52 @@ The library keeps the original integer amounts; only the display converts them.
 
 ## Get a token
 
-An **access token** is a temporary key that lets the library use your Wolt
-account. Treat it like a password.
+A **refresh token** is a long-lived key that lets the library sign requests
+for your Wolt account. Treat it like a password.
 
 1. Sign in to Wolt in your browser.
-2. Open Developer Tools and select the **Network** tab.
-3. Open your order history in Wolt.
-4. Select a successful request to `consumer-api.wolt.com`.
-5. Under **Request Headers**, find `authorization: Bearer ...`.
-6. Copy the long token after `Bearer `.
+2. Open Developer Tools and select **Application** (Firefox: **Storage**).
+3. Under **Cookies**, find the cookie named `__wrtoken`.
+4. Copy its value, without surrounding quotes.
 
 Do not share the token, put it in Git, or include it in screenshots.
 
-The browsing script can also read the token from an environment variable named
-`WOLT_ACCESS_TOKEN`. An environment variable is a setting passed to a program
-when it starts. If that variable is set, the script uses it instead of asking
-you to paste a token. No credential file is needed.
+The example scripts read the token from the file named by `--token-file`. If
+that file does not exist, or is empty, they ask with a hidden prompt and then
+save what you paste. The file is created readable only by you.
 
-Access tokens expire. With manually supplied headers, get a current access token
-if you receive **HTTP 401**, and update `WOLT_ACCESS_TOKEN` if you use it. For
-automatic renewal in Python, use a consumer refresh token as described below.
-The library cannot sign you in.
+Wolt may replace your refresh token over time. The scripts save each
+replacement to the same file, so later runs keep working without another visit
+to the browser. Point every run at the same file.
+
+Because of this, the token file holds a live secret and becomes the only copy
+once Wolt has replaced the original. Keep it out of Git and shared folders. Do
+not point two programs that run at the same time at one token file: whichever
+refreshes second will find its own token already replaced.
+
+If a run receives **HTTP 401**, the saved token has expired or was revoked. Put
+a current `__wrtoken` value in the token file, or delete the file and let the
+script ask again. The library cannot sign you in.
+
+The scripts exchange this refresh token for short-lived access tokens
+automatically; you never handle access tokens yourself. If you want to supply
+raw `Authorization` headers instead, use `SessionCredentials` from Python
+directly, as described under
+[Manually supplied headers](#manually-supplied-headers).
 
 ## Use it in Python
 
-Here is a complete browsing example. It asks for your token and location, then
-searches for pizza and loads the first result's menu:
+Here is a complete browsing example. It asks for your refresh token and
+location, then searches for pizza and loads the first result's menu:
 
 ```python
 from getpass import getpass
 
-from woltapi import SessionCredentials, WoltClient
-
-token = getpass("Wolt access token: ").strip()
-token = token.removeprefix("Bearer ")
-headers = {"Authorization": f"Bearer {token}"}
+from woltapi import RefreshTokenCredentials, WoltClient
 
 client = WoltClient(
-    SessionCredentials(
-        restaurant_headers=headers,
-        consumer_headers=headers,
+    RefreshTokenCredentials(
+        getpass("Wolt refresh token: ").strip(),
     )
 )
 
@@ -139,35 +150,17 @@ else:
     print("No restaurants found. Try another search.")
 ```
 
-Wolt uses different servers for different jobs. `restaurant_headers` supplies
-the login token for searches and saved delivery addresses. `consumer_headers`
-supplies it for menus and order history. The library sends each set of headers
-only to its matching server.
-
 **The library does not find your token for you.** Your code passes it into
-`SessionCredentials`. Reading an environment variable or asking for a token is
-the job of your script, not the library.
-
-### Automatic token refresh
+`RefreshTokenCredentials`. Reading a file, an environment variable, or a prompt
+is the job of your script, not the library.
 
-Only a **consumer refresh token** is needed to start: no access token, password,
-client secret, or browser cookies need to accompany the request. In your logged-in
-Wolt browser, find `__wrtoken` under **Developer Tools > Application > Cookies**.
-Use its value, without surrounding quotes. This is not the access token from an
-Authorization header or the refresh token used by the Converse support widget.
-Treat it like a password and do not put it in Git or logs.
+### How token refresh works
 
-```python
-from getpass import getpass
-
-from woltapi import RefreshTokenCredentials, WoltClient
-
-credentials = RefreshTokenCredentials(
-    getpass("Wolt consumer refresh token: ").strip(),
-)
-client = WoltClient(credentials)
-history = client.get_orders_page()
-```
+Only the **consumer refresh token** is needed to start: no access token,
+password, client secret, or browser cookies need to accompany the request. This
+is the `__wrtoken` value from [Get a token](#get-a-token). It is not the access
+token from an Authorization header or the refresh token used by the Converse
+support widget.
 
 The first API call exchanges the refresh token at
 `https://authentication.wolt.com/v1/wauth2/access_token`. Subsequent calls reuse
@@ -190,8 +183,8 @@ exception propagates but the new tokens remain in memory. Later calls retry the
 callback before any further authentication or API request; they remain blocked
 until persistence succeeds. Make your callback safe to repeat with the same token.
 
-Optional `restaurant_headers`, `consumer_headers`, and `payment_headers` still
-scope extra headers to their respective hosts. `Authorization` is managed by
+Optional `restaurant_headers`, `consumer_headers`, and `payment_headers` scope
+extra headers to their respective hosts. `Authorization` is managed by
 `RefreshTokenCredentials`. Its `timeout` controls authentication requests
 separately from `WoltClient`'s API timeout (both default to 10 seconds).
 
@@ -199,8 +192,28 @@ Refresh requests are not retried or redirected, and API requests are never
 automatically replayed after a 401, including purchases. An expired or revoked
 refresh token requires a new browser session credential. Authentication failures
 use the existing exceptions, such as `HTTPStatusError` with
-`service == "authentication"`. The example scripts still accept access tokens;
-automatic renewal is opt-in through this Python API.
+`service == "authentication"`.
+
+### Manually supplied headers
+
+If you already hold a short-lived access token and want to supply raw headers
+yourself, use `SessionCredentials` instead:
+
+```python
+from woltapi import SessionCredentials, WoltClient
+
+headers = {"Authorization": "Bearer <access token>"}
+client = WoltClient(
+    SessionCredentials(restaurant_headers=headers, consumer_headers=headers)
+)
+```
+
+Wolt uses different servers for different jobs. `restaurant_headers` supplies
+the login token for searches and saved delivery addresses. `consumer_headers`
+supplies it for menus and order history. The library sends each set of headers
+only to its matching server. With this class, nothing renews the token: after
+about 30 minutes, requests fail with **HTTP 401**. The example scripts no
+longer use this path; prefer `RefreshTokenCredentials`.
 
 ### Useful methods
 
@@ -211,8 +224,9 @@ automatic renewal is opt-in through this Python API.
 | `client.get_venue_static(slug)` | A dictionary of restaurant details. |
 | `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, without printing the addresses. |
+| `client.list_delivery_targets()` | References to your saved delivery addresses, with saved labels and address details. |
 | `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. |
 
 For example, after creating `client`:
 
@@ -226,7 +240,55 @@ print(f"You have {len(targets)} saved delivery addresses.")
 ```
 
 Responses can contain personal information. Avoid printing entire responses or
-sending them to shared logs. The browsing example prints only selected fields.
+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?
 
@@ -236,20 +298,27 @@ To try **checkout without buying anything**, use the new checkout-only example
 from an editable source installation:
 
 ```bash
-python examples/order.py --latitude 60.17 --longitude 24.94 --query pizza
+python examples/order.py --latitude 60.17 --longitude 24.94 --query pizza \
+  --token-file ~/.wolt-token
 ```
 
-Use your own coordinates. It prompts for your token (or uses `WOLT_ACCESS_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
+Use your own coordinates. It reads and saves your refresh token as described in
+[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.
 
-This is still a test tool: it may stop if the catalog lacks required checkout
-fields. Run `python examples/order.py --help` for available options.
+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 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.
+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