Premium Analytics: add Stats app notices endpoint

[kangzj]

Fixes #

Proposed changes

• Add Premium Analytics data package support for the Stats app notices endpoint, following the Stats endpoint patterns established in Premium Analytics: add Stats endpoint foundation #49886.
• Wire the endpoint-specific query, hook, public exports, and sanitizer/normalizer registration where applicable.
• Keep endpoint typing tied to sanitizer keys or passthrough query inference, with focused fixtures/tests for the raw endpoint payload shape where normalization is introduced.

Related product discussion/links

• Builds on Premium Analytics: add Stats endpoint foundation #49886.

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

No. This only adds typed client data/query integration for an existing Stats API endpoint.

Testing instructions

• pnpm --dir projects/packages/premium-analytics test -- packages/data/src/queries/tests/stats-queries.test.ts packages/data/src/hooks/tests/stats-exports.test.ts --runInBand
• pnpm exec eslint --max-warnings=0
• pnpm --dir projects/packages/premium-analytics run typecheck
• 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 please review this PR.

[claude]

Claude finished @kangzj's task in 2m 8s —— View job

---

PR Review: Stats app notices endpoint

• Gather context (diff, foundation files, conventions)
• Analyze query/hook/mutation wiring
• Check against package conventions (AGENTS.md)
• Post review

---

Reviewed against the foundation branch (origin/endpoint/stats-endpoint-foundation). Overall this is a clean, well-scoped addition that correctly follows the package's architecture. The decision to bypass the WPCOM proxy and hit the local /jetpack-premium-analytics/v1/notices route is correct and matches AGENTS.md ("Not proxied because GET merges WPCOM dismissal state with local flags"), and the inline comment documents the why nicely. ✅

A few suggestions, all minor/non-blocking:

1. Mutation uses the imported queryClient singleton instead of useQueryClient()

use-stats-app-notices.ts:21

queryClient.invalidateQueries( { queryKey: [ 'stats-app', 'notices' ] } );

This works today because AnalyticsQueryClientProvider shares the same exported singleton. But the idiomatic react-query pattern inside a hook is to pull the client from context via useQueryClient(), which keeps the hook correct if it's ever mounted under a different client (e.g. an isolated QueryClient in a unit test). Since this is the package's first mutation, it's worth setting the convention here.

import { useMutation, useQueryClient } from '@tanstack/react-query';

export function useStatsAppNoticeMutation() {
	const queryClient = useQueryClient();
	return useMutation( {
		mutationFn: ( data: StatsAppNoticeMutationParams ) => updateStatsAppNotice( data ),
		onSuccess: () => {
			queryClient.invalidateQueries( { queryKey: [ 'stats-app', 'notices' ] } );
		},
	} );
}

(The invalidateQueries prefix match itself is correct — [ 'stats-app', 'notices' ] partial-matches the full key [ 'stats-app', 'notices', {…} ] by default.)

Fix this →

2. statsAppNoticesQuery hardcodes UseQueryOptions< unknown >

stats-app-notices-query.ts:10

The foundation's statsAppProxyQuery< TData = unknown > is generic so callers can type the response. Making this query generic too (<TData = unknown>) would let useStatsAppNotices flow a real notices type through later without changing the signature, and keeps it consistent with the rest of the family. Non-blocking — fine to defer until the notices response shape lands.

3. StatsQueryParams is broad for a notices GET

stats-app-notices-query.ts:9 / use-stats-app-notices.ts:12

StatsQueryParams carries period/end_date/days/etc., which a notices listing endpoint likely doesn't accept. Reusing the shared type is harmless (extra params are just dropped server-side), but a narrower param type would document the actual contract better. Worth a quick check on what the /notices GET actually consumes.

4. Mutation params are loosely typed

stats-app-notices-query.ts:21-25

export type StatsAppNoticeMutationParams = {
	id: string;
	status: string;
	postponed_for?: number;
};

If status has a known finite set of values (e.g. 'dismissed' | 'postponed'), a string-literal union would catch typos at the call site. Optional polish.

Notes

• Exports/test wiring look consistent: stats-app-notices-query → queries/index.ts → hooks/index.ts → data/src/index.ts, and both hooks are added to stats-exports.test.ts. ✅
• The export-presence test only asserts the hooks are functions — there's no test asserting the GET path/query-arg building or the POST method. That matches the rest of the family (no per-query path tests), so it's consistent, but a small test for the path construction wouldn't hurt given this endpoint is special-cased off the proxy.
• Changelog entry is present and correctly formatted (Significance: patch, Type: added). ✅

