@hamak/notification-api 0.4.0

package/dist/api/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * API interfaces for notification service
+ */
+export type { INotificationService, NotificationListener, } from './notification-service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,4 @@
+/**
+ * API interfaces for notification service
+ */
+export {};

package/dist/api/notification-service.d.ts

@@ -0,0 +1,150 @@
+import type { INotification, NotificationOptions } from '../types/notification.js';
+/**
+ * Listener function for notification changes
+ */
+export type NotificationListener = (notifications: INotification[]) => void;
+/**
+ * Service interface for managing notifications
+ *
+ * This service provides methods to create, dismiss, and observe notifications.
+ * All notifications are pure data structures (fully serializable).
+ */
+export interface INotificationService {
+    /**
+     * Create a notification with full control over all properties
+     *
+     * @param notification - Notification data (id and timestamp will be auto-generated)
+     * @returns The generated notification ID
+     *
+     * @example
+     * ```typescript
+     * const id = notificationService.notify({
+     *   type: 'success',
+     *   title: 'Upload Complete',
+     *   message: 'File uploaded successfully',
+     *   duration: 5000,
+     *   source: 'file-upload',
+     *   metadata: { filePath: '/uploads/document.pdf' }
+     * });
+     * ```
+     */
+    notify(notification: Omit<INotification, 'id' | 'timestamp'>): string;
+    /**
+     * Create an informational notification
+     *
+     * @param message - The notification message
+     * @param title - Optional title (defaults to 'Info')
+     * @param options - Optional notification options
+     * @returns The generated notification ID
+     *
+     * @example
+     * ```typescript
+     * notificationService.info('Processing started', 'Background Task', {
+     *   duration: 3000,
+     *   source: 'task-processor'
+     * });
+     * ```
+     */
+    info(message: string, title?: string, options?: NotificationOptions): string;
+    /**
+     * Create a success notification
+     *
+     * @param message - The notification message
+     * @param title - Optional title (defaults to 'Success')
+     * @param options - Optional notification options
+     * @returns The generated notification ID
+     *
+     * @example
+     * ```typescript
+     * notificationService.success('Data saved successfully');
+     * ```
+     */
+    success(message: string, title?: string, options?: NotificationOptions): string;
+    /**
+     * Create a warning notification
+     *
+     * @param message - The notification message
+     * @param title - Optional title (defaults to 'Warning')
+     * @param options - Optional notification options
+     * @returns The generated notification ID
+     *
+     * @example
+     * ```typescript
+     * notificationService.warning('Disk space is running low', 'System Warning', {
+     *   source: 'system-monitor',
+     *   metadata: { diskSpace: 512000 }
+     * });
+     * ```
+     */
+    warning(message: string, title?: string, options?: NotificationOptions): string;
+    /**
+     * Create an error notification
+     *
+     * @param message - The notification message
+     * @param title - Optional title (defaults to 'Error')
+     * @param options - Optional notification options
+     * @returns The generated notification ID
+     *
+     * @example
+     * ```typescript
+     * notificationService.error('Failed to save data', 'Save Error', {
+     *   duration: 0, // No auto-dismiss for errors
+     *   source: 'data-service',
+     *   metadata: { errorCode: 'ERR_NETWORK' }
+     * });
+     * ```
+     */
+    error(message: string, title?: string, options?: NotificationOptions): string;
+    /**
+     * Dismiss a specific notification by ID
+     *
+     * @param id - The notification ID to dismiss
+     *
+     * @example
+     * ```typescript
+     * const id = notificationService.info('Processing...');
+     * // Later...
+     * notificationService.dismiss(id);
+     * ```
+     */
+    dismiss(id: string): void;
+    /**
+     * Dismiss all notifications
+     *
+     * @example
+     * ```typescript
+     * notificationService.dismissAll();
+     * ```
+     */
+    dismissAll(): void;
+    /**
+     * Get all current notifications
+     *
+     * @returns Array of all active notifications
+     *
+     * @example
+     * ```typescript
+     * const notifications = notificationService.getAll();
+     * console.log(`You have ${notifications.length} notifications`);
+     * ```
+     */
+    getAll(): INotification[];
+    /**
+     * Subscribe to notification changes
+     *
+     * @param listener - Callback function that receives updated notification list
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = notificationService.subscribe((notifications) => {
+     *   console.log('Notifications updated:', notifications);
+     * });
+     *
+     * // Later...
+     * unsubscribe();
+     * ```
+     */
+    subscribe(listener: NotificationListener): () => void;
+}
+//# sourceMappingURL=notification-service.d.ts.map

