create-forgeon 0.3.23 → 0.3.24

package/templates/module-presets/communications/packages/communications/src/email/email-channel.service.ts

@@ -0,0 +1,90 @@
+import { BadRequestException, Inject, Injectable, Logger } from '@nestjs/common';
+import { COMMUNICATIONS_EMAIL_PROVIDER } from '../communications.constants';
+import { CommunicationsConfigService } from '../communications-config.service';
+import { TemplateLoaderService } from '../template-loader.service';
+import { TemplateRendererService } from '../template-renderer.service';
+import type { CommunicationMessageInput, CommunicationResult } from '../communications.types';
+import type { EmailProvider } from './email-provider.port';
+
+const EMAIL_ERROR_CODES = {
+  missingRecipient: 'COMMUNICATIONS_EMAIL_RECIPIENT_REQUIRED',
+} as const;
+
+@Injectable()
+export class EmailChannelService {
+  private readonly logger = new Logger(EmailChannelService.name);
+
+  constructor(
+    private readonly configService: CommunicationsConfigService,
+    private readonly templateLoader: TemplateLoaderService,
+    private readonly templateRenderer: TemplateRendererService,
+    @Inject(COMMUNICATIONS_EMAIL_PROVIDER)
+    private readonly emailProvider: EmailProvider,
+  ) {}
+
+  async send(input: CommunicationMessageInput): Promise<CommunicationResult> {
+    const recipient = input.recipient.email?.trim();
+    if (!recipient) {
+      throw new BadRequestException({
+        message: 'Email channel requires an email recipient',
+        details: {
+          code: EMAIL_ERROR_CODES.missingRecipient,
+          channel: 'email',
+        },
+      });
+    }
+
+    const templateValues = {
+      ...(input.payload ?? {}),
+      ...(input.metadata ?? {}),
+    };
+
+    const [htmlTemplate, subjectTemplate] = await Promise.all([
+      this.templateLoader.loadChannelTemplate('email', input.kind, input.locale),
+      this.templateLoader.loadOptionalEmailSubjectTemplate(input.kind, input.locale),
+    ]);
+
+    const subject = this.decorateSubject(
+      this.templateRenderer.render(subjectTemplate ?? this.humanizeKind(input.kind), templateValues),
+    );
+    const html = this.templateRenderer.render(htmlTemplate, templateValues);
+
+    const response = await this.emailProvider.send({
+      to: recipient,
+      subject,
+      html,
+      replyTo: this.configService.emailReplyTo,
+    });
+
+    this.logger.log(`communications.email kind=${input.kind} provider=${this.emailProvider.providerId} to=${recipient}`);
+
+    return {
+      kind: input.kind,
+      channel: 'email',
+      provider: this.emailProvider.providerId,
+      status: response.status,
+      messageId: response.messageId,
+      recipient,
+      metadata: {
+        locale: input.locale ?? null,
+        subject,
+      },
+    };
+  }
+
+  private humanizeKind(kind: string): string {
+    return kind
+      .split(/[_-]/g)
+      .filter(Boolean)
+      .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+      .join(' ');
+  }
+
+  private decorateSubject(subject: string): string {
+    const prefix = this.configService.emailSubjectPrefix?.trim();
+    if (!prefix) {
+      return subject;
+    }
+    return `${prefix} ${subject}`.trim();
+  }
+}

package/templates/module-presets/communications/packages/communications/src/email/email-provider.port.ts

@@ -0,0 +1,16 @@
+export interface EmailProviderSendInput {
+  to: string;
+  subject: string;
+  html: string;
+  replyTo?: string | null;
+}
+
+export interface EmailProviderSendResult {
+  status: 'sent';
+  messageId: string | null;
+}
+
+export interface EmailProvider {
+  readonly providerId: string;
+  send(input: EmailProviderSendInput): Promise<EmailProviderSendResult>;
+}

package/templates/module-presets/communications/packages/communications/src/email/providers/gmail-smtp-email.provider.ts

