@gadmin2n/schematics 0.0.139 → 0.0.141

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

@@ -0,0 +1,774 @@
+import { HttpStatus, Injectable, Optional } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import { PrismaService } from 'nestjs-prisma';
+import { ExternalInteractionService } from '../externalInteraction/external-interaction.service';
+import type { ExternalResultInput } from '../externalInteraction/external-interaction.types';
+import { SubjectProviderRegistry } from '../subjectProvider/subject-provider.registry';
+import { ActorContext } from '../subjectProvider/subject-provider.types';
+import { hashNodeInstanceConfig } from '../workflowNodeInstance/node-instance-config.util';
+import { evaluateRules } from './approval-rule-evaluator';
+import {
+  ApprovalSubjectSource,
+  materializeApprovalSubjects,
+} from './approval-subject-source.util';
+import {
+  ApprovalConfigSnapshotDto,
+  StartApprovalRequestDto,
+  SubmitApprovalDecisionDto,
+  SubmitExternalApprovalDecisionDto,
+} from './human-approval.dto';
+import { HumanApprovalDomainError } from './human-approval.errors';
+
+type SignalResult = 'APPROVED' | 'REJECTED' | 'CANCELLED';
+type SignalReason = 'RULE_SATISFIED' | 'TIMEOUT' | 'WORKFLOW_CANCELLED';
+type DispatchState = 'DISPATCHING' | 'WAITING_APPROVAL' | 'DISPATCH_FAILED';
+
+@Injectable()
+export class HumanApprovalService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly providers: SubjectProviderRegistry,
+    @Optional()
+    private readonly externalInteractions?: ExternalInteractionService,
+  ) {}
+
+  async startRequest(input: StartApprovalRequestDto, actor: ActorContext) {
+    const workflowInstanceId = toBigInt(input.workflowInstanceId);
+    const workflowVersionId = toBigInt(input.workflowVersionId);
+    const snapshot = input.configSnapshot as unknown as Prisma.JsonValue;
+    if (hashNodeInstanceConfig(snapshot) !== input.configHash) {
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        'Approval configuration does not match the workflow version snapshot',
+        HttpStatus.CONFLICT,
+      );
+    }
+
+    const existing = await this.prisma.approvalRequest.findUnique({
+      where: {
+        workflowInstanceId_nodeId: { workflowInstanceId, nodeId: input.nodeId },
+      },
+    });
+    if (existing) return existing;
+
+    const channelRef = input.configSnapshot.channelRef?.trim();
+    if (channelRef) {
+      const channel = await this.prisma.approvalChannel.findUnique({
+        where: { code: channelRef },
+        select: { isEnabled: true },
+      });
+      if (!channel?.isEnabled)
+        throw approvalError(
+          'APPROVAL_CONFIG_MISMATCH',
+          `Approval channel ${channelRef} was not found or is disabled`,
+          HttpStatus.BAD_REQUEST,
+        );
+    }
+
+    let materializedSubjects;
+    try {
+      materializedSubjects = mergeSubjectSources(
+        materializeApprovalSubjects(
+          input.configSnapshot.subjects as unknown as ApprovalSubjectSource[],
+          input.dynamicInputs,
+        ),
+        input.resolvedSubjects ?? [],
+      );
+    } catch (error) {
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        error instanceof Error ? error.message : 'Invalid dynamic approvers',
+        HttpStatus.BAD_REQUEST,
+      );
+    }
+    const resolved = await this.resolveSubjects(materializedSubjects, actor);
+    const startedAt = new Date();
+    const expiresAt =
+      input.configSnapshot.timeout.durationSeconds > 0
+        ? new Date(
+            startedAt.getTime() +
+              input.configSnapshot.timeout.durationSeconds * 1000,
+          )
+        : null;
+    const blocked = resolved.candidates.length === 0;
+
+    return this.prisma.$transaction(async (tx) => {
+      const request = await tx.approvalRequest.create({
+        data: {
+          workflowInstanceId,
+          nodeId: input.nodeId,
+          workflowVersionId,
+          configHash: input.configHash,
+          configSnapshot: snapshot as Prisma.InputJsonValue,
+          approvalRule: input.configSnapshot
+            .approvalRule as unknown as Prisma.InputJsonValue,
+          rejectionRule: input.configSnapshot
+            .rejectionRule as unknown as Prisma.InputJsonValue,
+          status: blocked ? 'BLOCKED' : 'PENDING',
+          blockedReason: blocked
+            ? 'No eligible approval candidates resolved'
+            : null,
+          startedAt,
+          expiresAt,
+          completedAt: blocked ? startedAt : null,
+          creator: actor.userId,
+          subjects: { create: resolved.subjects },
+          candidates: { create: resolved.candidates },
+        },
+      });
+      if (channelRef && !blocked) {
+        const interaction =
+          this.externalInteractions &&
+          input.tenantNamespace &&
+          input.temporalRunId
+            ? await this.externalInteractions.createInteractionInTransaction(
+                {
+                  tenantNamespace: input.tenantNamespace,
+                  handlerType: 'HUMAN_APPROVAL',
+                  handlerConfig: {
+                    approvalRequestId: String(request.id),
+                    allowedOutcomes: ['APPROVE', 'REJECT'],
+                  },
+                  workflowInstanceId: String(workflowInstanceId),
+                  workflowVersionId: String(workflowVersionId),
+                  temporalRunId: input.temporalRunId,
+                  nodeId: input.nodeId,
+                  ...(expiresAt && { expiresAt: expiresAt.toISOString() }),
+                },
+                tx,
+              )
+            : undefined;
+        await tx.workflowEventOutbox.create({
+          data: {
+            eventName: `approval.requested.${channelRef}`,
+            payload: {
+              workflow: input.channelInputs ?? {},
+              system: {
+                approval: {
+                  channel: channelRef,
+                  requestId: String(request.id),
+                  candidates: resolved.candidates.map((candidate) => ({
+                    approverId: candidate.principalRef,
+                    displayName: candidate.displayName,
+                    principalType: candidate.principalType,
+                  })),
+                  expiresAt: expiresAt?.toISOString() ?? null,
+                },
+                caller: {
+                  workflowInstanceId: String(workflowInstanceId),
+                  workflowVersionId: String(workflowVersionId),
+                  nodeId: input.nodeId,
+                },
+                invocation: {
+                  id: `approval:${request.id}:${channelRef}`,
+                },
+                ...(interaction && {
+                  callback: { token: interaction.callbackToken },
+                }),
+              },
+            } as Prisma.InputJsonValue,
+          },
+        });
+      }
+      return request;
+    });
+  }
+
+  async submitDecision(
+    requestId: bigint,
+    input: SubmitApprovalDecisionDto,
+    actor: ActorContext,
+  ) {
+    return this.prisma.$transaction(async (tx) => {
+      const request = await tx.approvalRequest.findUnique({
+        where: { id: requestId },
+        include: {
+          candidates: true,
+          decisions: { include: { candidate: true } },
+        },
+      });
+      if (!request) throw notFound(requestId);
+
+      const candidate = request.candidates.find(
+        (item) =>
+          item.invalidatedAt === null && item.principalRef === actor.userId,
+      );
+      if (!candidate) {
+        throw approvalError(
+          'APPROVAL_NOT_CANDIDATE',
+          'Actor is not an active approval candidate',
+          HttpStatus.FORBIDDEN,
+        );
+      }
+      return (
+        await this.recordDecision(
+          tx,
+          request,
+          candidate,
+          input,
+          actor.userId,
+          input.payload,
+        )
+      ).decision;
+    });
+  }
+
+  async submitExternalDecision(
+    requestId: bigint,
+    input: SubmitExternalApprovalDecisionDto,
+  ) {
+    return this.prisma.$transaction(async (tx) => {
+      const request = await tx.approvalRequest.findUnique({
+        where: { id: requestId },
+        include: {
+          candidates: true,
+          decisions: { include: { candidate: true } },
+        },
+      });
+      if (!request) throw notFound(requestId);
+
+      const snapshot = asObject(request.configSnapshot);
+      if (snapshot.channelRef !== input.channelRef)
+        throw approvalError(
+          'APPROVAL_CHANNEL_MISMATCH',
+          'Callback channel does not match the channel selected by this approval request',
+          HttpStatus.FORBIDDEN,
+        );
+
+      const candidate = request.candidates.find(
+        (item) =>
+          item.invalidatedAt === null && item.principalRef === input.approverId,
+      );
+      if (!candidate)
+        throw approvalError(
+          'APPROVAL_NOT_CANDIDATE',
+          'External approver is not an active approval candidate',
+          HttpStatus.FORBIDDEN,
+        );
+
+      return (
+        await this.recordDecision(
+          tx,
+          request,
+          candidate,
+          input,
+          `external:${input.channelRef}:${input.approverId}`,
+          {
+            ...(input.payload ?? {}),
+            externalEventId: input.eventId,
+            approvalChannel: input.channelRef,
+          },
+        )
+      ).decision;
+    });
+  }
+
+  async handleExternalInteractionDecision(
+    tx: any,
+    requestId: bigint,
+    input: ExternalResultInput,
+  ): Promise<'PENDING' | 'APPROVED' | 'REJECTED'> {
+    if (input.outcome !== 'APPROVE' && input.outcome !== 'REJECT')
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        'External approval outcome must be APPROVE or REJECT',
+        HttpStatus.BAD_REQUEST,
+      );
+    if (!input.operatorId)
+      throw approvalError(
+        'APPROVAL_NOT_CANDIDATE',
+        'External approval requires an operator',
+        HttpStatus.FORBIDDEN,
+      );
+    const request = await tx.approvalRequest.findUnique({
+      where: { id: requestId },
+      include: {
+        candidates: true,
+        decisions: { include: { candidate: true } },
+      },
+    });
+    if (!request) throw notFound(requestId);
+    const candidate = request.candidates.find(
+      (item) =>
+        item.invalidatedAt === null && item.principalRef === input.operatorId,
+    );
+    if (!candidate)
+      throw approvalError(
+        'APPROVAL_NOT_CANDIDATE',
+        'External approver is not an active approval candidate',
+        HttpStatus.FORBIDDEN,
+      );
+    const data = asObject(input.data);
+    const result = await this.recordDecision(
+      tx,
+      request,
+      candidate,
+      {
+        decision: input.outcome,
+        ...(typeof data.comment === 'string' && { comment: data.comment }),
+      },
+      `external-token:${input.operatorId}`,
+      {
+        ...data,
+        externalEventId: input.eventId,
+      },
+      false,
+    );
+    return result.status;
+  }
+
+  private async recordDecision(
+    tx: any,
+    request: any,
+    candidate: { id: bigint; principalRef: string },
+    input: SubmitApprovalDecisionDto,
+    creator: string,
+    payload?: Record<string, unknown>,
+    createSignalOutbox = true,
+  ) {
+    const duplicate = request.decisions.find(
+      (item) => item.candidateId === candidate.id,
+    );
+    if (duplicate) {
+      if (duplicate.decision === input.decision)
+        return { decision: duplicate, status: request.status };
+      throw approvalError(
+        'APPROVAL_DECISION_CONFLICT',
+        'A different decision already exists for this eligibility revision',
+        HttpStatus.CONFLICT,
+      );
+    }
+    if (request.status !== 'PENDING') throw closed(request.id, request.status);
+
+    const decision = await tx.approvalDecision.create({
+      data: {
+        requestId: request.id,
+        candidateId: candidate.id,
+        decision: input.decision,
+        comment: input.comment,
+        ...(payload && {
+          payload: payload as Prisma.InputJsonValue,
+        }),
+        creator,
+      },
+    });
+    const activeIds = new Set(
+      request.candidates
+        .filter((item) => item.invalidatedAt === null)
+        .map((item) => item.id),
+    );
+    const status = evaluateRules({
+      candidateCount: activeIds.size,
+      approvalRule: request.approvalRule as any,
+      rejectionRule: request.rejectionRule as any,
+      decisions: [
+        ...request.decisions
+          .filter((item) => activeIds.has(item.candidateId))
+          .map((item) => ({
+            principalRef: item.candidate.principalRef,
+            decision: item.decision,
+          })),
+        { principalRef: candidate.principalRef, decision: input.decision },
+      ],
+    });
+    if (status === 'APPROVED' || status === 'REJECTED') {
+      const changed = await tx.approvalRequest.updateMany({
+        where: { id: request.id, status: 'PENDING' },
+        data: { status, completedAt: new Date() },
+      });
+      if (changed.count === 1 && createSignalOutbox)
+        await this.createSignal(tx, request, status, 'RULE_SATISFIED');
+    }
+    return {
+      decision,
+      status:
+        status === 'APPROVED' || status === 'REJECTED'
+          ? status
+          : ('PENDING' as const),
+    };
+  }
+
+  cancelRequest(requestId: bigint) {
+    return this.finishPending(requestId, 'CANCELLED', 'WORKFLOW_CANCELLED');
+  }
+
+  async expireRequest(requestId: bigint) {
+    const request = await this.getRequest(requestId);
+    if (request.status !== 'PENDING') return request;
+    const snapshot =
+      request.configSnapshot as unknown as ApprovalConfigSnapshotDto;
+    return this.finishPending(requestId, snapshot.timeout.action, 'TIMEOUT');
+  }
+
+  async expireDueRequests(now: Date) {
+    const due = await this.prisma.approvalRequest.findMany({
+      where: { status: 'PENDING', expiresAt: { not: null, lte: now } },
+      select: { id: true },
+    });
+    return Promise.all(due.map(({ id }) => this.expireRequest(id)));
+  }
+
+  async inbox(actor: ActorContext) {
+    const items = await this.prisma.approvalCandidate.findMany({
+      where: {
+        principalRef: actor.userId,
+        invalidatedAt: null,
+        request: { status: 'PENDING' },
+      },
+      select: {
+        id: true,
+        displayName: true,
+        eligibilityRevision: true,
+        request: true,
+      },
+      orderBy: { activeFrom: 'desc' },
+    });
+    return Promise.all(
+      items.map(async (item) => {
+        const channelRef = stringValue(
+          asObject(item.request.configSnapshot).channelRef,
+        );
+        return {
+          ...item,
+          request: {
+            ...item.request,
+            ...(channelRef && {
+              dispatch: await this.getDispatchStatus(
+                item.request.id,
+                channelRef,
+              ),
+            }),
+          },
+        };
+      }),
+    );
+  }
+
+  async status(requestId: bigint) {
+    const request = await this.prisma.approvalRequest.findUniqueOrThrow({
+      where: { id: requestId },
+      select: {
+        id: true,
+        status: true,
+        configSnapshot: true,
+        blockedReason: true,
+        startedAt: true,
+        expiresAt: true,
+        completedAt: true,
+        updatedAt: true,
+      },
+    });
+    const { configSnapshot, ...publicRequest } = request;
+    const channelRef = stringValue(asObject(configSnapshot).channelRef);
+    return {
+      ...publicRequest,
+      ...(channelRef && {
+        dispatch: await this.getDispatchStatus(requestId, channelRef),
+      }),
+    };
+  }
+
+  async retryDispatch(requestId: bigint) {
+    const request = await this.getRequest(requestId);
+    if (request.status !== 'PENDING') throw closed(request.id, request.status);
+
+    const channelRef = stringValue(asObject(request.configSnapshot).channelRef);
+    if (!channelRef)
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        'This approval request does not use an external channel',
+        HttpStatus.BAD_REQUEST,
+      );
+
+    const attempt = await this.findLatestDispatch(requestId, channelRef);
+    const dispatch = dispatchStatusFrom(attempt);
+    if (!attempt.outbox || dispatch.state !== 'DISPATCH_FAILED')
+      throw approvalError(
+        'APPROVAL_REQUEST_CLOSED',
+        'The approval request can only be resent after dispatch fails',
+        HttpStatus.CONFLICT,
+      );
+
+    await this.prisma.workflowEventOutbox.create({
+      data: {
+        eventName: `approval.requested.${channelRef}`,
+        payload: attempt.outbox.payload as Prisma.InputJsonValue,
+      },
+    });
+    return { success: true };
+  }
+
+  private async finishPending(
+    requestId: bigint,
+    status: SignalResult,
+    reason: SignalReason,
+  ) {
+    return this.prisma.$transaction(async (tx) => {
+      const request = await tx.approvalRequest.findUnique({
+        where: { id: requestId },
+      });
+      if (!request) throw notFound(requestId);
+      if (request.status !== 'PENDING') return request;
+      const changed = await tx.approvalRequest.updateMany({
+        where: { id: requestId, status: 'PENDING' },
+        data: { status, completedAt: new Date() },
+      });
+      if (changed.count === 1)
+        await this.createSignal(tx, request, status, reason);
+      return tx.approvalRequest.findUnique({ where: { id: requestId } });
+    });
+  }
+
+  private async getRequest(requestId: bigint) {
+    const request = await this.prisma.approvalRequest.findUnique({
+      where: { id: requestId },
+    });
+    if (!request) throw notFound(requestId);
+    return request;
+  }
+
+  private async getDispatchStatus(requestId: bigint, channelRef: string) {
+    return dispatchStatusFrom(
+      await this.findLatestDispatch(requestId, channelRef),
+    );
+  }
+
+  private async findLatestDispatch(requestId: bigint, channelRef: string) {
+    const outbox = await this.prisma.workflowEventOutbox.findFirst({
+      where: {
+        eventName: `approval.requested.${channelRef}`,
+        payload: {
+          path: ['requestId'],
+          equals: String(requestId),
+        },
+      },
+      orderBy: { createdAt: 'desc' },
+    });
+    const instance = outbox
+      ? await this.prisma.workflowInstance.findFirst({
+          where: { sourceOutboxId: outbox.id },
+          orderBy: { createdAt: 'desc' },
+          select: { status: true, result: true },
+        })
+      : null;
+    return { outbox, instance };
+  }
+
+  private async resolveSubjects(
+    configuredSubjects: Array<{ provider: string; refs: string[] }>,
+    actor: ActorContext,
+  ) {
+    const subjects: Array<{
+      provider: string;
+      ref: string;
+      resourceRevision?: number;
+      metadata?: Prisma.InputJsonValue;
+    }> = [];
+    const candidates = new Map<
+      string,
+      {
+        principalType: string;
+        principalRef: string;
+        displayName: string;
+        sourceRefs: Prisma.InputJsonValue;
+      }
+    >();
+    for (const configured of configuredSubjects) {
+      const provider = this.providers.get(configured.provider);
+      const preview = await provider.preview(configured.refs, actor);
+      const previewByRef = new Map(
+        preview.items.map((item) => [item.ref, item]),
+      );
+      for (const ref of configured.refs) {
+        const item = previewByRef.get(ref);
+        subjects.push({
+          provider: configured.provider,
+          ref,
+          ...(item?.revision !== undefined && {
+            resourceRevision: item.revision,
+          }),
+          ...(item?.metadata && {
+            metadata: item.metadata as Prisma.InputJsonValue,
+          }),
+        });
+      }
+      const principals = await provider.resolve(configured.refs, { actor });
+      for (const principal of principals) {
+        const key = candidateKey(principal);
+        const existing = candidates.get(key);
+        const sourceRefs = new Set<string>([
+          ...((existing?.sourceRefs as string[] | undefined) ?? []),
+          ...principal.sourceRefs,
+        ]);
+        candidates.set(key, {
+          principalType: principal.principalType,
+          principalRef: principal.principalRef,
+          displayName:
+            principal.displayName ??
+            existing?.displayName ??
+            principal.principalRef,
+          sourceRefs: [...sourceRefs],
+        });
+      }
+    }
+    return { subjects, candidates: [...candidates.values()] };
+  }
+
+  private createSignal(
+    tx: any,
+    request: { id: bigint; workflowInstanceId: bigint; nodeId: string },
+    result: SignalResult,
+    reason: SignalReason,
+  ) {
+    return tx.approvalSignalOutbox.upsert({
+      where: { idempotencyKey: `approval-request:${request.id}:${result}` },
+      update: {},
+      create: {
+        requestId: request.id,
+        idempotencyKey: `approval-request:${request.id}:${result}`,
+        payload: {
+          requestId: request.id.toString(),
+          nodeId: request.nodeId,
+          result,
+          reason,
+          decidedAt: new Date().toISOString(),
+        },
+      },
+    });
+  }
+}
+
+function candidateKey(value: { principalType: string; principalRef: string }) {
+  return `${value.principalType}\u0000${value.principalRef}`;
+}
+
+function toBigInt(value: string | number | bigint): bigint {
+  if (typeof value === 'number' && !Number.isSafeInteger(value)) {
+    throw approvalError(
+      'APPROVAL_CONFIG_MISMATCH',
+      'Numeric ID is not a safe integer',
+      HttpStatus.BAD_REQUEST,
+    );
+  }
+  try {
+    return BigInt(value);
+  } catch {
+    throw approvalError(
+      'APPROVAL_CONFIG_MISMATCH',
+      'Invalid integer ID',
+      HttpStatus.BAD_REQUEST,
+    );
+  }
+}
+
+function approvalError(code: any, message: string, status: HttpStatus) {
+  return new HumanApprovalDomainError(code, message, status);
+}
+
+function notFound(id: bigint) {
+  return approvalError(
+    'APPROVAL_REQUEST_NOT_FOUND',
+    `Approval request not found: ${id}`,
+    HttpStatus.NOT_FOUND,
+  );
+}
+
+function closed(id: bigint, status: string) {
+  return approvalError(
+    'APPROVAL_REQUEST_CLOSED',
+    `Approval request ${id} is ${status}`,
+    HttpStatus.CONFLICT,
+  );
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function dispatchStatusFrom(attempt: {
+  outbox: {
+    processed: boolean;
+    lastError: string | null;
+  } | null;
+  instance: {
+    status: string;
+    result: unknown;
+  } | null;
+}): {
+  state: DispatchState;
+  canRetry: boolean;
+  error?: string;
+} {
+  if (!attempt.outbox)
+    return {
+      state: 'DISPATCH_FAILED',
+      canRetry: false,
+      error: 'Approval dispatch event was not created',
+    };
+
+  if (!attempt.outbox.processed)
+    return {
+      state: 'DISPATCHING',
+      canRetry: false,
+      ...(attempt.outbox.lastError && { error: attempt.outbox.lastError }),
+    };
+
+  if (attempt.outbox.lastError)
+    return {
+      state: 'DISPATCH_FAILED',
+      canRetry: true,
+      error: attempt.outbox.lastError,
+    };
+
+  if (!attempt.instance)
+    return {
+      state: 'DISPATCH_FAILED',
+      canRetry: true,
+      error: 'Approval dispatch Workflow did not start',
+    };
+
+  if (attempt.instance.status === 'COMPLETED')
+    return { state: 'WAITING_APPROVAL', canRetry: false };
+  if (
+    attempt.instance.status === 'FAILED' ||
+    attempt.instance.status === 'CANCELLED'
+  )
+    return {
+      state: 'DISPATCH_FAILED',
+      canRetry: true,
+      ...(workflowError(attempt.instance.result) && {
+        error: workflowError(attempt.instance.result),
+      }),
+    };
+  return { state: 'DISPATCHING', canRetry: false };
+}
+
+function workflowError(result: unknown): string | undefined {
+  const error = asObject(result).error;
+  return typeof error === 'string' && error.trim() ? error : undefined;
+}
+
+function mergeSubjectSources(
+  ...groups: Array<Array<{ provider: string; refs: string[] }>>
+) {
+  const refsByProvider = new Map<string, Set<string>>();
+  for (const group of groups) {
+    for (const source of group) {
+      const refs = refsByProvider.get(source.provider) ?? new Set<string>();
+      for (const ref of source.refs) {
+        if (typeof ref === 'string' && ref.trim()) refs.add(ref.trim());
+      }
+      refsByProvider.set(source.provider, refs);
+    }
+  }
+  return [...refsByProvider].map(([provider, refs]) => ({
+    provider,
+    refs: [...refs],
+  }));
+}