@symbiote-native/notifications 0.1.0

package/src/core/native-modules.ts

@@ -0,0 +1,209 @@
+// Resolves expo-notifications' 13 native modules by the same names their own
+// `<Module>.native.ts` one-liners use (`.vendors/expo` @ origin/sdk-57,
+// `packages/expo-notifications/src/*.native.ts`) — see this package's `native-link.json` for
+// the matching Android Kotlin `importPath`/`className` for each.
+//
+// Every method is declared optional so a call site checks availability itself and throws an
+// `UnavailabilityError`, matching upstream's own per-platform capability checks rather than
+// assuming every native module implements its whole surface — same pattern
+// packages/task-manager/src/core/native-module.ts and packages/local-auth use.
+import {
+  NativeModule,
+  Platform,
+  requireNativeModule,
+  requireOptionalNativeModule,
+  type EventSubscription,
+  type ProxyNativeModule,
+} from 'expo-modules-core';
+
+import type {
+  INotification,
+  INotificationAction,
+  INotificationBehavior,
+  INotificationCategory,
+  INotificationCategoryOptions,
+  INotificationChannel,
+  INotificationChannelGroup,
+  INotificationChannelGroupInput,
+  INotificationChannelInput,
+  INotificationContentInput,
+  INotificationPermissionsRequest,
+  INotificationPermissionsStatus,
+  INotificationRequest,
+  INotificationResponse,
+  INativeNotificationTriggerInput,
+} from './types';
+
+// -- Permissions --------------------------------------------------------------------------
+export interface INativePermissionsModule extends ProxyNativeModule {
+  getPermissionsAsync?(): Promise<INotificationPermissionsStatus>;
+  requestPermissionsAsync?(
+    request: INotificationPermissionsRequest[keyof INotificationPermissionsRequest],
+  ): Promise<INotificationPermissionsStatus>;
+}
+export const notificationPermissionsModule =
+  requireNativeModule<INativePermissionsModule>(
+    'ExpoNotificationPermissionsModule',
+  );
+
+// -- Push token (also an EventEmitter — onDevicePushToken) --------------------------------
+export type IPushTokenManagerEvents = {
+  onDevicePushToken: (params: { devicePushToken: string }) => void;
+};
+export class PushTokenManagerModule extends NativeModule<IPushTokenManagerEvents> {
+  getDevicePushTokenAsync?(): Promise<string>;
+  unregisterForNotificationsAsync?(): Promise<void>;
+}
+export const pushTokenManager = requireNativeModule<PushTokenManagerModule>(
+  'ExpoPushTokenManager',
+);
+
+// -- Topic subscription (Android FCM topics only) ------------------------------------------
+// Upstream has no iOS native module for this at all — topics are an FCM/Android-only concept —
+// and resolves TopicSubscriptionModule per-platform (a real native module on Android, a plain
+// no-op JS object everywhere else). requireOptionalNativeModule mirrors that: a hard
+// requireNativeModule here would throw at import time on iOS before any screen code runs.
+export interface INativeTopicSubscriptionModule extends ProxyNativeModule {
+  subscribeToTopicAsync?(topic: string): Promise<null>;
+  unsubscribeFromTopicAsync?(topic: string): Promise<null>;
+}
+export const topicSubscriptionModule: INativeTopicSubscriptionModule =
+  Platform.OS === 'android'
+    ? requireNativeModule<INativeTopicSubscriptionModule>(
+        'ExpoTopicSubscriptionModule',
+      )
+    : (requireOptionalNativeModule<INativeTopicSubscriptionModule>(
+        'ExpoTopicSubscriptionModule',
+      ) ?? {});
+
+// -- Server registration (Expo push service device-id / registration-blob storage) --------
+export interface INativeServerRegistrationModule extends ProxyNativeModule {
+  getInstallationIdAsync?(): Promise<string>;
+  getRegistrationInfoAsync?(): Promise<string | undefined | null>;
+  setRegistrationInfoAsync?(registrationInfo: string | null): Promise<void>;
+}
+export const serverRegistrationModule =
+  requireNativeModule<INativeServerRegistrationModule>(
+    'NotificationsServerRegistrationModule',
+  );
+
+// -- Presenter (tray) -----------------------------------------------------------------------
+export interface INativePresenterModule extends ProxyNativeModule {
+  getPresentedNotificationsAsync?(): Promise<INotification[]>;
+  dismissNotificationAsync?(identifier: string): Promise<void>;
+  dismissAllNotificationsAsync?(): Promise<void>;
+}
+export const notificationPresenterModule =
+  requireNativeModule<INativePresenterModule>('ExpoNotificationPresenter');
+
+// -- Badge ------------------------------------------------------------------------------------
+export interface INativeBadgeModule extends ProxyNativeModule {
+  getBadgeCountAsync?(): Promise<number>;
+  setBadgeCountAsync?(badgeCount: number): Promise<boolean>;
+}
+export const badgeModule =
+  requireNativeModule<INativeBadgeModule>('ExpoBadgeModule');
+
+// -- Scheduler ----------------------------------------------------------------------------
+export interface INativeSchedulerModule extends ProxyNativeModule {
+  getAllScheduledNotificationsAsync?(): Promise<INotificationRequest[]>;
+  scheduleNotificationAsync?(
+    identifier: string,
+    content: INotificationContentInput,
+    trigger: INativeNotificationTriggerInput,
+  ): Promise<string>;
+  cancelScheduledNotificationAsync?(identifier: string): Promise<void>;
+  cancelAllScheduledNotificationsAsync?(): Promise<void>;
+  getNextTriggerDateAsync?(
+    trigger: INativeNotificationTriggerInput,
+  ): Promise<number>;
+}
+export const notificationScheduler =
+  requireNativeModule<INativeSchedulerModule>('ExpoNotificationScheduler');
+
+// -- Categories -----------------------------------------------------------------------------
+export interface INativeCategoriesModule extends ProxyNativeModule {
+  getNotificationCategoriesAsync?(): Promise<INotificationCategory[]>;
+  setNotificationCategoryAsync?(
+    identifier: string,
+    actions: INotificationAction[],
+    options?: INotificationCategoryOptions,
+  ): Promise<INotificationCategory>;
+  deleteNotificationCategoryAsync?(identifier: string): Promise<boolean>;
+}
+export const notificationCategoriesModule =
+  requireNativeModule<INativeCategoriesModule>(
+    'ExpoNotificationCategoriesModule',
+  );
+
+// -- Android channels / channel groups -----------------------------------------------------
+export interface INativeChannelManagerModule extends ProxyNativeModule {
+  getNotificationChannelsAsync?(): Promise<INotificationChannel[] | null>;
+  getNotificationChannelAsync?(
+    channelId: string,
+  ): Promise<INotificationChannel | null>;
+  setNotificationChannelAsync?(
+    channelId: string,
+    channel: INotificationChannelInput,
+  ): Promise<INotificationChannel | null>;
+  deleteNotificationChannelAsync?(channelId: string): Promise<void>;
+}
+// Android-only concept, same as topicSubscriptionModule above — a hard requireNativeModule
+// here throws at import time on iOS before any screen code runs.
+export const notificationChannelManager: INativeChannelManagerModule =
+  Platform.OS === 'android'
+    ? requireNativeModule<INativeChannelManagerModule>(
+        'ExpoNotificationChannelManager',
+      )
+    : (requireOptionalNativeModule<INativeChannelManagerModule>(
+        'ExpoNotificationChannelManager',
+      ) ?? {});
+
+export interface INativeChannelGroupManagerModule extends ProxyNativeModule {
+  getNotificationChannelGroupsAsync?(): Promise<INotificationChannelGroup[]>;
+  getNotificationChannelGroupAsync?(
+    groupId: string,
+  ): Promise<INotificationChannelGroup | null>;
+  setNotificationChannelGroupAsync?(
+    groupId: string,
+    group: INotificationChannelGroupInput,
+  ): Promise<INotificationChannelGroup | null>;
+  deleteNotificationChannelGroupAsync?(groupId: string): Promise<void>;
+}
+export const notificationChannelGroupManager: INativeChannelGroupManagerModule =
+  Platform.OS === 'android'
+    ? requireNativeModule<INativeChannelGroupManagerModule>(
+        'ExpoNotificationChannelGroupManager',
+      )
+    : (requireOptionalNativeModule<INativeChannelGroupManagerModule>(
+        'ExpoNotificationChannelGroupManager',
+      ) ?? {});
+
+// -- Handler / Emitter (legacy ProxyNativeModule + LegacyEventEmitter, same as upstream) ---
+export interface INativeHandlerModule extends ProxyNativeModule {
+  handleNotificationAsync?(
+    notificationId: string,
+    behavior: INotificationBehavior,
+  ): Promise<void>;
+}
+export const notificationsHandlerModule =
+  requireNativeModule<INativeHandlerModule>('ExpoNotificationsHandlerModule');
+
+export interface INativeEmitterModule extends ProxyNativeModule {
+  getLastNotificationResponse?(): INotificationResponse | null;
+  clearLastNotificationResponse?(): void;
+}
+export const notificationsEmitterModule =
+  requireNativeModule<INativeEmitterModule>('ExpoNotificationsEmitter');
+
+// -- Background task registration ----------------------------------------------------------
+export interface INativeBackgroundTasksModule extends ProxyNativeModule {
+  registerTaskAsync(taskName: string): Promise<null>;
+  unregisterTaskAsync(taskName: string): Promise<null>;
+}
+export const backgroundNotificationTasksModule =
+  requireNativeModule<INativeBackgroundTasksModule>(
+    'ExpoBackgroundNotificationTasksModule',
+  );
+
+export type { EventSubscription };

