pharos-sdk 0.1.0__py3-none-any.whl

pharos_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""Official Python SDK for Pharos Connect."""
+
+from pharos_sdk.async_client import AsyncPharosClient
+from pharos_sdk.client import PharosClient
+from pharos_sdk.config import AuthScheme
+from pharos_sdk.version import __version__
+
+__all__ = ["AsyncPharosClient", "AuthScheme", "PharosClient", "__version__"]

pharos_sdk/async_client.py

@@ -0,0 +1,52 @@
+"""Asynchronous Pharos Connect client."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import httpx
+
+from pharos_sdk.base import BaseClient
+from pharos_sdk.config import BASE_URL, AuthScheme, AuthSchemeInput, make_config
+from pharos_sdk.resources import AsyncDeclarationsResource, AsyncImportersResource
+from pharos_sdk.transport import AsyncTransport
+
+
+class AsyncPharosClient(BaseClient):
+    """Asynchronous client for the Pharos Connect API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = BASE_URL,
+        timeout: float = 10.0,
+        headers: Optional[Dict[str, str]] = None,
+        auth_scheme: AuthSchemeInput = AuthScheme.BEARER,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        """Create an asynchronous Pharos Connect client."""
+        config = make_config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers,
+            auth_scheme=auth_scheme,
+        )
+        self.transport = AsyncTransport(config, http_client=http_client)
+        self.importers = AsyncImportersResource(self.transport)
+        self.declarations = AsyncDeclarationsResource(self.transport)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client if this SDK instance owns it."""
+        await self.transport.close()
+
+    def is_closed(self) -> bool:
+        """Return whether the underlying HTTP client is closed."""
+        return bool(self.transport.client.is_closed)
+
+    async def __aenter__(self) -> AsyncPharosClient:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.close()

pharos_sdk/base.py

@@ -0,0 +1,13 @@
+"""Base client contracts."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class BaseClient(ABC):
+    """Common contract shared by sync and async clients."""
+
+    @abstractmethod
+    def is_closed(self) -> bool:
+        """Return whether the underlying SDK-owned transport is closed."""

pharos_sdk/client.py

@@ -0,0 +1,52 @@
+"""Synchronous Pharos Connect client."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import httpx
+
+from pharos_sdk.base import BaseClient
+from pharos_sdk.config import BASE_URL, AuthScheme, AuthSchemeInput, make_config
+from pharos_sdk.resources import DeclarationsResource, ImportersResource
+from pharos_sdk.transport import SyncTransport
+
+
+class PharosClient(BaseClient):
+    """Synchronous client for the Pharos Connect API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = BASE_URL,
+        timeout: float = 10.0,
+        headers: Optional[Dict[str, str]] = None,
+        auth_scheme: AuthSchemeInput = AuthScheme.BEARER,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        """Create a synchronous Pharos Connect client."""
+        config = make_config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers,
+            auth_scheme=auth_scheme,
+        )
+        self.transport = SyncTransport(config, http_client=http_client)
+        self.importers = ImportersResource(self.transport)
+        self.declarations = DeclarationsResource(self.transport)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client if this SDK instance owns it."""
+        self.transport.close()
+
+    def is_closed(self) -> bool:
+        """Return whether the underlying HTTP client is closed."""
+        return bool(self.transport.client.is_closed)
+
+    def __enter__(self) -> PharosClient:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        self.close()

pharos_sdk/config.py

