visor-python 0.1.0__py3-none-any.whl

visor/models/_base.py

@@ -0,0 +1,353 @@
+from datetime import date
+from enum import Enum
+from typing import Any, NamedTuple
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+
+class VisorRequestModel(BaseModel):
+    """Base for request/filter models. The API fails closed on unknown params."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class VisorResponseModel(BaseModel):
+    """Base for API responses. Beta responses may add fields over time."""
+
+    model_config = ConfigDict(extra="ignore")
+
+
+# ---------------------------------------------------------------------------
+# Shared response building blocks
+# ---------------------------------------------------------------------------
+
+
+class VehicleOption(VisorResponseModel):
+    code: str
+    name: str
+    msrp: float | None = None
+
+
+class VehicleBuild(VisorResponseModel):
+    year: int
+    make: str
+    model: str
+    trim: str | None = None
+    version: str | None = None
+    body_type: str | None = None
+    drivetrain: str | None = None
+    fuel_type: str | None = None
+    powertrain_type: str | None = None
+    transmission: str | None = None
+    engine: str | None = None
+    cylinders: int | None = None
+    doors: int | None = None
+    seating_capacity: int | None = None
+    exterior_color: str | None = None
+    interior_color: str | None = None
+    base_exterior_color: str | None = None
+    base_interior_color: str | None = None
+    assembly_location: str | None = None
+    assembly_country: str | None = None
+    window_sticker_verified: bool = False
+    base_msrp: int | None = None
+    combined_msrp: int | None = None
+    options: list[VehicleOption] | None = None
+
+
+class VehicleRecord(VisorResponseModel):
+    """VIN-level wrapper as returned inside ListingDetail.vehicle."""
+
+    vin: str
+    status: str
+    build: VehicleBuild
+
+
+class PriceHistoryEntry(VisorResponseModel):
+    date: date
+    price: int
+
+
+class DealerRef(VisorResponseModel):
+    dealer_id: str
+    name: str
+    city: str
+    state: str
+    latitude: float | None = None
+    longitude: float | None = None
+    phone: str | None = None
+
+
+class Pagination(VisorResponseModel):
+    limit: int
+    offset: int
+    total: int
+    next_offset: int | None = None
+
+
+class BBox(NamedTuple):
+    """Bounding box for map-viewport filtering: west, south, east, north."""
+
+    west: float
+    south: float
+    east: float
+    north: float
+
+
+# ---------------------------------------------------------------------------
+# Filter enums
+# ---------------------------------------------------------------------------
+
+
+class InventoryMode(str, Enum):
+    ACTIVE = "active"
+    SOLD = "sold"
+
+
+class SortOrder(str, Enum):
+    DAYS_ON_MARKET = "days_on_market"
+    DAYS_ON_MARKET_DESC = "-days_on_market"
+    PRICE = "price"
+    PRICE_DESC = "-price"
+    MILES = "miles"
+    MILES_DESC = "-miles"
+    MSRP = "msrp"
+    MSRP_DESC = "-msrp"
+    DISCOUNT = "discount"
+    DISCOUNT_DESC = "-discount"
+    DISTANCE = "distance"
+
+
+# ---------------------------------------------------------------------------
+# ListingsFilterBase — shared by ListingsFilter and FacetsFilter
+# ---------------------------------------------------------------------------
+
+
+class ListingsFilterBase(VisorRequestModel):
+    # Categorical filters (comma-separated on the wire)
+    make: list[str] | None = None
+    model: list[str] | None = None
+    trim: list[str] | None = None
+    year: list[int] | None = None
+    state: list[str] | None = None
+    dealer_id: list[str] | None = None
+    dealer_type: list[str] | None = None
+    availability_status: list[str] | None = None
+    inventory_type: list[str] | None = None
+    body_type: list[str] | None = None
+    transmission: list[str] | None = None
+    drivetrain: list[str] | None = None
+    fuel_type: list[str] | None = None
+    powertrain_type: list[str] | None = None
+    engine: list[str] | None = None
+    version: list[str] | None = None
+    exterior_color: list[str] | None = None
+    interior_color: list[str] | None = None
+    base_exterior_color: list[str] | None = None
+    base_interior_color: list[str] | None = None
+    seating_capacity: list[int] | None = None
+    cylinders: list[int] | None = None
+    doors: list[int] | None = None
+    options_packages: list[str] | None = None
+    features: list[str] | None = None
+    keywords: list[str] | None = None
+    vin_pattern: list[str] | None = None
+
+    # assembly_location uses PIPE separator (not comma)
+    assembly_location: list[str] | None = None
+    assembly_country: list[str] | None = None
+
+    # Exclude counterparts (comma-separated, EXCEPT assembly_location uses "+")
+    exclude_make: list[str] | None = None
+    exclude_model: list[str] | None = None
+    exclude_trim: list[str] | None = None
+    exclude_year: list[int] | None = None
+    exclude_state: list[str] | None = None
+    exclude_inventory_type: list[str] | None = None
+    exclude_body_type: list[str] | None = None
+    exclude_transmission: list[str] | None = None
+    exclude_drivetrain: list[str] | None = None
+    exclude_version: list[str] | None = None
+    exclude_engine: list[str] | None = None
+    exclude_assembly_location: list[str] | None = None  # plus-separated on the wire
+    exclude_assembly_country: list[str] | None = None
+    exclude_exterior_color: list[str] | None = None
+    exclude_interior_color: list[str] | None = None
+    exclude_base_exterior_color: list[str] | None = None
+    exclude_base_interior_color: list[str] | None = None
+    exclude_options_packages: list[str] | None = None
+    exclude_features: list[str] | None = None
+    exclude_fuel_type: list[str] | None = None
+    exclude_powertrain_type: list[str] | None = None
+    exclude_keywords: list[str] | None = None
+
+    # Range filters (integers, serialized as strings)
+    min_price: int | None = None
+    max_price: int | None = None
+    min_mileage: int | None = None
+    max_mileage: int | None = None
+    min_msrp: int | None = None
+    max_msrp: int | None = None
+    min_days_on_market: int | None = None
+    max_days_on_market: int | None = None
+
+    # Inventory mode
+    inventory_status: InventoryMode = InventoryMode.ACTIVE
+    sold_within_days: int | None = None
+    snapshot_date: date | None = None
+
+    # Geo
+    postal_code: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    radius: float | None = None
+    bbox: BBox | None = None
+
+    @model_validator(mode="after")
+    def _validate_geo_and_inventory(self) -> "ListingsFilterBase":
+        if self.radius is not None:
+            has_postal = self.postal_code is not None
+            has_latlon = self.latitude is not None and self.longitude is not None
+            if not (has_postal ^ has_latlon):
+                raise ValueError(
+                    "radius requires exactly one of postal_code"
+                    " or (latitude + longitude)"
+                )
+        if self.bbox is not None and self.radius is not None:
+            raise ValueError("bbox and radius are mutually exclusive")
+        if (
+            self.sold_within_days is not None
+            and self.inventory_status != InventoryMode.SOLD
+        ):
+            raise ValueError("sold_within_days requires inventory_status='sold'")
+        if (
+            self.snapshot_date is not None
+            and self.inventory_status != InventoryMode.ACTIVE
+        ):
+            raise ValueError("snapshot_date requires inventory_status='active'")
+        # NOTE: this branch is unreachable in practice — earlier checks already
+        # enforce sold_within_days→SOLD and snapshot_date→ACTIVE, making both
+        # non-None simultaneously impossible. Kept as a logical guard.
+        if self.sold_within_days is not None and self.snapshot_date is not None:
+            raise ValueError(
+                "sold_within_days and snapshot_date are mutually exclusive"
+            )
+        return self
+
+    def to_params(self) -> dict[str, str]:
+        """Serialize to flat query-string params, handling all separator quirks."""
+        params: dict[str, str] = {}
+
+        def comma(field: str, values: list[Any]) -> None:
+            if values:
+                params[field] = ",".join(str(v) for v in values)
+
+        def pipe(field: str, values: list[Any]) -> None:
+            if values:
+                params[field] = "|".join(str(v) for v in values)
+
+        def plus(field: str, values: list[Any]) -> None:
+            if values:
+                params[field] = "+".join(str(v) for v in values)
+
+        # Categorical fields (comma-separated)
+        for field in [
+            "make",
+            "model",
+            "trim",
+            "state",
+            "dealer_id",
+            "dealer_type",
+            "availability_status",
+            "inventory_type",
+            "body_type",
+            "transmission",
+            "drivetrain",
+            "fuel_type",
+            "powertrain_type",
+            "engine",
+            "version",
+            "exterior_color",
+            "interior_color",
+            "base_exterior_color",
+            "base_interior_color",
+            "options_packages",
+            "features",
+            "keywords",
+            "vin_pattern",
+            "assembly_country",
+            "exclude_make",
+            "exclude_model",
+            "exclude_trim",
+            "exclude_state",
+            "exclude_inventory_type",
+            "exclude_body_type",
+            "exclude_transmission",
+            "exclude_drivetrain",
+            "exclude_version",
+            "exclude_engine",
+            "exclude_assembly_country",
+            "exclude_exterior_color",
+            "exclude_interior_color",
+            "exclude_base_exterior_color",
+            "exclude_base_interior_color",
+            "exclude_options_packages",
+            "exclude_features",
+            "exclude_fuel_type",
+            "exclude_powertrain_type",
+            "exclude_keywords",
+        ]:
+            val = getattr(self, field)
+            if val is not None:
+                comma(field, val)
+
+        # Integer list fields (year, seating_capacity, etc.) — same comma join
+        for field in ["year", "seating_capacity", "cylinders", "doors", "exclude_year"]:
+            val = getattr(self, field)
+            if val is not None:
+                comma(field, val)
+
+        # Special separators
+        if self.assembly_location:
+            pipe("assembly_location", self.assembly_location)
+        if self.exclude_assembly_location:
+            plus("exclude_assembly_location", self.exclude_assembly_location)
+
+        # Range filters
+        for field in [
+            "min_price",
+            "max_price",
+            "min_mileage",
+            "max_mileage",
+            "min_msrp",
+            "max_msrp",
+            "min_days_on_market",
+            "max_days_on_market",
+        ]:
+            val = getattr(self, field)
+            if val is not None:
+                params[field] = str(val)
+
+        # Inventory mode (omit default to keep URLs clean)
+        if self.inventory_status != InventoryMode.ACTIVE:
+            params["inventory_status"] = self.inventory_status.value
+        if self.sold_within_days is not None:
+            params["sold_within_days"] = str(self.sold_within_days)
+        if self.snapshot_date is not None:
+            params["snapshot_date"] = self.snapshot_date.isoformat()
+
+        # Geo
+        if self.postal_code is not None:
+            params["postal_code"] = self.postal_code
+        if self.latitude is not None:
+            params["latitude"] = str(self.latitude)
+        if self.longitude is not None:
+            params["longitude"] = str(self.longitude)
+        if self.radius is not None:
+            params["radius"] = str(self.radius)
+        if self.bbox is not None:
+            params["bbox"] = (
+                f"{self.bbox.west},{self.bbox.south},{self.bbox.east},{self.bbox.north}"
+            )
+
+        return params

visor/models/dealers.py

@@ -0,0 +1,81 @@
+from typing import Literal
+
+from pydantic import Field, field_validator
+
+from visor.models._base import Pagination, VisorRequestModel, VisorResponseModel
+
+
+class DealerFilter(VisorRequestModel):
+    limit: int = 50
+    offset: int = 0
+    dealer_id: list[str] | None = None
+    state: list[str] | None = None
+    country: str | None = None
+    type: Literal["franchise", "independent"] | None = None
+    make: list[str] | None = None
+    q: str | None = None
+
+    @field_validator("limit")
+    @classmethod
+    def _limit_max(cls, v: int) -> int:
+        if v > 100:
+            raise ValueError("limit maximum is 100")
+        return v
+
+    @field_validator("dealer_id")
+    @classmethod
+    def _dealer_id_max(cls, v: list[str] | None) -> list[str] | None:
+        if v is not None and len(v) > 100:
+            raise ValueError("dealer_id maximum is 100 entries")
+        return v
+
+    def to_params(self) -> dict[str, str]:
+        params: dict[str, str] = {
+            "limit": str(self.limit),
+            "offset": str(self.offset),
+        }
+        if self.dealer_id:
+            params["dealer_id"] = ",".join(self.dealer_id)
+        if self.state:
+            params["state"] = ",".join(self.state)
+        if self.country:
+            params["country"] = self.country
+        if self.type:
+            params["type"] = self.type
+        if self.make:
+            params["make"] = ",".join(self.make)
+        if self.q:
+            params["q"] = self.q
+        return params
+
+
+class DealerAddress(VisorResponseModel):
+    line1: str | None = None
+    city: str
+    state: str
+    country: str
+
+
+class DealerSummary(VisorResponseModel):
+    dealer_id: str
+    name: str
+    city: str
+    state: str
+    country: str
+    latitude: float | None = None
+    longitude: float | None = None
+    type: str
+    website: str | None = None
+    makes: list[str] = Field(default_factory=list)
+    listing_count: int
+
+
+class DealerDetail(DealerSummary):
+    phone: str | None = None
+    address: DealerAddress | None = None
+
+
+class DealersPage(VisorResponseModel):
+    data: list[DealerSummary]
+    pagination: Pagination
+    meta: dict[str, object] = Field(default_factory=dict)

visor/models/facets.py

@@ -0,0 +1,142 @@
+from typing import Literal, TypeAlias
+
+from pydantic import Field, field_validator, model_validator
+
+from visor.models._base import ListingsFilterBase, VisorResponseModel
+
+FACET_NAMES = {
+    "make",
+    "model",
+    "inventory_type",
+    "year",
+    "trim",
+    "version",
+    "base_exterior_color",
+    "exterior_color",
+    "base_interior_color",
+    "interior_color",
+    "seating_capacity",
+    "doors",
+    "engine",
+    "state",
+    "drivetrain",
+    "assembly_location",
+    "assembly_country",
+    "transmission",
+    "fuel_type",
+    "body_type",
+    "cylinders",
+    "dealer_type",
+    "availability_status",
+    "options_packages",
+    "features",
+    "keywords",
+    "price",
+    "msrp",
+    "miles",
+    "days_on_market",
+}
+
+FacetSort: TypeAlias = Literal["count", "-count", "metric", "-metric"]
+
+# Facets that return range histograms; all others are categorical (bucket lists).
+RANGE_FACET_NAMES = {"price", "msrp", "miles", "days_on_market"}
+CATEGORICAL_FACET_NAMES = FACET_NAMES - RANGE_FACET_NAMES
+
+
+class FacetsFilter(ListingsFilterBase):
+    """Filter for GET /v1/facets. No pagination or projection."""
+
+    facets: list[str]
+    facet_value_limit: int | None = None
+    metric: str | None = None
+    sort: FacetSort = "-count"
+
+    @field_validator("facets")
+    @classmethod
+    def _validate_facets(cls, v: list[str]) -> list[str]:
+        unknown = set(v) - FACET_NAMES
+        if unknown:
+            raise ValueError(f"unknown facets: {unknown}")
+        return v
+
+    @field_validator("facet_value_limit")
+    @classmethod
+    def _facet_value_limit_max(cls, v: int | None) -> int | None:
+        if v is not None and v > 100:
+            raise ValueError("facet_value_limit maximum is 100")
+        return v
+
+    @model_validator(mode="after")
+    def _validate_metric_needs_categorical_facet(self) -> "FacetsFilter":
+        if self.metric is not None:
+            categorical = [f for f in self.facets if f in CATEGORICAL_FACET_NAMES]
+            if len(categorical) != 1:
+                raise ValueError(
+                    "metric requires exactly one categorical facet; "
+                    f"got {len(categorical)} ({categorical})"
+                )
+        return self
+
+    def to_params(self) -> dict[str, str]:
+        params = super().to_params()
+        params["facets"] = ",".join(self.facets)
+        if self.facet_value_limit is not None:
+            params["facet_value_limit"] = str(self.facet_value_limit)
+        if self.metric is not None:
+            params["metric"] = self.metric
+        params["sort"] = self.sort
+        return params
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class FacetBucket(VisorResponseModel):
+    value: str
+    count: int | None = None
+    metric: float | None = None
+
+
+class RangeBucket(VisorResponseModel):
+    min: float
+    max: float
+    count: int
+
+
+class RangeFacet(VisorResponseModel):
+    buckets: list[RangeBucket]
+    interval: float
+    min: float
+    max: float
+
+
+class FieldStats(VisorResponseModel):
+    min: float
+    max: float
+    count: int
+    missing: int
+    mean: float
+    median: float
+    stddev: float
+
+
+class FacetsData(VisorResponseModel):
+    total: int
+    facets: dict[str, list[FacetBucket]] = Field(default_factory=dict)
+    range_facets: dict[str, RangeFacet] = Field(default_factory=dict)
+    stats: dict[str, FieldStats] = Field(default_factory=dict)
+
+
+class FacetsMeta(VisorResponseModel):
+    facets: list[str]
+    metric: str
+    sort: str
+    minimum_metric_count: int
+
+
+class FacetsResponse(VisorResponseModel):
+    data: FacetsData
+    meta: FacetsMeta