karrio-canadapost 2025.5rc1__py3-none-any.whl

karrio/providers/canadapost/manifest.py

@@ -0,0 +1,127 @@
+import karrio.schemas.canadapost.manifest as canadapost
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.canadapost.error as error
+import karrio.providers.canadapost.utils as provider_utils
+import karrio.providers.canadapost.units as provider_units
+
+
+def parse_manifest_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    links = lib.find_element("link", response)
+
+    messages = error.parse_error_response(response, settings)
+    details = (
+        _extract_details(links, settings, _response.ctx) if len(links) > 0 else None
+    )
+
+    return details, messages
+
+
+def _extract_details(
+    links: typing.List[lib.Element],
+    settings: provider_utils.Settings,
+    ctx: dict = None,
+) -> models.ManifestDetails:
+    manifest = lib.bundle_base64(ctx["files"])
+
+    return models.ManifestDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_id,
+        doc=models.ManifestDocument(manifest=manifest),
+        meta=dict(
+            group_ids=ctx["group_ids"],
+            links=[_.get("href") for _ in links],
+        ),
+    )
+
+
+def manifest_request(
+    payload: models.ManifestRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    address = lib.to_address(payload.address)
+    options = lib.units.Options(
+        payload.options,
+        option_type=lib.units.create_enum(
+            "ManifestOptions",
+            {
+                "group_ids": lib.OptionEnum("group_ids", list),
+                "shipments": lib.OptionEnum("shipments", lib.to_dict),
+                "method_of_payment": lib.OptionEnum("method_of_payment"),
+                "shipping_point_id": lib.OptionEnum("shipping_point_id"),
+                "excluded_shipments": lib.OptionEnum("excluded_shipments", list),
+                "detailed_manifests": lib.OptionEnum("detailed_manifests", bool),
+                "cpc_pickup_indicator": lib.OptionEnum("cpc_pickup_indicator", bool),
+                "requested_shipping_point": lib.OptionEnum("requested_shipping_point"),
+            },
+        ),
+    )
+    group_ids = lib.identity(
+        options.group_ids.state
+        or [
+            *set(
+                (
+                    _.get("meta", {}).get("group_id")
+                    for _ in (options.shipments.state or [])
+                    if lib.text(_.get("meta", {}).get("group_id")) is not None
+                )
+            )
+        ]
+    )
+    retrieve_shipments = len(group_ids) == 0
+
+    request = canadapost.ShipmentTransmitSetType(
+        customer_request_id=None,
+        group_ids=canadapost.GroupIDListType(group_id=["[GROUP_IDS]"]),
+        cpc_pickup_indicator=options.cpc_pickup_indicator.state,
+        requested_shipping_point=provider_utils.format_ca_postal_code(
+            options.requested_shipping_point.state or address.postal_code
+        ),
+        shipping_point_id=options.shipping_point_id.state,
+        detailed_manifests=lib.identity(
+            True
+            if options.detailed_manifests.state is not False
+            else options.detailed_manifests.state
+        ),
+        method_of_payment=(options.method_of_payment.state or "Account"),
+        manifest_address=canadapost.ManifestAddressType(
+            manifest_name=address.contact,
+            manifest_company=address.company_name or address.contact or "N/A",
+            phone_number=address.phone_number or "000 000 0000",
+            address_details=canadapost.AddressDetailsType(
+                address_line_1=address.address_line1,
+                address_line_2=address.address_line2,
+                city=address.city,
+                prov_state=address.state_code,
+                country_code=address.country_code,
+                postal_zip_code=address.postal_code,
+            ),
+        ),
+        customer_reference=lib.text(payload.reference, max=12),
+        excluded_shipments=lib.identity(
+            canadapost.ExcludedShipmentsType(
+                shipment_id=options.excluded_shipments.state.slit(",")
+            )
+            if options.excluded_shipments.state
+            else None
+        ),
+    )
+
+    return lib.Serializable(
+        request,
+        lambda _: lib.to_xml(
+            request,
+            name_="transmit-set",
+            namespacedef_='xmlns="http://www.canadapost.ca/ws/manifest-v8"',
+        ),
+        dict(
+            group_ids=group_ids,
+            retrieve_shipments=retrieve_shipments,
+            shipment_identifiers=payload.shipment_identifiers,
+        ),
+    )

karrio/providers/canadapost/pickup/__init__.py

@@ -0,0 +1,3 @@
+from karrio.providers.canadapost.pickup.create import parse_pickup_response, pickup_request
+from karrio.providers.canadapost.pickup.update import parse_pickup_update_response, pickup_update_request
+from karrio.providers.canadapost.pickup.cancel import parse_pickup_cancel_response, pickup_cancel_request

karrio/providers/canadapost/pickup/cancel.py

@@ -0,0 +1,33 @@
+from typing import Tuple, List
+from karrio.core.models import (
+    PickupCancelRequest,
+    Message,
+    ConfirmationDetails,
+)
+from karrio.core.utils import Serializable, Element
+from karrio.providers.canadapost.error import parse_error_response
+from karrio.providers.canadapost.utils import Settings
+import karrio.lib as lib
+
+
+def parse_pickup_cancel_response(
+    _response: lib.Deserializable[Element], settings: Settings
+) -> Tuple[ConfirmationDetails, List[Message]]:
+    response = _response.deserialize()
+    errors = parse_error_response(response, settings)
+    cancellation = (
+        ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            success=True,
+            operation="Cancel Pickup",
+        )
+        if len(errors) == 0
+        else None
+    )
+
+    return cancellation, errors
+
+
+def pickup_cancel_request(payload: PickupCancelRequest, _) -> Serializable:
+    return Serializable(payload.confirmation_number)

