mtx-api-py 0.4.0__py3-none-any.whl

mtx_api/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from mtx_api.client.mtx_client import MTXClient
+from mtx_api.models.errors import (
+    ApiDecodingError,
+    ApiError,
+    InvalidEmailError,
+    MissingBaseUrlError,
+    MissingClientIdError,
+    MissingJurisdictionCodesError,
+    MissingJwtSecretError,
+)
+
+__all__ = [
+    "MTXClient",
+    "ApiError",
+    "ApiDecodingError",
+    "InvalidEmailError",
+    "MissingBaseUrlError",
+    "MissingClientIdError",
+    "MissingJwtSecretError",
+    "MissingJurisdictionCodesError",
+]
+
+__version__ = "0.4.0"

mtx_api/client/__init__.py

@@ -0,0 +1,3 @@
+from mtx_api.client.mtx_client import MTXClient
+
+__all__ = ["MTXClient"]

mtx_api/client/_auth_client.py

@@ -0,0 +1,230 @@
+import re
+from base64 import b64decode
+
+import jwt
+
+from mtx_api.client._mtx_http_client import Method, MtxHttpClient
+from mtx_api.models.auth import Authentication
+from mtx_api.models.errors import InvalidEmailError, MissingArgumentError, MissingJwtSecretError
+
+
+class AuthClient:
+    def __init__(self, client: MtxHttpClient):
+        self._client: MtxHttpClient = client
+
+    async def login_anonymous(
+        self,
+        *,
+        device_id: str,
+    ) -> Authentication:
+        """Authenticates a user anonymously using a unique device identifier.
+
+        Use this tool to log in a user who does not have a registered account,
+        identifying them solely by their device ID. This enables access to
+        features that require authentication without user registration.
+
+        Args:
+            device_id: A stable and unique identifier for the device.
+
+        Returns:
+            Authentication: A model containing access and refresh tokens.
+
+        Raises:
+            MissingArgumentError: If `device_id` is empty or None.
+        """
+        if not device_id:
+            raise MissingArgumentError("device_id")
+
+        return await self._client.http_request(
+            method=Method.POST,
+            path="login-anonymous",
+            model=Authentication,
+            body={
+                "client_id": self._client.client_id,
+                "device_id": device_id,
+            },
+        )
+
+    async def login_refresh(
+        self,
+        *,
+        refresh_token: str,
+    ) -> Authentication:
+        """Refreshes an existing authentication session using a valid refresh token.
+
+        Use this tool to obtain a new access token when the current one has expired,
+        allowing the user's session to continue without requiring re-authentication.
+
+        Args:
+            refresh_token: The token issued during a previous authentication, used
+                to refresh the session.
+
+        Returns:
+            Authentication: A model containing access and refresh tokens.
+
+        Raises:
+            MissingArgumentError: If `refresh_token` is empty or None.
+        """
+        if not refresh_token:
+            raise MissingArgumentError("refresh_token")
+        return await self._client.http_request(
+            method=Method.POST,
+            path="oauth/v2/token",
+            model=Authentication,
+            body={
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+                "client_id": self._client.client_id,
+            },
+        )
+
+    async def login_jwt(
+        self,
+        *,
+        email: str,
+        first_name: str | None = None,
+        last_name: str | None = None,
+        register: bool | None = None,
+        legal_terms_accepted: bool | None = None,
+    ) -> Authentication:
+        """Authenticates a user using a signed JSON Web Token (JWT).
+
+        Use this tool for trusted server-side authentication or Single Sign-On (SSO)
+        integration. It facilitates logging in or registering a user based on their
+        email address.
+
+        Args:
+            email: The user's email address.
+            first_name: Optional user's first name.
+            last_name: Optional user's last name.
+            register: Optional. If True, registers the user if they do not exist.
+            legal_terms_accepted: Optional. Whether the user has accepted the legal terms.
+
+        Returns:
+            Authentication: A model containing access and refresh tokens.
+
+        Raises:
+            InvalidEmailError: If the provided email format is invalid.
+            MissingJwtSecretError: If the JWT secret is not configured in the client.
+        """
+        if re.fullmatch(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}", email) is None:
+            raise InvalidEmailError()
+        user_data = {
+            k: v
+            for k, v in {
+                "username": email,
+                "first_name": first_name,
+                "last_name": last_name,
+                "register": register,
+                "legal_terms_accepted": legal_terms_accepted,
+            }.items()
+            if v is not None
+        }
+
+        secret = self._client.jwt_secret
+        if not secret:
+            raise MissingJwtSecretError()
+        while len(secret) % 4 != 0:
+            secret += "="
+        dec = b64decode(secret)
+        token = jwt.encode(user_data, dec, algorithm="HS256")
+
+        return await self._client.http_request(
+            method=Method.POST,
+            path="login-jwt",
+            model=Authentication,
+            body={
+                "client_id": self._client.client_id,
+                "token": token,
+            },
+        )
+
+    async def register(
+        self,
+        *,
+        username: str,
+        password: str,
+        first_name: str,
+        last_name: str,
+        legal_terms_accepted: bool,
+        jurisdiction_code: str | None = None,
+    ) -> Authentication:
+        """Registers a new user account and immediately authenticates the user.
+
+        Use this tool to create a new user profile with the provided credentials
+        and personal information. This action also logs the user in.
+
+        Args:
+            username: The email address to use as the username.
+            password: The password for the new account.
+            first_name: The user's first name.
+            last_name: The user's last name.
+            legal_terms_accepted: Must be True to indicate acceptance of legal terms.
+            jurisdiction_code: Optional jurisdiction code for the user.
+
+        Returns:
+            Authentication: A model containing access and refresh tokens.
+
+        Raises:
+            MissingArgumentError: If any required argument (username, password,
+                first_name, last_name) is missing.
+        """
+        if not username:
+            raise MissingArgumentError("username")
+        if not password:
+            raise MissingArgumentError("password")
+        if not first_name:
+            raise MissingArgumentError("first_name")
+        if not last_name:
+            raise MissingArgumentError("last_name")
+
+        return await self._client.http_request(
+            method=Method.POST,
+            path="login",
+            model=Authentication,
+            body={
+                "client_id": self._client.client_id,
+                "username": username,
+                "password": password,
+                "register": "true",
+                "first_name": first_name,
+                "last_name": last_name,
+                "legal_terms_accepted": "true" if legal_terms_accepted else None,
+                "jurisdiction_id": jurisdiction_code,
+            },
+        )
+
+    async def login(
+        self,
+        *,
+        username: str,
+        password: str,
+    ) -> Authentication:
+        """Authenticates a user using their username (email) and password.
+
+        Use this tool for standard user login to obtain access credentials.
+
+        Args:
+            username: The user's email address.
+            password: The user's password.
+
+        Returns:
+            Authentication: A model containing access and refresh tokens.
+
+        Raises:
+            MissingArgumentError: If `username` or `password` is missing.
+        """
+        if not username:
+            raise MissingArgumentError("username")
+        if not password:
+            raise MissingArgumentError("password")
+        return await self._client.http_request(
+            method=Method.POST,
+            path="login",
+            model=Authentication,
+            body={
+                "client_id": self._client.client_id,
+                "username": username,
+                "password": password,
+            },
+        )

