vindi-rails-integrations 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dd230e91c45c3972312a8c56b152b87b6cd5160cd306456cdf3404ce90b74b9
-  data.tar.gz: 9b0cb8eec04493f2f3547c6d8a05b8b409c70ff18d42e1e9d53c99dfa781e1be
+  metadata.gz: ac62896e691574d5b96e6ed7b00e2456222db8b7d575393199e1e5d2f982aaaf
+  data.tar.gz: 95876321b904170ac20f12163240fa140fecf3747f3383e725220b16fdf8b7e9
 SHA512:
-  metadata.gz: 43fabc5a71557ac8ca880d9d7be71cea5908a6c9d76b24e94d28feddc1720748a649afecd0202434c77403e11c2b8587114a3983be330162e8b72a11bc2cb915
-  data.tar.gz: b92a4cf06a918e309e842ca9de25aee365c7b477455bbdb4646d30963bf45cdfa5dfad425d4b2c9aa97403b6a5adcb5cc994b609689c3b390235918f6c4cd250
+  metadata.gz: 7dfcb70a8753f6a6272b82d4e8f71d23542a4400e45b4b5860b9291aeef90424ffe5178d1e47e7c2da3d06178b90f8ef086da7dbe067ef9213650d2805f288f9
+  data.tar.gz: 9d1ab6461d8d9e41e8825b6c1d4fc521496c80ee68dca3d27d76ac04f99e30de7e3fad58b10ed156011baa37aa423e877c7fd6eabe33493202e7afb476892aa7

data/README.md

