vindi-rails-integrations 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40f92c55d8ade3ac7811b05e7e0b25e202f59eee0b87eb4a9d54994a0448ec52
+  data.tar.gz: fbdae32b900767b7545db87488bd3f06c0b28f0971a93ce1869e223145734c22
+SHA512:
+  metadata.gz: ad7b6774270fd3e97f67a231a040ad4cee7145b301ff3979e36483719d66e06b5650e351fd85317fa63bc7511cd81528dba8977b1c4989701886de6238963cd3
+  data.tar.gz: fda62e2338d8500ef9d4efb909e04697b66198f6830d0ec06e471ecfd7e722c1cd41ac0bdf5f3892279d8fb7d2a3e7fcb44d7368cf5afde76155b92c5a7f4f09

data/README.md

@@ -0,0 +1,47 @@
+# 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: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/sync_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Vindi
+  module Generators
+    class SyncGenerator < ::Rails::Generators::NamedBase
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds Vindi synchronization columns to database and concern to your model."
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template "migration.rb", "db/migrate/add_vindi_fields_to_#{table_name}.rb"
+      end
+
+      def inject_concern_into_model
+        model_path = File.join("app/models", "#{file_path}.rb")
+        
+        if File.exist?(model_path)
+          inject_into_class(model_path, class_name, "  include Vindi::Synchronizable\n")
+        else
+          say_status("warning", "Model file #{model_path} not found. Please add 'include Vindi::Synchronizable' manually.", :yellow)
+        end
+      end
+
+      private
+
+      def table_name
+        name.pluralize.underscore
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class AddVindiFieldsTo<%= class_name.pluralize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :<%= table_name %>, :vindi_customer_id, :string
+    add_column :<%= table_name %>, :vindi_payment_profile_id, :string
+    
+    add_index :<%= table_name %>, :vindi_customer_id, unique: true
+  end
+end

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

@@ -0,0 +1,75 @@
+# 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

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Vindi
+  class WebhooksController < ActionController::API
+    before_action :verify_token!
+
+    def create
+      payload = JSON.parse(request.body.read, symbolize_names: true)
+      
+      # Enqueue Vindi Webhook processing
+      Vindi::WebhookJob.perform_later(payload)
+
+      render json: { status: "received" }, status: :ok
+    rescue JSON::ParserError
+      render json: { error: "Invalid payload" }, status: :bad_request
+    end
+
+    private
+
+    # SECURITY BEST PRACTICE: Verify the authenticity of the request.
+    # Configure your Webhook URL in the Vindi Dashboard with a secret query token, e.g.:
+    # https://yourdomain.com/vindi/webhooks?token=YOUR_SECURE_TOKEN
+    def verify_token!
+      token = params[:token]
+      expected_token = ENV["VINDI_WEBHOOK_TOKEN"]
+
+      if expected_token.blank? || token != expected_token
+        render json: { error: "Unauthorized access token" }, status: :unauthorized
+      end
+    end
+  end
+end

data/lib/generators/vindi/webhook_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Vindi
+  module Generators
+    class WebhookGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Webhooks controller and an ActiveJob to handle Vindi webhook events."
+
+      def copy_webhook_files
+        template "webhooks_controller.rb", "app/controllers/vindi/webhooks_controller.rb"
+        template "webhook_job.rb", "app/jobs/vindi/webhook_job.rb"
+        route 'post "/vindi/webhooks" => "vindi/webhooks#create"'
+      end
+    end
+  end
+end

data/lib/tasks/vindi/tasks.rake

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+namespace :vindi do
+  desc "Audit and reconcile local model records with Vindi Customers"
+  task audit: :environment do
+    model_name = ENV["model"] || "User"
+    klass = model_name.constantize
+    raise "Model #{model_name} is not synchronizable" unless klass.include?(Vindi::Synchronizable)
+
+    audit_records(klass)
+  end
+
+  desc "Simulate a Vindi webhook event locally"
+  task test_webhook: :environment do
+    event_type = ENV["event"] || "bill_paid"
+    url = ENV["url"] || "http://localhost:3000/vindi/webhooks"
+    token = ENV["token"] || ENV["VINDI_WEBHOOK_TOKEN"]
+
+    payload = build_simulated_payload(event_type)
+    send_simulated_webhook(url, token, payload)
+  end
+end
+
+def audit_records(klass)
+  puts "Auditing #{klass.name} records..."
+  klass.where.not(vindi_customer_id: nil).find_each do |record|
+    Vindi::Customer.find(record.vindi_customer_id)
+    puts "Record #{record.id}: OK (Synced with Vindi customer #{record.vindi_customer_id})"
+  rescue Vindi::NotFoundError
+    puts "Record #{record.id}: ERROR - Customer #{record.vindi_customer_id} not found in Vindi!"
+  rescue Vindi::Error => e
+    puts "Record #{record.id}: API Error - #{e.message}"
+  end
+end
+
+def build_simulated_payload(event_type)
+  {
+    event: {
+      id: rand(100_000..999_999),
+      type: event_type,
+      created_at: Time.current.iso8601,
+      data: {
+        bill: { id: 555, amount: "100.00", status: "paid" },
+        subscription: { id: 777, status: "active" }
+      }
+    }
+  }
+end
+
+def send_simulated_webhook(url, token, payload)
+  full_url = token ? "#{url}?token=#{token}" : url
+  puts "Sending simulated webhook to #{full_url}..."
+  
+  response = RestClient.post(
+    full_url,
+    payload.to_json,
+    { content_type: :json, accept: :json }
+  )
+  puts "Response Code: #{response.code}"
+  puts "Response Body: #{response.body}"
+rescue RestClient::Exception => e
+  puts "Failed: #{e.message}"
+  puts "Response: #{e.response&.body}"
+end

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

@@ -0,0 +1,65 @@
+# 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

data/lib/vindi/integrations/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Vindi
+  module Integrations
+    class Railtie < ::Rails::Railtie
+      # Automatic loading of generators and integrations in Rails
+      rake_tasks do
+        load File.expand_path("../../../tasks/vindi/tasks.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/vindi/integrations/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Vindi
+  module Integrations
+    VERSION = "0.1.0"
+  end
+end

data/lib/vindi-rails-integrations.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "vindi"
+require_relative "vindi/integrations/version"
+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

metadata

@@ -0,0 +1,183 @@
+--- !ruby/object:Gem::Specification
+name: vindi-rails-integrations
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Wesley Lima
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: vindi-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Provides webhook handling, background jobs, and data synchronization
+  for the Vindi Rails SDK.
+email:
+- wesleyskap@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/generators/vindi/sync_generator.rb
+- lib/generators/vindi/templates/migration.rb
+- lib/generators/vindi/templates/webhook_job.rb
+- lib/generators/vindi/templates/webhooks_controller.rb
+- lib/generators/vindi/webhook_generator.rb
+- lib/tasks/vindi/tasks.rake
+- lib/vindi-rails-integrations.rb
+- lib/vindi/integrations/concerns/synchronizable.rb
+- lib/vindi/integrations/railtie.rb
+- lib/vindi/integrations/version.rb
+homepage: https://github.com/wesleyskap/vindi-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/wesleyskap/vindi-rails
+  source_code_uri: https://github.com/wesleyskap/vindi-rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Rails backend integrations (webhooks, jobs, sync) for Vindi API.
+test_files: []