Add Theme and Testimonials API endpoints for Next.js integration

Phase 1: Theme API
- Add GET /api_public/v1/theme endpoint
- Returns complete theme configuration (colors, fonts, border radius, dark mode)
- Provides ready-to-inject CSS variables for Next.js client
- Leverages existing WebsiteStyleable concern and PaletteLoader

Phase 2: Testimonials API
- Add GET /api_public/v1/testimonials endpoint
- Create Pwb::Testimonial model with author, quote, rating, position
- Support query parameters: limit, featured_only, locale
- Multi-tenant scoped to current website
- Add YAML seed files and rake task for data population

Testing:
- Add RSpec tests for both endpoints (11 tests, 100% passing)
- Add FactoryBot factory for testimonials
- Manual verification with curl

Documentation:
- Add implementation plan (1,429 lines)
- Add implementation summary with examples
- Add quick reference guide for developers
- Update CHANGELOG.md

Files created: 13
Files modified: 4
Database tables: pwb_testimonials

All endpoints production-ready and fully tested.

Author: etewiah

CHANGELOG.md

@@ -3,6 +3,17 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+### New Features
+* **Theme API**: New `/api_public/v1/theme` endpoint exposing complete theme configuration including colors, fonts, border radius, dark mode settings, and ready-to-inject CSS variables for Next.js client integration
+* **Testimonials API**: New `/api_public/v1/testimonials` endpoint for dynamic testimonial management with support for featured filtering, limit parameter, and multi-tenant scoping
+* **Testimonials Model**: Added `Pwb::Testimonial` model with author name, role, quote, rating, and position fields, including visibility and featured flags
+* **Testimonials Seeding**: Added YAML seed files and rake task (`pwb:testimonials:seed`) for easy testimonial data population
+
+### API Enhancements
+* Theme endpoint provides complete branding data: palette colors, typography, spacing, and dark mode configuration
+* Testimonials endpoint supports query parameters: `limit`, `featured_only`, and `locale`
+* Both endpoints tested and production-ready for Next.js frontend integration
+
 ### Deprecated
 * **RETS/MLS Integration**: Removed `rets` gem and deprecated MLS integration code. The feature was experimental and never fully implemented. See `docs/claude_thoughts/DEPRECATED_FEATURES.md` for details and alternatives.
 

app/controllers/api_public/v1/testimonials_controller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    # Public API endpoint for testimonials
+    # Returns visible testimonials for display on the website
+    class TestimonialsController < BaseController
+
+      # GET /api_public/v1/testimonials
+      # Returns testimonials for the current website
+      #
+      # Query Parameters:
+      # - locale: optional locale code (e.g., "en", "es")
+      # - limit: max number of testimonials to return (default: all)
+      # - featured_only: if true, only return featured testimonials
+      #
+      # Response:
+      # {
+      #   "testimonials": [
+      #     {
+      #       "id": 1,
+      #       "quote": "Great service!",
+      #       "author_name": "John Doe",
+      #       "author_role": "Buyer",
+      #       "author_photo": "https://...",
+      #       "rating": 5,
+      #       "position": 1
+      #     }
+      #   ]
+      # }
+      def index
+        locale = params[:locale]
+        I18n.locale = locale if locale.present?
+
+        testimonials = Pwb::Current.website.testimonials.visible.ordered
+        testimonials = testimonials.featured if params[:featured_only] == 'true'
+        testimonials = testimonials.limit(params[:limit].to_i) if params[:limit].present?
+
+        render json: {
+          testimonials: testimonials.map(&:as_api_json)
+        }
+      end
+    end
+  end
+end

app/controllers/api_public/v1/theme_controller.rb

@@ -2,35 +2,90 @@
 
 module ApiPublic
   module V1
-    # ThemeController provides theming configuration for headless frontends
-    # Returns CSS variables, colors, and fonts for dynamic theme injection
+    # Public API endpoint for theme configuration
+    # Returns complete theme data including colors, fonts, and CSS
     class ThemeController < BaseController
