@gadmin2n/schematics 0.0.139 → 0.0.141

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/approval-rule-evaluator.spec.ts

@@ -0,0 +1,68 @@
+import {
+  evaluateRules,
+  evaluateRulesDetailed,
+} from './approval-rule-evaluator';
+import { ApprovalRuleEvaluationInput } from './approval-rule.types';
+
+const base = (candidateCount = 4): ApprovalRuleEvaluationInput => ({
+  candidateCount,
+  decisions: [],
+  approvalRule: { mode: 'ANY' },
+  rejectionRule: { mode: 'ANY' },
+});
+
+describe('approval rule evaluator', () => {
+  it.each([
+    [{ mode: 'ANY' } as const, 1, 4],
+    [{ mode: 'ALL' } as const, 4, 4],
+    [{ mode: 'COUNT', count: 2 } as const, 2, 4],
+    [{ mode: 'PERCENTAGE', percentage: 75 } as const, 3, 4],
+  ])(
+    'approves when the %s threshold is reached',
+    (approvalRule, count, total) => {
+      expect(
+        evaluateRules({
+          ...base(total),
+          approvalRule,
+          decisions: Array.from({ length: count }, (_, index) => ({
+            principalRef: `user-${index}`,
+            decision: 'APPROVE' as const,
+          })),
+        }),
+      ).toBe('APPROVED');
+    },
+  );
+
+  it('blocks without candidates and gives rejection precedence', () => {
+    expect(evaluateRules(base(0))).toBe('BLOCKED');
+    expect(
+      evaluateRules({
+        ...base(2),
+        decisions: [
+          { principalRef: 'alice', decision: 'APPROVE' },
+          { principalRef: 'bob', decision: 'REJECT' },
+        ],
+      }),
+    ).toBe('REJECTED');
+  });
+
+  it('ignores inactive decisions, deduplicates principals, and warns on an impossible COUNT', () => {
+    const result = evaluateRulesDetailed({
+      ...base(2),
+      approvalRule: { mode: 'COUNT', count: 3 },
+      rejectionRule: { mode: 'ALL' },
+      decisions: [
+        { principalRef: 'alice', decision: 'APPROVE' },
+        { principalRef: 'alice', decision: 'APPROVE' },
+        { principalRef: 'bob', decision: 'APPROVE', active: false },
+      ],
+    });
+
+    expect(result).toMatchObject({
+      status: 'PENDING',
+      approvalCount: 1,
+      rejectionCount: 0,
+    });
+    expect(result.warnings).toHaveLength(1);
+  });
+});

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/approval-rule-evaluator.ts

