@idealyst/notifications 1.2.114

package/README.md

@@ -0,0 +1,77 @@
+# @idealyst/notifications
+
+Cross-platform push and local notifications for React Native and web.
+
+- **Push**: Firebase Cloud Messaging (native) / Web Push API (web)
+- **Local**: Notifee (native) / Notification API (web)
+- **Backend-agnostic**: gives you device tokens — your server sends via any push service
+
+## Installation
+
+```bash
+yarn add @idealyst/notifications
+
+# Native push (required for push on iOS/Android):
+yarn add @react-native-firebase/app @react-native-firebase/messaging
+
+# Native local (required for local notifications on iOS/Android):
+yarn add @notifee/react-native
+```
+
+## Quick Start
+
+```tsx
+import {
+  usePushNotifications,
+  useLocalNotifications,
+  useNotificationPermissions,
+} from '@idealyst/notifications';
+
+function App() {
+  const { status, requestPermission } = useNotificationPermissions();
+  const { token, register } = usePushNotifications({ autoRegister: true });
+  const { displayNotification } = useLocalNotifications();
+
+  return (
+    <Button
+      onPress={async () => {
+        await requestPermission();
+        const pushToken = await register();
+        console.log('Push token:', pushToken);
+        await displayNotification({
+          title: 'Hello',
+          body: 'Notifications are working!',
+        });
+      }}
+    >
+      Enable Notifications
+    </Button>
+  );
+}
+```
+
+## API
+
+### Hooks
+
+- `usePushNotifications(options?)` — token management, message listeners
+- `useLocalNotifications(options?)` — display, schedule, channels, badges
+- `useNotificationPermissions(options?)` — check/request permissions
+
+### Standalone Functions
+
+Push: `requestPushPermission()`, `getPushToken()`, `deletePushToken()`, `onForegroundMessage()`, `onNotificationOpened()`, `onTokenRefresh()`, `setBackgroundMessageHandler()`, `subscribeToTopic()`, `unsubscribeFromTopic()`
+
+Local: `displayNotification()`, `scheduleNotification()`, `cancelNotification()`, `cancelAllNotifications()`, `createChannel()`, `deleteChannel()`, `getChannels()`, `setCategories()`, `setBadgeCount()`, `getBadgeCount()`
+
+Permissions: `checkPermission()`, `requestPermission()`, `openNotificationSettings()`
+
+Web-only: `configurePush({ vapidKey, serviceWorkerPath? })` — required before push registration on web
+
+## Native Setup
+
+See `get_install_guide('notifications')` via the MCP server for full iOS/Android configuration (Firebase, APNs, Gradle, permissions).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@idealyst/notifications",
+  "version": "1.2.114",
+  "description": "Cross-platform push and local notifications for React and React Native",
+  "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/notifications#readme",
+  "readme": "README.md",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.native.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IdealystIO/idealyst-framework.git",
+    "directory": "packages/notifications"
+  },
+  "author": "Idealyst <contact@idealyst.io>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "react-native": "./src/index.native.ts",
+      "browser": {
+        "types": "./src/index.web.ts",
+        "import": "./src/index.web.ts",
+        "require": "./src/index.web.ts"
+      },
+      "default": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "require": "./src/index.ts"
+      }
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing TypeScript source directly'",
+    "publish:npm": "npm publish"
+  },
+  "peerDependencies": {
+    "@notifee/react-native": ">=9.0.0",
+    "@react-native-firebase/app": ">=21.0.0",
+    "@react-native-firebase/messaging": ">=21.0.0",
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "@notifee/react-native": {
+      "optional": true
+    },
+    "@react-native-firebase/app": {
+      "optional": true
+    },
+    "@react-native-firebase/messaging": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "react-native",
+    "notifications",
+    "push-notifications",
+    "local-notifications",
+    "fcm",
+    "firebase-messaging",
+    "apns",
+    "web-push",
+    "notifee",
+    "cross-platform"
+  ]
+}

