@ftisindia/create-app 0.1.0

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

@@ -0,0 +1,455 @@
+import {
+  ConflictException,
+  ForbiddenException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
+import { MembershipStatus, Prisma } from "@prisma/client";
+import { PrismaService } from "../../../../database/prisma/prisma.service";
+import { RbacCacheService } from "../../../access-control/application/services/rbac-cache.service";
+import { AuthenticatedUser } from "../../../auth/types/authenticated-user";
+import { RequestContextService } from "../../../request-context/application/services/request-context.service";
+
+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 MembershipDetail = Prisma.MembershipGetPayload<{
+  include: typeof membershipDetailInclude;
+}>;
+
+@Injectable()
+export class MembershipsService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly rbacCache: RbacCacheService,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async getCurrentMembership(currentUser: AuthenticatedUser, orgId: string) {
+    return this.assertActiveMembership(currentUser.id, orgId);
+  }
+
+  async listMemberships(currentUser: AuthenticatedUser, orgId: string) {
+    await this.assertActiveMembership(currentUser.id, orgId);
+
+    return this.prisma.membership.findMany({
+      where: { orgId },
+      include: membershipDetailInclude,
+      orderBy: [{ isOwner: "desc" }, { createdAt: "asc" }],
+    });
+  }
+
+  async updateStatus(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    membershipId: string,
+    status: MembershipStatus,
+  ) {
+    const result = await this.prisma.$transaction(async (tx) => {
+      await this.assertActiveMembership(currentUser.id, orgId, tx);
+
+      const target = await this.findMembershipInOrg(tx, orgId, membershipId);
+      this.assertRevokedMembershipIsNotReused(target, status);
+
+      if (
+        target.isOwner &&
+        target.status === MembershipStatus.ACTIVE &&
+        status !== MembershipStatus.ACTIVE
+      ) {
+        await this.assertActiveOwner(currentUser.id, orgId, tx);
+        await this.ensureOtherActiveOwner(tx, orgId, target.id);
+      }
+
+      const updated = await tx.membership.update({
+        where: { id: target.id },
+        data: { status },
+        include: membershipDetailInclude,
+      });
+
+      await this.writeAudit(tx, {
+        orgId,
+        actorUserId: currentUser.id,
+        action: "membership.status.update",
+        targetId: target.id,
+        metadata: {
+          previousStatus: target.status,
+          nextStatus: status,
+          targetUserId: target.userId,
+        },
+      });
+
+      return {
+        updated,
+        affectedUserIds: [target.userId],
+      };
+    });
+
+    this.rbacCache.invalidateMany(
+      result.affectedUserIds.map((userId) => ({ userId, orgId })),
+    );
+    return result.updated;
+  }
+
+  async assignRole(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    membershipId: string,
+    roleId: string,
+  ) {
+    const result = await this.prisma.$transaction(async (tx) => {
+      await this.assertActiveMembership(currentUser.id, orgId, tx);
+
+      const target = await this.findMembershipInOrg(tx, orgId, membershipId);
+      this.assertMembershipCanBeModified(target);
+
+      const role = await tx.role.findUnique({
+        where: {
+          id_orgId: {
+            id: roleId,
+            orgId,
+          },
+        },
+        select: { id: true, name: true },
+      });
+
+      if (!role) {
+        throw new NotFoundException("Role was not found in this organisation.");
+      }
+
+      const updated = await tx.membership.update({
+        where: { id: target.id },
+        data: { roleId },
+        include: membershipDetailInclude,
+      });
+
+      await this.writeAudit(tx, {
+        orgId,
+        actorUserId: currentUser.id,
+        action: "membership.role.update",
+        targetId: target.id,
+        metadata: {
+          previousRoleId: target.roleId,
+          nextRoleId: role.id,
+          nextRoleName: role.name,
+          targetUserId: target.userId,
+        },
+      });
+
+      return {
+        updated,
+        affectedUserIds: [target.userId],
+      };
+    });
+
+    this.rbacCache.invalidateMany(
+      result.affectedUserIds.map((userId) => ({ userId, orgId })),
+    );
+    return result.updated;
+  }
+
+  async updateOwner(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    membershipId: string,
+    isOwner: boolean,
+  ) {
+    const result = await this.prisma.$transaction(async (tx) => {
+      await this.assertActiveOwner(currentUser.id, orgId, tx);
+
+      const target = await this.findMembershipInOrg(tx, orgId, membershipId);
+      this.assertMembershipCanBeModified(target);
+
+      if (isOwner && target.status !== MembershipStatus.ACTIVE) {
+        throw new ConflictException(
+          "Only active memberships can be made owners.",
+        );
+      }
+
+      if (
+        !isOwner &&
+        target.isOwner &&
+        target.status === MembershipStatus.ACTIVE
+      ) {
+        await this.ensureOtherActiveOwner(tx, orgId, target.id);
+      }
+
+      const updated = await tx.membership.update({
+        where: { id: target.id },
+        data: { isOwner },
+        include: membershipDetailInclude,
+      });
+
+      await this.writeAudit(tx, {
+        orgId,
+        actorUserId: currentUser.id,
+        action: "membership.owner.update",
+        targetId: target.id,
+        metadata: {
+          previousIsOwner: target.isOwner,
+          nextIsOwner: isOwner,
+          targetUserId: target.userId,
+        },
+      });
+
+      return {
+        updated,
+        affectedUserIds: [target.userId],
+      };
+    });
+
+    this.rbacCache.invalidateMany(
+      result.affectedUserIds.map((userId) => ({ userId, orgId })),
+    );
+    return result.updated;
+  }
+
+  async updateBillingContact(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    membershipId: string,
+    isBillingContact: boolean,
+  ) {
+    const result = await this.prisma.$transaction(async (tx) => {
+      await this.assertActiveMembership(currentUser.id, orgId, tx);
+
+      const target = await this.findMembershipInOrg(tx, orgId, membershipId);
+      this.assertMembershipCanBeModified(target);
+
+      const updated = await tx.membership.update({
+        where: { id: target.id },
+        data: { isBillingContact },
+        include: membershipDetailInclude,
+      });
+
+      await this.writeAudit(tx, {
+        orgId,
+        actorUserId: currentUser.id,
+        action: "membership.billing_contact.update",
+        targetId: target.id,
+        metadata: {
+          previousIsBillingContact: target.isBillingContact,
+          nextIsBillingContact: isBillingContact,
+          targetUserId: target.userId,
+        },
+      });
+
+      return {
+        updated,
+        affectedUserIds: [target.userId],
+      };
+    });
+
+    this.rbacCache.invalidateMany(
+      result.affectedUserIds.map((userId) => ({ userId, orgId })),
+    );
+    return result.updated;
+  }
+
+  async transferOwner(
+    currentUser: AuthenticatedUser,
+    orgId: string,
+    toMembershipId: string,
+  ) {
+    const result = await this.prisma.$transaction(async (tx) => {
+      const actorMembership = await this.assertActiveOwner(
+        currentUser.id,
+        orgId,
+        tx,
+      );
+      const target = await this.findMembershipInOrg(tx, orgId, toMembershipId);
+
+      if (target.status !== MembershipStatus.ACTIVE) {
+        throw new ConflictException(
+          "Ownership can only be transferred to an active membership.",
+        );
+      }
+
+      if (actorMembership.id === target.id) {
+        return {
+          updated: target,
+          affectedUserIds: [],
+        };
+      }
+
+      await tx.membership.update({
+        where: { id: target.id },
+        data: { isOwner: true },
+      });
+
+      await tx.membership.update({
+        where: { id: actorMembership.id },
+        data: { isOwner: false },
+      });
+
+      await this.writeAudit(tx, {
+        orgId,
+        actorUserId: currentUser.id,
+        action: "membership.owner.transfer",
+        targetId: target.id,
+        metadata: {
+          fromMembershipId: actorMembership.id,
+          toMembershipId: target.id,
+          toUserId: target.userId,
+        },
+      });
+
+      const updated = await tx.membership.findUniqueOrThrow({
+        where: { id: target.id },
+        include: membershipDetailInclude,
+      });
+
+      return {
+        updated,
+        affectedUserIds: [actorMembership.userId, target.userId],
+      };
+    });
+
+    this.rbacCache.invalidateMany(
+      result.affectedUserIds.map((userId) => ({ userId, orgId })),
+    );
+    return result.updated;
+  }
+
+  async assertActiveMembership(
+    userId: string,
+    orgId: string,
+    client: PrismaClient = this.prisma,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const membership = await client.membership.findUnique({
+      where: {
+        userId_orgId: {
+          userId,
+          orgId,
+        },
+      },
+      include: membershipDetailInclude,
+    });
+
+    if (!membership || membership.status !== MembershipStatus.ACTIVE) {
+      throw new ForbiddenException(
+        "Active organisation membership is required.",
+      );
+    }
+
+    return membership;
+  }
+
+  async assertActiveOwner(
+    userId: string,
+    orgId: string,
+    client: PrismaClient = this.prisma,
+  ) {
+    const membership = await this.assertActiveMembership(userId, orgId, client);
+
+    if (!membership.isOwner) {
+      throw new ForbiddenException("Organisation owner access is required.");
+    }
+
+    return membership;
+  }
+
+  private async findMembershipInOrg(
+    client: PrismaClient,
+    orgId: string,
+    membershipId: string,
+  ) {
+    const membership = await client.membership.findFirst({
+      where: {
+        id: membershipId,
+        orgId,
+      },
+      include: membershipDetailInclude,
+    });
+
+    if (!membership) {
+      throw new NotFoundException(
+        "Membership was not found in this organisation.",
+      );
+    }
+
+    return membership;
+  }
+
+  private assertRevokedMembershipIsNotReused(
+    membership: MembershipDetail,
+    nextStatus: MembershipStatus,
+  ) {
+    if (
+      membership.status === MembershipStatus.REVOKED &&
+      nextStatus !== MembershipStatus.REVOKED
+    ) {
+      throw new ConflictException(
+        "Revoked memberships cannot be reactivated or reused.",
+      );
+    }
+  }
+
+  private assertMembershipCanBeModified(membership: MembershipDetail) {
+    if (membership.status === MembershipStatus.REVOKED) {
+      throw new ConflictException("Revoked memberships cannot be modified.");
+    }
+  }
+
+  private async ensureOtherActiveOwner(
+    tx: Prisma.TransactionClient,
+    orgId: string,
+    targetMembershipId: string,
+  ) {
+    const activeOwners = await tx.$queryRaw<Array<{ id: string }>>`
+      SELECT "id"
+      FROM "Membership"
+      WHERE "orgId" = ${orgId}
+        AND "isOwner" = true
+        AND "status" = 'ACTIVE'::"MembershipStatus"
+      FOR UPDATE
+    `;
+
+    if (!activeOwners.some((owner) => owner.id !== targetMembershipId)) {
+      throw new ConflictException(
+        "The last active owner cannot be removed, suspended, or demoted.",
+      );
+    }
+  }
+
+  private async writeAudit(
+    client: PrismaClient,
+    data: {
+      orgId: string;
+      actorUserId: string;
+      action: string;
+      targetId: string;
+      metadata?: Prisma.InputJsonObject;
+    },
+  ) {
+    await client.auditLog.create({
+      data: {
+        orgId: data.orgId,
+        actorUserId: data.actorUserId,
+        action: data.action,
+        targetType: "Membership",
+        targetId: data.targetId,
+        metadata: data.metadata,
+      },
+    });
+  }
+}

