karrio-spring 2026.1.3__py3-none-any.whl

karrio/mappers/spring/__init__.py

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

karrio/mappers/spring/mapper.py

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

karrio/mappers/spring/proxy.py

@@ -0,0 +1,71 @@
+"""Karrio Spring client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.spring.settings as provider_settings
+import karrio.universal.mappers.rating_proxy as rating_proxy
+
+
+class Proxy(rating_proxy.RatingMixinProxy, proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        return super().get_rates(request)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Create shipments using Spring OrderShipment API.
+
+        Spring is a per-package carrier, so we make parallel requests
+        for each package and return a list of responses.
+        """
+        responses = lib.run_asynchronously(
+            lambda req: lib.request(
+                url=self.settings.server_url,
+                data=lib.to_json(req),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={"Content-Type": "text/json"},
+            ),
+            request.serialize(),
+        )
+
+        return lib.Deserializable(
+            responses,
+            lambda __: [lib.to_dict(res) for res in __],
+        )
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=self.settings.server_url,
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={"Content-Type": "text/json"},
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Track shipments using Spring TrackShipment API.
+
+        Spring tracks one shipment at a time, so we make parallel requests
+        for each tracking number and return results as (tracking_number, response) tuples.
+        """
+        responses = lib.run_asynchronously(
+            lambda req: (
+                req["Shipment"]["TrackingNumber"],
+                lib.request(
+                    url=self.settings.server_url,
+                    data=lib.to_json(req),
+                    trace=self.trace_as("json"),
+                    method="POST",
+                    headers={"Content-Type": "text/json"},
+                ),
+            ),
+            request.serialize(),
+        )
+
+        return lib.Deserializable(
+            responses,
+            lambda __: [(tracking_number, lib.to_dict(res)) for tracking_number, res in __],
+        )

karrio/mappers/spring/settings.py

@@ -0,0 +1,33 @@
+"""Karrio Spring client settings."""
+
+import attr
+import typing
+import jstruct
+import karrio.core.models as models
+import karrio.providers.spring.units as provider_units
+import karrio.providers.spring.utils as provider_utils
+import karrio.universal.mappers.rating_proxy as rating_proxy
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings, rating_proxy.RatingMixinSettings):
+    """Spring connection settings."""
+
+    # Carrier-specific credentials
+    api_key: str
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "spring"
+    services: typing.List[models.ServiceLevel] = jstruct.JList[models.ServiceLevel, False, dict(default=provider_units.DEFAULT_SERVICES)]  # type: ignore
+    account_country_code: str = None
+    metadata: dict = {}
+    config: dict = {}
+
+    @property
+    def shipping_services(self) -> typing.List[models.ServiceLevel]:
+        if any(self.services or []):
+            return self.services
+
+        return provider_units.DEFAULT_SERVICES

karrio/plugins/spring/__init__.py

@@ -0,0 +1,20 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.spring as mappers
+import karrio.providers.spring.units as units
+
+
+METADATA = metadata.PluginMetadata(
+    status="beta",
+    id="spring",
+    label="Spring",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    is_hub=False,
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    service_levels=units.DEFAULT_SERVICES,
+    connection_configs=units.ConnectionConfig,
+)

karrio/providers/spring/__init__.py

@@ -0,0 +1,12 @@
+"""Karrio Spring provider imports."""
+from karrio.providers.spring.utils import Settings
+from karrio.providers.spring.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.spring.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)

karrio/providers/spring/error.py

@@ -0,0 +1,48 @@
+"""Karrio Spring error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.spring.utils as provider_utils
+
+
+def parse_error_response(
+    response: dict,
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    """Parse Spring API error response.
+
+    Spring API uses ErrorLevel codes:
+    - 0: Command successfully completed without any errors
+    - 1: Command completed with errors (e.g., shipment created with errors)
+    - 10: Fatal error, command is not completed at all
+    """
+    errors: typing.List[models.Message] = []
+
+    if not isinstance(response, dict):
+        return errors
+
+    error_level = response.get("ErrorLevel")
+    error_message = response.get("Error") or ""
+
+    # ErrorLevel 0 means success, no errors
+    if error_level == 0:
+        return errors
+
+    # ErrorLevel 1 or 10 indicates an error
+    if error_level in (1, 10):
+        errors.append(
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code=str(error_level),
+                message=error_message or (
+                    "Command completed with errors" if error_level == 1
+                    else "Fatal error, command not completed"
+                ),
+                details={**kwargs},
+            )
+        )
+
+    return errors

karrio/providers/spring/shipment/__init__.py

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

karrio/providers/spring/shipment/cancel.py

