feat(heartbeat): add api monitor type for synthetics API journeys

[shahzad31]

Summary

Adds a new monitor.type: api to Heartbeat — a synthetics-driven monitor type that runs multi-step API checks via Playwright's APIRequestContext without ever launching Chromium.

Companion to elastic/synthetics#997, which introduces the apiJourney(...) DSL on the agent side.

# heartbeat.yml
heartbeat.monitors:
  - type: api
    id: orders-api-health
    name: Orders API health
    schedule: '@every 1m'
    source:
      local:
        path: '/etc/synthetics/api-checks'

What changed

New api plugin

• x-pack/heartbeat/monitors/api/api.go — registers monitor.type: api (alias synthetics/api) and bridges to browser.NewSourceJob.
• Skips the ELASTIC_SYNTHETICS_CAPABLE env gate (no Chromium needed), keeps the euid != 0 setuid guard (still spawns Node).

Centralised "synthetics-driven monitor" check

• New stdfields.IsSyntheticsType(t) / (StdMonitorFields).IsSyntheticsType(). Returns true for browser and api.
• Four call sites that previously special-cased "browser" now use the helper:
  • wrappers/wrappers.go — WrapBrowser path
  • wrappers/summarizer/summarizer.go — browser plugin set
  • monitors/factory.go — synthetics data stream auto-config
  • monitors/logger/logger.go — skip lightweight network-info extraction
• heartbeat/config/config.go — adds default api: {Limit: 2} and the SYNTHETICS_LIMIT_API env var.

Type-aware CLI invocation

• browser/config.go — new Type field on the config + (*Config).IsAPI() helper.
• browser/sourcejob.extraArgs — filters browser-only flags (--sandbox, --screenshots, --throttling/--no-throttling) for API journeys. --playwright-options and --ignore-https-errors are still forwarded (both apply to APIRequestContext).
• (*SourceJob).Plugin() is now exported so the api package can reuse the pipeline.

Event routing

• synthexec/synthtypes.go — Journey.Type is a new optional field; (Journey).IsAPI() helper. ToMap() omits type when empty so older agent docs aren't reshaped.
• synthexec/enrich.go — journey/network_info events from API journeys land in synthetics.api.network (new dataset) instead of browser.network. Legacy/unknown journeys keep going to browser.network for back-compat.

Tests (all green)

• stdfields/stdfields_test.go — table-driven TestIsSyntheticsType.
• browser/sourcejob_test.go — TestExtraArgsForAPIMonitor (filters apply) + TestExtraArgsForBrowserMonitorUnchanged (regression guard).
• synthexec/enrich_test.go — TestEnrichAPIJourneyDatasetRouting (api → synthetics.api.network) + TestEnrichLegacyJourneyDefaultsToBrowser (no journey.type → browser.network).
• synthexec/synthtypes_test.go — TestJourneyTypePropagation covers ToMap, IsAPI, JSON unmarshal.

ok  github.com/elastic/beats/v7/heartbeat/monitors/stdfields
ok  github.com/elastic/beats/v7/heartbeat/monitors/wrappers
ok  github.com/elastic/beats/v7/heartbeat/monitors/wrappers/summarizer
ok  github.com/elastic/beats/v7/heartbeat/monitors/logger
ok  github.com/elastic/beats/v7/heartbeat/config
ok  github.com/elastic/beats/v7/x-pack/heartbeat/monitors/browser
ok  github.com/elastic/beats/v7/x-pack/heartbeat/monitors/browser/synthexec

Compatibility

• Synthetics agent: requires @elastic/synthetics >= <TBD> (the release that ships apiJourney(...)). Older agents silently won't emit journey.type, and journey/network_info for any of their journeys keeps going to browser.network — same behavior as before, no regression.
• Stack / ingest pipelines: introduces a new dataset synthetics.api.network. Until ILM / dashboards in Kibana ship support, those docs land but won't be surfaced anywhere bespoke.
• Existing browser monitors: byte-compatible. The only branching change is Type != "browser" → !IsSyntheticsType(), which is logically identical when the only type in the set is browser. TestExtraArgsForBrowserMonitorUnchanged pins that the browser CLI invocation is unchanged.

Out of scope (follow-ups)

• Heartbeat docs (docs/reference/synthetics-monitor.asciidoc) — covered separately once the synthetics-side docs land.
• Bundled synthetics version bump in dev-tools/packaging/templates/docker/Dockerfile.tmpl — gated on @elastic/synthetics releasing.
• An end-to-end integration test against a real HTTPS server — depends on the synthetics agent being installed in CI.
• Kibana-side handling of monitor.type: api in the monitor list / waterfall / state.

Test plan

• go build -tags synthetics ./heartbeat/... ./x-pack/heartbeat/...
• go test -tags synthetics on all touched packages.
• Local end-to-end smoke: heartbeat container with a real apiJourney against httpbin.org, verify events land in synthetics.api.network.
• CI on this branch.

Linked issues / PRs

• feat: multi step api runner synthetics#997 — the agent-side apiJourney DSL + capture pipeline.
• [proposal] Lightweight API journeys DSL synthetics#900 — original API journeys proposal.
• Multi Step scriptable lightweight API Journeys synthetics#137 — 5+ year customer ask for multi-step API monitoring.

[botelastic]

This pull request doesn't have a Team:<team> label.

[github-actions]

🤖 GitHub comments

Just comment with:

• run docs-build : Re-trigger the docs validation. (use unformatted text in the comment!)
• /test : Run the Buildkite pipeline.

[mergify]

This pull request does not have a backport label.
If this is a bug or security fix, could you label this PR @shahzad31? 🙏.
For such, you'll need to label your PR with:

• The upcoming major version of the Elastic Stack
• The upcoming minor version of the Elastic Stack (if you're not pushing a breaking change)

To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-8./d is the label to automatically backport to the 8./d branch. /d is the digit
• backport-active-all is the label that automatically backports to all active branches.
• backport-active-8 is the label that automatically backports to all active minor branches for the 8 major.
• backport-active-9 is the label that automatically backports to all active minor branches for the 9 major.