feat: add admin apis

Signed-off-by: Umberto Sgueglia <usgueglia@contractor.linuxfoundation.org>

Author: ulemons

backend/src/api/public/v1/index.ts

@@ -17,6 +17,7 @@ import { membersRouter } from './members'
 import { organizationsRouter } from './organizations'
 import { packagesRouter } from './packages'
 import { batchGetStewardship } from './packages/batchGetStewardship'
+import { stewardshipsRouter } from './stewardships'
 
 const packagesRateLimiter = createRateLimiter({ max: 60, windowMs: 60 * 1000 })
 
@@ -36,6 +37,7 @@ export function v1Router(): Router {
     safeWrap(batchGetStewardship),
   )
   router.use('/packages', oauth2Middleware(AUTH0_CONFIG), packagesRouter())
+  router.use('/stewardships', oauth2Middleware(AUTH0_CONFIG), stewardshipsRouter())
 
   router.use(() => {
     throw new NotFoundError()

backend/src/api/public/v1/stewardships/assignSteward.ts

@@ -0,0 +1,30 @@
+import type { Request, Response } from 'express'
+import { z } from 'zod'
+
+import { NotFoundError } from '@crowd/common'
+import { assignSteward } from '@crowd/data-access-layer'
+
+import { getPackagesQx } from '@/db/packagesDb'
+import { ok } from '@/utils/api'
+import { validateOrThrow } from '@/utils/validation'
+
+import { stewardshipIdParamsSchema } from './schemas'
+
+const bodySchema = z.object({
+  userId: z.string().trim().min(1),
+  role: z.enum(['lead', 'co_steward']),
+})
+
+export async function assignStewardHandler(req: Request, res: Response): Promise<void> {
+  const { id } = validateOrThrow(stewardshipIdParamsSchema, req.params)
+  const { userId, role } = validateOrThrow(bodySchema, req.body)
+
+  const qx = await getPackagesQx()
+  const result = await assignSteward(qx, id, { userId, role, assignedBy: req.actor.id })
+
+  if (!result) {
+    throw new NotFoundError(`Stewardship not found: ${id}`)
+  }
+
+  ok(res, { stewardship: result.stewardship, stewards: result.stewards })
+}

backend/src/api/public/v1/stewardships/escalate.ts

@@ -0,0 +1,34 @@
+import type { Request, Response } from 'express'
+import { z } from 'zod'
+
+import { NotFoundError } from '@crowd/common'
+import { ESCALATION_RESOLUTION_PATHS, escalateStewardship } from '@crowd/data-access-layer'
+
+import { getPackagesQx } from '@/db/packagesDb'
+import { ok } from '@/utils/api'
+import { validateOrThrow } from '@/utils/validation'
+
+import { stewardshipIdParamsSchema } from './schemas'
+
+const bodySchema = z.object({
+  resolutionPath: z.enum(ESCALATION_RESOLUTION_PATHS),
+  notes: z.string().trim().min(1).optional(),
+})
+
+export async function escalateHandler(req: Request, res: Response): Promise<void> {
+  const { id } = validateOrThrow(stewardshipIdParamsSchema, req.params)
+  const { resolutionPath, notes } = validateOrThrow(bodySchema, req.body)
+
+  const qx = await getPackagesQx()
+  const stewardship = await escalateStewardship(qx, id, {
+    resolutionPath,
+    notes,
+    actorUserId: req.actor.id,
+  })
+
+  if (!stewardship) {
+    throw new NotFoundError(`Stewardship not found: ${id}`)
+  }
+
+  ok(res, { stewardship })
+}

backend/src/api/public/v1/stewardships/index.ts

@@ -0,0 +1,50 @@
+import { Router } from 'express'
+
+import { createRateLimiter } from '@/api/apiRateLimiter'
+// TODO: restore once write:stewardships is added to Auth0 staging tenant
+// import { requireScopes } from '@/api/public/middlewares/requireScopes'
+import { safeWrap } from '@/middlewares/errorMiddleware'
+
+// import { SCOPES } from '@/security/scopes'
+import { assignStewardHandler } from './assignSteward'
+import { escalateHandler } from './escalate'
+import { openStewardship } from './openStewardship'
+import { updateStatusHandler } from './updateStatus'
+
+const rateLimiter = createRateLimiter({ max: 60, windowMs: 60 * 1000 })
+
+export function stewardshipsRouter(): Router {
+  const router = Router()
+
+  router.use(rateLimiter)
+
+  router.post(
+    '/',
+    // TODO: restore once write:stewardships is added to Auth0 staging tenant
+    // requireScopes([SCOPES.WRITE_STEWARDSHIPS]),
+    safeWrap(openStewardship),
+  )
+
+  router.put(
+    '/:id/steward',
+    // TODO: restore once write:stewardships is added to Auth0 staging tenant
+    // requireScopes([SCOPES.WRITE_STEWARDSHIPS]),
+    safeWrap(assignStewardHandler),
+  )
+
+  router.put(
+    '/:id/escalate',
+    // TODO: restore once write:stewardships is added to Auth0 staging tenant
+    // requireScopes([SCOPES.WRITE_STEWARDSHIPS]),
+    safeWrap(escalateHandler),
+  )
+
+  router.put(
+    '/:id/status',
+    // TODO: restore once write:stewardships is added to Auth0 staging tenant
+    // requireScopes([SCOPES.WRITE_STEWARDSHIPS]),
+    safeWrap(updateStatusHandler),
+  )
+
+  return router
+}

backend/src/api/public/v1/stewardships/openStewardship.ts

@@ -0,0 +1,33 @@
+import type { Request, Response } from 'express'
+import { z } from 'zod'
+
+import { NotFoundError } from '@crowd/common'
+import { openStewardshipByPurl } from '@crowd/data-access-layer'
+
+import { getPackagesQx } from '@/db/packagesDb'
+import { ok } from '@/utils/api'
+import { validateOrThrow } from '@/utils/validation'
+
+import { normalizePurl } from '../packages/purl'
+
+const bodySchema = z.object({
+  purl: z
+    .string()
+    .trim()
+    .min(1)
+    .refine((v) => v.startsWith('pkg:'), { message: 'purl must start with pkg:' }),
+})
+
+export async function openStewardship(req: Request, res: Response): Promise<void> {
+  const { purl: rawPurl } = validateOrThrow(bodySchema, req.body)
+  const purl = normalizePurl(rawPurl)
+
+  const qx = await getPackagesQx()
+  const stewardship = await openStewardshipByPurl(qx, purl, req.actor.id)
+
+  if (!stewardship) {
+    throw new NotFoundError(`Package not found: ${rawPurl}`)
+  }
+
+  ok(res, { stewardship })
+}

backend/src/api/public/v1/stewardships/schemas.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod'
+
+export const stewardshipIdParamsSchema = z.object({
+  id: z.coerce.number().int().positive(),
+})

backend/src/api/public/v1/stewardships/updateStatus.ts

@@ -0,0 +1,45 @@
+import type { Request, Response } from 'express'
+import { z } from 'zod'
+
+import { NotFoundError } from '@crowd/common'
+import {
+  INACTIVE_REASONS,
+  STEWARDSHIP_UPDATABLE_STATUSES,
+  updateStewardshipStatus,
+} from '@crowd/data-access-layer'
+
+import { getPackagesQx } from '@/db/packagesDb'
+import { ok } from '@/utils/api'
+import { validateOrThrow } from '@/utils/validation'
+
+import { stewardshipIdParamsSchema } from './schemas'
+
+const bodySchema = z
+  .object({
+    status: z.enum(STEWARDSHIP_UPDATABLE_STATUSES),
+    inactiveReason: z.enum(INACTIVE_REASONS).optional(),
+    notes: z.string().trim().min(1).optional(),
+  })
+  .refine((d) => d.status !== 'inactive' || !!d.inactiveReason, {
+    message: 'inactiveReason is required when status is inactive',
+    path: ['inactiveReason'],
+  })
+
+export async function updateStatusHandler(req: Request, res: Response): Promise<void> {
+  const { id } = validateOrThrow(stewardshipIdParamsSchema, req.params)
+  const { status, inactiveReason, notes } = validateOrThrow(bodySchema, req.body)
+
+  const qx = await getPackagesQx()
+  const stewardship = await updateStewardshipStatus(qx, id, {
+    status,
+    inactiveReason,
+    notes,
+    actorUserId: req.actor.id,
+  })
+
+  if (!stewardship) {
+    throw new NotFoundError(`Stewardship not found: ${id}`)
+  }
+
+  ok(res, { stewardship })
+}