vinted-api-kit 0.1.0__py3-none-any.whl

vinted_api_kit/__init__.py

@@ -0,0 +1,6 @@
+__version__ = "0.1.0"
+
+from .models import CatalogItem, DetailedItem
+from .vinted_api import VintedApi
+
+__all__ = ["VintedApi", "CatalogItem", "DetailedItem"]

vinted_api_kit/client/user_agents.py

@@ -0,0 +1,25 @@
+import random
+
+USER_AGENTS = [
+    # Windows 10/11 CHROME
+    # 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36',
+    # Edge
+    # 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36 Edg/138.0.3351.95',
+    # Firefox Win10
+    # 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0',
+    # MacOS CHROME
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
+    # Safari MacOS
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.4 Safari/605.1.15",
+    # Firefox MacOS
+    # 'Mozilla/5.0 (Macintosh; Intel Mac OS X 15.5; rv:140.0) Gecko/20100101 Firefox/140.0',
+    # Linux CHROME
+    # 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36',
+]
+
+
+def get_random_user_agent() -> str:
+    """
+    Return a random user agent string from predefined list.
+    """
+    return random.choice(USER_AGENTS)

vinted_api_kit/client/vinted_http_client.py

@@ -0,0 +1,353 @@
+import logging
+import pickle
+from pathlib import Path
+from typing import Any, Optional, cast
+from urllib.parse import urlparse
+
+import curl_cffi
+from curl_cffi import AsyncSession
+from curl_cffi.requests import Response
+from curl_cffi.requests.exceptions import HTTPError
+
+from vinted_api_kit.client.user_agents import get_random_user_agent
+from vinted_api_kit.utils import format_proxy_for_log
+
+logger = logging.getLogger(__name__)
+
+HTTP_STATUS_UNAUTHORIZED = 401
+HTTP_STATUS_FORBIDDEN = 403
+
+
+class VintedHttpClient:
+    """
+    Asynchronous HTTP client for Vinted API.
+
+    Manages sessions, headers, proxies, cookies persistence and handles authentication.
+    """
+
+    def __init__(
+        self,
+        locale: Optional[str] = None,
+        proxies: Optional[dict[str, str]] = None,
+        client_ip: Optional[str] = None,
+        cookies_dir: Optional[Path] = None,
+        persist_cookies: bool = True,
+    ):
+        """
+        Initialize the HTTP client with optional locale, proxies, client IP and cookie handling.
+
+        Args:
+            locale (Optional[str]): Locale code (e.g. 'fr', 'de').
+            proxies (Optional[dict]): Proxy settings.
+            client_ip (Optional[str]): Client IP for headers.
+            cookies_dir (Optional[Path]): Directory to store cookies.
+            persist_cookies (bool): Whether to save/load cookies from disk.
+        """
+        self.locale = locale
+        self.proxies = proxies
+        self.client_ip = client_ip
+        self.base_url: Optional[str] = None
+        self.session: AsyncSession = curl_cffi.AsyncSession()
+        self.cookies_dir = cookies_dir or Path(".")
+        self.cookies_dir.mkdir(parents=True, exist_ok=True)
+        self.cookies_path = self._generate_cookies_path()
+        self.persist_cookies = persist_cookies
+        logger.debug(
+            "Initializing VintedHttpClient with locale=%s, proxy=%s, client_ip=%s, cookies_path=%s, persist_cookies=%s",
+            locale,
+            format_proxy_for_log(proxies),
+            client_ip,
+            self.cookies_path,
+            persist_cookies,
+        )
+        self._init_default_headers()
+        if proxies:
+            self.session.proxies.update(proxies)  # type: ignore[typeddict-item]
+            ip = proxies.get("http", "").split("@")[-1].split(":")[0]
+            self._set_x_forwarded_for(ip)
+        elif client_ip:
+            self._set_x_forwarded_for(client_ip)
+
+    def _generate_cookies_path(self) -> Path:
+        """
+        Generate file path for cookie storage based on proxies or client IP.
+
+        Returns:
+            Path object representing cookies file location.
+        """
+        if self.proxies:
+            proxy_str = self.proxies.get("http") or self.proxies.get("https")
+            if proxy_str:
+                proxy_uri = urlparse(proxy_str)
+                ip = proxy_uri.hostname or "unknown"
+                port = proxy_uri.port or 0
+                filename = f"cookies_{ip}_{port}.pk"
+                return self.cookies_dir / filename
+        if self.client_ip:
+            ip_safe = self.client_ip.replace(":", "_")
+            filename = f"cookies_{ip_safe}.pk"
+            return self.cookies_dir / filename
+        return self.cookies_dir / "cookies.pk"
+
+    def _init_default_headers(self):
+        """
+        Set default HTTP headers for all requests.
+        """
+        self.session.headers.update(
+            {
+                "User-Agent": get_random_user_agent(),
+                "Accept": "application/json, text/plain, */*",
+                "Accept-Encoding": "gzip, deflate, br, zstd",
+                "cache-control": "max-age=0",
+                "DNT": "1",
+                "Referer": "",
+                "Sec-CH-UA": '"Not)A;Brand";v="8", "Chromium";v="138", "Google Chrome";v="138"',
+                "Sec-CH-UA-Mobile": "?0",
+                "Sec-CH-UA-Platform": '"macOS"',
+                "Sec-Fetch-Dest": "empty",
+                "Sec-Fetch-Mode": "cors",
+                "Sec-Fetch-Site": "same-origin",
+                "X-Money-Object": "true",
+            }
+        )
+        logger.debug("Default headers set: %s", self.session.headers)
+
+    def _set_x_forwarded_for(self, ip) -> None:
+        """
+        Set 'X-Forwarded-For' HTTP header to the specified IP.
+        """
+        self.session.headers.update({"X-Forwarded-For": ip})
+
+    def configure_from_url(self, url: str) -> None:
+        """
+        Configure base URL and locale based on provided URL.
+
+        Args:
+            url (str): URL string to parse.
+        """
+        parsed_url = urlparse(url)
+        self.base_url = f"https://{parsed_url.netloc}"
+        if not self.locale:
+            domain_parts = parsed_url.netloc.split(".")
+            if len(domain_parts) > 1:
+                self.locale = domain_parts[-1]
+        self.session.headers.update({"Referer": self.base_url})
+        logger.debug(
+            "Configured client from URL: base_url=%s, locale=%s, referer header updated",
+            self.base_url,
+            self.locale,
+        )
+
+    def save_cookies(self) -> None:
+        """
+        Persist session cookies to disk if enabled.
+        """
+        if not self.persist_cookies:
+            logger.debug("Persist cookies disabled, skipping save")
+            return
+        try:
+            with self.cookies_path.open("wb") as f:
+                cookies_jar = cast(Any, self.session.cookies.jar)
+                pickle.dump(cookies_jar._cookies, f)  # noqa
+                logger.debug("Cookies saved successfully to %s", self.cookies_path)
+        except Exception as e:
+            logger.error("Failed to save cookies: %s", e, exc_info=True)
+
+    def load_cookies(self) -> Optional[dict]:
+        """
+        Load cookies from disk if available.
+
+        Returns:
+            Cookies dictionary or None if not exist/disabled.
+        """
+        if not self.persist_cookies:
+            logger.debug("Persist cookies disabled, skipping load")
+            return None
+        if not self.cookies_path.is_file():
+            logger.debug("Cookies file does not exist: %s", self.cookies_path)
+            return None
+        try:
+            with self.cookies_path.open("rb") as f:
+                cookies = pickle.load(f)
+            if not isinstance(cookies, dict):
+                logger.warning(
+                    "Cookies loaded but invalid format: expected dict, got %s", type(cookies)
+                )
+                return None
+            logger.debug("Cookies loaded successfully from %s", self.cookies_path)
+            return cookies
+        except Exception as e:
+            logger.error("Failed to load cookies: %s", e, exc_info=True)
+            return None
+
+    async def refresh_session_cookies(self) -> None:
+        """
+        Get fresh session cookies by visiting the site as a first-time user.
+
+        This method:
+        1. Clears all existing cookies
+        2. Makes a GET request to the base URL
+        3. Saves new cookies received from the server
+
+        Raises:
+            ValueError: If base_url is not configured
+            HTTPError: If the refresh request fails
+        """
+        if not self.base_url:
+            raise ValueError("base_url is not configured")
+
+        logger.info("Getting fresh cookies as first-time visitor...")
+
+        self.clear_all_cookies()
+
+        response = await self.session.get(self.base_url, impersonate="chrome", verify=False)
+        response.raise_for_status()
+
+        logger.debug("Fresh cookies received: %s", len(self.session.cookies))
+        logger.debug(
+            "New cookies: %s", [f"{k}={str(v)[:20]}..." for k, v in self.session.cookies.items()]
+        )
+
+        self.save_cookies()
+        logger.info("Fresh session cookies obtained successfully")
+
+    def clear_all_cookies(self) -> None:
+        """
+        Clear all cookies from session and delete cookies file.
+
+        This method is called when we need to start fresh, typically
+        when authentication fails or tokens are expired.
+        """
+        self.session.cookies.clear()
+
+        if self.cookies_path.exists():
+            try:
+                self.cookies_path.unlink()
+                logger.debug("Cookies file deleted: %s", self.cookies_path)
+            except Exception as e:
+                logger.error("Failed to delete cookies file: %s", e)
+
+        logger.info("All cookies cleared")
+
+    @staticmethod
+    def _is_token_expired(access_token: str) -> bool:
+        """Check if JWT access token is expired."""
+        try:
+            import base64
+            import json
+            from datetime import datetime
+
+            payload_b64: str = access_token.split(".")[1]
+            payload_b64 += "=" * (4 - len(payload_b64) % 4)
+            payload = json.loads(base64.b64decode(payload_b64))
+
+            exp_timestamp = payload.get("exp", 0)
+            current_timestamp = datetime.now().timestamp()
+            result: bool = current_timestamp >= exp_timestamp
+
+            return result
+        except Exception:
+            return True
+
+    def _update_auth_headers_from_cookies(self) -> None:
+        """
+        Update authentication and related headers from stored cookies.
+        """
+        cookies = self.session.cookies
+        access_token_web = cookies.get("access_token_web")
+        csrf_token = cookies.get("x-csrf-token")
+        anon_id = cookies.get("anon_id")
+        accept_language = cookies.get("anonymous-locale")
+
+        logger.debug(
+            "Current session cookies: %s",
+            [f"{k}={v[:20]}..." if len(str(v)) > 20 else f"{k}={v}" for k, v in cookies.items()],
+        )
+
+        if csrf_token:
+            self.session.headers.update({"X-Csrf-Token": csrf_token})
+        if access_token_web:
+            self.session.headers.update({"Authorization": f"Bearer {access_token_web}"})
+        if anon_id:
+            self.session.headers.update({"X-Anon-Id": anon_id})
+        if accept_language:
+            self.session.headers.update({"Accept-Language": accept_language})
+        logger.debug(
+            "Authentication headers updated from cookies: csrf_token=%s, access_token_web=%s, anon_id=%s, accept_language=%s",
+            bool(csrf_token),
+            bool(access_token_web),
+            bool(anon_id),
+            bool(accept_language),
+        )
+
+    async def request(
+        self,
+        url: str,
+        params: Optional[dict] = None,
+    ) -> Response:
+        """
+        Perform an async GET request with cookie and auth management.
+
+        Args:
+            url (str): URL for the HTTP GET.
+            params (Optional[dict]): Query parameters.
+
+        Returns:
+            Response object.
+
+        Raises:
+            HTTPError: If response code >= 400.
+        """
+
+        loaded_cookies = self.load_cookies()
+        if loaded_cookies:
+            cookies_jar = cast(Any, self.session.cookies.jar)
+            cookies_jar._cookies.update(loaded_cookies)  # noqa
+            logger.debug("Initial cookies loaded and applied")
+
+            # Checking token expiration
+            access_token = self.session.cookies.get("access_token_web")
+            if access_token and self._is_token_expired(access_token):
+                logger.info("Access token expired, getting fresh cookies")
+                await self.refresh_session_cookies()
+        else:
+            logger.debug("No saved cookies found, refreshing...")
+            await self.refresh_session_cookies()
+
+        self._update_auth_headers_from_cookies()
+
+        response: Response = await self.session.get(
+            url=url,
+            params=params,
+            impersonate="chrome",
+            verify=False,
+        )
+        logger.debug("First request status: %s", response.status_code)
+
+        if response.status_code in (HTTP_STATUS_UNAUTHORIZED, HTTP_STATUS_FORBIDDEN):
+            logger.warning("Auth failed, getting completely fresh cookies...")
+            await self.refresh_session_cookies()
+            self._update_auth_headers_from_cookies()
+
+            response = await self.session.get(
+                url=url,
+                params=params,
+                impersonate="chrome",
+                verify=False,
+            )
+            logger.debug("Retry request status: %s", response.status_code)
+
+        if response.status_code >= 400:
+            raise HTTPError(
+                f"HTTP Error {response.status_code}: {response.reason}",
+                code=response.status_code,  # type: ignore[arg-type]
+                response=response,
+            )
+
+        return response
+
+    async def close(self):
+        """
+        Close the underlying HTTP session.
+        """
+        await self.session.close()

