karrio-canadapost 2025.5__py3-none-any.whl

karrio/providers/canadapost/shipment/create.py

@@ -0,0 +1,340 @@
+import karrio.schemas.canadapost.shipment as canadapost
+import uuid
+import typing
+import datetime
+import karrio.lib as lib
+import karrio.core.units as units
+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_response(
+    _responses: lib.Deserializable[typing.Tuple[lib.Element, str]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+    responses = _responses.deserialize()
+
+    shipment_details = [
+        (
+            f"{_}",
+            (
+                _extract_shipment(response, settings, _responses.ctx)
+                if len(lib.find_element("shipment-id", response[0])) > 0
+                else None
+            ),
+        )
+        for _, response in enumerate(responses, start=1)
+    ]
+
+    shipment = lib.to_multi_piece_shipment(shipment_details)
+    messages: typing.List[models.Message] = sum(
+        [provider_error.parse_error_response(_, settings) for _, __ in responses],
+        start=[],
+    )
+
+    return shipment, messages
+
+
+def _extract_shipment(
+    _response: typing.Tuple[lib.Element, str],
+    settings: provider_utils.Settings,
+    ctx: dict,
+) -> models.ShipmentDetails:
+    response, label = _response
+    info = lib.to_object(canadapost.ShipmentInfoType, response)
+
+    base_amount = lib.failsafe(lambda: info.shipment_price.base_amount)
+    service_code = lib.failsafe(lambda: info.shipment_price.service_code)
+    service = provider_units.ServiceType.map(service_code)
+    adjustments = lib.failsafe(lambda: info.shipment_price.adjustments.adjustment) or []
+    priced_options = lib.failsafe(lambda: info.shipment_price.priced_options.priced_option) or []
+    charges = lib.failsafe(lambda: [
+        ("Base charge", info.shipment_price.base_amount),
+        ("GST", info.shipment_price.gst_amount),
+        ("PST", info.shipment_price.pst_amount),
+        ("HST", info.shipment_price.hst_amount),
+        *((f"Option {o.option_code}", o.option_price) for o in priced_options),
+        *((a.adjustment_code, a.adjustment_amount) for a in adjustments),
+    ]) or []
+
+    return models.ShipmentDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=info.tracking_pin,
+        shipment_identifier=info.shipment_id,
+        docs=models.Documents(label=label),
+        label_type=ctx["label_type"],
+        selected_rate=lib.identity(
+            models.RateDetails(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                service=service.name_or_key,
+                total_charge=lib.to_money(base_amount),
+                currency="CAD",
+                extra_charges=lib.identity([
+                    models.ChargeDetails(name=name, amount=lib.to_money(amount), currency="CAD")
+                    for name, amount in charges
+                    if amount and lib.to_money(amount) != 0
+                ]),
+                meta=dict(
+                    service_name=(service.name or service_code),
+                ),
+            )
+            if base_amount is not None else None
+        ),
+        meta=lib.to_dict(
+            dict(
+                carrier_tracking_link=settings.tracking_url.format(info.tracking_pin),
+                customer_request_ids=ctx["customer_request_ids"],
+                manifest_required=ctx["manifest_required"],
+                group_id=ctx["group_id"],
+            )
+        ),
+    )
+
+
+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.ServiceType.map(payload.service).value_or_key
+    options = lib.to_shipping_options(
+        payload.options,
+        is_international=(
+            recipient.country_code is not None and recipient.country_code != "CA"
+        ),
+        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,
+    )
+
+    customs = lib.to_customs_info(payload.customs, weight_unit=units.WeightUnit.KG.name)
+    label_encoding, label_format = provider_units.LabelType.map(
+        payload.label_type or "PDF_4x6"
+    ).value
+    group_id = lib.fdate(datetime.datetime.now(), "%Y%m%d") + "-" + settings.carrier_id
+    customer_request_ids = [f"{str(uuid.uuid4().hex)}" for _ in range(len(packages))]
+    submit_shipment = lib.identity(
+        #  set to true if canadapost_submit_shipment is true
+        options.canadapost_submit_shipment.state
+        #  default to true if transmit_shipment_by_default is true
+        or (
+            settings.connection_config.transmit_shipment_by_default.state
+            and options.canadapost_submit_shipment.state is not False
+        )
+    )
+
+    requests = [
+        canadapost.ShipmentType(
+            customer_request_id=customer_request_ids[index],
+            groupIdOrTransmitShipment=canadapost.groupIdOrTransmitShipment(),
+            quickship_label_requested=None,
+            cpc_pickup_indicator=None,
+            requested_shipping_point=provider_utils.format_ca_postal_code(
+                shipper.postal_code
+            ),
+            shipping_point_id=None,
+            expected_mailing_date=options.shipment_date.state,
+            provide_pricing_info=True,
+            provide_receipt_info=None,
+            delivery_spec=canadapost.DeliverySpecType(
+                service_code=service,
+                sender=canadapost.SenderType(
+                    name=shipper.person_name,
+                    company=(shipper.company_name or "Not Applicable"),
+                    contact_phone=(shipper.phone_number or "000 000 0000"),
+                    address_details=canadapost.AddressDetailsType(
+                        city=shipper.city,
+                        prov_state=shipper.state_code,
+                        country_code=shipper.country_code,
+                        postal_zip_code=provider_utils.format_ca_postal_code(
+                            shipper.postal_code
+                        ),
+                        address_line_1=shipper.street,
+                        address_line_2=lib.text(shipper.address_line2),
+                    ),
+                ),
+                destination=canadapost.DestinationType(
+                    name=recipient.person_name,
+                    company=recipient.company_name,
+                    additional_address_info=None,
+                    client_voice_number=recipient.phone_number or "000 000 0000",
+                    address_details=canadapost.DestinationAddressDetailsType(
+                        city=recipient.city,
+                        prov_state=recipient.state_code,
+                        country_code=recipient.country_code,
+                        postal_zip_code=provider_utils.format_ca_postal_code(
+                            recipient.postal_code
+                        ),
+                        address_line_1=recipient.street,
+                        address_line_2=lib.text(recipient.address_line2),
+                    ),
+                ),
+                parcel_characteristics=canadapost.ParcelCharacteristicsType(
+                    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,
+                ),
+                options=(
+                    canadapost.optionsType(
+                        option=[
+                            canadapost.OptionType(
+                                option_code=option.code,
+                                option_amount=lib.to_money(option.state),
+                                option_qualifier_1=None,
+                                option_qualifier_2=None,
+                            )
+                            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
+                ),
+                notification=(
+                    canadapost.NotificationType(
+                        email=(
+                            package.options.email_notification_to.state
+                            or recipient.email
+                        ),
+                        on_shipment=True,
+                        on_exception=True,
+                        on_delivery=True,
+                    )
+                    if package.options.email_notification.state
+                    and any(
+                        [package.options.email_notification_to.state, recipient.email]
+                    )
+                    else None
+                ),
+                print_preferences=canadapost.PrintPreferencesType(
+                    output_format=label_format,
+                    encoding=label_encoding,
+                ),
+                preferences=canadapost.PreferencesType(
+                    service_code=None,
+                    show_packing_instructions=False,
+                    show_postage_rate=True,
+                    show_insured_value=True,
+                ),
+                customs=(
+                    canadapost.CustomsType(
+                        currency=(options.currency.state or units.Currency.CAD.name),
+                        conversion_from_cad=None,
+                        reason_for_export="OTH",
+                        other_reason=customs.content_type,
+                        duties_and_taxes_prepaid=customs.duty.account_number,
+                        certificate_number=customs.options.certificate_number.state,
+                        licence_number=lib.text(
+                            customs.options.license_number.state, max=10
+                        ),
+                        invoice_number=lib.text(customs.invoice, max=10),
+                        sku_list=(
+                            (
+                                canadapost.sku_listType(
+                                    item=[
+                                        canadapost.SkuType(
+                                            customs_number_of_units=item.quantity,
+                                            customs_description=lib.text(
+                                                item.title
+                                                or item.description
+                                                or item.sku
+                                                or "N/B",
+                                                max=35,
+                                            ),
+                                            sku=item.sku or "0000",
+                                            hs_tariff_code=item.hs_code,
+                                            unit_weight=(item.weight or 1),
+                                            customs_value_per_unit=item.value_amount,
+                                            customs_unit_of_measure=None,
+                                            country_of_origin=(
+                                                item.origin_country
+                                                or shipper.country_code
+                                            ),
+                                            province_of_origin=shipper.state_code
+                                            or "N/B",
+                                        )
+                                        for item in customs.commodities
+                                    ]
+                                )
+                            )
+                            if any(customs.commodities or [])
+                            else None
+                        ),
+                    )
+                    if payload.customs is not None
+                    else None
+                ),
+                references=canadapost.ReferencesType(
+                    cost_centre=(
+                        options.canadapost_cost_center.state
+                        or settings.connection_config.cost_center.state
+                        or payload.reference
+                    ),
+                    customer_ref_1=payload.reference,
+                    customer_ref_2=None,
+                ),
+                settlement_info=canadapost.SettlementInfoType(
+                    paid_by_customer=getattr(
+                        payload.payment, "account_number", settings.customer_number
+                    ),
+                    contract_id=settings.contract_id,
+                    cif_shipment=None,
+                    intended_method_of_payment=provider_units.PaymentType.map(
+                        getattr(payload.payment, "paid_by", None)
+                    ).value,
+                    promo_code=None,
+                ),
+            ),
+            return_spec=None,
+            pre_authorized_payment=None,
+            create_qr_code=None,
+        )
+        for index, package in enumerate(packages)
+    ]
+
+    return lib.Serializable(
+        requests,
+        lambda __: [
+            lib.to_xml(
+                request,
+                name_="shipment",
+                namespacedef_='xmlns="http://www.canadapost.ca/ws/shipment-v8"',
+            ).replace(
+                "<groupIdOrTransmitShipment/>",
+                (
+                    "<transmit-shipment/>"
+                    if submit_shipment
+                    else f"<group-id>{group_id}</group-id>"
+                ),
+            )
+            for request in __
+        ],
+        dict(
+            label_type=label_encoding,
+            manifest_required=(not submit_shipment),
+            customer_request_ids=customer_request_ids,
+            group_id=(None if submit_shipment else group_id),
+        ),
+    )

karrio/providers/canadapost/tracking.py

@@ -0,0 +1,75 @@
+import karrio.schemas.canadapost.track as capost
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.canadapost.error as error
+import karrio.providers.canadapost.units as provider_units
+import karrio.providers.canadapost.utils as provider_utils
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    details = lib.find_element("tracking-detail", response)
+    tracking_details: typing.List[models.TrackingDetails] = [
+        _extract_tracking(node, settings)
+        for node in details
+        if len(lib.find_element("occurrence", node)) > 0
+    ]
+
+    return tracking_details, error.parse_error_response(response, settings)
+
+
+def _extract_tracking(
+    detail_node: lib.Element,
+    settings: provider_utils.Settings,
+) -> models.TrackingDetails:
+    details = lib.to_object(capost.tracking_detail, detail_node)
+    events: typing.List[capost.occurrenceType] = details.significant_events.occurrence
+    last_event = events[0]
+    estimated_delivery = lib.fdate(
+        details.changed_expected_date or details.expected_delivery_date,
+        "%Y-%m-%d",
+    )
+    status = next(
+        (
+            status.name
+            for status in list(provider_units.TrackingStatus)
+            if last_event.event_identifier in status.value
+        ),
+        provider_units.TrackingStatus.in_transit.name,
+    )
+
+    return models.TrackingDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=details.pin,
+        estimated_delivery=estimated_delivery,
+        delivered=status == "delivered",
+        status=status,
+        events=[
+            models.TrackingEvent(
+                date=lib.fdate(event.event_date, "%Y-%m-%d"),
+                time=lib.flocaltime(event.event_time, "%H:%M:%S"),
+                code=event.event_identifier,
+                location=lib.join(
+                    event.event_site, event.event_province, join=True, separator=", "
+                ),
+                description=event.event_description,
+            )
+            for event in events
+        ],
+        info=models.TrackingInfo(
+            carrier_tracking_link=settings.tracking_url.format(details.pin),
+            shipment_destination_postal_code=details.destination_postal_id,
+            shipment_delivery_date=estimated_delivery,
+            shipment_service=details.service_name,
+            signed_by=last_event.signatory_name,
+        ),
+    )
+
+
+def tracking_request(payload: models.TrackingRequest, _) -> lib.Serializable:
+    return lib.Serializable(payload.tracking_numbers)

karrio/providers/canadapost/units.py

@@ -0,0 +1,285 @@
+import karrio.lib as lib
+
+PRESET_DEFAULTS = dict(
+    dimension_unit="CM",
+    weight_unit="KG",
+)
+
+MeasurementOptions = lib.units.MeasurementOptionsType(
+    quant=0.1,
+    min_kg=0.01,
+    min_in=0.01,
+)
+
+
+class PackagePresets(lib.Enum):
+    """
+    Note that dimensions are in CM and weight in KG
+    """
+
+    canadapost_mailing_box = lib.units.PackagePreset(
+        **dict(width=10.2, height=15.2, length=1.0), **PRESET_DEFAULTS
+    )
+    canadapost_extra_small_mailing_box = lib.units.PackagePreset(
+        **dict(width=14.0, height=14.0, length=14.0), **PRESET_DEFAULTS
+    )
+    canadapost_small_mailing_box = lib.units.PackagePreset(
+        **dict(width=28.6, height=22.9, length=6.4), **PRESET_DEFAULTS
+    )
+    canadapost_medium_mailing_box = lib.units.PackagePreset(
+        **dict(width=31.0, height=23.5, length=13.3), **PRESET_DEFAULTS
+    )
+    canadapost_large_mailing_box = lib.units.PackagePreset(
+        **dict(width=38.1, height=30.5, length=9.5), **PRESET_DEFAULTS
+    )
+    canadapost_extra_large_mailing_box = lib.units.PackagePreset(
+        **dict(width=40.0, height=30.5, length=21.6), **PRESET_DEFAULTS
+    )
+    canadapost_corrugated_small_box = lib.units.PackagePreset(
+        **dict(width=42.0, height=32.0, length=32.0), **PRESET_DEFAULTS
+    )
+    canadapost_corrugated_medium_box = lib.units.PackagePreset(
+        **dict(width=46.0, height=38.0, length=32.0), **PRESET_DEFAULTS
+    )
+    canadapost_corrugated_large_box = lib.units.PackagePreset(
+        **dict(width=46.0, height=46.0, length=40.6), **PRESET_DEFAULTS
+    )
+    canadapost_xexpresspost_certified_envelope = lib.units.PackagePreset(
+        **dict(width=26.0, height=15.9, weight=0.5, length=1.5), **PRESET_DEFAULTS
+    )
+    canadapost_xexpresspost_national_large_envelope = lib.units.PackagePreset(
+        **dict(width=40.0, height=29.2, weight=1.36, length=1.5), **PRESET_DEFAULTS
+    )
+    canadapost_xexpresspost_regional_small_envelope = lib.units.PackagePreset(
+        **dict(width=26.0, height=15.9, weight=0.5, length=1.5), **PRESET_DEFAULTS
+    )
+    canadapost_xexpresspost_regional_large_envelope = lib.units.PackagePreset(
+        **dict(width=40.0, height=29.2, weight=1.36, length=1.5), **PRESET_DEFAULTS
+    )
+
+
+class LabelType(lib.Enum):
+    PDF_4x6 = ("PDF", "4x6")
+    PDF_8_5x11 = ("PDF", "8.5x11")
+    ZPL_4x6 = ("ZPL", "4x6")
+
+    """ Unified Label type mapping """
+    PDF = PDF_4x6
+    ZPL = ZPL_4x6
+
+
+class PaymentType(lib.StrEnum):
+    account = "Account"
+    card = "CreditCard"
+    supplier_account = "SupplierAccount"
+
+    sender = account
+    recipient = account
+    third_party = supplier_account
+    credit_card = card
+
+
+class ConnectionConfig(lib.Enum):
+    cost_center = lib.OptionEnum("cost_center")
+    label_type = lib.OptionEnum("label_type", LabelType)
+    shipping_options = lib.OptionEnum("shipping_options", list)
+    shipping_services = lib.OptionEnum("shipping_services", list)
+    transmit_shipment_by_default = lib.OptionEnum("transmit_shipment_by_default", bool)
+
+
+class ServiceType(lib.Enum):
+    canadapost_regular_parcel = "DOM.RP"
+    canadapost_expedited_parcel = "DOM.EP"
+    canadapost_xpresspost = "DOM.XP"
+    canadapost_xpresspost_certified = "DOM.XP.CERT"
+    canadapost_priority = "DOM.PC"
+    canadapost_library_books = "DOM.LIB"
+    canadapost_expedited_parcel_usa = "USA.EP"
+    canadapost_priority_worldwide_envelope_usa = "USA.PW.ENV"
+    canadapost_priority_worldwide_pak_usa = "USA.PW.PAK"
+    canadapost_priority_worldwide_parcel_usa = "USA.PW.PARCEL"
+    canadapost_small_packet_usa_air = "USA.SP.AIR"
+    canadapost_tracked_packet_usa = "USA.TP"
+    canadapost_tracked_packet_usa_lvm = "USA.TP.LVM"
+    canadapost_xpresspost_usa = "USA.XP"
+    canadapost_xpresspost_international = "INT.XP"
+    canadapost_international_parcel_air = "INT.IP.AIR"
+    canadapost_international_parcel_surface = "INT.IP.SURF"
+    canadapost_priority_worldwide_envelope_intl = "INT.PW.ENV"
+    canadapost_priority_worldwide_pak_intl = "INT.PW.PAK"
+    canadapost_priority_worldwide_parcel_intl = "INT.PW.PARCEL"
+    canadapost_small_packet_international_air = "INT.SP.AIR"
+    canadapost_small_packet_international_surface = "INT.SP.SURF"
+    canadapost_tracked_packet_international = "INT.TP"
+
+
+class ShippingOption(lib.Enum):
+    canadapost_signature = lib.OptionEnum("SO", bool)
+    canadapost_coverage = lib.OptionEnum("COV", float)
+    canadapost_collect_on_delivery = lib.OptionEnum("COD", float)
+    canadapost_proof_of_age_required_18 = lib.OptionEnum("PA18", bool)
+    canadapost_proof_of_age_required_19 = lib.OptionEnum("PA19", bool)
+    canadapost_card_for_pickup = lib.OptionEnum("HFP", bool)
+    canadapost_do_not_safe_drop = lib.OptionEnum("DNS", bool)
+    canadapost_leave_at_door = lib.OptionEnum("LAD", bool)
+    canadapost_deliver_to_post_office = lib.OptionEnum("D2PO", bool)
+    canadapost_return_at_senders_expense = lib.OptionEnum("RASE", bool)
+    canadapost_return_to_sender = lib.OptionEnum("RTS", bool)
+    canadapost_abandon = lib.OptionEnum("ABAN", bool)
+
+    """ Custom Option """
+    canadapost_cost_center = lib.OptionEnum("cost-centre")
+    canadapost_submit_shipment = lib.OptionEnum("transmit-shipment", bool)
+
+    """ Unified Option type mapping """
+    insurance = canadapost_coverage
+    cash_on_delivery = canadapost_collect_on_delivery
+    signature_confirmation = canadapost_signature
+
+
+def shipping_options_initializer(
+    options: dict,
+    package_options: lib.units.ShippingOptions = None,
+    is_international: bool = False,
+) -> lib.units.ShippingOptions:
+    _options = options.copy()
+
+    # Apply default non delivery options for if international.
+    no_international_option_specified: bool = not any(
+        key in _options for key in INTERNATIONAL_NON_DELIVERY_OPTION
+    )
+
+    if is_international and no_international_option_specified:
+        _options.update(
+            {ShippingOption.canadapost_return_at_senders_expense.name: True}
+        )
+
+    # Apply package options if specified.
+    if package_options is not None:
+        _options.update(package_options.content)
+
+    # Define carrier option filter.
+    def items_filter(key: str) -> bool:
+        return key in ShippingOption and key not in CUSTOM_OPTIONS  # type:ignore
+
+    return lib.units.ShippingOptions(
+        _options, ShippingOption, items_filter=items_filter
+    )
+
+
+class TrackingStatus(lib.Enum):
+    """Carrier tracking status mapping"""
+
+    delivered = [
+        "1408",
+        "1409",
+        "1421",
+        "1422",
+        "1423",
+        "1424",
+        "1425",
+        "1426",
+        "1427",
+        "1428",
+        "1429",
+        "1430",
+        "1431",
+        "1432",
+        "1433",
+        "1434",
+        "1441",
+        "1442",
+        "1496",
+        "1497",
+        "1498",
+        "1499",
+    ]
+    in_transit = [""]
+    on_hold = [
+        "117",
+        "120",
+        "121",
+        "125",
+        "127",
+        "810",
+        "1411",
+        "1414",
+        "1443",
+        "1484",
+        "1487",
+        "1494",
+        "2411",
+        "2414",
+        "4700",
+    ]
+    ready_for_pickup = [
+        "118",
+        "156",
+        "1407",
+        "1410",
+        "1435",
+        "1436",
+        "1437",
+        "1438",
+        "1479",
+        "1488",
+        "1701",
+        "2410",
+    ]
+    delivery_failed = [
+        "150",
+        "154",
+        "167",
+        "168",
+        "169",
+        "167",
+        "168",
+        "169",
+        "179",
+        "181",
+        "182",
+        "183",
+        "184",
+        "190",
+        "1100",
+        "1415",
+        "1416",
+        "1417",
+        "1418",
+        "1419",
+        "1420",
+        "1450",
+        "1481",
+        "1482",
+        "1483",
+        "1491",
+        "1492",
+        "1493",
+        "2600",
+        "2802",
+        "3001",
+        "4650",
+    ]
+    delivery_delayed = [
+        "159",
+        "160",
+        "161",
+        "162",
+        "163",
+        "172",
+        "173",
+        "2412",
+    ]
+    out_for_delivery = ["174", "500"]
+
+
+INTERNATIONAL_NON_DELIVERY_OPTION = [
+    ShippingOption.canadapost_return_at_senders_expense.name,
+    ShippingOption.canadapost_return_to_sender.name,
+    ShippingOption.canadapost_abandon.name,
+]
+
+CUSTOM_OPTIONS = [
+    ShippingOption.canadapost_cost_center.name,
+    ShippingOption.canadapost_submit_shipment.name,
+]