walla-cli 0.1.0__py3-none-any.whl

walla/core/errors.py

@@ -0,0 +1,90 @@
+"""Shared error classification for CLI and MCP."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from walla.core.exceptions import (
+    WallaAmbiguousError,
+    WallaAuthError,
+    WallaError,
+    WallaForbiddenError,
+    WallaHTTPError,
+    WallaNotFoundError,
+    WallaParseError,
+    WallaRateLimitError,
+    WallaUnsupportedError,
+)
+
+__all__ = (
+    "ErrorClassification",
+    "classify_error",
+)
+
+
+@dataclass(frozen=True)
+class ErrorClassification:
+    error_type: str
+    retryable: bool
+    http_status: int | None = None
+    retry_after_s: float | None = None
+
+    def as_fields(self) -> dict[str, Any]:
+        fields: dict[str, Any] = {
+            "error_type": self.error_type,
+            "retryable": self.retryable,
+        }
+        if self.http_status is not None:
+            fields["http_status"] = self.http_status
+        if self.retry_after_s is not None:
+            fields["retry_after_s"] = self.retry_after_s
+        return fields
+
+
+def classify_error(exc: BaseException) -> ErrorClassification:
+    """Map an exception to a stable ``error_type`` + ``retryable`` pair."""
+    cause = getattr(exc, "last_attempt", None)
+    if cause is not None:
+        try:
+            inner = cause.exception()
+            if inner is not None:
+                return classify_error(inner)
+        except Exception:  # noqa: BLE001
+            pass
+    if isinstance(exc, WallaAmbiguousError):
+        return ErrorClassification("ambiguous", retryable=False)
+    if isinstance(exc, WallaAuthError):
+        return ErrorClassification("auth", retryable=False)
+    if isinstance(exc, WallaUnsupportedError):
+        return ErrorClassification("unsupported", retryable=False)
+    if isinstance(exc, WallaNotFoundError):
+        return ErrorClassification("not_found", retryable=False)
+    if isinstance(exc, WallaParseError):
+        return ErrorClassification("parse_error", retryable=False)
+    if isinstance(exc, WallaRateLimitError):
+        return ErrorClassification(
+            "rate_limited",
+            retryable=True,
+            http_status=exc.status_code,
+            retry_after_s=exc.retry_after_s,
+        )
+    if isinstance(exc, WallaForbiddenError):
+        return ErrorClassification(
+            "forbidden", retryable=False, http_status=exc.status_code
+        )
+    if isinstance(exc, WallaHTTPError):
+        status = getattr(exc, "status_code", None)
+        retryable = status is not None and (status == 429 or status >= 500)
+        return ErrorClassification(
+            "http_error", retryable=retryable, http_status=status
+        )
+    if isinstance(exc, TimeoutError):
+        return ErrorClassification("timeout", retryable=True)
+    if isinstance(exc, ConnectionError | OSError):
+        return ErrorClassification("connection_error", retryable=True)
+    if isinstance(exc, ValueError):
+        return ErrorClassification("validation_error", retryable=False)
+    if isinstance(exc, WallaError):
+        return ErrorClassification("walla_error", retryable=False)
+    return ErrorClassification("unexpected_error", retryable=False)

walla/core/exceptions.py

@@ -0,0 +1,67 @@
+"""Shared walla error types (foundation -- importable by http + core)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = (
+    "WallaAmbiguousError",
+    "WallaAuthError",
+    "WallaError",
+    "WallaForbiddenError",
+    "WallaHTTPError",
+    "WallaNotFoundError",
+    "WallaParseError",
+    "WallaRateLimitError",
+    "WallaUnsupportedError",
+)
+
+
+class WallaError(Exception):
+    """Base."""
+
+
+class WallaHTTPError(WallaError):
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class WallaRateLimitError(WallaHTTPError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 429,
+        retry_after_s: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code)
+        self.retry_after_s = retry_after_s
+
+
+class WallaAuthError(WallaError):
+    """Missing or rejected credentials / session."""
+
+
+class WallaForbiddenError(WallaHTTPError):
+    """Hard stop (403 circuit)."""
+
+
+class WallaParseError(WallaError):
+    pass
+
+
+class WallaNotFoundError(WallaError):
+    pass
+
+
+class WallaUnsupportedError(WallaError):
+    """Wire shape not captured yet."""
+
+
+class WallaAmbiguousError(WallaError):
+    """Multiple listings matched; caller must pick an id."""
+
+    def __init__(self, message: str, *, candidates: list[Any]) -> None:
+        super().__init__(message)
+        self.candidates = candidates

walla/core/human_fix.py