package/template/src/modules/memberships/dto/transfer-owner.dto.ts

@@ -0,0 +1,11 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsUUID } from "class-validator";
+
+export class TransferOwnerDto {
+  @ApiProperty({
+    example: "0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3",
+    format: "uuid",
+  })
+  @IsUUID()
+  toMembershipId!: string;
+}

package/template/src/modules/memberships/dto/update-billing-contact.dto.ts

@@ -0,0 +1,8 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsBoolean } from "class-validator";
+
+export class UpdateBillingContactDto {
+  @ApiProperty({ example: true })
+  @IsBoolean()
+  isBillingContact!: boolean;
+}

package/template/src/modules/memberships/dto/update-membership-owner.dto.ts

@@ -0,0 +1,8 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsBoolean } from "class-validator";
+
+export class UpdateMembershipOwnerDto {
+  @ApiProperty({ example: true })
+  @IsBoolean()
+  isOwner!: boolean;
+}

package/template/src/modules/memberships/dto/update-membership-role.dto.ts

@@ -0,0 +1,11 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsUUID } from "class-validator";
+
+export class UpdateMembershipRoleDto {
+  @ApiProperty({
+    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
+    format: "uuid",
+  })
+  @IsUUID()
+  roleId!: string;
+}

package/template/src/modules/memberships/dto/update-membership-status.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { MembershipStatus } from "@prisma/client";
+import { IsEnum } from "class-validator";
+
+export class UpdateMembershipStatusDto {
+  @ApiProperty({ enum: MembershipStatus, example: MembershipStatus.SUSPENDED })
+  @IsEnum(MembershipStatus)
+  status!: MembershipStatus;
+}

