feat: implement Vercel Next.js server-side API proxy architecture to eliminate browser CORS

frontend/.env.example

@@ -1,2 +1,3 @@
-# RazorShield Frontend Environment Variables
+# RazorShield Frontend Environment Variables (Server-Only Backend URL)
+RAZORSHIELD_BACKEND_URL=https://vedantjadhav701-razorshield-api.hf.space
 NEXT_PUBLIC_API_URL=https://vedantjadhav701-razorshield-api.hf.space

frontend/app/api/explain/route.ts

@@ -0,0 +1,26 @@
+import { NextRequest, NextResponse } from "next/server";
+import { explainEvidence } from "@/lib/server/razorshield";
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const evidenceJson = typeof body.evidence_json === "string" ? body.evidence_json : JSON.stringify(body);
+    const result = await explainEvidence(evidenceJson);
+    if (!result.success) {
+      return NextResponse.json(result, { status: 500 });
+    }
+    return NextResponse.json(result, { status: 200 });
+  } catch (err: any) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: {
+          code: "INVALID_REQUEST",
+          message: "Failed to parse JSON body for explanation.",
+          details: err.message,
+        },
+      },
+      { status: 400 }
+    );
+  }
+}

frontend/app/api/health/route.ts

@@ -0,0 +1,10 @@
+import { NextResponse } from "next/server";
+import { healthCheck } from "@/lib/server/razorshield";
+
+export async function GET() {
+  const result = await healthCheck();
+  if (!result.success) {
+    return NextResponse.json(result, { status: 503 });
+  }
+  return NextResponse.json(result, { status: 200 });
+}

frontend/app/api/merchant/route.ts

@@ -0,0 +1,26 @@
+import { NextRequest, NextResponse } from "next/server";
+import { analyzeMerchant } from "@/lib/server/razorshield";
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const merchantId = body.merchant_id || "M_101";
+    const result = await analyzeMerchant(merchantId);
+    if (!result.success) {
+      return NextResponse.json(result, { status: 500 });
+    }
+    return NextResponse.json(result, { status: 200 });
+  } catch (err: any) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: {
+          code: "INVALID_REQUEST",
+          message: "Failed to parse JSON request body.",
+          details: err.message,
+        },
+      },
+      { status: 400 }
+    );
+  }
+}

frontend/app/api/reset/route.ts

@@ -0,0 +1,10 @@
+import { NextResponse } from "next/server";
+import { resetDemoState } from "@/lib/server/razorshield";
+
+export async function POST() {
+  const result = await resetDemoState();
+  if (!result.success) {
+    return NextResponse.json(result, { status: 500 });
+  }
+  return NextResponse.json(result, { status: 200 });
+}

frontend/app/api/scenario/route.ts

@@ -0,0 +1,27 @@
+import { NextRequest, NextResponse } from "next/server";
+import { runScenario } from "@/lib/server/razorshield";
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const scenarioName = body.scenario_name || "FRAUD_SPIKE";
+    const policyMode = body.policy_mode || "BALANCED";
+    const result = await runScenario(scenarioName, policyMode);
+    if (!result.success) {
+      return NextResponse.json(result, { status: 500 });
+    }
+    return NextResponse.json(result, { status: 200 });
+  } catch (err: any) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: {
+          code: "INVALID_REQUEST",
+          message: "Failed to parse JSON body for scenario replay.",
+          details: err.message,
+        },
+      },
+      { status: 400 }
+    );
+  }
+}

frontend/app/api/transaction/route.ts

@@ -0,0 +1,25 @@
+import { NextRequest, NextResponse } from "next/server";
+import { analyzeTransaction } from "@/lib/server/razorshield";
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const result = await analyzeTransaction(body);
+    if (!result.success) {
+      return NextResponse.json(result, { status: 500 });
+    }
+    return NextResponse.json(result, { status: 200 });
+  } catch (err: any) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: {
+          code: "INVALID_REQUEST",
+          message: "Failed to parse JSON body or invalid transaction payload.",
+          details: err.message,
+        },
+      },
+      { status: 400 }
+    );
+  }
+}

frontend/lib/api.ts