@@ -0,0 +1,26 @@
+"""User-visible fix recipes (not system prompts)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = (
+    "cookie_export_fix",
+)
+
+
+def cookie_export_fix() -> dict[str, Any]:
+    return {
+        "title": "Paste Wallapop session cookie",
+        "steps": [
+            "Log in at https://es.wallapop.com in your browser.",
+            "Copy cookie __Secure-next-auth.session-token (Cookie-Editor).",
+            "Run: walla login",
+            "Paste the cookie value when prompted.",
+            "Agents: walla login --cookie '<value>' --json",
+        ],
+        "say_to_user": (
+            "Run `walla login` and paste your "
+            "__Secure-next-auth.session-token cookie from es.wallapop.com."
+        ),
+    }

walla/core/instruct.py

@@ -0,0 +1,50 @@
+"""Agent recipe returned by ``walla instruct --json``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ("instruct_recipe",)
+
+
+def instruct_recipe() -> dict[str, Any]:
+    return {
+        "name": "walla",
+        "tagline": "look · offer · talk",
+        "example": (
+            "Human: find a used kite near Barcelona under 400eur, message "
+            "seller, offer if GRAB. Agent: walla search -> verdict + item URL "
+            "-> ask confirm -> walla say --yes -> walla offer --eur N --yes "
+            "-> walla inbox."
+        ),
+        "protocol": [
+            "Install: pipx install 'walla-cli[mcp]' (or pipx install -e '.[mcp]' in the clone).",
+            "walla doctor --json - never print tokens or cookies.",
+            "If no session: ask the human to run `walla login` and paste "
+            "__Secure-next-auth.session-token (or pass --cookie for non-interactive).",
+            "Do the ask with walla … --json and narrate in prose.",
+        ],
+        "verbs": {
+            "look": ["walla search <q> --json", "walla item <id> --json"],
+            "talk": [
+                "walla inbox --json",
+                "walla thread <id> --json",
+                "walla say <id> <text> --yes",
+            ],
+            "offer": ["walla offer <id> --eur <n> --yes"],
+        },
+        "rules": [
+            "search / item / inbox are safe reads.",
+            "say and offer require --yes / confirm=true; name listing + euros.",
+            "If only asked to look, do not send.",
+            "Ambiguous match: ask once with candidates.",
+            "Refuse in-person offers outside pickup radius.",
+            "No .env credentials. Login is cookie paste only (optional --password).",
+        ],
+        "envelope": ["ok", "api_version", "data | error / error_type / retryable"],
+        "standards": [
+            "docs/code_quality.md",
+            "docs/data_engineering_standards.md",
+            "docs/WIRE.md",
+        ],
+    }

walla/core/path.py