@@ -0,0 +1,126 @@
+import {
+  ApprovalRule,
+  ApprovalRuleEvaluation,
+  ApprovalRuleEvaluationInput,
+  ApprovalRuleStatus,
+} from './approval-rule.types';
+
+export function evaluateRules(
+  input: ApprovalRuleEvaluationInput,
+): ApprovalRuleStatus {
+  return evaluateRulesDetailed(input).status;
+}
+
+export function evaluateRulesDetailed(
+  input: ApprovalRuleEvaluationInput,
+): ApprovalRuleEvaluation {
+  const candidateCount = assertCandidateCount(input.candidateCount);
+  if (candidateCount === 0) {
+    return {
+      status: 'BLOCKED',
+      warnings: [],
+      approvalCount: 0,
+      rejectionCount: 0,
+    };
+  }
+
+  // A principal contributes at most once. If inconsistent duplicate records
+  // exist, REJECT wins so corrupted input cannot accidentally approve work.
+  const decisions = new Map<string, 'APPROVE' | 'REJECT'>();
+  for (const decision of input.decisions) {
+    if (decision.active === false || !decision.principalRef) continue;
+    const current = decisions.get(decision.principalRef);
+    if (!current || decision.decision === 'REJECT') {
+      decisions.set(decision.principalRef, decision.decision);
+    }
+  }
+
+  let approvalCount = 0;
+  let rejectionCount = 0;
+  for (const decision of decisions.values()) {
+    if (decision === 'APPROVE') approvalCount += 1;
+    else rejectionCount += 1;
+  }
+
+  const warnings: string[] = [];
+  const rejected = thresholdReached(
+    input.rejectionRule,
+    rejectionCount,
+    candidateCount,
+    warnings,
+    'rejection',
+  );
+  const approved = thresholdReached(
+    input.approvalRule,
+    approvalCount,
+    candidateCount,
+    warnings,
+    'approval',
+  );
+
+  return {
+    status: rejected ? 'REJECTED' : approved ? 'APPROVED' : 'PENDING',
+    warnings,
+    approvalCount,
+    rejectionCount,
+  };
+}
+
+function thresholdReached(
+  rule: ApprovalRule,
+  decisionCount: number,
+  candidateCount: number,
+  warnings: string[],
+  label: string,
+): boolean {
+  switch (rule.mode) {
+    case 'ANY':
+      return decisionCount >= 1;
+    case 'ALL':
+      return decisionCount >= candidateCount;
+    case 'COUNT': {
+      const count = assertPositiveInteger(rule.count, `${label} count`);
+      if (count > candidateCount) {
+        warnings.push(
+          `${label} COUNT threshold ${count} exceeds candidate count ${candidateCount}`,
+        );
+      }
+      return decisionCount >= count;
+    }
+    case 'PERCENTAGE': {
+      const percentage = assertPercentage(rule.percentage, label);
+      return decisionCount * 100 >= percentage * candidateCount;
+    }
+  }
+}
+
+function assertCandidateCount(value: number): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error('candidateCount must be a non-negative integer');
+  }
+  return value;
+}
+
+function assertPositiveInteger(
+  value: number | undefined,
+  label: string,
+): number {
+  if (!Number.isSafeInteger(value) || Number(value) < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return Number(value);
+}
+
+function assertPercentage(value: number | undefined, label: string): number {
+  if (
+    typeof value !== 'number' ||
+    !Number.isFinite(value) ||
+    value <= 0 ||
+    value > 100
+  ) {
+    throw new Error(
+      `${label} percentage must be greater than 0 and at most 100`,
+    );
+  }
+  return value;
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/approval-rule.types.ts

@@ -0,0 +1,34 @@
+export type ApprovalRuleMode = 'ANY' | 'ALL' | 'COUNT' | 'PERCENTAGE';
+
+export interface ApprovalRule {
+  mode: ApprovalRuleMode;
+  count?: number;
+  percentage?: number;
+}
+
+export interface ApprovalRuleDecision {
+  principalRef: string;
+  decision: 'APPROVE' | 'REJECT';
+  /** False when the candidate eligibility revision is no longer active. */
+  active?: boolean;
+}
+
+export interface ApprovalRuleEvaluationInput {
+  candidateCount: number;
+  decisions: readonly ApprovalRuleDecision[];
+  approvalRule: ApprovalRule;
+  rejectionRule: ApprovalRule;
+}
+
+export type ApprovalRuleStatus =
+  | 'APPROVED'
+  | 'REJECTED'
+  | 'PENDING'
+  | 'BLOCKED';
+
+export interface ApprovalRuleEvaluation {
+  status: ApprovalRuleStatus;
+  warnings: readonly string[];
+  approvalCount: number;
+  rejectionCount: number;
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/approval-signal-outbox.service.ts

@@ -0,0 +1,115 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Interval } from '@nestjs/schedule';
+import { randomUUID } from 'crypto';
+import { PrismaService } from 'nestjs-prisma';
+import { TemporalService } from '../workflow/temporal.service';
+import { outboxError, outboxRetryAt } from './outbox-retry.util';
+
+const BATCH_SIZE = 25;
+const LOCK_TIMEOUT_MS = 60_000;
+
+@Injectable()
+export class ApprovalSignalOutboxService {
+  private readonly logger = new Logger(ApprovalSignalOutboxService.name);
+  private readonly workerId = `approval-signal-${process.pid}-${randomUUID()}`;
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly temporal: TemporalService,
+  ) {}
+
+  @Interval(5000)
+  async poll(): Promise<void> {
+    const rows = await this.claim();
+    for (const row of rows) await this.dispatch(row);
+  }
+
+  private claim() {
+    const now = new Date();
+    const staleAt = new Date(now.getTime() - LOCK_TIMEOUT_MS);
+    const claimId = `${this.workerId}:${randomUUID()}`.slice(0, 128);
+    return this.prisma.$transaction(async (tx) => {
+      const candidates = await tx.approvalSignalOutbox.findMany({
+        where: {
+          nextAttemptAt: { lte: now },
+          OR: [
+            { status: { in: ['PENDING', 'FAILED'] }, lockedAt: null },
+            { status: 'PROCESSING', lockedAt: { lt: staleAt } },
+          ],
+        },
+        orderBy: { id: 'asc' },
+        take: BATCH_SIZE,
+      });
+      if (!candidates.length) return [];
+      const ids = candidates.map(({ id }) => id);
+      await tx.approvalSignalOutbox.updateMany({
+        where: {
+          id: { in: ids },
+          OR: [
+            { status: { in: ['PENDING', 'FAILED'] }, lockedAt: null },
+            { status: 'PROCESSING', lockedAt: { lt: staleAt } },
+          ],
+        },
+        data: { status: 'PROCESSING', lockedAt: now, lockedBy: claimId },
+      });
+      return tx.approvalSignalOutbox.findMany({
+        where: { id: { in: ids }, lockedBy: claimId, status: 'PROCESSING' },
+        orderBy: { id: 'asc' },
+      });
+    });
+  }
+
+  private async dispatch(row: {
+    id: bigint;
+    requestId: bigint;
+    payload: unknown;
+    retryCount: number;
+  }): Promise<void> {
+    try {
+      const instance = await this.prisma.workflowInstance.findUnique({
+        where: {
+          id: (
+            await this.prisma.approvalRequest.findUniqueOrThrow({
+              where: { id: row.requestId },
+              select: { workflowInstanceId: true },
+            })
+          ).workflowInstanceId,
+        },
+        select: { temporalRunId: true },
+      });
+      if (!instance?.temporalRunId)
+        throw new Error('Approval workflow has no Temporal run ID');
+      await this.temporal.signalWorkflow(
+        instance.temporalRunId,
+        'humanApprovalResolved',
+        row.payload,
+      );
+      await this.prisma.approvalSignalOutbox.updateMany({
+        where: { id: row.id, status: 'PROCESSING' },
+        data: {
+          status: 'PROCESSED',
+          processedAt: new Date(),
+          lockedAt: null,
+          lockedBy: null,
+          lastError: null,
+        },
+      });
+    } catch (error) {
+      const retryCount = row.retryCount + 1;
+      await this.prisma.approvalSignalOutbox.updateMany({
+        where: { id: row.id, status: 'PROCESSING' },
+        data: {
+          status: 'FAILED',
+          retryCount,
+          nextAttemptAt: outboxRetryAt(retryCount),
+          lockedAt: null,
+          lockedBy: null,
+          lastError: outboxError(error),
+        },
+      });
+      this.logger.warn(
+        `Approval signal ${row.id} failed: ${outboxError(error)}`,
+      );
+    }
+  }
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/approval-subject-source.util.spec.ts

@@ -0,0 +1,45 @@
+import { materializeApprovalSubjects } from './approval-subject-source.util';
+
+describe('materializeApprovalSubjects', () => {
+  it('combines static approvers with scalar and array dynamic inputs', () => {
+    expect(
+      materializeApprovalSubjects(
+        [
+          { source: 'STATIC', provider: 'USER', refs: ['alice'] },
+          {
+            source: 'DYNAMIC',
+            provider: 'USER',
+            inputKey: 'request_owner',
+          },
+          {
+            source: 'DYNAMIC',
+            provider: 'USER_GROUP',
+            inputKey: 'review_groups',
+          },
+        ],
+        {
+          request_owner: 'bob',
+          review_groups: ['finance', 'risk', 'finance'],
+        },
+      ),
+    ).toEqual([
+      { provider: 'USER', refs: ['alice', 'bob'] },
+      { provider: 'USER_GROUP', refs: ['finance', 'risk'] },
+    ]);
+  });
+
+  it('rejects a missing dynamic approver input', () => {
+    expect(() =>
+      materializeApprovalSubjects(
+        [
+          {
+            source: 'DYNAMIC',
+            provider: 'USER',
+            inputKey: 'request_owner',
+          },
+        ],
+        {},
+      ),
+    ).toThrow('Dynamic approver input "request_owner" is missing or empty');
+  });
+});

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/approval-subject-source.util.ts

@@ -0,0 +1,59 @@
+export type ApprovalSubjectProvider = 'USER' | 'USER_GROUP';
+
+export type ApprovalSubjectSource =
+  | {
+      source?: 'STATIC';
+      provider: ApprovalSubjectProvider;
+      refs: string[];
+    }
+  | {
+      source: 'DYNAMIC';
+      provider: ApprovalSubjectProvider;
+      inputKey: string;
+    };
+
+export interface MaterializedApprovalSubject {
+  provider: ApprovalSubjectProvider;
+  refs: string[];
+}
+
+export function materializeApprovalSubjects(
+  sources: ApprovalSubjectSource[],
+  dynamicInputs: Record<string, unknown> = {},
+): MaterializedApprovalSubject[] {
+  const refsByProvider = new Map<ApprovalSubjectProvider, string[]>();
+
+  for (const source of sources) {
+    const refs =
+      source.source === 'DYNAMIC'
+        ? normalizeDynamicRefs(dynamicInputs[source.inputKey], source.inputKey)
+        : normalizeRefs(source.refs);
+    const current = refsByProvider.get(source.provider) ?? [];
+    refsByProvider.set(source.provider, [...new Set([...current, ...refs])]);
+  }
+
+  return [...refsByProvider].map(([provider, refs]) => ({ provider, refs }));
+}
+
+function normalizeDynamicRefs(value: unknown, inputKey: string): string[] {
+  const refs = normalizeRefs(Array.isArray(value) ? value : [value]);
+  if (refs.length === 0)
+    throw new Error(`Dynamic approver input "${inputKey}" is missing or empty`);
+  return refs;
+}
+
+function normalizeRefs(values: unknown[]): string[] {
+  return [
+    ...new Set(
+      values
+        .filter(
+          (value) =>
+            typeof value === 'string' ||
+            (typeof value === 'number' && Number.isSafeInteger(value)),
+        )
+        .map(String)
+        .map((value) => value.trim())
+        .filter(Boolean),
+    ),
+  ];
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/human-approval.controller.ts

@@ -0,0 +1,72 @@
+import { ACGuard } from '@gadmin2n/nest-common';
+import {
+  Body,
+  Controller,
+  Get,
+  HttpStatus,
+  Param,
+  Post,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+import { UseRoles } from 'nest-access-control';
+import {
+  actorContextFromRequest,
+  AuthenticatedActorRequest,
+} from '../subjectProvider/actor-context.util';
+import { SubmitApprovalDecisionDto } from './human-approval.dto';
+import { HumanApprovalDomainError } from './human-approval.errors';
+import { HumanApprovalService } from './human-approval.service';
+
+@ApiTags('human-approval')
+@UseGuards(ACGuard)
+@Controller('human-approval')
+export class HumanApprovalController {
+  constructor(private readonly service: HumanApprovalService) {}
+
+  @Get('inbox')
+  @UseRoles({ resource: 'humanApproval', action: 'read', possession: 'any' })
+  inbox(@Req() request: AuthenticatedActorRequest) {
+    return this.service.inbox(actorContextFromRequest(request));
+  }
+
+  @Post(':requestId/decisions')
+  @UseRoles({
+    resource: 'humanApproval',
+    action: 'update',
+    possession: 'any',
+  })
+  decide(
+    @Param('requestId') requestId: string,
+    @Body() input: SubmitApprovalDecisionDto,
+    @Req() request: AuthenticatedActorRequest,
+  ) {
+    return this.service.submitDecision(
+      parseBigIntParam(requestId),
+      input,
+      actorContextFromRequest(request),
+    );
+  }
+
+  @Post(':requestId/retry-dispatch')
+  @UseRoles({
+    resource: 'humanApproval',
+    action: 'update',
+    possession: 'any',
+  })
+  retryDispatch(@Param('requestId') requestId: string) {
+    return this.service.retryDispatch(parseBigIntParam(requestId));
+  }
+}
+
+function parseBigIntParam(value: string): bigint {
+  if (!/^[0-9]+$/.test(value)) {
+    throw new HumanApprovalDomainError(
+      'APPROVAL_REQUEST_NOT_FOUND',
+      'Approval request ID must be an integer',
+      HttpStatus.BAD_REQUEST,
+    );
+  }
+  return BigInt(value);
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/human-approval.dto.ts

@@ -0,0 +1,144 @@
+import { Type } from 'class-transformer';
+import {
+  IsArray,
+  IsIn,
+  IsInt,
+  IsNotEmpty,
+  IsObject,
+  IsOptional,
+  IsString,
+  Min,
+  ValidateIf,
+  ValidateNested,
+} from 'class-validator';
+import { ApprovalRule } from './approval-rule.types';
+
+export class ApprovalSubjectConfigDto {
+  @IsIn(['STATIC', 'DYNAMIC'])
+  source: 'STATIC' | 'DYNAMIC';
+
+  @IsString()
+  @IsNotEmpty()
+  provider: string;
+
+  @ValidateIf((input) => input.source === 'STATIC')
+  @IsArray()
+  @IsString({ each: true })
+  refs?: string[];
+
+  @ValidateIf((input) => input.source === 'DYNAMIC')
+  @IsString()
+  @IsNotEmpty()
+  inputKey?: string;
+}
+
+export class ApprovalTimeoutConfigDto {
+  @IsInt()
+  @Min(0)
+  durationSeconds: number;
+
+  @IsIn(['APPROVED', 'REJECTED'])
+  action: 'APPROVED' | 'REJECTED';
+}
+
+export class ApprovalConfigSnapshotDto {
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  channelRef?: string;
+
+  @IsOptional()
+  @IsObject()
+  channelInputBindings?: Record<string, unknown>;
+
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ApprovalSubjectConfigDto)
+  subjects: ApprovalSubjectConfigDto[];
+
+  @IsObject()
+  approvalRule: ApprovalRule;
+
+  @IsObject()
+  rejectionRule: ApprovalRule;
+
+  @ValidateNested()
+  @Type(() => ApprovalTimeoutConfigDto)
+  timeout: ApprovalTimeoutConfigDto;
+}
+
+export class StartApprovalRequestDto {
+  workflowInstanceId: string | number | bigint;
+
+  @IsString()
+  @IsNotEmpty()
+  nodeId: string;
+
+  workflowVersionId: string | number | bigint;
+
+  @IsOptional()
+  @IsString()
+  tenantNamespace?: string;
+
+  @IsOptional()
+  @IsString()
+  temporalRunId?: string;
+
+  @IsString()
+  @IsNotEmpty()
+  configHash: string;
+
+  @ValidateNested()
+  @Type(() => ApprovalConfigSnapshotDto)
+  configSnapshot: ApprovalConfigSnapshotDto;
+
+  @IsOptional()
+  @IsObject()
+  dynamicInputs?: Record<string, unknown>;
+
+  @IsOptional()
+  @IsObject()
+  channelInputs?: Record<string, unknown>;
+
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ResolvedApprovalSubjectDto)
+  resolvedSubjects?: ResolvedApprovalSubjectDto[];
+}
+
+export class ResolvedApprovalSubjectDto {
+  @IsIn(['USER', 'USER_GROUP'])
+  provider!: 'USER' | 'USER_GROUP';
+
+  @IsArray()
+  @IsString({ each: true })
+  refs!: string[];
+}
+
+export class SubmitApprovalDecisionDto {
+  @IsIn(['APPROVE', 'REJECT'])
+  decision: 'APPROVE' | 'REJECT';
+
+  @IsOptional()
+  @IsString()
+  comment?: string;
+
+  @IsOptional()
+  @IsObject()
+  payload?: Record<string, unknown>;
+}
+
+export class SubmitExternalApprovalDecisionDto extends SubmitApprovalDecisionDto {
+  @IsString()
+  @IsNotEmpty()
+  channelRef!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  eventId!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  approverId!: string;
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/human-approval.errors.ts

@@ -0,0 +1,19 @@
+import { HttpException, HttpStatus } from '@nestjs/common';
+
+export type HumanApprovalErrorCode =
+  | 'APPROVAL_CONFIG_MISMATCH'
+  | 'APPROVAL_REQUEST_NOT_FOUND'
+  | 'APPROVAL_REQUEST_CLOSED'
+  | 'APPROVAL_NOT_CANDIDATE'
+  | 'APPROVAL_CHANNEL_MISMATCH'
+  | 'APPROVAL_DECISION_CONFLICT';
+
+export class HumanApprovalDomainError extends HttpException {
+  constructor(
+    code: HumanApprovalErrorCode,
+    message: string,
+    status: HttpStatus,
+  ) {
+    super({ code, message }, status);
+  }
+}