mtx_api/client/_base_client.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from mtx_api.client._mtx_http_client import Method, MtxHttpClient
+from mtx_api.models.base import EmptyResponse, TextResponse
+
+
+class BaseClient:
+    def __init__(self, client: MtxHttpClient):
+        self._client: MtxHttpClient = client
+
+    async def status(
+        self,
+        *,
+        access_token: str | None = None,
+    ) -> bool:
+        """Checks the operational status of the platform.
+
+        Verifies if the platform is running and reachable. Use this tool
+        to confirm platform availability before performing other operations.
+
+        Args:
+            access_token: Optional token used for authentication. If not provided, the operation
+                will be made without authentication.
+
+        Returns:
+            True if the platform is available and the operation succeeds.
+        """
+        await self._client.http_request(
+            method=Method.GET,
+            path="",
+            model=EmptyResponse,
+            access_token=access_token,
+        )
+        return True
+
+    async def openapi(self) -> str:
+        """Retrieves the OpenAPI specification of the platform.
+
+        Fetches the complete OpenAPI documentation in plain text. This provides details on available
+        tools, operation structures, and expected responses.
+
+        Returns:
+            The OpenAPI document content as a string.
+        """
+        resp = await self._client.http_request(
+            method=Method.GET,
+            path="openapi",
+            model=TextResponse,
+        )
+        return resp.text

