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

package/CHANGELOG.md

@@ -9,6 +9,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Releases are managed by [`nx release`](https://nx.dev/recipes/nx-release) with
 Conventional Commits — see `nx.json` for the release config.
 
+## 0.5.0 — 2026-07-06
+
+### Added
+
+- Optional `searchPaged(searchText, { page, pageSize })` on `BPMMemberResolver`
+  (returning `{ items, total }`) and the matching optional `searchMembersPaged`
+  on `BPMMemberBaseDirectory`. When a host implements it, BPM delegates
+  pagination and total counting to the host's source (e.g. DB `LIMIT/OFFSET` +
+  `COUNT`) instead of pulling everything through the ~50-cap member-picker
+  `search` and paginating in memory. New exported types `BPMMemberSearchPage`,
+  `BPMMemberSearchPageOptions`, and `BPMMemberBaseSearchPage`.
+
+### Changed
+
+- `searchMembers` and `memberCount` (via `IdentityService`) now detect the new
+  `searchPaged` capability: present → real paged delegation with an accurate
+  total and per-id `member_metadata_cache` backfill of the returned page;
+  absent → the pre-0.5.0 `search`-and-slice-in-memory path, unchanged. The
+  `search?` contract is clarified as member-picker-only (~50 matches, not
+  paginated).
+- Peer dependency `@rytass/bpm-core-shared` now requires ^0.5.0.
+
+> Behavior note: hosts that have **not** implemented `searchMembersPaged` still
+> see the admin members list (`admin/users`) capped by whatever their `search()`
+> returns (~50 rows) with a matching total. Implement `searchMembersPaged` to
+> page a larger directory and report the true total.
+
 ## 0.4.0 — 2026-07-02
 
 ### Added

package/eslint.config.mjs

@@ -0,0 +1,20 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredDependencies: ['graphql'],
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/jest.config.cts

@@ -0,0 +1,15 @@
+module.exports = {
+  displayName: 'bpm-core',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.ts$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+    '^.+\\.js$': 'babel-jest',
+  },
+  moduleNameMapper: {
+    '^cel-js$': '<rootDir>/src/lib/testing/cel-js.jest.ts',
+  },
+  transformIgnorePatterns: ['/node_modules/(?!\\.pnpm/cel-js@|cel-js)'],
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/bpm-core',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-nestjs-module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Embeddable NestJS BPM approval workflow module: workflow engine, approval templates, forms, organization/member contracts, attachments, signatures, notifications, delegation, and TypeORM migrations.",
   "keywords": [
     "bpm",
@@ -141,7 +141,7 @@
     "@nestjs/core": "^11.0.0",
     "@nestjs/graphql": "^13.4.0",
     "@nestjs/typeorm": "^11.0.1",
-    "@rytass/bpm-core-shared": "^0.4.0",
+    "@rytass/bpm-core-shared": "^0.5.0",
     "@rytass/secret-adapter-vault-nestjs": "^0.4.5 || ^0.5.0",
     "express": "^4.0.0 || ^5.0.0",
     "graphql": "^16.0.0",

package/project.json

@@ -0,0 +1,58 @@
+{
+  "name": "bpm-core",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/bpm-core/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/bpm-core",
+        "main": "libs/bpm-core/src/index.ts",
+        "tsConfig": "libs/bpm-core/tsconfig.lib.json",
+        "generatePackageJson": true,
+        "assets": [
+          "libs/bpm-core/*.md",
+          { "input": ".", "glob": "LICENSE", "output": "." }
+        ]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/libs/bpm-core"],
+      "options": {
+        "jestConfig": "libs/bpm-core/jest.config.cts",
+        "passWithNoTests": true
+      }
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsc --noEmit -p libs/bpm-core/tsconfig.lib.json"
+      }
+    },
+    "pkg-quality": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "commands": [
+          "pnpm exec publint dist/libs/bpm-core"
+        ],
+        "parallel": false
+      }
+    },
+    "pkg-quality-attw": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "pnpm exec attw --pack dist/libs/bpm-core"
+      }
+    },
+    "prepublish-check": {
+      "executor": "nx:noop",
+      "dependsOn": ["typecheck", "lint", "test", "build", "pkg-quality"]
+    }
+  }
+}

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

@@ -0,0 +1,45 @@
+import { resolveBPMAttachmentOptions } from './attachment-options';
+
+describe('resolveBPMAttachmentOptions', () => {
+  const originalNodeEnv = process.env.NODE_ENV;
+  let warnSpy: jest.SpiedFunction<typeof console.warn>;
+
+  beforeEach(() => {
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    process.env.NODE_ENV = originalNodeEnv;
+  });
+
+  it('does not warn when NODE_ENV is not production, even with default secret', (): void => {
+    process.env.NODE_ENV = 'development';
+
+    resolveBPMAttachmentOptions();
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('warns when default secret is used under NODE_ENV=production', (): void => {
+    process.env.NODE_ENV = 'production';
+
+    const resolved = resolveBPMAttachmentOptions();
+
+    expect(resolved.signedUrlSecret).toBe('bpm-core-local-attachment-url-key-v1');
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(String(warnSpy.mock.calls[0]?.[0])).toContain(
+      'attachmentSignedUrlSecret is using the built-in local development value',
+    );
+  });
+
+  it('does not warn when a custom secret is supplied under production', (): void => {
+    process.env.NODE_ENV = 'production';
+
+    resolveBPMAttachmentOptions({
+      attachmentSignedUrlSecret: 'my-real-secret',
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

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

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

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

@@ -0,0 +1,60 @@
+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-storage.token.d.ts → attachment-storage.token.ts}

@@ -1,3 +1,5 @@
 import type { Storage } from '@rytass/storages';
-export declare const ATTACHMENT_STORAGE: unique symbol;
+
+export const ATTACHMENT_STORAGE = Symbol('ATTACHMENT_STORAGE');
+
 export type AttachmentStorage = Storage<Readonly<Record<string, unknown>>>;

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

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

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