repsapi 0.1.0__py3-none-any.whl

repsapi/_errors.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+__all__ = [
+    "RepsApiError",
+    "APIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    "APITimeoutError",
+]
+
+
+class RepsApiError(Exception):
+    """Base class of every error this client raises."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class APIError(RepsApiError):
+    """The API answered with an error status."""
+
+    def __init__(
+        self,
+        status: int,
+        type: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        #: HTTP status
+        self.status = status
+        #: the API's error type, e.g. "bad_request", "unauthorized", "rate_limited"
+        self.type = type
+        #: extra fields of the error, e.g. ``allowed``, ``fields``, ``reset_at``
+        self.details: Dict[str, Any] = details or {}
+        #: the parsed response body (or the raw text when it isn't JSON)
+        self.body = body
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(status={self.status}, type={self.type!r}, message={self.message!r})"
+
+
+class BadRequestError(APIError):
+    """400, 413, 415 and other 4xx: the request itself is wrong."""
+
+
+class AuthenticationError(APIError):
+    """401: missing, malformed, invalid or revoked API key."""
+
+
+class PermissionDeniedError(APIError):
+    """403: the key lacks this API's scope, or the IP isn't whitelisted."""
+
+
+class NotFoundError(APIError):
+    """404"""
+
+
+class UnprocessableEntityError(APIError):
+    """422: no platform and product id could be read from the link."""
+
+
+class RateLimitError(APIError):
+    """429: per-minute rate limit or daily quota."""
+
+    def __init__(
+        self,
+        status: int,
+        type: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(status, type, message, details, body)
+        d = self.details
+        #: seconds to wait, from Retry-After
+        self.retry_after = retry_after
+        #: when the exhausted limit resets
+        self.reset_at: Optional[datetime] = _parse_time(d.get("reset_at"))
+        #: "org" = the workspace quota, "key" = the project's own daily cap
+        self.scope: Optional[str] = d.get("scope") if isinstance(d.get("scope"), str) else None
+        self.limit: Optional[int] = d.get("limit") if isinstance(d.get("limit"), int) else None
+        self.used: Optional[int] = d.get("used") if isinstance(d.get("used"), int) else None
+
+
+class InternalServerError(APIError):
+    """5xx: something failed on our side (already retried)."""
+
+
+class APIConnectionError(RepsApiError):
+    """The request never got an answer (DNS, TLS, connection reset ...)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """No answer within the timeout."""
+
+
+def _parse_time(value: Any) -> Optional[datetime]:
+    if not isinstance(value, str):
+        return None
+    try:
+        # fromisoformat before 3.11 doesn't take a trailing "Z"
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None

repsapi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

repsapi/types.py