karrio/providers/canadapost/pickup/create.py

@@ -0,0 +1,217 @@
+from typing import Tuple, List, Union
+from functools import partial
+from karrio.schemas.canadapost.pickup import pickup_availability
+from karrio.schemas.canadapost.pickuprequest import (
+    PickupRequestDetailsType,
+    PickupRequestUpdateDetailsType,
+    PickupLocationType,
+    AlternateAddressType,
+    ContactInfoType,
+    LocationDetailsType,
+    ItemsCharacteristicsType,
+    PickupTimesType,
+    OnDemandPickupTimeType,
+    PickupRequestPriceType,
+    PickupRequestHeaderType,
+    PickupTypeType as PickupType,
+)
+import karrio.lib as lib
+from karrio.core.utils import (
+    Serializable,
+    Element,
+    Job,
+    Pipeline,
+    DF,
+    NF,
+    XP,
+)
+from karrio.core.models import (
+    PickupRequest,
+    PickupDetails,
+    Message,
+    ChargeDetails,
+    PickupUpdateRequest,
+)
+from karrio.core.units import Packages
+from karrio.providers.canadapost.units import PackagePresets
+from karrio.providers.canadapost.utils import Settings
+from karrio.providers.canadapost.error import parse_error_response
+
+PickupRequestDetails = Union[PickupRequestDetailsType, PickupRequestUpdateDetailsType]
+
+
+def parse_pickup_response(
+    _response: lib.Deserializable[Element], settings: Settings
+) -> Tuple[PickupDetails, List[Message]]:
+    response = (
+        _response.deserialize() if hasattr(_response, "deserialize") else _response
+    )
+    pickup = (
+        _extract_pickup_details(response, settings)
+        if len(lib.find_element("pickup-request-header", response)) > 0
+        else None
+    )
+    return pickup, parse_error_response(response, settings)
+
+
+def _extract_pickup_details(response: Element, settings: Settings) -> PickupDetails:
+    header = lib.find_element(
+        "pickup-request-header", response, PickupRequestHeaderType, first=True
+    )
+    price = lib.find_element(
+        "pickup-request-price", response, PickupRequestPriceType, first=True
+    )
+    price_amount = (
+        sum(
+            [
+                NF.decimal(price.hst_amount or 0.0),
+                NF.decimal(price.gst_amount or 0.0),
+                NF.decimal(price.due_amount or 0.0),
+            ],
+            0.0,
+        )
+        if price is not None
+        else None
+    )
+
+    return PickupDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        confirmation_number=header.request_id,
+        pickup_date=DF.fdate(header.next_pickup_date),
+        pickup_charge=ChargeDetails(
+            name="Pickup fees", amount=NF.decimal(price_amount), currency="CAD"
+        )
+        if price is not None
+        else None,
+    )
+
+
+def pickup_request(payload: PickupRequest, settings: Settings) -> Serializable:
+    request: Pipeline = Pipeline(
+        get_availability=lambda *_: _get_pickup_availability(payload),
+        create_pickup=partial(_create_pickup, payload=payload, settings=settings),
+    )
+    return Serializable(request)
+
+
+def _create_pickup_request(
+    payload: PickupRequest, settings: Settings, update: bool = False
+) -> Serializable:
+    """
+    pickup_request create a serializable typed PickupRequestDetailsType
+
+    Options:
+        - five_ton_flag
+        - loading_dock_flag
+
+    :param update: bool
+    :param payload: PickupRequest
+    :param settings: Settings
+    :return: Serializable
+    """
+    RequestType = PickupRequestUpdateDetailsType if update else PickupRequestDetailsType
+    packages = Packages(payload.parcels, PackagePresets, required=["weight"])
+    heavy = any([p for p in packages if p.weight.KG > 23])
+    location_details = dict(
+        instruction=payload.instruction,
+        five_ton_flag=payload.options.get("five_ton_flag"),
+        loading_dock_flag=payload.options.get("loading_dock_flag"),
+    )
+    address = lib.to_address(payload.address)
+
+    request = RequestType(
+        customer_request_id=settings.customer_number,
+        pickup_type=PickupType.ON_DEMAND.value,
+        pickup_location=PickupLocationType(
+            business_address_flag=(not payload.address.residential),
+            alternate_address=AlternateAddressType(
+                company=address.company_name or "",
+                address_line_1=address.address_line,
+                city=address.city,
+                province=address.state_code,
+                postal_code=address.postal_code,
+            )
+            if payload.address
+            else None,
+        ),
+        contact_info=ContactInfoType(
+            contact_name=payload.address.person_name,
+            email=payload.address.email or "",
+            contact_phone=payload.address.phone_number,
+            telephone_ext=None,
+            receive_email_updates_flag=(payload.address.email is not None),
+        ),
+        location_details=(
+            LocationDetailsType(
+                five_ton_flag=location_details["five_ton_flag"],
+                loading_dock_flag=location_details["loading_dock_flag"],
+                pickup_instructions=location_details["instruction"],
+            )
+            if any(location_details.values())
+            else None
+        ),
+        items_characteristics=(
+            ItemsCharacteristicsType(
+                pww_flag=None,
+                priority_flag=None,
+                returns_flag=None,
+                heavy_item_flag=heavy,
+            )
+            if heavy
+            else None
+        ),
+        pickup_volume=f"{len(packages) or 1}",
+        pickup_times=PickupTimesType(
+            on_demand_pickup_time=OnDemandPickupTimeType(
+                date=payload.pickup_date,
+                preferred_time=payload.ready_time,
+                closing_time=payload.closing_time,
+            ),
+            scheduled_pickup_times=None,
+        ),
+        payment_info=None,
+    )
+    return Serializable(request, partial(_request_serializer, update=update))
+
+
+def _get_pickup_availability(payload: PickupRequest):
+    return Job(
+        id="availability", data=(payload.address.postal_code or "").replace(" ", "")
+    )
+
+
+def _create_pickup(
+    availability_response: str, payload: PickupRequest, settings: Settings
+):
+    availability = XP.to_object(pickup_availability, XP.to_xml(availability_response))
+    data = (
+        _create_pickup_request(payload, settings)
+        if availability.on_demand_tour
+        else None
+    )
+
+    return Job(id="create_pickup", data=data, fallback="" if data is None else "")
+
+
+def _get_pickup(
+    update_response: str, payload: PickupUpdateRequest, settings: Settings
+) -> Job:
+    errors = parse_error_response(XP.to_xml(XP.bundle_xml([update_response])), settings)
+    data = (
+        None
+        if any(errors)
+        else f"/enab/{settings.customer_number}/pickuprequest/{payload.confirmation_number}/details"
+    )
+
+    return Job(
+        id="get_pickup", data=Serializable(data), fallback="" if data is None else ""
+    )
+
+
+def _request_serializer(request: PickupRequestDetails, update: bool = False) -> str:
+    return XP.export(
+        request,
+        name_=("pickup-request-update" if update else "pickup-request-details"),
+        namespacedef_='xmlns="http://www.canadapost.ca/ws/pickuprequest"',
+    )