mtx_api/client/_jurisdiction_client.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from mtx_api.client._mtx_http_client import Method, MtxHttpClient
+from mtx_api.models.errors import MissingJurisdictionCodesError
+from mtx_api.models.jurisdiction import Jurisdiction, JurisdictionList
+
+
+class JurisdictionClient:
+    def __init__(self, client: MtxHttpClient):
+        self._client: MtxHttpClient = client
+
+    async def list(
+        self,
+        *,
+        access_token: str | None = None,
+        lat: float | None = None,
+        lng: float | None = None,
+    ) -> JurisdictionList:
+        """Retrieves a list of jurisdictions from the platform.
+
+        This tool allows you to list all available jurisdictions or find those closest to a
+        specific location if coordinates are provided.
+
+        Args:
+            access_token: Optional token used for authentication. If not provided,
+                the operation will be made without authentication.
+            lat: Optional latitude coordinate to filter jurisdictions by proximity.
+            lng: Optional longitude coordinate to filter jurisdictions by proximity.
+
+        Returns:
+            JurisdictionList: A collection of Jurisdiction objects with basic details.
+        """
+        return await self._client.http_request(
+            method=Method.GET,
+            path="jurisdictions",
+            model=JurisdictionList,
+            access_token=access_token,
+            query_params={
+                "lat": lat,
+                "long": lng,
+            },
+        )
+
+    async def detail(
+        self,
+        *,
+        access_token: str | None = None,
+        jurisdiction_code: str,
+    ) -> Jurisdiction:
+        """Retrieves detailed information for a specific jurisdiction.
+
+        This tool fetches the complete details of a jurisdiction using its unique code.
+        Use this tool when you need more information about a specific jurisdiction than what is
+        provided in the list.
+
+        Args:
+            access_token: Optional token used for authentication. If not provided,
+                the operation will be made without authentication.
+            jurisdiction_code: The unique string code of the jurisdiction to query.
+
+        Raises:
+            MissingJurisdictionCodesError: If the provided jurisdiction_code is empty.
+
+        Returns:
+            Jurisdiction: An object containing comprehensive information about the jurisdiction.
+        """
+        if not jurisdiction_code:
+            raise MissingJurisdictionCodesError()
+        return await self._client.http_request(
+            method=Method.GET,
+            path=f"jurisdictions/{jurisdiction_code}",
+            model=Jurisdiction,
+            access_token=access_token,
+        )

mtx_api/client/_jurisdiction_elements_client.py

@@ -0,0 +1,41 @@
+from mtx_api.client._mtx_http_client import Method, MtxHttpClient
+from mtx_api.models.errors import MissingJurisdictionCodesError
+from mtx_api.models.jurisdiction import JurisdictionElementList
+
+
+class JurisdictionElementsClient:
+    def __init__(self, client: MtxHttpClient):
+        self._client: MtxHttpClient = client
+
+    async def list(
+        self,
+        *,
+        access_token: str | None = None,
+        jurisdiction_code: str,
+    ) -> JurisdictionElementList:
+        """Retrieves jurisdiction elements associated with a specific jurisdiction code.
+
+        Use this tool to find all jurisdiction elements linked to a given jurisdiction code
+        from the platform.
+
+        Args:
+            access_token: Optional token used for authentication. If not provided, the operation
+                will be made without authentication.
+            jurisdiction_code: The unique string code of the jurisdiction to query.
+
+        Returns:
+            JurisdictionElementList: An object containing the list of retrieved
+                jurisdiction elements.
+
+        Raises:
+            MissingJurisdictionCodesError: If the `jurisdiction_code` argument is missing or empty.
+        """
+        if not jurisdiction_code:
+            raise MissingJurisdictionCodesError()
+
+        return await self._client.http_request(
+            method=Method.GET,
+            path=f"jurisdiction/{jurisdiction_code}/jurisdiction-elements",
+            model=JurisdictionElementList,
+            access_token=access_token,
+        )