@@ -0,0 +1,32 @@
+"""Config paths under ``~/.config/walla`` (override ``WALLA_CONFIG_DIR``)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+__all__ = (
+    "config_dir",
+    "profile_path",
+    "session_path",
+    "watches_path",
+)
+
+
+def config_dir() -> Path:
+    override = os.environ.get("WALLA_CONFIG_DIR")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".config" / "walla"
+
+
+def profile_path() -> Path:
+    return config_dir() / "profile.json"
+
+
+def session_path() -> Path:
+    return config_dir() / "session.json"
+
+
+def watches_path() -> Path:
+    return config_dir() / "watches.json"

walla/http/__init__.py

@@ -0,0 +1,14 @@
+"""HTTP package facade."""
+
+from __future__ import annotations
+
+from walla.http.client import HttpClient
+from walla.http.headers import API_BASE, WEB_BASE
+from walla.http.polite import reset_polite
+
+__all__ = (
+    "API_BASE",
+    "WEB_BASE",
+    "HttpClient",
+    "reset_polite",
+)

walla/http/client.py

@@ -0,0 +1,169 @@
+"""curl_cffi HTTP client with politeness and retries."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Literal, cast
+
+from curl_cffi import requests
+from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential
+
+from walla.core.exceptions import (
+    WallaForbiddenError,
+    WallaHTTPError,
+    WallaRateLimitError,
+)
+from walla.http.headers import API_BASE, default_headers
+from walla.http.polite import (
+    cache_get,
+    cache_key,
+    cache_set,
+    check_circuit,
+    trip_circuit,
+    wait_turn,
+)
+
+__all__ = (
+    "HttpClient",
+    "parse_retry_after",
+)
+
+Method = Literal["GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD", "TRACE", "PATCH"]
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def _retryable_http(exc: BaseException) -> bool:
+    if isinstance(exc, WallaForbiddenError):
+        return False
+    if isinstance(exc, WallaRateLimitError):
+        return True
+    if isinstance(exc, WallaHTTPError):
+        code = exc.status_code or 0
+        return code >= 500
+    return False
+
+
+class HttpClient:
+    """Thin Wallapop HTTP shell. No import-time network."""
+
+    def __init__(
+        self,
+        *,
+        access_token: str | None = None,
+        device_id: str | None = None,
+        base: str = API_BASE,
+        cookies: dict[str, str] | None = None,
+    ) -> None:
+        self.base = base.rstrip("/")
+        self.access_token = access_token
+        self.device_id = device_id
+        self.cookies = cookies or {}
+        self._session: Any = requests.Session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+        use_cache: bool = False,
+        auth: bool = False,
+    ) -> Any:
+        check_circuit()
+        params = params or {}
+        key = cache_key(f"{method}:{path}", params)
+        if use_cache and method.upper() == "GET":
+            hit = cache_get(key)
+            if hit is not None:
+                return hit
+        wait_turn()
+        headers = default_headers(device_id=self.device_id)
+        if auth and self.access_token:
+            headers["Authorization"] = f"Bearer {self.access_token}"
+        url = path if path.startswith("http") else f"{self.base}{path}"
+        resp = self._send(method, url, headers=headers, params=params, json_body=json_body)
+        data = self._decode(resp)
+        if use_cache and method.upper() == "GET":
+            cache_set(key, data)
+        return data
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    @retry(
+        retry=retry_if_exception(_retryable_http),
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=0.5, min=0.5, max=8),
+        reraise=True,
+    )
+    def _send(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str],
+        params: dict[str, Any],
+        json_body: dict[str, Any] | None,
+    ) -> Any:
+        resp = self._session.request(
+            cast(Method, method.upper()),
+            url,
+            headers=headers,
+            params=params or None,
+            json=json_body,
+            cookies=self.cookies or None,
+            impersonate="chrome",
+            timeout=30,
+        )
+        if resp.status_code == 429:
+            ra = parse_retry_after(resp.headers.get("Retry-After"))
+            if ra:
+                time.sleep(ra)
+            raise WallaRateLimitError(
+                "Wallapop rate limited (429)",
+                retry_after_s=ra,
+            )
+        if resp.status_code == 403:
+            trip_circuit()
+            raise WallaForbiddenError(
+                "Wallapop Forbidden (403) -- circuit open",
+                status_code=403,
+            )
+        if resp.status_code >= 500:
+            raise WallaHTTPError(
+                f"Wallapop server error {resp.status_code}",
+                status_code=resp.status_code,
+            )
+        return resp
+
+    def _decode(self, resp: Any) -> Any:
+        if resp.status_code in (200, 201, 204):
+            if not resp.content:
+                return {}
+            try:
+                return cast(Any, resp.json())
+            except Exception as exc:
+                raise WallaHTTPError(
+                    f"Invalid JSON ({resp.status_code})",
+                    status_code=resp.status_code,
+                ) from exc
+        body = (resp.text or "")[:300]
+        raise WallaHTTPError(
+            f"HTTP {resp.status_code}: {body}",
+            status_code=resp.status_code,
+        )

walla/http/headers.py

@@ -0,0 +1,36 @@
+"""Default browser-like headers for api.wallapop.com."""
+
+from __future__ import annotations
+
+import uuid
+
+__all__ = (
+    "API_BASE",
+    "WEB_BASE",
+    "default_headers",
+    "new_device_id",
+)
+
+API_BASE = "https://api.wallapop.com"
+WEB_BASE = "https://es.wallapop.com"
+
+
+def new_device_id() -> str:
+    return str(uuid.uuid4())
+
+
+def default_headers(*, device_id: str | None = None) -> dict[str, str]:
+    did = device_id or new_device_id()
+    return {
+        "Accept": "application/json",
+        "User-Agent": (
+            "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+            "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+        ),
+        "Origin": WEB_BASE,
+        "Referer": f"{WEB_BASE}/",
+        "X-DeviceOS": "0",
+        "DeviceOS": "0",
+        "X-DeviceID": did,
+        "DeviceID": did,
+    }

walla/http/polite.py

