pico_phone-rails 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a727b58fa9b03d91f9fed795d5f9b4898c8b6c1d416fa67eed38dc881c8a738a
-  data.tar.gz: 2727b559da6ec1a963f6b12f032aeeb9458eaacb5522e3ee98aabbb289863c28
+  metadata.gz: 0524cbb733d2edc10a4a6f0fcb13197f2853d58f437286c7aea7bf4c30d53092
+  data.tar.gz: b29da13e7d7308a7e4e60fda8be21fbd467a5e138e6d6509ce97a719cac77afd
 SHA512:
-  metadata.gz: f07be21c54bcd8f6f9f054af69875b7993f4428f6ef57a97d57252fcee3b71f540b1bcae6563568823c98960e4894afded9ec2e243178af10c36ff2a3dccca1d
-  data.tar.gz: 5b409b31ddbeaae09328eb1cbf6a98d392ad9cce01d5e047198c96149c6e985b9125baaa02c3557decbd1baacb6fc55e492203f9b9a76becd9386162474bad79
+  metadata.gz: c82086362cc5c8dcf692ba712c7a961b076c2d87becfd5d3ff9ccece17d7a1da095558d76748b83ecdee46fc6067c884671d6f681e2b037cf14fb06ffccc9e05
+  data.tar.gz: 0cc7b9175ebdbef5c3cddbabae8fbb8b8705b5cd7a8ffbce7077b4ef46510f895401bd6699105601d8ce13730692f09c513e4503568fe3dd2e17c4850a80bd8f

data/README.md

