autoassembler 0.3.1__py3-none-any.whl

autoassembler/_custom/assemblies.py

@@ -0,0 +1,226 @@
+"""The `Assembly` handle and the curated `client.assemblies` namespace.
+
+Hand-written, protected via `.fernignore`. Built on the generated client, which
+stays reachable as ``client.api.assemblies`` for anything not covered here.
+
+Vocabulary: a CAD file becomes an `Assembly`, which is ``ready`` to be diffed or
+planned once the service has processed it; ``diff()`` compares two of them.
+
+``upload()`` and ``diff()`` return the server's `Operation`: ``upload()`` calls ``process``
+right after the upload, because the upload endpoint only stores the file, and resolves to
+the `Assembly` once processing is done; ``diff()`` resolves to the `DiffReport` once it is
+written.
+"""
+
+from __future__ import annotations
+
+import os
+import typing
+from pathlib import Path
+
+from ..assemblies.types.get_status_response import GetStatusResponse
+from ..core.pydantic_utilities import parse_obj_as
+from ..operation import Operation
+from ..types.assembly_connections_response import AssemblyConnectionsResponse
+from ..types.assembly_json_response import AssemblyJsonResponse
+from ..types.diff_report import DiffReport
+from ..types.operation import Operation as OperationResource
+from ..types.operation_response import OperationResponse_AssemblyDiff
+from ..types.process_assembly_response import ProcessAssemblyResponse_Ok
+
+if typing.TYPE_CHECKING:
+    from ..client import AutoAssembler
+    from .planning import ProcessPlan
+
+Namespace = typing.Literal["user", "shared", "public"]
+"""Where an assembly lives in the URL space. Uploads land in ``user``."""
+
+AssemblyStatus = typing.Literal["processing", "ready", "failed"]
+"""The three states a caller needs: being worked on, usable, or not going to be."""
+
+# Content types the upload endpoint accepts, by extension.
+_CONTENT_TYPES = {
+    ".step": "application/step",
+    ".stp": "application/step",
+    ".pvz": "application/octet-stream",
+}
+
+
+class Assembly:
+    """A CAD file the service knows: the handle every assembly verb hangs off.
+
+    Carries its own addressing (``namespace`` and ``id``), so you never pass either
+    around. Obtained from ``client.assemblies.upload(...)`` or
+    ``client.assemblies.get(id)``; never constructed directly.
+    """
+
+    def __init__(
+        self,
+        client: AutoAssembler,
+        *,
+        id: str,
+        namespace: Namespace = "user",
+        name: str | None = None,
+        viewer_url: str | None = None,
+    ):
+        self._client = client
+        self.id = id
+        self.namespace: Namespace = namespace
+        self.name = name
+        self._viewer_url = viewer_url
+
+    def __repr__(self) -> str:
+        return f"Assembly({self.namespace}/{self.id}, name={self.name!r})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Assembly) and (other.namespace, other.id) == (
+            self.namespace,
+            self.id,
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.namespace, self.id))
+
+    @property
+    def viewer_url(self) -> str:
+        """The assembly in the UI."""
+        if self._viewer_url:
+            return self._viewer_url
+        return f"{self._client.base_url}/assemblies/{self.namespace}/{self.id}"
+
+    @property
+    def status(self) -> AssemblyStatus:
+        """``processing``, ``ready`` or ``failed`` (one request).
+
+        ``failed`` includes an assembly whose processing is not running and never
+        finished.
+        """
+        return _status_of(self._client.api.assemblies.get_status(self.namespace, self.id))
+
+    def structure(self) -> AssemblyJsonResponse:
+        """The assembly's structure (its eBOM), as processed."""
+        return self._client.api.assemblies.get_structure(self.namespace, self.id)
+
+    def connections(self) -> AssemblyConnectionsResponse:
+        """Part-to-part connections (the liaison graph), as processed."""
+        return self._client.api.assemblies.list_connections(self.namespace, self.id)
+
+    def plans(self) -> list[ProcessPlan]:
+        """The process plans that exist for this assembly."""
+        return self._client.planning.list_mpps(self)
+
+    def delete(self) -> None:
+        """Delete the assembly (only your own uploads can be deleted)."""
+        self._client.api.assemblies.delete_assembly(self.id)
+
+
+class Assemblies:
+    """``client.assemblies``: CAD files in, `Assembly` handles and reports out."""
+
+    def __init__(self, client: AutoAssembler):
+        self._client = client
+
+    def upload(
+        self,
+        file: str | os.PathLike[str] | typing.BinaryIO,
+        *,
+        filename: str | None = None,
+        attributes: dict[str, list[str]] | None = None,
+    ) -> Operation[Assembly]:
+        """Upload a CAD file (``.step``, ``.stp``, ``.pvz``) and start processing it.
+
+        Returns once uploaded, with the processing operation; ``result()`` returns the
+        `Assembly` once it is ``ready``, or raises `OperationFailed` with the reason (e.g.
+        the file is not an assembly). ``op.metadata.assembly_id`` names it from the start.
+        Start several uploads before waiting on any to have their processing overlap on
+        the server.
+
+        ``file`` is a path or an open binary file (then ``filename`` is required unless
+        the object has a ``name``). ``attributes`` are parsing patterns, e.g.
+        ``{"consolidated": ["*bolt*"]}``, applied to this processing run.
+        """
+        if isinstance(file, str | os.PathLike):
+            path = Path(file)
+            with path.open("rb") as handle:
+                response = self._post_upload(handle, filename or path.name)
+        else:
+            name = filename or getattr(file, "name", None)
+            if not name:
+                raise ValueError("upload(): pass filename= when uploading from a file object")
+            response = self._post_upload(file, os.path.basename(str(name)))
+
+        uploaded = response.assembly
+        if uploaded is None or uploaded.id is None:
+            raise RuntimeError("upload: the server returned no assembly id")
+        assembly = Assembly(
+            self._client,
+            id=uploaded.id,
+            namespace="user",
+            name=uploaded.name,
+            viewer_url=response.viewer_url,
+        )
+
+        # The upload endpoint only stores the file; processing is a separate call.
+        kwargs: dict[str, typing.Any] = {}
+        if attributes is not None:
+            kwargs["attributes"] = attributes
+        processing = self._client.api.assemblies.process(assembly.namespace, assembly.id, **kwargs)
+        if not isinstance(processing, ProcessAssemblyResponse_Ok):
+            raise RuntimeError(
+                f"upload: the server queued no processing for {assembly.id} ({processing.status})"
+            )
+        # The `ok` body is the operation, next to `status`.
+        operation = parse_obj_as(OperationResource, processing.dict(by_alias=True))
+        return self._client.operations.handle(operation, resolve=lambda _: assembly)
+
+    def _post_upload(self, handle: typing.BinaryIO, filename: str):
+        content_type = _CONTENT_TYPES.get(Path(filename).suffix.lower(), "application/octet-stream")
+        return self._client.api.assemblies.upload(file=(filename, handle, content_type))
+
+    def get(self, id: str, *, namespace: Namespace = "user") -> Assembly:
+        """A handle on an existing assembly (one request, to fetch its record)."""
+        info = self._client.api.assemblies.get_assembly_info(namespace, id)
+        return Assembly(self._client, id=id, namespace=namespace, name=info.name)
+
+    def diff(
+        self,
+        reference: Assembly | str,
+        target: Assembly | str,
+        *,
+        context_hops: int = 1,
+    ) -> Operation[DiffReport]:
+        """Compare a baseline assembly with a later one.
+
+        Both assemblies must be ``ready``. Returns the diff's operation; ``result()``
+        returns the typed report: ``summary`` holds the counts, ``details`` the parts
+        behind them. A comparison the server already made comes back done.
+        """
+        reference_id = reference.id if isinstance(reference, Assembly) else reference
+        target_id = target.id if isinstance(target, Assembly) else target
+        kwargs: dict[str, typing.Any] = {}
+        if context_hops != 1:
+            kwargs["context_n_hops"] = context_hops
+        api = self._client.api.assemblies
+        computing = api.diff(reference_id=reference_id, target_id=target_id, async_=True, **kwargs)
+
+        def resolve(finished: OperationResource) -> DiffReport:
+            if not isinstance(finished.response, OperationResponse_AssemblyDiff):
+                raise TypeError(f"{finished.name} is not a diff: {finished.metadata.type}")
+            return api.get_diff_report(finished.response.result_url)
+
+        return self._client.operations.handle(computing.operation, resolve=resolve)
+
+
+def _status_of(status: GetStatusResponse) -> AssemblyStatus:
+    """Fold a ``status.json`` reading into the three states.
+
+    An ``error`` is ``failed``, even next to ``ready`` (the server marks a failed run
+    ready so the UI can show the error); ``queued`` and ``processing`` are
+    ``processing``; ``unprocessed`` means no run is queued and none finished, so it is
+    ``failed`` too, as is ``not_found``.
+    """
+    if status.status in ("queued", "processing"):
+        return "processing"
+    if status.error or status.status != "ready":
+        return "failed"
+    return "ready"

