repository·main·Indexed 43 days ago
https://github.com/eikowagenknecht/lootscraperA tool to automatically find and notify users about free games and in-game loot across platforms like Epic Games, Steam, and Amazon Prime. It provides notifications via a Telegram bot, dedicated Telegram channels, and RSS feeds, as well as a web interface for browsing current and historical offers. Version 2.15.0 supports local installation via Node.js 22+ or deployment as a Docker container.
If you prefer pre-filtered notifications without managing a bot, you can join specific Telegram channels for different platforms:
To use Telegram notifications, follow these steps:
/create command, and follow the instructions to get an access token./debug command to the public Telegram LootScraperBot to retrieve it.Configuration Keys:
DeveloperChatId: The ID where Telegram-related errors will be sent.The Telegram bot is the recommended way to receive personalized notifications for specific platforms. You can manage which platforms you want to hear about directly through the bot interface.
@LootScraperBot in Telegram./start to initialize the bot./manage to select your preferred platforms./help to view all available commands.The bot will send messages whenever new free games or loot are detected on your selected platforms. You can also add the bot to your own groups or channels.
To make the process of claiming free games easier once you receive a notification, you can use userscripts compatible with Tampermonkey, Greasemonkey, or Violentmonkey.
Detailed instructions and the scripts can be found at: https://eikowagenknecht.com/posts/userscripts-to-claim-free-games/
You can run LootScraper using Docker. You can either build it yourself from the source or use the pre-built image from Docker Hub (eikowagenknecht/lootscraper:main).
Building from source
docker build . -t eikowagenknecht/lootscraper:develop./data directory for persistence):
docker run --volume "${PWD}/data:/data" --name lootscraper eikowagenknecht/lootscraper:develop
(Add --detach to run in the background)Managing the container
docker stop lootscraperdocker container rm lootscraperdocker logs -f lootscraperDebugging
To explore the container environment without running the scraper:
docker run -it --entrypoint /bin/bash --volume "${PWD}/data:/data" --name lootscraper_debug eikowagenknecht/lootscraper:develop
# Build
docker build . -t eikowagenknecht/lootscraper:develop
# Run
docker run --volume "${PWD}/data:/data" --name lootscraper eikowagenknecht/lootscraper:developTo run LootScraper on your own machine, ensure you have Node.js 22+ installed. Follow these steps:
pnpm install.playwright install firefox.Development Mode Run the application in development mode using:
pnpm run devProduction Mode To run in production, build the project first, then start it:
pnpm run build
pnpm run start# Install dependencies
pnpm install
# Install browser
playwright install firefox
# Run dev
pnpm run devThe Discord bot posts offers to dedicated channels with rich embeds and claim buttons.
bot, applications.commandsManage Channels, View Channels, Send Messages, Embed LinksEnable Developer Mode in Discord (User Settings $\rightarrow$ Advanced $\rightarrow$ Developer Mode) to easily copy IDs:
guildId).adminRoleId).Add the following to your configuration file:
actions:
discordBot: true
discord:
botToken: "your-bot-token-here"
guildId: "your-server-id"
adminRoleId: "" # Optional
channelPrefix: "" # Optional: e.g., "loot-"
categoryName: "Free Games" # Category to organize channels under/status: Show bot stats, feed channels, and upcoming scrapes./scrapenow: Trigger the scraper (Admin only)./populate: Backfill all channels with current active offers (Admin only).actions:
discordBot: true
discord:
botToken: "your-bot-token-here"
guildId: "your-server-id"
adminRoleId: ""
channelPrefix: ""
categoryName: "Free Games"If you prefer browsing manually without push notifications, you can view current and historical offers on dedicated web pages.
View the latest deals for specific platforms or all sources on one page:
To see all discovered offers (including expired ones), use the archive versions. Note that these pages can be large and slow to load:
When scrape() is called, the data flows through a standardized pipeline to ensure quality:
readOffers() fetches raw data.cleanOffers() trims whitespace from URLs and image URLs.deduplicateOffers() removes entries with identical titles.categorizeOffers() identifies if an offer is a DEMO, PRERELEASE, or VALID based on the title.filterForValidOffers() removes any offers that were categorized as non-valid (like demos or prereleases) if the scraper is configured to only return valid offers.On the first startup, LootScraper creates a default configuration file at ./data/config.toml. You can edit this file to:
After editing the file, you must restart the application for changes to take effect.
The application is designed to catch unhandled exceptions during the main execution loop. When an error occurs, the system performs the following sequence:
handleError(error) to process and log the error.shutdownApp() to ensure all services (database, etc.) are closed gracefully.1.LootScraper uses a centralized configuration system and a logger that can be controlled via the application configuration.
common.logLevel key in your configuration. You can use updateConsoleLevel to change the console output level and addFileTransport to direct logs to a file specified by common.logFile.DEBUG environment variable is set, the application will log its value during initialization.UTC as the default timezone and en-US as the default locale for consistent date handling across all services.// Example of how the application handles environment and config internally:
// (Note: These are internal initialization steps exposed via the core logic)
// Set log level from config
updateConsoleLevel(cfg.common.logLevel);
addFileTransport(cfg.common.logLevel, cfg.common.logFile);
// Debugging via environment variable
if (process.env.DEBUG) {
logger.info(`DEBUG env is set to ${process.env.DEBUG}.`);
}