package/template/src/modules/memberships/memberships.module.ts

@@ -0,0 +1,12 @@
+import { Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module";
+import { MembershipsService } from "./application/services/memberships.service";
+import { MembershipsController } from "./presentation/memberships.controller";
+
+@Module({
+  imports: [AuthModule],
+  controllers: [MembershipsController],
+  providers: [MembershipsService],
+  exports: [MembershipsService],
+})
+export class MembershipsModule {}

package/template/src/modules/memberships/presentation/memberships.controller.ts

@@ -0,0 +1,193 @@
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Param,
+  Patch,
+  Post,
+  UseGuards,
+} from "@nestjs/common";
+import {
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+} from "@nestjs/swagger";
+import { MembershipResponseDto } from "../../../common/dto/membership-response.dto";
+import { ApiProtectedErrorResponses } from "../../../common/swagger/api-error-responses";
+import { PermissionGuard } from "../../access-control/application/services/permission.guard";
+import { RequirePermissions } from "../../access-control/presentation/permissions.decorator";
+import { JwtAuthGuard } from "../../auth/infrastructure/passport/jwt-auth.guard";
+import { CurrentUser } from "../../auth/presentation/current-user.decorator";
+import { AuthenticatedUser } from "../../auth/types/authenticated-user";
+import { OrgScopeGuard } from "../../request-context/presentation/org-scope.guard";
+import { MembershipsService } from "../application/services/memberships.service";
+import { TransferOwnerDto } from "../dto/transfer-owner.dto";
+import { UpdateBillingContactDto } from "../dto/update-billing-contact.dto";
+import { UpdateMembershipOwnerDto } from "../dto/update-membership-owner.dto";
+import { UpdateMembershipRoleDto } from "../dto/update-membership-role.dto";
+import { UpdateMembershipStatusDto } from "../dto/update-membership-status.dto";
+
+@ApiTags("Memberships")
+@ApiBearerAuth()
+@ApiParam({ name: "orgId", description: "Organisation ID.", format: "uuid" })
+@ApiProtectedErrorResponses(404, 409)
+@Controller("organisations/:orgId/memberships")
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class MembershipsController {
+  constructor(private readonly membershipsService: MembershipsService) {}
+
+  @Get("me")
+  @RequirePermissions("memberships.read")
+  @ApiOperation({
+    summary: "Return the current user membership in the organisation.",
+  })
+  @ApiOkResponse({
+    description: "Current membership.",
+    type: MembershipResponseDto,
+  })
+  me(@CurrentUser() user: AuthenticatedUser, @Param("orgId") orgId: string) {
+    return this.membershipsService.getCurrentMembership(user, orgId);
+  }
+
+  @Get()
+  @RequirePermissions("memberships.read")
+  @ApiOperation({ summary: "List organisation memberships." })
+  @ApiOkResponse({
+    description: "Organisation memberships.",
+    type: [MembershipResponseDto],
+  })
+  list(@CurrentUser() user: AuthenticatedUser, @Param("orgId") orgId: string) {
+    return this.membershipsService.listMemberships(user, orgId);
+  }
+
+  @Patch(":membershipId/status")
+  @RequirePermissions("memberships.revoke")
+  @ApiParam({
+    name: "membershipId",
+    description: "Membership ID.",
+    format: "uuid",
+  })
+  @ApiOperation({ summary: "Update membership status." })
+  @ApiOkResponse({
+    description: "Updated membership.",
+    type: MembershipResponseDto,
+  })
+  updateStatus(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("membershipId") membershipId: string,
+    @Body() dto: UpdateMembershipStatusDto,
+  ) {
+    return this.membershipsService.updateStatus(
+      user,
+      orgId,
+      membershipId,
+      dto.status,
+    );
+  }
+
+  @Patch(":membershipId/role")
+  @RequirePermissions("roles.manage")
+  @ApiParam({
+    name: "membershipId",
+    description: "Membership ID.",
+    format: "uuid",
+  })
+  @ApiOperation({ summary: "Assign a role to a membership." })
+  @ApiOkResponse({
+    description: "Updated membership.",
+    type: MembershipResponseDto,
+  })
+  updateRole(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("membershipId") membershipId: string,
+    @Body() dto: UpdateMembershipRoleDto,
+  ) {
+    return this.membershipsService.assignRole(
+      user,
+      orgId,
+      membershipId,
+      dto.roleId,
+    );
+  }
+
+  @Patch(":membershipId/owner")
+  @RequirePermissions("roles.manage")
+  @ApiParam({
+    name: "membershipId",
+    description: "Membership ID.",
+    format: "uuid",
+  })
+  @ApiOperation({ summary: "Grant or remove owner status on a membership." })
+  @ApiOkResponse({
+    description: "Updated membership.",
+    type: MembershipResponseDto,
+  })
+  updateOwner(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("membershipId") membershipId: string,
+    @Body() dto: UpdateMembershipOwnerDto,
+  ) {
+    return this.membershipsService.updateOwner(
+      user,
+      orgId,
+      membershipId,
+      dto.isOwner,
+    );
+  }
+
+  @Patch(":membershipId/billing-contact")
+  @RequirePermissions("billing.manage")
+  @ApiParam({
+    name: "membershipId",
+    description: "Membership ID.",
+    format: "uuid",
+  })
+  @ApiOperation({
+    summary: "Grant or remove billing contact status on a membership.",
+  })
+  @ApiOkResponse({
+    description: "Updated membership.",
+    type: MembershipResponseDto,
+  })
+  updateBillingContact(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Param("membershipId") membershipId: string,
+    @Body() dto: UpdateBillingContactDto,
+  ) {
+    return this.membershipsService.updateBillingContact(
+      user,
+      orgId,
+      membershipId,
+      dto.isBillingContact,
+    );
+  }
+
+  @Post("transfer-owner")
+  @HttpCode(200)
+  @RequirePermissions("roles.manage")
+  @ApiOperation({
+    summary: "Transfer organisation ownership to another active membership.",
+  })
+  @ApiOkResponse({
+    description: "New owner membership.",
+    type: MembershipResponseDto,
+  })
+  transferOwner(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param("orgId") orgId: string,
+    @Body() dto: TransferOwnerDto,
+  ) {
+    return this.membershipsService.transferOwner(
+      user,
+      orgId,
+      dto.toMembershipId,
+    );
+  }
+}