karrio-teleship 2025.5__py3-none-any.whl

karrio/providers/teleship/hooks/event.py

@@ -0,0 +1,163 @@
+"""Karrio Teleship webhook event processing implementation."""
+
+import hmac
+import typing
+import hashlib
+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
+import karrio.schemas.teleship.tracking_response as tracking_res
+
+
+def on_webhook_event(
+    payload: models.RequestPayload,
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.WebhookEventDetails, typing.List[models.Message]]:
+    """
+    webhook payloads follow a structure:
+    {
+      "eventName": "label.generated",
+      "objectType": "shipment",
+      "objectId": "6f384ad7-f8bf-40ce-8bf0-715248738f10",
+      "data": {
+        // Event-specific data (see examples below)
+      }
+    }
+    """
+
+    if not verify_webhook_signature(payload, settings):
+        return None, [
+            models.Message(
+                code="invalid_signature",
+                message=f"Invalid webhook signature for {settings.carrier_name} webhook",
+            )
+        ]
+
+    messages = error.parse_error_response(payload.body, settings)
+    body = lib.to_dict(payload.body) if payload.body else {}
+    data = body.get("data") or {}
+
+    # Extract tracking details from webhook event data
+    tracking = lib.identity(
+        _extract_webhook_tracking(data, settings)
+        if body.get("eventName") == "shipment.updated" and data.get("trackingNumber")
+        else None
+    )
+    details = models.WebhookEventDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=data.get("trackingNumber"),
+        shipment_identifier=body.get("objectId"),
+        tracking=tracking,
+        shipment=None,
+    )
+
+    return details, messages
+
+
+def _extract_webhook_tracking(
+    data: typing.Any,
+    settings: provider_utils.Settings,
+) -> models.TrackingDetails:
+    """Extract tracking details from webhook event data.
+
+    Webhook data structure differs from tracking API response - timestamps include
+    milliseconds and the data is nested under 'data' in the webhook payload.
+    """
+
+    tracking = lib.to_object(tracking_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,
+    )
+
+    # Teleship webhook timestamps include milliseconds: "2025-11-27T05:48:00.000Z"
+    timestamp_formats = ["%Y-%m-%dT%H:%M:%S.%fZ", "%Y-%m-%dT%H:%M:%SZ"]
+
+    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, try_formats=timestamp_formats),
+                time=lib.flocaltime(event.timestamp, try_formats=timestamp_formats),
+                description=event.description,
+                code=event.code,
+                location=event.location,
+            )
+            for event in (tracking.events or [])
+        ],
+        delivered=status == "delivered",
+        status=status,
+        estimated_delivery=lib.fdate(
+            tracking.estimatedDelivery, try_formats=timestamp_formats
+        ),
+        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 verify_webhook_signature(
+    payload: models.RequestPayload,
+    settings: provider_utils.Settings,
+) -> bool:
+    """Verify the webhook signature using HMAC-SHA256.
+
+    JavaScript equivalent:
+        const crypto = require('crypto');
+
+        function verifyWebhookSignature(payload, signature, secret) {
+          const expectedSignature = crypto
+            .createHmac('sha256', secret)
+            .update(JSON.stringify(payload))
+            .digest('hex');
+
+          return crypto.timingSafeEqual(
+            Buffer.from(signature),
+            Buffer.from(expectedSignature)
+          );
+        }
+    """
+
+    # Get the signature from headers (access dict directly - headers contain hyphens)
+    headers = payload.headers or {}
+    signature = headers.get("x-teleship-signature")
+    secret = settings.connection_config.webhook_secret.state
+
+    # If no signature provided, skip verification (or return False for strict mode)
+    if not signature or not secret:
+        return True
+
+    # Compute expected signature using HMAC-SHA256
+    # The payload body should be JSON serialized consistently
+    payload_bytes = lib.to_json(payload.body).encode("utf-8")
+    secret_bytes = secret.encode("utf-8")
+
+    expected_signature = hmac.new(
+        secret_bytes,
+        payload_bytes,
+        hashlib.sha256,
+    ).hexdigest()
+
+    # Use constant-time comparison to prevent timing attacks
+    return hmac.compare_digest(signature, expected_signature)

karrio/providers/teleship/hooks/oauth.py

