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

projects/packages/premium-analytics/changelog/add-site-sync

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Add site-sync package (useSyncStatus hook) and configure apiFetch auth in init.

projects/packages/premium-analytics/jest.config.cjs

@@ -0,0 +1,21 @@
+const baseConfig = require( 'jetpack-js-tools/jest/config.base.js' );
+
+module.exports = {
+	...baseConfig,
+	rootDir: '.',
+	collectCoverageFrom: [
+		'<rootDir>/packages/**/src/**/*.{js,jsx,ts,tsx}',
+		...baseConfig.collectCoverageFrom,
+	],
+	// Compile TS/JSX to CommonJS (rather than leaving native ESM). `jest.mock`
+	// hoisting relies on `require`, which is undefined when `.ts` runs as ESM
+	// under `--experimental-vm-modules`; emitting CJS keeps mocks working without
+	// that flag. Mirrors the shared transform used by js-packages/charts.
+	transform: {
+		...baseConfig.transform,
+		'\\.[jt]sx?$': require( 'jetpack-js-tools/jest/babel-jest-config-factory.js' )(
+			require.resolve
+		),
+	},
+	extensionsToTreatAsEsm: [],
+};

projects/packages/premium-analytics/package.json

@@ -6,6 +6,7 @@
 	"scripts": {
 		"build": "wp-build && mkdir -p build/modules/boot && cp shims/boot-asset.php build/modules/boot/index.min.asset.php",
 		"build-production": "NODE_ENV=production wp-build && mkdir -p build/modules/boot && cp shims/boot-asset.php build/modules/boot/index.min.asset.php",
+		"test": "jest",
 		"typecheck": "tsgo --noEmit",
 		"watch": "wp-build --watch"
 	},
@@ -29,6 +30,8 @@
 		}
 	},
 	"dependencies": {
+		"@automattic/jetpack-script-data": "workspace:*",
+		"@wordpress/api-fetch": "^7.22.0",
 		"@wordpress/boot": "0.13.0",
 		"@wordpress/data": "10.46.0",
 		"@wordpress/i18n": "^6.9.0",
@@ -38,9 +41,18 @@
 		"react-dom": "18.3.1"
 	},
 	"devDependencies": {
+		"@automattic/jetpack-webpack-config": "workspace:*",
 		"@babel/core": "7.29.0",
+		"@babel/preset-react": "7.28.5",
+		"@babel/preset-typescript": "7.28.5",
+		"@babel/runtime": "7.29.2",
+		"@testing-library/dom": "10.4.1",
+		"@testing-library/react": "16.3.2",
+		"@types/jest": "30.0.0",
 		"@typescript/native-preview": "7.0.0-dev.20260225.1",
 		"@wordpress/build": "0.14.0",
-		"browserslist": "4.28.2"
+		"babel-jest": "30.4.1",
+		"browserslist": "4.28.2",
+		"jest": "30.4.2"
 	}
 }

projects/packages/premium-analytics/packages/init/package.json

