@codingfactory/notify-kit-client 0.1.0

package/dist/useNotifyKitModals-BZ_NiTKw.d.ts

@@ -0,0 +1,586 @@
+import { InjectionKey, ComputedRef, Ref } from 'vue';
+
+/**
+ * Modal-related type definitions for critical notification modals.
+ */
+/**
+ * Escape key behavior modes for modals.
+ */
+type EscapeKeyBehavior = 'close' | 'snooze' | 'disabled';
+/**
+ * Accessibility settings for modal notifications.
+ * Ensures WCAG 2.1 AA compliance.
+ */
+interface NotifyKitModalAccessibility {
+    /** Escape key behavior: close, snooze, or disabled */
+    readonly escape_key_behavior: EscapeKeyBehavior;
+    /** Whether focus is trapped inside the modal */
+    readonly focus_trap: boolean;
+    /** Whether to auto-focus the first action button */
+    readonly auto_focus_first_action: boolean;
+    /** ARIA role for the modal element */
+    readonly aria_role: string;
+    /** ID of the element that labels the modal (aria-labelledby) */
+    readonly aria_labelled_by: string | null;
+    /** ID of the element that describes the modal (aria-describedby) */
+    readonly aria_described_by: string | null;
+}
+/**
+ * Modal specification included in notifications that require modal display.
+ */
+interface NotifyKitModalSpec {
+    /** Whether modal display is enabled for this notification */
+    readonly enabled: boolean;
+    /** Whether the user must acknowledge before dismissing */
+    readonly requires_ack: boolean;
+    /** Available snooze duration options in minutes */
+    readonly snooze_options_minutes: readonly number[];
+    /** Accessibility settings for the modal */
+    readonly accessibility: NotifyKitModalAccessibility;
+}
+/**
+ * Modal state tracking for a notification.
+ * This represents the user's interaction state with a modal notification.
+ */
+interface NotifyKitModalState {
+    /** Timestamp when the modal was acknowledged (ISO 8601), null if not yet acknowledged */
+    readonly acknowledged_at: string | null;
+    /** Timestamp until which the modal is snoozed (ISO 8601), null if not snoozed */
+    readonly snoozed_until: string | null;
+}
+/**
+ * Type guard to validate if a value is a valid NotifyKitModalSpec.
+ */
+declare function isModalSpec(value: unknown): value is NotifyKitModalSpec;
+
+/**
+ * Notification type definitions matching the Notify Kit backend contract.
+ */
+
+/**
+ * Valid notification categories.
+ */
+type NotificationCategory = 'workspace' | 'security' | 'orders' | 'social' | 'system' | 'marketing';
+/**
+ * Valid notification severity levels.
+ */
+type NotificationLevel = 'info' | 'success' | 'warning' | 'danger';
+/**
+ * All valid category values for runtime validation.
+ */
+declare const NOTIFICATION_CATEGORIES: readonly NotificationCategory[];
+/**
+ * All valid level values for runtime validation.
+ */
+declare const NOTIFICATION_LEVELS: readonly NotificationLevel[];
+/**
+ * Core notification payload structure matching the Notify Kit backend contract.
+ */
+interface NotifyKitNotification {
+    /** Unique notification ID (UUID) */
+    readonly id: string;
+    /** Notification key (e.g., 'orders.shipped', 'security.critical_alert') */
+    readonly key: string;
+    /** Notification category */
+    readonly category: NotificationCategory;
+    /** Severity level */
+    readonly level: NotificationLevel;
+    /** Notification title */
+    readonly title: string;
+    /** Notification body text */
+    readonly body: string;
+    /** Optional URL for the notification action */
+    readonly action_url: string | null;
+    /** Workspace ID if this is a workspace-scoped notification */
+    readonly workspace_id: string | null;
+    /** Modal specification if this notification requires modal display */
+    readonly modal: NotifyKitModalSpec | null;
+    /** Group key for notification aggregation (Phase 2) */
+    readonly group_key: string | null;
+    /** Idempotency key to prevent duplicate notifications (Phase 2) */
+    readonly idempotency_key: string | null;
+    /** Additional arbitrary data */
+    readonly data: Record<string, unknown>;
+    /** Timestamp when notification was marked as read (ISO 8601) */
+    readonly read_at: string | null;
+    /** Timestamp when notification was created (ISO 8601) */
+    readonly created_at: string;
+}
+/**
+ * Type guard to validate if a value is a valid NotificationCategory.
+ */
+declare function isValidCategory(value: unknown): value is NotificationCategory;
+/**
+ * Type guard to validate if a value is a valid NotificationLevel.
+ */
+declare function isValidLevel(value: unknown): value is NotificationLevel;
+/**
+ * Type guard to validate if a value is a NotifyKitNotification.
+ * Use this to validate data from external sources (API responses, WebSocket messages).
+ */
+declare function isNotifyKitNotification(value: unknown): value is NotifyKitNotification;
+/**
+ * Helper to check if a notification has modal functionality enabled.
+ */
+declare function isModalEnabled(notification: NotifyKitNotification): boolean;
+
+/**
+ * User notification preferences type definitions.
+ */
+
+/**
+ * Channel preference settings for a single category.
+ */
+interface ChannelPreferences {
+    /** Whether to store in database (notification center) */
+    readonly database: boolean;
+    /** Whether to broadcast in real-time */
+    readonly broadcast: boolean;
+    /** Whether to send via email */
+    readonly mail: boolean;
+}
+/**
+ * User's notification preferences organized by category.
+ */
+interface NotifyKitPreferences {
+    /** Preferences per category */
+    readonly categories: Readonly<Record<NotificationCategory, ChannelPreferences>>;
+}
+/**
+ * Partial preferences update request.
+ * Only categories/channels that need updating should be included.
+ */
+interface NotifyKitPreferencesUpdate {
+    /** Partial category preferences to update */
+    readonly categories?: Partial<Record<NotificationCategory, Partial<ChannelPreferences>>>;
+}
+/**
+ * Type guard to validate if a value is valid ChannelPreferences.
+ */
+declare function isChannelPreferences(value: unknown): value is ChannelPreferences;
+
+/**
+ * API response type definitions for Notify Kit endpoints.
+ */
+
+/**
+ * Pagination metadata returned with list responses.
+ */
+interface PaginationMeta {
+    /** Current page number (1-indexed) */
+    readonly current_page: number;
+    /** Last page number */
+    readonly last_page: number;
+    /** Number of items per page */
+    readonly per_page: number;
+    /** Total number of items */
+    readonly total: number;
+}
+/**
+ * Response from GET /me endpoint.
+ */
+interface NotifyKitMeResponse {
+    /** The private broadcast channel for this user */
+    readonly broadcast_channel: string;
+}
+/**
+ * Response from GET /notifications endpoint.
+ */
+interface NotifyKitListResponse {
+    /** Array of notifications */
+    readonly data: readonly NotifyKitNotification[];
+    /** Pagination metadata */
+    readonly meta: PaginationMeta;
+}
+/**
+ * A grouped notification entry returned when using grouped=1 parameter.
+ */
+interface NotifyKitGroupedEntry {
+    /** The group key for this group */
+    readonly group_key: string;
+    /** Number of notifications in this group */
+    readonly group_count: number;
+    /** The most recent notification in the group */
+    readonly latest_notification: NotifyKitNotification;
+    /** IDs of all notifications in this group */
+    readonly notification_ids: readonly string[];
+    /** Whether any notification in the group is unread */
+    readonly has_unread: boolean;
+}
+/**
+ * Response from GET /notifications?grouped=1 endpoint.
+ */
+interface NotifyKitGroupedListResponse {
+    /** Array of grouped entries (may include ungrouped notifications as single-item groups) */
+    readonly data: readonly NotifyKitGroupedEntry[];
+    /** Pagination metadata */
+    readonly meta: PaginationMeta;
+}
+/**
+ * Response from GET /notifications/unread-count endpoint.
+ */
+interface NotifyKitUnreadCountResponse {
+    /** Number of unread notifications */
+    readonly count: number;
+}
+/**
+ * Response from GET /modals endpoint.
+ */
+interface NotifyKitModalsResponse {
+    /** Array of outstanding modal notifications */
+    readonly data: readonly NotifyKitNotification[];
+}
+/**
+ * Parameters for listing notifications.
+ */
+interface ListNotificationsParams {
+    /** Filter to unread notifications only */
+    readonly unread?: boolean;
+    /** Filter by category */
+    readonly category?: NotificationCategory;
+    /** Filter by workspace ID */
+    readonly workspace_id?: string;
+    /** Enable grouped mode (Phase 2) */
+    readonly grouped?: boolean;
+    /** Page number for pagination */
+    readonly page?: number;
+    /** Number of items per page */
+    readonly per_page?: number;
+}
+/**
+ * Parameters for paginated requests.
+ */
+interface PaginationParams {
+    /** Page number (1-indexed) */
+    readonly page?: number;
+    /** Number of items per page */
+    readonly per_page?: number;
+}
+/**
+ * Standard error response from the API.
+ */
+interface NotifyKitErrorResponse {
+    /** Error message */
+    readonly message: string;
+    /** Validation errors (field -> error messages) */
+    readonly errors?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Type guard to validate PaginationMeta.
+ */
+declare function isPaginationMeta(value: unknown): value is PaginationMeta;
+/**
+ * Type guard to validate NotifyKitMeResponse.
+ */
+declare function isMeResponse(value: unknown): value is NotifyKitMeResponse;
+/**
+ * Type guard to validate NotifyKitUnreadCountResponse.
+ */
+declare function isUnreadCountResponse(value: unknown): value is NotifyKitUnreadCountResponse;
+
+/**
+ * Notify Kit HTTP Client
+ *
+ * Provides type-safe access to all Notify Kit API endpoints.
+ */
+
+/**
+ * Configuration options for the NotifyKit client.
+ */
+interface NotifyKitClientConfig {
+    /** Base URL for the Notify Kit API (e.g., '/api/notify-kit' or 'https://api.example.com') */
+    baseUrl: string;
+    /** Optional function to provide auth headers for requests */
+    getAuthHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Optional custom fetch implementation (defaults to global fetch) */
+    fetch?: typeof fetch;
+}
+/**
+ * API error thrown when requests fail.
+ */
+declare class NotifyKitApiError extends Error {
+    readonly status: number;
+    readonly errors?: Readonly<Record<string, readonly string[]>> | undefined;
+    readonly name = "NotifyKitApiError";
+    constructor(message: string, status: number, errors?: Readonly<Record<string, readonly string[]>> | undefined);
+}
+/**
+ * HTTP Client for the Notify Kit API.
+ */
+declare class NotifyKitClient {
+    private readonly baseUrl;
+    private readonly getAuthHeaders;
+    private readonly fetchFn;
+    constructor(config: NotifyKitClientConfig);
+    /**
+     * Get the current user's broadcast channel information.
+     */
+    getMe(): Promise<NotifyKitMeResponse>;
+    /**
+     * List notifications for the current user.
+     */
+    listNotifications(params?: ListNotificationsParams): Promise<NotifyKitListResponse>;
+    /**
+     * Get the count of unread notifications.
+     */
+    getUnreadCount(): Promise<NotifyKitUnreadCountResponse>;
+    /**
+     * Mark a notification as read.
+     */
+    markRead(id: string): Promise<void>;
+    /**
+     * Mark all notifications as read.
+     */
+    markAllRead(): Promise<void>;
+    /**
+     * Delete a notification.
+     */
+    deleteNotification(id: string): Promise<void>;
+    /**
+     * Mark all notifications in a group as read.
+     */
+    markGroupRead(groupKey: string): Promise<void>;
+    /**
+     * Get all notifications in a group.
+     */
+    getGroupNotifications(groupKey: string, params?: PaginationParams): Promise<NotifyKitListResponse>;
+    /**
+     * List outstanding modal notifications.
+     */
+    listModals(): Promise<readonly NotifyKitNotification[]>;
+    /**
+     * Acknowledge a modal notification.
+     */
+    ackModal(id: string): Promise<void>;
+    /**
+     * Snooze a modal notification.
+     */
+    snoozeModal(id: string, minutes: number): Promise<void>;
+    /**
+     * Get the current user's notification preferences.
+     */
+    getPreferences(): Promise<NotifyKitPreferences>;
+    /**
+     * Update the current user's notification preferences.
+     */
+    updatePreferences(preferences: NotifyKitPreferencesUpdate): Promise<void>;
+    private buildNotificationParams;
+    private request;
+}
+/**
+ * Create a new NotifyKit client instance.
+ */
+declare function createNotifyKitClient(config: NotifyKitClientConfig): NotifyKitClient;
+
+/**
+ * useNotifyKitStore composable
+ *
+ * Provides a reactive store for NotifyKit state management.
+ * Manages notifications, unread counts, modal queue, and connection state.
+ * Uses singleton pattern to share state across components.
+ */
+
+/**
+ * Connection state for real-time subscriptions.
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+/**
+ * Store state shape.
+ */
+interface NotifyKitStoreState {
+    readonly notifications: readonly NotifyKitNotification[];
+    readonly notificationsLoading: boolean;
+    readonly notificationsMeta: PaginationMeta | null;
+    readonly unreadCount: number;
+    readonly unreadCountLoading: boolean;
+    readonly modalQueue: readonly NotifyKitNotification[];
+    readonly modalsLoading: boolean;
+    readonly broadcastChannel: string | null;
+    readonly connectionState: ConnectionState;
+    readonly lastNotificationsSync: number | null;
+    readonly lastModalsSync: number | null;
+}
+/**
+ * Return type of useNotifyKitStore composable.
+ */
+interface UseNotifyKitStoreReturn {
+    /** Readonly reactive state */
+    readonly state: NotifyKitStoreState;
+    /** Computed: whether there are unread notifications */
+    readonly hasUnread: ComputedRef<boolean>;
+    /** Computed: the current (first) modal in queue, or null */
+    readonly currentModal: ComputedRef<NotifyKitNotification | null>;
+    /** Computed: whether there are modals in the queue */
+    readonly hasModals: ComputedRef<boolean>;
+    addNotification: (notification: NotifyKitNotification) => void;
+    setNotifications: (notifications: readonly NotifyKitNotification[]) => void;
+    markNotificationRead: (id: string) => void;
+    removeNotification: (id: string) => void;
+    setUnreadCount: (count: number) => void;
+    incrementUnreadCount: () => void;
+    decrementUnreadCount: () => void;
+    enqueueModal: (notification: NotifyKitNotification) => void;
+    dequeueModal: (id: string) => void;
+    clearModalQueue: () => void;
+    setConnectionState: (state: ConnectionState) => void;
+    setBroadcastChannel: (channel: string) => void;
+    setNotificationsLoading: (loading: boolean) => void;
+    setUnreadCountLoading: (loading: boolean) => void;
+    setModalsLoading: (loading: boolean) => void;
+    setNotificationsMeta: (meta: PaginationMeta | null) => void;
+    setLastNotificationsSync: (timestamp: number | null) => void;
+    setLastModalsSync: (timestamp: number | null) => void;
+    reset: () => void;
+}
+/**
+ * Injection key for the NotifyKit store.
+ */
+declare const NOTIFY_KIT_STORE_KEY: InjectionKey<UseNotifyKitStoreReturn>;
+/**
+ * Resets the store state to initial values.
+ * Primarily used for testing to ensure clean state between tests.
+ */
+declare function resetNotifyKitStore(): void;
+/**
+ * Provides the NotifyKit store for injection into descendant components.
+ *
+ * Call this in your app's setup or a parent component to make the store
+ * available to all child components via useNotifyKitStore().
+ *
+ * @example
+ * ```typescript
+ * // In App.vue setup
+ * const store = provideNotifyKitStore()
+ *
+ * // In any child component
+ * const { state, addNotification } = useNotifyKitStore()
+ * ```
+ */
+declare function provideNotifyKitStore(): UseNotifyKitStoreReturn;
+/**
+ * Access the NotifyKit store within a Vue component.
+ *
+ * Uses a singleton pattern to share state across all components.
+ *
+ * @example
+ * ```typescript
+ * const {
+ *   state,
+ *   hasUnread,
+ *   currentModal,
+ *   addNotification,
+ *   markNotificationRead
+ * } = useNotifyKitStore()
+ * ```
+ */
+declare function useNotifyKitStore(): UseNotifyKitStoreReturn;
+
+/**
+ * useNotifyKitModals composable
+ *
+ * Provides modal queue management for critical notifications.
+ * Handles loading outstanding modals, acknowledgement, and snoozing.
+ */
+
+/**
+ * Minimal NotifyKit client interface - just the modal methods.
+ */
+interface NotifyKitModalsClientLike {
+    listModals: () => Promise<readonly NotifyKitNotification[]>;
+    ackModal: (id: string) => Promise<void>;
+    snoozeModal: (id: string, minutes: number) => Promise<void>;
+}
+/**
+ * Configuration options for useNotifyKitModals.
+ */
+interface UseNotifyKitModalsOptions {
+    /**
+     * NotifyKit client instance for modal API calls.
+     */
+    client: NotifyKitModalsClientLike;
+}
+/**
+ * Return type of useNotifyKitModals composable.
+ */
+interface UseNotifyKitModalsReturn {
+    /** The current (first) modal in queue, or null */
+    readonly currentModal: ComputedRef<NotifyKitNotification | null>;
+    /** All modals in the queue */
+    readonly modalQueue: ComputedRef<readonly NotifyKitNotification[]>;
+    /** Whether there are modals in the queue */
+    readonly hasModals: ComputedRef<boolean>;
+    /** Whether modals are currently being loaded */
+    readonly isLoading: Ref<boolean>;
+    /** Load outstanding modals from the API */
+    loadOutstandingModals: () => Promise<void>;
+    /** Acknowledge a modal (removes from queue) */
+    ack: (id: string) => Promise<void>;
+    /** Snooze a modal (removes from queue temporarily) */
+    snooze: (id: string, minutes: number) => Promise<void>;
+    /** Acknowledge the current modal */
+    dismissCurrent: () => Promise<void>;
+    /** Snooze the current modal */
+    snoozeCurrent: (minutes: number) => Promise<void>;
+    /** Get allowed snooze options for a notification */
+    getSnoozeOptions: (notification: NotifyKitNotification) => readonly number[];
+}
+/**
+ * Error thrown when an invalid snooze duration is provided.
+ */
+declare class InvalidSnoozeDurationError extends Error {
+    readonly name = "InvalidSnoozeDurationError";
+    constructor(minutes: number, allowedMinutes: readonly number[]);
+}
+/**
+ * Injection key for the NotifyKit modals composable.
+ */
+declare const NOTIFY_KIT_MODALS_KEY: InjectionKey<UseNotifyKitModalsReturn>;
+/**
+ * Provides NotifyKit modals management for injection into descendant components.
+ *
+ * @example
+ * ```typescript
+ * // In App.vue setup
+ * const modals = provideNotifyKitModals({ client })
+ *
+ * // In any child component
+ * const { currentModal, dismissCurrent } = useNotifyKitModals({ client })
+ * ```
+ */
+declare function provideNotifyKitModals(options: UseNotifyKitModalsOptions): UseNotifyKitModalsReturn;
+/**
+ * Composable for managing modal notification queue.
+ *
+ * Handles loading outstanding modals from the API, acknowledging them,
+ * and snoozing them. Uses the store for reactive queue management.
+ *
+ * @example
+ * ```typescript
+ * const {
+ *   currentModal,
+ *   hasModals,
+ *   loadOutstandingModals,
+ *   dismissCurrent,
+ *   snoozeCurrent,
+ *   getSnoozeOptions
+ * } = useNotifyKitModals({ client })
+ *
+ * // Load modals on login
+ * await loadOutstandingModals()
+ *
+ * // Handle current modal
+ * if (currentModal.value) {
+ *   const options = getSnoozeOptions(currentModal.value)
+ *   // Show modal with snooze options...
+ * }
+ *
+ * // User acknowledges
+ * await dismissCurrent()
+ *
+ * // Or user snoozes for 1 hour
+ * await snoozeCurrent(60)
+ * ```
+ */
+declare function useNotifyKitModals(options: UseNotifyKitModalsOptions): UseNotifyKitModalsReturn;
+
+export { createNotifyKitClient as A, isChannelPreferences as B, type ConnectionState as C, isMeResponse as D, isModalEnabled as E, isModalSpec as F, isNotifyKitNotification as G, isPaginationMeta as H, InvalidSnoozeDurationError as I, isUnreadCountResponse as J, isValidCategory as K, type ListNotificationsParams as L, isValidLevel as M, NotifyKitClient as N, provideNotifyKitModals as O, type PaginationParams as P, provideNotifyKitStore as Q, resetNotifyKitStore as R, useNotifyKitModals as S, useNotifyKitStore as T, type UseNotifyKitModalsOptions as U, type NotifyKitMeResponse as a, type NotifyKitListResponse as b, type NotifyKitUnreadCountResponse as c, type NotifyKitNotification as d, type NotifyKitPreferences as e, type NotifyKitPreferencesUpdate as f, type NotifyKitClientConfig as g, type NotificationCategory as h, type NotificationLevel as i, type ChannelPreferences as j, NOTIFICATION_CATEGORIES as k, NOTIFICATION_LEVELS as l, NOTIFY_KIT_MODALS_KEY as m, NOTIFY_KIT_STORE_KEY as n, NotifyKitApiError as o, type NotifyKitErrorResponse as p, type NotifyKitGroupedEntry as q, type NotifyKitGroupedListResponse as r, type NotifyKitModalSpec as s, type NotifyKitModalState as t, type NotifyKitModalsClientLike as u, type NotifyKitModalsResponse as v, type NotifyKitStoreState as w, type PaginationMeta as x, type UseNotifyKitModalsReturn as y, type UseNotifyKitStoreReturn as z };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@codingfactory/notify-kit-client",
+  "version": "0.1.0",
+  "description": "Headless Vue 3/Nuxt client for Notify Kit notifications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./nuxt": {
+      "import": "./dist/nuxt/index.js",
+      "types": "./dist/nuxt/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "generate:types": "npx tsx ../../scripts/generate-types.ts",
+    "dev": "tsup --watch",
+    "prebuild": "npm run generate:types",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "npm run typecheck && npm run lint && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "nuxt": "^3.0.0",
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "nuxt": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@nuxt/kit": "^3.0.0",
+    "@nuxt/schema": "^3.0.0",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "@vue/test-utils": "^2.4.0",
+    "eslint": "^9.0.0",
+    "happy-dom": "^15.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^2.0.0",
+    "vue": "^3.4.0"
+  },
+  "keywords": [
+    "vue",
+    "nuxt",
+    "notifications",
+    "laravel",
+    "real-time",
+    "composables"
+  ],
+  "author": "Coding Factory",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coding-factory/notify-kit.git",
+    "directory": "packages/notify-kit-client"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  }
+}