@nice2dev/game-engine 1.1.5 → 1.1.6

package/dist/types/systems/NiceNotification.d.ts

@@ -0,0 +1,438 @@
+/**
+ * NiceNotification - Notification & Alert System
+ *
+ * Comprehensive notification system for managing in-game notifications,
+ * alerts, toasts, banners, and system messages.
+ *
+ * Features:
+ * - Multiple notification types (toast, banner, popup, system)
+ * - Priority queue system
+ * - Notification categories
+ * - Auto-dismiss & manual dismiss
+ * - Notification stacking
+ * - Action buttons
+ * - Sound integration
+ * - Animation support
+ * - Notification history
+ * - Do Not Disturb mode
+ * - Notification grouping
+ * - Rich content support
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+/** Unique notification ID */
+export type NotificationId = string;
+/** Unique channel ID */
+export type ChannelId = string;
+/** Unique group ID */
+export type GroupId = string;
+/** Notification type */
+export type NotificationType = 'toast' | 'banner' | 'popup' | 'system' | 'alert' | 'snackbar';
+/** Notification priority */
+export type NotificationPriority = 'low' | 'normal' | 'high' | 'urgent' | 'critical';
+/** Notification status */
+export type NotificationStatus = 'pending' | 'showing' | 'dismissed' | 'expired' | 'action_taken';
+/** Notification position */
+export type NotificationPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'center';
+/** Animation type */
+export type AnimationType = 'fade' | 'slide' | 'scale' | 'bounce' | 'none';
+/** Notification category */
+export type NotificationCategory = 'info' | 'success' | 'warning' | 'error' | 'achievement' | 'reward' | 'social' | 'system' | 'quest' | 'combat' | 'trade' | 'custom';
+/** Notification action button */
+export interface NotificationAction {
+    id: string;
+    label: string;
+    icon?: string;
+    style?: 'primary' | 'secondary' | 'danger' | 'success';
+    callback?: () => void;
+    closeOnClick?: boolean;
+}
+/** Rich content for notification */
+export interface NotificationContent {
+    title: string;
+    message: string;
+    subtitle?: string;
+    icon?: string;
+    image?: string;
+    badge?: string;
+    progress?: number;
+    customData?: Record<string, unknown>;
+}
+/** Notification style */
+export interface NotificationStyle {
+    backgroundColor?: string;
+    textColor?: string;
+    borderColor?: string;
+    iconColor?: string;
+    width?: number;
+    maxWidth?: number;
+    opacity?: number;
+    blur?: boolean;
+    shadow?: boolean;
+    rounded?: boolean;
+}
+/** Notification sound */
+export interface NotificationSound {
+    soundId?: string;
+    volume?: number;
+    playOnShow?: boolean;
+    playOnDismiss?: boolean;
+}
+/** Notification definition */
+export interface NotificationDefinition {
+    id?: NotificationId;
+    type: NotificationType;
+    category: NotificationCategory;
+    priority: NotificationPriority;
+    content: NotificationContent;
+    position?: NotificationPosition;
+    duration?: number;
+    autoDismiss?: boolean;
+    dismissible?: boolean;
+    persistent?: boolean;
+    groupId?: GroupId;
+    channelId?: ChannelId;
+    actions?: NotificationAction[];
+    style?: NotificationStyle;
+    sound?: NotificationSound;
+    animation?: {
+        enter?: AnimationType;
+        exit?: AnimationType;
+        duration?: number;
+    };
+    metadata?: Record<string, unknown>;
+    expiresAt?: number;
+    scheduledAt?: number;
+}
+/** Active notification instance */
+export interface NotificationInstance extends NotificationDefinition {
+    id: NotificationId;
+    status: NotificationStatus;
+    createdAt: number;
+    shownAt?: number;
+    dismissedAt?: number;
+    actionTakenId?: string;
+    timeRemaining?: number;
+}
+/** Notification channel */
+export interface NotificationChannel {
+    id: ChannelId;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    soundEnabled: boolean;
+    vibrationEnabled: boolean;
+    defaultPriority: NotificationPriority;
+    defaultDuration?: number;
+    maxConcurrent: number;
+    groupSimilar: boolean;
+}
+/** Notification group */
+export interface NotificationGroup {
+    id: GroupId;
+    title: string;
+    notifications: NotificationId[];
+    collapsed: boolean;
+    createdAt: number;
+    updatedAt: number;
+    summary?: string;
+}
+/** Notification statistics */
+export interface NotificationStatistics {
+    totalShown: number;
+    totalDismissed: number;
+    totalClicked: number;
+    totalExpired: number;
+    averageViewTime: number;
+    byCategory: Record<NotificationCategory, number>;
+    byPriority: Record<NotificationPriority, number>;
+}
+/** Do Not Disturb settings */
+export interface DNDSettings {
+    enabled: boolean;
+    allowUrgent: boolean;
+    allowCritical: boolean;
+    scheduledStart?: number;
+    scheduledEnd?: number;
+    exceptChannels?: ChannelId[];
+}
+/** Filter options */
+export interface NotificationFilter {
+    types?: NotificationType[];
+    categories?: NotificationCategory[];
+    priorities?: NotificationPriority[];
+    statuses?: NotificationStatus[];
+    channelIds?: ChannelId[];
+    fromDate?: number;
+    toDate?: number;
+}
+/** Notification event types */
+export type NotificationEventType = 'notification_created' | 'notification_shown' | 'notification_dismissed' | 'notification_expired' | 'notification_clicked' | 'notification_action' | 'notification_updated' | 'group_created' | 'group_updated' | 'group_collapsed' | 'channel_changed' | 'dnd_changed' | 'queue_updated';
+/** Notification event data */
+export interface NotificationEvent {
+    type: NotificationEventType;
+    timestamp: number;
+    notificationId?: NotificationId;
+    groupId?: GroupId;
+    channelId?: ChannelId;
+    actionId?: string;
+    notification?: NotificationInstance;
+}
+/** Notification event callback */
+export type NotificationEventCallback = (event: NotificationEvent) => void;
+/** Notification system configuration */
+export interface NotificationConfig {
+    maxConcurrent: number;
+    maxQueueSize: number;
+    maxHistorySize: number;
+    defaultDuration: number;
+    defaultPosition: NotificationPosition;
+    defaultAnimationDuration: number;
+    enableSounds: boolean;
+    enableVibration: boolean;
+    enableHistory: boolean;
+    enableGrouping: boolean;
+    groupingThreshold: number;
+    stackingEnabled: boolean;
+    stackingOffset: number;
+    queueProcessInterval: number;
+    defaultChannel: ChannelId;
+}
+/** Default configuration */
+export declare const DEFAULT_NOTIFICATION_CONFIG: NotificationConfig;
+/** Priority settings */
+export declare const PRIORITY_SETTINGS: Record<NotificationPriority, {
+    autoDismiss: boolean;
+    duration: number;
+    sound: boolean;
+    vibration: boolean;
+    bypassDND: boolean;
+}>;
+/**
+ * Notification and alert system
+ */
+export declare class NiceNotification extends EventEmitter {
+    private config;
+    private notifications;
+    private queue;
+    private active;
+    private history;
+    private channels;
+    private groups;
+    private dndSettings;
+    private statistics;
+    private processInterval?;
+    private dismissTimers;
+    private idCounter;
+    constructor(config?: Partial<NotificationConfig>);
+    /**
+     * Initialize default notification channel
+     */
+    private initializeDefaultChannel;
+    /**
+     * Start queue processor
+     */
+    private startQueueProcessor;
+    /**
+     * Generate unique notification ID
+     */
+    private generateId;
+    /**
+     * Emit notification event
+     */
+    private emitEvent;
+    /**
+     * Check if notification should bypass DND
+     */
+    private shouldBypassDND;
+    /**
+     * Check if channel is enabled
+     */
+    private isChannelEnabled;
+    /**
+     * Show notification
+     */
+    show(definition: NotificationDefinition): NotificationId;
+    /**
+     * Queue notification for display
+     */
+    private queueNotification;
+    /**
+     * Insert notification into priority queue
+     */
+    private insertIntoQueue;
+    /**
+     * Process notification queue
+     */
+    private processQueue;
+    /**
+     * Show notification (make it active)
+     */
+    private showNotification;
+    /**
+     * Play notification sound
+     */
+    private playSound;
+    /**
+     * Check for expired notifications
+     */
+    private checkExpiredNotifications;
+    /**
+     * Dismiss notification
+     */
+    dismiss(id: NotificationId, _reason?: 'manual' | 'auto' | 'action'): boolean;
+    /**
+     * Dismiss all notifications
+     */
+    dismissAll(filter?: NotificationFilter): number;
+    /**
+     * Handle notification click
+     */
+    click(id: NotificationId): void;
+    /**
+     * Handle action button click
+     */
+    handleAction(notificationId: NotificationId, actionId: string): void;
+    /**
+     * Update notification
+     */
+    update(id: NotificationId, updates: Partial<NotificationContent>): boolean;
+    /**
+     * Update notification progress
+     */
+    updateProgress(id: NotificationId, progress: number): boolean;
+    /**
+     * Get notification by ID
+     */
+    get(id: NotificationId): NotificationInstance | undefined;
+    /**
+     * Get active notifications
+     */
+    getActive(): NotificationInstance[];
+    /**
+     * Get queued notifications
+     */
+    getQueued(): NotificationInstance[];
+    /**
+     * Get notifications by filter
+     */
+    getFiltered(filter: NotificationFilter): NotificationInstance[];
+    /**
+     * Add notification to group
+     */
+    private addToGroup;
+    /**
+     * Collapse notification group
+     */
+    collapseGroup(groupId: GroupId): boolean;
+    /**
+     * Expand notification group
+     */
+    expandGroup(groupId: GroupId): boolean;
+    /**
+     * Get group
+     */
+    getGroup(groupId: GroupId): NotificationGroup | undefined;
+    /**
+     * Get group notifications
+     */
+    getGroupNotifications(groupId: GroupId): NotificationInstance[];
+    /**
+     * Dismiss group
+     */
+    dismissGroup(groupId: GroupId): number;
+    /**
+     * Register notification channel
+     */
+    registerChannel(channel: NotificationChannel): void;
+    /**
+     * Get channel
+     */
+    getChannel(channelId: ChannelId): NotificationChannel | undefined;
+    /**
+     * Get all channels
+     */
+    getAllChannels(): NotificationChannel[];
+    /**
+     * Enable/disable channel
+     */
+    setChannelEnabled(channelId: ChannelId, enabled: boolean): boolean;
+    /**
+     * Update channel settings
+     */
+    updateChannel(channelId: ChannelId, updates: Partial<NotificationChannel>): boolean;
+    /**
+     * Enable Do Not Disturb
+     */
+    enableDND(settings?: Partial<DNDSettings>): void;
+    /**
+     * Disable Do Not Disturb
+     */
+    disableDND(): void;
+    /**
+     * Get DND settings
+     */
+    getDNDSettings(): DNDSettings;
+    /**
+     * Check if DND is active
+     */
+    isDNDActive(): boolean;
+    /**
+     * Add notification to history
+     */
+    private addToHistory;
+    /**
+     * Get notification history
+     */
+    getHistory(limit?: number): NotificationInstance[];
+    /**
+     * Clear history
+     */
+    clearHistory(): void;
+    /**
+     * Update average view time
+     */
+    private updateAverageViewTime;
+    /**
+     * Show info notification
+     */
+    info(title: string, message: string, options?: Partial<NotificationDefinition>): NotificationId;
+    /**
+     * Show success notification
+     */
+    success(title: string, message: string, options?: Partial<NotificationDefinition>): NotificationId;
+    /**
+     * Show warning notification
+     */
+    warning(title: string, message: string, options?: Partial<NotificationDefinition>): NotificationId;
+    /**
+     * Show error notification
+     */
+    error(title: string, message: string, options?: Partial<NotificationDefinition>): NotificationId;
+    /**
+     * Show confirm dialog
+     */
+    confirm(title: string, message: string, onConfirm: () => void, onCancel?: () => void, options?: Partial<NotificationDefinition>): NotificationId;
+    /**
+     * Get notification statistics
+     */
+    getStatistics(): NotificationStatistics;
+    /**
+     * Reset statistics
+     */
+    resetStatistics(): void;
+    /**
+     * Clear all notifications
+     */
+    clearAll(): void;
+    /**
+     * Destroy notification system
+     */
+    destroy(): void;
+}
+/**
+ * Create notification system instance
+ */
+export declare function createNotificationSystem(config?: Partial<NotificationConfig>): NiceNotification;
+export default NiceNotification;