vinted-api-kit 0.1.0__tar.gz → 1.0.0__tar.gz

{vinted_api_kit-0.1.0 → vinted_api_kit-1.0.0}/.github/workflows/ci.yaml

@@ -20,18 +20,16 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies
+      - name: Install hatch and create env
         run: |
           python -m pip install --upgrade pip
-          pip install poetry
-          poetry config virtualenvs.create false
-          poetry install --no-interaction --no-ansi --no-root
+          pip install hatch
 
       - name: Run linting
-        run: poetry run ruff check . --output-format=github
+        run: hatch run lint
 
       - name: Run type check
-        run: poetry run mypy vinted_api_kit/
+        run: hatch run type-check
 
       - name: Run tests (no coverage)
-        run: poetry run pytest -v --tb=short
+        run: hatch run test

{vinted_api_kit-0.1.0 → vinted_api_kit-1.0.0}/.github/workflows/coverage.yaml

@@ -20,12 +20,10 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install poetry
-          poetry config virtualenvs.create false
-          poetry install --no-interaction --no-ansi --no-root
+          pip install hatch
 
       - name: Run tests with coverage
-        run: poetry run pytest --cov=vinted_api_kit --cov-branch --cov-report=xml
+        run: hatch run pytest --cov=vinted --cov-branch --cov-report=xml
 
       - name: Upload results to Codecov
         uses: codecov/codecov-action@v5

{vinted_api_kit-0.1.0 → vinted_api_kit-1.0.0}/.gitignore

@@ -212,4 +212,7 @@ __marimo__/
 dev/
 reports/
 
-cookies*.pk
+cookies*.*
+
+# MacOS
+.DS_Store

{vinted_api_kit-0.1.0 → vinted_api_kit-1.0.0}/.pre-commit-config.yaml

@@ -19,3 +19,9 @@ repos:
         - --fix
     - id: ruff-format
       types: [python]
+
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v1.13.0
+  hooks:
+    - id: mypy
+      additional_dependencies: [curl-cffi]

vinted_api_kit-1.0.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+
+### Changed
+
+
+### Fixed
+
+
+
+## [1.0.0] - 2026-01-05
+
+### Added
+- Multiple cookie storage backends: `json`, `mozilla`, and `pickle`
+- Dataclass-based models (`CatalogItem`, `DetailedItem`) for performance and clarity
+- Custom exception hierarchy to surface network, auth, and validation errors distinctly
+- Automatic locale detection from target Vinted URLs
+- `SortOrder` and `StorageFormat` type literals for improved typing
+
+### Changed
+- Refactored architecture: separated `api/`, `storage/`, and `models/` layers for better maintainability
+- Default cookie storage format changed to `json` for security hardening
+- SSL verification enabled by default for all HTTP requests
+- Proxy configuration simplified to a single string parameter (`proxy="user:pass@host:port"`)
+- Cookie persistence now uses strategy pattern
+
+### Fixed
+- JWT token expiration parsing (base64url padding handling)
+- Retry/logging behavior for authentication failures
+- Cookie persistence reliability
+- Proxy handling edge cases
+- Token expiration detection accuracy
+
+## [0.1.0.post1] - 2025-08-07
+
+### Fixed
+- Logo display compatibility for PyPI
+- Added project badges to README.md for better presentation
+- Corrected CHANGELOG formatting and metadata
+
+## [0.1.0] - 2025-08-07
+
+### Added
+- Asynchronous HTTP client for Vinted API with cookie management
+- `VintedApi.search_items()` method for item searching with filters
+- `VintedApi.item_details()` method for detailed item information
+- Support for multiple Vinted domains (fr, de, sk, pl, it, etc.)
+- Proxy support for web scraping
+- Automatic authentication and session handling
+- Cookie persistence between requests
+- JWT token expiration detection and refresh
+- Comprehensive error handling with retry logic
+- Full typing support and async/await patterns
+- CI/CD pipeline with GitHub Actions
+- 80%+ test coverage
+
+[Unreleased]: https://github.com/vlymar1/vinted-api-kit/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/vlymar1/vinted-api-kit/compare/v0.1.0...v1.0.0
+[0.1.0.post1]: https://github.com/vlymar1/vinted-api-kit/compare/v0.1.0...v0.1.0.post1
+[0.1.0]: https://github.com/vlymar1/vinted-api-kit/releases/tag/v0.1.0

{vinted_api_kit-0.1.0 → vinted_api_kit-1.0.0}/LICENSE

@@ -19,3 +19,9 @@ 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.
+
+DISCLAIMER:
+This software is intended for personal and lawful use only.
+The authors and copyright holders are not responsible for any misuse of the
+software, including but not limited to violations of applicable laws,
+regulations, or terms of service of third-party platforms.

