📝 Add docstrings to codex/update-build-docs.sh-for-openapi-generation

Docstrings generation was requested by @shayancoin.

* #551 (comment)

The following files were modified:

* `frontend/src/app/configurator/quote/complete/page.tsx`
* `frontend/src/app/dealer/actions.ts`
* `frontend/src/app/kitchen-configurator/[sku]/page.tsx`
* `frontend/src/app/server-actions/dealerQuotes.ts`
* `frontend/src/app/web-vitals.ts`
* `frontend/src/lib/auth.ts`
* `frontend/tests/e2e/perf/perf-budget-loader.ts`
* `frontend/tests/e2e/utils/wasm-decoder-polyfill.ts`

Author: coderabbitai[bot]

frontend/src/app/configurator/quote/complete/page.tsx

@@ -8,6 +8,12 @@ import { useSearchParams } from 'next/navigation';
 
 export const dynamic = 'force-dynamic';
 
+/**
+ * Convert a string into a finite number or return `null` for empty or invalid input.
+ *
+ * @param value - The string (or `null`) to parse as a number.
+ * @returns The parsed numeric value, or `null` if `value` is empty or cannot be parsed to a finite number.
+ */
 function parseNumber(value: string | null): number | null {
   if (!value) {
     return null;
@@ -16,10 +22,24 @@ function parseNumber(value: string | null): number | null {
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+/**
+ * Formats a number as a locale-aware currency string.
+ *
+ * @param value - The numeric amount to format
+ * @param currency - The ISO 4217 currency code to use (for example, "USD" or "EUR")
+ * @returns A localized currency string representing `value` in the specified `currency`
+ */
 function formatCurrency(value: number, currency: string) {
   return new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(value);
 }
 
+/**
+ * Render a confirmation page that displays a generated quote, an optional monetary summary, and an optional PDF download link.
+ *
+ * The component derives its content from URL search parameters: `currency` (defaults to `USD`), `quoteId`, `subtotal`, `tax`, `total`, and `pdf` (decoded into a URL). Lines for subtotal, tax, and total are shown only when present; a PDF download button is shown when `pdf` is provided.
+ *
+ * @returns The rendered JSX element for the quote completion UI.
+ */
 function QuoteCompleteContent() {
   const searchParams = useSearchParams();
 
@@ -103,10 +123,15 @@ function QuoteCompleteContent() {
   );
 }
 
+/**
+ * Renders the quote completion page UI inside a Suspense boundary.
+ *
+ * @returns The React element tree for the quote completion page wrapped with `Suspense`.
+ */
 export default function QuoteCompletePage() {
   return (
     <Suspense fallback={null}>
       <QuoteCompleteContent />
     </Suspense>
   );
-}
+}

frontend/src/app/dealer/actions.ts

@@ -3,6 +3,12 @@
 import { cookies } from 'next/headers'
 import { redirect } from 'next/navigation'
 
+/**
+ * Read and validate Supabase connection values from environment variables.
+ *
+ * @returns An object whose `url` is the Supabase URL and `anonKey` is the anonymous public key.
+ * @throws Error if either the Supabase URL or anon key environment variable is not set.
+ */
 function getSupabaseConfig(): { url: string; anonKey: string } {
   const url = process.env.NEXT_PUBLIC_SUPABASE_URL ?? process.env.SUPABASE_URL
   const anonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ?? process.env.SUPABASE_ANON_KEY
@@ -14,6 +20,11 @@ function getSupabaseConfig(): { url: string; anonKey: string } {
   return { url, anonKey }
 }
 
+/**
+ * Build the Supabase REST v1 base URL from the configured Supabase URL.
+ *
+ * @returns The REST base URL — the configured Supabase URL with any trailing slash removed and `/rest/v1` appended
+ */
 function getRestBase(): string {
   const { url } = getSupabaseConfig()
   return `${url.replace(/\/$/, '')}/rest/v1`
@@ -103,6 +114,13 @@ function extractAccessTokenFromCookie(): string {
   redirect('/configurator')
 }
 
+/**
+ * Validate that the current session's role is "dealer" and return the session access token.
+ *
+ * Redirects the request to `/configurator` if the decoded token's role is not `dealer`.
+ *
+ * @returns The access token extracted from cookies
+ */
 function requireDealerToken(): string {
   const token = extractAccessTokenFromCookie()
   const payload = decodeJwtPayload(token)
@@ -121,6 +139,13 @@ function requireDealerToken(): string {
   return token
 }
 
+/**
+ * Constructs request headers required for Supabase REST calls.
+ *
+ * @param token - The Supabase access token to include in the `Authorization` header
+ * @param extra - Additional headers to merge into the result
+ * @returns A HeadersInit object containing `apikey`, `Authorization` with the bearer token, and any provided extra headers
+ */
 function buildHeaders(token: string, extra?: Record<string, string>): HeadersInit {
   const { anonKey } = getSupabaseConfig()
   return {
@@ -154,6 +179,14 @@ async function handleSupabaseError(response: Response): Promise<never> {
   throw new Error(`Supabase request failed: ${response.status} ${text}`)
 }
 
+/**
+ * Fetches dealer quote records for the authenticated dealer, ordered by creation time descending.
+ *
+ * Redirects the user to `/configurator` if the request is unauthorized (HTTP 401 or 403).
+ *
+ * @returns An array of `DealerQuote` objects with optional fields normalized (numeric fields are numbers or `null`).
+ * @throws Error If the Supabase request fails with a non-401/403 response; the error includes the response status and body.
+ */
 export async function listDealerQuotes(): Promise<DealerQuote[]> {
   const token = requireDealerToken()
   const REST_BASE = getRestBase()
@@ -196,6 +229,14 @@ export async function listDealerQuotes(): Promise<DealerQuote[]> {
   return payload.map((row) => normalizeQuote(row))
 }
 
+/**
+ * Approves a dealer quote by setting its status to "approved" and recording the approval timestamp.
+ *
+ * @param quoteId - The ID of the quote to approve
+ * @returns The updated DealerQuote record after approval
+ * @throws Error if the Supabase request fails or the response does not include the updated quote record
+ * @note Redirects the client to /configurator on 401 or 403 responses
+ */
 export async function approveDealerQuote(quoteId: string): Promise<DealerQuote> {
   const token = requireDealerToken()
   const REST_BASE = getRestBase()
@@ -234,6 +275,13 @@ export async function approveDealerQuote(quoteId: string): Promise<DealerQuote>
   return normalizeQuote(row)
 }
 
+/**
+ * Retrieve a downloadable URL for a dealer quote PDF.
+ *
+ * @param quoteId - The dealer quote's id to look up
+ * @returns An object with the resolved PDF `url`
+ * @throws Error if the quote PDF is not available yet
+ */
 export async function getQuoteDownloadUrl(quoteId: string): Promise<{ url: string }> {
   const token = requireDealerToken()
   const REST_BASE = getRestBase()
@@ -269,4 +317,4 @@ export async function getQuoteDownloadUrl(quoteId: string): Promise<{ url: strin
   const normalized = pdfUrl.startsWith('/') ? pdfUrl : `/${pdfUrl}`
   const { url: supabaseUrl } = getSupabaseConfig()
   return { url: `${supabaseUrl.replace(/\/$/, '')}${normalized}` }
-}
+}

frontend/src/app/kitchen-configurator/[sku]/page.tsx

@@ -37,6 +37,12 @@ async function load(gltf: GLTF & { scene: THREE.Group }, overrides: MaterialOver
   )
 }
 
+/**
+ * Loads a GLTF model for the given SKU, applies material overrides, plays its animations, and renders the scene.
+ *
+ * @param sku - Product SKU used to locate the GLTF file at `/models/{sku}.glb`
+ * @returns The GLTF scene as a React element, or `null` if the scene is not available
+ */
 function KitchenModel({ sku }: { sku: string }) {
   const src = useMemo(() => `/models/${sku}.glb`, [sku])
   const gltf = useGLTF(src) as unknown as GLTF & { scene: THREE.Group }
@@ -107,4 +113,4 @@ export default function KitchenConfiguratorPage({ params }: { params: { sku: str
   )
 }
 
-useGLTF.preload('/models/BaseCabinet600.glb')
+useGLTF.preload('/models/BaseCabinet600.glb')

frontend/src/app/server-actions/dealerQuotes.ts

@@ -11,6 +11,12 @@ class DealerAuthorizationError extends Error {
   }
 }
 
+/**
+ * Retrieve Supabase connection settings from environment variables.
+ *
+ * @returns An object containing `url` (Supabase URL) and `anonKey` (public anon key)
+ * @throws Error if `NEXT_PUBLIC_SUPABASE_URL` or `NEXT_PUBLIC_SUPABASE_ANON_KEY` is not set
+ */
 function getSupabaseConfig() {
   const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
   const anonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
@@ -22,6 +28,11 @@ function getSupabaseConfig() {
   return { url, anonKey };
 }
 
+/**
+ * Creates a Supabase server client configured to read and persist authentication state via Next.js server cookies.
+ *
+ * @returns A Supabase server client instance configured with cookie adapters for auth persistence
+ */
 function createDealerServerClient(): SupabaseClient<any, any, any> {
   const { url, anonKey } = getSupabaseConfig();
   const cookieStore = cookies();
@@ -49,6 +60,13 @@ function createDealerServerClient(): SupabaseClient<any, any, any> {
   });
 }
 
+/**
+ * Return a Supabase server client for the currently authenticated user after verifying dealer access.
+ *
+ * @returns A Supabase server client configured for the current session when the user is authenticated and authorized as a dealer.
+ * @throws DealerAuthorizationError - if there is no authenticated user or the user is not a dealer.
+ * @throws Error - if verifying the Supabase session or validating dealer access fails (contains the underlying error message).
+ */
 async function requireDealerClient(): Promise<SupabaseClient<any, any, any>> {
   const supabase = createDealerServerClient();
   const {
@@ -219,4 +237,4 @@ export async function approveDealerQuote(quoteId: string): Promise<DealerQuoteRe
   return data;
 }
 
-export { DealerAuthorizationError };
+export { DealerAuthorizationError };

frontend/src/app/web-vitals.ts

@@ -54,6 +54,11 @@ type MetricWithAttribution =
   | MetricFromHandler<Parameters<typeof onLCP>[0]>
   | MetricFromHandler<Parameters<typeof onTTFB>[0]>
 
+/**
+ * Trims the in-memory queue down to MAX_QUEUE_ITEMS by removing items from one end.
+ *
+ * @param drop - Which end to remove items from: `'oldest'` removes from the front of the queue, `'newest'` removes from the back
+ */
 function enforceQueueLimit(drop: 'oldest' | 'newest' = 'oldest') {
   while (queue.length > MAX_QUEUE_ITEMS) {
     if (drop === 'oldest') {
@@ -64,6 +69,13 @@ function enforceQueueLimit(drop: 'oldest' | 'newest' = 'oldest') {
   }
 }
 
+/**
+ * Compute the byte length of the serialized batch (metrics plus sent timestamp).
+ *
+ * @param metrics - Array of payloads to include in the serialized batch
+ * @param sentAt - ISO timestamp string to include alongside the metrics
+ * @returns The UTF-8 encoded byte length of `JSON.stringify({ sentAt, metrics })`
+ */
 function calculateChunkSize(metrics: Payload[], sentAt: string): number {
   return textEncoder.encode(JSON.stringify({ sentAt, metrics })).length
 }
@@ -155,6 +167,11 @@ async function sendChunk(chunk: Payload[], sentAt: string): Promise<boolean> {
   }
 }
 
+/**
+ * Sends all queued web-vitals payloads to the configured reporting endpoint.
+ *
+ * Splits the current queue into size-constrained chunks, attempts to transmit each chunk, and on failure re‑queues the failed chunk at the front of the queue (enforcing the queue size limit with a newest-item bias). If any items remain queued after processing, schedules a subsequent flush attempt.
+ */
 async function flushQueue(): Promise<void> {
   if (queue.length === 0) {
     return
@@ -234,6 +251,13 @@ function enqueue(payload: Payload) {
   scheduleFlush();
 }
 
+/**
+ * Schedule a future flush of the queued web-vital payloads.
+ *
+ * If running outside a browser or a flush is already scheduled, this function does nothing.
+ *
+ * @param delay - Time in milliseconds to wait before invoking the flush (defaults to FLUSH_INTERVAL_MS)
+ */
 function scheduleFlush(delay = FLUSH_INTERVAL_MS) {
   if (typeof window === 'undefined') {
     return
@@ -249,6 +273,14 @@ function scheduleFlush(delay = FLUSH_INTERVAL_MS) {
   }, delay)
 }
 
+/**
+ * Captures navigation timing entries once and enqueues them as navigation payloads.
+ *
+ * If navigation timing is available and has entries, this function records each entry
+ * (as a plain object), attaches page/href/timestamps and timeOrigin, enqueues a
+ * navigation payload for each entry, and marks navigation timing as captured to
+ * avoid duplicate reporting.
+ */
 function captureNavigationTiming() {
   if (navigationCaptured) {
     return;
@@ -330,6 +362,12 @@ function sanitizeAttribution(value: unknown): Record<string, unknown> | undefine
   return attribution;
 }
 
+/**
+ * Builds a WebVitalPayload from a web-vital metric, extracting attribution and navigation metadata.
+ *
+ * @param metric - The reported metric; may include `attribution` and `startTime` which are used in the payload.
+ * @returns The WebVitalPayload containing the metric details (`name`, `value`, `delta`, `id`, `rating`, `startTime`, `navigationType`, `attribution`) and contextual fields (`page`, `href`, `navigationType`, `timestamp`, `timeOrigin`). The `attribution` value is converted into a plain, JSON-serializable form if present.
+ */
 function createMetricPayload(metric: MetricWithAttribution): WebVitalPayload {
   const attribution = metric.attribution as ({ navigationType?: string } & Record<string, unknown>) | undefined
   const navigationType = attribution?.navigationType
@@ -409,4 +447,4 @@ export function flushWebVitalsQueue() {
   }
 
   return flushQueue()
-}
+}