swifttrack 0.1.3.dev33__py3-none-any.whl

swifttrack/__init__.py

@@ -0,0 +1,31 @@
+"""SwiftTrack Python SDK.
+
+A production-grade Python SDK for the SwiftTrack logistics platform.
+"""
+
+from swifttrack.client import SwiftTrackClient
+from swifttrack.config import SwiftTrackConfig
+from swifttrack.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    SwiftTrackError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "SwiftTrackClient",
+    "SwiftTrackConfig",
+    "SwiftTrackError",
+    "AuthenticationError",
+    "PermissionError",
+    "RateLimitError",
+    "APIError",
+    "ValidationError",
+    "NotFoundError",
+    "ServerError",
+]

swifttrack/account.py

@@ -0,0 +1,186 @@
+"""Account service for SwiftTrack SDK."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from swifttrack.models.account import (
+    Account,
+    AccountType,
+    CreateAccountRequest,
+    LedgerTransaction,
+)
+
+if TYPE_CHECKING:
+    from swifttrack.utils.http_client import HTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class AccountService:
+    """Service for account/wallet operations."""
+
+    BASE_PATH = "/api/accounts/v1"
+
+    def __init__(self, http_client: HTTPClient) -> None:
+        self._client = http_client
+
+    def get_my_account(self, user_id: UUID | str) -> Account:
+        """Get the authenticated user's account.
+
+        Args:
+            user_id: User ID.
+
+        Returns:
+            Account object.
+
+        Raises:
+            NotFoundError: If account doesn't exist.
+            AuthenticationError: If user is not authenticated.
+        """
+        user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
+        logger.debug(f"Fetching account for user: {user_uuid}")
+
+        response = self._client.get(
+            f"{self.BASE_PATH}/getMyAccount",
+            params={"userId": str(user_uuid)},
+        )
+        account = Account.model_validate(response)
+
+        logger.info(f"Retrieved account: {account.id}")
+        return account
+
+    def get_transactions(
+        self,
+        account_id: UUID | str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[LedgerTransaction]:
+        """Get transactions for an account.
+
+        Args:
+            account_id: Account ID.
+            limit: Number of transactions to return (1-100).
+            offset: Pagination offset.
+
+        Returns:
+            List of LedgerTransaction objects.
+
+        Raises:
+            NotFoundError: If account doesn't exist.
+            AuthenticationError: If user is not authenticated.
+            PermissionError: If user doesn't have access to account.
+        """
+        account_uuid = UUID(account_id) if isinstance(account_id, str) else account_id
+        logger.debug(f"Fetching transactions for account: {account_uuid}")
+
+        response = self._client.get(
+            f"{self.BASE_PATH}/getTransactions",
+            params={"accountId": str(account_uuid), "limit": limit, "offset": offset},
+        )
+
+        transactions = [LedgerTransaction.model_validate(item) for item in response]
+
+        logger.info(f"Retrieved {len(transactions)} transactions")
+        return transactions
+
+    def create_account(
+        self,
+        user_id: UUID | str,
+        account_type: AccountType,
+    ) -> Account:
+        """Create a new account for a user.
+
+        Args:
+            user_id: User ID.
+            account_type: Type of account to create.
+
+        Returns:
+            Created Account object.
+
+        Raises:
+            ValidationError: If account already exists.
+            AuthenticationError: If user is not authenticated.
+            PermissionError: If user doesn't have permission.
+        """
+        user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
+        request = CreateAccountRequest.model_validate(
+            {"userId": user_uuid, "accountType": account_type}
+        )
+        logger.debug(f"Creating {account_type} account for user: {user_uuid}")
+
+        response = self._client.post(
+            f"{self.BASE_PATH}/createAccount",
+            json_data=request.model_dump(by_alias=True, exclude_none=True),
+        )
+        account = Account.model_validate(response)
+
+        logger.info(f"Created account: {account.id}")
+        return account
+
+    def reconcile_balance(self, account_id: UUID | str) -> str:
+        """Reconcile account balance from ledger transactions.
+
+        Args:
+            account_id: Account ID to reconcile.
+
+        Returns:
+            Reconciliation status message.
+
+        Raises:
+            NotFoundError: If account doesn't exist.
+            AuthenticationError: If user is not authenticated.
+            PermissionError: If user doesn't have access to account.
+        """
+        account_uuid = UUID(account_id) if isinstance(account_id, str) else account_id
+        logger.debug(f"Reconciling balance for account: {account_uuid}")
+
+        response: Any = self._client.post(
+            f"{self.BASE_PATH}/reconcile",
+            params={"accountId": str(account_uuid)},
+        )
+
+        if isinstance(response, str):
+            message = response
+        elif isinstance(response, dict):
+            message = str(response.get("message", ""))
+        else:
+            message = str(response)
+
+        logger.info(f"Reconciled account: {account_uuid}")
+        return message
+
+    def top_up_wallet(
+        self,
+        user_id: UUID | str,
+        amount: float,
+        reference: str | None = None,
+    ) -> Account:
+        """Top up a user's wallet (admin only).
+
+        Args:
+            user_id: User ID.
+            amount: Amount to add.
+            reference: Payment reference ID.
+
+        Returns:
+            Updated Account object.
+
+        Raises:
+            PermissionError: If user doesn't have admin permissions.
+            NotFoundError: If account doesn't exist.
+        """
+        user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
+        logger.debug(f"Topping up wallet for user: {user_uuid}, amount: {amount}")
+
+        params: dict[str, Any] = {"userId": str(user_uuid), "amount": str(amount)}
+        if reference:
+            params["reference"] = reference
+
+        response = self._client.post(f"{self.BASE_PATH}/admin/topupWallet", params=params)
+        account = Account.model_validate(response)
+
+        logger.info(f"Topped up wallet for user: {user_uuid}")
+        return account

swifttrack/address.py

@@ -0,0 +1,174 @@
+"""Address service for SwiftTrack SDK."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from swifttrack.models.address import Address, AddressRequest
+
+if TYPE_CHECKING:
+    from swifttrack.utils.http_client import HTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class AddressService:
+    """Service for address management operations."""
+
+    BASE_PATH = "/api/order/addresses/v1"
+
+    def __init__(self, http_client: HTTPClient) -> None:
+        self._client = http_client
+
+    def list_addresses(self) -> list[Address]:
+        """Get all saved addresses for the authenticated user.
+
+        Returns:
+            List of Address objects.
+
+        Raises:
+            AuthenticationError: If user is not authenticated.
+        """
+        logger.debug("Fetching all addresses")
+
+        response = self._client.get(self.BASE_PATH)
+        addresses = [Address.model_validate(item) for item in response]
+
+        logger.info(f"Retrieved {len(addresses)} addresses")
+        return addresses
+
+    def get_address(self, address_id: UUID | str) -> Address:
+        """Get a specific address by ID.
+
+        Args:
+            address_id: UUID of the address.
+
+        Returns:
+            Address object.
+
+        Raises:
+            NotFoundError: If address doesn't exist.
+            AuthenticationError: If user is not authenticated.
+        """
+        address_uuid = UUID(address_id) if isinstance(address_id, str) else address_id
+        logger.debug(f"Fetching address: {address_uuid}")
+
+        response = self._client.get(f"{self.BASE_PATH}/{address_uuid}")
+        address = Address.model_validate(response)
+
+        logger.info(f"Retrieved address: {address_uuid}")
+        return address
+
+    def get_default_address(self) -> Address:
+        """Get the default address for the authenticated user.
+
+        Returns:
+            Default Address object.
+
+        Raises:
+            NotFoundError: If no default address exists.
+            AuthenticationError: If user is not authenticated.
+        """
+        logger.debug("Fetching default address")
+
+        response = self._client.get(f"{self.BASE_PATH}/default")
+        address = Address.model_validate(response)
+
+        logger.info(f"Retrieved default address: {address.id}")
+        return address
+
+    def create_address(self, address: AddressRequest) -> Address:
+        """Create a new address.
+
+        Args:
+            address: AddressRequest containing address details.
+
+        Returns:
+            Created Address object.
+
+        Raises:
+            ValidationError: If address data is invalid.
+            AuthenticationError: If user is not authenticated.
+        """
+        logger.debug("Creating new address")
+
+        response = self._client.post(
+            self.BASE_PATH,
+            json_data=address.model_dump(by_alias=True, exclude_none=True),
+        )
+        created_address = Address.model_validate(response)
+
+        logger.info(f"Created address: {created_address.id}")
+        return created_address
+
+    def update_address(self, address_id: UUID | str, address: AddressRequest) -> Address:
+        """Update an existing address.
+
+        Args:
+            address_id: UUID of the address to update.
+            address: AddressRequest containing updated details.
+
+        Returns:
+            Updated Address object.
+
+        Raises:
+            NotFoundError: If address doesn't exist.
+            ValidationError: If address data is invalid.
+            AuthenticationError: If user is not authenticated.
+        """
+        address_uuid = UUID(address_id) if isinstance(address_id, str) else address_id
+        logger.debug(f"Updating address: {address_uuid}")
+
+        response = self._client.put(
+            f"{self.BASE_PATH}/{address_uuid}",
+            json_data=address.model_dump(by_alias=True, exclude_none=True),
+        )
+        updated_address = Address.model_validate(response)
+
+        logger.info(f"Updated address: {address_uuid}")
+        return updated_address
+
+    def set_default(self, address_id: UUID | str) -> Address:
+        """Set an address as the default.
+
+        Args:
+            address_id: UUID of the address to set as default.
+
+        Returns:
+            Updated Address object.
+
+        Raises:
+            NotFoundError: If address doesn't exist.
+            AuthenticationError: If user is not authenticated.
+        """
+        address_uuid = UUID(address_id) if isinstance(address_id, str) else address_id
+        logger.debug(f"Setting default address: {address_uuid}")
+
+        response = self._client.post(f"{self.BASE_PATH}/{address_uuid}/default")
+        updated_address = Address.model_validate(response)
+
+        logger.info(f"Set default address: {address_uuid}")
+        return updated_address
+
+    def delete_address(self, address_id: UUID | str) -> dict[str, Any]:
+        """Delete an address.
+
+        Args:
+            address_id: UUID of the address to delete.
+
+        Returns:
+            Response message.
+
+        Raises:
+            NotFoundError: If address doesn't exist.
+            AuthenticationError: If user is not authenticated.
+        """
+        address_uuid = UUID(address_id) if isinstance(address_id, str) else address_id
+        logger.debug(f"Deleting address: {address_uuid}")
+
+        response = self._client.delete(f"{self.BASE_PATH}/{address_uuid}")
+
+        logger.info(f"Deleted address: {address_uuid}")
+        return response if isinstance(response, dict) else {"message": str(response)}

