feat: add JSON:API content negotiation support for REST endpoints

[teethaking]

---

Summary

Adds support for Accept: application/vnd.api+json content negotiation, allowing clients to request JSON:API-shaped responses from major endpoints — the convention preferred by enterprise integrators — without changing the default response shape for existing consumers.

Closes #135

---

What changed

src/middleware/jsonapi.ts (new)

• Middleware that inspects the incoming Accept header
• When Accept: application/vnd.api+json is present, transforms the standard response payload into a JSON:API-compliant document:
  • Wraps resources in the data envelope with type, id, and attributes
  • Maps relationships (where applicable) into the relationships key per the JSON:API spec
  • Sets the response Content-Type to application/vnd.api+json
• When the header is absent or set to a standard type (e.g. application/json), the existing response shape is returned unchanged — fully backward compatible
• Applied to three major endpoints (wired in their respective route handlers) to demonstrate and validate the pattern

Documentation

• Documented the supported Accept header and resulting response shape
• Listed the three endpoints that currently support JSON:API negotiation
• Included example request/response pairs showing the default JSON shape vs the JSON:API-negotiated shape

---

How to verify

• Send a request to each of the three supported endpoints with Accept: application/vnd.api+json and assert the response is JSON:API-shaped (data, type, id, attributes)
• Send the same requests with no Accept header (or application/json) and assert the original response shape is unchanged
• Confirm Content-Type: application/vnd.api+json is set on negotiated responses
• Review documentation for accuracy against actual endpoint behavior

---

Checklist

• src/middleware/jsonapi.ts implements content negotiation based on Accept header
• Three endpoints support JSON:API-shaped responses
• Default (non-JSON:API) response shape unchanged for existing consumers
• Response Content-Type correctly set when JSON:API is negotiated
• Documentation describes supported endpoints, header, and response shape with examples
• Closes JSON:API content negotiation #135

[drips-wave]

@teethaking Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

Nice approach — the content negotiation is correctly opt-in (a non-application/vnd.api+json Accept passes through untouched, and you have a test for it). But it doesn't compile:

src/middleware/jsonapi.ts(201,5): error TS2741: Property 'data' is missing in type
'{ errors: JsonApiError[] }' but required in type 'JsonApiResponse'

The error branch returns { errors: [...] } with no data, but JsonApiResponse declares data as required (line 27). Per JSON:API, data and errors are mutually exclusive, so the type should reflect that. Simplest fix — make data optional:

type JsonApiResponse = {
  data?: JsonApiResource | JsonApiResource[] | null;   // was: data: ...
  meta?: Record<string, unknown>;
  links?: Record<string, string>;
  errors?: JsonApiError[];
};

Please apply that and confirm npm run build (tsc) is green locally — the fork CI doesn't run the typecheck job, so it wasn't caught automatically. One more thing: this PR also now conflicts with src/api.ts since #149/#150 merged (both add routers there) — a quick git rebase origin/main will pick those up. Then I'll re-review.

[teethaking]

alright

[teethaking]

done merge