karrio-royalmail 2025.5rc1__py3-none-any.whl

karrio/mappers/royalmail/__init__.py

@@ -0,0 +1,3 @@
+from karrio.mappers.royalmail.mapper import Mapper
+from karrio.mappers.royalmail.proxy import Proxy
+from karrio.mappers.royalmail.settings import Settings

karrio/mappers/royalmail/mapper.py

@@ -0,0 +1,117 @@
+from typing import List, Tuple
+from karrio.core.utils.serializable import Serializable, Deserializable
+from karrio.api.mapper import Mapper as BaseMapper
+from karrio.core.models import (
+    # AddressValidationRequest,
+    # ShipmentCancelRequest,
+    # PickupUpdateRequest,
+    # PickupCancelRequest,
+    # ShipmentRequest,
+    TrackingRequest,
+    # PickupRequest,
+    # RateRequest,
+    # AddressValidationDetails,
+    # ConfirmationDetails,
+    TrackingDetails,
+    # ShipmentDetails,
+    # PickupDetails,
+    # RateDetails,
+    Message,
+)
+from karrio.providers.royalmail import (
+    # parse_address_validation_response,
+    # parse_shipment_cancel_response,
+    # parse_pickup_update_response,
+    # parse_pickup_cancel_response,
+    # parse_shipment_response,
+    parse_tracking_response,
+    # parse_pickup_response,
+    # parse_rate_response,
+    # address_validation_request,
+    # shipment_cancel_request,
+    # pickup_update_request,
+    # pickup_cancel_request,
+    tracking_request,
+    # shipment_request,
+    # pickup_request,
+    # rate_request,
+)
+from karrio.mappers.royalmail.settings import Settings
+
+
+class Mapper(BaseMapper):
+    settings: Settings
+
+    # def create_address_validation_request(self, payload: AddressValidationRequest) -> Serializable:
+    #     return address_validation_request(payload, self.settings)
+    #
+    # def create_pickup_request(
+    #     self, payload: PickupRequest
+    # ) -> Serializable:
+    #     return pickup_request(payload, self.settings)
+    #
+    # def create_pickup_update_request(
+    #     self, payload: PickupUpdateRequest
+    # ) -> Serializable:
+    #     return pickup_update_request(payload, self.settings)
+    #
+    # def create_cancel_pickup_request(
+    #     self, payload: PickupCancelRequest
+    # ) -> Serializable:
+    #     return pickup_cancel_request(payload, self.settings)
+
+    # def create_rate_request(
+    #     self, payload: RateRequest
+    # ) -> Serializable:
+    #     return rate_request(payload, self.settings)
+
+    # def create_shipment_request(
+    #     self, payload: ShipmentRequest
+    # ) -> Serializable:
+    #     return shipment_request(payload, self.settings)
+    #
+    # def create_cancel_shipment_request(self, payload: ShipmentCancelRequest) -> Serializable:
+    #     return shipment_cancel_request(payload, self.settings)
+
+    def create_tracking_request(self, payload: TrackingRequest) -> Serializable:
+        return tracking_request(payload, self.settings)
+
+    # def parse_address_validation_response(
+    #     self, response: Deserializable
+    # ) -> Tuple[AddressValidationDetails, List[Message]]:
+    #     return parse_address_validation_response(response, self.settings)
+    #
+    # def parse_cancel_pickup_response(
+    #     self, response: Deserializable
+    # ) -> Tuple[ConfirmationDetails, List[Message]]:
+    #     return parse_pickup_cancel_response(response, self.settings)
+    #
+    # def parse_pickup_response(
+    #     self, response: Deserializable
+    # ) -> Tuple[PickupDetails, List[Message]]:
+    #     return parse_pickup_response(response, self.settings)
+    #
+    # def parse_pickup_update_response(
+    #     self, response: Deserializable
+    # ) -> Tuple[PickupDetails, List[Message]]:
+    #     return parse_pickup_update_response(response, self.settings)
+
+    # def parse_rate_response(
+    #     self, response: Deserializable
+    # ) -> Tuple[List[RateDetails], List[Message]]:
+    #     return parse_rate_response(response, self.settings)
+
+    # def parse_shipment_response(
+    #     self, response: Deserializable
+    # ) -> Tuple[ShipmentDetails, List[Message]]:
+    #     return parse_shipment_response(response, self.settings)
+    #
+    # def parse_cancel_shipment_response(
+    #     self, response: Deserializable
+    # ) -> Tuple[ConfirmationDetails, List[Message]]:
+    #     return parse_shipment_cancel_response(response, self.settings)
+
+    def parse_tracking_response(
+        self, response: Deserializable
+    ) -> Tuple[List[TrackingDetails], List[Message]]:
+        return parse_tracking_response(response, self.settings)