@@ -1,10 +1,10 @@
 /**
  * api.ts
- * Hugging Face Gradio Space API Integration Layer.
- * Communicates with backend Space: vedantjadhav701/razorshield-api
+ * Browser-Side API Client.
+ * Communicates ONLY with same-origin Next.js Server Route Handlers (/api/...).
+ * The browser never connects directly to Hugging Face Spaces.
  */
 
-import { Client } from "@gradio/client";
 import {
   AnalyzeTransactionResponse,
   BackendHealthStatus,
@@ -14,80 +14,42 @@ import {
   TransactionApiInput,
 } from "./types";
 
-const SPACE_NAME = "vedantjadhav701/razorshield-api";
-const DEFAULT_URL = process.env.NEXT_PUBLIC_API_URL || `https://${SPACE_NAME.replace("/", "-")}.hf.space`;
-
-let gradioClient: Client | null = null;
-
 function generateRequestId(): string {
   return `REQ_${Math.random().toString(36).substring(2, 8).toUpperCase()}`;
 }
 
-async function getClient(): Promise<Client | null> {
-  if (gradioClient) return gradioClient;
-  try {
-    gradioClient = await Client.connect(SPACE_NAME);
-    return gradioClient;
-  } catch (err) {
-    console.warn("Gradio Client connection warning. Falling back to direct HTTP fetch:", err);
-    return null;
-  }
-}
-
 /**
- * Real Backend Health Check Handshake
+ * Health check probe via /api/health
  */
 export async function checkBackendHealth(): Promise<BackendHealthStatus> {
   const start = performance.now();
   const sentAt = new Date().toISOString();
   try {
-    const client = await getClient();
-    if (client) {
-      // Test prediction on analyze_merchant
-      await client.predict("analyze_merchant", ["M_HEALTH_CHECK"]);
-      const latency = Math.round(performance.now() - start);
-      return {
-        status: "CONNECTED",
-        endpoint: DEFAULT_URL,
-        last_sync_at: new Date().toISOString(),
-        roundtrip_latency_ms: latency,
-      };
-    }
-  } catch (err) {
-    console.warn("Gradio health check error:", err);
-  }
-
-  // HTTP endpoint fallback check
-  try {
-    const res = await fetch(`${DEFAULT_URL}/api/predict/analyze_merchant`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ data: ["M_HEALTH_CHECK"] }),
-    });
+    const res = await fetch("/api/health", { cache: "no-store" });
     const latency = Math.round(performance.now() - start);
     if (res.ok) {
       return {
         status: "CONNECTED",
-        endpoint: DEFAULT_URL,
+        endpoint: "/api/health (Vercel Server Proxy)",
         last_sync_at: new Date().toISOString(),
         roundtrip_latency_ms: latency,
       };
     }
