superroute-sapp 0.2.1__py3-none-any.whl

sapp/__init__.py

@@ -0,0 +1,25 @@
+"""sApp for Python: sign-in, the platform app API, Open Platform capabilities and webhook verification for
+Superroute (https://open.superroute.ca/developer/sapp)."""
+from ._operation import Operation, OperationFile
+from .core import (
+    DEFAULT_BASE_URL, SDK_VERSION, AuthorizationRequest, MemoryTokenStore, OpenClient, PartnerClient, SuperrouteError,
+    Tokens, TokenStore, Transport, code_challenge, create_pkce, theme_from_branding, urllib_transport,
+)
+from .generated.open_api import OPERATIONS as OPEN_OPERATIONS
+from .generated.open_api import OpenApi
+from .generated.partner_api import OPERATIONS as PARTNER_OPERATIONS
+from .generated.partner_api import PartnerApi
+from .webhooks import (
+    DEFAULT_WEBHOOK_TOLERANCE, TENANT_WEBHOOK_TOLERANCE, WEBHOOK_SCHEMES, WebhookEvent, WebhookVerificationError,
+    verify_webhook,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    'AuthorizationRequest', 'DEFAULT_BASE_URL', 'DEFAULT_WEBHOOK_TOLERANCE', 'MemoryTokenStore', 'OPEN_OPERATIONS',
+    'OpenApi', 'OpenClient', 'Operation', 'OperationFile', 'PARTNER_OPERATIONS', 'PartnerApi', 'PartnerClient',
+    'SDK_VERSION', 'SuperrouteError', 'TENANT_WEBHOOK_TOLERANCE', 'TokenStore', 'Tokens', 'Transport',
+    'WEBHOOK_SCHEMES', 'WebhookEvent', 'WebhookVerificationError', 'code_challenge', 'create_pkce',
+    'theme_from_branding', 'urllib_transport', 'verify_webhook',
+]

sapp/_operation.py