@@ -0,0 +1,64 @@
+import { Injectable, Logger, ServiceUnavailableException } from '@nestjs/common';
+import * as nodemailer from 'nodemailer';
+import type { Transporter } from 'nodemailer';
+import { CommunicationsConfigService } from '../../communications-config.service';
+import type { EmailProvider, EmailProviderSendInput, EmailProviderSendResult } from '../email-provider.port';
+
+const EMAIL_ERROR_CODES = {
+  providerNotConfigured: 'COMMUNICATIONS_EMAIL_PROVIDER_NOT_CONFIGURED',
+} as const;
+
+@Injectable()
+export class GmailSmtpEmailProvider implements EmailProvider {
+  private readonly logger = new Logger(GmailSmtpEmailProvider.name);
+  private transporter: Transporter | null = null;
+
+  constructor(private readonly configService: CommunicationsConfigService) {}
+
+  get providerId(): string {
+    return this.configService.emailProvider;
+  }
+
+  async send(input: EmailProviderSendInput): Promise<EmailProviderSendResult> {
+    if (!this.configService.emailProviderReady) {
+      throw new ServiceUnavailableException({
+        message: 'Email provider is not configured',
+        details: {
+          code: EMAIL_ERROR_CODES.providerNotConfigured,
+          provider: this.providerId,
+        },
+      });
+    }
+
+    const response = await this.getTransporter().sendMail({
+      from: this.configService.emailFrom,
+      to: input.to,
+      subject: input.subject,
+      html: input.html,
+      replyTo: input.replyTo ?? this.configService.emailReplyTo ?? undefined,
+    });
+
+    this.logger.log(`email.sent provider=${this.providerId} to=${input.to} messageId=${response.messageId ?? 'n/a'}`);
+
+    return {
+      status: 'sent',
+      messageId: response.messageId ?? null,
+    };
+  }
+
+  private getTransporter(): Transporter {
+    if (!this.transporter) {
+      this.transporter = nodemailer.createTransport({
+        host: this.configService.emailSmtpHost,
+        port: this.configService.emailSmtpPort,
+        secure: this.configService.emailSmtpSecure,
+        auth: {
+          user: this.configService.emailSmtpUser,
+          pass: this.configService.emailSmtpPass,
+        },
+      });
+    }
+
+    return this.transporter;
+  }
+}

package/templates/module-presets/communications/packages/communications/src/forgeon-communications.module.ts

@@ -0,0 +1,64 @@
+import { DynamicModule, Module, ModuleMetadata } from '@nestjs/common';
+import {
+  COMMUNICATIONS_EMAIL_PROVIDER,
+  COMMUNICATIONS_PUSH_PROVIDER,
+  COMMUNICATIONS_SMS_PROVIDER,
+} from './communications.constants';
+import { CommunicationsConfigModule } from './communications-config.module';
+import { CommunicationsProbeController } from './communications.probe.controller';
+import { CommunicationsService } from './communications.service';
+import { EmailChannelService } from './email/email-channel.service';
+import { GmailSmtpEmailProvider } from './email/providers/gmail-smtp-email.provider';
+import { PushChannelService } from './push/push-channel.service';
+import { StubPushProvider } from './push/providers/stub-push.provider';
+import { SmsChannelService } from './sms/sms-channel.service';
+import { StubSmsProvider } from './sms/providers/stub-sms.provider';
+import { TemplateLoaderService } from './template-loader.service';
+import { TemplateRendererService } from './template-renderer.service';
+
+export interface ForgeonCommunicationsModuleOptions {
+  imports?: ModuleMetadata['imports'];
+}
+
+@Module({})
+export class ForgeonCommunicationsModule {
+  static register(options: ForgeonCommunicationsModuleOptions = {}): DynamicModule {
+    return {
+      module: ForgeonCommunicationsModule,
+      imports: [CommunicationsConfigModule, ...(options.imports ?? [])],
+      controllers: [CommunicationsProbeController],
+      providers: [
+        TemplateLoaderService,
+        TemplateRendererService,
+        CommunicationsService,
+        EmailChannelService,
+        SmsChannelService,
+        PushChannelService,
+        GmailSmtpEmailProvider,
+        StubSmsProvider,
+        StubPushProvider,
+        {
+          provide: COMMUNICATIONS_EMAIL_PROVIDER,
+          useExisting: GmailSmtpEmailProvider,
+        },
+        {
+          provide: COMMUNICATIONS_SMS_PROVIDER,
+          useExisting: StubSmsProvider,
+        },
+        {
+          provide: COMMUNICATIONS_PUSH_PROVIDER,
+          useExisting: StubPushProvider,
+        },
+      ],
+      exports: [
+        CommunicationsConfigModule,
+        TemplateLoaderService,
+        TemplateRendererService,
+        CommunicationsService,
+        COMMUNICATIONS_EMAIL_PROVIDER,
+        COMMUNICATIONS_SMS_PROVIDER,
+        COMMUNICATIONS_PUSH_PROVIDER,
+      ],
+    };
+  }
+}

