@rytass/bpm-core-nestjs-module 0.5.0 → 0.5.1

package/src/lib/notification/notification-delivery.service.spec.ts

@@ -1,315 +0,0 @@
-import * as nodemailer from 'nodemailer';
-import { ModuleRef } from '@nestjs/core';
-import { Repository } from 'typeorm';
-import { IdentityService } from '../identity/identity.service';
-import { NotificationDeliveryService } from './notification-delivery.service';
-import {
-  BPM_NOTIFICATION_DISPATCHER,
-  BPMNotificationDispatcher,
-} from './notification-dispatcher.token';
-import { NotificationEntity } from './notification.entity';
-import {
-  NotificationChannelEnum,
-  NotificationStatusEnum,
-  NotificationTypeEnum,
-} from './notification.enums';
-import { DEFAULT_BPM_NOTIFICATION_OPTIONS } from './notification-options';
-
-describe('NotificationDeliveryService', () => {
-  afterEach((): void => {
-    jest.restoreAllMocks();
-  });
-
-  it('sends pending email notifications through SMTP and marks them sent', async (): Promise<void> => {
-    const sendMail = jest.fn((): Promise<void> => Promise.resolve());
-    jest.spyOn(nodemailer, 'createTransport').mockReturnValue({
-      sendMail,
-    } as unknown as ReturnType<typeof nodemailer.createTransport>);
-    const notification = createNotification(NotificationChannelEnum.EMAIL);
-    const repository = createNotificationRepository(notification);
-    const service = new NotificationDeliveryService(
-      repository,
-      createModuleRef(),
-    );
-
-    await expect(
-      service.deliverNotification(notification, {
-        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
-        emailEnabled: true,
-        emailFrom: 'BPM <bpm@example.com>',
-        emailSmtpHost: 'smtp.example.com',
-        emailSmtpPassword: 'secret',
-        emailSmtpPort: 587,
-        emailSmtpSecure: false,
-        emailSmtpUsername: 'bpm@example.com',
-      }),
-    ).resolves.toBe(true);
-
-    expect(sendMail).toHaveBeenCalledWith(
-      expect.objectContaining({
-        from: 'BPM <bpm@example.com>',
-        subject: notification.title,
-        text: notification.body,
-        to: 'member-001@example.com',
-      }),
-    );
-    expect(repository.save).toHaveBeenCalledWith(
-      expect.objectContaining({
-        status: NotificationStatusEnum.SENT,
-        deliveryTarget: 'member-001@example.com',
-      }),
-    );
-  });
-
-  it('sends signed webhook notifications', async (): Promise<void> => {
-    const fetchMock = jest.fn(() =>
-      Promise.resolve({
-        ok: true,
-        status: 200,
-      }),
-    );
-    jest
-      .spyOn(globalThis, 'fetch')
-      .mockImplementation(fetchMock as unknown as typeof fetch);
-    const notification = createNotification(NotificationChannelEnum.WEBHOOK);
-    const repository = createNotificationRepository(notification);
-    const service = new NotificationDeliveryService(
-      repository,
-      createModuleRef(),
-    );
-
-    await expect(
-      service.deliverNotification(notification, {
-        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
-        webhookEnabled: true,
-        webhookEndpointUrl: 'https://example.com/bpm-webhook',
-        webhookSigningSecret: 'secret',
-      }),
-    ).resolves.toBe(true);
-
-    expect(fetchMock).toHaveBeenCalledWith(
-      'https://example.com/bpm-webhook',
-      expect.objectContaining({
-        headers: expect.objectContaining({
-          'x-bpm-signature-sha256': expect.any(String),
-        }),
-        method: 'POST',
-      }),
-    );
-    expect(repository.save).toHaveBeenCalledWith(
-      expect.objectContaining({
-        status: NotificationStatusEnum.SENT,
-        deliveryTarget: 'https://example.com/bpm-webhook',
-      }),
-    );
-  });
-
-  it('dispatches email and webhook notifications through a host dispatcher when provided', async (): Promise<void> => {
-    const dispatch = jest.fn((): Promise<string> => Promise.resolve('queue-1'));
-    const notification = createNotification(NotificationChannelEnum.EMAIL);
-    const repository = createNotificationRepository(notification);
-    const service = new NotificationDeliveryService(
-      repository,
-      createModuleRef({
-        dispatch,
-      }),
-    );
-
-    await expect(
-      service.deliverNotification(notification, DEFAULT_BPM_NOTIFICATION_OPTIONS),
-    ).resolves.toBe(true);
-
-    expect(dispatch).toHaveBeenCalledWith(
-      notification,
-      DEFAULT_BPM_NOTIFICATION_OPTIONS,
-    );
-    expect(repository.save).toHaveBeenCalledWith(
-      expect.objectContaining({
-        deliveryTarget: 'queue-1',
-        status: NotificationStatusEnum.SENT,
-      }),
-    );
-  });
-
-  it('records delivery failures and schedules a retry', async (): Promise<void> => {
-    const notification = createNotification(NotificationChannelEnum.EMAIL);
-    const repository = createNotificationRepository(notification);
-    const service = new NotificationDeliveryService(
-      repository,
-      createModuleRef(),
-    );
-
-    await expect(
-      service.deliverNotification(notification, {
-        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
-        emailEnabled: false,
-      }),
-    ).resolves.toBe(false);
-
-    expect(repository.save).toHaveBeenCalledWith(
-      expect.objectContaining({
-        attemptCount: 1,
-        deliveryError: 'EMAIL_DISABLED',
-        nextRetryAt: expect.any(Date),
-        status: NotificationStatusEnum.PENDING,
-      }),
-    );
-  });
-
-  it('uses configured retry policy and marks notifications failed after max attempts', async (): Promise<void> => {
-    const notification = Object.assign(
-      createNotification(NotificationChannelEnum.EMAIL),
-      { attemptCount: 1 },
-    );
-    const repository = createNotificationRepository(notification);
-    const service = new NotificationDeliveryService(
-      repository,
-      createModuleRef(),
-    );
-
-    await expect(
-      service.deliverNotification(notification, {
-        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
-        deliveryMaxAttempts: 2,
-        deliveryRetryBaseDelayMs: 5_000,
-        emailEnabled: false,
-      }),
-    ).resolves.toBe(false);
-
-    expect(repository.save).toHaveBeenCalledWith(
-      expect.objectContaining({
-        attemptCount: 2,
-        nextRetryAt: null,
-        status: NotificationStatusEnum.FAILED,
-      }),
-    );
-  });
-
-  it('uses configured batch size when scanning pending notifications', async (): Promise<void> => {
-    const notification = createNotification(NotificationChannelEnum.IN_APP);
-    const repository = createNotificationRepository(notification);
-    const service = new NotificationDeliveryService(
-      repository,
-      createModuleRef(),
-    );
-
-    await service.deliverPendingNotifications({
-      options: {
-        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
-        deliveryBatchSize: 7,
-      },
-    });
-
-    expect(repository.find).toHaveBeenCalledWith(
-      expect.objectContaining({ take: 7 }),
-    );
-  });
-
-  it('includes stale in-progress notifications in the next delivery scan', async (): Promise<void> => {
-    const notification = createNotification(NotificationChannelEnum.IN_APP);
-    const repository = createNotificationRepository(notification);
-    const service = new NotificationDeliveryService(
-      repository,
-      createModuleRef(),
-    );
-
-    await service.deliverPendingNotifications({
-      now: new Date('2026-05-15T00:10:00.000Z'),
-      options: {
-        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
-        deliveryRetryBaseDelayMs: 60_000,
-      },
-    });
-
-    expect(repository.find).toHaveBeenCalledWith(
-      expect.objectContaining({
-        where: expect.arrayContaining([
-          expect.objectContaining({
-            lastAttemptAt: expect.any(Object),
-            status: NotificationStatusEnum.DELIVERY_IN_PROGRESS,
-          }),
-        ]),
-      }),
-    );
-  });
-});
-
-function createNotification(
-  channel: NotificationChannelEnum,
-): NotificationEntity {
-  return Object.assign(new NotificationEntity(), {
-    attemptCount: 0,
-    body: '請處理待簽任務。',
-    channel,
-    createdAt: new Date('2026-05-15T00:00:00.000Z'),
-    deliveredAt: null,
-    deliveryError: null,
-    deliveryTarget: null,
-    id: 'notification-001',
-    instanceId: 'd6f61a56-8b12-4ab8-9424-a2f7c27874e2',
-    lastAttemptAt: null,
-    nextRetryAt: null,
-    payload: { instanceTitle: '採購申請' },
-    readAt: null,
-    recipientMemberId: 'member-001',
-    sentAt: null,
-    status: NotificationStatusEnum.PENDING,
-    taskId: 'f4fae7b0-eab0-40de-8dfa-7dfbff746980',
-    title: '新的待簽任務',
-    type: NotificationTypeEnum.TASK_ASSIGNED,
-  });
-}
-
-function createNotificationRepository(
-  notification: NotificationEntity,
-): Repository<NotificationEntity> & {
-  readonly find: jest.Mock;
-  readonly save: jest.Mock;
-} {
-  const repository = {
-    find: jest.fn(
-      (): Promise<readonly NotificationEntity[]> =>
-        Promise.resolve([notification]),
-    ),
-    save: jest.fn(
-      (entity: NotificationEntity): Promise<NotificationEntity> =>
-        Promise.resolve(entity),
-    ),
-  };
-
-  return repository as unknown as Repository<NotificationEntity> & {
-    readonly find: jest.Mock;
-    readonly save: jest.Mock;
-  };
-}
-
-function createModuleRef(
-  dispatcher?: BPMNotificationDispatcher,
-): ModuleRef {
-  return {
-    get: (token: unknown): BPMNotificationDispatcher | IdentityService => {
-      if (token === BPM_NOTIFICATION_DISPATCHER && dispatcher) {
-        return dispatcher;
-      }
-
-      if (token !== IdentityService) {
-        throw new Error('Unexpected module token');
-      }
-
-      return {
-        resolveMember: (): Promise<{
-          readonly customFields: Readonly<Record<string, unknown>>;
-          readonly email: string;
-          readonly memberId: string;
-          readonly name: string;
-        }> =>
-          Promise.resolve({
-            customFields: {},
-            email: 'member-001@example.com',
-            memberId: 'member-001',
-            name: '王小明',
-          }),
-      } as unknown as IdentityService;
-    },
-  } as unknown as ModuleRef;
-}

