feat(api): Update API endpoints for Astro.js headless frontend

- Property images: Use absolute URLs (rails_blob_url) with variants
  - Added small/medium/large image variants for responsive images
  - Added meta_title and meta_description fields for SEO
  - Configured resolve_asset_host for ASSET_HOST/APP_HOST env vars

- Site details: Expanded as_json with frontend-required fields
  - Added logo_url, favicon_url, css_variables, dark_mode_setting
  - Added contact_info helper (phone, email, address from agency)
  - Added social_links helper (structured social media links)
  - Added top_nav_links and footer_links using as_api_json format

- Links: Standardized JSON format for API consumption
  - Added as_api_json method with consistent field names
  - Added resolved_url helper for URL generation
  - Updated LinksController to accept both placement and position params

- Theme endpoint: New GET /api_public/v1/theme
  - Returns CSS variables, colors, fonts, palette info
  - Enables frontend CSS variable injection for theming

Author: etewiah

app/controllers/api_public/v1/links_controller.rb

@@ -3,7 +3,8 @@ module V1
     class LinksController < BaseController
 
       def index
-        placement = params[:placement]
+        # Accept both 'placement' and 'position' for API compatibility
+        placement = params[:placement] || params[:position]
         locale = params[:locale]
 
         if locale
@@ -18,11 +19,12 @@ def index
 
         # Filter by visibility if needed, similar to GraphQL implementation
         if params[:visible_only] == 'true' || placement == 'top_nav' || placement == 'footer'
-           links = links.where(visible: true)
+           links = links.where(visible: true).order('sort_order asc')
         end
 
-        render json: links.as_json
+        render json: { data: links.map(&:as_api_json) }
       end
     end
   end
 end
+

app/controllers/api_public/v1/theme_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    # ThemeController provides theming configuration for headless frontends
+    # Returns CSS variables, colors, and fonts for dynamic theme injection
+    class ThemeController < BaseController
+      def index
+        website = Pwb::Current.website
+
+        render json: {
+          data: {
+            theme_name: website.theme_name,
+            dark_mode: website.dark_mode_setting,
+            colors: website.style_variables,
+            css_variables: website.css_variables,
+            css_with_dark_mode: website.css_variables_with_dark_mode,
+            fonts: extract_fonts(website),
+            palette: {
+              selected: website.selected_palette,
+              available: website.available_palettes.keys
+            }
+          }
+        }
+      end
+
+      private
+
+      def extract_fonts(website)
+        vars = website.style_variables || {}
+        {
+          primary: vars["font_primary"] || "Open Sans",
+          secondary: vars["font_secondary"] || "Vollkorn"
+        }
+      end
+    end
+  end
+end

app/models/concerns/listed_property/photo_accessors.rb

@@ -18,10 +18,26 @@ def ordered_photo(number)
     def primary_image_url
       first_photo = ordered_photo(1)
       if prop_photos.any? && first_photo&.image&.attached?
-        Rails.application.routes.url_helpers.rails_blob_path(first_photo.image, only_path: true)
+        Rails.application.routes.url_helpers.rails_blob_url(
+          first_photo.image,
+          host: resolve_asset_host
+        )
       else
         ""
       end
     end
+
+    private
+
+    def resolve_asset_host
+      ENV.fetch('ASSET_HOST') do
+        ENV.fetch('APP_HOST') do
+          Rails.application.config.action_controller.asset_host ||
+            Rails.application.routes.default_url_options[:host] ||
+            'http://localhost:3000'
+        end
+      end
+    end
   end
 end
+

app/models/pwb/link.rb

@@ -69,6 +69,37 @@ def as_json(options = nil)
       }.merge(options || {}))
     end
 
+    # API-formatted JSON for frontend consumption
+    # Uses consistent field names matching the frontend contract
+    def as_api_json
+      {
+        "id" => id,
+        "slug" => slug,
+        "title" => link_title,
+        "url" => resolved_url,
+        "position" => placement,
+        "order" => sort_order,
+        "visible" => visible,
+        "external" => is_external || false
+      }
+    end
+
+    # Resolves the URL for this link
+    # Prefers link_url (absolute), falls back to generating from link_path
+    def resolved_url
+      if link_url.present?
+        link_url
+      elsif link_path.present?
+        # Generate a basic path from the route helper name
+        path_name = link_path.gsub('_path', '')
+        "/#{I18n.locale}/#{path_name}"
+      elsif page_slug.present?
+        "/#{I18n.locale}/#{page_slug}"
+      else
+        "#"
+      end
+    end
+
     def admin_attribute_names
       mobility_attribute_names
     end
@@ -84,3 +115,4 @@ def mobility_attribute_names
     end
   end
 end
+

app/models/pwb/listed_property.rb

@@ -226,15 +226,77 @@ def extras_for_display
     def as_json(options = nil)
       super(options).tap do |hash|
         hash['prop_photos'] = prop_photos.map do |photo|