@@ -2,7 +2,8 @@
 
 Rails integration for [`pico_phone`](https://github.com/gjack/pico_phone): an
 ActiveRecord attribute type, an ActiveModel validator, a before-validation
-normalizer, and an ActiveJob serializer for phone numbers.
+normalizer, free-text phone number extraction, a same-table phone search
+index, and an ActiveJob serializer for phone numbers.
 
 ## Installation
 
@@ -52,6 +53,134 @@ A `before_validation` callback that rewrites the column to E.164 when it parses
 as valid, so formatting noise ("(510) 274-5656") is stripped before the
 validator runs. Pairs naturally with the validator above.
 
+### Extraction
+
+```ruby
+class Note < ApplicationRecord
+  extract_phone_numbers_from :body, region: "US"
+end
+
+note.extracted_phone_numbers    # => [#<PicoPhone::PhoneNumberMatch ...>, ...]
+note.body_with_phones_redacted  # => "Call me at [PHONE] or [PHONE]"
+```
+
+Scans a free-text column (notes, support tickets, chat logs) for phone
+numbers of any format. Both methods re-scan the column live -- nothing is
+persisted. Works without a model too:
+
+```ruby
+PicoPhone::Rails.extract_phone_numbers(text, region: "US")
+PicoPhone::Rails.redact_phone_numbers(text, region: "US", replacement: "[PHONE]")
+```
+
+#### Persisting matches for cross-record search
+
+```
+rails generate pico_phone:rails:extracted_phone_numbers
+rails db:migrate
+```
+
+```ruby
+class Note < ApplicationRecord
+  extract_phone_numbers_from :body, region: "US", persist: true
+end
+
+Note.containing_phone_number("(510) 274-5656")  # matches regardless of stored format
+Note.phone_number_starting_with("(510)")        # matches a locally-formatted prefix
+```
+
+`persist: true` keeps a `pico_phone_rails_extracted_phone_numbers` row in sync
+with the column on every save (only when it actually changes), so
+`containing_phone_number` can find records by E.164 instead of grepping raw
+text -- `"(510) 274-5656"`, `"5102745656"`, and `"+15102745656"` all match the
+same row. `phone_number_starting_with` matches the digits of the number's
+*displayed* national format, so a prefix like `"(510)"` matches the way a
+viewer actually sees/types it. Calling either without having run the
+generator and passed `persist: true` raises
+`PicoPhone::Rails::PersistenceNotEnabled` with instructions, rather than a
+bare "no such table" error.
+
+`region:` also accepts a Symbol (called as an instance method on the record)
+or a Proc (called with the record), for multi-tenant/multi-region apps where
+the correct region varies per record instead of being fixed for the whole
+model:
+
+```ruby
+extract_phone_numbers_from :body, region: ->(note) { note.campus.region }, persist: true
+```
+
+Since there's no single record to resolve a dynamic region against for a
+class-level search, `containing_phone_number` requires an explicit `region:`
+in that case (raising `PicoPhone::Rails::RegionRequired` otherwise):
+
+```ruby
+Note.containing_phone_number("01 23 45 67 89", region: current_organization.region)
+```
+
+### Phone search index
+
+For a table that's already one-row-per-phone-number (rather than free text
+that might mention one), `maintain_phone_search_index` keeps configurable
+sibling search columns in sync via `before_save` -- no child table required.
+
+Starting from scratch, with no phone-number table yet:
+
+```
+rails generate pico_phone:rails:phone_number PhoneNumber
+rails db:migrate
+```
+
+This creates a `phone_numbers` table (raw `number` column plus all four
+search-index columns, indexed) and an `app/models/phone_number.rb` with
+`maintain_phone_search_index` already wired up -- just fill in `region:` for
+your app. If you already have a table you want to add search columns to
+instead, skip the generator and call `maintain_phone_search_index` directly:
+
+```ruby
+class PhoneNumber < ApplicationRecord
+  maintain_phone_search_index :number,
+    region: "US",
+    columns: { e164: :e164, national_digits: :national_digits, reversed_digits: :reverse_index }
+end
+```
+
+Each `columns:` entry is independently optional -- omit any you don't want
+maintained. `reversed_digits` reverses the digit string so "ends with"/last-N
+searches can use a leftmost-prefix index lookup. Unparseable input (which the
+tracked column may deliberately allow) leaves every configured column `nil`
+rather than failing the save.
+
+To backfill rows that existed before you added the search index, use
+`sync_phone_search_index!` -- the `before_save` callback only fires when the
+tracked column *changes*, so re-saving an untouched row won't populate it:
+
+```ruby
+PhoneNumber.find_each(&:sync_phone_search_index!)
+```
+
+It writes immediately via `update_columns` (no callbacks, no validations),
+same graceful `nil`-on-unparseable behavior as the regular sync.
+
+Search against whichever columns you configured:
+
+```ruby
+PhoneNumber.phone_number_index_matching("(510) 274-5656")       # exact match via e164
+PhoneNumber.phone_number_index_starting_with("(510)")            # prefix, the way a viewer types it
+PhoneNumber.phone_number_index_ending_with("5656")                # last-N-digit suffix search
+```
+
+Each raises `PicoPhone::Rails::SearchColumnNotConfigured` if the column it
+needs wasn't included in `columns:`. `phone_number_index_matching` also
+accepts `region:` for interpreting an ambiguous query term, required
+explicitly (raising `PicoPhone::Rails::RegionRequired` otherwise) when the
+model's own `region:` is a Symbol/Proc rather than a fixed String -- same
+reasoning as `containing_phone_number` above.
+
+(These are named distinctly from Extraction's `containing_phone_number`/
+`phone_number_starting_with` on purpose -- both concerns get included onto
+every model, so identical names would collide and one would silently shadow
+the other.)
+
 ### ActiveJob serializer
 
 ```ruby

data/lib/generators/pico_phone/rails/extracted_phone_numbers/extracted_phone_numbers_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module PicoPhone
+  module Rails
+    # Invoked as `rails generate pico_phone:rails:extracted_phone_numbers`.
+    # Creates the migration for the table `extract_phone_numbers_from ...,
+    # persist: true` needs -- this is never run automatically, since a
+    # gem shouldn't silently add tables to an app's schema.
+    class ExtractedPhoneNumbersGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # @param dirname [String]
+      # @return [String]
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      # @return [void]
+      def create_migration_file
+        migration_template(
+          "create_pico_phone_rails_extracted_phone_numbers.rb.tt",
+          "db/migrate/create_pico_phone_rails_extracted_phone_numbers.rb"
+        )
+      end
+    end
+  end
+end

data/lib/generators/pico_phone/rails/extracted_phone_numbers/templates/create_pico_phone_rails_extracted_phone_numbers.rb.tt

@@ -0,0 +1,24 @@
+class CreatePicoPhoneRailsExtractedPhoneNumbers < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :pico_phone_rails_extracted_phone_numbers do |t|
+      t.references :extractable, polymorphic: true, null: false
+      t.string :source_attribute, null: false
+      t.string :region, null: false
+      t.string :e164, null: false
+      t.string :national_digits, null: false
+      t.string :raw_string, null: false
+      t.integer :start_offset, null: false
+      t.integer :end_offset, null: false
+
+      t.timestamps
+    end
+
+    # Explicit short names: the table name is long enough that the default
+    # generated name for the national_digits index exceeds the 64-character
+    # limit some databases (MySQL) and Rails versions enforce.
+    add_index :pico_phone_rails_extracted_phone_numbers, :e164,
+              name: "index_pico_phone_extracted_phone_numbers_on_e164"
+    add_index :pico_phone_rails_extracted_phone_numbers, :national_digits,
+              name: "index_pico_phone_extracted_phone_numbers_on_national_digits"
+  end
+end

