vghoost360/jumbo repository overview

⁠Jumbo API

🛒 Comprehensive REST API and modern web dashboard for the Jumbo.com grocery platform.

Automates authentication via headless Chromium, manages your shopping basket, lists (lijstjes), order history, store receipts, and provides detailed product lookups by SKU or EAN barcode with OpenFoodFacts fallback.

⁠🚀 Quick Start

docker compose up -d

• Web Dashboard: http://localhost:8000⁠
• API Documentation: http://localhost:8000/docs⁠ (Interactive Swagger UI)
• Complete API Guide: API_README.md⁠

⁠✨ Features

⁠🛒 Shopping Basket

• View your current basket with full product details
• Add/remove products by SKU
• Update quantities
• Real-time price calculations
• Promo price support

⁠📝 Shopping Lists (Lijstjes)

• Access all your shopping lists
• View favorite lists and custom lists
• See product images, prices, and details
• Product count tracking

⁠📦 Order Management

• View online order history
• Detailed order information with delivery dates
• Item-level details with images and pricing
• Track order status, substitutions, and unavailable items
• Support for home delivery and store pickup orders

⁠🧾 Store Receipts

• View in-store and online receipt history
• Detailed receipt breakdown with VAT summaries
• Product matching and enrichment
• Loyalty points tracking (Jumbo Extra's)
• Payment method information
• Store location details

⁠🔍 Product Search & Lookup

• Search products by SKU
• Intelligent barcode lookup (EAN codes) with OpenFoodFacts fallback
• EAN similarity matching algorithm - finds best product match when exact barcode not found
  • Searches up to 8 product candidates
  • Scores matches based on EAN prefix similarity (0-100)
  • Color-coded confidence indicators (green ≥90%, yellow <90%)
  • Shows both scanned barcode and matched product EAN
• If barcode not found in Jumbo, automatically queries OpenFoodFacts and searches by product name
• Comprehensive product information:
  • Nutritional data & allergens
  • Multiple images (thumbnails & high-res)
  • Pricing with promotions
  • Brand, categories, descriptions
  • Availability & stock status
  • Manufacturer details & origin
  • Storage & preparation instructions

⁠🔐 Authentication & Auto Re-login

• Automated Selenium-based browser login
• Cookie persistence across restarts
• Auto re-authentication when sessions expire
• Web-based credential management in Settings
• Save credentials directly from the dashboard
• Environment variable support for homelab deployments

⁠🎨 Modern Web Dashboard

• Dark-themed, responsive UI
• Real-time basket updates
• Interactive product cards with images
• Modal dialogs for detailed views
• Toast notifications
• Command history tracking
• Comprehensive Settings page with credential management

⁠⚙️ Product Matching Engine

• Intelligent receipt product enrichment
• Configurable confidence thresholds
• Price, weight, and name matching
• Caching for improved performance
• Manual cache clearing
• OpenFoodFacts integration for unknown barcodes

⁠📚 Documentation

⁠Interactive API Explorer

Visit http://localhost:8000/docs⁠ for the full Swagger/OpenAPI documentation where you can:

• Try all endpoints directly in your browser
• See request/response schemas
• Test authentication flows
• No code required

⁠Comprehensive API Reference

See API_README.md⁠ for:

• Complete endpoint documentation
• Authentication guides
• Code examples in Python, JavaScript, and cURL
• Architecture overview
• Troubleshooting tips

⁠🔐 Authentication Setup

The API supports three methods for persistent authentication:

⁠Option 1: Web Dashboard (Easiest)

1. Open http://localhost:8000⁠
2. Go to Settings tab
3. Enter your credentials in the "Login Credentials" section
4. Click "Save Credentials"
5. Credentials are stored securely for auto re-authentication

⁠Option 2: Environment Variables (Recommended for Homelab)

Set credentials via environment variables in Portainer or docker-compose:

environment:
  - [email protected]
  - JUMBO_PASSWORD=your-password

⁠Option 3: Manual Login

Login once via web dashboard:

• Click "Login" button in header
• Enter credentials
• Credentials auto-save for future sessions

How it works:

• Session cookies saved to /app/data/session-cookies.json
• Credentials saved to /app/data/credentials.json (or use env vars)
• Auto re-authentication triggers when cookies expire
• Seamless operation without manual intervention

⁠🔧 Settings & Configuration

⁠Web Dashboard Settings

Access the Settings panel to configure:

⁠🔐 Login Credentials

• Save/update your Jumbo.com credentials
• View credential status
• Remove saved credentials

⁠📦 Barcode Lookup

• OpenFoodFacts Fallback - automatically query OpenFoodFacts when barcode not found
• EAN Similarity Matching - intelligent algorithm finds best match:
  • Checks up to 8 product candidates
  • Scores based on matching EAN prefix digits
  • 10+ matching digits = 90 score (high confidence)
  • 8+ matching digits = 70 score (medium confidence)
  • 6+ matching digits = 50 score (low confidence)
• Displays confidence score with color coding
• Shows scanned vs matched EAN for transparency

⁠🧾 Receipt Product Matching

• Enable/disable product enrichment
• Strict matching mode
• Confidence threshold slider

⁠🎯 Matching Criteria

• Price matching
• Weight/volume matching
• Name matching

⁠🗑️ Cache Management

• Clear product match cache

⁠🔑 Quick API Examples

⁠Authentication

# Login
curl -X POST http://localhost:8000/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]","password":"yourpassword"}'

# Check auth status
curl http://localhost:8000/api/auth/status

⁠Basket Operations

# Get basket
curl http://localhost:8000/api/basket

# Add product
curl -X POST http://localhost:8000/api/basket/add \
  -H 'Content-Type: application/json' \
  -d '{"sku":"67649PAK","quantity":2}'

# Update quantity
curl -X PATCH http://localhost:8000/api/basket/items/{line_id} \
  -H 'Content-Type: application/json' \
  -d '{"quantity":5}'

# Remove product
curl -X POST http://localhost:8000/api/basket/remove \
  -H 'Content-Type: application/json' \
  -d '{"line_id":"abc123"}'

⁠Shopping Lists

# Get all lists
curl http://localhost:8000/api/lists

# Get specific list details
curl http://localhost:8000/api/lists/{list_id}

⁠Orders & Receipts

# Get orders and receipts
curl "http://localhost:8000/api/orders?limit=10&page=0"

# Get order details
curl http://localhost:8000/api/orders/{order_id}

# Get receipt details
curl http://localhost:8000/api/receipts/{transaction_id}

⁠Product Search & Barcode Lookup

# Search by SKU
curl "http://localhost:8000/api/products/search?sku=67649PAK"

# Barcode lookup (with OpenFoodFacts fallback and EAN matching)
curl -X POST http://localhost:8000/api/products/barcode \
  -H 'Content-Type: application/json' \
  -d '{"barcode":"8718452829408"}'

# Response includes EAN matching details:
# {
#   "sku": "629680PAK",
#   "title": "Jumbo Cola Regular 6 x 1,5 L",
#   "ean": "8718452829583",
#   "scannedBarcode": "8718452829408",
#   "eanMatchScore": 90,
#   "verified": true,
#   "matchSource": "OpenFoodFacts",
#   "matchedName": "Cola"
# }

⁠Settings Management

# Get all settings
curl http://localhost:8000/api/settings

# Update settings
curl -X PUT http://localhost:8000/api/settings \
  -H 'Content-Type: application/json' \
  -d '{"useOpenFoodFactsFallback":true,"confidenceThreshold":50}'

# Save credentials
curl -X PUT http://localhost:8000/api/settings/credentials \
  -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]","password":"yourpassword"}'