@@ -0,0 +1,75 @@
+"""Client configuration for Pharos Connect."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, Optional, Union
+
+from pharos_sdk.exceptions import ConfigurationError
+
+
+class AuthScheme(str, Enum):
+    """Supported authentication header schemes."""
+
+    BEARER = "bearer"
+    API_KEY = "api_key"
+
+
+AuthSchemeInput = Union[AuthScheme, str]
+BASE_URL = "https://app.pharos.pe/api/v1"
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Configuration shared by sync and async clients."""
+
+    api_key: str
+    base_url: str = BASE_URL
+    timeout: float = 10.0
+    headers: Dict[str, str] = field(default_factory=dict)
+    auth_scheme: AuthScheme = AuthScheme.BEARER
+
+    def auth_headers(self) -> Dict[str, str]:
+        """Return authentication headers for the configured scheme."""
+        if self.auth_scheme == AuthScheme.BEARER:
+            return {"Authorization": f"Bearer {self.api_key}"}
+        elif self.auth_scheme == AuthScheme.API_KEY:
+            return {"X-Pharos-Key": self.api_key}
+        else:
+            raise ValueError(f"Unsupported auth scheme: {self.auth_scheme}")
+
+
+def normalize_auth_scheme(auth_scheme: AuthSchemeInput) -> AuthScheme:
+    """Normalize a public auth scheme value into AuthScheme."""
+    if isinstance(auth_scheme, AuthScheme):
+        return auth_scheme
+    try:
+        return AuthScheme(auth_scheme)
+    except ValueError as e:
+        raise ValueError(f"Unsupported auth scheme: {auth_scheme}") from e
+
+
+def make_config(
+    *,
+    api_key: str,
+    base_url: str,
+    timeout: float,
+    headers: Optional[Dict[str, str]],
+    auth_scheme: AuthSchemeInput,
+) -> ClientConfig:
+    """Validate client options and return a ClientConfig."""
+    if not api_key:
+        raise ConfigurationError("api_key is required.")
+    try:
+        normalized_auth_scheme = normalize_auth_scheme(auth_scheme)
+    except ValueError as e:
+        raise ConfigurationError("auth_scheme must be 'bearer' or 'api_key'.") from e
+    else:
+        return ClientConfig(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers or {},
+            auth_scheme=normalized_auth_scheme,
+        )

pharos_sdk/exceptions.py