autoassembler/_custom/assemblies_api.py

@@ -0,0 +1,188 @@
+"""``client.api.assemblies``: the generated assemblies client, with an operation for async diffs.
+
+Hand-written, protected via `.fernignore`. `AssembliesApi` subclasses the generated
+`AssembliesClient` (keeping every assembly call). The generated ``diff`` reads any 2xx as a
+`DiffReport`, so with ``async_=True`` it cannot read the 202, which is the operation tracking
+the diff: the override returns an `Operation` for it instead, and `get_diff_report` fetches
+the report the finished operation's ``resultUrl`` serves (a server path, not in the spec).
+
+TODO: the blocking diff (no ``async``) is deprecated; once its deprecation period
+ends, the endpoint always answers 202 and drops the ``async`` flag. Then the spec has a single
+2xx, so the generated ``diff`` reads `DiffAccepted` itself: drop the overloads, `_diff_body`,
+`_parsed` and the raw request, and keep ``diff`` as a thin wrapper of ``super().diff()`` in an
+`Operation`, as `PlanningApi` does. Once the spec also documents the report route,
+`get_diff_report` becomes generated and goes too.
+"""
+
+import typing
+
+from ..assemblies.client import OMIT, AssembliesClient, AsyncAssembliesClient
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.request_options import RequestOptions
+from ..operation import AsyncOperation, Operation
+from ..types.diff_accepted import DiffAccepted
+from ..types.diff_report import DiffReport
+from ..types.operation_response import OperationResponse_AssemblyDiff
+from .http import parsed
+from .operations import AsyncOperations, Operations, async_response_of, response_of
+
+_DIFF_PATH = "api/v4/assemblies/diff"
+
+
+def _diff_body(
+    reference_id: str, target_id: str, context_n_hops: int | None
+) -> dict[str, typing.Any]:
+    return {
+        "referenceId": reference_id,
+        "targetId": target_id,
+        "contextNHops": context_n_hops,
+        "async": True,
+    }
+
+
+def _report_path(result_url: str) -> str:
+    # The server answers with a root-relative path; the HTTP client joins it to the base URL.
+    return result_url.lstrip("/")
+
+
+class AssembliesApi(AssembliesClient):
+    """Generated assemblies client + an operation for async diffs."""
+
+    def __init__(self, *, client_wrapper: SyncClientWrapper, operations: Operations):
+        super().__init__(client_wrapper=client_wrapper)
+        self._client_wrapper = client_wrapper
+        self._operations = operations
+
+    @typing.overload
+    def diff(
+        self,
+        *,
+        reference_id: str,
+        target_id: str,
+        context_n_hops: int | None = ...,
+        async_: typing.Literal[False] | None = ...,
+        request_options: RequestOptions | None = ...,
+    ) -> DiffReport: ...
+    @typing.overload
+    def diff(
+        self,
+        *,
+        reference_id: str,
+        target_id: str,
+        context_n_hops: int | None = ...,
+        async_: typing.Literal[True],
+        request_options: RequestOptions | None = ...,
+    ) -> Operation[OperationResponse_AssemblyDiff]: ...
+    def diff(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        *,
+        reference_id: str,
+        target_id: str,
+        context_n_hops: int | None = OMIT,
+        async_: bool | None = OMIT,
+        request_options: RequestOptions | None = None,
+    ) -> DiffReport | Operation[OperationResponse_AssemblyDiff]:
+        """Compare a reference assembly with a target one.
+
+        Without ``async_`` the call blocks and returns the `DiffReport`. With ``async_=True``
+        it returns the operation computing it: its result holds the ``resultUrl`` that
+        `get_diff_report` reads. A diff already computed comes back done.
+        """
+        if async_ is not True:  # unset (OMIT), None or False
+            return super().diff(
+                reference_id=reference_id,
+                target_id=target_id,
+                context_n_hops=context_n_hops,
+                async_=async_,
+                request_options=request_options,
+            )
+        response = self._client_wrapper.httpx_client.request(
+            _DIFF_PATH,
+            method="POST",
+            json=_diff_body(reference_id, target_id, context_n_hops),
+            headers={"content-type": "application/json"},
+            request_options=request_options,
+            omit=OMIT,
+        )
+        accepted = parsed(response, DiffAccepted)
+        return self._operations.handle(
+            accepted, resolve=response_of(OperationResponse_AssemblyDiff)
+        )
+
+    def get_diff_report(
+        self, result_url: str, *, request_options: RequestOptions | None = None
+    ) -> DiffReport:
+        """The report a finished async diff wrote, from its response's ``result_url``."""
+        response = self._client_wrapper.httpx_client.request(
+            _report_path(result_url), method="GET", request_options=request_options
+        )
+        return parsed(response, DiffReport)
+
+
+class AsyncAssembliesApi(AsyncAssembliesClient):
+    """Async generated assemblies client + an operation for async diffs (see `AssembliesApi`)."""
+
+    def __init__(self, *, client_wrapper: AsyncClientWrapper, operations: AsyncOperations):
+        super().__init__(client_wrapper=client_wrapper)
+        self._client_wrapper = client_wrapper
+        self._operations = operations
+
+    @typing.overload
+    async def diff(
+        self,
+        *,
+        reference_id: str,
+        target_id: str,
+        context_n_hops: int | None = ...,
+        async_: typing.Literal[False] | None = ...,
+        request_options: RequestOptions | None = ...,
+    ) -> DiffReport: ...
+    @typing.overload
+    async def diff(
+        self,
+        *,
+        reference_id: str,
+        target_id: str,
+        context_n_hops: int | None = ...,
+        async_: typing.Literal[True],
+        request_options: RequestOptions | None = ...,
+    ) -> AsyncOperation[OperationResponse_AssemblyDiff]: ...
+    async def diff(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        *,
+        reference_id: str,
+        target_id: str,
+        context_n_hops: int | None = OMIT,
+        async_: bool | None = OMIT,
+        request_options: RequestOptions | None = None,
+    ) -> DiffReport | AsyncOperation[OperationResponse_AssemblyDiff]:
+        """Compare a reference assembly with a target one; see `AssembliesApi.diff`."""
+        if async_ is not True:  # unset (OMIT), None or False
+            return await super().diff(
+                reference_id=reference_id,
+                target_id=target_id,
+                context_n_hops=context_n_hops,
+                async_=async_,
+                request_options=request_options,
+            )
+        response = await self._client_wrapper.httpx_client.request(
+            _DIFF_PATH,
+            method="POST",
+            json=_diff_body(reference_id, target_id, context_n_hops),
+            headers={"content-type": "application/json"},
+            request_options=request_options,
+            omit=OMIT,
+        )
+        accepted = parsed(response, DiffAccepted)
+        return await self._operations.handle(
+            accepted, resolve=async_response_of(OperationResponse_AssemblyDiff)
+        )
+
+    async def get_diff_report(
+        self, result_url: str, *, request_options: RequestOptions | None = None
+    ) -> DiffReport:
+        """The report a finished async diff wrote; see `AssembliesApi.get_diff_report`."""
+        response = await self._client_wrapper.httpx_client.request(
+            _report_path(result_url), method="GET", request_options=request_options
+        )
+        return parsed(response, DiffReport)

