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

package/src/lib/identity/identity.service.ts

@@ -0,0 +1,277 @@
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { In, Repository } from 'typeorm';
+import { MemberMetadata } from '@rytass/bpm-core-shared';
+import {
+  BPM_IDENTITY_OPTIONS,
+  BPMResolvedIdentityOptions,
+  DEFAULT_BPM_IDENTITY_OPTIONS,
+} from './identity-options';
+import { MemberMetadataCacheEntity } from './member-metadata-cache.entity';
+import { MEMBER_RESOLVER, MemberResolver } from './member-resolver.interface';
+
+const DEFAULT_MEMBER_PAGE = 1;
+const DEFAULT_MEMBER_PAGE_SIZE = 10;
+const MAX_MEMBER_PAGE_SIZE = 100;
+
+interface SearchMembersOptions {
+  readonly page?: number;
+  readonly pageSize?: number;
+}
+
+const normalizePage = (page?: number): number =>
+  Number.isInteger(page) && page !== undefined && page > 0
+    ? page
+    : DEFAULT_MEMBER_PAGE;
+
+const normalizePageSize = (pageSize?: number): number => {
+  if (!Number.isInteger(pageSize) || pageSize === undefined || pageSize <= 0) {
+    return DEFAULT_MEMBER_PAGE_SIZE;
+  }
+
+  return Math.min(pageSize, MAX_MEMBER_PAGE_SIZE);
+};
+
+const paginateMembers = (
+  members: readonly MemberMetadata[],
+  options: SearchMembersOptions,
+): readonly MemberMetadata[] => {
+  const page = normalizePage(options.page);
+  const pageSize = normalizePageSize(options.pageSize);
+  const offset = (page - 1) * pageSize;
+
+  return members.slice(offset, offset + pageSize);
+};
+
+@Injectable()
+export class IdentityService {
+  constructor(
+    @InjectRepository(MemberMetadataCacheEntity)
+    private readonly cacheRepository: Repository<MemberMetadataCacheEntity>,
+    @Inject(MEMBER_RESOLVER)
+    private readonly memberResolver: MemberResolver,
+    @Optional()
+    @Inject(BPM_IDENTITY_OPTIONS)
+    private readonly identityOptions: BPMResolvedIdentityOptions = DEFAULT_BPM_IDENTITY_OPTIONS,
+  ) {}
+
+  async resolveMember(memberId: string): Promise<MemberMetadata> {
+    const now = new Date();
+    const cached = await this.cacheRepository.findOne({ where: { memberId } });
+
+    if (cached && cached.expiresAt > now) {
+      return cached.metadata;
+    }
+
+    const metadata = await this.memberResolver.resolve(memberId);
+    const fetchedAt = now;
+    const expiresAt = new Date(
+      now.getTime() + this.identityOptions.memberMetadataCacheTtlMs,
+    );
+
+    const cacheEntity = cached ?? new MemberMetadataCacheEntity();
+    cacheEntity.fetchedAt = fetchedAt;
+    cacheEntity.expiresAt = expiresAt;
+    cacheEntity.memberId = memberId;
+    cacheEntity.metadata = metadata;
+
+    await this.cacheRepository.save(cacheEntity);
+
+    return metadata;
+  }
+
+  async resolveMembers(
+    memberIds: readonly string[],
+  ): Promise<readonly MemberMetadata[]> {
+    const uniqueMemberIds = [...new Set(memberIds)].filter(
+      (memberId) => memberId.length > 0,
+    );
+
+    if (uniqueMemberIds.length === 0) {
+      return [];
+    }
+
+    const now = new Date();
+    const cachedRows = await this.cacheRepository.find({
+      where: { memberId: In([...uniqueMemberIds]) },
+    });
+    const cacheEntityByMemberId = new Map(
+      cachedRows.map((row): readonly [string, MemberMetadataCacheEntity] => [
+        row.memberId,
+        row,
+      ]),
+    );
+    const metadataByMemberId = new Map<string, MemberMetadata>();
+    const staleMemberIds: string[] = [];
+
+    for (const memberId of uniqueMemberIds) {
+      const cached = cacheEntityByMemberId.get(memberId);
+
+      if (cached && cached.expiresAt > now) {
+        metadataByMemberId.set(memberId, cached.metadata);
+      } else {
+        staleMemberIds.push(memberId);
+      }
+    }
+
+    if (staleMemberIds.length > 0) {
+      const resolvedMap =
+        await this.memberResolver.resolveMany(staleMemberIds);
+      const expiresAt = new Date(
+        now.getTime() + this.identityOptions.memberMetadataCacheTtlMs,
+      );
+      const entitiesToSave: MemberMetadataCacheEntity[] = [];
+
+      for (const memberId of staleMemberIds) {
+        const metadata = resolvedMap.get(memberId);
+
+        if (!metadata) {
+          continue;
+        }
+
+        const cacheEntity =
+          cacheEntityByMemberId.get(memberId) ??
+          new MemberMetadataCacheEntity();
+
+        cacheEntity.memberId = memberId;
+        cacheEntity.metadata = metadata;
+        cacheEntity.fetchedAt = now;
+        cacheEntity.expiresAt = expiresAt;
+
+        entitiesToSave.push(cacheEntity);
+        metadataByMemberId.set(memberId, metadata);
+      }
+
+      if (entitiesToSave.length > 0) {
+        await this.cacheRepository.save(entitiesToSave);
+      }
+    }
+
+    return memberIds
+      .map((memberId) => metadataByMemberId.get(memberId))
+      .filter((metadata): metadata is MemberMetadata => Boolean(metadata));
+  }
+
+  async listCachedMembers(): Promise<readonly MemberMetadataCacheEntity[]> {
+    return this.cacheRepository.find({ order: { memberId: 'ASC' } });
+  }
+
+  async countMembers(searchText: string): Promise<number> {
+    if (this.memberResolver.searchPaged) {
+      const page = await this.memberResolver.searchPaged(searchText, {
+        page: DEFAULT_MEMBER_PAGE,
+        pageSize: 1,
+      });
+
+      return page.total;
+    }
+
+    const members = await this.searchAllMembers(searchText);
+
+    return members.length;
+  }
+
+  async searchMembers(
+    searchText: string,
+    options: SearchMembersOptions = {},
+  ): Promise<readonly MemberMetadata[]> {
+    const wantsPagination =
+      options.page !== undefined || options.pageSize !== undefined;
+
+    if (wantsPagination && this.memberResolver.searchPaged) {
+      const page = await this.memberResolver.searchPaged(searchText, {
+        page: normalizePage(options.page),
+        pageSize: normalizePageSize(options.pageSize),
+      });
+
+      await this.cacheMemberMetadata(page.items);
+
+      return page.items;
+    }
+
+    const members = await this.searchAllMembers(searchText);
+
+    if (!wantsPagination) {
+      return members;
+    }
+
+    return paginateMembers(members, options);
+  }
+
+  /**
+   * Backfills the per-id `member_metadata_cache` rows for members
+   * returned by a paged search, reusing the same row entities and TTL as
+   * `resolveMany`. Unlike `resolveMany` (which only rewrites rows it had
+   * to re-fetch), every returned member is refreshed here since a paged
+   * search always carries authoritative host data. The page query itself
+   * is never row-cached; only the individual member metadata is.
+   */
+  private async cacheMemberMetadata(
+    members: readonly MemberMetadata[],
+  ): Promise<void> {
+    if (members.length === 0) {
+      return;
+    }
+
+    const now = new Date();
+    const expiresAt = new Date(
+      now.getTime() + this.identityOptions.memberMetadataCacheTtlMs,
+    );
+    const memberIds = members.map((member) => member.memberId);
+    const existingRows = await this.cacheRepository.find({
+      where: { memberId: In([...memberIds]) },
+    });
+    const existingRowByMemberId = new Map(
+      existingRows.map((row): readonly [string, MemberMetadataCacheEntity] => [
+        row.memberId,
+        row,
+      ]),
+    );
+    const seenMemberIds = new Set<string>();
+    const entitiesToSave: MemberMetadataCacheEntity[] = [];
+
+    for (const metadata of members) {
+      if (seenMemberIds.has(metadata.memberId)) {
+        continue;
+      }
+
+      seenMemberIds.add(metadata.memberId);
+
+      const cacheEntity =
+        existingRowByMemberId.get(metadata.memberId) ??
+        new MemberMetadataCacheEntity();
+
+      cacheEntity.memberId = metadata.memberId;
+      cacheEntity.metadata = metadata;
+      cacheEntity.fetchedAt = now;
+      cacheEntity.expiresAt = expiresAt;
+
+      entitiesToSave.push(cacheEntity);
+    }
+
+    await this.cacheRepository.save(entitiesToSave);
+  }
+
+  private async searchAllMembers(
+    searchText: string,
+  ): Promise<readonly MemberMetadata[]> {
+    if (this.memberResolver.search) {
+      return this.memberResolver.search(searchText);
+    }
+
+    const normalizedSearchText = searchText.trim().toLocaleLowerCase();
+    const cachedMembers = await this.listCachedMembers();
+
+    return cachedMembers
+      .map((member) => member.metadata)
+      .filter((metadata) => {
+        if (!normalizedSearchText) {
+          return true;
+        }
+
+        return [metadata.email, metadata.memberId, metadata.name].some(
+          (value) => value.toLocaleLowerCase().includes(normalizedSearchText),
+        );
+      });
+  }
+}

