create-forgeon 0.3.23 → 0.3.25

package/templates/module-presets/communications/packages/communications/src/communications-env.schema.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+function normalizeEnvBoolean(value: unknown): unknown {
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(normalized)) {
+      return true;
+    }
+    if (['false', '0', 'no', 'off', ''].includes(normalized)) {
+      return false;
+    }
+  }
+
+  return value;
+}
+
+const envBoolean = z.preprocess(normalizeEnvBoolean, z.boolean());
+
+export const communicationsEnvSchema = z
+  .object({
+    COMMUNICATIONS_TEMPLATES_ROOT: z.string().trim().min(1).default('resources/communications'),
+    COMMUNICATIONS_EMAIL_PROVIDER: z.enum(['gmail-smtp']).default('gmail-smtp'),
+    COMMUNICATIONS_EMAIL_FROM: z.string().trim().default(''),
+    COMMUNICATIONS_EMAIL_REPLY_TO: z.string().trim().default(''),
+    COMMUNICATIONS_EMAIL_SUBJECT_PREFIX: z.string().trim().default('[Forgeon]'),
+    COMMUNICATIONS_EMAIL_SMTP_HOST: z.string().trim().min(1).default('smtp.gmail.com'),
+    COMMUNICATIONS_EMAIL_SMTP_PORT: z.coerce.number().int().min(1).max(65535).default(587),
+    COMMUNICATIONS_EMAIL_SMTP_SECURE: envBoolean.default(false),
+    COMMUNICATIONS_EMAIL_SMTP_USER: z.string().trim().default(''),
+    COMMUNICATIONS_EMAIL_SMTP_PASS: z.string().trim().default(''),
+    COMMUNICATIONS_SMS_PROVIDER: z.enum(['stub']).default('stub'),
+    COMMUNICATIONS_PUSH_PROVIDER: z.enum(['stub']).default('stub'),
+  })
+  .passthrough();
+
+export type CommunicationsEnv = z.infer<typeof communicationsEnvSchema>;
+
+export function parseCommunicationsEnv(input: Record<string, unknown>): CommunicationsEnv {
+  return communicationsEnvSchema.parse(input);
+}

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

@@ -0,0 +1,3 @@
+export const COMMUNICATIONS_EMAIL_PROVIDER = 'FORGEON_COMMUNICATIONS_EMAIL_PROVIDER';
+export const COMMUNICATIONS_SMS_PROVIDER = 'FORGEON_COMMUNICATIONS_SMS_PROVIDER';
+export const COMMUNICATIONS_PUSH_PROVIDER = 'FORGEON_COMMUNICATIONS_PUSH_PROVIDER';

package/templates/module-presets/communications/packages/communications/src/communications.probe.controller.ts

@@ -0,0 +1,18 @@
+import { Body, Controller, Get, Post } from '@nestjs/common';
+import { CommunicationsService } from './communications.service';
+import { SendCommunicationsProbeDto } from './dto/send-communications-probe.dto';
+
+@Controller('health')
+export class CommunicationsProbeController {
+  constructor(private readonly communicationsService: CommunicationsService) {}
+
+  @Get('communications')
+  getCommunicationsProbe() {
+    return this.communicationsService.getProbeStatus();
+  }
+
+  @Post('communications')
+  sendCommunicationsProbe(@Body() body: SendCommunicationsProbeDto) {
+    return this.communicationsService.sendProbeEmail(body.email);
+  }
+}

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