data/lib/generators/pico_phone/rails/phone_number/phone_number_generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module PicoPhone
+  module Rails
+    # Invoked as `rails generate pico_phone:rails:phone_number PhoneNumber`.
+    # For apps starting a phone-number table from scratch -- unlike
+    # `maintain_phone_search_index` itself, which has no generator on
+    # purpose, since it needs to map onto whatever columns an *existing*
+    # table already has.
+    #
+    # Generates a migration for a table with a raw `number` column plus all
+    # four search-index columns (e164, national_digits, reversed_digits,
+    # region), and a starter model with `maintain_phone_search_index`
+    # already wired up.
+    class PhoneNumberGenerator < ::Rails::Generators::NamedBase
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # @param dirname [String]
+      # @return [String]
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      # @return [void]
+      def create_migration_file
+        migration_template "create_table.rb.tt", "db/migrate/create_#{table_name}.rb"
+      end
+
+      # @return [void]
+      def create_model_file
+        template "model.rb.tt", "app/models/#{file_path}.rb"
+      end
+
+      private
+
+      # @return [String]
+      def migration_class_name
+        "Create#{table_name.camelize}"
+      end
+    end
+  end
+end

data/lib/generators/pico_phone/rails/phone_number/templates/create_table.rb.tt

@@ -0,0 +1,17 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= table_name %> do |t|
+      t.string :number
+      t.string :e164
+      t.string :national_digits
+      t.string :reversed_digits
+      t.string :region
+
+      t.timestamps
+    end
+
+    add_index :<%= table_name %>, :e164
+    add_index :<%= table_name %>, :national_digits
+    add_index :<%= table_name %>, :reversed_digits
+  end
+end

data/lib/generators/pico_phone/rails/phone_number/templates/model.rb.tt

@@ -0,0 +1,11 @@
+class <%= class_name %> < ApplicationRecord
+  maintain_phone_search_index :number,
+                               region: "US", # TODO: set your app's region -- a String, a Symbol
+                                             # (instance method name), or a Proc, see the README
+                               columns: {
+                                 e164: :e164,
+                                 national_digits: :national_digits,
+                                 reversed_digits: :reversed_digits,
+                                 region: :region
+                               }
+end

data/lib/pico_phone/rails/extracted_phone_number.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module PicoPhone
+  module Rails
+    # A single phone number match persisted from a free-text column by
+    # `extract_phone_numbers_from ..., persist: true`. Required only once
+    # ActiveRecord::Base exists -- see the railtie -- since it inherits from
+    # it directly.
+    #
+    # Requires the table created by the `pico_phone:rails:extracted_phone_numbers`
+    # generator.
+    class ExtractedPhoneNumber < ActiveRecord::Base
+      self.table_name = "pico_phone_rails_extracted_phone_numbers"
+
+      belongs_to :extractable, polymorphic: true
+    end
+  end
+end

