rails-contact 0.1.14 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a91f250f66bfd11f808193354a723ffb15cf9d8fefc5a52052bb11c7c7ca54e5
-  data.tar.gz: 18871d517ce8e9a9fca74e1e74ff775d0eab9ca7208d84397f390754f1a6c280
+  metadata.gz: 9a7f0cfd6a248a8763b84379dc244b151d7edc7328527586f0416d378f73e5ee
+  data.tar.gz: 6be4ad0ae1d604fdf9ae66c3f8649573c4d2688ce3b93000bac1723fd08e616c
 SHA512:
-  metadata.gz: 510ec523c32aedbfb1f867f990f06626e07a99a6170fbad9e96ef70cca883a34a097961cd92a4f335737fa77a103d611158e35ccf1a28069daba6e5ced1c4d49
-  data.tar.gz: 8ebc2b2e8a8b28df33bce4f265e4750fa7282ebc37f1208204e1ad8f23b25a178d8b6bb335bc1c3d2f458d6a7d586feba392efa75e60612484c3b0205f9d8d14
+  metadata.gz: c5b66c49e8c489d4565177a34ae71f210c1ccd8c4c36260aed0ef302e2a00ee766ac0c546f943c0f96bc2a843b3ba9c0a05b92518001487cae5a6f14de058714
+  data.tar.gz: e133e1d5768a619f4a33c7a5d5033351358a5a0490d1f387c52730406e1e5b30eead92ed25f48928f01beba7262ab476300dac959571cc5263d1d0ea7e29762f

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.16
+
+- **New metadata filter type `:exclude`** — hides rows whose metadata key equals a configured value, e.g. `{ key: "authenticity", type: :exclude, value: "test", default: :on }`. With `default: :on` the filter applies even when the request param is absent (first page load, bookmarks) and an explicit false-y value (`"0"`) switches it off — built for default-on "hide test data" checkboxes. Rows missing the key always pass, so unclassified legacy data is never hidden.
+
+## [Unreleased]
+
+### Documentation
+
+- Rewrote the README with a badge row, table of contents, requirements, a
+  gem-name/require/namespace note, and usage sections for search, Google sync,
+  merge, and metadata filters.
+- Added `docs/CONFIGURATION.md` with the full settings reference (type, default,
+  environment variable, and behavior for every configuration option).
+- Added `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md`.
+- Removed the duplicate `LICENSE.txt` (identical to `MIT-LICENSE`) and dropped it
+  from the gemspec file list; removed committed `.gem` build artifacts.
+
+## 0.1.15
+
+- **Host-configurable metadata filters and sorts.** `config.metadata_filters` declares filters over `Contact#metadata` by param name — `:values` (multi-select with optional whitelist), `:min_integer` / `:min_numeric` (numeric floors that filter out non-numeric stored values instead of casting them), and `:tag` (JSON-array containment checkbox). `config.metadata_sorts` declares `?sort=` options over numeric metadata (descending, non-numeric last, recency tiebreak). `filter_params` permits the configured params automatically, multi-selects get the same blank-strip/scalar-coercion normalization as `region`, and a metadata sort is dropped while a free-text `q` search is active (the search branch runs `SELECT DISTINCT`, which PostgreSQL cannot order by an out-of-select expression). Database backend only. Configured keys must be plain identifiers; anything else raises.
+
 ## 0.1.14
 
 - Contacts index filters: **`region` and `csv_import_id` are now multi-select**. `filter_params` permits `region: []` / `csv_import_id: []`, strips the hidden blank a `<select multiple>` submits, and coerces a legacy scalar (`?region=Europe`) to a one-element array. The database backend matches `metadata->>'csv_import_id' IN (...)` across the selected imports (a single id behaves exactly as before); `region` was already array-safe via `where(region_name:)`.

data/README.md

@@ -1,196 +1,444 @@
 # rails-contact
 
