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

mtx_api/models/errors.py

@@ -0,0 +1,117 @@
+# Modelos y excepciones de error extraídos de models.py
+import json
+
+from pydantic import AliasChoices, Field, ValidationError
+
+from mtx_api.models.base import ImmutableBaseModel
+
+
+class ApiErrorReason(ImmutableBaseModel):
+    """
+    Represents detailed information about an error from the platform.
+
+    This model captures the complete error context including HTTP status code,
+    platform-specific error code, and a human-readable description. It is used
+    to provide structured error information when operations fail.
+    """
+
+    status_code: int = Field(
+        description="The HTTP status code of the error response (e.g., 400, 404, 500).",
+    )
+    code: int | None = Field(
+        default=None,
+        validation_alias=AliasChoices("error_code", "code"),
+        description="Platform-specific error code for programmatic error handling.",
+    )
+    description: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("error_msg", "description", "message"),
+        description="Human-readable description of the error explaining what went wrong.",
+    )
+
+
+class ApiError(Exception):
+    def __init__(self, body: str, status_code: int):
+        super().__init__()
+        self.reason = self.parse_reason(body, status_code)
+
+    @staticmethod
+    def parse_reason(body: str, status_code: int) -> ApiErrorReason | None:
+        if body:
+            try:
+                obj = json.loads(body)
+                if isinstance(obj, list):
+                    obj = obj[0] if obj else {}
+                if obj is None or not isinstance(obj, dict):
+                    obj = {}
+                if "status_code" not in obj:
+                    obj["status_code"] = status_code
+                reason = ApiErrorReason.model_validate(obj)
+            except (ValidationError, ValueError):
+                reason = ApiErrorReason(description=str(body), status_code=status_code)
+        else:
+            reason = ApiErrorReason(status_code=status_code)
+        return reason
+
+    @property
+    def code(self) -> int | None:
+        return self.reason.code if self.reason else None
+
+    @property
+    def description(self) -> str | None:
+        return self.reason.description if self.reason else None
+
+    @property
+    def status_code(self) -> int | None:
+        return self.reason.status_code if self.reason else None
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code:
+            parts.append(str(self.status_code))
+        if self.code:
+            parts.append(str(self.code))
+        if self.description:
+            parts.append(self.description)
+        return " ".join(parts)
+
+
+class ApiDecodingError(Exception):
+    pass
+
+
+class InvalidEmailError(ValueError):
+    pass
+
+
+class MissingBaseUrlError(ValueError):
+    pass
+
+
+class MissingClientIdError(ValueError):
+    pass
+
+
+class MissingJwtSecretError(ValueError):
+    pass
+
+
+class MissingJurisdictionCodesError(ValueError):
+    pass
+
+
+class MissingServiceIdError(ValueError):
+    pass
+
+
+class MissingRequestIdError(ValueError):
+    pass
+
+
+class MissingJurisdictionElementIdError(ValueError):
+    pass
+
+
+class MissingArgumentError(ValueError):
+    def __init__(self, arg: str):
+        super().__init__(arg)

mtx_api/models/jurisdiction.py

