@theshelf/notification 0.0.1

package/README.md

@@ -0,0 +1,68 @@
+
+# Notification | The Shelf
+
+The notification package provides a universal interaction layer with an actual notification solution.
+
+This package is based on a push notification model.
+
+## Installation
+
+```bash
+npm install @theshelf/notification
+```
+
+## Implementations
+
+Currently, there are two implementations:
+
+* **Memory** - non-persistent in memory notifications (suited for testing).
+* **WebPush** - web browser based push notifications.
+
+## Configuration
+
+The used implementation needs to be configured in the `.env` file with the debug enabled setting.
+
+```env
+NOTIFICATION_IMPLEMENTATION="webpush" # (memory | webpush)
+```
+
+In case of WebPush, additional configuration is required.
+
+```env
+WEBPUSH_VAPID_SUBJECT="..."
+WEBPUSH_VAPID_PUBLIC_KEY="..."
+WEBPUSH_VAPID_PRIVATE_KEY="..."
+```
+
+## How to use
+
+An instance of the configured notification service implementation can be imported for performing notification operations.
+
+```ts
+import notificationService from '@theshelf/notification';
+
+// Perform operations with the notificationService instance
+```
+
+### Operations
+
+```ts
+import notificationService from '@theshelf/notification';
+
+// Open connection
+await notificationService.connect();
+
+// Close connection
+await notificationService.disconnect();
+
+// Subscribe to receive notifications
+await notificationService.subscribe(recipientId);
+
+// Unsubscribe from receiving notifications
+// Throws SubscriptionNotFound if subscription not found.
+await notificationService.unsubscribe(recipientId);
+
+// Send a notification to a recipient
+// Throws SubscriptionNotFound if subscription not found.
+await notificationService.sendNotification(recipientId, title, body);
+```

package/dist/definitions/interfaces.d.ts

@@ -0,0 +1,9 @@
+export interface NotificationService {
+    get connected(): boolean;
+    get subscriptions(): Map<string, unknown>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribe(recipientId: string, subscription: unknown): Promise<void>;
+    unsubscribe(recipientId: string): Promise<void>;
+    sendNotification(recipientId: string, title: string, message: string): Promise<void>;
+}

package/dist/definitions/interfaces.js

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

package/dist/errors/NotConnected.d.ts

@@ -0,0 +1,4 @@
+import NotificationError from './NotificationError';
+export default class NotConnected extends NotificationError {
+    constructor(message?: string);
+}

package/dist/errors/NotConnected.js

@@ -0,0 +1,6 @@
+import NotificationError from './NotificationError';
+export default class NotConnected extends NotificationError {
+    constructor(message) {
+        super(message ?? 'Notification service not connected');
+    }
+}

package/dist/errors/NotificationError.d.ts

@@ -0,0 +1,2 @@
+export default class NotificationError extends Error {
+}

package/dist/errors/NotificationError.js

@@ -0,0 +1,2 @@
+export default class NotificationError extends Error {
+}

package/dist/errors/SubscriptionNotFound.d.ts

@@ -0,0 +1,4 @@
+import NotificationError from './NotificationError';
+export default class SubscriptionNotFound extends NotificationError {
+    constructor(recipientId?: string);
+}

package/dist/errors/SubscriptionNotFound.js

@@ -0,0 +1,6 @@
+import NotificationError from './NotificationError';
+export default class SubscriptionNotFound extends NotificationError {
+    constructor(recipientId) {
+        super(recipientId ? `Subscription not found for: ${recipientId}` : 'Subscription not found');
+    }
+}

package/dist/errors/UnknownImplementation.d.ts

@@ -0,0 +1,4 @@
+import NotificationError from './NotificationError';
+export default class UnknownImplementation extends NotificationError {
+    constructor(name: string);
+}

package/dist/errors/UnknownImplementation.js

@@ -0,0 +1,6 @@
+import NotificationError from './NotificationError';
+export default class UnknownImplementation extends NotificationError {
+    constructor(name) {
+        super(`Unknown notification implementation: ${name}`);
+    }
+}

package/dist/implementation.d.ts

@@ -0,0 +1,3 @@
+import type { NotificationService } from './definitions/interfaces';
+declare const _default: NotificationService;
+export default _default;

package/dist/implementation.js

@@ -0,0 +1,14 @@
+import UnknownImplementation from './errors/UnknownImplementation';
+import createMemory from './implementations/memory/create';
+import createWebPush from './implementations/webpush/create';
+const implementations = new Map([
+    ['memory', createMemory],
+    ['webpush', createWebPush],
+]);
+const DEFAULT_NOTIFICATION_IMPLEMENTATION = 'memory';
+const implementationName = process.env.NOTIFICATION_IMPLEMENTATION ?? DEFAULT_NOTIFICATION_IMPLEMENTATION;
+const creator = implementations.get(implementationName.toLowerCase());
+if (creator === undefined) {
+    throw new UnknownImplementation(implementationName);
+}
+export default creator();

package/dist/implementations/memory/Memory.d.ts

@@ -0,0 +1,16 @@
+import type { NotificationService } from '../../definitions/interfaces';
+type Notification = {
+    title: string;
+    body: string;
+};
+export default class Memory implements NotificationService {
+    #private;
+    get connected(): boolean;
+    get subscriptions(): Map<string, Notification[]>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribe(recipientId: string): Promise<void>;
+    unsubscribe(recipientId: string): Promise<void>;
+    sendNotification(recipientId: string, title: string, body: string): Promise<void>;
+}
+export {};

package/dist/implementations/memory/Memory.js