swifttrack/auth.py

@@ -0,0 +1,78 @@
+"""Authentication service for SwiftTrack SDK."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from swifttrack.models.auth import LoginRequest, LoginResponse, UserDetails
+
+if TYPE_CHECKING:
+    from swifttrack.utils.http_client import HTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class AuthService:
+    """Service for authentication operations."""
+
+    BASE_PATH = "/api/tenant/api/users/v1"
+
+    def __init__(self, http_client: HTTPClient) -> None:
+        self._client = http_client
+
+    def login(self, email: str, password: str) -> LoginResponse:
+        """Authenticate with email and password.
+
+        Args:
+            email: User email address.
+            password: User password.
+
+        Returns:
+            LoginResponse containing the access token.
+
+        Raises:
+            AuthenticationError: If credentials are invalid.
+            ValidationError: If request validation fails.
+        """
+        request = LoginRequest(email=email, password=password)
+        logger.debug(f"Authenticating user: {email}")
+
+        response = self._client.post(
+            f"{self.BASE_PATH}/login/emailAndPassword",
+            json_data=request.model_dump(by_alias=True),
+        )
+
+        login_response = LoginResponse.model_validate(response)
+        logger.info(f"Successfully authenticated user: {email}")
+        return login_response
+
+    def get_user_details(self, token: str) -> UserDetails:
+        """Get user details from token.
+
+        Args:
+            token: JWT token to validate.
+
+        Returns:
+            UserDetails containing user information.
+
+        Raises:
+            AuthenticationError: If token is invalid.
+        """
+        logger.debug("Getting user details from token")
+
+        response = self._client.post(
+            f"{self.BASE_PATH}/getUserDetails",
+            params={"token": token},
+        )
+
+        return UserDetails.model_validate(response)
+
+    def update_auth_token(self, token: str) -> None:
+        """Update the authentication token for subsequent requests.
+
+        Args:
+            token: New authentication token.
+        """
+        self._client.update_token(token)
+        logger.debug("Updated authentication token")

swifttrack/client.py

@@ -0,0 +1,229 @@
+"""Main SwiftTrack client for interacting with the API."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from contextlib import contextmanager
+from types import TracebackType
+
+from typing_extensions import Self
+
+from swifttrack.account import AccountService
+from swifttrack.address import AddressService
+from swifttrack.auth import AuthService
+from swifttrack.config import SwiftTrackConfig
+from swifttrack.models.auth import LoginResponse
+from swifttrack.order import OrderService
+from swifttrack.utils.http_client import HTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class SwiftTrackClient:
+    """Main client for interacting with the SwiftTrack API.
+
+    This client provides a high-level interface to all SwiftTrack API endpoints,
+    with automatic authentication, retry logic, and error handling.
+
+    Example:
+        >>> from swifttrack import SwiftTrackClient
+        >>> client = SwiftTrackClient(base_url="https://api.example.com")
+        >>> client.login("user@email.com", "password")
+        >>> addresses = client.addresses.list_addresses()
+        >>> order = client.orders.get_order(order_id)
+
+    The client can be used as a context manager for automatic cleanup:
+        >>> with SwiftTrackClient() as client:
+        ...     client.login("user@email.com", "password")
+        ...     # use client...
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        config: SwiftTrackConfig | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        """Initialize the SwiftTrack client.
+
+        Args:
+            base_url: The base URL for the SwiftTrack API.
+                     Defaults to https://backend-swifttrack.ajayv.online
+            token: Optional authentication token.
+            config: Optional SwiftTrackConfig instance. If provided,
+                   base_url, token, timeout, and max_retries are ignored.
+            timeout: Request timeout in seconds (default: 30).
+            max_retries: Maximum number of retries for failed requests (default: 3).
+
+        Raises:
+            ValueError: If configuration is invalid.
+        """
+        if config is not None:
+            self._config = config
+        else:
+            # Use environment or default if base_url not provided
+            if base_url is None:
+                config = SwiftTrackConfig.from_env()
+                base_url = config.base_url
+
+            self._config = SwiftTrackConfig(
+                base_url=base_url or "https://backend-swifttrack.ajayv.online",
+                token=token,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+
+        self._http_client = HTTPClient(self._config)
+
+        # Initialize services
+        self._auth = AuthService(self._http_client)
+        self._addresses = AddressService(self._http_client)
+        self._orders = OrderService(self._http_client)
+        self._accounts = AccountService(self._http_client)
+
+        self._is_authenticated = self._config.token is not None
+
+        logger.debug(f"SwiftTrackClient initialized with base_url: {self._config.base_url}")
+
+    @property
+    def config(self) -> SwiftTrackConfig:
+        """Get the current configuration."""
+        return self._config
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if the client has an authentication token."""
+        return self._is_authenticated
+
+    @property
+    def auth(self) -> AuthService:
+        """Access authentication operations."""
+        return self._auth
+
+    @property
+    def addresses(self) -> AddressService:
+        """Access address operations."""
+        return self._addresses
+
+    @property
+    def orders(self) -> OrderService:
+        """Access order operations."""
+        return self._orders
+
+    @property
+    def accounts(self) -> AccountService:
+        """Access account/wallet operations."""
+        return self._accounts
+
+    def login(self, email: str, password: str) -> LoginResponse:
+        """Authenticate with email and password.
+
+        This method authenticates the user and automatically stores the
+        access token for subsequent API calls.
+
+        Args:
+            email: User email address.
+            password: User password.
+
+        Returns:
+            LoginResponse containing the access token.
+
+        Example:
+            >>> response = client.login("user@example.com", "password123")
+            >>> print(f"Token: {response.access_token}")
+
+        Raises:
+            AuthenticationError: If credentials are invalid.
+            ValidationError: If request validation fails.
+        """
+        response = self._auth.login(email, password)
+        self._set_token(response.access_token)
+        return response
+
+    def set_token(self, token: str) -> Self:
+        """Set or update the authentication token.
+
+        Use this method to manually set the token if you have it from
+        an external source (e.g., stored from a previous session).
+
+        Args:
+            token: The authentication token.
+
+        Returns:
+            Self for method chaining.
+
+        Example:
+            >>> client.set_token("your-jwt-token")
+            >>> # or chain it:
+            >>> client.set_token("token").addresses.list_addresses()
+        """
+        self._set_token(token)
+        return self
+
+    def _set_token(self, token: str) -> None:
+        """Internal method to set the token."""
+        self._http_client.update_token(token)
+        self._config = self._http_client.config
+        self._is_authenticated = True
+        logger.debug("Authentication token set")
+
+    def logout(self) -> None:
+        """Clear the authentication token.
+
+        This method clears the stored token but does not invalidate it
+        on the server. Call this when the user logs out of your application.
+        """
+        self._http_client.update_token("")
+        self._is_authenticated = False
+        logger.debug("Logged out, token cleared")
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources.
+
+        This method should be called when you're done using the client
+        to properly close the underlying HTTP connection pool.
+        """
+        self._http_client.close()
+        logger.debug("SwiftTrackClient closed")
+
+    def __enter__(self) -> Self:
+        """Enter context manager."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit context manager."""
+        self.close()
+
+    @contextmanager
+    def temp_token(self, token: str) -> Iterator[Self]:
+        """Context manager to temporarily use a different token.
+
+        This is useful for operations that need a different user's token
+        without affecting the main client's authentication.
+
+        Args:
+            token: Temporary token to use.
+
+        Example:
+            >>> with client.temp_token("other-user-token"):
+            ...     # operations use the temporary token
+            ...     addresses = client.addresses.list_addresses()
+            >>> # original token is restored
+        """
+        original_token = self._config.token
+        try:
+            self._set_token(token)
+            yield self
+        finally:
+            if original_token:
+                self._set_token(original_token)
+            else:
+                self.logout()