@@ -0,0 +1,104 @@
+import * as crypto from 'node:crypto';
+import { BadRequestException, Injectable } from '@nestjs/common';
+import { CommunicationsConfigService } from './communications-config.service';
+import { EmailChannelService } from './email/email-channel.service';
+import { PushChannelService } from './push/push-channel.service';
+import { SmsChannelService } from './sms/sms-channel.service';
+import type {
+  CommunicationChannel,
+  CommunicationMessageInput,
+  CommunicationProbeResult,
+  CommunicationResult,
+} from './communications.types';
+
+const COMMUNICATIONS_ERROR_CODES = {
+  channelsRequired: 'COMMUNICATIONS_CHANNELS_REQUIRED',
+  unsupportedChannel: 'COMMUNICATIONS_UNSUPPORTED_CHANNEL',
+} as const;
+
+@Injectable()
+export class CommunicationsService {
+  constructor(
+    private readonly configService: CommunicationsConfigService,
+    private readonly emailChannelService: EmailChannelService,
+    private readonly smsChannelService: SmsChannelService,
+    private readonly pushChannelService: PushChannelService,
+  ) {}
+
+  async send(input: CommunicationMessageInput): Promise<CommunicationResult[]> {
+    if (!Array.isArray(input.channels) || input.channels.length === 0) {
+      throw new BadRequestException({
+        message: 'Communication request must include at least one channel',
+        details: {
+          code: COMMUNICATIONS_ERROR_CODES.channelsRequired,
+        },
+      });
+    }
+
+    return Promise.all(input.channels.map((channel) => this.dispatchChannel(channel, input)));
+  }
+
+  async sendProbeEmail(email: string): Promise<CommunicationProbeResult> {
+    const probeId = crypto.randomUUID();
+    const [result] = await this.send({
+      kind: 'communications_probe',
+      channels: ['email'],
+      recipient: { email },
+      payload: {
+        PROBE_ID: probeId,
+        DATE: new Date().toISOString(),
+        EMAIL: email,
+      },
+      metadata: {
+        SOURCE: 'communications-health-probe',
+      },
+    });
+
+    return {
+      probeId,
+      recipient: email,
+      result,
+    };
+  }
+
+  getProbeStatus() {
+    return {
+      status: 'ok',
+      feature: 'communications',
+      templatesRoot: this.configService.templatesRoot,
+      email: {
+        provider: this.configService.emailProvider,
+        ready: this.configService.emailProviderReady,
+      },
+      sms: {
+        provider: this.configService.smsProvider,
+      },
+      push: {
+        provider: this.configService.pushProvider,
+      },
+      probeRoutes: {
+        inspect: 'GET /api/health/communications',
+        send: 'POST /api/health/communications',
+      },
+    };
+  }
+
+  private dispatchChannel(channel: CommunicationChannel, input: CommunicationMessageInput): Promise<CommunicationResult> {
+    switch (channel) {
+      case 'email':
+        return this.emailChannelService.send(input);
+      case 'sms':
+        return this.smsChannelService.send(input);
+      case 'push':
+        return this.pushChannelService.send(input);
+      default:
+        throw new BadRequestException({
+          message: 'Communication channel is not supported',
+          details: {
+            code: COMMUNICATIONS_ERROR_CODES.unsupportedChannel,
+            channel,
+          },
+        });
+    }
+  }
+}

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

@@ -0,0 +1,55 @@
+export const communicationChannels = ['email', 'sms', 'push'] as const;
+
+export type CommunicationChannel = (typeof communicationChannels)[number];
+
+export type CommunicationMessageKind =
+  | 'email_verification_code'
+  | 'password_reset'
+  | 'welcome_email'
+  | 'login_alert'
+  | 'order_status_changed'
+  | 'communications_probe'
+  | (string & {});
+
+export type CommunicationPayloadValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Date;
+
+export interface CommunicationRecipient {
+  email?: string;
+  phone?: string;
+  pushToken?: string;
+  userId?: string;
+  displayName?: string;
+}
+
+export interface CommunicationMessageInput {
+  kind: CommunicationMessageKind;
+  recipient: CommunicationRecipient;
+  channels: CommunicationChannel[];
+  payload?: Record<string, CommunicationPayloadValue>;
+  locale?: string;
+  metadata?: Record<string, CommunicationPayloadValue>;
+}
+
+export type CommunicationResultStatus = 'sent' | 'stub' | 'skipped';
+
+export interface CommunicationResult {
+  kind: string;
+  channel: CommunicationChannel;
+  provider: string;
+  status: CommunicationResultStatus;
+  messageId: string | null;
+  recipient: string | null;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CommunicationProbeResult {
+  probeId: string;
+  recipient: string;
+  result: CommunicationResult;
+}

package/templates/module-presets/communications/packages/communications/src/dto/send-communications-probe.dto.ts

@@ -0,0 +1,6 @@
+import { IsEmail } from 'class-validator';
+
+export class SendCommunicationsProbeDto {
+  @IsEmail()
+  email!: string;
+}

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,104 @@
+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',
+  providerSendFailed: 'COMMUNICATIONS_EMAIL_PROVIDER_SEND_FAILED',
+} 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,
+        },
+      });
+    }
+
+    try {
+      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,
+      };
+    } catch (error) {
+      const details = this.extractErrorDetails(error);
+      this.logger.error(`email.failed provider=${this.providerId} to=${input.to} details=${JSON.stringify(details)}`);
+      throw new ServiceUnavailableException({
+        message: 'Email delivery failed',
+        details: {
+          code: EMAIL_ERROR_CODES.providerSendFailed,
+          provider: this.providerId,
+          ...details,
+        },
+      });
+    }
+  }
+
+  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;
+  }
+
+  private extractErrorDetails(error: unknown): Record<string, unknown> {
+    if (!error || typeof error !== 'object') {
+      return { raw: String(error) };
+    }
+
+    const candidate = error as {
+      code?: unknown;
+      command?: unknown;
+      response?: unknown;
+      responseCode?: unknown;
+      errno?: unknown;
+      syscall?: unknown;
+      message?: unknown;
+    };
+
+    return {
+      message: typeof candidate.message === 'string' ? candidate.message : String(error),
+      code: candidate.code ?? null,
+      command: candidate.command ?? null,
+      responseCode: candidate.responseCode ?? null,
+      response: candidate.response ?? null,
+      errno: candidate.errno ?? null,
+      syscall: candidate.syscall ?? null,
+    };
+  }
+}

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

@@ -0,0 +1,65 @@
+import { DynamicModule, Global, 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'];
+}
+
+@Global()
+@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,
+    };
+  }
+}