PA - Ads: register the WordAds proxy on connection's Proxy_Controller

[retrofox]

Fixes WOOA7S-2275

Proposed changes

Third consumer of connection's Proxy_Controller (#53098), after VideoPress (#52941): the Ads package gets its own route for the WordPress.com endpoints its widgets read, so the data of the Ads section can leave the dashboard's proxy.

The three Ads widgets read wordads/earnings and wordads/stats through /jetpack-premium-analytics/v1/proxy/v1.1/wordads/.... This PR gives the package the same kind of route, so a client moves from one to the other by changing the base of the URL: same WordPress.com endpoint, same query params, same response.

What Ads declares

Api_Proxy_Controller is a table and two hooks. The table exposes wordads/earnings and wordads/stats on manage_options, the capability the dashboard asks for the Ads section (Capabilities::current_user_can_view_ad_reports()). The dashboard's own wordads group names activate_wordads, which no code grants, so admins-only is what it already enforces.

Analytics_Dashboard::init() hooks Api_Proxy_Controller::init() on rest_api_init at priority 0, as class-name callbacks, so the package class loads on REST requests only, and the cache prefix on jetpack_stats_transient_cleanup_prefixes, where cron can see it. Simple is skipped: it runs no Jetpack plugin and holds no blog token, and its clients reach WordPress.com directly. Atomic gets the route through the same init(), called by jetpack-mu-wpcom.

Allowlist, capability check, blog-signed forward, five-minute cache, force_refresh and the error shapes come from connection and are tested there. The Ads tests cover what the table declares and nothing the package already tests: which endpoints route, who reads them, and the cache prefix.

What does not change

No client calls the new route yet: the widgets move to it when the SDK exposes the host query engine (WOOA7S-2230), as the Top videos widget does. The dashboard keeps its wordads group until then.

Related product discussion/links

Linear: WOOA7S-2247. Stacked on #53098.

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

No.

Testing instructions

jp test php packages/ads

On a site connected to WordPress.com with the WordAds module active and the dashboard built, open any wp-admin page that loads wp.apiFetch and run in the browser console:

wp.apiFetch( { path: '/jetpack/v4/wordads/proxy/v1.1/wordads/earnings' } ).then( console.log );

• It resolves with the same payload as /jetpack-premium-analytics/v1/proxy/v1.1/wordads/earnings.
• /jetpack/v4/wordads/proxy/v1.1/wordads/stats?unit=day&quantity=7 resolves with the daily stats.
• /jetpack/v4/wordads/proxy/v1.1/wordads/settings is rejected with rest_no_route.
• As a user who is not an administrator, the first request is rejected with a 403.

For the cache, run the first request twice and list the transients:

wp transient list --search='jetpack_wordads_proxy_*'

One entry per distinct query. Adding force_refresh=1 to the query creates none.

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the update/ads-wpcom-proxy branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/ads-wpcom-proxy

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

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

---

Jetpack plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

[jp-launch-control]

Code Coverage Summary

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

Full summary · PHP report · JS report