karrio/providers/canadapost/pickup/update.py

@@ -0,0 +1,55 @@
+import karrio.lib as lib
+from typing import cast, Tuple, List
+from functools import partial
+from karrio.core.utils import Job, Pipeline, Serializable, Element
+from karrio.core.models import (
+    PickupRequest,
+    PickupUpdateRequest,
+    PickupDetails,
+    Message,
+)
+
+from karrio.providers.canadapost.utils import Settings
+from karrio.providers.canadapost.pickup.create import (
+    parse_pickup_response,
+    _create_pickup_request,
+    _get_pickup,
+)
+
+
+def parse_pickup_update_response(
+    _response: lib.Deserializable[Element], settings: Settings
+) -> Tuple[PickupDetails, List[Message]]:
+    response = _response.deserialize()
+    return parse_pickup_response(response, settings)
+
+
+def pickup_update_request(
+    payload: PickupUpdateRequest, settings: Settings
+) -> Serializable:
+    request: Pipeline = Pipeline(
+        update_pickup=lambda *_: _update_pickup(payload, settings),
+        get_pickup=partial(_get_pickup, payload=payload, settings=settings),
+    )
+    return Serializable(request)
+
+
+def _update_pickup(payload: PickupUpdateRequest, settings: Settings) -> Job:
+    data = Serializable(
+        dict(
+            confirmation_number=payload.confirmation_number,
+            data=_create_pickup_request(
+                cast(PickupRequest, payload), settings, update=True
+            ),
+        ),
+        _update_request_serializer,
+    )
+    fallback = "" if data is None else ""
+
+    return Job(id="update_pickup", data=data, fallback=fallback)
+
+
+def _update_request_serializer(request: dict) -> dict:
+    pickuprequest = request["confirmation_number"]
+    data = request["data"].serialize()
+    return dict(pickuprequest=pickuprequest, data=data)