@@ -0,0 +1,101 @@
+from pydantic import AliasChoices, Field, RootModel
+
+from mtx_api.models.base import ImmutableBaseModel
+
+
+class OriginDevice(ImmutableBaseModel):
+    """
+    Represents the type of origin device associated with a jurisdiction.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the origin device.",
+        min_length=1,
+    )
+    options: list[str] | None = Field(
+        default=None,
+        description="List of configuration options available for the device."
+        "Can be one of 'android', 'email', 'facebook', 'inperson', 'internal', 'ios', "
+        "'twitter', 'web_channel', 'bot_whatsapp', 'bot_telegram', 'bot_web',",
+    )
+
+
+class JurisdictionElement(ImmutableBaseModel):
+    """
+    Represents a specific component or administrative division within a jurisdiction.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the jurisdiction element.",
+        min_length=1,
+    )
+    name: str | None = Field(
+        default=None,
+        description="Name of the jurisdiction element.",
+        min_length=1,
+    )
+    type: str | None = Field(
+        default=None,
+        description="Type classification of the element. It can be 'city' or 'building'",
+        min_length=1,
+    )
+    visible_name: str | None = Field(
+        default=None,
+        description="Human-readable name.",
+        min_length=1,
+    )
+    is_main: bool | None = Field(
+        default=None,
+        description="Indicates whether this is the primary element for the jurisdiction.",
+    )
+
+
+class Jurisdiction(ImmutableBaseModel):
+    """
+    Represents a geographical or administrative jurisdiction entity
+    within the platform, usually a city.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the jurisdiction.",
+        min_length=1,
+    )
+    name: str | None = Field(
+        default=None,
+        description="Official name of the jurisdiction.",
+        min_length=1,
+    )
+    jurisdiction_code: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("jurisdiction_id", "jurisdiction_code"),
+        serialization_alias="jurisdiction_id",
+        description="Code identifying the jurisdiction within the platform",
+        min_length=1,
+    )
+    jurisdiction_elements: list[JurisdictionElement] | None = Field(
+        default=None,
+        description="Administrative elements that belong to this jurisdiction.",
+    )
+    origin_devices: list[OriginDevice] | None = Field(
+        default=None,
+        description="List of devices associated with this jurisdiction.",
+    )
+
+
+class JurisdictionElementList(RootModel[list[JurisdictionElement]]):
+    """
+    A collection of JurisdictionElement objects.
+    """
+
+    pass
+
+
+class JurisdictionList(RootModel[list[Jurisdiction]]):
+    """
+    A collection of Jurisdiction objects.
+    """
+
+    pass

mtx_api/models/medias.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from mtx_api.models.additional_data import AdditionalDataAnswer
+from mtx_api.models.base import ImmutableBaseModel
+from mtx_api.models.common import Tag
+
+
+class MediaMetadata(ImmutableBaseModel):
+    """
+    Represents metadata information associated with media files.
+
+    This model contains additional contextual data about media, including
+    location-based information and creation timestamps.
+    """
+
+    location_additional_data: list[AdditionalDataAnswer] | None = Field(
+        default=None,
+        description="Additional location-based data associated with where the media was captured.",
+    )
+    created: str | None = Field(
+        default=None,
+        description="The timestamp when the media metadata was created, in ISO format.",
+    )
+
+
+class File(ImmutableBaseModel):
+    """
+    Represents a file resource with its identifier and access URL.
+
+    This model provides basic file information for accessing uploaded or
+    stored files on the platform.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the file.",
+    )
+    url: str | None = Field(
+        default=None,
+        description="The URL where the file can be accessed or downloaded.",
+    )
+
+
+class Media(ImmutableBaseModel):
+    """
+    Represents media content such as images or videos attached to platform entities.
+
+    This model contains comprehensive information about media files including
+    their visibility, type, metadata, and validation checks.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the media item.",
+    )
+    public: bool | None = Field(
+        default=None,
+        description="Whether the media is publicly visible or restricted to authorized users.",
+    )
+    type: str | None = Field(
+        default=None,
+        description="The media type, such as 'image', 'video', or other content types.",
+    )
+    media_url: str | None = Field(
+        default=None,
+        description="The URL where the media content can be accessed.",
+    )
+    created_datetime: str | None = Field(
+        default=None,
+        description="The timestamp when the media was created or uploaded, in ISO format.",
+    )
+    deleted: bool | None = Field(
+        default=None,
+        description="Whether the media has been marked as deleted.",
+    )
+    media_code: str | None = Field(
+        default=None,
+        description="A code or reference identifier for the media item.",
+    )
+    check_distance: str | None = Field(
+        default=None,
+        description="Distance-based validation check value for media verification.",
+    )
+    check_time: str | None = Field(
+        default=None,
+        description="Time-based validation check value for media verification.",
+    )
+    media_metadata: MediaMetadata | None = Field(
+        default=None,
+        description="Additional metadata information associated with the media.",
+    )
+    tags: list[Tag] | None = Field(
+        default=None,
+        description="Classification tags associated with the media for categorization.",
+    )

mtx_api/models/request.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+from pydantic import AliasChoices, Field, RootModel
+
+from mtx_api.models.additional_data import AdditionalDataAnswer
+from mtx_api.models.base import DatetimeField, ImmutableBaseModel
+from mtx_api.models.common import Tag, User
+from mtx_api.models.jurisdiction import JurisdictionElement
+from mtx_api.models.medias import File, Media
+from mtx_api.models.service import StatusNode
+from mtx_api.models.typology import Typology
+
+
+class Following(ImmutableBaseModel):
+    """
+    Represents whether a user is following a request.
+
+    This model indicates if the current user has subscribed to receive
+    notifications about updates to a particular request.
+    """
+
+    is_following: bool | None = Field(
+        default=None,
+        alias="isFollowing",
+        description="Whether the current user is following this request.",
+    )
+
+
+class CreatedRequest(ImmutableBaseModel):
+    """
+    Represents a newly created request with basic information.
+
+    This model contains the essential identifiers and status information
+    returned immediately after creating a request.
+    """
+
+    id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("token", "id"),
+        serialization_alias="token",
+        description="Unique identifier token for the created request.",
+    )
+    service_request_id: str | None = Field(
+        default=None,
+        description="Human-readable identifier for the request.",
+    )
+    status_node: StatusNode | None = Field(
+        default=None,
+        description="The initial status node of the newly created request.",
+    )
+
+
+class CreatedRequestList(RootModel[list[CreatedRequest]]):
+    pass
+
+
+class Request(CreatedRequest):
+    """
+    Represents a complete request with all its details and metadata.
+
+    This model extends CreatedRequest with comprehensive information including
+    location data, timestamps, status, media attachments, user interactions,
+    and additional configurable fields.
+    """
+
+    description: str | None = Field(
+        default=None,
+        description="The detailed description of the request provided by the user.",
+    )
+    address: str | None = Field(
+        default=None,
+        description="The physical address associated with the request.",
+    )
+    address_string: str | None = Field(
+        default=None,
+        description="Alternative formatted address string for the request location.",
+    )
+    lat: float | None = Field(
+        default=None,
+        description="Latitude coordinate of the request location.",
+    )
+    lng: float | None = Field(
+        default=None,
+        alias="long",
+        description="Longitude coordinate of the request location.",
+    )
+    status_node_type: str | None = Field(
+        default=None,
+        description="The type of the current status node (e.g., 'initial_node', 'final_node').",
+    )
+    typology: Typology | None = Field(
+        default=None,
+        description="The typology classification of the request.",
+    )
+    jurisdiction_id: str | None = Field(
+        default=None,
+        description="Code of the jurisdiction where the request was created.",
+    )
+    jurisdiction_element: JurisdictionElement | None = Field(
+        default=None,
+        description="The specific jurisdiction element associated with the request.",
+    )
+    service_id: str | None = Field(
+        default=None,
+        description="Unique identifier of the service this request belongs to.",
+    )
+    service_name: str | None = Field(
+        default=None,
+        description="Internal name of the service.",
+    )
+    service_code: str | None = Field(
+        default=None,
+        description="Code identifier of the service.",
+    )
+    requested_datetime: DatetimeField | None = Field(
+        default=None,
+        description="Timestamp when the request was created, in ISO format with timezone.",
+    )
+    updated_datetime: DatetimeField | None = Field(
+        default=None,
+        description=("Timestamp when the request was last updated, in ISO format with timezone."),
+    )
+    current_node_estimated_final_datetime: DatetimeField | None = Field(
+        default=None,
+        description=(
+            "Estimated completion time for the current status node, in ISO format with timezone."
+        ),
+    )
+    current_node_estimated_start_datetime: DatetimeField | None = Field(
+        default=None,
+        description=(
+            "Estimated start time for the current status node, in ISO format with timezone."
+        ),
+    )
+    estimated_final_datetime: DatetimeField | None = Field(
+        default=None,
+        description=(
+            "Estimated completion time for the entire request, in ISO format with timezone."
+        ),
+    )
+    estimated_start_datetime: DatetimeField | None = Field(
+        default=None,
+        description=(
+            "Estimated start time for processing the request, in ISO format with timezone."
+        ),
+    )
+    reiterations_count: int | None = Field(
+        default=None,
+        description="Number of times the request has been reiterated by users.",
+    )
+    complaints_count: int | None = Field(
+        default=None,
+        description="Number of complaints filed about this request.",
+    )
+    comments_count: int | None = Field(
+        default=None,
+        description="Number of comments posted on this request.",
+    )
+    worknotes_count: int | None = Field(
+        default=None,
+        description="Number of internal work notes on this request.",
+    )
+    evaluation: int | None = Field(
+        default=None,
+        description="User's evaluation rating for this request.",
+    )
+    evaluations_count: int | None = Field(
+        default=None,
+        description="Total number of evaluations received for this request.",
+    )
+    evaluations_avg: int | None = Field(
+        default=None,
+        description="Average evaluation rating across all evaluations.",
+    )
+    public_visibility: bool | None = Field(
+        default=None,
+        description="Whether this request is visible to the public.",
+    )
+    complaining: bool | None = Field(
+        default=None,
+        description="Whether the current user has filed a complaint about this request.",
+    )
+    supporting: bool | None = Field(
+        default=None,
+        description="Whether the current user is supporting this request.",
+    )
+    supporting_count: int | None = Field(
+        default=None,
+        description="Number of users supporting this request.",
+    )
+    following_count: int | None = Field(
+        default=None,
+        description="Number of users following this request.",
+    )
+    following: Following | None = Field(
+        default=None,
+        description="Information about whether the current user is following this request.",
+    )
+    deleted: bool | None = Field(
+        default=None,
+        description="Whether this request has been marked as deleted.",
+    )
+    jurisdiction_name: str | None = Field(
+        default=None,
+        description="Name of the jurisdiction where the request was created.",
+    )
+    is_evaluable: bool | None = Field(
+        default=None,
+        description="Whether this request can be evaluated by the user.",
+    )
+    accepted: bool | None = Field(
+        default=None,
+        description="Whether this request has been accepted for processing.",
+    )
+    files: list[File] | None = Field(
+        default=None,
+        description="List of file attachments associated with this request.",
+    )
+    medias: list[Media] | None = Field(
+        default=None,
+        description="List of media items (images/videos) attached to this request.",
+    )
+    tags: list[Tag] | None = Field(
+        default=None,
+        description="Classification tags associated with this request.",
+    )
+    media_url: str | None = Field(
+        default=None,
+        description="URL to a primary media item for this request.",
+    )
+    additional_data: list[AdditionalDataAnswer] | None = Field(
+        default=None,
+        description="Answers to additional configurable questions for this request.",
+    )
+    location_additional_data: list[AdditionalDataAnswer] | None = Field(
+        default=None,
+        description="Location-specific additional data answers for this request.",
+    )
+    user: User | None = Field(
+        default=None,
+        description="Reference to the user who created this request.",
+    )
+
+
+class RequestList(RootModel[list[Request]]):
+    """
+    A collection of Request objects.
+
+    This model represents a list of requests returned when querying
+    multiple requests from the platform.
+    """
+
+    pass

mtx_api/models/request_comment.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from pydantic import AliasChoices, Field
+
+from mtx_api.models.base import DatetimeField, ImmutableBaseModel
+
+
+class RequestCommentMedia(ImmutableBaseModel):
+    """
+    Represents media content attached to a request comment.
+
+    This model contains information about images, videos, or other media files
+    that have been attached to a comment on a request.
+    """
+
+    id: str | None = Field(
+        default=None,
+        description="Unique identifier for the comment media item.",
+    )
+    media_url: str | None = Field(
+        default=None,
+        description="The URL where the media content can be accessed.",
+    )
+
+
+class RequestComment(ImmutableBaseModel):
+    """
+    Represents a comment or note attached to a request.
+
+    This model contains user-submitted comments on requests, which can
+    include text descriptions and attached media files for additional context.
+    """
+
+    created_datetime: DatetimeField | None = Field(
+        default=None,
+        description="The timestamp when the comment was created, in ISO format with timezone.",
+    )
+    id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("comment_code", "id"),
+        serialization_alias="comment_code",
+        description="Unique identifier for the comment.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="The text content of the comment.",
+    )
+    medias: list[RequestCommentMedia] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("medias_urls", "medias"),
+        serialization_alias="medias_urls",
+        description="List of media items attached to the comment.",
+    )

mtx_api/models/request_media.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from mtx_api.models.base import DatetimeField, ImmutableBaseModel
+
+
+class RequestMedia(ImmutableBaseModel):
+    """
+    Represents media content attached to a request.
+
+    This model contains information about images, videos, or other media files
+    that have been uploaded and associated with a request for
+    documentation or evidence purposes.
+    """
+
+    type: str | None = Field(
+        default=None,
+        description="The media type, such as 'image', 'video', or other content types.",
+    )
+    media_url: str | None = Field(
+        default=None,
+        description="The URL where the media content can be accessed.",
+    )
+    created_datetime: DatetimeField | None = Field(
+        default=None,
+        description="The timestamp when the media was uploaded, in ISO format with timezone.",
+    )
+    media_code: str | None = Field(
+        default=None,
+        description="A unique code or reference identifier for the media item.",
+    )