shippingboapy 0.1.0__py3-none-any.whl

shippingboapy/auth.py

@@ -0,0 +1,117 @@
+from dataclasses import dataclass
+from shippingboapy.config import ShippingBoConfig
+import httpx
+import time
+from shippingboapy.exceptions import BadRequestError, UnauthorizedError, AuthenticationError, TokenRefreshError
+from typing import Callable, Any, Awaitable
+
+@dataclass
+class TokenData:
+    access_token: str
+    token_type: str
+    expires_in: int
+    refresh_token: str
+    scope: str
+    created_at: int | None
+    
+def is_token_expired(token_data: TokenData) -> bool:
+    """Check if the token has expired."""
+    if token_data.created_at is None:
+        return True
+    current_time = int(time.time())
+    return current_time >= token_data.created_at + token_data.expires_in
+
+async def get_token(auth_code: str, session: httpx.AsyncClient, config: ShippingBoConfig, headers: dict[str, Any] | None = None) -> TokenData | None:
+    """
+    Get a valid access token, refreshing it if necessary.
+    Args:
+        auth_code (str): The authorization code to use for obtaining the access token.
+        session (httpx.AsyncClient): The HTTP client session to use for making the request.
+        config (ShippingBoConfig): The configuration object containing necessary parameters.
+        headers (dict[str, Any] | None): Optional headers to include in the request.
+    Returns:
+        TokenData | None: The token data if the request is successful, otherwise None.
+    Raises:
+        BadRequestError: If the request is malformed or contains invalid parameters.
+        UnauthorizedError: If the request is unauthorized.
+        AuthenticationError: If there is an error obtaining the token.
+    """
+    payload = {
+        'grant_type': 'authorization_code',
+        'code': auth_code,
+        'client_id': config.client_id,
+        'client_secret' : config.client_secret,
+        'redirect_uri': config.redirect_uri
+    }
+    
+    response = await session.post(config.auth_url, json=payload, headers=headers)
+
+    if response.status_code == 200:
+        token_data = response.json()
+    
+        token = TokenData(
+            access_token=token_data['access_token'],
+            token_type=token_data['token_type'],
+            expires_in=token_data['expires_in'],
+            refresh_token=token_data['refresh_token'],
+            scope=token_data['scope'],
+            created_at= token_data.get('created_at', int(time.time()))
+        )
+    
+        return token
+    else:
+        if response.status_code == 400:
+            raise BadRequestError(status_code=response.status_code, message=f"Bad request: {response.text}")
+        elif response.status_code == 401:
+            raise UnauthorizedError(status_code=response.status_code, message=f"Unauthorized access: {response.text}")
+        else:
+            raise AuthenticationError(f"Failed to get token: {response.status_code} - {response.text}")
+        
+async def refresh_token(refresh_token: str, 
+                        session: httpx.AsyncClient, 
+                        config: ShippingBoConfig, 
+                        headers: dict[str, Any] | None = None,
+                        on_refresh: Callable[[TokenData], Awaitable[None]] | None = None) -> TokenData: 
+    """
+    Refresh the access token using the refresh token.
+    Args:
+        refresh_token (str): The refresh token to use for refreshing the access token.
+        session (httpx.AsyncClient): The HTTP client session to use for making the request.
+        config (ShippingBoConfig): The configuration object containing necessary parameters.
+        headers (dict[str, Any] | None): Optional headers to include in the request.
+        on_refresh (Callable[[TokenData], Awaitable[None]] | None): Optional callback function to be called after a successful token refresh. The function should accept a TokenData object as its argument.
+    Returns:
+        TokenData: The new token data if the refresh is successful.
+    Raises:
+        TokenRefreshError: If there is an error refreshing the token.
+    """
+    payload = {
+        'grant_type': 'refresh_token',
+        'refresh_token': refresh_token,
+        'client_id': config.client_id,
+        'client_secret': config.client_secret,
+        'redirect_uri': config.redirect_uri
+    }
+    
+    response = await session.post(config.auth_url, json=payload, headers=headers)
+    if response.status_code == 200:
+        token_data = response.json()
+        if on_refresh is not None and callable(on_refresh):
+            await on_refresh(TokenData(
+                access_token=token_data['access_token'],
+                token_type=token_data['token_type'],
+                expires_in=token_data['expires_in'],
+                refresh_token=token_data['refresh_token'],
+                scope=token_data['scope'],
+                created_at=int(time.time())
+            ))
+        return TokenData(
+            access_token=token_data['access_token'],
+            token_type=token_data['token_type'],
+            expires_in=token_data['expires_in'],
+            refresh_token=token_data['refresh_token'],
+            scope=token_data['scope'],
+            created_at=int(time.time())
+        )
+    else:
+        raise TokenRefreshError(f"Failed to refresh token: {response.status_code} - {response.text}")

