Premium Analytics: add explicit return types to Stats data hooks

[kangzj]

Fixes #

Proposed changes

Anyone calling a Premium Analytics Stats hook (useStatsTopPosts, useStatsArchives, useStatsAppReferrersSpam, …) currently has to trace through the query/report helpers to find out what the hook returns, because the return types were left to TypeScript inference. This PR writes those contracts out explicitly so the return shape is visible at the call site and in editor tooltips, the same way useStatsEmailSummary and useStatsCommentFollowers already do.

• Introduce an exported UseReportResult< TData > describing the report helper's { primary, comparison, hasComparison, isLoading, isFetching, hasData, isError, error, refetch } shape, and annotate the shared helpers useReport, useStatsReport, useStatsQuery, and useStatsAppQuery.
• Annotate every Stats data hook with its exact return type:
  • report hooks (archives, clicks, country-views, devices, file-downloads, locations, referrers, search-terms, top-authors, top-posts, utm, video-plays, visits, WordAds stats) → UseReportResult< T >
  • query / app-query hooks (comments, email-breakdown, followers, highlights, insights, post, publicize, streak, subscribers, tags, site, WordAds earnings, plan-usage, site-has-never-published-post, referrers-spam read) → UseQueryResult< T >
  • mutation hooks (commercial-classification, dashboard-module-settings, referrers-spam mark/unmark) → UseMutationResult< … >

Each annotation matches the type TypeScript already inferred, so this is a pure typing change with no runtime or behavioural impact. comment-followers was already explicitly typed and is left untouched.

Related product discussion/links

• Follow-up to Premium Analytics: add Stats email summary endpoint #49900 (the Stats email summary endpoint), where the same explicit return type was applied; this brings the rest of the Stats hooks in line.

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

No. Type-only change; no data, requests, or behaviour are affected.

Testing instructions

• pnpm --dir projects/packages/premium-analytics run typecheck — passes (a clean typecheck is the proof that every explicit annotation matches the previously inferred type).
• pnpm exec eslint --max-warnings=0 projects/packages/premium-analytics/packages/data/src/hooks/*.ts — passes.
• No functional behaviour to exercise — confirm the diff is import additions and return-type annotations only.

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

Closing — this was optional polish, not a fix. The Stats hook return types are already fully correct via TypeScript inference (a passing typecheck with the explicit annotations confirms each one matched the inferred type exactly), so call-site types are identical with or without it. Not worth the churn across ~30 files for the marginal drift-guard benefit.

[jp-launch-control]

Code Coverage Summary

No summary data is available for parent commit 9e7d473, 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 9e7d473 is available.

Full summary · PHP report