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

mtx_api/client/mtx_client.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import httpx
+
+from mtx_api.client._auth_client import AuthClient
+from mtx_api.client._base_client import BaseClient
+from mtx_api.client._jurisdiction_client import JurisdictionClient
+from mtx_api.client._jurisdiction_elements_client import JurisdictionElementsClient
+from mtx_api.client._location_client import LocationClient
+from mtx_api.client._mtx_http_client import MtxHttpClient
+from mtx_api.client._request_client import RequestClient
+from mtx_api.client._service_client import ServiceClient
+from mtx_api.client._typology_client import TypologyClient
+from mtx_api.client._user_client import UserClient
+
+
+class MTXClient:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        client_id: str | None = None,
+        jwt_secret: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._http_client = MtxHttpClient(
+            base_url=base_url,
+            client_id=client_id,
+            jwt_secret=jwt_secret,
+            transport=transport,
+        )
+        self.base = BaseClient(self._http_client)
+        self.auth = AuthClient(self._http_client)
+        self.user = UserClient(self._http_client)
+        self.location = LocationClient(self._http_client)
+        self.services = ServiceClient(self._http_client)
+        self.typologies = TypologyClient(self._http_client)
+        self.jurisdictions = JurisdictionClient(self._http_client)
+        self.jurisdiction_elements = JurisdictionElementsClient(self._http_client)
+        self.requests = RequestClient(self._http_client)
+
+    async def __aenter__(self) -> MTXClient:
+        await self._http_client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: object | None,
+    ) -> None:
+        await self._http_client.__aexit__(exc_type, exc, tb)

mtx_api/models/additional_data.py