vinted_api_kit/models/__init__.py

@@ -0,0 +1,4 @@
+from .catalog_item import CatalogItem
+from .detailed_item import DetailedItem
+
+__all__ = ["CatalogItem", "DetailedItem"]

vinted_api_kit/models/catalog_item.py

@@ -0,0 +1,102 @@
+from datetime import datetime, timezone
+
+
+class CatalogItem:
+    """
+    Catalog item representation used in search results.
+
+    Attributes
+    ----------
+    raw_data : dict
+        Raw data dictionary from the API.
+    id : int
+        Unique item ID.
+    title : str
+        Item title.
+    brand_title : str
+        Brand name.
+    size_title : str
+        Size label.
+    currency : str
+        Currency code.
+    price : float
+        Item price amount.
+    photo : str
+        URL of the main photo.
+    url : str
+        Item URL on Vinted.
+    created_at_ts : datetime
+        Item creation datetime (UTC).
+    raw_timestamp : int
+        Raw timestamp from photo metadata.
+    """
+
+    def __init__(self, data):
+        """
+        Initialize CatalogItem from API data.
+
+        Parameters
+        ----------
+        data : dict
+            Raw catalog item data.
+        """
+        self.raw_data = data
+        self.id = data.get("id")
+        self.title = data.get("title")
+        self.brand_title = data.get("brand_title")
+        self.size_title = data.get("size_title")
+        price = data.get("price") or {}
+        self.currency = price.get("currency_code")
+        self.price = price.get("amount")
+        photo = data.get("photo") or {}
+        self.photo = photo.get("url")
+        self.url = data.get("url")
+        self.created_at_ts = self._get_created_at_ts(data)
+        high_res = photo.get("high_resolution") or {}
+        self.raw_timestamp = high_res.get("timestamp")
+
+    @staticmethod
+    def _get_created_at_ts(data: dict) -> datetime:
+        """
+        Parse creation timestamp from photo metadata.
+
+        Parameters
+        ----------
+        data : dict
+            Item data with photo details.
+
+        Returns
+        -------
+        datetime
+            UTC creation datetime or current time if unavailable.
+        """
+        photo = data.get("photo") or {}
+        high_res = photo.get("high_resolution") or {}
+        timestamp = high_res.get("timestamp", 0)
+
+        return datetime.fromtimestamp(timestamp, tz=timezone.utc)
+
+    def __eq__(self, other):
+        """Items are equal if IDs match."""
+        return self.id == other.id
+
+    def __hash__(self):
+        """Hash based on unique ID."""
+        return hash(("id", self.id))
+
+    def is_new_item(self, minutes=1):
+        """
+        Determine if the item is new within a time threshold.
+
+        Parameters
+        ----------
+        minutes : int
+            Time window in minutes to consider item as new.
+
+        Returns
+        -------
+        bool
+            True if item created within `minutes` from now.
+        """
+        delta = datetime.now(timezone.utc) - self.created_at_ts
+        return delta.total_seconds() < minutes * 60

