binaaz-python-sdk 0.1.0__py3-none-any.whl

binaaz_sdk/errors.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BinaAzError(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class ConfigurationError(BinaAzError):
+    pass
+
+
+class InvalidRequestError(BinaAzError, ValueError):
+    pass
+
+
+class TransportError(BinaAzError):
+    def __init__(self, message: str, *, path: str = "") -> None:
+        super().__init__(message)
+        self.path = path
+
+
+class NotSentError(TransportError):
+    pass
+
+
+class OutcomeUnknownError(TransportError):
+    def __init__(self, message: str, *, status_code: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.status_code = status_code
+
+
+class APIError(BinaAzError):
+    def __init__(self, message: str, *, status_code: int = 0, body: Any = None, path: str = "") -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.path = path
+
+    def __str__(self) -> str:
+        return f"[{self.status_code}] {self.message}" if self.status_code else self.message
+
+
+class BlockedError(APIError):
+    pass
+
+
+class BadRequestError(APIError):
+    pass
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(APIError):
+    pass
+
+
+class GraphQLError(BadRequestError):
+    def __init__(self, message: str, *, errors: Any = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.errors = list(errors or [])
+
+
+class ItemError(BadRequestError):
+    def __init__(self, message: str, *, status: Optional[str] = None, errors: Any = None,
+                 locked_until: Optional[str] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.status = status
+        self.errors = list(errors or [])
+        self.locked_until = locked_until
+
+
+class NotSupportedError(BinaAzError):
+    pass
+
+
+class CodeRejectedError(BadRequestError):
+    pass
+
+
+def for_status(status: int) -> type[APIError]:
+    if status in (401, 403, 419):
+        return AuthenticationError
+    if status == 404:
+        return NotFoundError
+    if status == 429:
+        return RateLimitError
+    if status >= 500:
+        return ServerError
+    if status >= 400:
+        return BadRequestError
+    return APIError

binaaz_sdk/messages.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import resources
+from pathlib import Path
+from typing import Any, Union
+
+import yaml
+
+PathLike = Union[str, Path]
+
+_PACKAGE_FILE = "messages.yaml"
+_catalog: dict[str, str] = {}
+
+
+def _flatten(node: Mapping[str, Any], prefix: str = "") -> dict[str, str]:
+    flat: dict[str, str] = {}
+    for key, value in node.items():
+        path = f"{prefix}{key}"
+        if isinstance(value, Mapping):
+            flat.update(_flatten(value, f"{path}."))
+        else:
+            flat[path] = str(value)
+    return flat
+
+
+def _parse(raw: str) -> dict[str, str]:
+    data = yaml.safe_load(raw) or {}
+    if not isinstance(data, Mapping):
+        raise ValueError("messages file must contain a mapping")
+    return _flatten(data)
+
+
+def _read_packaged() -> dict[str, str]:
+    raw = resources.files(__package__).joinpath(_PACKAGE_FILE).read_text(encoding="utf-8")
+    return _parse(raw)
+
+
+def catalog() -> Mapping[str, str]:
+    if not _catalog:
+        _catalog.update(_read_packaged())
+    return _catalog
+
+
+def use(source: PathLike | Mapping[str, Any]) -> None:
+    overrides = _flatten(source) if isinstance(source, Mapping) else _parse(Path(source).read_text(encoding="utf-8"))
+    unknown = set(overrides) - set(_read_packaged())
+    if unknown:
+        raise KeyError(", ".join(sorted(unknown)))
+    catalog()
+    _catalog.update(overrides)
+
+
+def reset() -> None:
+    _catalog.clear()
+
+
+def text(key: str, **params: Any) -> str:
+    template = catalog()[key]
+    return template.format(**params) if params else template

binaaz_sdk/messages.yaml

@@ -0,0 +1,62 @@
+settings:
+  description: Settings for the bina.az client. Values come from code, BINAAZ_* environment variables or a config file.
+  cookie: Signed in bina.az session, as a Cookie header value. Empty until you sign in or pass one
+  base_url: bina.az address. The GraphQL endpoint lives under it
+  photos_url: Photo service address
+  login_url: Address of the SMS login service bina.az uses
+  return_to: Page the SMS login service is told to return to
+  endpoints: Path of every call, relative to its service address
+  language: Language sent to the SMS login service
+  timeout: Seconds to wait for an answer
+  connect_timeout: Seconds to wait for a connection
+  max_retries: Extra attempts for calls that are safe to repeat
+  code_attempts: Attempts for an SMS login call whose answer has no known error, the login service drops some answers
+  backoff_base: First wait between retries, in seconds
+  backoff_cap: Longest wait between retries, in seconds
+  user_agent: User-Agent header
+  allow_insecure_http: Allow plain http addresses outside localhost, for a test server on a private network only
+
+value:
+  empty: "{field} cannot be empty"
+  too_long: "{field} is longer than {limit} characters"
+  range: "{field} must be a whole number from {low} to {high}, got {value!r}"
+  choice: "{field} must be one of {choices}, got {value!r}"
+  phone: "{value!r} is not an Azerbaijani mobile number such as 050 123 45 67"
+  id: "{field} must be a bina.az id, got {value!r}"
+  photos: "bina.az takes {low} to {high} photos on a listing, got {count}"
+  photo_file: "photo must be bytes, a file object or a path, got {value!r}"
+  confirm: "{action} costs money. Pass confirm=True to go ahead"
+  cookie: Cookie is empty or not in a known format
+
+error:
+  base_url: "{field} must be an absolute http or https address, got {url}"
+  insecure: "Refusing to send a session over plain http to {url}. Use https, or set allow_insecure_http for a private test server."
+  connect: "Could not reach {host}, nothing was sent: {error}"
+  timeout: "{host} did not answer: {error}"
+  unknown_outcome: "{action} may or may not have gone through ({reason}). Check the account before trying again."
+  body: "{host} sent an answer that is not JSON: {body}"
+  status: "{host} answered with HTTP {status}"
+  blocked: "{host} answered with a Cloudflare challenge page. This client does not solve challenges; the site has to let your address through."
+  session: bina.az did not accept the session. Sign in again
+  no_profile: bina.az returned no profile, the session is not signed in
+  no_cookie: bina.az accepted the sign in but set no session cookie
+  login: "bina.az did not accept the sign in: {detail}"
+  graphql: "bina.az refused the request: {detail}"
+  validation: "bina.az rejected the listing: {detail}"
+  not_company: "Listing management needs a bina.az company profile, this session is a {kind}"
+  not_found: "bina.az item {item_id} was not found for this account"
+  photo_id: bina.az did not return a photo id
+  photo_size: The photo is too large for bina.az
+  code_service: "The SMS login service did not answer after {attempts} attempts ({last}). Try again in a moment."
+  code_limit: "Too many SMS codes or wrong codes for this number. Wait before asking again: {detail}"
+  code_phone: "The SMS login service refused the number: {detail}"
+  code_rejected: "The code was not accepted: {detail}"
+  code_reused: "The code was not accepted: {detail}. It may have been used by an earlier attempt, ask for a new one."
+  no_token: The SMS login service returned no access token
+  status_restricted: bina.az wants the account's phone number confirmed before posting
+  status_unverified: The bina.az account is not verified yet
+  status_invalid: bina.az rejected the listing data
+  status_failure: bina.az could not create the listing
+  status_locked: "The listing is locked on bina.az, for example under moderation{until}"
+  status_forbidden: This bina.az account can not edit the listing
+  status_not_found: The listing was not found on bina.az

binaaz_sdk/models.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+from typing import Any, Mapping, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic.alias_generators import to_camel
+
+from .enums import PHOTOS_MAX, BuildingType, Category, ContactType, ItemState
+
+ORIGIN = "https://bina.az"
+
+
+def _pick(body: Mapping[str, Any], *keys: str) -> Any:
+    for key in keys:
+        value = body.get(key)
+        if value is not None and value != "":
+            return value
+    return None
+
+
+def _str(body: Mapping[str, Any], *keys: str) -> Optional[str]:
+    value = _pick(body, *keys)
+    return None if value is None else str(value)
+
+
+def _int(body: Mapping[str, Any], *keys: str) -> Optional[int]:
+    value = _pick(body, *keys)
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _money(value: Any) -> Optional[Decimal]:
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        result = Decimal(str(value))
+    except (InvalidOperation, ValueError):
+        return None
+    return result if result.is_finite() else None
+
+
+def _when(body: Mapping[str, Any], *keys: str) -> Optional[datetime]:
+    value = _pick(body, *keys)
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _map(value: Any) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _list(value: Any) -> list[Any]:
+    return list(value) if isinstance(value, (list, tuple)) else []
+
+
+def site_url(path: Optional[str], origin: str = ORIGIN) -> Optional[str]:
+    if not path:
+        return None
+    return path if path.startswith("http") else origin.rstrip("/") + path
+
+
+class _Camel(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True, extra="forbid")
+
+
+class Area(_Camel):
+    value: float = Field(gt=0)
+    land: Optional[float] = Field(default=None, gt=0)
+
+
+class Floor(_Camel):
+    value: float
+    total: float = Field(gt=0)
+
+    @model_validator(mode="after")
+    def _check(self) -> Floor:
+        if self.value > self.total:
+            raise ValueError("floor.value cannot exceed floor.total")
+        return self
+
+
+class Location(_Camel):
+    address: str = Field(min_length=1, max_length=500)
+    city_id: str
+    latitude: float = Field(ge=-90, le=90)
+    longitude: float = Field(ge=-180, le=180)
+    region_id: Optional[str] = None
+    township_id: Optional[str] = None
+    landmark_ids: Optional[list[str]] = None
+
+
+class Contact(_Camel):
+    type: ContactType
+    name: Optional[str] = Field(default=None, max_length=100)
+    email: Optional[str] = Field(default=None, max_length=255)
+
+
+class Listing(_Camel):
+    category_id: Category
+    is_leased: bool
+    price: int = Field(gt=0)
+    area: Area
+    location: Location
+    contact: Contact
+    photo_ids: list[str] = Field(default_factory=list, max_length=PHOTOS_MAX)
+    description: Optional[str] = Field(default=None, max_length=5000)
+    rooms: Optional[int] = Field(default=None, ge=1, le=50)
+    floor: Optional[Floor] = None
+    has_repair: Optional[bool] = None
+    has_mortgage: Optional[bool] = None
+    has_bill_of_sale: Optional[bool] = None
+    paid_daily: Optional[bool] = None
+    building_type: Optional[BuildingType] = None
+
+    @model_validator(mode="after")
+    def _check(self) -> Listing:
+        if self.paid_daily and not self.is_leased:
+            raise ValueError("paid_daily needs is_leased=True")
+        if self.building_type and self.category_id != Category.OFFICE:
+            raise ValueError("building_type is only valid for offices (category 7)")
+        return self
+
+    def _dump(self, **kw: Any) -> dict[str, Any]:
+        data = self.model_dump(mode="json", by_alias=True, exclude_none=True, **kw)
+        if "categoryId" in data:
+            data["categoryId"] = str(data["categoryId"])
+        return data
+
+    def to_create_input(self) -> dict[str, Any]:
+        return self._dump()
+
+    def to_update_input(self, item_id: str) -> dict[str, Any]:
+        data = self._dump(exclude={"category_id", "is_leased", "contact", "building_type"})
+        if self.contact.name:
+            data["contactName"] = self.contact.name
+        return {"itemId": str(item_id), **data}
+
+
+@dataclass(frozen=True)
+class Profile:
+    kind: str
+    id: Optional[str] = None
+    name: Optional[str] = None
+    email: Optional[str] = None
+    phone: Optional[str] = None
+    contact_name: Optional[str] = None
+    path: Optional[str] = None
+    agency: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def is_company(self) -> bool:
+        return self.kind == "CompanyProfile"
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Profile:
+        return cls(
+            kind=_str(body, "__typename") or "",
+            id=_str(body, "id"),
+            name=_str(body, "name"),
+            email=_str(body, "email"),
+            phone=_str(body, "phone"),
+            contact_name=_str(body, "contactName"),
+            path=_str(body, "path"),
+            agency=_str(_map(body.get("agency")), "name"),
+            raw=dict(body),
+        )
+
+
+@dataclass(frozen=True)
+class Price:
+    total: Optional[Decimal]
+    currency: str
+
+    @classmethod
+    def from_api(cls, body: Any) -> Optional[Price]:
+        data = _map(body)
+        if not data:
+            return None
+        return cls(_money(data.get("total")), _str(data, "currency") or "AZN")
+
+
+@dataclass(frozen=True)
+class Item:
+    id: str
+    state: ItemState
+    site_state: Optional[str] = None
+    title: Optional[str] = None
+    path: Optional[str] = None
+    url: Optional[str] = None
+    price: Optional[Price] = None
+    expires_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    thumbnail: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Item:
+        photos = [p for p in _list(body.get("photos")) if isinstance(p, Mapping)]
+        return cls(
+            id=_str(body, "id") or "",
+            state=ItemState.from_site(body.get("state")),
+            site_state=_str(body, "state"),
+            title=_str(body, "title"),
+            path=_str(body, "path"),
+            url=site_url(_str(body, "path")),
+            price=Price.from_api(body.get("price")),
+            expires_at=_when(body, "expiresAt"),
+            updated_at=_when(body, "updatedAt"),
+            thumbnail=_str(photos[0], "thumbnail") if photos else None,
+            raw=dict(body),
+        )
+
+
+@dataclass(frozen=True)
+class ItemPage:
+    items: tuple[Item, ...]
+    total: Optional[int]
+    next_cursor: Optional[str]
+
+    @property
+    def has_more(self) -> bool:
+        return self.next_cursor is not None
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> ItemPage:
+        info = _map(body.get("pageInfo"))
+        nodes = tuple(Item.from_api(n) for n in _list(body.get("nodes")) if isinstance(n, Mapping))
+        cursor = _str(info, "endCursor") if info.get("hasNextPage") else None
+        return cls(nodes, _int(body, "totalCount"), cursor)
+
+
+@dataclass(frozen=True)
+class ItemResult:
+    id: Optional[str]
+    state: Optional[ItemState]
+    site_state: Optional[str] = None
+    path: Optional[str] = None
+    url: Optional[str] = None
+    status: Optional[str] = None
+    locked_until: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> ItemResult:
+        item = _map(body.get("item"))
+        site_state = _str(item, "state")
+        return cls(
+            id=_str(item, "id"),
+            state=ItemState.from_site(site_state) if site_state else None,
+            site_state=site_state,
+            path=_str(item, "path"),
+            url=site_url(_str(item, "path")),
+            status=_str(body, "status"),
+            locked_until=_str(body, "lockedUntil"),
+            raw=dict(body),
+        )
+
+
+@dataclass(frozen=True)
+class Photo:
+    id: str
+    thumbnail_url: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Photo:
+        return cls(_str(body, "id") or "", _str(body, "thumbnail_url", "thumbnailUrl", "thumbnail"), dict(body))
+
+
+@dataclass(frozen=True)
+class Place:
+    id: str
+    name: str
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Place:
+        return cls(_str(body, "id") or "", _str(body, "name") or "")
+
+
+@dataclass(frozen=True)
+class CategoryNode:
+    id: str
+    name: str
+    children: tuple[Place, ...] = ()
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> CategoryNode:
+        kids = tuple(Place.from_api(c) for c in _list(body.get("children")) if isinstance(c, Mapping))
+        return cls(_str(body, "id") or "", _str(body, "name") or "", kids)
+
+
+@dataclass(frozen=True)
+class ServiceOption:
+    id: str
+    name: str
+    price: Optional[Decimal]
+    price_with_discount: Optional[Decimal]
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> ServiceOption:
+        return cls(_str(body, "id") or "", _str(body, "name") or "", _money(body.get("price")),
+                   _money(body.get("priceWithDiscount")))
+
+
+@dataclass(frozen=True)
+class PaymentMethod:
+    id: str
+    name: str
+    balance: Optional[Decimal]
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> PaymentMethod:
+        return cls(_str(body, "id") or "", _str(body, "name") or "", _money(body.get("balance")))
+
+
+@dataclass(frozen=True)
+class PaidService:
+    id: str
+    title: str
+    options: tuple[ServiceOption, ...] = ()
+    payment_methods: tuple[PaymentMethod, ...] = ()
+
+    @classmethod
+    def from_api(cls, service: Mapping[str, Any], details: Mapping[str, Any]) -> PaidService:
+        options = tuple(ServiceOption.from_api(o) for o in _list(details.get("paidServiceOptions"))
+                        if isinstance(o, Mapping))
+        methods = tuple(PaymentMethod.from_api(m) for m in _list(details.get("paymentMethods"))
+                        if isinstance(m, Mapping))
+        return cls(_str(service, "id") or "", _str(service, "title") or "", options, methods)
+
+
+@dataclass(frozen=True)
+class Payment:
+    status: Optional[str]
+    redirect_url: Optional[str]
+    payment_id: Optional[str]
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Payment:
+        return cls(_str(body, "status"), _str(body, "redirectUrl"), _str(body, "paymentId"), dict(body))
+
+
+@dataclass(frozen=True)
+class CodeSent:
+    phone: str
+    code_requests_left: Optional[int]
+    retried: bool = False
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def more_than_one_sms(self) -> bool:
+        return self.retried

binaaz_sdk/queries.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+PROFILE = (
+    "query Profile { profile { __typename "
+    "... on CompanyProfile { id name email phone contactName agency { name } } "
+    "... on Business { __typename ... on Agency { id name path } ... on Residence { id name path } } } }"
+)
+
+ITEM_FIELDS = "id title state path expiresAt updatedAt price { total currency } photos { thumbnail }"
+
+ITEM_EDIT = f"query ItemEdit($id: ID!) {{ itemEdit(itemId: $id) {{ item {{ {ITEM_FIELDS} }} }} }}"
+
+MY_ITEMS = (
+    "query MyItems($state: ProfileItemTabStatesEnum, $first: Int, $after: String) { profile { __typename "
+    "... on CompanyProfile { items(state: $state, first: $first, after: $after) { totalCount "
+    f"pageInfo {{ hasNextPage endCursor }} nodes {{ {ITEM_FIELDS} }} }} }} }} }}"
+)
+
+_ERRORS = "errors { code message path }"
+_ITEM_RESULT = f"item {{ id path state }} {_ERRORS}"
+
+CREATE_ITEM = (f"mutation CreateItem($input: ItemCreateInput!) "
+               f"{{ createItem(input: $input) {{ status {_ITEM_RESULT} }} }}")
+UPDATE_ITEM = (f"mutation UpdateItem($input: ItemUpdateInput!) "
+               f"{{ updateItem(input: $input) {{ status lockedUntil {_ITEM_RESULT} }} }}")
+DELETE_ITEM = (f"mutation DeleteItem($input: ItemDeleteInput!) "
+               f"{{ deleteItem(input: $input) {{ item {{ id state }} {_ERRORS} }} }}")
+PROLONG_ITEM = (f"mutation ProlongItem($input: ItemProlongInput!) "
+                f"{{ prolongItem(input: $input) {{ {_ITEM_RESULT} }} }}")
+PAY_FOR_ITEM = (f"mutation PayForItem($input: ItemPayInput!) "
+                f"{{ payForItem(input: $input) {{ item {{ id state }} {_ERRORS} }} }}")
+CREATE_PAYMENT = (f"mutation CreatePayment($input: PaymentCreateInput!) "
+                  f"{{ createPayment(input: $input) {{ status redirectUrl paymentId {_ERRORS} }} }}")
+
+PAID_SERVICES = "query PaidServices($ids: [ID!]!) { paidServices(targetIds: $ids, targetType: ITEM) { id title } }"
+
+PAID_SERVICE_DETAILS = (
+    "query PaidServiceDetails($sid: ID!, $ids: [ID!]!) { "
+    "paidServiceOptions(paidServiceId: $sid, targetIds: $ids) "
+    "{ id name price priceWithDiscount(paymentMethodId: \"wallet\") } "
+    "paymentMethods(paidServiceId: $sid, targetIds: $ids, targetType: ITEM) { id name balance } }"
+)
+
+SIGN_IN = (
+    "mutation SignIn($input: ProfileSignInInput!) { signIn(input: $input) { "
+    "profile { __typename ... on CompanyProfile { id name } } errors { message path } } }"
+)
+
+CATEGORIES = "{ categories { id name children { id name } } }"
+CITIES = "{ cities { id name } }"
+REGIONS = "query($c: ID!) { regions(cityId: $c) { id name } }"
+TOWNSHIPS = "query($r: ID!) { townships(regionId: $r) { id name } }"
+LANDMARKS = ("query($c: ID!, $lat: Float!, $lng: Float!) "
+             "{ landmarks(cityId: $c, latitude: $lat, longitude: $lng) { id name } }")