-  } catch (err) {
-    console.error("HTTP health check failed:", err);
+  } catch (err: any) {
+    console.warn("Health check error via /api/health:", err);
   }
 
   return {
     status: "OFFLINE",
-    endpoint: DEFAULT_URL,
+    endpoint: "/api/health",
     last_sync_at: sentAt,
     roundtrip_latency_ms: null,
-    error: "Hugging Face Space unreachable",
+    error: "Server-side RazorShield proxy unreachable",
   };
 }
 
 /**
- * Analyzes a single transaction payload using the deployed Hugging Face Space backend.
+ * Analyzes transaction via POST /api/transaction
  */
 export async function analyzeTransaction(
   input: TransactionApiInput
@@ -96,121 +58,33 @@ export async function analyzeTransaction(
   const sentAt = new Date().toISOString();
   const start = performance.now();
 
-  const mId = input.merchant_id || "M_101";
-  const txId = input.transaction_id || `TX_${Date.now().toString().slice(-6)}`;
-  const custId = input.customer_id || "C_1048";
-  const devId = input.device_id || "D_882";
-  const eventTime = input.event_time || new Date().toISOString();
-  const amount = input.amount || 100.0;
-  const pm = input.payment_method || "card";
-  const tt = input.transaction_type || "sale";
-  const policyMode = input.policy_mode || "BALANCED";
-
-  const client = await getClient();
+  const res = await fetch("/api/transaction", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(input),
+  });
 
-  if (client) {
-    try {
-      const res = await client.predict("analyze_transaction", [
-        mId,
-        txId,
-        custId,
-        devId,
-        eventTime,
-        amount,
-        pm,
-        tt,
-        policyMode,
-      ]);
-      const roundtrip = Math.round(performance.now() - start);
-      const dataStr = Array.isArray(res.data) ? (res.data[0] as string) : String(res.data);
-      const parsed: AnalyzeTransactionResponse = JSON.parse(dataStr);
-      parsed.meta = {
-        request_id: reqId,
-        request_sent_at: sentAt,
-        response_received_at: new Date().toISOString(),
-        roundtrip_latency_ms: roundtrip,
-        data_source: "LIVE HUGGING FACE BACKEND",
-      };
-      return parsed;
-    } catch (err) {
-      console.error("Gradio predict error for analyze_transaction:", err);
-    }
-  }
+  const roundtrip = Math.round(performance.now() - start);
+  const json = await res.json();
 
-  // HTTP Direct Fallback
-  try {
-    const httpRes = await fetch(`${DEFAULT_URL}/api/predict/analyze_transaction`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        data: [mId, txId, custId, devId, eventTime, amount, pm, tt, policyMode],
-      }),
-    });
-    const roundtrip = Math.round(performance.now() - start);
-    if (httpRes.ok) {
-      const json = await httpRes.json();
-      const rawText = Array.isArray(json.data) ? json.data[0] : json.data;
-      const parsed: AnalyzeTransactionResponse = JSON.parse(rawText);
-      parsed.meta = {
-        request_id: reqId,
-        request_sent_at: sentAt,
-        response_received_at: new Date().toISOString(),
-        roundtrip_latency_ms: roundtrip,
-        data_source: "LIVE HUGGING FACE BACKEND",
-      };
-      return parsed;
-    }
-  } catch (httpErr) {
-    console.warn("Direct HTTP endpoint unavailable:", httpErr);
+  if (!res.ok || !json.success || !json.data) {
+    throw new Error(json?.error?.message || `Transaction analysis failed with HTTP ${res.status}`);
   }
 
-  // Deterministic Client Fallback
-  const roundtrip = Math.round(performance.now() - start);
-  return {
-    transaction_id: txId,
-    merchant_id: mId,
-    transaction_risk: { fraud_probability: 0.012 },
-    merchant_risk: {
-      spike_probability: 0.04,
-      fraud_excess_ratio: 1.0,
-      velocity_ratio: 1.0,
-      incident_state: "NORMAL",
-      severity: "LOW",
-      incident_score: 0.06,
-      suspicious_windows: 0,
-    },
-    campaign: { active: false, campaign_name: null },
-    decision: { action: "APPROVE", policy_mode: policyMode },
-    explanation: {
-      title: "RazorShield Defensive Risk Assessment: NORMAL (LOW Severity)",
-      summary: `RazorShield evaluated merchant ${mId} activity as NORMAL (LOW severity). Observed fraud excess ratio is 1.0x baseline and volume velocity is 1.0x baseline.`,
-      key_signals: [
-        "Policy Incident Score: 0.06",
-        "Fraud Excess Ratio: 1.0x baseline",
-        "Volume Velocity Ratio: 1.0x baseline",
-        "Consecutive Suspicious Windows: 0",
-      ],
-      campaign_context: `No promotional campaign is active for merchant ${mId}.`,
-      recommended_action: "Maintain standard automated processing.",
-      confidence_note: "Explanation generated via deterministic fallback.",
-    },
-    performance: {
-      risk_engine_latency_ms: 0.62,
-      slm_latency_ms: 0.0,
-      total_latency_ms: 0.62,
-    },
-    meta: {
-      request_id: reqId,
-      request_sent_at: sentAt,
-      response_received_at: new Date().toISOString(),
-      roundtrip_latency_ms: roundtrip,
-      data_source: "CLIENT FALLBACK",
-    },
+  const parsed: AnalyzeTransactionResponse = json.data;
+  parsed.meta = {
+    request_id: reqId,
+    request_sent_at: sentAt,
+    response_received_at: new Date().toISOString(),
+    roundtrip_latency_ms: roundtrip,
+    data_source: "LIVE HUGGING FACE BACKEND",
   };
+
+  return parsed;
 }
 
 /**
- * Replays a test scenario through the Hugging Face Space backend.
+ * Replays scenario via POST /api/scenario
  */
 export async function runScenarioReplay(
   scenarioName: string,
@@ -220,164 +94,109 @@ export async function runScenarioReplay(
   const sentAt = new Date().toISOString();
   const start = performance.now();
 
-  const client = await getClient();
+  const res = await fetch("/api/scenario", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ scenario_name: scenarioName, policy_mode: policyMode }),
+  });
 
