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

package/src/lib/attachment/attachment.module.ts

@@ -0,0 +1,149 @@
+import {
+  DynamicModule,
+  Global,
+  InjectionToken,
+  Module,
+  Provider,
+} from '@nestjs/common';
+import { PATH_METADATA } from '@nestjs/common/constants';
+import { ModuleMetadata } from '@nestjs/common/interfaces';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { ApprovalInstanceEntity } from '../workflow-engine/approval-instance.entity';
+import { TaskCandidateEntity } from '../workflow-engine/task-candidate.entity';
+import { TaskDecisionEntity } from '../workflow-engine/task-decision.entity';
+import { TaskEntity } from '../workflow-engine/task.entity';
+import { AttachmentController } from './attachment.controller';
+import { AttachmentEntity } from './attachment.entity';
+import { AttachmentMutations } from './attachment.mutations';
+import { AttachmentQueries } from './attachment.queries';
+import { attachmentStorageProvider } from './attachment-storage.provider';
+import { AttachmentStorage } from './attachment-storage.token';
+import { AttachmentService } from './attachment.service';
+import {
+  BPM_ATTACHMENT_OPTIONS,
+  BPMRootAttachmentOptions,
+  resolveAttachmentControllerPath,
+  resolveBPMAttachmentOptions,
+} from './attachment-options';
+
+export interface AttachmentModuleOptions extends BPMRootAttachmentOptions {
+  readonly imports?: ModuleMetadata['imports'];
+  readonly storageProvider?: Provider<AttachmentStorage>;
+}
+
+export interface AttachmentModuleAsyncOptions extends Pick<
+  ModuleMetadata,
+  'imports'
+> {
+  /**
+   * Controller mount path used by the BPM attachment endpoints.
+   *
+   * Set at module wiring time because Nest reads the controller path metadata
+   * synchronously when the application starts. Async secrets cannot drive this
+   * value; only static URL routing decisions should set it.
+   *
+   * Defaults to `/attachments`.
+   */
+  readonly attachmentRoutePrefix?: string | null;
+  readonly inject?: readonly InjectionToken[];
+  readonly storageProvider?: Provider<AttachmentStorage>;
+  readonly useFactory: (
+    ...args: readonly unknown[]
+  ) => BPMRootAttachmentOptions | Promise<BPMRootAttachmentOptions>;
+}
+
+/**
+ * Applies the resolved attachment route prefix to `AttachmentController`'s
+ * Nest path metadata.
+ *
+ * Nest reads controller path metadata once at application bootstrap, so this
+ * helper must run before Nest finalizes route registration. It is safe to call
+ * multiple times within the same process as long as every BPM host agrees on
+ * a single prefix.
+ */
+function applyAttachmentControllerPath(
+  attachmentRoutePrefix: string | null | undefined,
+): void {
+  const controllerPath = resolveAttachmentControllerPath(attachmentRoutePrefix);
+
+  Reflect.defineMetadata(PATH_METADATA, controllerPath, AttachmentController);
+}
+
+const ATTACHMENT_MODULE_IMPORTS = [
+  TypeOrmModule.forFeature([
+    ApprovalInstanceEntity,
+    AttachmentEntity,
+    TaskCandidateEntity,
+    TaskDecisionEntity,
+    TaskEntity,
+  ]),
+];
+
+const ATTACHMENT_MODULE_CONTROLLERS = [AttachmentController];
+const ATTACHMENT_MODULE_PROVIDERS = [
+  AttachmentMutations,
+  AttachmentQueries,
+  AttachmentService,
+];
+const ATTACHMENT_MODULE_EXPORTS = [AttachmentService];
+
+@Global()
+@Module({
+  imports: ATTACHMENT_MODULE_IMPORTS,
+  controllers: ATTACHMENT_MODULE_CONTROLLERS,
+  providers: [
+    ...ATTACHMENT_MODULE_PROVIDERS,
+    attachmentStorageProvider,
+    createAttachmentOptionsProvider(),
+  ],
+  exports: ATTACHMENT_MODULE_EXPORTS,
+})
+export class AttachmentModule {
+  static forRoot(options: AttachmentModuleOptions = {}): DynamicModule {
+    applyAttachmentControllerPath(options.attachmentRoutePrefix);
+
+    return {
+      controllers: ATTACHMENT_MODULE_CONTROLLERS,
+      exports: ATTACHMENT_MODULE_EXPORTS,
+      imports: [...(options.imports ?? []), ...ATTACHMENT_MODULE_IMPORTS],
+      module: AttachmentModule,
+      providers: [
+        ...ATTACHMENT_MODULE_PROVIDERS,
+        options.storageProvider ?? attachmentStorageProvider,
+        createAttachmentOptionsProvider(options),
+      ],
+    };
+  }
+
+  static forRootAsync(options: AttachmentModuleAsyncOptions): DynamicModule {
+    applyAttachmentControllerPath(options.attachmentRoutePrefix);
+
+    return {
+      controllers: ATTACHMENT_MODULE_CONTROLLERS,
+      exports: ATTACHMENT_MODULE_EXPORTS,
+      imports: [...(options.imports ?? []), ...ATTACHMENT_MODULE_IMPORTS],
+      module: AttachmentModule,
+      providers: [
+        ...ATTACHMENT_MODULE_PROVIDERS,
+        options.storageProvider ?? attachmentStorageProvider,
+        {
+          inject: [...(options.inject ?? [])],
+          provide: BPM_ATTACHMENT_OPTIONS,
+          useFactory: async (
+            ...args: readonly unknown[]
+          ): Promise<ReturnType<typeof resolveBPMAttachmentOptions>> =>
+            resolveBPMAttachmentOptions(await options.useFactory(...args)),
+        },
+      ],
+    };
+  }
+}
+
+function createAttachmentOptionsProvider(
+  options: BPMRootAttachmentOptions = {},
+): Provider {
+  return {
+    provide: BPM_ATTACHMENT_OPTIONS,
+    useValue: resolveBPMAttachmentOptions(options),
+  };
+}

