karrio-teleship 2025.5__py3-none-any.whl

karrio/mappers/teleship/__init__.py

@@ -0,0 +1,4 @@
+from karrio.mappers.teleship.mapper import Mapper
+from karrio.mappers.teleship.proxy import Proxy
+from karrio.mappers.teleship.settings import Settings
+from karrio.mappers.teleship.hooks import Hooks

karrio/mappers/teleship/hooks.py

@@ -0,0 +1,27 @@
+"""Karrio Teleship client hooks."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.api.hooks as hooks
+import karrio.providers.teleship as provider
+import karrio.mappers.teleship.settings as provider_settings
+
+
+class Hooks(hooks.Hooks):
+    settings: provider_settings.Settings
+
+    def on_webhook_event(
+        self, payload: models.RequestPayload
+    ) -> typing.Tuple[models.WebhookEventDetails, typing.List[models.Message]]:
+        return provider.on_webhook_event(payload, self.settings)
+
+    def on_oauth_authorize(
+        self, payload: models.OAuthAuthorizePayload
+    ) -> typing.Tuple[models.OAuthAuthorizeRequest, typing.List[models.Message]]:
+        return provider.on_oauth_authorize(payload, self.settings)
+
+    def on_oauth_callback(
+        self, payload: models.RequestPayload
+    ) -> typing.Tuple[typing.List[typing.Dict], typing.List[models.Message]]:
+        return provider.on_oauth_callback(payload, self.settings)

karrio/mappers/teleship/mapper.py

@@ -0,0 +1,114 @@
+"""Karrio Teleship client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.teleship as provider
+import karrio.mappers.teleship.settings as provider_settings
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_rate_request(
+        self, payload: models.RateRequest
+    ) -> lib.Serializable:
+        return 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 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)
+
+    def create_pickup_request(
+        self, payload: models.PickupRequest
+    ) -> lib.Serializable:
+        return provider.pickup_request(payload, self.settings)
+
+    def create_cancel_pickup_request(
+        self, payload: models.PickupCancelRequest
+    ) -> lib.Serializable:
+        return provider.cancel_pickup_request(payload, self.settings)
+
+    def parse_pickup_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+        return provider.parse_pickup_response(response, self.settings)
+
+    def parse_cancel_pickup_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_cancel_pickup_response(response, self.settings)
+
+    def create_manifest_request(
+        self, payload: models.ManifestRequest
+    ) -> lib.Serializable:
+        return provider.manifest_request(payload, self.settings)
+
+    def parse_manifest_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+        return provider.parse_manifest_response(response, self.settings)
+
+    def create_duties_calculation_request(
+        self, payload: models.DutiesCalculationRequest
+    ) -> lib.Serializable:
+        return provider.duties_calculation_request(payload, self.settings)
+
+    def parse_duties_calculation_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.DutiesCalculationDetails, typing.List[models.Message]]:
+        return provider.parse_duties_calculation_response(response, self.settings)
+
+    def create_webhook_registration_request(
+        self, payload: models.WebhookRegistrationRequest
+    ) -> lib.Serializable:
+        return provider.webhook_registration_request(payload, self.settings)
+
+    def parse_webhook_registration_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.WebhookRegistrationDetails, typing.List[models.Message]]:
+        return provider.parse_webhook_registration_response(response, self.settings)
+
+    def create_webhook_deregistration_request(
+        self, payload: models.WebhookDeregistrationRequest
+    ) -> lib.Serializable:
+        return provider.webhook_deregistration_request(payload, self.settings)
+
+    def parse_webhook_deregistration_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_webhook_deregistration_response(response, self.settings)
+    

karrio/mappers/teleship/proxy.py