data/lib/pico_phone/rails/extraction.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module PicoPhone
+  module Rails
+    # Scans arbitrary text for phone numbers. Works on any string -- no
+    # ActiveRecord model required.
+    #
+    # @param text [String, nil]
+    # @param region [String] ISO 3166-1 alpha-2 default region for numbers found without a country code
+    # @return [Array<PicoPhone::PhoneNumberMatch>]
+    def self.extract_phone_numbers(text, region:)
+      return [] if text.nil? || text.empty?
+
+      PicoPhone.find_numbers(text, region)
+    end
+
+    # Replaces every phone number found in +text+ with +replacement+,
+    # preserving everything else in the string untouched.
+    #
+    # @param text [String, nil]
+    # @param region [String] ISO 3166-1 alpha-2 default region for numbers found without a country code
+    # @param replacement [String]
+    # @return [String]
+    def self.redact_phone_numbers(text, region:, replacement: "[PHONE]")
+      return text.to_s if text.nil? || text.empty?
+
+      matches = extract_phone_numbers(text, region: region)
+      return text.dup if matches.empty?
+
+      splice_redactions(text, matches, replacement)
+    end
+
+    # @param text [String]
+    # @param matches [Array<PicoPhone::PhoneNumberMatch>]
+    # @param replacement [String]
+    # @return [String]
+    def self.splice_redactions(text, matches, replacement)
+      segments = []
+      cursor = 0
+      matches.each do |match|
+        segments << text.byteslice(cursor, match.start - cursor)
+        segments << replacement
+        cursor = match.end_index
+      end
+      segments << text.byteslice(cursor, text.bytesize - cursor)
+      segments.join
+    end
+    private_class_method :splice_redactions
+
+    # Raised by `containing_phone_number` when the including model never
+    # opted into `persist: true` (or its migration hasn't been run), instead
+    # of an obscure ActiveRecord::StatementInvalid: no such table.
+    class PersistenceNotEnabled < Error; end
+
+    # Raised by `containing_phone_number` when the model's `region:` is
+    # resolved per record (a Symbol or Proc, for multi-tenant/multi-region
+    # apps) and the caller didn't pass an explicit `region:` -- there's no
+    # single record to resolve it against at the class level.
+    class RegionRequired < Error; end
+
+    # Included into ActiveRecord::Base by the railtie. Adds an
+    # `extract_phone_numbers_from` class macro that wraps a free-text column
+    # with helpers for pulling out and redacting the phone numbers it
+    # mentions -- useful for notes, support tickets, and chat logs where a
+    # phone number might appear anywhere in the text, in any format.
+    #
+    # @example
+    #   class Note < ApplicationRecord
+    #     extract_phone_numbers_from :body, region: "US"
+    #   end
+    #
+    #   note.extracted_phone_numbers    # => [#<PicoPhone::PhoneNumberMatch ...>, ...]
+    #   note.body_with_phones_redacted  # => "Call me at [PHONE] or [PHONE]"
+    #
+    # @example Persisting matches for cross-record search
+    #   class Note < ApplicationRecord
+    #     extract_phone_numbers_from :body, region: "US", persist: true
+    #   end
+    #
+    #   Note.containing_phone_number("(510) 274-5656") # matches regardless of stored format
+    module Extraction
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :pico_phone_rails_persisted, instance_accessor: false, default: false
+        class_attribute :pico_phone_rails_extraction_region, instance_accessor: false, default: nil
+      end
+
+      class_methods do
+        # @!method extract_phone_numbers_from(attribute, region:, persist: false)
+        #   Defines +#extracted_phone_numbers+ and +#<attribute>_with_phones_redacted+
+        #   on the including model, both backed by a live re-scan of +attribute+ --
+        #   nothing is persisted or cached by default.
+        #
+        #   When +persist: true+, also declares a +has_many :extracted_phone_number_records+
+        #   association and an +after_save+ callback that keeps it in sync with
+        #   +attribute+, so {.containing_phone_number} can find records by phone
+        #   number regardless of how it was formatted in the source text. Requires
+        #   the table created by the `pico_phone:rails:extracted_phone_numbers`
+        #   generator.
+        #   @param attribute [Symbol] the text attribute to scan
+        #   @param region [String, Symbol, Proc] ISO 3166-1 alpha-2 default region for numbers found without a
+        #     country code. A String is used as-is; a Symbol is called as an instance method on the record; a
+        #     Proc is called with the record. Either lets the region vary per record, e.g.
+        #     `region: ->(note) { note.campus.region }`, for multi-tenant/multi-region apps, rather than being
+        #     fixed once for the whole model.
+        #   @param persist [Boolean] persist matches for cross-record search via {.containing_phone_number}
+        #   @return [void]
+        def extract_phone_numbers_from(attribute, region:, persist: false)
+          define_method(:extracted_phone_numbers) do
+            resolved_region = PicoPhone::Rails.resolve_region(region, self)
+            PicoPhone::Rails.extract_phone_numbers(public_send(attribute).to_s, region: resolved_region)
+          end
+
+          define_method("#{attribute}_with_phones_redacted") do
+            resolved_region = PicoPhone::Rails.resolve_region(region, self)
+            PicoPhone::Rails.redact_phone_numbers(public_send(attribute).to_s, region: resolved_region)
+          end
+
+          return unless persist
+
+          persist_extracted_phone_numbers_from(attribute, region)
+        end
+      end
+
+      class_methods do
+        # @param term [String] a phone number in any format
+        # @param region [String, nil] ISO 3166-1 alpha-2 region for interpreting +term+ -- required if the
+        #   model's own region is resolved per record (a Symbol or Proc), since there's no record to resolve
+        #   it against here; pass the searching user's own region, e.g. `region: current_organization.region`
+        # @raise [PicoPhone::Rails::PersistenceNotEnabled] if no attribute was registered with +persist: true+
+        # @raise [PicoPhone::Rails::RegionRequired] if +region+ is omitted and the model's region is per-record
+        # @return [ActiveRecord::Relation]
+        def containing_phone_number(term, region: nil)
+          ensure_pico_phone_rails_persisted!
+          resolved_region = region || pico_phone_rails_static_extraction_region!
+
+          e164 = PicoPhone.parse(term.to_s, resolved_region).e164
+          joins(:extracted_phone_number_records)
+            .where(PicoPhone::Rails::ExtractedPhoneNumber.table_name => { e164: e164 })
+            .distinct
+        end
+
+        # Matches against the digits of the number's *displayed* national
+        # format (e.g. "5102745656", or "0123456789" for a French number
+        # whose national format shows a leading trunk "0") -- what a viewer
+        # would actually type while looking at the number, rather than the
+        # E.164 "national significant number" (which drops that trunk digit).
+        #
+        # @param prefix [String] a phone number prefix in any format, e.g. "(510)"
+        # @raise [PicoPhone::Rails::PersistenceNotEnabled] if no attribute was registered with +persist: true+
+        # @return [ActiveRecord::Relation]
+        def phone_number_starting_with(prefix)
+          ensure_pico_phone_rails_persisted!
+
+          digits = prefix.to_s.gsub(/\D/, "")
+          joins(:extracted_phone_number_records)
+            .where("#{PicoPhone::Rails::ExtractedPhoneNumber.table_name}.national_digits LIKE ?", "#{digits}%")
+            .distinct
+        end
+      end
+
+      class_methods do
+        private
+
+        # @raise [PicoPhone::Rails::PersistenceNotEnabled]
+        # @return [void]
+        def ensure_pico_phone_rails_persisted!
+          return if pico_phone_rails_persisted
+
+          raise PersistenceNotEnabled,
+                "#{name} has no attribute registered with `extract_phone_numbers_from ..., persist: true` -- " \
+                "add persist: true and run the pico_phone:rails:extracted_phone_numbers generator"
+        end
+
+        # @raise [PicoPhone::Rails::RegionRequired] if the configured region isn't a plain String
+        # @return [String, nil]
+        def pico_phone_rails_static_extraction_region!
+          region = pico_phone_rails_extraction_region
+          return region if region.nil? || region.is_a?(String)
+
+          raise RegionRequired,
+                "#{name}'s region is resolved per record (#{region.inspect}), so it can't be inferred for a " \
+                "class-level search -- pass region: explicitly, e.g. " \
+                "#{name}.containing_phone_number(term, region: current_organization.region)"
+        end
+      end
+
+      class_methods do
+        # @param attribute [Symbol]
+        # @param region [String]
+        # @return [void]
+        private def persist_extracted_phone_numbers_from(attribute, region)
+          self.pico_phone_rails_persisted = true
+          self.pico_phone_rails_extraction_region = region
+
+          has_many :extracted_phone_number_records,
+                   class_name: "PicoPhone::Rails::ExtractedPhoneNumber",
+                   as: :extractable,
+                   dependent: :delete_all
+
+          after_save(if: -> { public_send(:"saved_change_to_#{attribute}?") }) do
+            pico_phone_rails_sync_extracted_phone_numbers(attribute, region)
+          end
+        end
+      end
+
+      # @param attribute [Symbol]
+      # @param region [String, Symbol, Proc]
+      # @return [void]
+      def pico_phone_rails_sync_extracted_phone_numbers(attribute, region)
+        resolved_region = PicoPhone::Rails.resolve_region(region, self)
+        matches = PicoPhone::Rails.extract_phone_numbers(public_send(attribute).to_s, region: resolved_region)
+
+        extracted_phone_number_records.where(source_attribute: attribute.to_s).delete_all
+        return if matches.empty?
+
+        rows = matches.map do |match|
+          pico_phone_rails_extracted_phone_number_attributes(match, attribute, resolved_region)
+        end
+        extracted_phone_number_records.insert_all(rows)
+      end
+      private :pico_phone_rails_sync_extracted_phone_numbers
+
+      # @param match [PicoPhone::PhoneNumberMatch]
+      # @param attribute [Symbol]
+      # @param region [String] the region actually resolved for this record, persisted for auditability
+      # @return [Hash]
+      def pico_phone_rails_extracted_phone_number_attributes(match, attribute, region)
+        {
+          source_attribute: attribute.to_s,
+          region: region,
+          e164: match.number.e164,
+          national_digits: match.number.national.gsub(/\D/, ""),
+          raw_string: match.raw_string,
+          start_offset: match.start,
+          end_offset: match.end_index
+        }
+      end
+      private :pico_phone_rails_extracted_phone_number_attributes
+    end
+  end
+end

