karrio-easyship 2025.5rc1__py3-none-any.whl

karrio/providers/easyship/shipment/create.py

@@ -0,0 +1,306 @@
+"""Karrio Easyship shipment API implementation."""
+
+import karrio.schemas.easyship.shipment_request as easyship
+import karrio.schemas.easyship.shipment_response as shipping
+
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.easyship.error as error
+import karrio.providers.easyship.utils as provider_utils
+import karrio.providers.easyship.units as provider_units
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = error.parse_error_response(response, settings)
+    shipment = lib.identity(
+        _extract_details(response, settings, ctx=_response.ctx)
+        if response.get("shipment")
+        and any(response["shipment"].get("shipping_documents") or [])
+        else None
+    )
+
+    return shipment, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+    ctx: dict,
+) -> models.ShipmentDetails:
+    details = lib.to_object(shipping.ShipmentType, data["shipment"])
+    label_document = next(
+        (_ for _ in details.shipping_documents if _.category == "label"), None
+    )
+    label_type = (label_document.format or ctx.get("label_type") or "PDF").upper()
+    label = lib.bundle_base64(label_document.base64_encoded_strings, label_type)
+    tracking_numbers = [tracking.tracking_number for tracking in details.trackings]
+    tracking_number, *__ = tracking_numbers
+
+    return models.ShipmentDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=tracking_number,
+        shipment_identifier=details.easyship_shipment_id,
+        label_type=label_type,
+        docs=models.Documents(label=label),
+        meta=dict(
+            shipment_ids=[details.easyship_shipment_id],
+            tracking_numbers=tracking_numbers,
+            carrier=ctx["rate_provider"],
+            rate_provider=ctx["rate_provider"],
+            easyship_courier_id=ctx["courier_id"],
+            easyship_shipment_id=details.easyship_shipment_id,
+            easyship_courier_account_id=details.courier.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)
+    return_address = lib.to_address(payload.return_address or payload.shipper)
+    packages = lib.to_packages(payload.parcels, options=payload.options)
+    weight_unit, dimension_unit = packages.compatible_units
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+    service = lib.identity(
+        options.easyship_courier_id.state
+        or provider_units.ShippingServiceID.map(payload.service).name_or_key
+    )
+    courier = provider_units.ShippingCourierID.find(service)
+    customs = lib.to_customs_info(
+        payload.customs,
+        shipper=payload.shipper,
+        recipient=payload.recipient,
+        weight_unit=weight_unit.name,
+    )
+    incoterms = lib.identity(
+        options.easyship_incoterms.state or customs.options.incoterm.state or "DDU"
+    )
+    label_type = provider_units.LabelFormat.map(payload.label_type)
+
+    # map data to convert karrio model to easyship specific type
+    request = easyship.ShipmentRequestType(
+        buyer_regulatory_identifiers=lib.identity(
+            easyship.BuyerRegulatoryIdentifiersType(
+                ein=customs.duty_billing_address.tax_id,
+                vat_number=customs.options.vat_registration_number.state,
+            )
+            if any(
+                [
+                    customs.options.vat_registration_number.state,
+                    customs.duty_billing_address.tax_id,
+                ]
+            )
+            else None
+        ),
+        courier_selection=easyship.CourierSelectionType(
+            allow_courier_fallback=lib.identity(
+                options.easyship_allow_courier_fallback.state
+                if options.easyship_allow_courier_fallback.state is not None
+                else settings.connection_config.allow_courier_fallback.state
+            ),
+            apply_shipping_rules=lib.identity(
+                options.easyship_apply_shipping_rules.state
+                if options.easyship_apply_shipping_rules.state is not None
+                else settings.connection_config.apply_shipping_rules.state
+            ),
+            list_unavailable_couriers=lib.identity(
+                options.easyship_list_unavailable_couriers.state
+                if options.easyship_list_unavailable_couriers.state is not None
+                else False
+            ),
+            selected_courier_id=service,
+        ),
+        destination_address=easyship.AddressType(
+            city=recipient.city,
+            company_name=lib.text(recipient.company_name or "N/A", max=22),
+            contact_email=lib.identity(
+                recipient.email
+                or options.email_notification_to.state
+                or "user@mail.com"
+            ),
+            contact_name=lib.text(recipient.person_name, max=22),
+            contact_phone=recipient.phone_number or "N/A",
+            country_alpha2=recipient.country_code,
+            line_1=recipient.address_line1,
+            line_2=recipient.address_line2,
+            postal_code=recipient.postal_code,
+            state=recipient.state_code,
+        ),
+        consignee_tax_id=recipient.tax_id,
+        eei_reference=options.easyship_eei_reference.state,
+        incoterms=incoterms,
+        metadata=payload.metadata,
+        insurance=easyship.InsuranceType(
+            is_insured=options.insurance.state is not None
+        ),
+        order_data=None,
+        origin_address=easyship.AddressType(
+            city=return_address.city,
+            company_name=lib.text(return_address.company_name or "N/A", max=22),
+            contact_email=lib.identity(
+                return_address.email
+                or options.email_notification_to.state
+                or "user@mail.com"
+            ),
+            contact_name=lib.text(return_address.person_name, max=22),
+            contact_phone=return_address.phone_number or "N/A",
+            country_alpha2=return_address.country_code,
+            line_1=return_address.address_line1,
+            line_2=return_address.address_line2,
+            postal_code=return_address.postal_code,
+            state=return_address.state_code,
+        ),
+        regulatory_identifiers=lib.identity(
+            easyship.RegulatoryIdentifiersType(
+                eori=customs.options.eori.state,
+                ioss=customs.options.ioss.state,
+                vat_number=customs.options.vat_registration_number.state,
+            )
+            if any(
+                [
+                    customs.options.eori.state,
+                    customs.options.vat_registration_number.state,
+                    customs.duty_billing_address.tax_id,
+                ]
+            )
+            else None
+        ),
+        shipment_request_return=options.is_return.state,
+        return_address=easyship.AddressType(
+            city=return_address.city,
+            company_name=lib.text(return_address.company_name or "N/A", max=22),
+            contact_email=lib.identity(
+                return_address.email
+                or options.email_notification_to.state
+                or "user@mail.com"
+            ),
+            contact_name=lib.text(return_address.person_name, max=22),
+            contact_phone=return_address.phone_number or "N/A",
+            country_alpha2=return_address.country_code,
+            line_1=return_address.address_line1,
+            line_2=return_address.address_line2,
+            postal_code=return_address.postal_code,
+            state=return_address.state_code,
+        ),
+        return_address_id=options.easyship_return_address_id.state,
+        sender_address=easyship.AddressType(
+            city=shipper.city,
+            company_name=lib.text(shipper.company_name or "N/A", max=22),
+            contact_email=lib.identity(
+                shipper.email or options.email_notification_to.state or "user@mail.com"
+            ),
+            contact_name=lib.text(shipper.person_name, max=22),
+            contact_phone=shipper.phone_number or "N/A",
+            country_alpha2=shipper.country_code,
+            line_1=shipper.address_line1,
+            line_2=shipper.address_line2,
+            postal_code=shipper.postal_code,
+            state=shipper.state_code,
+        ),
+        sender_address_id=options.easyship_sender_address_id.state,
+        set_as_residential=recipient.residential,
+        shipping_settings=easyship.ShippingSettingsType(
+            additional_services=lib.identity(
+                easyship.AdditionalServicesType(
+                    delivery_confirmation=None,
+                    qr_code=None,
+                )
+                if any(
+                    [
+                        options.easyship_delivery_confirmation.state,
+                        options.easyship_qr_code.state,
+                    ]
+                )
+                else None
+            ),
+            b13_a_filing=None,
+            buy_label=True,
+            buy_label_synchronous=True,
+            printing_options=easyship.PrintingOptionsType(
+                commercial_invoice="A4",
+                format=label_type.value or "pdf",
+                label="4x6",
+                packing_slip=None,
+                remarks=payload.reference,
+            ),
+            units=easyship.UnitsType(
+                dimensions=provider_units.DimensionUnit.map(dimension_unit.name).value,
+                weight=provider_units.WeightUnit.map(weight_unit.name).value,
+            ),
+        ),
+        parcels=[
+            easyship.ParcelType(
+                box=easyship.BoxType(
+                    height=package.height.value,
+                    length=package.length.value,
+                    width=package.width.value,
+                    slug=package.parcel.options.get("easyship_box_slug"),
+                ),
+                items=[
+                    easyship.ItemType(
+                        dimensions=None,
+                        declared_currency=lib.identity(
+                            item.value_currency or options.currency.state or "USD"
+                        ),
+                        origin_country_alpha2=lib.identity(
+                            item.origin_country or shipper.country_code
+                        ),
+                        quantity=item.quantity,
+                        actual_weight=item.weight,
+                        category=item.category or "bags_luggages",
+                        declared_customs_value=item.value_amount,
+                        description=item.description or item.title or "Item",
+                        sku=item.sku or "N/A",
+                        hs_code=item.hs_code or "N/A",
+                        contains_liquids=item.metadata.get("contains_liquids"),
+                        contains_battery_pi966=item.metadata.get(
+                            "contains_battery_pi966"
+                        ),
+                        contains_battery_pi967=item.metadata.get(
+                            "contains_battery_pi967"
+                        ),
+                    )
+                    for item in lib.identity(
+                        (package.items if any(package.items) else customs.commodities)
+                        if any(package.items) or any(payload.customs or "")
+                        else [
+                            models.Commodity(
+                                title=lib.text(package.description, max=35),
+                                quantity=1,
+                                value_amount=1.0,
+                            )
+                        ]
+                    )
+                ],
+                total_actual_weight=package.weight.value,
+            )
+            for package in packages
+        ],
+    )
+
+    return lib.Serializable(
+        request,
+        lambda _: lib.to_dict(
+            lib.to_json(_).replace("shipment_request_return", "return")
+        ),
+        ctx=dict(
+            courier_id=service,
+            rate_provider=courier.name,
+            label_type=label_type.name or "PDF",
+        ),
+    )

