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

package/src/RedactoNoticeConsent/api/types.ts

@@ -171,8 +171,11 @@ export type ConsentEventPayload = {
   source?: string;
   declined?: boolean;
   meta_data?: {
-    specific_uuid: string;
+    specific_uuid?: string;
+    minor_age?: number;
   };
+  guardian_verification_reference?: string;
+  self_declared_adult?: boolean;
 };
 
 export type DataElement = {
@@ -199,22 +202,11 @@ export type SubmitConsentEventParams = {
   purposes: Array<Purpose>;
   declined: boolean;
   meta_data?: {
-    specific_uuid: string;
+    specific_uuid?: string;
+    minor_age?: number;
   };
-};
-
-export type SubmitGuardianInfoParams = {
-  accessToken: string;
-  baseUrl?: string;
-  guardianName: string;
-  guardianContact: string;
-  guardianRelationship: string;
-};
-
-export type GuardianInfoPayload = {
-  guardian_name: string;
-  guardian_contact: string;
-  guardian_relationship: string;
+  guardianVerificationReference?: string;
+  selfDeclaredAdult?: boolean;
 };
 
 // UI Component Types
@@ -330,3 +322,133 @@ export type FetchTTSAudioUrlsParams = {
   noticeUuid: string;
   language: string;
 };
+
+// =============================================================================
+// Guardian Verification Types (aligned with backend API)
+// =============================================================================
+
+/**
+ * Parameters for initiating guardian verification
+ * POST /guardian/initiate-verification
+ */
+export type InitiateGuardianVerificationParams = {
+  accessToken: string;
+  baseUrl?: string;
+  guardianName: string;
+  guardianContact: string;
+  guardianRelationship: string;
+  frontendCallbackUrl?: string;
+  metadata?: Record<string, unknown>;
+  signal?: AbortSignal;
+};
+
+/**
+ * Response from initiate verification API
+ *
+ * Two shapes:
+ * 1. New verification needed: already_verified=false, includes session_token + digilocker_redirect_url
+ * 2. Already verified: already_verified=true, includes verification_reference — skip DigiLocker
+ */
+export type InitiateGuardianVerificationResponse = {
+  success: boolean;
+  guardian_info_uuid: string;
+  already_verified: boolean;
+  /** Present only when already_verified=true */
+  verification_reference?: string;
+  /** Present only when already_verified=false (new flow) */
+  session_token?: string;
+  /** Present only when already_verified=false (new flow) */
+  digilocker_redirect_url?: string;
+  /** Present only when already_verified=false (new flow) */
+  expires_at?: string;
+};
+
+/**
+ * Parameters for checking verification status
+ * POST /guardian/verify-status
+ */
+export type VerifyGuardianStatusParams = {
+  accessToken: string;
+  baseUrl?: string;
+  sessionToken: string;
+  signal?: AbortSignal;
+};
+
+/**
+ * Guardian details returned after successful verification
+ */
+export type GuardianVerificationDetails = {
+  verified_name: string | null;
+  is_guardian_adult: boolean | null;
+  verified_at: string;
+  verification_reference: string | null;
+};
+
+/**
+ * Response from verify status API
+ */
+export type VerifyGuardianStatusResponse = {
+  status: "pending" | "in_progress" | "verified" | "failed" | "expired";
+  guardian_info_uuid: string | null;
+  verification_reference: string | null;
+  guardian_details: GuardianVerificationDetails | null;
+  error: string | null;
+  error_code: GuardianVerificationErrorCode | null;
+  can_retry: boolean;
+};
+
+/**
+ * Error codes from guardian verification
+ */
+export type GuardianVerificationErrorCode =
+  | "SESSION_EXPIRED"
+  | "GUARDIAN_UNDER_18"
+  | "TOKEN_FAILED"
+  | "DIGILOCKER_AUTH_FAILED"
+  | "NO_AUTH_CODE";
+
+// =============================================================================
+// Session Storage Types for redirect flow
+// =============================================================================
+
+/**
+ * State persisted during DigiLocker redirect flow.
+ * NOTE: accessToken is intentionally excluded — never store tokens in sessionStorage.
+ * The host app must provide the token when the component re-mounts.
+ */
+export type PersistedConsentState = {
+  flowState: ConsentFlowState;
+  sessionToken?: string;
+  guardianInfoUuid?: string;
+  verificationReference?: string;
+  selectedPurposes?: Record<string, boolean>;
+  selectedDataElements?: Record<string, boolean>;
+  timestamp: string;
+  originalUrl: string;
+  verificationResult?: "pending" | "verified" | "failed" | "in_progress" | "expired";
+  noticeId?: string;
+  baseUrl?: string;
+};
+
+export type ConsentFlowState =
+  | "age-check"
+  | "guardian-details"
+  | "digilocker-pending"
+  | "consent-form"
+  | "submitting"
+  | "success"
+  | "error";
+
+// =============================================================================
+// DigiLocker Callback Types
+// =============================================================================
+
+/**
+ * Props for DigiLockerCallback component
+ */
+export type DigiLockerCallbackProps = {
+  accessToken: string;
+  baseUrl?: string;
+  onSuccess?: (verificationReference: string) => void;
+  onError?: (error: Error, errorCode?: GuardianVerificationErrorCode) => void;
+};

package/src/RedactoNoticeConsent/components/DigiLockerCallback.tsx

@@ -0,0 +1,536 @@
+/**
+ * DigiLockerCallback Component
+ * 
+ * Standalone component for handling DigiLocker redirect callbacks.
+ * Clients should add this to their routing (e.g., /digilocker-callback page).
+ * 
+ * Usage in Next.js:
+ * ```tsx
+ * // pages/digilocker-callback.tsx
+ * import { DigiLockerCallback } from '@redacto.io/consent-sdk-react';
+ *
+ * export default function DigiLockerCallbackPage() {
+ *   return <DigiLockerCallback accessToken={"<token>"} />;
+ * }
+ * ```
+ *
+ * Usage in React Router:
+ * ```tsx
+ * <Route path="/digilocker-callback" element={<DigiLockerCallback accessToken={"<token>"} />} />
+ * ```
+ * 
+ * URL Parameters expected from redirect:
+ * - session_token: The verification session token
+ * - status: "verified" | "failed" | "expired"  
+ * - verification_reference: (if verified) Reference for consent submission
+ * - error_code: (if failed) Error code like GUARDIAN_UNDER_18, SESSION_EXPIRED, etc.
+ */
+
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { verifyGuardianStatus } from "../api";
+import type { DigiLockerCallbackProps, GuardianVerificationErrorCode } from "../api/types";
+import { injectCheckboxStyles } from "../injectStyles";
+import {
+    clearConsentState,
+    getConsentState,
+    updateConsentState,
+} from "../services/storage";
+
+type CallbackStatus = "processing" | "success" | "error";
+
+export const DigiLockerCallback: React.FC<DigiLockerCallbackProps> = ({
+  accessToken: propAccessToken,
+  baseUrl,
+  onSuccess,
+  onError,
+}) => {
+  const [status, setStatus] = useState<CallbackStatus>("processing");
+  const [message, setMessage] = useState("Verifying your guardian...");
+  const [errorDetail, setErrorDetail] = useState<string | null>(null);
+  const retryTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const redirectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const isMountedRef = useRef(true);
+
+  const getErrorMessage = (errorCode?: GuardianVerificationErrorCode): string => {
+    switch (errorCode) {
+      case "GUARDIAN_UNDER_18":
+        return "Guardian verification failed: The guardian must be 18 years or older.";
+      case "SESSION_EXPIRED":
+        return "Verification session has expired. Please restart the verification process.";
+      case "TOKEN_FAILED":
+        return "DigiLocker authentication failed. Please try again.";
+      case "DIGILOCKER_AUTH_FAILED":
+        return "DigiLocker authorization was cancelled or failed. Please try again.";
+      case "NO_AUTH_CODE":
+        return "Missing authorization code from DigiLocker. Please try again.";
+      default:
+        return "Verification failed. Please try again.";
+    }
+  };
+
+  const redirectToOriginalPage = useCallback(
+    (
+      originalUrl: string,
+      verificationResult: "verified" | "failed" | "expired",
+      verificationReference?: string
+    ) => {
+      // Update persisted state with verification result
+      updateConsentState({
+        verificationResult,
+        verificationReference,
+        flowState: verificationResult === "verified" ? "consent-form" : "error",
+      });
+
+      // Redirect back to original page
+      redirectTimeoutRef.current = setTimeout(() => {
+        window.location.href = originalUrl;
+      }, 1500);
+    },
+    []
+  );
+
+  const handleCallback = useCallback(async () => {
+    try {
+      // 1. Extract URL parameters (new format from backend)
+      const params = new URLSearchParams(window.location.search);
+      const sessionToken = params.get("session_token");
+      const urlStatus = params.get("status") as "verified" | "failed" | "expired" | null;
+      const verificationReference = params.get("verification_reference");
+      const errorCode = params.get("error_code") as GuardianVerificationErrorCode | null;
+
+      // 2. Retrieve persisted state (optional — popup mode may not have saved state)
+      const persistedState = getConsentState();
+
+      const originalUrl = persistedState?.originalUrl || "/";
+      const storedBaseUrl = persistedState?.baseUrl;
+      const storedSessionToken = persistedState?.sessionToken;
+
+      // Use accessToken from props (never stored in sessionStorage for security)
+      const accessToken = propAccessToken;
+      if (!accessToken) {
+        throw new Error("Access token not provided. Please pass accessToken as a prop.");
+      }
+
+      // Use session token from URL (source of truth) or stored state as fallback
+      const activeSessionToken = sessionToken || storedSessionToken;
+      if (!activeSessionToken) {
+        throw new Error("Session token not found. Please restart the verification process.");
+      }
+
+      // Check if we're in an iframe (for iframe mode)
+      // Wrapped in try-catch: cross-origin iframes throw SecurityError on window.top access
+      let isInIframe = false;
+      try {
+        isInIframe = window.self !== window.top;
+      } catch {
+        isInIframe = true;
+      }
+
+      // 3. If status is already in URL params (direct redirect from backend)
+      if (urlStatus === "verified" && verificationReference) {
+        setStatus("success");
+        setMessage("Guardian verified successfully! Redirecting...");
+        onSuccess?.(verificationReference);
+        
+        // If in iframe, postMessage to parent instead of redirecting
+        if (isInIframe && window.parent) {
+          window.parent.postMessage(
+            {
+              type: "DIGILOCKER_VERIFICATION_STATUS",
+              status: "verified",
+              verificationReference,
+            },
+            window.location.origin
+          );
+          return;
+        }
+        
+        redirectToOriginalPage(originalUrl, "verified", verificationReference);
+        return;
+      }
+
+      if (urlStatus === "failed" || urlStatus === "expired") {
+        const urlErrorCode = errorCode ?? undefined;
+        const errorMessage = getErrorMessage(urlErrorCode);
+        setStatus("error");
+        setMessage("Verification failed");
+        setErrorDetail(errorMessage);
+        onError?.(new Error(errorMessage), urlErrorCode);
+
+        // If in iframe, postMessage to parent instead of redirecting
+        if (isInIframe && window.parent) {
+          window.parent.postMessage(
+            {
+              type: "DIGILOCKER_VERIFICATION_STATUS",
+              status: urlStatus,
+              errorCode: urlErrorCode,
+              error: errorMessage,
+            },
+            window.location.origin
+          );
+          return;
+        }
+        
+        redirectToOriginalPage(originalUrl, urlStatus);
+        return;
+      }
+
+      // 4. If no status in URL, poll the backend for verification status
+      setMessage("Processing verification...");
+      
+      const apiBaseUrl = baseUrl || storedBaseUrl;
+      
+      const response = await verifyGuardianStatus({
+        accessToken,
+        baseUrl: apiBaseUrl,
+        sessionToken: activeSessionToken,
+      });
+      if (!isMountedRef.current) return;
+
+      if (response.status === "verified") {
+        // Use top-level verification_reference first, fall back to guardian_details
+        const verificationRef = response.verification_reference || response.guardian_details?.verification_reference || undefined;
+
+        if (!verificationRef) {
+          setStatus("error");
+          setMessage("Verification failed");
+          setErrorDetail("Verification completed but no reference received. Please try again.");
+          onError?.(new Error("Verification completed but no reference received."));
+          redirectToOriginalPage(originalUrl, "failed");
+          return;
+        }
+
+        setStatus("success");
+        setMessage("Guardian verified successfully! Redirecting...");
+        onSuccess?.(verificationRef);
+
+        // If in iframe, postMessage to parent instead of redirecting
+        if (isInIframe && window.parent) {
+          window.parent.postMessage(
+            {
+              type: "DIGILOCKER_VERIFICATION_STATUS",
+              status: "verified",
+              verificationReference: verificationRef,
+            },
+            window.location.origin
+          );
+          return;
+        }
+
+        redirectToOriginalPage(originalUrl, "verified", verificationRef);
+      } else if (response.status === "failed" || response.status === "expired") {
+        const responseErrorCode = response.error_code ?? undefined;
+        const errorMessage = response.error || getErrorMessage(responseErrorCode);
+        setStatus("error");
+        setMessage("Verification failed");
+        setErrorDetail(errorMessage);
+        onError?.(new Error(errorMessage), responseErrorCode);
+
+        // If in iframe, postMessage to parent instead of redirecting
+        if (isInIframe && window.parent) {
+          window.parent.postMessage(
+            {
+              type: "DIGILOCKER_VERIFICATION_STATUS",
+              status: response.status,
+              errorCode: responseErrorCode,
+              error: errorMessage,
+            },
+            window.location.origin
+          );
+          return;
+        }
+
+        redirectToOriginalPage(originalUrl, response.status);
+      } else {
+        // Still in progress - this shouldn't happen on callback page
+        // but handle it gracefully
+        setMessage("Verification is still in progress. Please wait...");
+        // Poll again after a short delay
+        // Retry with exponential backoff before giving up
+        const MAX_RETRIES = 3;
+        let retryCount = 0;
+
+        const attemptRetry = () => {
+          retryCount++;
+          const delay = 3000 * Math.pow(2, retryCount - 1); // 3s, 6s, 12s
+          retryTimeoutRef.current = setTimeout(async () => {
+            if (!isMountedRef.current) return;
+            try {
+              const retryResponse = await verifyGuardianStatus({
+                accessToken,
+                baseUrl: apiBaseUrl,
+                sessionToken: activeSessionToken,
+              });
+              if (!isMountedRef.current) return;
+
+              const retryRef = retryResponse.verification_reference || retryResponse.guardian_details?.verification_reference || undefined;
+
+              if (retryResponse.status === "verified" && retryRef) {
+                setStatus("success");
+                setMessage("Guardian verified successfully! Redirecting...");
+                onSuccess?.(retryRef);
+
+                if (isInIframe && window.parent) {
+                  window.parent.postMessage(
+                    {
+                      type: "DIGILOCKER_VERIFICATION_STATUS",
+                      status: "verified",
+                      verificationReference: retryRef,
+                    },
+                    window.location.origin
+                  );
+                  return;
+                }
+
+                redirectToOriginalPage(originalUrl, "verified", retryRef);
+              } else if (retryResponse.status === "failed" || retryResponse.status === "expired") {
+                const retryErrorCode = retryResponse.error_code ?? undefined;
+                const retryErrorMessage = retryResponse.error || getErrorMessage(retryErrorCode) || "Verification could not be completed. Please try again.";
+                setStatus("error");
+                setMessage("Verification failed");
+                setErrorDetail(retryErrorMessage);
+                onError?.(new Error(retryErrorMessage), retryErrorCode);
+
+                if (isInIframe && window.parent) {
+                  window.parent.postMessage(
+                    {
+                      type: "DIGILOCKER_VERIFICATION_STATUS",
+                      status: retryResponse.status,
+                      errorCode: retryErrorCode,
+                      error: retryErrorMessage,
+                    },
+                    window.location.origin
+                  );
+                  return;
+                }
+
+                redirectToOriginalPage(originalUrl, retryResponse.status);
+              } else if (retryCount < MAX_RETRIES) {
+                setMessage("Verification taking longer than expected. Please wait...");
+                attemptRetry();
+              } else {
+                const timeoutMessage = "Verification could not be completed in time. Please try again.";
+                setStatus("error");
+                setMessage("Verification failed");
+                setErrorDetail(timeoutMessage);
+                onError?.(new Error(timeoutMessage));
+                redirectToOriginalPage(originalUrl, "failed");
+              }
+            } catch (retryErr) {
+              if (!isMountedRef.current) return;
+              if (retryCount < MAX_RETRIES) {
+                attemptRetry();
+              } else {
+                setStatus("error");
+                setMessage("Verification failed");
+                setErrorDetail((retryErr as Error).message);
+                onError?.(retryErr as Error);
+                redirectToOriginalPage(originalUrl, "failed");
+              }
+            }
+          }, delay);
+        };
+
+        attemptRetry();
+      }
+    } catch (error) {
+      console.error("DigiLocker callback error:", error);
+      setStatus("error");
+      
+      const err = error as Error;
+      setMessage("Verification failed");
+      setErrorDetail(err.message || "An error occurred during verification");
+      
+      onError?.(err);
+
+      // Try to redirect back even on error
+      const persistedState = getConsentState();
+      if (persistedState?.originalUrl) {
+        redirectTimeoutRef.current = setTimeout(() => {
+          redirectToOriginalPage(persistedState.originalUrl, "failed");
+        }, 3000);
+      }
+    }
+  }, [propAccessToken, baseUrl, onSuccess, onError, redirectToOriginalPage]);
+
+  useEffect(() => {
+    injectCheckboxStyles();
+    handleCallback();
+    return () => {
+      isMountedRef.current = false;
+      if (retryTimeoutRef.current) clearTimeout(retryTimeoutRef.current);
+      if (redirectTimeoutRef.current) clearTimeout(redirectTimeoutRef.current);
+    };
+  }, [handleCallback]);
+
+  const handleRetry = useCallback(() => {
+    const persistedState = getConsentState();
+    if (persistedState?.originalUrl) {
+      clearConsentState();
+      window.location.href = persistedState.originalUrl;
+    } else {
+      window.location.href = "/";
+    }
+  }, []);
+
+  // Inline styles for the callback page
+  const containerStyle: React.CSSProperties = {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    minHeight: "100vh",
+    backgroundColor: "#f9fafb",
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+    padding: "20px",
+    boxSizing: "border-box",
+  };
+
+  const cardStyle: React.CSSProperties = {
+    backgroundColor: "#ffffff",
+    borderRadius: "12px",
+    boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
+    padding: "40px",
+    textAlign: "center",
+    maxWidth: "400px",
+    width: "100%",
+  };
+
+  const spinnerStyle: React.CSSProperties = {
+    width: "48px",
+    height: "48px",
+    border: "4px solid #e5e7eb",
+    borderTopColor: "#3b82f6",
+    borderRadius: "50%",
+    animation: "spin 1s linear infinite",
+    margin: "0 auto 24px",
+  };
+
+  const iconStyle: React.CSSProperties = {
+    width: "64px",
+    height: "64px",
+    borderRadius: "50%",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    margin: "0 auto 24px",
+  };
+
+  const successIconStyle: React.CSSProperties = {
+    ...iconStyle,
+    backgroundColor: "#d1fae5",
+    color: "#059669",
+  };
+
+  const errorIconStyle: React.CSSProperties = {
+    ...iconStyle,
+    backgroundColor: "#fee2e2",
+    color: "#dc2626",
+  };
+
+  const titleStyle: React.CSSProperties = {
+    fontSize: "20px",
+    fontWeight: 600,
+    color: "#111827",
+    margin: "0 0 12px 0",
+  };
+
+  const messageStyle: React.CSSProperties = {
+    fontSize: "14px",
+    color: "#6b7280",
+    marginBottom: "8px",
+    lineHeight: 1.5,
+  };
+
+  const errorDetailStyle: React.CSSProperties = {
+    fontSize: "13px",
+    color: "#dc2626",
+    marginTop: "12px",
+    padding: "12px",
+    backgroundColor: "#fef2f2",
+    borderRadius: "6px",
+    border: "1px solid #fecaca",
+  };
+
+  const buttonStyle: React.CSSProperties = {
+    marginTop: "20px",
+    padding: "10px 24px",
+    backgroundColor: "#3b82f6",
+    color: "#ffffff",
+    border: "none",
+    borderRadius: "6px",
+    fontSize: "14px",
+    fontWeight: 500,
+    cursor: "pointer",
+    transition: "background-color 0.2s",
+  };
+
+  return (
+      <div style={containerStyle}>
+        <div style={cardStyle}>
+          {status === "processing" && (
+            <>
+              <div style={spinnerStyle} />
+              <h2 style={titleStyle}>Processing Verification</h2>
+              <p style={messageStyle}>{message}</p>
+              <p style={{ ...messageStyle, fontSize: "12px", color: "#9ca3af" }}>
+                Please wait while we verify your guardian's identity...
+              </p>
+            </>
+          )}
+
+          {status === "success" && (
+            <>
+              <div style={successIconStyle}>
+                <svg
+                  width="32"
+                  height="32"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                >
+                  <polyline points="20 6 9 17 4 12" />
+                </svg>
+              </div>
+              <h2 style={titleStyle}>Verification Successful</h2>
+              <p style={messageStyle}>{message}</p>
+            </>
+          )}
+
+          {status === "error" && (
+            <>
+              <div style={errorIconStyle}>
+                <svg
+                  width="32"
+                  height="32"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                >
+                  <line x1="18" y1="6" x2="6" y2="18" />
+                  <line x1="6" y1="6" x2="18" y2="18" />
+                </svg>
+              </div>
+              <h2 style={titleStyle}>Verification Failed</h2>
+              <p style={messageStyle}>{message}</p>
+              {errorDetail && <p style={errorDetailStyle}>{errorDetail}</p>}
+              <button
+                className="redacto-dl-retry-btn"
+                style={buttonStyle}
+                onClick={handleRetry}
+              >
+                Try Again
+              </button>
+            </>
+          )}
+        </div>
+      </div>
+  );
+};
+
+export default DigiLockerCallback;