@@ -0,0 +1,54 @@
+"""Karrio Spring shipment cancellation API implementation."""
+
+import karrio.schemas.spring.shipment_cancel_request as spring_req
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.spring.error as error
+import karrio.providers.spring.utils as provider_utils
+
+
+def parse_shipment_cancel_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    """Parse VoidShipment response from Spring API."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # ErrorLevel 0 means success
+    success = response.get("ErrorLevel") == 0 and not any(messages)
+
+    confirmation = (
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            operation="Cancel Shipment",
+            success=success,
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def shipment_cancel_request(
+    payload: models.ShipmentCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a VoidShipment request for Spring API."""
+
+    # Spring API allows either TrackingNumber or ShipperReference
+    # payload.shipment_identifier is used as TrackingNumber
+    request = spring_req.ShipmentCancelRequestType(
+        Apikey=settings.api_key,
+        Command="VoidShipment",
+        Shipment=spring_req.ShipmentType(
+            TrackingNumber=payload.shipment_identifier,
+        ),
+    )
+
+    return lib.Serializable(request, lib.to_dict)
+    

karrio/providers/spring/shipment/create.py

@@ -0,0 +1,242 @@
+"""Karrio Spring shipment API implementation."""
+
+import karrio.schemas.spring.shipment_request as spring_req
+import karrio.schemas.spring.shipment_response as spring_res
+
+import uuid
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.spring.error as error
+import karrio.providers.spring.utils as provider_utils
+import karrio.providers.spring.units as provider_units
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[typing.List[dict]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.Optional[models.ShipmentDetails], typing.List[models.Message]]:
+    """Parse shipment responses from Spring API.
+
+    Spring is a per-package carrier, so we receive a list of responses
+    (one per package) and aggregate them using lib.to_multi_piece_shipment().
+    """
+    responses = _response.deserialize()
+
+    # Collect all error messages from all responses
+    messages: typing.List[models.Message] = sum(
+        [error.parse_error_response(response, settings) for response in responses],
+        start=[],
+    )
+
+    # Extract shipment details for successful responses
+    shipment_details = [
+        (
+            f"{index}",
+            (
+                _extract_details(response, settings)
+                if response.get("Shipment") and response.get("ErrorLevel") in (0, 1)
+                else None
+            ),
+        )
+        for index, response in enumerate(responses, start=1)
+    ]
+
+    # Aggregate multi-piece shipment
+    shipment = lib.to_multi_piece_shipment(shipment_details)
+
+    return shipment, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.ShipmentDetails:
+    """Extract shipment details from Spring API response."""
+    response = lib.to_object(spring_res.ShipmentResponseType, data)
+    shipment = response.Shipment
+
+    # Get tracking number - used as shipment_identifier for cancel operations
+    tracking_number = shipment.TrackingNumber
+
+    # Get label data - label_format defaults to PDF if not specified
+    label_format = shipment.LabelFormat or "PDF"
+
+    # Build documents object
+    documents = models.Documents(label=shipment.LabelImage)
+
+    return models.ShipmentDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=tracking_number,
+        shipment_identifier=tracking_number,
+        label_type=label_format,
+        docs=documents,
+        meta=dict(
+            service=shipment.Service,
+            carrier=shipment.Carrier,
+            shipper_reference=shipment.ShipperReference,
+            carrier_tracking_number=shipment.CarrierTrackingNumber,
+            carrier_local_tracking_number=shipment.CarrierLocalTrackingNumber,
+            carrier_tracking_url=shipment.CarrierTrackingUrl,
+            display_id=shipment.DisplayId,
+            label_type=shipment.LabelType,
+        ),
+    )
+
+
+def shipment_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create Spring OrderShipment requests.
+
+    Spring is a per-package carrier, so we create one request per package
+    and return a list of requests to be processed in parallel.
+    """
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    packages = lib.to_packages(payload.parcels)
+    service = provider_units.ShippingService.map(payload.service).value_or_key
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+
+    # Get customs info for international shipments
+    customs = lib.to_customs_info(
+        payload.customs,
+        shipper=shipper,
+        recipient=recipient,
+        weight_unit=units.WeightUnit.KG.name,
+    )
+
+    # Determine label format from settings or payload
+    label_format = (
+        provider_units.LabelFormat.map(payload.label_type).value
+        or settings.connection_config.label_format.state
+        or "PDF"
+    )
+
+    # Build consignor (shipper) address (same for all packages)
+    consignor_address = spring_req.ConsignorAddressType(
+        Name=shipper.person_name or shipper.company_name,
+        Company=shipper.company_name,
+        AddressLine1=shipper.address_line1,
+        AddressLine2=shipper.address_line2,
+        AddressLine3=None,
+        City=shipper.city,
+        State=shipper.state_code,
+        Zip=shipper.postal_code,
+        Country=shipper.country_code,
+        Phone=shipper.phone_number,
+        Email=shipper.email,
+        Vat=options.spring_consignor_vat.state or shipper.tax_id,
+        Eori=options.spring_consignor_eori.state,
+        NlVat=options.spring_consignor_nl_vat.state,
+        EuEori=options.spring_consignor_eu_eori.state,
+        GbEori=options.spring_consignor_gb_eori.state,
+        Ioss=options.spring_consignor_ioss.state,
+        LocalTaxNumber=options.spring_consignor_local_tax_number.state,
+    )
+
+    # Build consignee (recipient) address (same for all packages)
+    consignee_address = spring_req.AddressType(
+        Name=recipient.person_name or recipient.company_name,
+        Company=recipient.company_name,
+        AddressLine1=recipient.address_line1,
+        AddressLine2=recipient.address_line2,
+        AddressLine3=None,
+        City=recipient.city,
+        State=recipient.state_code,
+        Zip=recipient.postal_code,
+        Country=recipient.country_code,
+        Phone=recipient.phone_number,
+        Email=recipient.email,
+        Vat=recipient.tax_id,
+        PudoLocationId=options.spring_pudo_location_id.state,
+    )
+
+    # Build products array (customs items) - same for all packages
+    products = [
+        spring_req.ProductType(
+            Description=lib.text(item.description or item.title, max=60),
+            Sku=item.sku,
+            HsCode=item.hs_code,
+            OriginCountry=item.origin_country or shipper.country_code,
+            Quantity=str(item.quantity or 1),
+            Value=str(item.value_amount or 0),
+            Weight=str(item.weight or 0),
+        )
+        for item in (customs.commodities if customs else [])
+    ]
+
+    # Calculate total value from products or use declared value
+    total_value = (
+        sum(float(p.Value or 0) for p in products)
+        if products
+        else (customs.duty.declared_value if customs and customs.duty else None)
+    )
+
+    # Get declaration type mapping
+    declaration_type = None
+    if customs and customs.content_type:
+        declaration_type = provider_units.CustomsContentType.map(
+            customs.content_type
+        ).value
+
+    # Get customs duty type
+    customs_duty = options.spring_customs_duty.state or (
+        provider_units.CustomsDuty.map(customs.incoterm).value
+        if customs and customs.incoterm
+        else "DDU"
+    )
+
+    # Generate base reference for multi-piece shipment
+    base_reference = payload.reference or str(uuid.uuid4().hex)
+
+    # Create one request per package
+    requests = [
+        spring_req.ShipmentRequestType(
+            Apikey=settings.api_key,
+            Command="OrderShipment",
+            Shipment=spring_req.ShipmentType(
+                LabelFormat=label_format,
+                # Append package index to reference for multi-piece tracking
+                ShipperReference=(
+                    f"{base_reference}-{index + 1}"
+                    if len(packages) > 1
+                    else base_reference
+                ),
+                OrderReference=options.spring_order_reference.state,
+                OrderDate=options.spring_order_date.state,
+                DisplayId=options.spring_display_id.state,
+                InvoiceNumber=options.spring_invoice_number.state,
+                Service=service,
+                Weight=str(package.weight.KG),
+                WeightUnit="kg",
+                Length=str(package.length.CM) if package.length.CM else None,
+                Width=str(package.width.CM) if package.width.CM else None,
+                Height=str(package.height.CM) if package.height.CM else None,
+                DimUnit="cm" if any([package.length.CM, package.width.CM, package.height.CM]) else None,
+                Value=str(total_value) if total_value else None,
+                ShippingValue=str(options.spring_shipping_value.state) if options.spring_shipping_value.state else None,
+                Currency=customs.duty.currency if customs and customs.duty else options.currency.state,
+                CustomsDuty=customs_duty,
+                Description=package.parcel.description or (customs.content_description if customs else None),
+                DeclarationType=declaration_type or options.spring_declaration_type.state,
+                DangerousGoods="Y" if options.spring_dangerous_goods.state else "N",
+                ExportCarrierName=options.spring_export_carrier_name.state,
+                ExportAwb=options.spring_export_awb.state,
+                ConsignorAddress=consignor_address,
+                ConsigneeAddress=consignee_address,
+                # Pass empty list instead of None to avoid jstruct [None] serialization bug
+                Products=products if products else [],
+            ),
+        )
+        for index, package in enumerate(packages)
+    ]
+
+    return lib.Serializable(requests, lambda reqs: [lib.to_dict(r) for r in reqs])