Premium Analytics: add UTM stats data hook

[kangzj]

Fixes #

Why

The Premium Analytics data package has Stats hooks for the split endpoint work, but the UTM surface was stranded in closed PR #49773 and was not included in #49780, #49781, or #49782. This adds the missing UTM query, hook, and normalizer so consumers can request campaign performance data through the same typed data package patterns as the other Stats reports.

Proposed changes

• Add statsUtmQuery for stats/utm/{utmParam} with Calypso-aligned request params.
• Add useStatsUtm and public exports for the hook and response/item types.
• Add a UTM sanitizer that normalizes raw top_utm_values and optional top_posts payloads into the existing normalized Stats report shape.
• Add raw API-shaped fixtures plus query, normalizer, and export coverage.

Verification

Focused tests, lint, typecheck, and whitespace checks passed locally.

Output

$ pnpm --dir projects/packages/premium-analytics test -- packages/data/src/processing/stats/__tests__/utm.test.ts packages/data/src/queries/__tests__/stats-queries.test.ts packages/data/src/hooks/__tests__/stats-exports.test.ts --runInBand
Test Suites: 3 passed, 3 total
Tests:       34 passed, 34 total

$ pnpm exec eslint --max-warnings=0 <touched files>
Passed with no output.

$ pnpm --dir projects/packages/premium-analytics run typecheck
$ tsgo --noEmit

$ git diff --check
Passed with no output.

Related product discussion/links

• Premium Analytics: add Stats proxy data hooks #49773
• Premium Analytics: normalize secondary Stats reports #49780
• Premium Analytics: add remaining Stats hooks #49781
• Premium Analytics: add Stats app hooks #49782

Does this pull request change what data or activity we track or use?

No. This adds a typed client data hook/query/normalizer for an existing Stats endpoint and does not change what data is tracked or used.

Testing instructions

• Run pnpm --dir projects/packages/premium-analytics test -- packages/data/src/processing/stats/__tests__/utm.test.ts packages/data/src/queries/__tests__/stats-queries.test.ts packages/data/src/hooks/__tests__/stats-exports.test.ts --runInBand.
• Run pnpm exec eslint --max-warnings=0 projects/packages/premium-analytics/packages/data/src/hooks/__tests__/stats-exports.test.ts projects/packages/premium-analytics/packages/data/src/hooks/index.ts projects/packages/premium-analytics/packages/data/src/hooks/use-stats-utm.ts projects/packages/premium-analytics/packages/data/src/index.ts projects/packages/premium-analytics/packages/data/src/processing/stats/__fixtures__/utm.ts projects/packages/premium-analytics/packages/data/src/processing/stats/__tests__/utm.test.ts projects/packages/premium-analytics/packages/data/src/processing/stats/index.ts projects/packages/premium-analytics/packages/data/src/processing/stats/types.ts projects/packages/premium-analytics/packages/data/src/processing/stats/utm.ts projects/packages/premium-analytics/packages/data/src/queries/__tests__/stats-queries.test.ts projects/packages/premium-analytics/packages/data/src/queries/index.ts projects/packages/premium-analytics/packages/data/src/queries/stats-query.ts projects/packages/premium-analytics/packages/data/src/queries/stats-utm-query.ts.
• Run pnpm --dir projects/packages/premium-analytics run typecheck.
• Run git diff --check.

[jp-launch-control]

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report

[kangzj]

@claude review plz

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[kangzj]

Review-cycle summary — ef9e3be203 → aaa7b4b982

CI is green; Claude re-review is non-blocking; native-agent feedback was addressed; no inline review threads remain.

What changed during the cycle

Commits added:

• 0195fc98f9 — Address review: document UTM edge cases
• 14b0bcbf58 — Address review: document UTM top-post query parity
• 092ff3db16 — Address review: normalize UTM post-detail requests
• 4e481cbf08 — Address review: resolve disabled UTM top posts
• aaa7b4b982 — Address review: handle null UTM top posts

Review feedback addressed:

• Claude review comments around Calypso parity for empty UTM query args, top_posts resolution, and boolean query_top_posts serialization.
• Native-agent review finding for top_posts: null, preserving lazy paramValues when no usable top-post payload is returned.

Verification:

• Focused Jest tests for UTM/query/export coverage.
• ESLint on touched files.
• Premium Analytics package typecheck.
• git diff --check.
• GitHub required checks all passing.

Unaddressed human comments: None.