karrio/mappers/royalmail/proxy.py

@@ -0,0 +1,35 @@
+from typing import List
+from karrio.core.utils import (
+    DP,
+    request as http,
+    Serializable,
+    Deserializable,
+    exec_async,
+)
+from karrio.api.proxy import Proxy as BaseProxy
+from karrio.mappers.royalmail.settings import Settings
+
+
+class Proxy(BaseProxy):
+    settings: Settings
+
+    """ Proxy Methods """
+
+    def get_tracking(self, request: Serializable) -> Deserializable:
+        def _get_tracking(mail_piece_id: str):
+            return http(
+                url=f"{self.settings.server_url}/mailpieces/v2/{mail_piece_id}/events",
+                trace=self.trace_as("json"),
+                method="GET",
+                headers={
+                    "Accept": "application/json",
+                    "X-IBM-Client-Id": self.settings.client_id,
+                    "X-IBM-Client-Secret": self.settings.client_secret,
+                    "X-Accept-RMG-Terms": "yes",
+                },
+            )
+
+        responses: List[dict] = exec_async(_get_tracking, request.serialize())
+        return Deserializable(
+            responses, lambda res: [DP.to_dict(r) for r in res if any(r.strip())]
+        )

karrio/mappers/royalmail/settings.py

@@ -0,0 +1,21 @@
+"""Karrio Royal Mail settings."""
+
+import attr
+from karrio.providers.royalmail.utils import Settings as BaseSettings
+
+
+@attr.s(auto_attribs=True)
+class Settings(BaseSettings):
+    """Royal Mail connection settings."""
+
+    # Carrier specific properties
+    client_id: str
+    client_secret: str
+
+    # Base properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "royalmail"
+    account_country_code: str = "UK"
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/royalmail/__init__.py

@@ -0,0 +1,21 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.royalmail as mappers
+# import karrio.providers.royalmail.units as units
+
+
+METADATA = metadata.PluginMetadata(
+    status="beta",
+    id="royalmail",
+    label="Royal Mail",
+
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+
+    # Data Units
+    # options=units.OptionCode,
+    # package_presets=units.PackagePresets,
+    # packaging_types=units.PackagingType,
+    # services=units.Serives,
+)

karrio/providers/royalmail/__init__.py

@@ -0,0 +1,24 @@
+from karrio.providers.royalmail.utils import Settings
+# from karrio.providers.royalmail.rate import parse_rate_response, rate_request
+# from karrio.providers.royalmail.address import (
+#     parse_address_validation_response,
+#     address_validation_request
+# )
+# from karrio.providers.royalmail.shipment import (
+#     parse_shipment_cancel_response,
+#     parse_shipment_response,
+#     shipment_cancel_request,
+#     shipment_request,
+# )
+# from karrio.providers.royalmail.pickup import (
+#     parse_pickup_cancel_response,
+#     parse_pickup_update_response,
+#     parse_pickup_response,
+#     pickup_update_request,
+#     pickup_cancel_request,
+#     pickup_request,
+# )
+from karrio.providers.royalmail.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)

karrio/providers/royalmail/error.py

@@ -0,0 +1,21 @@
+from typing import List
+from karrio.schemas.royalmail.errors import Errors
+from karrio.providers.royalmail import Settings
+from karrio.core.models import Message
+
+
+def parse_error_response(response: List[dict], settings: Settings) -> List[Message]:
+    errors = [Errors(**e) for e in response]
+
+    return [
+        Message(
+            # context info
+            carrier_name=settings.carrier_name,
+            carrier_id=settings.carrier_id,
+            # carrier error info
+            code=str(error.httpCode),
+            message=error.httpMessage,
+            details=dict(information=error.moreInformation, errors=error.errors),
+        )
+        for error in errors
+    ]

