karrio-amazon-shipping 2025.5rc30__py3-none-any.whl → 2026.1__py3-none-any.whl

karrio/mappers/amazon_shipping/mapper.py

@@ -1,67 +1,66 @@
-from typing import List, Tuple
-from karrio.api.mapper import Mapper as BaseMapper
-from karrio.mappers.amazon_shipping.settings import Settings
-from karrio.core.utils.serializable import Deserializable, Serializable
-from karrio.core.models import (
-    RateRequest,
-    ShipmentRequest,
-    ShipmentDetails,
-    ShipmentCancelRequest,
-    RateDetails,
-    Message,
-    ConfirmationDetails,
-    TrackingDetails,
-    TrackingRequest,
-)
-from karrio.providers.amazon_shipping import (
-    parse_shipment_cancel_response,
-    parse_tracking_response,
-    parse_shipment_response,
-    parse_rate_response,
-    shipment_cancel_request,
-    tracking_request,
-    shipment_request,
-    rate_request,
-)
+"""Karrio Amazon Shipping mapper."""
 
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.amazon_shipping as provider
+import karrio.mappers.amazon_shipping.settings as provider_settings
 
-class Mapper(BaseMapper):
-    settings: Settings
+
+class Mapper(mapper.Mapper):
+    """Amazon Shipping API mapper."""
+
+    settings: provider_settings.Settings
 
     # Request Mappers
 
-    def create_rate_request(self, payload: RateRequest) -> Serializable:
-        return rate_request(payload, self.settings)
+    def create_rate_request(
+        self,
+        payload: models.RateRequest,
+    ) -> lib.Serializable:
+        return provider.rate_request(payload, self.settings)
 
-    def create_shipment_request(self, payload: ShipmentRequest) -> Serializable:
-        return shipment_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: ShipmentCancelRequest
-    ) -> Serializable:
-        return shipment_cancel_request(payload, self.settings)
+        self,
+        payload: models.ShipmentCancelRequest,
+    ) -> lib.Serializable:
+        return provider.shipment_cancel_request(payload, self.settings)
 
-    def create_tracking_request(self, payload: TrackingRequest) -> Serializable:
-        return tracking_request(payload, self.settings)
+    def create_tracking_request(
+        self,
+        payload: models.TrackingRequest,
+    ) -> lib.Serializable:
+        return provider.tracking_request(payload, self.settings)
 
     # Response Parsers
 
     def parse_rate_response(
-        self, response: Deserializable
-    ) -> Tuple[List[RateDetails], List[Message]]:
-        return parse_rate_response(response, self.settings)
+        self,
+        response: lib.Deserializable,
+    ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+        return provider.parse_rate_response(response, self.settings)
 
     def parse_shipment_response(
-        self, response: Deserializable
-    ) -> Tuple[ShipmentDetails, List[Message]]:
-        return parse_shipment_response(response, self.settings)
+        self,
+        response: lib.Deserializable,
+    ) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_response(response, self.settings)
 
     def parse_cancel_shipment_response(
-        self, response: Deserializable
-    ) -> Tuple[ConfirmationDetails, List[Message]]:
-        return parse_shipment_cancel_response(response, self.settings)
+        self,
+        response: lib.Deserializable,
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_cancel_response(response, self.settings)
 
     def parse_tracking_response(
-        self, response: Deserializable
-    ) -> Tuple[List[TrackingDetails], List[Message]]:
-        return parse_tracking_response(response, self.settings)
+        self,
+        response: lib.Deserializable,
+    ) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+        return provider.parse_tracking_response(response, self.settings)

karrio/mappers/amazon_shipping/proxy.py

@@ -1,65 +1,195 @@
+"""Karrio Amazon Shipping API proxy."""
+
 import typing
+import datetime
 import karrio.lib as lib
 import karrio.api.proxy as proxy
+import karrio.core.errors as errors
+import karrio.core.models as models
+import karrio.providers.amazon_shipping.error as provider_error
 from karrio.mappers.amazon_shipping.settings import Settings
 
 
 class Proxy(proxy.Proxy):
+    """Amazon Shipping SP-API proxy."""
+
     settings: Settings
 
