@l.x/notifications 1.0.3 → 1.0.4

package/src/index.ts

@@ -0,0 +1,41 @@
+export { getIsNotificationServiceLocalOverrideEnabled } from './getIsNotificationServiceLocalOverrideEnabled'
+export { getNotificationQueryOptions } from './notification-data-source/getNotificationQueryOptions'
+export { createIntervalNotificationDataSource } from './notification-data-source/implementations/createIntervalNotificationDataSource'
+export {
+  type CreateLocalTriggerDataSourceContext,
+  createLocalTriggerDataSource,
+  getTriggerById,
+  type TriggerCondition,
+} from './notification-data-source/implementations/createLocalTriggerDataSource'
+export { createNotificationDataSource } from './notification-data-source/implementations/createNotificationDataSource'
+export { createPollingNotificationDataSource } from './notification-data-source/implementations/createPollingNotificationDataSource'
+export {
+  type CreateReactiveDataSourceContext,
+  createReactiveDataSource,
+} from './notification-data-source/implementations/createReactiveDataSource'
+export { type NotificationDataSource } from './notification-data-source/NotificationDataSource'
+export { type ReactiveCondition } from './notification-data-source/types/ReactiveCondition'
+export { createBaseNotificationProcessor } from './notification-processor/implementations/createBaseNotificationProcessor'
+export { type NotificationProcessor } from './notification-processor/NotificationProcessor'
+export { BannerTemplate } from './notification-renderer/components/BannerTemplate'
+export { InlineBannerNotification } from './notification-renderer/components/InlineBannerNotification'
+export { createNotificationRenderer } from './notification-renderer/implementations/createNotificationRenderer'
+export { type NotificationRenderer } from './notification-renderer/NotificationRenderer'
+export { createNotificationService } from './notification-service/implementations/createNotificationService'
+export {
+  type NotificationClickTarget,
+  type NotificationService,
+  type NotificationServiceConfig,
+} from './notification-service/NotificationService'
+export { createNotificationTelemetry } from './notification-telemetry/implementations/createNotificationTelemetry'
+export {
+  createNoopNotificationTelemetry,
+  type NotificationTelemetry,
+} from './notification-telemetry/NotificationTelemetry'
+export {
+  type ApiNotificationTrackerContext,
+  createApiNotificationTracker,
+} from './notification-tracker/implementations/createApiNotificationTracker'
+export { createNoopNotificationTracker } from './notification-tracker/implementations/createNoopNotificationTracker'
+export { createNotificationTracker } from './notification-tracker/implementations/createNotificationTracker'
+export { type NotificationTracker } from './notification-tracker/NotificationTracker'

package/src/notification-data-source/NotificationDataSource.ts

@@ -0,0 +1,10 @@
+import { type InAppNotification } from '@luxfi/api'
+
+export interface NotificationDataSource {
+  // Start receiving notifications (implementation determines mechanism: fetch, websocket, polling, etc.)
+  start(onNotifications: (notifications: InAppNotification[], source: string) => void): void
+  // Stop receiving notifications and cleanup
+  stop(): Promise<void>
+  // Trigger an immediate poll outside of the normal interval (optional)
+  refresh?(): Promise<void>
+}

package/src/notification-data-source/getNotificationQueryOptions.ts

