rails-contact 0.1.13 → 0.1.16

data/docs/CONFIGURATION.md

@@ -0,0 +1,91 @@
+# Configuration reference
+
+Every setting on `Rails::Contact::Configuration`, with its default and what the engine
+does with it. Set them in `config/initializers/rails_contact.rb`:
+
+```ruby
+Rails::Contact.configure do |config|
+  config.search_backend = :database
+  # ...
+end
+```
+
+All settings have defaults, so you only need to list the ones you change.
+
+## Settings
+
+| Setting | Type | Default | Environment variable | Description |
+|---|---|---|---|---|
+| `contact_class_name` | String | `"Rails::Contact::Contact"` | — | Name of the contact model. Informational in the current version — the engine references `Rails::Contact::Contact` directly. |
+| `elasticsearch_url` | String | `"http://127.0.0.1:9200"` | `ELASTICSEARCH_URL` | URL of the Elasticsearch cluster used by the `:elasticsearch` backend. |
+| `search_backend` | Symbol | `:elasticsearch` | — | Search backend. `:elasticsearch` uses Elasticsearch (with a database fallback on error); any other value uses the database backend. |
+| `default_per_page` | Integer | `25` | — | Default page size for search. Capped at 100 per request. |
+| `inherit_host_layout` | Boolean | `true` | — | When `true`, engine pages render inside the host layout named `application`. When `false`, the engine uses its own layout and bundled JavaScript. |
+| `google_sync_enabled` | Boolean | `false` | `RAILS_CONTACT_GOOGLE_SYNC_ENABLED` (in the generated initializer) | Master switch for Google Contacts sync. The sync controller actions and jobs no-op when `false`. |
+| `google_sync_ui_on_index` | Boolean | `true` | — | When `true`, the index renders the gem's Google sync panel partial. Set `false` to supply your own UI. |
+| `google_max_contacts` | Integer | `25_000` | — | Cap on the rolling-window sync. `Contact.sync_window` limits to the newest N contacts by `updated_at`. |
+| `google_token_path` | String | `"tmp/rails_contact_google_token.json"` | `RAILS_CONTACT_GOOGLE_TOKEN_PATH` | Path to the JSON file holding the OAuth access token. `TokenStore` reads the `access_token` key from it. |
+| `google_client_id` | String / nil | `nil` | `GOOGLE_CLIENT_ID` | OAuth client id. Host-facing: a place to keep the value for your own OAuth flow. Not consumed by the engine. |
+| `google_client_secret` | String / nil | `nil` | `GOOGLE_CLIENT_SECRET` | OAuth client secret. Host-facing, not consumed by the engine. |
+| `google_redirect_uri` | String / nil | `nil` | `GOOGLE_REDIRECT_URI` | OAuth redirect URI. Host-facing, not consumed by the engine. |
+| `google_contact_family_name_suffix` | String / nil | `nil` | `RAILS_CONTACT_GOOGLE_CONTACT_FAMILY_NAME_SUFFIX` | Optional suffix appended to `familyName` in Google People payloads only. Not stored on the contact. Blank disables it. |
+| `rolling_window_sort` | Symbol | `:updated_at` | — | Intended sort column for the rolling window. Reserved: the current `sync_window` scope orders by `updated_at, id` and does not read this setting. |
+| `reset_index_on_boot` | Boolean | `false` | — | Reserved: defined but not read by the current engine. |
+| `metadata_filters` | Hash | `{}` | — | Declarative filters over `Contact#metadata`. Database backend only. See below. |
+| `metadata_sorts` | Hash | `{}` | — | Declarative `?sort=` options over numeric metadata. Database backend only. See below. |
+
+Settings marked "reserved" or "not consumed by the engine" are defined on the
+configuration object and safe to set, but the current release does not act on them.
+They are documented here for completeness.
+
+## Metadata filters and sorts
+
+Contacts carry app-specific values in the `metadata` JSON column. `metadata_filters`
+and `metadata_sorts` let the host decide which keys are filterable and sortable. The
+engine then permits the request params, normalizes multi-selects, guards the SQL, and
+applies the filter. These apply to the **database backend only**; the Elasticsearch
+backend ignores them.
+
+```ruby
+Rails::Contact.configure do |config|
+  config.metadata_filters = {
+    # request param name => filter declaration
+    "tier"      => { key: "quality_tier", type: :values, allowed: %w[hot warm standard] },
+    "min_pax"   => { key: "pax",          type: :min_integer },
+    "min_score" => { key: "score",        type: :min_numeric },
+    "vip"       => { key: "tags",         type: :tag, tag: "vip" }
+  }
+  config.metadata_sorts = {
+    "score" => { key: "score" }  # ?sort=score orders by metadata score, highest first
+  }
+end
+```
+
+`key:` is the metadata key to read. It is declared in code, never taken from a request
+param, and must be a plain identifier matching `[a-zA-Z0-9_]+` — anything else raises,
+as a guard against interpolating an unsafe fragment into SQL.
+
+### Filter types
+
+- `:values` — multi-select. Matches when `metadata->>key` equals any selected value.
+  An optional `allowed:` whitelist discards anything outside it. A scalar param (a
+  legacy bookmark such as `?tier=hot`) is coerced to a one-element selection.
+- `:min_integer` / `:min_numeric` — numeric floor. Stored values that are not numbers
+  are filtered out rather than cast, so an imported `"TBD"` cannot raise. `:min_numeric`
+  also accepts decimals.
+- `:tag` — checkbox. Matches when the metadata key (a JSON array) contains `tag:`. The
+  param value `"1"` switches it on.
+- `:exclude` — hides rows whose key equals `value:`. Add `default: :on` to apply the
+  filter even when the request param is absent (first page load, bookmarks); an
+  explicit `"0"` shows everything — built for default-on "hide test data" checkboxes.
+  Rows missing the key always pass, so unclassified data is never hidden.
+
+### Sorts
+
+A metadata sort orders descending, puts non-numeric or missing values last, and breaks
+ties by recency. Only sorts declared in `metadata_sorts` apply — an unknown `?sort=`
+value is ignored.
+
+A metadata sort is dropped while a free-text `q` search is active. The search branch
+runs `SELECT DISTINCT`, and PostgreSQL rejects ordering by an expression that is not in
+the select list, so search results keep recency order.