@@ -0,0 +1,334 @@
+from abc import ABC
+from collections.abc import Sequence
+from typing import Any
+
+from pydantic import AliasChoices, Field, RootModel, field_serializer
+
+from mtx_api.models.base import DatetimeField, ImmutableBaseModel
+from mtx_api.models.common import Location, Tag
+
+
+class Question(ImmutableBaseModel):
+    """
+    Represents a configurable question that can be asked when creating a request.
+
+    Questions are used to gather additional information from users during the request
+    creation process. They can have different types (label, text, number, etc.) and may include
+    predefined possible answers.
+    """
+
+    type: str | None = Field(
+        default=None,
+        description="The type of question input (label, number, boolean, color, datetime, "
+        "position, singleValueList, multiValueList, url, signature, image, "
+        "imageGallery, audioClip or videoClip).",
+    )
+    active: bool | None = Field(
+        default=None,
+        description="Whether this question is currently active and should be used.",
+    )
+    code: str | None = Field(
+        default=None,
+        description="Unique code identifier for the question.",
+    )
+    help_text: str | None = Field(
+        default=None,
+        description="Additional help text or instructions given to the user.",
+    )
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the question.",
+    )
+    question: str | None = Field(
+        default=None,
+        description="The question text given to the user.",
+    )
+    tags: list[Tag] | None = Field(
+        default=None,
+        description="Classification tags associated with this question.",
+    )
+    possible_answers: list["PossibleAnswer"] | None = Field(
+        default=None,
+        description=(
+            "List of predefined answer options for singleValueList or"
+            " multiValueList type questions."
+        ),
+    )
+
+
+class ConfigurableQuestion(ImmutableBaseModel):
+    """
+    Represents a question with its configuration settings.
+
+    This model extends a base question with additional metadata that controls
+    how and when the question is given in different contexts (forms, details...).
+    """
+
+    editable: bool | None = Field(
+        default=None,
+        description="Whether the answer to this question can be edited after initial submission.",
+    )
+    omit_in_detail: bool | None = Field(
+        default=None,
+        validation_alias=AliasChoices("omit_in_detail", "hidden_in_open010_detail"),
+        serialization_alias="hidden_in_open010_detail",
+        description=(
+            "Whether this question should be hidden when the request details. "
+            "When True, the question and its answer will not appear in the detail of a request."
+        ),
+    )
+    omit_in_form: bool | None = Field(
+        default=None,
+        validation_alias=AliasChoices("omit_in_form", "hidden_in_open010_form"),
+        serialization_alias="hidden_in_open010_form",
+        description=(
+            "Whether this question should be hidden in the request. "
+            "When True, the question will not be given to users when creating a new request."
+        ),
+    )
+    question: Question | None = Field(
+        default=None,
+        description="The underlying question definition with its content and options.",
+    )
+    required: bool | None = Field(
+        default=None,
+        description="Whether an answer to this question is mandatory for submission.",
+    )
+    default_value: str | None = Field(
+        default=None,
+        description="The default value pre-filled for this question.",
+    )
+    response_attribute: str | None = Field(
+        default=None,
+        description="The attribute name where the response should be stored.",
+    )
+
+
+class AdditionalData(ImmutableBaseModel):
+    """
+    Represents a collection of additional data questions for a service.
+
+    This model defines a set of configurable questions that can be asked
+    when creating or updating requests, along with metadata about
+    required variables and platform integration.
+    """
+
+    required_variables: list[str] | None = Field(
+        default=None,
+        alias="requiredVariables",
+        description="List of variable names that must be provided to use this additional data set.",
+    )
+    configurable_questions: list[ConfigurableQuestion] | None = Field(
+        default=None,
+        description="List of questions with their configuration.",
+    )
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the additional data set.",
+    )
+    name: str | None = Field(
+        default=None,
+        description="Name of the additional data set.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Description of what this additional data set is used for.",
+    )
+
+
+class PossibleAnswer(ImmutableBaseModel):
+    """
+    Represents a possible answer option for a singleValueList-type or multiValueList-type question.
+
+    When a question has predefined answers, each option is represented by this model.
+    Selecting an answer may trigger additional questions based on the conditional logic.
+    """
+
+    value: str | None = Field(
+        default=None,
+        description="The value of the answer option.",
+    )
+    next_question_list: AdditionalData | None = Field(
+        default=None,
+        description="Additional questions if this answer is selected.",
+    )
+
+
+class AdditionalDataAnswer(ImmutableBaseModel):
+    """
+    Represents an answer provided to an additional data question.
+
+    This model contains the user's response to a configurable question,
+    including the question details and the value provided.
+    """
+
+    type: str | None = Field(
+        default=None,
+        description=(
+            "The type of answer value (label, number, boolean, color, datetime, "
+            "position, singleValueList, multiValueList, url, signature, image, "
+            "imageGallery, audioClip or videoClip)."
+        ),
+    )
+    value: Any | None = Field(
+        default=None,
+        description=(
+            "The answer value, which can be of various types depending on the question type."
+        ),
+    )
+    question: Question | None = Field(
+        default=None,
+        description="The question that this answer corresponds to.",
+    )
+
+
+class AdditionalDataValue(ImmutableBaseModel, ABC):
+    """
+    Base model for additional data values when creating or updating requests.
+
+    This abstract model provides the foundation for different types of additional
+    data values that can be submitted with requests.
+    """
+
+    question_id: str = Field(
+        validation_alias=AliasChoices("question_id", "question"),
+        serialization_alias="question",
+        description="Unique identifier of the question this value answers.",
+    )
+
+
+class AdditionalDataSingleValue(AdditionalDataValue):
+    """
+    Represents a single-value answer to an additional data question.
+
+    This model is used when submitting answers that accept a single text value.
+    """
+
+    value: str = Field(
+        description="The single text value answering the question.",
+    )
+
+
+class AdditionalDataMultivalue(AdditionalDataValue):
+    """
+    Represents a multi-value answer to an additional data question.
+
+    This model is used when submitting answers that accept multiple values.
+    """
+
+    value: Sequence[str] = Field(
+        description="List of selected values answering the question.",
+    )
+
+
+class AdditionalDataDatetime(AdditionalDataValue):
+    """
+    Represents a datetime answer to an additional data question.
+
+    This model is used when submitting date or datetime values as answers,
+    automatically serialized to ISO format with timezone.
+    """
+
+    value: DatetimeField = Field(
+        description=(
+            "The datetime value answering the question, serialized in ISO format with timezone."
+        ),
+    )
+
+
+class AdditionalDataLocation(AdditionalDataValue):
+    """
+    Represents a geographic location answer to an additional data question.
+
+    This model is used when submitting location coordinates as answers.
+    The coordinates are stored separately but serialized as a nested object
+    in the value field.
+    """
+
+    lat: float = Field(
+        exclude=True,
+        description="Latitude coordinate.",
+    )
+    lng: float = Field(
+        exclude=True,
+        description="Longitude coordinate.",
+    )
+    srs: str | None = Field(
+        default="3857",
+        exclude=True,
+        description="Spatial Reference System identifier, default is '3857'.",
+    )
+
+    def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
+        data = super().model_dump(*args, **kwargs)
+        data["value"] = {
+            "lat": self.lat,
+            "lng": self.lng,
+            "srs": self.srs,
+        }
+        return data
+
+
+class AdditionalDataAudioClip(AdditionalDataValue):
+    """
+    Represents an audio clip answer to an additional data question.
+
+    This model is used when submitting audio file references as answers.
+    """
+
+    value: str = Field(
+        description="The audio clip URL to be submitted as the answer.",
+    )
+
+    @field_serializer("value")
+    def s(self, value: str) -> dict[str, dict[str, str]]:
+        return {"audio_clip": {"es": value}}
+
+
+class AdditionalDataVideoClip(AdditionalDataValue):
+    """
+    Represents a video clip answer to an additional data question.
+
+    This model is used when submitting video file references as answers.
+    """
+
+    value: str = Field(
+        description="The video clip URL to be submitted as the answer.",
+    )
+
+    @field_serializer("value")
+    def s(self, value: str) -> dict[str, dict[str, str]]:
+        return {"video_clip": {"es": value}}
+
+
+class LocationAdditionalData(ImmutableBaseModel):
+    """
+    Represents location-specific additional data and questions.
+
+    This model contains additional data questions that are specific to a particular
+    location, including the formatted address and geographic coordinates.
+    """
+
+    formatted_address: str | None = Field(
+        default=None,
+        description="The formatted address string of the location.",
+    )
+    data: list[AdditionalDataAnswer] | None = Field(
+        default=None,
+        description="List of additional data answers associated with this location.",
+    )
+    location: Location | None = Field(
+        default=None,
+        description="The geographic coordinates of the location.",
+    )
+
+
+class LocationAdditionalDataList(RootModel[list[LocationAdditionalData]]):
+    """
+    A collection of LocationAdditionalData objects.
+
+    This model represents a list of location-specific additional data returned
+    when querying location-based information for a jurisdiction element.
+    """
+
+    pass

