karrio-server-core 2025.5__py3-none-any.whl

karrio/server/core/datatypes.py

@@ -0,0 +1,394 @@
+import attr
+import typing
+import jstruct
+import karrio.core.units as units
+from karrio.core.models import (
+    DocumentDetails,
+    Documents,
+    Images,
+    Parcel,
+    Message,
+    Address as BaseAddress,
+    TrackingRequest as BaseTrackingRequest,
+    ShipmentDetails,
+    Payment,
+    Customs,
+    RateRequest as BaseRateRequest,
+    ShipmentRequest as BaseShipmentRequest,
+    ShipmentCancelRequest,
+    ChargeDetails,
+    PickupRequest as BasePickupRequest,
+    PickupDetails,
+    PickupUpdateRequest as BasePickupUpdateRequest,
+    PickupCancelRequest as BasePickupCancelRequest,
+    ConfirmationDetails as Confirmation,
+    TrackingEvent,
+    TrackingInfo,
+    ManifestDocument,
+    TrackingDetails,
+    DocumentFile,
+    DocumentUploadRequest,
+    ManifestRequest,
+    ManifestDetails,
+    RequestPayload,
+    OAuthAuthorizePayload,
+    OAuthAuthorizeRequest,
+    WebhookEventDetails,
+    WebhookRegistrationDetails,
+    WebhookDeregistrationRequest,
+    WebhookRegistrationRequest,
+    DutiesCalculationRequest,
+    DutiesCalculationDetails,
+    InsuranceRequest,
+    InsuranceDetails,
+)
+
+
+COUNTRIES = [(c.name, c.name) for c in units.Country]
+CURRENCIES = [(c.name, c.name) for c in units.Currency]
+WEIGHT_UNITS = [(c.name, c.name) for c in units.WeightUnit]
+DIMENSION_UNITS = [(c.name, c.name) for c in units.DimensionUnit]
+CAPABILITIES_CHOICES = [(c, c) for c in units.CarrierCapabilities.get_capabilities()]
+LABEL_TYPES = [(c.name, c.name) for c in list(units.LabelType)]
+
+
+class CarrierSettings:
+    def __init__(
+        self,
+        carrier_name: str,
+        carrier_id: str,
+        test_mode: bool = None,
+        active: bool = None,
+        id: str = None,
+        display_name: str = None,
+        **kwargs
+    ):
+        self.carrier_name = carrier_name
+        self.display_name = display_name
+        self.carrier_id = carrier_id
+        self.active = active
+        self.test_mode = test_mode
+        self.id = id
+
+        for name, value in kwargs.items():
+            if name not in ["carrier_ptr", "created_by", "active_users", "active_orgs"]:
+                self.__setattr__(name, value)
+
+    # TODO: rename this to avoid confusion
+    def to_dict(self):
+        return {
+            name: value
+            for name, value in self.__dict__.items()
+            if name
+            not in [
+                "carrier_name",
+                "created_by",
+                "active",
+                "capabilities",
+                "active_users",
+                "active_orgs",
+                *([] if self.carrier_name == "generic" else ["display_name"]),
+            ]
+        }
+
+    @classmethod
+    def create(cls, data: dict):
+        return cls(**data)
+
+
+@attr.s(auto_attribs=True)
+class AddressValidation:
+    success: bool
+    meta: dict = {}
+
+
+@attr.s(auto_attribs=True)
+class Address(BaseAddress):
+    id: str = None
+    postal_code: str = None
+    city: str = None
+    person_name: str = None
+    company_name: str = None
+    country_code: str = None
+    email: str = None
+    phone_number: str = None
+
+    state_code: str = None
+    residential: bool = False
+
+    address_line1: str = ""
+    address_line2: str = None
+    street_number: str = None
+    suite: str = None
+
+    federal_tax_id: str = None
+    state_tax_id: str = None
+
+    validate_location: bool = None
+    validation: jstruct.JStruct[AddressValidation] = None
+
+
+@attr.s(auto_attribs=True)
+class PickupRequest(BasePickupRequest):
+    pickup_date: str
+    ready_time: str
+    closing_time: str
+    address: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+
+    parcels: typing.List[Parcel] = jstruct.JList[Parcel]
+    shipment_identifiers: typing.List[str] = []
+    package_location: str = None
+    metadata: typing.Dict = {}
+    options: typing.Dict = {}
+    instruction: str = None
+
+
+@attr.s(auto_attribs=True)
+class PickupUpdateRequest(BasePickupUpdateRequest):
+    confirmation_number: str
+    pickup_date: str
+    ready_time: str
+    closing_time: str
+    address: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+
+    parcels: typing.List[Parcel] = jstruct.JList[Parcel]
+    shipment_identifiers: typing.List[str] = []
+    package_location: str = None
+    options: typing.Dict = {}
+    instruction: str = None
+
+
+@attr.s(auto_attribs=True)
+class PickupCancelRequest(BasePickupCancelRequest):
+    confirmation_number: str
+
+    address: Address = jstruct.JStruct[Address]
+    pickup_date: str = None
+    reason: str = None
+    options: typing.Dict = {}
+
+
+@attr.s(auto_attribs=True)
+class Rate:
+    carrier_name: str
+    carrier_id: str
+
+    currency: str = None
+    transit_days: int = None
+    service: str = None
+    total_charge: float = 0.0
+    extra_charges: typing.List[ChargeDetails] = []
+    estimated_delivery: str = None
+    id: str = None
+    meta: dict = None
+    test_mode: bool = None
+    object_type: str = "rate"
+
+
+@attr.s(auto_attribs=True)
+class RateRequest(BaseRateRequest):
+    shipper: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+    recipient: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+    parcels: typing.List[Parcel] = jstruct.JList[Parcel, jstruct.REQUIRED]
+
+    payment: Payment = jstruct.JStruct[Payment]
+    customs: Customs = jstruct.JStruct[Customs]
+    return_address: Address = jstruct.JStruct[Address]
+    billing_address: Address = jstruct.JStruct[Address]
+
+    services: typing.List[str] = []
+    options: typing.Dict = {}
+    reference: str = ""
+
+    carrier_ids: typing.List[str] = []
+
+
+@attr.s(auto_attribs=True)
+class ShipmentRequest(BaseShipmentRequest):
+    service: str
+    selected_rate_id: str  # type: ignore
+
+    shipper: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+    recipient: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+    parcels: typing.List[Parcel] = jstruct.JList[Parcel, jstruct.REQUIRED]
+    rates: typing.List[Rate] = jstruct.JList[Rate, jstruct.REQUIRED]
+
+    payment: Payment = jstruct.JStruct[Payment]
+    customs: Customs = jstruct.JStruct[Customs]
+    return_address: Address = jstruct.JStruct[Address]
+    billing_address: Address = jstruct.JStruct[Address]
+
+    options: typing.Dict = {}
+    reference: str = ""
+    label_type: str = None
+    id: str = None
+
+    metadata: typing.Dict = {}
+
+
+@attr.s(auto_attribs=True)
+class Shipment:
+    carrier_id: str
+    carrier_name: str
+    tracking_number: str
+    shipment_identifier: str
+    service: str
+    selected_rate_id: str
+
+    shipper: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+    recipient: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+    parcels: typing.List[Parcel] = jstruct.JList[Parcel, jstruct.REQUIRED]
+    rates: typing.List[Rate] = jstruct.JList[Rate, jstruct.REQUIRED]
+    selected_rate: Rate = jstruct.JStruct[Rate, jstruct.REQUIRED]
+    docs: Documents = jstruct.JStruct[Documents, jstruct.REQUIRED]
+
+    payment: Payment = jstruct.JStruct[Payment]
+    customs: Customs = jstruct.JStruct[Customs]
+    billing_address: Address = jstruct.JStruct[Address]
+
+    options: typing.Dict = {}
+    reference: str = ""
+    label_type: str = None
+    tracking_url: str = None
+    tracker_id: str = None
+    status: str = ""
+    metadata: typing.Dict = {}
+    meta: dict = {}
+    id: str = None
+
+    messages: typing.List[Message] = jstruct.JList[Message]
+    created_at: str = None
+    test_mode: bool = None
+
+
+@attr.s(auto_attribs=True)
+class Pickup:
+    carrier_id: str
+    carrier_name: str
+
+    pickup_date: str
+    ready_time: str
+    closing_time: str
+    confirmation_number: str
+    address: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+    parcels: typing.List[Parcel] = jstruct.JList[Parcel, jstruct.REQUIRED]
+
+    pickup_charge: ChargeDetails = jstruct.JStruct[ChargeDetails]
+    instruction: str = None
+    package_location: str = None
+    metadata: typing.Dict = {}
+    options: typing.Dict = {}
+    meta: dict = {}
+    id: str = None
+
+    messages: typing.List[Message] = jstruct.JList[Message]
+    test_mode: bool = None
+
+
+@attr.s(auto_attribs=True)
+class TrackingRequest(BaseTrackingRequest):
+    tracking_numbers: typing.List[str]
+    account_numer: str = None
+    reference: str = None
+    options: typing.Dict = {}
+    info: TrackingInfo = jstruct.JStruct[TrackingInfo]
+
+
+@attr.s(auto_attribs=True)
+class Tracking:
+    carrier_name: str
+    carrier_id: str
+    tracking_number: str
+    events: typing.List[TrackingEvent] = jstruct.JList[TrackingEvent]
+
+    status: str = "unknown"
+    info: TrackingInfo = jstruct.JStruct[TrackingInfo]
+    images: Images = jstruct.JStruct[Images]
+    estimated_delivery: str = None
+    delivered: bool = None
+    test_mode: bool = None
+    options: typing.Dict = {}
+    meta: dict = None
+    id: str = None
+
+
+@attr.s(auto_attribs=True)
+class DocumentUploadResponse:
+    carrier_name: str
+    carrier_id: str
+    documents: typing.List[DocumentDetails] = jstruct.JList[DocumentDetails]
+    reference: str = ""
+
+    test_mode: bool = None
+    options: typing.Dict = {}
+    meta: dict = None
+    id: str = None
+    messages: typing.List[Message] = jstruct.JList[Message]
+
+
+@attr.s(auto_attribs=True)
+class Manifest:
+    carrier_id: str
+    carrier_name: str
+
+    shipment_identifiers: typing.List[str]
+    address: Address = jstruct.JStruct[Address, jstruct.REQUIRED]
+    doc: ManifestDocument = jstruct.JStruct[ManifestDocument]
+
+    reference: str = None
+    metadata: typing.Dict = {}
+    options: typing.Dict = {}
+    meta: dict = {}
+    id: str = None
+
+    messages: typing.List[Message] = jstruct.JList[Message]
+    test_mode: bool = None
+
+
+@attr.s(auto_attribs=True)
+class ConfirmationResponse:
+    messages: typing.List[Message] = jstruct.JList[Message]
+    confirmation: Confirmation = jstruct.JStruct[Confirmation]
+
+
+@attr.s(auto_attribs=True)
+class PickupResponse:
+    messages: typing.List[Message] = jstruct.JList[Message]
+    pickup: Pickup = jstruct.JStruct[Pickup]
+
+
+@attr.s(auto_attribs=True)
+class RateResponse:
+    messages: typing.List[Message] = jstruct.JList[Message]
+    rates: typing.List[Rate] = jstruct.JList[Rate]
+
+
+@attr.s(auto_attribs=True)
+class TrackingResponse:
+    messages: typing.List[Message] = jstruct.JList[Message]
+    tracking: Tracking = jstruct.JStruct[Tracking]
+
+
+@attr.s(auto_attribs=True)
+class ManifestResponse:
+    messages: typing.List[Message] = jstruct.JList[Message]
+    manifest: Manifest = jstruct.JStruct[Manifest]
+
+
+@attr.s(auto_attribs=True)
+class DutiesResponse:
+    messages: typing.List[Message] = jstruct.JList[Message]
+    duties: DutiesCalculationDetails = jstruct.JStruct[DutiesCalculationDetails]
+
+
+@attr.s(auto_attribs=True)
+class InsuranceResponse:
+    messages: typing.List[Message] = jstruct.JList[Message]
+    insurance: InsuranceDetails = jstruct.JStruct[InsuranceDetails]
+
+
+@attr.s(auto_attribs=True)
+class Error:
+    code: str = None
+    message: str = None
+    details: typing.Dict = None

