@idealyst/notifications 1.2.114

package/src/permissions/useNotificationPermissions.ts

@@ -0,0 +1,108 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+import type {
+  UseNotificationPermissionsOptions,
+  UseNotificationPermissionsResult,
+  PermissionStatus,
+  PermissionResult,
+  RequestPermissionOptions,
+  NotificationError,
+} from '../types';
+import { DEFAULT_PERMISSION_RESULT } from '../constants';
+import { createNotificationError } from '../errors';
+
+/**
+ * Factory that creates a useNotificationPermissions hook bound to platform-specific functions.
+ */
+export function createUseNotificationPermissionsHook(fns: {
+  checkPermission: () => Promise<PermissionResult>;
+  requestPermission: (options?: RequestPermissionOptions) => Promise<PermissionResult>;
+  openNotificationSettings: () => Promise<void>;
+}) {
+  return function useNotificationPermissions(
+    options: UseNotificationPermissionsOptions = {},
+  ): UseNotificationPermissionsResult {
+    const { autoCheck = false } = options;
+
+    const [status, setStatus] = useState<PermissionStatus>('undetermined');
+    const [permission, setPermission] = useState<PermissionResult | null>(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const initializedRef = useRef(false);
+    const mountedRef = useRef(true);
+
+    useEffect(() => {
+      mountedRef.current = true;
+
+      if (autoCheck && !initializedRef.current) {
+        initializedRef.current = true;
+        fns.checkPermission().then((result) => {
+          if (mountedRef.current) {
+            setStatus(result.status);
+            setPermission(result);
+          }
+        }).catch(() => {
+          // Silently fail on auto-check
+        });
+      }
+
+      return () => {
+        mountedRef.current = false;
+      };
+    }, [autoCheck]);
+
+    const checkPermission = useCallback(async (): Promise<PermissionResult> => {
+      setIsLoading(true);
+      try {
+        const result = await fns.checkPermission();
+        if (mountedRef.current) {
+          setStatus(result.status);
+          setPermission(result);
+        }
+        return result;
+      } catch (error) {
+        throw createNotificationError(
+          'unknown',
+          error instanceof Error ? error.message : String(error),
+          error,
+        );
+      } finally {
+        if (mountedRef.current) setIsLoading(false);
+      }
+    }, []);
+
+    const requestPermission = useCallback(
+      async (reqOptions?: RequestPermissionOptions): Promise<PermissionResult> => {
+        setIsLoading(true);
+        try {
+          const result = await fns.requestPermission(reqOptions);
+          if (mountedRef.current) {
+            setStatus(result.status);
+            setPermission(result);
+          }
+          return result;
+        } catch (error) {
+          throw createNotificationError(
+            'permission_denied',
+            error instanceof Error ? error.message : String(error),
+            error,
+          );
+        } finally {
+          if (mountedRef.current) setIsLoading(false);
+        }
+      },
+      [],
+    );
+
+    const openSettings = useCallback(async (): Promise<void> => {
+      await fns.openNotificationSettings();
+    }, []);
+
+    return {
+      status,
+      permission,
+      isLoading,
+      checkPermission,
+      requestPermission,
+      openSettings,
+    };
+  };
+}

package/src/push/push.native.ts

@@ -0,0 +1,248 @@
+// ============================================================================
+// Native Push Notification Implementation
+// Wraps @react-native-firebase/messaging for FCM (Android) and APNs (iOS).
+//
+// FCM is the only push transport on Android (GCM was deprecated in 2019).
+// On iOS, Firebase Messaging bridges to APNs under the hood.
+// ============================================================================
+
+import { Platform } from 'react-native';
+import type {
+  PermissionResult,
+  RequestPermissionOptions,
+  PushToken,
+  RemoteMessage,
+  MessageHandler,
+  TokenRefreshHandler,
+} from '../types';
+import { createNotificationError, normalizeFirebaseError } from '../errors';
+
+// Graceful optional import — @react-native-firebase/messaging may not be installed
+// 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 when methods are called
+}
+
+function assertMessaging(): void {
+  if (!Messaging) {
+    throw createNotificationError(
+      'not_available',
+      '@react-native-firebase/messaging is not installed. Run: yarn add @react-native-firebase/app @react-native-firebase/messaging',
+    );
+  }
+}
+
+// ============================================================================
+// Push Functions
+// ============================================================================
+
+/**
+ * Request push notification permission.
+ * On iOS, prompts the user. On Android 12 and below, this is a no-op (auto-granted).
+ * Android 13+ (API 33) POST_NOTIFICATIONS permission should be handled via permissions layer.
+ */
+export async function requestPushPermission(
+  _options?: RequestPermissionOptions,
+): Promise<PermissionResult> {
+  assertMessaging();
+
+  try {
+    const status = await Messaging().requestPermission();
+    return mapAuthStatus(status);
+  } catch (error) {
+    throw normalizeFirebaseError(error);
+  }
+}
+
+/**
+ * Check if push notification permission is granted.
+ */
+export async function hasPermission(): Promise<boolean> {
+  assertMessaging();
+
+  try {
+    const status = await Messaging().hasPermission();
+    // 1 = AUTHORIZED, 2 = PROVISIONAL
+    return status === 1 || status === 2;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the FCM push token.
+ */
+export async function getPushToken(): Promise<PushToken> {
+  assertMessaging();
+
+  try {
+    const token = await Messaging().getToken();
+    return { token, type: 'fcm' };
+  } catch (error) {
+    throw normalizeFirebaseError(error);
+  }
+}
+
+/**
+ * Delete the FCM push token (unregister).
+ */
+export async function deletePushToken(): Promise<void> {
+  assertMessaging();
+
+  try {
+    await Messaging().deleteToken();
+  } catch (error) {
+    throw normalizeFirebaseError(error);
+  }
+}
+
+/**
+ * Register a handler for foreground push messages.
+ * Returns an unsubscribe function.
+ */
+export function onForegroundMessage(handler: MessageHandler): () => void {
+  assertMessaging();
+
+  return Messaging().onMessage((rawMessage: unknown) => {
+    const message = normalizeFirebaseMessage(rawMessage, 'foreground');
+    handler(message);
+  });
+}
+
+/**
+ * Register a handler for notification open events (when app is in background).
+ * Also checks for initial notification (when app was launched from quit state).
+ * Returns an unsubscribe function.
+ */
+export function onNotificationOpened(handler: MessageHandler): () => void {
+  assertMessaging();
+
+  // Check for initial notification (app opened from quit state)
+  Messaging()
+    .getInitialNotification()
+    .then((rawMessage: unknown) => {
+      if (rawMessage) {
+        const message = normalizeFirebaseMessage(rawMessage, 'quit');
+        handler(message);
+      }
+    })
+    .catch(() => {
+      // Silently fail — initial notification check is best-effort
+    });
+
+  // Listen for notification opens while app is in background
+  return Messaging().onNotificationOpenedApp((rawMessage: unknown) => {
+    const message = normalizeFirebaseMessage(rawMessage, 'background');
+    handler(message);
+  });
+}
+
+/**
+ * Register a handler for token refresh events.
+ * Returns an unsubscribe function.
+ */
+export function onTokenRefresh(handler: TokenRefreshHandler): () => void {
+  assertMessaging();
+
+  return Messaging().onTokenRefresh((newToken: string) => {
+    handler({ token: newToken, type: 'fcm' });
+  });
+}
+
+/**
+ * Set background message handler.
+ * MUST be called at the top level (outside React tree), typically in index.js.
+ */
+export function setBackgroundMessageHandler(handler: MessageHandler): void {
+  assertMessaging();
+
+  Messaging().setBackgroundMessageHandler(async (rawMessage: unknown) => {
+    const message = normalizeFirebaseMessage(rawMessage, 'background');
+    await handler(message);
+  });
+}
+
+/**
+ * Subscribe to an FCM topic.
+ */
+export async function subscribeToTopic(topic: string): Promise<void> {
+  assertMessaging();
+
+  try {
+    await Messaging().subscribeToTopic(topic);
+  } catch (error) {
+    throw normalizeFirebaseError(error);
+  }
+}
+
+/**
+ * Unsubscribe from an FCM topic.
+ */
+export async function unsubscribeFromTopic(topic: string): Promise<void> {
+  assertMessaging();
+
+  try {
+    await Messaging().unsubscribeFromTopic(topic);
+  } catch (error) {
+    throw normalizeFirebaseError(error);
+  }
+}
+
+/**
+ * Get the APNs token (iOS only).
+ * Returns null on Android.
+ */
+export async function getAPNsToken(): Promise<string | null> {
+  if (Platform.OS !== 'ios' || !Messaging) return null;
+
+  try {
+    return await Messaging().getAPNSToken();
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function mapAuthStatus(status: any): PermissionResult {
+  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 };
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function normalizeFirebaseMessage(raw: any, origin: RemoteMessage['origin']): RemoteMessage {
+  return {
+    messageId: raw.messageId ?? '',
+    data: raw.data ?? {},
+    notification: raw.notification
+      ? {
+          title: raw.notification.title,
+          body: raw.notification.body,
+          imageUrl:
+            raw.notification.android?.imageUrl ??
+            raw.notification.ios?.imageUrl ??
+            raw.notification.imageUrl,
+        }
+      : undefined,
+    topic: raw.topic,
+    collapseKey: raw.collapseKey,
+    sentTime: raw.sentTime,
+    ttl: raw.ttl,
+    origin,
+  };
+}

package/src/push/push.web.ts

@@ -0,0 +1,250 @@
+import type {
+  PermissionResult,
+  RequestPermissionOptions,
+  PushToken,
+  RemoteMessage,
+  MessageHandler,
+  TokenRefreshHandler,
+  WebPushConfig,
+} from '../types';
+import { DEFAULT_SERVICE_WORKER_PATH } from '../constants';
+import { createNotificationError } from '../errors';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+let _config: WebPushConfig | null = null;
+let _swRegistration: ServiceWorkerRegistration | null = null;
+let _subscription: PushSubscription | null = null;
+let _foregroundHandler: MessageHandler | null = null;
+let _openedHandler: MessageHandler | null = null;
+let _tokenRefreshHandler: TokenRefreshHandler | null = null;
+
+/**
+ * Configure web push with VAPID key and service worker path.
+ * Must be called before requesting a push token.
+ */
+export function configurePush(config: WebPushConfig): void {
+  _config = config;
+}
+
+// ============================================================================
+// Push Functions
+// ============================================================================
+
+/**
+ * Request push notification permission.
+ */
+export async function requestPushPermission(
+  _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 {
+    status: permission === 'granted' ? 'granted' : permission === 'denied' ? 'denied' : 'undetermined',
+    canNotify: permission === 'granted',
+  };
+}
+
+/**
+ * Check if push notification permission is granted.
+ */
+export async function hasPermission(): Promise<boolean> {
+  if (typeof Notification === 'undefined') return false;
+  return Notification.permission === 'granted';
+}
+
+/**
+ * Get push token (PushSubscription) from the browser.
+ * Requires configurePush() to have been called with a VAPID key.
+ */
+export async function getPushToken(): Promise<PushToken> {
+  if (!_config?.vapidKey) {
+    throw createNotificationError(
+      'token_failed',
+      'VAPID key not configured. Call configurePush({ vapidKey }) first.',
+    );
+  }
+
+  if (!('serviceWorker' in navigator) || !('PushManager' in window)) {
+    throw createNotificationError(
+      'not_supported',
+      'Push notifications are not supported in this browser',
+    );
+  }
+
+  try {
+    const registration = await navigator.serviceWorker.register(
+      _config.serviceWorkerPath ?? DEFAULT_SERVICE_WORKER_PATH,
+    );
+    await navigator.serviceWorker.ready;
+    _swRegistration = registration;
+
+    const subscription = await registration.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: urlBase64ToUint8Array(_config.vapidKey),
+    });
+
+    _subscription = subscription;
+
+    return {
+      token: JSON.stringify(subscription.toJSON()),
+      type: 'web',
+    };
+  } catch (error) {
+    throw createNotificationError(
+      'token_failed',
+      error instanceof Error ? error.message : 'Failed to get push subscription',
+      error,
+    );
+  }
+}
+
+/**
+ * Delete push token (unsubscribe from push).
+ */
+export async function deletePushToken(): Promise<void> {
+  if (_subscription) {
+    try {
+      await _subscription.unsubscribe();
+    } catch {
+      // Ignore unsubscribe errors
+    }
+    _subscription = null;
+  }
+}
+
+/**
+ * Register a handler for foreground push messages.
+ * Returns an unsubscribe function.
+ */
+export function onForegroundMessage(handler: MessageHandler): () => void {
+  _foregroundHandler = handler;
+
+  const listener = (event: MessageEvent) => {
+    if (event.data?.type === 'push-message' && _foregroundHandler) {
+      const message = normalizeWebMessage(event.data, 'foreground');
+      _foregroundHandler(message);
+    }
+  };
+
+  navigator.serviceWorker?.addEventListener('message', listener);
+
+  return () => {
+    _foregroundHandler = null;
+    navigator.serviceWorker?.removeEventListener('message', listener);
+  };
+}
+
+/**
+ * Register a handler for notification open events.
+ * Returns an unsubscribe function.
+ */
+export function onNotificationOpened(handler: MessageHandler): () => void {
+  _openedHandler = handler;
+
+  const listener = (event: MessageEvent) => {
+    if (event.data?.type === 'notification-click' && _openedHandler) {
+      const message = normalizeWebMessage(event.data, 'background');
+      _openedHandler(message);
+    }
+  };
+
+  navigator.serviceWorker?.addEventListener('message', listener);
+
+  return () => {
+    _openedHandler = null;
+    navigator.serviceWorker?.removeEventListener('message', listener);
+  };
+}
+
+/**
+ * Register a handler for token refresh events.
+ * Returns an unsubscribe function.
+ */
+export function onTokenRefresh(handler: TokenRefreshHandler): () => void {
+  _tokenRefreshHandler = handler;
+
+  // Web push subscriptions can change when service worker updates.
+  // Listen for pushsubscriptionchange via the service worker.
+  const listener = async () => {
+    if (_tokenRefreshHandler && _config) {
+      try {
+        const token = await getPushToken();
+        _tokenRefreshHandler(token);
+      } catch {
+        // Silently fail on token refresh
+      }
+    }
+  };
+
+  navigator.serviceWorker?.addEventListener('controllerchange', listener);
+
+  return () => {
+    _tokenRefreshHandler = null;
+    navigator.serviceWorker?.removeEventListener('controllerchange', listener);
+  };
+}
+
+/**
+ * Set background message handler.
+ * On web, background push messages are handled by the Service Worker.
+ * This is a no-op — implement background handling in your service worker script.
+ */
+export function setBackgroundMessageHandler(_handler: MessageHandler): void {
+  // No-op: background messages are handled by the Service Worker.
+}
+
+/**
+ * Subscribe to a topic.
+ * Not supported on web — topic management should be done server-side.
+ */
+export async function subscribeToTopic(_topic: string): Promise<void> {
+  // No-op: topic subscriptions are managed server-side for web push.
+}
+
+/**
+ * Unsubscribe from a topic.
+ * Not supported on web — topic management should be done server-side.
+ */
+export async function unsubscribeFromTopic(_topic: string): Promise<void> {
+  // No-op: topic subscriptions are managed server-side for web push.
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function urlBase64ToUint8Array(base64String: string): Uint8Array {
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+  const rawData = atob(base64);
+  const outputArray = new Uint8Array(rawData.length);
+  for (let i = 0; i < rawData.length; i++) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+  return outputArray;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function normalizeWebMessage(data: any, origin: RemoteMessage['origin']): RemoteMessage {
+  return {
+    messageId: data.messageId ?? data.id ?? String(Date.now()),
+    data: data.data ?? {},
+    notification: data.notification
+      ? {
+          title: data.notification.title,
+          body: data.notification.body,
+          imageUrl: data.notification.image ?? data.notification.imageUrl,
+        }
+      : undefined,
+    origin,
+  };
+}