@twin.org/messaging-service 0.0.1-next.2

package/dist/esm/index.mjs

@@ -0,0 +1,236 @@
+import { Is, GeneralError, Guards } from '@twin.org/core';
+import { EntityStorageConnectorFactory } from '@twin.org/entity-storage-models';
+import { MessagingEmailConnectorFactory, MessagingPushNotificationsConnectorFactory, MessagingSmsConnectorFactory } from '@twin.org/messaging-models';
+import { property, entity } from '@twin.org/entity';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Call defining a template message entry.
+ */
+let TemplateEntry = class TemplateEntry {
+    /**
+     * The id.
+     */
+    id;
+    /**
+     * The title.
+     */
+    title;
+    /**
+     * The content.
+     */
+    content;
+    /**
+     * The timestamp of the template entry.
+     */
+    ts;
+};
+__decorate([
+    property({ type: "string", isPrimary: true }),
+    __metadata("design:type", String)
+], TemplateEntry.prototype, "id", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], TemplateEntry.prototype, "title", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], TemplateEntry.prototype, "content", void 0);
+__decorate([
+    property({ type: "integer" }),
+    __metadata("design:type", Number)
+], TemplateEntry.prototype, "ts", void 0);
+TemplateEntry = __decorate([
+    entity()
+], TemplateEntry);
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Service for performing email messaging operations to a connector.
+ */
+class MessagingService {
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "MessagingService";
+    /**
+     * Emails messaging connector used by the service.
+     * @internal
+     */
+    _emailMessagingConnector;
+    /**
+     * Push notifications messaging connector used by the service.
+     * @internal
+     */
+    _pushNotificationMessagingConnector;
+    /**
+     * SMS messaging connector used by the service.
+     * @internal
+     */
+    _smsMessagingConnector;
+    /**
+     * Entity storage connector used by the service.
+     * @internal
+     */
+    _entityStorageConnector;
+    /**
+     * Create a new instance of MessagingService.
+     * @param options The options for the connector.
+     * @param options.messagingEmailConnectorType The type of the email messaging connector to use, defaults to not configured.
+     * @param options.messagingPushNotificationConnectorType The type of the push notifications messaging connector to use, defaults to not configured.
+     * @param options.messagingSmsConnectorType The type of the sms messaging connector to use, defaults to not configured.
+     * @param options.templateEntryStorageConnectorType The type of the entity connector to use, defaults to "messaging-templates".
+     */
+    constructor(options) {
+        if (Is.stringValue(options?.messagingEmailConnectorType)) {
+            this._emailMessagingConnector = MessagingEmailConnectorFactory.get(options.messagingEmailConnectorType);
+        }
+        if (Is.stringValue(options?.messagingPushNotificationConnectorType)) {
+            this._pushNotificationMessagingConnector = MessagingPushNotificationsConnectorFactory.get(options.messagingPushNotificationConnectorType);
+        }
+        if (Is.stringValue(options?.messagingSmsConnectorType)) {
+            this._smsMessagingConnector = MessagingSmsConnectorFactory.get(options.messagingSmsConnectorType);
+        }
+        this._entityStorageConnector = EntityStorageConnectorFactory.get(options?.templateEntryStorageConnectorType ?? "template-entry");
+    }
+    /**
+     * Send a custom email.
+     * @param sender The sender email address.
+     * @param recipients An array of recipients email addresses.
+     * @param templateId The id of the email template.
+     * @param data The data to populate the email template.
+     * @param locale The locale of the email template.
+     * @returns If the email was sent successfully.
+     */
+    async sendCustomEmail(sender, recipients, templateId, data, locale) {
+        if (Is.empty(this._emailMessagingConnector)) {
+            throw new GeneralError(this.CLASS_NAME, "notConfiguredEmailMessagingConnector");
+        }
+        Guards.stringValue(this.CLASS_NAME, "sender", sender);
+        Guards.arrayValue(this.CLASS_NAME, "recipients", recipients);
+        Guards.stringValue(this.CLASS_NAME, "templateId", templateId);
+        Guards.object(this.CLASS_NAME, "data", data);
+        Guards.stringValue(this.CLASS_NAME, "locale", locale);
+        const template = await this.getTemplate(templateId, locale);
+        const populatedTemplate = this.populateTemplate(template, data);
+        return this._emailMessagingConnector.sendCustomEmail(sender, recipients, populatedTemplate.title, populatedTemplate.content);
+    }
+    /**
+     * Registers a device to an specific app in order to send notifications to it.
+     * @param applicationId The application address.
+     * @param deviceToken The device token.
+     * @returns If the device was registered successfully.
+     */
+    async registerDevice(applicationId, deviceToken) {
+        if (Is.empty(this._pushNotificationMessagingConnector)) {
+            throw new GeneralError(this.CLASS_NAME, "notConfiguredPushNotificationMessagingConnector");
+        }
+        Guards.stringValue(this.CLASS_NAME, "applicationId", applicationId);
+        Guards.stringValue(this.CLASS_NAME, "deviceToken", deviceToken);
+        return this._pushNotificationMessagingConnector.registerDevice(applicationId, deviceToken);
+    }
+    /**
+     * Send a push notification to a device.
+     * @param deviceAddress The address of the device.
+     * @param templateId The id of the push notification template.
+     * @param data The data to populate the push notification template.
+     * @param locale The locale of the push notification template.
+     * @returns If the notification was sent successfully.
+     */
+    async sendSinglePushNotification(deviceAddress, templateId, data, locale) {
+        if (Is.empty(this._pushNotificationMessagingConnector)) {
+            throw new GeneralError(this.CLASS_NAME, "notConfiguredPushNotificationMessagingConnector");
+        }
+        Guards.stringValue(this.CLASS_NAME, "deviceAddress", deviceAddress);
+        Guards.stringValue(this.CLASS_NAME, "templateId", templateId);
+        Guards.object(this.CLASS_NAME, "data", data);
+        Guards.stringValue(this.CLASS_NAME, "locale", locale);
+        const template = await this.getTemplate(templateId, locale);
+        const populatedTemplate = this.populateTemplate(template, data);
+        return this._pushNotificationMessagingConnector.sendSinglePushNotification(deviceAddress, populatedTemplate.title, populatedTemplate.content);
+    }
+    /**
+     * Send a SMS message to a phone number.
+     * @param phoneNumber The recipient phone number.
+     * @param templateId The id of the SMS template.
+     * @param data The data to populate the SMS template.
+     * @param locale The locale of the SMS template.
+     * @returns If the SMS was sent successfully.
+     */
+    async sendSMS(phoneNumber, templateId, data, locale) {
+        if (Is.empty(this._smsMessagingConnector)) {
+            throw new GeneralError(this.CLASS_NAME, "notConfiguredSmsMessagingConnector");
+        }
+        Guards.stringValue(this.CLASS_NAME, "phoneNumber", phoneNumber);
+        Guards.stringValue(this.CLASS_NAME, "templateId", templateId);
+        Guards.object(this.CLASS_NAME, "data", data);
+        Guards.stringValue(this.CLASS_NAME, "locale", locale);
+        const template = await this.getTemplate(templateId, locale);
+        const populatedTemplate = this.populateTemplate(template, data);
+        return this._smsMessagingConnector.sendSMS(phoneNumber, populatedTemplate.content);
+    }
+    /**
+     * Create or update a template.
+     * @param templateId The id of the template.
+     * @param locale The locale of the template.
+     * @param title The title of the template.
+     * @param content The content of the template.
+     * @returns If the template was created or updated successfully.
+     */
+    async createOrUpdateTemplate(templateId, locale, title, content) {
+        Guards.stringValue(this.CLASS_NAME, "templateId", templateId);
+        Guards.stringValue(this.CLASS_NAME, "locale", locale);
+        Guards.stringValue(this.CLASS_NAME, "title", title);
+        Guards.stringValue(this.CLASS_NAME, "content", content);
+        const templateEntry = new TemplateEntry();
+        templateEntry.id = `${templateId}:${locale}`;
+        templateEntry.ts = Date.now();
+        templateEntry.title = title;
+        templateEntry.content = content;
+        await this._entityStorageConnector.set(templateEntry);
+        return true;
+    }
+    /**
+     * Get the email template by id and locale.
+     * @param templateId The id of the email template.
+     * @param locale The locale of the email template.
+     * @returns The email template.
+     * @internal
+     */
+    async getTemplate(templateId, locale) {
+        const entityId = `${templateId}:${locale}`;
+        const templateInfo = await this._entityStorageConnector.get(entityId);
+        if (!templateInfo) {
+            throw new GeneralError(this.CLASS_NAME, "getTemplateFailed", { templateId, locale });
+        }
+        return templateInfo;
+    }
+    /**
+     * Populate the template with data.
+     * @param template The template.
+     * @param template.title The title of the template.
+     * @param template.content The content of the template.
+     * @param data The data to populate the template.
+     * @internal
+     * @returns The populated template.
+     */
+    populateTemplate(template, data) {
+        let populatedTitle = template.title;
+        let populatedContent = template.content;
+        for (const key in data) {
+            const value = data[key];
+            const placeholder = `{{${key}}}`;
+            populatedTitle = populatedTitle.replace(new RegExp(placeholder, "g"), value);
+            populatedContent = populatedContent.replace(new RegExp(placeholder, "g"), value);
+        }
+        return {
+            title: populatedTitle,
+            content: populatedContent
+        };
+    }
+}
+
+export { MessagingService };