package/src/core/permissions.ts

@@ -0,0 +1,46 @@
+// Ported from expo-notifications @ sdk-57's NotificationPermissions.ts.
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+
+import { dlog } from '@symbiote-native/engine';
+
+import { notificationPermissionsModule } from './native-modules';
+import type {
+  INotificationPermissionsRequest,
+  INotificationPermissionsStatus,
+} from './types';
+
+/** Checks (without prompting) whether the app can currently display alerts, play sounds, etc. */
+export async function getPermissionsAsync(): Promise<INotificationPermissionsStatus> {
+  if (!notificationPermissionsModule.getPermissionsAsync) {
+    throw new UnavailabilityError('Notifications', 'getPermissionsAsync');
+  }
+  const result = await notificationPermissionsModule.getPermissionsAsync();
+  dlog(() => `[notifications] getPermissionsAsync -> ${result.status}`);
+  return result;
+}
+
+/**
+ * Prompts the user for notification permissions. Defaults to alerts + badge + sound on iOS —
+ * on Android every permission is already granted and there is nothing to prompt for.
+ */
+export async function requestPermissionsAsync(
+  permissions?: INotificationPermissionsRequest,
+): Promise<INotificationPermissionsStatus> {
+  if (!notificationPermissionsModule.requestPermissionsAsync) {
+    throw new UnavailabilityError('Notifications', 'requestPermissionsAsync');
+  }
+
+  const requested: INotificationPermissionsRequest = permissions ?? {
+    ios: { allowAlert: true, allowBadge: true, allowSound: true },
+  };
+  const platformRequest =
+    requested[Platform.OS as keyof INotificationPermissionsRequest];
+
+  dlog('[notifications] requestPermissionsAsync');
+  const result =
+    await notificationPermissionsModule.requestPermissionsAsync(
+      platformRequest,
+    );
+  dlog(() => `[notifications] requestPermissionsAsync -> ${result.status}`);
+  return result;
+}