vinted_api_kit-1.0.0/Makefile

@@ -0,0 +1,91 @@
+package_dir := vinted
+tests_dir := tests
+reports_dir := reports
+
+# ===========
+# Environment
+# ===========
+.PHONY: clean
+clean:
+	rm -rf `find . -name __pycache__`
+	rm -f `find . -type f -name '*.py[co]'`
+	rm -f `find . -type f -name '*~'`
+	rm -f `find . -type f -name '.*~'`
+	rm -rf `find . -name .pytest_cache`
+	rm -rf *.egg-info
+	rm -f report.html
+	rm -f .coverage
+	rm -rf {build,dist,.cache,.mypy_cache,.ruff_cache,.hatch,reports,.tox}
+	rm -rf htmlcov/
+
+
+# ===========
+# Development
+# ===========
+.PHONY: install
+install:
+	pip install hatch
+
+.PHONY: install-dev
+install-dev:
+	hatch env create
+
+
+# ============
+# Code quality
+# ============
+.PHONY: lint
+lint:
+	hatch run lint
+
+.PHONY: lint-check
+lint-check:
+	hatch run ruff check $(package_dir)
+	hatch run mypy $(package_dir)
+
+.PHONY: format
+format:
+	hatch run format
+
+.PHONY: type-check
+type-check:
+	hatch run type-check
+
+# ======
+# Tests
+# ======
+.PHONY: test
+test:
+	hatch run test
+
+.PHONY: test-cov
+test-coverage:
+	mkdir -p $(reports_dir)/tests/
+	hatch run pytest --cov=$(package_dir) --cov-report=html:$(reports_dir)/coverage --cov-report=term-missing --html=$(reports_dir)/tests/index.html $(tests_dir)
+
+.PHONY: test-coverage-view
+test-coverage-view: test-coverage
+	python -c "import webbrowser; webbrowser.open('file://$(shell pwd)/$(reports_dir)/coverage/index.html')"
+
+
+# =====
+# Build
+# =====
+.PHONY: build
+build: clean
+	hatch build
+
+.PHONY: publish
+publish: build
+	hatch publish
+
+.PHONY: publish-test
+publish-test: build
+	hatch publish -r test
+
+# ===
+# All
+# ===
+.PHONY: all
+all:
+	hatch run all

vinted_api_kit-1.0.0/PKG-INFO

