vindi-rails-integrations 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac62896e691574d5b96e6ed7b00e2456222db8b7d575393199e1e5d2f982aaaf
-  data.tar.gz: 95876321b904170ac20f12163240fa140fecf3747f3383e725220b16fdf8b7e9
+  metadata.gz: dcb347a77cfd8b20150b4469c8c2a0d5d18f09a95f832f5bd945ba72a3db44e4
+  data.tar.gz: ed3bc0bf9c62a9eb40c621573f66b92f094a924e98d0e6ebe07a67601d1b73d1
 SHA512:
-  metadata.gz: 7dfcb70a8753f6a6272b82d4e8f71d23542a4400e45b4b5860b9291aeef90424ffe5178d1e47e7c2da3d06178b90f8ef086da7dbe067ef9213650d2805f288f9
-  data.tar.gz: 9d1ab6461d8d9e41e8825b6c1d4fc521496c80ee68dca3d27d76ac04f99e30de7e3fad58b10ed156011baa37aa423e877c7fd6eabe33493202e7afb476892aa7
+  metadata.gz: c5b72856876005e684c701c7fb001826210c726d827b8bfa802537131b3d9e0b77a6086bc1659d9a69c8a4c210665e4944e116851e8ae548f0c53a5bca3991e6
+  data.tar.gz: 897c26195875b0b4e213b8f80b01e3761820ca0a694d0f1f5f4490b0c361b9bc4e6d4831a043e9af7032d2811fbe9adf57e9f6ee6b942d9b2cb3ccd8c287107d

data/README.md