@@ -0,0 +1,509 @@
+"""Response types of the RepsApi.pl API.
+
+Every method returns the API's JSON as plain dicts; these TypedDicts only
+describe them for editors and type checkers.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Literal, Optional, TypedDict
+
+Platform = Literal["weidian", "taobao", "1688", "tmall"]
+
+Agent = Literal[
+    "kakobuy", "cnfans", "acbuy", "mulebuy", "hoobuy", "oopbuy", "cnshopper", "ootdbuy",
+    "ponybuy", "superbuy", "sugargoo", "loongbuy", "cssbuy", "usfans", "litbuy",
+]
+
+TrackingStage = Literal[
+    "info_received", "received", "in_transit", "export_customs", "awaiting_flight",
+    "flight_departed", "flight_arrived", "import_customs", "last_mile", "out_for_delivery",
+    "ready_for_pickup", "delivered", "delayed", "exception", "returned",
+]
+
+ServiceName = Literal["api", "tracking", "qc", "lookup", "convert"]
+ServiceStatus = Literal["operational", "degraded", "down"]
+ChangeTag = Literal["new", "improved", "fixed", "removed"]
+
+# "from" is a keyword, hence the functional syntax
+Exchange = TypedDict(
+    "Exchange",
+    {"from": str, "to": str, "rate": float, "date": str, "source": Literal["NBP", "ECB"]},
+)
+
+
+class Dimensions(TypedDict):
+    length: float
+    width: float
+    height: float
+
+
+class Country(TypedDict):
+    code: str
+    name: str
+
+
+# ------------------------------- tracking -------------------------------
+
+class TrackingUpdate(TypedDict):
+    date: str
+    hour: str
+    status: str
+    status_en: str
+    status_original: str
+    stage: TrackingStage
+    location: str
+    country: Optional[str]
+
+
+EstimatedDelivery = TypedDict(
+    "EstimatedDelivery",
+    {"from": str, "to": str, "based_on": int, "from_stage": TrackingStage, "slower_than_usual": bool},
+)
+
+
+class TrackingSummary(TypedDict):
+    stage: TrackingStage
+    status: str
+    status_en: str
+    delivered: bool
+    last_update: str
+    origin_country: Optional[str]
+    destination_country: Optional[str]
+    carrier: Optional[str]
+    carrier_tracking_number: Optional[str]
+    estimated_delivery: Optional[EstimatedDelivery]
+
+
+class TrackingResponse(TypedDict):
+    tracking_number: str
+    count: int
+    summary: Optional[TrackingSummary]
+    updates: List[TrackingUpdate]
+    source: str
+    attribution: str
+    docs: str
+
+
+# ---------------------------------- QC ----------------------------------
+
+class _QcBatchBase(TypedDict):
+    date: Optional[str]
+    photos: List[str]
+
+
+class QcBatch(_QcBatchBase, total=False):
+    sku: str
+
+
+class _QcResponseBase(TypedDict):
+    platform: Platform
+    product_id: str
+    canonical: Optional[str]
+    provider: Optional[str]
+    total_photos: int
+    batch_count: int
+    batches: List[QcBatch]
+    listing_photos: List[str]
+    source: str
+    docs: str
+
+
+class QcResponse(_QcResponseBase, total=False):
+    note: str
+
+
+# -------------------------------- lookup --------------------------------
+
+class PriceRange(TypedDict):
+    low: Optional[float]
+    high: Optional[float]
+    discount_low: Optional[float]
+    discount_high: Optional[float]
+    currency: str
+
+
+class _VariantOptionBase(TypedDict):
+    name: str
+    values: List[str]
+
+
+class VariantOption(_VariantOptionBase, total=False):
+    name_cn: str
+    values_en: List[str]
+    values_pl: List[str]
+    images: Dict[str, str]
+
+
+class _VariantSkuBase(TypedDict):
+    attrs: Dict[str, str]
+    stock: Optional[int]
+    price: Optional[float]
+    image: Optional[str]
+
+
+class VariantSku(_VariantSkuBase, total=False):
+    price_local: Optional[float]
+
+
+class Variants(TypedDict):
+    options: List[VariantOption]
+    skus: List[VariantSku]
+
+
+class Labeled(TypedDict):
+    label: str
+    value: str
+
+
+class WarehouseStats(TypedDict):
+    storage_time: Optional[Labeled]
+    turnover: Optional[Labeled]
+    weight_g: Optional[float]
+    volume_cm3: Optional[float]
+    dimensions_cm: Optional[str]
+
+
+class WeightEstimate(TypedDict):
+    grams: int
+    category: str
+    source: Literal["similar_items", "typical"]
+    based_on: Optional[int]
+
+
+class PricePoint(TypedDict):
+    date: str
+    low: Optional[float]
+    high: Optional[float]
+
+
+class Seller(TypedDict):
+    id: Optional[str]
+    name: str
+
+
+class Availability(TypedDict):
+    in_stock: Optional[bool]
+    total_stock: Optional[int]
+
+
+class Money(TypedDict):
+    price: Optional[float]
+    currency: str
+
+
+class QcCount(TypedDict):
+    batches: int
+    photos: int
+
+
+class _LookupResponseBase(TypedDict):
+    platform: Platform
+    product_id: str
+    canonical: Optional[str]
+    source_agent: Optional[Agent]
+    title: Optional[str]
+    title_en: Optional[str]
+    title_pl: Optional[str]
+    main_image: Optional[str]
+    images: List[str]
+    price: Optional[PriceRange]
+    domestic_shipping: Optional[Money]
+    min_order: Optional[int]
+    seller: Optional[Seller]
+    availability: Availability
+    variant_source: Optional[Platform]
+    sizes: List[str]
+    versions: List[str]
+    variants: Variants
+    warehouse: Optional[WarehouseStats]
+    category: Optional[str]
+    weight_estimate: Optional[WeightEstimate]
+    qc: Optional[QcCount]
+    price_history: List[PricePoint]
+    source: str
+    docs: str
+
+
+class LookupResponse(_LookupResponseBase, total=False):
+    # only with currency=...
+    exchange: Optional[Exchange]
+    price_local: Optional[PriceRange]
+    domestic_shipping_local: Optional[Money]
+    note: str
+
+
+# -------------------------------- convert -------------------------------
+
+class ConvertResponse(TypedDict):
+    platform: Platform
+    id: str
+    canonical: str
+    agents: Dict[str, str]
+    source: str
+    docs: str
+
+
+# ------------------------------- shipping -------------------------------
+
+class LineDays(TypedDict):
+    min: Optional[int]
+    max: Optional[int]
+
+
+class LineFees(TypedDict):
+    first: Optional[float]
+    additional: Optional[float]
+    service: Optional[float]
+    fuel: Optional[float]
+    handling: Optional[float]
+
+
+class WeightLimits(TypedDict):
+    min: Optional[int]
+    max: Optional[int]
+
+
+class LineAccepts(TypedDict):
+    brands: bool
+    battery: bool
+    liquids: bool
+
+
+class _ShippingLineBase(TypedDict):
+    id: str
+    name: str
+    days: LineDays
+    price: float
+    currency: Literal["CNY"]
+    fees: LineFees
+    chargeable_weight_g: Optional[int]
+    volumetric_divisor: Optional[int]
+    weight_limits_g: WeightLimits
+    accepts: LineAccepts
+    restrictions: Optional[str]
+    features: Optional[str]
+
+
+class ShippingLine(_ShippingLineBase, total=False):
+    price_local: Optional[float]
+
+
+class _HaulItemBase(TypedDict):
+    url: str
+    platform: Optional[str]
+    product_id: Optional[str]
+    title: Optional[str]
+    title_pl: Optional[str]
+    image: Optional[str]
+    seller: Optional[str]
+    quantity: int
+    unit_price: Optional[float]
+    domestic_shipping: Optional[float]
+    weight_g: Optional[float]
+    weight_source: Optional[Literal["measured", "estimate"]]
+    dimensions_cm: Optional[Dimensions]
+
+
+class HaulItem(_HaulItemBase, total=False):
+    unit_price_local: Optional[float]
+    error: Literal["unsupported_link", "not_found"]
+
+
+class ParcelInfo(TypedDict):
+    weight_g: int
+    dimensions_cm: Optional[Dimensions]
+
+
+class _ShippingEstimateBase(TypedDict):
+    country: Country
+    parcel: ParcelInfo
+    currency: Literal["CNY"]
+    lines: List[ShippingLine]
+    cheapest: Optional[str]
+    fastest: Optional[str]
+    note: str
+    source: str
+    docs: str
+
+
+class ShippingEstimateResponse(_ShippingEstimateBase, total=False):
+    items: List[HaulItem]
+    exchange: Optional[Exchange]
+
+
+class ShippingCountriesResponse(TypedDict):
+    countries: List[Country]
+    count: int
+    source: str
+    docs: str
+
+
+# --------------------------------- haul ---------------------------------
+
+class _HaulItemInputBase(TypedDict):
+    url: str
+
+
+class HaulItemInput(_HaulItemInputBase, total=False):
+    quantity: int
+
+
+class LocalTotals(TypedDict):
+    goods: Optional[float]
+    domestic_shipping: Optional[float]
+    shipping: Optional[float]
+    total: Optional[float]
+    currency: str
+
+
+class _HaulTotalsBase(TypedDict):
+    goods: float
+    domestic_shipping: float
+    shipping: Optional[float]
+    total: Optional[float]
+
+
+class HaulTotals(_HaulTotalsBase, total=False):
+    local: LocalTotals
+
+
+class HaulParcel(TypedDict):
+    weight_g: int
+    dimensions_cm: Optional[Dimensions]
+    weight_complete: bool
+
+
+class HaulShipping(TypedDict):
+    lines: List[ShippingLine]
+    cheapest: Optional[str]
+    fastest: Optional[str]
+
+
+class _HaulResponseBase(TypedDict):
+    country: Country
+    currency: Literal["CNY"]
+    items: List[HaulItem]
+    totals: HaulTotals
+    parcel: HaulParcel
+    shipping: Optional[HaulShipping]
+    notes: List[str]
+    source: str
+    docs: str
+
+
+class HaulResponse(_HaulResponseBase, total=False):
+    exchange: Exchange
+
+
+# ----------------------------- account / misc ---------------------------
+
+class UsageProject(TypedDict):
+    name: str
+    today: int
+    daily_cap: Optional[int]
+
+
+class UsageWorkspace(TypedDict):
+    used_today: int
+    limit_per_day: Optional[int]
+    remaining: Optional[int]
+    rate_per_min: Optional[int]
+    reset_at: str
+
+
+class UsageResponse(TypedDict):
+    plan: Literal["free", "pro", "enterprise"]
+    project: UsageProject
+    workspace: UsageWorkspace
+    source: str
+    docs: str
+
+
+class RatesResponse(TypedDict):
+    base: str
+    date: str
+    source: Literal["NBP", "ECB"]
+    rates: Dict[str, float]
+    source_site: str
+    docs: str
+
+
+class ServiceSources(TypedDict):
+    up: int
+    total: int
+
+
+class ServiceHealth(TypedDict):
+    status: ServiceStatus
+    latency_ms: int
+    sources: ServiceSources
+
+
+class DayService(TypedDict):
+    status: ServiceStatus
+    uptime: float
+
+
+class DayHistory(TypedDict):
+    date: str
+    services: Dict[str, DayService]
+
+
+class _HealthResponseBase(TypedDict):
+    status: ServiceStatus
+    checked_at: str
+    services: Dict[str, ServiceHealth]
+    uptime_30d: Dict[str, Optional[float]]
+    source: str
+    docs: str
+
+
+class HealthResponse(_HealthResponseBase, total=False):
+    history: List[DayHistory]
+
+
+class Bilingual(TypedDict):
+    en: str
+    pl: str
+
+
+class ChangeItem(TypedDict):
+    tag: ChangeTag
+    en: str
+    pl: str
+
+
+class Release(TypedDict):
+    version: str
+    date: str
+    url: str
+    title: Bilingual
+    items: List[ChangeItem]
+
+
+class ChangelogResponse(TypedDict):
+    latest: Optional[str]
+    releases: List[Release]
+    rss: str
+    source: str
+
+
+class LocalizedChangeItem(TypedDict):
+    tag: ChangeTag
+    text: str
+
+
+class LocalizedRelease(TypedDict):
+    version: str
+    date: str
+    url: str
+    title: str
+    items: List[LocalizedChangeItem]
+
+
+class LocalizedChangelogResponse(TypedDict):
+    latest: Optional[str]
+    releases: List[LocalizedRelease]
+    rss: str
+    source: str