+    def authenticate(self, _=None) -> lib.Deserializable[str]:
+        """Obtain access token using LWA OAuth2 refresh token flow.
+
+        The token is cached and refreshed when expired.
+        """
+        cache_key = f"{self.settings.carrier_name}|{self.settings.client_id}"
+
+        def get_token():
+            result = lib.request(
+                url=self.settings.token_url,
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                data=lib.to_query_string(dict(
+                    grant_type="refresh_token",
+                    refresh_token=self.settings.refresh_token,
+                    client_id=self.settings.client_id,
+                    client_secret=self.settings.client_secret,
+                )),
+                max_retries=2,
+            )
+
+            response = lib.to_dict(result)
+
+            if "error" in response:
+                raise errors.ParsedMessagesError(
+                    messages=[
+                        models.Message(
+                            carrier_name=self.settings.carrier_name,
+                            carrier_id=self.settings.carrier_id,
+                            message=response.get("error_description", response["error"]),
+                            code=response.get("error"),
+                        )
+                    ]
+                )
+
+            access_token = response.get("access_token")
+            if not access_token:
+                raise errors.ParsedMessagesError(
+                    messages=[
+                        models.Message(
+                            carrier_name=self.settings.carrier_name,
+                            carrier_id=self.settings.carrier_id,
+                            message="Authentication failed: No access token received",
+                            code="AUTH_ERROR",
+                        )
+                    ]
+                )
+
+            expiry = datetime.datetime.now() + datetime.timedelta(
+                seconds=float(response.get("expires_in", 3600))
+            )
+
+            return {
+                **response,
+                "expiry": lib.fdatetime(expiry),
+                "access_token": access_token,
+            }
+
+        token_state = self.settings.connection_cache.thread_safe(
+            refresh_func=get_token,
+            cache_key=cache_key,
+            buffer_minutes=5,
+            token_field="access_token",
+        )
+
+        # Handle both Token object and direct dict from cache
+        state = (
+            token_state.get_state()
+            if hasattr(token_state, "get_state")
+            else token_state
+        )
+        access_token = (
+            state.get("access_token")
+            if isinstance(state, dict)
+            else state
+        )
+
+        return lib.Deserializable(access_token)
+
     def get_rates(self, request: lib.Serializable) -> lib.Deserializable:
+        """Get shipping rates using the v2 getRates API."""
         response = self._send_request(
-            path="/shipping/v1/rates",
-            request=lib.Serializable(request, lib.to_json),
+            path="/shipping/v2/shipments/rates",
+            request=request,
         )
 
         return lib.Deserializable(response, lib.to_dict)
 
     def create_shipment(self, request: lib.Serializable) -> lib.Deserializable:
+        """Create shipment using the oneClickShipment API for combined rate + purchase."""
         response = self._send_request(
-            path="/shipping/v1/purchaseShipment",
-            request=lib.Serializable(request, lib.to_json),
+            path="/shipping/v2/oneClickShipment",
+            request=request,
         )
 
         return lib.Deserializable(response, lib.to_dict)
 
     def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable:
+        """Cancel shipment using the v2 cancelShipment API."""
+        shipment_id = request.serialize()
         response = self._send_request(
-            path=f"/shipping/v1/shipments/{request.serialize()}/cancel",
+            path=f"/shipping/v2/shipments/{shipment_id}/cancel",
+            request=None,
+            method="PUT",
         )
 
-        return lib.Deserializable(response if any(response) else "{}", lib.to_dict)
+        return lib.Deserializable(
+            response if response.strip() else "{}",
+            lib.to_dict,
+        )
 
     def get_tracking(self, request: lib.Serializable) -> lib.Deserializable:
-        track = lambda trackingId: (
-            trackingId,
-            self._send_request(
-                path=f"/shipping/v1/tracking/{trackingId}",
-                method="GET",
-            ),
-        )
+        """Get tracking information using the v2 getTracking API."""
+        access_token = self.authenticate().deserialize()
+        tracking_data = request.serialize()
+
+        def track(data: dict) -> typing.Tuple[str, str]:
+            tracking_id = data.get("tracking_id")
+            carrier_id = data.get("carrier_id", "AMZN_US")
+
+            return (
+                tracking_id,
+                lib.request(
+                    url=f"{self.settings.server_url}/shipping/v2/tracking",
+                    trace=self.trace_as("json"),
+                    method="GET",
+                    headers=self._get_headers(access_token),
+                    params=dict(
+                        trackingId=tracking_id,
+                        carrierId=carrier_id,
+                    ),
+                ),
+            )
 
         responses: typing.List[typing.Tuple[str, str]] = lib.run_asynchronously(
-            track, request.serialize()
+            track, tracking_data
         )
