Add phase notification flag to resources

Author: jmgasper

docs/swagger.yaml

@@ -228,6 +228,51 @@ paths:
           $ref: '#/definitions/NotFound'
         '500':
           $ref: '#/definitions/ServerError'
+  '/resources/{resourceId}/phase-change-notifications':
+    put:
+      description: |
+        Update the phase change notification setting for a specific resource. The preference can only be changed by the resource owner, an administrator, or an authorized machine token.
+
+        ### Authentication
+        - JWT roles: `administrator`, `copilot`, `Connect Manager`, `Topcoder User`
+        - M2M scopes: `update:resources`, `all:resources`
+      tags:
+        - Resources
+      security:
+        - Bearer: []
+      parameters:
+        - name: resourceId
+          in: path
+          required: true
+          type: string
+          format: UUID
+          description: The resource identifier.
+        - in: body
+          name: payload
+          required: true
+          schema:
+            type: object
+            required:
+              - phaseChangeNotifications
+            properties:
+              phaseChangeNotifications:
+                type: boolean
+                description: Set to `true` to receive notifications when a challenge phase changes; `false` to opt out.
+      responses:
+        '200':
+          description: OK - the preference was updated successfully.
+          schema:
+            $ref: '#/definitions/Resource'
+        '400':
+          $ref: '#/definitions/BadRequest'
+        '401':
+          $ref: '#/definitions/Unauthorized'
+        '403':
+          $ref: '#/definitions/Forbidden'
+        '404':
+          $ref: '#/definitions/NotFound'
+        '500':
+          $ref: '#/definitions/ServerError'
   /resources/internal/jobs/clean:
     post:
       description: |
@@ -592,6 +637,7 @@ definitions:
       - memberId
       - memberHandle
       - roleId
+      - phaseChangeNotifications
       - created
     properties:
       id:
@@ -609,6 +655,9 @@ definitions:
         type: string
         format: UUID
         description: The resource role ID
+      phaseChangeNotifications:
+        type: boolean
+        description: Indicates whether the member receives notifications when challenge phases change.
       created:
         type: string
         format: date-time

migrator/src/migrators/migrateResource.js