@@ -0,0 +1,46 @@
+import NotConnected from '../../errors/NotConnected';
+import SubscriptionNotFound from '../../errors/SubscriptionNotFound';
+export default class Memory {
+    #subscriptions;
+    get connected() {
+        return this.#subscriptions !== undefined;
+    }
+    get subscriptions() {
+        return this.#getSubscriptions();
+    }
+    async connect() {
+        this.#subscriptions = new Map();
+    }
+    async disconnect() {
+        this.#subscriptions = undefined;
+    }
+    async subscribe(recipientId) {
+        const subscriptions = this.#getSubscriptions();
+        subscriptions.set(recipientId, []);
+    }
+    async unsubscribe(recipientId) {
+        const subscriptions = this.#getSubscriptions();
+        if (subscriptions.has(recipientId) === false) {
+            throw new SubscriptionNotFound(recipientId);
+        }
+        subscriptions.delete(recipientId);
+    }
+    async sendNotification(recipientId, title, body) {
+        const subscription = this.#getSubscription(recipientId);
+        subscription.push({ title, body });
+    }
+    #getSubscriptions() {
+        if (this.#subscriptions === undefined) {
+            throw new NotConnected();
+        }
+        return this.#subscriptions;
+    }
+    #getSubscription(recipientId) {
+        const subscriptions = this.#getSubscriptions();
+        const subscription = subscriptions.get(recipientId);
+        if (subscription === undefined) {
+            throw new SubscriptionNotFound(recipientId);
+        }
+        return subscription;
+    }
+}

package/dist/implementations/memory/create.d.ts

@@ -0,0 +1,2 @@
+import Memory from './Memory';
+export default function create(): Memory;

package/dist/implementations/memory/create.js

@@ -0,0 +1,4 @@
+import Memory from './Memory';
+export default function create() {
+    return new Memory();
+}

package/dist/implementations/webpush/WebPush.d.ts

@@ -0,0 +1,19 @@
+import type { PushSubscription } from 'web-push';
+import type { NotificationService } from '../../definitions/interfaces';
+type VapidDetails = {
+    subject: string;
+    publicKey: string;
+    privateKey: string;
+};
+export default class WebPush implements NotificationService {
+    #private;
+    constructor(configuration: VapidDetails);
+    get connected(): boolean;
+    get subscriptions(): Map<string, PushSubscription>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribe(recipientId: string, subscription: PushSubscription): Promise<void>;
+    unsubscribe(recipientId: string): Promise<void>;
+    sendNotification(recipientId: string, title: string, body: string): Promise<void>;
+}
+export {};

package/dist/implementations/webpush/WebPush.js

@@ -0,0 +1,52 @@
+import webpush from 'web-push';
+import NotConnected from '../../errors/NotConnected';
+import SubscriptionNotFound from '../../errors/SubscriptionNotFound';
+export default class WebPush {
+    #configuration;
+    #subscriptions;
+    constructor(configuration) {
+        this.#configuration = configuration;
+    }
+    get connected() {
+        return this.#subscriptions !== undefined;
+    }
+    get subscriptions() {
+        return this.#getSubscriptions();
+    }
+    async connect() {
+        this.#subscriptions = new Map();
+        webpush.setVapidDetails(this.#configuration.subject, this.#configuration.publicKey, this.#configuration.privateKey);
+    }
+    async disconnect() {
+        this.#subscriptions = undefined;
+    }
+    async subscribe(recipientId, subscription) {
+        const subscriptions = this.#getSubscriptions();
+        subscriptions.set(recipientId, subscription);
+    }
+    async unsubscribe(recipientId) {
+        const subscriptions = this.#getSubscriptions();
+        if (subscriptions.has(recipientId) === false) {
+            throw new SubscriptionNotFound(recipientId);
+        }
+        subscriptions.delete(recipientId);
+    }
+    async sendNotification(recipientId, title, body) {
+        const subscription = this.#getSubscription(recipientId);
+        await webpush.sendNotification(subscription, JSON.stringify({ title, body }));
+    }
+    #getSubscriptions() {
+        if (this.#subscriptions === undefined) {
+            throw new NotConnected();
+        }
+        return this.#subscriptions;
+    }
+    #getSubscription(recipientId) {
+        const subscriptions = this.#getSubscriptions();
+        const subscription = subscriptions.get(recipientId);
+        if (subscription === undefined) {
+            throw new SubscriptionNotFound(recipientId);
+        }
+        return subscription;
+    }
+}

package/dist/implementations/webpush/create.d.ts

@@ -0,0 +1,2 @@
+import WebPush from './WebPush';
+export default function create(): WebPush;

package/dist/implementations/webpush/create.js

@@ -0,0 +1,7 @@
+import WebPush from './WebPush';
+export default function create() {
+    const subject = process.env.WEBPUSH_SUBJECT ?? 'undefined';
+    const publicKey = process.env.WEBPUSH_PUBLIC_KEY ?? 'undefined';
+    const privateKey = process.env.WEBPUSH_PRIVATE_KEY ?? 'undefined';
+    return new WebPush({ subject, publicKey, privateKey });
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { NotificationService } from './definitions/interfaces';
+export { default as NotConnected } from './errors/NotConnected';
+export { default as NotificationError } from './errors/NotificationError';
+export { default as SubscriptionNotFound } from './errors/SubscriptionNotFound';
+export { default as UnknownImplementation } from './errors/UnknownImplementation';
+export { default } from './implementation';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { default as NotConnected } from './errors/NotConnected';
+export { default as NotificationError } from './errors/NotificationError';
+export { default as SubscriptionNotFound } from './errors/SubscriptionNotFound';
+export { default as UnknownImplementation } from './errors/UnknownImplementation';
+export { default } from './implementation';

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@theshelf/notification",
+  "private": false,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test-coverage": "vitest run --coverage",
+    "lint": "eslint",
+    "review": "npm run build && npm run lint && npm run test",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "dependencies": {
+    "web-push": "3.6.7"
+  }
+}