whatseerr - Moses Yebei

The Problem

Self-hosted media request tools like Jellyseerr/Overseerr force users into a web UI. For households or communities where WhatsApp is the primary communication channel, that's a barrier — requests don't get made, or they get made through a middleman. Whatseerr bridges that gap by turning WhatsApp messages into Seerr API calls.

What This Does

Whatseerr is a Node.js/Express bot that listens to WhatsApp messages through a WAHA HTTP API session, queries a Seerr (Jellyseerr/Overseerr) instance, presents numbered search results, and submits the user's selection as a media request. It also receives Seerr webhook notifications and forwards them into WhatsApp chats.

The core flow lives in lib/commands/search-command.js and lib/commands/selection-command.js — search, show numbered results, wait for a number reply, submit. lib/request.js wraps the Seerr API (search, details, create request, approve). lib/waha-client.js wraps the WAHA API for sending messages and resolving phone numbers to session IDs. lib/webhook-helpers.js (1,034 lines) formats Seerr notification payloads.

How It Is Wired

Execution starts at main in cli.js:39, which loads config (loadConfig in lib/utils.js, reading the filesystem via fs.readFileSync), then starts the Express server (createServer in lib/server.js). Incoming WhatsApp webhooks hit taskFn (lib/server.js:205), which routes through handleMessage → getPhoneNumberByLid — an outbound network call to WAHA — in as few as three hops from entry.

The command system is a registry (lib/commands/index.js) with BaseCommand subclasses: AgentCommand, ApprovalCommand, SearchCommand, SelectionCommand, SubscriptionsCommand. execute in agent-command.js is the largest reachable function (99 functions) and calls sendMessage and getErrorDetails 24 times each.

Two things matter for anyone changing this code:

lib/errors/error-formatter.js is a hub: 14 modules import getErrorDetails, and it's called from 29 places. Changes there ripple everywhere.
lib/utils.js and lib/waha-client.js participate in a circular import. Both are heavily imported (11 and 10 dependents respectively). Breaking that cycle should be a priority before any large refactor.

File map by responsibility: lib/request.js owns all Seerr API calls; lib/waha-client.js owns WhatsApp transport; lib/state/cache-state.js holds per-user search results between the search and selection steps; lib/queue/message-queue.js serializes outbound messages per user; lib/subscriptions/subscription-manager.js persists chat subscriptions to disk.

How To Use It

Docker is the supported path:

docker pull ghcr.io/sufxgit/whatseerr:latest

Configuration lives in a config.json mounted at /config. On first run a config.example.json is copied there. Required settings: jellyseerr.apiKey, waha.apiKey, host, and userIdMappings (WhatsApp phone number → Seerr user ID). Point the WAHA session webhook at http://YOUR_HOST:3006/requests, and optionally the Seerr webhook at http://YOUR_HOST:3006/seerr. Send r The Matrix from WhatsApp; reply with a number to confirm.

Code Health & Issues

Static analysis found 22 findings (3 high, 19 medium) across 6 kinds. The high-severity items: a circular import between lib/utils.js and lib/waha-client.js, and 28 duplicated 6-line code blocks across cli.js, lib/request.js, lib/commands/search-command.js, and lib/commands/selection-command.js. Medium findings include high branching density in lib/request.js (249 branch points over 575 lines), the error-formatter.js hub module, and deep nesting in lib/season-utils.js (depth 6).

The code health audit adds: High — GitHub Actions pinned to mutable tags (docker/setup-buildx-action@v3, etc.) instead of commit SHAs; High — no test suite at all (37 source files, zero tests); Medium — no Dependabot/Renovate, unpinned node:20-alpine base image, no dependency vulnerability scan in CI, no non-root USER in the Dockerfile; Low — no timeout-minutes on workflow jobs.

The Bottom Line

The architecture is sound for a bot of this scope: clean command separation, a queue for outbound messaging, and sensible state management. The absence of tests and the circular dependency are real liabilities — any refactor of the messaging or request paths will be done blind. Suitable for a small community or household that lives in WhatsApp and runs Jellyseerr; not something to build a large multi-tenant deployment on without addressing the test gap first.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

53 files

JavaScript37
Markdown3
JSON3
YAML2

ReactExpressDocker

Module dependencies

The 10 most depended-upon modules of 37, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_lib_errors_error_formatter["error-formatter"] n1_lib_request["request"] n2_lib_utils["utils"] n3_lib_waha_client["waha-client"] n4_lib_constants["constants"] n5_lib_state_cache_state["cache-state"] n6_lib_commands_base_command["base-command"] n7_iptions_subscription_manager["subscription-manager"] n8_lib_message_formatters["message-formatters"] n9_lib_logger["logger"] n8_lib_message_formatters --> n4_lib_constants n8_lib_message_formatters --> n1_lib_request n1_lib_request --> n2_lib_utils n1_lib_request --> n0_lib_errors_error_formatter n1_lib_request --> n4_lib_constants n7_iptions_subscription_manager --> n2_lib_utils n7_iptions_subscription_manager --> n0_lib_errors_error_formatter n7_iptions_subscription_manager --> n1_lib_request n2_lib_utils --> n9_lib_logger n2_lib_utils --> n3_lib_waha_client n2_lib_utils --> n0_lib_errors_error_formatter n3_lib_waha_client --> n2_lib_utils n3_lib_waha_client --> n0_lib_errors_error_formatter classDef cyc stroke:#ef4444,stroke-width:2px; class n2_lib_utils,n3_lib_waha_client cyc;

Findings

MediumNo test files detected - untested code paths repository-wide

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium4

low1

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

docker/setup-buildx-action@v3, docker/login-action@v3, docker/metadata-action@v5, docker/build-push-action@v5

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a test suite; this repository has nonehigh37 occurrences

37 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

node:20-alpine

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow

.github/workflows/docker-publish.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.