@redacto.io/consent-sdk-react 3.4.0 → 4.0.0

package/src/RedactoNoticeConsent/api/index.ts

@@ -4,18 +4,17 @@ import type {
   ConsentEventPayload,
   FetchConsentContentParams,
   FetchTTSAudioUrlsParams,
-  GuardianInfoPayload,
-  LegacyConsentEventPayload,
+  InitiateGuardianVerificationParams,
+  InitiateGuardianVerificationResponse,
   RedactoJwtPayload,
   SubmitConsentEventParams,
-  SubmitGuardianInfoParams,
   TTSAudioUrlsResponse,
+  VerifyGuardianStatusParams,
+  VerifyGuardianStatusResponse,
 } from "./types";
-import { isLegacyApi } from "../../utils/isLegacyApi";
 
 const BASE_URL = "https://api.redacto.io/consent";
 
-
 // Simple in-memory cache for API responses to reduce calls
 const apiCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
@@ -60,90 +59,82 @@ export const fetchConsentContent = async ({
   specific_uuid,
   validate_against = "all",
   include_fully_consented_data = false,
-  signal, // AbortSignal for request cancellation
+  signal,
 }: FetchConsentContentParams & { signal?: AbortSignal }): Promise<ConsentContent> => {
-  try {
-    // Validate required parameters
-    if (!noticeId || !accessToken || !validate_against) {
-      throw new Error("noticeId and accessToken are required");
-    }
-
-    const decodedToken = decodeTokenSafely(accessToken);
-    if (!decodedToken) {
-      throw new Error("Invalid access token");
-    }
-
-    const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
-    if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
-      throw new Error("Invalid token: missing organization or workspace UUID");
-    }
+  if (!noticeId || !accessToken || !validate_against) {
+    throw new Error("noticeId and accessToken are required");
+  }
 
-    const apiBaseUrl = baseUrl || BASE_URL;
+  const decodedToken = decodeTokenSafely(accessToken);
+  if (!decodedToken) {
+    throw new Error("Invalid access token");
+  }
 
-    // Create cache key for this request - include accessToken to ensure different users get different cache
-    const cacheKey = `${accessToken}-${noticeId}-${validate_against}-${language}-${specific_uuid || ''}-${include_fully_consented_data}`;
+  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
+  if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
+    throw new Error("Invalid token: missing organization or workspace UUID");
+  }
 
-    // Check cache first (skip for reconsent requests as they need fresh data)
-    if (validate_against === "all" && !specific_uuid) {
-      const cachedData = getCachedData(cacheKey);
-      if (cachedData) {
-        return cachedData;
-      }
-    }
+  const apiBaseUrl = baseUrl || BASE_URL;
 
-    const url = new URL(
-      `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/notices/${noticeId}`
-    );
+  // Create cache key for this request - include accessToken to ensure different users get different cache
+  const cacheKey = `${accessToken}-${noticeId}-${validate_against}-${language}-${specific_uuid || ''}-${include_fully_consented_data}`;
 