data/lib/pico_phone/rails/phone_search_index.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module PicoPhone
+  module Rails
+    # Raised by the {PhoneSearchIndex} class-level search methods when the
+    # column they need wasn't configured in `columns:`.
+    class SearchColumnNotConfigured < Error; end
+
+    # Included into ActiveRecord::Base by the railtie. Adds a
+    # `maintain_phone_search_index` class macro for a table that's already
+    # one-row-per-phone-number (unlike Extraction, which is for a free-text
+    # column that might mention a number anywhere in it). Keeps configurable
+    # sibling columns in sync via `before_save` -- no child table, no
+    # polymorphic association.
+    #
+    # @example
+    #   class PhoneNumber < ApplicationRecord
+    #     maintain_phone_search_index :number,
+    #       region: "US",
+    #       columns: { e164: :e164, national_digits: :national_digits, reversed_digits: :reverse_index }
+    #   end
+    #
+    #   PhoneNumber.phone_number_index_matching("(510) 274-5656")
+    #   PhoneNumber.phone_number_index_starting_with("(510)")
+    #   PhoneNumber.phone_number_index_ending_with("5656")
+    module PhoneSearchIndex
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :pico_phone_rails_phone_search_columns, instance_accessor: false, default: {}
+        class_attribute :pico_phone_rails_phone_search_region, instance_accessor: false, default: nil
+      end
+
+      class_methods do
+        # @!method maintain_phone_search_index(attribute, region:, columns: {})
+        #   Registers a +before_save+ callback (only when +attribute+ actually
+        #   changes) that parses +attribute+ and writes the configured derived
+        #   columns. Each entry in +columns:+ is independently optional -- omit
+        #   any key you don't want maintained, e.g. to keep an existing
+        #   hand-rolled column untouched.
+        #
+        #   Unparseable input (which +attribute+ may deliberately allow) leaves
+        #   every configured column +nil+ rather than failing the save, since
+        #   +PhoneNumber#e164+/+#national+ raise on input that can't be
+        #   interpreted as a phone number attempt at all.
+        #   @param attribute [Symbol] the column holding the raw phone number
+        #   @param region [String, Symbol, Proc] see {Extraction.extract_phone_numbers_from} for resolution rules
+        #   @param columns [Hash{Symbol => Symbol}] maps :e164, :national_digits, :reversed_digits, and/or :region
+        #     (search-index concepts) to the actual column names to write them to
+        #   @return [void]
+        def maintain_phone_search_index(attribute, region:, columns: {})
+          self.pico_phone_rails_phone_search_columns = columns
+          self.pico_phone_rails_phone_search_region = region
+
+          before_save(if: -> { public_send(:"#{attribute}_changed?") }) do
+            pico_phone_rails_stage_phone_search_index(attribute, region, columns)
+          end
+
+          # @!method sync_phone_search_index!
+          #   Recomputes and immediately persists the configured columns via
+          #   +update_columns+ (no callbacks, no validations), regardless of
+          #   whether +attribute+ has changed -- unlike the +before_save+
+          #   above, which only fires on an actual change. Meant for
+          #   backfilling existing rows, since dirty-tracking has no way to
+          #   know an unmodified row was never synced in the first place:
+          #     PhoneNumber.find_each(&:sync_phone_search_index!)
+          #   @return [void]
+          define_method(:sync_phone_search_index!) do
+            resolved_region = PicoPhone::Rails.resolve_region(region, self)
+            phone_number = PicoPhone.parse(public_send(attribute).to_s, resolved_region)
+            values = pico_phone_rails_phone_search_index_values(phone_number, resolved_region, columns)
+            update_columns(values)
+          end
+        end
+      end
+
+      class_methods do
+        # @param term [String] a phone number in any format
+        # @param region [String, nil] region for interpreting +term+ -- required if the model's own
+        #   region is resolved per record (a Symbol or Proc); pass the searching user's own region
+        # @raise [PicoPhone::Rails::SearchColumnNotConfigured] if +columns:+ didn't configure +:e164+
+        # @raise [PicoPhone::Rails::RegionRequired] if +region+ is omitted and the model's region is per-record
+        # @return [ActiveRecord::Relation]
+        def phone_number_index_matching(term, region: nil)
+          column = pico_phone_rails_phone_search_column!(:e164)
+          resolved_region = region || pico_phone_rails_static_phone_search_region!
+
+          e164 = PicoPhone.parse(term.to_s, resolved_region).e164
+          where(column => e164)
+        end
+
+        # Matches against the digits of the number's *displayed* national format -- see
+        # {Extraction::ClassMethods#phone_number_starting_with} for the "why" (national vs
+        # raw_national digits), and the same caveat applies here.
+        # @param prefix [String] a phone number prefix in any format, e.g. "(510)"
+        # @raise [PicoPhone::Rails::SearchColumnNotConfigured] if +columns:+ didn't configure +:national_digits+
+        # @return [ActiveRecord::Relation]
+        def phone_number_index_starting_with(prefix)
+          column = pico_phone_rails_phone_search_column!(:national_digits)
+          digits = prefix.to_s.gsub(/\D/, "")
+          where("#{column} LIKE ?", "#{digits}%")
+        end
+
+        # Matches against the reversed digits of the number's displayed national format, so a
+        # last-N-digit search can use a leftmost-prefix index lookup instead of a full scan.
+        # @param suffix [String] a phone number suffix in any format, e.g. "5656"
+        # @raise [PicoPhone::Rails::SearchColumnNotConfigured] if +columns:+ didn't configure +:reversed_digits+
+        # @return [ActiveRecord::Relation]
+        def phone_number_index_ending_with(suffix)
+          column = pico_phone_rails_phone_search_column!(:reversed_digits)
+          digits = suffix.to_s.gsub(/\D/, "")
+          where("#{column} LIKE ?", "#{digits.reverse}%")
+        end
+      end
+
+      class_methods do
+        private
+
+        # @param key [Symbol]
+        # @raise [PicoPhone::Rails::SearchColumnNotConfigured]
+        # @return [Symbol]
+        def pico_phone_rails_phone_search_column!(key)
+          column = pico_phone_rails_phone_search_columns[key]
+          return column if column
+
+          raise SearchColumnNotConfigured,
+                "#{name} didn't configure a :#{key} column -- add it to `columns:` in maintain_phone_search_index"
+        end
+
+        # @raise [PicoPhone::Rails::RegionRequired] if the configured region isn't a plain String
+        # @return [String, nil]
+        def pico_phone_rails_static_phone_search_region!
+          region = pico_phone_rails_phone_search_region
+          return region if region.nil? || region.is_a?(String)
+
+          raise RegionRequired,
+                "#{name}'s region is resolved per record (#{region.inspect}), so it can't be inferred for a " \
+                "class-level search -- pass region: explicitly, e.g. " \
+                "#{name}.phone_number_index_matching(term, region: current_organization.region)"
+        end
+      end
+
+      # @param attribute [Symbol]
+      # @param region [String, Symbol, Proc]
+      # @param columns [Hash{Symbol => Symbol}]
+      # @return [void]
+      def pico_phone_rails_stage_phone_search_index(attribute, region, columns)
+        resolved_region = PicoPhone::Rails.resolve_region(region, self)
+        phone_number = PicoPhone.parse(public_send(attribute).to_s, resolved_region)
+
+        pico_phone_rails_phone_search_index_values(phone_number, resolved_region, columns).each do |column, value|
+          public_send("#{column}=", value)
+        end
+      end
+      private :pico_phone_rails_stage_phone_search_index
+
+      # @param phone_number [PicoPhone::PhoneNumber]
+      # @param resolved_region [String]
+      # @param columns [Hash{Symbol => Symbol}]
+      # @return [Hash{Symbol => String, nil}] actual column name => value to write
+      def pico_phone_rails_phone_search_index_values(phone_number, resolved_region, columns)
+        e164 = pico_phone_rails_safe_phone_call(phone_number, :e164)
+        national_digits = pico_phone_rails_safe_phone_call(phone_number, :national)&.gsub(/\D/, "")
+
+        values = {
+          e164: e164,
+          national_digits: national_digits,
+          reversed_digits: national_digits&.reverse,
+          region: (resolved_region if e164)
+        }
+
+        columns.each_with_object({}) { |(key, column), result| result[column] = values[key] }
+      end
+      private :pico_phone_rails_phone_search_index_values
+
+      # @param phone_number [PicoPhone::PhoneNumber]
+      # @param method_name [Symbol]
+      # @return [String, nil] +nil+ if +method_name+ raises on unparseable input
+      def pico_phone_rails_safe_phone_call(phone_number, method_name)
+        phone_number.public_send(method_name)
+      rescue TypeError
+        nil
+      end
+      private :pico_phone_rails_safe_phone_call
+    end
+  end
+end

