@classic-homes/notifications 0.1.0

package/README.md

@@ -0,0 +1,277 @@
+# @classic-homes/notifications
+
+Framework-agnostic notifications core with Svelte bindings for the Classic Theme design system.
+
+## Features
+
+- Persistent notifications from API with pagination
+- Mark as read/unread functionality
+- Batch operations (mark all read, delete all)
+- Svelte reactive stores for notification state
+- Derived stores for unread count and loading state
+- TypeScript-first with full type safety
+- Integrates with `@classic-homes/auth` for API authentication
+
+## Installation
+
+```bash
+npm install @classic-homes/notifications
+```
+
+## Prerequisites
+
+This package requires `@classic-homes/auth` to be initialized first, as it uses the shared HTTP client and authentication headers.
+
+```typescript
+import { initAuth } from '@classic-homes/auth';
+
+initAuth({
+  baseUrl: 'https://api.example.com',
+  // ... other config
+});
+```
+
+## Quick Start
+
+### 1. Fetch Notifications
+
+```typescript
+import { notificationStore } from '@classic-homes/notifications/svelte';
+
+// Fetch initial notifications
+await notificationStore.fetch();
+
+// With pagination
+await notificationStore.fetch({ page: 1, limit: 20 });
+
+// Filter by type or read status
+await notificationStore.fetch({ type: 'info', unreadOnly: true });
+```
+
+### 2. Use in Svelte Components
+
+```svelte
+<script lang="ts">
+  import {
+    notificationStore,
+    notifications,
+    unreadCount,
+    isLoadingNotifications,
+  } from '@classic-homes/notifications/svelte';
+
+  // Load notifications on mount
+  $effect(() => {
+    notificationStore.fetch();
+  });
+</script>
+
+{#if $isLoadingNotifications}
+  <Spinner />
+{:else}
+  <p>You have {$unreadCount} unread notifications</p>
+
+  {#each $notifications as notification}
+    <div class:unread={!notification.read}>
+      <h4>{notification.title}</h4>
+      <p>{notification.message}</p>
+      <button onclick={() => notificationStore.markRead(notification.id)}> Mark as read </button>
+    </div>
+  {/each}
+{/if}
+```
+
+## API Reference
+
+### Core Exports
+
+```typescript
+import {
+  // API
+  notificationsApi,
+
+  // Service
+  notificationService,
+  NotificationService,
+
+  // Types
+  type Notification,
+  type NotificationType,
+  type NotificationPriority,
+  type NotificationPreferences,
+} from '@classic-homes/notifications';
+```
+
+### Svelte Exports
+
+```typescript
+import {
+  // Main store
+  notificationStore,
+
+  // Derived stores
+  notifications, // Notification[]
+  unreadCount, // number
+  isLoadingNotifications, // boolean
+
+  // Types
+  type Notification,
+  type NotificationType,
+  type NotificationPriority,
+} from '@classic-homes/notifications/svelte';
+```
+
+## Notification Store Methods
+
+### Fetching
+
+```typescript
+// Fetch notifications with optional filters
+await notificationStore.fetch({
+  page?: number,
+  limit?: number,
+  type?: NotificationType,
+  unreadOnly?: boolean,
+});
+
+// Refresh current page
+await notificationStore.refresh();
+
+// Load more (next page)
+await notificationStore.loadMore();
+```
+
+### Marking as Read
+
+```typescript
+// Mark single notification as read
+await notificationStore.markRead(notificationId);
+
+// Mark multiple notifications as read
+await notificationStore.markManyRead([id1, id2, id3]);
+
+// Mark all notifications as read
+await notificationStore.markAllRead();
+```
+
+### Deleting
+
+```typescript
+// Dismiss single notification
+await notificationStore.dismiss(notificationId);
+
+// Delete all notifications
+await notificationStore.deleteAll();
+```
+
+### State Management
+
+```typescript
+// Clear error state
+notificationStore.clearError();
+
+// Reset store to initial state
+notificationStore.reset();
+```
+
+## Notification Types
+
+```typescript
+interface Notification {
+  id: string;
+  type: 'info' | 'success' | 'warning' | 'error';
+  priority: 'low' | 'normal' | 'high' | 'urgent';
+  title: string;
+  message: string;
+  read: boolean;
+  readAt?: string;
+  actionUrl?: string;
+  actionLabel?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  expiresAt?: string;
+}
+```
+
+## Using with Toast Notifications
+
+For client-side only toast notifications (not persisted), use `toastStore` from `@classic-homes/theme-svelte`:
+
+```svelte
+<script lang="ts">
+  import { toastStore } from '@classic-homes/theme-svelte';
+
+  function showSuccess() {
+    toastStore.success('Operation completed!');
+  }
+
+  function showError() {
+    toastStore.error('Something went wrong');
+  }
+</script>
+```
+
+## Store State
+
+```typescript
+interface NotificationState {
+  notifications: Notification[];
+  unreadCount: number;
+  isLoading: boolean;
+  error: string | null;
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+```
+
+## Example: Notification Bell
+
+```svelte
+<script lang="ts">
+  import {
+    notificationStore,
+    notifications,
+    unreadCount,
+  } from '@classic-homes/notifications/svelte';
+  import { Badge, Button, DropdownMenu } from '@classic-homes/theme-svelte';
+
+  let isOpen = $state(false);
+
+  $effect(() => {
+    if (isOpen) {
+      notificationStore.fetch({ limit: 5 });
+    }
+  });
+</script>
+
+<DropdownMenu bind:open={isOpen}>
+  <Button slot="trigger" variant="ghost">
+    <BellIcon />
+    {#if $unreadCount > 0}
+      <Badge variant="destructive">{$unreadCount}</Badge>
+    {/if}
+  </Button>
+
+  <div slot="content">
+    {#each $notifications as notification}
+      <div class="notification-item">
+        <span>{notification.title}</span>
+        {#if !notification.read}
+          <button onclick={() => notificationStore.markRead(notification.id)}> Mark read </button>
+        {/if}
+      </div>
+    {/each}
+
+    {#if $unreadCount > 0}
+      <button onclick={() => notificationStore.markAllRead()}> Mark all as read </button>
+    {/if}
+  </div>
+</DropdownMenu>
+```
+
+## License
+
+MIT

