chore: initial goupix dex import

Made-with: Cursor

Author: Leoglme

.gitignore

@@ -0,0 +1,7 @@
+.vscode
+.idea
+api/.venv
+api/__pycache__
+api/*.pyc
+api/.env
+web/.env

api/.env.example

@@ -0,0 +1,35 @@
+# Database
+# Local dev (Python on host): point to localhost or Docker-published port.
+DATABASE_URL=mysql+pymysql://goupix:goupix@127.0.0.1:3306/goupixdex
+# Docker Compose: the compose file sets DATABASE_URL to host "mariadb" for the api service
+# (overrides this line via process environment). Keep 127.0.0.1 for running uvicorn on the host.
+
+# JWT
+JWT_SECRET=change-me-to-a-long-random-string
+
+# Optional: seed default user (python seeders/user_seeder.py)
+SEED_USER_EMAIL=you@example.com
+SEED_USER_PASSWORD=your-secure-password
+
+# Dev: ensure margin row for users missing settings (default 20%)
+# SEED_MARGIN_PERCENT=20
+
+# Dev: fake articles — uses SEED_USER_EMAIL if SEED_ARTICLE_USER_EMAIL is empty
+# SEED_ARTICLE_USER_EMAIL=you@example.com
+
+# Run all seeders in order: python seeders/run_all.py
+
+# APIs
+POKE_WALLET_API_KEY=
+GROQ_API_KEY=
+
+# Vinted: copied to users.vinted_email / users.vinted_password (Fernet-encrypted with JWT_SECRET) when you run user_seeder
+# (both keys required to sync). Used by cli_vinted_listings.py and publish fallback if DB fields are empty.
+VINTED_EMAIL_OR_USERNAME=
+VINTED_PASSWORD=
+
+# When true, article creation skips real browser automation (recommended in dev)
+VINTED_PUBLISH_STUB=true
+
+# CORS (comma-separated or *)
+CORS_ORIGINS=*

api/.gitignore

@@ -0,0 +1,8 @@
+.idea
+.env
+node_modules
+ebayBuilder.ts
+.venv
+__pycache__/
+*.pyc
+uploads/

api/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim-bookworm
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

api/README.md

@@ -0,0 +1,143 @@
+# GoupixDex — API (Python)
+
+Backend for **GoupixDex**: Pokémon TCG scanning, pricing (PokéWallet), inventory articles, JWT auth, and optional Vinted automation (nodriver).
+
+## Stack
+
+- **FastAPI** + **Uvicorn** — REST API, OpenAPI/Swagger at `/docs`
+- **SQLAlchemy 2** ORM — models under `models/` (not Pydantic)
+- **MariaDB / MySQL** — via **PyMySQL** (`mysql+pymysql://…`)
+- **JWT** (python-jose) + **bcrypt**
+- **Pydantic** — request/response validation only (`schemas/`)
+- **Custom SQL migrations** in `migrations/` (no Alembic)
+- **Docker Compose** — API (hot reload), MariaDB, phpMyAdmin
+
+## Layout
+
+```text
+api/
+  main.py                 # FastAPI app
+  config.py               # AppSettings + legacy Vinted CLI defaults
+  cli_vinted_listings.py  # Standalone nodriver CLI (was main.py)
+  app_types/              # TypedDict (PokéWallet, Groq, Vinted payloads)
+  core/
+    database.py           # Engine, SessionLocal, get_db
+    security.py           # JWT + password hashing
+    deps.py               # Current user (Bearer)
+  models/                 # SQLAlchemy ORM (User, Article, Image, MarginSettings)
+  schemas/                # Pydantic API bodies only
+  routes/                 # auth, users, articles, settings, scan
+  services/
+    ocr_service.py        # Groq vision wrapper
+    pricing_service.py    # PokéWallet + EUR/USD average
+    scan_service.py       # Title/description templates
+    article_service.py
+    auth_service.py
+    vinted_publish_service.py  # Calls existing VintedService
+    … (pokewallet, groq_vision_client, vinted_service, …)
+  migrations/
+  seeders/
+  uploads/                # Local image storage (created at runtime)
+```
+
+## Requirements
+
+- Python **3.10+**
+- MariaDB or MySQL (local or Docker)
+- Optional: `POKE_WALLET_API_KEY`, `GROQ_API_KEY`, Chrome for real Vinted runs
+
+## Install
+
+```bash
+cd api
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+Copy `.env.example` to `.env` and set at least `DATABASE_URL` and `JWT_SECRET`.
+
+### Database
+
+```bash
+python migrations/run_migrations.py
+```
+
+### Seeders (optional, dev)
+
+1. **User** — set `SEED_USER_EMAIL` and `SEED_USER_PASSWORD` in `.env`, then:
+
+   ```bash
+   python seeders/user_seeder.py
+   ```
+
+2. **Margin (20% default)** — creates a `settings` row for any user that does not have one yet:
+
+   ```bash
+   python seeders/margin_seeder.py
+   ```
+
+   Override default percent with `SEED_MARGIN_PERCENT` (e.g. `25`).
+
+3. **Fake articles** — requires an existing user. Uses `SEED_ARTICLE_USER_EMAIL` or falls back to `SEED_USER_EMAIL`. Deletes previous `[DEV] …` titles for that user, then inserts four sample articles (one marked sold):
+
+   ```bash
+   python seeders/article_seeder.py
+   ```
+
+4. **Everything in order** (same env vars as above):
+
+   ```bash
+   python seeders/run_all.py
+   ```
+
+## Run API
+
+```bash
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+- Swagger UI: http://127.0.0.1:8000/docs  
+- Health: `GET /health`  
+- Uploaded files are served under `/uploads/...`
+
+### Main endpoints
+
+| Method | Path | Notes |
+|--------|------|--------|
+| POST | `/auth/login` | JWT Bearer |
+| POST | `/users` | Register |
+| GET/PUT/DELETE | `/users`, `/users/{id}`, `/users/me` | Auth required for most |
+| POST | `/scan-card` | Multipart image + optional `margin_percent`; OCR + pricing preview (no DB) |
+| CRUD | `/articles` | Create uses multipart (fields + `images` files); then Vinted attempt |
+| PATCH | `/articles/{id}/sold` | Mark sold + `sell_price` |
+| GET/PUT | `/settings` | Margin % (default 20) |
+
+**Vinted:** set `VINTED_PUBLISH_STUB=true` in dev to skip browser automation. On `POST /articles`, publication uses the authenticated user’s `vinted_email` and **encrypted** `vinted_password` (Fernet, key derived from `JWT_SECRET`). Legacy rows still holding a bcrypt hash cannot be decrypted—re-save the Vinted password via user settings or the seeder, or set `VINTED_EMAIL_OR_USERNAME` / `VINTED_PASSWORD` in the environment as fallback.
+
+### Legacy Vinted CLI (batch `items.json`)
+
+```bash
+python cli_vinted_listings.py
+```
+
+Uses `config.py` listing defaults and `items.json` / `images/` at the project root.
+
+## Docker
+
+From `api/`:
+
+```bash
+docker compose up --build
+```
+
+- API: port **8000** (migrations run on startup)
+- MariaDB: **3306**
+- phpMyAdmin: **8080**
+
+Create a user after startup: `docker compose exec api python seeders/user_seeder.py` (with env vars set), or use `POST /users` and `POST /auth/login`.
+
+## Limitations
+
+- Vinted UI and anti-bot policies may break automation; use stub mode when developing.
+- Average price mixes Cardmarket (EUR) and TCGPlayer (USD) using `USD_TO_EUR` in `config` (`AppSettings.usd_to_eur`).

api/app_types/__init__.py

@@ -0,0 +1 @@
+"""TypedDict and legacy typing helpers (not SQLAlchemy ORM)."""

api/app_types/groq_vision.py

@@ -0,0 +1,34 @@
+"""Types for Groq vision OCR-style card extraction."""
+
+from typing import Literal, NotRequired, TypedDict
+
+GroqVisionImageMimeType = Literal["image/jpeg", "image/png", "image/webp"]
+
+
+class GroqVisionExtractOptions(TypedDict, total=False):
+    """Optional tuning for Groq vision extraction."""
+
+    temperature: float
+    model: str
+    include_raw_assistant_json: bool
+    resolve_english_name_from_poke_wallet: bool
+
+
+class GroqVisionCardCollectorResult(TypedDict, total=False):
+    """
+    Pokémon TCG collector info inferred from a card photo (set code, number, name).
+    ``None`` fields mean unreadable or absent per model (not guessed), except fraction parts
+    derived from ``card_number`` when possible.
+    """
+
+    set_code: str | None
+    card_number: str | None
+    card_number_numerator: str | None
+    card_number_denominator: str | None
+    pokemon_name: str | None
+    pokemon_name_english: str | None
+    pokemon_name_french: str | None
+    card_variant_label: str | None
+    set_name_english: str | None
+    rarity_english: str | None
+    raw_assistant_json: NotRequired[str]

api/app_types/payload.py

@@ -0,0 +1,24 @@
+"""Item listing payload shape (matches ``items.json`` entries)."""
+
+from typing import NotRequired, TypedDict
+
+from app_types.vinted import VintedConditions
+
+
+class ItemPayload(TypedDict):
+    """
+    Describes one Vinted listing loaded from ``items.json``.
+
+    Attributes:
+        title: Listing title shown on Vinted.
+        description: Optional long description (see VintedService for how it is applied).
+        price: Price as a number (currency follows your Vinted account).
+        condition: One of the French Vinted condition labels.
+        images: Filenames under the project ``images/`` folder.
+    """
+
+    title: str
+    description: NotRequired[str]
+    price: float | int
+    condition: VintedConditions
+    images: list[str]

api/app_types/pokewallet.py

@@ -0,0 +1,121 @@
+"""PokéWallet API response shapes (https://api.pokewallet.io)."""
+
+from typing import NotRequired, TypedDict
+
+
+class PokeWalletSearchMetadata(TypedDict):
+    """Metadata returned alongside search results, summarising source coverage."""
+
+    total_count: int
+    tcg: int
+    cardmarket: int
+    tcg_only: int
+    cardmarket_only: int
+    both_sources: int
+
+
+class PokeWalletPagination(TypedDict):
+    """Pagination envelope for the search endpoint."""
+
+    page: int
+    limit: int
+    total: int
+    total_pages: int
+
+
+class PokeWalletSearchOptions(TypedDict, total=False):
+    """Optional query flags for ``GET /search`` (page default 1, limit default 20, max 100)."""
+
+    page: int
+    limit: int
+    pokemonName: str
+
+
+class PokeWalletGetCardOptions(TypedDict, total=False):
+    """Optional query flags for ``GET /cards/:id`` (disambiguation)."""
+
+    setCode: str
+
+
+class PokeWalletCardInfo(TypedDict, total=False):
+    """Core card attributes as returned by the API (fields may be omitted on partial matches)."""
+
+    name: str
+    clean_name: str
+    set_name: str
+    set_code: str
+    set_id: str
+    card_number: str
+    rarity: str
+    card_type: str
+    hp: str
+    stage: str
+    card_text: str | None
+    attacks: list[str]
+    weakness: str
+    resistance: str | None
+    retreat_cost: str
+
+
+class PokeWalletTcgPlayerPriceRow(TypedDict):
+    """A single TCGPlayer price row for a product sub-type (e.g. Holofoil)."""
+
+    low_price: float
+    mid_price: float
+    high_price: float
+    updated_at: str
+    market_price: float
+    direct_low_price: float | None
+    sub_type_name: str
+
+
+class PokeWalletTcgPlayerBlock(TypedDict):
+    """TCGPlayer listing block; may be absent when the card is not listed there."""
+
+    prices: list[PokeWalletTcgPlayerPriceRow]
+    url: str
+
+
+class PokeWalletCardmarketPriceRow(TypedDict, total=False):
+    """
+    Cardmarket price snapshot for a variant (normal / holo, etc.).
+    Some rows omit fields (API returns partial objects for certain products).
+    """
+
+    avg: float | None
+    low: float | None
+    avg1: float | None
+    avg7: float | None
+    avg30: float | None
+    trend: float | None
+    updated_at: str
+    variant_type: str
+
+
+class PokeWalletCardmarketBlock(TypedDict):
+    """Cardmarket listing block; absent when the card is TCG-only."""
+
+    product_name: str
+    prices: list[PokeWalletCardmarketPriceRow]
+    product_url: str
+
+
+class PokeWalletCard(TypedDict):
+    """
+    One card hit from search, or the full payload from GET /cards/:id.
+    ``id`` may be ``pk_…`` (TCG) or a hex hash (CardMarket-only).
+    """
+
+    id: str
+    card_info: PokeWalletCardInfo
+    tcgplayer: PokeWalletTcgPlayerBlock | None
+    cardmarket: PokeWalletCardmarketBlock | None
+
+
+class PokeWalletSearchResponse(TypedDict):
+    """Response body from GET /search."""
+
+    query: str
+    results: list[PokeWalletCard]
+    pagination: PokeWalletPagination
+    metadata: PokeWalletSearchMetadata