AI-1063 Backend Functions for Group Membership Requests (#47)

Author: dbarkowsky

.github/copilot-instructions.md

@@ -16,4 +16,8 @@
 ## Prisma and Database Guidelines
 - If you need to run `npx prisma generate`, run `npm run db:generate` from `apps/backend-services` - it's a special script that writes models into apps/temporal/src and apps/backend-services/src. Don't forget to run migrations as normal if necessary.
 - Tables should be designed with a `created_at` timestamp (default to now) and an `updated_at` timestamp (auto-updated on change) for auditing purposes.
-- Table names should be singular (e.g., `User`, not `Users`) to align with Prisma conventions.
+- Table names should be singular (e.g., `User`, not `Users`) to align with Prisma conventions.
+
+## Requirements and User Stories
+- When finished implementing a user story, check it off in the related user stories file in `feature-docs/002-group-management/user_stories/README.md` and update the acceptance checklist.
+- If you find any gaps in the requirements or user stories, document them in the summary notes after implementation and ask for clarification before proceeding with any assumptions.

.github/skills/requirements-refiner/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: requirements-refiner
+description: "Requirements Refiner: Iteratively questions the user to clarify vague requirements and outputs a single consolidated requirements document in feature-docs."
+---
+**Role**: You are an expert Technical Product Manager and Business Analyst. Your goal is to take initial, potentially vague business requirements and refine them into a clear, comprehensive specification by asking clarifying questions.
+
+## Your Workflow
+
+1. **Analyze**: Read the input text or file. Compare it against the standards defined in `.claude/skills/requirements-refiner/elicitation_standards.md`.
+2. **Iterative Elicitation**:
+- Identify gaps, ambiguities, or assumptions.
+- Ask a set of numbered clarifying questions.
+- Wait for the user's response.
+- Repeat this step until the requirements are clear and complete.
+3. **Consolidate**:
+- Once the requirements are fully understood, create a single consolidated document.
+- This document should include the initial requirements plus all details gathered during the Q&A process.
+- Ensure the output is structured and ready for a User Story writer to consume.
+4. **Save to feature-docs**:
+- Examine the `feature-docs/` directory to find the highest numbered folder (e.g., `001-graph-workflows`).
+- Determine the next increment number (e.g., if `001` exists, use `002`).
+- Generate a short feature name/slug (kebab-case, e.g., "benchmarking-system").
+- Create a new folder: `feature-docs/{NNN}-{feature-slug}/` (e.g., `feature-docs/002-benchmarking-system/`).
+- Save the consolidated requirements as `REQUIREMENTS.md` in that folder.
+
+## Key Behaviors
+- **Iterative Approach**: Do not rush to the final output. Prioritize clarity over speed.
+- **Probe Deeply**: Ask about edge cases, error states, and user roles.
+- **Auto-increment Folders**: Always check existing feature-docs folders to determine the next number.
+- **Output Format**: The final output must be saved as `feature-docs/{NNN}-{feature-slug}/REQUIREMENTS.md`.

.github/skills/requirements-refiner/elicitation_standards.md

@@ -0,0 +1,30 @@
+# Elicitation Standards & Tips
+
+Use these categories to generate questions when analyzing requirements.
+
+## 1. The "Who" (Personas)
+- Who exactly is the user? (Admin, Guest, Registered User?)
+- Are there different permissions or roles involved?
+- *Tip*: Never assume "User" is a single entity.
+
+## 2. The "What" (Functional & Edge Cases)
+- **Happy Path**: What is the ideal flow?
+- **Unhappy Path**: What happens if...
+    - The operation fails?
+    - The data is missing?
+    - The internet connection is lost?
+    - The user inputs invalid data?
+
+## 3. The "Where" & "When" (Context)
+- Is this mobile, desktop, or both?
+- Does this happen in real-time or as a background job?
+
+## 4. The "How" (Data & Integrity)
+- Where does the data come from?
+- Do we need to validate formats (email, phone, dates)?
+- Are there security concerns (PII, specialized access)?
+
+## 5. Non-Functional Requirements
+- **Performance**: How fast must it load?
+- **Scale**: How many headers/items?
+- **Localization**: Do we need multi-language support?

.github/skills/write-user-stories/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: write-user-stories
+description: Convert a refined requirements document into one user story file per story in a user_stories subfolder using the strict template, plus a README.md with phase breakdown.
+argument-hint: refined-requirements-file
+context: fork
+agent: user-story-writer
+disable-model-invocation: true
+---
+Generate user stories from: $ARGUMENTS
+
+Requirements:
+- Decompose into atomic, independent user stories.
+- Write each story using the strict template you have access to.
+- Create user_stories subfolder in the same directory as the requirements file.
+- Use filename format `US-{number}-{short-description}.md`.
+- Generate a README.md in the user_stories folder with all stories organized by phases with checkboxes.

.github/skills/write-user-stories/user_story_template.md

@@ -0,0 +1,25 @@
+# [Story ID]: [Title of the Story]
+
+**As a** [Persona],
+**I want to** [Action],
+**So that** [Benefit/Value].
+
+## Acceptance Criteria
+- [ ] **Scenario 1**: [Title]
+    - **Given** [Context]
+    - **When** [Action]
+    - **Then** [Outcome]
+
+- [ ] **Scenario 2**: [Title]
+    - **Given** ...
+    - **When** ...
+    - **Then** ...
+
+## Priority
+- [ ] High (Must Have)
+- [ ] Medium (Should Have)
+- [ ] Low (Nice to Have)
+
+## Technical Notes / Assumptions
+- [Add any technical constraints, data requirements, or assumptions here]
+- [e.g., "Requires update to User Profile API"]

apps/backend-services/src/group/dto/membership-request-action.dto.ts

@@ -0,0 +1,13 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsOptional, IsString } from "class-validator";
+
+/**
+ * DTO for actions on a group membership request (approve, deny, cancel).
+ * The actor's identity is derived from the JWT token, not this body.
+ */
+export class MembershipRequestActionDto {
+  @ApiPropertyOptional({ description: "Optional reason for the action" })
+  @IsOptional()
+  @IsString()
+  reason?: string;
+}

