@salesforce/templates 66.11.0 → 66.12.0

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/reactive-form-page.base.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { Directive } from "@angular/core";
+import { FormGroup } from "@angular/forms";
+
+/**
+ * Shared helpers for the auth form pages.
+ *
+ * The base `app-input` primitive exposes a two-way `[(value)]` model rather than
+ * a ControlValueAccessor, so neither `formControlName` nor `[formGroup]` can bind
+ * to it directly. These pages therefore keep a Reactive Forms `FormGroup` as the
+ * validation + submit source of truth (with no `[formGroup]` on the template
+ * `<form>`) and bridge each field manually with `[value]` / `(valueChange)`:
+ *   <app-input [value]="form.controls.x.value" (valueChange)="setControl('x', $event)" />
+ *
+ * `setControl` pushes edits back into the control (marking it touched/dirty so
+ * validation surfaces), and `controlError` reads a specific error message for
+ * display once the control has been touched — mirroring the React forms, which
+ * showed field errors after interaction.
+ *
+ * Kept as an abstract base (not injectable) so each page owns its own typed
+ * `form`. Not an Angular component/service; no DI.
+ */
+@Directive()
+export abstract class ReactiveFormPageBase {
+	protected abstract readonly form: FormGroup;
+
+	/** Push an edited value into the named control and mark it touched/dirty. */
+	protected setControl(name: string, value: string): void {
+		const control = this.form.get(name);
+		if (!control) return;
+		control.setValue(value);
+		control.markAsDirty();
+		control.markAsTouched();
+	}
+
+	/**
+	 * Returns the message for the named error key on the control, but only once
+	 * the control has been touched (so pristine fields don't show errors).
+	 */
+	protected controlError(name: string, errorKey: string): string | null {
+		const control = this.form.get(name);
+		if (!control || !control.touched) return null;
+		const message = control.errors?.[errorKey];
+		return typeof message === "string" ? message : null;
+	}
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/session/session.html

@@ -0,0 +1,55 @@
+@if (showWarningModal()) {
+<app-dialog [open]="true" [closeOnBackdrop]="false">
+	<div
+		class="max-w-md"
+		role="alertdialog"
+		aria-labelledby="session-warning-title"
+		aria-describedby="session-warning-description"
+	>
+		<h2 id="session-warning-title" class="text-lg font-semibold">
+			{{ labels.sessionWarningTitle }}
+		</h2>
+		<p id="session-warning-description" class="text-sm text-muted-foreground mt-1">
+			{{ labels.sessionWarningMessage }}
+		</p>
+
+		<div class="flex flex-col items-center gap-4 py-6">
+			<time
+				[attr.datetime]="isoTime()"
+				role="timer"
+				aria-live="off"
+				aria-atomic="true"
+				aria-describedby="session-warning-description"
+				class="text-5xl font-bold text-center tabular-nums text-destructive"
+			>
+				{{ formattedTime() }}
+			</time>
+		</div>
+
+		<div class="flex gap-4 justify-end">
+			<app-button variant="outlined" (clicked)="onLogoutClick()">
+				{{ labels.logoutButton }}
+			</app-button>
+			<app-button variant="filled" (clicked)="onContinue()">
+				{{ labels.continueButton }}
+			</app-button>
+		</div>
+	</div>
+</app-dialog>
+} @if (showExpiredAlert()) {
+<div class="fixed top-4 left-1/2 -translate-x-1/2 z-50 w-full max-w-md px-4">
+	<app-status-alert
+		variant="error"
+		[title]="labels.sessionWarningTitle"
+		[message]="labels.invalidSessionMessage"
+	/>
+	<button
+		type="button"
+		class="sr-only"
+		[attr.aria-label]="labels.closeLabel"
+		(click)="onDismissAlert()"
+	>
+		{{ labels.closeLabel }}
+	</button>
+</div>
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/session/session.ts

@@ -0,0 +1,205 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import {
+	ChangeDetectionStrategy,
+	Component,
+	DestroyRef,
+	effect,
+	inject,
+	OnInit,
+	signal,
+} from "@angular/core";
+import { Router } from "@angular/router";
+import { DialogComponent } from "../../../components/ui/dialog/dialog";
+import { StatusAlertComponent } from "../status-alert/status-alert";
+import { ButtonComponent } from "../../../components/ui/button/button";
+import { AuthService } from "../auth/auth.service";
+import { SessionTimeoutService } from "../utils/session-timeout.service";
+import { LABELS, STORAGE_KEYS } from "../utils/session-timeout.config";
+import { ROUTES } from "../config/authentication.config";
+
+/**
+ * Session-timeout validator — the Angular port of the React
+ * `SessionTimeoutValidator`. Rendered app-wide by `AuthAppLayoutComponent` so
+ * the warning modal is available on every route (exactly like React).
+ *
+ * Responsibilities (all mirrored from React):
+ * - Starts polling via `SessionTimeoutService` on init, skipping guest users.
+ * - Shows a non-dismissable warning modal with a live countdown when the session
+ *   nears expiry; "Continue" extends the session, "Log Out" logs out.
+ * - When the countdown reaches 0 it re-checks the server before logging out
+ *   (prevents premature logout).
+ * - On expiry it sets the `showSessionMessage` sessionStorage flag then calls
+ *   `AuthService.logout(window.location.pathname)` (hard nav).
+ * - On the login page, if the flag is set, shows the session-expired alert once
+ *   (lazily read at init, since the expiry logout hard-navigates and this
+ *   component always remounts fresh on login).
+ *
+ * `SessionTimeoutService` is provided here so its timers are scoped to this
+ * component's lifetime (mirrors the hook's unmount cleanup).
+ */
+@Component({
+	selector: "app-session-timeout-validator",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	providers: [SessionTimeoutService],
+	imports: [DialogComponent, StatusAlertComponent, ButtonComponent],
+	templateUrl: "./session.html",
+})
+export class SessionTimeoutValidatorComponent implements OnInit {
+	private readonly authService = inject(AuthService);
+	private readonly session = inject(SessionTimeoutService);
+	private readonly destroyRef = inject(DestroyRef);
+	private readonly router = inject(Router);
+
+	protected readonly labels = LABELS;
+
+	// Community base path. React hard-codes "" here (root-relative); kept identical.
+	private readonly basePath = "";
+
+	// -- Exposed session state (from the service) ----------------------------
+	protected readonly showWarningModal = this.session.showWarningModal;
+	protected readonly timeLeftInSession = this.session.timeLeftInSession;
+
+	// -- Session-expired alert (lazy, read once at init) ---------------------
+	protected readonly showExpiredAlert = signal<boolean>(false);
+
+	// -- Countdown state (mirrors useCountdownTimer) -------------------------
+	protected readonly countdownSeconds = signal<number>(0);
+	private countdownIntervalId: ReturnType<typeof setInterval> | null = null;
+	private countdownEndTime = 0;
+	private lastModalOpen = false;
+
+	constructor() {
+		// React's SessionWarningModal resets+starts the countdown when the modal
+		// opens and stops it when it closes. This effect mirrors that: it reacts to
+		// the warning-modal signal and (re)starts the countdown from the latest
+		// remaining time whenever the modal is open.
+		effect(() => {
+			const open = this.showWarningModal();
+			const remaining = this.timeLeftInSession() ?? 0;
+			if (open) {
+				this.startCountdown(remaining);
+			} else if (this.lastModalOpen) {
+				this.stopCountdown();
+			}
+			this.lastModalOpen = open;
+		});
+
+		// Auto-logout when the countdown/poll reports the session is expired and the
+		// user is not a guest (mirrors the React expiry `useEffect`).
+		effect(() => {
+			const timeLeft = this.timeLeftInSession();
+			if (timeLeft !== null && timeLeft <= 0 && !this.isGuest()) {
+				this.handleLogout();
+			}
+		});
+	}
+
+	ngOnInit(): void {
+		// Session-expired alert: checked once at init via a lazy read. The expiry
+		// handler triggers a hard navigation, so this component always mounts fresh
+		// on the login page after expiry.
+		//
+		// Compare against the router's parsed URL (base-href/community-path stripped)
+		// rather than `window.location.pathname`: the raw browser path includes any
+		// base href (e.g. `/sfsites/c/.../login`) and would never equal `/login`,
+		// silently hiding the banner. `router.url` is router-relative, matching the
+		// React `useLocation().pathname` behavior. Strip the query/fragment before
+		// comparing.
+		const routerPath = this.router.url.split(/[?#]/)[0];
+		const isLoginPage = routerPath === ROUTES.LOGIN.PATH;
+		const shouldShow =
+			isLoginPage && sessionStorage.getItem(STORAGE_KEYS.SHOW_SESSION_MESSAGE) === "true";
+		if (shouldShow) {
+			sessionStorage.removeItem(STORAGE_KEYS.SHOW_SESSION_MESSAGE);
+			this.showExpiredAlert.set(true);
+		}
+
+		// Start monitoring (service skips guests internally).
+		this.session.start(this.basePath, this.isGuest());
+
+		this.destroyRef.onDestroy(() => {
+			this.session.stop();
+			this.stopCountdown();
+		});
+	}
+
+	private isGuest(): boolean {
+		return !this.authService.isAuthenticated();
+	}
+
+	// -- Countdown ------------------------------------------------------------
+
+	private startCountdown(seconds: number): void {
+		this.stopCountdown();
+		this.countdownSeconds.set(seconds);
+		this.countdownEndTime = Date.now() + seconds * 1000;
+		this.countdownIntervalId = setInterval(() => {
+			const remainingMs = this.countdownEndTime - Date.now();
+			const newTime = Math.max(0, Math.ceil(remainingMs / 1000));
+			this.countdownSeconds.set(newTime);
+			if (newTime <= 0) {
+				this.stopCountdown();
+				// Re-check with the server before logging out (React onCountdownExpire).
+				void this.session.checkSession();
+			}
+		}, 100);
+	}
+
+	private stopCountdown(): void {
+		if (this.countdownIntervalId) {
+			clearInterval(this.countdownIntervalId);
+			this.countdownIntervalId = null;
+		}
+	}
+
+	/** MM:SS formatted countdown (mirrors useCountdownTimer.formattedTime). */
+	protected formattedTime(): string {
+		const total = this.countdownSeconds();
+		const minutes = Math.floor(total / 60);
+		const secs = total % 60;
+		const pad = (n: number) => n.toString().padStart(2, "0");
+		return `${pad(minutes)}:${pad(secs)}`;
+	}
+
+	/** ISO 8601 duration for the <time> element (mirrors isoTime). */
+	protected isoTime(): string {
+		const total = this.countdownSeconds();
+		const minutes = Math.floor(total / 60);
+		const secs = total % 60;
+		return `PT${minutes}M${secs}S`;
+	}
+
+	// -- Actions --------------------------------------------------------------
+
+	/** "Continue" — stop countdown and extend the session. */
+	protected onContinue(): void {
+		this.stopCountdown();
+		void this.session.extendSession();
+	}
+
+	/** "Log Out" button in the warning modal. */
+	protected onLogoutClick(): void {
+		this.stopCountdown();
+		this.handleLogout();
+	}
+
+	/** Dismiss the session-expired alert. */
+	protected onDismissAlert(): void {
+		this.showExpiredAlert.set(false);
+	}
+
+	/**
+	 * Set the session-message flag, stop monitoring, then hand off to the
+	 * centralized logout (hard nav). Passes the current pathname as the return
+	 * URL. Mirrors the React `handleLogout`.
+	 */
+	private handleLogout(): void {
+		sessionStorage.setItem(STORAGE_KEYS.SHOW_SESSION_MESSAGE, "true");
+		this.session.stop();
+		this.authService.logout(window.location.pathname);
+	}
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/status-alert/status-alert.html

@@ -0,0 +1,5 @@
+<app-alert [title]="title()" [class]="toneClass()">
+	@if (message()) { {{ message() }} } @else {
+	<ng-content />
+	}
+</app-alert>

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/status-alert/status-alert.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, computed, input } from "@angular/core";
+import { AlertComponent } from "../../../components/ui/alert/alert";
+
+/** Status banner variant conveying the tone of the message. */
+export type AppStatusAlertVariant = "error" | "success" | "info" | "warning";
+
+/**
+ * Status / error banner — a feature-owned composition over the base `app-alert`
+ * ui primitive (not a base-template component). Adds a four-way `variant` with a
+ * colour treatment, mirroring the React `components/alerts/status-alert`.
+ *
+ * Supply the copy via the `message` input, or content-project richer markup
+ * (lists, links) as the default slot. Consumed by the authentication
+ * login-error / success / session-expired banners.
+ */
+@Component({
+	selector: "app-status-alert",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [AlertComponent],
+	templateUrl: "./status-alert.html",
+	host: {
+		"data-slot": "status-alert",
+	},
+})
+export class StatusAlertComponent {
+	readonly variant = input<AppStatusAlertVariant>("info");
+
+	/** Optional title rendered above the message / projected content. */
+	readonly title = input<string>("");
+
+	/** Message copy; may be omitted in favour of projected content. */
+	readonly message = input<string>("");
+
+	/** Colour utilities applied to the banner for the current variant. */
+	protected readonly toneClass = computed(() => {
+		switch (this.variant()) {
+			case "error":
+				return "text-destructive";
+			case "success":
+				return "text-emerald-700";
+			case "warning":
+				return "text-amber-700";
+			default:
+				return "text-sky-700";
+		}
+	});
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/submit-button/submit-button.html

@@ -0,0 +1,5 @@
+<app-button type="submit" [disabled]="submitting() || disabled()" class="w-full">
+	@if (submitting()) {
+	<app-spinner [diameter]="16" aria-hidden="true" />
+	{{ loadingLabel() }} } @else { {{ label() }} }
+</app-button>

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/submit-button/submit-button.scss

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+// Material lays the button's projected content out inside `.mdc-button__label`.
+// Make it a flex row so the spinner and the loading label sit on the same line,
+// vertically centred. Scoped under `:host` (via `::ng-deep`) so the override
+// only reaches this submit button's inner `matButton`, never other buttons.
+:host ::ng-deep .mdc-button__label {
+	display: flex;
+
+	> app-spinner {
+		margin: auto 1rem;
+	}
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/submit-button/submit-button.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { ChangeDetectionStrategy, Component, input } from "@angular/core";
+import { ButtonComponent } from "../../../components/ui/button/button";
+import { SpinnerComponent } from "../../../components/ui/spinner/spinner";
+
+/**
+ * Submit button that reflects form submission state — the Angular port of the
+ * React `SubmitButton`, which subscribed to `form.isSubmitting`.
+ *
+ * Reactive Forms have no equivalent subscription; instead the parent passes the
+ * form's `pending`/submitting flag via `[submitting]` and the caller-provided
+ * `[disabled]`. While submitting the button is disabled and shows a spinner with
+ * the loading label — the same UX (prevents double-submit + gives feedback).
+ */
+@Component({
+	selector: "app-submit-button",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [ButtonComponent, SpinnerComponent],
+	templateUrl: "./submit-button.html",
+	styleUrl: "./submit-button.scss",
+})
+export class SubmitButtonComponent {
+	/** Button text when not submitting. */
+	readonly label = input.required<string>();
+	/** Button text while submitting. */
+	readonly loadingLabel = input<string>("Submitting…");
+	/** True while the form submission is in flight. */
+	readonly submitting = input<boolean>(false);
+	/** Additional disabled condition from the caller (e.g. already authenticated). */
+	readonly disabled = input<boolean>(false);
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/utils/auth-helpers.ts

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { AUTH_REDIRECT_PARAM } from "../config/authentication.config";
+
+/**
+ * Extracts the startUrl from the current query params, defaulting to '/'.
+ *
+ * SECURITY NOTE: This function strictly validates the URL to prevent Open
+ * Redirect vulnerabilities. It allows only relative paths.
+ *
+ * Direct port of the React `getStartUrl`. The React version takes a
+ * `URLSearchParams`; Angular's `ParamMap` exposes the same `get(key)` contract,
+ * so this accepts a minimal `{ get(name): string | null }` shape and works with
+ * both an `ActivatedRoute` `ParamMap` and a `URLSearchParams`.
+ *
+ * @param params - The query-param map (e.g. ActivatedRoute.snapshot.queryParamMap).
+ * @returns The start URL for post-authentication redirect.
+ */
+export function getStartUrl(params: { get(name: string): string | null }): string {
+	const url = params.get(AUTH_REDIRECT_PARAM);
+	if (url && isValidRedirect(url)) {
+		return url;
+	}
+	return "/";
+}
+
+/**
+ * Security: Validates that the redirect URL is a relative path to prevent Open
+ * Redirect vulnerabilities.
+ *
+ * Security Checks:
+ * 1. Rejects protocol-relative URLs (//)
+ * 2. Rejects backslash usage which some browsers treat as slashes (/\)
+ * 3. Rejects control characters
+ *
+ * Ported from the React `isValidRedirect`, with one intentional hardening: the
+ * character-range ceiling is tightened from the React source's U+00FF to the
+ * printable-ASCII bound U+007E (~) so DEL / C1 controls / NBSP are rejected in
+ * line with check #3. Do not relax any of these checks without security review.
+ */
+export function isValidRedirect(url: string): boolean {
+	// Basic structure check
+	if (!url.startsWith("/") || url.startsWith("//")) return false;
+	// Security: Reject backslashes to prevent /\example.com bypasses
+	if (url.includes("\\")) return false;
+	// Robustness: Ensure it doesn't contain whitespace/control characters.
+	// Allowed range is the printable-ASCII band U+0021 (!) through U+007E (~).
+	// This deliberately tightens the React reference's U+00FF ceiling, which
+	// admitted U+007F (DEL), the C1 control block (U+0080-U+009F, incl. NEL),
+	// and U+00A0 (NBSP) - all of which contradict the "reject control
+	// characters" contract and are open-redirect / request-splitting vectors.
+	if (/[^!-~]/.test(url)) return false;
+	return true;
+}
+
+/**
+ * Shared response type for authentication endpoints (login/register). Success
+ * responses contain `success: true` and `redirectUrl`. Error responses contain
+ * an `errors` array.
+ */
+export interface AuthResponse {
+	success?: boolean;
+	redirectUrl?: string | null;
+	errors?: string[];
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/utils/auth-validators.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { AbstractControl, ValidationErrors, ValidatorFn } from "@angular/forms";
+
+/**
+ * Angular Reactive Forms validators that mirror the React feature's zod schemas
+ * (`authHelpers.ts`). The React port dropped zod in favour of native Angular
+ * validators; these reproduce the same rules and messages so the UX is
+ * identical. Each validator returns `{ <key>: message }` on failure and `null`
+ * on success; templates read the first message via `control.errors`.
+ */
+
+/** Mirrors zod `emailSchema`: trimmed, valid email. */
+export const emailValidator: ValidatorFn = (control: AbstractControl): ValidationErrors | null => {
+	const value = (control.value ?? "").toString().trim();
+	if (value === "") {
+		return { email: "Please enter a valid email address" };
+	}
+	// Same intent as zod's email check: a single @ with non-empty local/domain
+	// parts and a dotted domain. Kept deliberately permissive, like zod.
+	const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+	return emailPattern.test(value) ? null : { email: "Please enter a valid email address" };
+};
+
+/** Mirrors zod `passwordSchema`: minimum 8 characters. */
+export const passwordMinValidator: ValidatorFn = (
+	control: AbstractControl,
+): ValidationErrors | null => {
+	const value = (control.value ?? "").toString();
+	return value.length >= 8 ? null : { password: "Password must be at least 8 characters" };
+};
+
+/** A required-with-custom-message validator (mirrors zod `min(1, message)`). */
+export function requiredWithMessage(message: string): ValidatorFn {
+	return (control: AbstractControl): ValidationErrors | null => {
+		const value = (control.value ?? "").toString().trim();
+		return value.length >= 1 ? null : { required: message };
+	};
+}
+
+/**
+ * Cross-field validator mirroring the `newPasswordSchema` refine: the
+ * `confirmPassword` control must equal the `newPassword` control. Attach to the
+ * FormGroup; sets `{ passwordMismatch: '...' }` on the confirm control (matching
+ * the zod `path: ['confirmPassword']`) so the error renders under that field.
+ */
+export function passwordsMatchValidator(
+	passwordKey = "newPassword",
+	confirmKey = "confirmPassword",
+): ValidatorFn {
+	return (group: AbstractControl): ValidationErrors | null => {
+		const password = group.get(passwordKey);
+		const confirm = group.get(confirmKey);
+		if (!password || !confirm) {
+			return null;
+		}
+		if (confirm.value !== password.value) {
+			const existing = confirm.errors ?? {};
+			confirm.setErrors({ ...existing, passwordMismatch: "Passwords do not match" });
+			return { passwordMismatch: "Passwords do not match" };
+		}
+		// Clear only our own error, preserving any other errors on the control.
+		if (confirm.errors) {
+			const { passwordMismatch: _removed, ...rest } = confirm.errors;
+			confirm.setErrors(Object.keys(rest).length ? rest : null);
+		}
+		return null;
+	};
+}

package/lib/templates/project/angularextapp/_p_/_m_/_w_/_a_/src/app/features/authentication/utils/helpers.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Error thrown when the API returns a non-OK response with structured error
+ * messages. The `errors` array contains user-facing messages that are safe to
+ * display — backend Apex classes guarantee that system exceptions are never
+ * exposed. Direct port of the React `ApiError`.
+ */
+export class ApiError extends Error {
+	readonly errors: string[];
+	constructor(errors: string[]) {
+		super(errors[0]);
+		this.name = "ApiError";
+		this.errors = errors;
+	}
+}
+
+/**
+ * Helper to parse the fetch Response. Handles the distinction between success
+ * (JSON) and failure (throwing Error). Ported from the React `handleApiResponse`.
+ */
+export async function handleApiResponse<T = unknown>(response: Response): Promise<T> {
+	// Robustness: Handle 204 No Content gracefully
+	if (response.status === 204) {
+		return {} as T;
+	}
+
+	let data: { errors?: string[] } | null = null;
+
+	const contentType = response.headers.get("content-type");
+	if (contentType?.includes("application/json")) {
+		data = (await response.json()) as { errors?: string[] };
+	} else {
+		// If Salesforce returns HTML (e.g. standard error page), consume the text
+		// to avoid parsing errors.
+		await response.text();
+	}
+
+	if (!response.ok) {
+		console.error("API request failed", data);
+		if (data?.errors?.length) {
+			throw new ApiError(data.errors);
+		}
+		throw new Error("An unexpected error occurred");
+	}
+
+	return data as T;
+}
+
+/** UI API Record response structure. */
+export type RecordResponse = {
+	fields: Record<string, { value: string }>;
+};
+
+/**
+ * GraphQL can return a complex nested structure. This helper flattens it to a
+ * simple object for easier form binding. Ported from the React
+ * `flattenGraphQLRecord`.
+ *
+ * @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: unknown,
+	fallbackError = "An unknown error occurred",
+): T {
+	if (!data || typeof data !== "object") {
+		throw new Error(fallbackError);
+	}
+
+	return Object.fromEntries(
+		Object.entries(data as Record<string, unknown>).map(([key, field]) => [
+			key,
+			field !== null && typeof field === "object" && "value" in field
+				? (field as { value: unknown }).value
+				: (field ?? null),
+		]),
+	) as T;
+}