package/templates/module-presets/communications/packages/communications/src/index.ts

@@ -0,0 +1,21 @@
+export * from './communications-config.loader';
+export * from './communications-config.module';
+export * from './communications-config.service';
+export * from './communications-env.schema';
+export * from './communications.probe.controller';
+export * from './communications.service';
+export * from './communications.types';
+export * from './communications.constants';
+export * from './dto/send-communications-probe.dto';
+export * from './email/email-channel.service';
+export * from './email/email-provider.port';
+export * from './email/providers/gmail-smtp-email.provider';
+export * from './forgeon-communications.module';
+export * from './push/providers/stub-push.provider';
+export * from './push/push-channel.service';
+export * from './push/push-provider.port';
+export * from './sms/providers/stub-sms.provider';
+export * from './sms/sms-channel.service';
+export * from './sms/sms-provider.port';
+export * from './template-loader.service';
+export * from './template-renderer.service';

package/templates/module-presets/communications/packages/communications/src/push/providers/stub-push.provider.ts

@@ -0,0 +1,16 @@
+import { Injectable, Logger } from '@nestjs/common';
+import type { PushProvider, PushProviderSendInput, PushProviderSendResult } from '../push-provider.port';
+
+@Injectable()
+export class StubPushProvider implements PushProvider {
+  private readonly logger = new Logger(StubPushProvider.name);
+  readonly providerId = 'stub';
+
+  async send(input: PushProviderSendInput): Promise<PushProviderSendResult> {
+    this.logger.warn(`communications.push.stub token=${input.pushToken} length=${input.body.length}`);
+    return {
+      status: 'stub',
+      messageId: null,
+    };
+  }
+}

package/templates/module-presets/communications/packages/communications/src/push/push-channel.service.ts

@@ -0,0 +1,56 @@
+import { BadRequestException, Inject, Injectable, Logger } from '@nestjs/common';
+import { COMMUNICATIONS_PUSH_PROVIDER } from '../communications.constants';
+import { TemplateLoaderService } from '../template-loader.service';
+import { TemplateRendererService } from '../template-renderer.service';
+import type { CommunicationMessageInput, CommunicationResult } from '../communications.types';
+import type { PushProvider } from './push-provider.port';
+
+const PUSH_ERROR_CODES = {
+  missingRecipient: 'COMMUNICATIONS_PUSH_RECIPIENT_REQUIRED',
+} as const;
+
+@Injectable()
+export class PushChannelService {
+  private readonly logger = new Logger(PushChannelService.name);
+
+  constructor(
+    private readonly templateLoader: TemplateLoaderService,
+    private readonly templateRenderer: TemplateRendererService,
+    @Inject(COMMUNICATIONS_PUSH_PROVIDER)
+    private readonly pushProvider: PushProvider,
+  ) {}
+
+  async send(input: CommunicationMessageInput): Promise<CommunicationResult> {
+    const recipient = input.recipient.pushToken?.trim();
+    if (!recipient) {
+      throw new BadRequestException({
+        message: 'Push channel requires a push token recipient',
+        details: {
+          code: PUSH_ERROR_CODES.missingRecipient,
+          channel: 'push',
+        },
+      });
+    }
+
+    const template = await this.templateLoader.loadChannelTemplate('push', input.kind, input.locale);
+    const body = this.templateRenderer.render(template, {
+      ...(input.payload ?? {}),
+      ...(input.metadata ?? {}),
+    });
+
+    const response = await this.pushProvider.send({ pushToken: recipient, body });
+    this.logger.warn(`communications.push kind=${input.kind} provider=${this.pushProvider.providerId}`);
+
+    return {
+      kind: input.kind,
+      channel: 'push',
+      provider: this.pushProvider.providerId,
+      status: response.status,
+      messageId: response.messageId,
+      recipient,
+      metadata: {
+        locale: input.locale ?? null,
+      },
+    };
+  }
+}