mtx_api/client/_location_client.py

@@ -0,0 +1,61 @@
+from mtx_api.client._mtx_http_client import Method, MtxHttpClient
+from mtx_api.models.additional_data import LocationAdditionalDataList
+from mtx_api.models.errors import MissingJurisdictionElementIdError
+
+
+class LocationClient:
+    def __init__(self, client: MtxHttpClient):
+        self.client: MtxHttpClient = client
+
+    async def resolve(
+        self,
+        *,
+        jurisdiction_element_id: str,
+        formatted_address: str | None = None,
+        lat: float | None = None,
+        lng: float | None = None,
+    ) -> LocationAdditionalDataList:
+        """
+        Retrieves latitude and longitude information from an address, or vice versa.
+
+        This tool fetches location-specific questions configured for a
+        jurisdiction element. You can identify the location by providing either a formatted
+        address, geographic coordinates (lat, lng), or both. Regardless of which parameters
+        you provide, the tool always returns the complete location information including
+        formatted address, geographic coordinates, and the list of additional data questions.
+
+        Use this tool when you need to know what additional information should be collected
+        for a specific location.
+
+        Args:
+            jurisdiction_element_id: The unique identifier string of the jurisdiction element
+                where the location is being queried.
+            formatted_address: Optional complete address string in human-readable format
+                to identify the location.
+            lat: Optional latitude coordinate as a decimal number to identify the location.
+                Must be provided together with lng.
+            lng: Optional longitude coordinate as a decimal number to identify the location.
+                Must be provided together with lat.
+
+        Returns:
+            LocationAdditionalDataList: A collection of location entries. Each entry always
+                contains the formatted address, geographic coordinates (latitude and longitude),
+                and a list of additional data questions configured for that location, regardless
+                of which input parameters were used to identify the location.
+
+        Raises:
+            MissingJurisdictionElementIdError: If jurisdiction_element_id is empty or not provided.
+        """
+        if not jurisdiction_element_id:
+            raise MissingJurisdictionElementIdError()
+        return await self.client.http_request(
+            method=Method.GET,
+            path="location-additional-data",
+            model=LocationAdditionalDataList,
+            query_params={
+                "jurisdiction_element_id": jurisdiction_element_id,
+                "formatted_address": formatted_address,
+                "lat": lat,
+                "lng": lng,
+            },
+        )