package/src/core/presenter.ts

@@ -0,0 +1,45 @@
+// Ported from expo-notifications @ sdk-57's getPresentedNotificationsAsync.ts,
+// dismissNotificationAsync.ts, dismissAllNotificationsAsync.ts.
+import { UnavailabilityError } from 'expo-modules-core';
+
+import { notificationPresenterModule } from './native-modules';
+import type { INotification } from './types';
+import { mapNotification } from './utils';
+
+/** Notifications currently in the tray (Notification Center). Empty on Android below API 23. */
+export async function getPresentedNotificationsAsync(): Promise<
+  INotification[]
+> {
+  if (!notificationPresenterModule.getPresentedNotificationsAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'getPresentedNotificationsAsync',
+    );
+  }
+  const notifications =
+    await notificationPresenterModule.getPresentedNotificationsAsync();
+  return notifications.map(mapNotification);
+}
+
+/** Removes one notification from the tray by its identifier. */
+export async function dismissNotificationAsync(
+  notificationIdentifier: string,
+): Promise<void> {
+  if (!notificationPresenterModule.dismissNotificationAsync) {
+    throw new UnavailabilityError('Notifications', 'dismissNotificationAsync');
+  }
+  return notificationPresenterModule.dismissNotificationAsync(
+    notificationIdentifier,
+  );
+}
+
+/** Removes every one of this app's notifications from the tray. */
+export async function dismissAllNotificationsAsync(): Promise<void> {
+  if (!notificationPresenterModule.dismissAllNotificationsAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'dismissAllNotificationsAsync',
+    );
+  }
+  return notificationPresenterModule.dismissAllNotificationsAsync();
+}

package/src/core/scheduler.ts

