woltapi 0.1.0__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: woltapi
-Version: 0.1.0
+Version: 0.2.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.
-
-```python
-from getpass import getpass
+### How token refresh works
 
-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,8 @@ 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.
 
 ## Can it order food?
 
@@ -254,16 +269,24 @@ 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
-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.
+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

{woltapi-0.1.0 → woltapi-0.2.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.
-
-```python
-from getpass import getpass
+### How token refresh works
 
-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,8 @@ 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.
 
 ## Can it order food?
 
@@ -236,16 +251,24 @@ 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
-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.
+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

{woltapi-0.1.0 → woltapi-0.2.0}/examples/browse.py

@@ -8,8 +8,10 @@ import argparse
 import getpass
 import math
 import os
+import tempfile
+from pathlib import Path
 
-from woltapi import HTTPStatusError, SessionCredentials, WoltApiError, WoltClient
+from woltapi import HTTPStatusError, RefreshTokenCredentials, WoltApiError, WoltClient
 
 
 def text(value, language="en"):
@@ -97,10 +99,20 @@ def positive_int(value):
     return number
 
 
+def check_token_file(parser, token_file):
+    """Fail early on an unusable token path, before any secret is typed."""
+    if token_file.exists():
+        if not token_file.is_file():
+            parser.error("--token-file must name a file.")
+    elif not token_file.parent.is_dir():
+        parser.error("The folder for --token-file does not exist.")
+
+
 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("--query", default="pizza")
     parser.add_argument("--orders", type=positive_int, default=5)
     parser.add_argument("--menu-limit", type=positive_int, default=20)
@@ -114,19 +126,26 @@ def main():
         and -180 <= args.longitude <= 180
     ):
         parser.error("Provide finite latitude [-90, 90] and longitude [-180, 180].")
+    check_token_file(parser, args.token_file)
     try:
-        headers = {
-            "Authorization": "Bearer " + access_token(),
-            "app-language": args.language,
-        }
-        client = WoltClient(
-            SessionCredentials(restaurant_headers=headers, consumer_headers=headers)
-        )
+        client = WoltClient(refresh_credentials(args.language, args.token_file))
         browse(client, args)
+    except TokenFileError:
+        print(
+            "\nCould not save the refresh token to the token file."
+            " Wolt may have replaced it, so the stored value can be dead."
+            " Put a current __wrtoken value in the file."
+        )
+        return 1
     except HTTPStatusError as exc:
-        print(f"\nRequest failed: HTTP {exc.status_code}. No retry was sent.")
+        print(
+            f"\nRequest failed: {exc.service} HTTP {exc.status_code}. No retry was sent."
+        )
         if exc.status_code == 401:
-            print("Supply a current access token from a successful browser request.")
+            print(
+                "The refresh token may be expired or revoked."
+                " Put a current __wrtoken value in the token file."
+            )
         return 1
     except (EOFError, OSError, UnicodeError, ValueError, WoltApiError) as exc:
         print(f"\nBrowse failed: {type(exc).__name__}. Private error details omitted.")
@@ -134,16 +153,66 @@ def main():
     return 0
 
 
-def access_token():
-    token = os.environ.get("WOLT_ACCESS_TOKEN", "").strip()
+class TokenFileError(OSError):
+    """The refresh token could not be saved, so the stored value may be dead."""
+
+
+def write_refresh_token(token_file, token):
+    """Atomically persist a Wolt consumer refresh token with private permissions."""
+    temporary_file = tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=token_file.parent,
+        prefix=f".{token_file.name}.",
+        delete=False,
+    )
+    temporary_path = Path(temporary_file.name)
+    replaced = False
+    try:
+        with temporary_file:
+            os.chmod(temporary_path, 0o600)
+            temporary_file.write(token)
+        os.replace(temporary_path, token_file)
+        replaced = True
+    except OSError:
+        raise TokenFileError from None
+    finally:
+        # Any failure, including KeyboardInterrupt, must not leave the token
+        # behind in a stray temporary file.
+        if not replaced:
+            try:
+                temporary_path.unlink()
+            except OSError:
+                pass
+
+
+def read_refresh_token(token_file):
+    """Read the Wolt consumer refresh token (the __wrtoken cookie value)."""
+    try:
+        token = token_file.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        token = ""
     if not token:
-        token = getpass.getpass("Wolt access token (hidden): ").strip()
-    if token.lower().startswith("bearer "):
-        token = token[7:].strip()
-    if not token or not token.isascii() or any(c.isspace() for c in token):
-        raise ValueError("A nonempty bearer token is required.")
+        token = getpass.getpass("Wolt refresh token (hidden): ").strip()
+        if not token:
+            raise ValueError("A nonempty refresh token is required.")
+        write_refresh_token(token_file, token)
     return token
 
 
+def refresh_credentials(language, token_file):
+    """Build auto-refreshing credentials from a token file or hidden prompt."""
+    token = read_refresh_token(token_file)
+
+    headers = {"app-language": language}
+    return RefreshTokenCredentials(
+        token,
+        on_refresh=lambda current_token: write_refresh_token(token_file, current_token),
+        restaurant_headers=headers,
+        consumer_headers=headers,
+        payment_headers=headers,
+    )
+
+
 if __name__ == "__main__":
     raise SystemExit(main())