vinted_api_kit/models/detailed_item.py

@@ -0,0 +1,140 @@
+from datetime import datetime, timezone
+
+
+class DetailedItem:
+    """
+    Detailed representation of a Vinted item with extended information.
+
+    Attributes
+    ----------
+    raw_data : dict
+        Original raw data dictionary from API.
+    id : int
+        Unique identifier of the item.
+    title : str
+        Item title.
+    description : str
+        Item description text.
+    brand_title : str
+        Brand name.
+    brand_slug : str
+        Brand slug (URL-friendly).
+    size_title : str
+        Size label extracted from item attributes.
+    currency : str
+        Currency code of the price.
+    price : float
+        Price amount.
+    total_item_price : float
+        Total price including fees or adjustments.
+    photo : str
+        URL of the first photo.
+    url : str
+        URL to the item on Vinted.
+    created_at_ts : datetime
+        Creation date/time of the item (UTC).
+    raw_timestamp : int
+        Raw timestamp from the high resolution photo metadata.
+    """
+
+    def __init__(self, data: dict):
+        """
+        Initialize DetailedItem from raw data dictionary.
+
+        Parameters
+        ----------
+        data : dict
+            Raw response data from Vinted API.
+        """
+        self.raw_data = data
+        self.id = data.get("id")
+        self.title = data.get("title")
+        self.description = data.get("description")
+        brand_dto = data.get("brand_dto") or {}
+        self.brand_title = brand_dto.get("title")
+        self.brand_slug = brand_dto.get("slug")
+        self.size_title = self._get_size_title(data)
+        price_data = data.get("price") or {}
+        self.currency = price_data.get("currency_code")
+        self.price = price_data.get("amount")
+        total_item_price_data = data.get("total_item_price") or {}
+        self.total_item_price = total_item_price_data.get("amount")
+        self.photo = self._get_first_photo_url(data)
+        self.url = data.get("url")
+        self.created_at_ts = self._get_created_at_ts(data)
+        photos = data.get("photos") or []
+        if photos and photos[0] and isinstance(photos[0], dict):
+            self.raw_timestamp = (photos[0].get("high_resolution") or {}).get("timestamp")
+        else:
+            self.raw_timestamp = None
+
+    @staticmethod
+    def _get_size_title(data: dict) -> str:
+        """
+        Extracts the size title from plugins attributes.
+
+        Parameters
+        ----------
+        data : dict
+            Raw item data containing plugins info.
+
+        Returns
+        -------
+        str
+            Size label or empty string if not found.
+        """
+        for plugin in data.get("plugins", []):
+            if plugin.get("name") == "attributes":
+                for attr in plugin.get("data", {}).get("attributes", []):
+                    if attr.get("code") == "size":
+                        val = attr.get("data", {}).get("value", "")
+                        return str(val) if val is not None else ""
+        return ""
+
+    @staticmethod
+    def _get_first_photo_url(data: dict) -> str:
+        """
+        Retrieves URL of the first photo of the item.
+
+        Parameters
+        ----------
+        data : dict
+            Raw item data.
+
+        Returns
+        -------
+        str
+            URL string or empty if missing.
+        """
+        photos = data.get("photos", [])
+        return photos[0].get("url", "") if photos else ""
+
+    @staticmethod
+    def _get_created_at_ts(data: dict) -> datetime:
+        """
+        Parses the creation timestamp from photo metadata.
+
+        Parameters
+        ----------
+        data : dict
+            Item data containing photos info.
+
+        Returns
+        -------
+        datetime
+            UTC datetime of creation or current time if missing.
+        """
+        timestamp = data.get("photos", [{}])[0].get("high_resolution", {}).get("timestamp", 0)
+        return (
+            datetime.fromtimestamp(timestamp, tz=timezone.utc)
+            if timestamp
+            else datetime.now(tz=timezone.utc)
+        )
+
+    def __eq__(self, other):
+        """Compare equality by item ID."""
+        return self.id == other.id
+
+    def __hash__(self):
+        """Hash by item ID."""
+        return hash(("id", self.id))