@@ -0,0 +1,108 @@
+"""Process-wide Wallapop politeness: spacing, short TTL cache, ban circuit."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import threading
+import time
+from typing import Any
+
+from walla.core.exceptions import WallaForbiddenError
+
+__all__ = (
+    "CACHE_MAX",
+    "CACHE_TTL",
+    "CIRCUIT_TTL",
+    "MIN_INTERVAL",
+    "cache_get",
+    "cache_key",
+    "cache_set",
+    "check_circuit",
+    "reset_polite",
+    "trip_circuit",
+    "wait_turn",
+)
+
+MIN_INTERVAL = float(os.environ.get("WALLA_MIN_INTERVAL", "1.0"))
+CACHE_TTL = float(os.environ.get("WALLA_CACHE_TTL", "60"))
+CIRCUIT_TTL = float(os.environ.get("WALLA_CIRCUIT_TTL", "3600"))
+CACHE_MAX = int(os.environ.get("WALLA_CACHE_MAX", "256"))
+
+_lock = threading.Lock()
+_last_request_at = 0.0
+_circuit_open_until = 0.0
+_cache: dict[str, tuple[float, Any]] = {}
+
+
+def reset_polite() -> None:
+    """Clear spacing / cache / circuit (tests)."""
+    global _last_request_at, _circuit_open_until, _cache
+    with _lock:
+        _last_request_at = 0.0
+        _circuit_open_until = 0.0
+        _cache = {}
+
+
+def cache_key(base: str, params: dict[str, Any]) -> str:
+    payload = json.dumps({"base": base, "params": params}, sort_keys=True, default=str)
+    return hashlib.sha256(payload.encode()).hexdigest()
+
+
+def cache_get(key: str) -> Any | None:
+    now = time.monotonic()
+    with _lock:
+        hit = _cache.get(key)
+        if hit is None:
+            return None
+        expires, value = hit
+        if expires <= now:
+            del _cache[key]
+            return None
+        return value
+
+
+def cache_set(key: str, value: Any, *, ttl: float | None = None) -> None:
+    life = CACHE_TTL if ttl is None else ttl
+    with _lock:
+        if len(_cache) >= CACHE_MAX:
+            now = time.monotonic()
+            expired = [k for k, (exp, _) in _cache.items() if exp <= now]
+            for k in expired:
+                del _cache[k]
+            while len(_cache) >= CACHE_MAX:
+                _cache.pop(next(iter(_cache)))
+        _cache[key] = (time.monotonic() + life, value)
+
+
+def check_circuit() -> None:
+    with _lock:
+        open_until = _circuit_open_until
+    if open_until and time.monotonic() < open_until:
+        raise WallaForbiddenError(
+            "Wallapop Forbidden circuit open -- stop requests. "
+            "Wait for WALLA_CIRCUIT_TTL or reset_polite().",
+            status_code=403,
+        )
+
+
+def trip_circuit(*, ttl: float | None = None) -> None:
+    life = CIRCUIT_TTL if ttl is None else ttl
+    global _circuit_open_until
+    with _lock:
+        _circuit_open_until = time.monotonic() + max(life, 0.0)
+
+
+def wait_turn(*, min_interval: float | None = None) -> None:
+    """Serialize dials with a minimum gap (sleep outside the lock)."""
+    gap = MIN_INTERVAL if min_interval is None else min_interval
+    global _last_request_at
+    while True:
+        with _lock:
+            now = time.monotonic()
+            delay = (_last_request_at + gap) - now
+            if delay <= 0:
+                _last_request_at = now
+                return
+        time.sleep(delay)

walla/hunter/__init__.py

@@ -0,0 +1,18 @@
+"""Hunter package facade."""
+
+from __future__ import annotations
+
+from walla.hunter.profile_store import load_profile, parse_intake, save_profile
+from walla.hunter.verdict import score_listing
+from walla.hunter.watches import Watch, diff_new_ids, load_watches, save_watches
+
+__all__ = (
+    "Watch",
+    "diff_new_ids",
+    "load_profile",
+    "load_watches",
+    "parse_intake",
+    "save_profile",
+    "save_watches",
+    "score_listing",
+)

walla/hunter/profile_store.py

@@ -0,0 +1,56 @@
+"""Profile store on disk."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from walla.core.path import profile_path
+from walla.models.profile import Profile
+
+__all__ = (
+    "load_profile",
+    "parse_intake",
+    "save_profile",
+)
+
+
+def load_profile(path: Path | None = None) -> Profile:
+    p = path or profile_path()
+    if not p.is_file():
+        return Profile()
+    data = json.loads(p.read_text(encoding="utf-8"))
+    return Profile.model_validate(data)
+
+
+def save_profile(profile: Profile, path: Path | None = None) -> Path:
+    p = path or profile_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(profile.model_dump_json(indent=2), encoding="utf-8")
+    return p
+
+
+def parse_intake(text: str) -> Profile:
+    """Parse ``key=value`` intake line into a Profile."""
+    fields: dict[str, str] = {}
+    for part in text.replace(",", " ").split():
+        if "=" not in part:
+            continue
+        k, _, v = part.partition("=")
+        fields[k.strip().lower()] = v.strip()
+    profile = load_profile()
+    if "lat" in fields:
+        profile.lat = float(fields["lat"])
+    if "lon" in fields:
+        profile.lon = float(fields["lon"])
+    if "km" in fields:
+        profile.km = float(fields["km"])
+    if "pickup_km" in fields:
+        profile.pickup_km = float(fields["pickup_km"])
+    if "label" in fields:
+        profile.label = fields["label"]
+    if "budget" in fields:
+        profile.budget = float(fields["budget"])
+    if "max_price" in fields:
+        profile.max_price = float(fields["max_price"])
+    return profile