+
         return lib.Deserializable(
             responses,
             lambda res: [(key, lib.to_dict(response)) for key, response in res],
         )
 
     def _send_request(
-        self, path: str, request: lib.Serializable = None, method: str = "POST"
+        self,
+        path: str,
+        request: lib.Serializable = None,
+        method: str = "POST",
     ) -> str:
-        data: dict = dict(data=request.serialize()) if request is not None else dict()
+        """Send request to Amazon Shipping API."""
+        access_token = self.authenticate().deserialize()
+        data = dict(data=request.serialize()) if request is not None else {}
+
         return lib.request(
-            **{
-                "url": f"{self.settings.server_url}{path}",
-                "trace": self.trace_as("json"),
-                "method": method,
-                "headers": {
-                    "Content-Type": "application/json",
-                    "x-amz-access-token": self.settings.access_token,
-                },
-                **data,
-            }
+            url=f"{self.settings.server_url}{path}",
+            trace=self.trace_as("json"),
+            method=method,
+            headers=self._get_headers(access_token),
+            **data,
         )
+
+    def _get_headers(self, access_token: str) -> dict:
+        """Get request headers with authentication and business ID."""
+        headers = {
+            "Content-Type": "application/json",
+            "x-amz-access-token": access_token,
+        }
+
+        # Add shipping business ID if configured
+        business_id = (
+            self.settings.shipping_business_id
+            or self.settings.connection_config.shipping_business_id.state
+        )
+        if business_id:
+            headers["x-amzn-shipping-business-id"] = business_id
+
+        return headers

karrio/mappers/amazon_shipping/settings.py

@@ -1,22 +1,35 @@
 """Karrio Amazon Shipping connection settings."""
 
 import attr
-import jstruct
-import karrio.lib as lib
-from karrio.providers.amazon_shipping.utils import Settings as BaseSettings
+import karrio.providers.amazon_shipping.utils as provider_utils
 
 
 @attr.s(auto_attribs=True)
-class Settings(BaseSettings):
-    """Amazon Shipping connection settings."""
+class Settings(provider_utils.Settings):
+    """Amazon Shipping SP-API connection settings.
 
-    seller_id: str  # type:ignore
-    developer_id: str  # type:ignore
-    mws_auth_token: str  # type:ignore
+    Credentials for Login with Amazon (LWA) OAuth2 authentication:
+    - client_id: LWA application client ID
+    - client_secret: LWA application client secret
+    - refresh_token: LWA refresh token for the authorized seller
+
+    Optional configuration:
+    - aws_region: AWS region (us-east-1, eu-west-1, us-west-2)
+    - shipping_business_id: Amazon business ID header (e.g., AmazonShipping_US)
+    """
+
+    # Required SP-API credentials
+    client_id: str
+    client_secret: str
+    refresh_token: str
+
+    # Optional configuration
     aws_region: str = "us-east-1"
+    shipping_business_id: str = None
 
-    carrier_id: str = "amazon_shipping"
+    # Standard karrio settings
     account_country_code: str = None
+    carrier_id: str = "amazon_shipping"
     test_mode: bool = False
     metadata: dict = {}
     config: dict = {}

karrio/plugins/amazon_shipping/__init__.py

@@ -1,3 +1,5 @@
+"""Karrio Amazon Shipping plugin."""
+
 import karrio.core.metadata as metadata
 import karrio.mappers.amazon_shipping as mappers
 import karrio.providers.amazon_shipping.units as units
@@ -6,12 +8,13 @@ import karrio.providers.amazon_shipping.units as units
 METADATA = metadata.PluginMetadata(
     status="beta",
     id="amazon_shipping",
-    label="AmazonShipping",
+    label="Amazon Shipping",
     # Integrations
     Mapper=mappers.Mapper,
     Proxy=mappers.Proxy,
     Settings=mappers.Settings,
     # Data Units
-    services=units.Service,
+    services=units.ShippingService,
+    options=units.ShippingOption,
     has_intl_accounts=True,
 )

karrio/providers/amazon_shipping/error.py

@@ -1,4 +1,5 @@
-import karrio.schemas.amazon_shipping.error_response as amazon
+"""Karrio Amazon Shipping error parser."""
+
 import typing
 import karrio.lib as lib
 import karrio.core.models as models