package/src/lib/identity/member-base.adapter.spec.ts

@@ -0,0 +1,122 @@
+import {
+  BPMMemberBaseResolverAdapter,
+  createBPMAuthContextFromMemberBaseMember,
+} from './member-base.adapter';
+
+interface TestMemberBaseMember {
+  readonly email: string;
+  readonly id: string;
+  readonly name: string;
+  readonly permissions: readonly string[];
+  readonly roles: readonly string[];
+}
+
+describe('member-base adapter', () => {
+  it('creates BPM auth context from a host member-base member', (): void => {
+    const context = createBPMAuthContextFromMemberBaseMember(
+      createMember('member-001'),
+      {
+        readCustomFields: (member): Readonly<Record<string, unknown>> => ({
+          source: 'member-base',
+          tenantMemberId: member.id,
+        }),
+        readPermissions: (member): readonly string[] => member.permissions,
+        readRoles: (member): readonly string[] => member.roles,
+      },
+    );
+
+    expect(context).toEqual({
+      memberId: 'member-001',
+      metadata: {
+        source: 'member-base',
+        tenantMemberId: 'member-001',
+      },
+      permissions: ['bpm:approve'],
+      roles: ['approver'],
+    });
+  });
+
+  it('adapts member-base lookup and search to BPM member metadata', async (): Promise<void> => {
+    const members = [createMember('member-001'), createMember('member-002')];
+    const resolver = new BPMMemberBaseResolverAdapter<TestMemberBaseMember>({
+      resolveMember: (memberId): Promise<TestMemberBaseMember | null> =>
+        Promise.resolve(
+          members.find((member) => member.id === memberId) ?? null,
+        ),
+      searchMembers: (searchText): Promise<readonly TestMemberBaseMember[]> =>
+        Promise.resolve(
+          members.filter((member) => member.email.includes(searchText)),
+        ),
+    });
+
+    await expect(resolver.resolve('member-001')).resolves.toEqual({
+      customFields: {},
+      email: 'member-001@example.com',
+      memberId: 'member-001',
+      name: 'Member member-001',
+    });
+    await expect(resolver.search?.('member-002')).resolves.toEqual([
+      {
+        customFields: {},
+        email: 'member-002@example.com',
+        memberId: 'member-002',
+        name: 'Member member-002',
+      },
+    ]);
+  });
+
+  it('leaves searchPaged undefined when the directory does not implement searchMembersPaged', (): void => {
+    const resolver = new BPMMemberBaseResolverAdapter<TestMemberBaseMember>({
+      resolveMember: (): Promise<TestMemberBaseMember | null> =>
+        Promise.resolve(null),
+    });
+
+    expect(resolver.searchPaged).toBeUndefined();
+  });
+
+  it('delegates searchPaged to the directory and maps items to member metadata', async (): Promise<void> => {
+    const members = [
+      createMember('member-001'),
+      createMember('member-002'),
+      createMember('member-003'),
+    ];
+    const resolver = new BPMMemberBaseResolverAdapter<TestMemberBaseMember>({
+      resolveMember: (memberId): Promise<TestMemberBaseMember | null> =>
+        Promise.resolve(
+          members.find((member) => member.id === memberId) ?? null,
+        ),
+      searchMembersPaged: (_searchText, options) => {
+        const offset = (options.page - 1) * options.pageSize;
+
+        return Promise.resolve({
+          items: members.slice(offset, offset + options.pageSize),
+          total: members.length,
+        });
+      },
+    });
+
+    await expect(
+      resolver.searchPaged?.('', { page: 2, pageSize: 2 }),
+    ).resolves.toEqual({
+      items: [
+        {
+          customFields: {},
+          email: 'member-003@example.com',
+          memberId: 'member-003',
+          name: 'Member member-003',
+        },
+      ],
+      total: 3,
+    });
+  });
+});
+
+function createMember(id: string): TestMemberBaseMember {
+  return {
+    email: `${id}@example.com`,
+    id,
+    name: `Member ${id}`,
+    permissions: ['bpm:approve'],
+    roles: ['approver'],
+  };
+}

