@aws-amplify/notifications 2.0.1-console-preview.5a31ca1.0 → 2.0.1-console-preview.8d88eef.0

package/src/pushNotifications/index.ts

@@ -1,9 +1,31 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export { identifyUser } from './providers/pinpoint';
 export {
-	PushNotificationEvent,
-	PushNotificationMessage,
-	PushNotificationPermissionStatus,
-} from './types';
+	getBadgeCount,
+	getLaunchNotification,
+	GetLaunchNotificationOutput,
+	getPermissionStatus,
+	GetPermissionStatusOutput,
+	identifyUser,
+	IdentifyUserInput,
+	initializePushNotifications,
+	onNotificationOpened,
+	OnNotificationOpenedInput,
+	OnNotificationOpenedOutput,
+	onNotificationReceivedInBackground,
+	OnNotificationReceivedInBackgroundInput,
+	OnNotificationReceivedInBackgroundOutput,
+	onNotificationReceivedInForeground,
+	OnNotificationReceivedInForegroundInput,
+	OnNotificationReceivedInForegroundOutput,
+	onTokenReceived,
+	OnTokenReceivedInput,
+	OnTokenReceivedOutput,
+	requestPermissions,
+	RequestPermissionsInput,
+	setBadgeCount,
+	SetBadgeCountInput,
+} from './providers/pinpoint';
+export { PushNotificationMessage } from './types';
+export { PushNotificationError } from './errors';

package/src/pushNotifications/providers/pinpoint/apis/getBadgeCount.native.ts

@@ -0,0 +1,9 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { loadAmplifyPushNotification } from '@aws-amplify/react-native';
+import { GetBadgeCount } from '../types';
+
+const { getBadgeCount: getBadgeCountNative } = loadAmplifyPushNotification();
+
+export const getBadgeCount: GetBadgeCount = async () => getBadgeCountNative();

package/src/pushNotifications/providers/pinpoint/apis/getBadgeCount.ts

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+import { GetBadgeCount } from '../types';
+
+/**
+ * Returns the current badge count (the number next to your app's icon). This function is safe to call (but will be
+ * ignored) even when your React Native app is running on platforms where badges are not supported.
+ *
+ * @throws platform: {@link PlatformNotSupportedError} - Thrown if called against an unsupported platform. Currently,
+ * only React Native is supported by this API.
+ * @returns A promise that resolves to a number representing the current count displayed on the app badge.
+ * @example
+ * ```ts
+ * const badgeCount = await getBadgeCount();
+ * ```
+ */
+export const getBadgeCount: GetBadgeCount = () => {
+	throw new PlatformNotSupportedError();
+};

package/src/pushNotifications/providers/pinpoint/apis/getLaunchNotification.native.ts

@@ -0,0 +1,11 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { loadAmplifyPushNotification } from '@aws-amplify/react-native';
+import { GetLaunchNotification } from '../types';
+
+const { getLaunchNotification: getLaunchNotificationNative } =
+	loadAmplifyPushNotification();
+
+export const getLaunchNotification: GetLaunchNotification = () =>
+	getLaunchNotificationNative();

package/src/pushNotifications/providers/pinpoint/apis/getLaunchNotification.ts

@@ -0,0 +1,26 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+import { PushNotificationMessage } from '../../../types';
+import { GetLaunchNotification, GetLaunchNotificationOutput } from '../types';
+
+/**
+ * Returns the notification which launched your app from a terminated state. The launch notification is consumed by
+ * calls to this function and will yield a null result if:
+ *   1. It is more than once (i.e. subsequent calls will be null)
+ *   2. Another notification was opened while your app was running (either in foreground or background)
+ *   3. Your app was brought back to the foreground by some other means (e.g. user tapped the app icon)
+ *
+ * @throws platform: {@link PlatformNotSupportedError} - Thrown if called against an unsupported platform. Currently,
+ * only React Native is supported by this API.
+ * @returns {Promise<GetLaunchNotificationOutput>} - a promise resolving to {@link PushNotificationMessage} if there is
+ * a launch notification and `null` otherwise.
+ * @example
+ * ```ts
+ * const launchNotification = await getLaunchNotification();
+ * ```
+ */
+export const getLaunchNotification: GetLaunchNotification = () => {
+	throw new PlatformNotSupportedError();
+};