data/lib/rails/contact/configuration.rb

@@ -6,7 +6,8 @@ module Rails
                     :google_client_id, :google_client_secret, :google_redirect_uri,
                     :google_token_path, :reset_index_on_boot, :default_per_page,
                     :inherit_host_layout,
-                    :google_contact_family_name_suffix
+                    :google_contact_family_name_suffix,
+                    :metadata_filters, :metadata_sorts
 
       def initialize
         @contact_class_name = "Rails::Contact::Contact"
@@ -29,6 +30,39 @@ module Rails
         # importmap/Turbo match the rest of the app. Engine CSS and nested-field JS are still
         # injected from gem templates so behavior does not depend on the engine layout asset tags.
         @inherit_host_layout = true
+        # Declarative filters over Contact#metadata, keyed by the request param
+        # name. The host app decides which metadata keys are filterable; the
+        # engine permits the params, guards the SQL, and applies the filter
+        # (database backend only). Example:
+        #
+        #   config.metadata_filters = {
+        #     "tier"      => { key: "quality_tier", type: :values, allowed: %w[hot warm standard] },
+        #     "min_pax"   => { key: "pax",          type: :min_integer },
+        #     "min_score" => { key: "score",        type: :min_numeric },
+        #     "vip"       => { key: "tags",         type: :tag, tag: "vip" }
+        #   }
+        #
+        # :values      — multi-select; matches metadata->>key IN (...). Optional
+        #                :allowed whitelist discards anything else.
+        # :min_integer — numeric floor over an integer-ish metadata string;
+        #                non-numeric stored values are filtered out, never cast.
+        # :min_numeric — same, but accepts decimals.
+        # :tag         — checkbox; matches when the metadata key (a JSON array)
+        #                contains :tag. Param value "1" switches it on.
+        # :exclude     — hides rows whose key equals :value. Add default: :on
+        #                to apply it even when the param is absent; an
+        #                explicit "0" shows everything. Rows missing the key
+        #                always pass.
+        @metadata_filters = {}
+        # Sort options over numeric metadata, keyed by the ?sort= param value:
+        #
+        #   config.metadata_sorts = { "score" => { key: "score" } }
+        #
+        # Sorts descending, non-numeric values last, ties broken by recency.
+        # Ignored while a free-text q search is active: the search branch runs
+        # SELECT DISTINCT and PostgreSQL rejects ordering by an expression that
+        # is not in the select list, so search results keep recency order.
+        @metadata_sorts = {}
       end
     end
   end