-  if (client) {
-    try {
-      const res = await client.predict("run_scenario", [scenarioName, policyMode]);
-      const roundtrip = Math.round(performance.now() - start);
-      const dataStr = Array.isArray(res.data) ? (res.data[0] as string) : String(res.data);
-      const parsed: ScenarioReplayResult = JSON.parse(dataStr);
-      parsed.meta = {
-        request_id: reqId,
-        request_sent_at: sentAt,
-        response_received_at: new Date().toISOString(),
-        roundtrip_latency_ms: roundtrip,
-        data_source: "LIVE HUGGING FACE BACKEND",
-      };
-      return parsed;
-    } catch (err) {
-      console.error("Gradio predict error for run_scenario:", err);
-    }
+  const roundtrip = Math.round(performance.now() - start);
+  const json = await res.json();
+
+  if (!res.ok || !json.success || !json.data) {
+    throw new Error(json?.error?.message || `Scenario replay failed with HTTP ${res.status}`);
   }
 
-  // Deterministic Fallback Replay Data
-  const roundtrip = Math.round(performance.now() - start);
-  const isAlert = scenarioName.includes("FRAUD");
-  return {
-    scenario_name: scenarioName,
-    scenario_id: `sc_demo_${Date.now()}`,
-    merchant_id: `M_DEMO_${scenarioName}`,
-    total_transactions: 600,
-    replay_time_ms: 112.5,
-    incident_state_distribution: {
-      NORMAL: isAlert ? 570 : 600,
-      INVESTIGATE: 0,
-      ALERT: isAlert ? 30 : 0,
-    },
-    final_incident_state: isAlert ? "ALERT" : "NORMAL",
-    final_severity: isAlert ? "HIGH" : "LOW",
-    explanation: {
-      title: `RazorShield Defensive Risk Assessment: ${isAlert ? "ALERT" : "NORMAL"}`,
-      summary: isAlert
-        ? "RazorShield classified merchant activity as ALERT due to persistent fraud excess ratio surging to 2.5x baseline across monitoring windows."
-        : "RazorShield classified merchant activity as NORMAL. Volume surge is normalized with fraud excess ratio remaining 1.0x baseline.",
-      key_signals: [
-        `Incident State: ${isAlert ? "ALERT" : "NORMAL"}`,
-        `Fraud Excess Ratio: ${isAlert ? "2.5x" : "1.0x"}`,
-      ],
-      campaign_context: scenarioName.includes("FLASH")
-        ? "Promotional campaign registered. Volume velocity is normalized."
-        : "No campaign active.",
-      recommended_action: isAlert ? "Initiate merchant review & verification." : "Maintain standard processing.",
-      confidence_note: "Deterministic scenario replay result.",
-    },
-    meta: {
-      request_id: reqId,
-      request_sent_at: sentAt,
-      response_received_at: new Date().toISOString(),
-      roundtrip_latency_ms: roundtrip,
-      data_source: "CLIENT FALLBACK",
-    },
+  const parsed: ScenarioReplayResult = json.data;
+  parsed.meta = {
+    request_id: reqId,
+    request_sent_at: sentAt,
+    response_received_at: new Date().toISOString(),
+    roundtrip_latency_ms: roundtrip,
+    data_source: "LIVE HUGGING FACE BACKEND",
   };
+
+  return parsed;
 }
 
 /**
- * Queries live merchant temporal state.
+ * Queries merchant state via POST /api/merchant
  */
 export async function queryMerchantState(merchantId: string): Promise<MerchantStateQueryResponse> {
   const reqId = generateRequestId();
   const sentAt = new Date().toISOString();
   const start = performance.now();
 
-  const client = await getClient();
+  const res = await fetch("/api/merchant", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ merchant_id: merchantId }),
+  });
 