data/lib/pico_phone/rails/railtie.rb

@@ -17,6 +17,19 @@ module PicoPhone
         end
       end
 
+      initializer "pico_phone_rails.extraction" do
+        ActiveSupport.on_load(:active_record) do
+          require "pico_phone/rails/extracted_phone_number"
+          include PicoPhone::Rails::Extraction
+        end
+      end
+
+      initializer "pico_phone_rails.phone_search_index" do
+        ActiveSupport.on_load(:active_record) do
+          include PicoPhone::Rails::PhoneSearchIndex
+        end
+      end
+
       initializer "pico_phone_rails.active_job_serializer" do
         ActiveSupport.on_load(:active_job) do
           require "pico_phone/rails/serializers/phone_number_serializer"

data/lib/pico_phone/rails/region_resolution.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PicoPhone
+  module Rails
+    # Resolves a `region:` option that may be a plain region code, or --
+    # for apps where the correct region varies per record (multi-tenant,
+    # multi-region) -- a Symbol naming an instance method, or a Proc called
+    # with the record. Shared by {Extraction} and {PhoneSearchIndex}.
+    #
+    # @param region [String, Symbol, Proc]
+    # @param record [Object]
+    # @return [String, nil]
+    def self.resolve_region(region, record)
+      case region
+      when Symbol then record.public_send(region)
+      when Proc then region.call(record)
+      else region
+      end
+    end
+  end
+end