autoassembler/_custom/credentials.py

@@ -0,0 +1,248 @@
+"""Device login and the credential store.
+
+Hand-written, protected via `.fernignore`. Built on the generated ``auth`` client
+(``create_device_authorization`` / ``create_access_token``, RFC 8628).
+
+Three ways to hold a token, in the order ``AutoAssembler()`` looks for one:
+
+1. ``AutoAssembler(token=...)``: explicit, what CI and scripts do (an API key's secret
+   is a bearer token).
+2. The ``AA_TOKEN`` environment variable.
+3. The credential store written by `login`: ``$XDG_CONFIG_HOME/autoassembler/credentials.json``
+   (``~/.config/autoassembler/credentials.json`` by default), one entry per server URL,
+   file mode 0600.
+
+`login` runs the OAuth device authorization grant: it asks the server for a code, prints
+the URL and the code for the person to approve in a browser, polls the token endpoint
+until the approval lands, and stores the token. Tokens last 30 days and have no refresh,
+so an expired store means logging in again; `AutoAssembler()` says so.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import time
+import typing
+from pathlib import Path
+
+from .._version import __version__
+from ..base_client import BaseAutoAssembler
+from ..core.api_error import ApiError
+from ..core.request_options import RequestOptions
+from ..environment import AutoAssemblerEnvironment
+
+ENV_TOKEN = "AA_TOKEN"  # noqa: S105  (the variable name, not a secret)
+"""Environment variable `AutoAssembler()` reads a bearer token from."""
+
+DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+
+# A stored token this close to expiry is treated as expired, so a request never fails mid-flight.
+_EXPIRY_SKEW_SECONDS = 60.0
+
+
+class CredentialsError(RuntimeError):
+    """No usable token: none given, none in the environment, none stored (or it expired)."""
+
+
+class DeviceAuthorizationError(RuntimeError):
+    """The device authorization grant ended without a token.
+
+    ``code`` is the server's OAuth error code (RFC 6749 §5.2 / RFC 8628 §3.5), e.g.
+    ``expired_token``, ``access_denied``, ``invalid_grant``; ``None`` for a timeout here.
+    """
+
+    def __init__(self, message: str, *, code: str | None = None):
+        super().__init__(message)
+        self.code = code
+
+
+# ---------------------------------------------------------------------------
+# Resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_token(base_url: str) -> str:
+    """The token `AutoAssembler()` uses for ``base_url`` when none is passed.
+
+    ``AA_TOKEN`` first, then the credential store. Raises `CredentialsError` naming
+    `login` when neither has one.
+    """
+    from_env = os.environ.get(ENV_TOKEN)
+    if from_env:
+        return from_env
+    stored = stored_token(base_url)
+    if stored is not None:
+        return stored
+    raise CredentialsError(
+        f"No credentials for {_normalize(base_url)}: pass token=..., set {ENV_TOKEN}, "
+        "or run autoassembler.login()."
+    )
+
+
+def stored_token(base_url: str) -> str | None:
+    """The stored, unexpired token for ``base_url``, or ``None``."""
+    entry = _read_store().get("credentials", {}).get(_normalize(base_url))
+    if not isinstance(entry, dict):
+        return None
+    token = entry.get("access_token")
+    expires_at = entry.get("expires_at")
+    if not isinstance(token, str) or not isinstance(expires_at, int | float):
+        return None
+    if time.time() >= expires_at - _EXPIRY_SKEW_SECONDS:
+        return None
+    return token
+
+
+# ---------------------------------------------------------------------------
+# Login / logout
+# ---------------------------------------------------------------------------
+
+
+def login(
+    base_url: str | None = None,
+    *,
+    force: bool = False,
+    output: typing.TextIO | None = None,
+    timeout: float | None = None,
+) -> str:
+    """Log in to ``base_url`` (production by default) with the device authorization grant.
+
+    Prints a URL and a code to ``output`` (stderr by default); open the URL, enter the
+    code, and this returns once the server has issued a token, which is also stored for
+    `AutoAssembler()` to pick up. A stored, unexpired token is reused unless ``force``.
+    ``timeout`` caps the wait in seconds (the code's own lifetime by default).
+
+    Raises `DeviceAuthorizationError` if the grant ends without a token.
+    """
+    url = _normalize(base_url or AutoAssemblerEnvironment.PRODUCTION.value)
+    out = output or sys.stderr
+    if not force:
+        existing = stored_token(url)
+        if existing is not None:
+            print(f"Already logged in to {url} (login(force=True) logs in again).", file=out)
+            return existing
+
+    # The auth endpoints take no token; the generated client is used directly.
+    api = BaseAutoAssembler(
+        base_url=url, token=None, headers={"User-Agent": f"autoassembler-python/{__version__}"}
+    )
+    grant = api.auth.create_device_authorization()
+
+    print(f"To log in to {url}, open:", file=out)
+    print(f"  {grant.verification_uri_complete}", file=out)
+    print(f"and confirm the code {grant.user_code}", file=out)
+    out.flush()
+
+    interval = float(grant.interval or 5)
+    deadline = time.monotonic() + (timeout if timeout is not None else float(grant.expires_in))
+    while True:
+        if time.monotonic() >= deadline:
+            raise DeviceAuthorizationError(
+                f"the code {grant.user_code} was not confirmed in time; run login() again"
+            )
+        time.sleep(interval)
+        try:
+            token = api.auth.create_access_token(
+                grant_type=DEVICE_GRANT,
+                device_code=grant.device_code,
+                # The transport would retry a 429 by itself; the RFC says to slow down instead.
+                request_options=RequestOptions(max_retries=0),
+            )
+        except ApiError as exc:
+            code = _oauth_error_code(exc)
+            if code == "authorization_pending":
+                continue
+            if code == "slow_down" or exc.status_code == 429:
+                interval += 5
+                continue
+            raise DeviceAuthorizationError(
+                f"device authorization failed: {code or f'HTTP {exc.status_code}'}", code=code
+            ) from exc
+        break
+
+    _save(url, token.access_token, expires_in=float(token.expires_in))
+    print("Logged in.", file=out)
+    out.flush()
+    return token.access_token
+
+
+def logout(base_url: str | None = None) -> bool:
+    """Forget the stored credential for ``base_url`` (production by default).
+
+    Returns whether there was one. The token itself stays valid until it expires: the
+    server has no revocation for device tokens yet.
+    """
+    url = _normalize(base_url or AutoAssemblerEnvironment.PRODUCTION.value)
+    store = _read_store()
+    credentials = store.get("credentials")
+    if not isinstance(credentials, dict) or url not in credentials:
+        return False
+    del credentials[url]
+    _write_store(store)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# The store
+# ---------------------------------------------------------------------------
+
+
+def credentials_file() -> Path:
+    """Where `login` keeps tokens: ``$XDG_CONFIG_HOME/autoassembler/credentials.json``."""
+    config_home = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(config_home) / "autoassembler" / "credentials.json"
+
+
+def _read_store() -> dict[str, typing.Any]:
+    path = credentials_file()
+    try:
+        data = json.loads(path.read_text())
+    except FileNotFoundError:
+        return {"version": 1, "credentials": {}}
+    except (OSError, ValueError) as exc:
+        raise CredentialsError(f"cannot read {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise CredentialsError(f"cannot read {path}: not a JSON object")
+    data.setdefault("version", 1)
+    data.setdefault("credentials", {})
+    return data
+
+
+def _write_store(data: dict[str, typing.Any]) -> None:
+    path = credentials_file()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    # Create with private permissions before writing any token. A unique name also
+    # avoids following a pre-existing credentials.json.tmp symlink.
+    fd, name = tempfile.mkstemp(dir=path.parent, prefix=".credentials-", suffix=".tmp")
+    tmp = Path(name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            stream.write(json.dumps(data, indent=2) + "\n")
+        os.replace(tmp, path)
+    finally:
+        tmp.unlink(missing_ok=True)
+
+
+def _save(url: str, access_token: str, *, expires_in: float) -> None:
+    store = _read_store()
+    store["credentials"][url] = {
+        "access_token": access_token,
+        "token_type": "Bearer",
+        "expires_at": time.time() + expires_in,
+    }
+    _write_store(store)
+
+
+def _normalize(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+def _oauth_error_code(exc: ApiError) -> str | None:
+    body = exc.body
+    if isinstance(body, dict):
+        code = body.get("error")
+        return code if isinstance(code, str) else None
+    return None