vinted_api_kit/services/item_service.py

@@ -0,0 +1,230 @@
+import logging
+import time
+from typing import Optional, Union
+from urllib.parse import parse_qsl, urlparse
+
+from curl_cffi.requests.exceptions import HTTPError
+
+from vinted_api_kit.client.vinted_http_client import VintedHttpClient
+from vinted_api_kit.models import CatalogItem, DetailedItem
+
+logger = logging.getLogger(__name__)
+
+
+class ItemService:
+    """
+    Provides item-related operations using the VintedHttpClient.
+    """
+
+    VALID_ORDERS = {"newest_first", "relevance", "price_high_to_low", "price_low_to_high"}
+
+    def __init__(self, client: VintedHttpClient):
+        """
+        Initialize service with HTTP client.
+
+        Args:
+            client (VintedHttpClient): HTTP client instance.
+        """
+        self.client = client
+
+    async def search_items(
+        self,
+        url: str,
+        per_page: int = 20,
+        page: int = 1,
+        timestamp: Optional[int] = None,
+        raw_data: bool = False,
+        order: Optional[str] = None,
+    ) -> Union[list[CatalogItem], list[dict], None]:
+        """
+        Search items on Vinted.
+
+        Args:
+            url (str): URL with search filters.
+            per_page (int): Items per page.
+            page (int): Page number.
+            timestamp (Optional[int]): Unix timestamp override.
+            raw_data (bool): Return raw JSON data if True.
+            order (str): Sorting order.
+
+        Returns:
+            List of CatalogItem or raw data list.
+        """
+        logger.debug(
+            "Searching items with url=%s, per_page=%d, page=%d, timestamp=%s, raw_data=%s, order=%s",
+            url,
+            per_page,
+            page,
+            timestamp,
+            raw_data,
+            order,
+        )
+        if order and order not in self.VALID_ORDERS:
+            logger.error(
+                "Invalid order parameter '%s'. Valid options: %s",
+                order,
+                ", ".join(self.VALID_ORDERS),
+            )
+            raise ValueError(
+                f"Invalid order '{order}'. Valid options are: {', '.join(self.VALID_ORDERS)}"
+            )
+        try:
+            self.client.configure_from_url(url)
+            api_url = f"{self.client.base_url}/api/v2/catalog/items"
+            params = self._parse_url(url, per_page=per_page, page=page)
+            params["time"] = timestamp or int(time.time())
+            if order:
+                params["order"] = order
+            logger.debug("Calling client.request with url=%s and params=%s", api_url, params)
+            response = await self.client.request(api_url, params=params)
+            data = response.json()
+            items = data.get("items", [])
+            logger.debug("Received %d items from API", len(items) if items else 0)
+
+            if raw_data:
+                from typing import Any, cast
+
+                return cast(list[dict[str, Any]], items)
+            return [CatalogItem(item) for item in items] if items else []
+        except Exception:
+            raise
+
+    async def item_details(self, url: str, raw_data: bool = False) -> Union[DetailedItem, dict]:
+        """
+        Get detailed info of an item by URL.
+
+        Args:
+            url (str): Item URL.
+            raw_data (bool): Return raw JSON if True.
+
+        Returns:
+            DetailedItem instance or raw dict.
+        """
+        logger.debug("Fetching item details for url=%s, raw_data=%s", url, raw_data)
+        try:
+            self.client.configure_from_url(url)
+            product_id = urlparse(url).path.split("/")[2].split("-")[0]
+            api_url = f"{self.client.base_url}/api/v2/items/{product_id}/details"
+            logger.debug("Requesting item details from %s", api_url)
+
+            response = await self.client.request(api_url)
+            response.raise_for_status()
+            data = response.json()
+            product_data = data.get("item", [])
+            logger.debug("Item details fetched successfully")
+
+            return DetailedItem(product_data) if not raw_data else product_data
+        except HTTPError as err:
+            raise err
+        except Exception:
+            raise
+
+    def _parse_url(self, url: str, per_page: int = 20, page: int = 1) -> dict:
+        """
+        Parse and build API query parameters from URL.
+
+        Args:
+            url (str): URL to parse.
+            per_page (int): Items per page.
+            page (int): Page number.
+
+        Returns:
+            Dict with query parameters.
+        """
+        parsed_url = urlparse(url)
+        query_params = parse_qsl(parsed_url.query)
+
+        catalog_id = self._extract_catalog_id(parsed_url.path)
+        catalog_ids_from_query = self._join_query_values(query_params, "catalog[]")
+
+        params = {
+            "search_text": "+".join(self._extract_query_values(query_params, "search_text")),
+            "catalog_ids": str(catalog_id) if catalog_id is not None else catalog_ids_from_query,
+            "color_ids": self._join_query_values(query_params, "color_ids[]"),
+            "brand_ids": self._join_query_values(query_params, "brand_ids[]"),
+            "size_ids": self._join_query_values(query_params, "size_ids[]"),
+            "material_ids": self._join_query_values(query_params, "material_ids[]"),
+            "status_ids": self._join_query_values(query_params, "status[]"),
+            "country_ids": self._join_query_values(query_params, "country_ids[]"),
+            "city_ids": self._join_query_values(query_params, "city_ids[]"),
+            "is_for_swap": ",".join(
+                "1" for _ in self._extract_query_values(query_params, "disposal[]")
+            ),
+            "currency": self._join_query_values(query_params, "currency"),
+            "price_to": self._join_query_values(query_params, "price_to"),
+            "price_from": self._join_query_values(query_params, "price_from"),
+            "page": page,
+            "per_page": per_page,
+            "order": self._join_query_values(query_params, "order"),
+            "time": int(time.time()),
+        }
+
+        params_cleaned = {k: v for k, v in params.items() if v}
+        return params_cleaned
+
+    @staticmethod
+    def _extract_catalog_id(path: str) -> Optional[int]:
+        """
+        Extract catalog ID from URL path.
+
+        Args:
+            path (str): URL path string.
+
+        Returns:
+            Catalog ID as int or None if missing.
+        """
+        path_parts = path.split("/")
+        if len(path_parts) > 2 and path_parts[1] == "catalog":
+            catalog_part = path_parts[2]
+            catalog_id_str = catalog_part.split("-")[0] if "-" in catalog_part else catalog_part
+            try:
+                return int(catalog_id_str)
+            except ValueError:
+                logger.debug("Failed to convert catalog id to int from path: %s", path)
+                return None
+        return None
+
+    @staticmethod
+    def _extract_product_id_from_url(url: str) -> str:
+        """
+        Extract product ID from item URL.
+
+        Args:
+            url (str): Item URL string.
+
+        Returns:
+            Product ID string.
+        """
+        path = urlparse(url).path
+        return path.split("/")[2].split("-")[0]
+
+    @staticmethod
+    def _extract_query_values(query_params: list[tuple[str, str]], key: str) -> list[str]:
+        """
+        Get all values for a query key.
+
+        Args:
+            query_params (list of tuple): Parsed query pairs.
+            key (str): Key to find.
+
+        Returns:
+            List of values as strings.
+        """
+        return [v for k, v in query_params if k == key]
+
+    def _join_query_values(
+        self, query_params: list[tuple[str, str]], key: str, sep: str = ","
+    ) -> str:
+        """
+        Join multiple query values for a key into a string.
+
+        Args:
+            query_params (list of tuple): Parsed queries.
+            key (str): Key to find.
+            sep (str): Separator to join strings.
+
+        Returns:
+            Joined string or empty string if none.
+        """
+        values = self._extract_query_values(query_params, key)
+        return sep.join(values)

