feat(api): Add complete headless JS client API support

P0 - Critical:
- Add Favorites API (CRUD + check) at /api_public/v1/favorites
- Add Saved Searches API (CRUD + verify/unsubscribe) at /api_public/v1/saved_searches
- Token-based authentication for anonymous access

P1 - High Priority:
- Add Locales endpoint for i18n and hreflang tags
- Add Cacheable concern with ETag/Cache-Control helpers
- Add page parts support via include_parts param on Pages API
- Add caching to theme, site_details, translations, search_config

P2 - Medium Priority:
- Add Search Facets endpoint for lightweight filter counts
- Add JSON-LD schema endpoint for SEO

P3 - Nice to Have:
- Add map_config to theme response
- Add analytics config to site_details response

New files:
- app/controllers/api_public/v1/favorites_controller.rb
- app/controllers/api_public/v1/saved_searches_controller.rb
- app/controllers/api_public/v1/locales_controller.rb
- app/controllers/api_public/v1/search_facets_controller.rb
- app/controllers/concerns/api_public/cacheable.rb
- docs/frontend/BACKEND_WORK_FOR_JS_CLIENTS.md
- docs/frontend/public_frontend_functionality.md
- spec/requests/api_public/v1/favorites_spec.rb
- spec/requests/api_public/v1/saved_searches_spec.rb
- spec/requests/api_public/v1/locales_spec.rb
- spec/requests/api_public/v1/search_facets_spec.rb

Modified files:
- config/routes.rb (new API routes)
- app/controllers/api_public/v1/properties_controller.rb (caching + schema)
- app/controllers/api_public/v1/theme_controller.rb (caching + map_config)
- app/controllers/api_public/v1/site_details_controller.rb (caching + analytics)
- app/controllers/api_public/v1/translations_controller.rb (caching)
- app/controllers/api_public/v1/search_config_controller.rb (caching)
- app/controllers/api_public/v1/pages_controller.rb (caching + page_parts)

Author: etewiah

app/controllers/api_public/v1/favorites_controller.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    # Public API for managing saved/favorited properties
+    # Users access this via token-based authentication (no login required)
+    class FavoritesController < BaseController
+      before_action :set_favorite_by_token, only: %i[show update destroy]
+      before_action :set_favorites_by_manage_token, only: [:index]
+
+      # GET /api_public/v1/favorites?token=XXX
+      # List all favorites for email associated with token
+      def index
+        render json: {
+          email: @favorites.first&.email,
+          favorites: @favorites.map { |f| favorite_json(f) }
+        }
+      end
+
+      # GET /api_public/v1/favorites/:id?token=XXX
+      def show
+        render json: favorite_json(@favorite)
+      end
+
+      # POST /api_public/v1/favorites
+      # Create a new favorite
+      # Body: { favorite: { email, provider, external_reference, property_data?, notes? } }
+      def create
+        favorite = build_favorite
+
+        if favorite.save
+          render json: {
+            success: true,
+            favorite: favorite_json(favorite),
+            manage_token: favorite.manage_token,
+            manage_url: favorites_manage_url(favorite.manage_token)
+          }, status: :created
+        else
+          render json: { success: false, errors: favorite.errors.full_messages },
+                 status: :unprocessable_content
+        end
+      end
+
+      # PATCH /api_public/v1/favorites/:id?token=XXX
+      # Update notes
+      def update
+        if @favorite.update(favorite_update_params)
+          render json: { success: true, favorite: favorite_json(@favorite) }
+        else
+          render json: { success: false, errors: @favorite.errors.full_messages },
+                 status: :unprocessable_content
+        end
+      end
+
+      # DELETE /api_public/v1/favorites/:id?token=XXX
+      def destroy
+        @favorite.destroy
+        render json: { success: true }
+      end
+
+      # POST /api_public/v1/favorites/check
+      # Check which references are already saved for an email
+      # Body: { email, references: [] }
+      def check
+        email = params[:email].to_s.downcase.strip
+        references = Array(params[:references])
+
+        saved = saved_property_class
+                .for_email(email)
+                .where(external_reference: references)
+                .pluck(:external_reference)
+
+        render json: { saved: saved }
+      end
+
+      private
+
+      def set_favorite_by_token
+        @favorite = saved_property_class.find_by(manage_token: params[:token])
+        @favorite ||= saved_property_class.find_by(id: params[:id], manage_token: params[:token])
+
+        return if @favorite
+
+        render json: { error: "Invalid token" }, status: :unauthorized
+      end
+
+      def set_favorites_by_manage_token
+        sample = saved_property_class.find_by(manage_token: params[:token])
+
+        unless sample
+          render json: { error: "Invalid token" }, status: :unauthorized
+          return
+        end
+
+        @favorites = saved_property_class.for_email(sample.email).recent
+      end
+
+      def build_favorite
+        favorite = saved_property_class.new(favorite_params)
+        favorite.website = Pwb::Current.website
+
+        # Fetch and cache property data if not provided
+        fetch_and_cache_property_data(favorite) if favorite.property_data.blank? && favorite.external_reference.present?
+
+        favorite
+      end
+
+      def fetch_and_cache_property_data(favorite)
+        # For internal properties, fetch from database
+        return unless favorite.provider == "internal"
+
+        property = Pwb::Current.website.listed_properties.find_by(
+          id: favorite.external_reference
+        ) || Pwb::Current.website.listed_properties.find_by(
+          slug: favorite.external_reference
+        )
+
+        return unless property
+
+        favorite.property_data = {
+          title: property.title,
+          price: property.price_hash,
+          image_url: property.primary_image_url,
+          property_url: "/properties/#{property.slug}",
+          bedrooms: property.count_bedrooms,
+          bathrooms: property.count_bathrooms,
+          area: property.plot_area
+        }
+        favorite.original_price_cents = property.price_cents
+        favorite.current_price_cents = property.price_cents
+
+        # External properties would use the feed API - handled elsewhere
+      end
+
+      def favorite_params
+        params.require(:favorite).permit(
+          :email, :provider, :external_reference, :notes,
+          property_data: {}
+        )
+      end
+
+      def favorite_update_params
+        params.require(:favorite).permit(:notes)
+      end
+
+      def favorite_json(fav)
+        {
+          id: fav.id,
+          email: fav.email,
+          provider: fav.provider,
+          external_reference: fav.external_reference,
+          notes: fav.notes,
+          title: fav.title,
+          price: fav.price,
+          price_formatted: fav.price_formatted,
+          image_url: fav.image_url,
+          property_url: fav.property_url,
+          original_price_cents: fav.original_price_cents,
+          current_price_cents: fav.current_price_cents,
+          price_changed: fav.price_changed_at.present?,
+          price_changed_at: fav.price_changed_at,
+          created_at: fav.created_at,
+          manage_token: fav.manage_token
+        }
+      end
+
+      def favorites_manage_url(token)
+        "#{request.protocol}#{request.host_with_port}/my/favorites?token=#{token}"
+      end
+
+      def saved_property_class
+        # Use tenant-specific model if available, otherwise fall back to Pwb
+        if defined?(PwbTenant::SavedProperty)
+          PwbTenant::SavedProperty
+        else
+          Pwb::SavedProperty
+        end
+      end
+    end
+  end
+end

