Preferences: Add API validation and update documentation (#116045)

pkg/api/dtos/prefs.go

@@ -13,7 +13,7 @@ type UpdatePrefsCmd struct {
 	// Deprecated: Use HomeDashboardUID instead
 	HomeDashboardID  int64   `json:"homeDashboardId"`
 	HomeDashboardUID *string `json:"homeDashboardUID,omitempty"`
-	// Enum: utc,browser
+	// Any IANA timezone string (e.g. America/New_York), 'utc', 'browser', or empty string
 	Timezone       string                       `json:"timezone"`
 	WeekStart      string                       `json:"weekStart"`
 	QueryHistory   *pref.QueryHistoryPreference `json:"queryHistory,omitempty"`
@@ -31,7 +31,7 @@ type PatchPrefsCmd struct {
 	// Default:0
 	// Deprecated: Use HomeDashboardUID instead
 	HomeDashboardID *int64 `json:"homeDashboardId,omitempty"`
-	// Enum: utc,browser
+	// Any IANA timezone string (e.g. America/New_York), 'utc', 'browser', or empty string
 	Timezone         *string                      `json:"timezone,omitempty"`
 	WeekStart        *string                      `json:"weekStart,omitempty"`
 	Language         *string                      `json:"language,omitempty"`

pkg/api/preferences.go

@@ -134,6 +134,10 @@ func (hs *HTTPServer) patchPreferencesFor(ctx context.Context, orgID, userID, te
 		return response.Error(http.StatusBadRequest, "Invalid theme", nil)
 	}
 
+	if dtoCmd.Timezone != nil && !pref.IsValidTimezone(*dtoCmd.Timezone) {
+		return response.Error(http.StatusBadRequest, "Invalid timezone. Must be a valid IANA timezone (e.g., America/New_York), 'utc', 'browser', or empty string", nil)
+	}
+
 	// convert dashboard UID to ID in order to store internally if it exists in the query, otherwise take the id from query
 	// nolint:staticcheck
 	dashboardID := dtoCmd.HomeDashboardID