apps/backend-services/src/group/dto/request-membership.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString } from "class-validator";
+
+/**
+ * DTO for submitting a group membership request.
+ * The requesting user's identity is derived from the JWT token, not this body.
+ */
+export class RequestMembershipDto {
+  @ApiProperty({ description: "The ID of the group to request membership for" })
+  @IsString()
+  groupId: string;
+}

apps/backend-services/src/group/group.controller.spec.ts

@@ -1,4 +1,6 @@
+import { HttpException, HttpStatus } from "@nestjs/common";
 import { Test, TestingModule } from "@nestjs/testing";
+import { RequestMembershipDto } from "./dto/request-membership.dto";
 import { GroupController } from "./group.controller";
 import { GroupService } from "./group.service";
 
@@ -14,6 +16,10 @@ describe("GroupController", () => {
           provide: GroupService,
           useValue: {
             assignUserToGroups: jest.fn(),
+            requestMembership: jest.fn(),
+            cancelMembershipRequest: jest.fn(),
+            approveMembershipRequest: jest.fn(),
+            denyMembershipRequest: jest.fn(),
           },
         },
       ],
@@ -35,4 +41,181 @@ describe("GroupController", () => {
   it("should throw if groupIds is empty", async () => {
     await expect(controller.assignUserToGroups("user1", [])).rejects.toThrow();
   });
+
+  describe("requestMembership", () => {
+    it("should call service with userId from JWT sub and groupId from body", async () => {
+      const sub = "jwt-user-id";
+      const body: RequestMembershipDto = { groupId: "group1" };
+      jest.spyOn(service, "requestMembership").mockResolvedValueOnce();
+      const req = { user: { sub } } as any;
+      const result = await controller.requestMembership(req, body);
+      expect(service.requestMembership).toHaveBeenCalledWith(sub, body.groupId);
+      expect(result).toEqual({ success: true });
+    });
+
+    it("should throw 401 if no user in request", async () => {
+      const req = { user: undefined } as any;
+      await expect(
+        controller.requestMembership(req, { groupId: "group1" }),
+      ).rejects.toThrow(
+        new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED),
+      );
+    });
+
+    it("should throw 401 if user has no sub claim", async () => {
+      const req = { user: {} } as any;
+      await expect(
+        controller.requestMembership(req, { groupId: "group1" }),
+      ).rejects.toThrow(
+        new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED),
+      );
+    });
+  });
+
+  describe("cancelMembershipRequest", () => {
+    it("should call service with userId from JWT, requestId from param, and reason from body", async () => {
+      const sub = "jwt-user-id";
+      const requestId = "req1";
+      jest.spyOn(service, "cancelMembershipRequest").mockResolvedValueOnce();
+      const req = { user: { sub } } as any;
+      const result = await controller.cancelMembershipRequest(req, requestId, {
+        reason: "No longer needed",
+      });
+      expect(service.cancelMembershipRequest).toHaveBeenCalledWith(
+        sub,
+        requestId,
+        "No longer needed",
+      );
+      expect(result).toEqual({ success: true });
+    });
+
+    it("should call service without reason when body has no reason", async () => {
+      const sub = "jwt-user-id";
+      const requestId = "req1";
+      jest.spyOn(service, "cancelMembershipRequest").mockResolvedValueOnce();
+      const req = { user: { sub } } as any;
+      await controller.cancelMembershipRequest(req, requestId, {});
+      expect(service.cancelMembershipRequest).toHaveBeenCalledWith(
+        sub,
+        requestId,
+        undefined,
+      );
+    });
+
+    it("should throw 401 if no user in request", async () => {
+      const req = { user: undefined } as any;
+      await expect(
+        controller.cancelMembershipRequest(req, "req1", {}),
+      ).rejects.toThrow(
+        new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED),
+      );
+    });
+
+    it("should throw 401 if user has no sub claim", async () => {
+      const req = { user: {} } as any;
+      await expect(
+        controller.cancelMembershipRequest(req, "req1", {}),
+      ).rejects.toThrow(
+        new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED),
+      );
+    });
+  });
+
+  describe("approveMembershipRequest", () => {
+    it("should call service with adminId from JWT, requestId from param, and reason from body", async () => {
+      const sub = "jwt-admin-id";
+      const requestId = "req1";
+      jest.spyOn(service, "approveMembershipRequest").mockResolvedValueOnce();
+      const req = { user: { sub } } as any;
+      const result = await controller.approveMembershipRequest(req, requestId, {
+        reason: "Approved",
+      });
+      expect(service.approveMembershipRequest).toHaveBeenCalledWith(
+        sub,
+        requestId,
+        "Approved",
+      );
+      expect(result).toEqual({ success: true });
+    });
+
+    it("should call service without reason when body has no reason", async () => {
+      const sub = "jwt-admin-id";
+      const requestId = "req1";
+      jest.spyOn(service, "approveMembershipRequest").mockResolvedValueOnce();
+      const req = { user: { sub } } as any;
+      await controller.approveMembershipRequest(req, requestId, {});
+      expect(service.approveMembershipRequest).toHaveBeenCalledWith(
+        sub,
+        requestId,
+        undefined,
+      );
+    });
+
+    it("should throw 401 if no user in request", async () => {
+      const req = { user: undefined } as any;
+      await expect(
+        controller.approveMembershipRequest(req, "req1", {}),
+      ).rejects.toThrow(
+        new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED),
+      );
+    });
+
+    it("should throw 401 if user has no sub claim", async () => {
+      const req = { user: {} } as any;
+      await expect(
+        controller.approveMembershipRequest(req, "req1", {}),
+      ).rejects.toThrow(
+        new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED),
+      );
+    });
+  });
+
+  describe("denyMembershipRequest", () => {
+    it("should call service with adminId from JWT, requestId from param, and reason from body", async () => {
+      const sub = "jwt-admin-id";
+      const requestId = "req1";
+      jest.spyOn(service, "denyMembershipRequest").mockResolvedValueOnce();
+      const req = { user: { sub } } as any;
+      const result = await controller.denyMembershipRequest(req, requestId, {
+        reason: "Not eligible",
+      });
+      expect(service.denyMembershipRequest).toHaveBeenCalledWith(
+        sub,
+        requestId,
+        "Not eligible",
+      );
+      expect(result).toEqual({ success: true });
+    });
+
+    it("should call service without reason when body has no reason", async () => {
+      const sub = "jwt-admin-id";
+      const requestId = "req1";
+      jest.spyOn(service, "denyMembershipRequest").mockResolvedValueOnce();
+      const req = { user: { sub } } as any;
+      await controller.denyMembershipRequest(req, requestId, {});
+      expect(service.denyMembershipRequest).toHaveBeenCalledWith(
+        sub,
+        requestId,
+        undefined,
+      );
+    });
+
+    it("should throw 401 if no user in request", async () => {
+      const req = { user: undefined } as any;
+      await expect(
+        controller.denyMembershipRequest(req, "req1", {}),
+      ).rejects.toThrow(
+        new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED),
+      );
+    });
+
+    it("should throw 401 if user has no sub claim", async () => {
+      const req = { user: {} } as any;
+      await expect(
+        controller.denyMembershipRequest(req, "req1", {}),
+      ).rejects.toThrow(
+        new HttpException("Unauthorized", HttpStatus.UNAUTHORIZED),
+      );
+    });
+  });
 });