app/controllers/api_public/v1/locales_controller.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    # Public API endpoint for available locales/languages
+    # Returns enabled locales for the current website for language switchers and hreflang
+    class LocalesController < BaseController
+      # GET /api_public/v1/locales
+      def index
+        website = Pwb::Current.website
+
+        render json: {
+          default_locale: default_locale(website),
+          available_locales: available_locales(website),
+          current_locale: I18n.locale.to_s
+        }
+      end
+
+      private
+
+      def default_locale(website)
+        if website.respond_to?(:default_locale) && website.default_locale.present?
+          website.default_locale
+        else
+          I18n.default_locale.to_s
+        end
+      end
+
+      def available_locales(website)
+        # Website may have enabled_locales field, otherwise fall back to app defaults
+        locales = if website.respond_to?(:enabled_locales) && website.enabled_locales.present?
+                    website.enabled_locales
+                  else
+                    %w[en es de fr nl pt it]
+                  end
+
+        locales.map do |code|
+          {
+            code: code,
+            name: locale_name(code),
+            native_name: locale_native_name(code),
+            flag_emoji: locale_flag(code),
+            url_prefix: code == default_locale(website) ? nil : "/#{code}"
+          }
+        end
+      end
+
+      def locale_name(code)
+        LOCALE_NAMES[code] || code.upcase
+      end
+
+      def locale_native_name(code)
+        LOCALE_NATIVE_NAMES[code] || code.upcase
+      end
+
+      def locale_flag(code)
+        LOCALE_FLAGS[code] || "🏳️"
+      end
+
+      LOCALE_NAMES = {
+        "en" => "English",
+        "es" => "Spanish",
+        "de" => "German",
+        "fr" => "French",
+        "nl" => "Dutch",
+        "pt" => "Portuguese",
+        "it" => "Italian",
+        "ru" => "Russian",
+        "zh" => "Chinese",
+        "ja" => "Japanese",
+        "ar" => "Arabic",
+        "pl" => "Polish",
+        "sv" => "Swedish",
+        "no" => "Norwegian",
+        "da" => "Danish",
+        "fi" => "Finnish"
+      }.freeze
+
+      LOCALE_NATIVE_NAMES = {
+        "en" => "English",
+        "es" => "Español",
+        "de" => "Deutsch",
+        "fr" => "Français",
+        "nl" => "Nederlands",
+        "pt" => "Português",
+        "it" => "Italiano",
+        "ru" => "Русский",
+        "zh" => "中文",
+        "ja" => "日本語",
+        "ar" => "العربية",
+        "pl" => "Polski",
+        "sv" => "Svenska",
+        "no" => "Norsk",
+        "da" => "Dansk",
+        "fi" => "Suomi"
+      }.freeze
+
+      LOCALE_FLAGS = {
+        "en" => "🇬🇧",
+        "es" => "🇪🇸",
+        "de" => "🇩🇪",
+        "fr" => "🇫🇷",
+        "nl" => "🇳🇱",
+        "pt" => "🇵🇹",
+        "it" => "🇮🇹",
+        "ru" => "🇷🇺",
+        "zh" => "🇨🇳",
+        "ja" => "🇯🇵",
+        "ar" => "🇸🇦",
+        "pl" => "🇵🇱",
+        "sv" => "🇸🇪",
+        "no" => "🇳🇴",
+        "da" => "🇩🇰",
+        "fi" => "🇫🇮"
+      }.freeze
+    end
+  end
+end