rails-contact 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da9e560dd16bfddaae191d2951cdb891d1c81a5c03e854fa608ce698bad0f4ed
+  data.tar.gz: be80125cfbca594d514a43701f0468a083868d74cb77a5a7e9fdb9bfa1b92cb3
+SHA512:
+  metadata.gz: b2e6b507b3e9b1eb0bb4a06a9784ce5965937d3625a74b81749ea60785918f3afeb752f2ae8ca530ff47c4211907e49d9d91e0ea1cf281c8daefdabee92c0a55
+  data.tar.gz: 7ef76b8f5e22865f80b36a05665c3dd25105ccba061fb5810b6d79c3a530bb2d68d6d9fe1d4464383f76d33989666e1622db2754063e868c6ec9fa715b4f9152

data/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: weekly
+  open-pull-requests-limit: 10
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: weekly
+  open-pull-requests-limit: 10

data/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      RUBY_VERSION: "3.3"
+      RUBOCOP_CACHE_ROOT: tmp/rubocop
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.RUBY_VERSION }}
+          bundler-cache: true
+
+      - name: Prepare RuboCop cache
+        uses: actions/cache@v4
+        env:
+          DEPENDENCIES_HASH: ${{ hashFiles('**/.rubocop.yml', '**/.rubocop_todo.yml', 'Gemfile.lock') }}
+        with:
+          path: ${{ env.RUBOCOP_CACHE_ROOT }}
+          key: rubocop-${{ runner.os }}-${{ env.RUBY_VERSION }}-${{ env.DEPENDENCIES_HASH }}-${{ github.ref_name == github.event.repository.default_branch && github.run_id || 'default' }}
+          restore-keys: |
+            rubocop-${{ runner.os }}-${{ env.RUBY_VERSION }}-${{ env.DEPENDENCIES_HASH }}-
+
+      - name: Lint code for consistent style
+        run: bin/rubocop -f github
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3"]
+    services:
+      elasticsearch:
+        image: docker.elastic.co/elasticsearch/elasticsearch:8.13.4
+        env:
+          discovery.type: single-node
+          xpack.security.enabled: "false"
+        ports:
+          - 9200:9200
+    env:
+      ELASTICSEARCH_URL: http://127.0.0.1:9200
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec ruby -Itest -e 'Dir["test/**/*_test.rb"].sort.each { |f| require File.expand_path(f) }'
+

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release of `rails-contact`.
+- Mountable engine with contact CRUD.
+- CSV import service for Google-shaped contact fields.
+- Elasticsearch-backed search with database fallback.
+- Google Contacts sync service scaffold with rolling-window support.
+- Generators for install and migrations.

data/Gemfile

@@ -0,0 +1,19 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rails-contact.gemspec.
+gemspec
+
+gem "puma"
+
+gem "sqlite3"
+gem "rack-test"
+gem "minitest-reporters"
+gem "mocha"
+gem "webmock"
+gem "parallel", "~> 1.26.0"
+
+# Omakase Ruby styling [https://github.com/rails/rubocop-rails-omakase/]
+gem "rubocop-rails-omakase", require: false
+
+# Start debugger with binding.b [https://github.com/ruby/debug]
+# gem "debug", ">= 1.0.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+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.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+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.

data/README.md