Nothing here is blocking — the core wiring is correct. The useQueryClient() change (#1) is the one I'd most recommend before this becomes the template for future mutations.
· endpoint/stats-app-notices-endpoint

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

Rebased onto the clean foundation PR (#49886). @claude please re-review.\n\n

[claude]

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

---

PR Re-Review: Stats app notices endpoint

• Gather context (diff vs rebased foundation)
• Re-check query/hook/mutation wiring
• Verify previous feedback status
• Post review

---

Re-reviewed against the rebased base (origin/endpoint/stats-endpoint-foundation). The rebase is clean — the diff is content-identical to the prior review (7 files, +77/−0), now correctly stacked on the clean foundation rather than the old layered stack. Wiring still verified end to end:

• stats-app-notices-query → queries/index.ts ✅
• use-stats-app-notices → hooks/index.ts → data/src/index.ts ✅
• both hooks in stats-exports.test.ts ✅
• changelog present and well-formed (Significance: patch, Type: added) ✅

The local-route decision is still correct and matches AGENTS.md — /notices is deliberately not proxied because the GET merges WPCOM dismissal state with local flags. The invalidateQueries({ queryKey: [ 'stats-app', 'notices' ] }) prefix correctly partial-matches the full key [ 'stats-app', 'notices', {…} ]. ✅

Status of prior feedback (all still open, all non-blocking)

None of the four earlier suggestions were addressed in the rebase — relisting with updated notes:

1. Mutation uses the queryClient singleton instead of useQueryClient() — use-stats-app-notices.ts:21

Worth noting: there is existing precedent for importing the singleton — prefetch/prefetch-report.ts does the same. But that's a plain module function, not a hook. Inside a hook the idiomatic react-query pattern is useQueryClient(), which keeps the hook correct under an isolated client (e.g. a unit-test QueryClient). Since this is the package's first mutation it sets the template, so I'd still nudge toward the context-based client here.

import { useMutation, useQueryClient } from '@tanstack/react-query';

export function useStatsAppNoticeMutation() {
	const queryClient = useQueryClient();
	return useMutation( {
		mutationFn: ( data: StatsAppNoticeMutationParams ) => updateStatsAppNotice( data ),
		onSuccess: () => {
			queryClient.invalidateQueries( { queryKey: [ 'stats-app', 'notices' ] } );
		},
	} );
}

Fix this →

2. statsAppNoticesQuery hardcodes UseQueryOptions< unknown > — stats-app-notices-query.ts:10

The foundation's statsAppProxyQuery< TData = unknown > is generic (confirmed at stats-app-query.ts:21). Making this query < TData = unknown > too lets a real notices type flow through useStatsAppNotices later without a signature change. Fine to defer until the response shape lands.

3. StatsQueryParams is broad for a notices GET — stats-app-notices-query.ts:9 / use-stats-app-notices.ts:12

StatsQueryParams carries period/end_date/days/etc. that the /notices GET likely doesn't accept. Harmless (extra params are dropped server-side), but a narrower param type would document the real contract.

4. Mutation params loosely typed — stats-app-notices-query.ts:21-25

If status has a finite value set (e.g. 'dismissed' | 'postponed'), a string-literal union would catch typos at call sites. Optional polish.

Verdict

Nothing blocking — the rebase is clean and the wiring is correct. The useQueryClient() change (#1) remains the one I'd most recommend before this becomes the mutation template, but it's a judgment call you can reasonably defer.
· endpoint/stats-app-notices-endpoint

[kangzj]

Addressing claude[bot]'s re-review (comment #4787361853): switched the notice mutation to useQueryClient() so invalidation uses the active React Query client. Local pnpm --dir projects/packages/premium-analytics typecheck passed.\n\n

[kangzj]

@claude please re-review.\n\n

[claude]

Claude finished @kangzj's task in 42s —— View job

---

PR Re-Review: Stats app notices endpoint

• Pull latest diff vs rebased foundation
• Verify prior feedback Use class_exists() guard for Featured_Content. #1 (useQueryClient()) was addressed
• Re-check wiring + remaining suggestions
• Post review

---

Re-reviewed against origin/endpoint/stats-endpoint-foundation. Diff unchanged in shape (7 files, +78/−0).

✅ Prior feedback #1 is resolved

use-stats-app-notices.ts:15-24 — the mutation now pulls the client from context instead of the singleton:

export function useStatsAppNoticeMutation() {
	const queryClient = useQueryClient();
	return useMutation( {
		mutationFn: ( data: StatsAppNoticeMutationParams ) => updateStatsAppNotice( data ),
		onSuccess: () => {
			queryClient.invalidateQueries( { queryKey: [ 'stats-app', 'notices' ] } );
		},
	} );
}

This is exactly the idiomatic react-query pattern and sets a good template for future mutations in the package. The invalidateQueries prefix [ 'stats-app', 'notices' ] still correctly partial-matches the full key [ 'stats-app', 'notices', statsAppQueryKeyPart(params) ]. 👍

Wiring re-verified

• statsAppQueryKeyPart / useStatsAppQuery / UseStatsAppOptions all resolve against the foundation (stats-app-query.ts:8, use-stats-app-query.ts:5-7). ✅
• Export chain intact: stats-app-notices-query → queries/index.ts → hooks/index.ts → data/src/index.ts; both hooks present in stats-exports.test.ts. ✅
• Local /jetpack-premium-analytics/v1/notices route (not proxied) still matches AGENTS.md rationale, with the // Notices are served by the local plugin REST route comment documenting the why. ✅
• Changelog present and well-formed. ✅

Remaining items (all non-blocking, fine to defer)

• Allow plugins to inject additional template-specific open graph tags #2 Generic query type — statsAppNoticesQuery still hardcodes UseQueryOptions< unknown >; the foundation's statsAppProxyQuery< TData = unknown > (stats-app-query.ts:21) is generic. Making this < TData = unknown > later lets a real notices type flow through without a signature change. Fine to defer until the response shape lands.
• Edit and rename the readme for GitHub #3 Broad param type — StatsQueryParams carries period/end_date/days the /notices GET likely ignores. Harmless (extra args dropped server-side), but a narrower type would document the real contract.
• Merge the changes in 2.7.1 upstream to master. #4 Loosely typed status — if status has a finite set (e.g. 'dismissed' | 'postponed'), a string-literal union would catch call-site typos. Optional polish.

Verdict

The one change I'd most recommended (#1) is done and done cleanly. Nothing blocking remains — the rest are optional refinements that can reasonably wait for the notices response/request contract to firm up. LGTM. ✅
· endpoint/stats-app-notices-endpoint