mtx_api/client/_mtx_http_client.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping, Sequence
+from enum import Enum
+from typing import TypeVar
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from mtx_api.models.base import EmptyResponse, TextResponse
+from mtx_api.models.errors import (
+    ApiDecodingError,
+    ApiError,
+    MissingBaseUrlError,
+    MissingClientIdError,
+)
+from mtx_api.settings import MTXSettings
+
+M = TypeVar("M", bound=BaseModel)
+
+
+class Method(Enum):
+    PUT = "PUT"
+    GET = "GET"
+    POST = "POST"
+
+
+class MtxHttpClient:
+    def __init__(
+        self,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        base_url: str | None = None,
+        client_id: str | None = None,
+        jwt_secret: str | None = None,
+    ) -> None:
+        settings = MTXSettings()
+
+        base_url_value = base_url or settings.base_url
+        if not base_url_value:
+            raise MissingBaseUrlError()
+        self._base_url: str = base_url_value.rstrip("/")
+
+        client_id_value = client_id or settings.client_id
+        if not client_id_value:
+            raise MissingClientIdError()
+        self._client_id: str = client_id_value
+
+        self._jwt_secret: str | None = jwt_secret or settings.jwt_secret
+
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+        self.logger = logging.getLogger("mtx_logs")
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=30.0,
+            transport=transport,
+            follow_redirects=True,
+        )
+
+    async def __aenter__(self) -> MtxHttpClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: object | None,
+    ) -> None:
+        await self._client.aclose()
+
+    @property
+    def client_id(self) -> str:
+        return self._client_id
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def jwt_secret(self) -> str | None:
+        return self._jwt_secret
+
+    async def http_request(
+        self,
+        *,
+        method: Method,
+        path: str,
+        model: type[M],
+        access_token: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        body: Mapping[str, object] | None = None,
+        query_params: Mapping[str, object] | None = None,
+        files: Mapping[str, tuple[str, bytes]] | None = None,
+    ) -> M:
+        if not path.startswith("/"):
+            path = f"/{path}"
+        try:
+            auth_header = {"Authorization": f"Bearer {access_token}"} if access_token else {}
+            headers = {
+                **auth_header,
+                **(headers or {}),
+                "X-CLIENT-ID": self._client_id,
+            }
+
+            is_multipart = files is not None
+
+            if not is_multipart:
+                headers["Content-type"] = "application/json"
+
+            def normalize(value: object) -> str | None:
+                if value is None:
+                    return None
+                if isinstance(value, bool):
+                    return "true" if value else "false"
+                if isinstance(value, list):
+                    return ",".join(map(str, value)) if value else None
+                return str(value)
+
+            params = {k: normalize(v) for k, v in query_params.items()} if query_params else None
+
+            body = {k: v for k, v in body.items() if v is not None} if body else None
+
+            req = self._client.build_request(
+                method=method.value,
+                url=path,
+                headers=headers,
+                json=body if body and not is_multipart else None,
+                data=body if body and is_multipart else None,
+                params={k: v for k, v in params.items() if v is not None} if params else None,
+                files=files,
+            )
+
+            if is_multipart:
+                req.extensions["mtx_file_names"] = files
+                req.extensions["mtx_form_fields"] = body
+
+            self.log_as_curl(req)
+            resp = await self._client.send(req)
+            resp.raise_for_status()
+            self.log_response(resp)
+            try:
+                if model is EmptyResponse:
+                    return model()
+                elif model is TextResponse:
+                    return model(text=resp.text)
+                else:
+                    return model.model_validate_json(resp.text)
+            except (ValidationError, ValueError) as de:
+                raise ApiDecodingError(str(de))
+        except httpx.HTTPStatusError as e:
+            resp = e.response
+            api_error = ApiError(body=resp.text, status_code=resp.status_code)
+            self.log_error(api_error)
+            raise api_error from e
+
+    def log_as_curl(
+        self,
+        request: httpx.Request,
+    ) -> None:
+        header_parts = " ".join([f'-H "{k}: {v}"' for k, v in request.headers.items()])
+        content_type = request.headers.get("content-type", "").lower()
+
+        def replace_quotes(s: str) -> str:
+            return s.replace("'", "'\"'\"'")
+
+        data_part = ""
+        if content_type.startswith("multipart/form-data"):
+            extensions = request.extensions
+            parts = []
+
+            form_meta = extensions.get("mtx_form_fields") or {}
+            parts.extend([f"{k}={v}" for k, v in form_meta.items()])
+
+            files_meta = extensions.get("mtx_file_names") or {}
+            parts.extend([f"{k}=@{v[0]}" for k, v in files_meta.items()])
+
+            data_part = " ".join([f"-F '{replace_quotes(p)}'" for p in parts])
+        elif request.content:
+            data = request.content.decode()
+            data_part = f" -d '{replace_quotes(data)}'"
+
+        self.logger.info(f"HTTP {request.method} to {request.url.path}")
+        self.logger.debug(f"curl -X {request.method} {str(request.url)} {header_parts} {data_part}")
+
+    def log_response(self, resp: httpx.Response) -> None:
+        try:
+            json_obj = json.loads(resp.text)
+            formatted_json = json.dumps(json_obj, indent=4)
+            self.logger.debug(f"Response JSON: {resp.status_code} {formatted_json}")
+        except json.JSONDecodeError:
+            self.logger.debug(f"Response Text: {resp.status_code} {resp.text}")
+
+    def log_error(self, e: ApiError) -> None:
+        self.logger.error(f"{type(e).__name__}: {e}")
+
+
+def array_query_param(key: str, value: Sequence[object] | None) -> dict[str, object]:
+    return {} if value is None else {f"{key}[{i}]": v for i, v in enumerate(value)}