package/src/pushNotifications/providers/pinpoint/apis/getPermissionStatus.native.ts

@@ -0,0 +1,11 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { loadAmplifyPushNotification } from '@aws-amplify/react-native';
+import { GetPermissionStatus } from '../types';
+
+const { getPermissionStatus: getPermissionStatusNative } =
+	loadAmplifyPushNotification();
+
+export const getPermissionStatus: GetPermissionStatus = () =>
+	getPermissionStatusNative();

package/src/pushNotifications/providers/pinpoint/apis/getPermissionStatus.ts

@@ -0,0 +1,34 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+import { GetPermissionStatus, GetPermissionStatusOutput } from '../types';
+
+/**
+ * Returns a string representing the current status of user permissions to display push notifications. The possible
+ * statuses are as follows:
+ *
+ *   * `'shouldRequest'` - No permissions have been requested yet. It is idiomatic at this time to simply request for
+ *   permissions from the user.
+ *
+ *   * `'shouldExplainThenRequest'` - It is recommended at this time to provide some context or rationale to the user
+ *   explaining why you want to send them push notifications before requesting for permissions.
+ *
+ *   * `'granted'` - Permissions have been granted by the user. No further actions are needed and their app is ready to
+ *   display notifications.
+ *
+ *   * `'denied'` - Permissions have been denied by the user. Further attempts to request permissions will no longer
+ *   trigger a permission dialog. Your app should now either degrade gracefully or prompt your user to grant the
+ *   permissions needed in their device settings.
+ *
+ * @throws platform: {@link PlatformNotSupportedError} - Thrown if called against an unsupported platform. Currently,
+ * only React Native is supported by this API.
+ * @return {Promise<GetPermissionStatusOutput>} a promise resolving to a string representing the current status of user
+ * selected notification permissions.
+ * @example
+ * ```ts
+ * const permissionStatus = await getPermissionStatus();
+ */
+export const getPermissionStatus: GetPermissionStatus = () => {
+	throw new PlatformNotSupportedError();
+};

package/src/pushNotifications/providers/pinpoint/apis/identifyUser.native.ts

@@ -0,0 +1,38 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PushNotificationAction } from '@aws-amplify/core/internals/utils';
+import { updateEndpoint } from '@aws-amplify/core/internals/providers/pinpoint';
+import {
+	getChannelType,
+	getPushNotificationUserAgentString,
+	resolveConfig,
+	resolveCredentials,
+} from '../utils';
+import { IdentifyUser } from '../types';
+
+export const identifyUser: IdentifyUser = async ({
+	userId,
+	userProfile,
+	options,
+}) => {
+	const { credentials, identityId } = await resolveCredentials();
+	const { appId, region } = resolveConfig();
+	const { address, optOut, userAttributes } = options ?? {};
+	updateEndpoint({
+		address,
+		channelType: getChannelType(),
+		optOut,
+		appId,
+		category: 'PushNotification',
+		credentials,
+		identityId,
+		region,
+		userAttributes,
+		userId,
+		userProfile,
+		userAgentValue: getPushNotificationUserAgentString(
+			PushNotificationAction.IdentifyUser
+		),
+	});
+};

package/src/pushNotifications/providers/pinpoint/apis/identifyUser.ts

@@ -1,11 +1,62 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { UserInfo } from '../../../../types';
+import { UpdateEndpointException } from '@aws-amplify/core/internals/providers/pinpoint';
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+import { PushNotificationValidationErrorCode } from '../../../errors';
+import { IdentifyUser, IdentifyUserInput } from '../types';
 
