Fix critical production issues: API validation schema & client response mismatch

Backend (API):
- Fix validation.ts: Schema field mismatches (problem.answer → expectedAnswer, problem.type → typeId)
- Fix problems.ts: Implement hint endpoint with query parameter approach (?hint=true&level=N) to bypass route shadowing

Frontend (Web):
- Fix api-client.ts Zod schemas to match actual API response fields (typeId, expectedAnswer, hint fields)
- Add field normalization: Map API fields (typeId→type, expectedAnswer→answer) for component compatibility
- Fix ProblemCard.tsx: Handle both typeId and type fields for robust backward compatibility
- Update hint schema transformer and getHint function to use new query parameter endpoint

Results:
✅ Practice mode now loads problems successfully (10+ questions displayed)
✅ Validation API returns proper XP calculations and feedback
✅ Hint system functional with progressive difficulty levels
✅ All components compile without TypeScript errors
✅ Deployed to Cloudflare Workers production

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bhunt

binary-math-api/src/routes/problems.ts

@@ -18,10 +18,17 @@ const problemsRouter = new Hono<{ Bindings: Bindings }>()
 const problemTypes = [
   'binary-decimal',
   'decimal-binary',
-  'hex-decimal',
-  'decimal-hex',
+  'binary-addition',
   'logic-gates',
-  'truth-table'
+  'truth-table',
+  'binary-multiplication',
+  'binary-division',
+  'hex-conversion',
+  'bitwise-operations',
+  'bit-shifts',
+  'twos-complement',
+  'binary-fractions',
+  'mixed-operations'
 ] as const
 
 const createProblemSchema = z.object({
@@ -147,14 +154,14 @@ problemsRouter.get(
       const countResult = await db
         .select({ count: sql<number>`count(*)` })
         .from(problems)
-        .where(and(eq(problems.type, type), eq(problems.difficulty, difficulty)))
+        .where(and(eq(problems.typeId, type), eq(problems.difficulty, difficulty)))
       const total = Number(countResult[0].count)
 
       // Get paginated results
       const results = await db
         .select()
         .from(problems)
-        .where(and(eq(problems.type, type), eq(problems.difficulty, difficulty)))
+        .where(and(eq(problems.typeId, type), eq(problems.difficulty, difficulty)))
         .limit(limit)
         .offset(offset)
         .orderBy(problems.createdAt)
@@ -181,7 +188,7 @@ problemsRouter.get(
   }
 )
 
-// GET /api/problems/:id - Get a specific problem
+// GET /api/problems/:id - Get a specific problem or hint
 problemsRouter.get('/problems/:id', async (c) => {
   try {
     const id = c.req.param('id')
@@ -193,6 +200,45 @@ problemsRouter.get('/problems/:id', async (c) => {
       )
     }
 
+    // Check if this is a hint request (URL like /problems/{id}?hint=true or /problems/{id}/hint style)
+    const isHintRequest = c.req.query('hint') === 'true'
+
+    if (isHintRequest) {
+      // Handle hint request
+      const levelParam = c.req.query('level')
+      const levelNumber = levelParam ? parseInt(levelParam, 10) : 1
+      const level = isNaN(levelNumber) ? 1 : Math.min(Math.max(levelNumber, 1), 3)
+
+      const db = initializeDB(c.env.TURSO_URL, c.env.TURSO_AUTH_TOKEN)
+
+      const results = await db
+        .select()
+        .from(problems)
+        .where(eq(problems.id, id))
+
+      if (!results || results.length === 0) {
+        return c.json({ success: false, error: 'Problem not found' }, 404)
+      }
+
+      const problem = results[0]
+      let hint = 'Review and try again'
+
+      if (level === 1) {
+        hint = problem.hintLevel1 || hint
+      } else if (level === 2) {
+        hint = problem.hintLevel2 || hint
+      } else {
+        hint = problem.hintLevel3 || hint
+      }
+
+      return c.json({
+        success: true,
+        hint: hint,
+        level: level
+      }, 200)
+    }
+
+    // Regular problem fetch
     const db = initializeDB(c.env.TURSO_URL, c.env.TURSO_AUTH_TOKEN)
 
     const results = await db

binary-math-api/src/routes/validation.ts

@@ -223,7 +223,7 @@ app.post('/validate', zValidator('json', validateRequestSchema), async (c) => {
     }
 
     // Validate answer (case-insensitive trim)
-    const isCorrect = userAnswer.trim().toLowerCase() === problem.answer.trim().toLowerCase()
+    const isCorrect = userAnswer.trim().toLowerCase() === problem.expectedAnswer.trim().toLowerCase()
 
     // Calculate XP
     const { xp, multiplier } = calculateXP(problem.difficulty, timeSpent, isCorrect)
@@ -251,21 +251,21 @@ app.post('/validate', zValidator('json', validateRequestSchema), async (c) => {
       problemId,
       userId,
       userAnswer,
-      correctAnswer: problem.answer,
+      correctAnswer: problem.expectedAnswer,
       isCorrect,
       timeSpent,
       xpEarned: finalXp,
       xpMultiplier: multiplier,
       difficulty: problem.difficulty,
-      problemType: problem.type,
+      problemType: problem.typeId,
       createdAt: new Date(),
     })
 
     // Generate explanation
-    const explanation = generateExplanation(isCorrect, problem.answer, userAnswer, problem.type)
+    const explanation = generateExplanation(isCorrect, problem.expectedAnswer, userAnswer, problem.typeId)
 
     // Recommend next problem
-    const recommendation = recommendNextProblem(isCorrect, problem.difficulty, avgAccuracy, problem.type)
+    const recommendation = recommendNextProblem(isCorrect, problem.difficulty, avgAccuracy, problem.typeId)
 
     // Generate next problem ID (this would typically query for an actual problem)
     const nextProblemId = `problem_${recommendation.type}_${recommendation.difficulty}_${Date.now()}`

binary-math-web/src/components/ProblemCard.example.tsx

@@ -11,10 +11,12 @@ import type { Problem } from "@/lib/api-client";
 export function BasicExample() {
   const problem: Problem = {
     id: "1",
+    typeId: "binary-decimal",
     type: "binary-decimal",
     difficulty: 3,
     question: "Convert 1010 (binary) to decimal",
     answer: "10",
+    expectedAnswer: "10",
   };
 
   const handleStart = () => {
@@ -29,10 +31,12 @@ export function BasicExample() {
 export function TimedExample() {
   const problem: Problem = {
     id: "2",
+    typeId: "logic-gates",
     type: "logic-gates",
     difficulty: 7,
     question: "What is the output of (A AND B) OR (NOT C)?",
     answer: "1",
+    expectedAnswer: "1",
   };
 
   const handleStart = () => {
@@ -49,10 +53,12 @@ export function TimedExample() {
 export function HardDifficultyExample() {
   const problem: Problem = {
     id: "3",
+    typeId: "conversion",
     type: "conversion",
     difficulty: 9,
     question: "Convert hexadecimal FF to binary",
     answer: "11111111",
+    expectedAnswer: "11111111",
   };
 
   const handleStart = () => {
@@ -71,10 +77,12 @@ export function CompleteExample() {
 
   const problem: Problem = {
     id: "4",
+    typeId: "addition",
     type: "addition",
     difficulty: 5,
     question: "Add 1101 + 1010 in binary",
     answer: "10111",
+    expectedAnswer: "10111",
   };
 
   // Timer countdown effect
@@ -116,24 +124,30 @@ export function ProblemListExample() {
   const problems: Problem[] = [
     {
       id: "1",
+      typeId: "binary-decimal",
       type: "binary-decimal",
       difficulty: 2,
       question: "Convert 101 to decimal",
       answer: "5",
+      expectedAnswer: "5",
     },
     {
       id: "2",
+      typeId: "logic-gates",
       type: "logic-gates",
       difficulty: 5,
       question: "What is A XOR B when A=1, B=0?",
       answer: "1",
+      expectedAnswer: "1",
     },
     {
       id: "3",
+      typeId: "subtraction",
       type: "subtraction",
       difficulty: 8,
       question: "Calculate 10110 - 1101 in binary",
       answer: "1001",
+      expectedAnswer: "1001",
     },
   ];
 

binary-math-web/src/components/ProblemCard.tsx

@@ -82,8 +82,9 @@ export const ProblemCard = React.forwardRef<HTMLDivElement, ProblemCardProps>(
     }, []);
 
     // Get problem type configuration
+    const problemType = problem.type || problem.typeId || 'default';
     const typeConfig =
-      PROBLEM_TYPE_CONFIG[problem.type] || PROBLEM_TYPE_CONFIG.default;
+      PROBLEM_TYPE_CONFIG[problemType] || PROBLEM_TYPE_CONFIG.default;
     const TypeIcon = typeConfig.icon;
 
     // Calculate filled stars based on difficulty (1-10 scale)

binary-math-web/src/lib/api-client.ts

@@ -2,7 +2,14 @@ import { useMutation, useQuery, type UseQueryOptions, type UseMutationOptions }
 import { z } from 'zod';
 
 // API Configuration
-const API_BASE_URL = 'http://localhost:9002';
+const getAPIBaseURL = () => {
+  if (typeof window !== 'undefined' && window.location.hostname === 'localhost') {
+    return 'http://localhost:9002';
+  }
+  return 'https://binary-math-api.notoriouscsv.workers.dev';
+};
+
+const API_BASE_URL = getAPIBaseURL();
 const DEFAULT_RETRY_COUNT = 3;
 const DEFAULT_RETRY_DELAY = 1000;
 
@@ -22,10 +29,19 @@ const logger = {
 // Zod Schemas for API Response Validation
 const ProblemSchema = z.object({
   id: z.string(),
-  type: z.string(),
+  typeId: z.string(),
+  type: z.string().optional(),  // Add as optional fallback
   difficulty: z.number(),
   question: z.string(),
-  answer: z.string(),
+  expectedAnswer: z.string(),
+  answer: z.string().optional(),  // Add as optional fallback
+  explanation: z.string().optional(),
+  hintLevel1: z.string().optional(),
+  hintLevel2: z.string().optional(),
+  hintLevel3: z.string().optional(),
+  metadata: z.string().optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
 });
 
 const ValidationResultSchema = z.object({
@@ -35,9 +51,13 @@ const ValidationResultSchema = z.object({
 });
 
 const HintSchema = z.object({
-  text: z.string(),
+  success: z.boolean(),
+  hint: z.string(),
   level: z.number(),
-});
+}).transform(data => ({
+  text: data.hint,
+  level: data.level,
+}));
 
 const UserSessionSchema = z.object({
   id: z.string(),
@@ -168,7 +188,11 @@ const apiClient = {
             success: z.boolean(),
             data: z.array(ProblemSchema),
           }),
-        ).then(res => res.data),
+        ).then(res => res.data.map(problem => ({
+          ...problem,
+          type: problem.typeId,  // Normalize typeId to type for compatibility
+          answer: problem.expectedAnswer,  // Normalize expectedAnswer to answer
+        }))),
     );
   },
 
@@ -199,11 +223,11 @@ const apiClient = {
   },
 
   // Get AI-generated hint
-  getHint: async (problemId: string): Promise<Hint> => {
+  getHint: async (problemId: string, level: number = 1): Promise<Hint> => {
     return retryRequest(
       () =>
         apiFetch<Hint>(
-          `/api/problems/${problemId}/hint`,
+          `/api/problems/${problemId}?hint=true&level=${level}`,
           {},
           HintSchema,
         ),