package/templates/module-presets/communications/packages/communications/src/push/push-provider.port.ts

@@ -0,0 +1,14 @@
+export interface PushProviderSendInput {
+  pushToken: string;
+  body: string;
+}
+
+export interface PushProviderSendResult {
+  status: 'stub' | 'sent';
+  messageId: string | null;
+}
+
+export interface PushProvider {
+  readonly providerId: string;
+  send(input: PushProviderSendInput): Promise<PushProviderSendResult>;
+}

package/templates/module-presets/communications/packages/communications/src/sms/providers/stub-sms.provider.ts

@@ -0,0 +1,16 @@
+import { Injectable, Logger } from '@nestjs/common';
+import type { SmsProvider, SmsProviderSendInput, SmsProviderSendResult } from '../sms-provider.port';
+
+@Injectable()
+export class StubSmsProvider implements SmsProvider {
+  private readonly logger = new Logger(StubSmsProvider.name);
+  readonly providerId = 'stub';
+
+  async send(input: SmsProviderSendInput): Promise<SmsProviderSendResult> {
+    this.logger.warn(`communications.sms.stub phone=${input.phone} length=${input.text.length}`);
+    return {
+      status: 'stub',
+      messageId: null,
+    };
+  }
+}

package/templates/module-presets/communications/packages/communications/src/sms/sms-channel.service.ts

@@ -0,0 +1,56 @@
+import { BadRequestException, Inject, Injectable, Logger } from '@nestjs/common';
+import { COMMUNICATIONS_SMS_PROVIDER } from '../communications.constants';
+import { TemplateLoaderService } from '../template-loader.service';
+import { TemplateRendererService } from '../template-renderer.service';
+import type { CommunicationMessageInput, CommunicationResult } from '../communications.types';
+import type { SmsProvider } from './sms-provider.port';
+
+const SMS_ERROR_CODES = {
+  missingRecipient: 'COMMUNICATIONS_SMS_RECIPIENT_REQUIRED',
+} as const;
+
+@Injectable()
+export class SmsChannelService {
+  private readonly logger = new Logger(SmsChannelService.name);
+
+  constructor(
+    private readonly templateLoader: TemplateLoaderService,
+    private readonly templateRenderer: TemplateRendererService,
+    @Inject(COMMUNICATIONS_SMS_PROVIDER)
+    private readonly smsProvider: SmsProvider,
+  ) {}
+
+  async send(input: CommunicationMessageInput): Promise<CommunicationResult> {
+    const recipient = input.recipient.phone?.trim();
+    if (!recipient) {
+      throw new BadRequestException({
+        message: 'SMS channel requires a phone recipient',
+        details: {
+          code: SMS_ERROR_CODES.missingRecipient,
+          channel: 'sms',
+        },
+      });
+    }
+
+    const template = await this.templateLoader.loadChannelTemplate('sms', input.kind, input.locale);
+    const text = this.templateRenderer.render(template, {
+      ...(input.payload ?? {}),
+      ...(input.metadata ?? {}),
+    });
+
+    const response = await this.smsProvider.send({ phone: recipient, text });
+    this.logger.warn(`communications.sms kind=${input.kind} provider=${this.smsProvider.providerId} phone=${recipient}`);
+
+    return {
+      kind: input.kind,
+      channel: 'sms',
+      provider: this.smsProvider.providerId,
+      status: response.status,
+      messageId: response.messageId,
+      recipient,
+      metadata: {
+        locale: input.locale ?? null,
+      },
+    };
+  }
+}