package/src/constants.ts

@@ -0,0 +1,86 @@
+import type {
+  PermissionResult,
+  AndroidChannel,
+  NotificationImportance,
+} from './types';
+
+// ============================================================================
+// Default States
+// ============================================================================
+
+export const DEFAULT_PERMISSION_RESULT: PermissionResult = {
+  status: 'undetermined',
+  canNotify: false,
+};
+
+// ============================================================================
+// Default Android Channel
+// ============================================================================
+
+export const DEFAULT_CHANNEL_ID = 'default';
+
+export const DEFAULT_CHANNEL: AndroidChannel = {
+  id: DEFAULT_CHANNEL_ID,
+  name: 'Default',
+  description: 'Default notification channel',
+  importance: 'high',
+  vibration: true,
+  badge: true,
+  visibility: 'private',
+};
+
+// ============================================================================
+// Channel Presets
+// ============================================================================
+
+export const CHANNEL_PRESETS = {
+  alerts: {
+    id: 'alerts',
+    name: 'Alerts',
+    description: 'Important alerts and messages',
+    importance: 'high' as NotificationImportance,
+    vibration: true,
+    lights: true,
+    badge: true,
+    visibility: 'private' as const,
+  },
+
+  silent: {
+    id: 'silent',
+    name: 'Silent Updates',
+    description: 'Background updates without sound or vibration',
+    importance: 'low' as NotificationImportance,
+    vibration: false,
+    lights: false,
+    badge: false,
+    visibility: 'private' as const,
+  },
+
+  marketing: {
+    id: 'marketing',
+    name: 'Promotions',
+    description: 'Promotional offers and updates',
+    importance: 'default' as NotificationImportance,
+    vibration: false,
+    badge: true,
+    visibility: 'public' as const,
+  },
+
+  chat: {
+    id: 'chat',
+    name: 'Messages',
+    description: 'Chat messages and conversations',
+    importance: 'high' as NotificationImportance,
+    vibration: true,
+    lights: true,
+    badge: true,
+    sound: 'default',
+    visibility: 'private' as const,
+  },
+} as const satisfies Record<string, AndroidChannel>;
+
+// ============================================================================
+// Web Push Defaults
+// ============================================================================
+
+export const DEFAULT_SERVICE_WORKER_PATH = '/sw.js';

package/src/errors.ts

@@ -0,0 +1,92 @@
+import type { NotificationError, NotificationErrorCode } from './types';
+
+export function createNotificationError(
+  code: NotificationErrorCode,
+  message: string,
+  originalError?: unknown,
+): NotificationError {
+  return { code, message, originalError };
+}
+
+/**
+ * Normalize errors from @react-native-firebase/messaging into NotificationError.
+ */
+export function normalizeFirebaseError(error: unknown): NotificationError {
+  if (error && typeof error === 'object' && 'code' in error) {
+    const fbError = error as { code?: string; message?: string };
+
+    switch (fbError.code) {
+      case 'messaging/permission-blocked':
+      case 'messaging/permission-denied':
+        return createNotificationError(
+          'permission_denied',
+          'Notification permission was denied by the user',
+          error,
+        );
+      case 'messaging/token-subscribe-failed':
+      case 'messaging/token-unsubscribe-failed':
+        return createNotificationError(
+          'token_failed',
+          fbError.message || 'Failed to manage push token',
+          error,
+        );
+      case 'messaging/topic-subscribe-failed':
+      case 'messaging/topic-unsubscribe-failed':
+        return createNotificationError(
+          'topic_failed',
+          fbError.message || 'Failed to manage topic subscription',
+          error,
+        );
+      case 'messaging/unknown':
+      default:
+        return createNotificationError(
+          'unknown',
+          fbError.message || 'An unknown messaging error occurred',
+          error,
+        );
+    }
+  }
+
+  if (error instanceof Error) {
+    return createNotificationError('unknown', error.message, error);
+  }
+
+  return createNotificationError('unknown', String(error), error);
+}
+
+/**
+ * Normalize errors from @notifee/react-native into NotificationError.
+ */
+export function normalizeNotifeeError(error: unknown): NotificationError {
+  if (error && typeof error === 'object' && 'code' in error) {
+    const nError = error as { code?: string; message?: string };
+
+    if (nError.code?.includes('permission')) {
+      return createNotificationError(
+        'permission_denied',
+        nError.message || 'Notification permission denied',
+        error,
+      );
+    }
+
+    if (nError.code?.includes('channel')) {
+      return createNotificationError(
+        'channel_failed',
+        nError.message || 'Failed to manage notification channel',
+        error,
+      );
+    }
+
+    return createNotificationError(
+      'unknown',
+      nError.message || 'A notification error occurred',
+      error,
+    );
+  }
+
+  if (error instanceof Error) {
+    return createNotificationError('unknown', error.message, error);
+  }
+
+  return createNotificationError('unknown', String(error), error);
+}

