feat(admin): add admin invoice listing and detail endpoints

[soomtochukwu]

Summary

Closes #43

Introduces cross-merchant admin invoice visibility endpoints for the admin dashboard.

Details

1. New Endpoints

• GET /api/v1/admin/invoices:
  • Protected behind authenticateAdmin.
  • Supports query filtering by merchantAddress (via joined relation on merchant.address) and status (reusing existing InvoiceStatus enum).
  • Paginated using standard DEFAULT_LIMIT (20) / MAX_LIMIT (100) conventions with default ordering by createdAt desc (and id desc tiebreaker).
• GET /api/v1/admin/invoices/:id:
  • Protected behind authenticateAdmin.
  • Returns full invoice details unscoped by merchant ownership.
  • Returns 404 when the invoice does not exist.

2. Validation & Services

• Added parseAdminInvoiceListQuery in src/utils/invoice.validation.ts.
• Added listAdminInvoices and getAdminInvoice in src/services/invoice.services.ts.
• Added listAdminInvoicesController and getAdminInvoiceController in src/controllers/admin-invoice.controllers.ts.
• Mounted invoiceRoutes in src/routes/admin/index.ts.

3. Tests & Verification

• Unit tests: tests/unit/admin-invoice.validation.test.ts & tests/unit/invoice.services.test.ts
• Integration tests: tests/integration/admin.invoices.routes.test.ts
• Full checks passed: npm run check and npm test (48 test suites, 430 tests passing).

Summary by CodeRabbit

• New Features

  • Added admin invoice listing with status and merchant-address filters, pagination, and newest-first ordering.
  • Added admin invoice detail retrieval by invoice ID.
  • Secured invoice endpoints with admin authentication.
  • Added validation with clear errors for invalid query parameters.

• Bug Fixes

  • Missing invoices now return a 404 response.
  • Unexpected service failures return a 500 response.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a89009ec-2a86-40ae-a112-111c8c89092a

📥 Commits

Reviewing files that changed from the base of the PR and between 8c09acf and 0a42861.

📒 Files selected for processing (8)

• src/controllers/admin-invoice.controllers.ts
• src/routes/admin/index.ts
• src/routes/admin/invoice.routes.ts
• src/services/invoice.services.ts
• src/utils/invoice.validation.ts
• tests/integration/admin.invoices.routes.test.ts
• tests/unit/admin-invoice.validation.test.ts
• tests/unit/invoice.services.test.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR adds authenticated admin invoice list and detail endpoints. It supports status and merchant-address filters, pagination, cross-merchant retrieval, validation errors, application error mapping, and integration and unit tests.

Changes

Admin invoice endpoints

Layer / File(s)	Summary
Admin invoice query contracts src/utils/invoice.validation.ts, tests/unit/admin-invoice.validation.test.ts	Adds admin invoice filter types and query parsing for status, merchant address, limit, and offset. Tests cover normalization, clamping, and validation errors.
Cross-merchant invoice services src/services/invoice.services.ts, tests/unit/invoice.services.test.ts	Adds invoice listing across merchants with status, merchant-address, pagination, and ordering support. Adds invoice retrieval by ID with 404 handling.
Authenticated HTTP endpoints src/controllers/admin-invoice.controllers.ts, src/routes/admin/invoice.routes.ts, src/routes/admin/index.ts	Adds list and detail controllers, shared error handling, authenticated GET routes, and /admin/invoices router mounting.
Endpoint integration validation tests/integration/admin.invoices.routes.test.ts	Tests authentication, filtering, pagination, validation failures, detail retrieval, 404 responses, and database errors.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 0a428

The PR adds authenticated admin invoice listing and detail endpoints with validation, pagination, filtering, and reported passing checks; no actionable merge-blocking risk remains beyond normal review.

Suggested reviewers: g-elm

Sequence Diagram(s)

sequenceDiagram
  participant AdminClient
  participant authenticateAdmin
  participant AdminInvoiceController
  participant InvoiceServices
  participant Prisma

  AdminClient->>authenticateAdmin: Request admin invoice endpoint
  authenticateAdmin->>AdminInvoiceController: Forward authenticated request
  AdminInvoiceController->>InvoiceServices: Parse input and call invoice service
  InvoiceServices->>Prisma: Query invoices or invoice by ID
  Prisma-->>InvoiceServices: Return records or not found
  InvoiceServices-->>AdminInvoiceController: Return sanitized data or error
  AdminInvoiceController-->>AdminClient: Return HTTP response

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: admin invoice listing and detail endpoints.
Linked Issues check	✅ Passed	The changes implement issue #43: authenticated cross-merchant invoice listing with merchantAddress and status filters, pagination, default newest-first ordering, unscoped detail retrieval, 404 handlin…
Out of Scope Changes check	✅ Passed	The changes stay within issue #43. They add the required validation, services, controllers, routes, and tests without unrelated product or data-model changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 8…

Full details: Linked Issues check

Explanation

The changes implement issue #43: authenticated cross-merchant invoice listing with merchantAddress and status filters, pagination, default newest-first ordering, unscoped detail retrieval, 404 handling, validation, and tests. No Prisma models or fields were added.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 8 files.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[codebestia]

LGTM!
Thank you for your contribution