shippingboapy/client.py

@@ -0,0 +1,222 @@
+import httpx
+from shippingboapy.config import ShippingBoConfig
+from shippingboapy.auth import TokenData, get_token, refresh_token
+import asyncio
+from shippingboapy.exceptions import BadRequestError, AuthenticationError, TokenRefreshError, UnexpectedError, ForbiddenError, NotFoundError, ServerError
+from shippingboapy.resources.product import ProductResource
+from shippingboapy.resources.order import OrderResource
+from shippingboapy.resources.order_tag import OrderTagResource
+from shippingboapy.resources.pack_component import PackComponentResource
+from shippingboapy.resources.package import PackageResource
+from shippingboapy.resources.order_document import OrderDocumentResource
+from shippingboapy.resources.address_label import AddressLabelResource
+from shippingboapy.resources.order_dispatch import OrderDispatchResource
+from shippingboapy.resources.order_event import OrderEventResource
+from shippingboapy.resources.address_label_summaries import AddressLabelSummariesResource
+from shippingboapy.resources.address_label_config import AddressLabelConfigResource
+from shippingboapy.resources.address import AddressResource
+from shippingboapy.resources.background_job import BackgroundJobResource
+from shippingboapy.resources.carrier import CarrierResource
+from shippingboapy.resources.client_order_origin import ClientOrderOriginResource
+from shippingboapy.resources.client_order_source import ClientOrderSourceResource
+from shippingboapy.resources.dangerous_good_product_informations import DangerousGoodProductInformationResource
+from shippingboapy.resources.kit_component import KitComponentResource
+from shippingboapy.resources.logistician_service_config import LogisticianServiceConfigResource
+from shippingboapy.resources.order_item_product_mapping import OrderItemProductMappingResource
+
+from typing import Callable, Awaitable, Any, Protocol
+
+class OnTokenRefreshCallback(Protocol):
+    async def __call__(self, token_data: TokenData) -> None: ...
+    
+class RetryableRequest(Protocol):
+    async def __call__(self, _retry: int = 0, **kwargs: Any) -> httpx.Response: ...
+
+class Client:
+    def __init__(self, access_token: str  = "", 
+                 refresh_token: str = "",
+                 app_id: str = "",
+                 api_version: str  = "",
+                 client_id: str = "",
+                 client_secret: str  = "",
+                 on_token_refresh: OnTokenRefreshCallback | None = None):
+        
+        if not app_id:
+            raise AuthenticationError("app_id is required")
+        if not api_version:
+            raise AuthenticationError("api_version is required")
+        if not client_id:
+            raise AuthenticationError("client_id is required")
+        if not client_secret:
+            raise AuthenticationError("client_secret is required")
+        
+        self.on_token_refresh: Callable[[TokenData], Awaitable[None]] | None = on_token_refresh
+        
+        self.config = ShippingBoConfig(
+            app_id=app_id,
+            api_version=api_version,
+            client_id=client_id,
+            client_secret=client_secret
+        )
+        
+        self.token: TokenData | None = TokenData(
+            access_token=str(access_token),
+            refresh_token=str(refresh_token),
+            token_type= "Bearer",
+            expires_in=3600,
+            scope="",
+            created_at = None
+        )
+        self.session = httpx.AsyncClient(timeout=self.config.timeout)
+        
+        
+        self.products = ProductResource(self)
+        self.orders = OrderResource(self)
+        self.order_tags = OrderTagResource(self)
+        self.pack_components = PackComponentResource(self)
+        self.packages = PackageResource(self)
+        self.order_documents = OrderDocumentResource(self)
+        self.address_labels = AddressLabelResource(self)
+        self.order_dispatches = OrderDispatchResource(self)
+        self.order_events = OrderEventResource(self)
+        self.address_label_summaries = AddressLabelSummariesResource(self)
+        self.address_label_configs = AddressLabelConfigResource(self)
+        self.address = AddressResource(self)
+        self.background_jobs = BackgroundJobResource(self)
+        self.carrier = CarrierResource(self)
+        self.client_order_origin = ClientOrderOriginResource(self)
+        self.client_order_source = ClientOrderSourceResource(self)
+        self.dangerous_good_product_informations = DangerousGoodProductInformationResource(self)
+        self.kit_components = KitComponentResource(self)
+        self.logistician_service_configs = LogisticianServiceConfigResource(self)
+        self.order_item_product_mappings = OrderItemProductMappingResource(self)
+        
+    def _set_token(self, token_data: TokenData):
+        self.token = token_data
+    
+    def set_config(self, timeout: int | None = None, max_retries: int | None = None, retry_backoff_factor: float | None = None, redirect_uri: str | None = None, auth_url: str | None = None, api_url: str | None = None):
+        if timeout is not None:
+            self.config.timeout = timeout
+            self.session.timeout = timeout
+        if max_retries is not None:
+            self.config.max_retries = max_retries
+        if retry_backoff_factor is not None:
+            self.config.retry_backoff_factor = retry_backoff_factor
+        if redirect_uri is not None:
+            self.config.redirect_uri = redirect_uri
+        if auth_url is not None:
+            self.config.auth_url = auth_url
+        if api_url is not None:
+            self.config.api_url = api_url
+    
+    async def _process_response(self, response: httpx.Response) -> httpx.Response:
+        match response.status_code:
+            case s if 200 <= s < 300:
+                return response
+            case 400:
+                raise BadRequestError(response.status_code, f"Bad request: {response.text}")
+            case 401:
+                raise AuthenticationError(response.status_code, f"Authentication failed: {response.text}")
+            case 403:
+                raise ForbiddenError(response.status_code, f"Forbidden access: {response.text}")
+            case 404:
+                raise NotFoundError(response.status_code, f"Resource not found: {response.text}")
+            case 422:
+                raise BadRequestError(response.status_code, f"Unprocessable entity: {response.text}")
+            case s if s >= 500:
+                raise ServerError(response.status_code, f"Server error after {self.config.max_retries} retries: {response.text}")
+            case _:
+                raise UnexpectedError(response.status_code, f"Unexpected error: {response.text}")
+            
+    
+    async def _raw_request(self, method: str, endpoint: str, params: dict[str, Any] | None = None, **kwargs: Any) -> httpx.Response:
+        
+        if self.token is None:
+            raise AuthenticationError("Access token is missing. Please authenticate first.")
+        
+        url = f"{self.config.api_url.rstrip('/')}/{endpoint.lstrip('/')}"
+        extra_headers = kwargs.pop("headers", {})
+        
+        auth_attempts : int = 0
+        server_attempts : int = 0
+        
+        while True:
+            
+            headers = {
+                "Authorization": f"Bearer {self.token.access_token}",
+                "X-API-VERSION": self.config.api_version,
+                "X-API-APP-ID": self.config.app_id,
+                "Accept": "application/json",  
+                **extra_headers
+            }
+        
+            response = await self.session.request(method, url, headers=headers, params=params, **kwargs)
+
+            if response.status_code == 401 and auth_attempts == 0:
+                auth_attempts += 1
+                try:
+                    new_token : TokenData | None = await refresh_token(self.token.refresh_token, self.session, self.config, on_refresh=self.on_token_refresh)
+                    self._set_token(new_token)
+                    continue 
+                except Exception as e:
+                    raise TokenRefreshError(f"Failed to refresh token: {str(e)}") from e
+                
+            if response.status_code >= 500 and server_attempts < self.config.max_retries:
+                server_attempts += 1
+                await asyncio.sleep(self.config.retry_backoff_factor * (2 ** (server_attempts - 1)))
+                continue
+            
+            return await self._process_response(response)
+
+    async def _request(self, method: str, endpoint: str, params: dict[str, Any] | None = None, **kwargs: Any) -> Any:
+        response = await self._raw_request(method, endpoint, params, **kwargs)
+        if not response.content:
+            return {}
+        return response.json()
+
+
+    async def _download(self, method: str, endpoint: str, params: dict[str, Any] | None = None, **kwargs: Any) -> bytes:
+        kwargs.setdefault("headers", {})["Accept"] = "application/pdf, application/octet-stream, */*"
+        response = await self._raw_request(method, endpoint, params, **kwargs)
+        return response.content 
+       
+    
+    @classmethod
+    async def from_auth_code(cls, auth_code: str, app_id: str, api_version: str, client_id: str, client_secret: str, redirect_uri: str | None = None, headers: dict[str, Any] | None = None):
+        config_dict : dict[str, Any] = {
+            "app_id": app_id,
+            "api_version": api_version,
+            "client_id": client_id,
+            "client_secret": client_secret
+        }
+        
+        if redirect_uri is not None:
+            config_dict["redirect_uri"] = redirect_uri
+            
+        config = ShippingBoConfig(**config_dict)
+        async with httpx.AsyncClient(timeout=config.timeout) as session:
+            token = await get_token(auth_code, session, config, headers)
+            
+        if token is None:
+            raise AuthenticationError("Failed to obtain access token with the provided authorization code.")
+            
+        cls = cls(
+            access_token=token.access_token,
+            refresh_token=token.refresh_token,
+            app_id=config.app_id,
+            api_version=config.api_version,
+            client_id=config.client_id,
+            client_secret=config.client_secret
+        )
+        cls._set_token(token)
+        return cls
+    
+    async def close(self):
+        await self.session.aclose()
+    
+    async def __aenter__(self):
+        return self
+    
+    async def __aexit__(self):
+        await self.close()
+

