Extract admin webhook helpers

[liangtovi-debug]

Summary

• Extract admin webhook event listing, filtering, serialization, and status summary helpers from app/main.py into app/admin.py.
• Keep the admin API/page route behavior delegated through the same database session boundary while moving query and response-shaping details out of the route layer.
• Add focused helper regression coverage for status normalization, event ordering/serialization, and admin scan-order summaries.

Evidence

• Confusion, missing step, stale example, or bug this addresses: Bounty MRWK bounty: code health and app.main expansion readiness #320 asks for code-health extraction work that makes app/main.py easier to expand. This PR targets the admin webhook boundary, distinct from the accepted MCP/public-serializer work and the currently held bounty-attempt/auth PRs.

Test Evidence

• ruff format --check .
• ruff check .
• mypy app
• pytest
• python scripts/docs_smoke.py (docs, template, example, or onboarding changes)

Validation run after rebasing on current upstream main:

• uv run --extra dev ruff format --check . -> 48 files already formatted.
• uv run --extra dev ruff check . -> All checks passed.
• uv run --extra dev python -m mypy app -> Success: no issues found in 14 source files.
• uv run --extra dev python -m pytest -q -> 329 passed.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check upstream/main...HEAD -> clean.

MRWK

Related bounty or issue (Bounty #N or Refs #N for multi-award bounties): Bounty #320

No secrets, wallet private keys, payout credentials, private vulnerability details, deployment values, or MRWK price claims are included.

Summary by CodeRabbit

• Refactor

  • Reorganized webhook event management logic for improved code maintainability and modularity.

• Tests

  • Added comprehensive test coverage for webhook event helpers including filtering, listing, and status aggregation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4b7373d4-c4c3-4215-92a2-a0a0ad68ff7e

📥 Commits

Reviewing files that changed from the base of the PR and between cb11a80 and 6578bbf.

📒 Files selected for processing (3)

• app/admin.py
• app/main.py
• tests/test_admin_helpers.py

---

📝 Walkthrough

Walkthrough

Webhook event administration logic (filtering, listing, aggregating) is extracted from app/main.py into a new app/admin.py module. The main application file is refactored to import and call these helpers, removing local implementations and simplifying both the REST endpoint and the admin UI webhook-filtering path.

Changes

Webhook Admin Utilities Extraction

Layer / File(s)	Summary
Webhook admin helpers module app/admin.py	New module defines WEBHOOK_OUTCOME_SCAN_ORDER rank mapping, normalize_webhook_status_filter for case-insensitive filtering, list_webhook_events to query with ordering and limits, serialization helpers (webhook_event_to_dict, webhook_events_to_dict), and webhook_status_summary to aggregate and sort counts by custom scan order.
Refactor main.py to use admin helpers app/main.py	Imports webhook helpers from app.admin, removes WEBHOOK_OUTCOME_SCAN_ORDER constant and local webhook_status_summary implementation, removes WebhookEvent from model imports, and updates the /api/v1/admin/webhook-events endpoint and /admin page webhook filtering to call list_webhook_events and related helpers instead of inline SQL construction.
Test coverage for admin webhook helpers tests/test_admin_helpers.py	Adds factory (_event) and three test functions covering status normalization, event listing with serialization and ordering, and status summary aggregation with correct custom scan-order sorting.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ramimbo/mergework#309: Both PRs implement the admin webhook-events listing (filtering/ordering/serialization) in app/main.py, with the main PR refactoring that endpoint's logic into new app/admin.py helper functions.
• ramimbo/mergework#318: Both PRs change the /admin webhook outcomes UI logic to normalize webhook_status, query WebhookEvent by processed_status, order by created_at/delivery_id, and apply a limit (main PR refactors that same behavior into app/admin.py helpers).
• ramimbo/mergework#331: The main PR refactors the same webhook status summary logic from app/main.py into app/admin.py by moving WEBHOOK_OUTCOME_SCAN_ORDER and webhook_status_summary(...) (and updating call sites/templates accordingly), so it directly overlaps with PR #331's introduced summary functionality.

Suggested reviewers

• g8rr5dg2p7-svg
• weilixiong
• ayskobtw-lil

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Extract admin webhook helpers' clearly and concisely summarizes the main change: moving webhook helper functions from app/main.py to app/admin.py.
Description check	✅ Passed	The PR description is complete and follows the template, providing clear summary, evidence linking to Bounty #320, comprehensive test validation results, and confirming no sensitive data is included.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[TateLyman]

Reviewed the admin webhook helper extraction for Bounty #320.

What I checked:

• app/admin.py: status normalization, admin webhook event query/filter/order, safe event serialization, and status summary scan ordering.
• app/main.py: admin API and admin page routes now delegate to the helper module while preserving the same session boundary, admin-token/cookie auth boundaries, limit handling, and template data shape.
• tests/test_admin_helpers.py: focused coverage for trimming/lowercasing filters, case-insensitive filtering, newest-first event ordering, safe serialized fields, and status-summary ordering.
• tests/test_security.py: existing admin page/API behavior still exercises the routed surface with real WebhookEvent rows.

Validation run locally:

• uv run --extra dev python -m pytest tests/test_admin_helpers.py tests/test_security.py -q -> 56 passed.
• uv run --extra dev python -m pytest -q -> 329 passed.
• uv run --extra dev ruff check app/admin.py app/main.py tests/test_admin_helpers.py -> passed.
• uv run --extra dev ruff format --check app/admin.py app/main.py tests/test_admin_helpers.py -> passed.
• uv run --extra dev python -m mypy app/admin.py app/main.py -> passed.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.

Hosted quality check is green and GitHub reports mergeState CLEAN. No blockers from my pass.