package/src/index.native.ts

@@ -0,0 +1,120 @@
+export * from './types';
+export {
+  DEFAULT_PERMISSION_RESULT,
+  DEFAULT_CHANNEL,
+  DEFAULT_CHANNEL_ID,
+  CHANNEL_PRESETS,
+} from './constants';
+export { createNotificationError } from './errors';
+
+// Push
+export {
+  requestPushPermission,
+  getPushToken,
+  deletePushToken,
+  hasPermission,
+  onForegroundMessage,
+  onNotificationOpened,
+  onTokenRefresh,
+  setBackgroundMessageHandler,
+  subscribeToTopic,
+  unsubscribeFromTopic,
+  getAPNsToken,
+} from './push/push.native';
+
+// Local
+export {
+  displayNotification,
+  scheduleNotification,
+  cancelNotification,
+  cancelAllNotifications,
+  cancelDisplayedNotifications,
+  cancelPendingNotifications,
+  createChannel,
+  deleteChannel,
+  getChannels,
+  setCategories,
+  getDisplayedNotifications,
+  getPendingNotifications,
+  setBadgeCount,
+  getBadgeCount,
+  onNotificationEvent,
+} from './local/local.native';
+
+// Permissions
+export {
+  checkPermission,
+  requestPermission,
+  openNotificationSettings,
+} from './permissions/permissions.native';
+
+// Hooks — bound to native implementations
+import { createUsePushNotificationsHook } from './push/usePushNotifications';
+import { createUseLocalNotificationsHook } from './local/useLocalNotifications';
+import { createUseNotificationPermissionsHook } from './permissions/useNotificationPermissions';
+
+import {
+  requestPushPermission,
+  getPushToken,
+  deletePushToken,
+  onForegroundMessage,
+  onNotificationOpened,
+  onTokenRefresh,
+  subscribeToTopic,
+  unsubscribeFromTopic,
+} from './push/push.native';
+
+import {
+  displayNotification,
+  scheduleNotification,
+  cancelNotification,
+  cancelAllNotifications,
+  createChannel,
+  deleteChannel,
+  getChannels,
+  setCategories,
+  getDisplayedNotifications,
+  getPendingNotifications,
+  setBadgeCount,
+  getBadgeCount,
+  onNotificationEvent,
+} from './local/local.native';
+
+import {
+  checkPermission,
+  requestPermission,
+  openNotificationSettings,
+} from './permissions/permissions.native';
+
+export const usePushNotifications = createUsePushNotificationsHook({
+  requestPushPermission,
+  getPushToken,
+  deletePushToken,
+  onForegroundMessage,
+  onNotificationOpened,
+  onTokenRefresh,
+  subscribeToTopic,
+  unsubscribeFromTopic,
+});
+
+export const useLocalNotifications = createUseLocalNotificationsHook({
+  displayNotification,
+  scheduleNotification,
+  cancelNotification,
+  cancelAllNotifications,
+  createChannel,
+  deleteChannel,
+  getChannels,
+  setCategories,
+  getDisplayedNotifications,
+  getPendingNotifications,
+  setBadgeCount,
+  getBadgeCount,
+  onNotificationEvent,
+});
+
+export const useNotificationPermissions = createUseNotificationPermissionsHook({
+  checkPermission,
+  requestPermission,
+  openNotificationSettings,
+});