@@ -0,0 +1,71 @@
+# rails-contact
+
+`rails-contact` is a mountable Rails engine for Google-shaped contact management with:
+
+- local source-of-truth data model
+- Elasticsearch-powered search/filter (with DB fallback)
+- CSV import pipeline
+- capped rolling-window Google Contacts sync hooks
+
+## Install
+
+```ruby
+gem "rails-contact"
+```
+
+```bash
+bundle install
+rails generate rails:contact:install
+rails generate rails:contact:contact Contact
+rails db:migrate
+```
+
+## Configure
+
+Initializer: `config/initializers/rails_contact.rb`
+
+```ruby
+Rails::Contact.configure do |config|
+  config.search_backend = :elasticsearch
+  config.elasticsearch_url = ENV.fetch("ELASTICSEARCH_URL", "http://127.0.0.1:9200")
+  config.google_sync_enabled = true
+  config.google_max_contacts = 25_000
+  config.rolling_window_sort = :updated_at
+end
+```
+
+## Mount
+
+```ruby
+mount Rails::Contact::Engine => "/contacts", as: "rails_contact"
+```
+
+## Features
+
+- Contact CRUD with nested emails/phones/addresses
+- Filter and full-text search by name, email, and phone
+- CSV import mapping for fields like Enquirer First Name / Enquirer Email / country-code phones
+- Google payload mapping and sync service scaffolding
+- Reindex and sync tasks:
+  - `rake rails_contact:reindex`
+  - `rake rails_contact:sync_google`
+  - `rake rails_contact:import_csv CSV_PATH=/path/to/file.csv`
+
+## Test
+
+```bash
+bundle exec ruby -Itest test/**/*_test.rb
+```
+
+## Release
+
+```bash
+bundle exec rake build
+bundle exec rake release
+```
+
+Ensure RubyGems MFA is enabled for maintainers.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/rails/contact/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

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

@@ -0,0 +1,13 @@
+module Rails
+  module Contact
+    class ApplicationController < ActionController::Base
+      protect_from_forgery with: :exception
+
+      private
+
+      def t_flash(key, default:)
+        I18n.t("rails_contact.flash.#{key}", default: default)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+module Rails
+  module Contact
+    class ContactsController < ApplicationController
+      before_action :set_contact, only: [ :show, :edit, :update, :destroy ]
+
+      def index
+        @query = params[:q].to_s.strip
+        @contacts = Search::Query.new(@query, filters: filter_params).call
+      end
+
+      def show; end
+
+      def new
+        @contact = Contact.new
+        build_default_associations
+      end
+
+      def edit; end
+
+      def create
+        @contact = Contact.new(contact_params)
+        if @contact.save
+          enqueue_index(@contact.id)
+          redirect_to contact_path(@contact), notice: "Contact created."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def update
+        if @contact.update(contact_params)
+          enqueue_index(@contact.id)
+          redirect_to contact_path(@contact), notice: "Contact updated."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        id = @contact.id
+        @contact.destroy!
+        IndexContactJob.perform_later(id, remove: true)
+        redirect_to contacts_path, notice: "Contact deleted."
+      end
+
+      private
+
+      def set_contact
+        @contact = Contact.find(params[:id])
+        build_default_associations
+      end
+
+      def contact_params
+        params.require(:contact).permit(
+          :given_name, :family_name, :current_city, :departure_city, :region_name, :biography, :sync_eligible,
+          emails_attributes: [ :id, :value, :label, :primary, :_destroy ],
+          phones_attributes: [ :id, :value, :label, :primary, :_destroy ],
+          addresses_attributes: [ :id, :city, :departure_city, :formatted_value, :label, :_destroy ]
+        )
+      end
+
+      def filter_params
+        params.permit(:city, :region, :sync_eligible)
+      end
+
+      def enqueue_index(contact_id)
+        IndexContactJob.perform_later(contact_id)
+      end
+
+      def build_default_associations
+        @contact.emails.build if @contact.emails.empty?
+        @contact.phones.build if @contact.phones.empty?
+        @contact.addresses.build if @contact.addresses.empty?
+      end
+    end
+  end
+end

data/app/helpers/rails/contact/application_helper.rb

@@ -0,0 +1,6 @@
+module Rails
+  module Contact
+    module ApplicationHelper
+    end
+  end
+end

data/app/jobs/rails/contact/application_job.rb

@@ -0,0 +1,6 @@
+module Rails
+  module Contact
+    class ApplicationJob < ActiveJob::Base
+    end
+  end
+end

data/app/jobs/rails/contact/google_sync_job.rb

@@ -0,0 +1,13 @@
+module Rails
+  module Contact
+    class GoogleSyncJob < ApplicationJob
+      queue_as :default
+
+      def perform
+        return unless Rails::Contact.configuration.google_sync_enabled
+
+        Google::SyncService.new.sync!
+      end
+    end
+  end
+end

data/app/jobs/rails/contact/index_contact_job.rb