package/dist/core/index.d.ts

@@ -0,0 +1,163 @@
+import { d as NotificationListParams, c as NotificationsListResponse, b as Notification, k as ChannelsResponse, N as NotificationType, P as PreferencesResponse, U as UpdatePreferenceData, l as UpdatePreferenceResponse, B as BatchPreferenceUpdate, j as BulkPreferenceResponse, D as DeletePreferenceResponse, T as TestNotificationParams, m as TestNotificationResponse, e as NotificationChannel, g as NotificationPreference } from '../types-BSztr7EQ.js';
+export { C as ChannelType, i as NotificationError, f as NotificationFrequency, h as NotificationPreferenceResult, a as NotificationPriority } from '../types-BSztr7EQ.js';
+
+/**
+ * Notifications API
+ *
+ * API client methods for notification endpoints.
+ * Uses the auth package's HTTP client for making requests.
+ */
+
+declare const notificationsApi: {
+    /**
+     * List notifications with optional filters.
+     */
+    list(params?: NotificationListParams, customFetch?: typeof fetch): Promise<NotificationsListResponse>;
+    /**
+     * Get a single notification by ID.
+     */
+    get(id: string, customFetch?: typeof fetch): Promise<Notification>;
+    /**
+     * Mark a notification as read.
+     */
+    markRead(id: string): Promise<void>;
+    /**
+     * Mark multiple notifications as read.
+     */
+    markManyRead(ids: string[]): Promise<void>;
+    /**
+     * Mark all notifications as read.
+     */
+    markAllRead(): Promise<void>;
+    /**
+     * Dismiss (delete) a notification.
+     */
+    dismiss(id: string): Promise<void>;
+    /**
+     * Delete multiple notifications in bulk.
+     */
+    bulkDelete(ids: string[]): Promise<void>;
+    /**
+     * Delete all notifications.
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * Get available notification channels.
+     */
+    getChannels(customFetch?: typeof fetch): Promise<ChannelsResponse>;
+    /**
+     * Get notification preferences.
+     */
+    getPreferences(params?: {
+        channelId?: string;
+        notificationType?: NotificationType;
+    }, customFetch?: typeof fetch): Promise<PreferencesResponse>;
+    /**
+     * Update a notification preference.
+     */
+    updatePreference(preference: UpdatePreferenceData): Promise<UpdatePreferenceResponse>;
+    /**
+     * Batch update notification preferences.
+     */
+    batchUpdatePreferences(preferences: BatchPreferenceUpdate[]): Promise<BulkPreferenceResponse>;
+    /**
+     * Delete a notification preference.
+     */
+    deletePreference(subscriptionId: string): Promise<DeletePreferenceResponse>;
+    /**
+     * Generate test notifications.
+     */
+    generateTestNotifications(params?: TestNotificationParams): Promise<TestNotificationResponse>;
+};
+
+/**
+ * Notification Service
+ *
+ * Business logic layer for notification operations.
+ * Wraps notificationsApi calls and provides a clean interface for components.
+ */
+
+/**
+ * NotificationService
+ *
+ * Provides a clean interface for notification operations.
+ * Can be instantiated for testing or used via the singleton export.
+ */
+declare class NotificationService {
+    /**
+     * List notifications with optional filters.
+     */
+    list(params?: NotificationListParams, customFetch?: typeof fetch): Promise<NotificationsListResponse>;
+    /**
+     * Get a single notification by ID.
+     */
+    get(id: string, customFetch?: typeof fetch): Promise<Notification>;
+    /**
+     * Mark a notification as read.
+     */
+    markRead(id: string): Promise<void>;
+    /**
+     * Mark multiple notifications as read.
+     */
+    markManyRead(ids: string[]): Promise<void>;
+    /**
+     * Mark all notifications as read.
+     */
+    markAllRead(): Promise<void>;
+    /**
+     * Dismiss (delete) a notification.
+     */
+    dismiss(id: string): Promise<void>;
+    /**
+     * Delete multiple notifications in bulk.
+     */
+    bulkDelete(ids: string[]): Promise<void>;
+    /**
+     * Delete all notifications.
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * Get available notification channels.
+     */
+    getChannels(customFetch?: typeof fetch): Promise<{
+        success: boolean;
+        channels: NotificationChannel[];
+    }>;
+    /**
+     * Get notification preferences.
+     */
+    getPreferences(params?: {
+        channelId?: string;
+        notificationType?: NotificationType;
+    }, customFetch?: typeof fetch): Promise<{
+        success: boolean;
+        preferences: NotificationPreference[];
+    }>;
+    /**
+     * Update a notification preference.
+     */
+    updatePreference(preference: UpdatePreferenceData): Promise<{
+        success: boolean;
+        message: string;
+        subscriptionId: string;
+    }>;
+    /**
+     * Batch update notification preferences.
+     */
+    batchUpdatePreferences(preferences: BatchPreferenceUpdate[]): Promise<BulkPreferenceResponse>;
+    /**
+     * Delete a notification preference.
+     */
+    deletePreference(subscriptionId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Generate test notifications (dev/admin only).
+     */
+    generateTestNotifications(params?: TestNotificationParams): Promise<TestNotificationResponse>;
+}
+/** Singleton instance of NotificationService */
+declare const notificationService: NotificationService;
+
+export { BatchPreferenceUpdate, BulkPreferenceResponse, ChannelsResponse, DeletePreferenceResponse, Notification, NotificationChannel, NotificationListParams, NotificationPreference, NotificationService, NotificationType, NotificationsListResponse, PreferencesResponse, TestNotificationParams, TestNotificationResponse, UpdatePreferenceData, UpdatePreferenceResponse, notificationService, notificationsApi };

package/dist/core/index.js

@@ -0,0 +1,258 @@
+import { api } from '@classic-homes/auth/core';
+
+// src/core/api.ts
+var notificationsApi = {
+  // ============================================================================
+  // Notifications CRUD
+  // ============================================================================
+  /**
+   * List notifications with optional filters.
+   */
+  async list(params, customFetch) {
+    const queryParams = new URLSearchParams();
+    const page = params?.page || 1;
+    const limit = params?.limit || 20;
+    const offset = (page - 1) * limit;
+    queryParams.append("limit", limit.toString());
+    queryParams.append("offset", offset.toString());
+    if (params?.unreadOnly) {
+      queryParams.append("read", "false");
+    } else if (params?.readOnly) {
+      queryParams.append("read", "true");
+    }
+    if (params?.type) {
+      queryParams.append("type", params.type);
+    }
+    const response = await api.get(
+      `/notifications?${queryParams.toString()}`,
+      true,
+      customFetch
+    );
+    return response;
+  },
+  /**
+   * Get a single notification by ID.
+   */
+  async get(id, customFetch) {
+    const response = await api.get(
+      `/notifications/${id}`,
+      true,
+      customFetch
+    );
+    return response.notification;
+  },
+  /**
+   * Mark a notification as read.
+   */
+  async markRead(id) {
+    await api.patch(`/notifications/${id}/read`, {}, true);
+  },
+  /**
+   * Mark multiple notifications as read.
+   */
+  async markManyRead(ids) {
+    await api.post("/notifications/mark-read", { ids }, true);
+  },
+  /**
+   * Mark all notifications as read.
+   */
+  async markAllRead() {
+    await api.post("/notifications/mark-read", { all: true }, true);
+  },
+  /**
+   * Dismiss (delete) a notification.
+   */
+  async dismiss(id) {
+    await api.delete(`/notifications/${id}`, true);
+  },
+  /**
+   * Delete multiple notifications in bulk.
+   */
+  async bulkDelete(ids) {
+    await api.post("/notifications/bulk-delete", { ids }, true);
+  },
+  /**
+   * Delete all notifications.
+   */
+  async deleteAll() {
+    await api.post("/notifications/bulk-delete", { all: true }, true);
+  },
+  // ============================================================================
+  // Notification Channels
+  // ============================================================================
+  /**
+   * Get available notification channels.
+   */
+  async getChannels(customFetch) {
+    const response = await api.get("/notifications/channels", true, customFetch);
+    return response;
+  },
+  // ============================================================================
+  // Notification Preferences
+  // ============================================================================
+  /**
+   * Get notification preferences.
+   */
+  async getPreferences(params, customFetch) {
+    const queryParams = new URLSearchParams();
+    if (params?.channelId) queryParams.append("channelId", params.channelId);
+    if (params?.notificationType) queryParams.append("notificationType", params.notificationType);
+    const response = await api.get(
+      `/notifications/preferences?${queryParams.toString()}`,
+      true,
+      customFetch
+    );
+    return response;
+  },
+  /**
+   * Update a notification preference.
+   */
+  async updatePreference(preference) {
+    const response = await api.put(
+      "/notifications/preferences",
+      preference,
+      true
+    );
+    return response;
+  },
+  /**
+   * Batch update notification preferences.
+   */
+  async batchUpdatePreferences(preferences) {
+    const response = await api.post(
+      "/notifications/preferences/batch",
+      { preferences },
+      true
+    );
+    const data = response;
+    return data.data || data;
+  },
+  /**
+   * Delete a notification preference.
+   */
+  async deletePreference(subscriptionId) {
+    const response = await api.delete(
+      `/notifications/preferences/${subscriptionId}`,
+      true
+    );
+    return response;
+  },
+  // ============================================================================
+  // Test Notifications (Dev/Admin)
+  // ============================================================================
+  /**
+   * Generate test notifications.
+   */
+  async generateTestNotifications(params) {
+    const response = await api.post(
+      "/notifications/test",
+      params || {},
+      true
+    );
+    const data = response;
+    return data.data ?? data;
+  }
+};
+
+// src/core/service.ts
+var NotificationService = class {
+  // ============================================================================
+  // Notifications CRUD
+  // ============================================================================
+  /**
+   * List notifications with optional filters.
+   */
+  async list(params, customFetch) {
+    return await notificationsApi.list(params, customFetch);
+  }
+  /**
+   * Get a single notification by ID.
+   */
+  async get(id, customFetch) {
+    return await notificationsApi.get(id, customFetch);
+  }
+  /**
+   * Mark a notification as read.
+   */
+  async markRead(id) {
+    await notificationsApi.markRead(id);
+  }
+  /**
+   * Mark multiple notifications as read.
+   */
+  async markManyRead(ids) {
+    await notificationsApi.markManyRead(ids);
+  }
+  /**
+   * Mark all notifications as read.
+   */
+  async markAllRead() {
+    await notificationsApi.markAllRead();
+  }
+  /**
+   * Dismiss (delete) a notification.
+   */
+  async dismiss(id) {
+    await notificationsApi.dismiss(id);
+  }
+  /**
+   * Delete multiple notifications in bulk.
+   */
+  async bulkDelete(ids) {
+    await notificationsApi.bulkDelete(ids);
+  }
+  /**
+   * Delete all notifications.
+   */
+  async deleteAll() {
+    await notificationsApi.deleteAll();
+  }
+  // ============================================================================
+  // Notification Channels
+  // ============================================================================
+  /**
+   * Get available notification channels.
+   */
+  async getChannels(customFetch) {
+    return await notificationsApi.getChannels(customFetch);
+  }
+  // ============================================================================
+  // Notification Preferences
+  // ============================================================================
+  /**
+   * Get notification preferences.
+   */
+  async getPreferences(params, customFetch) {
+    return await notificationsApi.getPreferences(params, customFetch);
+  }
+  /**
+   * Update a notification preference.
+   */
+  async updatePreference(preference) {
+    return await notificationsApi.updatePreference(preference);
+  }
+  /**
+   * Batch update notification preferences.
+   */
+  async batchUpdatePreferences(preferences) {
+    return await notificationsApi.batchUpdatePreferences(preferences);
+  }
+  /**
+   * Delete a notification preference.
+   */
+  async deletePreference(subscriptionId) {
+    return await notificationsApi.deletePreference(subscriptionId);
+  }
+  // ============================================================================
+  // Test Notifications
+  // ============================================================================
+  /**
+   * Generate test notifications (dev/admin only).
+   */
+  async generateTestNotifications(params) {
+    return await notificationsApi.generateTestNotifications(params);
+  }
+};
+var notificationService = new NotificationService();
+
+export { NotificationService, notificationService, notificationsApi };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { NotificationService, notificationService, notificationsApi } from './core/index.js';
+export { B as BatchPreferenceUpdate, j as BulkPreferenceResponse, C as ChannelType, k as ChannelsResponse, D as DeletePreferenceResponse, b as Notification, e as NotificationChannel, i as NotificationError, f as NotificationFrequency, d as NotificationListParams, g as NotificationPreference, h as NotificationPreferenceResult, a as NotificationPriority, N as NotificationType, c as NotificationsListResponse, P as PreferencesResponse, T as TestNotificationParams, m as TestNotificationResponse, U as UpdatePreferenceData, l as UpdatePreferenceResponse } from './types-BSztr7EQ.js';
+export { isLoadingNotifications, notificationStore, notifications, unreadCount } from './svelte/index.js';