-  if (client) {
-    try {
-      const res = await client.predict("analyze_merchant", [merchantId]);
-      const roundtrip = Math.round(performance.now() - start);
-      const dataStr = Array.isArray(res.data) ? (res.data[0] as string) : String(res.data);
-      const parsed: MerchantStateQueryResponse = JSON.parse(dataStr);
-      parsed.meta = {
-        request_id: reqId,
-        request_sent_at: sentAt,
-        response_received_at: new Date().toISOString(),
-        roundtrip_latency_ms: roundtrip,
-        data_source: "LIVE HUGGING FACE BACKEND",
-      };
-      return parsed;
-    } catch (err) {
-      console.error("Gradio predict error for analyze_merchant:", err);
-    }
+  const roundtrip = Math.round(performance.now() - start);
+  const json = await res.json();
+
+  if (!res.ok || !json.success || !json.data) {
+    throw new Error(json?.error?.message || `Merchant query failed with HTTP ${res.status}`);
   }
 
-  const roundtrip = Math.round(performance.now() - start);
-  return {
-    merchant_id: merchantId,
-    rolling_window: {
-      rolling_txn_count_15m: 15,
-      baseline_txn_count_15m: 15,
-      velocity_ratio: 1.0,
-      estimated_fraud_count: 0.12,
-      expected_fraud_count: 0.12,
-      fraud_excess_ratio: 1.0,
-    },
-    incident_state: {
-      merchant_id: merchantId,
-      current_spike_probability: 0.05,
-      current_fraud_excess_ratio: 1.0,
-      current_velocity_ratio: 1.0,
-      suspicious_transaction_count: 0,
-      consecutive_suspicious_windows: 0,
-      campaign_active: false,
-    },
-    meta: {
-      request_id: reqId,
-      request_sent_at: sentAt,
-      response_received_at: new Date().toISOString(),
-      roundtrip_latency_ms: roundtrip,
-      data_source: "CLIENT FALLBACK",
-    },
+  const parsed: MerchantStateQueryResponse = json.data;
+  parsed.meta = {
+    request_id: reqId,
+    request_sent_at: sentAt,
+    response_received_at: new Date().toISOString(),
+    roundtrip_latency_ms: roundtrip,
+    data_source: "LIVE HUGGING FACE BACKEND",
   };
+
+  return parsed;
 }
 
 /**
- * Resets all demo merchant states.
+ * Explains evidence via POST /api/explain
+ */
+export async function explainEvidencePayload(evidenceJson: string): Promise<any> {
+  const res = await fetch("/api/explain", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ evidence_json: evidenceJson }),
+  });
+
+  const json = await res.json();
+  if (!res.ok || !json.success) {
+    throw new Error(json?.error?.message || `Explanation failed with HTTP ${res.status}`);
+  }
+
+  return json.data;
+}
+
+/**
+ * Resets demo state via POST /api/reset
  */
 export async function resetDemoState(): Promise<{ status: string; message: string; meta?: ResponseMetadata }> {
   const reqId = generateRequestId();
   const sentAt = new Date().toISOString();
   const start = performance.now();
 
-  const client = await getClient();
-  if (client) {
-    try {
-      const res = await client.predict("reset_demo_state", []);
-      const roundtrip = Math.round(performance.now() - start);
-      const dataStr = Array.isArray(res.data) ? (res.data[0] as string) : String(res.data);
-      const parsed = JSON.parse(dataStr);
-      parsed.meta = {
-        request_id: reqId,
-        request_sent_at: sentAt,
-        response_received_at: new Date().toISOString(),
-        roundtrip_latency_ms: roundtrip,
-        data_source: "LIVE HUGGING FACE BACKEND",
-      };
-      return parsed;
-    } catch (err) {
-      console.error("Gradio predict error for reset_demo_state:", err);
-    }
-  }
+  const res = await fetch("/api/reset", {
+    method: "POST",
+  });
+
   const roundtrip = Math.round(performance.now() - start);
-  return {
-    status: "SUCCESS",
-    message: "Demo state reset completed.",
-    meta: {
-      request_id: reqId,
-      request_sent_at: sentAt,
-      response_received_at: new Date().toISOString(),
-      roundtrip_latency_ms: roundtrip,
-      data_source: "CLIENT FALLBACK",
-    },
+  const json = await res.json();
+
+  if (!res.ok || !json.success || !json.data) {
+    throw new Error(json?.error?.message || `Reset demo state failed with HTTP ${res.status}`);
+  }
+
+  const parsed = json.data;
+  parsed.meta = {
+    request_id: reqId,
+    request_sent_at: sentAt,
+    response_received_at: new Date().toISOString(),
+    roundtrip_latency_ms: roundtrip,
+    data_source: "LIVE HUGGING FACE BACKEND",
   };
+
+  return parsed;
 }

frontend/lib/server/razorshield.ts

@@ -0,0 +1,258 @@
+/**
+ * razorshield.ts
+ * Server-Side RazorShield API Client.
+ * Runs exclusively on the Vercel Node.js Server.
+ * Communicates server-to-server with Hugging Face Space backend (Gradio 5+ API).
+ */
+
+import {
+  AnalyzeTransactionResponse,
+  MerchantStateQueryResponse,
+  ScenarioReplayResult,
+  TransactionApiInput,
+} from "../types";
+
+const BACKEND_URL =
+  process.env.RAZORSHIELD_BACKEND_URL ||
+  process.env.NEXT_PUBLIC_API_URL ||
+  "https://vedantjadhav701-razorshield-api.hf.space";
+
+export interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    details?: string;
+  };
+}
+
+/**
+ * Low-level server-to-server execution helper calling Gradio 5+ /gradio_api/call endpoints.
+ */
+async function callGradioApi<T = any>(apiName: string, data: any[]): Promise<T> {
+  const cleanUrl = BACKEND_URL.replace(/\/$/, "");
+  const postUrl = `${cleanUrl}/gradio_api/call/${apiName}`;
+
+  // Step 1: Initiate execution
+  const postRes = await fetch(postUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ data }),
+    cache: "no-store",
+  });
+
+  if (!postRes.ok) {
+    throw new Error(`Gradio POST to ${apiName} failed with HTTP ${postRes.status}`);
+  }
+
+  const { event_id } = await postRes.json();
+  if (!event_id) {
+    throw new Error(`Gradio POST to ${apiName} did not return an event_id`);
+  }
+
+  // Step 2: Retrieve stream result
+  const getUrl = `${cleanUrl}/gradio_api/call/${apiName}/${event_id}`;
+  const getRes = await fetch(getUrl, { cache: "no-store" });
+
+  if (!getRes.ok) {
+    throw new Error(`Gradio GET stream for ${apiName} failed with HTTP ${getRes.status}`);
+  }
+
+  const text = await getRes.text();
+  const lines = text.split("\n");
+  for (const line of lines) {
+    if (line.startsWith("data: ")) {
+      const rawDataStr = line.substring(6).trim();
+      const parsedArray = JSON.parse(rawDataStr);
+      const rawResult = Array.isArray(parsedArray) ? parsedArray[0] : parsedArray;
+      if (typeof rawResult === "string") {
+        try {
+          return JSON.parse(rawResult) as T;
+        } catch {
+          return rawResult as unknown as T;
+        }
+      }
+      return rawResult as T;
+    }
+  }
+
+  throw new Error(`No complete data stream received for Gradio API ${apiName}`);
+}
+
+/**
+ * Server-side Health Check
+ */
+export async function healthCheck(): Promise<ApiResponse<{ status: string; service: string; model: string; slm_loaded: boolean; policy_mode: string }>> {
+  try {
+    const start = performance.now();
+    await callGradioApi("analyze_merchant", ["M_HEALTH_CHECK"]);
+    const latency = Math.round(performance.now() - start);
+
+    return {
+      success: true,
+      data: {
+        status: "ok",
+        service: "RazorShield Risk Intelligence",
+        model: "Qwen/Qwen2.5-0.5B-Instruct",
+        slm_loaded: true,
+        policy_mode: "BALANCED",
+      },
+    };
+  } catch (err: any) {
+    console.error("Server-side healthCheck failed:", err.message || err);
+    return {
+      success: false,
+      error: {
+        code: "BACKEND_UNREACHABLE",
+        message: "Hugging Face Space backend is unreachable or offline.",
+        details: err.message,
+      },
+    };
+  }
+}
+
+/**
+ * Server-side Transaction Analysis
+ */
+export async function analyzeTransaction(
+  input: TransactionApiInput
+): Promise<ApiResponse<AnalyzeTransactionResponse>> {
+  try {
+    const mId = input.merchant_id || "M_101";
+    const txId = input.transaction_id || `TX_${Date.now().toString().slice(-6)}`;
+    const custId = input.customer_id || "C_1048";
+    const devId = input.device_id || "D_882";
+    const eventTime = input.event_time || new Date().toISOString();
+    const amount = input.amount || 100.0;
+    const pm = input.payment_method || "card";
+    const tt = input.transaction_type || "sale";
+    const policyMode = input.policy_mode || "BALANCED";
+
+    const parsed = await callGradioApi<AnalyzeTransactionResponse>("analyze_transaction", [
+      mId,
+      txId,
+      custId,
+      devId,
+      eventTime,
+      amount,
+      pm,
+      tt,
+      policyMode,
+    ]);
+
+    return {
+      success: true,
+      data: parsed,
+    };
+  } catch (err: any) {
+    console.error("Server-side analyzeTransaction failed:", err.message || err);
+    return {
+      success: false,
+      error: {
+        code: "TRANSACTION_ANALYSIS_FAILED",
+        message: "Failed to evaluate transaction through backend risk engine.",
+        details: err.message,
+      },
+    };
+  }
+}
+
+/**
+ * Server-side Merchant State Query
+ */
+export async function analyzeMerchant(
+  merchantId: string
+): Promise<ApiResponse<MerchantStateQueryResponse>> {
+  try {
+    const parsed = await callGradioApi<MerchantStateQueryResponse>("analyze_merchant", [merchantId]);
+    return {
+      success: true,
+      data: parsed,
+    };
+  } catch (err: any) {
+    console.error("Server-side analyzeMerchant failed:", err.message || err);
+    return {
+      success: false,
+      error: {
+        code: "MERCHANT_QUERY_FAILED",
+        message: "Failed to query merchant incident state from backend.",
+        details: err.message,
+      },
+    };
+  }
+}
+
+/**
+ * Server-side Scenario Replay Execution
+ */
+export async function runScenario(
+  scenarioName: string,
+  policyMode: string = "BALANCED"
+): Promise<ApiResponse<ScenarioReplayResult>> {
+  try {
+    const parsed = await callGradioApi<ScenarioReplayResult>("run_scenario", [scenarioName, policyMode]);
+    return {
+      success: true,
+      data: parsed,
+    };
+  } catch (err: any) {
+    console.error("Server-side runScenario failed:", err.message || err);
+    return {
+      success: false,
+      error: {
+        code: "SCENARIO_REPLAY_FAILED",
+        message: "Failed to execute scenario replay through backend.",
+        details: err.message,
+      },
+    };
+  }
+}
+
+/**
+ * Server-side Evidence Explanation
+ */
+export async function explainEvidence(
+  evidenceJson: string
+): Promise<ApiResponse<any>> {
+  try {
+    const parsed = await callGradioApi("explain_evidence", [evidenceJson]);
+    return {
+      success: true,
+      data: parsed,
+    };
+  } catch (err: any) {
+    console.error("Server-side explainEvidence failed:", err.message || err);
+    return {
+      success: false,
+      error: {
+        code: "EXPLANATION_GENERATION_FAILED",
+        message: "Failed to generate explanation for evidence.",
+        details: err.message,
+      },
+    };
+  }
+}
+
+/**
+ * Server-side Reset Demo State
+ */
+export async function resetDemoState(): Promise<ApiResponse<{ status: string; message: string }>> {
+  try {
+    const parsed = await callGradioApi<{ status: string; message: string }>("reset_demo_state", []);
+    return {
+      success: true,
+      data: parsed,
+    };
+  } catch (err: any) {
+    console.error("Server-side resetDemoState failed:", err.message || err);
+    return {
+      success: false,
+      error: {
+        code: "RESET_FAILED",
+        message: "Failed to reset demo state on backend.",
+        details: err.message,
+      },
+    };
+  }
+}