@@ -0,0 +1,18 @@
+module Rails
+  module Contact
+    class IndexContactJob < ApplicationJob
+      queue_as :default
+
+      def perform(contact_id, remove: false)
+        backend = Search::Backends::Elasticsearch.new
+        return backend.remove(contact_id) if remove
+
+        contact = Contact.includes(:emails, :phones).find_by(id: contact_id)
+        return if contact.nil?
+
+        backend.create_index!
+        backend.upsert(contact)
+      end
+    end
+  end
+end

data/app/mailers/rails/contact/application_mailer.rb

@@ -0,0 +1,8 @@
+module Rails
+  module Contact
+    class ApplicationMailer < ActionMailer::Base
+      default from: "from@example.com"
+      layout "mailer"
+    end
+  end
+end

data/app/mailers/rails/contact/contact_mailer.rb

@@ -0,0 +1,32 @@
+module Rails
+  module Contact
+    class ContactMailer < ApplicationMailer
+      def confirmation_instructions(email, token)
+        mail_for(email, "Confirmation instructions", token)
+      end
+
+      def reset_password_instructions(email, token)
+        mail_for(email, "Reset password instructions", token)
+      end
+
+      def unlock_instructions(email, token)
+        mail_for(email, "Unlock instructions", token)
+      end
+
+      def email_changed(email)
+        mail(to: email, subject: "Email changed notification")
+      end
+
+      def password_changed(email)
+        mail(to: email, subject: "Password changed notification")
+      end
+
+      private
+
+      def mail_for(email, subject, token)
+        Rails.logger.info("[rails-contact] #{subject} for #{email}: #{token}")
+        mail(to: email, subject: subject)
+      end
+    end
+  end
+end

data/app/models/rails/contact/application_record.rb

@@ -0,0 +1,7 @@
+module Rails
+  module Contact
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/rails/contact/contact.rb

@@ -0,0 +1,32 @@
+module Rails
+  module Contact
+    class Contact < ApplicationRecord
+      self.table_name = "rails_contact_contacts"
+
+      has_many :emails, class_name: "Rails::Contact::ContactEmail", dependent: :destroy, inverse_of: :contact
+      has_many :phones, class_name: "Rails::Contact::ContactPhone", dependent: :destroy, inverse_of: :contact
+      has_many :addresses, class_name: "Rails::Contact::ContactAddress", dependent: :destroy, inverse_of: :contact
+
+      accepts_nested_attributes_for :emails, :phones, :addresses, allow_destroy: true
+
+      validates :given_name, presence: true
+
+      scope :recent_first, -> { order(updated_at: :desc, id: :desc) }
+      scope :sync_window, lambda {
+        recent_first.limit(Rails::Contact.configuration.google_max_contacts)
+      }
+
+      def full_name
+        [ given_name, family_name ].compact.join(" ").strip
+      end
+
+      def primary_email
+        emails.find(&:primary?) || emails.first
+      end
+
+      def primary_phone
+        phones.find(&:primary?) || phones.first
+      end
+    end
+  end
+end

data/app/models/rails/contact/contact_address.rb

@@ -0,0 +1,9 @@
+module Rails
+  module Contact
+    class ContactAddress < ApplicationRecord
+      self.table_name = "rails_contact_contact_addresses"
+
+      belongs_to :contact, class_name: "Rails::Contact::Contact", inverse_of: :addresses
+    end
+  end
+end

data/app/models/rails/contact/contact_email.rb

@@ -0,0 +1,24 @@
+module Rails
+  module Contact
+    class ContactEmail < ApplicationRecord
+      self.table_name = "rails_contact_contact_emails"
+
+      belongs_to :contact, class_name: "Rails::Contact::Contact", inverse_of: :emails
+
+      validates :value, presence: true
+      validates :value, format: { with: URI::MailTo::EMAIL_REGEXP }
+
+      before_validation :normalize_value
+
+      def primary?
+        primary
+      end
+
+      private
+
+      def normalize_value
+        self.value = value.to_s.strip.downcase.presence
+      end
+    end
+  end
+end

data/app/models/rails/contact/contact_phone.rb

