@symbiote-native/notifications 0.1.0

package/src/core/channels.ts

@@ -0,0 +1,183 @@
+// Ported from expo-notifications @ sdk-57's get/set/deleteNotificationChannel(Group)Async.ts —
+// upstream splits each of these into a `.ts` (iOS no-op) and a `.android.ts` (real) file picked
+// by Metro's platform extension resolution; this port collapses each pair into one function with
+// a runtime `Platform.OS === 'android'` branch, since this package has no separate build step
+// per platform to exploit the file-split for.
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+
+import {
+  notificationChannelGroupManager,
+  notificationChannelManager,
+} from './native-modules';
+import {
+  AndroidImportance,
+  type INotificationChannel,
+  type INotificationChannelGroup,
+  type INotificationChannelGroupInput,
+  type INotificationChannelInput,
+} from './types';
+
+const ANDROID_ONLY_NOTICE =
+  'Notification channels are only supported on Android.';
+
+function isAndroid(): boolean {
+  return Platform.OS === 'android';
+}
+
+/** @platform android — empty array on every other platform. */
+export async function getNotificationChannelsAsync(): Promise<
+  INotificationChannel[]
+> {
+  if (!isAndroid()) {
+    console.debug(ANDROID_ONLY_NOTICE);
+    return [];
+  }
+  if (!notificationChannelManager.getNotificationChannelsAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'getNotificationChannelsAsync',
+    );
+  }
+  return (
+    (await notificationChannelManager.getNotificationChannelsAsync()) ?? []
+  );
+}
+
+/** @platform android — `null` on every other platform. */
+export async function getNotificationChannelAsync(
+  channelId: string,
+): Promise<INotificationChannel | null> {
+  if (!isAndroid()) {
+    console.debug(ANDROID_ONLY_NOTICE);
+    return null;
+  }
+  if (!notificationChannelManager.getNotificationChannelAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'getNotificationChannelAsync',
+    );
+  }
+  return notificationChannelManager.getNotificationChannelAsync(channelId);
+}
+
+/**
+ * Creates or updates a channel. Only the name and description may change once a channel
+ * exists — an Android OS limitation. @platform android — `null` on every other platform.
+ */
+export async function setNotificationChannelAsync(
+  channelId: string,
+  channel: INotificationChannelInput,
+): Promise<INotificationChannel | null> {
+  if (!isAndroid()) {
+    console.debug(ANDROID_ONLY_NOTICE);
+    return null;
+  }
+  if (!notificationChannelManager.setNotificationChannelAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'setNotificationChannelAsync',
+    );
+  }
+  if (channel.importance === AndroidImportance.UNSPECIFIED) {
+    console.warn(
+      `[notifications] Channel "${channelId}" importance is UNSPECIFIED, which can error on some Android versions — use AndroidImportance.DEFAULT instead.`,
+    );
+  }
+  return notificationChannelManager.setNotificationChannelAsync(
+    channelId,
+    channel,
+  );
+}
+
+/** @platform android — no-op on every other platform. */
+export async function deleteNotificationChannelAsync(
+  channelId: string,
+): Promise<void> {
+  if (!isAndroid()) {
+    console.debug(ANDROID_ONLY_NOTICE);
+    return;
+  }
+  if (!notificationChannelManager.deleteNotificationChannelAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'deleteNotificationChannelAsync',
+    );
+  }
+  return notificationChannelManager.deleteNotificationChannelAsync(channelId);
+}
+
+/** @platform android — empty array on every other platform. */
+export async function getNotificationChannelGroupsAsync(): Promise<
+  INotificationChannelGroup[]
+> {
+  if (!isAndroid()) {
+    console.debug(ANDROID_ONLY_NOTICE);
+    return [];
+  }
+  if (!notificationChannelGroupManager.getNotificationChannelGroupsAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'getNotificationChannelGroupsAsync',
+    );
+  }
+  return notificationChannelGroupManager.getNotificationChannelGroupsAsync();
+}
+
+/** @platform android — `null` on every other platform. */
+export async function getNotificationChannelGroupAsync(
+  groupId: string,
+): Promise<INotificationChannelGroup | null> {
+  if (!isAndroid()) {
+    console.debug(ANDROID_ONLY_NOTICE);
+    return null;
+  }
+  if (!notificationChannelGroupManager.getNotificationChannelGroupAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'getNotificationChannelGroupAsync',
+    );
+  }
+  return notificationChannelGroupManager.getNotificationChannelGroupAsync(
+    groupId,
+  );
+}
+
+/** @platform android — `null` on every other platform. */
+export async function setNotificationChannelGroupAsync(
+  groupId: string,
+  group: INotificationChannelGroupInput,
+): Promise<INotificationChannelGroup | null> {
+  if (!isAndroid()) {
+    console.debug(ANDROID_ONLY_NOTICE);
+    return null;
+  }
+  if (!notificationChannelGroupManager.setNotificationChannelGroupAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'setNotificationChannelGroupAsync',
+    );
+  }
+  return notificationChannelGroupManager.setNotificationChannelGroupAsync(
+    groupId,
+    group,
+  );
+}
+
+/** @platform android — no-op on every other platform. */
+export async function deleteNotificationChannelGroupAsync(
+  groupId: string,
+): Promise<void> {
+  if (!isAndroid()) {
+    console.debug(ANDROID_ONLY_NOTICE);
+    return;
+  }
+  if (!notificationChannelGroupManager.deleteNotificationChannelGroupAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'deleteNotificationChannelGroupAsync',
+    );
+  }
+  return notificationChannelGroupManager.deleteNotificationChannelGroupAsync(
+    groupId,
+  );
+}