vinted_api_kit/utils.py

@@ -0,0 +1,22 @@
+from typing import Optional
+
+
+def format_proxy_for_log(proxy: Optional[dict[str, str]]) -> str:
+    """
+    Format proxy address for logging.
+
+    Args:
+        proxy: Optional dict with keys like 'http' mapping to proxy URL.
+
+    Returns:
+        A string to show safe proxy information in logs.
+    """
+    if not proxy:
+        return "local IP (no proxy configured)"
+    proxy_value = proxy.get("http", "")
+    if "@" in proxy_value:
+        return proxy_value.split("@")[-1]
+    elif proxy_value:
+        return proxy_value
+    else:
+        return "unknown (invalid proxy format)"

vinted_api_kit/vinted_api.py

@@ -0,0 +1,120 @@
+import logging
+from typing import Optional, Union
+
+from vinted_api_kit.client.vinted_http_client import VintedHttpClient
+from vinted_api_kit.models import CatalogItem, DetailedItem
+from vinted_api_kit.services.item_service import ItemService
+from vinted_api_kit.utils import format_proxy_for_log
+
+logger = logging.getLogger(__name__)
+
+
+class VintedApi:
+    """
+    Facade class providing async context management for Vinted API client and services.
+    """
+
+    def __init__(
+        self, locale=None, proxies=None, client_ip=None, cookies_dir=None, persist_cookies=False
+    ):
+        logger.info(
+            "Initializing VintedApi client with locale=%s, proxies=%s",
+            locale,
+            format_proxy_for_log(proxies),
+        )
+        """
+        Initialize VintedApi with client configuration.
+
+        Args:
+            locale (str, optional): Locale for API requests.
+            proxies (dict, optional): Proxy configuration.
+            client_ip (str, optional): Client IP for headers.
+            cookies_dir (str, optional): Directory for storing cookies.
+            persist_cookies (bool, optional): Whether to save cookies to disk.
+        """
+        self._client = VintedHttpClient(
+            locale=locale,
+            proxies=proxies,
+            client_ip=client_ip,
+            cookies_dir=cookies_dir,
+            persist_cookies=persist_cookies,
+        )
+        self._items_service = ItemService(self._client)
+
+    async def __aenter__(self):
+        """
+        Enter async context, return self.
+        """
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        """
+        Exit async context, close the client session.
+
+        Args:
+            exc_type: Exception type if any.
+            exc_value: Exception value if any.
+            traceback: Traceback if any.
+
+        Returns:
+            False (do not suppress exceptions)
+        """
+        if exc_type:
+            logger.error(
+                "Exception %s occurred: %s",
+                exc_type,
+                exc_value,
+                exc_info=(exc_type, exc_value, traceback),
+            )
+        await self._client.close()
+        return False
+
+    async def search_items(
+        self,
+        url: str,
+        per_page: int = 20,
+        page: int = 1,
+        timestamp: Optional[int] = None,
+        raw_data: bool = False,
+        order: Optional[str] = None,
+    ) -> Union[list[CatalogItem], list[dict], None]:
+        """
+        Search items on Vinted.
+
+        Args:
+            url (str): URL with search filters.
+            per_page (int): Items per page.
+            page (int): Page number.
+            timestamp (Optional[int]): Unix timestamp override.
+            raw_data (bool): Return raw JSON data if True.
+            order (str): Sorting order.
+
+        Returns:
+            List of CatalogItem or raw data list.
+        """
+        try:
+            result = await self._items_service.search_items(
+                url, per_page, page, timestamp, raw_data, order
+            )
+            return result
+        except Exception as e:
+            logger.error("search_items failed: %s", e)
+            raise
+
+    async def item_details(self, url: str, raw_data: bool = False) -> Union[DetailedItem, dict]:
+        """
+        Get detailed information of an item by URL.
+
+        Args:
+            url (str): Item URL.
+            raw_data (bool): Return raw JSON if True.
+
+        Returns:
+            DetailedItem or raw dict.
+        """
+        try:
+            result = await self._items_service.item_details(url, raw_data)
+            return result
+        except Exception as e:
+            logger.error("item_details failed: %s", e)
+            raise