-          if photo.image.attached?
-            { 'image' => Rails.application.routes.url_helpers.rails_blob_path(photo.image, only_path: true) }
-          else
-            { 'image' => nil }
-          end
-        end
+          serialize_photo(photo)
+        end.compact
         hash['title'] = title
         hash['description'] = description
+        hash['meta_title'] = generate_meta_title
+        hash['meta_description'] = generate_meta_description
+      end
+    end
+
+    private
+
+    def serialize_photo(photo)
+      return nil unless photo.image.attached?
+
+      {
+        'id' => photo.id,
+        'url' => absolute_image_url(photo.image),
+        'alt' => photo.respond_to?(:caption) ? photo.caption.presence : nil,
+        'position' => photo.sort_order,
+        'variants' => generate_image_variants(photo.image)
+      }
+    end
+
+    def absolute_image_url(image)
+      Rails.application.routes.url_helpers.rails_blob_url(
+        image,
+        host: resolve_asset_host
+      )
+    rescue StandardError => e
+      Rails.logger.warn("Failed to generate absolute image URL: #{e.message}")
+      nil
+    end
+
+    def generate_image_variants(image)
+      return {} unless image.variable?
+
+      {
+        'small' => variant_url(image, resize_to_limit: [300, 200]),
+        'medium' => variant_url(image, resize_to_limit: [600, 400]),
+        'large' => variant_url(image, resize_to_limit: [1200, 800])
+      }
+    rescue StandardError => e
+      Rails.logger.warn("Failed to generate image variants: #{e.message}")
+      {}
+    end
+
+    def variant_url(image, transformations)
+      Rails.application.routes.url_helpers.rails_representation_url(
+        image.variant(transformations).processed,
+        host: resolve_asset_host
+      )
+    rescue StandardError
+      nil
+    end
+
+    def resolve_asset_host
+      ENV.fetch('ASSET_HOST') do
+        ENV.fetch('APP_HOST') do
+          Rails.application.config.action_controller.asset_host ||
+            Rails.application.routes.default_url_options[:host] ||
+            'http://localhost:3000'
+        end
       end
     end
+
+    def generate_meta_title
+      title.presence || "Property #{reference}"
+    end
+
+    def generate_meta_description
+      description&.truncate(160)
+    end
   end
 end

app/models/pwb/website.rb

@@ -353,13 +353,63 @@ def as_json(options = nil)
         "company_display_name", "theme_name",
         "default_area_unit", "default_client_locale",
         "available_currencies", "default_currency",
-        "supported_locales", "social_media",
-        "raw_css", "analytics_id", "analytics_id_type",
-        "sale_price_options_from", "sale_price_options_till",
-        "rent_price_options_from", "rent_price_options_till",
+        "supported_locales", "dark_mode_setting"
       ],
-              methods: ["style_variables", "admin_page_links", "top_nav_display_links",
-                        "footer_display_links", "agency"] }.merge(options || {}))
+              methods: [
+                "logo_url", "favicon_url",
+                "style_variables", "css_variables",
+                "contact_info", "social_links",
+                "top_nav_links", "footer_links",
+                "agency"
+              ] }.merge(options || {}))
+    end
+
+    # API helper: Returns contact information from agency
+    def contact_info
+      return {} unless agency
+
+      {
+        "phone" => agency.phone_number_primary,
+        "phone_mobile" => agency.phone_number_mobile,
+        "email" => agency.email_primary,
+        "address" => format_agency_address
+      }
+    end
+
+    # API helper: Returns structured social media links
+    def social_links
+      {
+        "facebook" => social_media_facebook,
+        "twitter" => social_media_twitter,
+        "instagram" => social_media_instagram,
+        "linkedin" => social_media_linkedin,
+        "youtube" => social_media_youtube,
+        "whatsapp" => social_media_whatsapp,
+        "pinterest" => social_media_pinterest
+      }.compact
+    end
+
+    # API helper: Returns navigation links formatted for API consumption
+    def top_nav_links
+      links.ordered_visible_top_nav.map(&:as_api_json)
+    end
+
+    # API helper: Returns footer links formatted for API consumption
+    def footer_links
+      links.ordered_visible_footer.map(&:as_api_json)
+    end
+
+    private
+
+    def format_agency_address
+      return nil unless agency&.primary_address
+
+      [
+        agency.street_address,
+        agency.city,
+        agency.postal_code
+      ].compact.reject(&:blank?).join(", ")
     end
   end
 end
+

config/routes.rb

@@ -727,6 +727,7 @@
       get "/links" => "links#index"
       get "/site_details" => "site_details#index"
       get "/select_values" => "select_values#index"
+      get "/theme" => "theme#index"
       post "/auth/firebase" => "auth#firebase"
 
       # Embeddable Widget API