package/src/core/emitter.ts

@@ -0,0 +1,95 @@
+// Ported from expo-notifications @ sdk-57's NotificationsEmitter.ts.
+import {
+  LegacyEventEmitter,
+  UnavailabilityError,
+  type EventSubscription,
+} from 'expo-modules-core';
+
+import { dlog } from '@symbiote-native/engine';
+
+import { notificationsEmitterModule } from './native-modules';
+import type { INotification, INotificationResponse } from './types';
+import { mapNotification, mapNotificationResponse } from './utils';
+
+const emitter = new LegacyEventEmitter(notificationsEmitterModule);
+
+const RECEIVED_EVENT = 'onDidReceiveNotification';
+const DROPPED_EVENT = 'onNotificationsDeleted';
+const RESPONSE_RECEIVED_EVENT = 'onDidReceiveNotificationResponse';
+const RESPONSE_CLEARED_EVENT = 'onDidClearNotificationResponse';
+
+export const DEFAULT_ACTION_IDENTIFIER =
+  'expo.modules.notifications.actions.DEFAULT';
+
+/** Fires whenever a notification is received while the app is running. */
+export function addNotificationReceivedListener(
+  listener: (event: INotification) => void,
+): EventSubscription {
+  return emitter.addListener<INotification>(RECEIVED_EVENT, notification => {
+    dlog(() => `[notifications] received ${notification.request.identifier}`);
+    listener(mapNotification(notification));
+  });
+}
+
+/**
+ * Fires whenever the server (Firebase Cloud Messaging) dropped queued notifications.
+ * @platform android
+ */
+export function addNotificationsDroppedListener(
+  listener: () => void,
+): EventSubscription {
+  return emitter.addListener<void>(DROPPED_EVENT, listener);
+}
+
+/** Fires whenever the user interacts with a notification (e.g. taps it). */
+export function addNotificationResponseReceivedListener(
+  listener: (event: INotificationResponse) => void,
+): EventSubscription {
+  return emitter.addListener<INotificationResponse>(
+    RESPONSE_RECEIVED_EVENT,
+    response => {
+      dlog(
+        () =>
+          `[notifications] response ${response.actionIdentifier} for ${response.notification.request.identifier}`,
+      );
+      listener(mapNotificationResponse(response));
+    },
+  );
+}
+
+/**
+ * The most recently received notification response, or `null` if the app was not opened by
+ * one.
+ */
+export function getLastNotificationResponse(): INotificationResponse | null {
+  if (!notificationsEmitterModule.getLastNotificationResponse) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'getLastNotificationResponse',
+    );
+  }
+  const response = notificationsEmitterModule.getLastNotificationResponse();
+  return response ? mapNotificationResponse(response) : response;
+}
+
+/**
+ * Clears the last notification response, e.g. once its route has been handled and should not
+ * be re-applied on the next read.
+ */
+export function clearLastNotificationResponse(): void {
+  if (!notificationsEmitterModule.clearLastNotificationResponse) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'clearLastNotificationResponse',
+    );
+  }
+  notificationsEmitterModule.clearLastNotificationResponse();
+  emitter.emit(RESPONSE_CLEARED_EVENT, []);
+}
+
+/** Fires whenever `clearLastNotificationResponse` runs. */
+export function addNotificationResponseClearedListener(
+  listener: () => void,
+): EventSubscription {
+  return emitter.addListener<void>(RESPONSE_CLEARED_EVENT, listener);
+}