-export function identifyUser(
-	userId: string,
-	userInfo: UserInfo
-): Promise<void> {
-	throw new Error('WIP');
-}
+/**
+ * Sends information about a user to Pinpoint. Sending user information allows you to associate a user to their user
+ * profile and activities or actions in your application. Activity can be tracked across devices & platforms by using
+ * the same `userId`.
+ *
+ * @param {IdentifyUserInput} input The input object used to construct requests sent to Pinpoint's UpdateEndpoint
+ *  API.
+ * @throws service: {@link UpdateEndpointException} - Thrown when the underlying Pinpoint service returns an error.
+ * @throws validation: {@link PushNotificationValidationErrorCode} - Thrown when the provided parameters or library
+ *  configuration is incorrect.
+ * @throws platform: {@link PlatformNotSupportedError} - Thrown if called against an unsupported platform. Currently,
+ * only React Native is supported by this API.
+ * @returns A promise that will resolve when the operation is complete.
+ * @example
+ * ```ts
+ * // Identify a user with Pinpoint
+ * await identifyUser({
+ *     userId,
+ *     userProfile: {
+ *         email: 'userEmail@example.com'
+ *         customProperties: {
+ *             phoneNumber: ['555-555-5555'],
+ *         },
+ *     }
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Identify a user with Pinpoint specific options
+ * await identifyUser({
+ *     userId,
+ *     userProfile: {
+ *         email: 'userEmail@example.com'
+ *         customProperties: {
+ *             phoneNumber: ['555-555-5555'],
+ *         },
+ *         demographic: {
+ *             platform: 'ios',
+ *             timezone: 'America/Los_Angeles'
+ *         }
+ *     },
+ *     options: {
+ *         address: 'device-address',
+ *         optOut: 'NONE',
+ *         userAttributes: {
+ *             interests: ['food']
+ *         },
+ *     },
+ * });
+ */
+export const identifyUser: IdentifyUser = () => {
+	throw new PlatformNotSupportedError();
+};

package/src/pushNotifications/providers/pinpoint/apis/index.ts

@@ -1,4 +1,14 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+export { getBadgeCount } from './getBadgeCount';
+export { getLaunchNotification } from './getLaunchNotification';
+export { getPermissionStatus } from './getPermissionStatus';
 export { identifyUser } from './identifyUser';
+export { initializePushNotifications } from './initializePushNotifications';
+export { onNotificationOpened } from './onNotificationOpened';
+export { onNotificationReceivedInBackground } from './onNotificationReceivedInBackground';
+export { onNotificationReceivedInForeground } from './onNotificationReceivedInForeground';
+export { onTokenReceived } from './onTokenReceived';
+export { requestPermissions } from './requestPermissions';
+export { setBadgeCount } from './setBadgeCount';

package/src/pushNotifications/providers/pinpoint/apis/initializePushNotifications.native.ts

