karrio-australiapost 2025.5__py3-none-any.whl

karrio/providers/australiapost/shipment/create.py

@@ -0,0 +1,294 @@
+import karrio.schemas.australiapost.shipment_request as australiapost
+import karrio.schemas.australiapost.shipment_response as shipping
+import karrio.schemas.australiapost.label_request as label_request
+import karrio.schemas.australiapost.label_response as labels
+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_shipment_response(
+    _response: lib.Deserializable[
+        typing.Tuple[dict, typing.Optional[dict], typing.Optional[str]]
+    ],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    [shipment_response, label_response, label] = _response.deserialize()
+    shipments = shipment_response.get("shipments") or []
+    labels = label_response.get("labels") or []
+    messages = [
+        *error.parse_error_response(label_response, settings),
+        *error.parse_error_response(shipment_response, settings),
+    ]
+    shipment = (
+        _extract_details((shipments[0], labels[0], label), settings)
+        if label is not None
+        else None
+    )
+
+    return shipment, messages
+
+
+def _extract_details(
+    data: typing.Tuple[dict, dict, str],
+    settings: provider_utils.Settings,
+    ctx: dict = {},
+) -> models.ShipmentDetails:
+    [shipment_response, label_response, label] = data
+    label_format = ctx.get("label_format") or "PDF"
+    label_info = lib.to_object(labels.LabelType, label_response)
+    shipment = lib.to_object(shipping.ShipmentType, shipment_response)
+    article_ids = [item.tracking_details.article_id for item in shipment.items]
+    tracking_numbers = [item.tracking_details.consignment_id for item in shipment.items]
+
+    return models.ShipmentDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=tracking_numbers[0],
+        shipment_identifier=shipment.shipment_id,
+        label_type=label_format,
+        docs=models.Documents(label=label),
+        meta=dict(
+            carrier_tracking_link=settings.tracking_url.format(tracking_numbers[0]),
+            label_request_id=label_info.request_id,
+            tracking_numbers=tracking_numbers,
+            article_ids=article_ids,
+            manifest_required=True,
+        ),
+    )
+
+
+def shipment_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    service = provider_units.ShippingService.map(payload.service)
+    is_intl = shipper.country_code != recipient.country_code
+    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,
+    )
+    customs = lib.to_customs_info(payload.customs, weight_unit=units.WeightUnit.KG.name)
+    label_format, label_layout = provider_units.LabelType.map(
+        payload.label_type or "PDF"
+    ).value
+    label_group = (
+        provider_units.ServiceLabelGroup.map(service.name).value
+        or provider_units.ServiceLabelGroup.australiapost_parcel_post.value
+    )
+
+    request = dict(
+        shipment=australiapost.ShipmentRequestType(
+            shipments=[
+                australiapost.ShipmentType(
+                    shipment_reference=payload.reference,
+                    customer_reference_1=None,
+                    customer_reference_2=None,
+                    email_tracking_enabled=options.email_notification.state,
+                    shipment_from=australiapost.FromType(
+                        name=shipper.contact,
+                        lines=shipper.address_lines,
+                        suburb=shipper.city,
+                        state=shipper.state_code,
+                        postcode=shipper.postal_code,
+                        country=shipper.country_code,
+                        email=shipper.email,
+                        phone=shipper.phone_number,
+                    ),
+                    to=australiapost.FromType(
+                        name=recipient.contact,
+                        lines=recipient.address_lines,
+                        suburb=recipient.city,
+                        state=recipient.state_code,
+                        postcode=recipient.postal_code,
+                        country=recipient.country_code,
+                        email=recipient.email,
+                        phone=recipient.phone_number,
+                    ),
+                    items=[
+                        australiapost.ItemType(
+                            item_reference=getattr(package, "id", None) or str(idx),
+                            product_id=service.value_or_key,
+                            length=package.length.CM,
+                            width=package.width.CM,
+                            height=package.height.CM,
+                            weight=package.weight.KG,
+                            cubic_volume=None,
+                            transportable_by_air=package.options.transportable_by_air.state,
+                            authority_to_leave=package.options.australiapost_authority_to_leave.state,
+                            allow_partial_delivery=package.options.australiapost_allow_partial_delivery.state,
+                            contains_dangerous_goods=package.options.australiapost_contains_dangerous_goods.state,
+                            item_description=package.parcel.description,
+                            features=(
+                                australiapost.FeaturesType(
+                                    DELIVERY_DATE=(
+                                        australiapost.DELIVERYDATEAttributesType(
+                                            date=package.options.australiapost_delivery_date.state,
+                                        )
+                                        if package.options.australiapost_delivery_date.state
+                                        else None
+                                    ),
+                                    DELIVERY_TIMES=(
+                                        australiapost.DELIVERYTIMESAttributesType(
+                                            windows=australiapost.WindowType(
+                                                start=package.options.australiapost_delivery_time_start.state,
+                                                end=package.options.australiapost_delivery_time_end.state,
+                                            )
+                                        )
+                                        if any(
+                                            [
+                                                package.options.australiapost_delivery_time_start.state,
+                                                package.options.australiapost_delivery_time_end.state,
+                                            ]
+                                        )
+                                        else None
+                                    ),
+                                    PICKUP_DATE=(
+                                        australiapost.DateType(
+                                            attributes=australiapost.DELIVERYDATEAttributesType(
+                                                date=package.options.australiapost_pickup_date.state,
+                                            )
+                                        )
+                                        if package.options.australiapost_pickup_date.state
+                                        else None
+                                    ),
+                                    PICKUP_TIME=(
+                                        australiapost.PickupTimeType(
+                                            attributes=australiapost.PICKUPTIMEAttributesType(
+                                                time=package.options.australiapost_pickup_time.state,
+                                            )
+                                        )
+                                        if package.options.australiapost_pickup_time.state
+                                        else None
+                                    ),
+                                    IDENTITY_ON_DELIVERY=(
+                                        australiapost.IdentityOnDeliveryType(
+                                            attributes=australiapost.IDENTITYONDELIVERYAttributesType(
+                                                id_capture_type=package.options.australiapost_identity_on_delivery.state,
+                                                redirection_enabled=None,
+                                            )
+                                        )
+                                        if package.options.australiapost_identity_on_delivery.state
+                                        else None
+                                    ),
+                                    PRINT_AT_DEPOT=(
+                                        australiapost.PrintAtDepotType(
+                                            attributes=australiapost.PRINTATDEPOTAttributesType(
+                                                enabled=package.options.australiapost_print_at_depot.state,
+                                            )
+                                        )
+                                        if package.options.australiapost_print_at_depot.state
+                                        else None
+                                    ),
+                                    SAMEDAY_IDENTITY_ON_DELIVERY=(
+                                        australiapost.SamedayIdentityOnDeliveryType(
+                                            attributes=australiapost.SAMEDAYIDENTITYONDELIVERYAttributesType(
+                                                id_option=package.options.australiapost_sameday_identity_on_delivery.state,
+                                            )
+                                        )
+                                        if package.options.australiapost_sameday_identity_on_delivery.state
+                                        else None
+                                    ),
+                                    COMMERCIAL_CLEARANCE=(
+                                        australiapost.CommercialClearanceType()
+                                        if payload.customs
+                                        else None
+                                    ),
+                                )
+                                if any(
+                                    [
+                                        package.options.australiapost_delivery_date.state,
+                                        package.options.australiapost_delivery_time_start.state,
+                                        package.options.australiapost_delivery_time_end.state,
+                                        package.options.australiapost_pickup_date.state,
+                                        package.options.australiapost_pickup_time.state,
+                                        package.options.australiapost_identity_on_delivery.state,
+                                        package.options.australiapost_print_at_depot.state,
+                                        package.options.australiapost_sameday_identity_on_delivery.state,
+                                        payload.customs,
+                                    ]
+                                )
+                                else None
+                            ),
+                            classification_type=(
+                                # fmt: off
+                                provider_units.ContentType.map(customs.content_type).value or "OTHER" 
+                                if payload.customs 
+                                else None
+                                # fmt: on
+                            ),
+                            commercial_value=customs.commercial_invoice,
+                            description_of_other=customs.content_description,
+                            export_declaration_number=customs.options.export_declaration_number.state,
+                            import_reference_number=customs.options.import_reference_number.state,
+                            item_contents=(
+                                [
+                                    australiapost.ItemContentType(
+                                        country_of_origin=content.country,
+                                        description=content.description,
+                                        sku=content.sku,
+                                        quantity=content.quantity,
+                                        tariff_code=content.hs_code,
+                                        value=content.value_amount,
+                                        weight=content.weight,
+                                        item_contents_reference=None,
+                                    )
+                                    for content in (
+                                        package.items
+                                        if any(package.items)
+                                        else customs.commodities
+                                    )
+                                ]
+                                if is_intl
+                                else []
+                            ),
+                        )
+                        for idx, package in enumerate(packages, start=1)
+                    ],
+                    movement_type="DESPATCH",
+                )
+            ]
+        ),
+        label=label_request.LabelRequestType(
+            wait_for_label_url=True,
+            preferences=[
+                label_request.PreferenceType(
+                    type="PRINT",
+                    format=label_format,
+                    groups=[
+                        label_request.GroupType(
+                            group=label_group,
+                            layout=label_layout,
+                            branded=True,
+                            left_offset=0,
+                            top_offset=0,
+                        )
+                    ],
+                )
+            ],
+            shipments=[label_request.ShipmentType(shipment_id="[SHIPMENT_ID]")],
+        ),
+    )
+
+    return lib.Serializable(
+        request,
+        lambda _: dict(
+            shipment=lib.to_dict(
+                lib.to_json(_["shipment"]).replace("shipment_from", "from")
+            ),
+            label=lib.to_dict(_["label"]),
+        ),
+        dict(label_format=label_format),
+    )

