@codingfactory/notify-kit-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,547 @@
+import { N as NotifyKitClient, a as NotifyKitMeResponse, L as ListNotificationsParams, b as NotifyKitListResponse, c as NotifyKitUnreadCountResponse, P as PaginationParams, d as NotifyKitNotification, e as NotifyKitPreferences, f as NotifyKitPreferencesUpdate, g as NotifyKitClientConfig, C as ConnectionState, h as NotificationCategory, i as NotificationLevel } from './useNotifyKitModals-BZ_NiTKw.js';
+export { j as ChannelPreferences, I as InvalidSnoozeDurationError, k as NOTIFICATION_CATEGORIES, l as NOTIFICATION_LEVELS, m as NOTIFY_KIT_MODALS_KEY, n as NOTIFY_KIT_STORE_KEY, o as NotifyKitApiError, p as NotifyKitErrorResponse, q as NotifyKitGroupedEntry, r as NotifyKitGroupedListResponse, s as NotifyKitModalSpec, t as NotifyKitModalState, u as NotifyKitModalsClientLike, v as NotifyKitModalsResponse, w as NotifyKitStoreState, x as PaginationMeta, U as UseNotifyKitModalsOptions, y as UseNotifyKitModalsReturn, z as UseNotifyKitStoreReturn, A as createNotifyKitClient, B as isChannelPreferences, D as isMeResponse, E as isModalEnabled, F as isModalSpec, G as isNotifyKitNotification, H as isPaginationMeta, J as isUnreadCountResponse, K as isValidCategory, M as isValidLevel, O as provideNotifyKitModals, Q as provideNotifyKitStore, R as resetNotifyKitStore, S as useNotifyKitModals, T as useNotifyKitStore } from './useNotifyKitModals-BZ_NiTKw.js';
+import { InjectionKey, ComputedRef, Ref } from 'vue';
+
+/**
+ * Notify Kit API endpoint constants.
+ *
+ * These are provided for reference and debugging purposes.
+ * The NotifyKitClient class handles URL construction internally.
+ */
+declare const ENDPOINTS: {
+    /** GET - Returns broadcast channel for authenticated user */
+    readonly ME: "/me";
+    /** GET - List notifications (supports filters and pagination) */
+    readonly NOTIFICATIONS: "/notifications";
+    /** GET - Get count of unread notifications */
+    readonly UNREAD_COUNT: "/notifications/unread-count";
+    /** PATCH - Mark a specific notification as read */
+    readonly MARK_READ: (id: string) => string;
+    /** POST - Mark all notifications as read */
+    readonly MARK_ALL_READ: "/notifications/read-all";
+    /** DELETE - Delete a specific notification */
+    readonly DELETE_NOTIFICATION: (id: string) => string;
+    /** PATCH - Mark all notifications in a group as read (Phase 2) */
+    readonly MARK_GROUP_READ: (groupKey: string) => string;
+    /** GET - Get all notifications in a group (Phase 2) */
+    readonly GROUP_NOTIFICATIONS: (groupKey: string) => string;
+    /** GET - List outstanding modal notifications */
+    readonly MODALS: "/modals";
+    /** POST - Acknowledge a modal notification */
+    readonly ACK_MODAL: (id: string) => string;
+    /** POST - Snooze a modal notification */
+    readonly SNOOZE_MODAL: (id: string) => string;
+    /** GET - Get user's notification preferences */
+    readonly PREFERENCES: "/preferences";
+};
+
+/**
+ * useNotifyKitClient composable
+ *
+ * Provides access to the NotifyKit HTTP client within Vue components.
+ * Supports both direct configuration and provide/inject pattern.
+ */
+
+/**
+ * Injection key for the NotifyKit client.
+ */
+declare const NOTIFY_KIT_CLIENT_KEY: InjectionKey<NotifyKitClient>;
+/**
+ * Return type of useNotifyKitClient composable.
+ */
+interface UseNotifyKitClientReturn {
+    /** The underlying NotifyKitClient instance */
+    readonly client: NotifyKitClient;
+    getMe: () => Promise<NotifyKitMeResponse>;
+    listNotifications: (params?: ListNotificationsParams) => Promise<NotifyKitListResponse>;
+    getUnreadCount: () => Promise<NotifyKitUnreadCountResponse>;
+    markRead: (id: string) => Promise<void>;
+    markAllRead: () => Promise<void>;
+    deleteNotification: (id: string) => Promise<void>;
+    markGroupRead: (groupKey: string) => Promise<void>;
+    getGroupNotifications: (groupKey: string, params?: PaginationParams) => Promise<NotifyKitListResponse>;
+    listModals: () => Promise<readonly NotifyKitNotification[]>;
+    ackModal: (id: string) => Promise<void>;
+    snoozeModal: (id: string, minutes: number) => Promise<void>;
+    getPreferences: () => Promise<NotifyKitPreferences>;
+    updatePreferences: (preferences: NotifyKitPreferencesUpdate) => Promise<void>;
+}
+/**
+ * Provides a NotifyKitClient for injection into descendant components.
+ *
+ * Call this in your app's setup or a parent component to make the client
+ * available to all child components via useNotifyKitClient().
+ *
+ * @example
+ * ```typescript
+ * // In App.vue setup
+ * provideNotifyKitClient({
+ *   baseUrl: '/api/notify-kit',
+ *   getAuthHeaders: () => ({ Authorization: `Bearer ${token}` })
+ * })
+ *
+ * // In any child component
+ * const { listNotifications, markRead } = useNotifyKitClient()
+ * ```
+ */
+declare function provideNotifyKitClient(config: NotifyKitClientConfig): NotifyKitClient;
+/**
+ * Access the NotifyKit client within a Vue component.
+ *
+ * If a config is provided, creates a new client instance.
+ * Otherwise, uses the client provided via provideNotifyKitClient().
+ *
+ * @throws Error if no client is available (neither config nor injection)
+ *
+ * @example
+ * ```typescript
+ * // Use injected client
+ * const { client, getMe, listNotifications } = useNotifyKitClient()
+ *
+ * // Or provide config directly
+ * const { client } = useNotifyKitClient({
+ *   baseUrl: 'https://api.example.com/notify-kit'
+ * })
+ * ```
+ */
+declare function useNotifyKitClient(config?: NotifyKitClientConfig): UseNotifyKitClientReturn;
+
+/**
+ * useNotifyKitRealtime composable
+ *
+ * Provides real-time notification handling via Laravel Echo.
+ * Manages WebSocket connection, subscribes to user's broadcast channel,
+ * and updates the store when notifications are received.
+ */
+
+/**
+ * Minimal Echo interface - just what we need for notifications.
+ * This allows consumers to pass their own Echo instance.
+ */
+interface EchoLike {
+    private: (channel: string) => EchoChannelLike;
+    leave: (channel: string) => void;
+}
+/**
+ * Minimal Echo channel interface.
+ */
+interface EchoChannelLike {
+    notification: (callback: (notification: NotifyKitNotification) => void) => EchoChannelLike;
+    stopListening: (event: string) => EchoChannelLike;
+}
+/**
+ * Minimal NotifyKit client interface - just the methods we need.
+ */
+interface NotifyKitClientLike {
+    getMe: () => Promise<{
+        broadcast_channel: string;
+    }>;
+}
+/**
+ * Configuration options for useNotifyKitRealtime.
+ */
+interface UseNotifyKitRealtimeOptions {
+    /**
+     * Laravel Echo instance or a function that returns one.
+     * Function form is useful for lazy initialization or SSR safety.
+     */
+    echo: EchoLike | (() => EchoLike);
+    /**
+     * NotifyKit client instance for fetching broadcast channel.
+     */
+    client: NotifyKitClientLike;
+    /**
+     * Whether to auto-connect when the composable is created.
+     * Default: true
+     */
+    autoConnect?: boolean;
+    /**
+     * Callback called when a notification is received.
+     * Called after store is updated.
+     */
+    onNotification?: (notification: NotifyKitNotification) => void;
+    /**
+     * Callback called when connection state changes.
+     */
+    onConnectionChange?: (state: ConnectionState) => void;
+}
+/**
+ * Return type of useNotifyKitRealtime composable.
+ */
+interface UseNotifyKitRealtimeReturn {
+    /** Whether currently connected */
+    readonly isConnected: ComputedRef<boolean>;
+    /** Current connection state */
+    readonly connectionState: Ref<ConnectionState>;
+    /** Connect to real-time notifications */
+    connect: () => Promise<void>;
+    /** Disconnect from real-time notifications */
+    disconnect: () => void;
+    /** Disconnect and reconnect */
+    reconnect: () => Promise<void>;
+}
+/**
+ * Composable for real-time notification handling via Laravel Echo.
+ *
+ * @example
+ * ```typescript
+ * import Echo from 'laravel-echo'
+ * import { useNotifyKitRealtime } from '@coding-factory/notify-kit-client'
+ *
+ * const echo = new Echo({ ... })
+ * const client = useNotifyKitClient()
+ *
+ * const {
+ *   isConnected,
+ *   connectionState,
+ *   connect,
+ *   disconnect
+ * } = useNotifyKitRealtime({
+ *   echo,
+ *   client: client.client,
+ *   onNotification: (notification) => {
+ *     console.log('New notification:', notification.title)
+ *   }
+ * })
+ * ```
+ */
+declare function useNotifyKitRealtime(options: UseNotifyKitRealtimeOptions): UseNotifyKitRealtimeReturn;
+
+/**
+ * useNotifyKitFallback composable
+ *
+ * Provides fallback polling when WebSocket connection fails.
+ * Automatically starts polling when disconnected and stops when reconnected.
+ */
+
+/**
+ * Configuration options for fallback polling.
+ */
+interface FallbackConfig {
+    /**
+     * Time in milliseconds before starting fallback polling after disconnect.
+     * Default: 5000 (5 seconds)
+     */
+    disconnectThresholdMs: number;
+    /**
+     * Polling interval for unread count in milliseconds.
+     * Default: 30000 (30 seconds)
+     */
+    unreadCountIntervalMs: number;
+    /**
+     * Polling interval for modals in milliseconds.
+     * Default: 120000 (2 minutes)
+     */
+    modalsIntervalMs: number;
+    /**
+     * Grace period in milliseconds after reconnection before stopping polling.
+     * Default: 2000 (2 seconds)
+     */
+    reconnectGracePeriodMs: number;
+}
+/**
+ * Options for useNotifyKitFallback composable.
+ */
+interface UseNotifyKitFallbackOptions {
+    /**
+     * NotifyKit client instance for API calls.
+     */
+    client: NotifyKitClient;
+    /**
+     * Connection state ref to watch for disconnect/reconnect.
+     */
+    connectionState: Ref<ConnectionState>;
+    /**
+     * Partial fallback configuration (merged with defaults).
+     */
+    config?: Partial<FallbackConfig>;
+    /**
+     * Callback when new modals are fetched during fallback.
+     */
+    onModalsReceived?: (modals: readonly NotifyKitNotification[]) => void;
+    /**
+     * Callback when unread count is fetched during fallback.
+     */
+    onUnreadCountReceived?: (count: number) => void;
+}
+/**
+ * Return type of useNotifyKitFallback composable.
+ */
+interface UseNotifyKitFallbackReturn {
+    /** Whether fallback polling is currently active */
+    readonly isPolling: Ref<boolean>;
+    /** Timestamp of the last poll */
+    readonly lastPollAt: Ref<number | null>;
+    /** Start fallback polling manually */
+    startPolling: () => void;
+    /** Stop fallback polling manually */
+    stopPolling: () => void;
+    /** Poll unread count immediately */
+    pollUnreadCount: () => Promise<void>;
+    /** Poll modals immediately */
+    pollModals: () => Promise<void>;
+}
+/**
+ * Composable for fallback polling when WebSocket connection fails.
+ *
+ * Automatically monitors connection state and starts/stops polling
+ * based on WebSocket connectivity.
+ *
+ * @example
+ * ```typescript
+ * const { connectionState } = useNotifyKitRealtime({ ... })
+ * const client = useNotifyKitClient()
+ *
+ * const {
+ *   isPolling,
+ *   lastPollAt,
+ *   startPolling,
+ *   stopPolling
+ * } = useNotifyKitFallback({
+ *   client: client.client,
+ *   connectionState,
+ *   config: {
+ *     unreadCountIntervalMs: 15000, // Poll more frequently
+ *   }
+ * })
+ * ```
+ */
+declare function useNotifyKitFallback(options: UseNotifyKitFallbackOptions): UseNotifyKitFallbackReturn;
+
+/**
+ * Toast Policy Helpers
+ *
+ * Provides utilities for apps to decide which notifications should
+ * display as toasts vs only appear in the notification inbox, and
+ * which should play sound alerts.
+ */
+
+/**
+ * Interface for toast policy implementations.
+ * Apps can implement this directly for full customization.
+ */
+interface ToastPolicy {
+    /**
+     * Determines if a notification should display as a toast.
+     * @param notification The notification to evaluate
+     * @returns true if the notification should toast
+     */
+    shouldToast(notification: NotifyKitNotification): boolean;
+    /**
+     * Determines if a notification should play a sound alert.
+     * @param notification The notification to evaluate
+     * @returns true if the notification should play sound
+     */
+    shouldPlaySound(notification: NotifyKitNotification): boolean;
+}
+/**
+ * Configuration options for creating a custom toast policy.
+ */
+interface ToastPolicyConfig {
+    /**
+     * Per-category toast settings.
+     * true = toast, false = don't toast
+     * Categories not specified use defaults.
+     */
+    toastCategories?: Partial<Record<NotificationCategory, boolean>>;
+    /**
+     * Notification levels that should play sound.
+     * Defaults to ['danger'].
+     */
+    soundLevels?: NotificationLevel[];
+    /**
+     * Categories that should always play sound regardless of level.
+     * Defaults to ['security'].
+     */
+    soundCategories?: NotificationCategory[];
+    /**
+     * Custom shouldToast function.
+     * If provided, takes precedence over toastCategories.
+     */
+    shouldToast?: (notification: NotifyKitNotification) => boolean;
+    /**
+     * Custom shouldPlaySound function.
+     * If provided, takes precedence over soundLevels and soundCategories.
+     */
+    shouldPlaySound?: (notification: NotifyKitNotification) => boolean;
+}
+/**
+ * The default toast policy.
+ *
+ * Rules:
+ * - Critical modals (requires_ack): no toast (modal is the UX)
+ * - Security: always toast
+ * - Social: no toast by default (high frequency)
+ * - All others: toast
+ *
+ * Sound rules:
+ * - Danger level: play sound
+ * - Security category: play sound
+ * - All others: no sound
+ */
+declare const defaultToastPolicy: ToastPolicy;
+/**
+ * Creates a custom toast policy with the specified overrides.
+ *
+ * @param config Configuration options for the policy
+ * @returns A ToastPolicy instance
+ *
+ * @example
+ * ```typescript
+ * // Enable toasts for social, disable for marketing
+ * const policy = createToastPolicy({
+ *   toastCategories: {
+ *     social: true,
+ *     marketing: false,
+ *   },
+ * });
+ *
+ * // Custom sound for warnings
+ * const policy = createToastPolicy({
+ *   soundLevels: ['warning', 'danger'],
+ * });
+ *
+ * // Fully custom logic
+ * const policy = createToastPolicy({
+ *   shouldToast: (n) => n.level === 'danger',
+ *   shouldPlaySound: (n) => n.category === 'security',
+ * });
+ * ```
+ */
+declare function createToastPolicy(config: ToastPolicyConfig): ToastPolicy;
+
+/**
+ * Modal helper functions for implementing accessible notification modals.
+ * These helpers ensure WCAG 2.1 AA compliance.
+ */
+
+/**
+ * Action type from notification payload.
+ */
+interface NotifyKitAction {
+    readonly type: 'link' | 'api' | 'ack' | 'snooze';
+    readonly label: string;
+    readonly primary?: boolean;
+    readonly url?: string;
+    readonly method?: string;
+    readonly endpoint?: string;
+    readonly body?: Record<string, unknown>;
+    readonly confirm?: string;
+}
+/**
+ * Get appropriate ARIA attributes for a modal element.
+ *
+ * @param notification - The notification being displayed in the modal
+ * @param ids - Element IDs for title and body elements
+ * @returns Object of ARIA attributes to spread on the modal element
+ *
+ * @example
+ * ```vue
+ * <div v-bind="getModalAriaAttributes(notification, { titleId: 'modal-title', bodyId: 'modal-body' })">
+ *   <h2 id="modal-title">{{ notification.title }}</h2>
+ *   <p id="modal-body">{{ notification.body }}</p>
+ * </div>
+ * ```
+ */
+declare function getModalAriaAttributes(notification: NotifyKitNotification, ids: {
+    titleId: string;
+    bodyId: string;
+}): Record<string, string>;
+/**
+ * Get an escape key handler based on the modal's escape behavior configuration.
+ *
+ * @param notification - The notification being displayed
+ * @param callbacks - Callback functions for close and snooze actions
+ * @returns A keydown event handler, or null if escape is disabled
+ *
+ * @example
+ * ```typescript
+ * const handleKeydown = getEscapeKeyHandler(notification, {
+ *   onClose: () => closeModal(),
+ *   onSnooze: (minutes) => snoozeModal(minutes),
+ * });
+ *
+ * if (handleKeydown) {
+ *   document.addEventListener('keydown', handleKeydown);
+ * }
+ * ```
+ */
+declare function getEscapeKeyHandler(notification: NotifyKitNotification, callbacks: {
+    onClose: () => void;
+    onSnooze: (minutes: number) => void;
+}): ((event: KeyboardEvent) => void) | null;
+/**
+ * Focus trap interface returned by createFocusTrap.
+ */
+interface FocusTrap {
+    /** Activate the focus trap - call when modal opens */
+    activate: () => void;
+    /** Deactivate the focus trap - call when modal closes */
+    deactivate: () => void;
+}
+/**
+ * Create a focus trap for a modal element.
+ * Traps tab/shift+tab navigation inside the modal.
+ *
+ * @param modalElement - The modal DOM element to trap focus within
+ * @returns Object with activate/deactivate methods
+ *
+ * @example
+ * ```typescript
+ * const trap = createFocusTrap(modalRef.value);
+ *
+ * onMounted(() => trap.activate());
+ * onUnmounted(() => trap.deactivate());
+ * ```
+ */
+declare function createFocusTrap(modalElement: HTMLElement): FocusTrap;
+/**
+ * Get data attributes for an action button.
+ *
+ * @param action - The action configuration
+ * @param index - Index of the action in the actions array
+ * @returns Object of attributes to spread on the button element
+ *
+ * @example
+ * ```vue
+ * <button
+ *   v-for="(action, index) in actions"
+ *   v-bind="getActionButtonAttributes(action, index)"
+ *   @click="handleAction(action)"
+ * >
+ *   {{ action.label }}
+ * </button>
+ * ```
+ */
+declare function getActionButtonAttributes(action: NotifyKitAction, index: number): Record<string, string | boolean>;
+/**
+ * Determine if a notification is critical (requires acknowledgment).
+ *
+ * @param notification - The notification to check
+ * @returns True if the notification is critical
+ */
+declare function isCriticalModal(notification: NotifyKitNotification): boolean;
+/**
+ * Determine if backdrop click should close the modal.
+ *
+ * @param notification - The notification being displayed
+ * @returns True if clicking the backdrop should close the modal
+ */
+declare function shouldCloseOnBackdropClick(notification: NotifyKitNotification): boolean;
+/**
+ * Get the minimum snooze duration for a notification.
+ *
+ * @param notification - The notification to check
+ * @returns Minimum snooze duration in minutes, or null if snoozing is not available
+ */
+declare function getMinSnoozeDuration(notification: NotifyKitNotification): number | null;
+
+/**
+ * @coding-factory/notify-kit-client
+ *
+ * Headless Vue 3/Nuxt client for Notify Kit notifications.
+ * Provides TypeScript types, HTTP client, composables, and Nuxt integration.
+ */
+declare const VERSION = "0.1.0";
+
+export { ConnectionState, ENDPOINTS, type EchoChannelLike, type EchoLike, type FallbackConfig, type FocusTrap, ListNotificationsParams, NOTIFY_KIT_CLIENT_KEY, NotificationCategory, NotificationLevel, type NotifyKitAction, NotifyKitClient, NotifyKitClientConfig, type NotifyKitClientLike, NotifyKitListResponse, NotifyKitMeResponse, NotifyKitNotification, NotifyKitPreferences, NotifyKitPreferencesUpdate, NotifyKitUnreadCountResponse, PaginationParams, type ToastPolicy, type ToastPolicyConfig, type UseNotifyKitClientReturn, type UseNotifyKitFallbackOptions, type UseNotifyKitFallbackReturn, type UseNotifyKitRealtimeOptions, type UseNotifyKitRealtimeReturn, VERSION, createFocusTrap, createToastPolicy, defaultToastPolicy, getActionButtonAttributes, getEscapeKeyHandler, getMinSnoozeDuration, getModalAriaAttributes, isCriticalModal, provideNotifyKitClient, shouldCloseOnBackdropClick, useNotifyKitClient, useNotifyKitFallback, useNotifyKitRealtime };