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

package/src/lib/attachment/attachment-options.ts

@@ -1,130 +0,0 @@
-import { InjectionToken } from '@nestjs/common';
-
-export interface BPMRootAttachmentOptions {
-  /**
-   * Public HTTP base URL used to build signed attachment download and preview
-   * URLs.
-   */
-  readonly attachmentPublicBaseUrl?: string | null;
-
-  /**
-   * Route prefix used by the host application for BPM attachment endpoints.
-   *
-   * Drives both the Nest controller mount path and the path embedded in BPM
-   * signed attachment URLs. Defaults to `/attachments`.
-   */
-  readonly attachmentRoutePrefix?: string | null;
-
-  /**
-   * HMAC secret used to sign attachment download and preview tokens.
-   */
-  readonly attachmentSignedUrlSecret?: string | null;
-
-  /**
-   * Signed attachment URL lifetime in seconds.
-   */
-  readonly attachmentSignedUrlTtlSeconds?: number;
-
-  /**
-   * Storage provider id recorded on attachment metadata.
-   */
-  readonly attachmentStorageProviderId?: string | null;
-}
-
-export interface BPMResolvedAttachmentOptions {
-  readonly publicBaseUrl: string;
-  readonly routePrefix: string;
-  readonly signedUrlSecret: string;
-  readonly signedUrlTtlSeconds: number;
-  readonly storageProviderId: string;
-}
-
-export const BPM_ATTACHMENT_OPTIONS: InjectionToken<BPMResolvedAttachmentOptions> =
-  Symbol('BPM_ATTACHMENT_OPTIONS');
-
-export const DEFAULT_BPM_ATTACHMENT_OPTIONS: BPMResolvedAttachmentOptions = {
-  publicBaseUrl: 'http://localhost:17603',
-  routePrefix: '/attachments',
-  signedUrlSecret: 'bpm-core-local-attachment-url-key-v1',
-  signedUrlTtlSeconds: 300,
-  storageProviderId: 'local',
-};
-
-export function resolveBPMAttachmentOptions(
-  options: BPMRootAttachmentOptions = {},
-): BPMResolvedAttachmentOptions {
-  const resolvedSignedUrlSecret =
-    normalizeText(options.attachmentSignedUrlSecret) ??
-    DEFAULT_BPM_ATTACHMENT_OPTIONS.signedUrlSecret;
-
-  if (
-    resolvedSignedUrlSecret === DEFAULT_BPM_ATTACHMENT_OPTIONS.signedUrlSecret &&
-    process.env.NODE_ENV === 'production'
-  ) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      '[@rytass/bpm-core-nestjs-module] attachmentSignedUrlSecret is using the built-in local development value. Set BPMRootModuleOptions.attachmentSignedUrlSecret to a strong secret before serving production traffic — signed attachment URLs would otherwise be forgeable.',
-    );
-  }
-
-  return {
-    publicBaseUrl: normalizePublicBaseUrl(options.attachmentPublicBaseUrl),
-    routePrefix: normalizeRoutePrefix(options.attachmentRoutePrefix),
-    signedUrlSecret: resolvedSignedUrlSecret,
-    signedUrlTtlSeconds: normalizePositiveInteger(
-      options.attachmentSignedUrlTtlSeconds,
-      DEFAULT_BPM_ATTACHMENT_OPTIONS.signedUrlTtlSeconds,
-    ),
-    storageProviderId:
-      normalizeText(options.attachmentStorageProviderId) ??
-      DEFAULT_BPM_ATTACHMENT_OPTIONS.storageProviderId,
-  };
-}
-
-/**
- * Normalizes an attachment route prefix into the form Nest expects on a
- * controller decorator (no leading slash, no trailing slash).
- *
- * Returns the BPM default `attachments` path when no value is provided.
- */
-export function resolveAttachmentControllerPath(
-  value: string | null | undefined,
-): string {
-  const normalizedPrefix = normalizeRoutePrefix(value);
-
-  return normalizedPrefix.replace(/^\//, '');
-}
-
-function normalizePublicBaseUrl(value: string | null | undefined): string {
-  const normalizedValue =
-    normalizeText(value) ?? DEFAULT_BPM_ATTACHMENT_OPTIONS.publicBaseUrl;
-
-  return normalizedValue.replace(/\/+$/, '');
-}
-
-function normalizeRoutePrefix(value: string | null | undefined): string {
-  const normalizedValue =
-    normalizeText(value) ?? DEFAULT_BPM_ATTACHMENT_OPTIONS.routePrefix;
-  const withLeadingSlash = normalizedValue.startsWith('/')
-    ? normalizedValue
-    : `/${normalizedValue}`;
-
-  return withLeadingSlash.replace(/\/+$/, '');
-}
-
-function normalizeText(value: string | null | undefined): string | null {
-  const trimmedValue = value?.trim() ?? '';
-
-  return trimmedValue || null;
-}
-
-function normalizePositiveInteger(
-  value: number | undefined,
-  fallback: number,
-): number {
-  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
-    return fallback;
-  }
-
-  return value;
-}