@@ -0,0 +1,28 @@
+require "phonelib"
+
+module Rails
+  module Contact
+    class ContactPhone < ApplicationRecord
+      self.table_name = "rails_contact_contact_phones"
+
+      belongs_to :contact, class_name: "Rails::Contact::Contact", inverse_of: :phones
+
+      validates :value, presence: true
+
+      before_validation :normalize_value
+
+      def primary?
+        primary
+      end
+
+      private
+
+      def normalize_value
+        return if value.blank?
+
+        parsed = Phonelib.parse(value)
+        self.e164 = parsed.e164 || value
+      end
+    end
+  end
+end

data/app/views/layouts/rails/contact/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Rails contact</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "rails/contact/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/app/views/rails/contact/contacts/_form.html.erb

@@ -0,0 +1,61 @@
+<%= form_with model: contact, local: true do |f| %>
+  <% if contact.errors.any? %>
+    <div data-turbo-temporary="true">
+      <h2><%= pluralize(contact.errors.count, "error") %> prevented save</h2>
+      <ul>
+        <% contact.errors.full_messages.each do |message| %>
+          <li><%= message %></li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <p>
+    <%= f.label :given_name %>
+    <%= f.text_field :given_name %>
+  </p>
+  <p>
+    <%= f.label :family_name %>
+    <%= f.text_field :family_name %>
+  </p>
+  <p>
+    <%= f.label :current_city %>
+    <%= f.text_field :current_city %>
+  </p>
+  <p>
+    <%= f.label :departure_city %>
+    <%= f.text_field :departure_city %>
+  </p>
+  <p>
+    <%= f.label :region_name %>
+    <%= f.text_field :region_name %>
+  </p>
+  <p>
+    <%= f.label :biography %>
+    <%= f.text_area :biography, rows: 3 %>
+  </p>
+  <p>
+    <%= f.label :sync_eligible %>
+    <%= f.check_box :sync_eligible %>
+  </p>
+
+  <%= f.fields_for :emails do |email_fields| %>
+    <p>
+      <%= email_fields.label :value, "Email" %>
+      <%= email_fields.email_field :value %>
+      <%= email_fields.label :primary %>
+      <%= email_fields.check_box :primary %>
+    </p>
+  <% end %>
+
+  <%= f.fields_for :phones do |phone_fields| %>
+    <p>
+      <%= phone_fields.label :value, "Phone" %>
+      <%= phone_fields.text_field :value %>
+      <%= phone_fields.label :label %>
+      <%= phone_fields.text_field :label %>
+    </p>
+  <% end %>
+
+  <%= f.submit %>
+<% end %>

data/app/views/rails/contact/contacts/edit.html.erb

@@ -0,0 +1,3 @@
+<h1>Edit Contact</h1>
+<%= render "form", contact: @contact %>
+<%= link_to "Back", contacts_path %>

data/app/views/rails/contact/contacts/index.html.erb

@@ -0,0 +1,38 @@
+<h1>Contacts</h1>
+
+<%= form_with url: contacts_path, method: :get, local: true do |f| %>
+  <%= f.label :q, "Search" %>
+  <%= f.text_field :q, value: @query %>
+  <%= f.label :city, "Current City" %>
+  <%= f.text_field :city, value: params[:city] %>
+  <%= f.label :region, "Region" %>
+  <%= f.text_field :region, value: params[:region] %>
+  <%= f.submit "Filter" %>
+<% end %>
+
+<p><%= link_to "New Contact", new_contact_path %></p>
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Email</th>
+      <th>Phone</th>
+      <th>Current City</th>
+      <th>Region</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <% @contacts.each do |contact| %>
+      <tr>
+        <td><%= contact.full_name %></td>
+        <td><%= contact.primary_email&.value %></td>
+        <td><%= contact.primary_phone&.e164 %></td>
+        <td><%= contact.current_city %></td>
+        <td><%= contact.region_name %></td>
+        <td><%= link_to "Show", contact_path(contact) %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/views/rails/contact/contacts/new.html.erb

@@ -0,0 +1,3 @@
+<h1>New Contact</h1>
+<%= render "form", contact: @contact %>
+<%= link_to "Back", contacts_path %>