data/lib/rails/contact/search/backends/database.rb

@@ -3,7 +3,22 @@ module Rails
     module Search
       module Backends
         class Database
+          # Cap user input so the LIKE pattern stays bounded; 200 chars covers
+          # any realistic name/email/phone substring.
+          MAX_QUERY_LENGTH = 200
+
+          # Configured metadata keys are interpolated into SQL fragments, so
+          # they must be plain identifiers. This is a foot-gun guard for host
+          # developers, not a user-input path — params never reach the key.
+          METADATA_KEY_FORMAT = /\A[a-zA-Z0-9_]+\z/
+
           def search(query, filters, page:, per_page:)
+            query = sanitize_query(query)
+            # Metadata sort cannot combine with free-text search: the search
+            # branch below runs SELECT DISTINCT, and PostgreSQL rejects ORDER BY
+            # expressions that are not in the select list. Searching means
+            # hunting a specific contact anyway, so q results keep recency order.
+            filters = filters.except("sort") if query.present?
             offset = (page - 1) * per_page
             scope = Contact.includes(:emails, :phones, :labels).recent_first
             scope = apply_filters(scope, filters)
@@ -33,6 +48,16 @@ module Rails
 
           private
 
+          # Escape LIKE metacharacters (% _ \) so a user typing "%" can't widen
+          # the match to every row, and cap length to keep the pattern bounded.
+          # The backend builds raw "%…%" LIKE patterns, so this guard belongs
+          # here — host apps should not have to wrap search() to stay safe.
+          def sanitize_query(query)
+            return query if query.blank?
+
+            ActiveRecord::Base.sanitize_sql_like(query.to_s[0, MAX_QUERY_LENGTH])
+          end
+
           def apply_filters(scope, filters)
             scoped = scope
             scoped = scoped.where(current_city: filters["city"]) if filters["city"].present?
@@ -58,12 +83,133 @@ module Rails
               scoped = scoped.where("metadata->>'contact_created_at' <= ?", filters["contact_created_at_end"])
             end
 
+            # csv_import_id is a multi-select filter: it may be a single id or an
+            # array of ids. region above is already array-safe via where(region_name:),
+            # but this JSON-extraction predicate needs an explicit IN. A single id
+            # yields IN ('5'), identical to the old = '5'.
             if filters["csv_import_id"].present?
-              scoped = scoped.where("metadata->>'csv_import_id' = ?", filters["csv_import_id"].to_s)
+              ids = Array(filters["csv_import_id"]).map(&:to_s).reject(&:blank?)
+              scoped = scoped.where("metadata->>'csv_import_id' IN (?)", ids) if ids.any?
             end
 
+            scoped = apply_metadata_filters(scoped, filters)
+            apply_metadata_sort(scoped, filters["sort"])
+          end
+
+          # Host-configured filters over Contact#metadata — see
+          # Configuration#metadata_filters for the declaration format. Every
+          # stored value came from user data (CSV imports, forms), so numeric
+          # comparisons never cast blindly: non-numeric values are filtered
+          # out by a guard instead of raising.
+          def apply_metadata_filters(scoped, filters)
+            Rails::Contact.configuration.metadata_filters.each do |param, config|
+              value = filters[param.to_s]
+              # A blank param means "not filtering" — except for default-on
+              # filters (config default: :on), which apply until the user
+              # explicitly switches them off with a false-y value ("0").
+              next if value.blank? && config[:default] != :on
+
+              key = metadata_key!(config.fetch(:key))
+              scoped = case config.fetch(:type)
+              when :values      then apply_values_filter(scoped, key, value, config[:allowed])
+              when :min_integer then apply_min_filter(scoped, key, value, decimals: false)
+              when :min_numeric then apply_min_filter(scoped, key, value, decimals: true)
+              when :tag         then apply_tag_filter(scoped, key, value, config.fetch(:tag))
+              when :exclude     then apply_exclude_filter(scoped, key, value, config.fetch(:value))
+              else
+                raise ArgumentError, "unknown metadata filter type #{config[:type].inspect} for #{param.inspect}"
+              end
+            end
             scoped
           end
