matelab-python-sdk 0.1.0a1__py3-none-any.whl

matelab/_transport.py

@@ -0,0 +1,481 @@
+import asyncio
+import json
+import re
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import IO, Generic, TypeAlias, TypeVar, cast
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from matelab._generated.models import ErrorResponse, TokenRefreshRequest, TokenRefreshResponse
+from matelab.errors import (
+    MatelabAuthenticationError,
+    MatelabProtocolError,
+    MatelabProviderError,
+    MatelabTransportError,
+    MatelabUsageError,
+)
+from matelab.models import Session, Token
+from matelab.streaming import DownloadStream
+
+WireResponse = TypeVar("WireResponse", bound=BaseModel)
+_ACCESS_EXPIRY_SKEW_MS = 30_000
+_ParameterValue: TypeAlias = str | int | float | bool | None
+_FileContent: TypeAlias = IO[bytes] | bytes | str
+_FilePart: TypeAlias = (
+    _FileContent
+    | tuple[str | None, _FileContent]
+    | tuple[str | None, _FileContent, str | None]
+    | tuple[str | None, _FileContent, str | None, Mapping[str, str]]
+)
+_Files: TypeAlias = Mapping[str, _FilePart]
+_ReplayPositions: TypeAlias = tuple[tuple[IO[bytes], int], ...]
+_REDACTED = "[REDACTED]"
+_SENSITIVE_KEYS = frozenset(
+    {
+        "access",
+        "access_token",
+        "authorization",
+        "code",
+        "file",
+        "h",
+        "hash",
+        "key",
+        "password",
+        "refresh",
+        "refresh_token",
+        "token",
+        "uid",
+    }
+)
+_CONTENT_RANGE_PATTERN = re.compile(r"^bytes [0-9]+-[0-9]+/[0-9]+$")
+
+
+def multipart_fields(payload: Mapping[str, object]) -> dict[str, tuple[None, str]]:
+    return {key: (None, str(value)) for key, value in payload.items()}
+
+
+def _is_sensitive_key(key: str | None) -> bool:
+    if key is None:
+        return False
+    normalized = key.casefold().replace("-", "_")
+    return normalized in _SENSITIVE_KEYS or normalized.endswith(("_password", "_secret", "_token"))
+
+
+def _collect_sensitive_values(value: object, *, key: str | None = None) -> set[str]:
+    values: set[str] = set()
+    if _is_sensitive_key(key) and isinstance(value, str) and value:
+        values.add(value)
+    if isinstance(value, Mapping):
+        for raw_key, nested in cast(Mapping[object, object], value).items():
+            values.update(_collect_sensitive_values(nested, key=raw_key if isinstance(raw_key, str) else None))
+    elif isinstance(value, (list, tuple)):
+        for nested in cast(list[object] | tuple[object, ...], value):
+            values.update(_collect_sensitive_values(nested))
+    return values
+
+
+def _collect_sensitive_multipart_values(files: _Files | None) -> set[str]:
+    if files is None:
+        return set()
+    values: set[str] = set()
+    for key, part in files.items():
+        if not _is_sensitive_key(key) or not isinstance(part, tuple) or part[0] is not None:
+            continue
+        content = part[1]
+        if isinstance(content, str) and content:
+            values.add(content)
+    return values
+
+
+def _sanitize_value(value: object, sensitive_values: set[str], *, key: str | None = None) -> object:
+    if _is_sensitive_key(key) and isinstance(value, (str, bytes)):
+        return _REDACTED
+    if isinstance(value, str):
+        return _redact_text(value, sensitive_values)
+    if isinstance(value, Mapping):
+        return {
+            str(raw_key): _sanitize_value(nested, sensitive_values, key=raw_key if isinstance(raw_key, str) else None)
+            for raw_key, nested in cast(Mapping[object, object], value).items()
+        }
+    if isinstance(value, list):
+        return [_sanitize_value(item, sensitive_values) for item in cast(list[object], value)]
+    if isinstance(value, tuple):
+        return tuple(_sanitize_value(item, sensitive_values) for item in cast(tuple[object, ...], value))
+    return value
+
+
+def _sanitize_payload(payload: Mapping[str, object], sensitive_values: set[str]) -> dict[str, object]:
+    return {key: _sanitize_value(value, sensitive_values, key=key) for key, value in payload.items()}
+
+
+def _redact_text(message: str, sensitive_values: set[str]) -> str:
+    redacted = message
+    for value in sorted(sensitive_values, key=len, reverse=True):
+        redacted = redacted.replace(value, _REDACTED)
+    return redacted
+
+
+class Encoding(StrEnum):
+    NONE = "none"
+    QUERY = "query"
+    JSON = "json"
+    FORM = "form"
+    MULTIPART = "multipart"
+
+
+@dataclass(frozen=True, slots=True)
+class Operation(Generic[WireResponse]):
+    method: str
+    path: str
+    encoding: Encoding
+    response_model: type[WireResponse]
+    success_codes: frozenset[int]
+    authenticated: bool = True
+    authentication_errors: bool = False
+    retry_on_access_expired: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class StreamOperation:
+    method: str
+    path: str
+    authenticated: bool = True
+    retry_on_access_expired: bool = False
+    media_types: frozenset[str] | None = None
+
+
+_REFRESH_TOKENS = Operation(
+    method="POST",
+    path="/tokens/tokens_refresh",
+    encoding=Encoding.FORM,
+    response_model=TokenRefreshResponse,
+    success_codes=frozenset({0}),
+    authenticated=False,
+    authentication_errors=True,
+)
+
+
+class SessionTransport:
+    def __init__(self, http_client: httpx.AsyncClient, *, session: Session | None = None) -> None:
+        self._http: httpx.AsyncClient = http_client
+        self.session: Session | None = session
+        self._refresh_lock: asyncio.Lock = asyncio.Lock()
+
+    @staticmethod
+    def _now_ms() -> int:
+        return time.time_ns() // 1_000_000
+
+    def require_session(self) -> Session:
+        if self.session is None:
+            raise MatelabAuthenticationError("No Matelab session is configured.")
+        return self.session
+
+    def absolute_url(self, path: str, query: str) -> str:
+        """Resolve a Provider-returned relative path without exposing transport state."""
+        base = str(self._http.base_url).rstrip("/")
+        suffix = path.lstrip("/")
+        return f"{base}/{suffix}?{query}"
+
+    async def _access_token(self) -> str:
+        session = self.require_session()
+        if session.access.expires_at_ms <= self._now_ms() + _ACCESS_EXPIRY_SKEW_MS:
+            _ = await self.refresh()
+            session = self.require_session()
+        return session.access.value
+
+    async def refresh(self, *, force: bool = False, stale_access_token: str | None = None) -> Session:
+        observed_access_token = stale_access_token
+        if force and observed_access_token is None:
+            observed_access_token = self.require_session().access.value
+        async with self._refresh_lock:
+            session = self.require_session()
+            if observed_access_token is not None and session.access.value != observed_access_token:
+                return session
+            if not force and session.access.expires_at_ms > self._now_ms() + _ACCESS_EXPIRY_SKEW_MS:
+                return session
+            if session.refresh.expires_at_ms <= self._now_ms():
+                raise MatelabAuthenticationError("Matelab refresh token expired.")
+            try:
+                request = TokenRefreshRequest(refresh_token=session.refresh.value)
+            except ValidationError:
+                raise MatelabAuthenticationError("The Matelab refresh token is invalid.") from None
+            response = await self.request(_REFRESH_TOKENS, payload=request.model_dump(mode="json"))
+            self.session = Session(
+                access=Token(value=response.access.token, expires_at_ms=response.access.expiredAt),
+                refresh=Token(value=response.refresh.token, expires_at_ms=response.refresh.expiredAt),
+                identity=session.identity,
+            )
+            return self.session
+
+    async def request(
+        self,
+        operation: Operation[WireResponse],
+        *,
+        payload: Mapping[str, object] | None = None,
+        files: _Files | None = None,
+        bearer_token: str | None = None,
+    ) -> WireResponse:
+        replay_positions = self._capture_replay_positions(operation, files) if bearer_token is None else ()
+        sensitive_values = _collect_sensitive_values(payload) | _collect_sensitive_multipart_values(files)
+        if bearer_token:
+            sensitive_values.add(bearer_token)
+        return await self._request(
+            operation,
+            payload=payload,
+            files=files,
+            bearer_token=bearer_token,
+            replay_positions=replay_positions,
+            sensitive_values=sensitive_values,
+            allow_access_expired_retry=True,
+        )
+
+    async def stream(
+        self, operation: StreamOperation, *, payload: Mapping[str, object], range_header: str | None = None
+    ) -> DownloadStream:
+        sensitive_values = _collect_sensitive_values(payload)
+        return await self._stream(
+            operation,
+            payload=payload,
+            range_header=range_header,
+            sensitive_values=sensitive_values,
+            allow_access_expired_retry=True,
+        )
+
+    @staticmethod
+    def _capture_replay_positions(operation: Operation[WireResponse], files: _Files | None) -> _ReplayPositions:
+        if files is None or not operation.authenticated or not operation.retry_on_access_expired:
+            return ()
+        positions: list[tuple[IO[bytes], int]] = []
+        for part in files.values():
+            content = part[1] if isinstance(part, tuple) else part
+            if isinstance(content, (bytes, str)):
+                continue
+            try:
+                position = content.tell()
+                _ = content.seek(position)
+            except (AttributeError, OSError, ValueError) as exc:
+                raise MatelabUsageError(
+                    "Cannot retry multipart request because a file stream is not seekable."
+                ) from exc
+            positions.append((content, position))
+        return tuple(positions)
+
+    @staticmethod
+    def _rewind_files(replay_positions: _ReplayPositions) -> None:
+        for content, position in replay_positions:
+            try:
+                _ = content.seek(position)
+            except (OSError, ValueError) as exc:
+                raise MatelabUsageError(
+                    "Cannot retry multipart request because a file stream could not be rewound."
+                ) from exc
+
+    async def _request(
+        self,
+        operation: Operation[WireResponse],
+        *,
+        payload: Mapping[str, object] | None,
+        files: _Files | None,
+        bearer_token: str | None,
+        replay_positions: _ReplayPositions,
+        sensitive_values: set[str],
+        allow_access_expired_retry: bool,
+    ) -> WireResponse:
+        headers = {"Accept": "application/json"}
+        access_token: str | None = None
+        if operation.authenticated:
+            access_token = bearer_token if bearer_token is not None else await self._access_token()
+            headers["Authorization"] = f"Bearer {access_token}"
+
+        try:
+            if operation.encoding is Encoding.JSON:
+                response = await self._http.request(operation.method, operation.path, headers=headers, json=payload)
+            elif operation.encoding is Encoding.QUERY:
+                params = cast(Mapping[str, _ParameterValue], payload)
+                response = await self._http.request(operation.method, operation.path, headers=headers, params=params)
+            elif operation.encoding is Encoding.FORM:
+                response = await self._http.request(operation.method, operation.path, headers=headers, data=payload)
+            elif operation.encoding is Encoding.MULTIPART:
+                response = await self._http.request(
+                    operation.method, operation.path, headers=headers, data=payload, files=files
+                )
+            elif operation.encoding is Encoding.NONE:
+                response = await self._http.request(operation.method, operation.path, headers=headers)
+            else:
+                raise MatelabProtocolError(f"Unsupported request encoding: {operation.encoding}.")
+        except httpx.TransportError:
+            raise MatelabTransportError("Could not exchange data with the Matelab Provider.") from None
+        if not response.is_success:
+            raise MatelabTransportError(
+                f"Matelab returned HTTP {response.status_code}.", status_code=response.status_code
+            )
+        try:
+            raw_payload = cast(object, response.json())
+        except ValueError:
+            raise MatelabProtocolError("Matelab returned invalid JSON.") from None
+        if not isinstance(raw_payload, dict):
+            raise MatelabProtocolError("Matelab returned a non-object JSON payload.")
+        response_payload = cast(dict[str, object], raw_payload)
+        response_sensitive_values = sensitive_values | _collect_sensitive_values(response_payload)
+        sanitized_payload = _sanitize_payload(response_payload, response_sensitive_values)
+        code = response_payload.get("code")
+        if isinstance(code, bool) or not isinstance(code, int):
+            raise MatelabProtocolError(
+                "Matelab response does not contain an integer business code.", payload=sanitized_payload
+            )
+        if code not in operation.success_codes:
+            try:
+                error_response = ErrorResponse.model_validate(response_payload)
+            except ValidationError:
+                raise MatelabProtocolError(
+                    "Matelab error response does not match the Integration Contract.", payload=sanitized_payload
+                ) from None
+            if (
+                code == 5
+                and access_token is not None
+                and bearer_token is None
+                and operation.retry_on_access_expired
+                and allow_access_expired_retry
+            ):
+                _ = await self.refresh(force=True, stale_access_token=access_token)
+                self._rewind_files(replay_positions)
+                return await self._request(
+                    operation,
+                    payload=payload,
+                    files=files,
+                    bearer_token=None,
+                    replay_positions=replay_positions,
+                    sensitive_values=sensitive_values,
+                    allow_access_expired_retry=False,
+                )
+            error_type = (
+                MatelabAuthenticationError
+                if operation.authentication_errors or code == 5 or (operation.authenticated and code == 1)
+                else MatelabProviderError
+            )
+            raise error_type(
+                _redact_text(error_response.msg or "Matelab request failed.", response_sensitive_values),
+                code=code,
+                payload=sanitized_payload,
+            )
+        try:
+            return operation.response_model.model_validate(response_payload)
+        except ValidationError:
+            raise MatelabProtocolError(
+                "Matelab response does not match the Integration Contract.", payload=sanitized_payload
+            ) from None
+
+    async def _stream(
+        self,
+        operation: StreamOperation,
+        *,
+        payload: Mapping[str, object],
+        range_header: str | None,
+        sensitive_values: set[str],
+        allow_access_expired_retry: bool,
+    ) -> DownloadStream:
+        headers = {"Accept": "*/*"}
+        access_token: str | None = None
+        if operation.authenticated:
+            access_token = await self._access_token()
+            headers["Authorization"] = f"Bearer {access_token}"
+        if range_header is not None:
+            headers["Range"] = range_header
+
+        request = self._http.build_request(
+            operation.method, operation.path, headers=headers, params=cast(Mapping[str, _ParameterValue], payload)
+        )
+        try:
+            response = await self._http.send(request, stream=True)
+        except httpx.TransportError:
+            raise MatelabTransportError("Could not exchange data with the Matelab Provider.") from None
+
+        if response.status_code not in {200, 206}:
+            await response.aclose()
+            raise MatelabTransportError(
+                f"Matelab returned HTTP {response.status_code}.", status_code=response.status_code
+            )
+
+        media_type = (self._header(response, "Content-Type") or "").partition(";")[0].strip().casefold()
+        if media_type == "application/json":
+            body = await response.aread()
+            await response.aclose()
+            try:
+                raw_payload = cast(object, json.loads(body))
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                raise MatelabProtocolError("Matelab returned invalid JSON for a download.") from None
+            if not isinstance(raw_payload, dict):
+                raise MatelabProtocolError("Matelab returned a non-object JSON payload for a download.")
+            response_payload = cast(dict[str, object], raw_payload)
+            response_sensitive_values = sensitive_values | _collect_sensitive_values(response_payload)
+            sanitized_payload = _sanitize_payload(response_payload, response_sensitive_values)
+            code = response_payload.get("code")
+            if isinstance(code, bool) or not isinstance(code, int):
+                raise MatelabProtocolError(
+                    "Matelab download response does not contain an integer business code.", payload=sanitized_payload
+                )
+            if code == 0:
+                raise MatelabProtocolError(
+                    "Matelab returned a JSON success envelope instead of attachment bytes.", payload=sanitized_payload
+                )
+            try:
+                error_response = ErrorResponse.model_validate(response_payload)
+            except ValidationError:
+                raise MatelabProtocolError(
+                    "Matelab download error response does not match the Integration Contract.",
+                    payload=sanitized_payload,
+                ) from None
+            if (
+                code == 5
+                and access_token is not None
+                and operation.retry_on_access_expired
+                and allow_access_expired_retry
+            ):
+                _ = await self.refresh(force=True, stale_access_token=access_token)
+                return await self._stream(
+                    operation,
+                    payload=payload,
+                    range_header=range_header,
+                    sensitive_values=sensitive_values,
+                    allow_access_expired_retry=False,
+                )
+            error_type = MatelabAuthenticationError if code in {1, 5} else MatelabProviderError
+            raise error_type(
+                _redact_text(error_response.msg or "Matelab download failed.", response_sensitive_values),
+                code=code,
+                payload=sanitized_payload,
+            )
+        if operation.media_types is not None and media_type not in operation.media_types:
+            await response.aclose()
+            raise MatelabProtocolError("Matelab returned an unexpected download media type.")
+
+        content_length = self._parse_content_length(response)
+        if response.status_code == 206 and (
+            (self._header(response, "Accept-Ranges") or "").casefold() != "bytes"
+            or content_length is None
+            or content_length < 1
+            or not _CONTENT_RANGE_PATTERN.fullmatch(self._header(response, "Content-Range") or "")
+            or not self._header(response, "Content-Disposition")
+        ):
+            await response.aclose()
+            raise MatelabProtocolError("Matelab returned invalid partial-download metadata.")
+        return DownloadStream(response, content_length=content_length)
+
+    @staticmethod
+    def _parse_content_length(response: httpx.Response) -> int | None:
+        value = SessionTransport._header(response, "Content-Length")
+        if value is None:
+            return None
+        try:
+            content_length = int(value)
+        except ValueError:
+            return None
+        return content_length if content_length >= 0 else None
+
+    @staticmethod
+    def _header(response: httpx.Response, name: str) -> str | None:
+        return cast(str | None, response.headers.get(name))

