@classic-homes/notifications 0.1.35 → 0.1.36

package/README.md

@@ -93,11 +93,28 @@ import {
   notificationService,
   NotificationService,
 
+  // Utilities
+  getNotificationIconName,
+  getNotificationIconColor,
+  getPriorityBadgeVariant,
+  getTypeBadgeVariant,
+  getPriorityLabel,
+  getTypeLabel,
+  formatRelativeTime,
+  formatFullTimestamp,
+  formatNotificationTime,
+  getPrioritySortValue,
+
   // Types
   type Notification,
   type NotificationType,
   type NotificationPriority,
-  type NotificationPreferences,
+  type NotificationPreference,
+  type NotificationChannel,
+  type NotificationFrequency,
+  type NotificationFilter,
+  type NotificationCounts,
+  type BadgeVariant,
 } from '@classic-homes/notifications';
 ```
 
@@ -176,22 +193,124 @@ notificationStore.reset();
 ## Notification Types
 
 ```typescript
+type NotificationType = 'security' | 'system' | 'feature' | 'update' | 'alert' | 'info';
+type NotificationPriority = 'urgent' | 'high' | 'normal' | 'low';
+
 interface Notification {
   id: string;
-  type: 'info' | 'success' | 'warning' | 'error';
-  priority: 'low' | 'normal' | 'high' | 'urgent';
+  userId: string;
+  type: NotificationType;
+  category: string;
   title: string;
   message: string;
+  icon?: string;
+  color?: string;
+  priority: NotificationPriority;
   read: boolean;
-  readAt?: string;
+  dismissed: boolean;
   actionUrl?: string;
   actionLabel?: string;
   metadata?: Record<string, unknown>;
   createdAt: string;
-  expiresAt?: string;
+  readAt?: string;
+  dismissedAt?: string;
+}
+```
+
+## Channels and Preferences
+
+The package supports notification channels (email, sms, push, in_app) and user preferences for fine-grained control.
+
+### Getting Channels
+
+```typescript
+import { notificationService } from '@classic-homes/notifications/core';
+
+const { channels } = await notificationService.getChannels();
+// channels: [{ id, name, displayName, enabled, priority }]
+```
+
+### Managing Preferences
+
+```typescript
+import { notificationService } from '@classic-homes/notifications/core';
+
+// Get user preferences
+const { preferences } = await notificationService.getPreferences();
+
+// Update a preference
+await notificationService.updatePreference({
+  channelId: 'email',
+  notificationType: 'security',
+  enabled: true,
+  frequency: 'immediate',
+  minPriority: 'normal',
+});
+
+// Batch update preferences
+await notificationService.batchUpdatePreferences([
+  { eventType: 'security', channels: ['email', 'push'], enabled: true },
+  { eventType: 'feature', channels: ['in_app'], enabled: true },
+]);
+```
+
+### Preference Types
+
+```typescript
+type ChannelType = 'email' | 'sms' | 'push' | 'in_app';
+type NotificationFrequency = 'immediate' | 'digest_hourly' | 'digest_daily' | 'digest_weekly';
+
+interface NotificationPreference {
+  id: string;
+  userId: string;
+  channelId: string;
+  notificationType: NotificationType;
+  notificationCategory?: string;
+  enabled: boolean;
+  frequency: NotificationFrequency;
+  quietHoursStart?: string;
+  quietHoursEnd?: string;
+  quietHoursTimezone?: string;
+  minPriority: NotificationPriority;
+  tags?: string[];
+  createdAt: string;
+  updatedAt?: string;
 }
 ```
 
+## Utility Functions
+
+Display helpers for consistent notification rendering:
+
+```typescript
+import {
+  getNotificationIconName,
+  getNotificationIconColor,
+  getPriorityBadgeVariant,
+  getTypeBadgeVariant,
+  getPriorityLabel,
+  getTypeLabel,
+  formatRelativeTime,
+  formatNotificationTime,
+} from '@classic-homes/notifications/core';
+
+// Get icon for notification type
+getNotificationIconName('security'); // 'shield'
+getNotificationIconColor('security'); // 'text-red-500'
+
+// Get badge variants
+getPriorityBadgeVariant('urgent'); // 'destructive'
+getTypeBadgeVariant('update'); // 'success'
+
+// Get display labels
+getPriorityLabel('high'); // 'High'
+getTypeLabel('feature'); // 'Feature'
+
+// Format timestamps
+formatRelativeTime('2024-01-22T10:00:00Z'); // '2h ago'
+formatNotificationTime('2024-01-15T10:00:00Z'); // 'Jan 15'
+```
+
 ## Using with Toast Notifications
 
 For client-side only toast notifications (not persisted), use `toastStore` from `@classic-homes/theme-svelte`:
@@ -272,6 +391,39 @@ interface NotificationState {
 </DropdownMenu>
 ```
 
+## Direct API Access
+
+For direct API access without the Svelte store:
+
+```typescript
+import { notificationsApi } from '@classic-homes/notifications/core';
+
+// List notifications
+const response = await notificationsApi.list({ page: 1, limit: 20 });
+
+// Get single notification
+const notification = await notificationsApi.get('notification-id');
+
+// Mark as read
+await notificationsApi.markRead('notification-id');
+await notificationsApi.markManyRead(['id1', 'id2']);
+await notificationsApi.markAllRead();
+
+// Delete notifications
+await notificationsApi.dismiss('notification-id');
+await notificationsApi.bulkDelete(['id1', 'id2']);
+await notificationsApi.deleteAll();
+
+// Channels and preferences
+const channels = await notificationsApi.getChannels();
+const preferences = await notificationsApi.getPreferences();
+await notificationsApi.updatePreference(preferenceData);
+await notificationsApi.deletePreference('subscription-id');
+
+// Test notifications (dev/admin only)
+await notificationsApi.generateTestNotifications({ type: 'info' });
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/notifications",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "Notification services and Svelte bindings for Classic Theme apps",
   "type": "module",
   "main": "dist/index.js",