karrio-teleship 2025.5__py3-none-any.whl

karrio/providers/teleship/tracking.py

@@ -0,0 +1,100 @@
+"""Karrio Teleship tracking API implementation."""
+
+import karrio.schemas.teleship.tracking_response as teleship_res
+
+import typing
+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
+import karrio.providers.teleship.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()
+
+    # Aggregate error messages using functional sum pattern
+    messages: typing.List[models.Message] = sum(
+        [
+            error.parse_error_response(
+                response, settings, **dict(tracking_number=tracking_number)
+            )
+            for tracking_number, response in responses
+        ],
+        start=[],
+    )
+
+    # Extract tracking details using list comprehension (skip error responses)
+    tracking_details = [
+        _extract_details(details, settings)
+        for tracking_number, details in responses
+        if details and not details.get("messages")
+    ]
+
+    return tracking_details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.TrackingDetails:
+    """Extract tracking details from carrier response data"""
+
+    tracking = lib.to_object(teleship_res.TrackingResponseType, data)
+    last_event = next(iter(tracking.events or []), None)
+    status = next(
+        (
+            status.name
+            for status in list(provider_units.TrackingStatus)
+            if last_event and last_event.code in status.value
+        ),
+        provider_units.TrackingStatus.in_transit.name,
+    )
+
+    return models.TrackingDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=tracking.trackingNumber,
+        events=[
+            models.TrackingEvent(
+                date=lib.fdate(event.timestamp, "%Y-%m-%dT%H:%M:%SZ"),
+                time=lib.flocaltime(event.timestamp, "%Y-%m-%dT%H:%M:%SZ"),
+                description=event.description,
+                code=event.code,
+                location=event.location,
+            )
+            for event in tracking.events
+        ],
+        delivered=status == "delivered",
+        status=status,
+        estimated_delivery=lib.fdate(
+            tracking.estimatedDelivery,
+            try_formats=["%Y-%m-%dT%H:%M:%S.%fZ", "%Y-%m-%dT%H:%M:%SZ"],
+        ),
+        info=models.TrackingInfo(
+            shipment_service=tracking.firstMile.carrier,
+            carrier_tracking_link=settings.tracking_url.format(tracking.trackingNumber),
+            customer_name=tracking.shipTo.address.city,
+            shipment_destination_country=tracking.shipTo.address.country,
+            shipment_origin_country=tracking.shipFrom.address.country,
+        ),
+        meta=dict(
+            shipment_id=tracking.shipmentId,
+            customer_reference=tracking.customerReference,
+            ship_date=tracking.shipDate,
+            last_mile_carrier=tracking.lastMile.carrier,
+            last_mile_tracking=tracking.lastMile.trackingNumber,
+        ),
+    )
+
+
+def tracking_request(
+    payload: models.TrackingRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a tracking request for the carrier API"""
+    # Return tracking numbers as serializable for proxy to handle
+    return lib.Serializable(payload.tracking_numbers)

karrio/providers/teleship/units.py

@@ -0,0 +1,154 @@
+import karrio.lib as lib
+import karrio.core.units as units
+
+
+# System config schema for runtime settings (e.g., OAuth credentials)
+# Format: Dict[str, Tuple[default_value, description, type]]
+# Note: The actual env values are read by the server (constance.py) using decouple
+SYSTEM_CONFIG = {
+    "TELESHIP_OAUTH_CLIENT_ID": (
+        "",
+        "The Teleship OAuth client ID",
+        str,
+    ),
+    "TELESHIP_OAUTH_CLIENT_SECRET": (
+        "",
+        "The Teleship OAuth client secret",
+        str,
+    ),
+    "TELESHIP_SANDBOX_OAUTH_CLIENT_ID": (
+        "",
+        "The Teleship sandbox OAuth client ID",
+        str,
+    ),
+    "TELESHIP_SANDBOX_OAUTH_CLIENT_SECRET": (
+        "",
+        "The Teleship sandbox OAuth client secret",
+        str,
+    ),
+}
+
+
+class LabelType(lib.StrEnum):
+    """Carrier specific label type"""
+
+    PDF = "PDF"
+    ZPL = "ZPL"
+    PNG = "PNG"
+
+
+class ConnectionConfig(lib.Enum):
+    """Teleship connection configuration."""
+
+    shipping_options = lib.OptionEnum("shipping_options", list)
+    shipping_services = lib.OptionEnum("shipping_services", list)
+    label_format = lib.OptionEnum(
+        "label_format",
+        lib.units.create_enum("LabelType", [_.name for _ in list(LabelType)]),
+        "PDF",
+    )
+
+
+class PackagingType(lib.StrEnum):
+    """Carrier specific packaging type"""
+
+    envelope = "envelope"
+    tube = "tube"
+    parcel = "parcel"
+
+    """ Unified Packaging type mapping """
+    pak = envelope
+    small_box = parcel
+    medium_box = parcel
+    your_packaging = parcel
+
+
+class ShippingService(lib.StrEnum):
+    """Carrier specific services"""
+
+    teleship_expedited_pickup = "TELESHIP-EXPEDITED-PICKUP"
+    teleship_expedited_dropoff = "TELESHIP-EXPEDITED-DROPOFF"
+    teleship_standard_dropoff = "TELESHIP-STANDARD-DROPOFF"
+    teleship_standard_pickup = "TELESHIP-STANDARD-PICKUP"
+    teleship_postal_dropoff = "TELESHIP-POSTAL-DROPOFF"
+    teleship_postal_pickup = "TELESHIP-POSTAL-PICKUP"
+
+
+class ShippingOption(lib.Enum):
+    """Carrier specific options"""
+
+    teleship_signature_required = lib.OptionEnum("signatureRequired", bool)
+    teleship_delivery_warranty = lib.OptionEnum("deliveryWarranty", bool)
+    teleship_delivery_PUDO = lib.OptionEnum("deliveryPUDO", bool)
+    teleship_low_carbon = lib.OptionEnum("lowCarbon", bool)
+    teleship_duty_tax_calculation = lib.OptionEnum("dutyTaxCalculation", bool)
+    teleship_customer_reference = lib.OptionEnum("customerReference")
+    teleship_order_tracking_reference = lib.OptionEnum("orderTrackingReference")
+    teleship_commercial_invoice_reference = lib.OptionEnum("commercialInvoiceReference")
+
+
+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 CustomsContentType(lib.StrEnum):
+    """Teleship customs content types"""
+
+    # Teleship-specific values (PascalCase)
+    documents = "Documents"
+    gift = "Gift"
+    sample = "Sample"
+    other = "Other"
+    commercial_goods = "CommercialGoods"
+    return_of_goods = "ReturnOfGoods"
+
+    """ Unified content type mapping """
+    merchandise = commercial_goods
+
+
+class CustomsOption(lib.Enum):
+    """Teleship customs identifiers"""
+
+    EORI = lib.OptionEnum("EORI")
+    IOSS = lib.OptionEnum("IOSS")
+    VAT = lib.OptionEnum("VAT")
+    EIN = lib.OptionEnum("EIN")
+    VOECNUMBER = lib.OptionEnum("VOECNUMBER")
+
+    """ Unified Customs Identifier type mapping """
+
+    ioss = IOSS
+    eori_number = EORI
+    vat = VAT
+    ein = EIN
+    voec_number = VOECNUMBER
+    vat_registration_number = VAT
+
+
+class TrackingStatus(lib.Enum):
+    """Teleship tracking statuses"""
+
+    delivered = ["delivered"]
+    in_transit = [
+        "in_transit",
+        "collected",
+        "in_hub",
+        "out_for_delivery",
+        "customs_cleared",
+    ]
+    out_for_delivery = ["out_for_delivery"]
+    delivery_failed = ["delivery_failed", "returned", "cancelled"]
+    pending = ["pending", "created", "label_created"]

karrio/providers/teleship/utils.py

@@ -0,0 +1,57 @@
+import os
+import logging
+import karrio.lib as lib
+import karrio.core as core
+
+logger = logging.getLogger(__name__)
+
+
+class Settings(core.Settings):
+    """Teleship connection settings."""
+
+    # Add carrier specific api connection properties here
+    client_id: str
+    client_secret: str
+
+    @property
+    def carrier_name(self):
+        return "teleship"
+
+    @property
+    def server_url(self):
+        return os.getenv("TELESHIP_SERVER_URL") or (
+            "https://sandbox.teleship.com"
+            if self.test_mode
+            else "https://api.teleship.com"
+        )
+
+    @property
+    def tracking_url(self):
+        return "https://track.teleship.com/{}"
+
+    @property
+    def connection_config(self) -> lib.units.Options:
+        from karrio.providers.teleship.units import ConnectionConfig
+
+        return lib.to_connection_config(
+            self.config or {},
+            option_type=ConnectionConfig,
+        )
+
+    @property
+    def oauth_client_id(self):
+        return (
+            self.connection_system_config.get("TELESHIP_OAUTH_CLIENT_ID")
+            if self.test_mode
+            else self.connection_system_config.get("TELESHIP_SANDBOX_OAUTH_CLIENT_ID")
+        )
+
+    @property
+    def oauth_client_secret(self):
+        return (
+            self.connection_system_config.get("TELESHIP_OAUTH_CLIENT_SECRET")
+            if self.test_mode
+            else self.connection_system_config.get(
+                "TELESHIP_SANDBOX_OAUTH_CLIENT_SECRET"
+            )
+        )

karrio/providers/teleship/webhook/__init__.py

@@ -0,0 +1,8 @@
+from karrio.providers.teleship.webhook.register import (
+    webhook_registration_request,
+    parse_webhook_registration_response,
+)
+from karrio.providers.teleship.webhook.deregister import (
+    webhook_deregistration_request,
+    parse_webhook_deregistration_response,
+)

karrio/providers/teleship/webhook/deregister.py

@@ -0,0 +1,47 @@
+"""Karrio Teleship webhook deregistration implementation."""
+
+import typing
+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_webhook_deregistration_response(
+    _response: lib.Deserializable[str],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # Teleship returns 204 No Content on successful deletion
+    # or success response with status
+    success = not any(messages) and (
+        isinstance(response, dict) and response.get("success") is not False
+        or response == ""
+        or response is None
+    )
+
+    confirmation = (
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            success=success,
+            operation="webhook_deregistration",
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def webhook_deregistration_request(
+    payload: models.WebhookDeregistrationRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a Teleship webhook deregistration request"""
+
+    request = {"webhookId": payload.webhook_id}
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/teleship/webhook/register.py

@@ -0,0 +1,48 @@
+"""Karrio Teleship webhook registration implementation."""
+
+import typing
+import karrio.schemas.teleship.webhook_request as teleship
+import karrio.schemas.teleship.webhook_response as webhook
+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_webhook_registration_response(
+    _response: lib.Deserializable[str],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.WebhookRegistrationDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    details = lib.to_object(webhook.WebhookResponseType, response)
+
+    webhook_details = (
+        models.WebhookRegistrationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            webhook_identifier=details.id,
+            secret=details.secret,
+            meta=lib.to_dict(details),
+        )
+        if details and details.id
+        else None
+    )
+
+    return webhook_details, messages
+
+
+def webhook_registration_request(
+    payload: models.WebhookRegistrationRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a Teleship webhook registration request"""
+
+    request = teleship.WebhookRequestType(
+        url=payload.url,
+        description=payload.description,
+        enabled=True,
+        enabledEvents=(payload.enabled_events if any(payload.enabled_events) else ["*"]),
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/schemas/teleship/duties_taxes_request.py

@@ -0,0 +1,82 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class UnitWeightType:
+    unit: typing.Optional[str] = None
+    value: typing.Optional[float] = None
+
+
+@attr.s(auto_attribs=True)
+class ConsigneeChargesType:
+    amount: typing.Optional[float] = None
+    currency: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class CommodityType:
+    title: typing.Optional[str] = None
+    description: typing.Optional[str] = None
+    hsCode: typing.Optional[str] = None
+    sku: typing.Optional[str] = None
+    quantity: typing.Optional[int] = None
+    value: typing.Optional[ConsigneeChargesType] = jstruct.JStruct[ConsigneeChargesType]
+    unitWeight: typing.Optional[UnitWeightType] = jstruct.JStruct[UnitWeightType]
+    countryOfOrigin: typing.Optional[str] = None
+    category: typing.Optional[str] = None
+    imageUrl: typing.Optional[str] = None
+    productUrl: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class CustomsType:
+    contentType: typing.Optional[str] = None
+    incoterms: typing.Optional[str] = None
+    invoiceNumber: typing.Optional[str] = None
+    invoiceDate: typing.Optional[str] = None
+    EORI: typing.Optional[str] = None
+    VAT: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class MessageType:
+    code: typing.Optional[int] = None
+    level: typing.Optional[str] = None
+    timestamp: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+    details: typing.Optional[typing.List[str]] = None
+
+
+@attr.s(auto_attribs=True)
+class AddressType:
+    line1: typing.Optional[str] = None
+    line2: typing.Optional[str] = None
+    city: typing.Optional[str] = None
+    state: typing.Optional[str] = None
+    postcode: typing.Optional[str] = None
+    country: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ShipType:
+    name: typing.Optional[str] = None
+    email: typing.Optional[str] = None
+    phone: typing.Optional[str] = None
+    company: typing.Optional[str] = None
+    address: typing.Optional[AddressType] = jstruct.JStruct[AddressType]
+
+
+@attr.s(auto_attribs=True)
+class DutiesTaxesRequestType:
+    messages: typing.Optional[typing.List[MessageType]] = jstruct.JList[MessageType]
+    shipTo: typing.Optional[ShipType] = jstruct.JStruct[ShipType]
+    shipFrom: typing.Optional[ShipType] = jstruct.JStruct[ShipType]
+    commodities: typing.Optional[typing.List[CommodityType]] = jstruct.JList[CommodityType]
+    customs: typing.Optional[CustomsType] = jstruct.JStruct[CustomsType]
+    currency: typing.Optional[str] = None
+    orderTrackingReference: typing.Optional[int] = None
+    freightCost: typing.Optional[ConsigneeChargesType] = jstruct.JStruct[ConsigneeChargesType]
+    consigneeCharges: typing.Optional[ConsigneeChargesType] = jstruct.JStruct[ConsigneeChargesType]
+    insuranceValue: typing.Optional[ConsigneeChargesType] = jstruct.JStruct[ConsigneeChargesType]

karrio/schemas/teleship/duties_taxes_response.py

@@ -0,0 +1,28 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class ChargeType:
+    name: typing.Optional[str] = None
+    amount: typing.Optional[float] = None
+    currency: typing.Optional[str] = None
+    rate: typing.Optional[float] = None
+
+
+@attr.s(auto_attribs=True)
+class CommodityType:
+    itemNumber: typing.Optional[int] = None
+    title: typing.Optional[str] = None
+    charges: typing.Optional[typing.List[ChargeType]] = jstruct.JList[ChargeType]
+    restrictions: typing.Optional[typing.List[typing.Any]] = None
+
+
+@attr.s(auto_attribs=True)
+class DutiesTaxesResponseType:
+    messages: typing.Optional[typing.List[typing.Any]] = None
+    price: typing.Optional[float] = None
+    currency: typing.Optional[str] = None
+    charges: typing.Optional[typing.List[ChargeType]] = jstruct.JList[ChargeType]
+    commodities: typing.Optional[typing.List[CommodityType]] = jstruct.JList[CommodityType]

karrio/schemas/teleship/error_response.py

@@ -0,0 +1,17 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class MessageType:
+    code: typing.Optional[int] = None
+    level: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+    timestamp: typing.Optional[str] = None
+    details: typing.Optional[typing.List[str]] = None
+
+
+@attr.s(auto_attribs=True)
+class ErrorResponseType:
+    messages: typing.Optional[typing.List[MessageType]] = jstruct.JList[MessageType]

karrio/schemas/teleship/manifest_request.py

@@ -0,0 +1,39 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AddressAddressType:
+    line1: typing.Optional[str] = None
+    line2: typing.Optional[str] = None
+    city: typing.Optional[str] = None
+    state: typing.Optional[str] = None
+    postcode: typing.Optional[int] = None
+    country: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ManifestRequestAddressType:
+    name: typing.Optional[str] = None
+    email: typing.Optional[str] = None
+    phone: typing.Optional[str] = None
+    company: typing.Optional[str] = None
+    address: typing.Optional[AddressAddressType] = jstruct.JStruct[AddressAddressType]
+
+
+@attr.s(auto_attribs=True)
+class MessageType:
+    code: typing.Optional[int] = None
+    level: typing.Optional[str] = None
+    timestamp: typing.Optional[str] = None
+    message: typing.Optional[str] = None
+    details: typing.Optional[typing.List[str]] = None
+
+
+@attr.s(auto_attribs=True)
+class ManifestRequestType:
+    messages: typing.Optional[typing.List[MessageType]] = jstruct.JList[MessageType]
+    shipmentIds: typing.Optional[typing.List[str]] = None
+    reference: typing.Optional[str] = None
+    address: typing.Optional[ManifestRequestAddressType] = jstruct.JStruct[ManifestRequestAddressType]

karrio/schemas/teleship/manifest_response.py

@@ -0,0 +1,31 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AddressAddressType:
+    line1: typing.Optional[str] = None
+    line2: typing.Optional[str] = None
+    city: typing.Optional[str] = None
+    state: typing.Optional[str] = None
+    postcode: typing.Optional[int] = None
+    country: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class ManifestResponseAddressType:
+    name: typing.Optional[str] = None
+    email: typing.Optional[str] = None
+    phone: typing.Optional[str] = None
+    company: typing.Optional[str] = None
+    address: typing.Optional[AddressAddressType] = jstruct.JStruct[AddressAddressType]
+
+
+@attr.s(auto_attribs=True)
+class ManifestResponseType:
+    id: typing.Optional[str] = None
+    status: typing.Optional[str] = None
+    reference: typing.Optional[str] = None
+    createdAt: typing.Optional[str] = None
+    address: typing.Optional[ManifestResponseAddressType] = jstruct.JStruct[ManifestResponseAddressType]

karrio/schemas/teleship/pickup_request.py

@@ -0,0 +1,31 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class AddressAddressType:
+    line1: typing.Optional[str] = None
+    line2: typing.Optional[str] = None
+    city: typing.Optional[str] = None
+    state: typing.Optional[str] = None
+    postcode: typing.Optional[str] = None
+    country: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupRequestAddressType:
+    name: typing.Optional[str] = None
+    email: typing.Optional[str] = None
+    phone: typing.Optional[str] = None
+    company: typing.Optional[str] = None
+    address: typing.Optional[AddressAddressType] = jstruct.JStruct[AddressAddressType]
+
+
+@attr.s(auto_attribs=True)
+class PickupRequestType:
+    startAt: typing.Optional[str] = None
+    endAt: typing.Optional[str] = None
+    shipmentIds: typing.Optional[typing.List[str]] = None
+    address: typing.Optional[PickupRequestAddressType] = jstruct.JStruct[PickupRequestAddressType]
+    reference: typing.Optional[str] = None