karrio/providers/royalmail/tracking.py

@@ -0,0 +1,54 @@
+from typing import List, Tuple
+from karrio.schemas.royalmail.tracking import MailPieces
+from karrio.core.models import (
+    TrackingEvent,
+    TrackingDetails,
+    TrackingRequest,
+    Message,
+)
+from karrio.providers.royalmail.utils import Settings
+from karrio.providers.royalmail.error import parse_error_response
+import karrio.lib as lib
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[List[dict]],
+    settings: Settings,
+) -> Tuple[List[TrackingDetails], List[Message]]:
+    response = _response.deserialize()
+    errors = [e for e in response if "mailPieces" not in e]
+    details = [
+        _extract_detail(d["mailPieces"], settings)
+        for d in response
+        if "mailPieces" in d
+    ]
+
+    return details, parse_error_response(errors, settings)
+
+
+def _extract_detail(data: dict, settings: Settings) -> TrackingDetails:
+    detail = lib.to_object(MailPieces, data)
+
+    return TrackingDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=detail.mailPieceId,
+        delivered=("Delivered" in detail.summary.lastEventName),
+        events=[
+            TrackingEvent(
+                date=lib.fdate(event.eventDateTime, "%Y-%m-%dT%H:%M:%S%z"),
+                description=event.eventName,
+                location=event.locationName,
+                code=event.eventCode,
+                time=lib.flocaltime(event.eventDateTime, "%Y-%m-%dT%H:%M:%S%z"),
+            )
+            for event in detail.events
+        ],
+        estimated_delivery=lib.fdate(detail.estimatedDelivery.date, "%Y-%m-%d"),
+    )
+
+
+def tracking_request(payload: TrackingRequest, _) -> lib.Serializable:
+    request = payload.tracking_numbers
+
+    return lib.Serializable(request)

karrio/providers/royalmail/units.py

@@ -0,0 +1,46 @@
+""" Royal Mail Native Types """
+
+# import karrio.lib as lib
+# from karrio.core.utils import Enum, Flag
+#
+# PRESET_DEFAULTS = dict(dimension_unit="CM", weight_unit="KG")
+#
+#
+# class PackagePresets(lib.Enum):
+#     # carrier_envelope = PackagePreset(
+#     #     **dict(weight=0.5, width=35.0, height=27.5, length=1.0, packaging_type="envelope"),
+#     #     **PRESET_DEFAULTS
+#     # )
+#     # carrier_box = PackagePreset(
+#     #     **dict(weight=0.5, width=35.0, height=27.5, length=1.0, packaging_type="medium_box"),
+#     #     **PRESET_DEFAULTS
+#     # )
+#     pass
+#
+#
+# class PackageType(lib.StrEnum):
+#     carrier_envelope = "ENVELOPE CODE"
+#     carrier_box = "BOX CODE"
+#     carrier_your_packaging = "CUSTOM PACKAGING CODE"
+#
+#     """ Unified Packaging type mapping """
+#     envelope = carrier_envelope
+#     pak = carrier_envelope
+#     tube = carrier_your_packaging
+#     pallet = carrier_your_packaging
+#     small_box = carrier_box
+#     medium_box = carrier_box
+#     large_box = carrier_box
+#     your_packaging = carrier_your_packaging
+#
+#
+# class Service(Enum):
+#     carrier_standard = "STANDARD CODE"
+#     carrier_premium = "PREMIUM CODE"
+#     carrier_overnight = "OVERNIGHT CODE"
+#
+#
+# class Option(lib.Enum):
+#     carrier_signature = "SIGNATURE CODE"
+#     carrier_saturday_delivery = "SATURDAY DELIVERY CODE"
+#     carrier_dry_ice = "DRY ICE CODE"

karrio/providers/royalmail/utils.py

