karrio-australiapost 2025.5rc1__py3-none-any.whl

karrio/mappers/australiapost/__init__.py

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

karrio/mappers/australiapost/mapper.py

@@ -0,0 +1,60 @@
+"""Karrio Australia Post client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.australiapost as provider
+import karrio.mappers.australiapost.settings as provider_settings
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_rate_request(self, payload: models.RateRequest) -> lib.Serializable:
+        return provider.rate_request(payload, self.settings)
+
+    def create_tracking_request(
+        self, payload: models.TrackingRequest
+    ) -> lib.Serializable:
+        return provider.tracking_request(payload, self.settings)
+
+    def create_shipment_request(
+        self, payload: models.ShipmentRequest
+    ) -> lib.Serializable:
+        return provider.shipment_request(payload, self.settings)
+
+    def create_cancel_shipment_request(
+        self, payload: models.ShipmentCancelRequest
+    ) -> lib.Serializable[str]:
+        return provider.shipment_cancel_request(payload, self.settings)
+
+    def create_manifest_request(
+        self, payload: models.ManifestRequest
+    ) -> lib.Serializable:
+        return provider.manifest_request(payload, self.settings)
+
+    def parse_cancel_shipment_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_cancel_response(response, self.settings)
+
+    def parse_rate_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+        return provider.parse_rate_response(response, self.settings)
+
+    def parse_shipment_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_response(response, self.settings)
+
+    def parse_tracking_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+        return provider.parse_tracking_response(response, self.settings)
+
+    def parse_manifest_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+        return provider.parse_manifest_response(response, self.settings)

karrio/mappers/australiapost/proxy.py

@@ -0,0 +1,151 @@
+"""Karrio Australia Post client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.australiapost.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipping/v1/prices/items",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "Account-Number": self.settings.account_number,
+                "Authorization": f"Basic {self.settings.authorization}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        payload = request.serialize()
+        responses: list = []
+        responses.append(
+            lib.request(
+                url=f"{self.settings.server_url}/shipping/v1/shipments",
+                data=lib.to_json(payload["shipment"]),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={
+                    "Accept": "application/json",
+                    "Content-Type": "application/json",
+                    "Account-Number": self.settings.account_number,
+                    "Authorization": f"Basic {self.settings.authorization}",
+                },
+            )
+        )
+
+        shipment_id = (lib.to_dict(responses[0]).get("shipments") or [{}])[0].get(
+            "shipment_id"
+        )
+
+        if shipment_id is not None:
+            responses.append(
+                lib.request(
+                    url=f"{self.settings.server_url}/shipping/v1/labels",
+                    trace=self.trace_as("json"),
+                    data=lib.to_json(payload["label"]).replace(
+                        "[SHIPMENT_ID]", shipment_id
+                    ),
+                    method="POST",
+                    headers={
+                        "Accept": "application/json",
+                        "Content-Type": "application/json",
+                        "Account-Number": self.settings.account_number,
+                        "Authorization": f"Basic {self.settings.authorization}",
+                    },
+                )
+            )
+
+            label_url = (lib.to_dict(responses[1]).get("labels") or [{}])[0].get("url")
+
+            if label_url is not None:
+                responses.append(
+                    lib.request(
+                        decoder=lib.encode_base64,
+                        url=label_url,
+                        method="GET",
+                    )
+                )
+
+        return lib.Deserializable(
+            responses,
+            lambda _: [
+                # parse create shipment response
+                lib.to_dict(_[0]),
+                # parse create label response if exists
+                lib.to_dict(_[1] if len(_) > 1 else "{}"),
+                # return label image if exists
+                (_[2] if len(_) > 2 else None),
+            ],
+            request.ctx,
+        )
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        payload = request.serialize()
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipping/v1/shipments/{payload['shipment_id']}",
+            trace=self.trace_as("json"),
+            method="DELETE",
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "Account-Number": self.settings.account_number,
+                "Authorization": f"Basic {self.settings.authorization}",
+            },
+            decoder=lambda _: dict(ok=True),
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        query = request.serialize()
+        tracking_ids = ",".join(query["tracking_ids"])
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipping/v1/track?tracking_ids={tracking_ids}",
+            trace=self.trace_as("json"),
+            method="GET",
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "Account-Number": self.settings.account_number,
+                "Authorization": f"Basic {self.settings.authorization}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_manifest(self, request: lib.Serializable) -> lib.Deserializable:
+        ctx: dict = {}
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipping/v1/orders",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "Account-Number": self.settings.account_number,
+                "Authorization": f"Basic {self.settings.authorization}",
+            },
+        )
+
+        order_id = lib.to_dict(response).get("order", {}).get("order_id")
+
+        if order_id is not None:
+            ctx.update(
+                manifest=lib.request(
+                    url=f"{self.settings.server_url}/shipping/v1/accounts/{self.settings.account_number}/orders/{order_id}/summary",
+                    decoder=lib.encode_base64,
+                    method="GET",
+                )
+            )
+
+        return lib.Deserializable(response, lib.to_dict, ctx=ctx)

