(SP: 3) [Backend] add internal janitor (jobs 1-4), claim/lease + runbook

[liudmylasovetovs]

Description

This PR implements the Monobank internal janitor (tasks G0–G6) to keep Monobank payment state consistent and observable, without changing Stripe behavior.

Why:

• Provide a secure internal-only ops endpoint to run Monobank hygiene jobs.
• Ensure safe concurrency on Neon HTTP (no reliance on multi-statement transactions) via DB gating + claim/lease.
• Make needs_review visible via a stable aggregate report and structured logs.
• Ship an ops runbook + PowerShell sanity commands for operators.

---

Related Issue

Issue: #<issue_number>

---

Changes

• Added internal route POST /api/shop/internal/monobank/janitor with:
  • guardNonBrowserOnly protection
  • internal secret auth (x-internal-janitor-secret fallback x-internal-secret)
  • strict payload validation (unknown-field reject, limit clamp 1..500)
  • DB spam-guard using internal_job_state (429 with Retry-After)
  • stable response envelope and structured logs
• Implemented Monobank janitor jobs:
  • job1: reconcile stale active Monobank attempts via existing apply/state-machine logic
  • job2: finalize stuck creating attempts missing invoice/provider ref; release/restock once (idempotent)
  • job3: store-mode backfill for Monobank events using claim + ordered apply; reruns are noop
  • job4: needs_review hygiene report (aggregate-only, no IDs/PII) with stable report shape + slicing
• Added claim/lease mechanisms:
  • payment_attempts.janitor_claimed_until/by + index for janitor workers
  • Monobank events claim helper used by job3
• Added/updated docs:
  • docs/monobank-janitor-map.md (repo-backed fact map; no business-logic speculation)
  • docs/monobank-janitor.md (runbook: endpoint, auth, codes, env knobs, PowerShell examples, DEV/UAT/PROD guidance)
• Added/updated Vitest coverage for route + jobs + claim logic (idempotency and invariants preserved)

---

Database Changes (if applicable)

• Schema migration required
• Seed data updated
• Breaking changes to existing queries
• Transaction-safe migration
• Migration tested locally on Neon

Migration notes:

• Adds payment_attempts.janitor_claimed_until (timestamptz) and payment_attempts.janitor_claimed_by (text)
• Adds payment_attempts_janitor_claim_idx on (provider, status, janitor_claimed_until, updated_at)

---

How Has This Been Tested?

• Tested locally
• Verified in development environment
• Checked responsive layout (if UI-related)
• Tested accessibility (keyboard / screen reader)

Checklist

Before submitting

• Code has been self-reviewed
• No TypeScript or console errors
• Code follows project conventions
• Scope is limited to this feature/fix
• No unrelated refactors included
• English used in code, commits, and docs
• New dependencies discussed with team
• Database migration tested locally (if applicable)
• GitHub Projects card moved to In Review

---

Reviewers

• @ViktorSvertoka
• @AndrewMotko

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
devlovers-net	Ready	Preview, Comment	Feb 13, 2026 0:57am

[netlify]

✅ Deploy Preview for develop-devlovers ready!

Name	Link
🔨 Latest commit	be244cb
🔍 Latest deploy log	https://app.netlify.com/projects/develop-devlovers/deploys/698e76fe66440600089b7c4d
😎 Deploy Preview	https://deploy-preview-318--develop-devlovers.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

📝 Walkthrough

Walkthrough

Implements a comprehensive monobank payment cleanup system featuring a new internal API endpoint (/api/shop/internal/monobank/janitor) that dispatches four scheduled janitor jobs, database schema extensions to track payment attempt claims, and supporting server-side services to manage stale payment attempts and stored webhook events.

Changes

