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

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;

package/src/RedactoNoticeConsent/components/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Consent SDK Components
+ * 
+ * Export reusable components for the consent flow.
+ */
+
+export { DigiLockerCallback } from "./DigiLockerCallback";

package/src/RedactoNoticeConsent/injectStyles.ts

@@ -133,6 +133,17 @@ export const injectCheckboxStyles = () => {
       outline: 3px solid #FFF9C4 !important;
       outline-offset: 2px !important;
     }
+
+    /* Spinner animation for verification screens */
+    @keyframes spin {
+      from { transform: rotate(0deg); }
+      to { transform: rotate(360deg); }
+    }
+
+    /* DigiLocker callback retry button hover */
+    .redacto-dl-retry-btn:hover {
+      background-color: #2563eb !important;
+    }
   `;
 
   document.head.appendChild(style);

package/src/RedactoNoticeConsent/services/storage.ts

@@ -0,0 +1,122 @@
+/**
+ * Session Storage Service
+ * 
+ * Handles state persistence for consent flow during DigiLocker redirects.
+ * Uses sessionStorage to maintain state across page navigations.
+ */
+
+import type { PersistedConsentState } from "../api/types";
+
+const STORAGE_KEY = "redacto_consent_sdk_state";
+const STATE_EXPIRY_MS = 30 * 60 * 1000; // 30 minutes
+
+/**
+ * Check if code is running in browser environment
+ */
+const isBrowser = (): boolean => {
+  return typeof window !== "undefined" && typeof window.sessionStorage !== "undefined";
+};
+
+/**
+ * Save consent flow state to sessionStorage
+ */
+export const saveConsentState = (state: PersistedConsentState): void => {
+  if (!isBrowser()) {
+    console.warn("SessionStorage not available - state not persisted");
+    return;
+  }
+
+  try {
+    const stateWithTimestamp = {
+      ...state,
+      timestamp: new Date().toISOString(),
+    };
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(stateWithTimestamp));
+  } catch (error) {
+    console.error("Failed to save consent state:", error);
+  }
+};
+
+/**
+ * Retrieve consent flow state from sessionStorage
+ * Returns null if state doesn't exist or is expired
+ */
+export const getConsentState = (): PersistedConsentState | null => {
+  if (!isBrowser()) {
+    return null;
+  }
+
+  try {
+    const savedState = sessionStorage.getItem(STORAGE_KEY);
+    if (!savedState) {
+      return null;
+    }
+
+    const parsed: PersistedConsentState = JSON.parse(savedState);
+
+    // Check if state is expired
+    const stateAge = Date.now() - new Date(parsed.timestamp).getTime();
+    if (stateAge > STATE_EXPIRY_MS) {
+      clearConsentState();
+      return null;
+    }
+
+    return parsed;
+  } catch (error) {
+    console.error("Failed to get consent state:", error);
+    return null;
+  }
+};
+
+/**
+ * Clear consent flow state from sessionStorage
+ */
+export const clearConsentState = (): void => {
+  if (!isBrowser()) {
+    return;
+  }
+
+  try {
+    sessionStorage.removeItem(STORAGE_KEY);
+  } catch (error) {
+    console.error("Failed to clear consent state:", error);
+  }
+};
+
+/**
+ * Update specific fields in the persisted consent state
+ */
+export const updateConsentState = (updates: Partial<PersistedConsentState>): void => {
+  const currentState = getConsentState();
+  if (currentState) {
+    saveConsentState({
+      ...currentState,
+      ...updates,
+      timestamp: new Date().toISOString(),
+    });
+  }
+};
+
+/**
+ * Check if there's a pending verification to resume
+ */
+export const hasPendingVerification = (): boolean => {
+  const state = getConsentState();
+  return state !== null && state.flowState === "digilocker-pending";
+};
+
+/**
+ * Get verification result from persisted state
+ */
+export const getVerificationResult = (): "pending" | "verified" | "failed" | "in_progress" | "expired" | null => {
+  const state = getConsentState();
+  return state?.verificationResult ?? null;
+};
+
+/**
+ * Get verification reference from persisted state (after successful verification)
+ */
+export const getVerificationReference = (): string | null => {
+  const state = getConsentState();
+  return state?.verificationReference ?? null;
+};

package/src/RedactoNoticeConsent/types.ts

@@ -13,6 +13,8 @@ export type Props = Readonly<{
   onError?: (error: Error) => void;
   applicationId?: string;
   validateAgainst?: "all" | "required";
+  digilockerMode?: "popup" | "redirect"; // Default: "redirect" (full page redirect - required for DigiLocker)
+  digilockerCallbackUrl?: string; // Default: "/digilocker-callback"
   includeFullyConsentedData?: boolean;
   reviewModeButtonText?: string;
 }>;