@@ -0,0 +1,239 @@
+"""Karrio Teleship client proxy."""
+
+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.teleship.error as provider_error
+import karrio.mappers.teleship.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def authenticate(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Retrieve access token using thread-safe token manager.
+
+        Returns the cached token if available and not expired,
+        otherwise fetches a new token from the OAuth endpoint.
+        """
+        cache_key = f"{self.settings.carrier_name}|{self.settings.client_id}|{self.settings.client_secret}"
+
+        def get_token():
+            response = lib.request(
+                url=f"{self.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",
+                        clientId=self.settings.client_id,
+                        clientSecret=self.settings.client_secret,
+                    )
+                ),
+                decoder=lib.to_dict,
+            )
+
+            messages = provider_error.parse_error_response(response, self.settings)
+
+            if any(messages):
+                raise errors.ParsedMessagesError(messages)
+
+            expiry = datetime.datetime.now() + datetime.timedelta(
+                seconds=float(response.get("expiresIn", 0))
+            )
+
+            return {**response, "expiry": lib.fdatetime(expiry)}
+
+        token = self.settings.connection_cache.thread_safe(
+            refresh_func=get_token,
+            cache_key=cache_key,
+            buffer_minutes=30,
+            token_field="accessToken",
+        )
+
+        return lib.Deserializable(token.get_state())
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+
+        responses = lib.run_asynchronously(
+            lambda payload: lib.request(
+                url=f"{self.settings.server_url}/api/rates/quotes",
+                data=lib.to_json(payload),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {access_token}",
+                },
+            ),
+            request.serialize(),
+        )
+
+        return lib.Deserializable(
+            responses,
+            lambda __: [lib.to_dict(_) for _ in __],
+        )
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+
+        responses = lib.run_asynchronously(
+            lambda payload: lib.request(
+                url=f"{self.settings.server_url}/api/shipments/labels",
+                data=lib.to_json(payload),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {access_token}",
+                },
+            ),
+            request.serialize(),
+        )
+
+        return lib.Deserializable(
+            responses,
+            lambda __: [lib.to_dict(_) for _ in __],
+        )
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+        shipment_id = request.serialize().get("shipmentId")
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/api/shipments/labels/{shipment_id}/void",
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable:
+        access_token = self.authenticate(request).deserialize()
+
+        def _get_tracking(tracking_number: str):
+            return tracking_number, lib.request(
+                url=f"{self.settings.server_url}/api/tracking/{tracking_number}",
+                trace=self.trace_as("json"),
+                method="GET",
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {access_token}",
+                },
+            )
+
+        # Use concurrent requests for multiple tracking numbers
+        responses = lib.run_concurently(_get_tracking, request.serialize())
+
+        return lib.Deserializable(
+            responses,
+            lambda res: [
+                (num, lib.to_dict(track)) for num, track in res if any(track.strip())
+            ],
+        )
+
+    def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/api/pickups",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+        pickup_id = request.serialize().get("pickupId")
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/api/pickups/{pickup_id}/cancel",
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def create_manifest(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/api/manifests",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def calculate_duties(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/api/trade-engine/duties-taxes",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def register_webhook(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/api/webhooks",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def deregister_webhook(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        access_token = self.authenticate(request).deserialize()
+        webhook_id = request.serialize().get("webhookId")
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/api/webhooks/{webhook_id}",
+            trace=self.trace_as("json"),
+            method="DELETE",
+            headers={
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+        # DELETE returns 204 No Content on success - handle empty response
+        return lib.Deserializable(
+            response,
+            lambda r: lib.to_dict(r) if r and r.strip() else {},
+        )

karrio/mappers/teleship/settings.py

@@ -0,0 +1,21 @@
+"""Karrio Teleship client settings."""
+
+import attr
+import karrio.providers.teleship.utils as provider_utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """Teleship connection settings."""
+
+    # Add carrier specific API connection properties here
+    client_id: str
+    client_secret: str
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "teleship"
+    account_country_code: str = None
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/teleship/__init__.py

@@ -0,0 +1,32 @@
+from karrio.core.metadata import PluginMetadata
+
+from karrio.mappers.teleship.mapper import Mapper
+from karrio.mappers.teleship.proxy import Proxy
+from karrio.mappers.teleship.settings import Settings
+from karrio.mappers.teleship.hooks import Hooks
+import karrio.providers.teleship.units as units
+import karrio.providers.teleship.utils as utils
+
+
+# This METADATA object is used by Karrio to discover and register this plugin
+# when loaded through Python entrypoints or local plugin directories.
+# The entrypoint is defined in pyproject.toml under [project.entry-points."karrio.plugins"]
+METADATA = PluginMetadata(
+    id="teleship",
+    label="Teleship",
+    description="Teleship is an international shipping platform providing end-to-end logistics solutions with real-time rates, automated customs compliance, and shipment tracking.",
+    # Integrations
+    Mapper=Mapper,
+    Proxy=Proxy,
+    Settings=Settings,
+    Hooks=Hooks,
+    # Data Units
+    is_hub=False,
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    connection_configs=units.ConnectionConfig,
+    system_config=units.SYSTEM_CONFIG,
+    # Extra info
+    website="https://www.teleship.com",
+    documentation="https://developers.teleship.com",
+)

karrio/providers/teleship/__init__.py

@@ -0,0 +1,41 @@
+"""Karrio Teleship provider imports."""
+from karrio.providers.teleship.utils import Settings
+from karrio.providers.teleship.rate import (
+    parse_rate_response,
+    rate_request,
+)
+from karrio.providers.teleship.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.teleship.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)
+from karrio.providers.teleship.pickup import (
+    pickup_request,
+    parse_pickup_response,
+    cancel_pickup_request,
+    parse_cancel_pickup_response,
+)
+from karrio.providers.teleship.manifest import (
+    manifest_request,
+    parse_manifest_response,
+)
+from karrio.providers.teleship.duties import (
+    duties_calculation_request,
+    parse_duties_calculation_response,
+)
+from karrio.providers.teleship.webhook import (
+    webhook_registration_request,
+    parse_webhook_registration_response,
+    webhook_deregistration_request,
+    parse_webhook_deregistration_response,
+)
+from karrio.providers.teleship.hooks import (
+    on_webhook_event,
+    on_oauth_authorize,
+    on_oauth_callback,
+)

karrio/providers/teleship/duties.py

@@ -0,0 +1,115 @@
+"""Karrio Teleship duties calculation implementation."""
+
+import typing
+import karrio.schemas.teleship.duties_taxes_request as teleship
+import karrio.schemas.teleship.duties_taxes_response as duties
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.teleship.error as error
+import karrio.providers.teleship.utils as provider_utils
+
+
+def parse_duties_calculation_response(
+    _response: lib.Deserializable[str],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.DutiesCalculationDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    details = lib.to_object(duties.DutiesTaxesResponseType, response)
+
+    duties_details = lib.identity(
+        models.DutiesCalculationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            total_charge=lib.to_money(details.price),
+            currency=details.currency,
+            charges=[
+                models.ChargeDetails(
+                    name=charge.name,
+                    amount=lib.to_money(charge.amount),
+                    currency=charge.currency,
+                )
+                for charge in (details.charges or [])
+            ],
+            meta=lib.to_dict(details),
+        )
+        if details and details.price
+        else None
+    )
+
+    return duties_details, messages
+
+
+def duties_calculation_request(
+    payload: models.DutiesCalculationRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    customs = lib.to_customs_info(payload.customs)
+    commodities = lib.to_commodities(customs.commodities or [])
+
+    request = teleship.DutiesTaxesRequestType(
+        shipTo=teleship.ShipType(
+            name=recipient.person_name,
+            email=recipient.email,
+            phone=recipient.phone_number,
+            company=recipient.company_name,
+            address=teleship.AddressType(
+                line1=recipient.address_line1,
+                line2=recipient.address_line2,
+                city=recipient.city,
+                state=recipient.state_code,
+                postcode=recipient.postal_code,
+                country=recipient.country_code,
+            ),
+        ),
+        shipFrom=teleship.ShipType(
+            name=shipper.person_name,
+            email=shipper.email,
+            phone=shipper.phone_number,
+            company=shipper.company_name,
+            address=teleship.AddressType(
+                line1=shipper.address_line1,
+                line2=shipper.address_line2,
+                city=shipper.city,
+                state=shipper.state_code,
+                postcode=shipper.postal_code,
+                country=shipper.country_code,
+            ),
+        ),
+        commodities=[
+            teleship.CommodityType(
+                quantity=commodity.quantity,
+                title=commodity.title or commodities.description,
+                description=lib.identity(
+                    commodity.description if commodity.title else None
+                ),
+                hsCode=commodity.hs_code,
+                sku=commodity.sku,
+                value=teleship.ConsigneeChargesType(
+                    amount=commodity.value_amount,
+                    currency=commodity.value_currency,
+                ),
+                unitWeight=teleship.UnitWeightType(
+                    unit=commodity.weight_unit or "kg",
+                    value=commodity.weight,
+                ),
+                countryOfOrigin=commodity.origin_country,
+                category=commodity.category,
+            )
+            for commodity in commodities
+        ],
+        customs=teleship.CustomsType(
+            contentType=customs.content_type or "CommercialGoods",
+            incoterms=lib.failsafe(lambda: customs.options.incoterms.state),
+            invoiceNumber=customs.invoice,
+            invoiceDate=customs.invoice_date,
+            EORI=lib.failsafe(lambda: customs.options.eori_number.state),
+            VAT=lib.failsafe(lambda: customs.options.vat.state),
+        ),
+        currency=payload.options.get("currency") if payload.options else None,
+        orderTrackingReference=payload.reference,
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/teleship/error.py

@@ -0,0 +1,44 @@
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.teleship.utils as provider_utils
+import karrio.schemas.teleship.error_response as teleship
+
+
+def parse_error_response(
+    response: typing.Union[dict, list],
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    """Parse Teleship error response"""
+
+    errors = lib.failsafe(lambda: response.get("messages")) or []
+
+    # Handle single error format
+    if isinstance(response, dict) and response.get("error"):
+        error_obj = response.get("error")
+        if isinstance(error_obj, dict):
+            errors = [error_obj]
+        elif isinstance(error_obj, list):
+            errors = error_obj
+
+    # Handle messages array format
+    if isinstance(errors, list) and any(errors):
+        return [
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code=str(error.get("code", "")),
+                message=error.get("message", ""),
+                details=lib.to_dict(
+                    {
+                        **kwargs,
+                        "timestamp": error.get("timestamp"),
+                        "details": error.get("details"),
+                    }
+                ),
+            )
+            for error in errors
+        ]
+
+    return []

karrio/providers/teleship/hooks/__init__.py

@@ -0,0 +1,5 @@
+from karrio.providers.teleship.hooks.event import on_webhook_event
+from karrio.providers.teleship.hooks.oauth import (
+    on_oauth_authorize,
+    on_oauth_callback,
+)