package/dist/types/entities/templateEntry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Call defining a template message entry.
+ */
+export declare class TemplateEntry {
+    /**
+     * The id.
+     */
+    id: string;
+    /**
+     * The title.
+     */
+    title: string;
+    /**
+     * The content.
+     */
+    content: string;
+    /**
+     * The timestamp of the template entry.
+     */
+    ts: number;
+}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./messagingService";

package/dist/types/messagingService.d.ts

@@ -0,0 +1,74 @@
+import { type IMessagingComponent } from "@twin.org/messaging-models";
+/**
+ * Service for performing email messaging operations to a connector.
+ */
+export declare class MessagingService implements IMessagingComponent {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of MessagingService.
+     * @param options The options for the connector.
+     * @param options.messagingEmailConnectorType The type of the email messaging connector to use, defaults to not configured.
+     * @param options.messagingPushNotificationConnectorType The type of the push notifications messaging connector to use, defaults to not configured.
+     * @param options.messagingSmsConnectorType The type of the sms messaging connector to use, defaults to not configured.
+     * @param options.templateEntryStorageConnectorType The type of the entity connector to use, defaults to "messaging-templates".
+     */
+    constructor(options?: {
+        messagingEmailConnectorType?: string;
+        messagingPushNotificationConnectorType?: string;
+        messagingSmsConnectorType?: string;
+        templateEntryStorageConnectorType?: string;
+    });
+    /**
+     * Send a custom email.
+     * @param sender The sender email address.
+     * @param recipients An array of recipients email addresses.
+     * @param templateId The id of the email template.
+     * @param data The data to populate the email template.
+     * @param locale The locale of the email template.
+     * @returns If the email was sent successfully.
+     */
+    sendCustomEmail(sender: string, recipients: string[], templateId: string, data: {
+        [key: string]: string;
+    }, locale: string): Promise<boolean>;
+    /**
+     * Registers a device to an specific app in order to send notifications to it.
+     * @param applicationId The application address.
+     * @param deviceToken The device token.
+     * @returns If the device was registered successfully.
+     */
+    registerDevice(applicationId: string, deviceToken: string): Promise<string>;
+    /**
+     * Send a push notification to a device.
+     * @param deviceAddress The address of the device.
+     * @param templateId The id of the push notification template.
+     * @param data The data to populate the push notification template.
+     * @param locale The locale of the push notification template.
+     * @returns If the notification was sent successfully.
+     */
+    sendSinglePushNotification(deviceAddress: string, templateId: string, data: {
+        [key: string]: string;
+    }, locale: string): Promise<boolean>;
+    /**
+     * Send a SMS message to a phone number.
+     * @param phoneNumber The recipient phone number.
+     * @param templateId The id of the SMS template.
+     * @param data The data to populate the SMS template.
+     * @param locale The locale of the SMS template.
+     * @returns If the SMS was sent successfully.
+     */
+    sendSMS(phoneNumber: string, templateId: string, data: {
+        [key: string]: string;
+    }, locale: string): Promise<boolean>;
+    /**
+     * Create or update a template.
+     * @param templateId The id of the template.
+     * @param locale The locale of the template.
+     * @param title The title of the template.
+     * @param content The content of the template.
+     * @returns If the template was created or updated successfully.
+     */
+    createOrUpdateTemplate(templateId: string, locale: string, title: string, content: string): Promise<boolean>;
+}

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/messaging-service - Changelog
+
+## v0.0.1-next.4
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/messaging-service - Examples