package/src/lib/notification/notification-delivery.service.ts

@@ -1,339 +0,0 @@
-import { createHmac } from 'node:crypto';
-import { Injectable, Logger } from '@nestjs/common';
-import { ModuleRef } from '@nestjs/core';
-import { InjectRepository } from '@nestjs/typeorm';
-import * as nodemailer from 'nodemailer';
-import { In, IsNull, LessThanOrEqual, Repository } from 'typeorm';
-import { IdentityService } from '../identity/identity.service';
-import {
-  BPM_NOTIFICATION_DISPATCHER,
-  BPMNotificationDispatcher,
-} from './notification-dispatcher.token';
-import { NotificationEntity } from './notification.entity';
-import {
-  NotificationChannelEnum,
-  NotificationStatusEnum,
-} from './notification.enums';
-import { BPMResolvedNotificationOptions } from './notification-options';
-
-@Injectable()
-export class NotificationDeliveryService {
-  private readonly logger = new Logger(NotificationDeliveryService.name);
-
-  constructor(
-    @InjectRepository(NotificationEntity)
-    private readonly notificationRepository: Repository<NotificationEntity>,
-    private readonly moduleRef: ModuleRef,
-  ) {}
-
-  async deliverPendingNotifications({
-    limit,
-    now = new Date(),
-    options,
-  }: {
-    readonly limit?: number;
-    readonly now?: Date;
-    readonly options: BPMResolvedNotificationOptions;
-  }): Promise<number> {
-    const deliveryLimit = normalizePositiveInteger(
-      limit,
-      options.deliveryBatchSize,
-    );
-    const pendingNotifications = await this.claimPendingNotifications({
-      claimStaleBefore: new Date(
-        now.getTime() - options.deliveryRetryBaseDelayMs,
-      ),
-      limit: deliveryLimit,
-      now,
-    });
-    const results = await Promise.all(
-      pendingNotifications.map((notification) =>
-        this.deliverNotification(notification, options),
-      ),
-    );
-
-    return results.filter(Boolean).length;
-  }
-
-  async deliverNotification(
-    notification: NotificationEntity,
-    options: BPMResolvedNotificationOptions,
-  ): Promise<boolean> {
-    if (notification.channel === NotificationChannelEnum.IN_APP) {
-      return false;
-    }
-
-    if (
-      notification.status !== NotificationStatusEnum.PENDING &&
-      notification.status !== NotificationStatusEnum.DELIVERY_IN_PROGRESS
-    ) {
-      return false;
-    }
-
-    try {
-      const deliveryTarget = await this.dispatch(notification, options);
-      await this.notificationRepository.save({
-        ...notification,
-        attemptCount: notification.attemptCount + 1,
-        deliveredAt: new Date(),
-        deliveryError: null,
-        deliveryTarget,
-        lastAttemptAt: new Date(),
-        nextRetryAt: null,
-        sentAt: new Date(),
-        status: NotificationStatusEnum.SENT,
-      });
-
-      return true;
-    } catch (error: unknown) {
-      await this.recordDeliveryFailure(
-        notification,
-        readErrorMessage(error),
-        options,
-      );
-
-      return false;
-    }
-  }
-
-  private async claimPendingNotifications({
-    claimStaleBefore,
-    limit,
-    now,
-  }: {
-    readonly claimStaleBefore: Date;
-    readonly limit: number;
-    readonly now: Date;
-  }): Promise<readonly NotificationEntity[]> {
-    if (!this.notificationRepository.manager?.transaction) {
-      return this.notificationRepository.find({
-        order: { createdAt: 'ASC' },
-        take: limit,
-        where: [
-          {
-            nextRetryAt: LessThanOrEqual(now),
-            status: NotificationStatusEnum.PENDING,
-          },
-          {
-            nextRetryAt: IsNull(),
-            status: NotificationStatusEnum.PENDING,
-          },
-          {
-            lastAttemptAt: LessThanOrEqual(claimStaleBefore),
-            status: NotificationStatusEnum.DELIVERY_IN_PROGRESS,
-          },
-        ],
-      });
-    }
-
-    return this.notificationRepository.manager.transaction(
-      async (manager): Promise<readonly NotificationEntity[]> => {
-        const claimedRows = (await manager.query(
-          `
-            UPDATE notifications
-               SET status = $1,
-                   last_attempt_at = $2
-             WHERE id IN (
-               SELECT id
-                 FROM notifications
-                WHERE (
-                    (
-                      status = $3
-                      AND (next_retry_at IS NULL OR next_retry_at <= $2)
-                    )
-                    OR (
-                      status = $5
-                      AND last_attempt_at <= $6
-                    )
-                  )
-                ORDER BY created_at ASC
-                FOR UPDATE SKIP LOCKED
-                LIMIT $4
-             )
-             RETURNING id
-          `,
-          [
-            NotificationStatusEnum.DELIVERY_IN_PROGRESS,
-            now,
-            NotificationStatusEnum.PENDING,
-            limit,
-            NotificationStatusEnum.DELIVERY_IN_PROGRESS,
-            claimStaleBefore,
-          ],
-        )) as readonly { readonly id: string }[];
-        const claimedIds = claimedRows.map((row) => row.id);
-
-        return claimedIds.length
-          ? manager
-              .getRepository(NotificationEntity)
-              .find({ where: { id: In(claimedIds) } })
-          : [];
-      },
-    );
-  }
-
-  private async dispatch(
-    notification: NotificationEntity,
-    options: BPMResolvedNotificationOptions,
-  ): Promise<string> {
-    const hostDispatcher = this.readHostDispatcher();
-
-    if (hostDispatcher) {
-      return hostDispatcher.dispatch(notification, options);
-    }
-
-    return this.dispatchBuiltIn(notification, options);
-  }
-
-  private async dispatchBuiltIn(
-    notification: NotificationEntity,
-    options: BPMResolvedNotificationOptions,
-  ): Promise<string> {
-    if (notification.channel === NotificationChannelEnum.EMAIL) {
-      return this.dispatchEmail(notification, options);
-    }
-
-    if (notification.channel === NotificationChannelEnum.WEBHOOK) {
-      return this.dispatchWebhook(notification, options);
-    }
-
-    throw new Error(`Unsupported notification channel ${notification.channel}`);
-  }
-
-  private readHostDispatcher(): BPMNotificationDispatcher | null {
-    try {
-      return this.moduleRef.get(BPM_NOTIFICATION_DISPATCHER, {
-        strict: false,
-      });
-    } catch {
-      return null;
-    }
-  }
-
-  private async dispatchEmail(
-    notification: NotificationEntity,
-    options: BPMResolvedNotificationOptions,
-  ): Promise<string> {
-    if (
-      !options.emailEnabled ||
-      !options.emailSmtpHost ||
-      !options.emailSmtpPort ||
-      !options.emailSmtpUsername ||
-      !options.emailSmtpPassword ||
-      !options.emailFrom
-    ) {
-      throw new Error('EMAIL_DISABLED');
-    }
-
-    const identityService = this.moduleRef.get(IdentityService, {
-      strict: false,
-    });
-    const recipient = await identityService.resolveMember(
-      notification.recipientMemberId,
-    );
-    const transporter = nodemailer.createTransport({
-      auth: {
-        pass: options.emailSmtpPassword,
-        user: options.emailSmtpUsername,
-      },
-      host: options.emailSmtpHost,
-      port: options.emailSmtpPort,
-      secure: options.emailSmtpSecure,
-    });
-
-    await transporter.sendMail({
-      from: options.emailFrom,
-      subject: notification.title,
-      text: notification.body,
-      to: recipient.email,
-    });
-
-    return recipient.email;
-  }
-
-  private async dispatchWebhook(
-    notification: NotificationEntity,
-    options: BPMResolvedNotificationOptions,
-  ): Promise<string> {
-    if (
-      !options.webhookEnabled ||
-      !options.webhookEndpointUrl ||
-      !options.webhookSigningSecret
-    ) {
-      throw new Error('WEBHOOK_DISABLED');
-    }
-
-    const payload = JSON.stringify({
-      body: notification.body,
-      channel: notification.channel,
-      createdAt: notification.createdAt.toISOString(),
-      id: notification.id,
-      instanceId: notification.instanceId,
-      payload: notification.payload,
-      recipientMemberId: notification.recipientMemberId,
-      taskId: notification.taskId,
-      title: notification.title,
-      type: notification.type,
-    });
-    const signature = createHmac('sha256', options.webhookSigningSecret)
-      .update(payload)
-      .digest('hex');
-    const response = await fetch(options.webhookEndpointUrl, {
-      body: payload,
-      headers: {
-        'content-type': 'application/json',
-        'x-bpm-signature-sha256': signature,
-      },
-      method: 'POST',
-    });
-
-    if (!response.ok) {
-      throw new Error(`WEBHOOK_HTTP_${response.status}`);
-    }
-
-    return options.webhookEndpointUrl;
-  }
-
-  private async recordDeliveryFailure(
-    notification: NotificationEntity,
-    errorMessage: string,
-    options: BPMResolvedNotificationOptions,
-  ): Promise<void> {
-    const attemptCount = notification.attemptCount + 1;
-    const failedPermanently = attemptCount >= options.deliveryMaxAttempts;
-    const now = new Date();
-
-    await this.notificationRepository.save({
-      ...notification,
-      attemptCount,
-      deliveryError: errorMessage,
-      lastAttemptAt: now,
-      nextRetryAt: failedPermanently
-        ? null
-        : new Date(
-            now.getTime() + options.deliveryRetryBaseDelayMs * attemptCount,
-          ),
-      status: failedPermanently
-        ? NotificationStatusEnum.FAILED
-        : NotificationStatusEnum.PENDING,
-    });
-    this.logger.warn(
-      `Notification ${notification.id} delivery failed: ${errorMessage}`,
-    );
-  }
-}
-
-function readErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : 'Unknown delivery error';
-}
-
-function normalizePositiveInteger(
-  value: number | undefined,
-  fallback: number,
-): number {
-  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
-    return fallback;
-  }
-
-  return value;
-}

package/src/lib/notification/notification-dispatcher.token.ts

@@ -1,13 +0,0 @@
-import { InjectionToken } from '@nestjs/common';
-import { NotificationEntity } from './notification.entity';
-import { BPMResolvedNotificationOptions } from './notification-options';
-
-export interface BPMNotificationDispatcher {
-  dispatch(
-    notification: NotificationEntity,
-    options: BPMResolvedNotificationOptions,
-  ): Promise<string>;
-}
-
-export const BPM_NOTIFICATION_DISPATCHER: InjectionToken<BPMNotificationDispatcher> =
-  Symbol('BPM_NOTIFICATION_DISPATCHER');