karrio/providers/easyship/tracking.py

@@ -0,0 +1,110 @@
+"""Karrio Easyship tracking API implementation."""
+
+# import karrio.schemas.easyship.tracking_request as easyship
+# import karrio.schemas.easyship.tracking_response as tracking
+import karrio.schemas.easyship.shipment_response as shipping
+
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.easyship.error as error
+import karrio.providers.easyship.utils as provider_utils
+import karrio.providers.easyship.units as provider_units
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[typing.List[typing.Tuple[str, dict]]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+    responses = _response.deserialize()
+
+    messages: typing.List[models.Message] = sum(
+        [
+            error.parse_error_response(response, settings, shipment_id=_)
+            for _, response in responses
+        ],
+        start=[],
+    )
+    tracking_details = [
+        _extract_details(details, settings)
+        for _, details in responses
+        if details.get("shipment") is not None and any(details["shipment"]["trackings"])
+    ]
+
+    return tracking_details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.TrackingDetails:
+    details = lib.to_object(shipping.ShipmentType, data["shipment"])
+    master = details.trackings[0]
+    status = next(
+        (
+            status.name
+            for status in list(provider_units.TrackingStatus)
+            if getattr(master, "tracking_state", None) in status.value
+        ),
+        provider_units.TrackingStatus.in_transit.name,
+    )
+
+    return models.TrackingDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=master.tracking_number,
+        delivered=status == "delivered",
+        status=status,
+        events=[
+            models.TrackingEvent(
+                code=str(master.leg_number),
+                date=lib.ftime(details.updated_at, "%Y-%m-%dT%H:%M:%SZ"),
+                time=lib.ftime(details.updated_at, "%Y-%m-%dT%H:%M:%SZ"),
+                description="",
+            )
+        ],
+    )
+
+
+def tracking_request(
+    payload: models.TrackingRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Send one or multiple tracking request(s) to Easyship.
+    the payload must match the following schema:
+    {
+        "tracking_numbers": ["123456789"],
+        "shipment_ids": ["ESSG10006002"],
+        "options": {
+            "123456789": {
+                "carrier": "usps",
+                "easyship_shipment_id": "trk_xxxxxxxx",  # optional
+            }
+        }
+    }
+    """
+
+    requests: typing.List[dict] = []
+
+    for tracking_number in payload.tracking_numbers:
+        options = payload.options.get(tracking_number) or {}
+        shipment_id = lib.identity(
+            options.get("easyship_shipment_id")
+            or payload.options.get("easyship_shipment_id")
+        )
+        should_add = lib.identity(
+            shipment_id is not None
+            and not any(_.get("easyship_shipment_id") == shipment_id for _ in requests)
+        )
+
+        if should_add:
+            requests.append(
+                dict(
+                    tracking_number=tracking_number,
+                    shipment_id=shipment_id,
+                    carrier=options.get("carrier"),
+                )
+            )
+
+    return lib.Serializable(requests, lib.to_dict)

karrio/providers/easyship/units.py

@@ -0,0 +1,162 @@
+import typing
+import pathlib
+import karrio.lib as lib
+import karrio.core.units as units
+
+METADATA_JSON = lib.load_json(pathlib.Path(__file__).resolve().parent / "metadata.json")
+EASYSHIP_CARRIER_METADATA = [_ for sublist in METADATA_JSON for _ in sublist]
+KARRIO_CARRIER_MAPPING = {
+    "canada_post": "canadapost",
+    "dhl": "dhl_express",
+}
+
+
+class LabelFormat(lib.StrEnum):
+    """Carrier specific label format"""
+
+    pdf = "pdf"
+    png = "png"
+    zpl = "zpl"
+    url = "url"
+
+    PDF = pdf
+    PNG = png
+    ZPL = zpl
+
+
+class Incoterms(lib.StrEnum):
+    """Carrier specific incoterms"""
+
+    DDU = "DDU"
+    DDP = "DDP"
+
+
+class DimensionUnit(lib.StrEnum):
+    """Carrier specific dimension unit"""
+
+    CM = "cm"
+    IN = "in"
+
+
+class WeightUnit(lib.StrEnum):
+    """Carrier specific weight unit"""
+
+    LB = "lb"
+    KG = "kg"
+
+
+class PackagingType(lib.StrEnum):
+    """Carrier specific packaging type"""
+
+    PACKAGE = "PACKAGE"
+
+    """ Unified Packaging type mapping """
+    envelope = PACKAGE
+    pak = PACKAGE
+    tube = PACKAGE
+    pallet = PACKAGE
+    small_box = PACKAGE
+    medium_box = PACKAGE
+    your_packaging = PACKAGE
+
+
+class ShippingOption(lib.Enum):
+    """Carrier specific options"""
+
+    # fmt: off
+    easyship_box_slug = lib.OptionEnum("box_slug")
+    easyship_courier_id = lib.OptionEnum("courier_id")
+    easyship_eei_reference = lib.OptionEnum("eei_reference")
+    easyship_incoterms = lib.OptionEnum("incoterms", Incoterms)
+    easyship_apply_shipping_rules = lib.OptionEnum("apply_shipping_rules", bool)
+    easyship_show_courier_logo_url = lib.OptionEnum("show_courier_logo_url", bool)
+    easyship_allow_courier_fallback = lib.OptionEnum("allow_courier_fallback", bool)
+    easyship_list_unavailable_couriers = lib.OptionEnum("list_unavailable_couriers", bool)
+    easyship_buyer_notes = lib.OptionEnum("buyer_notes")
+    easyship_seller_notes = lib.OptionEnum("seller_notes")
+    easyship_sender_address_id = lib.OptionEnum("sender_address_id")
+    easyship_return_address_id = lib.OptionEnum("return_address_id")
+    # 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  # type: ignore
+
+    return units.ShippingOptions(options, ShippingOption, items_filter=items_filter)
+
+
+class TrackingStatus(lib.Enum):
+    on_hold = ["on_hold"]
+    delivered = ["delivered"]
+    in_transit = ["in_transit"]
+    delivery_failed = ["delivery_failed"]
+    delivery_delayed = ["delivery_delayed"]
+    out_for_delivery = ["out_for_delivery"]
+    ready_for_pickup = ["ready_for_pickup"]
+
+
+def to_service_code(service: typing.Dict[str, str]) -> str:
+    return lib.to_slug(
+        f'easyship_{to_carrier_code(service)}_{lib.to_snake_case(service["service_name"])}'
+    )
+
+
+def to_carrier_code(service: typing.Dict[str, str]) -> str:
+    code = lib.to_slug(service["umbrella_name"])
+    return KARRIO_CARRIER_MAPPING.get(code, code)
+
+
+def find_courier(search: str):
+    courier: dict = next(
+        (
+            item
+            for item in EASYSHIP_CARRIER_METADATA
+            if item["name"] == search
+            or item["id"] == search
+            or item["umbrella_name"] == search
+            or to_service_code(item) == search
+            or to_carrier_code(item) == search
+        ),
+        {},
+    )
+    if courier:
+        return ShippingCourierID.map(to_carrier_code(courier))
+
+    return ShippingCourierID.map(search)
+
+
+ShippingService = lib.StrEnum(
+    "ShippingService",
+    {
+        to_service_code(service): service["service_name"]
+        for service in EASYSHIP_CARRIER_METADATA
+    },
+)
+
+ShippingServiceID = lib.StrEnum(
+    "ShippingServiceID",
+    {service["id"]: to_service_code(service) for service in EASYSHIP_CARRIER_METADATA},
+)
+
+ShippingCourierID = lib.StrEnum(
+    "ShippingCourierID",
+    {
+        to_carrier_code(courier): courier["name"]
+        for courier in {
+            _["umbrella_name"]: _ for _ in EASYSHIP_CARRIER_METADATA
+        }.values()
+    },
+)
+
+setattr(ShippingCourierID, "find", find_courier)

karrio/providers/easyship/utils.py

@@ -0,0 +1,98 @@
+import base64
+import datetime
+import karrio.lib as lib
+import karrio.core as core
+import karrio.core.errors as errors
+
+
+class Settings(core.Settings):
+    """Easyship connection settings."""
+
+    # Add carrier specific api connection properties here
+    access_token: str
+
+    @property
+    def carrier_name(self):
+        return "easyship"
+
+    @property
+    def server_url(self):
+        return "https://api.easyship.com"
+
+    # """uncomment the following code block to expose a carrier tracking url."""
+    # @property
+    # def tracking_url(self):
+    #     return "https://www.carrier.com/tracking?tracking-id={}"
+
+    # """uncomment the following code block to implement the Basic auth."""
+    # @property
+    # def authorization(self):
+    #     pair = "%s:%s" % (self.username, self.password)
+    #     return base64.b64encode(pair.encode("utf-8")).decode("ascii")
+
+    @property
+    def connection_config(self) -> lib.units.Options:
+        return lib.to_connection_config(
+            self.config or {},
+            option_type=ConnectionConfig,
+        )
+
+
+#     """uncomment the following code block to implement the oauth login."""
+#     @property
+#     def access_token(self):
+#         """Retrieve the access_token using the client_id|client_secret pair
+#         or collect it from the cache if an unexpired access_token exist.
+#         """
+#         cache_key = f"{self.carrier_name}|{self.client_id}|{self.client_secret}"
+#         now = datetime.datetime.now() + datetime.timedelta(minutes=30)
+
+#         auth = self.connection_cache.get(cache_key) or {}
+#         token = auth.get("access_token")
+#         expiry = lib.to_date(auth.get("expiry"), current_format="%Y-%m-%d %H:%M:%S")
+
+#         if token is not None and expiry is not None and expiry > now:
+#             return token
+
+#         self.connection_cache.set(cache_key, lambda: login(self))
+#         new_auth = self.connection_cache.get(cache_key)
+
+#         return new_auth["access_token"]
+
+# """uncomment the following code block to implement the oauth login."""
+# def login(settings: Settings):
+#     import karrio.providers.easyship.error as error
+
+#     result = lib.request(
+#         url=f"{settings.server_url}/oauth/token",
+#         method="POST",
+#         headers={"content-Type": "application/x-www-form-urlencoded"},
+#         data=lib.to_query_string(
+#             dict(
+#                 grant_type="client_credentials",
+#                 client_id=settings.client_id,
+#                 client_secret=settings.client_secret,
+#             )
+#         ),
+#     )
+
+#     response = lib.to_dict(result)
+#     messages = error.parse_error_response(response, settings)
+
+#     if any(messages):
+#         raise errors.ParsedMessagesError(messages)
+
+#     expiry = datetime.datetime.now() + datetime.timedelta(
+#         seconds=float(response.get("expires_in", 0))
+#     )
+#     return {**response, "expiry": lib.fdatetime(expiry)}
+
+
+class ConnectionConfig(lib.Enum):
+    """Carrier specific connection configs"""
+
+    platform_name = lib.OptionEnum("platform_name")
+    apply_shipping_rules = lib.OptionEnum("apply_shipping_rules", bool)
+    allow_courier_fallback = lib.OptionEnum("allow_courier_fallback", bool)
+    shipping_options = lib.OptionEnum("shipping_options", list)
+    shipping_services = lib.OptionEnum("shipping_services", list)

karrio/schemas/easyship/error_response.py

@@ -0,0 +1,17 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class ErrorType:
+    code: typing.Optional[str] = None
+    details: typing.Optional[typing.List[str]] = None
+    message: typing.Optional[str] = None
+    request_id: typing.Optional[str] = None
+    type: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ErrorResponseType:
+    error: typing.Optional[ErrorType] = jstruct.JStruct[ErrorType]