feat(@merkur/plugin-http-client)!: normalize headers to Headers insta…

[mjancarik]

…nce, add default Content-Type for body requests

• Add transformHeaders transformer that normalizes request.headers to a Headers instance (accepts plain objects and Headers instances)
• Add transformHeaders as first entry in getDefaultTransformers pipeline
• Set default Content-Type: application/json for body-bearing requests (non-GET/HEAD) when no Content-Type is already set in transformBody
• Add changeset documenting all three breaking changes and migration steps
• Add tests for Headers instance normalization, default Content-Type, and preservation of existing headers
• Update website documentation

[Copilot]

Pull request overview

This PR introduces a breaking-change update to @merkur/plugin-http-client to standardize header handling by normalizing request.headers to a Headers instance, and to improve default request behavior by automatically applying Content-Type: application/json for body-bearing requests when not explicitly set.

Changes:

• Added a new built-in transformHeaders transformer and made it the first step in the default transformer pipeline.
• Updated transformBody to auto-apply Content-Type: application/json for non-GET/HEAD requests with a body when missing, and to use shared constants for JSON content-type matching.
• Updated tests, documentation, and added a changeset with migration guidance for the breaking changes.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/plugin-http-client/src/index.js	Adds transformHeaders and updates transformBody behavior around header normalization and default JSON Content-Type.
packages/plugin-http-client/src/__tests__/indexSpec.js	Adds coverage for header normalization and default Content-Type behavior; updates transformer pipeline expectations.
packages/plugin-http-cache/src/__tests__/indexSpec.js	Updates snapshot expectations to reflect the additional default transformer.
packages/plugin-graphql-client/src/__tests__/indexSpec.js	Updates snapshot expectations to reflect the additional default transformer.
website/docs/http-client-plugin.md	Documents Headers support, new default transformer order, and default Content-Type behavior.
.changeset/http-client-headers-normalization.md	Adds a major-version changeset explaining the breaking changes and migration steps.

Suppressed comments (2)

website/docs/http-client-plugin.md:166

• The markdown table row for headers has mismatched backticks, which breaks rendering (it currently shows object \| Headers``).

| `headers` | `object \| `[Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers)`` | `{}` | Request headers — plain objects and `Headers` instances are both accepted |

.changeset/http-client-headers-normalization.md:65

• The polyfill note ties Headers availability to the bundler's ES target ("below ES2017"), but this is primarily a runtime-environment concern (whether fetch/Headers exist), not a transpilation target. Rewording would avoid misleading migration guidance.

### Polyfill required for build targets below ES2017 (ES8)

The `Headers` global (part of the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Headers)) is used at runtime by `transformHeaders`. Widgets built with a bundler target below ES2017 (e.g. `target: 'es5'` or `target: 'es6'` in webpack/Rollup) that run in environments without a native `Headers` implementation must add a polyfill such as [`whatwg-fetch`](https://github.com/github/fetch) or [`cross-fetch`](https://github.com/lquixada/cross-fetch).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.