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

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

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

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

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