Metadata-Version: 2.4
Name: jed-api
Version: 0.1.0
Summary: JupiterEd message scraping CLI and importable Python library.
Project-URL: Homepage, https://github.com/x0rgo/jed-api
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: selenium==4.41.0
Requires-Dist: beautifulsoup4==4.14.3

# Jed API

CLI scraper for JupiterEd messages, including:
- full message content
- attachment links
- sender profile photo URL
- fast "check for new messages" mode

## Features

- Headless by default (no browser window).
- Optional headed mode for debugging (`--headed`).
- Filter scraping by newest count, days since, or date range.
- Detect new inbox messages with persistent state tracking.
- Optionally fetch full content for only new messages.
- JSON export support.

## Requirements

- Python 3.10+
- Google Chrome installed

Install dependencies:

```bash
pip install -r requirements.txt
```

Install as an importable package (recommended for using in other projects):

```bash
pip install -e .
```

## Configuration

Copy `config.example.json` to `config.json` in the project root, then fill in your values.

```json
{
  "name": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "school": "YOUR_SCHOOL",
  "city": "YOUR_CITY",
  "state": "YOUR_STATE",
  "school_id": "OPTIONAL"
}
```

`school_id` can exist in the file, but current CLI flow does not require it.
`config.json` is ignored by git to keep credentials out of the repository.

## Usage

```bash
python main.py [--headless|--headed] [--json-out FILE] <command> [options]
```

### Commands

- `newest <count>`: fetch newest N messages.
- `since <days> [--limit N]`: fetch messages from last N days.
- `range --from YYYY-MM-DD [--to YYYY-MM-DD] [--limit N]`: fetch messages in date range.
- `all [--limit N]`: fetch all available messages.
- `check-new [--state-file FILE] [--no-update] [--fetch]`: detect unseen inbox messages.

## Examples

Fetch newest 10:

```bash
python main.py newest 10
```

Fetch last 7 days, save JSON:

```bash
python main.py since 7 --json-out messages.json
```

Check for new messages only:

```bash
python main.py check-new
```

Check for new messages and fetch full details for those new ones:

```bash
python main.py check-new --fetch --json-out new_messages_full.json
```

Use visible browser window (debug mode):

```bash
python main.py --headed check-new --fetch
```

## Library Usage

```python
from jed_api import JupiterEdClient

with JupiterEdClient(config_path="config.json", headless=True) as client:
    messages = client.newest(5)
    print(messages[0]["subject"] if messages else "No messages")
```

Check for new messages and fetch full content:

```python
from jed_api import JupiterEdClient

with JupiterEdClient(config_path="config.json") as client:
    result = client.check_new_messages(fetch=True)
    print("new:", len(result["new_messages"]))
```

Use direct credentials instead of `config.json`:

```python
from jed_api import JupiterEdClient

credentials = {
    "name": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "school": "YOUR_SCHOOL",
    "city": "YOUR_CITY",
    "state": "YOUR_STATE",
}

with JupiterEdClient(credentials=credentials, headless=True) as client:
    data = client.since(7, limit=20)
```

## New Message State File

`check-new` stores seen message keys in `message_state.json` by default.

- First run: most/all inbox messages may be marked as new.
- Later runs: only unseen messages are returned.
- Use `--no-update` to test without modifying state.

## Output Format

Scraped message JSON objects include:

- `time`
- `parsed_time`
- `sender`
- `sender_pfp`
- `subject`
- `recipients`
- `body`
- `attachments` (list of `{name, url}`)
- `url`

## Notes

- This project uses Selenium and website UI behavior can change over time.
- Keep credentials private. Do not commit real credentials to GitHub.
