Premium Analytics: add Stats traffic normalizers

[kangzj]

Fixes #

Proposed changes

• Add the first Stats response normalizers for traffic-style reports: top posts, referrers, clicks, search terms, file downloads, authors, locations, and video plays.
• Export the normalized Stats report/item types from the package data layer.
• Add fixture-based tests for representative response shapes with nested rows and numeric string coercion.

What changed and why

This is PR 2 in the split from #49773, stacked on #49775. It keeps the data-shaping layer separate from the query/hook API so reviewers can validate the normalized report contract before endpoint wiring is added.

The normalizers convert Jetpack Stats proxy responses into the existing Premium Analytics-style report shape: a numeric summary plus data rows with shared keys like label, value, children, link, and action metadata. That keeps Stats widgets and dashboards from needing endpoint-specific response handling.

Non-test/support implementation size: 344 lines including changelog and exports.

Related product discussion/links

• Part of WOOA7S-1571.
• Linear: https://linear.app/a8c/issue/WOOA7S-1571/premium-analytics-add-stats-proxy-data-hooks.
• Supports Premium Analytics: extend the API proxy to cover Stats-Admin endpoints #49571.
• Split from Premium Analytics: add Stats proxy data hooks #49773.
• Stacked on Premium Analytics: add Stats proxy foundation #49775.

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

No.

Testing instructions

• Run pnpm --dir projects/packages/premium-analytics test.
• Run pnpm --dir projects/packages/premium-analytics typecheck.
• Run pnpm --dir projects/packages/premium-analytics build.

[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!

[jp-launch-control]

Code Coverage Summary

No summary data is available for parent commit b8db15a, so cannot calculate coverage changes. 😴

If that commit is a feature branch rather than a trunk commit, this is expected. Otherwise, this should be updated once coverage for b8db15a is available.

Full summary · PHP report

[kangzj]

Review loop clear for current head e9be8ec1f3. No required checks are reported for this stacked branch. Local validation after the latest stack rebase passed: pnpm --dir projects/packages/premium-analytics test, typecheck, and build.

[louwie17]

I left a couple thoughts, a bit around simplification. Also that we may want to change the structure of the normalized data a bit to help simplify the normalization for each endpoint.
For example each item relies on views and a label most of the other things could be considered meta.

[louwie17]

This seems a bit redundant given getStatsBucket, as it basically does the same thing as far as I am understanding.
This is duplicated in each function, so maybe we can clean this up. Also asRecord sounds a bit confusing. Do we need this? Can't we use response?.<key> in that case?

[louwie17]

We are doing the reduce in a lot of places as well to count the total amount. Maybe a function countTotalByKey or something would help make this a bit more readable.

Also what does numericSummary exactly do? it seems like it enforces the summary to be a float? Maybe we can highlight that in the function call as well.
Also curious in what scenarios we run into either a string or number that it has to be explicitly converted. There seem to be a lot of handling of potential edge cases, but not sure if they are real?

[louwie17]

It may be helpful to split this up a bit into data that is shown in a chart ( labels, values ) and things that may be required for adding custom labels or additional data points, that could be considered meta data that is more specific to the widget it-self.
This may help simplify the parsing below as well.
This is just a thought, I did not double check if that seems reasonable.