package/src/lib/attachment/attachment.mutations.ts

@@ -0,0 +1,22 @@
+import { Args, Mutation, Resolver } from '@nestjs/graphql';
+import { BPMAuthenticated, BPMCurrentMemberId } from '../bpm-auth';
+import { AttachmentEntity } from './attachment.entity';
+import { AttachmentService } from './attachment.service';
+import { UploadAttachmentInput } from './dto/upload-attachment.input';
+
+@Resolver()
+@BPMAuthenticated()
+export class AttachmentMutations {
+  constructor(private readonly attachmentService: AttachmentService) {}
+
+  @Mutation(() => AttachmentEntity)
+  async uploadAttachment(
+    @Args('input') input: UploadAttachmentInput,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<AttachmentEntity> {
+    return this.attachmentService.uploadAttachment({
+      ...input,
+      uploaderMemberId: currentMemberId,
+    });
+  }
+}

package/src/lib/attachment/attachment.queries.ts

@@ -0,0 +1,65 @@
+import { Args, Query, Resolver } from '@nestjs/graphql';
+import { BPMAuthenticated, BPMCurrentMemberId } from '../bpm-auth';
+import { AttachmentEntity } from './attachment.entity';
+import { AttachmentService } from './attachment.service';
+
+@Resolver()
+@BPMAuthenticated()
+export class AttachmentQueries {
+  constructor(private readonly attachmentService: AttachmentService) {}
+
+  @Query(() => [AttachmentEntity])
+  async attachments(
+    @Args('instanceId', { type: () => String }) instanceId: string,
+    @Args('taskId', { nullable: true, type: () => String })
+    taskId?: string | null,
+    @Args('formFieldPath', { nullable: true, type: () => String })
+    formFieldPath?: string | null,
+    @BPMCurrentMemberId() currentMemberId?: string,
+  ): Promise<readonly AttachmentEntity[]> {
+    return this.attachmentService.listAttachments({
+      formFieldPath: formFieldPath ?? null,
+      instanceId,
+      requestedByMemberId: currentMemberId,
+      taskId: taskId ?? null,
+    });
+  }
+
+  @Query(() => String)
+  async attachmentDownloadUrl(
+    @Args('id', { type: () => String }) id: string,
+    @Args('requestedByMemberId', {
+      deprecationReason:
+        'Ignored. The current authenticated BPM member is always used.',
+      nullable: true,
+      type: () => String,
+    })
+    _requestedByMemberId: string | null,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<string> {
+    return this.attachmentService.createSignedUrl({
+      disposition: 'attachment',
+      id,
+      requestedByMemberId: currentMemberId,
+    });
+  }
+
+  @Query(() => String)
+  async attachmentPreviewUrl(
+    @Args('id', { type: () => String }) id: string,
+    @Args('requestedByMemberId', {
+      deprecationReason:
+        'Ignored. The current authenticated BPM member is always used.',
+      nullable: true,
+      type: () => String,
+    })
+    _requestedByMemberId: string | null,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<string> {
+    return this.attachmentService.createSignedUrl({
+      disposition: 'inline',
+      id,
+      requestedByMemberId: currentMemberId,
+    });
+  }
+}

package/src/lib/attachment/attachment.service.spec.ts

@@ -0,0 +1,319 @@
+import { EntityManager, ObjectLiteral, Repository } from 'typeorm';
+import { ApprovalInstanceEntity } from '../workflow-engine/approval-instance.entity';
+import { TaskCandidateEntity } from '../workflow-engine/task-candidate.entity';
+import { TaskDecisionEntity } from '../workflow-engine/task-decision.entity';
+import { TaskEntity } from '../workflow-engine/task.entity';
+import { AttachmentStorage } from './attachment-storage.token';
+import { AttachmentEntity } from './attachment.entity';
+import { AttachmentService } from './attachment.service';
+
+describe('AttachmentService', () => {
+  afterEach((): void => {
+    jest.restoreAllMocks();
+  });
+
+  it('stores uploads through the configured storage adapter and binds form attachment ids to an instance', async (): Promise<void> => {
+    const attachments: AttachmentEntity[] = [];
+    const storage = createStorage();
+    const repository = createAttachmentRepository(attachments);
+    const service = new AttachmentService(
+      repository,
+      createRepository<ApprovalInstanceEntity>({}),
+      createRepository<TaskEntity>({}),
+      createRepository<TaskCandidateEntity>({}),
+      createRepository<TaskDecisionEntity>({}),
+      storage,
+    );
+
+    const attachment = await service.uploadAttachment({
+      checksumSha256:
+        '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
+      contentBase64: Buffer.from('hello').toString('base64'),
+      filename: 'hello.pdf',
+      formFieldPath: 'form.file',
+      instanceId: null,
+      mimeType: 'application/pdf',
+      sizeBytes: 5,
+      taskId: null,
+      uploaderMemberId: 'member-001',
+    });
+
+    expect(storage.write).toHaveBeenCalledWith(expect.any(Buffer), {
+      contentType: 'application/pdf',
+      filename: `${attachment.id}/hello.pdf`,
+    });
+
+    await service.bindFormDataAttachmentsToInstance(createManager(repository), {
+      formData: { file: [attachment.id] },
+      instanceId: '8e3fd0fc-cc1e-43f5-9601-017dd26ad8ce',
+    });
+
+    expect(attachments[0]).toMatchObject({
+      formFieldPath: 'form.file',
+      instanceId: '8e3fd0fc-cc1e-43f5-9601-017dd26ad8ce',
+    });
+  });
+
+  it('builds signed URLs with configured public URL, TTL, and signing secret', async (): Promise<void> => {
+    jest
+      .spyOn(Date, 'now')
+      .mockReturnValue(new Date('2026-05-15T10:00:00.000Z').getTime());
+    const attachments: AttachmentEntity[] = [];
+    const storage = createStorage();
+    const repository = createAttachmentRepository(attachments);
+    const service = new AttachmentService(
+      repository,
+      createRepository<ApprovalInstanceEntity>({}),
+      createRepository<TaskEntity>({}),
+      createRepository<TaskCandidateEntity>({}),
+      createRepository<TaskDecisionEntity>({}),
+      storage,
+      {
+        publicBaseUrl: 'https://bpm.example.com',
+        routePrefix: '/api/attachments',
+        signedUrlSecret: 'attachment-secret',
+        signedUrlTtlSeconds: 60,
+        storageProviderId: 'local',
+      },
+    );
+
+    const attachment = await service.uploadAttachment({
+      checksumSha256:
+        '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
+      contentBase64: Buffer.from('hello').toString('base64'),
+      filename: 'hello.pdf',
+      formFieldPath: 'form.file',
+      instanceId: null,
+      mimeType: 'application/pdf',
+      sizeBytes: 5,
+      taskId: null,
+      uploaderMemberId: 'member-001',
+    });
+    const signedUrl = await service.createSignedUrl({
+      disposition: 'inline',
+      id: attachment.id,
+      requestedByMemberId: 'member-001',
+    });
+    const url = new URL(signedUrl);
+
+    await expect(
+      service.readSignedAttachment({
+        disposition: 'inline',
+        id: attachment.id,
+        token: url.searchParams.get('token') ?? '',
+      }),
+    ).resolves.toMatchObject({ attachment });
+    expect(url.origin).toBe('https://bpm.example.com');
+    expect(url.pathname).toBe(`/api/attachments/${attachment.id}/download`);
+    expect(url.searchParams.get('disposition')).toBe('inline');
+  });
+
+  it('records custom storage provider metadata and uses configured signed URL route prefix', async (): Promise<void> => {
+    const attachments: AttachmentEntity[] = [];
+    const service = new AttachmentService(
+      createAttachmentRepository(attachments),
+      createRepository<ApprovalInstanceEntity>({}),
+      createRepository<TaskEntity>({}),
+      createRepository<TaskCandidateEntity>({}),
+      createRepository<TaskDecisionEntity>({}),
+      createStorage(),
+      {
+        publicBaseUrl: 'https://bpm.example.com',
+        routePrefix: '/internal/bpm/files',
+        signedUrlSecret: 'attachment-secret',
+        signedUrlTtlSeconds: 60,
+        storageProviderId: 's3',
+      },
+    );
+
+    const attachment = await service.uploadAttachment({
+      checksumSha256:
+        '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
+      contentBase64: Buffer.from('hello').toString('base64'),
+      filename: 'hello.pdf',
+      formFieldPath: 'form.file',
+      instanceId: null,
+      mimeType: 'application/pdf',
+      sizeBytes: 5,
+      taskId: null,
+      uploaderMemberId: 'member-001',
+    });
+    const signedUrl = await service.createSignedUrl({
+      disposition: 'attachment',
+      id: attachment.id,
+      requestedByMemberId: 'member-001',
+    });
+    const url = new URL(signedUrl);
+
+    expect(attachment.storageProvider).toBe('s3');
+    expect(url.pathname).toBe(
+      `/internal/bpm/files/${attachment.id}/download`,
+    );
+  });
+
+  it('allows workflow-related members to read instance attachments', async (): Promise<void> => {
+    const attachment = createAttachment({
+      instanceId: '8e3fd0fc-cc1e-43f5-9601-017dd26ad8ce',
+      uploaderMemberId: 'member-uploader',
+    });
+    const service = new AttachmentService(
+      createAttachmentRepository([attachment]),
+      createRepository<ApprovalInstanceEntity>({
+        findOne: (): Promise<ApprovalInstanceEntity> =>
+          Promise.resolve(
+            Object.assign(new ApprovalInstanceEntity(), {
+              id: '8e3fd0fc-cc1e-43f5-9601-017dd26ad8ce',
+              initiatorMemberId: 'member-initiator',
+            }),
+          ),
+      }),
+      createRepository<TaskEntity>({
+        find: (): Promise<readonly TaskEntity[]> =>
+          Promise.resolve([
+            Object.assign(new TaskEntity(), {
+              assigneeMemberId: 'member-assignee',
+              id: 'task-1',
+              instanceId: '8e3fd0fc-cc1e-43f5-9601-017dd26ad8ce',
+              originalAssigneeMemberId: 'member-original-assignee',
+            }),
+          ]),
+      }),
+      createRepository<TaskCandidateEntity>({
+        find: (): Promise<readonly TaskCandidateEntity[]> =>
+          Promise.resolve([
+            Object.assign(new TaskCandidateEntity(), {
+              memberId: 'member-candidate',
+              originalMemberId: 'member-original-candidate',
+              taskId: 'task-1',
+            }),
+          ]),
+      }),
+      createRepository<TaskDecisionEntity>({
+        find: (): Promise<readonly TaskDecisionEntity[]> =>
+          Promise.resolve([
+            Object.assign(new TaskDecisionEntity(), {
+              decidedByMemberId: 'member-decision-actor',
+              taskId: 'task-1',
+            }),
+          ]),
+      }),
+      createStorage(),
+    );
+
+    await expect(
+      service.listAttachments({
+        instanceId: '8e3fd0fc-cc1e-43f5-9601-017dd26ad8ce',
+        requestedByMemberId: 'member-original-candidate',
+      }),
+    ).resolves.toEqual([attachment]);
+    await expect(
+      service.createSignedUrl({
+        disposition: 'attachment',
+        id: attachment.id,
+        requestedByMemberId: 'member-decision-actor',
+      }),
+    ).resolves.toContain(`/attachments/${attachment.id}/download`);
+    await expect(
+      service.listAttachments({
+        instanceId: '8e3fd0fc-cc1e-43f5-9601-017dd26ad8ce',
+        requestedByMemberId: 'member-unrelated',
+      }),
+    ).resolves.toEqual([]);
+  });
+});
+
+function createStorage(): AttachmentStorage & {
+  readonly write: jest.Mock;
+} {
+  return {
+    batchWrite: jest.fn(),
+    converterManager: {} as AttachmentStorage['converterManager'],
+    getBufferFilename: jest.fn(),
+    getExtension: jest.fn(),
+    getStreamFilename: jest.fn(),
+    hashAlgorithm: 'sha256',
+    isExists: jest.fn(),
+    read: jest.fn(),
+    remove: jest.fn(),
+    write: jest.fn((_buffer: Buffer, options: { readonly filename: string }) =>
+      Promise.resolve({ key: options.filename }),
+    ),
+  };
+}
+
+function createAttachmentRepository(
+  attachments: AttachmentEntity[],
+): Repository<AttachmentEntity> {
+  const repository = {
+    create: (entity: Partial<AttachmentEntity>): AttachmentEntity =>
+      Object.assign(new AttachmentEntity(), entity),
+    find: (): Promise<readonly AttachmentEntity[]> =>
+      Promise.resolve(attachments),
+    findOne: ({
+      where,
+    }: {
+      readonly where: { readonly id: string };
+    }): Promise<AttachmentEntity | null> =>
+      Promise.resolve(
+        attachments.find((attachment) => attachment.id === where.id) ?? null,
+      ),
+    save: (
+      entityOrEntities: AttachmentEntity | readonly AttachmentEntity[],
+    ): Promise<AttachmentEntity | readonly AttachmentEntity[]> => {
+      const entities = Array.isArray(entityOrEntities)
+        ? entityOrEntities
+        : [entityOrEntities];
+
+      entities.forEach((entity) => {
+        const currentIndex = attachments.findIndex(
+          (attachment) => attachment.id === entity.id,
+        );
+
+        if (currentIndex === -1) {
+          attachments.push(entity);
+        } else {
+          attachments[currentIndex] = entity;
+        }
+      });
+
+      return Promise.resolve(entityOrEntities);
+    },
+  };
+
+  return repository as unknown as Repository<AttachmentEntity>;
+}
+
+function createAttachment(
+  value: Partial<AttachmentEntity>,
+): AttachmentEntity {
+  return Object.assign(new AttachmentEntity(), {
+    checksumSha256:
+      '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
+    createdAt: new Date('2026-05-15T10:00:00.000Z'),
+    filename: 'hello.pdf',
+    formFieldPath: 'form.file',
+    id: '9dd3f2e8-6d7e-4f28-8801-f6859b25669e',
+    instanceId: null,
+    mimeType: 'application/pdf',
+    sizeBytes: '5',
+    storageKey: 'hello.pdf',
+    storageProvider: 'local',
+    taskId: null,
+    uploaderMemberId: 'member-001',
+    ...value,
+  });
+}
+
+function createRepository<TEntity extends ObjectLiteral>(
+  value: Readonly<Record<string, unknown>>,
+): Repository<TEntity> {
+  return value as unknown as Repository<TEntity>;
+}
+
+function createManager(
+  repository: Repository<AttachmentEntity>,
+): EntityManager {
+  return {
+    getRepository: (): Repository<AttachmentEntity> => repository,
+  } as unknown as EntityManager;
+}