airtable_sync 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8591433d500307558e933d3861df761d6da9434a51628ae0a961410cfc85d552
+  data.tar.gz: ce375ba7fbc498b4e46cc93cb25c824c1e216ee9dd0e46ddd7f15396b2bbbf54
+SHA512:
+  metadata.gz: 73d23e7524abcbcad6b7bbc5a428cd06135fb3344f5ddaf9299b9392bef7f6d93fc1066985b6d57abcf955b08d466f4a765e59ffad16ca7fe04a5a5fa0509f7e
+  data.tar.gz: 408e6f38899dac41d6638da0dba2d1007f94a1b10bb5c7df4fc99f33c77ebdc1d94f0578bf03f5e2b651b5f4ba94d7020b52715f8a3ee0cd05037e6f29f22be0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2023 Viktor
+
+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,175 @@
+[![Build Status](https://github.com/vfonic/airtable_sync/workflows/build/badge.svg)](https://github.com/vfonic/airtable_sync/actions)
+
+# AirtableSync
+
+Keep your Ruby on Rails records in sync with AirTable.
+
+Currently only one way Rails => AirTable synchronization.
+
+For the latest changes, see the [CHANGELOG.md](CHANGELOG.md).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'airtable_sync'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Then run the install generator:
+
+```bash
+bundle exec rails generate airtable_sync:install
+```
+
+## Usage
+
+1. Generate AirTable API key
+   https://airtable.com/create/apikey
+2.
+
+### Configuration options
+
+In `config/initializers/airtable_sync.rb` you can specify configuration options:
+
+1. `api_key`
+2. `webflow_site_id`
+3. `skip_airtable_sync` - skip synchronization for different environments.
+
+Example:
+
+```rb
+AirtableSync.configure do |config|
+  config.api_key = ENV.fetch('AIRTABLE_API_KEY')
+  config.skip_airtable_sync = ActiveModel::Type::Boolean.new.cast(ENV.fetch('SKIP_AIRTABLE_SYNC'))
+end
+```
+
+### Add AirtableSync to models
+
+For each model that you want to sync to AirTable, you need to run the connection generator:
+
+```bash
+bundle exec rails generate airtable_sync:connection Article
+```
+
+Please note that this _does not_ create the AirTable table. You need to already have it or create it manually.
+
+### Create AirTable tables
+
+As mentioned above, you need to create the AirTable tables yourself.
+
+### Set `airtable_base_id`
+
+There are couple of ways how you can set the `airtable_base_id` to be used.
+
+#### Set `airtable_base_id` through configuration
+
+In `config/initializers/airtable_sync.rb` you can specify `airtable_base_id`:
+
+```ruby
+AirtableSync.configure do |config|
+  config.airtable_base_id = ENV.fetch('AIRTABLE_BASE_ID')
+end
+```
+
+### Customize fields to synchronize
+
+By default, AirtableSync calls `#as_airtable_json` on a record to get the fields that it needs to push to AirTable. `#as_airtable_json` simply calls `#as_json` in its default implementation. To change this behavior, you can override `#as_airtable_json` in your model:
+
+```ruby
+# app/models/article.rb
+class Article < ApplicationRecord
+  include AirtableSync::RecordSync
+
+  def as_airtable_json
+    {
+      'Post Title': self.title.capitalize,
+      'Short Description': self.title.parameterize,
+      'Long Description': self.created_at,
+    }
+  end
+end
+```
+
+### Sync a Rails model to different AirTable table
+
+If AirTable table name does not match the Rails model collection name, you need to specify table name for each `CreateRecordJob`, `DestroyRecordJob`, and `UpdateRecordJob` call. If not specified, model collection name is used as the table name.
+You also need to replace included `AirtableSync::RecordSync` with custom callbacks that will call appropriate AirtableSync jobs.
+
+For example:
+
+```ruby
+AirtableSync::CreateRecordJob.perform_later(model_name, id, table_name)
+AirtableSync::UpdateRecordJob.perform_later(model_name, id, table_name)
+AirtableSync::DestroyRecordJob.perform_later(table_name:, airtable_id:)
+```
+
+Where:
+
+1.  `model_name` - Rails model with `airtable_id` column
+2.  `table_name` - AirTable table name (defaults to: `model_name.underscore.pluralize.humanize`)
+
+For example:
+
+```ruby
+AirtableSync::CreateRecordJob.perform_now('articles', 1, 'Stories')
+```
+
+Or, if you want to use the default 'articles' table name:
+
+```ruby
+AirtableSync::CreateRecordJob.perform_now('articles', 1)
+```
+
+### Run the initial sync
+
+After setting up which models you want to sync to AirTable, you can run the initial sync for each of the models:
+
+```ruby
+AirtableSync::InitialSyncJob.perform_later('articles')
+```
+
+You can also run this from a Rake task:
+
+```ruby
+bundle exec rails "airtable_sync:initial_sync[articles]"
+```
+
+Quotes are needed in order for this to work in all shells.
+
+### Important note
+
+This gem silently "fails" (does nothing) when `airtable_base_id` or `airtable_id` is `nil`! This is not always desired behavior so be aware of that.
+
+## Contributing
+
+PRs welcome!
+
+To run RuboCop style check and RSpec tests run:
+
+```sh
+bundle exec rake
+```
+
+To run only RuboCop run:
+
+```sh
+bundle exec rails style
+```
+
+To run RSpec tests run:
+
+```sh
+bundle exec spec
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'stylecheck/rake_tasks' unless Rails.env.production?
+
+load 'rspec/rails/tasks/rspec.rake'
+task :default do
+  Rake::Task['style:rubocop:run'].execute
+  Rake::Task['spec'].execute
+end

data/app/jobs/airtable_sync/create_record_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  class CreateRecordJob < ApplicationJob
+    # AirTable table name should be in plural form.
+    # 'JobListing'.underscore.pluralize.humanize => "Job listings"
+    # 'job_listing'.underscore.pluralize.humanize => "Job listings"
+    # We can sync Rails model that has different class name than its AirTable table name
+    # model_name => Rails model that has airtable_id column
+    # table_name => AirTable table name
+    # model_name = 'Article'; id = article.id, table_name = 'Posts'
+    def perform(model_name, id, table_name = model_name.underscore.pluralize.humanize)
+      model_class = model_name.underscore.classify.constantize
+      record = model_class.find_by(id:)
+      return if record.blank?
+      return if record.airtable_base_id.blank?
+
+      AirtableSync::Api.new(record.airtable_base_id).create_record(record, table_name)
+    end
+  end
+end

data/app/jobs/airtable_sync/destroy_record_job.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  class DestroyRecordJob < ApplicationJob
+    def perform(table_name:, airtable_base_id:, airtable_id:)
+      return if airtable_base_id.blank?
+      return if airtable_id.blank?
+
+      AirtableSync::Api.new(airtable_base_id).delete_record(table_name, airtable_id)
+    end
+  end
+end

data/app/jobs/airtable_sync/initial_sync_job.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  class InitialSyncJob < ApplicationJob
+    def perform(table_name)
+      model_class = table_name.underscore.classify.constantize
+      model_class.where(airtable_id: nil).find_each do |record|
+        next if record.airtable_base_id.blank?
+
+        client(record.airtable_base_id).create_record(record, table_name)
+      end
+    end
+
+    private
+
+      def client(site_id)
+        if @client&.site_id == site_id
+          @client
+        else
+          @client = AirtableSync::Api.new(site_id)
+        end
+      end
+  end
+end

data/app/jobs/airtable_sync/update_record_job.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  class UpdateRecordJob < ApplicationJob
+    # AirTable table name should be in plural form.
+    # 'JobListing'.underscore.pluralize.humanize => 'Job listings'
+    # 'job_listing'.underscore.pluralize.humanize => 'Job listings'
+    def perform(model_name, id, table_name = model_name.underscore.pluralize.humanize)
+      model_class = model_name.underscore.classify.constantize
+      record = model_class.find_by(id:)
+      return if record.blank?
+      return if record.airtable_base_id.blank?
+      return AirtableSync::CreateRecordJob.perform_now(model_name, id, table_name) if record.airtable_id.blank?
+
+      AirtableSync::Api.new(record.airtable_base_id).update_record(record, table_name)
+    end
+  end
+end

data/app/models/concerns/airtable_sync/callbacks.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Synchronizes any changes to public records to AirTable
+module AirtableSync
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :skip_airtable_sync
+
+      after_commit :create_airtable_record, on: :create
+      after_commit :update_airtable_record, on: :update
+      after_commit :destroy_airtable_record, on: :destroy
+
+      def create_airtable_record
+        return if should_skip_sync?
+
+        AirtableSync::CreateRecordJob.perform_later(self.model_name.collection, self.id)
+      end
+
+      def update_airtable_record
+        return if should_skip_sync?
+
+        AirtableSync::UpdateRecordJob.perform_later(self.model_name.collection, self.id)
+      end
+
+      def destroy_airtable_record
+        return if should_skip_sync?
+
+        # Make sure table name is in the plural form
+        table_name = self.model_name.collection.underscore.humanize
+
+        AirtableSync::DestroyRecordJob.perform_later(table_name:, airtable_base_id:, airtable_id:)
+      end
+
+      private
+
+        def should_skip_sync? = AirtableSync.configuration.skip_airtable_sync || self.skip_airtable_sync || self.airtable_base_id.blank?
+    end
+  end
+end

data/app/models/concerns/airtable_sync/record_sync.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Synchronizes any changes to public records to AirTable
+module AirtableSync
+  module RecordSync
+    extend ActiveSupport::Concern
+
+    included do
+      include AirtableSync::Callbacks
+
+      # override this method to get more granular, per site customization
+      # for example, you could have Site model in your codebase:
+      #
+      # class Site < ApplicationRecord
+      #   has_many :articles
+      # end
+      #
+      # class Article < ApplicationRecord
+      #   belongs_to :site
+      #
+      #   def airtable_base_id
+      #     self.site.airtable_base_id
+      #   end
+      # end
+      #
+      def airtable_base_id = AirtableSync.configuration.airtable_base_id
+
+      # You can customize this to your liking:
+      # def as_airtable_json
+      #   {
+      #     title: self.title.capitalize,
+      #     slug: self.title.parameterize,
+      #     published_at: self.created_at,
+      #     image: self.image_url
+      #   }
+      # end
+      def as_airtable_json = self.as_json
+    end
+  end
+end

data/app/services/airtable_sync/api.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  class Api
+    attr_reader :base_id
+
+    def initialize(base_id)
+      @base_id = base_id
+    end
+
+    def get_all_items(table_name:) = table(table_name).all
+
+    def get_item(table_name, airtable_id) = table(table_name).find(airtable_id)
+
+    def create_record(record, table_name)
+      airtable_record = table(table_name).create(record.as_airtable_json) # rubocop:disable Rails/SaveBang
+      record.update_column(:airtable_id, airtable_record.id) # rubocop:disable Rails/SkipsModelValidations
+    end
+
+    def update_record(record, table_name)
+      airtable_record = table(table_name).find(record.airtable_id)
+      record.as_airtable_json.each { |key, value| airtable_record[key.to_s] = value }
+      airtable_record.save # rubocop:disable Rails/SaveBang
+    end
+
+    def delete_record(table_name, airtable_id) = table(table_name).find(airtable_id).destroy
+
+    private
+
+      def table(table_name) = Airrecord.table(AirtableSync.configuration.api_key, base_id, table_name)
+  end
+end

data/lib/airtable_sync/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  class << self
+    attr_reader :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+
+      self.configuration.skip_airtable_sync = !Rails.env.production?
+
+      yield(self.configuration)
+
+      self.configuration.api_key ||= ENV.fetch('AIRTABLE_API_KEY')
+    end
+
+    private
+
+      attr_writer :configuration
+  end
+
+  class Configuration
+    attr_accessor :skip_airtable_sync, :airtable_base_id, :api_key
+  end
+end

data/lib/airtable_sync/engine.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/airtable_sync/railtie.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/airtable_sync/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  VERSION = '1.0.0'
+end

data/lib/airtable_sync.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'airtable_sync/version'
+require 'airtable_sync/configuration'
+require 'airtable_sync/engine'
+require 'airrecord'
+
+module AirtableSync
+end
+
+module Airrecord
+  class Client
+    def escape(*args) = ERB::Util.url_encode(*args)
+  end
+end

data/lib/generators/airtable_sync/connection_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'rails/generators/active_record'
+
+module AirtableSync
+  module Generators
+    class ConnectionGenerator < Rails::Generators::NamedBase
+      desc 'Registers ActiveRecord model to sync to AirTable table'
+
+      source_root File.expand_path('templates', __dir__)
+
+      include Rails::Generators::Migration
+      def add_migration
+        migration_template 'migration.rb.erb', "#{migration_path}/add_airtable_id_to_#{table_name}.rb",
+                           migration_version:
+      end
+
+      def include_record_sync_in_model_file
+        module_snippet = <<~END_OF_INCLUDE.indent(2)
+
+          include AirtableSync::RecordSync
+        END_OF_INCLUDE
+
+        insert_into_file "app/models/#{name.underscore}.rb", module_snippet, after: / < ApplicationRecord$/
+      end
+
+      def self.next_migration_number(dirname) = ActiveRecord::Generators::Base.next_migration_number(dirname)
+
+      private
+
+        def migration_path = ActiveRecord::Migrator.migrations_paths.first
+
+        def migration_version = "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+    end
+  end
+end

data/lib/generators/airtable_sync/install_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module AirtableSync
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def add_config_initializer
+        template 'airtable_sync.rb', 'config/initializers/airtable_sync.rb'
+      end
+    end
+  end
+end

data/lib/generators/airtable_sync/templates/airtable_sync.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+AirtableSync.configure do |config|
+  # config.api_key = ENV.fetch('AIRTABLE_API_KEY')
+  # config.skip_airtable_sync = !Rails.env.production?
+  config.airtable_base_id = ENV.fetch('AIRTABLE_BASE_ID')
+end

data/lib/generators/airtable_sync/templates/migration.rb.erb

@@ -0,0 +1,6 @@
+class AddAirtableIdTo<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :<%= table_name %>, :airtable_id, :string
+    add_index :<%= table_name %>, :airtable_id, unique: true
+  end
+end

data/lib/tasks/airtable_sync.rake

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+namespace :airtable_sync do
+  desc 'Perform initial sync from Rails to AirTable'
+  task :initial_sync, %i[table_name] => :environment do |_task, args|
+    AirtableSync::InitialSyncJob.perform_later(args[:table_name])
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: airtable_sync
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Viktor
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-02-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: airrecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: sprockets-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- viktor.fonic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/jobs/airtable_sync/create_record_job.rb
+- app/jobs/airtable_sync/destroy_record_job.rb
+- app/jobs/airtable_sync/initial_sync_job.rb
+- app/jobs/airtable_sync/update_record_job.rb
+- app/models/concerns/airtable_sync/callbacks.rb
+- app/models/concerns/airtable_sync/record_sync.rb
+- app/services/airtable_sync/api.rb
+- lib/airtable_sync.rb
+- lib/airtable_sync/configuration.rb
+- lib/airtable_sync/engine.rb
+- lib/airtable_sync/railtie.rb
+- lib/airtable_sync/version.rb
+- lib/generators/airtable_sync/connection_generator.rb
+- lib/generators/airtable_sync/install_generator.rb
+- lib/generators/airtable_sync/templates/airtable_sync.rb
+- lib/generators/airtable_sync/templates/migration.rb.erb
+- lib/tasks/airtable_sync.rake
+homepage: https://github.com/vfonic/airtable_sync
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/vfonic/airtable_sync
+  source_code_uri: https://github.com/vfonic/airtable_sync
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Keep Rails models in sync with AirTable.
+test_files: []