package/dist/api/notification-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-service.d.ts","sourceRoot":"","sources":["../../src/api/notification-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEnF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,MAAM,CAAC;IAEtE;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAE7E;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAEhF;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAEhF;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAE9E;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;;;;;OAOG;IACH,UAAU,IAAI,IAAI,CAAC;IAEnB;;;;;;;;;;OAUG;IACH,MAAM,IAAI,aAAa,EAAE,CAAC;IAE1B;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAC;CACvD"}

package/dist/api/notification-service.js

@@ -0,0 +1 @@
+export {};

package/dist/es2015/api/index.js

@@ -0,0 +1,4 @@
+/**
+ * API interfaces for notification service
+ */
+export {};

package/dist/es2015/api/notification-service.js

@@ -0,0 +1 @@
+export {};

package/dist/es2015/index.js

@@ -0,0 +1,15 @@
+/**
+ * @hamak/notification-api
+ *
+ * Public API for the pluggable notification system.
+ * Provides pure interfaces, types, and service tokens for notifications.
+ * All data structures are fully serializable for Redux/storage/network.
+ *
+ * @packageDocumentation
+ */
+// Export all API interfaces
+export * from './api/index.js';
+// Export all types
+export * from './types/index.js';
+// Export service tokens
+export * from './tokens/index.js';

package/dist/es2015/tokens/index.js

@@ -0,0 +1,4 @@
+/**
+ * Service tokens for notification system
+ */
+export { NOTIFICATION_SERVICE_TOKEN, } from './service-tokens.js';

package/dist/es2015/tokens/service-tokens.js

@@ -0,0 +1,17 @@
+/**
+ * Dependency Injection tokens for notification services
+ */
+/**
+ * Token for injecting the NotificationService
+ *
+ * @example
+ * ```typescript
+ * export const myPlugin: PluginModule = {
+ *   initialize(ctx) {
+ *     const notificationService = ctx.resolve(NOTIFICATION_SERVICE_TOKEN);
+ *     notificationService.success('Plugin initialized');
+ *   }
+ * };
+ * ```
+ */
+export const NOTIFICATION_SERVICE_TOKEN = Symbol.for('@hamak/notification:NotificationService');

package/dist/es2015/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for notifications
+ */
+export {};

package/dist/es2015/types/notification.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @hamak/notification-api
+ *
+ * Public API for the pluggable notification system.
+ * Provides pure interfaces, types, and service tokens for notifications.
+ * All data structures are fully serializable for Redux/storage/network.
+ *
+ * @packageDocumentation
+ */
+export * from './api/index.js';
+export * from './types/index.js';
+export * from './tokens/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @hamak/notification-api
+ *
+ * Public API for the pluggable notification system.
+ * Provides pure interfaces, types, and service tokens for notifications.
+ * All data structures are fully serializable for Redux/storage/network.
+ *
+ * @packageDocumentation
+ */
+// Export all API interfaces
+export * from './api/index.js';
+// Export all types
+export * from './types/index.js';
+// Export service tokens
+export * from './tokens/index.js';

package/dist/tokens/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Service tokens for notification system
+ */
+export { NOTIFICATION_SERVICE_TOKEN, type NotificationServiceToken, } from './service-tokens.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tokens/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,0BAA0B,EAC1B,KAAK,wBAAwB,GAC9B,MAAM,qBAAqB,CAAC"}

package/dist/tokens/index.js

@@ -0,0 +1,4 @@
+/**
+ * Service tokens for notification system
+ */
+export { NOTIFICATION_SERVICE_TOKEN, } from './service-tokens.js';

