@salesforce/webapp-template-app-react-sample-b2x-experimental 1.79.2 → 1.80.0

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/sessionTimeout/sessionTimeService.ts

@@ -0,0 +1,161 @@
+/**
+ * SessionTimeServlet API service
+ * Handles communication with the session validation endpoint
+ */
+
+import { SESSION_CONFIG } from "./sessionTimeoutConfig";
+
+/**
+ * Response from SessionTimeServlet API
+ */
+export interface SessionResponse {
+	/** Session phase */
+	sp: number;
+	/** Seconds remaining in session */
+	sr: number;
+}
+
+/**
+ * Parse the servlet response text into SessionResponse object
+ * Handles CSRF protection prefix
+ *
+ * @param text - Raw response text from servlet
+ * @returns Parsed session response
+ * @throws Error if response cannot be parsed
+ */
+function parseResponseResult(text: string): SessionResponse {
+	let cleanedText = text;
+
+	// Strip CSRF protection prefix if present
+	if (cleanedText.startsWith(SESSION_CONFIG.CSRF_TOKEN)) {
+		cleanedText = cleanedText.substring(SESSION_CONFIG.CSRF_TOKEN.length);
+	}
+
+	// Trim whitespace
+	cleanedText = cleanedText.trim();
+
+	try {
+		const parsed = JSON.parse(cleanedText) as SessionResponse;
+
+		// Validate response structure
+		if (typeof parsed.sp !== "number" || typeof parsed.sr !== "number") {
+			throw new Error("Invalid response structure: missing sp or sr properties");
+		}
+
+		return parsed;
+	} catch (error) {
+		console.error("[sessionTimeService] Failed to parse response:", error, "Text:", cleanedText);
+		throw new Error(
+			`Failed to parse session response: ${error instanceof Error ? error.message : "Unknown error"}`,
+		);
+	}
+}
+
+/**
+ * Call SessionTimeServlet API
+ * Internal function used by both poll and extend functions
+ *
+ * @param basePath - Community base path (e.g., "/sfsites/c/")
+ * @param extend - Whether to extend the session (updateTimedOutSession param)
+ * @returns Session response with remaining time
+ * @throws Error if API call fails or security checks fail
+ */
+async function callSessionTimeServlet(
+	basePath: string,
+	extend: boolean = false,
+): Promise<SessionResponse> {
+	// Build URL with cache-busting timestamp
+	const timestamp = Date.now();
+	let url = `${basePath}${SESSION_CONFIG.SERVLET_URL}?buster=${timestamp}`;
+
+	if (extend) {
+		url += "&updateTimedOutSession=true";
+	}
+
+	try {
+		const response = await fetch(url, {
+			method: "GET",
+			credentials: "same-origin", // Include cookies for session
+			cache: "no-cache",
+			// Security headers
+			headers: {
+				"X-Requested-With": "XMLHttpRequest", // Helps identify XHR requests
+			},
+		});
+
+		if (!response.ok) {
+			// Provide more context for common error codes
+			if (response.status === 401) {
+				throw new Error("Session expired or unauthorized");
+			} else if (response.status === 403) {
+				throw new Error("Access forbidden");
+			} else if (response.status === 404) {
+				throw new Error("Session endpoint not found");
+			} else {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+		}
+
+		// Security: Validate content type (should be text or JSON)
+		const contentType = response.headers.get("content-type");
+		if (contentType && !contentType.includes("text") && !contentType.includes("json")) {
+			throw new Error(`Unexpected content type: ${contentType}`);
+		}
+
+		const text = await response.text();
+		const parsed = parseResponseResult(text);
+
+		// Apply latency buffer to account for network delay
+		const adjustedSecondsRemaining = Math.max(0, parsed.sr - SESSION_CONFIG.LATENCY_BUFFER_SECONDS);
+
+		return {
+			sp: parsed.sp,
+			sr: adjustedSecondsRemaining,
+		};
+	} catch (error) {
+		// Don't log the full URL in production to avoid leaking sensitive info
+		console.error("[sessionTimeService] API call failed:", error);
+		throw error;
+	}
+}
+
+/**
+ * Poll SessionTimeServlet to check remaining session time
+ * Called periodically to monitor session status
+ *
+ * @param basePath - Community base path (e.g., "/sfsites/c/")
+ * @returns Session response with remaining time (after latency buffer adjustment)
+ * @throws Error if API call fails
+ *
+ * @example
+ * const { sr, sp } = await pollSessionTimeServlet('/sfsites/c/');
+ * if (sr <= 300) {
+ *   // Less than 5 minutes remaining
+ *   showWarning();
+ * }
+ */
+export async function pollSessionTimeServlet(basePath: string): Promise<SessionResponse> {
+	return callSessionTimeServlet(basePath, false);
+}
+
+/**
+ * Extend the current session time
+ * Called when user clicks "Continue Working" in warning modal
+ *
+ * @param basePath - Community base path (e.g., "/sfsites/c/")
+ * @returns Session response with new remaining time
+ * @throws Error if API call fails
+ *
+ * @example
+ * const { sr } = await extendSessionTime('/sfsites/c/');
+ * console.log(`Session extended. ${sr} seconds remaining.`);
+ */
+export async function extendSessionTime(basePath: string): Promise<SessionResponse> {
+	return callSessionTimeServlet(basePath, true);
+}
+
+/**
+ * Export parseResponseResult for testing purposes
+ * @internal
+ */
+export { parseResponseResult };

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/sessionTimeout/sessionTimeoutConfig.ts

@@ -0,0 +1,77 @@
+/**
+ * Configuration constants for session timeout monitoring
+ */
+
+// ============================================================================
+// Retry Configuration
+// ============================================================================
+
+/** Initial delay for first retry attempt (2 seconds) */
+export const INITIAL_RETRY_DELAY = 2000;
+
+/** Maximum number of retry attempts before giving up */
+export const MAX_RETRY_ATTEMPTS = 10;
+
+/** Maximum retry delay (30 minutes) */
+export const MAX_RETRY_DELAY = 30 * 60 * 1000;
+
+// ============================================================================
+// Session Storage Keys
+// ============================================================================
+
+/** sessionStorage keys used by session validator */
+export const STORAGE_KEYS = {
+	/** Flag to show session expired message on login page */
+	SHOW_SESSION_MESSAGE: "lwrSessionValidator.showSessionMessage",
+} as const;
+
+// ============================================================================
+// Servlet Configuration
+// ============================================================================
+
+/** SessionTimeServlet configuration */
+export const SESSION_CONFIG = {
+	/** Relative URL to SessionTimeServlet */
+	SERVLET_URL: "/sfsites/c/_nc_external/system/security/session/SessionTimeServlet",
+
+	/** Latency buffer to subtract from server response (seconds) */
+	LATENCY_BUFFER_SECONDS: 3,
+
+	/** CSRF protection prefix in servlet responses */
+	CSRF_TOKEN: "while(1);\n",
+} as const;
+
+// ============================================================================
+// UI Labels
+// ============================================================================
+
+/**
+ * UI labels for session timeout components
+ */
+export const LABELS = {
+	/** Title for session warning modal */
+	sessionWarningTitle: "Session Timeout Warning",
+
+	/** Message text in session warning modal */
+	sessionWarningMessage:
+		"For security, we log you out if you’re inactive for too long. To continue working, click Continue before the time expires.",
+
+	/** Text for "Continue" button */
+	continueButton: "Continue",
+
+	/** Text for "Log Out" button */
+	logoutButton: "Log Out",
+
+	/** Message shown on login page after session expires */
+	invalidSessionMessage: "Your session has expired. Please log in again.",
+
+	/** Accessibility label for close button */
+	closeLabel: "Close",
+} as const;
+
+// ============================================================================
+// Session Timeout Configuration
+// ============================================================================
+
+/** Session warning time in seconds (30 seconds) */
+export const SESSION_WARNING_TIME = 30;

package/dist/force-app/main/default/webapplications/appreactsampleb2x/src/features/authentication/utils/helpers.ts

@@ -0,0 +1,121 @@
+/**
+ * MAINTAINABILITY: Robust error extraction.
+ * Handles strings, objects, and standard Error instances.
+ *
+ * @param err - The error object (unknown type)
+ * @param fallback - Fallback message if error doesn't have a message property
+ * @returns The error message string
+ */
+export function getErrorMessage(err: unknown, fallback: string): string {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	// Check if it's an object with a message property
+	if (typeof err === "object" && err !== null && "message" in err) {
+		return String((err as { message: unknown }).message);
+	}
+	return fallback;
+}
+
+/**
+ * [Dev Note] Helper to parse the fetch Response.
+ * It handles the distinction between success (JSON) and failure (throwing Error).
+ */
+export async function handleApiResponse<T = unknown>(
+	response: Response,
+	fallbackError: string,
+): Promise<T> {
+	// 1. Robustness: Handle 204 No Content gracefully
+	if (response.status === 204) {
+		return {} as T;
+	}
+
+	let data: any = null;
+
+	const contentType = response.headers.get("content-type");
+	if (contentType?.includes("application/json")) {
+		data = await response.json();
+	} else {
+		// [Dev Note] If Salesforce returns HTML (e.g. standard error page),
+		// we consume text to avoid parsing errors.
+		await response.text();
+	}
+
+	if (!response.ok) {
+		// [Dev Note] Throwing here allows the calling component to catch and
+		// display the error via getErrorMessage()
+		throw new Error(parseApiResponseError(data, fallbackError));
+	}
+
+	return data as T;
+}
+
+/**
+ * UI API Record response structure.
+ */
+export type RecordResponse = {
+	fields: Record<
+		string,
+		{
+			value: string;
+		}
+	>;
+};
+
+/**
+ * [Dev Note] GraphQL can return a complex nested structure.
+ * This helper flattens it to a simple object for easier form binding.
+ *
+ * @param data - Extracted payload from the GraphQL response.
+ * @param fallbackError - Fallback error message if data is null/undefined or not an object.
+ * @throws {Error} If data is not valid.
+ * @returns Flattened object with values mapped directly to the fields.
+ */
+export function flattenGraphQLRecord<T>(
+	data: any,
+	fallbackError: string = "An unknown error occurred",
+): T {
+	if (!data || typeof data !== "object") {
+		throw new Error(fallbackError);
+	}
+
+	return Object.fromEntries(
+		Object.entries(data).map(([key, field]) => [
+			key,
+			field !== null && typeof field === "object" && "value" in field
+				? (field as { value: unknown }).value
+				: (field ?? null),
+		]),
+	) as T;
+}
+
+/**
+ * [Dev Note] Salesforce APIs may return errors as an array or a single object.
+ * This helper standardizes the extraction of the error message string.
+ *
+ * @param data - The response data.
+ * @param fallbackError - Fallback error message if response doesn't have a message property
+ * @returns The error message string
+ */
+function parseApiResponseError(
+	data: any,
+	fallbackError: string = "An unknown error occurred",
+): string {
+	if (data?.message) {
+		return data.message;
+	}
+	if (data?.error) {
+		return data.error;
+	}
+	if (data?.errors && Array.isArray(data.errors) && data.errors.length > 0) {
+		return data.errors.join(" ") || fallbackError;
+	}
+	if (Array.isArray(data) && data.length > 0) {
+		return (
+			data
+				.map((e) => e?.message)
+				.filter(Boolean)
+				.join(" ") || fallbackError
+		);
+	}
+	return fallbackError;
+}