@@ -0,0 +1,82 @@
+"""Exception hierarchy for Pharos Connect."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+class PharosError(Exception):
+    """Base class for all SDK errors."""
+
+
+class ConfigurationError(PharosError):
+    """Raised when client configuration is invalid."""
+
+
+class TransportError(PharosError):
+    """Raised when the HTTP transport cannot complete a request."""
+
+
+class ResponseDecodeError(PharosError):
+    """Raised when Pharos returns a response that cannot be decoded as JSON."""
+
+
+@dataclass
+class APIError(PharosError):
+    """Raised for documented Pharos API errors."""
+
+    message: str
+    status_code: int
+    code: Optional[str] = None
+    retry_after: Optional[int] = None
+    headers: Dict[str, str] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        code = f" ({self.code})" if self.code else ""
+        return f"Pharos API error {self.status_code}{code}: {self.message}"
+
+
+class AuthenticationError(APIError):
+    """Raised for missing or invalid API keys."""
+
+
+class AuthorizationError(APIError):
+    """Raised when the credential is valid but not allowed to access the API."""
+
+
+class NotFoundError(APIError):
+    """Raised when a resource does not exist or is outside the credential scope."""
+
+
+class RateLimitError(APIError):
+    """Raised when the API rate limit is exceeded."""
+
+
+class InvalidRequestError(APIError):
+    """Raised when request parameters are invalid."""
+
+
+class ServerError(APIError):
+    """Raised for unexpected Pharos server errors."""
+
+
+class WebhookVerificationError(PharosError):
+    """Raised when a webhook signature or payload cannot be verified."""
+
+
+@dataclass
+class UnsupportedWebhookEvent(PharosError):
+    """Raised when a webhook carries an event type this version does not know.
+
+    The signature and the timestamp were already checked, so the delivery is
+    authentic — only its type is unrecognised. **Catch this and answer 2xx**: a
+    rejected delivery counts as a failure, and enough consecutive failures
+    suspend the endpoint, so treating a new event type as an error would take
+    the whole integration down instead of only the part that is new.
+    """
+
+    event: str
+
+    def __str__(self) -> str:
+        return f"Unsupported Pharos webhook event: {self.event}"

pharos_sdk/models.py

@@ -0,0 +1,318 @@
+"""Dataclass models for the Pharos Connect OpenAPI contract."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Dict, Generic, Optional, Tuple, TypeVar, Union
+from uuid import UUID
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class ListEnvelope(Generic[T]):
+    """Common list response envelope returned by Pharos Connect."""
+
+    object: str
+    count: int
+    retrieved_at: datetime
+    data: Tuple[T, ...]
+    limit: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class Importer:
+    """Company included in the integration scope."""
+
+    object: str
+    ruc: str
+    name: str
+    address: str
+    department: Optional[str]
+    province: Optional[str]
+    district: Optional[str]
+
+
+@dataclass(frozen=True)
+class ImporterRef:
+    """Minimal importer identity used in summaries and webhooks."""
+
+    ruc: str
+    name: str
+
+
+@dataclass(frozen=True)
+class CustomsOffice:
+    """Customs office identity."""
+
+    code: str
+    name: str
+
+
+@dataclass(frozen=True)
+class CustomsBroker:
+    """Customs broker identity."""
+
+    code: str
+    name: str
+
+
+@dataclass(frozen=True)
+class Vehicle:
+    """Vehicle detail block for a vehicle item."""
+
+    category: str
+    vehicle_class: str
+    brand: str
+    model: str
+    version: str
+    model_year: Optional[int]
+    vin_number: str
+    chassis_number: str
+    engine_number: str
+    fuel_type: str
+    engine_cylinders_count: Optional[int]
+    engine_displacement_cc: Optional[Decimal]
+    engine_power: str
+    drivetrain: str
+    transmission_type: str
+    axles_count: int
+    wheels_count: Optional[Decimal]
+    seats_count: Optional[int]
+    passengers_count: int
+    color_1: str
+    color_2: Optional[str]
+    gross_weight: Optional[Decimal]
+    net_weight: Optional[Decimal]
+    load_capacity: Optional[Decimal]
+    length_mm: Optional[Decimal]
+    width_mm: Optional[Decimal]
+    height_mm: Optional[Decimal]
+    fob_usd: Optional[Decimal]
+    freight_usd: Optional[Decimal]
+    insurance_usd: Optional[Decimal]
+    additional_notes: str
+
+
+@dataclass(frozen=True)
+class Product:
+    """Product detail block for a product item."""
+
+    commercial_description: str
+    product_category: str
+    brand: str
+    model: str
+    quantity: Decimal
+
+
+@dataclass(frozen=True)
+class ItemBase:
+    """Fields shared by VehicleItem and ProductItem.
+
+    `retrieved_at` is set only when the item was fetched on its own, through
+    `declarations.item(...)`. Pharos puts it at the top level of every response,
+    which for a list is the envelope: read `ListEnvelope.retrieved_at` there, or
+    `Declaration.retrieved_at` for the items inside a declaration. It says when
+    Pharos built the response, not when the declaration was read from customs —
+    that is `created_at` and `updated_at`.
+    """
+
+    object: str
+    item_number: int
+    item_type: str
+    nandina_code: str
+    tariff_description: str
+    commercial_description: str
+    commercial_units: Decimal
+    commercial_unit_type: str
+    physical_units: Decimal
+    package_quantity: Decimal
+    package_class: str
+    net_weight_kg: Decimal
+    gross_weight_kg: Decimal
+    fob_usd: Decimal
+    freight_usd: Decimal
+    insurance_usd: Decimal
+    advalorem_usd: Decimal
+    igv_usd: Decimal
+    ipm_usd: Decimal
+    isc_usd: Decimal
+    origin_country: str
+    acquisition_country: str
+    port_of_loading: str
+    bill_of_lading: str
+    shipment_date: Optional[date]
+    invoice_numbers: Tuple[str, ...]
+    status: str
+    retrieved_at: Optional[datetime]
+
+
+@dataclass(frozen=True)
+class VehicleItem(ItemBase):
+    """Declaration item with a vehicle block."""
+
+    vehicle: Vehicle
+
+
+@dataclass(frozen=True)
+class ProductItem(ItemBase):
+    """Declaration item with a product block."""
+
+    product: Product
+
+
+Item = Union[VehicleItem, ProductItem]
+
+
+@dataclass(frozen=True)
+class DeclarationNumber:
+    """Structured DUA number accepted by declaration resource methods."""
+
+    customs_office: str
+    year: int
+    regime: str
+    number: int
+    control_number: Optional[str] = None
+
+    def format(self) -> str:
+        """Return the DUA number in the API path format."""
+        base = f"{self.customs_office}-{self.year}-{self.regime}-{self.number:06d}"
+        if self.control_number is None:
+            return base
+        else:
+            return f"{base}-{self.control_number}"
+
+    def __str__(self) -> str:
+        return self.format()
+
+
+@dataclass(frozen=True)
+class DeclarationHeader:
+    """Fields shared by Declaration and DeclarationSummary."""
+
+    full_number: str
+    customs_office: CustomsOffice
+    year: int
+    number: int
+    revision: int
+    numbering_date: date
+    channel: str
+    customs_broker: CustomsBroker
+    created_at: datetime
+    updated_at: datetime
+
+
+@dataclass(frozen=True)
+class TotalsBase:
+    """Value totals present on every declaration representation."""
+
+    items: int
+    fob_usd: Decimal
+    freight_usd: Decimal
+    insurance_usd: Decimal
+    cif_usd: Decimal
+
+
+@dataclass(frozen=True)
+class DeclarationSummary(DeclarationHeader):
+    """Header-only declaration returned by the latest endpoint."""
+
+    object: str
+    importer: ImporterRef
+    totals: TotalsBase
+
+
+@dataclass(frozen=True)
+class Transport:
+    """Transport block of a full declaration."""
+
+    mode: str
+    company: Optional[str]
+    terminal: str
+    manifest_number: str
+
+
+@dataclass(frozen=True)
+class DeclarationTotals(TotalsBase):
+    """Full declaration totals."""
+
+    net_weight_kg: Decimal
+    gross_weight_kg: Decimal
+    packages: Decimal
+    commercial_units: Decimal
+    physical_units: Decimal
+    liquidation: Decimal
+
+
+@dataclass(frozen=True)
+class Transaction:
+    """Transaction block of a full declaration."""
+
+    currency: str
+    payment_method: str
+    payment_term_days: Optional[int]
+
+
+@dataclass(frozen=True)
+class Declaration(DeclarationHeader):
+    """Full declaration with items, vehicles and products."""
+
+    object: str
+    arrival_date: Optional[date]
+    last_payment_date: date
+    importer: Importer
+    transport: Transport
+    totals: DeclarationTotals
+    transaction: Transaction
+    items: Tuple[Item, ...]
+    retrieved_at: datetime
+
+
+@dataclass(frozen=True)
+class WebhookDeclarationRef:
+    """Declaration reference carried by webhook events."""
+
+    full_number: str
+    customs_office_code: str
+    year: int
+    number: int
+    numbering_date: date
+    items_count: int
+
+
+@dataclass(frozen=True)
+class WebhookEvent:
+    """Base webhook event payload.
+
+    `extra` holds whatever the endpoint was configured to send on top of the
+    documented keys. The contract allows them — `additionalProperties: true` —
+    and a typed event has to give them one named home or drop them, so anything
+    that is not a field above arrives here. Values keep their JSON type, except
+    on a form-encoded endpoint, where a form carried no types and they are text.
+    """
+
+    event_id: UUID
+    event: str
+    occurred_at: datetime
+    revision: int
+    declaration: WebhookDeclarationRef
+    importer: ImporterRef
+    resource_url: str
+    extra: Dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DeclarationIngestedEvent(WebhookEvent):
+    """Webhook event emitted when a declaration first enters Pharos."""
+
+
+@dataclass(frozen=True)
+class DeclarationCorrectedEvent(WebhookEvent):
+    """Webhook event emitted when a declaration is reprocessed."""
+
+
+@dataclass(frozen=True)
+class DeclarationDeletedEvent(WebhookEvent):
+    """Webhook event emitted before a declaration is removed."""