data/lib/pico_phone/rails/version.rb

@@ -2,6 +2,6 @@
 
 module PicoPhone
   module Rails
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/pico_phone/rails.rb

@@ -2,13 +2,17 @@
 
 require "pico_phone"
 require "pico_phone/rails/version"
-require "phone_validator"
-require "pico_phone/rails/type"
-require "pico_phone/rails/normalizer"
-require "pico_phone/rails/railtie" if defined?(Rails::Railtie)
 
 module PicoPhone
   module Rails
     class Error < StandardError; end
   end
 end
+
+require "phone_validator"
+require "pico_phone/rails/region_resolution"
+require "pico_phone/rails/type"
+require "pico_phone/rails/normalizer"
+require "pico_phone/rails/extraction"
+require "pico_phone/rails/phone_search_index"
+require "pico_phone/rails/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pico_phone-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Gabi Jack
@@ -53,8 +53,11 @@ dependencies:
         version: '7.0'
 description: 'pico_phone-rails wires the pico_phone gem into Rails: a :phone_number
   ActiveRecord attribute type, a PhoneValidator for ActiveModel validations, a normalize_phone
-  class macro that rewrites phone attributes to E.164 before validation, and an ActiveJob
-  serializer so a PhoneNumber survives being passed as a job argument.'
+  class macro that rewrites phone attributes to E.164 before validation, extract_phone_numbers_from
+  for pulling phone numbers out of free text (with an optional persisted backend for
+  cross-record search), maintain_phone_search_index for keeping search columns in
+  sync on an existing phone-number table, and an ActiveJob serializer so a PhoneNumber
+  survives being passed as a job argument.'
 email:
 - gabi@gabijack.com
 executables: []