# Remove credentials
curl -X PUT http://localhost:8000/api/settings/credentials \
  -H 'Content-Type: application/json' \
  -d '{"removeCredentials":true}'

# Clear match cache
curl -X POST http://localhost:8000/api/settings/clear-cache

For more examples, see API_README.md⁠

⁠🏗️ Project Structure

app/
  main.py              # FastAPI application & REST endpoints
  jumbo_client.py      # Jumbo GraphQL client + Selenium auth + OpenFoodFacts
  templates/
    index.html         # Web dashboard with settings management
  static/
    app.js            # Frontend JavaScript
    style.css         # Responsive dark theme
  Dockerfile
  requirements.txt
data/                  # Persistent data volume
  session-cookies.json # Saved session cookies
  credentials.json     # Encrypted credentials (optional)
  barcode-cache.json   # Product barcode cache
  settings.json        # User preferences
docker-compose.yml
API_README.md          # Complete API documentation

⁠🐳 Docker Deployment

⁠Using Docker Compose (Recommended)

docker-compose up -d

⁠Using Docker Run

docker run -d \
  --name jumbo-api \
  -p 8000:8000 \
  -v jumbo-data:/app/data \
  -e [email protected] \
  -e JUMBO_PASSWORD=yourpassword \
  vghoost360/jumbo:latest