package/templates/module-presets/communications/packages/communications/src/sms/sms-provider.port.ts

@@ -0,0 +1,14 @@
+export interface SmsProviderSendInput {
+  phone: string;
+  text: string;
+}
+
+export interface SmsProviderSendResult {
+  status: 'stub' | 'sent';
+  messageId: string | null;
+}
+
+export interface SmsProvider {
+  readonly providerId: string;
+  send(input: SmsProviderSendInput): Promise<SmsProviderSendResult>;
+}

package/templates/module-presets/communications/packages/communications/src/template-loader.service.ts

@@ -0,0 +1,98 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { promises as fsPromises } from 'node:fs';
+import { BadRequestException, Injectable, InternalServerErrorException } from '@nestjs/common';
+import type { CommunicationChannel } from './communications.types';
+import { CommunicationsConfigService } from './communications-config.service';
+
+type TemplateVariant = 'body' | 'subject';
+
+const CHANNEL_EXTENSIONS: Record<CommunicationChannel, string> = {
+  email: '.html',
+  sms: '.txt',
+  push: '.json',
+};
+
+const SUBJECT_EXTENSION = '.subject.txt';
+const TEMPLATE_ERROR_CODES = {
+  invalidKey: 'COMMUNICATIONS_TEMPLATE_INVALID_KEY',
+  missing: 'COMMUNICATIONS_TEMPLATE_MISSING',
+} as const;
+
+@Injectable()
+export class TemplateLoaderService {
+  constructor(private readonly configService: CommunicationsConfigService) {}
+
+  async loadChannelTemplate(
+    channel: CommunicationChannel,
+    kind: string,
+    locale?: string,
+  ): Promise<string> {
+    const relativePath = this.resolveTemplateRelativePath(channel, kind, 'body', locale);
+    return this.readTemplate(relativePath, channel, kind);
+  }
+
+  async loadOptionalEmailSubjectTemplate(kind: string, locale?: string): Promise<string | null> {
+    const relativePath = this.resolveTemplateRelativePath('email', kind, 'subject', locale);
+    const absolutePath = path.join(this.configService.templatesRoot, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+      return null;
+    }
+
+    return fsPromises.readFile(absolutePath, 'utf8');
+  }
+
+  private resolveTemplateRelativePath(
+    channel: CommunicationChannel,
+    kind: string,
+    variant: TemplateVariant,
+    locale?: string,
+  ): string {
+    const safeKind = this.sanitizeSegment(kind, 'kind');
+    const safeLocale = locale ? this.sanitizeSegment(locale, 'locale') : null;
+    const extension = variant === 'subject' ? SUBJECT_EXTENSION : CHANNEL_EXTENSIONS[channel];
+
+    if (safeLocale) {
+      const localizedPath = path.join(channel, `${safeKind}.${safeLocale}${extension}`);
+      const absoluteLocalizedPath = path.join(this.configService.templatesRoot, localizedPath);
+      if (fs.existsSync(absoluteLocalizedPath)) {
+        return localizedPath;
+      }
+    }
+
+    return path.join(channel, `${safeKind}${extension}`);
+  }
+
+  private async readTemplate(relativePath: string, channel: CommunicationChannel, kind: string): Promise<string> {
+    const absolutePath = path.join(this.configService.templatesRoot, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+      throw new InternalServerErrorException({
+        message: 'Communication template was not found',
+        details: {
+          code: TEMPLATE_ERROR_CODES.missing,
+          channel,
+          kind,
+          relativePath,
+        },
+      });
+    }
+
+    return fsPromises.readFile(absolutePath, 'utf8');
+  }
+
+  private sanitizeSegment(value: string, field: 'kind' | 'locale'): string {
+    const normalized = value.trim();
+    if (!/^[a-z0-9._-]+$/i.test(normalized)) {
+      throw new BadRequestException({
+        message: `Communication ${field} contains unsupported characters`,
+        details: {
+          code: TEMPLATE_ERROR_CODES.invalidKey,
+          field,
+          value,
+        },
+      });
+    }
+
+    return normalized;
+  }
+}