Cohort / File(s)	Summary
Monobank Janitor Endpoint frontend/app/api/shop/internal/monobank/janitor/route.ts	New POST endpoint with strict payload validation, time-constant secret authentication, origin guard, rate-limiting via database-backed gate, and delegation to four job runners (job1–4) with structured result reporting and comprehensive error handling.
Database Schema & Migration frontend/db/schema/shop.ts, frontend/drizzle/0013_monobank_janitor_claim_attempts.sql, frontend/drizzle/meta/_journal.json	Adds two new columns (janitorClaimedUntil, janitorClaimedBy) to payment_attempts table and a composite index for efficient querying of janitor candidates.
Monobank Janitor Services frontend/lib/services/orders/monobank-janitor.ts, frontend/lib/services/orders/monobank-events-claim.ts	Four job implementations for claiming and processing stale/unclaimed payment attempts (jobs 1–2), executing stored webhook events (job 3), and generating needs-review event reports (job 4); includes event claiming service with lease/expiration logic.
Monobank Webhook Updates frontend/lib/services/orders/monobank-webhook.ts	Centralizes restock handling with finalizeOutcomeWithRestock helper and adds applyStoredMonobankEvent for processing stored webhooks with consistent error handling across both paths.
Font Dependency Update frontend/app/layout.tsx, frontend/package.json	Replaces Next.js Google font builder with direct imports from Geist package; adds geist@^1.7.0 dependency.
Instrumentation Export frontend/instrumentation-client.ts	Exports onRouterTransitionStart bound to Sentry.captureRouterTransitionStart for router transition tracking.
Comprehensive Test Coverage frontend/lib/tests/shop/monobank-janitor-route-g1.test.ts, frontend/lib/tests/shop/monobank-janitor-job1.test.ts, frontend/lib/tests/shop/monobank-janitor-job2.test.ts, frontend/lib/tests/shop/monobank-janitor-job3.test.ts, frontend/lib/tests/shop/monobank-janitor-job4-needs-review.test.ts, frontend/lib/tests/shop/monobank-events-claim.test.ts	Test suites validating route behavior (auth, validation, rate-limiting, error responses), janitor job workflows (claiming, processing, idempotency, dry-run), and event claiming lease mechanics.

Sequence Diagram

sequenceDiagram
    actor Client
    participant Route as Janitor Route<br/>/api/shop/internal/monobank/janitor
    participant Auth as Auth & Validation
    participant Gate as Rate Limiter<br/>(DB Gate)
    participant Job as Janitor Job<br/>(Job 1-4)
    participant DB as Database
    participant Service as Invoice/Order<br/>Services

    Client->>Route: POST /api/shop/internal/monobank/janitor
    Route->>Auth: Validate secret & payload
    alt Invalid Auth/Payload
        Auth-->>Client: 401/400 Error
    else Valid
        Auth->>Gate: Check rate limit (DB next_allowed_at)
        alt Rate Limited
            Gate-->>Client: 429 Retry-After
        else Allowed
            Gate->>DB: Update next_allowed_at
            Route->>Job: Dispatch to Job 1-4
            Job->>DB: Query stale attempts/events
            Job->>Service: Get invoice status / Apply webhook
            Service->>DB: Update order/attempt state
            Job-->>Route: Return result<br/>(processed/applied/noop/failed)
            Route-->>Client: 200 OK with result
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~70 minutes

Possibly related PRs

• (SP: 3)[Backend][Shop][Monobank] Webhook apply hardening + safer cleanup (archive test products) #305 — Both PRs refactor and centralize monobank webhook handling by extracting restock logic into shared helpers and adding new entry points for stored event processing.

Suggested reviewers

• AM1007
• ViktorSvertoka

Poem

🐰 A janitor hops through payment claims,
Four jobs sweep the monobank frames,
Stale attempts now find their peace,
With rate limits and lease release,
Cleanup complete—no mess remains! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 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 (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding an internal janitor system with jobs 1-4 and claim/lease mechanisms for Monobank payment reconciliation, directly matching the substantial changes across route, services, schema, and tests.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into develop
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch lso/feat/shop

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: be244cb7c5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Claim stored monobank events instead of unapplied ones

Update the job3 claim predicate to target stored backlog rows, because claimNextMonobankEvent currently requires applied_at IS NULL while webhook store mode persists events with applied_result='stored' and a non-null applied_at. In production this means the janitor cannot claim the very events it is meant to backfill, so job3 reports no work and leaves store-mode payments unreconciled.

Useful? React with 👍 / 👎.