# Cantaloupe Downloader — Agent Guide

CLI tool for exporting machine list data (Excel .xlsx) from mycantaloupe.com. Used as the upstream data source for the Canteen asset tracking pipeline.

## Stack

- **Python** 3.11+, **click** (CLI framework)
- **httpx** (async HTTP client with anti-forgery token handling)
- **playwright** (browser automation fallback for JS challenges)
- **openpyxl** (Excel file reading)
- **respx** / **pytest** (testing)

## Project Structure

```
cantaloupe/
  __init__.py
  __main__.py       # Entry: python -m cantaloupe
  cli.py             # Click CLI: export, diff, configure commands
  config.py          # Config file management (~/.cantaloupe.env)
  diff.py            # Compare two Excel exports

src/
  auth.py            # Login: httpx anti-forgery token or Playwright fallback
  download.py        # Export POST → save .xlsx

tests/
  test_auth.py
  test_cli.py
  test_diff.py
  test_download.py

API.md               # API investigation notes
README.md
requirements.txt
```

## How to Run

```bash
# Export machines list
python -m cantaloupe export

# With scheduled-output path
python -m cantaloupe export --scheduled

# Compare two exports
python -m cantaloupe diff file1.xlsx file2.xlsx

# Configure credentials
python -m cantaloupe configure
```

## Key Architecture

- **Two auth strategies:**
  1. **Primary:** httpx — anti-forgery token extraction from HTML, form-based login
  2. **Fallback:** Playwright — full browser automation for JS challenges
- Config stored in `~/.cantaloupe.env` (credentials)
- Exports go to `~/cantaloupe-exports/` with manifest tracking via `manifest.json`
- `diff` command compares two exports cell-by-cell

## Production

- **CLI tool only** — no server, no systemd
- Triggered via cron: `cantaloupe-sync.sh` runs every 6 hours
- Part of the Canteen pipeline: Cantaloupe → downloader → sync API

## Environment Variables

| Var | Description |
|-----|-------------|
| CANTALOUPE_EMAIL | Login email |
| CANTALOUPE_PASSWORD | Login password |
| CANTALOUPE_OTP_SECRET | Optional TOTP secret for 2FA |

## Pitfalls

- Cantaloupe may show JS challenges — Playwright fallback handles this but requires browser binaries (`playwright install chromium`)
- Export format may change on Cantaloupe's side (they're a third-party SaaS) — `diff.py` detects structural changes
- Auth tokens expire; each run re-authenticates