package/dist/tokens/service-tokens.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Dependency Injection tokens for notification services
+ */
+/**
+ * Token for injecting the NotificationService
+ *
+ * @example
+ * ```typescript
+ * export const myPlugin: PluginModule = {
+ *   initialize(ctx) {
+ *     const notificationService = ctx.resolve(NOTIFICATION_SERVICE_TOKEN);
+ *     notificationService.success('Plugin initialized');
+ *   }
+ * };
+ * ```
+ */
+export declare const NOTIFICATION_SERVICE_TOKEN: unique symbol;
+/**
+ * Type helper for NOTIFICATION_SERVICE_TOKEN
+ */
+export type NotificationServiceToken = typeof NOTIFICATION_SERVICE_TOKEN;
+//# sourceMappingURL=service-tokens.d.ts.map

package/dist/tokens/service-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-tokens.d.ts","sourceRoot":"","sources":["../../src/tokens/service-tokens.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,eAAwD,CAAC;AAEhG;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,0BAA0B,CAAC"}

package/dist/tokens/service-tokens.js

@@ -0,0 +1,17 @@
+/**
+ * Dependency Injection tokens for notification services
+ */
+/**
+ * Token for injecting the NotificationService
+ *
+ * @example
+ * ```typescript
+ * export const myPlugin: PluginModule = {
+ *   initialize(ctx) {
+ *     const notificationService = ctx.resolve(NOTIFICATION_SERVICE_TOKEN);
+ *     notificationService.success('Plugin initialized');
+ *   }
+ * };
+ * ```
+ */
+export const NOTIFICATION_SERVICE_TOKEN = Symbol.for('@hamak/notification:NotificationService');

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for notifications
+ */
+export type { INotification, NotificationType, NotificationOptions, } from './notification.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for notifications
+ */
+export {};

package/dist/types/notification.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure data structure representing a notification message.
+ * This interface is fully serializable and can be stored in Redux,
+ * persisted to storage, or transmitted over the network.
+ */
+export interface INotification {
+    /**
+     * Unique identifier for the notification
+     */
+    id: string;
+    /**
+     * Type/severity of the notification
+     */
+    type: 'info' | 'success' | 'warning' | 'error';
+    /**
+     * Title/heading of the notification
+     */
+    title: string;
+    /**
+     * Main notification message
+     */
+    message: string;
+    /**
+     * Unix timestamp (milliseconds) when notification was created
+     */
+    timestamp: number;
+    /**
+     * Optional auto-dismiss duration in milliseconds
+     * If not set, notification will persist until manually dismissed
+     */
+    duration?: number;
+    /**
+     * Optional source identifier (e.g., 'file-upload', 'auth-session')
+     * Used by UI layer to determine appropriate actions
+     */
+    source?: string;
+    /**
+     * Optional serializable metadata for additional context
+     * Must be JSON-serializable (no functions, Dates should be timestamps, etc.)
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Type for notification severity levels
+ */
+export type NotificationType = INotification['type'];
+/**
+ * Options for creating a notification (excludes id and timestamp)
+ */
+export interface NotificationOptions {
+    /**
+     * Auto-dismiss duration in milliseconds
+     */
+    duration?: number;
+    /**
+     * Source identifier
+     */
+    source?: string;
+    /**
+     * Additional serializable metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=notification.d.ts.map

package/dist/types/notification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.d.ts","sourceRoot":"","sources":["../../src/types/notification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IAE/C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC"}

package/dist/types/notification.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hamak/notification-api",
+  "version": "0.4.0",
+  "description": "Notification API - Pure interfaces and types for pluggable notification system",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js",
+      "legacy": "./dist/es2015/index.js"
+    },
+    "./es2015": {
+      "import": "./dist/es2015/index.js",
+      "default": "./dist/es2015/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amah/app-framework.git",
+    "directory": "packages/notification/notification-api"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json && tsc -p tsconfig.es2015.json",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "notification",
+    "api",
+    "interfaces",
+    "microkernel"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}