-    if (specific_uuid) {
-      url.searchParams.append("specific_uuid", specific_uuid);
-    }
-    url.searchParams.append("validate_against", validate_against);
-    if (include_fully_consented_data) {
-      url.searchParams.append("include_fully_consented_data", "true");
+  if (validate_against === "all" && !specific_uuid) {
+    const cachedData = getCachedData(cacheKey);
+    if (cachedData) {
+      return cachedData;
     }
+  }
 
-    const response = await fetch(url.toString(), {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-        "Accept-Language": language,
-        "Content-Type": "application/json",
-      },
-      signal, // Add abort signal for request cancellation
-    });
-
-    if (!response.ok) {
-      let errorMessage = `Failed to fetch consent content: ${response.status} ${response.statusText}`;
+  const url = new URL(
+    `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/notices/${noticeId}`
+  );
 
-      if (response.status === 401) {
-        errorMessage = "Unauthorized: Invalid or expired token";
-      } else if (response.status === 403) {
-        errorMessage = "Forbidden: Access denied";
-      } else if (response.status === 404) {
-        errorMessage = "Notice not found";
-      } else if (response.status === 409) {
-        errorMessage = "User has already provided consent";
-      } else if (response.status >= 500) {
-        errorMessage = "Server error: Please try again later";
-      }
+  if (specific_uuid) {
+    url.searchParams.append("specific_uuid", specific_uuid);
+  }
+  url.searchParams.append("validate_against", validate_against);
+  if (include_fully_consented_data) {
+    url.searchParams.append("include_fully_consented_data", "true");
+  }
 
-      const error = new Error(errorMessage) as Error & { status?: number };
-      error.status = response.status;
-      throw error;
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      "Accept-Language": language,
+    },
+    signal,
+  });
+
+  if (!response.ok) {
+    let errorMessage = `Failed to fetch consent content: ${response.status} ${response.statusText}`;
+
+    if (response.status === 401) {
+      errorMessage = "Unauthorized: Invalid or expired token";
+    } else if (response.status === 403) {
+      errorMessage = "Forbidden: Access denied";
+    } else if (response.status === 404) {
+      errorMessage = "Notice not found";
+    } else if (response.status === 409) {
+      errorMessage = "User has already provided consent";
+    } else if (response.status >= 500) {
+      errorMessage = "Server error: Please try again later";
     }
 
-    const data: ConsentContent = await response.json();
+    const error = new Error(errorMessage) as Error & { status?: number };
+    error.status = response.status;
+    throw error;
+  }
 
-    // Cache successful responses (skip for reconsent as data may change)
-    if (validate_against === "all" && !specific_uuid) {
-      setCachedData(cacheKey, data);
-    }
+  const data: ConsentContent = await response.json();
 