package/src/lib/attachment/attachment-storage.provider.spec.ts

@@ -1,79 +0,0 @@
-import { mkdtemp, readFile, rm } from 'fs/promises';
-import { join } from 'path';
-import { tmpdir } from 'os';
-import { AttachmentModule } from './attachment.module';
-import { createLocalAttachmentStorage } from './attachment-storage.provider';
-import {
-  ATTACHMENT_STORAGE,
-  AttachmentStorage,
-} from './attachment-storage.token';
-
-jest.mock('@rytass/storages-adapter-local', () => {
-  const fs = jest.requireActual<typeof import('fs/promises')>('fs/promises');
-  const path = jest.requireActual<typeof import('path')>('path');
-
-  class LocalStorage {
-    private readonly directory: string;
-
-    constructor(options: { readonly directory: string }) {
-      this.directory = options.directory;
-    }
-
-    async write(
-      file: Buffer,
-      options: { readonly filename?: string } = {},
-    ): Promise<{ readonly key: string }> {
-      const filename = options.filename ?? 'file.bin';
-
-      await fs.writeFile(path.join(this.directory, filename), file);
-
-      return { key: filename };
-    }
-  }
-
-  return { LocalStorage };
-});
-
-describe('createLocalAttachmentStorage', () => {
-  it('creates nested local directories before writing adapter files', async (): Promise<void> => {
-    const directory = await mkdtemp(join(tmpdir(), 'bpm-attachments-'));
-    const storage = createLocalAttachmentStorage(directory);
-
-    try {
-      const storedFile = await storage.write(Buffer.from('hello'), {
-        filename: 'instance-001/hello.pdf',
-      });
-
-      await expect(
-        readFile(join(directory, 'instance-001', 'hello.pdf'), 'utf8'),
-      ).resolves.toBe('hello');
-      expect(storedFile.key).toBe('instance-001/hello.pdf');
-    } finally {
-      await rm(directory, { force: true, recursive: true });
-    }
-  });
-
-  it('allows host applications to replace the attachment storage provider', (): void => {
-    const customStorage: AttachmentStorage = {
-      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(),
-    };
-    const customStorageProvider = {
-      provide: ATTACHMENT_STORAGE,
-      useValue: customStorage,
-    };
-    const module = AttachmentModule.forRoot({
-      storageProvider: customStorageProvider,
-    });
-
-    expect(module.providers).toContain(customStorageProvider);
-  });
-});

package/src/lib/attachment/attachment-storage.provider.ts