@@ -7,6 +7,8 @@
 	"module": "build-module/index.mjs",
 	"wpScriptModuleExports": "./build-module/index.mjs",
 	"dependencies": {
+		"@automattic/jetpack-script-data": "workspace:*",
+		"@wordpress/api-fetch": "^7.22.0",
 		"@wordpress/boot": "0.13.0",
 		"@wordpress/data": "10.46.0",
 		"@wordpress/icons": "^13.0.0"

projects/packages/premium-analytics/packages/init/src/index.ts

@@ -1,6 +1,8 @@
 /**
  * External dependencies
  */
+import { getScriptData } from '@automattic/jetpack-script-data';
+import apiFetch from '@wordpress/api-fetch';
 import { store as bootStore } from '@wordpress/boot';
 import { dispatch } from '@wordpress/data';
 import { chartBar } from '@wordpress/icons';
@@ -10,6 +12,16 @@ import { chartBar } from '@wordpress/icons';
  * Runs before routes render.
  */
 export async function init(): Promise< void > {
+	// Point apiFetch at this site's REST API and authenticate requests. Required
+	// before any package (e.g. site-sync) calls apiFetch against /jetpack/v4/*.
+	const site = getScriptData()?.site;
+	if ( site?.rest_root ) {
+		apiFetch.use( apiFetch.createRootURLMiddleware( site.rest_root ) );
+	}
+	if ( site?.rest_nonce ) {
+		apiFetch.use( apiFetch.createNonceMiddleware( site.rest_nonce ) );
+	}
+
 	dispatch( bootStore ).updateMenuItem( 'dashboard', {
 		icon: chartBar,
 	} );

projects/packages/premium-analytics/packages/site-sync/package.json

@@ -0,0 +1,18 @@
+{
+	"private": true,
+	"name": "@automattic/jetpack-premium-analytics-site-sync",
+	"version": "0.1.0",
+	"type": "module",
+	"wpScript": true,
+	"module": "build-module/index.mjs",
+	"wpScriptModuleExports": "./build-module/index.mjs",
+	"dependencies": {
+		"@automattic/jetpack-script-data": "workspace:*",
+		"@wordpress/api-fetch": "^7.22.0",
+		"@wordpress/i18n": "^6.9.0",
+		"react": "18.3.1"
+	},
+	"devDependencies": {
+		"@testing-library/react": "16.3.2"
+	}
+}

projects/packages/premium-analytics/packages/site-sync/src/api/fetch-sync-status.ts

@@ -0,0 +1,18 @@
+/**
+ * External dependencies
+ */
+import apiFetch from '@wordpress/api-fetch';
+/**
+ * Internal dependencies
+ */
+import { SYNC_STATUS_PATH } from '../constants';
+import type { SyncStatusApiResponse } from '../types';
+
+/**
+ * Fetch the current sync status from Jetpack core.
+ *
+ * @return The current sync status.
+ */
+export function fetchSyncStatus(): Promise< SyncStatusApiResponse > {
+	return apiFetch( { path: SYNC_STATUS_PATH } );
+}

projects/packages/premium-analytics/packages/site-sync/src/api/trigger-full-sync.ts

@@ -0,0 +1,17 @@
+/**
+ * External dependencies
+ */
+import apiFetch from '@wordpress/api-fetch';
+/**
+ * Internal dependencies
+ */
+import { FULL_SYNC_PATH } from '../constants';
+
+/**
+ * Trigger a Jetpack full sync.
+ *
+ * @return The full-sync trigger response.
+ */
+export function triggerFullSync(): Promise< unknown > {
+	return apiFetch( { path: FULL_SYNC_PATH, method: 'POST' } );
+}

projects/packages/premium-analytics/packages/site-sync/src/constants.ts

@@ -0,0 +1,20 @@
+/**
+ * Polling interval in milliseconds.
+ */
+export const POLL_INTERVAL = 3_000;
+
+/**
+ * Jetpack core sync status endpoint (queue + full-sync state).
+ */
+export const SYNC_STATUS_PATH = '/jetpack/v4/sync/status';
+
+/**
+ * Jetpack core full-sync trigger endpoint.
+ */
+export const FULL_SYNC_PATH = '/jetpack/v4/sync/full-sync';
+
+/**
+ * Sync-module key whose progress gates the analytics dashboard. Mirrors the
+ * backend default (`Sync_Status_Tracker::ANALYTICS_SYNC_MODULE`).
+ */
+export const ANALYTICS_SYNC_MODULE = 'woocommerce_analytics';

projects/packages/premium-analytics/packages/site-sync/src/hooks/__tests__/use-sync-status.test.ts

@@ -0,0 +1,120 @@
+/**
+ * External dependencies
+ */
+import { getScriptData } from '@automattic/jetpack-script-data';
+import { renderHook, act, waitFor } from '@testing-library/react';
+/**
+ * Internal dependencies
+ */
+import { fetchSyncStatus } from '../../api/fetch-sync-status';
+import { triggerFullSync } from '../../api/trigger-full-sync';
+import { useSyncStatus } from '../use-sync-status';
+import type { SyncStatusApiResponse } from '../../types';
+
+jest.mock( '../../api/fetch-sync-status' );
+jest.mock( '../../api/trigger-full-sync' );
+jest.mock( '@automattic/jetpack-script-data' );
+
+const mockFetch = fetchSyncStatus as jest.MockedFunction< typeof fetchSyncStatus >;
+const mockTrigger = triggerFullSync as jest.MockedFunction< typeof triggerFullSync >;
+const mockScriptData = getScriptData as jest.MockedFunction< typeof getScriptData >;
+
+/**
+ * Build a raw sync-status API response for tests.
+ *
+ * @param overrides - Fields to override on the default running-analytics response.
+ * @return A raw sync-status API response.
+ */
+function rawStatus( overrides: Partial< SyncStatusApiResponse > = {} ): SyncStatusApiResponse {
+	return {
+		started: true,
+		finished: false,
+		progress: { woocommerce_analytics: { sent: 1, total: 2 } },
+		...overrides,
+	};
+}
+
+beforeEach( () => {
+	jest.useFakeTimers();
+	// Default: milestone not set.
+	mockScriptData.mockReturnValue( {
+		premium_analytics: { initial_full_sync_finished: 0 },
+	} as ReturnType< typeof getScriptData > );
+	mockFetch.mockResolvedValue( rawStatus() );
+	mockTrigger.mockResolvedValue( undefined );
+} );
+
+afterEach( () => {
+	jest.clearAllTimers();
+	jest.useRealTimers();
+	jest.clearAllMocks();
+} );
+
+describe( 'useSyncStatus', () => {
+	it( 'exposes normalized progress after the first poll', async () => {
+		const { result } = renderHook( () => useSyncStatus() );
+
+		await waitFor( () => expect( result.current.isLoading ).toBe( false ) );
+		expect( result.current.data?.percentage ).toBe( 50 );
+		expect( result.current.data?.isRunning ).toBe( true );
+		expect( result.current.error ).toBeNull();
+	} );
+
+	it( 'reports complete and stops polling when analytics reaches 100', async () => {
+		mockFetch.mockResolvedValue(
+			rawStatus( {
+				finished: true,
+				progress: { woocommerce_analytics: { sent: 2, total: 2 } },
+			} )
+		);
+		const { result } = renderHook( () => useSyncStatus() );
+
+		await waitFor( () => expect( result.current.isComplete ).toBe( true ) );
+		const callsAfterComplete = mockFetch.mock.calls.length;
+
+		await act( async () => {
+			jest.advanceTimersByTime( 10_000 );
+		} );
+		expect( mockFetch.mock.calls ).toHaveLength( callsAfterComplete );
+	} );
+
+	it( 'flags a stalled sync with an error', async () => {
+		mockFetch.mockResolvedValue(
+			rawStatus( {
+				started: true,
+				finished: true,
+				progress: { woocommerce_analytics: { sent: 1, total: 2 } },
+			} )
+		);
+		const { result } = renderHook( () => useSyncStatus() );
+
+		await waitFor( () => expect( result.current.isStalled ).toBe( true ) );
+		expect( result.current.error ).toBeInstanceOf( Error );
+	} );
+
+	it( 'surfaces fetch errors and never rejects triggerSync', async () => {
+		mockFetch.mockRejectedValueOnce( new Error( 'boom' ) );
+		const { result } = renderHook( () => useSyncStatus() );
+
+		await waitFor( () => expect( result.current.error ).toBeInstanceOf( Error ) );
+		expect( result.current.error?.message ).toBe( 'boom' );
+
+		// triggerSync resolves even if the trigger call fails.
+		mockTrigger.mockRejectedValueOnce( new Error( 'nope' ) );
+		await act( async () => {
+			await result.current.triggerSync();
+		} );
+		expect( result.current.error?.message ).toBe( 'nope' );
+	} );
+
+	it( 'starts complete and skips polling when the milestone is set', async () => {
+		mockScriptData.mockReturnValue( {
+			premium_analytics: { initial_full_sync_finished: 1_700_000_000 },
+		} as ReturnType< typeof getScriptData > );
+
+		const { result } = renderHook( () => useSyncStatus() );
+
+		await waitFor( () => expect( result.current.isComplete ).toBe( true ) );
+		expect( mockFetch ).not.toHaveBeenCalled();
+	} );
+} );