pharos_sdk/parsers/__init__.py

@@ -0,0 +1,23 @@
+"""Explicit parsers for Pharos Connect response models."""
+
+from pharos_sdk.parsers.declarations import (
+    parse_declaration,
+    parse_declaration_summary,
+    parse_declaration_summary_value,
+)
+from pharos_sdk.parsers.envelopes import parse_list_envelope
+from pharos_sdk.parsers.importers import parse_importer, parse_importer_value
+from pharos_sdk.parsers.items import parse_item, parse_item_value
+from pharos_sdk.parsers.webhook_events import parse_webhook_event
+
+__all__ = [
+    "parse_declaration",
+    "parse_declaration_summary",
+    "parse_declaration_summary_value",
+    "parse_importer",
+    "parse_importer_value",
+    "parse_item",
+    "parse_item_value",
+    "parse_list_envelope",
+    "parse_webhook_event",
+]

pharos_sdk/parsers/customs.py

@@ -0,0 +1,23 @@
+"""Parsers for customs identity schemas."""
+
+from __future__ import annotations
+
+from pharos_sdk.models import CustomsBroker, CustomsOffice
+from pharos_sdk.parsers.primitives import field_string
+from pharos_sdk.types import JSONObject
+
+
+def parse_customs_office(payload: JSONObject, *, path: str) -> CustomsOffice:
+    """Parse a CustomsOffice object."""
+    return CustomsOffice(
+        code=field_string(payload, key="code", path=path),
+        name=field_string(payload, key="name", path=path),
+    )
+
+
+def parse_customs_broker(payload: JSONObject, *, path: str) -> CustomsBroker:
+    """Parse a CustomsBroker object."""
+    return CustomsBroker(
+        code=field_string(payload, key="code", path=path),
+        name=field_string(payload, key="name", path=path),
+    )