mtx_api/models/auth.py

@@ -0,0 +1,84 @@
+from typing import Literal
+
+from pydantic import AliasChoices, Field
+
+from mtx_api.models.base import ImmutableBaseModel
+
+
+class Authentication(ImmutableBaseModel):
+    """
+    Represents authentication credentials for a user session.
+
+    This model contains the tokens required to authenticate operations on the platform.
+    The access token is used for authorized operations, while the refresh token allows
+    obtaining a new access token when it expires.
+    """
+
+    access_token: str = Field(
+        description="The bearer token used to authenticate operations on the platform.",
+    )
+    refresh_token: str = Field(
+        description="The token used to obtain a new access token when the current one expires.",
+    )
+    expires_in: int = Field(
+        description="The number of seconds until the access token expires.",
+    )
+    token_type: str = Field(
+        description="The type of token, typically 'bearer' for OAuth2 tokens.",
+    )
+
+
+type Gender = Literal["male", "female", "other", "not_specified"]
+
+
+class Profile(ImmutableBaseModel):
+    """
+    Represents a user profile with personal information and account details.
+
+    This model contains all the personal and account information associated with
+    a user on the platform. It includes identification, contact information,
+    and demographic data.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the user profile.",
+    )
+    email: str | None = Field(
+        default=None,
+        description="The user's email address used for contact and authentication.",
+    )
+    username: str | None = Field(
+        default=None,
+        description="The user's chosen username, typically their email address.",
+    )
+    first_name: str | None = Field(
+        default=None,
+        description="The user's first name or given name.",
+    )
+    last_name: str | None = Field(
+        default=None,
+        description="The user's last name or family name.",
+    )
+    twitter_nickname: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("twitter_nickname", "twitterNickname"),
+        serialization_alias="twitterNickname",
+        description="The user's Twitter handle or social media nickname visible to others.",
+    )
+    anonymous: bool | None = Field(
+        default=None,
+        description="Whether the user is logged in anonymously without a registered account.",
+    )
+    phone: str | None = Field(
+        default=None,
+        description="The user's primary phone number for contact purposes.",
+    )
+    gender: Gender | None = Field(
+        default=None,
+        description="The user's gender identification.",
+    )
+    birthday: str | None = Field(
+        default=None,
+        description="The user's date of birth in format YYYY-MM-DD.",
+    )

mtx_api/models/base.py

@@ -0,0 +1,26 @@
+from datetime import UTC, datetime
+from typing import Annotated
+
+from pydantic import BaseModel, PlainSerializer
+
+
+class ImmutableBaseModel(BaseModel):
+    model_config = {
+        "frozen": True,
+    }
+
+
+class EmptyResponse(ImmutableBaseModel):
+    pass
+
+
+class TextResponse(ImmutableBaseModel):
+    text: str
+
+
+DatetimeField = Annotated[
+    datetime,
+    PlainSerializer(
+        lambda v: v.astimezone(UTC).isoformat() if v else None,
+    ),
+]

mtx_api/models/common.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from mtx_api.models.base import ImmutableBaseModel
+
+
+class Tag(ImmutableBaseModel):
+    """
+    Represents a label or category tag for classification purposes.
+
+    Tags are used throughout the platform to categorize and filter various
+    entities such as questions, services, or other content items.
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="The name of the tag.",
+    )
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the tag.",
+    )
+
+
+class User(ImmutableBaseModel):
+    """
+    Represents a basic user reference with minimal information.
+
+    This simplified model is used when referencing a user in contexts where
+    only the identifier is needed, without full profile details.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the user.",
+    )
+
+
+class Location(ImmutableBaseModel):
+    """
+    Represents geographic coordinates for a location on Earth.
+
+    This model uses the standard GPS coordinates system
+    with latitude and longitude.
+    """
+
+    lat: float | None = Field(
+        default=None,
+        description="Latitude coordinate.",
+    )
+    lng: float | None = Field(
+        default=None,
+        description="Longitude coordinate.",
+    )
+
+
+class LegalText(ImmutableBaseModel):
+    """
+    Represents the legal documentation content required for platform usage.
+
+    This model encapsulates all legal text content that users must review and
+    accept to use the platform. Each field may contain plain text, formatted
+    text, or links to external legal documents.
+    """
+
+    privacy_policy: str | None = Field(
+        default=None,
+        description=(
+            "The privacy policy content describing how user data is collected, "
+            "processed, and protected. May be plain text or a link to the full document."
+        ),
+    )
+    terms_of_use: str | None = Field(
+        default=None,
+        description=(
+            "The terms of use content outlining the rules and conditions for using "
+            "the platform. May be plain text or a link to the full document."
+        ),
+    )
+    cookies_policy: str | None = Field(
+        default=None,
+        description=(
+            "The cookies policy content explaining how cookies are used on the platform. "
+            "May be plain text or a link to the full document."
+        ),
+    )
+
+
+class LegalTerms(ImmutableBaseModel):
+    """
+    Container model for platform legal terms and conditions.
+
+    This model serves as a wrapper for all legal documentation that users must
+    accept before using the platform. It is typically retrieved when showing
+    legal information during registration or when terms have been updated.
+    """
+
+    legal_text: LegalText | None = Field(
+        default=None,
+        description="The complete legal documentation including privacy policy,"
+        " terms of use, and cookies policy.",
+    )