karrio/mappers/australiapost/settings.py

@@ -0,0 +1,22 @@
+"""Karrio Australia Post client settings."""
+
+import attr
+import karrio.providers.australiapost.utils as provider_utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """Australia Post connection settings."""
+
+    # required carrier specific properties
+    api_key: str
+    password: str
+    account_number: str
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "australiapost"
+    account_country_code: str = "AU"
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/australiapost/__init__.py

@@ -0,0 +1,23 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.australiapost as mappers
+import karrio.providers.australiapost.units as units
+import karrio.providers.australiapost.utils as utils
+
+
+METADATA = metadata.PluginMetadata(
+    status="beta",
+    id="australiapost",
+    label="Australia Post",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    is_hub=False,
+    services=units.ShippingService,
+    options=units.ShippingOption,
+    # New fields
+    website="https://auspost.com.au/",
+    documentation="https://developers.auspost.com.au/apis/shipping-and-tracking/reference",
+    description="Australia Post, formally known as the Australian Postal Corporation, is a Commonwealth government-owned corporation that provides postal services throughout Australia.",
+)

karrio/providers/australiapost/__init__.py

@@ -0,0 +1,16 @@
+from karrio.providers.australiapost.utils import Settings
+from karrio.providers.australiapost.rate import parse_rate_response, rate_request
+from karrio.providers.australiapost.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.australiapost.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)
+from karrio.providers.australiapost.manifest import (
+    parse_manifest_response,
+    manifest_request,
+)

karrio/providers/australiapost/error.py

@@ -0,0 +1,41 @@
+import karrio.schemas.australiapost.error_response as australiapost
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.australiapost.utils as provider_utils
+
+
+def parse_error_response(
+    response: dict,
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    responses = response if isinstance(response, list) else [response]
+    error_list: typing.List[dict] = sum(
+        [
+            *[res.get("errors", []) for res in responses if "errors" in res],
+            *[res.get("warnings", []) for res in responses if "warnings" in res],
+        ],
+        [],
+    )
+    errors: typing.List[australiapost.ErrorType] = [
+        lib.to_object(australiapost.ErrorType, error) for error in error_list
+    ]
+
+    return [
+        models.Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            code=(error.code or error.error_code or error.error),
+            message=(error.message or error.error_description or error.name),
+            details=lib.to_dict(
+                {
+                    **kwargs,
+                    "field": error.field,
+                    "context": error.context,
+                    "messages": error.messages,
+                }
+            ),
+        )
+        for error in errors
+    ]

karrio/providers/australiapost/manifest.py