package/src/lib/identity/member-base.adapter.ts

@@ -0,0 +1,302 @@
+import { InjectionToken, Provider } from '@nestjs/common';
+import { MemberMetadata } from '@rytass/bpm-core-shared';
+import { BPMAuthContext } from '../bpm-auth';
+import {
+  BPMMemberResolver,
+  BPMMemberSearchPage,
+  BPMMemberSearchPageOptions,
+} from './member-resolver.interface';
+
+/**
+ * Structural contract a host identity backend should implement (or a thin
+ * adapter wrap) so BPM can be plugged into any `member-base`-style
+ * directory without coupling `@rytass/bpm-core-nestjs-module` to a
+ * specific identity package.
+ *
+ * `TMember` is the host's own member shape; the adapter walks it through
+ * {@link BPMMemberBaseAdapterOptions} field readers.
+ */
+export interface BPMMemberBaseDirectory<TMember> {
+  readonly resolveMember: (memberId: string) => Promise<TMember | null>;
+  readonly resolveMembers?: (
+    memberIds: readonly string[],
+  ) => Promise<readonly TMember[]>;
+  readonly searchMembers?: (searchText: string) => Promise<readonly TMember[]>;
+  /**
+   * Optional paged directory search. Implement this (in addition to, or
+   * instead of, `searchMembers`) to let BPM page through a directory
+   * larger than `searchMembers`' member-picker cap and report an
+   * accurate total on the admin members list. `page` is 1-based and
+   * already normalized/clamped by BPM. Return the requested slice as
+   * `items` and the full match count as `total`. When omitted, the
+   * adapter's `searchPaged` stays `undefined` and BPM falls back to the
+   * `searchMembers`-and-slice path.
+   */
+  readonly searchMembersPaged?: (
+    searchText: string,
+    options: BPMMemberSearchPageOptions,
+  ) => Promise<BPMMemberBaseSearchPage<TMember>>;
+}
+
+/**
+ * Host-shaped page returned by
+ * {@link BPMMemberBaseDirectory.searchMembersPaged}. The adapter maps
+ * each `TMember` in `items` through the field readers into
+ * {@link MemberMetadata} and forwards `total` unchanged.
+ */
+export interface BPMMemberBaseSearchPage<TMember> {
+  readonly items: readonly TMember[];
+  readonly total: number;
+}
+
+/**
+ * Per-host field readers that tell the adapter how to extract canonical
+ * BPM fields out of the host's `TMember`. Each reader is optional;
+ * sensible defaults are inferred when the host uses common conventions
+ * (`memberId` / `id` / `sub` for the member id, `email` for the email,
+ * `name` / `displayName` for the name, etc.).
+ *
+ * Provide `readPermissions` and `readRoles` if you want BPM's
+ * `BPMAdminGuard` / `BPMDesignerGuard` to receive the host's RBAC
+ * strings; otherwise the resolved `BPMAuthContext` will carry empty
+ * arrays.
+ */
+export interface BPMMemberBaseAdapterOptions<TMember> {
+  readonly readCustomFields?: (
+    member: TMember,
+  ) => Readonly<Record<string, unknown>>;
+  readonly readEmail?: (member: TMember) => string | null;
+  readonly readMemberId?: (member: TMember) => string | null;
+  readonly readName?: (member: TMember) => string | null;
+  readonly readPermissions?: (member: TMember) => readonly string[];
+  readonly readRoles?: (member: TMember) => readonly string[];
+}
+
+export interface BPMMemberBaseResolverProviderOptions<TMember> {
+  readonly adapterOptions?: BPMMemberBaseAdapterOptions<TMember>;
+  readonly directoryToken: InjectionToken<BPMMemberBaseDirectory<TMember>>;
+  readonly provide: InjectionToken<BPMMemberResolver>;
+}
+
+export class BPMMemberBaseResolverAdapter<TMember>
+  implements BPMMemberResolver
+{
+  /**
+   * Present only when the wrapped directory implements
+   * `searchMembersPaged`. Left `undefined` otherwise so `IdentityService`
+   * capability detection falls back to the `search`-and-slice path,
+   * preserving pre-0.5.0 behavior.
+   */
+  readonly searchPaged?: (
+    searchText: string,
+    options: BPMMemberSearchPageOptions,
+  ) => Promise<BPMMemberSearchPage>;
+
+  constructor(
+    private readonly directory: BPMMemberBaseDirectory<TMember>,
+    private readonly options: BPMMemberBaseAdapterOptions<TMember> = {},
+  ) {
+    const searchMembersPaged = directory.searchMembersPaged;
+
+    if (searchMembersPaged) {
+      this.searchPaged = async (
+        searchText: string,
+        pageOptions: BPMMemberSearchPageOptions,
+      ): Promise<BPMMemberSearchPage> => {
+        const page = await searchMembersPaged(searchText, pageOptions);
+
+        return {
+          items: page.items.map((member): MemberMetadata =>
+            readMemberMetadataFromMemberBaseMember(member, this.options),
+          ),
+          total: page.total,
+        };
+      };
+    }
+  }
+
+  async resolve(memberId: string): Promise<MemberMetadata> {
+    const member = await this.directory.resolveMember(memberId);
+
+    if (!member) {
+      throw new Error(`member-base member ${memberId} was not found`);
+    }
+
+    return readMemberMetadataFromMemberBaseMember(member, this.options);
+  }
+
+  async resolveMany(
+    memberIds: readonly string[],
+  ): Promise<ReadonlyMap<string, MemberMetadata>> {
+    const members = this.directory.resolveMembers
+      ? await this.directory.resolveMembers(memberIds)
+      : await Promise.all(
+          memberIds.map((memberId): Promise<TMember | null> =>
+            this.directory.resolveMember(memberId),
+          ),
+        );
+
+    return members
+      .filter((member): member is TMember => Boolean(member))
+      .map((member): MemberMetadata =>
+        readMemberMetadataFromMemberBaseMember(member, this.options),
+      )
+      .reduce<ReadonlyMap<string, MemberMetadata>>(
+        (metadataByMemberId, metadata): ReadonlyMap<string, MemberMetadata> =>
+          new Map(metadataByMemberId).set(metadata.memberId, metadata),
+        new Map(),
+      );
+  }
+
+  async search(searchText: string): Promise<readonly MemberMetadata[]> {
+    if (!this.directory.searchMembers) {
+      return [];
+    }
+
+    return (await this.directory.searchMembers(searchText)).map(
+      (member): MemberMetadata =>
+        readMemberMetadataFromMemberBaseMember(member, this.options),
+    );
+  }
+}
+
+/**
+ * Helper for hosts that already hold an authenticated `TMember` (for
+ * example from `@rytass/member-base-nestjs-module`) and want to project it
+ * into a {@link BPMAuthContext} without writing the boilerplate by hand.
+ *
+ * Returns `null` when the input is nullish or when the member is missing
+ * an id — never throws. Pair this with `BPMRootModuleOptions.authContextFactory`
+ * so BPM resolvers receive the projected context on every request.
+ *
+ * @example
+ * ```ts
+ * const bpmAuth = createBPMAuthContextFromMemberBaseMember(memberBaseUser, {
+ *   readRoles: (m) => m.roles,
+ *   readPermissions: (m) => m.permissions,
+ *   readCustomFields: (m) => ({ tenantId: m.tenantId }),
+ * });
+ * ```
+ */
+export function createBPMAuthContextFromMemberBaseMember<TMember>(
+  member: TMember | null | undefined,
+  options: BPMMemberBaseAdapterOptions<TMember> = {},
+): BPMAuthContext | null {
+  if (!member) {
+    return null;
+  }
+
+  const memberId = readMemberId(member, options);
+
+  return memberId
+    ? {
+        memberId,
+        metadata: options.readCustomFields?.(member) ?? {},
+        permissions: options.readPermissions?.(member) ?? [],
+        roles: options.readRoles?.(member) ?? [],
+      }
+    : null;
+}
+
+/**
+ * Builds a Nest `Provider` that adapts a host-provided
+ * {@link BPMMemberBaseDirectory} into a {@link BPMMemberResolver}, then
+ * registers it under the host-chosen injection token (typically
+ * {@link BPM_MEMBER_RESOLVER}).
+ *
+ * Pass the result inside `BPMRootModuleOptions.memberResolverProvider`.
+ *
+ * @example
+ * ```ts
+ * BPMRootModule.forRoot({
+ *   memberResolverProvider: createBPMMemberBaseResolverProvider({
+ *     provide: BPM_MEMBER_RESOLVER,
+ *     directoryToken: HOST_MEMBER_DIRECTORY,
+ *     adapterOptions: {
+ *       readEmail: (m) => m.email,
+ *       readName: (m) => m.name,
+ *     },
+ *   }),
+ *   // ...
+ * });
+ * ```
+ */
+export function createBPMMemberBaseResolverProvider<TMember>({
+  adapterOptions,
+  directoryToken,
+  provide,
+}: BPMMemberBaseResolverProviderOptions<TMember>): Provider<BPMMemberResolver> {
+  return {
+    inject: [directoryToken],
+    provide,
+    useFactory: (
+      directory: BPMMemberBaseDirectory<TMember>,
+    ): BPMMemberResolver =>
+      new BPMMemberBaseResolverAdapter(directory, adapterOptions),
+  };
+}
+
+export function readMemberMetadataFromMemberBaseMember<TMember>(
+  member: TMember,
+  options: BPMMemberBaseAdapterOptions<TMember> = {},
+): MemberMetadata {
+  const memberId = readMemberId(member, options);
+
+  if (!memberId) {
+    throw new Error('member-base member id is required for BPM integration');
+  }
+
+  return {
+    customFields: options.readCustomFields?.(member) ?? {},
+    email: readMemberEmail(member, options) ?? '',
+    memberId,
+    name: readMemberName(member, options) ?? memberId,
+  };
+}
+
+function readMemberId<TMember>(
+  member: TMember,
+  options: BPMMemberBaseAdapterOptions<TMember>,
+): string | null {
+  return (
+    normalizeText(options.readMemberId?.(member)) ??
+    readStringProperty(member, 'memberId') ??
+    readStringProperty(member, 'id') ??
+    readStringProperty(member, 'sub')
+  );
+}
+
+function readMemberEmail<TMember>(
+  member: TMember,
+  options: BPMMemberBaseAdapterOptions<TMember>,
+): string | null {
+  return normalizeText(options.readEmail?.(member)) ?? readStringProperty(member, 'email');
+}
+
+function readMemberName<TMember>(
+  member: TMember,
+  options: BPMMemberBaseAdapterOptions<TMember>,
+): string | null {
+  return (
+    normalizeText(options.readName?.(member)) ??
+    readStringProperty(member, 'name') ??
+    readStringProperty(member, 'displayName') ??
+    readMemberEmail(member, options)
+  );
+}
+
+function readStringProperty(value: unknown, key: string): string | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  return normalizeText(value[key]);
+}
+
+function normalizeText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null;
+}