luobinger/PerkRadar

What it does

PerkRadar is a self-hosted dashboard that periodically pulls titles, links, and short summaries from a fixed set of public RSS, Atom, JSON, and Markdown feeds and stores them in a lightweight SQLite database. A web board lets you search, filter, sort, bookmark, and mark items as claimed. It targets people who want their own deal feed rather than relying on one shopping site.

It is a lead collector, not a claim-verification platform. Each record only means the source once returned that item; validity, eligibility, and stock are not checked, so the original page remains the authority.

Quick start

Requirements: Node.js 22 or newer (the project uses the built-in node:sqlite), npm, and Docker Desktop or a compatible Docker Compose environment (v2.24+) for the container route.

The recommended local path is Docker:

docker compose -p daily-free-info up -d --build

Then open http://127.0.0.1:38471/ or check health:

curl -sS http://127.0.0.1:38471/api/health

Data persists in ./data. The root .env is optional; set JINA_API_KEY only if you need Jina authentication, or point JINA_API_KEY_FILE at a mounted secret file. If the host port is taken, override only the host side with HOST_PORT=38481 docker compose -p daily-free-info up -d --build and open http://127.0.0.1:38481/.

For development use npm ci && npm run dev, then open the same port. The /demo layout preview is available only in development.

Sources and classification

Seven fixed sources are defined in source-defs.ts and cannot be replaced by callers: LINUX DO, V2EX promotions, Epic free games, NodeSeek, 小众软件, 果核剥壳, and 异次元软件世界. Combined RSS/Atom sources use a 7-day retention window and domain allowlists; Epic items expire at the end of the free promotion. Failures are isolated per source, requests time out after 25 seconds, and links are validated and normalized before storage.

Categories are assigned by title keywords, not human review, so a category is not proof of eligibility or authenticity. The default "all" view hides items classified as "other"; the toggle shows them without deleting records. See the data quality docs for source boundaries and acceptance rules.

Refresh and freshness

The scheduler runs inside the Node process: one fetch about 4 seconds after startup, then every 2 hours. Shutting down Docker or sleeping the machine stops fetching, and missed rounds are not backfilled. Manual refresh shares the same in-process lock, has a 60-second cooldown, and is limited to 8 triggers per IP per 10 minutes. Data older than 2.5 hours is marked stale and over 4 hours severely stale. PerkRadar sends no email or chat notifications itself.

A POST /api/refresh returns 200 on completion, 409 while a round is running, and 429 during cooldown or rate limiting.

Constraints and security

Bookmarks and claimed status live only in the browser's localStorage under daily-deals-personal-v1 and daily-deals-show-all-v1; clearing site data removes them. The refresh API has no authentication and relies on same-origin checks and rate limiting, so the app binds to 127.0.0.1 and should not be exposed publicly without a reverse proxy, TLS, authentication, and refresh access control. The production container runs as the non-root node user, so the host ./data must be writable by uid 1000. Back up the SQLite database consistently rather than copying only deals.db while running. The code is MIT-licensed, but source-site content and terms are not covered by that license.

HotRepo's take

PerkRadar entered HotRepo's new-project list on 2026-11-10 with 119 stars and 17 stars gained in the recorded one-hour window, no GitHub daily rank recorded. The repository is unusually explicit about its limits: source isolation, stale-data thresholds, keyword-only classification, and the unauthenticated refresh endpoint are all documented rather than glossed over. That candor makes the tool easier to evaluate, but the fixed seven-source list and title-match categories mean coverage is narrow by design, and the browser-only bookmarks won't follow you across devices.