@@ -0,0 +1,62 @@
+import karrio.schemas.australiapost.manifest_request as australiapost
+import karrio.schemas.australiapost.manifest_response as manifest
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.australiapost.error as error
+import karrio.providers.australiapost.utils as provider_utils
+import karrio.providers.australiapost.units as provider_units
+
+
+def parse_manifest_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    details = (
+        _extract_details(response, settings, ctx=_response.ctx)
+        if response.get("order", {}).get("order_id") is not None
+        else None
+    )
+
+    return details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+    ctx: dict = {},
+) -> models.ManifestDetails:
+    manifest = ctx.get("manifest")
+
+    return models.ManifestDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_id,
+        doc=models.ManifestDocument(manifest=manifest),
+        meta=dict(
+            order_id=data["order"]["order_id"],
+            order_reference=data["order"]["order_reference"],
+            order_creation_date=data["order"]["order_creation_date"],
+        ),
+    )
+
+
+def manifest_request(
+    payload: models.ManifestRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    address = lib.to_address(payload.address)
+
+    request = australiapost.ManifestRequestType(
+        order_reference=lib.text(payload.reference),
+        payment_method="CHARGE_TO_ACCOUNT",
+        consignor=lib.text(address.company_name or address.contact, max=40),
+        shipments=[
+            australiapost.ShipmentType(shipment_id=id)
+            for id in payload.shipment_identifiers
+        ],
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/australiapost/rate.py

@@ -0,0 +1,141 @@
+import karrio.schemas.australiapost.rate_request as australiapost
+import karrio.schemas.australiapost.rate_response as rating
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.australiapost.error as error
+import karrio.providers.australiapost.utils as provider_utils
+import karrio.providers.australiapost.units as provider_units
+
+
+def parse_rate_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    items = response.get("items") or []
+
+    messages = sum(
+        [
+            error.parse_error_response(
+                item,
+                settings,
+            )
+            for item in items
+            if "errors" in item or "warnings" in item
+        ],
+        start=error.parse_error_response(response, settings),
+    )
+    rates = lib.to_multi_piece_rates(
+        [
+            (
+                f"{_}",
+                [
+                    _extract_details(price, settings)
+                    for price in item.get("prices") or []
+                ],
+            )
+            for _, item in enumerate(items, start=1)
+        ]
+    )
+
+    return rates, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.RateDetails:
+    rate = lib.to_object(rating.PriceElementType, data)
+    service = provider_units.ShippingService.map(rate.product_id)
+    features = data.get("features") or {}
+    charges = [
+        ("base charge", rate.calculated_price_ex_gst),
+        ("GST", rate.calculated_gst),
+        *[
+            (_.type, _.attributes.price.calculated_price)
+            for _ in features.values()
+            if lib.failsafe(lambda: _.attributes.price.calculated_price) is not None
+        ],
+    ]
+
+    return models.RateDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        service=service.name_or_key,
+        total_charge=lib.to_money(rate.calculated_price),
+        currency=units.Currency.AUD.name,
+        extra_charges=[
+            models.ChargeDetails(
+                name=name,
+                amount=lib.to_money(value),
+                currency=units.Currency.AUD.name,
+            )
+            for name, value in charges
+            if value
+        ],
+        meta=dict(
+            service_name=rate.product_type,
+        ),
+    )
+
+
+def rate_request(
+    payload: models.RateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    options = lib.to_shipping_options(
+        payload.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+    packages = lib.to_packages(
+        payload.parcels,
+        options=options,
+        package_option_type=provider_units.ShippingOption,
+        shipping_options_initializer=provider_units.shipping_options_initializer,
+    )
+    services = lib.to_services(payload.services, provider_units.ShippingService)
+
+    request = australiapost.RateRequestType(
+        rate_request_from=australiapost.FromType(
+            postcode=payload.shipper.postal_code,
+            country=payload.shipper.country_code,
+        ),
+        to=australiapost.FromType(
+            postcode=payload.recipient.postal_code,
+            country=payload.recipient.country_code,
+        ),
+        items=[
+            australiapost.ItemType(
+                item_reference=(getattr(package.parcel, "id", None) or str(idx)),
+                length=package.length.CM,
+                width=package.width.CM,
+                height=package.height.CM,
+                weight=package.weight.KG,
+                packaging_type=provider_units.PackagingType.map(
+                    package.packaging_type
+                ).value,
+                product_ids=[_.value for _ in services],
+                features=lib.identity(
+                    dict(
+                        TRANSIT_COVER=dict(
+                            attributes=dict(
+                                cover_amount=package.options.australiapost_transit_cover.state,
+                            ),
+                        )
+                    )
+                    if (package.options.australiapost_transit_cover.state is not None)
+                    else None
+                ),
+            )
+            for idx, package in enumerate(packages, start=1)
+        ],
+    )
+
+    return lib.Serializable(
+        request,
+        lambda _: lib.to_dict(
+            lib.to_json(_).replace("rate_request_from", "from"),
+        ),
+    )

karrio/providers/australiapost/shipment/__init__.py

@@ -0,0 +1,9 @@
+
+from karrio.providers.australiapost.shipment.create import (
+    parse_shipment_response,
+    shipment_request,
+)
+from karrio.providers.australiapost.shipment.cancel import (
+    parse_shipment_cancel_response,
+    shipment_cancel_request,
+)

karrio/providers/australiapost/shipment/cancel.py

@@ -0,0 +1,38 @@
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.australiapost.error as error
+import karrio.providers.australiapost.utils as provider_utils
+import karrio.providers.australiapost.units as provider_units
+
+
+def parse_shipment_cancel_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    success = len(messages) == 0
+
+    confirmation = (
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            operation="Cancel Shipment",
+            success=success,
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def shipment_cancel_request(
+    payload: models.ShipmentCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    request = dict(shipment_id=payload.shipment_identifier)
+
+    return lib.Serializable(request)