@@ -46,6 +46,25 @@ bundle exec rails generate vindi:sync User
 ```
 This generates a database migration to add `vindi_customer_id` and includes the `Vindi::Synchronizable` concern into your model.
 
+#### Resilient Transactional Outbox Sync (Optional)
+To prevent network latencies or API downtime from blocking your local database transactions, you can enable the Outbox pattern. This saves the synchronization tasks locally in a database table during the transaction, and processes them asynchronously.
+
+1. **Generate the Outbox migration**:
+   ```bash
+   bundle exec rails generate vindi:outbox
+   bundle exec rails db:migrate
+   ```
+2. **Enable Outbox** in your initializer:
+   ```ruby
+   Vindi.configure do |config|
+     config.use_outbox = true
+   end
+   ```
+3. **Processing**: The `Vindi::ProcessPendingSyncsJob` is automatically queued to run in the background after the model commits. You can also run it manually or schedule it:
+   ```ruby
+   Vindi::ProcessPendingSyncsJob.perform_later
+   ```
+
 ### 3. Rake Tasks
 - **`bundle exec rake vindi:status`**: Verifies API configuration, environment, credentials (safely masked), and tests connection to Vindi.
 - **`bundle exec rake vindi:audit model=User`**: Reconciles database records against the Vindi API to detect missing or mismatched records.

data/lib/generators/vindi/outbox_generator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Vindi
+  module Generators
+    class OutboxGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates migration to store transactional outbox pending synchronization tasks"
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template "outbox_migration.rb", "db/migrate/create_vindi_pending_syncs.rb"
+      end
+    end
+  end
+end

data/lib/generators/vindi/templates/outbox_migration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateVindiPendingSyncs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :vindi_pending_syncs do |t|
+      t.string :item_type, null: false
+      t.string :item_id, null: false
+      t.string :action, null: false
+      t.text :params
+      t.string :status, null: false, default: "pending"
+      t.integer :attempts, null: false, default: 0
+      t.text :last_error
+
+      t.timestamps
+    end
+
+    add_index :vindi_pending_syncs, [:status, :attempts]
+    add_index :vindi_pending_syncs, [:item_type, :item_id]
+  end
+end

data/lib/vindi/integrations/concerns/synchronizable.rb

@@ -1,65 +1,121 @@
-# frozen_string_literal: true
-
-module Vindi
-  module Synchronizable
-    extend ActiveSupport::Concern
-
-    included do
-      after_commit :create_vindi_customer, on: :create, unless: :vindi_customer_id?
-      after_commit :update_vindi_customer, on: :update, if: :should_sync_vindi_update?
-    end
-
-    def sync_vindi_customer!
-      return if vindi_customer_id?
-
-      params = vindi_customer_attributes
-      customer = Vindi::Customer.create(params)
-      
-      update_columns(vindi_customer_id: customer.id.to_s)
-    rescue Vindi::Error => e
-      Rails.logger.error("Failed to sync customer to Vindi: #{e.message}")
-    end
-
-    def update_vindi_customer!
-      return unless vindi_customer_id?
-
-      params = vindi_customer_attributes
-      Vindi::Customer.update(vindi_customer_id, params)
-    rescue Vindi::Error => e
-      Rails.logger.error("Failed to update customer in Vindi: #{e.message}")
-    end
-
-    private
-
-    def create_vindi_customer
-      # Run in background or synchronously based on configuration
-      sync_vindi_customer!
-    end
-
-    def update_vindi_customer
-      update_vindi_customer!
-    end
-
-    def should_sync_vindi_update?
-      vindi_customer_id? && (saved_change_to_name? || saved_change_to_email?)
-    end
-
-    # Default attributes mapping. Override this in the ActiveRecord model
-    # to customize parameters sent to Vindi (like registry_code, phone, etc.)
-    def vindi_customer_attributes
-      {
-        name: try(:name),
-        email: try(:email),
-        code: id.to_s
-      }
-    end
-  end
-end
-module Vindi
-  module Integrations
-    # Auto-load the concern when rails loads
-    ActiveSupport.on_load(:active_record) do
-      include Vindi::Synchronizable
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Vindi
+  module Synchronizable
+    extend ActiveSupport::Concern
+
+    included do
+      after_create :record_vindi_create_pending_sync, if: :use_vindi_outbox?
+      after_update :record_vindi_update_pending_sync, if: :should_record_vindi_update_sync?
+
+      after_commit :create_vindi_customer, on: :create, if: :should_sync_vindi_create?
+      after_commit :update_vindi_customer, on: :update, if: :should_sync_vindi_update?
+    end
+
+    def sync_vindi_customer!
+      return unless synchronizable?
+      return if vindi_customer_id?
+
+      params = vindi_customer_attributes
+      customer = Vindi::Customer.create(params)
+      
+      update_columns(vindi_customer_id: customer.id.to_s)
+    rescue Vindi::Error => e
+      Rails.logger.error("Failed to sync customer to Vindi: #{e.message}")
+    end
+
+    def update_vindi_customer!
+      return unless synchronizable?
+      return unless vindi_customer_id?
+
+      params = vindi_customer_attributes
+      Vindi::Customer.update(vindi_customer_id, params)
+    rescue Vindi::Error => e
+      Rails.logger.error("Failed to update customer in Vindi: #{e.message}")
+    end
+
+    def use_vindi_outbox?
+      synchronizable? && Vindi.configuration.respond_to?(:use_outbox) && Vindi.configuration.use_outbox
+    end
+
+    def synchronizable?
+      respond_to?(:vindi_customer_id) && self.class.name != "Vindi::PendingSync"
+    end
+
+    private
+
+    def create_vindi_customer
+      return unless synchronizable?
+      if use_vindi_outbox?
+        enqueue_vindi_outbox_processing
+      else
+        sync_vindi_customer!
+      end
+    end
+
+    def update_vindi_customer
+      return unless synchronizable?
+      if use_vindi_outbox?
+        enqueue_vindi_outbox_processing
+      else
+        update_vindi_customer!
+      end
+    end
+
+    def should_sync_vindi_create?
+      synchronizable? && !vindi_customer_id?
+    end
+
+    def should_sync_vindi_update?
+      synchronizable? && vindi_customer_id? && (saved_change_to_name? || saved_change_to_email?)
+    end
+
+    def record_vindi_create_pending_sync
+      return unless synchronizable?
+      Vindi::PendingSync.create!(
+        item_type: self.class.name,
+        item_id: id,
+        action: "create",
+        params: vindi_customer_attributes,
+        status: "pending"
+      )
+    end
+
+    def record_vindi_update_pending_sync
+      return unless synchronizable?
+      Vindi::PendingSync.create!(
+        item_type: self.class.name,
+        item_id: id,
+        action: "update",
+        params: vindi_customer_attributes,
+        status: "pending"
+      )
+    end
+
+    def should_record_vindi_update_sync?
+      use_vindi_outbox? && should_sync_vindi_update?
+    end
+
+    def enqueue_vindi_outbox_processing
+      Vindi::ProcessPendingSyncsJob.perform_later
+    end
+
+    # Default attributes mapping. Override this in the ActiveRecord model
+    # to customize parameters sent to Vindi (like registry_code, phone, etc.)
+    def vindi_customer_attributes
+      {
+        name: try(:name),
+        email: try(:email),
+        code: id.to_s
+      }
+    end
+  end
+end
+module Vindi
+  module Integrations
+    # Auto-load the concern when rails loads
+    ActiveSupport.on_load(:active_record) do
+      include Vindi::Synchronizable
+    end
+  end
+end

data/lib/vindi/integrations/pending_sync.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Vindi
+  class PendingSync < ActiveRecord::Base
+    self.table_name = "vindi_pending_syncs"
+
+    if ActiveRecord.version >= Gem::Version.new("7.1.0")
+      serialize :params, coder: JSON
+    else
+      serialize :params, JSON
+    end
+
+    validates :item_type, :item_id, :action, :status, presence: true
+    validates :status, inclusion: { in: %w[pending processing processed failed] }
+
+    scope :pending, -> { where(status: "pending") }
+    scope :failed, -> { where(status: "failed") }
+    scope :retryable, ->(max_attempts = 5) { where(status: %w[pending failed]).where("attempts < ?", max_attempts) }
+  end
+end

data/lib/vindi/integrations/version.rb

@@ -2,6 +2,6 @@
 
 module Vindi
   module Integrations
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/vindi/jobs/process_pending_syncs_job.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Vindi
+  class ProcessPendingSyncsJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(pending_sync_id = nil)
+      if pending_sync_id
+        pending_sync = Vindi::PendingSync.find_by(id: pending_sync_id)
+        process_sync(pending_sync) if pending_sync
+      else
+        Vindi::PendingSync.retryable.find_each do |sync|
+          process_sync(sync)
+        end
+      end
+    end
+
+    private
+
+    def process_sync(pending_sync)
+      return unless retryable?(pending_sync)
+
+      pending_sync.update!(status: "processing")
+      item = find_local_item(pending_sync)
+
+      if item.nil?
+        pending_sync.update!(status: "failed", last_error: "Record not found locally: #{pending_sync.item_type}##{pending_sync.item_id}")
+        return
+      end
+
+      execute_api_call!(pending_sync, item)
+      pending_sync.update!(status: "processed", last_error: nil)
+    rescue StandardError => e
+      handle_sync_failure(pending_sync, e)
+    end
+
+    def retryable?(pending_sync)
+      %w[pending failed].include?(pending_sync.status)
+    end
+
+    def find_local_item(pending_sync)
+      pending_sync.item_type.constantize.find_by(id: pending_sync.item_id)
+    end
+
+    def execute_api_call!(pending_sync, item)
+      case pending_sync.action
+      when "create", "update"
+        sync_to_vindi(item.vindi_customer_id, pending_sync.params, item)
+      else
+        raise ArgumentError, "Unknown action #{pending_sync.action.inspect}. Expected 'create' or 'update'."
+      end
+    end
+
+    def sync_to_vindi(customer_id, params, item)
+      if customer_id.present?
+        Vindi::Customer.update(customer_id, params)
+      else
+        customer = Vindi::Customer.create(params)
+        item.update_columns(vindi_customer_id: customer.id.to_s)
+      end
+    end
+
+    def handle_sync_failure(pending_sync, error)
+      new_attempts = pending_sync.attempts + 1
+      status = new_attempts >= 5 ? "failed" : "pending"
+      pending_sync.update!(
+        status: status,
+        attempts: new_attempts,
+        last_error: "#{error.class}: #{error.message}"
+      )
+    end
+  end
+end

data/lib/vindi-rails-integrations.rb

@@ -1,13 +1,19 @@
-# frozen_string_literal: true
-
-require "vindi"
-require_relative "vindi/integrations/version"
-require_relative "vindi/integrations/diagnostics"
-require_relative "vindi/integrations/railtie" if defined?(Rails)
-require_relative "vindi/integrations/concerns/synchronizable" if defined?(ActiveRecord)
-
-module Vindi
-  module Integrations
-    class Error < StandardError; end
-  end
-end
+# frozen_string_literal: true
+
+require "vindi"
+require_relative "vindi/integrations/version"
+require_relative "vindi/integrations/diagnostics"
+require_relative "vindi/integrations/railtie" if defined?(Rails)
+require_relative "vindi/integrations/concerns/synchronizable" if defined?(ActiveRecord)
+require_relative "vindi/integrations/pending_sync" if defined?(ActiveRecord)
+require_relative "vindi/jobs/process_pending_syncs_job" if defined?(ActiveJob)
+
+module Vindi
+  class Configuration
+    attr_accessor :use_outbox
+  end
+
+  module Integrations
+    class Error < StandardError; end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vindi-rails-integrations
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Wesley Lima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-12 00:00:00.000000000 Z
+date: 2026-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: vindi-rails
@@ -145,9 +145,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- lib/generators/vindi/outbox_generator.rb
 - lib/generators/vindi/sync_generator.rb
 - lib/generators/vindi/templates/base_handler.rb
 - lib/generators/vindi/templates/migration.rb
+- lib/generators/vindi/templates/outbox_migration.rb
 - lib/generators/vindi/templates/webhook_handler.rb
 - lib/generators/vindi/templates/webhook_job.rb
 - lib/generators/vindi/templates/webhooks_controller.rb
@@ -157,8 +159,10 @@ files:
 - lib/vindi-rails-integrations.rb
 - lib/vindi/integrations/concerns/synchronizable.rb
 - lib/vindi/integrations/diagnostics.rb
+- lib/vindi/integrations/pending_sync.rb
 - lib/vindi/integrations/railtie.rb
 - lib/vindi/integrations/version.rb
+- lib/vindi/jobs/process_pending_syncs_job.rb
 homepage: https://github.com/wesleyskap/vindi-rails-integrations
 licenses:
 - MIT