-    return data;
-  } catch (error) {
-    throw error;
+  if (validate_against === "all" && !specific_uuid) {
+    setCachedData(cacheKey, data);
   }
+
+  return data;
 };
 
 export const submitConsentEvent = async ({
@@ -153,156 +144,190 @@ export const submitConsentEvent = async ({
   purposes,
   declined,
   meta_data,
-  signal, // AbortSignal for request cancellation
+  guardianVerificationReference,
+  selfDeclaredAdult,
+  signal,
 }: SubmitConsentEventParams & { signal?: AbortSignal }): Promise<void> => {
-  try {
-    // Validate required parameters
-    if (!noticeUuid || !accessToken || !Array.isArray(purposes)) {
-      throw new Error("noticeUuid, accessToken, and purposes array are required");
-    }
-
-    const decodedToken = decodeTokenSafely(accessToken);
-    if (!decodedToken) {
-      throw new Error("Invalid access token");
-    }
+  if (!noticeUuid || !accessToken || !Array.isArray(purposes)) {
+    throw new Error("noticeUuid, accessToken, and purposes array are required");
+  }
 
-    const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
-    if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
-      throw new Error("Invalid token: missing organization or workspace UUID");
-    }
+  const decodedToken = decodeTokenSafely(accessToken);
+  if (!decodedToken) {
+    throw new Error("Invalid access token");
+  }
 
-    const apiBaseUrl = baseUrl || BASE_URL;
+  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
+  if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
+    throw new Error("Invalid token: missing organization or workspace UUID");
+  }
 
-    let payload: ConsentEventPayload | LegacyConsentEventPayload;
-
-    if (isLegacyApi(apiBaseUrl)) {
-      // @deprecated Legacy payload for production (.io) backend
-      const primaryEmail = typeof window !== "undefined" ? localStorage.getItem("userEmail") : null;
-      payload = {
-        primary_email: primaryEmail || undefined,
-        notice_uuid: noticeUuid,
-        source: "WEB",
-        declined: Boolean(declined),
-        consents: {
-          purposes: purposes.map((purpose) => {
-            if (!purpose.uuid) {
-              throw new Error(`Invalid purpose data: missing uuid`);
-            }
-            return {
-              uuid: purpose.uuid,
-              name: purpose.name,
-              description: purpose.description || "",
-              industries: purpose.industries || "",
-              selected: Boolean(purpose.selected),
-              data_elements: (purpose.data_elements || []).map((element) => ({
-                uuid: element.uuid,
-                name: element.name,
-                enabled: Boolean(element.enabled),
-                required: Boolean(element.required),
-                selected: element.required ? true : Boolean(element.selected),
-              })),
-            };
-          }),
-        },
-        meta_data: meta_data ? { specific_uuid: meta_data.specific_uuid } : undefined,
-      };
-    } else {
-      // New payload for staging (.tech) / localhost
-      const validatedPurposes = purposes.map((purpose) => {
-        if (!purpose.uuid) {
-          throw new Error(`Invalid purpose data: missing uuid`);
-        }
+  const apiBaseUrl = baseUrl || BASE_URL;
 
-        // Only include enabled data elements (disabled elements are not selectable)
-        const dataElements = (purpose.data_elements || [])
-          .filter((element) => element.enabled)
-          .map((element) => ({
-            uuid: element.uuid,
-            selected: element.required ? true : Boolean(element.selected),
-          }));
-
-        return {
-          purpose_uuid: purpose.uuid,
-          selected: Boolean(purpose.selected),
-          data_elements: dataElements.length > 0 ? dataElements : undefined,
-        };
-      });
-
-      payload = {
-        notice_uuid: noticeUuid,
-        purposes: validatedPurposes,
-        select_all_mandatory: false,
-        source: "WEB",
-        declined: Boolean(declined),
-        meta_data: meta_data ? { specific_uuid: meta_data.specific_uuid } : undefined,
-      };
+  const validatedPurposes = purposes.map((purpose) => {
+    if (!purpose.uuid) {
+      throw new Error(`Invalid purpose data: missing uuid`);
     }
 
-    const response = await fetch(
-      `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/submit-consent`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify(payload),
-        signal, // Add abort signal for request cancellation
-      }
-    );
+    // Only include enabled data elements (disabled elements are not selectable)
+    const dataElements = (purpose.data_elements || [])
+      .filter((element) => element.enabled)
+      .map((element) => ({
+        uuid: element.uuid,
+        selected: element.required ? true : Boolean(element.selected),
+      }));
+
+    return {
+      purpose_uuid: purpose.uuid,
+      selected: Boolean(purpose.selected),
+      data_elements: dataElements.length > 0 ? dataElements : undefined,
+    };
+  });
+
+  const payload: ConsentEventPayload = {
+    notice_uuid: noticeUuid,
+    purposes: validatedPurposes,
+    select_all_mandatory: false,
+    source: "WEB",
+    declined: Boolean(declined),
+    meta_data: meta_data ? { specific_uuid: meta_data.specific_uuid, minor_age: meta_data.minor_age } : undefined,
+    guardian_verification_reference: guardianVerificationReference,
+    self_declared_adult: selfDeclaredAdult,
+  };
+
+  const response = await fetch(
+    `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/submit-consent`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(payload),
+      signal,
+    }
+  );
 
-    if (!response.ok) {
-      let errorMessage = `Failed to submit consent: ${response.status} ${response.statusText}`;
+  if (!response.ok) {
+    let errorMessage = `Failed to submit consent: ${response.status} ${response.statusText}`;
 
-      if (response.status === 400) {
+    if (response.status === 400) {
+      try {
+        const errorData = await response.json();
+        errorMessage = errorData.message || "Invalid request data";
+      } catch {
         errorMessage = "Invalid request data";
-      } else if (response.status === 401) {
-        errorMessage = "Unauthorized: Invalid or expired token";
-      } else if (response.status === 403) {
-        errorMessage = "Forbidden: Access denied";
-      } else if (response.status === 404) {
-        errorMessage = "Notice not found";
-      } else if (response.status >= 500) {
-        errorMessage = "Server error: Please try again later";
       }
-
-      const error = new Error(errorMessage) as Error & { status?: number };
-      error.status = response.status;
-      throw error;
+    } else if (response.status === 401) {
+      errorMessage = "Unauthorized: Invalid or expired token";
+    } else if (response.status === 403) {
+      errorMessage = "Forbidden: Access denied";
+    } else if (response.status === 404) {
+      errorMessage = "Notice not found";
+    } else if (response.status >= 500) {
+      errorMessage = "Server error: Please try again later";
     }
 
-    // Clear any cached consent content since user preferences have changed
-    apiCache.clear();
+    const error = new Error(errorMessage) as Error & { status?: number };
+    error.status = response.status;
+    throw error;
+  }
 
-  } catch (error) {
+  // Clear any cached consent content since user preferences have changed
+  apiCache.clear();
+};
+
+export const fetchTTSAudioUrls = async ({
+  accessToken,
+  baseUrl,
+  noticeUuid,
+  language,
+  signal,
+}: FetchTTSAudioUrlsParams & { signal?: AbortSignal }): Promise<TTSAudioUrlsResponse> => {
+  if (!accessToken || !noticeUuid || !language) {
+    throw new Error("accessToken, noticeUuid, and language are required");
+  }
+
+  const decodedToken = decodeTokenSafely(accessToken);
+  if (!decodedToken) {
+    throw new Error("Invalid access token");
+  }
+
+  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
+  if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
+    throw new Error("Invalid token: missing organization or workspace UUID");
+  }
+
+  const apiBaseUrl = baseUrl || BASE_URL;
+
+  const url = `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/notices/${noticeUuid}/audio/${language}`;
+
+  const response = await fetch(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: "application/json",
+    },
+    signal,
+  });
+
+  if (!response.ok) {
+    let errorMessage = `Failed to fetch TTS audio URLs: ${response.status} ${response.statusText}`;
+
+    if (response.status === 401) {
+      errorMessage = "Unauthorized: Invalid or expired token";
+    } else if (response.status === 403) {
+      errorMessage = "Forbidden: Access denied";
+    } else if (response.status === 404) {
+      errorMessage = "Notice or audio not found";
+    } else if (response.status >= 500) {
+      errorMessage = "Server error: Please try again later";
+    }
+
+    const error = new Error(errorMessage) as Error & { status?: number };
+    error.status = response.status;
     throw error;
   }
