(SP:2) feat(api): clean up AI helper for Vercel & fix orders i18n (#245)

- Refactor /api/ai/explain route for Vercel deployment
    - Replace dynamic import with static import of groq-sdk
    - Use request.json() instead of Netlify-safe body parsing
    - Add proper error handling with Groq.APIError types
    - Simplify GET health check endpoint
    - Update model from llama3-70b-8192 to llama-3.3-70b-versatile
- Add table.openOrder and table.orderId to en/uk/pl locales

Author: TiZorii

frontend/app/api/ai/explain/route.ts

@@ -2,53 +2,16 @@ export const runtime = 'nodejs';
 
 import { NextRequest, NextResponse } from 'next/server';
 import { z } from 'zod';
+import Groq from 'groq-sdk';
 import {
   createExplainPrompt,
   type ExplanationResponse,
 } from '@/lib/ai/prompts';
 import { getClientIp } from '@/lib/security/client-ip';
 
 // =============================================================================
-// SERVER-SIDE LOGGING (sanitized - no sensitive data exposed)
+// Rate Limiter (in-memory, resets on cold start)
 // =============================================================================
-function logEnvironmentDiagnostics() {
-  const apiKey = process.env.GROQ_API_KEY;
-  console.log('[ENV] GROQ_API_KEY configured:', !!apiKey);
-  console.log('[ENV] NODE_ENV:', process.env.NODE_ENV);
-}
-
-function logRequestDiagnostics(request: NextRequest) {
-  console.log('[REQ] Method:', request.method);
-  console.log('[REQ] URL path:', new URL(request.url).pathname);
-}
-
-function logBodyParsingResult(success: boolean, error?: unknown) {
-  console.log('[BODY] Parse success:', success);
-  if (error) {
-    console.log('[BODY] Parse error:', error instanceof Error ? error.message : 'Unknown error');
-  }
-}
-
-function logGroqInitialization(success: boolean, error?: unknown) {
-  console.log('[GROQ] Init success:', success);
-  if (error) {
-    const err = error as Error & { status?: number; code?: string };
-    console.log('[GROQ] Init error:', err.name, err.message);
-  }
-}
-
-function logGroqApiCall(phase: 'start' | 'success' | 'error', details?: unknown) {
-  if (phase === 'start') {
-    console.log('[GROQ] Starting API call');
-  } else if (phase === 'success') {
-    console.log('[GROQ] API call successful');
-  } else if (phase === 'error') {
-    const err = details as Error & { status?: number; code?: string };
-    console.log('[GROQ] API error:', err?.name, err?.message);
-  }
-}
-// =============================================================================
-
 const rateLimiter = new Map<string, { count: number; resetAt: number }>();
 const MAX_REQUESTS_PER_WINDOW = 10;
 const RATE_LIMIT_WINDOW_MS = 20 * 60 * 1000;
@@ -136,22 +99,21 @@ function parseExplanationResponse(content: string): ExplanationResponse {
   return parsed as ExplanationResponse;
 }
 
+// =============================================================================
+// POST /api/ai/explain - Generate term explanation in 3 languages
+// =============================================================================
 export async function POST(request: NextRequest) {
-  logEnvironmentDiagnostics();
-  logRequestDiagnostics(request);
-
+  // Fail fast if API key is missing
   const apiKey = process.env.GROQ_API_KEY;
   if (!apiKey) {
-    console.error('[FATAL] GROQ_API_KEY is not configured. Check environment variables.');
+    console.error('[ai/explain] GROQ_API_KEY not configured');
     return NextResponse.json(
-      {
-        error: 'AI service not configured',
-        code: 'SERVICE_UNAVAILABLE',
-      },
+      { error: 'AI service not configured', code: 'SERVICE_UNAVAILABLE' },
       { status: 503 }
     );
   }
 
+  // Rate limiting
   const clientIp = getClientIp(request) ?? 'unknown';
   const rateLimit = checkRateLimit(clientIp);
 
@@ -174,21 +136,11 @@ export async function POST(request: NextRequest) {
     );
   }
 
-  // Safe JSON body parsing for Netlify
+  // Parse and validate request body
   let body: unknown;
   try {
-    const text = await request.text();
-    if (!text || text.trim() === '') {
-      console.log('[BODY] Empty request body received');
-      return NextResponse.json(
-        { error: 'Request body is empty', code: 'EMPTY_BODY' },
-        { status: 400 }
-      );
-    }
-    body = JSON.parse(text);
-    logBodyParsingResult(true);
-  } catch (parseError) {
-    logBodyParsingResult(false, parseError);
+    body = await request.json();
+  } catch {
     return NextResponse.json(
       { error: 'Invalid JSON body', code: 'INVALID_JSON' },
       { status: 400 }
@@ -209,65 +161,28 @@ export async function POST(request: NextRequest) {
 
   const { term, context } = validationResult.data;
 
-  // Dynamic import for Netlify compatibility
-  let Groq: typeof import('groq-sdk').default;
-  try {
-    const groqModule = await import('groq-sdk');
-    Groq = groqModule.default;
-  } catch (importError) {
-    console.error('[SDK_IMPORT_ERROR] Failed to import groq-sdk:',
-      importError instanceof Error ? importError.message : String(importError)
-    );
-    return NextResponse.json(
-      {
-        error: 'Failed to load AI client',
-        code: 'SDK_IMPORT_ERROR',
-      },
-      { status: 503 }
-    );
-  }
-
-  let groq: InstanceType<typeof Groq>;
-  try {
-    groq = new Groq({ apiKey });
-    logGroqInitialization(true);
-  } catch (initError) {
-    logGroqInitialization(false, initError);
-    console.error('[SDK_INIT_ERROR] Failed to initialize Groq client:',
-      initError instanceof Error ? initError.message : String(initError)
-    );
-    return NextResponse.json(
-      {
-        error: 'Failed to initialize AI client',
-        code: 'SDK_INIT_ERROR',
-      },
-      { status: 503 }
-    );
-  }
+  // Initialize Groq client
+  const groq = new Groq({ apiKey });
 
   try {
     const prompt = createExplainPrompt({ term, context });
 
-    logGroqApiCall('start');
     const chatCompletion = await groq.chat.completions.create({
-      messages: [
-        {
-          role: 'user',
-          content: prompt,
-        },
-      ],
-      model: 'llama3-70b-8192',
+      messages: [{ role: 'user', content: prompt }],
+      model: 'llama-3.3-70b-versatile',
       temperature: 0.7,
       max_tokens: 1500,
       top_p: 1,
     });
-    logGroqApiCall('success', chatCompletion);
 
     const content = chatCompletion.choices[0]?.message?.content;
 
     if (!content) {
-      console.error('[ERROR] No content in Groq response');
-      throw new Error('No content in response');
+      console.error('[ai/explain] Empty response from Groq');
+      return NextResponse.json(
+        { error: 'AI returned empty response', code: 'EMPTY_RESPONSE' },
+        { status: 502 }
+      );
     }
 
     const explanation = parseExplanationResponse(content);
@@ -281,64 +196,87 @@ export async function POST(request: NextRequest) {
       },
     });
   } catch (error) {
-    logGroqApiCall('error', error);
-    console.error('[GROQ_ERROR]', error instanceof Error ? error.message : 'Unknown error');
-
-    if (error instanceof Error) {
-      if (
-        error.message.includes('401') ||
-        error.message.includes('authentication') ||
-        error.message.includes('Invalid API Key')
-      ) {
-        console.error('[AUTH_ERROR] API key authentication failed');
-        return NextResponse.json(
-          {
-            error: 'AI service authentication failed',
-            code: 'AUTH_ERROR',
-          },
-          { status: 503 }
-        );
-      }
-      if (
-        error.message.includes('429') ||
-        error.message.includes('rate limit')
-      ) {
-        return NextResponse.json(
-          { error: 'AI service rate limited', code: 'API_RATE_LIMITED' },
-          { status: 503 }
-        );
-      }
-      if (error.message.includes('model')) {
-        return NextResponse.json(
-          {
-            error: 'AI model not available',
-            code: 'MODEL_ERROR',
-          },
-          { status: 503 }
-        );
-      }
-    }
+    return handleGroqError(error);
+  }
+}
+
+// =============================================================================
+// GET /api/ai/explain - Health check
+// =============================================================================
+export async function GET() {
+  const hasApiKey = !!process.env.GROQ_API_KEY;
 
+  if (!hasApiKey) {
     return NextResponse.json(
-      {
-        error: 'Failed to generate explanation',
-        code: 'AI_ERROR',
-      },
-      { status: 500 }
+      { status: 'error', service: 'ai-explain', message: 'API key not configured' },
+      { status: 503 }
     );
   }
-}
 
-export async function GET() {
   return NextResponse.json(
-    {
-      status: 'ok',
-      service: 'ai-explain',
-      env: {
-        hasGroqKey: !!process.env.GROQ_API_KEY,
-        nodeEnv: process.env.NODE_ENV,
-      },
-    },
+    { status: 'ok', service: 'ai-explain' },
     { status: 200 }
   );
 }
+
+// =============================================================================
+// Error Handling
+// =============================================================================
+function handleGroqError(error: unknown): NextResponse {
+  // Handle Groq SDK specific errors
+  if (error instanceof Groq.APIError) {
+    console.error(`[ai/explain] Groq API error: ${error.status} ${error.message}`);
+
+    if (error.status === 401) {
+      return NextResponse.json(
+        { error: 'AI service authentication failed', code: 'AUTH_ERROR' },
+        { status: 503 }
+      );
+    }
+
+    if (error.status === 429) {
+      return NextResponse.json(
+        { error: 'AI service rate limited', code: 'API_RATE_LIMITED' },
+        { status: 503 }
+      );
+    }
+
+    if (error.status === 404) {
+      return NextResponse.json(
+        { error: 'AI model not available', code: 'MODEL_ERROR' },
+        { status: 503 }
+      );
+    }
+
+    // Other API errors (500, 503, etc.)
+    return NextResponse.json(
+      { error: 'AI service temporarily unavailable', code: 'API_ERROR' },
+      { status: 503 }
+    );
+  }
+
+  // Handle JSON parse errors from response parsing
+  if (error instanceof SyntaxError) {
+    console.error('[ai/explain] Failed to parse AI response as JSON');
+    return NextResponse.json(
+      { error: 'AI returned invalid format', code: 'PARSE_ERROR' },
+      { status: 502 }
+    );
+  }
+
+  // Handle response structure validation errors
+  if (error instanceof Error && error.message === 'Invalid response structure') {
+    console.error('[ai/explain] AI response missing required fields');
+    return NextResponse.json(
+      { error: 'AI returned incomplete response', code: 'INVALID_STRUCTURE' },
+      { status: 502 }
+    );
+  }
+
+  // Unknown errors
+  console.error('[ai/explain] Unexpected error:', error);
+  return NextResponse.json(
+    { error: 'Failed to generate explanation', code: 'AI_ERROR' },
+    { status: 500 }
+  );
+}

frontend/messages/en.json

@@ -547,7 +547,9 @@
         "items": "Items",
         "date": "Date",
         "status": "Status",
-        "total": "Total"
+        "total": "Total",
+        "openOrder": "Open order {id}",
+        "orderId": "Order ID"
       },
       "orderHeadline": {
         "incomplete": "Order {id} (incomplete)",
@@ -921,7 +923,7 @@
     }
   },
   "onlineCounter": {
-    "one": "you are one step closer to the goal",
+    "one": "one step closer to the goal",
     "two": "chasing the dream",
     "upToFive": "on the way to an offer",
     "upToTen": "closer to the dream job",

frontend/messages/pl.json

@@ -547,7 +547,9 @@
         "items": "Produkty",
         "date": "Data",
         "status": "Status",
-        "total": "Razem"
+        "total": "Razem",
+        "openOrder": "Otwórz zamówienie {id}",
+        "orderId": "ID zamówienia"
       },
       "orderHeadline": {
         "incomplete": "Zamówienie {id} (niekompletne)",

frontend/messages/uk.json

@@ -547,7 +547,9 @@
         "items": "Товари",
         "date": "Дата",
         "status": "Статус",
-        "total": "Всього"
+        "total": "Всього",
+        "openOrder": "Відкрити замовлення {id}",
+        "orderId": "ID замовлення"
       },
       "orderHeadline": {
         "incomplete": "Замовлення {id} (незавершене)",
@@ -921,7 +923,7 @@
     }
   },
   "onlineCounter": {
-    "one": "ти на крок до цілі",
+    "one": "на крок до цілі",
     "two": "йдуть до мрії",
     "upToFive": "на шляху до оффера",
     "upToTen": "ближчі до dream job",