@@ -0,0 +1,25 @@
+from karrio.core import Settings as BaseSettings
+
+
+class Settings(BaseSettings):
+    """Royal Mail connection settings."""
+
+    # Carrier specific properties
+    client_id: str
+    client_secret: str
+
+    id: str = None
+    account_country_code: str = "UK"
+    metadata: dict = {}
+
+    @property
+    def carrier_name(self):
+        return "royalmail"
+
+    @property
+    def server_url(self):
+        return (
+            "https://api.royalmail.net"
+            if self.test_mode
+            else "https://api.royalmail.net"
+        )

karrio/schemas/royalmail/errors.py

@@ -0,0 +1,19 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class Error:
+    errorCode: typing.Optional[str] = None
+    errorDescription: typing.Optional[str] = None
+    errorCause: typing.Optional[str] = None
+    errorResolution: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Errors:
+    httpCode: typing.Optional[int] = None
+    httpMessage: typing.Optional[str] = None
+    moreInformation: typing.Optional[str] = None
+    errors: typing.Optional[typing.List[Error]] = jstruct.JList[Error]

karrio/schemas/royalmail/tracking.py

@@ -0,0 +1,86 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class EstimatedDelivery:
+    date: typing.Optional[str] = None
+    startOfEstimatedWindow: typing.Optional[str] = None
+    endOfEstimatedWindow: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Event:
+    eventCode: typing.Optional[str] = None
+    eventName: typing.Optional[str] = None
+    eventDateTime: typing.Optional[str] = None
+    locationName: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Redelivery:
+    href: typing.Optional[str] = None
+    title: typing.Optional[str] = None
+    description: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Links:
+    summary: typing.Optional[Redelivery] = jstruct.JStruct[Redelivery]
+    signature: typing.Optional[Redelivery] = jstruct.JStruct[Redelivery]
+    redelivery: typing.Optional[Redelivery] = jstruct.JStruct[Redelivery]
+
+
+@attr.s(auto_attribs=True)
+class Signature:
+    recipientName: typing.Optional[str] = None
+    signatureDateTime: typing.Optional[str] = None
+    imageId: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class InternationalPostalProvider:
+    url: typing.Optional[str] = None
+    title: typing.Optional[str] = None
+    description: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Summary:
+    uniqueItemId: typing.Optional[str] = None
+    oneDBarcode: typing.Optional[str] = None
+    productId: typing.Optional[str] = None
+    productName: typing.Optional[str] = None
+    productDescription: typing.Optional[str] = None
+    productCategory: typing.Optional[str] = None
+    destinationCountryCode: typing.Optional[str] = None
+    destinationCountryName: typing.Optional[str] = None
+    originCountryCode: typing.Optional[str] = None
+    originCountryName: typing.Optional[str] = None
+    lastEventCode: typing.Optional[str] = None
+    lastEventName: typing.Optional[str] = None
+    lastEventDateTime: typing.Optional[str] = None
+    lastEventLocationName: typing.Optional[str] = None
+    statusDescription: typing.Optional[str] = None
+    statusCategory: typing.Optional[str] = None
+    statusHelpText: typing.Optional[str] = None
+    summaryLine: typing.Optional[str] = None
+    internationalPostalProvider: typing.Optional[InternationalPostalProvider] = jstruct.JStruct[InternationalPostalProvider]
+
+
+@attr.s(auto_attribs=True)
+class MailPieces:
+    mailPieceId: typing.Optional[str] = None
+    carrierShortName: typing.Optional[str] = None
+    carrierFullName: typing.Optional[str] = None
+    summary: typing.Optional[Summary] = jstruct.JStruct[Summary]
+    signature: typing.Optional[Signature] = jstruct.JStruct[Signature]
+    estimatedDelivery: typing.Optional[EstimatedDelivery] = jstruct.JStruct[EstimatedDelivery]
+    events: typing.Optional[typing.List[Event]] = jstruct.JList[Event]
+    links: typing.Optional[Links] = jstruct.JStruct[Links]
+
+
+@attr.s(auto_attribs=True)
+class Tracking:
+    mailPieces: typing.Optional[MailPieces] = jstruct.JStruct[MailPieces]