+
+      # GET /api_public/v1/theme
+      # Returns theme configuration for the current website
+      #
+      # Query Parameters:
+      # - locale: optional locale code (e.g., "en", "es")
+      #
+      # Response:
+      # {
+      #   "theme": {
+      #     "name": "brisbane",
+      #     "palette_id": "ocean_blue",
+      #     "colors": {
+      #       "primary_color": "#3B82F6",
+      #       "secondary_color": "#10B981",
+      #       ...
+      #     },
+      #     "fonts": {
+      #       "heading": "Playfair Display",
+      #       "body": "Inter"
+      #     },
+      #     "dark_mode": {
+      #       "enabled": true,
+      #       "setting": "auto"
+      #     },
+      #     "css_variables": ":root { --primary-color: #3B82F6; ... }"
+      #   }
+      # }
       def index
-        website = Pwb::Current.website
+        locale = params[:locale]
+        I18n.locale = locale if locale.present?
 
+        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
-            }
-          }
+          theme: build_theme_response(website)
         }
       end
 
       private
 
+      def build_theme_response(website)
+        {
+          name: website.theme_name || "default",
+          palette_id: website.effective_palette_id,
+          palette_mode: website.respond_to?(:palette_mode) ? (website.palette_mode || "dynamic") : "dynamic",
+          colors: website.style_variables,
+          fonts: extract_fonts(website),
+          border_radius: extract_border_radius(website),
+          dark_mode: build_dark_mode_config(website),
+          css_variables: website.css_variables_with_dark_mode,
+          custom_css: website.respond_to?(:raw_css) ? website.raw_css : nil
+        }
+      end
+
       def extract_fonts(website)
-        vars = website.style_variables || {}
+        vars = website.style_variables
+        {
+          heading: vars["font_primary"] || vars["font_secondary"] || "Inter",
+          body: vars["font_primary"] || "Inter"
+        }
+      end
+
+      def extract_border_radius(website)
+        vars = website.style_variables
+        base_radius = vars["border_radius"] || "0.5rem"
+        
+        {
+          sm: "calc(#{base_radius} * 0.5)",
+          md: base_radius,
+          lg: "calc(#{base_radius} * 1.5)",
+          xl: "calc(#{base_radius} * 2)"
+        }
+      end
+
+      def build_dark_mode_config(website)
         {
-          primary: vars["font_primary"] || "Open Sans",
-          secondary: vars["font_secondary"] || "Vollkorn"
+          enabled: website.dark_mode_enabled?,
+          setting: website.dark_mode_setting,
+          force_dark: website.force_dark_mode?,
+          auto: website.auto_dark_mode?
         }
       end
     end

app/models/pwb/testimonial.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: pwb_testimonials
+# Database name: primary
+#
+#  id              :bigint           not null, primary key
+#  author_name     :string           not null
+#  author_role     :string
+#  featured        :boolean          default(FALSE), not null
+#  position        :integer          default(0), not null
+#  quote           :text             not null
+#  rating          :integer
+#  visible         :boolean          default(TRUE), not null
+#  created_at      :datetime         not null
+#  updated_at      :datetime         not null
+#  author_photo_id :bigint
+#  website_id      :bigint           not null
+#
+# Indexes
+#
+#  index_pwb_testimonials_on_author_photo_id  (author_photo_id)
+#  index_pwb_testimonials_on_position         (position)
+#  index_pwb_testimonials_on_visible          (visible)
+#  index_pwb_testimonials_on_website_id       (website_id)
+#
+# Foreign Keys
+#
+#  fk_rails_...  (author_photo_id => pwb_media.id)
+#  fk_rails_...  (website_id => pwb_websites.id)
+#
+module Pwb
+  class Testimonial < ApplicationRecord
+    # ===================
+    # Associations
+    # ===================
+    belongs_to :website, class_name: 'Pwb::Website'
+    belongs_to :author_photo, class_name: 'Pwb::Media', optional: true
+
+    # ===================
+    # Validations
+    # ===================
+    validates :author_name, presence: true
+    validates :quote, presence: true, length: { minimum: 10, maximum: 1000 }
+    validates :rating, numericality: { 
+      only_integer: true, 
+      greater_than_or_equal_to: 1, 
+      less_than_or_equal_to: 5 
+    }, allow_nil: true
+    validates :position, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+
+    # ===================
+    # Scopes
+    # ===================
+    scope :visible, -> { where(visible: true) }
+    scope :featured, -> { where(featured: true) }
+    scope :ordered, -> { order(position: :asc, created_at: :desc) }
+
+    # ===================
+    # Instance Methods
+    # ===================
+    
+    def author_photo_url
+      author_photo&.image_url
+    end
+
+    def as_api_json
+      {
+        id: id,
+        quote: quote,
+        author_name: author_name,
+        author_role: author_role,
+        author_photo: author_photo_url,
+        rating: rating,
+        position: position
+      }
+    end
+  end
+end

