Fix docs accuracy + two real bugs found while verifying them - #2
Merged
Merged
Conversation
Asked to confirm README/CHANGELOG are up to date; while checking each
claim against the actual code, found and fixed two functional bugs:
- web/app.py's home page 500'd on every load (TypeError: cannot use
'tuple' as a dict key) — templates.TemplateResponse("index.html",
{"request": request}) is the old, removed Starlette calling
convention on the pinned starlette version. Fixed to
TemplateResponse(request, "index.html").
- The dashboard's own frontend called every /api/* endpoint with a
bare fetch(), so the X-API-Key requirement added in the previous
round of fixes broke the built-in UI (401 on every button and the
initial status load). Added an apiFetch() wrapper that prompts for
the key once, stores it in localStorage, and re-prompts on 401.
Verified the full flow (200 with correct key, 401 + cleared storage
on wrong key) via a live preview server.
- python-dotenv was declared as a dependency but never actually
loaded, so `cp .env.example .env` silently did nothing for a plain
`python web/app.py` run (only docker-compose substitutes .env).
Added load_dotenv() on startup.
Then fixed what was actually stale in the docs:
- All three install paths in README told users to "edit .env with
your Telegram API credentials" — .env only ever holds web-dashboard
settings (API_KEY/WEB_HOST/WEB_PORT); credentials are entered
interactively and stored in resources/credentials.json. Corrected
each path and added notes that the web dashboard / Docker web
service need a session created by running `python main.py` once.
- `## Changelog Policy` sat between two subsections of `## Usage`,
making `### Web API` read as its child. Moved it under
`## Contributing`, restored `### Web API` under `## Usage`, and
documented the new X-API-Key requirement there.
- Added docs/ and tests/ to the project tree, plus "Running Tests and
Checks" and "Building Documentation" subsections matching what CI
actually runs.
Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #1 (merged). While confirming the README/CHANGELOG were up to date against the current code, found and fixed two real functional bugs, plus corrected several stale doc claims:
Bugs found while verifying docs:
web/app.py's home page 500'd on every load (TypeError: cannot use 'tuple' as a dict key) —templates.TemplateResponse("index.html", {"request": request})is the old, removed Starlette calling convention on the pinned version. Fixed toTemplateResponse(request, "index.html")./api/*endpoint with a barefetch(), so theX-API-Keyauth requirement added in Fix broken reply-history mapping; harden web dashboard #1 broke the built-in UI (401 on every button and the initial status load). Added anapiFetch()wrapper that prompts for the key once, stores it inlocalStorage, and re-prompts on 401. Verified the full flow live (200 with correct key, 401 + cleared storage on wrong key).python-dotenvwas a declared dependency that nothing ever called —cp .env.example .envhad no effect on a plainpython web/app.pyrun. Addedload_dotenv()on startup.Docs corrected:
.envwith your Telegram API credentials" —.envonly ever holds web-dashboard settings; credentials are entered interactively and stored inresources/credentials.json. Corrected each path and noted the web dashboard/Dockerwebservice need a session from runningpython main.pyonce first.## Changelog Policysat between two subsections of## Usage, making### Web APIread as its child. Moved it under## Contributing, restored### Web APIunder## Usage, documented theX-API-Keyrequirement there.docs/andtests/to the project tree, plus "Running Tests and Checks" / "Building Documentation" subsections matching what CI actually runs.Test plan
ruff check/ruff format --check— cleanmypy source/ web/app.py— cleanpytest tests/— 16/16 passapiFetchcorrectly attachesX-API-Key(200 with correct key, 401 + key cleared on wrong key)