woltapi 0.0.1__py3-none-any.whl

woltapi/services.py

@@ -0,0 +1,24 @@
+"""Fixed service-host definitions for ordering discovery operations."""
+
+from __future__ import annotations
+
+from enum import Enum
+from types import MappingProxyType
+from typing import Final, Mapping
+
+
+class ServiceHost(str, Enum):
+    """The only hosts to which this library routes ordering credentials."""
+
+    RESTAURANT = "restaurant"
+    CONSUMER = "consumer"
+    PAYMENT = "payment"
+
+
+BASE_URLS: Final[Mapping[ServiceHost, str]] = MappingProxyType(
+    {
+        ServiceHost.RESTAURANT: "https://restaurant-api.wolt.com",
+        ServiceHost.CONSUMER: "https://consumer-api.wolt.com",
+        ServiceHost.PAYMENT: "https://payment-service.wolt.com",
+    }
+)

woltapi/transport.py

@@ -0,0 +1,198 @@
+"""Synchronous, non-retrying transport for fixed Wolt service hosts."""
+
+from __future__ import annotations
+
+import json
+import math
+import socket
+from collections.abc import Mapping
+from typing import Any, Protocol
+from urllib import error as urlerror
+from urllib import request as urlrequest
+from urllib.parse import urlencode
+
+from .credentials import SessionCredentials
+from .errors import (
+    HTTPStatusError,
+    RequestFailedError,
+    RequestTimeoutError,
+    ResponseDecodeError,
+    ResponseShapeError,
+)
+from .services import BASE_URLS, ServiceHost
+
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+
+class _Opener(Protocol):
+    def open(
+        self, fullurl: Any, data: bytes | None = None, timeout: float = ...
+    ) -> Any:
+        """Open a request and return a response-like object."""
+
+
+class _NoRedirect(urlrequest.HTTPRedirectHandler):
+    """Refuse redirects so credentials cannot be forwarded to a new URL."""
+
+    def redirect_request(
+        self,
+        req: urlrequest.Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> None:
+        return None
+
+
+class WoltTransport:
+    """Transport that permits only the three explicitly configured hosts.
+
+    The default opener has no cookie jar, no retry policy, and no redirect
+    handler capable of forwarding caller-supplied credentials.
+    """
+
+    def __init__(
+        self,
+        credentials: SessionCredentials,
+        *,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        _opener: _Opener | None = None,
+    ) -> None:
+        if not isinstance(credentials, SessionCredentials):
+            raise TypeError("credentials must be a SessionCredentials instance.")
+        self._credentials = credentials
+        self._timeout = _validate_timeout(timeout)
+        self._opener: _Opener = _opener or urlrequest.build_opener(_NoRedirect())
+
+    def request(
+        self,
+        service: ServiceHost,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        json_body: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make one JSON request to a fixed host without retries or redirects."""
+
+        if not isinstance(service, ServiceHost):
+            raise TypeError("service must be a ServiceHost instance.")
+        if method not in {"GET", "POST"}:
+            raise ValueError("Only GET and POST requests are supported.")
+        if not isinstance(path, str) or not path.startswith("/"):
+            raise ValueError("path must start with '/'.")
+        if query is not None and not isinstance(query, Mapping):
+            raise TypeError("query must be a mapping when provided.")
+        if json_body is not None and not isinstance(json_body, Mapping):
+            raise TypeError("json_body must be a mapping when provided.")
+
+        data = _encode_json(json_body, service) if json_body is not None else None
+        headers = _request_headers(
+            self._credentials.headers_for(service), data is not None
+        )
+        request = urlrequest.Request(
+            _build_url(service, path, query),
+            data=data,
+            headers=headers,
+            method=method,
+        )
+
+        try:
+            response = self._opener.open(request, timeout=self._timeout)
+            try:
+                status_code = _status_code(response, service)
+                response_body = response.read()
+            finally:
+                _close_response(response)
+        except urlerror.HTTPError as error:
+            _close_response(error)
+            raise HTTPStatusError(service.value, error.code) from None
+        except (TimeoutError, socket.timeout):
+            raise RequestTimeoutError(service.value) from None
+        except (urlerror.URLError, OSError):
+            raise RequestFailedError(service.value) from None
+
+        if not 200 <= status_code < 300:
+            raise HTTPStatusError(service.value, status_code)
+        return _decode_json_object(response_body, service)
+
+
+def _validate_timeout(timeout: float) -> float:
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        raise TypeError("timeout must be a positive finite number of seconds.")
+    timeout_as_float = float(timeout)
+    if not math.isfinite(timeout_as_float) or timeout_as_float <= 0:
+        raise ValueError("timeout must be a positive finite number of seconds.")
+    return timeout_as_float
+
+
+def _encode_json(payload: Mapping[str, Any], service: ServiceHost) -> bytes:
+    try:
+        return json.dumps(payload, allow_nan=False, separators=(",", ":")).encode(
+            "utf-8"
+        )
+    except (TypeError, ValueError, UnicodeEncodeError):
+        raise RequestFailedError(service.value) from None
+
+
+def _request_headers(
+    credential_headers: Mapping[str, str],
+    has_json_body: bool,
+) -> dict[str, str]:
+    """Copy headers while ensuring JSON writes have one content type."""
+
+    headers: dict[str, str] = {}
+    lower_names: set[str] = set()
+    for name, value in credential_headers.items():
+        normalized_name = name.lower()
+        if normalized_name == "content-type" and has_json_body:
+            continue
+        if normalized_name in lower_names:
+            continue
+        headers[name] = value
+        lower_names.add(normalized_name)
+    if has_json_body:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+def _build_url(
+    service: ServiceHost,
+    path: str,
+    query: Mapping[str, Any] | None,
+) -> str:
+    url = f"{BASE_URLS[service]}{path}"
+    if query:
+        return f"{url}?{urlencode(query, doseq=True)}"
+    return url
+
+
+def _status_code(response: Any, service: ServiceHost) -> int:
+    getcode = getattr(response, "getcode", None)
+    status_code = getcode() if callable(getcode) else getattr(response, "status", None)
+    if isinstance(status_code, bool) or not isinstance(status_code, int):
+        raise ResponseShapeError(service.value)
+    return status_code
+
+
+def _close_response(response: Any) -> None:
+    close = getattr(response, "close", None)
+    if callable(close):
+        try:
+            close()
+        except OSError:
+            pass
+
+
+def _decode_json_object(response_body: Any, service: ServiceHost) -> dict[str, Any]:
+    if not isinstance(response_body, bytes) or not response_body:
+        raise ResponseShapeError(service.value)
+    try:
+        payload = json.loads(response_body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        raise ResponseDecodeError(service.value) from None
+    if not isinstance(payload, dict):
+        raise ResponseShapeError(service.value)
+    return payload

woltapi-0.0.1.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: woltapi
+Version: 0.0.1
+Summary: A small synchronous client for observed Wolt ordering flows.
+License-Expression: AGPL-3.0-only
+Project-URL: Repository, https://github.com/skorokithakis/woltapi
+Project-URL: Issues, https://github.com/skorokithakis/woltapi/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# woltapi
+
+A Python library for looking up restaurants, reading menus, and viewing your
+Wolt orders.
+
+This is an **unofficial** project. It also has code for placing orders, but that
+part is unfinished and has not been tested with a real purchase.
+
+## Install
+
+You need Python 3.10 or newer. Open a terminal in this project's folder and run:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+These commands create a separate Python environment and install the library in
+it. On Windows, activate it with `.venv\Scripts\activate` instead of `source`.
+
+## Try it
+
+The browsing example shows your recent orders, searches for a restaurant, and
+lists some of its menu items. **It will not order anything or change your basket.**
+
+```bash
+python examples/browse.py \
+  --latitude 60.17 \
+  --longitude 24.94 \
+  --query "pizza"
+```
+
+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.
+
+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:
+
+```bash
+python examples/browse.py \
+  --latitude 60.17 \
+  --longitude 24.94 \
+  --query "burger" \
+  --orders 3 \
+  --menu-limit 50 \
+  --venue-index 2
+```
+
+`--venue-index 2` chooses the second search result. You can also search for a
+restaurant by name. Use `--help` to see all the options.
+
+Menu prices are converted from cents: for example, `1234` is shown as `12.34 EUR`.
+These are item prices, not a final order total including delivery and other fees.
+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.
+
+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 `.
+
+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.
+
+Tokens expire. This library cannot refresh them or sign you in. If you get
+**HTTP 401**, get a current token from a successful browser request and try again.
+If you set `WOLT_ACCESS_TOKEN`, remember to update it too.
+
+## 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:
+
+```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}"}
+
+client = WoltClient(
+    SessionCredentials(
+        restaurant_headers=headers,
+        consumer_headers=headers,
+    )
+)
+
+latitude = float(input("Latitude: "))
+longitude = float(input("Longitude: "))
+
+restaurants = client.search_venues(
+    "pizza",
+    latitude=latitude,
+    longitude=longitude,
+)
+
+for restaurant in restaurants:
+    print(restaurant.title or restaurant.slug)
+
+if restaurants:
+    restaurant = restaurants[0]
+    menu = client.get_assortment(restaurant.slug)
+    print(f"Found {len(menu.get('items', []))} menu items.")
+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.
+
+### Useful methods
+
+| Call | What you get |
+| --- | --- |
+| `client.search_venues("pizza", latitude, longitude)` | Restaurant results with names, IDs, and slugs. A slug is the name used in a restaurant's URL. |
+| `client.get_assortment(slug)` | A dictionary containing menu items and their options. |
+| `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.get_order_status(purchase_id)` | An order's status and some price information. |
+
+For example, after creating `client`:
+
+```python
+history = client.get_orders_page()
+orders = history.get("orders", [])
+print(f"This page contains {len(orders)} orders.")
+
+targets = client.list_delivery_targets()
+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.
+
+## Can it order food?
+
+Not as a simple, ready-to-use feature yet. There is no `order("pizza")` method.
+
+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.
+
+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
+only targets one restaurant, immediate home delivery, and one saved card.
+
+`submit_prepared_order()` is the call that can place an order and charge you.
+Do not call it unless you intend to buy the exact order you have reviewed. If it
+times out or raises `OrderOutcomeUnknown`, **do not send it again**: Wolt may
+already have received it. Check the order in Wolt instead.
+
+Login, token refresh, adding cards, payment verification screens, scheduled
+orders, cancellation, and refunds are not supported.
+
+For the technical details behind the ordering code, see [WOLT_API.md](WOLT_API.md).
+You do not need to read that file to use the browsing example.
+
+## Run the tests
+
+With your Python environment active:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest
+```
+
+The tests use made-up responses. They do not contact Wolt, need your token, or
+place orders.
+
+## License
+
+Licensed under the GNU Affero General Public License, version 3
+(`AGPL-3.0-only`). See [LICENSE](LICENSE) for the full terms.

woltapi-0.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+woltapi/__init__.py,sha256=W6cJjdgLClC-Fgf7oUQtUmmguA_uMw8Ii8RHD6qReoc,2245
+woltapi/client.py,sha256=etLtJZ9UZHU6T1k1YRR3toL1JupSQcs2v4_UBIbsBCM,20822
+woltapi/credentials.py,sha256=teBxuZ0qZrweoI2LticsjOvCJGYyJeLAQJqdoi3WcxE,2260
+woltapi/errors.py,sha256=Epm7bqwhkUir-WEkrEr0LoJrunIKCHzS8q-Wc2mH95A,3203
+woltapi/models.py,sha256=9MjzFceMb57v_HoVrzRrk1nwoJtgJW2Cd_xWzkltzQE,991
+woltapi/purchase.py,sha256=6s8UricGyVH_AxjF0-Sz0AeuHWfnaIz_V_JqpG-1IuM,41676
+woltapi/selection.py,sha256=hW99NONZXQEF49fsFkUsFLCPkkkkYbof14NU9iCfstU,31147
+woltapi/services.py,sha256=sDtZNzD6Gr7Y0TTLU5jvQNdtl4IYnojH49Eb6ObLA4c,664
+woltapi/transport.py,sha256=XQwIBnLM9zhj-lF4Vuo7Eek06IUqT0uPdlm26xeuTZw,6663
+woltapi-0.0.1.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+woltapi-0.0.1.dist-info/METADATA,sha256=h_4xCw-7irW6p1_X66mYELD8sWS4b2csS69pU-ft-5A,7627
+woltapi-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+woltapi-0.0.1.dist-info/top_level.txt,sha256=lKGrCxwJsbyzH7Ch2-uq5iEM8sAWWzWfC2FK0JcnOLI,8
+woltapi-0.0.1.dist-info/RECORD,,

woltapi-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+