package/src/core/handler.ts

@@ -0,0 +1,95 @@
+// Ported from expo-notifications @ sdk-57's NotificationsHandler.ts.
+import {
+  CodedError,
+  LegacyEventEmitter,
+  type EventSubscription,
+} from 'expo-modules-core';
+
+import { dlog } from '@symbiote-native/engine';
+
+import { notificationsHandlerModule } from './native-modules';
+import type {
+  INotification,
+  INotificationBehavior,
+  INotificationHandler,
+} from './types';
+import { mapNotification } from './utils';
+
+export class NotificationTimeoutError extends CodedError {
+  override info: { notification: INotification; id: string };
+  constructor(notificationId: string, notification: INotification) {
+    super(
+      'ERR_NOTIFICATION_TIMEOUT',
+      `Notification handling timed out for ID ${notificationId}.`,
+    );
+    this.info = { id: notificationId, notification };
+  }
+}
+
+type IHandleNotificationEvent = { id: string; notification: INotification };
+
+const emitter = new LegacyEventEmitter(notificationsHandlerModule);
+const HANDLE_EVENT = 'onHandleNotification';
+const HANDLE_TIMEOUT_EVENT = 'onHandleNotificationTimeout';
+
+let handleSubscription: EventSubscription | null = null;
+let handleTimeoutSubscription: EventSubscription | null = null;
+
+/**
+ * Sets the callback deciding whether/how a notification received while the app is running
+ * should be shown. Must respond within 3 seconds or the notification is discarded. Passing
+ * `null` clears the handler — the default (no handler) is to not show anything.
+ */
+export function setNotificationHandler(
+  handler: INotificationHandler | null,
+): void {
+  handleSubscription?.remove();
+  handleSubscription = null;
+  handleTimeoutSubscription?.remove();
+  handleTimeoutSubscription = null;
+
+  if (!handler) return;
+
+  dlog('[notifications] setNotificationHandler');
+
+  handleSubscription = emitter.addListener<IHandleNotificationEvent>(
+    HANDLE_EVENT,
+    async ({ id, notification }) => {
+      if (!notificationsHandlerModule.handleNotificationAsync) {
+        handler.handleError?.(
+          id,
+          new Error(
+            'handleNotificationAsync is not available on this platform',
+          ),
+        );
+        return;
+      }
+      try {
+        const behavior: INotificationBehavior =
+          await handler.handleNotification(mapNotification(notification));
+        if (behavior.shouldShowAlert) {
+          console.warn(
+            '[notifications] `shouldShowAlert` is deprecated — specify `shouldShowBanner` and/or `shouldShowList` instead.',
+          );
+        }
+        await notificationsHandlerModule.handleNotificationAsync(id, behavior);
+        dlog(() => `[notifications] handled ${id}`);
+        handler.handleSuccess?.(id);
+      } catch (error) {
+        handler.handleError?.(
+          id,
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+    },
+  );
+
+  handleTimeoutSubscription = emitter.addListener<IHandleNotificationEvent>(
+    HANDLE_TIMEOUT_EVENT,
+    ({ id, notification }) =>
+      handler.handleError?.(
+        id,
+        new NotificationTimeoutError(id, mapNotification(notification)),
+      ),
+  );
+}

package/src/core/index.ts

@@ -0,0 +1,144 @@
+export { getPermissionsAsync, requestPermissionsAsync } from './permissions';
+
+export {
+  addPushTokenListener,
+  getDevicePushTokenAsync,
+  getExpoPushTokenAsync,
+  setAutoServerRegistrationEnabledAsync,
+  subscribeToTopicAsync,
+  unregisterForNotificationsAsync,
+  unsubscribeFromTopicAsync,
+  type IPushTokenListener,
+} from './tokens';
+
+export {
+  dismissAllNotificationsAsync,
+  dismissNotificationAsync,
+  getPresentedNotificationsAsync,
+} from './presenter';
+
+export { getBadgeCountAsync, setBadgeCountAsync } from './badge';
+
+export {
+  cancelAllScheduledNotificationsAsync,
+  cancelScheduledNotificationAsync,
+  getAllScheduledNotificationsAsync,
+  getNextTriggerDateAsync,
+  scheduleNotificationAsync,
+} from './scheduler';
+
+export {
+  deleteNotificationCategoryAsync,
+  getNotificationCategoriesAsync,
+  setNotificationCategoryAsync,
+} from './categories';
+
+export {
+  deleteNotificationChannelAsync,
+  deleteNotificationChannelGroupAsync,
+  getNotificationChannelAsync,
+  getNotificationChannelGroupAsync,
+  getNotificationChannelGroupsAsync,
+  getNotificationChannelsAsync,
+  setNotificationChannelAsync,
+  setNotificationChannelGroupAsync,
+} from './channels';
+
+export { NotificationTimeoutError, setNotificationHandler } from './handler';
+
+export {
+  DEFAULT_ACTION_IDENTIFIER,
+  addNotificationReceivedListener,
+  addNotificationResponseClearedListener,
+  addNotificationResponseReceivedListener,
+  addNotificationsDroppedListener,
+  clearLastNotificationResponse,
+  getLastNotificationResponse,
+} from './emitter';
+
+export {
+  BackgroundNotificationTaskResult,
+  registerTaskAsync,
+  unregisterTaskAsync,
+} from './background-task';
+
+export type {
+  IAudioAttributes,
+  IAudioAttributesInput,
+  IBeaconRegion,
+  ICalendarNotificationTrigger,
+  ICalendarTriggerInput,
+  IChannelAwareTriggerInput,
+  ICircularRegion,
+  IDailyNotificationTrigger,
+  IDailyTriggerInput,
+  IDateTriggerInput,
+  IDevicePushToken,
+  IExpoPushToken,
+  IExpoPushTokenOptions,
+  IFirebaseRemoteMessage,
+  IFirebaseRemoteMessageNotification,
+  IInterruptionLevel,
+  IIosNotificationPermissionsRequest,
+  ILocationNotificationTrigger,
+  IMaybeNotificationResponse,
+  IMonthlyNotificationTrigger,
+  IMonthlyTriggerInput,
+  INativeCalendarTriggerInput,
+  INativeChannelAwareTriggerInput,
+  INativeDailyTriggerInput,
+  INativeDateTriggerInput,
+  INativeDevicePushToken,
+  INativeMonthlyTriggerInput,
+  INativeNotificationTriggerInput,
+  INativeTimeIntervalTriggerInput,
+  INativeWeeklyTriggerInput,
+  INativeYearlyTriggerInput,
+  INotification,
+  INotificationAction,
+  INotificationBehavior,
+  INotificationCategory,
+  INotificationCategoryOptions,
+  INotificationChannel,
+  INotificationChannelGroup,
+  INotificationChannelGroupInput,
+  INotificationChannelInput,
+  INotificationContent,
+  INotificationContentAndroid,
+  INotificationContentAttachmentIos,
+  INotificationContentInput,
+  INotificationContentIos,
+  INotificationHandler,
+  INotificationPermissionsRequest,
+  INotificationPermissionsStatus,
+  INotificationRequest,
+  INotificationRequestInput,
+  INotificationResponse,
+  INotificationTaskPayload,
+  INotificationTrigger,
+  INotificationTriggerInput,
+  IPushNotificationTrigger,
+  IRegion,
+  ISchedulableNotificationTriggerInput,
+  ITimeIntervalNotificationTrigger,
+  ITimeIntervalTriggerInput,
+  IUnknownNotificationTrigger,
+  IWeeklyNotificationTrigger,
+  IWeeklyTriggerInput,
+  IYearlyNotificationTrigger,
+  IYearlyTriggerInput,
+  PermissionExpiration,
+  PermissionResponse,
+} from './types';
+export {
+  AndroidAudioContentType,
+  AndroidAudioUsage,
+  AndroidImportance,
+  AndroidNotificationPriority,
+  AndroidNotificationVisibility,
+  IosAlertStyle,
+  IosAllowsPreviews,
+  IosAuthorizationStatus,
+  PermissionStatus,
+  SchedulableTriggerInputTypes,
+} from './types';