karrio/server/core/dataunits.py

@@ -0,0 +1,187 @@
+from constance import config
+from django.urls import reverse
+from rest_framework.request import Request
+
+import karrio.lib as lib
+import karrio.references as ref
+import karrio.core.units as units
+import karrio.server.conf as conf
+import karrio.server.core.utils as utils
+
+
+PACKAGE_MAPPERS = ref.collect_providers_data()
+REFERENCE_MODELS = {
+    **ref.collect_references(),
+    "customs_content_type": {c.name: c.value for c in list(units.CustomsContentType)},
+    "incoterms": {c.name: c.value for c in list(units.Incoterm)},
+}
+REFERENCE_EXCLUSIONS = [
+    "currencies",
+    "incoterms",
+    "weight_units",
+    "dimension_units",
+    "payment_types",
+    "option_names",
+    "customs_content_type",
+    "options",
+]
+CARRIER_NAMES = list(sorted(set([*REFERENCE_MODELS["carriers"].keys(), "generic"])))
+CARRIER_HUBS = list(sorted(REFERENCE_MODELS["carrier_hubs"].keys()))
+NON_HUBS_CARRIERS = [
+    carrier_name for carrier_name in CARRIER_NAMES if carrier_name not in CARRIER_HUBS
+]
+
+
+def contextual_metadata(request: Request):
+    # Detect HTTPS from headers (for proxied environments like Caddy/ALB)
+    is_https = False
+    if hasattr(request, 'META'):
+        # Check X-Forwarded-Proto header (set by load balancers/proxies)
+        forwarded_proto = request.META.get('HTTP_X_FORWARDED_PROTO', '').lower()
+        # Check if request is secure (Django's built-in HTTPS detection)
+        is_secure = getattr(request, 'is_secure', lambda: False)()
+        is_https = forwarded_proto == 'https' or is_secure
+
+    if hasattr(request, "build_absolute_uri"):
+        _host: str = request.build_absolute_uri(
+            reverse("karrio.server.core:metadata", kwargs={})
+        )
+        # Override protocol if we detected HTTPS but build_absolute_uri returned HTTP
+        if is_https and _host.startswith('http://'):
+            _host = _host.replace('http://', 'https://', 1)
+    else:
+        _host = "/"
+
+    host = _host[:-1] if _host[-1] == "/" else _host
+    name = lib.identity(
+        getattr(conf.settings.tenant, "name", conf.settings.APP_NAME)
+        if conf.settings.MULTI_TENANTS
+        else getattr(config, "APP_NAME", None) or conf.settings.APP_NAME
+    )
+    website = lib.identity(
+        getattr(conf.settings.tenant, "website", conf.settings.APP_WEBSITE)
+        if conf.settings.MULTI_TENANTS
+        else getattr(config, "APP_WEBSITE", None) or conf.settings.APP_WEBSITE
+    )
+
+    # Batch fetch all feature flags
+    flag_names = [flag for flag, _ in conf.settings.FEATURE_FLAGS]
+
+    if conf.settings.MULTI_TENANTS:
+        # In multi-tenancy mode, feature flags come from tenant.feature_flags (JSON field)
+        # No N+1 issue since it's a single field access on an already-loaded tenant object
+        tenant = conf.settings.tenant
+        tenant_flags = getattr(tenant, "feature_flags", {}) if tenant else {}
+        feature_flags = {
+            flag: tenant_flags.get(flag, getattr(conf.settings, flag, None))
+            for flag in flag_names
+        }
+    else:
+        # In single-tenant mode, batch fetch from Constance to avoid N+1 queries
+        constance_values = utils.batch_get_constance_values(flag_names)
+        feature_flags = {
+            flag: (
+                constance_values.get(flag)
+                if flag in constance_values
+                else getattr(conf.settings, flag, None)
+            )
+            for flag in flag_names
+        }
+
+    return {
+        "VERSION": conf.settings.VERSION,
+        "APP_NAME": name,
+        "APP_WEBSITE": website,
+        "HOST": f"{host}/",
+        "ADMIN": f"{host}/admin",
+        "GRAPHQL": f"{host}/graphql",
+        "OPENAPI": f"{host}/openapi",
+        **feature_flags,
+    }
+
+
+def contextual_reference(request: Request = None, reduced: bool = True):
+    import karrio.server.core.gateway as gateway
+    import karrio.server.core.validators as validators
+    import karrio.server.core.middleware as middleware
+
+    request = request or middleware.SessionContext.get_current_request()
+    is_authenticated = lib.identity(
+        request.user.is_authenticated if hasattr(request, "user") else False
+    )
+    references = {
+        **contextual_metadata(request),
+        "ADDRESS_AUTO_COMPLETE": lib.failsafe(
+            lambda: validators.Address.get_info(is_authenticated),
+            None,
+        ),
+        **{
+            k: v
+            for k, v in REFERENCE_MODELS.items()
+            if k not in (REFERENCE_EXCLUSIONS if reduced else [])
+        },
+    }
+
+    def _get_generic_carriers():
+        # Get all carriers, then filter by extension instead of hardcoded slug
+        system_custom_carriers = [
+            c for c in gateway.Carriers.list(system_only=True)
+            if c.ext == "generic"
+        ]
+        custom_carriers = [
+            c
+            for c in (
+                gateway.Carriers.list(context=request).exclude(is_system=True)
+                if is_authenticated
+                else []
+            )
+            if c.ext == "generic"
+        ]
+
+        extra_carriers = {
+            c.carrier_code: c.display_name
+            for c in custom_carriers
+        }
+        system_carriers = {
+            c.carrier_code: c.display_name
+            for c in system_custom_carriers
+        }
+        extra_services = {
+            c.carrier_code: {
+                s.service_code: s.service_code
+                for s in c.services
+                or [
+                    lib.to_object(lib.models.ServiceLevel, _)
+                    for _ in references["service_levels"][c.ext]
+                ]
+            }
+            for c in custom_carriers
+        }
+        extra_service_names = {
+            name: {key: key.upper().replace("_", " ") for key, _ in value.items()}
+            for name, value in extra_services.items()
+        }
+
+        references.update(
+            dict(
+                custom_carriers=extra_carriers,
+                services={**references["services"], **extra_services},
+                carriers={**references["carriers"], **system_carriers},
+                service_names={**references["service_names"], **extra_service_names},
+            )
+        )
+
+    if request is not None and "generic" in CARRIER_NAMES:
+        _get_generic_carriers()
+
+    return references
+
+
+def get_carrier_details(
+    carrier_name: str,
+    contextual_reference: dict = None,
+) -> dict:
+    return ref.get_carrier_details(
+        carrier_name,
+        contextual_reference=contextual_reference or contextual_reference(),
+    )