@@ -0,0 +1,28 @@
+"""One operation of a generated API, and a file sent with a multipart operation."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+
+@dataclass(frozen=True)
+class Operation:
+    """``auth`` is ``token``, ``key``, ``token_or_key`` or ``none``; ``body`` is ``json``, ``form``, ``multipart`` or None."""
+
+    id: str
+    name: str
+    method: str
+    path: str
+    auth: str
+    query: Tuple[str, ...]
+    body: Optional[str]
+
+
+@dataclass(frozen=True)
+class OperationFile:
+    """A file sent with a multipart operation (photos, signatures)."""
+
+    field: str
+    content: bytes
+    filename: str
+    content_type: str = 'application/octet-stream'

sapp/core.py

@@ -0,0 +1,613 @@
+"""sApp for Python: the core, sign-in and the generated API clients (docs/PLATFORM-APP-SDK-DESIGN.md §10).
+
+Standard library only: urllib for HTTP, hashlib / secrets for PKCE. Every client takes a ``transport`` so tests and
+apps can send requests their own way.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+import secrets
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Mapping, Optional, Protocol, Sequence, Tuple
+
+from ._operation import Operation, OperationFile
+from .generated.open_api import OpenApi
+from .generated.partner_api import PartnerApi
+
+SDK_VERSION = '0.2.1'
+DEFAULT_BASE_URL = 'https://open.superroute.ca'
+
+_TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange'
+_ID_TOKEN = 'urn:ietf:params:oauth:token-type:id_token'
+#: Refresh this long before the access token expires, so a call never starts with a token about to lapse.
+_REFRESH_MARGIN_MS = 60_000
+
+#: transport(method, url, headers, body) -> (status, headers, body). Raises OSError on a lost connection.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes]], Tuple[int, Mapping[str, str], bytes]]
+
+# ------------------------------------------------------------------------------------------------ errors
+
+
+class SuperrouteError(Exception):
+    """Every failed call. ``status`` is the HTTP status (0 when the request never got an answer), ``code`` the
+    server's error code (``invalid_token``, ``insufficient_scope``, ``access_denied``, a platform app code such as
+    ``APP_ACCESS_DENIED``, …) when it sent one, ``body`` the parsed answer."""
+
+    def __init__(self, status: int, code: Optional[str] = None, message: Optional[str] = None, body: Any = None,
+                 request_id: Optional[str] = None) -> None:
+        super().__init__(message or code or f'Request failed with status {status}')
+        self.status = status
+        self.code = code
+        self.message = str(self)
+        self.body = body
+        self.request_id = request_id
+
+    @property
+    def sign_in_required(self) -> bool:
+        """The person must sign in again: the session ended or was revoked."""
+        return self.status == 401 or self.code == 'invalid_grant'
+
+
+def _error_from(status: int, body: Any, request_id: Optional[str] = None) -> SuperrouteError:
+    b = body if isinstance(body, dict) else {}
+    message = b.get('message')
+    code = b.get('error') or b.get('code') or (message if isinstance(message, str) and re.fullmatch(r'[A-Z_]+', message) else None)
+    text = b.get('error_description') or (' '.join(str(m) for m in message) if isinstance(message, list) else message) or b.get('title')
+    return SuperrouteError(status, code, text, body, b.get('request_id') or request_id)
+
+
+# ------------------------------------------------------------------------------------------------ tokens
+
+
+@dataclass
+class Tokens:
+    access_token: str
+    refresh_token: Optional[str] = None
+    #: Milliseconds since the epoch.
+    expires_at: int = 0
+    scope: List[str] = field(default_factory=list)
+
+
+class TokenStore(Protocol):
+    """Where tokens are kept. Use encrypted storage for anything that should last."""
+
+    def get(self) -> Optional[Tokens]: ...
+
+    def set(self, tokens: Tokens) -> None: ...
+
+    def clear(self) -> None: ...
+
+
+class MemoryTokenStore:
+    """Keeps the tokens in memory only."""
+
+    def __init__(self, tokens: Optional[Tokens] = None) -> None:
+        self._tokens = tokens
+
+    def get(self) -> Optional[Tokens]:
+        return self._tokens
+
+    def set(self, tokens: Tokens) -> None:
+        self._tokens = tokens
+
+    def clear(self) -> None:
+        self._tokens = None
+
+
+def _tokens_from(body: Any, now_ms: int) -> Tokens:
+    if not isinstance(body, dict) or not isinstance(body.get('access_token'), str):
+        raise SuperrouteError(200, 'invalid_response', 'The token answer had no access token.', body)
+    try:
+        expires_in = float(body.get('expires_in') or 3600)
+    except (TypeError, ValueError):
+        expires_in = 3600.0
+    scope = body.get('scope')
+    return Tokens(
+        access_token=body['access_token'],
+        refresh_token=body.get('refresh_token') or None,
+        expires_at=now_ms + int(expires_in * 1000),
+        scope=[s for s in scope.split(' ') if s] if isinstance(scope, str) else [],
+    )
+
+
+# ------------------------------------------------------------------------------------------------ PKCE
+
+
+def _base64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode('ascii').rstrip('=')
+
+
+def code_challenge(verifier: str) -> str:
+    """S256 code challenge of a verifier (RFC 7636 §4.2)."""
+    return _base64url(hashlib.sha256(verifier.encode('ascii')).digest())
+
+
+def create_pkce() -> Dict[str, str]:
+    """A fresh PKCE pair: keep ``verifier`` until the redirect comes back, send ``challenge`` with the request."""
+    verifier = _base64url(secrets.token_bytes(48))
+    return {'verifier': verifier, 'challenge': code_challenge(verifier), 'method': 'S256'}
+
+
+@dataclass(frozen=True)
+class AuthorizationRequest:
+    """A started sign-in on the Superroute sign-in page."""
+
+    url: str
+    verifier: str
+    state: str
+    redirect_uri: str
+
+
+# ------------------------------------------------------------------------------------------------ requests
+
+
+def _text(value: Any) -> str:
+    if value is None:
+        return ''
+    if isinstance(value, bool):
+        return '1' if value else '0'
+    if isinstance(value, float) and value.is_integer() and abs(value) < 1e15:
+        return str(int(value))
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, separators=(',', ':'))
+    return str(value)
+
+
+def _build_url(base_url: str, operation: Operation, params: Mapping[str, Any]) -> str:
+    def segment(m: 're.Match[str]') -> str:
+        value = params.get(m.group(1))
+        text = _text(value)
+        return '' if text == '' else urllib.parse.quote(text, safe='')
+
+    path = re.sub(r'\{([^}]+)\}', segment, operation.path)
+    path = re.sub(r'/{2,}', '/', path)
+    path = path.rstrip('/') or '/'
+    query: List[Tuple[str, str]] = []
+    for name in operation.query:
+        value = params.get(name)
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            query.extend((name, _text(v)) for v in value)
+        else:
+            query.append((name, _text(value)))
+    url = base_url + path
+    if query:
+        url += '?' + urllib.parse.urlencode(query, quote_via=urllib.parse.quote)
+    return url
+
+
+def _encode_body(kind: Optional[str], body: Optional[Mapping[str, Any]], files: Optional[Sequence[OperationFile]]) -> Tuple[Optional[bytes], Dict[str, str]]:
+    if kind is None or (body is None and not files):
+        return None, {}
+    body = body or {}
+    if kind == 'multipart':
+        boundary = 'sapp-' + uuid.uuid4().hex
+        parts: List[bytes] = []
+
+        def part(name: str, content: bytes, filename: Optional[str] = None, content_type: Optional[str] = None) -> None:
+            disposition = f'form-data; name="{name}"' + (f'; filename="{filename}"' if filename is not None else '')
+            head = f'--{boundary}\r\nContent-Disposition: {disposition}\r\n'
+            if content_type:
+                head += f'Content-Type: {content_type}\r\n'
+            parts.append(head.encode('utf-8') + b'\r\n' + content + b'\r\n')
+
+        for key, value in body.items():
+            if value is None:
+                continue
+            if isinstance(value, (list, tuple)):
+                for item in value:
+                    part(f'{key}[]', _text(item).encode('utf-8'))
+            else:
+                part(key, _text(value).encode('utf-8'))
+        for f in files or ():
+            part(f.field, f.content, f.filename, f.content_type)
+        return b''.join(parts) + f'--{boundary}--\r\n'.encode('ascii'), {'Content-Type': f'multipart/form-data; boundary={boundary}'}
+    if kind == 'form':
+        fields = [(k, _text(v)) for k, v in body.items() if v is not None]
+        return urllib.parse.urlencode(fields).encode('ascii'), {'Content-Type': 'application/x-www-form-urlencoded'}
+    return json.dumps(body, separators=(',', ':')).encode('utf-8'), {'Content-Type': 'application/json'}
+
+
+def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes]) -> Tuple[int, Mapping[str, str], bytes]:
+    """The default transport: urllib.request. 4xx / 5xx answers are returned, not raised."""
+    if body is None and method in ('POST', 'PUT', 'PATCH'):
+        body = b''
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=60) as response:
+            return response.status, dict(response.headers.items()), response.read()
+    except urllib.error.HTTPError as e:
+        return e.code, dict(e.headers.items()) if e.headers else {}, e.read() or b''
+
+
+def _header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    lower = name.lower()
+    for k, v in headers.items():
+        if k.lower() == lower:
+            return v
+    return None
+
+
+def _read_body(raw: bytes) -> Any:
+    if not raw:
+        return None
+    text = raw.decode('utf-8', errors='replace')
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+@dataclass
+class _Answer:
+    status: int
+    headers: Mapping[str, str]
+    body: Any
+
+    def or_raise(self) -> Any:
+        if self.status >= 400:
+            raise _error_from(self.status, self.body, _header(self.headers, 'X-Request-Id'))
+        return self.body
+
+
+def _send(transport: Transport, sleep: Callable[[float], None], method: str, url: str, headers: Dict[str, str],
+          body: Optional[bytes], retries: int, retryable: bool) -> _Answer:
+    """Repeatable calls are retried on a lost connection, 502–504, and 429 with Retry-After. Writes never are."""
+    attempt = 0
+    while True:
+        try:
+            status, response_headers, raw = transport(method, url, headers, body)
+        except OSError as e:
+            if retryable and attempt < retries:
+                sleep(0.3 * 2 ** attempt)
+                attempt += 1
+                continue
+            raise SuperrouteError(0, 'network_error', 'The request could not reach Superroute.') from e
+        retry_after = _header(response_headers, 'Retry-After')
+        throttled = status == 429 and retry_after is not None
+        if retryable and attempt < retries and (status in (502, 503, 504) or throttled):
+            if throttled:
+                try:
+                    wait = min(30.0, float(retry_after) or 1.0)
+                except ValueError:
+                    wait = 1.0
+            else:
+                wait = 0.3 * 2 ** attempt
+            sleep(wait)
+            attempt += 1
+            continue
+        return _Answer(status, response_headers, _read_body(raw))
+
+
+# ------------------------------------------------------------------------------------------------ partner client
+
+
+class _Refresh:
+    def __init__(self) -> None:
+        self.done = threading.Event()
+        self.tokens: Optional[Tokens] = None
+        self.error: Optional[BaseException] = None
+
+
+class PartnerClient:
+    """The partner profile: an app registered on the Open Platform console, acting for one person at one service
+    provider.
+
+        sr = PartnerClient('p_acme_parcels', client_code='k3m9q2', app_key='sp_appkey_…')
+        sr.sign_in_with_id_token(google_id_token)
+        wallet = sr.api.platform_app_wallet()
+    """
+
+    def __init__(self, app_code: str, client_code: Optional[str] = None, app_key: Optional[str] = None,
+                 token_store: Optional[TokenStore] = None, base_url: str = DEFAULT_BASE_URL, locale: Optional[str] = None,
+                 device_id: Optional[str] = None, retries: int = 2, transport: Optional[Transport] = None,
+                 now: Optional[Callable[[], int]] = None, on_signed_out: Optional[Callable[[], None]] = None,
+                 sleep: Optional[Callable[[float], None]] = None) -> None:
+        if not app_code:
+            raise ValueError('app_code is required')
+        self.app_code = app_code
+        self.client_code = client_code
+        self.app_key = app_key
+        self.token_store: TokenStore = token_store if token_store is not None else MemoryTokenStore()
+        self.base_url = base_url.rstrip('/')
+        self.locale = locale
+        self.device_id = device_id
+        self.retries = retries
+        self._transport: Transport = transport or urllib_transport
+        self._now = now or (lambda: int(time.time() * 1000))
+        self._sleep = sleep or time.sleep
+        self._on_signed_out = on_signed_out
+        self._lock = threading.Lock()
+        self._refreshing: Optional[_Refresh] = None
+        self._listeners: List[Callable[[bool], None]] = []
+        #: One method per operation of the partner surface.
+        self.api = PartnerApi(self._api_call)
+
+    # -- session ---------------------------------------------------------------------------------------------------
+
+    def on_session_change(self, listener: Callable[[bool], None]) -> Callable[[], None]:
+        """Called with True when a sign-in starts a session and False when it ends. Answers the unsubscribe function."""
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            if listener in self._listeners:
+                self._listeners.remove(listener)
+        return unsubscribe
+
+    def _emit(self, signed_in: bool) -> None:
+        for listener in list(self._listeners):
+            try:
+                listener(signed_in)
+            except Exception:  # noqa: BLE001 - a listener's error never breaks the session
+                pass
+
+    def set_client_code(self, code: Optional[str]) -> None:
+        """Change the service provider, e.g. after the person picked one at sign-up. Sign in again afterwards."""
+        self.client_code = code
+
+    def set_locale(self, locale: Optional[str]) -> None:
+        self.locale = locale
+
+    def _base_headers(self) -> Dict[str, str]:
+        headers = {'Accept': 'application/json', 'X-SApp': f'python/{SDK_VERSION}'}
+        if self.locale:
+            headers['Accept-Language'] = self.locale
+        return headers
+
+    def _require_client_code(self) -> str:
+        if not self.client_code:
+            raise ValueError('client_code is required to sign in')
+        return self.client_code
+
+    def _form_post(self, path: str, fields: Mapping[str, Optional[str]]) -> _Answer:
+        body = urllib.parse.urlencode([(k, v) for k, v in fields.items() if v not in (None, '')]).encode('ascii')
+        headers = dict(self._base_headers(), **{'Content-Type': 'application/x-www-form-urlencoded'})
+        return _send(self._transport, self._sleep, 'POST', self.base_url + path, headers, body, 0, False)
+
+    def _token_request(self, fields: Mapping[str, Optional[str]]) -> Tokens:
+        answer = self._form_post('/app/oauth/token', dict({'client_id': self.app_code}, **fields)).or_raise()
+        tokens = _tokens_from(answer, self._now())
+        was_signed_in = self.token_store.get() is not None
+        self.token_store.set(tokens)
+        if not was_signed_in:
+            self._emit(True)
+        return tokens
+
+    def _end_session(self) -> None:
+        self.token_store.clear()
+        if self._on_signed_out:
+            self._on_signed_out()
+        self._emit(False)
+
+    def authorization_request(self, redirect_uri: str, scope: Sequence[str] = (), language: Optional[str] = None,
+                              state: Optional[str] = None) -> AuthorizationRequest:
+        """The Superroute sign-in page (method 1): open ``url`` in the browser, then pass the URL it returned to
+        :meth:`complete_sign_in`."""
+        pkce = create_pkce()
+        s = state or _base64url(secrets.token_bytes(16))
+        query = {
+            'response_type': 'code', 'client_id': self.app_code, 'client_code': self._require_client_code(),
+            'redirect_uri': redirect_uri, 'state': s, 'code_challenge': pkce['challenge'], 'code_challenge_method': 'S256',
+            'scope': ' '.join(scope), 'language': language or self.locale,
+        }
+        url = self.base_url + '/app/oauth/authorize?' + urllib.parse.urlencode([(k, v) for k, v in query.items() if v], quote_via=urllib.parse.quote)
+        return AuthorizationRequest(url, pkce['verifier'], s, redirect_uri)
+
+    def complete_sign_in(self, request: AuthorizationRequest, returned_url: str) -> Tokens:
+        """Finishes method 1 with the URL the sign-in page returned to. Raises when it does not belong to the request."""
+        answer = dict(urllib.parse.parse_qsl(urllib.parse.urlsplit(returned_url).query, keep_blank_values=True))
+        if answer.get('state') != request.state:
+            raise SuperrouteError(400, 'invalid_state', 'The sign-in answer does not belong to this request.')
+        if answer.get('error'):
+            raise SuperrouteError(400, answer['error'], answer.get('error_description'))
+        return self.exchange_code(answer.get('code', ''), request.redirect_uri, request.verifier)
+
+    def exchange_code(self, code: str, redirect_uri: str, verifier: str) -> Tokens:
+        """Finish method 1 with the redirect's code and the verifier from :meth:`authorization_request`."""
+        return self._token_request({'grant_type': 'authorization_code', 'code': code, 'redirect_uri': redirect_uri,
+                                    'code_verifier': verifier, 'device_id': self.device_id})
+
+    def sign_in_with_id_token(self, id_token: str, scope: Sequence[str] = ()) -> Tokens:
+        """Method 2: a Google or Apple ID token issued for one of the app's registered audiences."""
+        return self._token_request({'grant_type': _TOKEN_EXCHANGE, 'client_code': self._require_client_code(),
+                                    'subject_token': id_token, 'subject_token_type': _ID_TOKEN, 'scope': ' '.join(scope),
+                                    'device_id': self.device_id})
+
+    def sign_in_with_password(self, username: str, password: str, scope: Sequence[str] = ()) -> Tokens:
+        """Method 3: email and password in the app's own screens, for apps approved for it."""
+        return self._token_request({'grant_type': 'password', 'client_code': self._require_client_code(),
+                                    'username': username, 'password': password, 'scope': ' '.join(scope),
+                                    'device_id': self.device_id})
+
+    def refresh(self) -> Tokens:
+        """One refresh at a time: concurrent calls wait for the same one (a refresh token works once)."""
+        with self._lock:
+            running = self._refreshing
+            owner = running is None
+            if owner:
+                running = self._refreshing = _Refresh()
+        assert running is not None
+        if not owner:
+            running.done.wait()
+            if running.error is not None:
+                raise running.error
+            assert running.tokens is not None
+            return running.tokens
+        try:
+            tokens = self.token_store.get()
+            if tokens is None or not tokens.refresh_token:
+                self._end_session()
+                raise SuperrouteError(401, 'invalid_grant', 'Not signed in.')
+            try:
+                running.tokens = self._token_request({'grant_type': 'refresh_token', 'refresh_token': tokens.refresh_token,
+                                                      'device_id': self.device_id})
+            except SuperrouteError as e:
+                if e.code == 'invalid_grant' or e.status == 401:
+                    self._end_session()
+                raise
+            return running.tokens
+        except BaseException as e:
+            running.error = e
+            raise
+        finally:
+            with self._lock:
+                self._refreshing = None
+            running.done.set()
+
+    def _access_token(self) -> Optional[str]:
+        tokens = self.token_store.get()
+        if tokens is None:
+            return None
+        if tokens.refresh_token and tokens.expires_at - _REFRESH_MARGIN_MS <= self._now():
+            return self.refresh().access_token
+        return tokens.access_token
+
+    def sign_out(self) -> None:
+        """Ends this sign-in on the server and forgets the tokens."""
+        tokens = self.token_store.get()
+        if tokens is not None and tokens.refresh_token:
+            try:
+                self._form_post('/app/oauth/revoke', {'token': tokens.refresh_token, 'client_id': self.app_code})
+            except Exception:  # noqa: BLE001 - signing out locally never waits on the network
+                pass
+        self._end_session()
+
+    def is_signed_in(self) -> bool:
+        return self.token_store.get() is not None
+
+    # -- calls -----------------------------------------------------------------------------------------------------
+
+    def _headers(self, operation: Operation) -> Dict[str, str]:
+        headers = self._base_headers()
+        if operation.auth in ('token', 'token_or_key'):
+            token = self._access_token()
+            if token:
+                headers['Authorization'] = f'Bearer {token}'
+                return headers
+            if operation.auth == 'token':
+                raise SuperrouteError(401, 'invalid_token', 'Not signed in.')
+        if operation.auth in ('key', 'token_or_key') and self.app_key:
+            headers['X-App-Key'] = self.app_key
+        return headers
+
+    def _call(self, operation: Operation, params: Mapping[str, Any], body: Optional[Mapping[str, Any]],
+              files: Optional[Sequence[OperationFile]]) -> Any:
+        url = _build_url(self.base_url, operation, params)
+        payload, extra = _encode_body(operation.body, body, files)
+        retryable = operation.method == 'GET'
+        headers = dict(self._headers(operation), **extra)
+        answer = _send(self._transport, self._sleep, operation.method, url, headers, payload, self.retries, retryable)
+        # An access token can end early (revoked, the person's access changed): refresh once and try again.
+        if answer.status == 401 and 'Authorization' in headers:
+            self.refresh()
+            headers = dict(self._headers(operation), **extra)
+            answer = _send(self._transport, self._sleep, operation.method, url, headers, payload, self.retries, retryable)
+        return answer.or_raise()
+
+    def _api_call(self, operation: Operation, params: Mapping[str, Any], body: Optional[Mapping[str, Any]],
+                  files: Optional[Sequence[OperationFile]]) -> Any:
+        values = dict(params)
+        # Public calls name the service provider in the path; take it from the client unless the caller passes one.
+        if '{clientCode}' in operation.path and values.get('clientCode') is None:
+            values['clientCode'] = self.client_code
+        return self._call(operation, values, body, files)
+
+    def graphql(self, query: str, variables: Optional[Mapping[str, Any]] = None) -> Any:
+        """A partner GraphQL operation (open.superroute.ca/app/graphql), with the token when signed in, else the key."""
+        operation = Operation('graphql', 'graphql', 'POST', '/app/graphql', 'token_or_key', (), 'json')
+        answer = self._call(operation, {}, {'query': query, 'variables': dict(variables or {})}, None)
+        errors = answer.get('errors') if isinstance(answer, dict) else None
+        if isinstance(errors, list) and errors:
+            raise SuperrouteError(200, 'graphql_error', ' '.join(str(e.get('message', '')) if isinstance(e, dict) else str(e) for e in errors), answer)
+        return answer.get('data') if isinstance(answer, dict) else None
+
+
+# ------------------------------------------------------------------------------------------------ open client
+
+
+class OpenClient:
+    """The open profile: Open Platform capabilities (routing, geocoding, ETA, packing, …) at open.superroute.ca/v1.
+    Pass ``get_token``, answered by your backend with a short-lived token, or ``api_key`` on a server."""
+
+    def __init__(self, get_token: Optional[Callable[[], str]] = None, api_key: Optional[str] = None,
+                 base_url: str = DEFAULT_BASE_URL, locale: Optional[str] = None, retries: int = 2,
+                 transport: Optional[Transport] = None, sleep: Optional[Callable[[float], None]] = None) -> None:
+        if (get_token is None) == (api_key is None):
+            raise ValueError('pass exactly one of get_token or api_key')
+        self._get_token = get_token
+        self._api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.locale = locale
+        self.retries = retries
+        self._transport: Transport = transport or urllib_transport
+        self._sleep = sleep or time.sleep
+        #: One method per Open Platform operation.
+        self.api = OpenApi(self._call)
+
+    def _call(self, operation: Operation, params: Mapping[str, Any], body: Optional[Mapping[str, Any]],
+              files: Optional[Sequence[OperationFile]]) -> Any:
+        token = self._get_token() if self._get_token is not None else self._api_key
+        payload, extra = _encode_body(operation.body, body, files)
+        headers = {'Accept': 'application/json', 'Authorization': f'Bearer {token}', 'X-SApp': f'python/{SDK_VERSION}'}
+        if self.locale:
+            headers['Accept-Language'] = self.locale
+        headers.update(extra)
+        url = _build_url(self.base_url, operation, params)
+        return _send(self._transport, self._sleep, operation.method, url, headers, payload, self.retries,
+                     operation.method == 'GET').or_raise()
+
+
+# ------------------------------------------------------------------------------------------------ theme
+
+
+def _channel(hex_: str, i: int) -> int:
+    return int(hex_[1 + i * 2:3 + i * 2], 16)
+
+
+def _luminance(hex_: str) -> float:
+    def lin(i: int) -> float:
+        c = _channel(hex_, i) / 255
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+    return 0.2126 * lin(0) + 0.7152 * lin(1) + 0.0722 * lin(2)
+
+
+def _mix(hex_: str, target: int, amount: float) -> str:
+    def js_round(x: float) -> int:
+        return int(x + 0.5) if x >= 0 else -int(-x + 0.5)
+    return '#' + ''.join(f'{js_round(_channel(hex_, i) + (target - _channel(hex_, i)) * amount):02X}' for i in range(3))
+
+
+def theme_from_branding(branding: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
+    """Theme tokens from the service provider's branding (the bootstrap's ``client.settings.branding``)."""
+    branding = branding or {}
+    raw = branding.get('primary_color') or ''
+    primary = raw.upper() if isinstance(raw, str) and re.fullmatch(r'#[0-9a-fA-F]{6}', raw) else '#E02020'
+    return {
+        'displayName': branding.get('display_name') or None,
+        'logoUrl': branding.get('logo_url') or None,
+        'color': {
+            'primary': primary,
+            'onPrimary': '#111111' if _luminance(primary) > 0.4 else '#FFFFFF',
+            'primaryContainer': _mix(primary, 255, 0.85),
+            'onPrimaryContainer': _mix(primary, 0, 0.55),
+            'surface': '#FFFFFF',
+            'onSurface': '#1C1C1E',
+            'muted': '#6B7280',
+            'success': '#16A34A',
+            'warning': '#FD7E14',
+            'danger': '#DC2626',
+        },
+        'radius': {'small': 6, 'medium': 10, 'large': 16},
+        'spacing': {'xs': 4, 's': 8, 'm': 12, 'l': 16, 'xl': 24},
+        'type': {'body': 15, 'small': 13, 'title': 20, 'headline': 26},
+    }

sapp/generated/__init__.py

@@ -0,0 +1 @@
+"""Generated API clients."""