package/templates/module-presets/communications/packages/communications/src/template-renderer.service.ts

@@ -0,0 +1,30 @@
+import { Injectable } from '@nestjs/common';
+import type { CommunicationPayloadValue } from './communications.types';
+
+@Injectable()
+export class TemplateRendererService {
+  render(template: string, values: Record<string, CommunicationPayloadValue> = {}): string {
+    let output = template;
+
+    for (const [rawKey, rawValue] of Object.entries(values)) {
+      const replacement = this.stringifyValue(rawValue);
+      const normalizedKeys = new Set([rawKey, rawKey.toUpperCase()]);
+
+      for (const key of normalizedKeys) {
+        output = output.split(`$${key}$`).join(replacement);
+      }
+    }
+
+    return output;
+  }
+
+  private stringifyValue(value: CommunicationPayloadValue): string {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (value === null || value === undefined) {
+      return '';
+    }
+    return String(value);
+  }
+}

package/templates/module-presets/communications/packages/communications/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/module-presets/communications/resources/communications/email/communications_probe.html

@@ -0,0 +1,9 @@
+<html>
+  <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #111827;">
+    <h1>Communications Probe</h1>
+    <p>This is a test message from the Forgeon communications module.</p>
+    <p>Recipient: <strong>$EMAIL$</strong></p>
+    <p>Probe id: <strong>$PROBE_ID$</strong></p>
+    <p>Generated at: <strong>$DATE$</strong></p>
+  </body>
+</html>

package/templates/module-presets/communications/resources/communications/email/communications_probe.subject.txt

@@ -0,0 +1 @@
+Communications probe

package/templates/module-presets/communications/resources/communications/email/email_verification_code.html

@@ -0,0 +1,8 @@
+<html>
+  <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #111827;">
+    <h1>Email Verification</h1>
+    <p>Hello $NAME$,</p>
+    <p>Your verification code is <strong>$CODE$</strong>.</p>
+    <p>If you did not request this, you can safely ignore this message.</p>
+  </body>
+</html>

package/templates/module-presets/communications/resources/communications/email/email_verification_code.subject.txt

@@ -0,0 +1 @@
+Verify your email address

package/templates/module-presets/communications/resources/communications/email/password_reset.html

@@ -0,0 +1,8 @@
+<html>
+  <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #111827;">
+    <h1>Password Reset</h1>
+    <p>Hello $NAME$,</p>
+    <p>Use this reset token to continue: <strong>$TOKEN$</strong>.</p>
+    <p>If you did not request a password reset, please ignore this email.</p>
+  </body>
+</html>

package/templates/module-presets/communications/resources/communications/email/password_reset.subject.txt

@@ -0,0 +1 @@
+Reset your password

package/templates/module-presets/communications/resources/communications/email/welcome_email.html

@@ -0,0 +1,8 @@
+<html>
+  <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #111827;">
+    <h1>Welcome</h1>
+    <p>Hello $NAME$,</p>
+    <p>Your account is ready.</p>
+    <p>We are glad to have you here.</p>
+  </body>
+</html>

package/templates/module-presets/communications/resources/communications/email/welcome_email.subject.txt

@@ -0,0 +1 @@
+Welcome to Forgeon

package/templates/module-presets/communications/resources/communications/push/login_alert.json

@@ -0,0 +1,4 @@
+{
+  "title": "Login alert",
+  "message": "A new login was detected on $DATE$"
+}

package/templates/module-presets/communications/resources/communications/sms/phone_verification.txt

@@ -0,0 +1 @@
+Phone verification code: $CODE$