rails-contact 0.1.13 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f494c5d67c2e057d1e12c490eadf40a64137f3fa801a5654b405c642b13e70e
-  data.tar.gz: 5543c60122860c18d71c90428f0d74eabee77d64e8b95270367b707b9ca0d26d
+  metadata.gz: 9a7f0cfd6a248a8763b84379dc244b151d7edc7328527586f0416d378f73e5ee
+  data.tar.gz: 6be4ad0ae1d604fdf9ae66c3f8649573c4d2688ce3b93000bac1723fd08e616c
 SHA512:
-  metadata.gz: 9da8786e7cb36fff8eaa83399d41dd8ed517892dd9ecc2859ab3ef7d964f27f643798dc7bc39ee33f5b73ceef7b72354a5cf1ab5f65d75f9e6bb8edbbfb6e64f
-  data.tar.gz: afa7e5ea14872cd7cd16229d60ada9baac2f2d638c79a16bd18a81831f307d2f3d24a68b25fb4c640fb7f607659d25e8bba727e13d1fddb6f1c69203d9b0fa5e
+  metadata.gz: c5b66c49e8c489d4565177a34ae71f210c1ccd8c4c36260aed0ef302e2a00ee766ac0c546f943c0f96bc2a843b3ba9c0a05b92518001487cae5a6f14de058714
+  data.tar.gz: e133e1d5768a619f4a33c7a5d5033351358a5a0490d1f387c52730406e1e5b30eead92ed25f48928f01beba7262ab476300dac959571cc5263d1d0ea7e29762f

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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:)`.
+- Database backend: **search query is now sanitized internally** — LIKE metacharacters (`% _ \`) are escaped and input is capped at 200 chars, so a user typing `%` can no longer widen the match to every row. Host apps no longer need to wrap `search` to be safe.
+
 ## 0.1.12
 
 - `_google_sync_panel`: render the card whenever `google_sync_ui_on_index`; if `google_sync_enabled` is false, show short instructions instead of hiding the section entirely.

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,7 +127,47 @@ module Rails
       end
 
       def filter_params
-        params.permit(:city, :region, :sync_eligible, :starred, :travel_date_start, :travel_date_end, :contact_created_at_start, :contact_created_at_end, :csv_import_id)
+        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,
+          :starred,
+          :travel_date_start,
+          :travel_date_end,
+          :contact_created_at_start,
+          :contact_created_at_end,
+          *metadata_scalars,
+          region: [],
+          csv_import_id: [],
+          **metadata_arrays.index_with { [] }
+        )
+
+        ([ :region, :csv_import_id ] + metadata_arrays).each { |key| normalize_multi_select!(permitted, key) }
+        permitted
+      end
+
+      # 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] ]
+        end
+        return unless permitted[key].is_a?(Array)
+
+        permitted[key] = permitted[key].reject(&:blank?)
+        permitted.delete(key) if permitted[key].empty?
       end
 
       def google_pending_sync_count