+
+          def apply_values_filter(scoped, key, value, allowed)
+            values = Array(value).map(&:to_s).reject(&:blank?)
+            values &= allowed.map(&:to_s) if allowed
+            return scoped if values.empty?
+
+            scoped.where("metadata->>'#{key}' IN (?)", values)
+          end
+
+          def apply_min_filter(scoped, key, value, decimals:)
+            floor = decimals ? value.to_f : value.to_i
+            return scoped unless floor.positive?
+
+            if postgres?(scoped)
+              # {0,1} instead of the ? quantifier: Rails' bind sanitizer counts
+              # every literal ? in the fragment as a placeholder, even inside a
+              # quoted regex.
+              pattern = decimals ? "^[0-9]+(\\.[0-9]+){0,1}$" : "^[0-9]+$"
+              cast = decimals ? "numeric" : "int"
+              scoped.where("metadata->>'#{key}' ~ '#{pattern}' AND (metadata->>'#{key}')::#{cast} >= ?", floor)
+            else
+              # SQLite (test harness): CAST never raises — junk casts to 0,
+              # which a positive floor excludes on its own.
+              scoped.where("CAST(metadata->>'#{key}' AS REAL) >= ?", floor)
+            end
+          end
+
+          def apply_tag_filter(scoped, key, value, tag)
+            return scoped unless ActiveModel::Type::Boolean.new.cast(value)
+
+            if postgres?(scoped)
+              scoped.where("metadata->'#{key}' @> ?", [ tag ].to_json)
+            else
+              scoped.where(
+                "EXISTS (SELECT 1 FROM json_each(rails_contact_contacts.metadata, '$.#{key}') WHERE json_each.value = ?)",
+                tag
+              )
+            end
+          end
+
+          # Hide rows whose metadata key equals the configured value. Built
+          # for default-on filters (\"hide test data\"): a nil param arrives
+          # here only when the config says default: :on, and nil casts to
+          # nil (not false), so the exclusion applies; an explicit "0"
+          # switches it off. Rows MISSING the key must pass — unclassified
+          # legacy data is not test data.
+          def apply_exclude_filter(scoped, key, value, excluded)
+            return scoped if value.present? && ActiveModel::Type::Boolean.new.cast(value) == false
+
+            if postgres?(scoped)
+              scoped.where("metadata->>'#{key}' IS DISTINCT FROM ?", excluded.to_s)
+            else
+              # SQLite (test harness): IS DISTINCT FROM needs 3.39+.
+              scoped.where("COALESCE(metadata->>'#{key}', '') <> ?", excluded.to_s)
+            end
+          end
+
+          # Descending sort over a numeric metadata key; rows with a
+          # non-numeric or missing value sink to the bottom, recency breaks
+          # ties. Only sorts declared in Configuration#metadata_sorts apply —
+          # an unknown ?sort= value is ignored.
+          def apply_metadata_sort(scoped, sort_param)
+            sort = Rails::Contact.configuration.metadata_sorts[sort_param.to_s]
+            return scoped unless sort
+
+            key = metadata_key!(sort.fetch(:key))
+            order = if postgres?(scoped)
+              "CASE WHEN metadata->>'#{key}' ~ '^[0-9]+(\\.[0-9]+){0,1}$' " \
+                "THEN (metadata->>'#{key}')::numeric ELSE -1 END DESC, " \
+                "rails_contact_contacts.created_at DESC"
+            else
+              "CAST(metadata->>'#{key}' AS REAL) DESC, rails_contact_contacts.created_at DESC"
+            end
+            scoped.reorder(Arel.sql(order))
+          end
+
+          def metadata_key!(key)
+            key = key.to_s
+            unless METADATA_KEY_FORMAT.match?(key)
+              raise ArgumentError, "metadata filter key #{key.inspect} must match #{METADATA_KEY_FORMAT.inspect}"
+            end
+
+            key
+          end
+
+          def postgres?(scoped)
+            scoped.klass.connection.adapter_name.match?(/postgres/i)
+          end
         end
       end
     end

data/lib/rails/contact/search/backends/elasticsearch.rb

@@ -120,8 +120,8 @@ module Rails
 
           def filter_clauses(filters)
             clauses = []
-            clauses << { term: { current_city: filters["city"] } } if filters["city"].present?
-            clauses << { term: { region_name: filters["region"] } } if filters["region"].present?
+            clauses << match_clause(:current_city, filters["city"]) if filters["city"].present?
+            clauses << match_clause(:region_name, filters["region"]) if filters["region"].present?
             unless filters["starred"].nil?
               starred_value = ActiveModel::Type::Boolean.new.cast(filters["starred"])
               clauses << { term: { starred: starred_value } }
