test/docs: Add tests and documentation for new API endpoints

Tests:
- search_config_spec.rb (NEW): Tests for /search/config endpoint
- contact_spec.rb (NEW): Tests for /contact general enquiry endpoint
- properties_spec.rb: Added tests for map_markers, pagination meta,
  highlighted filter, limit parameter, and locale support

Documentation:
- docs/api/01_rest_api.md: Added comprehensive Public API section
  documenting all headless frontend endpoints including properties,
  search config, site details, theme, pages, enquiries, contact,
  testimonials with example request/response formats

Author: etewiah

docs/api/01_rest_api.md

@@ -145,6 +145,102 @@ The website endpoint is used to manage the website's configuration.
 
 ---
 
+## Public API (Headless Frontend)
+
+The Public API (`/api_public/v1/`) is designed for headless JavaScript frontends (Astro.js, Next.js, etc.) and does not require authentication.
+
+### Properties
+
+**`GET /api_public/v1/properties`** - Search properties
+
+Query Parameters:
+- `sale_or_rental` - "sale" or "rent"
+- `property_type` - Filter by property type
+- `for_sale_price_from/till` - Price range for sale
+- `for_rent_price_from/till` - Price range for rent
+- `bedrooms_from` - Minimum bedrooms
+- `bathrooms_from` - Minimum bathrooms
+- `highlighted` - "true" to filter featured properties
+- `limit` - Limit results
+- `page` - Page number (default: 1)
+- `per_page` - Results per page (default: 12)
+- `locale` - Locale code
+
+Response:
+```json
+{
+  "data": [...],
+  "map_markers": [{"id": 1, "lat": 41.40, "lng": 2.17, "title": "...", "price": "..."}],
+  "meta": {"total": 100, "page": 1, "per_page": 12, "total_pages": 9}
+}
+```
+
+**`GET /api_public/v1/properties/:id`** - Get property by ID or slug
+
+---
+
+### Search Configuration
+
+**`GET /api_public/v1/search/config`** - Get search filter options
+
+Response:
+```json
+{
+  "property_types": [{"key": "apartment", "label": "Apartment", "count": 15}],
+  "price_options": {"sale": {"from": [...], "to": [...]}, "rent": {...}},
+  "features": [{"key": "has_pool", "label": "Swimming Pool"}],
+  "bedrooms": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+  "bathrooms": [0, 1, 2, 3, 4, 5, 6],
+  "sort_options": [{"value": "price_asc", "label": "Price: Low to High"}]
+}
+```
+
+---
+
+### Site Configuration
+
+**`GET /api_public/v1/site_details`** - Get website configuration
+
+Response includes: `company_display_name`, `theme_name`, `contact_info`, `social_links`, `top_nav_links`, `footer_links`, `agency`
+
+**`GET /api_public/v1/theme`** - Get theme/CSS configuration
+
+Response: `theme_name`, `colors`, `css_variables`, `fonts`, `dark_mode`
+
+---
+
+### Pages & Content
+
+**`GET /api_public/v1/pages/by_slug/:slug`** - Get page content by slug
+
+**`GET /api_public/v1/translations?locale=xx`** - Get all translations for a locale
+
+**`GET /api_public/v1/links?position=top_nav`** - Get navigation links
+
+---
+
+### Forms
+
+**`POST /api_public/v1/enquiries`** - Submit property enquiry
+```json
+{"enquiry": {"name": "...", "email": "...", "phone": "...", "message": "...", "property_id": "..."}}
+```
+
+**`POST /api_public/v1/contact`** - Submit general contact form
+```json
+{"contact": {"name": "...", "email": "...", "phone": "...", "subject": "...", "message": "..."}}
+```
+
+---
+
+### Dynamic Content
+
+**`GET /api_public/v1/testimonials`** - Get testimonials
+
+**`GET /api_public/v1/select_values?field_names=property-types`** - Get select options
+
+---
+
 ## GraphQL API
 
 The GraphQL API provides a more flexible and powerful way to query the application's data.

spec/requests/api_public/v1/contact_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe "ApiPublic::V1::Contact", type: :request do
+  let!(:website) { FactoryBot.create(:pwb_website, subdomain: 'contact-test') }
+  let!(:agency) { website.agency || website.create_agency!(display_name: 'Test Agency', email_primary: 'test@example.com') }
+
+  before do
+    host! 'contact-test.example.com'
+  end
+
+  describe "POST /api_public/v1/contact" do
+    let(:valid_params) do
+      {
+        contact: {
+          name: "John Doe",
+          email: "john@example.com",
+          phone: "+1234567890",
+          subject: "General Inquiry",
+          message: "I would like more information about your services."
+        }
+      }
+    end
+
+    it "creates a contact and message with valid params" do
+      expect {
+        post "/api_public/v1/contact", params: valid_params, as: :json
+      }.to change(Pwb::Contact, :count).by(1)
+        .and change(Pwb::Message, :count).by(1)
+
+      expect(response).to have_http_status(201)
+      json = response.parsed_body
+      expect(json["success"]).to be true
+      expect(json["data"]["contact_id"]).to be_present
+      expect(json["data"]["message_id"]).to be_present
+    end
+
+    it "returns success message" do
+      post "/api_public/v1/contact", params: valid_params, as: :json
+      json = response.parsed_body
+      expect(json["message"]).to be_present
+    end
+
+    it "reuses existing contact by email" do
+      existing_contact = website.contacts.create!(
+        primary_email: "john@example.com",
+        first_name: "Existing"
+      )
+
+      expect {
+        post "/api_public/v1/contact", params: valid_params, as: :json
+      }.to change(Pwb::Contact, :count).by(0)
+        .and change(Pwb::Message, :count).by(1)
+
+      expect(response).to have_http_status(201)
+    end
+
+    it "returns error for missing email" do
+      invalid_params = {
+        contact: {
+          name: "John Doe",
+          message: "Hello"
+        }
+      }
+
+      post "/api_public/v1/contact", params: invalid_params, as: :json
+      # Should either return 422 or handle missing parameter
+      expect(response.status).to be_in([400, 422, 500])
+    end
+
+    it "respects locale parameter" do
+      post "/api_public/v1/contact", params: valid_params.merge(locale: "es"), as: :json
+      expect(response).to have_http_status(201)
+    end
+  end
+end