@@ -0,0 +1,197 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ConsoleLogger } from '@aws-amplify/core';
+import { PushNotificationAction } from '@aws-amplify/core/internals/utils';
+import { updateEndpoint } from '@aws-amplify/core/internals/providers/pinpoint';
+import { loadAmplifyPushNotification } from '@aws-amplify/react-native';
+import {
+	EventListenerRemover,
+	addEventListener,
+	notifyEventListeners,
+	notifyEventListenersAndAwaitHandlers,
+} from '../../../../eventListeners';
+import {
+	createMessageEventRecorder,
+	getChannelType,
+	getPushNotificationUserAgentString,
+	getToken,
+	initialize,
+	isInitialized,
+	resolveConfig,
+	resolveCredentials,
+	setToken,
+} from '../utils';
+
+const {
+	addMessageEventListener,
+	addTokenEventListener,
+	completeNotification,
+	getConstants,
+	registerHeadlessTask,
+} = loadAmplifyPushNotification();
+
+const logger = new ConsoleLogger('Notifications.PushNotification');
+
+const BACKGROUND_TASK_TIMEOUT = 25; // seconds
+
+export const initializePushNotifications = (): Promise<void> => {
+	if (isInitialized()) {
+		logger.info('Push notifications have already been enabled');
+		return;
+	}
+	addNativeListeners();
+	addAnalyticsListeners();
+	initialize();
+};
+
+const addAnalyticsListeners = (): void => {
+	let launchNotificationOpenedListenerRemover: EventListenerRemover;
+
+	// wire up default Pinpoint message event handling
+	addEventListener(
+		'backgroundMessageReceived',
+		createMessageEventRecorder('backgroundMessageReceived')
+	);
+	addEventListener(
+		'foregroundMessageReceived',
+		createMessageEventRecorder('foregroundMessageReceived')
+	);
+	launchNotificationOpenedListenerRemover = addEventListener(
+		'launchNotificationsOpened',
+		createMessageEventRecorder(
+			'notificationOpened',
+			// once we are done with it we can remove the listener
+			launchNotificationOpenedListenerRemover?.remove
+		)
+	);
+	addEventListener(
+		'notificationOpened',
+		createMessageEventRecorder(
+			'notificationOpened',
+			// if we are in this state, we no longer need the listener as the app was launched via some other means
+			launchNotificationOpenedListenerRemover?.remove
+		)
+	);
+};
+
+const addNativeListeners = (): void => {
+	const { NativeEvent, NativeHeadlessTaskKey } = getConstants();
+	const {
+		BACKGROUND_MESSAGE_RECEIVED,
+		FOREGROUND_MESSAGE_RECEIVED,
+		LAUNCH_NOTIFICATION_OPENED,
+		NOTIFICATION_OPENED,
+		TOKEN_RECEIVED,
+	} = NativeEvent;
+	// on platforms that can handle headless tasks, register one to broadcast background message received to
+	// library listeners
+	if (NativeHeadlessTaskKey) {
+		registerHeadlessTask(async message => {
+			// keep headless task running until handlers have completed their work
+			await notifyEventListenersAndAwaitHandlers(
+				'backgroundMessageReceived',
+				message
+			);
+		});
+	} else if (BACKGROUND_MESSAGE_RECEIVED) {
+		// on platforms that can't handle headless tasks, listen for native background message received event and
+		// broadcast to library listeners
+		addMessageEventListener(
+			BACKGROUND_MESSAGE_RECEIVED,
+			async (message, completionHandlerId) => {
+				// keep background task running until handlers have completed their work
+				try {
+					await Promise.race([
+						notifyEventListenersAndAwaitHandlers(
+							'backgroundMessageReceived',
+							message
+						),
+						// background tasks will get suspended and all future tasks be deprioritized by the OS if they run for
+						// more than 30 seconds so we reject with a error in a shorter amount of time to prevent this from
+						// happening
+						new Promise((_, reject) => {
+							setTimeout(
+								() =>
+									reject(
+										`onNotificationReceivedInBackground handlers should complete their work within ${BACKGROUND_TASK_TIMEOUT} seconds, but they did not.`
+									),
+								BACKGROUND_TASK_TIMEOUT * 1000
+							);
+						}),
+					]);
+				} catch (err) {
+					logger.error(err);
+				} finally {
+					// notify native module that handlers have completed their work (or timed out)
+					completeNotification(completionHandlerId);
+				}
+			}
+		);
+	}
+
+	addMessageEventListener(
+		// listen for native foreground message received event and broadcast to library listeners
+		FOREGROUND_MESSAGE_RECEIVED,
+		message => {
+			notifyEventListeners('foregroundMessageReceived', message);
+		}
+	);
+
+	const launchNotificationOpenedListener = LAUNCH_NOTIFICATION_OPENED
+		? addMessageEventListener(
+				// listen for native notification opened app (user tapped on notification, opening the app from quit -
+				// not background - state) event. This is broadcasted to an internal listener only as it is not intended
+				// for use otherwise as it produces inconsistent results when used within React Native app context
+				LAUNCH_NOTIFICATION_OPENED,
+				message => {
+					notifyEventListeners('launchNotificationsOpened', message);
+					// once we are done with it we can remove the listener
+					launchNotificationOpenedListener?.remove();
+				}
+		  )
+		: null;
+
+	addMessageEventListener(
+		// listen for native notification opened (user tapped on notification, opening the app from background -
+		// not quit - state) event and broadcast to library listeners
+		NOTIFICATION_OPENED,
+		message => {
+			notifyEventListeners('notificationOpened', message);
+			// if we are in this state, we no longer need the listener as the app was launched via some other means
+			launchNotificationOpenedListener?.remove();
+		}
+	);
+
+	addTokenEventListener(
+		// listen for native new token event, automatically re-register device with provider using new token and
+		// broadcast to library listeners
+		TOKEN_RECEIVED,
+		token => {
+			// avoid a race condition where two endpoints are created with the same token on a fresh install
+			if (getToken() === token) {
+				return;
+			}
+			setToken(token);
+			registerDevice();
+			notifyEventListeners('tokenReceived', token);
+		}
+	);
+};
+
+const registerDevice = async (): Promise<void> => {
+	const { credentials, identityId } = await resolveCredentials();
+	const { appId, region } = resolveConfig();
+	return updateEndpoint({
+		address: getToken(),
+		appId,
+		category: 'PushNotification',
+		credentials,
+		region,
+		channelType: getChannelType(),
+		identityId,
+		userAgentValue: getPushNotificationUserAgentString(
+			PushNotificationAction.InitializePushNotifications
+		),
+	});
+};