⁠Pull Latest Version

docker pull vghoost360/jumbo:latest
# or specific version
docker pull vghoost360/jumbo:v2.6.0

⁠Volume Mounting

The container uses a persistent volume at /app/data for:

• Session cookies
• Credentials (encrypted)
• Product match cache
• Barcode lookup cache
• User settings

Important: Mount this volume to preserve authentication between container restarts.

⁠🛠️ Tech Stack

• Backend: Python 3.11, FastAPI, Uvicorn
• Authentication: Selenium (headless Chromium)
• HTTP Client: httpx (async)
• External API: OpenFoodFacts API integration
• Frontend: Vanilla JavaScript, CSS Grid/Flexbox
• Container: Docker (python:3.11-slim + Chromium)

⁠🔧 Configuration

⁠Environment Variables

⁠Settings API

Configure behavior via /api/settings or the web dashboard:

• productMatchingEnabled - Enable/disable receipt enrichment
• strictMatching - Require higher confidence for matches
• confidenceThreshold - Minimum confidence percentage (0-100)
• usePriceMatching - Include price in matching algorithm
• useWeightMatching - Include weight in matching algorithm
• useNameMatching - Include name similarity in matching
• useOpenFoodFactsFallback - Query OpenFoodFacts when barcode not found

⁠📊 Health Check

curl http://localhost:8000/api/health

Response:

{
  "status": "healthy",
  "timestamp": "2026-02-22T17:43:00Z",
  "authenticated": true
}

⁠🆕 Changelog

⁠v2.6.0 (2026-02-22)

New Features:

• 🌐 OpenFoodFacts Integration - Automatic fallback when barcode not found in Jumbo
  • Queries OpenFoodFacts API for product name
  • Searches Jumbo catalog with matched name
  • Configurable via settings toggle
• 🎯 EAN Similarity Matching Algorithm - Intelligent product matching system
  • Checks up to 8 product candidates for best EAN match
  • Scores based on matching EAN prefix digits (0-100)
  • Pattern matching: 8718452829xxx = 10 matching digits = 90 score
  • Returns both scanned barcode and matched product EAN
  • Color-coded confidence indicators in UI (green/yellow/red)
  • Warnings for low confidence matches (<90%)
• 🔐 Credential Management UI - Save/update credentials directly from Settings page
  • Visual credential status indicator
  • Secure credential storage
  • Remove credentials option

Bug Fixes:

• 🐛 Fixed critical JavaScript syntax errors preventing button clicks
• 🔧 Added missing hasProduct variable definition
• 🎨 Fixed malformed template literals in receipt rendering
• ✅ Resolved 89+ linting errors
• 🔍 Fixed SKU preservation in EAN matching results

Improvements:

• 📝 Enhanced settings page with credential management
• 🎯 Better barcode lookup with intelligent EAN matching
• 📊 Transparent confidence scoring system
• 🎨 Fixed Settings page CSS (input field overlap)
• 🧹 Code cleanup and validation
• 📚 Comprehensive documentation updates

⁠v2.5.1

• Receipt product enrichment
• Order detail views
• Shopping list support
• Product matching engine

⁠🔒 Security Notes

• Credentials are stored in Docker volumes (not in image)
• .dockerignore excludes personal data from builds
• Session cookies managed securely
• No credentials in logs or version control
• Use environment variables for production deployments
• OpenFoodFacts queries use anonymous API access

⁠🤝 Contributing

This project is for educational purposes. Contributions welcome!

⁠📝 License

Educational use only. Jumbo.com's and OpenFoodFacts' Terms of Service apply to API usage.

⁠🐛 Troubleshooting

⁠Buttons Not Working

• Hard refresh browser (Ctrl+Shift+R)
• Check browser console for JavaScript errors
• Verify container is running: docker ps

⁠Barcode Not Found

• Enable "OpenFoodFacts Fallback" in Settings
• Check if product exists on OpenFoodFacts.org
• Try searching by product name instead

⁠Authentication Issues

• Use Settings page to save credentials
• Check credentials are correct
• Verify cookies in /app/data/session-cookies.json
• Check logs: docker logs jumbo-api

⁠Container Won't Start

• Check port 8000 is available
• Verify Docker has enough resources
• Check logs for error messages

For more help, see API_README.md⁠