feat(premium-analytics): add 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 was split out separately (#49211, now merged), so the JS composes three Jetpack-native sources.

Data sources (replacing the original single endpoint)

Field	Source
initial_full_sync_finished (milestone)	JetpackScriptData.premium_analytics.initial_full_sync_finished (int) — page-load seed, refreshed live from /sync/status (#49602)
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	seeded from script-data, refreshed live from the poll	Backend persists it; injected via script-data and surfaced on /sync/status (#49602)
text domain woocommerce-analytics	jetpack-premium-analytics	Monorepo convention
symlink build hack	wp-build packages/* autodiscovery	Internal-package convention (no link: self-dep, matching datetime/data)

What's intentionally not here

• No PHP. The sync-status milestone backend landed separately in Premium Analytics: Track analytics-aware sync milestone #49211 (merged); this is the JS half.
• 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/data package precedent).
• No new test config. The package already has Jest infrastructure (tests/jest.config.cjs + babel.config.cjs, landed with the data port feat(premium-analytics): port data package from next-woocommerce-analytics #49263); the hook's jest.mock calls work under that shared babel transform, so no custom transform is needed here.
• Live milestone. initial_full_sync_finished is seeded from page-load script-data, then refreshed live from each /jetpack/v4/sync/status poll (the backend surfaces it there — stacked PR feat(premium-analytics): expose initial_full_sync_finished on sync status response #49602), so it flips mid-session without a reload. Covered by tests.

Parent-level wiring (projects/packages/premium-analytics/)

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/data use). This PR adds:

• dependencies: @automattic/jetpack-script-data (consumed by both init and site-sync).
• devDependencies: @testing-library/react (the useSyncStatus hook test uses renderHook).

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

No.

Testing instructions

Requires Node 24 (repo engineStrict).

pnpm install
cd projects/packages/premium-analytics
pnpm test         # jest — 121 tests pass (incl. site-sync status helpers + useSyncStatus hook)
pnpm typecheck    # tsgo --noEmit — passes
pnpm exec eslint . # clean
pnpm build        # wp-build — passes

Quick visual test (optional — via companion branch)

The review-only branch wooa7s-1321-site-sync-test-harness-v2 wires useSyncStatus into the dashboard as a debug panel + Trigger full sync button. The real woocommerce_analytics sync module isn't registered yet, so it points the watched module (and the backend milestone filter) at posts for real progress. Do not merge.

git fetch origin wooa7s-1321-site-sync-test-harness-v2 && git checkout wooa7s-1321-site-sync-test-harness-v2
pnpm install && cd projects/packages/premium-analytics && pnpm build
wp post generate --count=1500

On a Jetpack-connected site, open the dashboard and click Trigger full sync: percentage climbs 0 → 100, isRunning flips true → false, isComplete becomes true, and initialFullSyncFinished flips 0 → <timestamp> live (#49602, no reload).

Screen.Recording.2026-06-15.at.1.49.38.PM.mov

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

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 · JS report

[louwie17]

This tested well, and code looks good!
I did leave one inline comment with something Claude pointed out, at initial glance it seems not super likely, but figured I mention it. ( I didn't have time to dig into it further ). But for the sake of this PR, I think we can merge this and address it as a follow up if you think it makes sense.

[louwie17]

Claude seemed to think this could potentially fall short because of this, I don't have quite enough time to dig into this further today, but figured I mention it now:

[suggestion] Stall detection can misfire on a normally-completing sync and stop polling irrecoverably.

  use-sync-status.ts:83-89 clears the polling interval and surfaces a "Sync has stalled" error whenever a poll returns isStarted && !isRunning && !isSyncComplete. And isSyncComplete requires
  both percentage >= 100 and milestone > 0 (status.ts:42-43).

  The problem is that those two inputs come from different backend signals:
  - finished (→ isRunning) reflects Jetpack core's full-sync module state, returned by /jetpack/v4/sync/status.
  - initial_full_sync_finished (the milestone) is set separately in Sync_Status_Tracker::on_sync_processed_actions — only once the jetpack_full_sync_end action is confirmed processed — and then
  bolted onto the same response via enrich_sync_status_response (rest_post_dispatch).

  They ride on the same HTTP response, but they don't share a source of truth. So if any poll observes finished: true before the milestone option has flipped, the hook computes: percentage 100,
  isRunning false, isComplete false (milestone still 0) → isStalled = true → it calls clearPolling() and tears down polling permanently. The very next poll that would have carried the milestone
  never runs. The user is left on a false "stalled" error until they manually hit retry (triggerSync).

  Why it may or may not reproduce: with Full_Sync_Immediately (inline action processing), the module-finished flip and the jetpack_sync_processed_actions fire in the same cycle, so milestone and
  finished likely land together — no gap. With the legacy queue-based path, or any lag between "module marked finished" and "end-action processed," the window opens.

  Suggested fixes (either):
  - Don't clear polling on the first stalled observation — require N consecutive stalls, mirroring the MAX_POLL_FAILURES pattern the error path already uses.
  - Or treat finished && milestone === 0 as "finishing, keep polling" rather than stalled, so a one-poll lag self-heals.

[chihsuan]

I did leave one inline comment with something Claude pointed out, at initial glance it seems not super likely, but figured I mention it. ( I didn't have time to dig into it further ). But for the sake of this PR, I think we can merge this and address it as a follow up if you think it makes sense

Thanks for flagging this! @louwie17 Yes, I dug into the actual flow, and I think we're safe on the path that ships.

On the default path it can't happen but happy to do it as a follow-up.

The base branch was changed.