approval_engine 1.0.0

data/lib/approval_engine/model_extensions.rb

@@ -0,0 +1,20 @@
+module ApprovalEngine
+  # Extended onto ActiveRecord::Base so every model gains the class macro,
+  # the way `acts_as_*` gems do. Calling it mixes in the Approvable concern.
+  module ModelExtensions
+    # Arm a model with approvals.
+    #
+    #   has_approvals                          # auto-routes on create (default)
+    #   has_approvals(on: [:create, :update])  # also route on update
+    #   has_approvals(on: [])                  # opt out; trigger manually
+    #
+    # `on:` accepts any of ApprovalEngine::Approvable::LIFECYCLE_EVENTS
+    # (:create, :update, :destroy), routing the conventional "<model>.created" etc.
+    # For domain transitions (e.g. "invoice.rejected"), the engine isn't lifecycle
+    # bound at all — just call `run_approval!(event:)` from your own action.
+    def has_approvals(on: [ :create ])
+      include ApprovalEngine::Approvable
+      self.approval_trigger_events = Array(on).freeze
+    end
+  end
+end

data/lib/approval_engine/version.rb

@@ -0,0 +1,3 @@
+module ApprovalEngine
+  VERSION = "1.0.0"
+end

data/lib/approval_engine.rb

@@ -0,0 +1,12 @@
+require "approval_engine/version"
+require "approval_engine/configuration"
+require "approval_engine/approval_exposure"
+require "approval_engine/model_extensions"
+require "approval_engine/engine"
+
+module ApprovalEngine
+  # Base class for every error the engine raises itself, so a host can rescue
+  # ApprovalEngine::Error to catch them all. (Step transitions still raise the
+  # Rails-idiomatic ActiveRecord::RecordInvalid.)
+  class Error < StandardError; end
+end

data/lib/generators/approval_engine/install/install_generator.rb

@@ -0,0 +1,34 @@
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ApprovalEngine
+  module Generators
+    # Copies the engine migrations into the host app and drops a configured
+    # initializer.
+    #
+    #   rails generate approval_engine:install
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs ApprovalEngine: copies migrations and creates an initializer."
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_initializer
+        template "approval_engine.rb", "config/initializers/approval_engine.rb"
+      end
+
+      def copy_migrations
+        rake "approval_engine:install:migrations"
+      end
+
+      def show_readme
+        readme "POST_INSTALL" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/approval_engine/install/templates/POST_INSTALL

@@ -0,0 +1,55 @@
+===============================================================================
+
+ApprovalEngine installed.
+
+Next steps:
+
+  1. Run the migrations:
+
+       rails db:migrate
+
+  2. Edit config/initializers/approval_engine.rb and set BOTH:
+       * actor_class           — your approver class (e.g. "User")
+       * current_tenant_method — REQUIRED. Until it's set, auto-routing on
+                                 create silently does nothing. Single-tenant
+                                 apps can return a constant.
+
+  3. Make your actor class resolve approval groups:
+
+       class User < ApplicationRecord
+         def self.resolve_approval_group(group_name, target)
+           where(role: group_name)
+         end
+       end
+
+  4. Arm a model and declare its safe surface (a rule can only read attributes
+     you expose here):
+
+       class Invoice < ApplicationRecord
+         has_approvals
+
+         exposes_for_approval do
+           attribute :amount, type: :decimal
+         end
+
+         def after_approved
+           PaymentService.disburse_funds!(self)
+         end
+       end
+
+  5. Create an ACTIVE template + a matching rule (see the README quickstart),
+     then CONFIRM the wiring before relying on it:
+
+       invoice.preview_approval(event: "invoice.created").triggered?
+       # false? -> check event_name match, the template's `active` status,
+       #           the rule condition, and that its vars are exposed attributes.
+
+  6. (Optional) Copy the approval views to customise them:
+
+       rails generate approval_engine:views
+
+  7. (Optional) Mount the ops dashboard in config/routes.rb:
+
+       mount ApprovalEngine::Engine => "/approval_engine"
+
+===============================================================================

data/lib/generators/approval_engine/install/templates/approval_engine.rb

@@ -0,0 +1,21 @@
+ApprovalEngine.configure do |config|
+  # ActiveJob queue used to relay the transactional outbox (host callbacks and
+  # notifications). Defaults to :default; a dedicated queue is recommended.
+  config.outbox_queue = :default
+
+  # How the engine resolves the current tenant for strict data isolation.
+  # Return anything that responds to #id, e.g. with acts_as_tenant:
+  #   config.current_tenant_method = -> { Current.account }
+  # IMPORTANT: while this is nil, auto-routing on create silently no-ops (the
+  # engine can't scope the rules). Single-tenant apps can return a constant:
+  #   config.current_tenant_method = -> { Struct.new(:id).new("default") }
+  config.current_tenant_method = nil
+
+  # Your application's actor class (who approves). It must define:
+  #   def self.resolve_approval_group(group_name, target) -> [actors]
+  config.actor_class = "User"
+
+  # Fail closed by default: a malformed dynamic rule quarantines the approval
+  # instead of crashing the approval. Set to true in development/test to raise.
+  config.raise_on_rule_errors = false
+end

data/lib/generators/approval_engine/views/templates/approvals/index.html.erb

@@ -0,0 +1,17 @@
+<%# Copied by `rails generate approval_engine:views`. Style this however you like. %>
+<h1>My approvals</h1>
+
+<% if @pending_steps.empty? %>
+  <p>Nothing is awaiting your approval.</p>
+<% else %>
+  <ul>
+    <% @pending_steps.each do |step| %>
+      <li>
+        <strong><%= step.target %></strong> —
+        <%= step.name || "Step" %> (layer <%= step.layer %>, iteration <%= step.iteration %>)
+        <%= button_to "Approve", approve_approval_path(step), method: :patch %>
+        <%= button_to "Reject", reject_approval_path(step), method: :patch %>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

