feat(core): add ServiceWorker onStateChange telemetry hook (#14867)

* feat(core): add optional onStateChange telemetry hook to ServiceWorker

Add an additive, vendor-neutral telemetry hook to the ServiceWorker
class. When a consumer supplies register(..., { onStateChange }), the
handler is invoked on every service worker statechange event.

The existing built-in Pinpoint auto-recording is preserved but now
guarded: it only runs when no onStateChange handler is provided, so a
supplied handler overrides it and prevents double-recording. The
implicit Pinpoint auto-recording is deprecated in favor of onStateChange
and will be removed in a future major version.

Behavior details:
- The handler is captured per register() call, so re-registering with a
  different handler only affects its own statechange listener.
- Consumer handler invocation is wrapped in try/catch; a throwing handler
  is logged via logger.error and never rejects out of the async listener.

Backwards compatible: with no handler, behavior is unchanged.

Exports new ServiceWorkerStateChangeHandler type and ServiceWorkerOptions
interface from @aws-amplify/core and re-exports them from aws-amplify/utils.

* fix(core): await onStateChange handler so async rejections are caught

Addresses PR review feedback (review 4653674756): the statechange listener
called onStateChange?.(currentState) without awaiting. Since the handler
type (state) => void structurally accepts async handlers, a rejected promise
from an async handler escaped the synchronous try/catch as an unhandled
rejection, contradicting the documented 'never rejects out of the async
listener' guarantee.

Await the handler inside the try/catch (await undefined resolves immediately
for sync/absent handlers) and add a regression test with an async throwing
handler.

* fix(core): emit current state to onStateChange on register for already-active worker

Addresses PR review feedback (review 4653676315 / comment 3543553215): a
service worker already in a state when register() resolves (e.g. 'activated'
on a repeat visit via the registration.active branch) dispatches no
'statechange' event, so the onStateChange hook never observed the current
state.

After attaching the statechange listener, emit the current state once to the
consumer hook. The emit is intentionally scoped to onStateChange only and does
NOT invoke the built-in Pinpoint path, preserving the 'no hook = identical to
today' guarantee for existing consumers. Extract a shared _notifyStateChange
helper (used by both the listener and the initial emit) and add regression
tests for the initial emit and the no-hook no-record-on-register case.

* test(core): use real Amplify.configure instead of mocking getConfig

Author: soberm

.changeset/serviceworker-onstatechange-hook.md

@@ -0,0 +1,6 @@
+---
+'@aws-amplify/core': minor
+'aws-amplify': minor
+---
+
+feat(core): add optional onStateChange telemetry hook to ServiceWorker.register(); deprecate implicit Pinpoint auto-recording of SW lifecycle events (opt-in, backwards compatible)

packages/aws-amplify/src/utils/index.ts

@@ -11,6 +11,8 @@ export {
 	Cache,
 	ConsoleLogger,
 	ServiceWorker,
+	ServiceWorkerOptions,
+	ServiceWorkerStateChangeHandler,
 	CookieStorage,
 	defaultStorage,
 	sessionStorage,

packages/core/__tests__/ServiceWorker.test.ts

@@ -1,6 +1,12 @@
 import { AmplifyError } from '../src/libraryUtils';
 import { ServiceWorker } from '../src';
 import { ServiceWorkerErrorCode } from '../src/ServiceWorker/errorHelpers';
+import { record } from '../src/providers/pinpoint';
+import { Amplify, fetchAuthSession } from '../src/singleton';
+import { ConsoleLogger } from '../src/Logger';
+
+jest.mock('../src/providers/pinpoint');
+jest.mock('../src/singleton/apis/fetchAuthSession');
 
 describe('ServiceWorker test', () => {
 	describe('Error conditions', () => {
@@ -168,4 +174,248 @@ describe('ServiceWorker test', () => {
 			);
 		});
 	});
+	describe('State change telemetry', () => {
+		const pinpointConfig = {
+			appId: 'test-app-id',
+			region: 'us-east-1',
+			bufferSize: 100,
+			flushInterval: 1000,
+			flushSize: 10,
+			resendLimit: 5,
+		};
+		const credentials = {
+			accessKeyId: 'access-key-id',
+			secretAccessKey: 'secret-access-key',
+		};
+
+		const registerAndGetStateChangeHandler = async (
+			onStateChange?: (state: ServiceWorkerState) => void,
+		): Promise<() => Promise<void>> => {
+			const mockServiceWorker = {
+				state: 'activated' as ServiceWorkerState,
+				addEventListener: jest.fn(),
+			};
+
+			(global as any).navigator.serviceWorker = {
+				register: () => Promise.resolve({ installing: mockServiceWorker }),
+			};
+
+			const serviceWorker = new ServiceWorker();
+			await serviceWorker.register(
+				'/service-worker.js',
+				'/',
+				onStateChange ? { onStateChange } : undefined,
+			);
+
+			const [, stateChangeHandler] =
+				mockServiceWorker.addEventListener.mock.calls.find(
+					call => call[0] === 'statechange',
+				) ?? [];
+
+			return stateChangeHandler;
+		};
+
+		beforeEach(() => {
+			jest.clearAllMocks();
+			Amplify.configure({
+				Analytics: { Pinpoint: pinpointConfig },
+			});
+			(fetchAuthSession as jest.Mock).mockResolvedValue({ credentials });
+		});
+
+		afterAll(() => {
+			jest.restoreAllMocks();
+		});
+
+		test('records a Pinpoint event when no onStateChange handler is provided', async () => {
+			const handleStateChange = await registerAndGetStateChangeHandler();
+
+			await handleStateChange();
+
+			expect(record).toHaveBeenCalledTimes(1);
+			expect(record).toHaveBeenCalledWith(
+				expect.objectContaining({
+					appId: pinpointConfig.appId,
+					region: pinpointConfig.region,
+					category: 'Core',
+					credentials,
+					event: {
+						name: 'ServiceWorker',
+						attributes: { state: 'activated' },
+					},
+				}),
+			);
+		});
+
+		test('invokes onStateChange and suppresses built-in recording when a handler is provided', async () => {
+			const onStateChange = jest.fn();
+			const handleStateChange =
+				await registerAndGetStateChangeHandler(onStateChange);
+			// Ignore the initial-state emit fired during register(); this test
+			// isolates the statechange-listener path (covered separately below).
+			onStateChange.mockClear();
+
+			await handleStateChange();
+
+			expect(onStateChange).toHaveBeenCalledTimes(1);
+			expect(onStateChange).toHaveBeenCalledWith('activated');
+			// The provided handler overrides the built-in path: no double-recording.
+			expect(fetchAuthSession).not.toHaveBeenCalled();
+			expect(record).not.toHaveBeenCalled();
+		});
+
+		test('does not record when Pinpoint is not configured and no handler is provided', async () => {
+			Amplify.configure({});
+			const handleStateChange = await registerAndGetStateChangeHandler();
+
+			await handleStateChange();
+
+			expect(record).not.toHaveBeenCalled();
+		});
+
+		test('logs and swallows errors thrown by the onStateChange handler', async () => {
+			const errorSpy = jest
+				.spyOn(ConsoleLogger.prototype, 'error')
+				.mockImplementation(() => undefined);
+			const thrown = new Error('handler boom');
+			const onStateChange = jest.fn(() => {
+				throw thrown;
+			});
+			const handleStateChange =
+				await registerAndGetStateChangeHandler(onStateChange);
+			// Ignore the initial-state emit fired during register().
+			onStateChange.mockClear();
+			errorSpy.mockClear();
+
+			// A throwing handler must not reject out of the async listener.
+			await expect(handleStateChange()).resolves.toBeUndefined();
+
+			expect(onStateChange).toHaveBeenCalledWith('activated');
+			expect(errorSpy).toHaveBeenCalledWith(
+				'onStateChange handler threw',
+				thrown,
+			);
+			// The built-in path stays suppressed even when the handler throws.
+			expect(record).not.toHaveBeenCalled();
+
+			errorSpy.mockRestore();
+		});
+
+		test('logs and swallows errors thrown by an async onStateChange handler', async () => {
+			const errorSpy = jest
+				.spyOn(ConsoleLogger.prototype, 'error')
+				.mockImplementation(() => undefined);
+			const thrown = new Error('async handler boom');
+			const onStateChange = jest.fn(async () => {
+				throw thrown;
+			});
+			const handleStateChange =
+				await registerAndGetStateChangeHandler(onStateChange);
+			// Let the initial-state emit's async rejection settle, then ignore it.
+			await new Promise(resolve => setTimeout(resolve, 0));
+			onStateChange.mockClear();
+			errorSpy.mockClear();
+
+			// An async handler that rejects must not reject out of the async
+			// listener (the listener awaits the handler inside the try/catch).
+			await expect(handleStateChange()).resolves.toBeUndefined();
+
+			expect(onStateChange).toHaveBeenCalledWith('activated');
+			expect(errorSpy).toHaveBeenCalledWith(
+				'onStateChange handler threw',
+				thrown,
+			);
+			// The built-in path stays suppressed even when the handler rejects.
+			expect(record).not.toHaveBeenCalled();
+
+			errorSpy.mockRestore();
+		});
+
+		test('invokes the handler once per statechange event', async () => {
+			const onStateChange = jest.fn();
+			const handleStateChange =
+				await registerAndGetStateChangeHandler(onStateChange);
+			// Ignore the initial-state emit fired during register().
+			onStateChange.mockClear();
+
+			await handleStateChange();
+			await handleStateChange();
+			await handleStateChange();
+
+			expect(onStateChange).toHaveBeenCalledTimes(3);
+			expect(record).not.toHaveBeenCalled();
+		});
+
+		test('captures the handler per registration so re-register does not re-target a prior listener', async () => {
+			const handlerA = jest.fn();
+			const handlerB = jest.fn();
+			const workerA = {
+				state: 'activated' as ServiceWorkerState,
+				addEventListener: jest.fn(),
+			};
+			const workerB = {
+				state: 'activated' as ServiceWorkerState,
+				addEventListener: jest.fn(),
+			};
+			const serviceWorker = new ServiceWorker();
+
+			(global as any).navigator.serviceWorker = {
+				register: () => Promise.resolve({ installing: workerA }),
+			};
+			await serviceWorker.register('/service-worker.js', '/', {
+				onStateChange: handlerA,
+			});
+
+			(global as any).navigator.serviceWorker = {
+				register: () => Promise.resolve({ installing: workerB }),
+			};
+			await serviceWorker.register('/service-worker.js', '/', {
+				onStateChange: handlerB,
+			});
+
+			// Both registrations fire an initial-state emit; ignore those here so
+			// this test isolates the per-listener capture behavior.
+			handlerA.mockClear();
+			handlerB.mockClear();
+
+			const [, listenerA] =
+				workerA.addEventListener.mock.calls.find(
+					call => call[0] === 'statechange',
+				) ?? [];
+
+			await listenerA();
+
+			// The first listener keeps its own captured handler even after a
+			// second registration swapped the instance's current handler.
+			expect(handlerA).toHaveBeenCalledTimes(1);
+			expect(handlerA).toHaveBeenCalledWith('activated');
+			expect(handlerB).not.toHaveBeenCalled();
+			expect(record).not.toHaveBeenCalled();
+		});
+
+		test('emits the current state to the handler on register when the worker is already in a state', async () => {
+			const onStateChange = jest.fn();
+
+			// registerAndGetStateChangeHandler resolves after register() completes;
+			// the initial-state emit runs synchronously during _setupListeners, so
+			// the handler has already been notified with the current state without
+			// any statechange event being dispatched.
+			await registerAndGetStateChangeHandler(onStateChange);
+
+			expect(onStateChange).toHaveBeenCalledTimes(1);
+			expect(onStateChange).toHaveBeenCalledWith('activated');
+			// The initial emit must NOT trigger the built-in Pinpoint path; that
+			// path stays unchanged for consumers that do not pass a handler.
+			expect(fetchAuthSession).not.toHaveBeenCalled();
+			expect(record).not.toHaveBeenCalled();
+		});
+
+		test('does not record to Pinpoint on register when no handler is provided (no initial emit)', async () => {
+			// Without a handler there is no initial emit, and the built-in path is
+			// only exercised on an actual statechange event, not on register().
+			await registerAndGetStateChangeHandler();
+
+			expect(record).not.toHaveBeenCalled();
+		});
+	});
 });