package/src/pushNotifications/providers/pinpoint/apis/initializePushNotifications.ts

@@ -0,0 +1,24 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+import { InitializePushNotifications } from '../types';
+
+/**
+ * Initialize and set up the push notification category. The category must be first initialized before all other
+ * functionalities become available.
+ *
+ * @throws platform: {@link PlatformNotSupportedError} - Thrown if called against an unsupported platform. Currently,
+ * only React Native is supported by this API.
+ * @remarks
+ * It is recommended that this be called as early in your app as possible at the root of your application to allow
+ * background processing of notifications.
+ * @example
+ * ```ts
+ * Amplify.configure(config);
+ * initializePushNotifications();
+ * ```
+ */
+export const initializePushNotifications: InitializePushNotifications = () => {
+	throw new PlatformNotSupportedError();
+};

package/src/pushNotifications/providers/pinpoint/apis/onNotificationOpened.native.ts

@@ -0,0 +1,8 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { addEventListener } from '../../../../eventListeners';
+import { OnNotificationOpened } from '../types';
+
+export const onNotificationOpened: OnNotificationOpened = input =>
+	addEventListener('notificationOpened', input);

package/src/pushNotifications/providers/pinpoint/apis/onNotificationOpened.ts

@@ -0,0 +1,39 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+import { PushNotificationMessage } from '../../../types';
+import {
+	OnNotificationOpened,
+	OnNotificationOpenedInput,
+	OnNotificationOpenedOutput,
+} from '../types';
+
+/**
+ * Registers a listener that will be triggered when a notification is opened by user.
+ *
+ * @param {OnNotificationOpenedInput} input - A callback handler to be invoked with the opened
+ * {@link PushNotificationMessage}.
+ * @returns {OnNotificationOpenedOutput} - An object with a remove function to remove the listener.
+ * @example
+ * ```ts
+ * // Register a listener
+ * onNotificationOpened(message => {
+ *   doSomething(message);
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Register multiple listeners
+ * onNotificationOpened(message => {
+ *   doSomething(message);
+ * });
+ *
+ * onNotificationOpened(message => {
+ *   doSomethingElse(message);
+ * });
+ * ```
+ */
+export const onNotificationOpened: OnNotificationOpened = () => {
+	throw new PlatformNotSupportedError();
+};

package/src/pushNotifications/providers/pinpoint/apis/onNotificationReceivedInBackground.native.ts

