Premium Analytics: add Stats traffic hooks

[kangzj]

Fixes #

Proposed changes

• Add split useStats* hooks for the core traffic endpoints introduced by Premium Analytics: add Stats traffic queries #49777.
• Keep comparison handling in the shared useStatsReport helper while leaving each endpoint hook in its own file.
• Export the new hooks from the hooks package surface and the package root, with an export-shape test for discoverability.

Related product discussion/links

• Stacked on Premium Analytics: add Stats traffic queries #49777.
• Stack continues in Premium Analytics: normalize Stats time-series reports #49779.

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

No. This exposes React Query hooks for existing Stats query factories.

Testing instructions

• Run pnpm --dir projects/packages/premium-analytics test --runInBand.
• Run pnpm --dir projects/packages/premium-analytics typecheck.
• Run pnpm --dir projects/packages/premium-analytics build.
• Browser verification for the stack: dashboard and detail-page requests were inspected in a logged-in browser; summarized traffic endpoints continue to use summarize=1, while replayed raw requests without summarize=1 return the expected date, period, and days bucket shapes.

[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

[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 loop clear for current head 92cbcd503d. 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.

[chihsuan]

Thanks for splitting this into stacked PRs @kangzj focused scope makes it much easier to review. 🙂

Changes look good.

[chihsuan]

Not sure why we re-exports each useReport* hook individually in upstream, while hooks/index.ts is supposed to be the "all hooks" but is actually missing 6 of them. 🤔

I don't think we should fix it in this PR, but it'd be nice to follow up by making hooks/index.ts the canonical barrel (every hook re-exported there) and having src/index.ts just do export * from './hooks' instead of listing each hook. That removes the per-hook duplication and the drift risk. Filing this as a note so we can pick it up later.

[kangzj]

Tracked: https://linear.app/a8c/issue/WOOA7S-1579/premium-analytics-make-hooks-barrel-canonical

The base branch was changed.

[kangzj]

@claude review plz

[claude]

Claude finished @kangzj's task in 1m 23s —— View job

---

Code Review: Stats traffic hooks

• Read the diff and surrounding code (useReport, query factories, exports)
• Review hook implementations
• Review exports & test
• Post review feedback

---

Nice, clean split. The per-endpoint hooks are thin and consistent, comparison handling stays in the shared useStatsReport wrapper, and the export surface is covered by a test. I didn't find any correctness bugs — the notes below are minor.

What looks good

• useStatsReport correctly funnels through useReport, so comparison/enable/refetch semantics are inherited rather than re-implemented per endpoint. ✅
• useStatsLocations threading geoMode through its own param extension (matching statsLocationsQuery) is handled right — it's stripped from the static type at the useStatsReport boundary but preserved at runtime via { ...params } in useReport. ✅
• useStatsSite bypassing the report wrapper and calling useQuery directly is the correct call since the site endpoint has no comparison concept. ✅
• Each disabledComparisonKey is unique per report, so the placeholder (no-queryFn, never-enabled) comparison queries won't collide in the cache. ✅

Minor suggestions (non-blocking)

1. Indirect return-type coupling in use-stats-report.ts:12-14. StatsReportQueryFactory derives its return via ReturnType< typeof statsTopPostsQuery >, importing one specific query factory purely as a type anchor. It works (all report factories return UseQueryOptions< StatsSanitizerData >), but it's a bit surprising — if statsTopPostsQuery's signature ever diverged it would silently constrain every other hook. A named type exported from stats-query.ts (e.g. StatsReportQueryOptions) would express the intent more directly.

2. disabledComparisonKey is hand-typed per hook. Every caller passes [ 'stats', '<name>', '__comparison__', 'disabled' ]. Since the slug is the only varying part, useStatsReport could accept the slug and build the key internally — removes 10 near-identical arrays and the chance of a typo'd key. Optional.

3. Export-shape test asserts presence only (stats-exports.test.ts). toHaveProperty passes even if an export were accidentally a non-function. A typeof dataPackage.useStatsSite === 'function' check (or a small it.each) would catch that and cut the repetition. Very minor.

Re: @chihsuan's barrel-drift note — agreed, and worth flagging concretely: hooks/index.ts and src/index.ts now both list all 10 stats hooks, so they can drift (the existing useReport* set already isn't fully mirrored). Making hooks/index.ts the canonical barrel and having src/index.ts do export * from './hooks' is the right follow-up. Good call leaving it out of this PR's scope.

Verdict: looks good to merge. 👍 I followed the documented test/typecheck/build instructions as the source of truth rather than running the full pipeline here.
• split/stats-core-hooks

[kangzj]

Addressed the concrete review suggestions in 29f645b:

• Added a named StatsReportQueryOptions type instead of anchoring the wrapper to statsTopPostsQuery.
• Moved the Stats disabled-comparison key construction into useStatsReport; callers now pass only the report slug.
• Strengthened stats-exports.test.ts to assert each public Stats hook export is a function.

Validation:

• pnpm --dir projects/packages/premium-analytics test
• pnpm --dir projects/packages/premium-analytics typecheck