feat(premium-analytics): integrate site-sync package into analytics

[chihsuan]

Proposed changes

Adds a site-sync internal package to @automattic/jetpack-premium-analytics and configures apiFetch auth in the init module. Provides useSyncStatus — a React hook that polls Jetpack's native sync endpoints, exposes analytics-scoped progress, completion gating, and stall detection for the analytics dashboard.

This is a redesign, not a straight port of WooCommerce-Analytics' @wc-analytics/site-sync. The original hit a single custom WooCommerce REST endpoint; that PHP is being split out separately (#49211), so the JS now composes three Jetpack-native sources.

Implements WOOA7S-1321. Stacked on #49189 (WOOA7S-1320) for the internal-package tsconfig/build resolution it relies on.

Data sources (replacing the original single endpoint)

Field	Source
initial_full_sync_finished (milestone)	JetpackScriptData.premium_analytics — page-load, no fetch (from #49211)
started / finished / per-module progress	poll GET /jetpack/v4/sync/status
analytics percentage	computed client-side from progress.woocommerce_analytics.{sent,total}
trigger	POST /jetpack/v4/sync/full-sync

Adaptations from @wc-analytics/site-sync

Original	Here	Why
GET /wc/v3/woocommerce-analytics/sync-status	GET /jetpack/v4/sync/status + client-side %	Custom WC endpoint not ported; consume Jetpack core directly
POST .../sync-trigger	POST /jetpack/v4/sync/full-sync	No duplicate trigger endpoint (per backend WOOA7S-1436)
isConnected field	dropped	Pure passthrough — nothing branched on it; avoids a connection dep
milestone re-read every poll	read once at mount from script-data	Backend now persists it + injects via jetpack_admin_js_script_data
text domain woocommerce-analytics	jetpack-premium-analytics	Monorepo convention
symlink build hack	wp-build packages/* autodiscovery	Internal-package convention (no link: self-dep, matching #49221)

What's intentionally not here

• No PHP. The sync-status milestone backend is Premium Analytics: Track analytics-aware sync milestone #49211; this is the JS half only.
• No isConnected. Connection-gating belongs higher up (the analytics page only renders when connected).
• No consumer yet. The hook is exported but nothing imports it; the dashboard UI wiring is a follow-up (matches the datetime package precedent, feat(premium-analytics): port datetime package from next-woocommerce-analytics #49221).
• Page-load-static milestone caveat. initial_full_sync_finished is injected once and won't flip mid-session; live completion is detected from the polled analytics-module percentage reaching 100, not by re-reading script-data. Covered by tests.

Notes

• Adds Jest infrastructure to the premium-analytics package (config + a CJS transform for jest.mock, mirroring js-packages/charts).
• The nested packages/* are intentionally not pnpm workspace members; their runtime deps are declared on the parent package.json so the build resolves them (same model the README documents and datetime uses).

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

No.

Testing instructions

pnpm install
cd projects/packages/premium-analytics
pnpm test         # jest — 18 tests pass (status helpers + useSyncStatus hook)
pnpm typecheck    # tsgo --noEmit — passes
cd - && jp build packages/premium-analytics   # wp-build — emits build/modules/site-sync/

End-to-end (requires #49211 + a Jetpack-connected dev site): activate the plugin, open the analytics dashboard, and confirm a fresh site polls/advances, triggering advances the percentage, completion gates the dashboard open, and a stalled sync surfaces the retry error.

Optional — build-time resolution via link: (confirms wp-build tracks the package as a module dependency once a consumer imports it):

1. Add to projects/packages/premium-analytics/package.json dependencies: "@jetpack-premium-analytics/site-sync": "link:packages/site-sync" (the valid-dependencies lint rejects link: — relax it for the temp edit).
2. Import + reference a site-sync export in routes/dashboard/stage.tsx.
3. pnpm install && pnpm build → build/routes/dashboard/content.min.asset.php lists the dependency under module_dependencies.
4. Revert the edits + pnpm install.

Note: the @jetpack-premium-analytics/site-sync specifier is a temporary bridge inherited from the source repo. Once name-based identity (WordPress/gutenberg#78822, mirrored monorepo-wide by #48089) lands, the specifier becomes the package's own name (@automattic/jetpack-premium-analytics-site-sync) and the bare-scope alias/link: drop out — so long term there's no @jetpack-premium-analytics/... to maintain. The package's canonical name is @automattic/jetpack-premium-analytics-site-sync.

[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 or WordPress.com Site Helper), and enable the wooa7s-1321-integrate-site-sync-package-into-analytics branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack wooa7s-1321-integrate-site-sync-package-into-analytics

bin/jetpack-downloader test jetpack-mu-wpcom-plugin wooa7s-1321-integrate-site-sync-package-into-analytics

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!

[simison]

Would it make sense to rather have this be as part of the sync module as a feature? cc @Automattic/jetpack-vulcan who maintain sync.

[chihsuan]

Would it make sense to rather have this be as part of the sync module as a feature? cc @Automattic/jetpack-vulcan who maintain sync.

Good call-out, thanks! I The way I see it, the package/hook is really doing two things: the generic part (polling /sync/status, kicking off a full sync, the polling loop + stall detection) and the analytics-specific part (scoping progress to the woocommerce_analytics module and reading the premium_analytics milestone from script-data).

The analytics-specific stuff pretty clearly belongs here. The generic part is the interesting question. It'd be reusable, so sync could be a natural home. The only snag is that packages/sync is PHP-only right now, so we'd be standing up a brand-new JS layer there just for this one consumer.

If @Automattic/jetpack-vulcan want to own a shared sync-status/trigger hook in sync, I'm genuinely happy with that.

[simison]

Seems like a good opportunity for projects/js-packages/sync then for generic parts but really up to Vulcan team.

Can be easily done in follow-up PR btw, too.

[fgiannar]

Thank you both for bringing this to our attention!

If @Automattic/jetpack-vulcan want to own a shared sync-status/trigger hook in sync, I'm genuinely happy with that.

For now we don't plan to add a JS layer in the sync package, however this could indeed be implemented as part of the following two potential future projects:

• pf5801-1If-p2
• pghT6q-9Z-p2

Actually, when we were brainstorming on the first one we did mention that we could potentially "steal" parts of your implementation, since you are the only plugin that exposes a Sync related UI. For now, feel free to proceed with this approach and we can refactor in the future as needed, ideally without duplicating the effort.

[jp-launch-control]

Code Coverage Summary

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

Full summary · PHP report · JS report