@@ -27,6 +27,9 @@ async function migrateResource(filePath) {
       const jsonLine = JSON.parse(line);
       const data = jsonLine._source;
       const createdBy = data.createdBy || process.env.CREATED_BY;
+      const phaseChangeNotifications = Object.prototype.hasOwnProperty.call(data, 'phaseChangeNotifications')
+        ? data.phaseChangeNotifications
+        : null;
 
       await prisma.resource.upsert({
         where: { id: data.id },
@@ -38,7 +41,8 @@ async function migrateResource(filePath) {
           createdAt: data.created ? new Date(data.created) : new Date(),
           createdBy,
           updatedAt: data.updatedAt ? new Date(data.updatedAt) : null,
-          updatedBy: data.updatedBy || null
+          updatedBy: data.updatedBy || null,
+          phaseChangeNotifications
         },
         create: {
           id: data.id,
@@ -49,7 +53,8 @@ async function migrateResource(filePath) {
           createdAt: data.created ? new Date(data.created) : new Date(),
           createdBy,
           updatedAt: data.updatedAt ? new Date(data.updatedAt) : null,
-          updatedBy: data.updatedBy || null
+          updatedBy: data.updatedBy || null,
+          phaseChangeNotifications
         }
       });
 

migrator/src/migrators/migrateResourceBatch.js

@@ -33,6 +33,9 @@ async function migrateResource(filePath) {
     const results = await Promise.allSettled(
       batch.map(data => {
         const createdBy = data.createdBy || process.env.CREATED_BY;
+        const phaseChangeNotifications = Object.prototype.hasOwnProperty.call(data, 'phaseChangeNotifications')
+          ? data.phaseChangeNotifications
+          : null;
 
         return prisma.resource.upsert({
           where: { id: data.id },
@@ -44,7 +47,8 @@ async function migrateResource(filePath) {
             createdAt: data.created ? new Date(data.created) : new Date(),
             createdBy,
             updatedAt: data.updatedAt ? new Date(data.updatedAt) : null,
-            updatedBy: data.updatedBy || null
+            updatedBy: data.updatedBy || null,
+            phaseChangeNotifications
           },
           create: {
             id: data.id,
@@ -55,7 +59,8 @@ async function migrateResource(filePath) {
             createdAt: data.created ? new Date(data.created) : new Date(),
             createdBy,
             updatedAt: data.updatedAt ? new Date(data.updatedAt) : null,
-            updatedBy: data.updatedBy || null
+            updatedBy: data.updatedBy || null,
+            phaseChangeNotifications
           }
         }).catch(err => {
           failCount++;

prisma/migrations/20251201000000_add_phase_change_notifications/migration.sql

@@ -0,0 +1,3 @@
+-- Add phaseChangeNotifications flag to Resource
+ALTER TABLE "Resource" ADD COLUMN "phaseChangeNotifications" BOOLEAN;
+ALTER TABLE "Resource" ALTER COLUMN "phaseChangeNotifications" SET DEFAULT TRUE;

prisma/schema.prisma

@@ -35,6 +35,7 @@ model Resource {
   memberHandle String
   roleId       String
   legacyId     Int?
+  phaseChangeNotifications Boolean? @default(true)
   createdAt    DateTime @default(now())
   createdBy    String
   updatedAt    DateTime? @updatedAt

src/controllers/ResourceController.js

@@ -36,6 +36,16 @@ async function deleteResource (req, res) {
   res.send(result)
 }
 
+/**
+ * Update the phase change notifications preference for a resource.
+ * @param {Object} req the request
+ * @param {Object} res the response
+ */
+async function updatePhaseChangeNotifications (req, res) {
+  const result = await service.updatePhaseChangeNotifications(req.authUser, req.params.resourceId, req.body)
+  res.send(result)
+}
+
 /**
  * List all challenge ids that given member has access to.
  * @param {Object} req the request
@@ -61,6 +71,7 @@ module.exports = {
   getResources,
   createResource,
   deleteResource,
+  updatePhaseChangeNotifications,
   listChallengesByMember,
   getResourceCount
 }

src/routes.js

@@ -42,6 +42,15 @@ module.exports = {
       scopes: [READ, ALL]
     }
   },
+  '/resources/:resourceId/phase-change-notifications': {
+    put: {
+      controller: 'ResourceController',
+      method: 'updatePhaseChangeNotifications',
+      auth: 'jwt',
+      access: [constants.UserRoles.Admin, constants.UserRoles.Copilot, constants.UserRoles.Manager, constants.UserRoles.User],
+      scopes: [UPDATE, ALL]
+    }
+  },
   '/resources/internal/jobs/clean': {
     post: {
       controller: 'CleanUpController',

src/services/ResourceService.js

@@ -14,7 +14,7 @@ const errors = require('../common/errors')
 const constants = require('../../app-constants')
 const prisma = require('../common/prisma').getClient()
 
-const payloadFields = ['id', 'challengeId', 'memberId', 'memberHandle', 'roleId', 'created', 'createdBy', 'updated', 'updatedBy']
+const payloadFields = ['id', 'challengeId', 'memberId', 'memberHandle', 'roleId', 'phaseChangeNotifications', 'created', 'createdBy', 'updated', 'updatedBy']
 
 let copilotResourceRoleIdsCache
 
@@ -170,6 +170,7 @@ async function getResources (currentUser, challengeId, roleId, memberId, memberH
   resources = _.map(resources, item => {
     const ret = _.omit(item, 'updatedBy', 'updatedAt', 'createdAt')
     ret.created = item.createdAt
+    ret.phaseChangeNotifications = Boolean(item.phaseChangeNotifications)
     return ret
   })
 
@@ -423,6 +424,7 @@ async function createResource (currentUser, resource) {
     let ret = _.pick(createdResource, payloadFields)
     ret.created = createdResource.createdAt
     ret.updated = createdResource.updatedAt
+    ret.phaseChangeNotifications = Boolean(createdResource.phaseChangeNotifications)
 
     logger.debug(`Created resource: ${JSON.stringify(ret)}`)
     await helper.postEvent(config.RESOURCE_CREATE_TOPIC, ret)
@@ -525,6 +527,7 @@ async function deleteResource (currentUser, resource) {
       created: ret.createdAt,
       updated: ret.updatedAt
     }
+    ret.phaseChangeNotifications = Boolean(ret.phaseChangeNotifications)
     await prisma.resource.deleteMany({ where: { id: ret.id } })
 
     logger.debug(`Deleted resource, posting to Bus API: ${JSON.stringify(ret)}`)
@@ -568,6 +571,59 @@ deleteResource.schema = {
   )
 }
 
+/**
+ * Update the phase change notifications preference for a resource.
+ * @param {Object} currentUser the current user
+ * @param {String} resourceId the resource id
+ * @param {Object} payload the incoming payload
+ * @returns {Object} the updated resource
+ */
+async function updatePhaseChangeNotifications (currentUser, resourceId, payload) {
+  logger.debug(`updatePhaseChangeNotifications ${JSON.stringify([resourceId, payload])}`)
+
+  const resource = await prisma.resource.findUnique({ where: { id: resourceId } })
+
+  if (!resource) {
+    throw new errors.NotFoundError(`Resource with id ${resourceId} not found`)
+  }
+
+  const isMachineUser = Boolean(currentUser && currentUser.isMachine)
+  const isAdminUser = Boolean(currentUser && helper.hasAdminRole(currentUser))
+
+  if (!isMachineUser && !isAdminUser) {
+    if (!currentUser || _.toString(resource.memberId) !== _.toString(currentUser.userId)) {
+      throw new errors.ForbiddenError('You may only update your own phase change notification preference.')
+    }
+  }
+
+  const updatedBy = isMachineUser
+    ? (currentUser.sub || currentUser.clientId || 'system')
+    : _.toString(currentUser.userId)
+
+  const updatedResource = await prisma.resource.update({
+    where: { id: resourceId },
+    data: {
+      phaseChangeNotifications: payload.phaseChangeNotifications,
+      updatedBy
+    }
+  })
+
+  const ret = _.pick(updatedResource, payloadFields)
+  ret.created = updatedResource.createdAt
+  ret.updated = updatedResource.updatedAt
+  ret.phaseChangeNotifications = Boolean(updatedResource.phaseChangeNotifications)
+
+  return ret
+}
+
+updatePhaseChangeNotifications.schema = {
+  currentUser: Joi.any(),
+  resourceId: Joi.id().required(),
+  payload: Joi.object().keys({
+    phaseChangeNotifications: Joi.boolean().required()
+  }).required()
+}
+
 /**
  * List all challenge ids that given member has access to.
  * @param {Number} memberId the member id
@@ -658,6 +714,7 @@ module.exports = {
   getResources,
   createResource,
   deleteResource,
+  updatePhaseChangeNotifications,
   listChallengesByMember,
   getResourceCount
 }

test/common/testHelper.js

@@ -141,6 +141,9 @@ async function assertResource (id, expected) {
   should.equal(entity.memberId, expected.memberId)
   should.equal(entity.memberHandle.toLowerCase(), expected.memberHandle.toLowerCase())
   should.equal(entity.roleId, expected.roleId)
+  if (typeof expected.phaseChangeNotifications !== 'undefined') {
+    should.equal(Boolean(entity.phaseChangeNotifications), expected.phaseChangeNotifications)
+  }
   should.exist(expected.created)
   should.equal(entity.createdBy, expected.createdBy)
 }

test/unit/getResources.test.js

@@ -5,6 +5,7 @@
 const should = require('should')
 const service = require('../../src/services/ResourceService')
 const helper = require('../../src/common/helper')
+const prisma = require('../../src/common/prisma').getClient()
 const { user } = require('../common/testData')
 const { assertValidationError, assertError, getRoleIds } = require('../common/testHelper')
 
@@ -145,4 +146,24 @@ module.exports = describe('Get resources', () => {
       assertError(err, `Challenge ID ${challengeNotFoundId} not found`)
     }
   })
+
+  it('returns false when phaseChangeNotifications is null', async () => {
+    const target = await prisma.resource.findFirst({ where: { challengeId } })
+    should.exist(target)
+    const originalValue = target.phaseChangeNotifications
+    await prisma.resource.update({
+      where: { id: target.id },
+      data: { phaseChangeNotifications: null }
+    })
+
+    const result = await service.getResources(user.admin, challengeId)
+    const resourceRecord = result.data.find(r => r.id === target.id)
+    should.exist(resourceRecord)
+    should.equal(resourceRecord.phaseChangeNotifications, false)
+
+    await prisma.resource.update({
+      where: { id: target.id },
+      data: { phaseChangeNotifications: originalValue }
+    })
+  })
 })