data/lib/generators/approval_engine/views/templates/approvals_controller.rb

@@ -0,0 +1,32 @@
+# Copied by `rails generate approval_engine:views`.
+#
+# This file is yours now — restyle it, rename it, add authorization (Pundit,
+# etc.). ApprovalEngine provides the mechanism (step.approve! / reject!); the
+# user-facing experience is entirely up to you.
+class ApprovalsController < ApplicationController
+  def index
+    # actionable_by includes steps delegated to you, and preloads each step's
+    # target so the view can show *what* is awaiting approval without N+1s.
+    @pending_steps = ApprovalEngine::Step.actionable_by(current_user)
+                                         .includes(track: { approval: :target })
+                                         .order(:created_at)
+  end
+
+  def approve
+    act(:approve!, notice: "Approval recorded.")
+  end
+
+  def reject
+    act(:reject!, notice: "Rejection recorded.")
+  end
+
+  private
+
+  def act(method, notice:)
+    step = ApprovalEngine::Step.pending.find(params[:id])
+    step.public_send(method, by: current_user, comment: params[:comment])
+    redirect_back fallback_location: approvals_path, notice: notice
+  rescue ActiveRecord::RecordInvalid => e
+    redirect_back fallback_location: approvals_path, alert: e.message
+  end
+end

data/lib/generators/approval_engine/views/views_generator.rb

@@ -0,0 +1,33 @@
+require "rails/generators/base"
+
+module ApprovalEngine
+  module Generators
+    # Copies an example approvals controller and views into the host app. They
+    # are intentionally unstyled and minimal — you own them, theme them, rename
+    # them. The engine ships the mechanism; the customer-facing UI is yours.
+    #
+    #   rails generate approval_engine:views
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copies example approval controller and views into your app to customise."
+
+      def copy_controller
+        copy_file "approvals_controller.rb", "app/controllers/approvals_controller.rb"
+      end
+
+      def copy_views
+        directory "approvals", "app/views/approvals"
+      end
+
+      def routes_hint
+        say "\nAdd routes for the copied controller, for example:", :green
+        say <<~RUBY
+          resources :approvals, only: :index do
+            member { patch :approve; patch :reject }
+          end
+        RUBY
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: approval_engine
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Harry-kp
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.8
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.8
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: shiny_json_logic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: |-
+  A mountable Rails engine for human-in-the-loop approval flows: an
+  append-only ledger, dynamic JSON-Logic routing, consensus (any/all/majority),
+  delegation, and a transactional outbox — without forcing Redis or Sidekiq.
+email:
+- chaudharyharshit9@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- app/controllers/approval_engine/application_controller.rb
+- app/controllers/approval_engine/approvals_controller.rb
+- app/helpers/approval_engine/application_helper.rb
+- app/jobs/approval_engine/application_job.rb
+- app/jobs/approval_engine/process_outbox_job.rb
+- app/jobs/approval_engine/timeout_sweep_job.rb
+- app/models/approval_engine/application_record.rb
+- app/models/approval_engine/approval.rb
+- app/models/approval_engine/approval_plan.rb
+- app/models/approval_engine/audit_log.rb
+- app/models/approval_engine/consensus.rb
+- app/models/approval_engine/delegation.rb
+- app/models/approval_engine/history.rb
+- app/models/approval_engine/outbox_event.rb
+- app/models/approval_engine/step.rb
+- app/models/approval_engine/template_step.rb
+- app/models/approval_engine/track.rb
+- app/models/approval_engine/track_template.rb
+- app/models/approval_engine/trigger_rule.rb
+- app/models/concerns/approval_engine/approvable.rb
+- app/services/approval_engine/approval_builder.rb
+- app/services/approval_engine/iteration_builder.rb
+- app/services/approval_engine/rule_evaluator.rb
+- app/views/approval_engine/approvals/index.html.erb
+- app/views/approval_engine/approvals/show.html.erb
+- app/views/layouts/approval_engine/dashboard.html.erb
+- config/routes.rb
+- db/migrate/20260614103434_create_approval_engine_core_tables.rb
+- db/migrate/20260614103435_create_approval_engine_infrastructure_tables.rb
+- db/migrate/20260614104809_create_approval_engine_blueprint_tables.rb
+- db/migrate/20260616000001_add_trigger_rule_to_approvals.rb
+- db/migrate/20260617000001_add_approvals_required_to_approvals.rb
+- db/migrate/20260617000002_add_delivery_tracking_to_outbox_events.rb
+- lib/approval_engine.rb
+- lib/approval_engine/approval_exposure.rb
+- lib/approval_engine/configuration.rb
+- lib/approval_engine/engine.rb
+- lib/approval_engine/model_extensions.rb
+- lib/approval_engine/version.rb
+- lib/generators/approval_engine/install/install_generator.rb
+- lib/generators/approval_engine/install/templates/POST_INSTALL
+- lib/generators/approval_engine/install/templates/approval_engine.rb
+- lib/generators/approval_engine/views/templates/approvals/index.html.erb
+- lib/generators/approval_engine/views/templates/approvals_controller.rb
+- lib/generators/approval_engine/views/views_generator.rb
+homepage: https://github.com/Harry-kp/approval_engine
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Harry-kp/approval_engine
+  changelog_uri: https://github.com/Harry-kp/approval_engine/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Harry-kp/approval_engine/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Multi-tenant, immutable-ledger approval flows for Rails.
+test_files: []