@ftisindia/create-app 0.1.0

package/template/src/modules/invitations/application/services/invitations.service.ts

@@ -0,0 +1,967 @@
+import {
+  BadRequestException,
+  ConflictException,
+  GoneException,
+  Injectable,
+  NotFoundException,
+  UnauthorizedException,
+} from "@nestjs/common";
+import {
+  AuthProvider,
+  InvitationStatus,
+  InvitationTargetType,
+  MembershipStatus,
+  Prisma,
+  User,
+} from "@prisma/client";
+import { isEmail } from "class-validator";
+import { createHash, randomBytes } from "crypto";
+import { PrismaService } from "../../../../database/prisma/prisma.service";
+import { RbacCacheService } from "../../../access-control/application/services/rbac-cache.service";
+import { PasswordService } from "../../../auth/application/services/password.service";
+import { AuthenticatedUser } from "../../../auth/types/authenticated-user";
+import { MembershipsService } from "../../../memberships/application/services/memberships.service";
+import { RequestContextService } from "../../../request-context/application/services/request-context.service";
+import { AcceptInvitationDto } from "../../dto/accept-invitation.dto";
+import { CreateInvitationDto } from "../../dto/create-invitation.dto";
+import { InvitationTokenDto } from "../../dto/invitation-token.dto";
+
+const DEFAULT_INVITATION_EXPIRY_DAYS = 7;
+const mobileTargetPattern = /^\+?[1-9]\d{6,14}$/;
+
+const invitationDetailInclude = {
+  role: {
+    select: {
+      id: true,
+      name: true,
+      description: true,
+    },
+  },
+  invitedByUser: {
+    select: {
+      id: true,
+      email: true,
+      mobile: true,
+      displayName: true,
+    },
+  },
+  acceptedByUser: {
+    select: {
+      id: true,
+      email: true,
+      mobile: true,
+      displayName: true,
+    },
+  },
+} satisfies Prisma.InvitationInclude;
+
+const membershipDetailInclude = {
+  user: {
+    select: {
+      id: true,
+      email: true,
+      mobile: true,
+      displayName: true,
+      isActive: true,
+    },
+  },
+  role: {
+    select: {
+      id: true,
+      name: true,
+      description: true,
+      isSystemSeeded: true,
+    },
+  },
+} satisfies Prisma.MembershipInclude;
+
+type PrismaClient = Prisma.TransactionClient | PrismaService;
+type InvitationDetail = Prisma.InvitationGetPayload<{
+  include: typeof invitationDetailInclude;
+}>;
+
+@Injectable()
+export class InvitationsService {
+  constructor(
+    private readonly membershipsService: MembershipsService,
+    private readonly passwordService: PasswordService,
+    private readonly prisma: PrismaService,
+    private readonly rbacCache: RbacCacheService,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async createInvitation(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    dto: CreateInvitationDto,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const normalizedTargetValue = normalizeTarget(
+      dto.targetType,
+      dto.targetValue,
+    );
+    const targetValue = dto.targetValue.trim();
+    const inviteToken = createInvitationToken();
+    const tokenHash = hashInvitationToken(inviteToken);
+    const expiresAt = addDays(
+      new Date(),
+      dto.expiresInDays ?? DEFAULT_INVITATION_EXPIRY_DAYS,
+    );
+
+    let invitation: InvitationDetail;
+    try {
+      invitation = await this.prisma.$transaction(async (tx) => {
+        await this.membershipsService.assertActiveMembership(
+          currentUser.id,
+          orgId,
+          tx,
+        );
+        await this.lockOrganisation(tx, orgId);
+        await this.assertRoleBelongsToOrg(tx, orgId, dto.roleId);
+        await this.assertNoPendingInvitation(
+          tx,
+          orgId,
+          dto.targetType,
+          normalizedTargetValue,
+        );
+        await this.assertTargetIsNotExistingMember(
+          tx,
+          orgId,
+          dto.targetType,
+          normalizedTargetValue,
+        );
+
+        const created = await tx.invitation.create({
+          data: {
+            orgId,
+            targetType: dto.targetType,
+            targetValue,
+            normalizedTargetValue,
+            roleId: dto.roleId,
+            tokenHash,
+            expiresAt,
+            invitedByUserId: currentUser.id,
+          },
+          include: invitationDetailInclude,
+        });
+
+        await this.writeAudit(tx, {
+          orgId,
+          actorUserId: currentUser.id,
+          action: "invitation.create",
+          targetId: created.id,
+          metadata: {
+            targetType: created.targetType,
+            normalizedTargetValue: created.normalizedTargetValue,
+            roleId: created.roleId,
+            expiresAt: created.expiresAt.toISOString(),
+          },
+        });
+
+        return created;
+      });
+    } catch (error) {
+      if (isPrismaUniqueError(error)) {
+        throw new ConflictException(
+          "A pending invitation already exists for this target.",
+        );
+      }
+
+      throw error;
+    }
+
+    return {
+      invitation: serializeInvitation(invitation),
+      inviteToken,
+    };
+  }
+
+  async listInvitations(currentUser: AuthenticatedUser, orgId: string) {
+    this.requestContext.assertOrgScope(orgId);
+    await this.membershipsService.assertActiveMembership(currentUser.id, orgId);
+
+    const invitations = await this.prisma.invitation.findMany({
+      where: { orgId },
+      include: invitationDetailInclude,
+      orderBy: { createdAt: "desc" },
+    });
+
+    return invitations.map(serializeInvitation);
+  }
+
+  async revokeInvitation(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    invitationId: string,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+
+    return this.prisma.$transaction(async (tx) => {
+      await this.membershipsService.assertActiveMembership(
+        currentUser.id,
+        orgId,
+        tx,
+      );
+
+      const invitation = await this.findInvitationInOrgForUpdate(
+        tx,
+        orgId,
+        invitationId,
+      );
+      this.assertPendingInvitation(invitation);
+      this.assertInvitationNotExpiredInTransaction(invitation);
+
+      const result = await tx.invitation.updateMany({
+        where: {
+          id: invitation.id,
+          status: InvitationStatus.PENDING,
+        },
+        data: {
+          status: InvitationStatus.REVOKED,
+          tokenHash: deadTokenHash(),
+          revokedAt: new Date(),
+        },
+      });
+
+      if (result.count !== 1) {
+        throw invitationStateChanged();
+      }
+
+      const revoked = await tx.invitation.findUniqueOrThrow({
+        where: { id: invitation.id },
+        include: invitationDetailInclude,
+      });
+
+      await this.writeAudit(tx, {
+        orgId,
+        actorUserId: currentUser.id,
+        action: "invitation.revoke",
+        targetId: invitation.id,
+        metadata: {
+          targetType: invitation.targetType,
+          normalizedTargetValue: invitation.normalizedTargetValue,
+        },
+      });
+
+      return serializeInvitation(revoked);
+    });
+  }
+
+  async resendInvitation(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    invitationId: string,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const inviteToken = createInvitationToken();
+    const tokenHash = hashInvitationToken(inviteToken);
+
+    const invitation = await this.prisma.$transaction(async (tx) => {
+      await this.membershipsService.assertActiveMembership(
+        currentUser.id,
+        orgId,
+        tx,
+      );
+
+      const existing = await this.findInvitationInOrgForUpdate(
+        tx,
+        orgId,
+        invitationId,
+      );
+      this.assertResendableInvitation(existing);
+      await this.assertRoleBelongsToOrg(tx, orgId, existing.roleId);
+      await this.assertTargetIsNotExistingMember(
+        tx,
+        orgId,
+        existing.targetType,
+        existing.normalizedTargetValue,
+      );
+
+      const result = await tx.invitation.updateMany({
+        where: {
+          id: existing.id,
+          status: {
+            in: [InvitationStatus.PENDING, InvitationStatus.EXPIRED],
+          },
+        },
+        data: {
+          status: InvitationStatus.PENDING,
+          tokenHash,
+          expiresAt: addDays(new Date(), DEFAULT_INVITATION_EXPIRY_DAYS),
+        },
+      });
+
+      if (result.count !== 1) {
+        throw invitationStateChanged();
+      }
+
+      const updated = await tx.invitation.findUniqueOrThrow({
+        where: { id: existing.id },
+        include: invitationDetailInclude,
+      });
+
+      await this.writeAudit(tx, {
+        orgId,
+        actorUserId: currentUser.id,
+        action: "invitation.resend",
+        targetId: existing.id,
+        metadata: {
+          targetType: existing.targetType,
+          normalizedTargetValue: existing.normalizedTargetValue,
+          expiresAt: updated.expiresAt.toISOString(),
+        },
+      });
+
+      return updated;
+    });
+
+    return {
+      invitation: serializeInvitation(invitation),
+      inviteToken,
+    };
+  }
+
+  async acceptInvitation(dto: AcceptInvitationDto) {
+    const tokenHash = hashInvitationToken(dto.token);
+    const invitation = await this.findInvitationByToken(tokenHash);
+    await this.assertInvitationNotExpired(invitation);
+
+    const result = await this.prisma.$transaction(async (tx) => {
+      const pendingInvitation = await this.findInvitationByTokenForUpdate(
+        tx,
+        tokenHash,
+      );
+      this.assertPendingInvitation(pendingInvitation);
+      this.assertInvitationNotExpiredInTransaction(pendingInvitation);
+      await this.assertRoleBelongsToOrg(
+        tx,
+        pendingInvitation.orgId,
+        pendingInvitation.roleId,
+      );
+
+      const user = await this.resolveTargetUser(tx, pendingInvitation, dto);
+      await this.assertMembershipCanBeCreated(
+        tx,
+        pendingInvitation.orgId,
+        user.id,
+      );
+
+      const membership = await tx.membership.create({
+        data: {
+          userId: user.id,
+          orgId: pendingInvitation.orgId,
+          roleId: pendingInvitation.roleId,
+          status: MembershipStatus.ACTIVE,
+          isOwner: false,
+          isBillingContact: false,
+        },
+        include: membershipDetailInclude,
+      });
+
+      const result = await tx.invitation.updateMany({
+        where: {
+          id: pendingInvitation.id,
+          status: InvitationStatus.PENDING,
+        },
+        data: {
+          status: InvitationStatus.ACCEPTED,
+          tokenHash: deadTokenHash(),
+          acceptedByUserId: user.id,
+          acceptedAt: new Date(),
+        },
+      });
+
+      if (result.count !== 1) {
+        throw invitationStateChanged();
+      }
+
+      const accepted = await tx.invitation.findUniqueOrThrow({
+        where: { id: pendingInvitation.id },
+        include: invitationDetailInclude,
+      });
+
+      await this.writeAudit(tx, {
+        orgId: pendingInvitation.orgId,
+        actorUserId: user.id,
+        action: "invitation.accept",
+        targetId: pendingInvitation.id,
+        metadata: {
+          targetType: pendingInvitation.targetType,
+          normalizedTargetValue: pendingInvitation.normalizedTargetValue,
+          membershipId: membership.id,
+        },
+      });
+
+      await this.writeAudit(tx, {
+        orgId: pendingInvitation.orgId,
+        actorUserId: user.id,
+        action: "membership.created",
+        targetType: "Membership",
+        targetId: membership.id,
+        metadata: {
+          invitedByUserId: pendingInvitation.invitedByUserId,
+          invitationId: pendingInvitation.id,
+          roleId: membership.roleId,
+          userId: user.id,
+        },
+      });
+
+      return {
+        invitation: serializeInvitation(accepted),
+        membership,
+        user: toSafeUser(user),
+        rbacInvalidation: {
+          userId: user.id,
+          orgId: pendingInvitation.orgId,
+        },
+      };
+    });
+
+    this.rbacCache.invalidate(
+      result.rbacInvalidation.userId,
+      result.rbacInvalidation.orgId,
+    );
+
+    const { rbacInvalidation: _rbacInvalidation, ...response } = result;
+    return response;
+  }
+
+  async declineInvitation(dto: InvitationTokenDto) {
+    const tokenHash = hashInvitationToken(dto.token);
+    const invitation = await this.findInvitationByToken(tokenHash);
+    await this.assertInvitationNotExpired(invitation);
+
+    return this.prisma.$transaction(async (tx) => {
+      const pendingInvitation = await this.findInvitationByTokenForUpdate(
+        tx,
+        tokenHash,
+      );
+      this.assertPendingInvitation(pendingInvitation);
+      this.assertInvitationNotExpiredInTransaction(pendingInvitation);
+
+      const result = await tx.invitation.updateMany({
+        where: {
+          id: pendingInvitation.id,
+          status: InvitationStatus.PENDING,
+        },
+        data: {
+          status: InvitationStatus.DECLINED,
+          tokenHash: deadTokenHash(),
+        },
+      });
+
+      if (result.count !== 1) {
+        throw invitationStateChanged();
+      }
+
+      const declined = await tx.invitation.findUniqueOrThrow({
+        where: { id: pendingInvitation.id },
+        include: invitationDetailInclude,
+      });
+
+      await this.writeAudit(tx, {
+        orgId: pendingInvitation.orgId,
+        action: "invitation.decline",
+        targetId: pendingInvitation.id,
+        metadata: {
+          targetType: pendingInvitation.targetType,
+          normalizedTargetValue: pendingInvitation.normalizedTargetValue,
+        },
+      });
+
+      return serializeInvitation(declined);
+    });
+  }
+
+  private async findInvitationByToken(tokenHash: string) {
+    const invitation = await this.prisma.invitation.findUnique({
+      where: { tokenHash },
+      include: invitationDetailInclude,
+    });
+
+    if (!invitation) {
+      throw invalidInvitationToken();
+    }
+
+    this.assertPendingInvitation(invitation);
+    return invitation;
+  }
+
+  private async findInvitationByTokenForUpdate(
+    tx: Prisma.TransactionClient,
+    tokenHash: string,
+  ) {
+    const rows = await tx.$queryRaw<Array<{ id: string }>>`
+      SELECT "id"
+      FROM "Invitation"
+      WHERE "tokenHash" = ${tokenHash}
+      FOR UPDATE
+    `;
+
+    if (rows.length === 0) {
+      throw invalidInvitationToken();
+    }
+
+    const invitation = await tx.invitation.findUnique({
+      where: { id: rows[0].id },
+      include: invitationDetailInclude,
+    });
+
+    if (!invitation) {
+      throw invalidInvitationToken();
+    }
+
+    return invitation;
+  }
+
+  private async findInvitationInOrg(
+    client: PrismaClient,
+    orgId: string,
+    invitationId: string,
+  ) {
+    const invitation = await client.invitation.findFirst({
+      where: {
+        id: invitationId,
+        orgId,
+      },
+      include: invitationDetailInclude,
+    });
+
+    if (!invitation) {
+      throw new NotFoundException(
+        "Invitation was not found in this organisation.",
+      );
+    }
+
+    return invitation;
+  }
+
+  private async findInvitationInOrgForUpdate(
+    tx: Prisma.TransactionClient,
+    orgId: string,
+    invitationId: string,
+  ) {
+    const rows = await tx.$queryRaw<Array<{ id: string }>>`
+      SELECT "id"
+      FROM "Invitation"
+      WHERE "id" = ${invitationId}
+        AND "orgId" = ${orgId}
+      FOR UPDATE
+    `;
+
+    if (rows.length === 0) {
+      throw new NotFoundException(
+        "Invitation was not found in this organisation.",
+      );
+    }
+
+    return tx.invitation.findUniqueOrThrow({
+      where: { id: rows[0].id },
+      include: invitationDetailInclude,
+    });
+  }
+
+  private async lockOrganisation(tx: Prisma.TransactionClient, orgId: string) {
+    await tx.$queryRaw<Array<{ id: string }>>`
+      SELECT "id"
+      FROM "Organisation"
+      WHERE "id" = ${orgId}
+      FOR UPDATE
+    `;
+  }
+
+  private async assertRoleBelongsToOrg(
+    client: PrismaClient,
+    orgId: string,
+    roleId: string,
+  ) {
+    const role = await client.role.findUnique({
+      where: {
+        id_orgId: {
+          id: roleId,
+          orgId,
+        },
+      },
+      select: { id: true },
+    });
+
+    if (!role) {
+      throw new NotFoundException("Role was not found in this organisation.");
+    }
+  }
+
+  private async assertNoPendingInvitation(
+    client: PrismaClient,
+    orgId: string,
+    targetType: InvitationTargetType,
+    normalizedTargetValue: string,
+  ) {
+    const existing = await client.invitation.findFirst({
+      where: {
+        orgId,
+        targetType,
+        normalizedTargetValue,
+        status: InvitationStatus.PENDING,
+      },
+      select: { id: true },
+    });
+
+    if (existing) {
+      throw new ConflictException(
+        "A pending invitation already exists for this target.",
+      );
+    }
+  }
+
+  private assertPendingInvitation(
+    invitation: Pick<InvitationDetail, "status">,
+  ) {
+    if (invitation.status === InvitationStatus.EXPIRED) {
+      throw new GoneException("Invitation has expired.");
+    }
+
+    if (invitation.status !== InvitationStatus.PENDING) {
+      throw new ConflictException("Invitation is no longer pending.");
+    }
+  }
+
+  private assertResendableInvitation(
+    invitation: Pick<InvitationDetail, "status">,
+  ) {
+    if (
+      invitation.status !== InvitationStatus.PENDING &&
+      invitation.status !== InvitationStatus.EXPIRED
+    ) {
+      throw new ConflictException(
+        "Invitation cannot be resent after it has been completed.",
+      );
+    }
+  }
+
+  private async assertInvitationNotExpired(invitation: InvitationDetail) {
+    if (invitation.expiresAt > new Date()) {
+      return;
+    }
+
+    await this.markInvitationExpired(invitation);
+    throw new GoneException("Invitation has expired.");
+  }
+
+  private assertInvitationNotExpiredInTransaction(
+    invitation: InvitationDetail,
+  ) {
+    if (invitation.status === InvitationStatus.EXPIRED) {
+      throw new GoneException("Invitation has expired.");
+    }
+
+    if (invitation.expiresAt > new Date()) {
+      return;
+    }
+
+    throw new GoneException("Invitation has expired.");
+  }
+
+  private async markInvitationExpired(invitation: InvitationDetail) {
+    if (invitation.status !== InvitationStatus.PENDING) {
+      return;
+    }
+
+    await this.prisma.$transaction((tx) =>
+      this.markInvitationExpiredInTransaction(tx, invitation),
+    );
+  }
+
+  private async markInvitationExpiredInTransaction(
+    tx: Prisma.TransactionClient,
+    invitation: InvitationDetail,
+  ) {
+    const result = await tx.invitation.updateMany({
+      where: {
+        id: invitation.id,
+        status: InvitationStatus.PENDING,
+      },
+      data: {
+        status: InvitationStatus.EXPIRED,
+        tokenHash: deadTokenHash(),
+      },
+    });
+
+    if (result.count === 0) {
+      return;
+    }
+
+    await this.writeAudit(tx, {
+      orgId: invitation.orgId,
+      action: "invitation.expired",
+      targetId: invitation.id,
+      metadata: {
+        targetType: invitation.targetType,
+        normalizedTargetValue: invitation.normalizedTargetValue,
+      },
+    });
+  }
+
+  private async resolveTargetUser(
+    tx: Prisma.TransactionClient,
+    invitation: InvitationDetail,
+    dto: AcceptInvitationDto,
+  ) {
+    if (invitation.targetType === InvitationTargetType.EMAIL) {
+      return this.resolveEmailUser(tx, invitation.normalizedTargetValue, dto);
+    }
+
+    return this.resolveMobileUser(tx, invitation.normalizedTargetValue, dto);
+  }
+
+  private async resolveEmailUser(
+    tx: Prisma.TransactionClient,
+    email: string,
+    dto: AcceptInvitationDto,
+  ) {
+    const existing = await tx.user.findUnique({
+      where: { email },
+    });
+
+    if (existing) {
+      if (!existing.isActive) {
+        throw new ConflictException("The invited user is inactive.");
+      }
+
+      return existing;
+    }
+
+    if (!dto.password) {
+      throw new BadRequestException(
+        "Password is required when accepting an email invitation as a new user.",
+      );
+    }
+
+    const passwordHash = await this.passwordService.hash(dto.password);
+    const user = await tx.user.create({
+      data: {
+        email,
+        passwordHash,
+        displayName: dto.displayName?.trim() || null,
+      },
+    });
+
+    await tx.authIdentity.create({
+      data: {
+        userId: user.id,
+        provider: AuthProvider.EMAIL_PASSWORD,
+        providerUserId: email,
+        email,
+      },
+    });
+
+    return user;
+  }
+
+  private async resolveMobileUser(
+    tx: Prisma.TransactionClient,
+    mobile: string,
+    dto: AcceptInvitationDto,
+  ) {
+    const existing = await tx.user.findUnique({
+      where: { mobile },
+    });
+
+    if (existing) {
+      if (!existing.isActive) {
+        throw new ConflictException("The invited user is inactive.");
+      }
+
+      return existing;
+    }
+
+    const user = await tx.user.create({
+      data: {
+        mobile,
+        displayName: dto.displayName?.trim() || null,
+      },
+    });
+
+    await tx.authIdentity.create({
+      data: {
+        userId: user.id,
+        provider: AuthProvider.MOBILE_OTP,
+        providerUserId: mobile,
+        mobile,
+      },
+    });
+
+    return user;
+  }
+
+  private async assertMembershipCanBeCreated(
+    tx: Prisma.TransactionClient,
+    orgId: string,
+    userId: string,
+  ) {
+    const existing = await tx.membership.findUnique({
+      where: {
+        userId_orgId: {
+          userId,
+          orgId,
+        },
+      },
+      select: {
+        id: true,
+        status: true,
+      },
+    });
+
+    if (!existing) {
+      return;
+    }
+
+    if (existing.status === MembershipStatus.REVOKED) {
+      throw new ConflictException(
+        "Revoked memberships cannot be reused through an invitation.",
+      );
+    }
+
+    throw new ConflictException(
+      "User already has a membership in this organisation.",
+    );
+  }
+
+  private async assertTargetIsNotExistingMember(
+    tx: Prisma.TransactionClient,
+    orgId: string,
+    targetType: InvitationTargetType,
+    normalizedTargetValue: string,
+  ) {
+    const user =
+      targetType === InvitationTargetType.EMAIL
+        ? await tx.user.findUnique({
+            where: { email: normalizedTargetValue },
+            select: { id: true },
+          })
+        : await tx.user.findUnique({
+            where: { mobile: normalizedTargetValue },
+            select: { id: true },
+          });
+
+    if (!user) {
+      return;
+    }
+
+    const membership = await tx.membership.findUnique({
+      where: {
+        userId_orgId: {
+          userId: user.id,
+          orgId,
+        },
+      },
+      select: { status: true },
+    });
+
+    if (!membership) {
+      return;
+    }
+
+    if (membership.status === MembershipStatus.REVOKED) {
+      throw new ConflictException(
+        "A revoked membership already exists for this invitation target.",
+      );
+    }
+
+    throw new ConflictException(
+      "Invitation target already has a membership in this organisation.",
+    );
+  }
+
+  private async writeAudit(
+    client: PrismaClient,
+    data: {
+      orgId: string;
+      actorUserId?: string;
+      action: string;
+      targetType?: string;
+      targetId: string;
+      metadata?: Prisma.InputJsonObject;
+    },
+  ) {
+    await client.auditLog.create({
+      data: {
+        orgId: data.orgId,
+        actorUserId: data.actorUserId,
+        action: data.action,
+        targetType: data.targetType ?? "Invitation",
+        targetId: data.targetId,
+        metadata: data.metadata,
+      },
+    });
+  }
+}
+
+function createInvitationToken() {
+  return randomBytes(32).toString("base64url");
+}
+
+function hashInvitationToken(token: string) {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+const deadTokenHash = () =>
+  hashInvitationToken(randomBytes(32).toString("base64url"));
+
+function addDays(date: Date, days: number) {
+  const next = new Date(date);
+  next.setUTCDate(next.getUTCDate() + days);
+  return next;
+}
+
+function normalizeTarget(type: InvitationTargetType, value: string) {
+  if (type === InvitationTargetType.EMAIL) {
+    const email = value.trim().toLowerCase();
+    if (!isEmail(email)) {
+      throw new BadRequestException("Invitation email must be valid.");
+    }
+    return email;
+  }
+
+  const mobile = value.trim().replace(/[\s()-]/g, "");
+  const normalized = mobile.startsWith("00") ? `+${mobile.slice(2)}` : mobile;
+
+  if (!mobileTargetPattern.test(normalized)) {
+    throw new BadRequestException(
+      "Invitation mobile number must be E.164-style.",
+    );
+  }
+
+  return normalized;
+}
+
+function serializeInvitation(invitation: InvitationDetail) {
+  const { tokenHash: _tokenHash, ...safeInvitation } = invitation;
+  return safeInvitation;
+}
+
+function toSafeUser(user: User) {
+  return {
+    id: user.id,
+    email: user.email,
+    mobile: user.mobile,
+    displayName: user.displayName,
+    isActive: user.isActive,
+  };
+}
+
+function invalidInvitationToken() {
+  return new UnauthorizedException("Invalid invitation token.");
+}
+
+function invitationStateChanged() {
+  return new ConflictException("Invitation is no longer pending.");
+}
+
+function isPrismaUniqueError(error: unknown) {
+  return (
+    error instanceof Prisma.PrismaClientKnownRequestError &&
+    error.code === "P2002"
+  );
+}