shippingboapy/config.py

@@ -0,0 +1,15 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class ShippingBoConfig(BaseSettings):
+    app_id: str
+    api_version: str
+    client_secret: str
+    client_id: str
+    auth_url: str = "https://oauth.shippingbo.com/oauth/token"
+    api_url: str = "https://app.shippingbo.com"
+    redirect_uri: str = "urn:ietf:wg:oauth:2.0:oob"
+    max_retries: int = 3
+    retry_backoff_factor: float = 0.5
+    timeout : int = 30
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

shippingboapy/exceptions.py

@@ -0,0 +1,54 @@
+class ShippingboAPYException(Exception):
+    """Base exception for ShippingboAPY."""
+    pass
+
+class ValueError(ValueError):
+    """Raised when an invalid value is provided."""
+    pass
+
+class AuthenticationError(ShippingboAPYException):
+    """Raised when authentication fails."""
+    pass
+
+class TokenExpiredError(AuthenticationError):
+    """Raised when the authentication token has expired."""
+    pass
+
+class TokenRefreshError(AuthenticationError):
+    """Raised when there is an error refreshing the authentication token."""
+    pass
+
+class APIRequestError(ShippingboAPYException):
+    """Raised when an API request fails."""
+    def __init__(self, status_code, message):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"API Request failed with status {status_code}: {message}")
+        
+class BadRequestError(APIRequestError):
+    """Raised when the API request is malformed or contains invalid parameters."""
+    pass
+
+class UnauthorizedError(APIRequestError):
+    """Raised when the API request is unauthorized."""
+    pass
+
+class ForbiddenError(APIRequestError):
+    """Raised when the API request is forbidden."""
+    pass
+
+class NotFoundError(APIRequestError):
+    """Raised when the requested resource is not found."""
+    pass
+
+class RateLimitError(APIRequestError):
+    """Raised when the API rate limit is exceeded."""
+    pass
+
+class ServerError(APIRequestError):
+    """Raised when the server encounters an error."""
+    pass
+
+class UnexpectedError(APIRequestError):
+    """Raised when an unexpected error occurs."""
+    pass