app/models/pwb/website.rb

@@ -156,6 +156,7 @@ class Website < ApplicationRecord
     has_many :field_keys, class_name: 'Pwb::FieldKey', foreign_key: :pwb_website_id
     has_many :email_templates, class_name: 'Pwb::EmailTemplate', dependent: :destroy
     has_many :shard_audit_logs, class_name: 'Pwb::ShardAuditLog', dependent: :destroy
+    has_many :testimonials, class_name: 'Pwb::Testimonial', dependent: :destroy
 
     # Media Library
     has_many :media, class_name: 'Pwb::Media', dependent: :destroy

config/routes.rb

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

db/migrate/20260110165317_create_pwb_testimonials.rb

@@ -0,0 +1,21 @@
+class CreatePwbTestimonials < ActiveRecord::Migration[8.1]
+  def change
+    create_table :pwb_testimonials do |t|
+      t.string :author_name, null: false
+      t.string :author_role
+      t.text :quote, null: false
+      t.integer :rating
+      t.integer :position, default: 0, null: false
+      t.boolean :visible, default: true, null: false
+      t.boolean :featured, default: false, null: false
+
+      t.references :website, null: false, foreign_key: { to_table: :pwb_websites }
+      t.references :author_photo, foreign_key: { to_table: :pwb_media }
+
+      t.timestamps
+    end
+
+    add_index :pwb_testimonials, :visible
+    add_index :pwb_testimonials, :position
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[8.1].define(version: 2026_01_09_114702) do
+ActiveRecord::Schema[8.1].define(version: 2026_01_10_165317) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "pg_catalog.plpgsql"
   enable_extension "pgcrypto"
@@ -967,6 +967,24 @@
     t.index ["singleton_key"], name: "index_pwb_tenant_settings_on_singleton_key", unique: true
   end
 
+  create_table "pwb_testimonials", force: :cascade do |t|
+    t.string "author_name", null: false
+    t.bigint "author_photo_id"
+    t.string "author_role"
+    t.datetime "created_at", null: false
+    t.boolean "featured", default: false, null: false
+    t.integer "position", default: 0, null: false
+    t.text "quote", null: false
+    t.integer "rating"
+    t.datetime "updated_at", null: false
+    t.boolean "visible", default: true, null: false
+    t.bigint "website_id", null: false
+    t.index ["author_photo_id"], name: "index_pwb_testimonials_on_author_photo_id"
+    t.index ["position"], name: "index_pwb_testimonials_on_position"
+    t.index ["visible"], name: "index_pwb_testimonials_on_visible"
+    t.index ["website_id"], name: "index_pwb_testimonials_on_website_id"
+  end
+
   create_table "pwb_ticket_messages", id: :uuid, default: -> { "gen_random_uuid()" }, force: :cascade do |t|
     t.text "content", null: false
     t.datetime "created_at", null: false
@@ -1360,6 +1378,8 @@
   add_foreign_key "pwb_support_tickets", "pwb_users", column: "assigned_to_id"
   add_foreign_key "pwb_support_tickets", "pwb_users", column: "creator_id"
   add_foreign_key "pwb_support_tickets", "pwb_websites", column: "website_id"
+  add_foreign_key "pwb_testimonials", "pwb_media", column: "author_photo_id"
+  add_foreign_key "pwb_testimonials", "pwb_websites", column: "website_id"
   add_foreign_key "pwb_ticket_messages", "pwb_support_tickets", column: "support_ticket_id"
   add_foreign_key "pwb_ticket_messages", "pwb_users", column: "user_id"
   add_foreign_key "pwb_ticket_messages", "pwb_websites", column: "website_id"

db/yml_seeds/testimonials/testimonial_001.yml

@@ -0,0 +1,7 @@
+author_name: "Sarah Johnson"
+author_role: "Property Buyer"
+quote: "The team helped us find our dream home in record time. Professional, responsive, and genuinely caring about our needs."
+rating: 5
+position: 1
+visible: true
+featured: true

db/yml_seeds/testimonials/testimonial_002.yml

@@ -0,0 +1,7 @@
+author_name: "Michael Chen"
+author_role: "Landlord"
+quote: "Excellent property management service. They handle everything from tenant screening to maintenance, making my life so much easier."
+rating: 5
+position: 2
+visible: true
+featured: true