@idealyst/notifications 1.2.114

package/src/local/local.web.ts

@@ -0,0 +1,360 @@
+import type {
+  DisplayNotificationOptions,
+  ScheduleNotificationOptions,
+  DisplayedNotification,
+  PendingNotification,
+  AndroidChannel,
+  NotificationCategory,
+  NotificationEvent,
+  NotificationEventHandler,
+} from '../types';
+import { createNotificationError } from '../errors';
+
+// ============================================================================
+// Internal State
+// ============================================================================
+
+interface TrackedNotification {
+  id: string;
+  notification: Notification;
+  options: DisplayNotificationOptions;
+  displayedAt: number;
+}
+
+interface ScheduledNotification {
+  id: string;
+  options: ScheduleNotificationOptions;
+  timerId: ReturnType<typeof setTimeout>;
+  intervalId?: ReturnType<typeof setInterval>;
+}
+
+const _displayed = new Map<string, TrackedNotification>();
+const _pending = new Map<string, ScheduledNotification>();
+const _eventHandlers = new Set<NotificationEventHandler>();
+let _badgeCount = 0;
+let _idCounter = 0;
+
+function generateId(): string {
+  return `notif_${Date.now()}_${++_idCounter}`;
+}
+
+// ============================================================================
+// Display Functions
+// ============================================================================
+
+/**
+ * Display a notification immediately.
+ * Returns the notification ID.
+ */
+export async function displayNotification(
+  options: DisplayNotificationOptions,
+): Promise<string> {
+  if (typeof Notification === 'undefined') {
+    throw createNotificationError(
+      'not_supported',
+      'Notifications are not supported in this browser',
+    );
+  }
+
+  if (Notification.permission !== 'granted') {
+    throw createNotificationError(
+      'permission_denied',
+      'Notification permission not granted',
+    );
+  }
+
+  const id = options.id ?? generateId();
+
+  const notification = new Notification(options.title, {
+    body: options.body,
+    icon: options.imageUrl,
+    tag: id,
+    data: { id, ...options.data },
+    silent: options.sound === undefined,
+    badge: options.imageUrl,
+  });
+
+  const tracked: TrackedNotification = {
+    id,
+    notification,
+    options,
+    displayedAt: Date.now(),
+  };
+
+  _displayed.set(id, tracked);
+
+  notification.onclick = () => {
+    emitEvent({
+      type: 'press',
+      id,
+      notification: {
+        id,
+        title: options.title,
+        body: options.body,
+        data: options.data,
+        date: tracked.displayedAt,
+      },
+    });
+  };
+
+  notification.onclose = () => {
+    _displayed.delete(id);
+    emitEvent({
+      type: 'dismissed',
+      id,
+      notification: {
+        id,
+        title: options.title,
+        body: options.body,
+        data: options.data,
+        date: tracked.displayedAt,
+      },
+    });
+  };
+
+  return id;
+}
+
+/**
+ * Schedule a notification.
+ * Returns the notification ID.
+ *
+ * Note: Web scheduling uses setTimeout/setInterval and is lost on page close.
+ */
+export async function scheduleNotification(
+  options: ScheduleNotificationOptions,
+): Promise<string> {
+  const id = options.id ?? generateId();
+  const { trigger } = options;
+
+  if (trigger.type === 'timestamp' && trigger.timestamp) {
+    const delay = Math.max(0, trigger.timestamp - Date.now());
+
+    if (trigger.repeatFrequency && trigger.repeatFrequency !== 'none') {
+      // Initial delay, then repeat
+      const intervalMs = getRepeatIntervalMs(trigger.repeatFrequency);
+      const timerId = setTimeout(() => {
+        displayNotification({ ...options, id });
+        const intervalId = setInterval(() => {
+          displayNotification({ ...options, id: generateId() });
+        }, intervalMs);
+        const existing = _pending.get(id);
+        if (existing) {
+          existing.intervalId = intervalId;
+        }
+      }, delay);
+
+      _pending.set(id, { id, options, timerId });
+    } else {
+      const timerId = setTimeout(() => {
+        _pending.delete(id);
+        displayNotification({ ...options, id });
+      }, delay);
+      _pending.set(id, { id, options, timerId });
+    }
+  } else if (trigger.type === 'interval' && trigger.interval) {
+    const intervalMs = trigger.interval * 60 * 1000;
+
+    if (trigger.repeatFrequency && trigger.repeatFrequency !== 'none') {
+      const timerId = setTimeout(() => {
+        displayNotification({ ...options, id });
+      }, intervalMs);
+
+      const intervalId = setInterval(() => {
+        displayNotification({ ...options, id: generateId() });
+      }, intervalMs);
+
+      _pending.set(id, { id, options, timerId, intervalId });
+    } else {
+      const timerId = setTimeout(() => {
+        _pending.delete(id);
+        displayNotification({ ...options, id });
+      }, intervalMs);
+      _pending.set(id, { id, options, timerId });
+    }
+  }
+
+  return id;
+}
+
+// ============================================================================
+// Cancel Functions
+// ============================================================================
+
+/**
+ * Cancel a specific notification by ID.
+ */
+export async function cancelNotification(id: string): Promise<void> {
+  // Cancel displayed
+  const displayed = _displayed.get(id);
+  if (displayed) {
+    displayed.notification.close();
+    _displayed.delete(id);
+  }
+
+  // Cancel pending
+  const pending = _pending.get(id);
+  if (pending) {
+    clearTimeout(pending.timerId);
+    if (pending.intervalId) clearInterval(pending.intervalId);
+    _pending.delete(id);
+  }
+}
+
+/**
+ * Cancel all notifications (displayed + pending).
+ */
+export async function cancelAllNotifications(): Promise<void> {
+  await cancelDisplayedNotifications();
+  await cancelPendingNotifications();
+}
+
+/**
+ * Cancel all currently displayed notifications.
+ */
+export async function cancelDisplayedNotifications(): Promise<void> {
+  for (const [id, tracked] of _displayed) {
+    tracked.notification.close();
+  }
+  _displayed.clear();
+}
+
+/**
+ * Cancel all pending (scheduled) notifications.
+ */
+export async function cancelPendingNotifications(): Promise<void> {
+  for (const [id, pending] of _pending) {
+    clearTimeout(pending.timerId);
+    if (pending.intervalId) clearInterval(pending.intervalId);
+  }
+  _pending.clear();
+}
+
+// ============================================================================
+// Channels (Android — no-op on web)
+// ============================================================================
+
+export async function createChannel(_channel: AndroidChannel): Promise<void> {
+  // No-op: Android notification channels have no web equivalent.
+}
+
+export async function deleteChannel(_channelId: string): Promise<void> {
+  // No-op
+}
+
+export async function getChannels(): Promise<AndroidChannel[]> {
+  return [];
+}
+
+// ============================================================================
+// Categories (iOS — no-op on web)
+// ============================================================================
+
+export async function setCategories(
+  _categories: NotificationCategory[],
+): Promise<void> {
+  // No-op: iOS notification categories have no web equivalent.
+}
+
+// ============================================================================
+// Queries
+// ============================================================================
+
+/**
+ * Get all currently displayed notifications.
+ */
+export async function getDisplayedNotifications(): Promise<DisplayedNotification[]> {
+  return Array.from(_displayed.values()).map((tracked) => ({
+    id: tracked.id,
+    title: tracked.options.title,
+    body: tracked.options.body,
+    data: tracked.options.data,
+    date: tracked.displayedAt,
+  }));
+}
+
+/**
+ * Get all pending (scheduled) notifications.
+ */
+export async function getPendingNotifications(): Promise<PendingNotification[]> {
+  return Array.from(_pending.values()).map((pending) => ({
+    id: pending.id,
+    title: pending.options.title,
+    body: pending.options.body,
+    trigger: pending.options.trigger,
+    data: pending.options.data,
+  }));
+}
+
+// ============================================================================
+// Badge
+// ============================================================================
+
+/**
+ * Set the app badge count (PWA Badge API).
+ */
+export async function setBadgeCount(count: number): Promise<void> {
+  _badgeCount = count;
+
+  if ('setAppBadge' in navigator) {
+    try {
+      if (count > 0) {
+        await (navigator as Navigator & { setAppBadge: (n: number) => Promise<void> }).setAppBadge(count);
+      } else {
+        await (navigator as Navigator & { clearAppBadge: () => Promise<void> }).clearAppBadge();
+      }
+    } catch {
+      // Badge API may not be supported or permission may be denied
+    }
+  }
+}
+
+/**
+ * Get the current app badge count.
+ * Returns the last set count (no read API exists on web).
+ */
+export async function getBadgeCount(): Promise<number> {
+  return _badgeCount;
+}
+
+// ============================================================================
+// Events
+// ============================================================================
+
+/**
+ * Register a handler for notification events (press, dismiss).
+ * Returns an unsubscribe function.
+ */
+export function onNotificationEvent(handler: NotificationEventHandler): () => void {
+  _eventHandlers.add(handler);
+  return () => {
+    _eventHandlers.delete(handler);
+  };
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function emitEvent(event: NotificationEvent): void {
+  for (const handler of _eventHandlers) {
+    try {
+      handler(event);
+    } catch {
+      // Don't let handler errors break other handlers
+    }
+  }
+}
+
+function getRepeatIntervalMs(frequency: string): number {
+  switch (frequency) {
+    case 'hourly':
+      return 60 * 60 * 1000;
+    case 'daily':
+      return 24 * 60 * 60 * 1000;
+    case 'weekly':
+      return 7 * 24 * 60 * 60 * 1000;
+    default:
+      return 24 * 60 * 60 * 1000;
+  }
+}

package/src/local/useLocalNotifications.ts

@@ -0,0 +1,122 @@
+import { useCallback, useEffect, useRef } from 'react';
+import type {
+  UseLocalNotificationsOptions,
+  UseLocalNotificationsResult,
+  DisplayNotificationOptions,
+  ScheduleNotificationOptions,
+  AndroidChannel,
+  NotificationCategory,
+  DisplayedNotification,
+  PendingNotification,
+  NotificationEventHandler,
+} from '../types';
+
+/**
+ * Factory that creates a useLocalNotifications hook bound to platform-specific functions.
+ * Each platform entry point calls this with the correct implementations.
+ */
+export function createUseLocalNotificationsHook(fns: {
+  displayNotification: (options: DisplayNotificationOptions) => Promise<string>;
+  scheduleNotification: (options: ScheduleNotificationOptions) => Promise<string>;
+  cancelNotification: (id: string) => Promise<void>;
+  cancelAllNotifications: () => Promise<void>;
+  createChannel: (channel: AndroidChannel) => Promise<void>;
+  deleteChannel: (channelId: string) => Promise<void>;
+  getChannels: () => Promise<AndroidChannel[]>;
+  setCategories: (categories: NotificationCategory[]) => Promise<void>;
+  getDisplayedNotifications: () => Promise<DisplayedNotification[]>;
+  getPendingNotifications: () => Promise<PendingNotification[]>;
+  setBadgeCount: (count: number) => Promise<void>;
+  getBadgeCount: () => Promise<number>;
+  onNotificationEvent: (handler: NotificationEventHandler) => () => void;
+}) {
+  return function useLocalNotifications(
+    options: UseLocalNotificationsOptions = {},
+  ): UseLocalNotificationsResult {
+    const { onEvent } = options;
+    const mountedRef = useRef(true);
+
+    useEffect(() => {
+      mountedRef.current = true;
+      let unsub: (() => void) | undefined;
+
+      if (onEvent) {
+        unsub = fns.onNotificationEvent(onEvent);
+      }
+
+      return () => {
+        mountedRef.current = false;
+        unsub?.();
+      };
+    }, [onEvent]);
+
+    const displayNotification = useCallback(
+      (opts: DisplayNotificationOptions) => fns.displayNotification(opts),
+      [],
+    );
+
+    const scheduleNotification = useCallback(
+      (opts: ScheduleNotificationOptions) => fns.scheduleNotification(opts),
+      [],
+    );
+
+    const cancelNotification = useCallback(
+      (id: string) => fns.cancelNotification(id),
+      [],
+    );
+
+    const cancelAllNotifications = useCallback(
+      () => fns.cancelAllNotifications(),
+      [],
+    );
+
+    const createChannel = useCallback(
+      (channel: AndroidChannel) => fns.createChannel(channel),
+      [],
+    );
+
+    const deleteChannel = useCallback(
+      (channelId: string) => fns.deleteChannel(channelId),
+      [],
+    );
+
+    const getChannels = useCallback(() => fns.getChannels(), []);
+
+    const setCategories = useCallback(
+      (categories: NotificationCategory[]) => fns.setCategories(categories),
+      [],
+    );
+
+    const getDisplayedNotifications = useCallback(
+      () => fns.getDisplayedNotifications(),
+      [],
+    );
+
+    const getPendingNotifications = useCallback(
+      () => fns.getPendingNotifications(),
+      [],
+    );
+
+    const setBadgeCount = useCallback(
+      (count: number) => fns.setBadgeCount(count),
+      [],
+    );
+
+    const getBadgeCount = useCallback(() => fns.getBadgeCount(), []);
+
+    return {
+      displayNotification,
+      scheduleNotification,
+      cancelNotification,
+      cancelAllNotifications,
+      createChannel,
+      deleteChannel,
+      getChannels,
+      setCategories,
+      getDisplayedNotifications,
+      getPendingNotifications,
+      setBadgeCount,
+      getBadgeCount,
+    };
+  };
+}

package/src/permissions/permissions.native.ts

@@ -0,0 +1,148 @@
+import { Platform, Linking, PermissionsAndroid } from 'react-native';
+import type { PermissionResult, RequestPermissionOptions } from '../types';
+import { createNotificationError } from '../errors';
+
+// Graceful optional imports
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let Notifee: any = null;
+try {
+  Notifee = require('@notifee/react-native').default;
+} catch {
+  // Will degrade gracefully
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let Messaging: any = null;
+try {
+  Messaging = require('@react-native-firebase/messaging').default;
+} catch {
+  // Will degrade gracefully
+}
+
+/**
+ * Check current notification permission without prompting.
+ */
+export async function checkPermission(): Promise<PermissionResult> {
+  if (Notifee) {
+    const settings = await Notifee.getNotificationSettings();
+    return mapNotifeeSettings(settings);
+  }
+
+  if (Messaging) {
+    const status = await Messaging().hasPermission();
+    return mapFirebaseAuthStatus(status);
+  }
+
+  return { status: 'undetermined', canNotify: false };
+}
+
+/**
+ * Request notification permission from the user.
+ */
+export async function requestPermission(
+  options?: RequestPermissionOptions,
+): Promise<PermissionResult> {
+  // On Android 13+ (API 33), request the POST_NOTIFICATIONS runtime permission
+  if (Platform.OS === 'android' && Platform.Version >= 33) {
+    const result = await PermissionsAndroid.request(
+      'android.permission.POST_NOTIFICATIONS' as any,
+    );
+    if (result === PermissionsAndroid.RESULTS.DENIED) {
+      return { status: 'denied', canNotify: false };
+    }
+    if (result === PermissionsAndroid.RESULTS.NEVER_ASK_AGAIN) {
+      return { status: 'blocked', canNotify: false };
+    }
+  }
+
+  // Use Notifee for permission request (covers both local + push on iOS)
+  if (Notifee) {
+    const settings = await Notifee.requestPermission(
+      options?.ios
+        ? {
+            alert: options.ios.alert,
+            badge: options.ios.badge,
+            sound: options.ios.sound,
+            criticalAlert: options.ios.criticalAlert,
+            provisional: options.ios.provisional ?? options.provisional,
+            carPlay: options.ios.carPlay,
+            announcement: options.ios.announcement,
+          }
+        : options?.provisional
+          ? { provisional: true }
+          : undefined,
+    );
+    return mapNotifeeSettings(settings);
+  }
+
+  // Fallback to Firebase Messaging permission request
+  if (Messaging) {
+    const status = await Messaging().requestPermission();
+    return mapFirebaseAuthStatus(status);
+  }
+
+  throw createNotificationError(
+    'not_available',
+    'Neither @notifee/react-native nor @react-native-firebase/messaging is installed',
+  );
+}
+
+/**
+ * Open system notification settings for this app.
+ */
+export async function openNotificationSettings(): Promise<void> {
+  if (Platform.OS === 'android' && Notifee) {
+    await Notifee.openNotificationSettings();
+    return;
+  }
+
+  // iOS: open app settings
+  await Linking.openSettings();
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function mapNotifeeSettings(settings: any): PermissionResult {
+  // Notifee AuthorizationStatus: 0=NOT_DETERMINED, 1=DENIED, 2=AUTHORIZED, 3=PROVISIONAL
+  const authStatus = settings?.authorizationStatus ?? 0;
+  const iosSettings = Platform.OS === 'ios'
+    ? {
+        alert: Boolean(settings?.ios?.alert),
+        badge: Boolean(settings?.ios?.badge),
+        sound: Boolean(settings?.ios?.sound),
+        criticalAlert: Boolean(settings?.ios?.criticalAlert),
+        provisional: authStatus === 3,
+      }
+    : undefined;
+
+  switch (authStatus) {
+    case 2: // AUTHORIZED
+      return { status: 'granted', canNotify: true, ios: iosSettings };
+    case 3: // PROVISIONAL
+      return { status: 'provisional', canNotify: true, ios: iosSettings };
+    case 1: // DENIED
+      return { status: 'denied', canNotify: false, ios: iosSettings };
+    case 0: // NOT_DETERMINED
+    default:
+      return { status: 'undetermined', canNotify: false, ios: iosSettings };
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function mapFirebaseAuthStatus(status: any): PermissionResult {
+  // Firebase AuthorizationStatus: -1=NOT_DETERMINED, 0=DENIED, 1=AUTHORIZED, 2=PROVISIONAL
+  switch (status) {
+    case 1: // AUTHORIZED
+      return { status: 'granted', canNotify: true };
+    case 2: // PROVISIONAL
+      return { status: 'provisional', canNotify: true };
+    case 0: // DENIED
+      return { status: 'denied', canNotify: false };
+    case -1: // NOT_DETERMINED
+    default:
+      return { status: 'undetermined', canNotify: false };
+  }
+}

package/src/permissions/permissions.web.ts

@@ -0,0 +1,49 @@
+import type { PermissionResult, RequestPermissionOptions } from '../types';
+import { createNotificationError } from '../errors';
+
+function mapWebPermission(permission: NotificationPermission): PermissionResult {
+  switch (permission) {
+    case 'granted':
+      return { status: 'granted', canNotify: true };
+    case 'denied':
+      return { status: 'denied', canNotify: false };
+    case 'default':
+    default:
+      return { status: 'undetermined', canNotify: false };
+  }
+}
+
+/**
+ * Check current notification permission without prompting.
+ */
+export async function checkPermission(): Promise<PermissionResult> {
+  if (typeof Notification === 'undefined') {
+    return { status: 'denied', canNotify: false };
+  }
+  return mapWebPermission(Notification.permission);
+}
+
+/**
+ * Request notification permission from the user.
+ */
+export async function requestPermission(
+  _options?: RequestPermissionOptions,
+): Promise<PermissionResult> {
+  if (typeof Notification === 'undefined') {
+    throw createNotificationError(
+      'not_supported',
+      'Notifications are not supported in this browser',
+    );
+  }
+
+  const permission = await Notification.requestPermission();
+  return mapWebPermission(permission);
+}
+
+/**
+ * Open system notification settings.
+ * Browsers do not support programmatic settings access — this is a no-op.
+ */
+export async function openNotificationSettings(): Promise<void> {
+  // Browsers have no API to open notification settings programmatically.
+}