package/src/index.ts

@@ -0,0 +1,123 @@
+// Default entry — re-exports web implementation.
+// Platform-specific entry points (index.native.ts, index.web.ts) are resolved by bundlers.
+export * from './types';
+export {
+  DEFAULT_PERMISSION_RESULT,
+  DEFAULT_CHANNEL,
+  DEFAULT_CHANNEL_ID,
+  CHANNEL_PRESETS,
+  DEFAULT_SERVICE_WORKER_PATH,
+} from './constants';
+export { createNotificationError } from './errors';
+
+// Push
+export {
+  configurePush,
+  requestPushPermission,
+  getPushToken,
+  deletePushToken,
+  hasPermission,
+  onForegroundMessage,
+  onNotificationOpened,
+  onTokenRefresh,
+  setBackgroundMessageHandler,
+  subscribeToTopic,
+  unsubscribeFromTopic,
+} from './push/push.web';
+
+// Local
+export {
+  displayNotification,
+  scheduleNotification,
+  cancelNotification,
+  cancelAllNotifications,
+  cancelDisplayedNotifications,
+  cancelPendingNotifications,
+  createChannel,
+  deleteChannel,
+  getChannels,
+  setCategories,
+  getDisplayedNotifications,
+  getPendingNotifications,
+  setBadgeCount,
+  getBadgeCount,
+  onNotificationEvent,
+} from './local/local.web';
+
+// Permissions
+export {
+  checkPermission,
+  requestPermission,
+  openNotificationSettings,
+} from './permissions/permissions.web';
+
+// Hooks — bound to web implementations
+import { createUsePushNotificationsHook } from './push/usePushNotifications';
+import { createUseLocalNotificationsHook } from './local/useLocalNotifications';
+import { createUseNotificationPermissionsHook } from './permissions/useNotificationPermissions';
+
+import {
+  requestPushPermission,
+  getPushToken,
+  deletePushToken,
+  onForegroundMessage,
+  onNotificationOpened,
+  onTokenRefresh,
+  subscribeToTopic,
+  unsubscribeFromTopic,
+} from './push/push.web';
+
+import {
+  displayNotification,
+  scheduleNotification,
+  cancelNotification,
+  cancelAllNotifications,
+  createChannel,
+  deleteChannel,
+  getChannels,
+  setCategories,
+  getDisplayedNotifications,
+  getPendingNotifications,
+  setBadgeCount,
+  getBadgeCount,
+  onNotificationEvent,
+} from './local/local.web';
+
+import {
+  checkPermission,
+  requestPermission,
+  openNotificationSettings,
+} from './permissions/permissions.web';
+
+export const usePushNotifications = createUsePushNotificationsHook({
+  requestPushPermission,
+  getPushToken,
+  deletePushToken,
+  onForegroundMessage,
+  onNotificationOpened,
+  onTokenRefresh,
+  subscribeToTopic,
+  unsubscribeFromTopic,
+});
+
+export const useLocalNotifications = createUseLocalNotificationsHook({
+  displayNotification,
+  scheduleNotification,
+  cancelNotification,
+  cancelAllNotifications,
+  createChannel,
+  deleteChannel,
+  getChannels,
+  setCategories,
+  getDisplayedNotifications,
+  getPendingNotifications,
+  setBadgeCount,
+  getBadgeCount,
+  onNotificationEvent,
+});
+
+export const useNotificationPermissions = createUseNotificationPermissionsHook({
+  checkPermission,
+  requestPermission,
+  openNotificationSettings,
+});

package/src/index.web.ts

@@ -0,0 +1,2 @@
+// Web entry — identical to index.ts.
+export * from './index';