-`rails-contact` is a mountable Rails engine for Google-Contacts-style contact management.
-
-It provides:
-
-- rich contact profile fields
-- multi-value contact methods (emails/phones/addresses/websites/events)
-- labels/tags
-- dynamic add/remove nested rows
-- Elasticsearch-backed search with DB fallback
-- Google sync scaffolding
-- merge and bulk-delete operations
-- Devise-style override generators
-
----
-
-## Quickstart
-
-### 1) Add gem
+Google-shaped contacts for Rails: contact CRUD, Elasticsearch-backed search, and optional capped Google Contacts sync.
+
+[![Gem Version](https://img.shields.io/gem/v/rails-contact.svg)](https://rubygems.org/gems/rails-contact)
+[![CI](https://github.com/kshtzkr/rails-contact/actions/workflows/ci.yml/badge.svg)](https://github.com/kshtzkr/rails-contact/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](MIT-LICENSE)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-cc342d.svg)](https://www.ruby-lang.org)
+
+`rails-contact` is a mountable Rails engine that adds a contacts section to a host
+application. It models contacts the way Google Contacts does: rich name fields plus
+many emails, phones, addresses, websites, and events per person, with labels and a
+free-form `metadata` JSON column for host-specific data. Search runs through
+Elasticsearch and falls back to a plain SQL query when Elasticsearch is unavailable.
+An optional feature pushes contacts to Google Contacts through the People API, bounded
+by a configurable cap so a large table never syncs unbounded.
+
+## Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Names and namespaces](#names-and-namespaces)
+- [Quick start](#quick-start)
+- [Usage](#usage)
+  - [Contacts and the UI](#contacts-and-the-ui)
+  - [Search](#search)
+  - [Google Contacts sync](#google-contacts-sync)
+  - [Merge and bulk delete](#merge-and-bulk-delete)
+  - [Metadata filters and sorts](#metadata-filters-and-sorts)
+  - [Host layout and asset injection](#host-layout-and-asset-injection)
+- [Configuration](#configuration)
+- [Generators](#generators)
+- [Rake tasks](#rake-tasks)
+- [Routes](#routes)
+- [Testing](#testing)
+- [Development](#development)
+- [Releasing](#releasing)
+- [Contributing](#contributing)
+- [Security](#security)
+- [Versioning and changelog](#versioning-and-changelog)
+- [Related docs](#related-docs)
+- [License](#license)
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.1 (this is a mountable engine; it runs inside a host Rails app)
+- PostgreSQL for the host database. The database search backend uses PostgreSQL
+  JSON operators (`metadata->>'key'`) and a regex cast for numeric metadata; the
+  test suite runs on SQLite, which the backend also handles.
+- Elasticsearch 8.13+ if you use the default `:elasticsearch` search backend. It
+  is optional: set `search_backend = :database` to skip it, and even with the
+  Elasticsearch backend selected, search falls back to SQL when the cluster is
+  unreachable.
+- A Google OAuth access token with People API access if you enable Google sync
+  (see [Google Contacts sync](#google-contacts-sync)).
+
+## Installation
+
+Add the gem to the host application's `Gemfile`:
 
 ```ruby
-gem "rails-contact", "~> 0.1.4"
+gem "rails-contact"
 ```
 
+Install it:
+
 ```bash
 bundle install
 ```
 
-### 2) Install and generate schema
+Generate the initializer, migrations, and route mount, then migrate:
 
 ```bash
-rails generate rails:contact:install
 rails generate rails:contact:contact Contact
 rails db:migrate
 ```
 
-### 3) Mount engine routes
+`rails:contact:contact` invokes the install generator (which writes
+`config/initializers/rails_contact.rb` and mounts the engine) and copies the eight
+migrations for contacts and their associated tables. See [Generators](#generators)
+for the individual generators if you want finer control.
+
+## Names and namespaces
+
+The gem name and the code namespace differ, which trips up most first installs:
+
+| What | Value |
+|---|---|
+| Gem name (Gemfile, RubyGems) | `rails-contact` |
+| Require path | `rails/contact` (`require "rails/contact"`) |
+| Ruby namespace | `Rails::Contact` |
+| Engine class | `Rails::Contact::Engine` |
+| Generator namespace | `rails:contact:*` |
+
+Bundler auto-requires the gem, so a plain `gem "rails-contact"` is enough — you do
+not normally call `require` yourself. If you do, the path is `rails/contact`, not
+`rails-contact` or `rails_contact`. Configuration and models live under the
+`Rails::Contact` namespace.
+
+## Quick start
+
+After installing (above), the engine is mounted at `/contacts`. Start the app and
+visit:
+
+- `/contacts` — searchable, paginated list
+- `/contacts/new` — create form with dynamic add/remove rows
+- `/contacts/:id` — contact detail
+
+Create a contact in code:
 
 ```ruby
-rails_contact_for :contacts
+contact = Rails::Contact::Contact.create!(
+  given_name: "Ada",
+  family_name: "Lovelace",
+  emails_attributes: [{ value: "ada@example.com", label: "work", primary: true }],
+  phones_attributes: [{ value: "+1 555 0100", label: "mobile" }]
+)
+
+contact.full_name       # => "Ada Lovelace"
+contact.primary_email    # => the primary ContactEmail
+contact.set_labels_from_csv!("vip, investor")
 ```
 
-or explicit mount:
+`given_name` is the only required field. Search the index the UI uses:
 
 ```ruby
-mount Rails::Contact::Engine => "/contacts", as: "rails_contact"
+result = Rails::Contact::Search::Query.new("ada", page: 1).call
+result.records      # => [contact, ...]
+result.total_count  # => 1
+result.total_pages  # => 1
 ```
 
-`rails_contact_for :contact` is auto-normalized to `/contacts`.
+## Usage
 
-### 4) Visit UI
+### Contacts and the UI
 
-- `/contacts`
-- `/contacts/new`
-- `/contacts/:id`
+`Rails::Contact::Contact` has the scalar fields `given_name`, `family_name`,
+`current_city`, `departure_city`, `region_name`, `biography`, `starred`,
+`sync_eligible`, `photo_url`, and a `metadata` JSON column. It has many `emails`,
+`phones`, `addresses`, `websites`, `events`, and `labels`. Nested attributes are
+accepted for the first five, with `allow_destroy: true`, so the generated form can
+add and remove rows client-side.
 
-### Host layout and importmap
+The mounted controller (`Rails::Contact::ContactsController`) serves the standard
+seven actions plus `bulk_destroy`, `merge`, `google_sync_unsynced`, and
+`google_sync_rolling_window`. Creating, updating, or deleting a contact enqueues
+`Rails::Contact::IndexContactJob` to keep the Elasticsearch index current.
 
-By default the engine uses your host app layout named `application` so contacts pages match the rest of your UI (including Turbo and importmap). Styles for engine markup are included per page via `stylesheet_link_tag`, and nested “add row” / bulk-selection behavior uses small inline scripts so you do **not** need to pin gem JavaScript in the host importmap.
+Only a fixed set of `metadata` keys is accepted through the form:
+`prefix`, `middle_name`, `suffix`, `nickname`, `company`, `job_title`, `department`,
+`website`, `birthday`, `notes`. Read them back with `contact.meta(:company)`.
 
-To use the engine’s standalone layout and bundled `javascript_include_tag "rails/contact/application"` instead:
+### Search
+
+`Rails::Contact::Search::Query` is the entry point the index action uses. It picks a
+backend from `config.search_backend`, runs the query, and returns a
+`Rails::Contact::Search::Result` (a struct of `records`, `total_count`, `page`,
+`per_page`, and a derived `total_pages`).
+
+```ruby
+Rails::Contact::Search::Query.new(
+  "lovelace",
+  filters: { "city" => "London", "starred" => true },
+  page: 1,
+  per_page: 25
+).call
+```
+
+`per_page` defaults to `config.default_per_page` and is capped at 100.
+
+Two backends implement the same `search(query, filters, page:, per_page:)` contract:
+
+- **Elasticsearch** (`config.search_backend = :elasticsearch`, the default). Queries
+  the `rails_contact_contacts` index with a fuzzy `multi_match` over name, emails,
+  phone (E.164), company, job title, and labels. If any Elasticsearch call raises,
+  it falls back to the database backend for that request. Supported filters: `city`,
+  `region`, `starred`, `sync_eligible` (city and region accept an array for
+  multi-select). Metadata filters and sorts are ignored by this backend.
+- **Database** (`config.search_backend = :database`, or any other value). Runs a
+  `LIKE` query over name, `metadata` company/job title, email value, phone E.164, and
+  label name. The query string is sanitized internally — `LIKE` metacharacters
+  (`% _ \`) are escaped and input is capped at 200 characters — so a user typing `%`
+  cannot widen the match to every row. This backend also supports the date-range,
+  `csv_import_id`, and configured metadata filters and sorts (see below).
+
+Keep the Elasticsearch index in sync with the rake task:
+
+```bash
+rake rails_contact:reindex
+```
+
+It creates the index if needed and reindexes every contact.
+
+### Google Contacts sync
+
+Sync is off by default. It pushes local contacts to Google Contacts through the
+People API (`https://people.googleapis.com/v1`): new contacts are created, contacts
+already linked to a Google record are updated, and Google's `resourceName` and `etag`
+are stored back on the contact so later updates target the right remote record.
+
+Enable it and provide credentials in `config/initializers/rails_contact.rb`:
 
 ```ruby
 Rails::Contact.configure do |config|
-  config.inherit_host_layout = false
+  config.google_sync_enabled = true
+  config.google_max_contacts = 25_000
+  config.google_token_path   = "tmp/rails_contact_google_token.json"
 end
 ```
 
----
+Authentication uses an OAuth access token, not the client credentials directly. The
+engine reads the token from a JSON file at `google_token_path`:
 
-## Generators
+```json
+{ "access_token": "ya29...." }
+```
+
+Your host application is responsible for the OAuth flow (request a scope such as
+`https://www.googleapis.com/auth/contacts`) and for writing that file. The
+`google_client_id`, `google_client_secret`, and `google_redirect_uri` settings are
+provided as a place to keep those values for your own flow; the engine itself does
+not consume them. `Rails::Contact::Google::TokenStore#write!(payload)` is available
+to persist the token JSON once you have it. The engine adds
+`google_access_token`, `google_refresh_token`, and `authorization` to Rails'
+filtered parameters so tokens do not appear in logs.
+
+**The cap.** `google_max_contacts` (default 25,000) bounds a rolling-window sync.
+`Contact.sync_window` is `recent_first.limit(google_max_contacts)`, ordered by
+`updated_at` then `id` descending, so a rolling sync only ever pushes the most
+recently updated N contacts. Contacts that fall outside that window are not touched
+by the rolling job.
+
+Two operations exist:
+
+| Operation | Job | Scope |
+|---|---|---|
+| Rolling window | `GoogleSyncJob` (`SyncService#sync!`) | the newest `google_max_contacts` contacts (create + update) |
+| Unsynced only | `GoogleSyncUnsyncedJob` (`SyncService#sync_unsynced!`) | contacts with no `google_resource_name`, in batches of 100, uncapped |
+
+Trigger them from the UI (the buttons on the index, when sync is enabled), by
+enqueuing the jobs, or through rake:
 
 ```bash
-rails generate rails:contact:install
-rails generate rails:contact:contact Contact
-rails generate rails:contact:views
-rails generate rails:contact:controllers
+rake rails_contact:sync_google   # runs GoogleSyncJob.perform_now
 ```
 
-- `views` copies templates so host apps can customize UI.
-- `controllers` copies an override-ready contacts controller.
-
----
+The index action posts to `google_sync_rolling_window_contacts_path` and
+`google_sync_unsynced_contacts_path`, which enqueue the two jobs. Both the controller
+actions and the jobs no-op unless `google_sync_enabled` is true.
 
-## Feature map
+### Merge and bulk delete
 
-### Core profile fields
+`POST /merge` with `source_id` and `target_id` runs
+`Rails::Contact::MergeContactsService`, which folds the source contact into the
+target inside a transaction: scalar fields fill blanks on the target, nested records
+(emails, phones, addresses, websites, events) are copied when not already present,
+labels are unioned, metadata is merged (target wins on key conflicts), and the source
+is destroyed. Merging a contact into itself raises.
 
-- Prefix, first, middle, last, suffix, nickname
-- Company, job title, department
-- Labels (comma-separated input)
-- Notes and metadata
-- Starred flag
-- Photo URL
+`POST /bulk_destroy` with a comma-separated `ids` param deletes the selected contacts.
 
-### Multi-value sections (dynamic)
+### Metadata filters and sorts
 
-- Emails
-- Phones
-- Addresses
-- Websites
-- Events (birthday/custom)
+Contacts carry app-specific values in the `metadata` JSON column. You declare which
+keys are filterable and sortable, and the engine permits the params, normalizes
+multi-selects, guards the SQL, and applies the filter (database backend only):
 
-Rows can be added/removed dynamically in form UI.
+```ruby
+Rails::Contact.configure do |config|
+  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" }
+  }
+  config.metadata_sorts = {
+    "score" => { key: "score" }  # ?sort=score orders by metadata score, highest first
+  }
+end
+```
 
-### List/search
+The filter types and the rules that guard them are described in full in
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md#metadata-filters-and-sorts).
 
-- Search by name/email/phone/company/job title/labels
-- Filter by city/region/sync/starred
-- Sort by recent updates
+### Host layout and asset injection
 
-### Actions
+By default the engine renders its pages inside the host layout named `application`, so
+contacts pages match the rest of the app (Turbo and importmap included). Engine CSS is
+pulled into each view with `stylesheet_link_tag`, and the add-row and bulk-selection
+behavior runs from small inline scripts, so you do not have to pin gem JavaScript in
+the host importmap.
 
-- Bulk delete selected contacts
-- Merge source contact into target contact
+To use the engine's own layout and its bundled
+`javascript_include_tag "rails/contact/application"` instead:
 
----
+```ruby
+Rails::Contact.configure do |config|
+  config.inherit_host_layout = false
+end
+```
 
 ## Configuration
 
-Initializer: `config/initializers/rails_contact.rb`
+The install generator writes `config/initializers/rails_contact.rb`. Every setting has
+a default, so the initializer only needs the ones you change. The commonly used
+settings:
 
 ```ruby
 Rails::Contact.configure do |config|
-  config.search_backend = :elasticsearch
-  config.elasticsearch_url = ENV.fetch("ELASTICSEARCH_URL", "http://127.0.0.1:9200")
+  config.search_backend    = :elasticsearch
+  config.elasticsearch_url  = ENV.fetch("ELASTICSEARCH_URL", "http://127.0.0.1:9200")
+  config.default_per_page   = 25
+  config.inherit_host_layout = true
+
   config.google_sync_enabled = false
   config.google_max_contacts = 25_000
-  config.rolling_window_sort = :updated_at
-  # Optional: appended to familyName in Google People API payloads only (blank = unchanged).
-  # config.google_contact_family_name_suffix = "_by_vendor"
-  config.default_per_page = 25
+  config.google_token_path   = "tmp/rails_contact_google_token.json"
 end
 ```
 
-### Google sync UI: gem default vs host override
-
-**Recommendation:** keep the **default panel in the gem** so every app gets working buttons when `google_sync_enabled` is true. You avoid copy-paste and stay aligned with new endpoints.
-
-- The index template renders `rails/contact/_google_sync_panel` when `google_sync_ui_on_index` is **true** (default).
-- **Customize without forking the engine:** add `app/views/rails/contact/_google_sync_panel.html.erb` in the host app; Rails resolves that file instead of the gem’s partial.
-- **Hide the default panel:** set `config.google_sync_ui_on_index = false` and render your own UI anywhere (same `POST` targets below).
-- **Custom index only:** override `rails/contact/index` and `<%= render "rails/contact/google_sync_panel" %>` wherever it fits (e.g. after a CSV upload section).
+The full reference — every setting, its type, default, backing environment variable,
+and what it does — is in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
-Endpoints (used by the default partial):
+## Generators
 
-- `google_sync_rolling_window_contacts_path` — `GoogleSyncJob` (rolling window re-sync).
-- `google_sync_unsynced_contacts_path` — `GoogleSyncUnsyncedJob` (contacts with no `google_resource_name`).
+```bash
+rails generate rails:contact:install      # initializer + engine mount
+rails generate rails:contact:contact NAME # invokes install, then copies migrations
+rails generate rails:contact:controllers  # copy an override-ready contacts controller
+```
 
-`ContactsController#index` sets `@google_contacts_pending_sync` when sync is enabled.
+- `install` writes `config/initializers/rails_contact.rb` and adds
+  `mount Rails::Contact::Engine => '/contacts', as: 'rails_contact'` to your routes.
+- `contact` runs `install` and copies the eight migrations (contacts, emails, phones,
+  addresses, websites, events, labels, contact_labels).
+- `controllers` copies an override-ready contacts controller into the host app so you
+  can customize it, Devise-style.
 
----
+A `rails:contact:views` generator is also defined, but it currently copies from
+`app/views/rails/contact/contacts`, a directory the engine no longer uses (its views
+live directly under `app/views/rails/contact`), so it does not copy the current
+templates. To customize views today, copy the files from
+`app/views/rails/contact/` in the gem into the same path in your app.
 
 ## Rake tasks
 
 ```bash
-rake rails_contact:reindex
-rake rails_contact:sync_google
+rake rails_contact:reindex      # create the Elasticsearch index and reindex all contacts
+rake rails_contact:sync_google  # run GoogleSyncJob.perform_now (rolling-window sync)
+rake rails_contact:install      # prints the install generator command
 ```
 
----
+## Routes
 
-## Testing and coverage
+Mounting adds these routes under the mount path (`/contacts` by default):
 
-RSpec is the primary framework.
+| Method | Path | Action |
+|---|---|---|
+| GET | `/` | `index` |
+| GET | `/new` | `new` |
+| POST | `/` | `create` |
+| GET | `/:id` | `show` |
+| GET | `/:id/edit` | `edit` |
+| PATCH/PUT | `/:id` | `update` |
+| DELETE | `/:id` | `destroy` |
+| POST | `/bulk_destroy` | `bulk_destroy` |
+| POST | `/merge` | `merge` |
+| POST | `/google_sync_unsynced` | `google_sync_unsynced` |
+| POST | `/google_sync_rolling_window` | `google_sync_rolling_window` |
+
+You can mount explicitly or use the routing helper, which normalizes a singular or
+plural resource name to the plural path:
+
+```ruby
+# config/routes.rb
+mount Rails::Contact::Engine => "/contacts", as: "rails_contact"
+# or, equivalently:
+rails_contact_for :contacts   # rails_contact_for :contact also mounts at /contacts
+```
+
+`rails_contact_for` accepts an `at:` path and an `as:` name if you want to override
+the defaults.
+
+## Testing
+
+The suite is RSpec, with SimpleCov enforcing line and branch coverage in CI:
 
 ```bash
 bundle exec rspec
 ```
 
-Coverage is enforced with SimpleCov:
+CI (`.github/workflows/ci.yml`) runs RuboCop and the specs against Ruby 3.2 and 3.3
+with an Elasticsearch 8.13 service. A smaller Minitest suite under `test/` covers the
+Google client and sync service.
 
-- 100% line coverage target
-- 100% branch coverage target
-- CI fails below thresholds
+## Development
 
----
+```bash
+git clone https://github.com/kshtzkr/rails-contact.git
+cd rails-contact
+bundle install
+bundle exec rspec        # run the tests
+bin/rubocop              # lint
+```
+
+## Releasing
 
-## Release
+Releases go to RubyGems with the standard Bundler gem tasks:
 
 ```bash
 bundle exec rake build
 bundle exec rake release
 ```
 
-RubyGems MFA is required for push.
+RubyGems MFA is required to push (`rubygems_mfa_required` is set in the gemspec).
+
+## Contributing
+
+Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+setup, the branch and PR flow, and the commit-message convention. This project follows
+the [Contributor Covenant](CODE_OF_CONDUCT.md) code of conduct.
+
+## Security
+
+Please report security issues privately rather than opening a public issue. See
+[SECURITY.md](SECURITY.md).
+
+## Versioning and changelog
+
+`rails-contact` follows [Semantic Versioning](https://semver.org). Notable changes are
+recorded in [CHANGELOG.md](CHANGELOG.md).
+
+## Related docs
 
----
+- [docs/CONFIGURATION.md](docs/CONFIGURATION.md) — full configuration reference
+- [docs/migration_guide.md](docs/migration_guide.md) — upgrading across the breaking rewrite
+- [docs/parity_matrix.md](docs/parity_matrix.md) — feature parity against Google Contacts
+- [docs/product_decisions.md](docs/product_decisions.md) — design decisions
+- [docs/roadmap.md](docs/roadmap.md) — planned work
 
-## Extended docs
+## License
 
-- `docs/parity_matrix.md`
-- `docs/product_decisions.md`
-- `docs/roadmap.md`
-- `docs/migration_guide.md`
+Released under the [MIT License](MIT-LICENSE).

data/app/controllers/rails/contact/contacts_controller.rb

@@ -127,6 +127,14 @@ module Rails
       end
 
       def filter_params
+        config = Rails::Contact.configuration
+        # Host-configured metadata filters: :values filters arrive as
+        # multi-selects (arrays), every other type as a scalar. ?sort= is only
+        # a filter param when the host declared at least one metadata sort.
+        metadata_arrays  = config.metadata_filters.select { |_, f| f[:type] == :values }.keys.map(&:to_sym)
+        metadata_scalars = config.metadata_filters.reject { |_, f| f[:type] == :values }.keys.map(&:to_sym)
+        metadata_scalars << :sort if config.metadata_sorts.any?
+
         permitted = params.permit(
           :city,
           :sync_eligible,
@@ -135,21 +143,23 @@ module Rails
           :travel_date_end,
           :contact_created_at_start,
           :contact_created_at_end,
+          *metadata_scalars,
           region: [],
-          csv_import_id: []
+          csv_import_id: [],
+          **metadata_arrays.index_with { [] }
         )
 
-        normalize_multi_select!(permitted, :region)
-        normalize_multi_select!(permitted, :csv_import_id)
+        ([ :region, :csv_import_id ] + metadata_arrays).each { |key| normalize_multi_select!(permitted, key) }
         permitted
       end
 
-      # region and csv_import_id are multi-select filters: a <select multiple>
-      # submits param[] (an array) plus a hidden param[]="" that Rails always
-      # sends, so the blank must be stripped — otherwise IN ('', 'x') matches
-      # every blank-valued row. Legacy bookmarks may still send a scalar
-      # (?region=Europe); coerce those to a one-element array so the search
-      # backend only ever sees an array (or no key at all).
+      # region, csv_import_id and every configured :values metadata filter are
+      # multi-selects: a <select multiple> submits param[] (an array) plus a
+      # hidden param[]="" that Rails always sends, so the blank must be
+      # stripped — otherwise IN ('', 'x') matches every blank-valued row.
+      # Legacy bookmarks may still send a scalar (?region=Europe); coerce those
+      # to a one-element array so the search backend only ever sees an array
+      # (or no key at all).
       def normalize_multi_select!(permitted, key)
         if permitted[key].blank? && params[key].is_a?(String) && params[key].present?
           permitted[key] = [ params[key] ]

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

@@ -7,8 +7,18 @@ module Rails
           # 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)
@@ -82,8 +92,124 @@ module Rails
               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/version.rb

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

data/spec/controllers/contacts_controller_spec.rb

@@ -29,6 +29,45 @@ RSpec.describe Rails::Contact::ContactsController do
     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
+
   describe "association defaults" do
     it "builds default nested associations" do
       contact = Rails::Contact::Contact.new(given_name: "X")

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-contact
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.1.16
 platform: ruby
 authors:
 - Kshitiz Sinha
@@ -106,7 +106,6 @@ files:
 - ".rspec"
 - CHANGELOG.md
 - Gemfile
-- LICENSE.txt
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -151,6 +150,7 @@ files:
 - bin/rails
 - bin/rubocop
 - config/routes.rb
+- docs/CONFIGURATION.md
 - docs/migration_guide.md
 - docs/parity_matrix.md
 - docs/product_decisions.md
@@ -195,6 +195,7 @@ files:
 - spec/rails_helper.rb
 - spec/search/database_backend_spec.rb
 - spec/search/elasticsearch_backend_spec.rb
+- spec/search/metadata_filters_spec.rb
 - spec/services/merge_contacts_service_spec.rb
 - spec/spec_helper.rb
 - spec/views/contact_templates_spec.rb

data/LICENSE.txt

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Kshitiz Sinha
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.