@@ -133,6 +133,12 @@ module Rails
             clauses
           end
 
+          # city and region are multi-select filters: an array uses a `terms`
+          # clause (match any), a single value keeps the scalar `term` clause.
+          def match_clause(field, value)
+            value.is_a?(Array) ? { terms: { field => value } } : { term: { field => value } }
+          end
+
           def document_for(contact)
             {
               id: contact.id,

data/lib/rails/contact/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Contact
-    VERSION = "0.1.13"
+    VERSION = "0.1.16"
   end
 end

data/lib/tasks/rails/contact_tasks.rake

@@ -19,5 +19,4 @@ namespace :rails_contact do
     Rails::Contact::GoogleSyncJob.perform_now
     puts "Google sync completed"
   end
-
 end

data/spec/controllers/contacts_controller_spec.rb

@@ -4,10 +4,67 @@ RSpec.describe Rails::Contact::ContactsController do
   let(:controller) { described_class.new }
 
   describe "private filter params" do
-    it "permits city/region/sync_eligible keys" do
+    it "permits city/sync_eligible and coerces a scalar region to an array" do
       controller.params = ActionController::Parameters.new(city: "Delhi", region: "Europe", sync_eligible: "true", x: "1")
       permitted = controller.send(:filter_params)
-      expect(permitted.to_h).to eq({ "city" => "Delhi", "region" => "Europe", "sync_eligible" => "true" })
+      expect(permitted.to_h).to eq({ "city" => "Delhi", "region" => [ "Europe" ], "sync_eligible" => "true" })
+    end
+
+    it "permits multi-select region[] and csv_import_id[] arrays" do
+      controller.params = ActionController::Parameters.new(region: [ "Europe", "Asia" ], csv_import_id: [ "5", "7" ])
+      permitted = controller.send(:filter_params)
+      expect(permitted.to_h).to eq({ "region" => [ "Europe", "Asia" ], "csv_import_id" => [ "5", "7" ] })
+    end
+
+    it "strips the hidden blank a <select multiple> submits" do
+      controller.params = ActionController::Parameters.new(csv_import_id: [ "", "7" ])
+      permitted = controller.send(:filter_params)
+      expect(permitted.to_h).to eq({ "csv_import_id" => [ "7" ] })
+    end
+
+    it "drops a multi-select key entirely when only blanks are submitted" do
+      controller.params = ActionController::Parameters.new(region: [ "" ])
+      permitted = controller.send(:filter_params)
+      expect(permitted.to_h).to eq({})
+    end
+  end
+
+  describe "configured metadata filter params" do
+    around do |example|
+      config = Rails::Contact.configuration
+      original_filters = config.metadata_filters
+      original_sorts = config.metadata_sorts
+      config.metadata_filters = {
+        "tier" => { key: "quality_tier", type: :values, allowed: %w[hot warm] },
+        "min_pax" => { key: "pax", type: :min_integer }
+      }
+      config.metadata_sorts = { "score" => { key: "score" } }
+      example.run
+    ensure
+      config.metadata_filters = original_filters
+      config.metadata_sorts = original_sorts
+    end
+
+    it "permits configured array, scalar and sort params" do
+      controller.params = ActionController::Parameters.new(
+        tier: [ "hot" ], min_pax: "4", sort: "score", unrelated: "x"
+      )
+      permitted = controller.send(:filter_params)
+      expect(permitted.to_h).to eq({ "tier" => [ "hot" ], "min_pax" => "4", "sort" => "score" })
+    end
+
+    it "normalizes configured multi-selects like region (scalar coercion + blank strip)" do
+      controller.params = ActionController::Parameters.new(tier: "warm")
+      expect(controller.send(:filter_params).to_h).to eq({ "tier" => [ "warm" ] })
+
+      controller.params = ActionController::Parameters.new(tier: [ "" ])
+      expect(controller.send(:filter_params).to_h).to eq({})
+    end
+
+    it "does not permit sort when no metadata sorts are configured" do
+      Rails::Contact.configuration.metadata_sorts = {}
+      controller.params = ActionController::Parameters.new(sort: "score")
+      expect(controller.send(:filter_params).to_h).to eq({})
     end
   end
 

data/spec/search/database_backend_spec.rb

@@ -0,0 +1,49 @@
+require "rails_helper"
+
+RSpec.describe Rails::Contact::Search::Backends::Database do
+  # metadata is a text column read back through JSON.parse, so store JSON for
+  # the SQL `metadata->>'csv_import_id'` extraction to resolve.
+  def make(name, import_id)
+    create(:rails_contact_contact, given_name: name, metadata: { "csv_import_id" => import_id }.to_json)
+  end
+
+  let!(:alice) { make("Alice", "imp_1") }
+  let!(:bob)   { make("Bob", "imp_2") }
+  let!(:carol) { make("Carol", "imp_3") }
+
+  def records(filters)
+    described_class.new.search("", filters, page: 1, per_page: 25).records
+  end
+
+  describe "csv_import_id filter (multi-select)" do
+    it "matches contacts across every selected import (array -> IN)" do
+      expect(records("csv_import_id" => [ "imp_1", "imp_2" ])).to match_array([ alice, bob ])
+    end
+
+    it "matches a single import exactly as before (scalar)" do
+      expect(records("csv_import_id" => "imp_1")).to match_array([ alice ])
+    end
+
+    it "applies no constraint when the selection is blank only" do
+      expect(records("csv_import_id" => [ "" ])).to match_array([ alice, bob, carol ])
+    end
+  end
+
+  describe "query sanitization" do
+    def search_for(query)
+      described_class.new.search(query, {}, page: 1, per_page: 25).records
+    end
+
+    it "treats % as a literal, not a match-everything wildcard" do
+      expect(search_for("%")).to be_empty
+    end
+
+    it "still matches a real substring" do
+      expect(search_for("Ali")).to include(alice)
+    end
+
+    it "does not blow up on pathologically long input" do
+      expect { search_for("a" * 1000) }.not_to raise_error
+    end
+  end
+end

data/spec/search/elasticsearch_backend_spec.rb

@@ -0,0 +1,33 @@
+require "rails_helper"
+
+RSpec.describe Rails::Contact::Search::Backends::Elasticsearch do
+  # Captures the query body so we can assert filter-clause shape without a real
+  # Elasticsearch server. Returns an empty hit set so #search resolves cleanly.
+  let(:captured) { {} }
+  let(:client) do
+    cap = captured
+    Class.new do
+      define_method(:initialize) { cap }
+      define_method(:search) do |index:, body:|
+        cap[:index] = index
+        cap[:body]  = body
+        { "hits" => { "total" => { "value" => 0 }, "hits" => [] } }
+      end
+    end.new
+  end
+
+  def filter_clauses(filters)
+    described_class.new(client: client).search("", filters, page: 1, per_page: 25)
+    captured[:body][:query][:bool][:filter]
+  end
+
+  it "emits a terms clause for a multi-select region array" do
+    expect(filter_clauses("region" => [ "Europe", "Asia" ]))
+      .to include({ terms: { region_name: [ "Europe", "Asia" ] } })
+  end
+
+  it "emits a scalar term clause for a single city" do
+    expect(filter_clauses("city" => "Delhi"))
+      .to include({ term: { current_city: "Delhi" } })
+  end
+end

data/spec/search/metadata_filters_spec.rb

@@ -0,0 +1,140 @@
+require "rails_helper"
+
+# Host-configured metadata filters + sorts (Configuration#metadata_filters /
+# #metadata_sorts) applied by the database backend. The suite runs on SQLite;
+# the PostgreSQL branches of the SQL are exercised by host applications.
+RSpec.describe Rails::Contact::Search::Backends::Database do
+  around do |example|
+    config = Rails::Contact.configuration
+    original_filters = config.metadata_filters
+    original_sorts = config.metadata_sorts
+    config.metadata_filters = {
+      "tier" => { key: "quality_tier", type: :values, allowed: %w[hot warm standard] },
+      "window" => { key: "booking_window", type: :values },
+      "min_pax" => { key: "pax", type: :min_integer },
+      "min_score" => { key: "score", type: :min_numeric },
+      "vip" => { key: "tags", type: :tag, tag: "vip" },
+      "hide_junk" => { key: "authenticity", type: :exclude, value: "junk", default: :on }
+    }
+    config.metadata_sorts = { "score" => { key: "score" } }
+    example.run
+  ensure
+    config.metadata_filters = original_filters
+    config.metadata_sorts = original_sorts
+  end
+
+  def make(name, meta)
+    create(:rails_contact_contact, given_name: name, metadata: meta.to_json)
+  end
+
+  let!(:hot) do
+    make("Hot", "quality_tier" => "hot", "pax" => "12", "score" => "18.6",
+                "booking_window" => "This week", "tags" => [ "vip" ])
+  end
+  let!(:warm) { make("Warm", "quality_tier" => "warm", "pax" => "2", "score" => "9.1") }
+  let!(:junk) { make("Junk", "quality_tier" => "standard", "pax" => "TBD", "score" => "n/a") }
+
+  def records(filters)
+    described_class.new.search("", filters, page: 1, per_page: 25).records
+  end
+
+  describe ":values filters" do
+    it "matches any of the selected values" do
+      expect(records("tier" => [ "hot", "warm" ])).to match_array([ hot, warm ])
+    end
+
+    it "coerces a scalar like the other multi-selects" do
+      expect(records("tier" => "hot")).to eq([ hot ])
+    end
+
+    it "discards values outside the whitelist" do
+      expect(records("tier" => [ "hot", "'; DROP TABLE--" ])).to eq([ hot ])
+    end
+
+    it "applies no constraint when only junk was submitted" do
+      expect(records("tier" => [ "'; DROP TABLE--" ])).to match_array([ hot, warm, junk ])
+    end
+
+    it "matches free values when no whitelist is configured" do
+      expect(records("window" => [ "This week" ])).to eq([ hot ])
+    end
+  end
+
+  describe ":min_integer / :min_numeric filters" do
+    it "keeps rows at or above the floor and drops non-numeric values" do
+      expect(records("min_pax" => "3")).to eq([ hot ])
+      expect(records("min_pax" => "2")).to match_array([ hot, warm ])
+    end
+
+    it "accepts decimal floors" do
+      expect(records("min_score" => "9.1")).to match_array([ hot, warm ])
+      expect(records("min_score" => "10")).to eq([ hot ])
+    end
+
+    it "ignores a non-positive floor" do
+      expect(records("min_pax" => "0")).to match_array([ hot, warm, junk ])
+      expect(records("min_pax" => "abc")).to match_array([ hot, warm, junk ])
+    end
+  end
+
+  describe ":tag filter" do
+    it "matches contacts whose tag array contains the configured tag" do
+      expect(records("vip" => "1")).to eq([ hot ])
+    end
+
+    it "is inert when the checkbox is off" do
+      expect(records("vip" => "0")).to match_array([ hot, warm, junk ])
+    end
+  end
+
+  describe ":exclude filter (default on)" do
+    let!(:junk) { make("Junk2", "authenticity" => "junk") }
+
+    it "hides the excluded value when the param is ABSENT (default on)" do
+      expect(records({})).not_to include(junk)
+    end
+
+    it "hides when the param is affirmative" do
+      expect(records("hide_junk" => "1")).not_to include(junk)
+    end
+
+    it "shows everything when explicitly disabled with 0" do
+      expect(records("hide_junk" => "0")).to include(junk)
+    end
+
+    it "never hides rows that simply lack the key (unclassified data)" do
+      expect(records({})).to include(hot, warm)
+    end
+  end
+
+  describe "metadata sort" do
+    it "orders by the metadata number descending, junk last" do
+      expect(records("sort" => "score")).to eq([ hot, warm, junk ])
+    end
+
+    it "ignores an unknown sort value" do
+      expect { records("sort" => "bogus") }.not_to raise_error
+    end
+
+    it "drops the sort under a free-text query instead of erroring (DISTINCT branch)" do
+      result = described_class.new.search("Stone", { "sort" => "score" }, page: 1, per_page: 25)
+      expect(result.records).to match_array([ hot, warm, junk ]) # factory family_name
+    end
+  end
+
+  describe "key validation" do
+    it "rejects a config key that is not a plain identifier" do
+      Rails::Contact.configuration.metadata_filters = {
+        "bad" => { key: "x'; DROP", type: :values }
+      }
+      expect { records("bad" => [ "1" ]) }.to raise_error(ArgumentError, /must match/)
+    end
+
+    it "rejects an unknown filter type" do
+      Rails::Contact.configuration.metadata_filters = {
+        "bad" => { key: "x", type: :wat }
+      }
+      expect { records("bad" => "1") }.to raise_error(ArgumentError, /unknown metadata filter type/)
+    end
+  end
+end