feat(notifications): proxy Open edX notification preferences

[AhtishamShahid]

What are the relevant tickets?

Fixes mitodl/hq#12930

Paired with mitodl/mit-learn#3960, which is the UI. Merge this one first — without it, that PR's requests 404.

Description (What does it do?)

Open edX owns a learner's notification preferences and serves them only to the learner themselves, so nothing outside the LMS could read or change them on a learner's behalf.

This adds a GET/PUT /api/notification-preferences/ proxy that calls the LMS as the learner, using the Open edX bearer token this app already mints and refreshes for them. Nothing is stored here; the LMS response is passed through verbatim.

Three states are mapped to something a client can act on rather than a bare 502: a learner with no Open edX account yet gets 409, an LMS throttle passes through as 429, and any other upstream failure becomes 502. PUT validates the payload locally first, because the upstream API changes one channel per request and a malformed change would otherwise spend one of the learner's rate-limited LMS calls.

This PR is backend only. It originally carried a Notifications section for My Account; that UI now lives in MIT Learn (mitodl/mit-learn#3960), and the components, styles, query layer and constants were removed here.

How can this be tested?

1. As a learner with a synced Open edX account, GET /api/notification-preferences/ and confirm the body matches what the LMS returns for that learner.
2. PUT one change — for example {"notification_app": "discussion", "notification_type": "grouped_notification", "notification_channel": "web", "value": false} — then re-read and confirm it persisted, and that NotificationPreference in edx-platform changed for that user.
3. PUT a malformed payload (a channel of email_cadence with no email_cadence field) and confirm a 400, with no LMS call made.
4. As a learner with no Open edX account, confirm a 409 rather than a 500.
5. Confirm the endpoint appears in openapi/specs/v0.yaml and that ./manage.py generate_openapi_spec leaves the committed specs unchanged.

Validation run on this branch: pytest openedx — 205 passed, 6 skipped; ruff clean; spec regeneration verified byte-identical with --fail-on-warn. Rebased onto current main (the earlier CI failures were staleness — a regenerated Keycloak dataclass and moved specs that main already had), and all checks pass.

Additional Context

The 200 body is declared in the schema as a pass-through object rather than a modelled shape: it is the LMS response, and pinning a shape here would misrepresent who owns it.

[github-actions]

OpenAPI Changes

Show/hide changes

## Changes for v0.yaml:
2 changes: 0 error, 0 warning, 2 info
info	[endpoint-added] at head/openapi/specs/v0.yaml
	in API GET /api/notification-preferences/
		endpoint added

info	[endpoint-added] at head/openapi/specs/v0.yaml
	in API PUT /api/notification-preferences/
		endpoint added



## Changes for v1.yaml:
2 changes: 0 error, 0 warning, 2 info
info	[endpoint-added] at head/openapi/specs/v1.yaml
	in API GET /api/notification-preferences/
		endpoint added

info	[endpoint-added] at head/openapi/specs/v1.yaml
	in API PUT /api/notification-preferences/
		endpoint added



## Changes for v2.yaml:
2 changes: 0 error, 0 warning, 2 info
info	[endpoint-added] at head/openapi/specs/v2.yaml
	in API GET /api/notification-preferences/
		endpoint added

info	[endpoint-added] at head/openapi/specs/v2.yaml
	in API PUT /api/notification-preferences/
		endpoint added

Unexpected changes? Ensure your branch is up-to-date with main (consider rebasing).

[Copilot]

Pull request overview

Adds learner-managed Open edX notification preferences to My Account through a session-authenticated proxy.

Changes:

• Adds GET/PUT notification preference proxy endpoints and validation.
• Adds notification controls, labels, styling, and LMS synchronization.
• Adds backend and frontend tests for preferences and error handling.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
openedx/views.py	Exposes the authenticated proxy view.
openedx/views_test.py	Tests endpoint behavior and errors.
openedx/urls.py	Registers the proxy route.
openedx/serializers.py	Validates preference updates.
openedx/exceptions.py	Defines the proxy exception.
openedx/api.py	Calls Open edX using learner tokens.
openedx/api_test.py	Tests LMS requests and authentication failures.
frontend/public/src/lib/queries/notificationPreferences.js	Defines frontend query and mutation configurations.
frontend/public/src/containers/pages/settings/AccountSettingsPage.js	Integrates preferences into My Account.
frontend/public/src/constants.js	Adds notification display metadata.
frontend/public/src/components/NotificationPreferences.js	Renders preference controls.
frontend/public/src/components/NotificationPreferences_test.js	Tests preference rendering and interactions.
frontend/public/scss/notification-preferences.scss	Styles the notification section.
frontend/public/scss/layout.scss	Includes the new stylesheet.

Suppressed comments (2)

openedx/api.py:2063

• A timeout/connection failure from requests.get escapes as an unhandled 500 because only non-200 responses are wrapped. Likewise, invalid JSON from a 200 response fails at resp.json(). Catch RequestException and JSON decoding errors and re-raise EdxApiNotificationPreferencesError so upstream transport failures follow the documented 502 path.

    resp = requests.get(
        edx_url(OPENEDX_NOTIFICATION_PREFERENCES_PATH),
        headers=_notification_preferences_headers(user),
        timeout=settings.EDX_API_CLIENT_TIMEOUT,
    )

openedx/api.py:2097

• The PUT path also leaves connection timeouts and malformed successful JSON unwrapped, so the view returns 500 instead of the intended upstream 502. Convert request/decoding failures to EdxApiNotificationPreferencesError, matching the handling for non-200 LMS responses.

    resp = requests.put(
        edx_url(OPENEDX_NOTIFICATION_PREFERENCES_PATH),
        json=preference,
        headers={
            **_notification_preferences_headers(user),

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[AhtishamShahid]

Closing this in favour of mitodl/mit-learn#3960

[alexfigtree]

Hi, your precommit is failing, I can take a better look once that has been fixed

[sentry]

Bug: The functions get_notification_preferences and update_notification_preference do not handle network exceptions from the requests library, such as timeouts or connection errors.
_{Severity: MEDIUM}

Suggested Fix

Wrap the requests calls within a try...except requests.exceptions.RequestException block. In the except block, catch the exception and raise an appropriate custom exception or return a response indicating a gateway error, similar to the pattern used elsewhere in the file.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: openedx/api.py#L2078-L2090

Potential issue: The functions `get_notification_preferences` and
`update_notification_preference` make API calls using the `requests` library but do not
handle potential network-level exceptions like `requests.exceptions.ConnectionError` or
`requests.exceptions.Timeout`. If the remote LMS is slow or unreachable, these unhandled
exceptions will propagate and cause a 500 Internal Server Error instead of the intended
502 Bad Gateway. Given the configured 60-second timeout (`EDX_API_CLIENT_TIMEOUT`), a
timeout exception is a realistic possibility in a production environment.

_{Did we get this right? 👍 / 👎 to inform future reviews.}