@@ -0,0 +1,103 @@
+"""Karrio Teleship OAuth processing implementation."""
+
+import typing
+import urllib.parse
+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 on_oauth_authorize(
+    payload: models.OAuthAuthorizePayload,
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.OAuthAuthorizeRequest, typing.List[models.Message]]:
+    """Create OAuth authorize request for Teleship.
+
+    Generates the authorization URL and parameters needed to initiate
+    the OAuth flow with Teleship.
+    """
+    messages: typing.List[models.Message] = []
+
+    # Get OAuth credentials from system config
+    scope = payload.options.get("scope", "read_accounts write_shipments")
+
+    if not settings.oauth_client_id:
+        messages.append(
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code="OAUTH_CONFIG_ERROR",
+                message="TELESHIP_OAUTH_CLIENT_ID is not configured in system settings",
+            )
+        )
+
+    # Build authorization URL parameters
+    auth_params = dict(
+        redirectUri=payload.redirect_uri,
+        state=payload.state,
+        responseType="code",
+        clientId=settings.oauth_client_id,
+        scope=scope,
+    )
+
+    authorization_url = lib.identity(
+        f"{settings.server_url}/oauth/authorize?{urllib.parse.urlencode(auth_params)}"
+    )
+
+    return (
+        models.OAuthAuthorizeRequest(
+            carrier_name=settings.carrier_name,
+            authorization_url=authorization_url,
+            meta=dict(scope=scope),
+        ),
+        messages,
+    )
+
+
+def on_oauth_callback(
+    payload: models.RequestPayload,
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.Optional[typing.Dict], typing.List[models.Message]]:
+    """Process OAuth authorization callback.
+
+    Extracts the authorization code and user credentials from the callback.
+    Teleship returns account_client_id and account_client_secret in the callback
+    query parameters which are the user's credentials for API access.
+    """
+    query = payload.query or {}
+    messages = error.parse_error_response(payload.body, settings)
+
+    code = query.get("code")
+    account_client_id = query.get("account_client_id")
+    account_client_secret = query.get("account_client_secret")
+
+    if not code:
+        messages.append(
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code="OAUTH_CALLBACK_ERROR",
+                message="No authorization code received in callback",
+            )
+        )
+        return None, messages
+
+    if not account_client_id or not account_client_secret:
+        messages.append(
+            models.Message(
+                carrier_id=settings.carrier_id,
+                carrier_name=settings.carrier_name,
+                code="OAUTH_CALLBACK_ERROR",
+                message="Missing account credentials in callback",
+            )
+        )
+        return None, messages
+
+    # Return credentials that map to the Teleship connection settings
+    credentials = dict(
+        client_id=account_client_id,
+        client_secret=account_client_secret,
+    )
+
+    return credentials, messages

karrio/providers/teleship/manifest.py

@@ -0,0 +1,68 @@
+"""Karrio Teleship manifest creation implementation."""
+
+import typing
+import karrio.schemas.teleship.manifest_request as teleship
+import karrio.schemas.teleship.manifest_response as manifest
+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_manifest_response(
+    _response: lib.Deserializable[str],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    details = lib.to_object(manifest.ManifestResponseType, response)
+
+    manifest_details = lib.identity(
+        models.ManifestDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            id=details.id,
+            doc=None,
+            meta=dict(
+                status=details.status,
+                reference=details.reference,
+                createdAt=details.createdAt,
+            ),
+        )
+        if details and details.id
+        else None
+    )
+
+    return manifest_details, messages
+
+
+def manifest_request(
+    payload: models.ManifestRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    address = lib.to_address(payload.address)
+
+    request = teleship.ManifestRequestType(
+        shipmentIds=payload.shipment_identifiers,
+        reference=payload.reference,
+        address=lib.identity(
+            teleship.ManifestRequestAddressType(
+                name=address.person_name,
+                email=address.email,
+                phone=address.phone_number,
+                company=address.company_name,
+                address=teleship.AddressAddressType(
+                    line1=address.address_line1,
+                    line2=address.address_line2,
+                    city=address.city,
+                    state=address.state_code,
+                    postcode=address.postal_code,
+                    country=address.country_code,
+                ),
+            )
+            if address
+            else None
+        ),
+    )
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/teleship/pickup/__init__.py

@@ -0,0 +1,8 @@
+from karrio.providers.teleship.pickup.schedule import (
+    pickup_request,
+    parse_pickup_response,
+)
+from karrio.providers.teleship.pickup.cancel import (
+    cancel_pickup_request,
+    parse_cancel_pickup_response,
+)

karrio/providers/teleship/pickup/cancel.py

@@ -0,0 +1,43 @@
+"""Karrio Teleship pickup cancellation 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_cancel_pickup_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)
+
+    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="pickup_cancellation",
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def cancel_pickup_request(
+    payload: models.PickupCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    request = {"pickupId": payload.confirmation_number}
+
+    return lib.Serializable(request, lib.to_dict)

karrio/providers/teleship/pickup/schedule.py

@@ -0,0 +1,66 @@
+"""Karrio Teleship pickup scheduling implementation."""
+
+import typing
+import karrio.schemas.teleship.pickup_request as teleship
+import karrio.schemas.teleship.pickup_response as pickup
+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_pickup_response(
+    _response: lib.Deserializable[str],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.PickupDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    details = lib.to_object(pickup.PickupResponseType, response)
+
+    pickup_details = lib.identity(
+        models.PickupDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            confirmation_number=details.pickup.id,
+            pickup_date=lib.fdatetime(
+                details.pickup.startAt,
+                current_format="%Y-%m-%dT%H:%M:%S.%fZ",
+                output_format="%Y-%m-%d",
+            ),
+            meta=lib.to_dict(details.pickup),
+        )
+        if details and details.pickup and details.pickup.id
+        else None
+    )
+
+    return pickup_details, messages
+
+
+def pickup_request(
+    payload: models.PickupRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    address = lib.to_address(payload.address)
+
+    request = teleship.PickupRequestType(
+        startAt=payload.pickup_date,
+        endAt=payload.closing_time or payload.pickup_date,
+        shipmentIds=payload.shipment_identifiers,
+        address=teleship.PickupRequestAddressType(
+            name=address.person_name,
+            email=address.email,
+            phone=address.phone_number,
+            company=address.company_name,
+            address=teleship.AddressAddressType(
+                line1=address.address_line1,
+                line2=address.address_line2,
+                city=address.city,
+                state=address.state_code,
+                postcode=address.postal_code,
+                country=address.country_code,
+            ),
+        ),
+        reference=payload.instruction,
+    )
+
+    return lib.Serializable(request, lib.to_dict)