karrio/providers/australiapost/tracking.py

@@ -0,0 +1,84 @@
+import karrio.schemas.australiapost.tracking_request as australiapost
+import karrio.schemas.australiapost.tracking_response as tracking
+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_tracking_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    tracking_results = response.get("tracking_results") or []
+    messages = sum(
+        [
+            error.parse_error_response(
+                result,
+                settings,
+                tracking_number=result.get("tracking_id"),
+            )
+            for result in tracking_results
+            if "errors" in result
+        ],
+        start=error.parse_error_response(response, settings),
+    )
+    tracking_details = [
+        _extract_details(details, settings)
+        for details in tracking_results
+        if "trackable_items" in details
+    ]
+
+    return tracking_details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.TrackingDetails:
+    detail = lib.to_object(tracking.TrackingResultType, data)
+    item = detail.trackable_items[0]
+    status = next(
+        (
+            status.name
+            for status in list(provider_units.TrackingStatus)
+            if item.status in status.value
+        ),
+        provider_units.TrackingStatus.in_transit.name,
+    )
+
+    return models.TrackingDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=detail.tracking_id,
+        events=[
+            models.TrackingEvent(
+                date=lib.fdate(event.date, "%Y-%m-%dT%H:%M:%S%z"),
+                description=event.description,
+                location=event.location,
+                time=lib.flocaltime(event.date, "%Y-%m-%dT%H:%M:%S%z"),
+            )
+            for event in item.events
+        ],
+        delivered=(status == provider_units.TrackingStatus.delivered.name),
+        status=status,
+        info=models.TrackingInfo(
+            carrier_tracking_link=settings.tracking_url.format(detail.tracking_id),
+            shipment_service=item.product_type,
+        ),
+    )
+
+
+def tracking_request(
+    payload: models.TrackingRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    request = australiapost.TrackingRequestType(
+        tracking_ids=payload.tracking_numbers,
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/australiapost/units.py

@@ -0,0 +1,159 @@
+import karrio.lib as lib
+import karrio.core.units as units
+
+
+class PackagingType(lib.StrEnum):
+    """Carrier specific packaging type"""
+
+    box = "BOX"
+    carton = "CTN"
+    pallet = "PAL"
+    satchel = "SAT"
+    bag = "BAG"
+    envelope = "ENV"
+    item = "ITM"
+    jiffy_bag = "JIF"
+    skid = "SKI"
+
+    """ Unified Packaging type mapping """
+    pak = satchel
+    tube = item
+    small_box = box
+    medium_box = box
+    your_packaging = box
+
+
+class LabelType(lib.Enum):
+    PDF_A4_1pp = ("PDF", "A4-1pp")
+    ZPL_A4_1pp = ("ZPL", "A4-1pp")
+    PDF_A4_3pp = ("PDF", "A4-3pp")
+    ZPL_A4_3pp = ("ZPL", "A4-3pp")
+    PDF_A4_4pp = ("PDF", "A4-4pp")
+    ZPL_A4_4pp = ("ZPL", "A4-4pp")
+    PDF_A6_1pp = ("PDF", "A6-1pp")
+    ZPL_A6_1pp = ("ZPL", "A6-1pp")
+    PDF_A4_2pp = ("PDF", "A4-2pp")
+    ZPL_A4_2pp = ("ZPL", "A4-2pp")
+    PDF_A4_1pp_landscape = ("PDF", "A4-1pp landscape")
+    ZPL_A4_1pp_landscape = ("ZPL", "A4-1pp landscape")
+    PDF_A4_2pp_landscape = ("PDF", "A4-2pp landscape")
+    ZPL_A4_2pp_landscape = ("ZPL", "A4-2pp landscape")
+
+    """ Unified Label type mapping """
+    PDF = PDF_A4_1pp
+    ZPL = PDF_A4_1pp
+    PNG = PDF_A4_1pp
+
+
+class CustomsContentType(lib.StrEnum):
+    """Carrier specific customs content type"""
+
+    document = "DOCUMENT"
+    gift = "GIFT"
+    sample = "SAMPLE"
+    other = "OTHER"
+    return_of_goods = "RETURN"
+    sale_of_goods = "SALE_OF_GOODS"
+
+    """ Unified Content type mapping """
+    documents = document
+    merchandise = sale_of_goods
+    return_merchandise = return_of_goods
+
+
+class ServiceLabelGroup(lib.StrEnum):
+    """Carrier specific services"""
+
+    australiapost_parcel_post = "Parcel Post"
+    australiapost_express_post = "Express Post"
+    australiapost_startrack_courier = "Startrack Courier"
+    australiapost_startrack = "StarTrack"
+    australiapost_on_demand = "On Demand"
+    australiapost_international = "International"
+    australiapost_commercial = "Commercial"
+
+
+class ShippingService(lib.StrEnum):
+    """Carrier specific services"""
+
+    australiapost_parcel_post = "T28"
+    australiapost_express_post = "E34"
+    australiapost_parcel_post_signature = "3D55"
+    australiapost_express_post_signature = "3J55"
+    australiapost_intl_standard_pack_track = "PTI8"
+    australiapost_intl_standard_with_signature = "PTI7"
+    australiapost_intl_express_merch = "ECM8"
+    australiapost_intl_express_docs = "ECD8"
+    australiapost_eparcel_post_returns = "PR"
+    australiapost_express_eparcel_post_returns = "XPR"
+
+    # australiapost_parcel_post = "PARCEL POST"
+    # australiapost_express_post = "EXPRESS POST"
+    # australiapost_parcel_post_signature = "PARCEL POST + SIGNATURE"
+    # australiapost_express_post_signature = "EXPRESS POST + SIGNATURE"
+    # australiapost_intl_standard_pack_track = "INTL STANDARD/PACK & TRACK"
+    # australiapost_intl_standard_with_signature = "INT'L STANDARD WITH SIGNATURE"
+    # australiapost_intl_express_merch = "INTL EXPRESS MERCH"
+    # australiapost_intl_express_docs = "INTL EXPRESS DOCS"
+    # australiapost_eparcel_post_returns = "EPARCEL POST RETURNS"
+    # australiapost_express_eparcel_post_returns = "EXPRESS EPARCEL POST RETURNS"
+
+
+class ShippingOption(lib.Enum):
+    """Carrier specific options"""
+
+    # fmt: off
+    australiapost_delivery_date = lib.OptionEnum("DELIVERY_DATE")
+    australiapost_delivery_time_start = lib.OptionEnum("DELIVERY_TIMES")
+    australiapost_delivery_time_end = lib.OptionEnum("DELIVERY_TIMES")
+    australiapost_pickup_date = lib.OptionEnum("PICKUP_DATE")
+    australiapost_pickup_time = lib.OptionEnum("PICKUP_TIME")
+    australiapost_identity_on_delivery = lib.OptionEnum("IDENTITY_ON_DELIVERY")
+    australiapost_print_at_depot = lib.OptionEnum("PRINT_AT_DEPOT", bool)
+    australiapost_transit_cover = lib.OptionEnum("TRANSIT_COVER", float)
+    australiapost_sameday_identity_on_delivery = lib.OptionEnum("SAMEDAY_IDENTITY_ON_DELIVERY")
+
+    australiapost_authority_to_leave = lib.OptionEnum("authority_to_leave", bool)
+    australiapost_allow_partial_delivery = lib.OptionEnum("allow_partial_delivery", bool)
+    australiapost_contains_dangerous_goods = lib.OptionEnum("contains_dangerous_goods", bool)
+
+    """ Unified Option type mapping """
+
+    insurance = australiapost_transit_cover
+    # fmt: on
+
+
+def shipping_options_initializer(
+    options: dict,
+    package_options: units.ShippingOptions = None,
+) -> units.ShippingOptions:
+    """
+    Apply default values to the given options.
+    """
+
+    if package_options is not None:
+        options.update(package_options.content)
+
+    def items_filter(key: str) -> bool:
+        return key in ShippingOption and key not in [  # type: ignore
+            "australiapost_authority_to_leave",
+            "australiapost_allow_partial_delivery",
+            "australiapost_contains_dangerous_goods",
+        ]
+
+    return units.ShippingOptions(options, ShippingOption, items_filter=items_filter)
+
+
+class TrackingStatus(lib.Enum):
+    on_hold = ["Possible delay", "Held by courier"]
+    delivered = ["Delivered", "Delivered in Full"]
+    in_transit = ["In transit"]
+    delivery_failed = [
+        "Article damaged",
+        "Cancelled",
+        "Cannot be delivered",
+        "Unsuccessful Delivery",
+    ]
+    delivery_delayed = ["Possible delay", "To be Re-Delivered"]
+    out_for_delivery = ["On Board for Delivery"]
+    ready_for_pickup = ["Awaiting collection", "Ready for Pickup"]

karrio/providers/australiapost/utils.py

@@ -0,0 +1,34 @@
+import base64
+import karrio.core as core
+
+
+class Settings(core.Settings):
+    """Australia Post connection settings."""
+
+    # Carrier specific properties
+    api_key: str
+    password: str
+    account_number: str
+
+    account_country_code: str = "AU"
+
+    @property
+    def carrier_name(self):
+        return "australiapost"
+
+    @property
+    def server_url(self):
+        return (
+            "https://digitalapi.auspost.com.au/test"
+            if self.test_mode
+            else "https://digitalapi.auspost.com.au"
+        )
+
+    @property
+    def tracking_url(self):
+        return "https://auspost.com.au/mypost/beta/track/details/{}"
+
+    @property
+    def authorization(self):
+        pair = "%s:%s" % (self.api_key, self.password)
+        return base64.b64encode(pair.encode("utf-8")).decode("ascii")

karrio/schemas/australiapost/error_response.py

@@ -0,0 +1,22 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class ErrorType:
+    error_code: typing.Optional[str] = None
+    error_name: typing.Optional[str] = None
+    code: typing.Optional[str] = None
+    name: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+    field: typing.Optional[str] = None
+    context: typing.Optional[typing.List[typing.Any]] = None
+    messages: typing.Optional[typing.List[typing.Any]] = None
+    error: typing.Optional[str] = None
+    error_description: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ErrorResponseType:
+    errors: typing.Optional[typing.List[ErrorType]] = jstruct.JList[ErrorType]

karrio/schemas/australiapost/label_request.py

@@ -0,0 +1,37 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class GroupType:
+    group: typing.Optional[str] = None
+    layout: typing.Optional[str] = None
+    branded: typing.Optional[bool] = None
+    left_offset: typing.Optional[int] = None
+    top_offset: typing.Optional[int] = None
+
+
+@attr.s(auto_attribs=True)
+class PreferenceType:
+    type: typing.Optional[str] = None
+    format: typing.Optional[str] = None
+    groups: typing.Optional[typing.List[GroupType]] = jstruct.JList[GroupType]
+
+
+@attr.s(auto_attribs=True)
+class ItemType:
+    item_id: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ShipmentType:
+    shipment_id: typing.Optional[str] = None
+    items: typing.Optional[typing.List[ItemType]] = jstruct.JList[ItemType]
+
+
+@attr.s(auto_attribs=True)
+class LabelRequestType:
+    wait_for_label_url: typing.Optional[bool] = None
+    preferences: typing.Optional[typing.List[PreferenceType]] = jstruct.JList[PreferenceType]
+    shipments: typing.Optional[typing.List[ShipmentType]] = jstruct.JList[ShipmentType]

karrio/schemas/australiapost/label_response.py

@@ -0,0 +1,31 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class ItemType:
+    item_id: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ShipmentType:
+    shipment_id: typing.Optional[str] = None
+    options: typing.Optional[typing.List[typing.Any]] = None
+    items: typing.Optional[typing.List[ItemType]] = jstruct.JList[ItemType]
+
+
+@attr.s(auto_attribs=True)
+class LabelType:
+    request_id: typing.Optional[str] = None
+    url: typing.Optional[str] = None
+    status: typing.Optional[str] = None
+    request_date: typing.Optional[str] = None
+    url_creation_date: typing.Optional[str] = None
+    shipments: typing.Optional[typing.List[ShipmentType]] = jstruct.JList[ShipmentType]
+    shipment_ids: typing.Optional[typing.List[str]] = None
+
+
+@attr.s(auto_attribs=True)
+class LabelResponseType:
+    labels: typing.Optional[typing.List[LabelType]] = jstruct.JList[LabelType]

karrio/schemas/australiapost/manifest_request.py

@@ -0,0 +1,16 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class ShipmentType:
+    shipment_id: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ManifestRequestType:
+    order_reference: typing.Optional[str] = None
+    payment_method: typing.Optional[str] = None
+    consignor: typing.Optional[str] = None
+    shipments: typing.Optional[typing.List[ShipmentType]] = jstruct.JList[ShipmentType]