@@ -1,60 +0,0 @@
-import { Provider } from '@nestjs/common';
-import { mkdir } from 'fs/promises';
-import { dirname, resolve } from 'path';
-import {
-  ATTACHMENT_STORAGE,
-  AttachmentStorage,
-} from './attachment-storage.token';
-
-interface LocalStorageConstructor {
-  new (options: {
-    readonly autoMkdir: boolean;
-    readonly directory: string;
-  }): AttachmentStorage;
-}
-
-interface LocalStorageModule {
-  readonly LocalStorage: LocalStorageConstructor;
-}
-
-export const attachmentStorageProvider: Provider<AttachmentStorage> = {
-  provide: ATTACHMENT_STORAGE,
-  useFactory: (): AttachmentStorage =>
-    createLocalAttachmentStorage(
-      resolve(process.cwd(), '.storage', 'attachments'),
-    ),
-};
-
-export function createLocalAttachmentStorage(
-  directory: string,
-): AttachmentStorage {
-  const storageDirectory = resolve(directory);
-  const LocalStorage = readLocalStorageConstructor();
-  const localStorage = new LocalStorage({
-    autoMkdir: true,
-    directory: storageDirectory,
-  });
-  const write: AttachmentStorage['write'] = async (
-    file,
-    options,
-  ): ReturnType<AttachmentStorage['write']> => {
-    if (options?.filename) {
-      await mkdir(dirname(resolve(storageDirectory, options.filename)), {
-        recursive: true,
-      });
-    }
-
-    return localStorage.write(file, options);
-  };
-
-  return new Proxy(localStorage, {
-    get: (target, property, receiver): unknown =>
-      property === 'write' ? write : Reflect.get(target, property, receiver),
-  }) as AttachmentStorage;
-}
-
-function readLocalStorageConstructor(): LocalStorageConstructor {
-  const adapter = require('@rytass/storages-adapter-local') as LocalStorageModule;
-
-  return adapter.LocalStorage;
-}

package/src/lib/attachment/attachment.controller.ts

@@ -1,39 +0,0 @@
-import {
-  Controller,
-  Get,
-  Param,
-  Query,
-  Res,
-  StreamableFile,
-} from '@nestjs/common';
-import type { Response } from 'express';
-import { AttachmentService } from './attachment.service';
-
-@Controller('attachments')
-export class AttachmentController {
-  constructor(private readonly attachmentService: AttachmentService) {}
-
-  @Get(':id/download')
-  async downloadAttachment(
-    @Param('id') id: string,
-    @Query('token') token: string,
-    @Query('disposition') disposition: 'attachment' | 'inline' = 'attachment',
-    @Res({ passthrough: true }) response: Response,
-  ): Promise<StreamableFile> {
-    const { attachment, buffer } =
-      await this.attachmentService.readSignedAttachment({
-        disposition,
-        id,
-        token,
-      });
-
-    response.setHeader('Content-Type', attachment.mimeType);
-    response.setHeader(
-      'Content-Disposition',
-      `${disposition}; filename="${encodeURIComponent(attachment.filename)}"`,
-    );
-    response.setHeader('Content-Length', String(buffer.length));
-
-    return new StreamableFile(buffer);
-  }
-}

package/src/lib/attachment/attachment.entity.ts

@@ -1,59 +0,0 @@
-import { Field, ID, ObjectType } from '@nestjs/graphql';
-import {
-  Column,
-  CreateDateColumn,
-  Entity,
-  PrimaryGeneratedColumn,
-} from 'typeorm';
-
-@Entity('attachments')
-@ObjectType('Attachment')
-export class AttachmentEntity {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(() => ID)
-  id!: string;
-
-  @Column('uuid', { name: 'instance_id', nullable: true })
-  @Field(() => ID, { nullable: true })
-  instanceId!: string | null;
-
-  @Column('uuid', { name: 'task_id', nullable: true })
-  @Field(() => ID, { nullable: true })
-  taskId!: string | null;
-
-  @Column('text', { name: 'form_field_path', nullable: true })
-  @Field(() => String, { nullable: true })
-  formFieldPath!: string | null;
-
-  @Column('text', { name: 'uploader_member_id' })
-  @Field()
-  uploaderMemberId!: string;
-
-  @Column('text')
-  @Field()
-  filename!: string;
-
-  @Column('text', { name: 'mime_type' })
-  @Field()
-  mimeType!: string;
-
-  @Column('bigint', { name: 'size_bytes' })
-  @Field()
-  sizeBytes!: string;
-
-  @Column('text', { name: 'storage_provider' })
-  @Field()
-  storageProvider!: string;
-
-  @Column('text', { name: 'storage_key' })
-  @Field()
-  storageKey!: string;
-
-  @Column('text', { name: 'checksum_sha256' })
-  @Field()
-  checksumSha256!: string;
-
-  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
-  @Field()
-  createdAt!: Date;
-}

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

@@ -1,149 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,65 +0,0 @@
-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,
-    });
-  }
-}