TGTG Scanner

TGTG Scanner observes your favorite TGTG Magic Bags for new available items and notifies you via mail, IFTTT, Telegram, pushSafer or any other WebHook. Notifications will be send when the available amount of Magic Bags rises from zero to something.

Additionally the currently available amounts can be provided via a http server.

Running in a docker container the scanner can be seamlessly integrated with OpenHab, Prometheus and other automation, notification and visualization services.

This software is provided as is without warranty of any kind. If you have problems, find bugs or have suggestions for improvement feel free to create an issue or contribute to the project. Before creating an issue please refer to the FAQ.

Disclaimer

Too Good To Go explicitly forbids the use of their platform the way this tool does. In their Terms and Conditions it says: "The Consumer must not misuse the Platform (including hacking or 'scraping')."

If you use this tool you do it at your own risk. TGTG may stop you from doing so by (temporarily) blocking your access and may even delete your account.

Error 403

If you see the Error 403 in your logs please refer to the FAQ.

Installation

You can install this tool on any computer. For 24/7 notifications I recommended to install the tool on a NAS like Synology or a Raspberry Pi. You can also use a virtual cloud server. Starting at 1,00 €/Month at Strato.de or try AWS free tier.

If you have any problems or questions feel free to create an issue.

You have the following three options to install the scanner, ascending in complexity:

Use prebuild Release

This is the simplest but least flexible solution suitable for most operating systems.

Download latest Releases for your OS
Unzip the archive
Edit config.ini as described in the file
Run scanner

You can run the scanner manually if you need it, add it to your system startup or create a service.

The executables for Windows and MacOS are not signed by Microsoft and Apple, which would be very expensive. On Mac you need to hold the control key while opening the file and on Windows you need to confirm the displayed dialog.

Run with Docker

My preferred method for servers using the pre build multi-arch linux images available on Docker Hub.

Install Docker and docker-compose
Copy and edit docker-compose.yml as described in the file
Run docker-compose up -d

The container creates a volume mounting \tokens where the app saves the TGTG credentials after login. These credentials will be reused on every start of the container to avoid the mail login process. To login with a different account you have to delete the created volume.

Run from source

Method for developers.

Install Python>=3.9 and pip
Run pip install -r requirements.txt
Create src/config.ini as described in the file config.template.ini
Run python src/main.py

Alternatively you can use environment variables as described in the sample.env file. The scanner will look for environment variables if no config.ini is present.

Running

When the scanner is started it will first try to login to your TGTG account. Similar to logging in to the TGTG app, you have to click on the link send to you by mail. This won't work on your mobile phone if you have installed the TGTG app, so you have to check your mailbox on PC.

After a successful login the scanner will send a test notification on all configured notifiers. If you don't receive any notifications, please check your configuration.

Metrics

Enabling the metrics option will expose a http server on the specified port supplying the currently available items. You can scrape the data with prometheus to create and visualize historic data or use it with your home automation.

Scrape config:

  - job_name: 'TGTG'
    scrape_interval: 1m
    scheme: http
    metrics_path: /
    static_configs:
    - targets:
      - 'localhost:8000'

Developing

For development I recommend using docker. The Makefile depends on docker and docker-compose.

Create .env based on sample.env for configuration.

Developing with VSCode you can open the project in the configured development container.

Makefile commands

make image builds docker image with tag tgtg-scanner:latest

make install installs dependencies

make start short for python src/main.py

make bash starts dev python docker image with installed dependencies and mounted project in bash

make executable creates bundled executable in /dist

make test runs unit tests

make clean cleans up docker compose

Helper functions

src/main.py contains some useful helper functions that can be accessed via optional command line arguments. Running python src/main.py --help displays the available commands.

usage: main.py [-h] [-v] [-d] [-t] [-f] [-F] [-a item_id [item_id ...]] [-r item_id [item_id ...]] [-R]

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -d, --debug           activate debugging mode
  -t, --tokens          display your current access tokens and exit
  -f, --favorites       display your favorites and exit
  -F, --favorite_ids    display the item ids of your favorites and exit
  -a item_id [item_id ...], --add item_id [item_id ...]
                        add item ids to favorites and exit
  -r item_id [item_id ...], --remove item_id [item_id ...]
                        remove item ids from favorites and exit
  -R, --remove_all      remove all favorites and exit

Creating new notifiers

Feel free to create and contribute new notifiers for other services and endpoints. You can use an existing notifier as template.

If you want to support me, feel free to buy me a coffee.

p0lycarpio/tgtg