vinted_api_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: vinted-api-kit
+Version: 0.1.0
+Summary: Lightweight asynchronous Python client library for accessing Vinted API and scraping item data.
+Project-URL: Homepage, https://github.com/vlymar-dev/vinted-api-kit
+Project-URL: Documentation, https://github.com/vlymar-dev/vinted-api-kit
+Project-URL: Repository, https://github.com/vlymar-dev/vinted-api-kit
+Author-email: Lymar Volodymyr <volodymyr.lymar1@gmail.com>
+Maintainer-email: Lymar Volodymyr <volodymyr.lymar1@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,async,ecommerce,python,vinted,vinted-api,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi<0.13.0,>=0.12.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+![Vinted Api Kit](./assets/logo.png)
+
+***Lightweight asynchronous Python client library for accessing Vinted API and scraping item data.***
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+</div>
+
+---
+## ✨ Features
+
+- 🚀 **Asynchronous** - Built with asyncio for high performance
+- 🌍 **Multi-locale** - Supports multiple Vinted domains (FR, DE, US, etc.)
+- 🔍 **Item Search** - Search catalog with filters and pagination
+- 📦 **Item Details** - Get complete item information
+- 🍪 **Cookie Persistence** - Automatic session management
+- 🔐 **Proxy Support** - Built-in proxy configuration
+- 📊 **Type Hints** - Full typing support for better IDE experience
+
+---
+## 📚 Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Development](#development)
+- [Changelog](#changelog)
+- [License](#license)
+
+---
+## Installation
+
+Install via pip:
+```bash
+pip install vinted-api-kit
+```
+Or using poetry:
+```bash
+poetry add vinted-api-kit
+```
+
+---
+## Quick Start
+
+```python
+import asyncio
+from vinted_api_kit import VintedApi, CatalogItem, DetailedItem
+
+async def main():
+    async with VintedApi(locale="fr") as vinted:
+        # Get detailed item information
+        item_detail: DetailedItem = await vinted.item_details(
+            url="https://www.vinted.fr/items/922704975-adidas-x-15"
+        )
+        print(f"📦 {item_detail.title}")
+        print(f"💰 {item_detail.price}\n")
+
+        # Search for items
+        items: list[CatalogItem] = await vinted.search_items(
+            url="https://www.vinted.fr/catalog?search_text=adidas",
+            per_page=5
+        )
+
+        print("🔍 Search results:")
+        for item in items:
+            print(f"  • {item.title} - {item.price} {item.currency}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+## Configuration
+
+### Basic usage
+```python
+from vinted_api_kit import VintedApi
+
+async with VintedApi(locale="fr") as vinted:
+    pass
+```
+
+### Advanced configuration
+```python
+from vinted_api_kit import VintedApi
+
+async with VintedApi(
+    locale="de",
+    proxies={"http": "http://proxy:8080"},
+    client_ip="192.168.1.1",
+    cookies_dir="./cookies",
+    persist_cookies=True
+) as vinted:
+    pass
+```
+
+**Parameters:**
+- `locale` - Vinted domain locale (`'fr'`, `'de'`, `'us'`, etc.)
+- `proxies` - Proxy configuration (requests format)
+- `client_ip` - Override client IP header
+- `cookies_dir` - Directory for cookie storage
+- `persist_cookies` - Enable/disable cookie persistence
+
+These can be set when creating an instance of the `VintedApi` class.
+
+No additional environment variables are required by default.
+
+---
+## 🛠️ Development
+
+### Setup
+```shell
+git clone https://github.com/vlymar1/vinted-api-kit.git
+cd vinted-api-kit
+```
+*Install dependencies (you'll need to set up your dev environment)*
+### Testing
+
+```shell
+make test-coverage # run tests with coverage
+make test-coverage-view # view coverage report in browser
+```
+
+### Code Quality
+
+```shell
+make lint-check # check code with ruff and mypy
+make lint-reformat # format and fix code with ruff
+```
+
+### Cleanup
+
+```shell
+make clean # remove cache files and build artifacts
+```
+
+**Development Guidelines:**
+- Follow PEP8 style guidelines
+- Configure ruff in `pyproject.toml` for your preferred rules
+- Set up pre-commit hooks for automatic linting
+- Contributions welcome! Please open issues or pull requests
+
+---
+## Changelog
+
+See [`CHANGELOG.md`](CHANGELOG.md) for the list of notable changes per version.
+
+### How to create and maintain changelog?
+
+- Start a `CHANGELOG.md` file at the root of your repo.
+- Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format for consistent structure.
+- For each release version, record:
+  - Added — new features
+  - Changed — updates/improvements
+  - Fixed — bug fixes
+  - Removed — deprecated or removed features
+- Update changelog **before** tagging a new release (e.g., `v1.0.0`).
+- Automate changelog generation optionally by tools such as:
+  - [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator)
+  - [auto-changelog](https://github.com/CookPete/auto-changelog)
+  - Conventional commits combined with [semantic-release](https://semantic-release.gitbook.io/semantic-release/)
+
+---
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+## Maintainers / Contacts
+
+- GitHub: [https://github.com/vlymar1](https://github.com/vlymar1)
+
+Feel free to open issues or contact for support and collaborations.

vinted_api_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+vinted_api_kit/__init__.py,sha256=oIDo9ySeku2rY-gvm9AMWeaoW3Bf_fH0EDLI693F_-g,159
+vinted_api_kit/utils.py,sha256=00E97ACew8ZixeQFpFVOWEKWPTr5aRP3ciCGol_zXXE,587
+vinted_api_kit/vinted_api.py,sha256=6sXnMiSVpnFw40GLJ-zYBiwMYB_J6b6rBfuGY-CbC0s,3738
+vinted_api_kit/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vinted_api_kit/client/user_agents.py,sha256=9JWrxaGwVcT57fFQpJJeh5a6oc6wj9D1UcDvi-uQnNs,1121
+vinted_api_kit/client/vinted_http_client.py,sha256=UvtH0z2dpJRRpf5x2VH-SmDoC_tCHLrMpfapaV_gFCw,12686
+vinted_api_kit/models/__init__.py,sha256=2KsOrQSjWGT1yS4-MIu4ueYh5wrsMvlq886iWq2BhYs,121
+vinted_api_kit/models/catalog_item.py,sha256=Vu7ruhNi3ZAyDPnqI9NhluYorPGyAdPaTNHShN6t_88,2755
+vinted_api_kit/models/detailed_item.py,sha256=qFPPKb1FxzzSH60MV94RZiF6Z8nxdbDBVBLuSDp3PJE,4227
+vinted_api_kit/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vinted_api_kit/services/item_service.py,sha256=TCLKBppR9NQYL4Ea86Vjbsvs4ghVcJiP6NiZsGh8ySE,8073
+vinted_api_kit-0.1.0.dist-info/METADATA,sha256=vyiZc4RWwhSXEBEQ2S7NDn_jnwKHQSx8Inw54pI_Ahs,6089
+vinted_api_kit-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+vinted_api_kit-0.1.0.dist-info/licenses/LICENSE,sha256=5EYzaUx_5tQATzjSjGeBI5mdu2tCD3ZHzm-PDzBlNm8,1072
+vinted_api_kit-0.1.0.dist-info/RECORD,,

vinted_api_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vinted_api_kit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Volodymyr Lymar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.