@@ -0,0 +1,265 @@
+// Ported from expo-notifications @ sdk-57's scheduleNotificationAsync.ts,
+// getAllScheduledNotificationsAsync.ts, cancelScheduledNotificationAsync.ts,
+// cancelAllScheduledNotificationsAsync.ts, getNextTriggerDateAsync.ts.
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+
+import { dlog } from '@symbiote-native/engine';
+
+import { notificationScheduler } from './native-modules';
+import {
+  SchedulableTriggerInputTypes,
+  type INativeCalendarTriggerInput,
+  type INativeDailyTriggerInput,
+  type INativeDateTriggerInput,
+  type INativeMonthlyTriggerInput,
+  type INativeNotificationTriggerInput,
+  type INativeTimeIntervalTriggerInput,
+  type INativeWeeklyTriggerInput,
+  type INativeYearlyTriggerInput,
+  type INotificationRequest,
+  type INotificationRequestInput,
+  type INotificationTriggerInput,
+  type ISchedulableNotificationTriggerInput,
+} from './types';
+import { hasValidTriggerObject, mapNotificationRequest } from './utils';
+
+function uuid(): string {
+  // Same fallback expo-modules-core's own `uuid.v4()` boils down to on native — a real RFC4122
+  // v4 id, no extra dependency for one call site.
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, char => {
+    const random = (Math.random() * 16) | 0;
+    const value = char === 'x' ? random : (random & 0x3) | 0x8;
+    return value.toString(16);
+  });
+}
+
+type DateComponent = 'month' | 'day' | 'weekday' | 'hour' | 'minute';
+
+function daysInMonth(month: number, year?: number): number {
+  return new Date(year ?? 2000, month + 1, 0).getDate();
+}
+
+function validateDateComponents(
+  trigger: Record<string, unknown>,
+  components: readonly DateComponent[],
+): void {
+  for (const component of components) {
+    if (!(component in trigger)) {
+      throw new TypeError(`The ${component} parameter needs to be present`);
+    }
+    const value = trigger[component];
+    if (typeof value !== 'number') {
+      throw new TypeError(`The ${component} parameter should be a number`);
+    }
+    switch (component) {
+      case 'month':
+        if (value < 0 || value > 11) {
+          throw new RangeError(
+            `The month parameter needs to be between 0 and 11. Found: ${value}`,
+          );
+        }
+        break;
+      case 'day': {
+        const month =
+          typeof trigger.month === 'number'
+            ? trigger.month
+            : new Date().getMonth();
+        const max = daysInMonth(month);
+        if (value < 1 || value > max) {
+          throw new RangeError(
+            `The day parameter for month ${month} must be between 1 and ${max}. Found: ${value}`,
+          );
+        }
+        break;
+      }
+      case 'weekday':
+        if (value < 1 || value > 7) {
+          throw new RangeError(
+            `The weekday parameter needs to be between 1 and 7. Found: ${value}`,
+          );
+        }
+        break;
+      case 'hour':
+        if (value < 0 || value > 23) {
+          throw new RangeError(
+            `The hour parameter needs to be between 0 and 23. Found: ${value}`,
+          );
+        }
+        break;
+      case 'minute':
+        if (value < 0 || value > 59) {
+          throw new RangeError(
+            `The minute parameter needs to be between 0 and 59. Found: ${value}`,
+          );
+        }
+        break;
+    }
+  }
+}
+
+/** Translates a public `INotificationTriggerInput` into the shape native expects. */
+export function parseTrigger(
+  trigger: INotificationTriggerInput,
+): INativeNotificationTriggerInput {
+  if (trigger === null) {
+    return null;
+  }
+  if (trigger === undefined) {
+    throw new TypeError(
+      'Encountered an `undefined` notification trigger. Pass an explicit `null` to trigger immediately.',
+    );
+  }
+  if (!hasValidTriggerObject(trigger)) {
+    throw new TypeError(
+      'The `trigger` object needs a `type` or `channelId` entry.',
+    );
+  }
+
+  if ('type' in trigger) {
+    if (trigger.type === SchedulableTriggerInputTypes.DATE) {
+      const timestamp =
+        trigger.date instanceof Date ? trigger.date.getTime() : trigger.date;
+      const result: INativeDateTriggerInput = { type: 'date', timestamp };
+      if (trigger.channelId) result.channelId = trigger.channelId;
+      return result;
+    }
+
+    if (trigger.type === SchedulableTriggerInputTypes.CALENDAR) {
+      const { repeats, ...rest } = trigger;
+      return {
+        ...rest,
+        repeats: Boolean(repeats),
+        type: 'calendar',
+      } satisfies INativeCalendarTriggerInput;
+    }
+
+    if (trigger.type === SchedulableTriggerInputTypes.DAILY) {
+      validateDateComponents(trigger, ['hour', 'minute']);
+      const result: INativeDailyTriggerInput = {
+        type: 'daily',
+        hour: trigger.hour,
+        minute: trigger.minute,
+      };
+      if (trigger.channelId) result.channelId = trigger.channelId;
+      return result;
+    }
+
+    if (trigger.type === SchedulableTriggerInputTypes.WEEKLY) {
+      validateDateComponents(trigger, ['weekday', 'hour', 'minute']);
+      const result: INativeWeeklyTriggerInput = {
+        type: 'weekly',
+        weekday: trigger.weekday,
+        hour: trigger.hour,
+        minute: trigger.minute,
+      };
+      if (trigger.channelId) result.channelId = trigger.channelId;
+      return result;
+    }
+
+    if (trigger.type === SchedulableTriggerInputTypes.MONTHLY) {
+      validateDateComponents(trigger, ['day', 'hour', 'minute']);
+      const result: INativeMonthlyTriggerInput = {
+        type: 'monthly',
+        day: trigger.day,
+        hour: trigger.hour,
+        minute: trigger.minute,
+      };
+      if (trigger.channelId) result.channelId = trigger.channelId;
+      return result;
+    }
+
+    if (trigger.type === SchedulableTriggerInputTypes.YEARLY) {
+      validateDateComponents(trigger, ['month', 'day', 'hour', 'minute']);
+      const result: INativeYearlyTriggerInput = {
+        type: 'yearly',
+        month: trigger.month,
+        day: trigger.day,
+        hour: trigger.hour,
+        minute: trigger.minute,
+      };
+      if (trigger.channelId) result.channelId = trigger.channelId;
+      return result;
+    }
+
+    if (trigger.type === SchedulableTriggerInputTypes.TIME_INTERVAL) {
+      const result: INativeTimeIntervalTriggerInput = {
+        type: 'timeInterval',
+        seconds: trigger.seconds,
+        repeats: trigger.repeats ?? false,
+      };
+      if (trigger.channelId) result.channelId = trigger.channelId;
+      return result;
+    }
+  }
+
+  if (Platform.OS === 'android' && 'channelId' in trigger) {
+    return { type: 'channel', channelId: trigger.channelId };
+  }
+  // No notion of channels off Android — deliver immediately.
+  return null;
+}
+
+/** Fetches every notification currently scheduled for future delivery. */
+export async function getAllScheduledNotificationsAsync(): Promise<
+  INotificationRequest[]
+> {
+  if (!notificationScheduler.getAllScheduledNotificationsAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'getAllScheduledNotificationsAsync',
+    );
+  }
+  const requests =
+    await notificationScheduler.getAllScheduledNotificationsAsync();
+  return requests.map(mapNotificationRequest);
+}
+
+/** Schedules a notification. Returns the identifier used to cancel it later. */
+export async function scheduleNotificationAsync(
+  request: INotificationRequestInput,
+): Promise<string> {
+  if (!notificationScheduler.scheduleNotificationAsync) {
+    throw new UnavailabilityError('Notifications', 'scheduleNotificationAsync');
+  }
+  const identifier = request.identifier ?? uuid();
+  dlog(() => `[notifications] scheduleNotificationAsync ${identifier}`);
+  return notificationScheduler.scheduleNotificationAsync(
+    identifier,
+    request.content,
+    parseTrigger(request.trigger),
+  );
+}
+
+/** Cancels one scheduled notification by its identifier. */
+export async function cancelScheduledNotificationAsync(
+  identifier: string,
+): Promise<void> {
+  if (!notificationScheduler.cancelScheduledNotificationAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'cancelScheduledNotificationAsync',
+    );
+  }
+  return notificationScheduler.cancelScheduledNotificationAsync(identifier);
+}
+
+/** Cancels every scheduled notification. */
+export async function cancelAllScheduledNotificationsAsync(): Promise<void> {
+  if (!notificationScheduler.cancelAllScheduledNotificationsAsync) {
+    throw new UnavailabilityError(
+      'Notifications',
+      'cancelAllScheduledNotificationsAsync',
+    );
+  }
+  return notificationScheduler.cancelAllScheduledNotificationsAsync();
+}
+
+/** The next Unix timestamp (ms) a schedulable trigger would fire at, or `null` if never. */
+export async function getNextTriggerDateAsync(
+  trigger: ISchedulableNotificationTriggerInput,
+): Promise<number | null> {
+  if (!notificationScheduler.getNextTriggerDateAsync) {
+    throw new UnavailabilityError('Notifications', 'getNextTriggerDateAsync');
+  }
+  return notificationScheduler.getNextTriggerDateAsync(parseTrigger(trigger));
+}