typescript-express-route-discoverability

Answer

Root cause (DOGFOOD-006): GET /api/v1/parent/progress had no route — only GET /progress/:parentId existed, so the param-less path fell through to Express's 404 handler even for valid JWTs.

Fix pattern — add a token-resolved param-less alias. getRequestedParentId() is a shared resolver: explicit URL :parentId first (backwards-compat), falling back to parentService.getProfileByUserId(user.id) from the JWT. Route ordering matters: exact /progress must be registered before /progress/:parentId.

// src/routes/parent.ts
import { Router, Request, Response, NextFunction } from 'express';
import { parentService } from '../services/parentService';

export const parentRouter = Router();

interface AuthedRequest extends Request {
  user?: { id: string }; // injected by requireAuth JWT middleware
}

/** Resolve effective parentId: explicit :parentId param, else from JWT profile. */
async function getRequestedParentId(req: AuthedRequest, res: Response): Promise<string | null> {
  const paramParentId = req.params.parentId;
  if (typeof paramParentId === 'string') return paramParentId; // fallback path

  const userId = req.user?.id;
  if (!userId) {
    res.status(401).json({ error: 'Unauthorized' });
    return null;
  }
  const profile = await parentService.getProfileByUserId(userId);
  if (!profile) {
    res.status(404).json({ error: 'No parent profile linked to this account',
                           code: 'PARENT_PROFILE_NOT_FOUND' });
    return null;
  }
  return profile.id;
}

// ── ORDER MATTERS: exact route FIRST, then :parentId ──────────────────────
// GET /api/v1/parent/progress — token-resolved alias (the fix)
parentRouter.get('/progress', async (req: AuthedRequest, res: Response, next: NextFunction) => {
  try {
    const parentId = await getRequestedParentId(req, res);
    if (!parentId) return;
    res.json({ data: await parentService.getProgress(parentId) });
  } catch (err) { next(err); }
});

// GET /api/v1/parent/progress/:parentId — explicit id (stays AFTER /progress)
parentRouter.get('/progress/:parentId', async (req: AuthedRequest, res: Response, next: NextFunction) => {
  try {
    res.json({ data: await parentService.getProgress(
      typeof req.params.parentId === 'string' ? req.params.parentId : '') });
  } catch (err) { next(err); }
});

OpenAPI fix — document the param-less route and the quiz requestBody; options must be [{ text, isCorrect }] objects, not strings:

# src/openapi/parent.yaml (excerpt)
paths:
  /api/v1/parent/progress:
    get:
      summary: Progress for children of the authenticated parent (parentId from JWT)
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: Progress entries for linked children }
        '401': { description: Missing/invalid token }
        '404': { description: No parent profile linked to this account }
  /api/v1/parent/progress/{parentId}:
    get:
      parameters:
        - { name: parentId, in: path, required: true, schema: { type: string } }
      # ...same 200/404 responses (backwards-compatible path)

components:
  schemas:
    QuizOption:            # ← objects, NOT strings
      type: object
      required: [text, isCorrect]
      additionalProperties: false
      properties:
        text: { type: string }
        isCorrect: { type: boolean }
    QuizAnswer:
      type: object
      required: [questionId, options]
      properties:
        questionId: { type: string }
        options: { type: array, minItems: 1, items: { $ref: '#/components/schemas/QuizOption' } }
    QuizSubmission:
      type: object
      required: [quizId, answers]
      properties:
        quizId: { type: string }
        answers: { type: array, items: { $ref: '#/components/schemas/QuizAnswer' } }
  # /api/v1/parent/quiz/{quizId}/submit:
  #   post.requestBody.content['application/json'].schema → $ref QuizSubmission

Enforced at runtime with a small guard (returns 422 INVALID_OPTIONS_SHAPE if any option is a string):

const isQuizOption = (o: unknown): o is { text: string; isCorrect: boolean } =>
  typeof o === 'object' && o !== null &&
  typeof (o as any).text === 'string' && typeof (o as any).isCorrect === 'boolean';
// validateQuizPayload: every answer.options must pass .every(isQuizOption)

Regression tests (the 2 required + 4 edge cases) hit a live Express server via fetch:

// T1: GET /api/v1/parent/progress (Bearer user_42) → expect 200, data.length === 2
// T2: GET /api/v1/parent/progress (Bearer user_without_profile) → expect 404 PARENT_PROFILE_NOT_FOUND
// T3: GET /api/v1/parent/progress/prof_abc123 → expect 200 (explicit-param fallback intact)
// T4: GET /api/v1/parent/progress → expect 200 + data (exact route matched, not :parentId)
// T5: POST quiz submit with options: ['Paris','Rome'] → expect 422
// T6: POST quiz submit with options: [{text,isCorrect}...] → expect 200