@@ -0,0 +1,8 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { addEventListener } from '../../../../eventListeners';
+import { OnNotificationReceivedInBackground } from '../types';
+
+export const onNotificationReceivedInBackground: OnNotificationReceivedInBackground =
+	input => addEventListener('backgroundMessageReceived', input);

package/src/pushNotifications/providers/pinpoint/apis/onNotificationReceivedInBackground.ts

@@ -0,0 +1,56 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+import { PushNotificationMessage } from '../../../types';
+import {
+	OnNotificationReceivedInBackground,
+	OnNotificationReceivedInBackgroundInput,
+	OnNotificationReceivedInBackgroundOutput,
+} from '../types';
+
+/**
+ * Registers a listener that will be triggered when a notification is received while app is in a background state.
+ *
+ * @throws platform: {@link PlatformNotSupportedError} - Thrown if called against an unsupported platform. Currently,
+ * only React Native is supported by this API.
+ * @param {OnNotificationReceivedInBackgroundInput} input - A callback handler to be invoked with the received
+ * {@link PushNotificationMessage}.
+ * @returns {OnNotificationReceivedInBackgroundOutput} - An object with a remove function to remove the listener.
+ * @remarks Notifications received while app is in a quit state will start the app (as a headless JS instance running
+ * on a background service on Android) in the background. Handlers registered via this function should return promises
+ * if it needs to be asynchronous (e.g. to perform some network requests). The app should run in the background as long
+ * as there are handlers still running (however, if they run for more than 30 seconds on iOS, subsequent tasks could
+ * get deprioritized!). If it is necessary for a handler to execute while the app is in quit state, it should be
+ * registered in the application entry point (e.g. index.js) since the application will not fully mount in that case.
+ * @example
+ * ```ts
+ * // Register a listener
+ * onNotificationReceivedInBackground(message => {
+ *   doSomething(message);
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Register multiple listeners
+ * onNotificationReceivedInBackground(message => {
+ *   doSomething(message);
+ * });
+ *
+ * onNotificationReceivedInBackground(message => {
+ *   doSomethingElse(message);
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Register async listener
+ * onNotificationReceivedInBackground(async message => {
+ *   await doSomething(message);
+ *   console.log(`did something with ${message}`);
+ * });
+ * ```
+ */
+export const onNotificationReceivedInBackground: OnNotificationReceivedInBackground =
+	() => {
+		throw new PlatformNotSupportedError();
+	};

package/src/pushNotifications/providers/pinpoint/apis/onNotificationReceivedInForeground.native.ts

@@ -0,0 +1,8 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { addEventListener } from '../../../../eventListeners';
+import { OnNotificationReceivedInForeground } from '../types';
+
+export const onNotificationReceivedInForeground: OnNotificationReceivedInForeground =
+	input => addEventListener('foregroundMessageReceived', input);

package/src/pushNotifications/providers/pinpoint/apis/onNotificationReceivedInForeground.ts

@@ -0,0 +1,40 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+import { PushNotificationMessage } from '../../../types';
+import {
+	OnNotificationReceivedInForeground,
+	OnNotificationReceivedInForegroundInput,
+	OnNotificationReceivedInForegroundOutput,
+} from '../types';
+
+/**
+ * Registers a listener that will be triggered when a notification is received while app is in a foreground state.
+ *
+ * @param {OnNotificationReceivedInForegroundInput} input - A callback handler to be invoked with the received
+ * {@link PushNotificationMessage}.
+ * @returns {OnNotificationReceivedInForegroundOutput} - An object with a remove function to remove the listener.
+ * @example
+ * ```ts
+ * // Register a listener
+ * onNotificationReceivedInForeground(message => {
+ *   doSomething(message);
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Register multiple listeners
+ * onNotificationReceivedInForeground(message => {
+ *   doSomething(message);
+ * });
+ *
+ * onNotificationReceivedInForeground(message => {
+ *   doSomethingElse(message);
+ * });
+ * ```
+ */
+export const onNotificationReceivedInForeground: OnNotificationReceivedInForeground =
+	() => {
+		throw new PlatformNotSupportedError();
+	};