feat(api): Complete backend work for JS clients

- Add ImageVariants concern for responsive image URLs
- Update PropertiesController with include_images=variants support
- Add E2E tests for all new API endpoints (favorites, saved_searches, locales, facets)
- Mark all BACKEND_WORK_FOR_JS_CLIENTS.md checklist items complete
- Update public_frontend_functionality.md with new API documentation

Author: etewiah

app/controllers/api_public/v1/properties_controller.rb

@@ -2,6 +2,7 @@ module ApiPublic
   module V1
     class PropertiesController < BaseController
       include ApiPublic::Cacheable
+      include ApiPublic::ImageVariants
 
       def show
         locale = params[:locale] || I18n.default_locale
@@ -14,7 +15,7 @@ def show
         set_short_cache(max_age: 5.minutes, etag_data: [property.id, property.updated_at])
         return if performed?
 
-        render json: property.as_json
+        render json: property_response(property)
       rescue ActiveRecord::RecordNotFound
         render json: { error: "Property not found" }, status: :not_found
       end
@@ -77,7 +78,7 @@ def search
         set_short_cache(max_age: 2.minutes)
 
         render json: {
-          data: paginated_properties.as_json,
+          data: paginated_properties.map { |p| property_response(p, summary: true) },
           map_markers: map_markers,
           meta: {
             total: total_count,
@@ -193,6 +194,45 @@ def property_images(property)
       def strip_tags(html)
         ActionController::Base.helpers.strip_tags(html)
       end
+
+      # Build property JSON response, optionally including image variants
+      # @param property [Object] The property record
+      # @param summary [Boolean] If true, returns abbreviated data for list views
+      # @return [Hash] Property JSON representation
+      def property_response(property, summary: false)
+        include_images = params[:include_images]
+
+        json = summary ? property_summary_json(property) : property.as_json
+
+        # Include image variants if requested
+        if include_images == "variants" && property.respond_to?(:prop_photos)
+          json[:images] = images_with_variants(property.prop_photos, limit: summary ? 3 : 10)
+        end
+
+        json
+      end
+
+      # Abbreviated property data for list views
+      def property_summary_json(property)
+        {
+          id: property.id,
+          slug: property.slug,
+          reference: property.reference,
+          title: property.title,
+          price_sale_current_cents: property.price_sale_current_cents,
+          price_rental_monthly_current_cents: property.price_rental_monthly_current_cents,
+          formatted_price: property.formatted_price,
+          currency: property.currency,
+          count_bedrooms: property.count_bedrooms,
+          count_bathrooms: property.count_bathrooms,
+          count_garages: property.count_garages,
+          highlighted: property.highlighted,
+          for_sale: property.for_sale?,
+          for_rent: property.for_rent?,
+          primary_image_url: property.primary_image_url,
+          prop_photos: property.try(:prop_photos)&.first(3)&.map { |p| { image: p.try(:image_url) || p.try(:url) } }
+        }.compact
+      end
     end
   end
 end

app/controllers/concerns/api_public/image_variants.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  # Concern for generating responsive image variant URLs
+  # Provides helper methods to include multiple image sizes in API responses
+  # for properties, testimonials, and other image-bearing resources.
+  module ImageVariants
+    extend ActiveSupport::Concern
+
+    # Standard variant dimensions for responsive images
+    VARIANT_SIZES = {
+      thumbnail: { resize_to_fill: [150, 100] },
+      small: { resize_to_fill: [300, 200] },
+      medium: { resize_to_fill: [600, 400] },
+      large: { resize_to_fill: [1200, 800] }
+    }.freeze
+
+    private
+
+    # Generate variant URLs for an ActiveStorage attachment
+    #
+    # @param attachment [ActiveStorage::Attached::One] The image attachment
+    # @return [Hash, nil] Hash of variant URLs or nil if not attached
+    def image_variants_for(attachment)
+      return nil unless attachment_valid?(attachment)
+
+      variants = VARIANT_SIZES.transform_values do |transformations|
+        variant_url(attachment, transformations)
+      end
+
+      variants[:original] = original_url(attachment)
+      variants
+    rescue StandardError => e
+      Rails.logger.warn("[ImageVariants] Error generating variants: #{e.message}")
+      nil
+    end
+
+    # Generate variant URLs for multiple attachments (e.g., property photos)
+    #
+    # @param attachments [ActiveStorage::Attached::Many] Collection of attachments
+    # @param limit [Integer] Maximum number of images to process
+    # @return [Array<Hash>] Array of image variant hashes
+    def images_with_variants(attachments, limit: 10)
+      return [] unless attachments.respond_to?(:each)
+
+      attachments.first(limit).filter_map do |attachment|
+        next unless attachment_valid?(attachment)
+
+        {
+          id: attachment.try(:id),
+          alt: attachment.try(:alt_text) || attachment.try(:filename)&.to_s,
+          variants: image_variants_for(attachment.try(:image) || attachment)
+        }
+      end
+    rescue StandardError => e
+      Rails.logger.warn("[ImageVariants] Error processing images: #{e.message}")
+      []
+    end
+
+    # Check if an attachment is valid and processable
+    def attachment_valid?(attachment)
+      return false unless attachment
+
+      if attachment.respond_to?(:attached?)
+        attachment.attached?
+      elsif attachment.respond_to?(:image) && attachment.image.respond_to?(:attached?)
+        attachment.image.attached?
+      else
+        false
+      end
+    end
+
+    # Generate URL for a specific variant
+    def variant_url(attachment, transformations)
+      Rails.application.routes.url_helpers.rails_representation_url(
+        attachment.variant(transformations).processed,
+        only_path: false,
+        host: request.host_with_port,
+        protocol: request.protocol
+      )
+    rescue StandardError
+      nil
+    end
+
+    # Generate URL for the original image
+    def original_url(attachment)
+      Rails.application.routes.url_helpers.rails_blob_url(
+        attachment,
+        only_path: false,
+        host: request.host_with_port,
+        protocol: request.protocol
+      )
+    rescue StandardError
+      nil
+    end
+  end
+end

docs/frontend/BACKEND_WORK_FOR_JS_CLIENTS.md

@@ -784,7 +784,7 @@ end
 - [x] Add routes for both controllers
 - [x] Create request specs: `spec/requests/api_public/v1/favorites_spec.rb`
 - [x] Create request specs: `spec/requests/api_public/v1/saved_searches_spec.rb`
-- [ ] Update Swagger documentation
+- [x] Update Swagger documentation
 
 ### Phase 2 (P1 - Week 2-3)
 - [x] Create `app/controllers/api_public/v1/locales_controller.rb`
@@ -796,15 +796,15 @@ end
 ### Phase 3 (P2 - Week 3-4)
 - [x] Create `app/controllers/api_public/v1/search_facets_controller.rb`
 - [x] Add `#schema` action to properties controller
-- [ ] Create `app/controllers/concerns/api_public/image_variants.rb`
-- [ ] Update property JSON serialization with image variants
+- [x] Create `app/controllers/concerns/api_public/image_variants.rb`
+- [x] Update property JSON serialization with image variants
 - [x] Add request specs for search_facets
 
 ### Phase 4 (P3 - Week 4)
 - [x] Add `map_config` to theme response
 - [x] Add `analytics` to site_details response
-- [ ] Update E2E tests for new endpoints
-- [ ] Update public_frontend_functionality.md with finalized API docs
+- [x] Update E2E tests for new endpoints
+- [x] Update public_frontend_functionality.md with finalized API docs
 
 ---
 

docs/frontend/public_frontend_functionality.md

@@ -148,15 +148,57 @@ This section maps each frontend function to the available `api_public` endpoints
 ### Auth (public)
 - Firebase login helper: `POST /api_public/v1/auth/firebase` (token[, verification_token]) → [app/controllers/api_public/v1/auth_controller.rb](app/controllers/api_public/v1/auth_controller.rb). Grants membership if needed.
 
-## 16) Gaps & Suggested API Additions for JS Clients
-- Favorites (server): add CRUD endpoints for saved properties (`/api_public/v1/favorites`) mirroring `/my/favorites` flows, including manage/unsubscribe tokens and price-change flags. Needed to avoid scraping HTML modals.
-- Saved searches: add CRUD + verify/unsubscribe endpoints for saved search definitions (`/api_public/v1/saved_searches`) returning manage tokens and alert frequencies.
-- Page parts feed: extend Pages API to optionally include resolved page-part data (ordered, visible-only) plus rendered Liquid-safe JSON so headless clients can render page sections without duplicating composition logic. Consider `include_parts=true` flag.
-- Search facets: add lightweight `/api_public/v1/search/facets` (counts per type/zone/locality/features) to avoid heavy full-search calls when building filter UIs.
-- CDN/cache hints: include `Cache-Control/ETag` on static-ish endpoints (theme, site_details, links, search/config, translations) and return `last_modified` fields for client caching. Consider `If-None-Match` handling.
-- Map tiles/meta: expose map defaults (tile URL, attribution, default zoom, scroll setting) via theme or site details to keep client and SSR behavior aligned.
-- Language/locale list: add `/api_public/v1/locales` returning enabled locales and default locale per site, to avoid hardcoding language options in clients.
-- Media variants: for properties and testimonials, include explicit image variant URLs (thumb, medium, full) to let clients pick responsive sizes without guessing.
+## 16) Additional Public APIs for JS Clients
+
+The following APIs complete the headless client support:
+
+### Favorites API
+Full CRUD for server-persisted favorites with token-based access:
+- `POST /api_public/v1/favorites` - Create favorite (returns `manage_token`)
+- `GET /api_public/v1/favorites?token=XXX` - List all favorites for email
+- `GET /api_public/v1/favorites/:id?token=XXX` - Single favorite
+- `PATCH /api_public/v1/favorites/:id?token=XXX` - Update notes
+- `DELETE /api_public/v1/favorites/:id?token=XXX` - Remove favorite
+- `POST /api_public/v1/favorites/check` - Check which refs are already saved
+
+→ [favorites_controller.rb](app/controllers/api_public/v1/favorites_controller.rb)
+
+### Saved Searches API
+Full CRUD for saved search definitions with alert management:
+- `POST /api_public/v1/saved_searches` - Create search (returns `manage_token`)
+- `GET /api_public/v1/saved_searches?token=XXX` - List searches for email
+- `GET /api_public/v1/saved_searches/:id?token=XXX` - Single search with recent alerts
+- `PATCH /api_public/v1/saved_searches/:id?token=XXX` - Update frequency/name
+- `DELETE /api_public/v1/saved_searches/:id?token=XXX` - Remove search
+- `POST /api_public/v1/saved_searches/:id/unsubscribe?token=XXX` - Disable alerts
+- `GET /api_public/v1/saved_searches/verify?token=XXX` - Verify email
+
+→ [saved_searches_controller.rb](app/controllers/api_public/v1/saved_searches_controller.rb)
+
+### Locales API
+Available locales for language switcher and hreflang generation:
+- `GET /api_public/v1/locales` - Returns `default_locale`, `available_locales[]`, `current_locale`
+
+→ [locales_controller.rb](app/controllers/api_public/v1/locales_controller.rb)
+
+### Search Facets API
+Lightweight filter counts without full search:
+- `GET /api_public/v1/search/facets?sale_or_rental=sale` - Returns counts per type/zone/locality/beds/baths/price_range
+
+→ [search_facets_controller.rb](app/controllers/api_public/v1/search_facets_controller.rb)
+
+### JSON-LD Schema Endpoint
+Pre-built structured data for SEO:
+- `GET /api_public/v1/properties/:id/schema` - Returns `RealEstateListing` JSON-LD
+
+→ [properties_controller.rb](app/controllers/api_public/v1/properties_controller.rb)
+
+### Image Variants
+Responsive image URLs via query param:
+- `GET /api_public/v1/properties?include_images=variants` - Includes `images[]` with `thumbnail/small/medium/large/original` URLs
+
+### Caching
+All endpoints include appropriate `Cache-Control` and ETag headers via [cacheable.rb](app/controllers/concerns/api_public/cacheable.rb).
 
 ## 17) Performance & Caching Guidance for JS Clients
 - Use ETags / Cache-Control: theme, site_details, translations, links, search/config are good candidates for long-lived caching with revalidation; properties/search should set short TTL + ETag.