Premium Analytics: normalize Stats time-series reports

[kangzj]

Fixes #

Proposed changes

• Add split Stats normalizers for generic time-series reports, visits, email summary, and email breakdowns.
• Keep endpoint-specific normalizers separate; this PR does not change the existing traffic endpoint normalizers from the earlier stack.
• Normalize generic time-series payloads from matrix fields/data, object data, and scalar/object days shapes.
• Normalize email summary and email breakdown payloads, including fieldless email all-time breakdown arrays for countries, clients/devices, and links.
• Use date-fns helpers for week/month/year interval boundaries and validate ISO week labels before normalizing them.
• Add focused fixtures and tests for visits/time-series payloads, email payloads, scalar days maps, month/year/leap-year boundaries, and invalid ISO week fallback.

Related product discussion/links

• Stacked on Premium Analytics: add Stats traffic hooks #49778.
• Stack continues in Premium Analytics: normalize secondary Stats reports #49780.
• Top Posts row value contract follow-up: WOOA7S-1585.

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

No. This only normalizes existing Stats API response shapes.

Testing instructions

• Run pnpm --dir projects/packages/premium-analytics test --runInBand projects/packages/premium-analytics/packages/data/src/processing/stats.
• Run pnpm --dir projects/packages/premium-analytics typecheck.
• Run pnpm --dir projects/packages/premium-analytics test --runInBand.
• Browser verification for the stack: the live Stats dashboard request capture confirmed the visits/time-series request pattern, and raw authenticated replays confirmed the non-summarized date, period, and days response shape expected by the normalizers.

Out of scope

• This PR does not add a generic value field to existing endpoint normalizers. Consumers should choose the primary row metric in a follow-up adapter/row-contract change, tracked in WOOA7S-1585.

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

Addressed Claude review feedback from #4775464752 in 8160906483.

Changes:

• Replaced new Date( 0 ) with new Date( 2001, 0, 1 ) so date-fns parsing has a timezone-safe local day/month reference.
• Added a comment documenting that value uses the first numeric metric in API field/object order.
• Added coverage for top-level data[] object rows and isStatsTimeSeriesPayload.
• Added fallback/empty tests for email breakdown and email summary.

Verification:

• TZ=America/New_York pnpm --dir projects/packages/premium-analytics test --runInBand projects/packages/premium-analytics/packages/data/src/processing/stats/__tests__/time-series.test.ts
• pnpm --dir projects/packages/premium-analytics test --runInBand projects/packages/premium-analytics/packages/data/src/processing/stats
• pnpm --dir projects/packages/premium-analytics typecheck
• pnpm --dir projects/packages/premium-analytics test --runInBand

[kangzj]

@claude review plz

[kangzj]

Addressed the email breakdown summary observation in 53fb0cf494.

Changes:

• The empty/no-metric email breakdown path now keeps only numeric scalar summary values instead of passing the whole raw response through summary.
• Added a regression case with nested empty countries / countries-info payload data to verify those raw objects do not leak into summary.

I left the time-series summary.value asymmetry as a conscious follow-up for the row-contract work tracked in WOOA7S-1585.

Verified:

• pnpm --dir projects/packages/premium-analytics test --runInBand projects/packages/premium-analytics/packages/data/src/processing/stats/__tests__/email-breakdown.test.ts
• pnpm --dir projects/packages/premium-analytics test --runInBand projects/packages/premium-analytics/packages/data/src/processing/stats
• pnpm --dir projects/packages/premium-analytics typecheck
• pnpm --dir projects/packages/premium-analytics test --runInBand

[kangzj]

Addressed in 44f6365e91.

Changes:

• Added a note documenting that matrix email-link payloads intentionally keep API labels while fieldless all-time link payloads map known link types to display labels.
• Fixed the CI ESLint/Prettier failure in email-breakdown.ts.

Verified locally:

• pnpm run lint-file projects/packages/premium-analytics/packages/data/src/processing/stats/email-breakdown.ts --max-warnings=0
• pnpm --dir projects/packages/premium-analytics test --runInBand projects/packages/premium-analytics/packages/data/src/processing/stats
• pnpm --dir projects/packages/premium-analytics typecheck
• pnpm --dir projects/packages/premium-analytics test --runInBand

[claude]

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

---

Re-review — current head 44f6365e

Read the full layer again (time-series.ts, visits.ts, email-summary.ts, email-breakdown.ts, utils.ts, types.ts, index.ts, fixtures + tests). Everything from the four prior rounds is resolved and the new label-asymmetry note landed cleanly. ✅ to merge from my side — no blockers.

Confirmed resolved

Prior item	Status
TZ-dependent month/year parse	✅ referenceDate = new Date( 2001, 0, 1 ) (time-series.ts:24) — local day-of-month is 1 everywhere, so the yyyy-MM/yyyy round-trip guards hold
Implicit first-numeric-field value contract	✅ comment at time-series.ts:84
data[] object-row path + isStatsTimeSeriesPayload untested	✅ objectRowsTimeSeriesFixture + detection test incl. negative case (time-series.test.ts:39, :134)
Email breakdown empty path leaking raw objects	✅ scalar-only summary (email-breakdown.ts:204-215) with nested-empty countries/countries-info regression (email-breakdown.test.ts:26)
Matrix vs fieldless email-link label asymmetry	✅ documented at email-breakdown.ts:186-188

Spot checks this pass

• Leap-year boundaries (2024-02-29, 2024-12-31) and invalid-ISO-week fallbacks (2026-W54, 2025-W53) are explicit and correct — the format() round-trip rejects overflowed weeks/months before they reach startOf/endOf*.
• index.ts exports (sanitizeStatsTimeSeriesResponse, Visits, EmailSummary, EmailBreakdown + the two item types) and the StatsNormalizedItem union additions in types.ts line up — no dangling exports.
• sortEmailBreakdownItems keeps Other last regardless of value (email-breakdown.ts:36-48); the link test (Post URL 7 → url 4 → url 2 → Like 1 → Other 3) confirms the ordering contract.
• email-summary.ts correctly emits data: [] on the empty-posts path while still returning a zeroed summary — consistent with the breakdown empty path.

Still a conscious deferral (non-blocking)

• summary.value asymmetry in time-series.ts — present only on the scalar-days path, absent on matrix/object paths. Already flagged for the row-contract follow-up (WOOA7S-1585); leaving it stays consistent with that plan.

Note: the Jest command is blocked in this review sandbox, so the above is static-only — your posted local + TZ=America/New_York runs cover execution.
· split/stats-time-series-normalizers