shippingboapy/models/address.py

@@ -0,0 +1,101 @@
+from pydantic import BaseModel, Field
+from typing import Optional
+from shippingboapy.models.types import ShippingboDateTime
+
+class Address(BaseModel):
+    apartement_number: Optional[str] = Field(None, description="The number of the apartment, if applicable.")
+    building: Optional[str] = Field(None, alias="building", description="The building name or number, if applicable.")
+    city: str = Field(..., alias="city", description="The city of the address.")
+    civility: Optional[str] = Field(None, alias="civilitity", description="The civility of the recipient (e.g., Mr, Ms, Company).")
+    company_name: Optional[str] = Field(None, alias="company_name", description="The name of the company, if applicable.")
+    country: str = Field(..., alias="country", description="The country of the address.")
+    created_at: Optional[ShippingboDateTime] = Field(None, alias="created_at", description="The date and time when the address was created.")
+    email: Optional[str] = Field(None, alias="email", description="The email address associated with the address.")
+    eori_importer: Optional[str] = Field(None, alias="eori_importer", description="The EORI number of the importer, if applicable.")
+    firstname: Optional[str] = Field(None, alias="firstname", description="The first name of the recipient.")
+    fullname: Optional[str] = Field(None, alias="fullname", description="The full name of the recipient.")
+    id: Optional[int] = Field(..., alias="id", description="The unique identifier of the address.")
+    instructions: Optional[str] = Field(None, alias="instructions", description="Special instructions for the delivery, if applicable.")
+    lastname: Optional[str] = Field(None, alias="lastname", description="The last name of the recipient.")
+    phone1: Optional[str] = Field(None, alias="phone", description="The phone number associated with the address.")
+    phone2: Optional[str] = Field(None, alias="phone2", description="An additional phone number associated with the address, if applicable.")
+    place_name: Optional[str] = Field(None, alias="place_name", description="The name of the place, if applicable.")
+    state: Optional[str] = Field(None, alias="state", description="The state or province of the address.")
+    street1: Optional[str] = Field(None, alias="street1", description="The first line of the street address.")
+    street2: Optional[str] = Field(None, alias="street2", description="The second line of the street address, if applicable.")
+    street3: Optional[str] = Field(None, alias="street3", description="The third line of the street address, if applicable.")
+    street4: Optional[str] = Field(None, alias="street4", description="The fourth line of the street address, if applicable.")
+    updated_at: Optional[ShippingboDateTime] = Field(None, alias="updated_at", description="The date and time when the address was last updated.")
+    vat_importer: Optional[str] = Field(None, alias="vat_importer", description="The VAT number of the importer, if applicable.")
+    zip: Optional[str] = Field(None, alias="zip", description="The postal code of the address.")
+
+    model_config = {
+        "extra": "allow",
+        "populate_by_name": True,
+        "validate_assignment": True
+    }   
+    
+class AddressCreate(BaseModel):
+    apartement_number: Optional[str] = Field(None, alias="apartement_number", description="The number of the apartment, if applicable.")
+    building: Optional[str] = Field(None, alias="building", description="The building name or number, if applicable.")
+    city: str = Field(..., alias="city", description="The city of the address.")
+    civility: Optional[str] = Field(None, alias="civilitity", description="The civility of the recipient (e.g., Mr, Ms, Company).")
+    company_name: Optional[str] = Field(None, alias="company_name", description="The name of the company, if applicable.")
+    country: str = Field(..., alias="country", description="The country of the address.")
+    created_at: Optional[ShippingboDateTime] = Field(None, alias="created_at", description="The date and time when the address was created.")
+    email: Optional[str] = Field(None, alias="email", description="The email address associated with the address.")
+    eori_importer: Optional[str] = Field(None, alias="eori_importer", description="The EORI number of the importer, if applicable.")
+    firstname: Optional[str] = Field(None, alias="firstname", description="The first name of the recipient.")
+    fullname: Optional[str] = Field(None, alias="fullname", description="The full name of the recipient.")
+    instructions: Optional[str] = Field(None, alias="instructions", description="Special instructions for the delivery, if applicable.")
+    lastname: Optional[str] = Field(None, alias="lastname", description="The last name of the recipient.")
+    phone1: Optional[str] = Field(None, alias="phone", description="The phone number associated with the address.")
+    phone2: Optional[str] = Field(None, alias="phone2", description="An additional phone number associated with the address, if applicable.")
+    place_name: Optional[str] = Field(None, alias="place_name", description="The name of the place, if applicable.")
+    state: Optional[str] = Field(None, alias="state", description="The state or province of the address.")
+    street1: Optional[str] = Field(None, alias="street1", description="The first line of the street address.")
+    street2: Optional[str] = Field(None, alias="street2", description="The second line of the street address, if applicable.")
+    street3: Optional[str] = Field(None, alias="street3", description="The third line of the street address, if applicable.")
+    street4: Optional[str] = Field(None, alias="street4", description="The fourth line of the street address, if applicable.")
+    updated_at: Optional[ShippingboDateTime] = Field(None, alias="updated_at", description="The date and time when the address was last updated.")
+    vat_importer: Optional[str] = Field(None, alias="vat_importer", description="The VAT number of the importer, if applicable.")
+    zip: Optional[str] = Field(None, alias="zip", description="The postal code of the address.")
+    
+    model_config = {
+        "extra": "allow",
+        "populate_by_name": True,
+        "validate_assignment": True
+    }
+
+class AddressUpdate(BaseModel):
+    address_kind: Optional[str] = Field("", alias="address_kind", description="The kind of the address (e.g., shipping, billing), if applicable.")
+    client_ref: Optional[str] = Field("", alias="client_ref", description="A client reference for the address, if applicable.")
+    prefill_origin: Optional[str] = Field("", alias="prefill_origin", description="The origin to prefill the address with, if applicable.")
+    apartement_number: Optional[str] = Field("", alias="apartement_number", description="The number of the apartment, if applicable.")
+    building: Optional[str] = Field("", alias="building", description="The building name or number, if applicable.")
+    city: str = Field(..., alias="city", description="The city of the address.")
+    civility: Optional[str] = Field("", alias="civility", description="The civility of the recipient (e.g., Mr, Ms, Company).")
+    company_name: Optional[str] = Field("", alias="company_name", description="The name of the company, if applicable.")
+    country: str = Field(..., alias="country", description="The country of the address.")
+    email: Optional[str] = Field("", alias="email", description="The email address associated with the address.")
+    eori_importer: Optional[str] = Field("", alias="eori_importer", description="The EORI number of the importer, if applicable.")
+    firstname: Optional[str] = Field("", alias="frstname", description="The first name of the recipient.") # Note: The alias "frstname" is intentional to match the expected field name in the API request for updating an address, which may differ from the field name used in the Address model.
+    fullname: Optional[str] = Field("", alias="fullname", description="The full name of the recipient.")
+    instructions: Optional[str] = Field("", alias="instructions", description="Special instructions for the delivery, if applicable.")
+    lastname: Optional[str] = Field("", alias="lastname", description="The last name of the recipient.")
+    phone1: Optional[str] = Field("", alias="phone", description="The phone number associated with the address.")
+    phone2: Optional[str] = Field("", alias="phone2", description="An additional phone number associated with the address, if applicable.")
+    place_name: Optional[str] = Field("", alias="place_name", description="The name of the place, if applicable.")
+    state: Optional[str] = Field("", alias="state", description="The state or province of the address.")
+    street1: Optional[str] = Field("", alias="street1", description="The first line of the street address.")
+    street2: Optional[str] = Field("", alias="street2", description="The second line of the street address, if applicable.")
+    street3: Optional[str] = Field("", alias="street3", description="The third line of the street address, if applicable.")
+    street4: Optional[str] = Field("", alias="street4", description="The fourth line of the street address, if applicable.")
+    vat_importer: Optional[str] = Field("", alias="vat_importer", description="The VAT number of the importer, if applicable.")
+    zip: Optional[str] = Field("", alias="zip", description="The postal code of the address.")
+    
+    model_config = {
+        "extra": "allow",
+        "populate_by_name": True,
+        "validate_assignment": True
+    }

shippingboapy/models/address_label.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel, Field
+from typing import Optional
+
+class AddressLabel(BaseModel):
+    address_label_config_id: int = Field(..., alias="address_label_config_id", description="The unique identifier of the address label configuration associated with the address label.")
+    id: Optional[int] = Field(None, alias="id", description="The unique identifier of the address label.")
+    label_url: Optional[str] = Field(None, alias="label_url", description="The URL of the address label, if applicable.")
+    package_id: Optional[int] = Field(None, alias="package_id", description="The unique identifier of the package associated with the address label, if applicable.")
+    
+    model_config = {
+        "extra": "allow",
+        "populate_by_name": True,
+        "validate_assignment": True
+    }