@@ -0,0 +1,85 @@
+import { toPlainMessage } from '@bufbuild/protobuf'
+import { queryOptions } from '@tanstack/react-query'
+import { PlatformType } from '@luxamm/client-notification-service/dist/lx/notificationservice/v1/api_pb'
+import type { InAppNotification, NotificationsApiClient } from '@l.x/api'
+import { getLogger } from 'utilities/src/logger/logger'
+import { ReactQueryCacheKey } from 'utilities/src/reactQuery/cache'
+import { type QueryOptionsResult } from 'utilities/src/reactQuery/queryOptions'
+import { ONE_MINUTE_MS } from 'utilities/src/time/time'
+
+const DEFAULT_POLL_INTERVAL_MS = 2 * ONE_MINUTE_MS
+
+interface GetNotificationQueryOptionsContext {
+  apiClient: NotificationsApiClient
+  getPlatformType: () => PlatformType
+  pollIntervalMs?: number
+  getIsSessionInitialized?: () => boolean
+}
+
+/**
+ * Creates query options for polling notifications.
+ * This can be used directly in hooks or injected into the notification data source.
+ *
+ * @example
+ * ```typescript
+ * import { getNotificationQueryOptions } from '@l.x/notifications'
+ * import { useQuery } from '@tanstack/react-query'
+ *
+ * // Use in a hook
+ * const queryOptions = getNotificationQueryOptions({ apiClient })
+ * const { data } = useQuery(queryOptions)
+ *
+ * // Or inject into data source
+ * const dataSource = createFetchNotificationDataSource({
+ *   queryClient,
+ *   queryOptions,
+ * })
+ * ```
+ */
+export function getNotificationQueryOptions(
+  ctx: GetNotificationQueryOptionsContext,
+): QueryOptionsResult<InAppNotification[], Error, InAppNotification[], [ReactQueryCacheKey.Notifications]> {
+  const { apiClient, getPlatformType, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, getIsSessionInitialized } = ctx
+
+  return queryOptions({
+    queryKey: [ReactQueryCacheKey.Notifications],
+    queryFn: async (): Promise<InAppNotification[]> => {
+      const isSessionInitialized = getIsSessionInitialized?.() ?? true
+
+      if (getIsSessionInitialized && !isSessionInitialized) {
+        return []
+      }
+
+      try {
+        const platformType = getPlatformType()
+        const response = await apiClient.getNotifications({ platform_type: platformType })
+        // Convert protobuf Messages to plain objects for React Query caching
+        // toPlainMessage strips the Message prototype chain and preserves numeric enum values
+        // It's schema-aware and automatically handles nested messages, making it resilient to schema changes
+        const serialized: InAppNotification[] = response.notifications.map((notification) =>
+          toPlainMessage(notification),
+        )
+        return serialized
+      } catch (error) {
+        getLogger().error(error, {
+          tags: { file: 'notificationQueryOptions', function: 'queryFn' },
+        })
+        throw error
+      }
+    },
+    refetchInterval: getIsSessionInitialized
+      ? (): number => {
+          const isInit = getIsSessionInitialized()
+          // Poll faster (2s) when waiting for session, normal interval once initialized
+          return isInit ? pollIntervalMs : 2000
+        }
+      : (): number => pollIntervalMs,
+    refetchIntervalInBackground: true,
+    refetchOnWindowFocus: false,
+    // Use short staleTime when session check is enabled - allows faster refetches when session becomes ready
+    // Without this, empty results from pre-session fetches would be cached too long
+    staleTime: getIsSessionInitialized ? 1000 : pollIntervalMs - 1000,
+    retry: 2,
+    retryDelay: (attemptIndex: number): number => Math.min(1000 * 2 ** attemptIndex, 30000),
+  })
+}

package/src/notification-data-source/implementations/createIntervalNotificationDataSource.ts

@@ -0,0 +1,77 @@
+import { type InAppNotification } from '@l.x/api'
+import { createNotificationDataSource } from '@l.x/notifications/src/notification-data-source/implementations/createNotificationDataSource'
+import { type NotificationDataSource } from '@l.x/notifications/src/notification-data-source/NotificationDataSource'
+import { getLogger } from 'utilities/src/logger/logger'
+
+interface CreateIntervalNotificationDataSourceContext {
+  pollIntervalMs: number
+  source: string
+  logFileTag: string
+  getNotifications: () => Promise<InAppNotification[]>
+}
+
+/**
+ * Helper for building interval-based notification data sources.
+ * Handles start/stop lifecycle, immediate initial poll, and consistent error logging.
+ */
+export function createIntervalNotificationDataSource(
+  ctx: CreateIntervalNotificationDataSourceContext,
+): NotificationDataSource {
+  const { pollIntervalMs, source, logFileTag, getNotifications } = ctx
+
+  let intervalId: ReturnType<typeof setInterval> | null = null
+  let currentCallback: ((notifications: InAppNotification[], source: string) => void) | null = null
+
+  const pollAndEmit = async (logFunctionTag: string): Promise<void> => {
+    if (!currentCallback) {
+      return
+    }
+
+    try {
+      const notifications = await getNotifications()
+      currentCallback(notifications, source)
+    } catch (error) {
+      getLogger().error(error, {
+        tags: { file: logFileTag, function: logFunctionTag },
+      })
+    }
+  }
+
+  const start = (onNotifications: (notifications: InAppNotification[], source: string) => void): void => {
+    if (intervalId) {
+      return
+    }
+
+    currentCallback = onNotifications
+
+    // Check immediately on start
+    pollAndEmit('start').catch((error) => {
+      getLogger().error(error, {
+        tags: { file: logFileTag, function: 'start' },
+      })
+    })
+
+    // Then poll at interval
+    intervalId = setInterval(() => {
+      pollAndEmit('setInterval').catch((error) => {
+        getLogger().error(error, {
+          tags: { file: logFileTag, function: 'setInterval' },
+        })
+      })
+    }, pollIntervalMs)
+  }
+
+  const stop = async (): Promise<void> => {
+    if (intervalId) {
+      clearInterval(intervalId)
+      intervalId = null
+    }
+    currentCallback = null
+  }
+
+  const refresh = async (): Promise<void> => {
+    await pollAndEmit('refresh')
+  }
+
+  return { ...createNotificationDataSource({ start, stop }), refresh }
+}