karrio_royalmail-2025.5rc1.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: karrio_royalmail
+Version: 2025.5rc1
+Summary: Karrio - Royal Mail Shipping extension
+Author-email: karrio <hello@karrio.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/karrioapi/karrio
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: karrio
+
+# karrio.royalmail
+
+This package is a Royal Mail extension of the [karrio](https://pypi.org/project/karrio) multi carrier shipping SDK.
+
+## Requirements
+
+`Python 3.7+`
+
+## Installation
+
+```bash
+pip install karrio.royalmail
+```
+
+## Usage
+
+```python
+import karrio.sdk as karrio
+from karrio.mappers.royalmail.settings import Settings
+
+
+# Initialize a carrier gateway
+canadapost = karrio.gateway["royalmail"].create(
+    Settings(
+        ...
+    )
+)
+```
+
+Check the [Karrio Mutli-carrier SDK docs](https://docs.karrio.io) for Shipping API requests

karrio_royalmail-2025.5rc1.dist-info/RECORD

@@ -0,0 +1,18 @@
+karrio/mappers/royalmail/__init__.py,sha256=1tG6gGRxAoCPrCGX-uYNNj6TGmpAOBa4xeoWlkvSuBQ,155
+karrio/mappers/royalmail/mapper.py,sha256=1X1n1LwODVVaXT6SjqLfL3wu_or4Cqu1Q6bMAbuMGQI,4091
+karrio/mappers/royalmail/proxy.py,sha256=UhWm1pnDIAB97YQyHOtMX9k4dOKC1GWu_sCVz8lvM0I,1122
+karrio/mappers/royalmail/settings.py,sha256=KRtxvBa67-G124vhUfkDS7MNMtgxbbS_fxE6rGnhttg,482
+karrio/plugins/royalmail/__init__.py,sha256=mk8Ehum7FBkCkVLOE6b_GPSROewpcBRrvzsdtTHhdL8,507
+karrio/providers/royalmail/__init__.py,sha256=qffDByM43WA2dHiclXLtuLmU35EqHwEDuUvGyKSnlNM,781
+karrio/providers/royalmail/error.py,sha256=cGnLQUS7CNHFshTiD4kVeWR_8obeFbk57HYyUPz1htI,680
+karrio/providers/royalmail/tracking.py,sha256=89o5uYXtygDLZygOODRGxytmrRsGs2S8QZ5Uqoze7ek,1752
+karrio/providers/royalmail/units.py,sha256=lVaPNYMl_sIOUOi9VceCGJloNzPSu678GUqBr1DYdEI,1378
+karrio/providers/royalmail/utils.py,sha256=U_mmAnbzYYoULaOhyGOFdcSPEF9mikOIeI0Ewesc5CQ,534
+karrio/schemas/royalmail/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+karrio/schemas/royalmail/errors.py,sha256=Va_0E1ETGNkN48w-eWFsarHq1vkp9hCv5mXY7V53P4I,519
+karrio/schemas/royalmail/tracking.py,sha256=kP3N5ISI5Wz8Lq-O9VHi-y1G2Ng3inf4XoFhWo7TVFM,2989
+karrio_royalmail-2025.5rc1.dist-info/METADATA,sha256=ZcoGs6opiLkMpgB-eW5qwD2ieqxDQZPsFVps4Hlb_Wg,1010
+karrio_royalmail-2025.5rc1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+karrio_royalmail-2025.5rc1.dist-info/entry_points.txt,sha256=xS5bCUhqI29tWlwzL84qemzWJGg4T5z25p61SuAP4WA,63
+karrio_royalmail-2025.5rc1.dist-info/top_level.txt,sha256=FZCY8Nwft8oEGHdl--xku8P3TrnOxu5dETEU_fWpRSM,20
+karrio_royalmail-2025.5rc1.dist-info/RECORD,,

karrio_royalmail-2025.5rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

karrio_royalmail-2025.5rc1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[karrio.plugins]
+royalmail = karrio.plugins.royalmail:METADATA

karrio_royalmail-2025.5rc1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+karrio
+schemas