HipLeech

Downloads grade information from a given cevex Home.InfoPoint website. As a parent, you have to login manually and check for new grades every now and then. This is tedious, especially with several kids. This program automates the process and allows you to poll the site frequently. If new grades are posted, it can post a notification to a Telegram channel.

This is an example of HipLeech in action. The new grades are shown, as well as the average grade per course and the average of all courses in the current semester.

Requirements

• Swift 6.0 or later
• macOS 13+ or Linux

Building

• Clone this repo from GitHub
• Install the latest Swift toolchain from https://www.swift.org/download/
• Make sure swift is in your path. It's usually something like /home/user/swift-6.0-RELEASE-ubuntu20.04/usr/bin (depends on where you installed the Swift toolchain)

Debug Build

swift build

The binary can be found at:

• macOS: .build/debug/HipLeech
• Linux: .build/x86_64-unknown-linux-gnu/debug/HipLeech

Release Build (Recommended for Production)

swift build -c release

The optimized binary can be found at:

• macOS: .build/release/HipLeech
• Linux: .build/x86_64-unknown-linux-gnu/release/HipLeech

Running

You have to run HipLeech frequently to detect new grades. This example fetches the grades for two students from the same school (the URL is the same).

Note: For production use, copy the release binary to a convenient location:

cp .build/release/HipLeech /home/melle/bin/HipLeech
# or on macOS: cp .build/release/HipLeech /usr/local/bin/HipLeech

Example script for polling grades:

#!/bin/sh
/home/melle/bin/HipLeech \
   Kid1 username1 password1 \
   "https://www.name-of-the-school.de/homeInfoPoint/" \
   --previous-state /home/melle/tmp/hipleech-previous-kid1.json \
   --output markdown \
   --telegram "telegramToken+chatID"

/home/melle/bin/HipLeech \
   Kid2 username2 password2 \
   "https://www.name-of-the-school.de/homeInfoPoint/" \
   --previous-state /home/melle/tmp/hipleech-previous-kid2.json \
   --output markdown \
   --telegram "telegramToken+chatID"

Please note that --previous-state /home/melle/tmp/hipleech-previous-kid1.json saves the last known grades. The file location has to be unique per student. On the first launch, the file does not exist and all grades are reported as new. On the next launch, only the difference between the saved state and the website is reported.

In order to receive notifications, create a Telegram channel and add the contacts that should be notified about new grades, like your kids. See this Stack Overflow post on how to obtain the chat ID of that channel.

Put this in your crontab to query the portal every 20 minutes:

*/20    *       *       *       *       /home/melle/bin/hipleech.sh

Usage

OVERVIEW: Grade information from a given cevex Home.InfoPoint website.

Fetches grade information and can format output as ASCII, JSON, or Markdown.
If a JSON file with previous grade information is provided, only the diff
between the old and current state is returned. Supports sending notifications
via Telegram bot.

USAGE: HipLeech <nickname> <username> <password> <url> [--output <output>] [--input <input>] [--previous-state <previous-state>] [--telegram <telegram>]

ARGUMENTS:
  <nickname>              Nickname used in the report (helps distinguish
                          multiple reports)
  <username>              Username provided by the school
  <password>              Password provided by the school
  <url>                   Home.InfoPoint URL (e.g.,
                          https://www.school.de/homeInfoPoint/)

OPTIONS:
  -o, --output <output>   Output format: ascii, json, or markdown (default:
                          ascii)
  -i, --input <input>     Input format: grades or points (default: grades)
  -p, --previous-state <previous-state>
                          Path to previous state JSON file
  -t, --telegram <telegram>
                          Telegram API token and chat ID, joined by + (e.g.,
                          123456:ABC+789)
  -h, --help              Show help information.