@@ -6,24 +7,32 @@ import karrio.providers.amazon_shipping.utils as provider_utils
 
 
 def parse_error_response(
-    response: dict, settings: provider_utils.Settings, details: dict = None
+    response: dict,
+    settings: provider_utils.Settings,
+    **kwargs,
 ) -> typing.List[models.Message]:
-    errors = (
-        lib.to_object(amazon.ErrorResponse, response)
-        if response.get("errors") is not None
-        else amazon.ErrorResponse(errors=[])
-    )
+    """Parse error response from Amazon Shipping API.
+
+    The v2 API returns errors in the format:
+    {
+        "errors": [
+            {"code": "InvalidRequest", "message": "...", "details": "..."}
+        ]
+    }
+    """
+    errors = response.get("errors") or []
 
     return [
         models.Message(
             carrier_id=settings.carrier_id,
             carrier_name=settings.carrier_name,
-            code=error.code,
-            message=error.message,
+            code=error.get("code"),
+            message=error.get("message"),
             details={
-                **(details or {}),
-                **({} if error.details is None else {"note": error.details}),
-            },
+                **kwargs,
+                **({"note": error.get("details")} if error.get("details") else {}),
+            } or None,
         )
-        for error in errors.errors
+        for error in errors
+        if error.get("code") or error.get("message")
     ]

karrio/providers/amazon_shipping/rate.py

@@ -1,104 +1,165 @@
-import karrio.schemas.amazon_shipping.rate_request as amazon
-from karrio.schemas.amazon_shipping.rate_response import ServiceRate
+"""Karrio Amazon Shipping rating implementation."""
 
 import typing
 import karrio.lib as lib
-import karrio.core.units as units
 import karrio.core.models as models
-import karrio.core.errors as errors
-import karrio.providers.amazon_shipping.error as provider_error
-import karrio.providers.amazon_shipping.units as provider_units
+import karrio.providers.amazon_shipping.error as error
 import karrio.providers.amazon_shipping.utils as provider_utils