spec/requests/api_public/v1/properties_spec.rb

@@ -42,5 +42,52 @@
       get "/api_public/v1/properties", params: { sale_or_rental: "sale" }
       expect(response).to have_http_status(200)
     end
+
+    it "returns data in correct structure with meta" do
+      host! 'properties-test.example.com'
+      get "/api_public/v1/properties", params: { sale_or_rental: "sale" }
+      json = response.parsed_body
+      expect(json).to have_key("data")
+      expect(json).to have_key("meta")
+      expect(json["meta"]).to have_key("total")
+      expect(json["meta"]).to have_key("page")
+      expect(json["meta"]).to have_key("per_page")
+      expect(json["meta"]).to have_key("total_pages")
+    end
+
+    it "returns map_markers array" do
+      host! 'properties-test.example.com'
+      get "/api_public/v1/properties", params: { sale_or_rental: "sale" }
+      json = response.parsed_body
+      expect(json).to have_key("map_markers")
+      expect(json["map_markers"]).to be_an(Array)
+    end
+
+    it "supports pagination parameters" do
+      host! 'properties-test.example.com'
+      get "/api_public/v1/properties", params: { sale_or_rental: "sale", page: 1, per_page: 5 }
+      expect(response).to have_http_status(200)
+      json = response.parsed_body
+      expect(json["meta"]["page"]).to eq(1)
+      expect(json["meta"]["per_page"]).to eq(5)
+    end
+
+    it "supports highlighted filter" do
+      host! 'properties-test.example.com'
+      get "/api_public/v1/properties", params: { sale_or_rental: "sale", highlighted: "true" }
+      expect(response).to have_http_status(200)
+    end
+
+    it "supports limit parameter" do
+      host! 'properties-test.example.com'
+      get "/api_public/v1/properties", params: { sale_or_rental: "sale", limit: 3 }
+      expect(response).to have_http_status(200)
+    end
+
+    it "respects locale parameter" do
+      host! 'properties-test.example.com'
+      get "/api_public/v1/properties", params: { sale_or_rental: "sale", locale: "es" }
+      expect(response).to have_http_status(200)
+    end
   end
 end

spec/requests/api_public/v1/search_config_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe "ApiPublic::V1::SearchConfig", type: :request do
+  let!(:website) { FactoryBot.create(:pwb_website, subdomain: 'search-config-test') }
+  let!(:realty_asset) { FactoryBot.create(:pwb_realty_asset, website: website, prop_type_key: 'apartment') }
+  let!(:sale_listing) { FactoryBot.create(:pwb_sale_listing, :visible, realty_asset: realty_asset) }
+
+  before do
+    host! 'search-config-test.example.com'
+    # Refresh the materialized view so properties are visible
+    Pwb::ListedProperty.refresh(concurrently: false)
+  end
+
+  describe "GET /api_public/v1/search/config" do
+    it "returns successful response" do
+      get "/api_public/v1/search/config"
+      expect(response).to have_http_status(200)
+    end
+
+    it "returns property_types array" do
+      get "/api_public/v1/search/config"
+      json = response.parsed_body
+      expect(json).to have_key("property_types")
+      expect(json["property_types"]).to be_an(Array)
+    end
+
+    it "returns price_options with sale and rent" do
+      get "/api_public/v1/search/config"
+      json = response.parsed_body
+      expect(json).to have_key("price_options")
+      expect(json["price_options"]).to have_key("sale")
+      expect(json["price_options"]).to have_key("rent")
+    end
+
+    it "returns bedrooms and bathrooms arrays" do
+      get "/api_public/v1/search/config"
+      json = response.parsed_body
+      expect(json["bedrooms"]).to be_an(Array)
+      expect(json["bathrooms"]).to be_an(Array)
+    end
+
+    it "returns sort_options" do
+      get "/api_public/v1/search/config"
+      json = response.parsed_body
+      expect(json["sort_options"]).to be_an(Array)
+      expect(json["sort_options"].first).to have_key("value")
+      expect(json["sort_options"].first).to have_key("label")
+    end
+
+    it "respects locale parameter" do
+      get "/api_public/v1/search/config", params: { locale: "es" }
+      expect(response).to have_http_status(200)
+    end
+  end
+end