Add Next.js App Router and Pages Router integration for health checks

[Copilot]

Adds Next.js health check integration supporting both App Router (Next.js 13+) and Pages Router, enabling seamless health check endpoints in Next.js applications.

Changes

• Integration (src/integrations/nextjs.ts)

  • createNextHealthCheckHandler: Primary handler for Next.js App Router (uses NextRequest/NextResponse)
  • createNextPagesHealthCheckHandler: Handler for legacy Pages Router (uses NextApiRequest/NextApiResponse)
  • Supports query parameters: debug, last, simulate
  • Returns 200 (healthy/degraded) or 503 (unhealthy)
  • Optional peer dependency on next@>=13.0.0
  • Debug Detector: Supports boolean or function (req) => boolean | Promise<boolean> for conditional debug output based on authentication or other request properties
  • Headers Option: Custom response headers support (merged with default headers)
  • Options-Only API: Only accepts MedicusOption (consistent with other integrations)
  • Reuses DefaultHttpHeaders constant from HTTP integration

• Tests (test/integrations/nextjs.test.ts)

  • 15 test cases covering both App Router and Pages Router handlers
  • Tests for handler creation, query params, status codes, debug detector, custom headers
  • Mock Next.js request/response objects for isolated testing

• Documentation (docs/integrations/nextjs.md)

  • Concise documentation focused on integration specifics
  • App Router examples (primary/recommended)
  • Pages Router examples (legacy support)
  • Query parameters and options reference
  • Conditional debug based on authentication examples

Usage

App Router (Recommended)

// app/api/health/route.ts
import { HealthStatus } from 'medicus';
import { createNextHealthCheckHandler } from 'medicus/nextjs';

export const GET = createNextHealthCheckHandler({
  checkers: {
    database: () => HealthStatus.HEALTHY,
    redis: async () => {
      const isConnected = await checkRedis();
      return isConnected ? HealthStatus.HEALTHY : HealthStatus.DEGRADED;
    }
  },
  // Optional: conditional debug based on auth
  debug: (req) => req.headers.get('authorization') === 'Bearer secret-token'
});

Pages Router (Legacy)

// pages/api/health.ts
import { HealthStatus } from 'medicus';
import { createNextPagesHealthCheckHandler } from 'medicus/nextjs';

export default createNextPagesHealthCheckHandler({
  checkers: {
    database: () => HealthStatus.HEALTHY
  }
});

Both endpoints support /api/health?debug=true&last=true&simulate=unhealthy for testing and debugging.

Original prompt

Learn how the package works, read all files under @src/**/* and prepare an nextjs 16 integration.

A default api route is defined such as:

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(_: NextApiRequest, res: NextApiResponse) {
  res.status(200).send({ status: 'ok' })
}

(Obviously we need to provide all things medicus already does and the above code is just an api route example)

so ideally we would just export default medicusNext(options) or maybe mdicusIntegration()? idk figure a good name.

Also add a doc page for nextjs and also add unit tests

Read https://raw.githubusercontent.com/vercel/next.js/refs/heads/canary/docs/02-pages/03-building-your-application/01-routing/07-api-routes.mdx for context if needed

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 99.01478% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.41%. Comparing base (a316045) to head (268d3ae).

Files with missing lines	Patch %	Lines
src/integrations/nextjs.ts	99.48%	0 Missing and 1 partial ⚠️
src/utils/http.ts	87.50%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #155      +/-   ##
==========================================
+ Coverage   98.21%   98.41%   +0.20%     
==========================================
  Files          14       15       +1     
  Lines        1064     1264     +200     
  Branches       75       82       +7     
==========================================
+ Hits         1045     1244     +199     
- Misses         13       14       +1     
  Partials        6        6              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[arthurfiorette]

@copilot i fixed the docs for you, now:

1. just like the http integration reuse the default http headers constant and also add the headers options.

2. remove the ability to pass a medicus instance and make it only options just as all other integrations.

3. Make a app router alternative (the default one since app is the newer approach) and change the doc format to state that both options works. Remember: keep docs short and just related to the integration itself instead of documenting things particular to a generic Medicus instance/class

[Copilot]

@copilot i fixed the docs for you, now:

1. just like the http integration reuse the default http headers constant and also add the headers options.
   ...

Done! ✅ (cad2db8)

Changes made:

1. Reuses DefaultHttpHeaders and adds headers option - Just like HTTP integration, merges custom headers with defaults

2. Removed Medicus instance parameter - Now only accepts options object. Both functions create the Medicus instance internally.

3. App Router as primary, Pages Router as secondary:

   • createNextHealthCheckHandler() - App Router (Next.js 13+) - uses NextRequest/NextResponse
   • createNextPagesHealthCheckHandler() - Pages Router (legacy) - uses NextApiRequest/NextApiResponse

4. Concise documentation - Focused on integration specifics, removed generic Medicus documentation. Shows both routers with clear examples.

All 35 tests passing with 100% code coverage on the integration.