+import karrio.providers.amazon_shipping.units as provider_units
+import karrio.schemas.amazon_shipping.rate_response as amazon
 
 
 def parse_rate_response(
-    _response: lib.Deserializable[dict], settings: provider_utils.Settings
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
 ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    """Parse rate response from Amazon Shipping API."""
     response = _response.deserialize()
-    errors: typing.List[models.Message] = sum(
-        [
-            provider_error.parse_error_response(data, settings)
-            for data in response.get("errors", [])
-        ],
-        [],
-    )
+    messages = error.parse_error_response(response, settings)
+
     rates = [
-        _extract_details(data, settings) for data in response.get("serviceRates", [])
+        _extract_details(rate, settings)
+        for rate in response.get("rates") or []
     ]
 
-    return rates, errors
+    return rates, messages
 
 
 def _extract_details(
     data: dict,
     settings: provider_utils.Settings,
 ) -> models.RateDetails:
-    rate = lib.to_object(ServiceRate, data)
-    transit = (
-        lib.to_date(rate.promise.deliveryWindow.start, "%Y-%m-%dT%H:%M:%S.%fZ").date()
-        - lib.to_date(rate.promise.receiveWindow.end, "%Y-%m-%dT%H:%M:%S.%fZ").date()
-    ).days
+    """Extract rate details from API response."""
+    rate = lib.to_object(amazon.Rate, data)
+
+    # Calculate transit days from delivery window
+    transit_days = lib.failsafe(
+        lambda: (
+            lib.to_date(rate.promise.deliveryWindow.start).date()
+            - lib.to_date(rate.promise.pickupWindow.start).date()
+        ).days
+    )
+
+    # Extract rate items as extra charges
+    extra_charges = [
+        models.ChargeDetails(
+            name=item.rateItemNameLocalization or item.rateItemID,
+            amount=lib.to_money(item.rateItemCharge.value),
+            currency=item.rateItemCharge.unit,
+        )
+        for item in rate.rateItemList or []
+    ]
 
     return models.RateDetails(
         carrier_id=settings.carrier_id,
         carrier_name=settings.carrier_name,
-        service=provider_units.Service.map(rate.serviceType).name_or_key,
-        total_charge=lib.to_decimal(rate.totalCharge.value),
+        service=provider_units.ShippingService.map(rate.serviceId).name_or_key,
+        total_charge=lib.to_money(rate.totalCharge.value),
         currency=rate.totalCharge.unit,
-        transit_days=transit,
+        transit_days=transit_days,
+        extra_charges=extra_charges,
         meta=dict(
-            service_name=rate.serviceType,
+            rate_id=rate.rateId,
+            carrier_id=rate.carrierId,
+            carrier_name=rate.carrierName,
+            service_id=rate.serviceId,
+            service_name=rate.serviceName,
         ),
     )
 
 
-def rate_request(payload: models.RateRequest, _) -> lib.Serializable:
+def rate_request(
+    payload: models.RateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create Amazon Shipping rate request."""
     shipper = lib.to_address(payload.shipper)
     recipient = lib.to_address(payload.recipient)
-    packages = lib.to_packages(payload.parcels)
-    options = lib.to_shipping_options(payload.options)
-    services = lib.to_services(payload.services, provider_units.Service)
+    packages = lib.to_packages(payload.parcels, required=["weight"])
+    services = lib.to_services(payload.services, provider_units.ShippingService)
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
 
-    request = amazon.RateRequest(
-        shipFrom=amazon.Ship(
-            name=shipper.person_name,
-            city=shipper.city,
+    # Determine label format from options or settings
+    label_format = (
+        options.amazon_shipping_label_format.state
+        or settings.connection_config.label_format.state
+        or "PNG"
+    )
+
+    request = dict(
+        shipFrom=dict(
+            name=shipper.company_name or shipper.person_name,
             addressLine1=shipper.street,
             addressLine2=shipper.address_line2,
+            addressLine3=None,
+            companyName=shipper.company_name,
             stateOrRegion=shipper.state_code,
+            city=shipper.city,
+            countryCode=shipper.country_code,
+            postalCode=shipper.postal_code,
             email=shipper.email,
-            copyEmails=lib.join(shipper.email),
             phoneNumber=shipper.phone_number,
         ),
-        shipTo=amazon.Ship(
-            name=recipient.person_name,
-            city=recipient.city,
+        shipTo=dict(
+            name=recipient.company_name or recipient.person_name,
             addressLine1=recipient.street,
             addressLine2=recipient.address_line2,
+            addressLine3=None,
+            companyName=recipient.company_name,
             stateOrRegion=recipient.state_code,
+            city=recipient.city,
+            countryCode=recipient.country_code,
+            postalCode=recipient.postal_code,
             email=recipient.email,
-            copyEmails=lib.join(recipient.email),
             phoneNumber=recipient.phone_number,
         ),
-        serviceTypes=list(services),
         shipDate=lib.fdatetime(
-            options.shipment_date.state, "%Y-%m-%d", "%Y-%m-%dT%H:%M:%S.%fZ"
-        ),
-        containerSpecifications=[
-            amazon.ContainerSpecification(
-                dimensions=amazon.Dimensions(
-                    height=package.height.IN,
+            options.shipment_date.state,
+            current_format="%Y-%m-%d",
+            output_format="%Y-%m-%dT%H:%M:%SZ",
+        ) if options.shipment_date.state else None,
+        packages=[
+            dict(
+                dimensions=dict(
                     length=package.length.IN,
                     width=package.width.IN,
-                    unit="IN",
-                ),
-                weight=amazon.Weight(
+                    height=package.height.IN,
+                    unit="INCH",
+                ) if package.has_dimensions else None,
+                weight=dict(
                     value=package.weight.LB,
-                    unit="LB",
+                    unit="POUND",
                 ),
+                insuredValue=dict(
+                    value=lib.to_money(package.options.declared_value.state),
+                    unit=package.options.currency.state or "USD",
+                ) if package.options.declared_value.state else None,
+                packageClientReferenceId=package.parcel.id or str(index),
             )
-            for package in packages
+            for index, package in enumerate(packages, 1)
         ],
+        channelDetails=dict(
+            channelType=options.amazon_shipping_channel_type.state or "EXTERNAL",
+        ),
+        labelSpecifications=dict(
+            format=label_format,
+            size=dict(
+                length=settings.connection_config.label_size_length.state or 6,
+                width=settings.connection_config.label_size_width.state or 4,
+                unit=settings.connection_config.label_size_unit.state or "INCH",
+            ),
+            dpi=300,
+            pageLayout="DEFAULT",
+            needFileJoining=False,
+            requestedDocumentTypes=["LABEL"],
+        ),
+        serviceSelection=dict(
+            serviceId=list(services) if any(services) else None,
+        ) if any(services) else None,
     )
 
     return lib.Serializable(request, lib.to_dict)