matelab/client.py

@@ -0,0 +1,191 @@
+from typing import Self
+
+import httpx
+from pydantic import SecretStr, ValidationError
+
+from matelab._generated.models import (
+    AppIdentityResponse,
+    AuthToken,
+    ChatSsoCodeExchangeRequest,
+    ChatSsoCodeExchangeResponse,
+    TokenLoginRequest,
+    TokenLoginResponse,
+    TokenRefreshRequest,
+    TokenRefreshResponse,
+)
+from matelab._transport import Encoding, Operation, SessionTransport, multipart_fields
+from matelab.cloud_drive import CloudDrive
+from matelab.errors import MatelabAuthenticationError, MatelabUsageError
+from matelab.groups import Groups
+from matelab.literature import Literature
+from matelab.models import Identity, Session, Token
+from matelab.notebooks import Notebooks
+from matelab.records import Records
+from matelab.templates import Templates
+from matelab.uploads import Uploads
+from matelab.users import Users
+
+_DEFAULT_BASE_URL = "https://matelab.iphy.ac.cn/api"
+
+_LOGIN = Operation(
+    method="POST",
+    path="/tokens/tokens",
+    encoding=Encoding.MULTIPART,
+    response_model=TokenLoginResponse,
+    success_codes=frozenset({0}),
+    authenticated=False,
+    authentication_errors=True,
+)
+_EXTERNAL_TOKEN_REFRESH = Operation(
+    method="POST",
+    path="/tokens/tokens_refresh",
+    encoding=Encoding.FORM,
+    response_model=TokenRefreshResponse,
+    success_codes=frozenset({0}),
+    authenticated=False,
+    authentication_errors=True,
+)
+_APP_IDENTITY = Operation(
+    method="GET",
+    path="/actions/app",
+    encoding=Encoding.NONE,
+    response_model=AppIdentityResponse,
+    success_codes=frozenset({0}),
+    authentication_errors=True,
+    retry_on_access_expired=True,
+)
+_CHAT_SSO = Operation(
+    method="POST",
+    path="/unlogin_eln/code_check",
+    encoding=Encoding.FORM,
+    response_model=ChatSsoCodeExchangeResponse,
+    success_codes=frozenset({0}),
+    authenticated=False,
+    authentication_errors=True,
+)
+
+
+class AsyncMatelab:
+    """One-user async client that owns at most one process-local Matelab Session.
+
+    Do not share one instance across logical user sessions. Separate instances may share an injected
+    ``httpx.AsyncClient`` while retaining independent Session state and refresh locks.
+    """
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_BASE_URL,
+        *,
+        session: Session | None = None,
+        timeout: float = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """Create a client without performing network I/O.
+
+        ``session`` restores caller-validated persisted state. The caller remains responsible for storing
+        the latest value exposed by :attr:`session`.
+        """
+        self._owns_http_client: bool = http_client is None
+        self._http: httpx.AsyncClient = (
+            http_client
+            if http_client is not None
+            else httpx.AsyncClient(base_url=base_url.rstrip("/"), timeout=timeout)
+        )
+        self._transport: SessionTransport = SessionTransport(self._http, session=session)
+        self.cloud_drive: CloudDrive = CloudDrive(self._transport)
+        self.groups: Groups = Groups(self._transport)
+        self.literature: Literature = Literature(self._transport)
+        self.notebooks: Notebooks = Notebooks(self._transport)
+        self.records: Records = Records(self._transport)
+        self.templates: Templates = Templates(self._transport)
+        self.uploads: Uploads = Uploads(self._transport)
+        self.users: Users = Users(self._transport)
+
+    @property
+    def session(self) -> Session | None:
+        """Return the latest Session, including tokens rotated before a later request failure."""
+        return self._transport.session
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http_client:
+            await self._http.aclose()
+
+    async def authenticate(self, username: str, password: str) -> Session:
+        """Authenticate, install, and return the same latest instance Session."""
+        try:
+            request = TokenLoginRequest(username=username, password=SecretStr(password))
+        except ValidationError:
+            raise MatelabUsageError("Matelab username or password does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _LOGIN,
+            files=multipart_fields({"username": request.username, "password": request.password.get_secret_value()}),
+        )
+        identity = Identity(userid=response.userid, username=response.username, email=response.email)
+        session = self._session_from_wire(response.access, response.refresh, identity=identity)
+        self._transport.session = session
+        return session
+
+    async def exchange_chat_sso_code(self, *, code: str, key: str) -> Session:
+        """Consume one Chat SSO code, install its Session, and return that same Session."""
+        try:
+            request = ChatSsoCodeExchangeRequest(code=code, key=SecretStr(key))
+        except ValidationError:
+            raise MatelabUsageError("Chat SSO credentials do not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _CHAT_SSO, payload={"code": request.code, "key": request.key.get_secret_value()}
+        )
+        identity = Identity(userid=response.userid, username=response.username, email=response.email)
+        session = self._session_from_wire(response.token.access, response.token.refresh, identity=identity)
+        self._transport.session = session
+        return session
+
+    async def bind_external_tokens(self, access_token: str, refresh_token: str) -> Session:
+        """Validate and exchange external tokens, then atomically install the resulting Session.
+
+        The current Session is left unchanged unless both identity checks and the refresh exchange succeed.
+        """
+        if not access_token or not refresh_token:
+            raise MatelabAuthenticationError("Matelab access and refresh tokens must be non-empty.")
+        original_identity = await self._resolve_identity(access_token)
+        refreshed = await self._exchange_external_refresh_token(refresh_token)
+        refreshed_identity = await self._resolve_identity(refreshed.access.token)
+        if refreshed_identity.userid != original_identity.userid:
+            raise MatelabAuthenticationError("Matelab access and refresh tokens belong to different users.")
+        session = self._session_from_wire(refreshed.access, refreshed.refresh, identity=refreshed_identity)
+        self._transport.session = session
+        return session
+
+    async def refresh(self) -> Session:
+        """Force a refresh and return the latest instance Session."""
+        return await self._transport.refresh(force=True)
+
+    async def resolve_identity(self) -> Identity:
+        identity = await self._resolve_identity()
+        session = self._transport.require_session()
+        self._transport.session = Session(access=session.access, refresh=session.refresh, identity=identity)
+        return identity
+
+    async def _resolve_identity(self, access_token: str | None = None) -> Identity:
+        response = await self._transport.request(_APP_IDENTITY, bearer_token=access_token)
+        return Identity(userid=response.user.userid, username=response.user.username, email=response.user.email)
+
+    async def _exchange_external_refresh_token(self, refresh_token: str) -> TokenRefreshResponse:
+        try:
+            request = TokenRefreshRequest(refresh_token=refresh_token)
+        except ValidationError:
+            raise MatelabAuthenticationError("The Matelab refresh token is invalid.") from None
+        return await self._transport.request(_EXTERNAL_TOKEN_REFRESH, payload=request.model_dump(mode="json"))
+
+    @staticmethod
+    def _session_from_wire(access: AuthToken, refresh: AuthToken, *, identity: Identity | None) -> Session:
+        return Session(
+            access=Token(value=access.token, expires_at_ms=access.expiredAt),
+            refresh=Token(value=refresh.token, expires_at_ms=refresh.expiredAt),
+            identity=identity,
+        )