karrio/providers/canadapost/rate.py

@@ -0,0 +1,192 @@
+import karrio.schemas.canadapost.rating as canadapost
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.errors as errors
+import karrio.core.models as models
+import karrio.providers.canadapost.error as provider_error
+import karrio.providers.canadapost.units as provider_units
+import karrio.providers.canadapost.utils as provider_utils
+
+
+def parse_rate_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    responses = _response.deserialize()
+
+    package_rates: typing.List[typing.Tuple[str, typing.List[models.RateDetails]]] = [
+        (
+            f"{_}",
+            [
+                _extract_details(node, settings)
+                for node in lib.find_element("price-quote", response)
+            ],
+        )
+        for _, response in enumerate(responses, start=1)
+    ]
+
+    messages = provider_error.parse_error_response(responses, settings)
+    rates = lib.to_multi_piece_rates(package_rates)
+
+    return rates, messages
+
+
+def _extract_details(
+    node: lib.Element, settings: provider_utils.Settings
+) -> models.RateDetails:
+    quote = lib.to_object(canadapost.price_quoteType, node)
+    service = provider_units.ServiceType.map(quote.service_code)
+
+    adjustments = getattr(quote.price_details.adjustments, "adjustment", [])
+    charges = [
+        ("Base charge", quote.price_details.base),
+        ("GST", quote.price_details.taxes.gst.valueOf_),
+        ("PST", quote.price_details.taxes.pst.valueOf_),
+        ("HST", quote.price_details.taxes.hst.valueOf_),
+        *((a.adjustment_name, a.adjustment_cost) for a in adjustments),
+    ]
+
+    return models.RateDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        currency=units.Currency.CAD.name,
+        transit_days=quote.service_standard.expected_transit_time,
+        service=service.name_or_key,
+        total_charge=lib.to_money(quote.price_details.due or 0),
+        extra_charges=[
+            models.ChargeDetails(
+                name=name,
+                currency=units.Currency.CAD.name,
+                amount=lib.to_money(amount),
+            )
+            for name, amount in charges
+            if amount
+        ],
+        meta=dict(service_name=(service.name or quote.service_name)),
+    )
+
+
+def rate_request(
+    payload: models.RateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create the appropriate Canada Post rate request depending on the destination
+
+    :param settings: Karrio carrier connection settings
+    :param payload: Karrio unified API rate request data
+    :return: a domestic or international Canada post compatible request
+    :raises: an OriginNotServicedError when origin country is not serviced by the carrier
+    """
+    if (
+        payload.shipper.country_code
+        and payload.shipper.country_code != units.Country.CA.name
+    ):
+        raise errors.OriginNotServicedError(payload.shipper.country_code)
+
+    services = lib.to_services(payload.services, provider_units.ServiceType)
+    options = lib.to_shipping_options(
+        payload.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+    packages = lib.to_packages(
+        payload.parcels,
+        provider_units.PackagePresets,
+        required=["weight"],
+        options=options,
+        package_option_type=provider_units.ShippingOption,
+        shipping_options_initializer=provider_units.shipping_options_initializer,
+    )
+
+    requests = [
+        canadapost.mailing_scenario(
+            customer_number=settings.customer_number,
+            contract_id=settings.contract_id,
+            promo_code=None,
+            quote_type=None,
+            expected_mailing_date=package.options.shipment_date.state,
+            options=(
+                canadapost.optionsType(
+                    option=[
+                        canadapost.optionType(
+                            option_code=option.code,
+                            option_amount=lib.to_money(option.state),
+                        )
+                        for _, option in package.options.items()
+                        if option.state is not False
+                    ]
+                )
+                if any(
+                    [
+                        option
+                        for _, option in package.options.items()
+                        if option.state is not False
+                    ]
+                )
+                else None
+            ),
+            parcel_characteristics=canadapost.parcel_characteristicsType(
+                weight=package.weight.map(provider_units.MeasurementOptions).KG,
+                dimensions=canadapost.dimensionsType(
+                    length=package.length.map(provider_units.MeasurementOptions).CM,
+                    width=package.width.map(provider_units.MeasurementOptions).CM,
+                    height=package.height.map(provider_units.MeasurementOptions).CM,
+                ),
+                unpackaged=None,
+                mailing_tube=None,
+                oversized=None,
+            ),
+            services=(
+                canadapost.servicesType(service_code=[svc.value for svc in services])
+                if any(services)
+                else None
+            ),
+            origin_postal_code=provider_utils.format_ca_postal_code(
+                payload.shipper.postal_code
+            ),
+            destination=canadapost.destinationType(
+                domestic=(
+                    canadapost.domesticType(
+                        postal_code=provider_utils.format_ca_postal_code(
+                            payload.recipient.postal_code
+                        )
+                    )
+                    if (payload.recipient.country_code == units.Country.CA.name)
+                    else None
+                ),
+                united_states=(
+                    canadapost.united_statesType(
+                        zip_code=provider_utils.format_ca_postal_code(
+                            payload.recipient.postal_code
+                        )
+                    )
+                    if (payload.recipient.country_code == units.Country.US.name)
+                    else None
+                ),
+                international=(
+                    canadapost.internationalType(
+                        country_code=provider_utils.format_ca_postal_code(
+                            payload.recipient.postal_code
+                        )
+                    )
+                    if (
+                        payload.recipient.country_code
+                        not in [units.Country.US.name, units.Country.CA.name]
+                    )
+                    else None
+                ),
+            ),
+        )
+        for package in packages
+    ]
+
+    return lib.Serializable(
+        requests,
+        lambda __: [
+            lib.to_xml(
+                request,
+                namespacedef_='xmlns="http://www.canadapost.ca/ws/ship/rate-v4"',
+            )
+            for request in __
+        ],
+    )

karrio/providers/canadapost/shipment/__init__.py

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

karrio/providers/canadapost/shipment/cancel.py

@@ -0,0 +1,53 @@
+import karrio.schemas.canadapost.shipment as canadapost
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.errors as errors
+import karrio.core.models as models
+import karrio.providers.canadapost.error as provider_error
+import karrio.providers.canadapost.units as provider_units
+import karrio.providers.canadapost.utils as provider_utils
+
+
+def parse_shipment_cancel_response(
+    _responses: lib.Deserializable[typing.List[typing.Tuple[str, lib.Element]]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    responses = [
+        (_, provider_error.parse_error_response(response, settings, shipment_id=_))
+        for _, response in _responses.deserialize()
+    ]
+    messages: typing.List[models.Message] = sum([__ for _, __ in responses], start=[])
+    success = any([len(errors) == 0 for _, errors in responses])
+
+    confirmation: models.ConfirmationDetails = (
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            success=success,
+            operation="Cancel Shipment",
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def shipment_cancel_request(
+    payload: models.ShipmentCancelRequest, _
+) -> lib.Serializable:
+    request = list(
+        set(
+            [
+                payload.shipment_identifier,
+                *((payload.options or {}).get("shipment_identifiers") or []),
+            ]
+        )
+    )
+
+    return lib.Serializable(
+        request,
+        lib.identity,
+        dict(email=payload.options.get("email")),
+    )