@@ -0,0 +1,424 @@
+Metadata-Version: 2.4
+Name: vinted-api-kit
+Version: 1.0.0
+Summary: Lightweight asynchronous Python client library for accessing Vinted API and scraping item data.
+Project-URL: Homepage, https://github.com/vlymar1/vinted-api-kit
+Project-URL: Documentation, https://github.com/vlymar1/vinted-api-kit
+Project-URL: Repository, https://github.com/vlymar1/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 :: 5 - Production/Stable
+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 logo](https://raw.githubusercontent.com/vlymar1/vinted-api-kit/main/assets/logo.png)
+
+***Lightweight asynchronous Python client library for accessing Vinted API and scraping item data.***
+
+[![Package Version](https://img.shields.io/pypi/v/vinted-api-kit.svg)](https://pypi.org/project/vinted-api-kit/)
+[![Python Version](https://img.shields.io/pypi/pyversions/vinted-api-kit.svg)](https://pypi.org/project/vinted-api-kit/)
+[![codecov](https://codecov.io/github/vlymar1/vinted-api-kit/graph/badge.svg?token=SLCFGVYDOM)](https://codecov.io/github/vlymar1/vinted-api-kit)
+[![Downloads](https://static.pepy.tech/badge/vinted-api-kit)](https://pepy.tech/project/vinted-api-kit)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Typed](https://img.shields.io/badge/typed-mypy-blue)](http://mypy-lang.org/)
+[![License](https://img.shields.io/pypi/l/vinted-api-kit.svg)](https://github.com/vlymar1/vinted-api-kit/blob/main/LICENSE)
+</div>
+
+## ✨ Features
+
+- 🚀 **Asynchronous** - Built with asyncio for high performance
+- 🌍 **Auto-locale Detection** - Automatically detects locale from URL
+- 🔍 **Item Search** - Search catalog with filters, sorting and pagination
+- 📦 **Item Details** - Get complete item information with rich metadata
+- 🍪 **Cookie Persistence** - Automatic session management with multiple storage formats
+- 🔐 **Proxy Support** - Simple string-based proxy configuration
+- 📊 **Type Hints** - Full typing support with Literal types for better IDE experience
+- 🎯 **Dataclass Models** - Fast and efficient data models (15% performance boost)  # TODO: Убрать у будущем
+- 🛡️ **Custom Exceptions** - Detailed error hierarchy for precise error handling
+- 💾 **Flexible Storage** - Choose between pickle, JSON, or Mozilla cookie formats
+
+## 📚 Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Migration Guide](#migration-guide)
+- [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
+```
+
+## Usage
+
+### Basic Example
+```python
+import asyncio
+from vinted import VintedClient
+
+async def main():
+    async with VintedClient() as client:
+        items = await client.search_items(
+            url="https://www.vinted.com/catalog?search_text=nike",
+            per_page=5
+        )
+
+        for item in items:
+            print(f"• {item.title} - {item.price} {item.currency}")
+
+asyncio.run(main())
+```
+
+---
+
+### Configuration
+
+#### 🔐 Proxy Support
+
+> Use a proxy by passing a simple connection string:
+```python
+async with VintedClient(
+    proxy="user:pass@proxy.example.com:8080"  # Format: [user:pass@]host:port
+) as client:
+    items = await client.search_items(url)
+```
+
+#### 💾 Cookie Persistence
+
+> Save cookies between sessions to avoid repeated authentication:
+```python
+from pathlib import Path
+
+async with VintedClient(
+    persist_cookies=True,              # Enable persistence
+    cookies_dir=Path("./cookies"),     # Storage directory
+    storage_format="json"              # Format: pickle | json | mozilla
+) as client:
+    items = await client.search_items(url)
+```
+
+**Storage formats:**
+- **`"json"`** (default) - Human-readable, portable across platforms
+- **`"pickle"`** - Fastest, Python-native binary format
+- **`"mozilla"`** - Browser-compatible Netscape format
+
+#### 🔍 Search Options
+
+> Use type-safe sorting and pagination:
+```python
+from vinted import SortOrder
+
+items = await client.search_items(
+    url="https://www.vinted.de/catalog?brand_ids[]=53",
+    per_page=20,                      # Items per page (1-96)
+    page=1,                           # Page number
+    order="price_low_to_high"         # Sort order (IDE auto-complete)
+)
+```
+
+**Available sort orders:**
+- `newest_first` - Most recent items
+- `relevance` - Best match
+- `price_low_to_high` - Cheapest first
+- `price_high_to_low` - Most expensive first
+
+#### 📦 Raw Data
+
+> Get raw JSON dictionaries instead of parsed models:
+```python
+raw_items = await client.search_items(
+    url="https://www.vinted.com/catalog?search_text=shoes",
+    raw_data=True  # Returns list[dict] instead of list[CatalogItem]
+)
+```
+
+---
+
+### Item Details
+
+> Fetch detailed information about a specific item:
+```python
+item = await client.item_details(
+    url="https://www.vinted.com/items/1234567890"
+)
+
+print(f"Title: {item.title}")
+print(f"Brand: {item.brand_title}")
+print(f"Size: {item.size_title}")
+print(f"Price: {item.price} {item.currency}")
+print(f"Total: {item.total_item_price}")
+print(f"Description: {item.description}")
+
+# Or get raw JSON
+raw_item = await client.item_details(url, raw_data=True)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `proxy` | `str \| None` | `None` | Proxy string: `"user:pass@host:port"` or `"host:port"` |
+| `cookies_dir` | `Path \| None` | `Path(".")` | Directory for cookie storage |
+| `persist_cookies` | `bool` | `False` | Enable cookie persistence between sessions |
+| `storage_format` | `"json" \| "pickle" \| "mozilla"` | `"json"` | Cookie storage format |
+
+**Storage formats:** `json` (default), `pickle`, `mozilla`. See [Storage Formats](#storage-formats:) for details.
+
+
+
+### Exception Handling
+```python
+from vinted import (
+    VintedClient,
+    VintedError,           # Base exception
+    VintedAPIError,        # API errors (4xx, 5xx)
+    VintedAuthError,       # Authentication failures
+    VintedNetworkError,    # Network/connection errors
+    VintedConfigError,     # Invalid configuration
+    VintedValidationError, # Input validation errors
+    VintedRateLimitError,  # Rate limiting (429)
+)
+
+try:
+    async with VintedClient(proxy="invalid://proxy") as client:
+        items = await client.search_items(url)
+except VintedConfigError as e:
+    print(f"Configuration error: {e}")
+except VintedValidationError as e:
+    print(f"Invalid input: {e}")
+except VintedRateLimitError as e:
+    print(f"Rate limited: {e.status_code}")
+except VintedAuthError as e:
+    print(f"Auth failed: {e}")
+except VintedNetworkError as e:
+    print(f"Network error: {e.original_error}")
+except VintedAPIError as e:
+    print(f"API error: {e.status_code}")
+```
+
+
+---
+## Migration Guide
+### (v0.x → v1.0)
+### Breaking Changes
+
+If you're upgrading from version 0.x, here are the key changes:
+
+#### 1. Import Path Changed
+```python
+# ❌ Old (v0.x)
+from vinted_api_kit import VintedApi
+
+# ✅ New (v1.0)
+from vinted import VintedClient
+```
+
+#### 2. Class Renamed
+```python
+# ❌ Old
+async with VintedApi() as api:
+    pass
+
+# ✅ New
+async with VintedClient() as client:
+    pass
+```
+
+#### 3. Locale Parameter Removed
+```python
+# ❌ Old (manual locale)
+async with VintedApi(locale="fr") as api:
+    items = await api.search_items(url)
+
+# ✅ New (auto-detected from URL)
+async with VintedClient() as client:
+    items = await client.search_items(url)  # Locale detected from URL
+```
+
+#### 4. Proxy Configuration Changed
+```python
+# ❌ Old (dict format)
+async with VintedApi(
+    proxies={"http": "http://user:pass@proxy:8080"}
+) as api:
+    pass
+
+# ✅ New (simple string)
+async with VintedClient(
+    proxy="user:pass@proxy:8080"  # ← Without "http://"
+) as client:
+    pass
+```
+
+#### 5. New Storage Format Option
+```python
+# ✅ New feature in v1.0
+async with VintedClient(
+    persist_cookies=True,
+    storage_format="json"  # Choose: "json", "pickle", "mozilla"
+) as client:
+    pass
+```
+
+### Quick Migration Checklist
+
+- [ ] Change import: `vinted_api_kit` → `vinted`
+- [ ] Rename class: `VintedApi` → `VintedClient`
+- [ ] Remove `locale` parameter (auto-detected)
+- [ ] Update proxy format: dict → string
+- [ ] Optional: Choose storage format
+
+### Full Example
+
+**Before (v0.x):**
+```python
+from vinted_api_kit import VintedApi
+
+async with VintedApi(
+    locale="fr",
+    proxies={"http": "http://proxy:8080"},
+    persist_cookies=True
+) as api:
+    items = await api.search_items(
+        url="https://www.vinted.fr/catalog?search_text=nike"
+    )
+```
+
+**After (v1.0):**
+```python
+from vinted import VintedClient
+
+async with VintedClient(
+    proxy="proxy:8080",
+    persist_cookies=True,
+    storage_format="pickle"  # New option!
+) as client:
+    items = await client.search_items(
+        url="https://www.vinted.fr/catalog?search_text=nike"
+    )
+```
+
+---
+## Development
+
+### Setup
+```bash
+git clone https://github.com/vlymar1/vinted-api-kit.git
+cd vinted-api-kit
+
+pip install hatch
+hatch shell
+```
+
+### Project Structure
+```
+vinted-api-kit/
+├── vinted/             # Main package
+│   ├── api/            # API endpoint handlers
+│   ├── models/         # Data models (dataclasses)
+│   ├── storage/        # Cookie storage strategies
+│   ├── client.py       # Main client (VintedClient)
+│   ├── session.py      # HTTP session management
+│   ├── auth.py         # Authentication logic
+│   ├── constants.py    # Constants and type definitions
+│   ├── exceptions.py   # Custom exceptions
+│   └── utils.py        # Utility functions
+├── tests/              # Test suite
+└── examples/           # Usage examples
+```
+
+### Testing
+```bash
+make test-coverage      # Run tests with coverage
+make test-coverage-view # View coverage report in browser
+```
+
+### Code Quality
+```bash
+make lint-check         # Check code with ruff and mypy
+make lint-reformat      # Format and fix code with ruff
+```
+
+### Cleanup
+```bash
+make clean              # Remove cache files and build artifacts
+```
+
+### Development Guidelines
+
+- Follow PEP 8 style guidelines
+- Use type hints for all functions
+- Write tests for new features
+- Update CHANGELOG.md for notable changes
+- Run `make lint-check` before committing
+- Contributions welcome! 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.
+
+_⚠ Disclaimer_
+
+This library is intended for personal and lawful use only.
+The author is not responsible for any misuse, including but not limited to:
+- Violations of applicable laws or regulations
+- Breaches of terms of service of third-party websites
+
+_By using this library, you agree that you are solely responsible for your actions._
+
+---
+## Maintainers / Contacts
+
+- GitHub: [https://github.com/vlymar1](https://github.com/vlymar1)
+
+Feel free to open issues or contact for support and collaborations.