@@ -1,48 +1,59 @@
-# Vindi Rails Integrations
-
-[Leia em Português (README.pt-BR.md)](./README.pt-BR.md)
-
-An extension gem for the [vindi-rails](https://github.com/wesleyskap/vindi-rails) core SDK, providing backend integrations such as automatic ActiveRecord model synchronization, webhook controller endpoints, asynchronous processing jobs, and verification Rake tasks.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'vindi-rails-integrations'
-```
-
-## Features & Usage
-
-### 1. Webhook Setup
-To handle incoming webhook events asynchronously with built-in access token verification:
-```bash
-bundle exec rails generate vindi:webhook
-```
-This generates:
-- `Vindi::WebhooksController` (`app/controllers/vindi/webhooks_controller.rb`)
-- `Vindi::WebhookJob` (`app/jobs/vindi/webhook_job.rb`)
-
-Configure your webhook access token in your environment files:
-```bash
-ENV["VINDI_WEBHOOK_TOKEN"] = "YOUR_SECURE_TOKEN"
-```
-
-### 2. ActiveRecord Model Sync
-To automatically synchronize local models (e.g. `User`) with Vindi Customers:
-```bash
-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.
-
-### 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.
-- **`bundle exec rake vindi:test_webhook event=bill_paid`**: Simulates sending a webhook event payload directly to your local endpoint.
-
-## Running Tests
-
-To run the Minitest suite:
-```bash
-bundle exec rake test
-```
+# Vindi Rails Integrations
+
+[Leia em Português (README.pt-BR.md)](./README.pt-BR.md)
+
+An extension gem for the [vindi-rails](https://github.com/wesleyskap/vindi-rails) core SDK, providing backend integrations such as automatic ActiveRecord model synchronization, webhook controller endpoints, asynchronous processing jobs, and verification Rake tasks.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'vindi-rails-integrations'
+```
+
+## Features & Usage
+
+### 1. Webhook Setup
+To handle incoming webhook events asynchronously with built-in access token verification:
+```bash
+bundle exec rails generate vindi:webhook
+```
+This generates:
+- `Vindi::WebhooksController` (`app/controllers/vindi/webhooks_controller.rb`)
+- `Vindi::WebhookJob` (`app/jobs/vindi/webhook_job.rb`)
+
+Configure your webhook access token in your environment files:
+```bash
+ENV["VINDI_WEBHOOK_TOKEN"] = "YOUR_SECURE_TOKEN"
+```
+
+#### Modular Webhook Handlers
+Instead of processing all webhook events inside a single `WebhookJob`, you can generate modular event-specific handlers:
+```bash
+bundle exec rails generate vindi:webhook_handler subscription_canceled
+```
+This generates:
+- `Vindi::Webhooks::BaseHandler` (`app/services/vindi/webhooks/base_handler.rb`) - created once if missing.
+- `Vindi::Webhooks::SubscriptionCanceledHandler` (`app/services/vindi/webhooks/subscription_canceled_handler.rb`)
+
+The main `WebhookJob` automatically detects and forwards the event payload to matching handlers (e.g. `Vindi::Webhooks::SubscriptionCanceledHandler` for `subscription_canceled` events) with safe fallback to legacy inline handlers.
+
+### 2. ActiveRecord Model Sync
+To automatically synchronize local models (e.g. `User`) with Vindi Customers:
+```bash
+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.
+
+### 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.
+- **`bundle exec rake vindi:test_webhook event=bill_paid`**: Simulates sending a webhook event payload directly to your local endpoint.
+
+## Running Tests
+
+To run the Minitest suite:
+```bash
+bundle exec rake test
+```

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Vindi
+  module Webhooks
+    class BaseHandler
+      attr_reader :event_payload
+
+      def initialize(event_payload)
+        @event_payload = event_payload
+      end
+
+      def call
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Vindi
+  module Webhooks
+    class <%= class_name %>Handler < BaseHandler
+      def call
+        # Implement dynamic business action logic for <%= file_name %> event here.
+        # Access the event details via `event_payload`.
+        # Example:
+        # Rails.logger.info "Processing <%= file_name %> with payload: #{event_payload.inspect}"
+      end
+    end
+  end
+end

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

@@ -1,75 +1,92 @@
-# frozen_string_literal: true
-
-module Vindi
-  # =========================================================================
-  # VINDI WEBHOOK PAYLOAD STRUCTURE EXAMPLE:
-  # {
-  #   event: {
-  #     id: 123456,                      # Unique ID for the webhook event (useful for idempotency)
-  #     type: "bill_paid",               # Type of event (e.g. subscription_created, bill_paid, charge_rejected)
-  #     created_at: "2026-06-10T15:00:00.000-03:00",
-  #     data: {                          # Object data (context depends on the event type)
-  #       bill: {
-  #         id: 555,
-  #         amount: "100.00",
-  #         status: "paid",
-  #         customer: { id: 123, email: "john@example.com", code: "app_user_id" },
-  #         charges: [...]
-  #       }
-  #     }
-  #   }
-  # }
-  # =========================================================================
-  class WebhookJob < ActiveJob::Base
-    queue_as :default
-
-    def perform(payload)
-      event_id = payload.dig(:event, :id)
-      event_type = payload.dig(:event, :type)
-
-      # BEST PRACTICE 1: Idempotency Check
-      # Check if this event_id has already been processed to avoid duplicate actions.
-      return if already_processed?(event_id)
-
-      process_event(event_type, payload.dig(:event, :data))
-      
-      # BEST PRACTICE 2: Record that this event was successfully processed
-      mark_as_processed!(event_id)
-    end
-
-    private
-
-    def process_event(event_type, data)
-      case event_type
-      when "subscription_created"
-        handle_subscription_created(data[:subscription])
-      when "bill_paid"
-        handle_bill_paid(data[:bill])
-      else
-        logger.info "Unhandled Vindi webhook event: #{event_type}"
-      end
-    end
-
-    # BEST PRACTICE 3: Safe target state validations (e.g. ignore if already active/paid)
-    def handle_subscription_created(subscription_data)
-      return if subscription_data.nil?
-      # e.g., Find local tenant/user using subscription_data[:customer][:code]
-      # and activate their account.
-    end
-
-    def handle_bill_paid(bill_data)
-      return if bill_data.nil?
-      # e.g., Find local invoice by bill_data[:id]
-      # and mark as paid. Check first if it isn't already paid.
-    end
-
-    def already_processed?(event_id)
-      # e.g., VindiWebhookEvent.exists?(vindi_event_id: event_id)
-      false
-    end
-
-    def mark_as_processed!(event_id)
-      # e.g., VindiWebhookEvent.create!(vindi_event_id: event_id, processed_at: Time.current)
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Vindi
+  # =========================================================================
+  # VINDI WEBHOOK PAYLOAD STRUCTURE EXAMPLE:
+  # {
+  #   event: {
+  #     id: 123456,                      # Unique ID for the webhook event (useful for idempotency)
+  #     type: "bill_paid",               # Type of event (e.g. subscription_created, bill_paid, charge_rejected)
+  #     created_at: "2026-06-10T15:00:00.000-03:00",
+  #     data: {                          # Object data (context depends on the event type)
+  #       bill: {
+  #         id: 555,
+  #         amount: "100.00",
+  #         status: "paid",
+  #         customer: { id: 123, email: "john@example.com", code: "app_user_id" },
+  #         charges: [...]
+  #       }
+  #     }
+  #   }
+  # }
+  # =========================================================================
+  class WebhookJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(payload)
+      event_id = payload.dig(:event, :id)
+      event_type = payload.dig(:event, :type)
+
+      # BEST PRACTICE 1: Idempotency Check
+      # Check if this event_id has already been processed to avoid duplicate actions.
+      return if already_processed?(event_id)
+
+      process_event(event_type, payload.dig(:event, :data))
+      
+      # BEST PRACTICE 2: Record that this event was successfully processed
+      mark_as_processed!(event_id)
+    end
+
+    private
+
+    def process_event(event_type, data)
+      handler_klass = find_handler_class(event_type)
+      if handler_klass
+        handler_klass.new(data).call
+      else
+        fallback_process_event(event_type, data)
+      end
+    end
+
+    def find_handler_class(event_type)
+      return if event_type.blank?
+
+      "Vindi::Webhooks::#{event_type.camelize}Handler".safe_constantize
+    rescue NameError
+      nil
+    end
+
+    def fallback_process_event(event_type, data)
+      case event_type
+      when "subscription_created"
+        handle_subscription_created(data[:subscription])
+      when "bill_paid"
+        handle_bill_paid(data[:bill])
+      else
+        logger.info "Unhandled Vindi webhook event: #{event_type}"
+      end
+    end
+
+    # BEST PRACTICE 3: Safe target state validations (e.g. ignore if already active/paid)
+    def handle_subscription_created(subscription_data)
+      return if subscription_data.nil?
+      # e.g., Find local tenant/user using subscription_data[:customer][:code]
+      # and activate their account.
+    end
+
+    def handle_bill_paid(bill_data)
+      return if bill_data.nil?
+      # e.g., Find local invoice by bill_data[:id]
+      # and mark as paid. Check first if it isn't already paid.
+    end
+
+    def already_processed?(event_id)
+      # e.g., VindiWebhookEvent.exists?(vindi_event_id: event_id)
+      false
+    end
+
+    def mark_as_processed!(event_id)
+      # e.g., VindiWebhookEvent.create!(vindi_event_id: event_id, processed_at: Time.current)
+    end
+  end
+end

data/lib/generators/vindi/webhook_handler_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Vindi
+  module Generators
+    class WebhookHandlerGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a specific modular webhook handler and a base handler if it does not exist."
+
+      def create_webhook_handler_files
+        template "base_handler.rb", "app/services/vindi/webhooks/base_handler.rb"
+        template "webhook_handler.rb", "app/services/vindi/webhooks/#{file_name}_handler.rb"
+      end
+    end
+  end
+end

data/lib/vindi/integrations/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vindi-rails-integrations
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Wesley Lima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: vindi-rails
@@ -146,10 +146,13 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/generators/vindi/sync_generator.rb
+- lib/generators/vindi/templates/base_handler.rb
 - lib/generators/vindi/templates/migration.rb
+- lib/generators/vindi/templates/webhook_handler.rb
 - lib/generators/vindi/templates/webhook_job.rb
 - lib/generators/vindi/templates/webhooks_controller.rb
 - lib/generators/vindi/webhook_generator.rb
+- lib/generators/vindi/webhook_handler_generator.rb
 - lib/tasks/vindi/tasks.rake
 - lib/vindi-rails-integrations.rb
 - lib/vindi/integrations/concerns/synchronizable.rb