+
+  const data: TTSAudioUrlsResponse = await response.json();
+  return data;
 };
 
-export const submitGuardianInfo = async ({
+// =============================================================================
+// Guardian Verification API Functions
+// =============================================================================
+
+/**
+ * Initiate guardian verification via DigiLocker
+ * POST /guardian/initiate-verification
+ * 
+ * This combines guardian details submission and DigiLocker initiation in one call.
+ */
+export const initiateGuardianVerification = async ({
   accessToken,
   baseUrl,
   guardianName,
   guardianContact,
   guardianRelationship,
-  signal, // AbortSignal for request cancellation
-}: SubmitGuardianInfoParams & { signal?: AbortSignal }): Promise<void> => {
+  frontendCallbackUrl,
+  metadata,
+  signal,
+}: InitiateGuardianVerificationParams): Promise<InitiateGuardianVerificationResponse> => {
   try {
-    // Validate required parameters
     if (!accessToken) {
       throw new Error("accessToken is required");
     }
 
     if (!guardianName?.trim()) {
-      throw new Error("guardianName is required and cannot be empty");
+      throw new Error("Guardian name is required");
     }
 
     if (!guardianContact?.trim()) {
-      throw new Error("guardianContact is required and cannot be empty");
+      throw new Error("Guardian contact is required");
     }
 
     if (!guardianRelationship?.trim()) {
-      throw new Error("guardianRelationship is required and cannot be empty");
+      throw new Error("Guardian relationship is required");
     }
 
     const decodedToken = decodeTokenSafely(accessToken);
@@ -315,16 +340,30 @@ export const submitGuardianInfo = async ({
       throw new Error("Invalid token: missing organization or workspace UUID");
     }
 
-    const payload: GuardianInfoPayload = {
+    const apiBaseUrl = baseUrl || BASE_URL;
+
+    const payload: {
+      guardian_name: string;
+      guardian_contact: string;
+      guardian_relationship: string;
+      frontend_callback_url?: string;
+      metadata?: Record<string, unknown>;
+    } = {
       guardian_name: guardianName.trim(),
       guardian_contact: guardianContact.trim(),
       guardian_relationship: guardianRelationship.trim(),
     };
 
-    const apiBaseUrl = baseUrl || BASE_URL;
+    if (frontendCallbackUrl) {
+      payload.frontend_callback_url = frontendCallbackUrl;
+    }
+
+    if (metadata) {
+      payload.metadata = metadata;
+    }
 
     const response = await fetch(
-      `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/guardian-info`,
+      `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/guardian/initiate-verification`,
       {
         method: "POST",
         headers: {
@@ -332,27 +371,29 @@ export const submitGuardianInfo = async ({
           "Content-Type": "application/json",
         },
         body: JSON.stringify(payload),
-        signal, // Add abort signal for request cancellation
+        signal,
       }
     );
 
     if (!response.ok) {
-      let errorMessage = `Failed to submit guardian info: ${response.status} ${response.statusText}`;
+      let errorMessage = `Failed to initiate verification: ${response.status} ${response.statusText}`;
 
       if (response.status === 400) {
-        errorMessage = "Invalid request data";
+        try {
+          const errorData = await response.json();
+          errorMessage = errorData.message || "Invalid request data";
+        } catch {
+          errorMessage = "Invalid request data";
+        }
       } else if (response.status === 401) {
         errorMessage = "Unauthorized: Invalid or expired token";
-      } else if (response.status === 403) {
-        errorMessage = "Forbidden: Access denied";
       } else if (response.status === 404) {
         errorMessage = "Organization or workspace not found";
       } else if (response.status === 422) {
-        // Handle validation errors from the server
         try {
           const errorData = await response.json();
-          errorMessage = errorData.message || "Validation error";
-        } catch (parseError) {
+          errorMessage = errorData.message || "Validation error: Please check your input";
+        } catch {
           errorMessage = "Validation error: Please check your input";
         }
       } else if (response.status >= 500) {
@@ -364,72 +405,120 @@ export const submitGuardianInfo = async ({
       throw error;
     }
 
+    const responseData = await response.json();
+
+    // Handle response with detail wrapper (backend format: { code, status, detail: {...} })
+    const detail = responseData.detail || responseData;
+
+    // Already verified — skip DigiLocker entirely
+    if (detail.already_verified) {
+      return {
+        success: true,
+        guardian_info_uuid: detail.guardian_info_uuid,
+        already_verified: true,
+        verification_reference: detail.verification_reference,
+      };
+    }
+
+    // New verification flow — needs DigiLocker
+    if (!detail.session_token || !detail.digilocker_redirect_url) {
+      throw new Error("Invalid response: missing session_token or digilocker_redirect_url");
+    }
+
+    return {
+      success: detail.success ?? true,
+      guardian_info_uuid: detail.guardian_info_uuid,
+      already_verified: false,
+      session_token: detail.session_token,
+      digilocker_redirect_url: detail.digilocker_redirect_url,
+      expires_at: detail.expires_at,
+    };
   } catch (error) {
-    // Log error for debugging but don't expose sensitive information
-    console.error("Error submitting guardian info:", error instanceof Error ? error.message : error);
+    console.error("Error initiating guardian verification:", error instanceof Error ? error.message : error);
     throw error;
   }
 };
 
-export const fetchTTSAudioUrls = async ({
+/**
+ * Check guardian verification status
+ * POST /guardian/verify-status
+ * 
+ * Poll this endpoint to check if DigiLocker verification is complete.
+ * Returns verification_reference when status is "verified".
+ */
+export const verifyGuardianStatus = async ({
   accessToken,
   baseUrl,
-  noticeUuid,
-  language,
-  signal, // AbortSignal for request cancellation
-}: FetchTTSAudioUrlsParams & { signal?: AbortSignal }): Promise<TTSAudioUrlsResponse> => {
-  try {
-    // Validate required parameters
-    if (!accessToken || !noticeUuid || !language) {
-      throw new Error("accessToken, noticeUuid, and language are required");
-    }
-
-    const decodedToken = decodeTokenSafely(accessToken);
-    if (!decodedToken) {
-      throw new Error("Invalid access token");
-    }
+  sessionToken,
+  signal,
+}: VerifyGuardianStatusParams): Promise<VerifyGuardianStatusResponse> => {
+  if (!accessToken || !sessionToken) {
+    throw new Error("accessToken and sessionToken are required");
+  }
 
-    const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
-    if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
-      throw new Error("Invalid token: missing organization or workspace UUID");
-    }
+  const decodedToken = decodeTokenSafely(accessToken);
+  if (!decodedToken) {
+    throw new Error("Invalid access token");
+  }
 
-    const apiBaseUrl = baseUrl || BASE_URL;
+  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
+  if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
+    throw new Error("Invalid token: missing organization or workspace UUID");
+  }
 
-    const url = `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/notices/${noticeUuid}/audio/${language}`;
+  const apiBaseUrl = baseUrl || BASE_URL;
 
-    const response = await fetch(url, {
-      method: "GET",
+  const response = await fetch(
+    `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/guardian/verify-status`,
+    {
+      method: "POST",
       headers: {
         Authorization: `Bearer ${accessToken}`,
-        Accept: "application/json",
         "Content-Type": "application/json",
       },
-      signal, // Add abort signal for request cancellation
-    });
+      body: JSON.stringify({
+        session_token: sessionToken,
+      }),
+      signal,
+    }
+  );
 
-    if (!response.ok) {
-      let errorMessage = `Failed to fetch TTS audio URLs: ${response.status} ${response.statusText}`;
+  if (!response.ok) {
+    let errorMessage = `Failed to check verification status: ${response.status} ${response.statusText}`;
 
-      if (response.status === 401) {
-        errorMessage = "Unauthorized: Invalid or expired token";
-      } else if (response.status === 403) {
-        errorMessage = "Forbidden: Access denied";
-      } else if (response.status === 404) {
-        errorMessage = "Notice or audio not found";
-      } else if (response.status >= 500) {
-        errorMessage = "Server error: Please try again later";
+    if (response.status === 400) {
+      try {
+        const errorData = await response.json();
+        errorMessage = errorData.message || errorData.detail?.message || "Invalid session token";
+      } catch {
+        errorMessage = "Invalid session token";
       }
-
-      const error = new Error(errorMessage) as Error & { status?: number };
-      error.status = response.status;
-      throw error;
+    } else if (response.status === 401) {
+      errorMessage = "Unauthorized: Invalid or expired token";
+    } else if (response.status === 404) {
+      errorMessage = "Verification session not found or expired. Please restart the verification process.";
+    } else if (response.status === 410) {
+      errorMessage = "Verification session has expired. Please restart the verification process.";
+    } else if (response.status >= 500) {
+      errorMessage = "Server error: Please try again later";
     }
 
-    const data: TTSAudioUrlsResponse = await response.json();
-
-    return data;
-  } catch (error) {
+    const error = new Error(errorMessage) as Error & { status?: number };
+    error.status = response.status;
     throw error;
   }
+
+  const responseData = await response.json();
+  const detail = responseData.detail || responseData;
+
+  return {
+    status: detail.status ?? "in_progress",
+    guardian_info_uuid: detail.guardian_info_uuid ?? null,
+    verification_reference: detail.verification_reference ?? null,
+    guardian_details: detail.guardian_details ?? null,
+    error: detail.error ?? null,
+    error_code: detail.error_code ?? null,
+    can_retry: detail.can_retry ?? true,
+  };
 };
+