@@ -63,11 +66,20 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/generators/pico_phone/rails/extracted_phone_numbers/extracted_phone_numbers_generator.rb
+- lib/generators/pico_phone/rails/extracted_phone_numbers/templates/create_pico_phone_rails_extracted_phone_numbers.rb.tt
+- lib/generators/pico_phone/rails/phone_number/phone_number_generator.rb
+- lib/generators/pico_phone/rails/phone_number/templates/create_table.rb.tt
+- lib/generators/pico_phone/rails/phone_number/templates/model.rb.tt
 - lib/phone_validator.rb
 - lib/pico_phone/rails.rb
+- lib/pico_phone/rails/extracted_phone_number.rb
+- lib/pico_phone/rails/extraction.rb
 - lib/pico_phone/rails/locale/en.yml
 - lib/pico_phone/rails/normalizer.rb
+- lib/pico_phone/rails/phone_search_index.rb
 - lib/pico_phone/rails/railtie.rb
+- lib/pico_phone/rails/region_resolution.rb
 - lib/pico_phone/rails/serializers/phone_number_serializer.rb
 - lib/pico_phone/rails/type.rb
 - lib/pico_phone/rails/version.rb
@@ -98,5 +110,5 @@ requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
 summary: 'Rails integration for pico_phone: attribute type, validator, normalizer,
-  and ActiveJob serializer'
+  free-text extraction, phone search index, and ActiveJob serializer'
 test_files: []