fix(sdk-client) #35655: translate UVE_MODE key to backend PageMode value in page.get()

[zJaaal]

Summary

Closes #35655.

The mode parameter on @dotcms/client's client.page.get() is typed as keyof typeof UVE_MODE ('EDIT' | 'PREVIEW' | 'LIVE' | 'UNKNOWN'), but the value was being forwarded as-is to the GraphQL pageMode variable. The backend PageMode.get(String) matches against the Java enum's name() (EDIT_MODE, PREVIEW_MODE, LIVE, ...) and silently falls back to LIVE for anything else — so mode: 'EDIT' and mode: 'PREVIEW' from the SDK were rendering as LIVE on the backend.

This change translates the enum key to its value (UVE_MODE[mode]) right before constructing the GraphQL variables, so 'EDIT' is sent as 'EDIT_MODE' and 'PREVIEW' as 'PREVIEW_MODE'. The public type for DotCMSPageRequestParams.mode is unchanged, so this is a non-breaking fix for SDK consumers.

mode argument	Before (sent / resolved)	After (sent / resolved)
'LIVE' (default)	LIVE → ✅ LIVE	LIVE → ✅ LIVE
'EDIT'	EDIT → ❌ LIVE (fallback)	EDIT_MODE → ✅ EDIT_MODE
'PREVIEW'	PREVIEW → ❌ LIVE (fallback)	PREVIEW_MODE → ✅ PREVIEW_MODE
'UNKNOWN'	UNKNOWN → ❌ LIVE (fallback)	UNKNOWN → ❌ LIVE (fallback, unchanged — backend has no UNKNOWN mode)

Why only @dotcms/client?

@dotcms/react, @dotcms/angular, and @dotcms/uve use UVE_MODE only for runtime UI checks (state.mode === UVE_MODE.EDIT) and route page fetches through @dotcms/client underneath — they inherit the fix transitively.

Files changed

• libs/sdk/client/src/lib/client/page/page-api.ts — import UVE_MODE, translate key → value before sending
• libs/sdk/client/src/lib/client/page/page-api.spec.ts — replaced the existing single-mode test with a parametrized it.each covering all four UVE_MODE keys, and updated the older "should pass correct variables" test to use a real key

Test plan

• yarn nx test sdk-client --testPathPattern=page-api.spec — 278 tests pass, including new parametrized translation test (EDIT → EDIT_MODE, PREVIEW → PREVIEW_MODE, LIVE → LIVE, UNKNOWN → UNKNOWN)
• yarn nx lint sdk-client — clean (3 pre-existing warnings in unrelated structured-error block)
• Manual verification: external Next.js example consuming @dotcms/client requests a page with mode: 'PREVIEW' against a live backend and confirms the preview version is returned (not LIVE)

🤖 Generated with Claude Code

This PR fixes: #35655

[claude]

Claude finished @zJaaal's task in 2m 6s —— View job

---

Review

• Read changed files (page-api.ts, page-api.spec.ts)
• Verified UVE_MODE enum (EDIT='EDIT_MODE', PREVIEW='PREVIEW_MODE', LIVE='LIVE', UNKNOWN='UNKNOWN') and DotCMSPageRequestParams.mode: keyof typeof UVE_MODE typing
• Confirmed backend PageMode.get(String) (dotCMS/src/main/java/com/dotmarketing/util/PageMode.java:97) matches name() (LIVE, PREVIEW_MODE, EDIT_MODE, …) and silently defaults to LIVE, validating the root cause
• Checked other page.get() callers in @dotcms/react/@dotcms/angular/@dotcms/uve — none forward mode directly; UVE only uses UVE_MODE for UI state, so the fix is correctly scoped
• Verified spec file: no remaining test passes a backend-value (e.g. 'PREVIEW_MODE') as input to mode; only keyof typeof UVE_MODE values are sent

Verdict

Clean. Fix is correctly scoped and well-tested.

Nits (non-blocking)

1. Unrelated ?. change at page-api.ts:219-221. Swapping structuredError.extensions!.code! → structuredError.extensions?.code is unrelated to the stated PR scope and widens code from string to string | undefined. The .find() predicate already guarantees extensions.code is truthy here, so the non-null assertion expressed the actual invariant. Defensible either way, but it's drift that doesn't belong in a "translate UVE_MODE" PR — consider reverting to keep the diff focused, or split into a small follow-up.

2. UNKNOWN still falls through to backend LIVE. Documented in the PR description, but silent — a JS consumer who somehow ends up in UNKNOWN will get LIVE content with no warning. Worth a consola.warn (or at minimum a JSDoc note on DotCMSPageRequestParams.mode) so future readers know 'UNKNOWN' is a no-op rather than a bug. Low priority since UNKNOWN is documented as an error state nobody should reach.

3. JS (non-TS) consumer fallback. UVE_MODE[arbitraryString] returns undefined, which the backend's PageMode.get(null) resolves to LIVE. Behavior is fine; just noting it's an implicit contract for the non-typed path.