rsb-entitlements 0.9.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 989e890034f790d70eb7f72b08ec9e09c32a78a6c662d7fdfdb8c870820493b2
+  data.tar.gz: 3792b156c3b2bedd73206fa73a42f8d5739efebdf000a54869faafa09cf96773
+SHA512:
+  metadata.gz: fe68f954e44a3555217aa8ffa7af1c5e4adf99a3b86b5603b7eef8857a980ff025499377f7c0f1399028465249286ad1654bc76bb2ef6d91f6e20ea890659c2c
+  data.tar.gz: c607f75ca712375e2a8369dfa291146493a0a8e8205e92c24c976c4910ebd6bdc7bc3cda21b903caad4f019bef36648c7a297a30de58f7de950f590aa1648110

data/LICENSE

@@ -0,0 +1,15 @@
+Rails SaaS Builder (RSB)
+Copyright (C) 2026 Aleksandr Marchenko
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

data/README.md

@@ -0,0 +1,73 @@
+# rsb-entitlements
+
+Plan-based feature gating, entitlements, and metered usage tracking for Rails SaaS Builder. Drop-in `Entitleable` concern for any model. Extensible provider registry for payment integrations (Stripe, wire transfers, admin grants). Includes usage counter ledger and automated expiration.
+
+## Installation
+
+### As part of Rails SaaS Builder
+
+```ruby
+gem "rails-saas-builder"
+```
+
+### Standalone
+
+```ruby
+gem "rsb-entitlements"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate rsb_entitlements:install
+rails db:migrate
+```
+
+## Key Features
+
+- Plan management with feature flags and usage limits
+- `Entitleable` concern: mix into any model for plan-based access
+- Feature checking: `entitled_to?(:feature_name)`
+- Usage metering: `within_limit?(:metric)`, `increment_usage(:metric)`
+- Pluggable payment providers (Stripe, wire transfer, custom)
+- Payment request lifecycle with automatic expiration
+- Usage counter ledger (daily, weekly, monthly, cumulative periods)
+- Automatic entitlement expiration
+
+## Basic Usage
+
+```ruby
+# Add to your model
+class Organization < ApplicationRecord
+  include RSB::Entitlements::Entitleable
+end
+
+# Check features and usage
+org.entitled_to?(:advanced_analytics)  #=> true/false
+org.within_limit?(:api_calls)          #=> true/false
+org.increment_usage(:api_calls, 1)
+
+# Grant an entitlement
+org.grant_entitlement(plan: plan, provider: :admin)
+
+# Request payment
+org.request_payment(plan: premium_plan, provider: :stripe)
+```
+
+## Configuration
+
+```ruby
+RSB::Entitlements.configure do |config|
+  config.after_entitlement_changed = ->(entitlement) { ... }
+  config.after_usage_limit_reached = ->(counter) { ... }
+end
+```
+
+## Documentation
+
+Part of [Rails SaaS Builder](../README.md). See the main README for the full picture.
+
+## License
+
+[LGPL-3.0](../LICENSE)

data/Rakefile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'fileutils'
+require 'rake/testtask'
+
+task :prepare_test_db do
+  ENV['RAILS_ENV'] = 'test'
+  db = File.expand_path('test/dummy/db/test.sqlite3', __dir__)
+  FileUtils.rm_f(db)
+  require_relative 'test/dummy/config/environment'
+  ActiveRecord::Migration.verbose = false
+  ActiveRecord::MigrationContext.new(Rails.application.paths['db/migrate'].to_a).migrate
+  schema = File.expand_path('test/dummy/db/schema.rb', __dir__)
+  File.open(schema, 'w') { |f| ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, f) }
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task test: :prepare_test_db
+task default: :test

data/app/controllers/rsb/entitlements/admin/payment_requests_controller.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    module Admin
+      class PaymentRequestsController < RSB::Admin::AdminController
+        before_action :authorize_payment_requests
+        before_action :set_payment_request, only: %i[show approve reject refund]
+
+        def index
+          page = params[:page].to_i
+          per_page = 20
+          scope = RSB::Entitlements::PaymentRequest.order(created_at: :desc)
+
+          scope = scope.where(status: params[:status]) if params[:status].present?
+          scope = scope.where(provider_key: params[:provider_key]) if params[:provider_key].present?
+          scope = scope.where(requestable_type: params[:requestable_type]) if params[:requestable_type].present?
+
+          @payment_requests = scope.limit(per_page).offset(page * per_page)
+          @current_page = page
+          @per_page = per_page
+        end
+
+        def show
+          definition = RSB::Entitlements.providers.find(@payment_request.provider_key)
+          if definition
+            provider_instance = definition.provider_class.new(@payment_request)
+            @provider_details = provider_instance.admin_details
+            @provider_definition = definition
+          else
+            @provider_details = {}
+            @provider_definition = nil
+          end
+        end
+
+        def approve
+          definition = RSB::Entitlements.providers.find(@payment_request.provider_key)
+          return redirect_with_alert('Provider not found') unless definition
+
+          return redirect_with_alert('Request is not actionable') unless @payment_request.actionable?
+
+          @payment_request.update!(
+            resolved_by: current_admin_user.email,
+            resolved_at: Time.current
+          )
+
+          provider_instance = definition.provider_class.new(@payment_request)
+          provider_instance.complete!
+
+          redirect_to "/admin/payment_requests/#{@payment_request.id}",
+                      notice: 'Payment request approved.'
+        end
+
+        def reject
+          definition = RSB::Entitlements.providers.find(@payment_request.provider_key)
+          return redirect_with_alert('Provider not found') unless definition
+
+          return redirect_with_alert('Request is not actionable') unless @payment_request.actionable?
+
+          @payment_request.update!(
+            admin_note: params[:admin_note],
+            resolved_by: current_admin_user.email,
+            resolved_at: Time.current
+          )
+
+          provider_instance = definition.provider_class.new(@payment_request)
+          provider_instance.reject!
+
+          redirect_to "/admin/payment_requests/#{@payment_request.id}",
+                      notice: 'Payment request rejected.'
+        end
+
+        def refund
+          definition = RSB::Entitlements.providers.find(@payment_request.provider_key)
+          return redirect_with_alert('Provider not found') unless definition
+          return redirect_with_alert('Provider does not support refunds') unless definition.refundable
+          return redirect_with_alert('Request is not approved') unless @payment_request.approved?
+
+          @payment_request.update!(
+            resolved_by: current_admin_user.email,
+            resolved_at: Time.current
+          )
+
+          provider_instance = definition.provider_class.new(@payment_request)
+          provider_instance.refund!
+
+          # Revoke linked entitlement if present
+          @payment_request.entitlement.revoke!(reason: 'refund') if @payment_request.entitlement&.active?
+
+          @payment_request.update!(status: 'refunded')
+
+          redirect_to "/admin/payment_requests/#{@payment_request.id}",
+                      notice: 'Payment request refunded.'
+        end
+
+        private
+
+        def set_payment_request
+          @payment_request = RSB::Entitlements::PaymentRequest.find(params[:id])
+        end
+
+        def authorize_payment_requests
+          authorize_admin_action!(resource: 'payment_requests', action: action_name)
+        end
+
+        def redirect_with_alert(message)
+          redirect_to "/admin/payment_requests/#{@payment_request.id}", alert: message
+        end
+      end
+    end
+  end
+end

data/app/controllers/rsb/entitlements/admin/plans_controller.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    module Admin
+      class PlansController < RSB::Admin::AdminController
+        before_action :authorize_plans
+        before_action :set_plan, only: %i[show edit update destroy]
+
+        def index
+          page = params[:page].to_i
+          per_page = 20
+          @plans = RSB::Entitlements::Plan.order(:created_at)
+                                          .limit(per_page)
+                                          .offset(page * per_page)
+          @current_page = page
+          @per_page = per_page
+        end
+
+        def show; end
+
+        def new
+          @plan = RSB::Entitlements::Plan.new(
+            features: {},
+            limits: {},
+            metadata: {},
+            active: true
+          )
+        end
+
+        def create
+          @plan = RSB::Entitlements::Plan.new(plan_params)
+          if @plan.save
+            redirect_to "/admin/plans/#{@plan.id}", notice: 'Plan created.'
+          else
+            render :new, status: :unprocessable_entity
+          end
+        end
+
+        def edit; end
+
+        def update
+          if @plan.update(plan_params)
+            redirect_to "/admin/plans/#{@plan.id}", notice: 'Plan updated.'
+          else
+            render :edit, status: :unprocessable_entity
+          end
+        end
+
+        def destroy
+          if @plan.entitlements.exists?
+            redirect_to '/admin/plans',
+                        alert: 'Cannot delete a plan with active entitlements.'
+          else
+            @plan.destroy!
+            redirect_to '/admin/plans', notice: 'Plan deleted.'
+          end
+        end
+
+        private
+
+        def set_plan
+          @plan = RSB::Entitlements::Plan.find(params[:id])
+        end
+
+        def plan_params
+          permitted = params.require(:plan).permit(
+            :name, :slug, :interval, :price_cents, :currency, :active,
+            features: {},
+            limits: {},
+            metadata: {}
+          )
+
+          # Convert feature string values to booleans
+          if permitted[:features].present?
+            permitted[:features] = permitted[:features].transform_values { |v| ['true', true].include?(v) }
+          end
+
+          # Convert limit string values to integers
+          permitted[:limits] = permitted[:limits].transform_values(&:to_i) if permitted[:limits].present?
+
+          permitted
+        end
+
+        def authorize_plans
+          authorize_admin_action!(resource: 'plans', action: action_name)
+        end
+      end
+    end
+  end
+end

data/app/controllers/rsb/entitlements/admin/usage_counters_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    module Admin
+      class UsageCountersController < RSB::Admin::AdminController
+        # Displays a filterable, sortable, paginated table of usage counters.
+        #
+        # Params:
+        #   metric (optional) - filter by metric name
+        #   period_key (optional) - filter by period key
+        #   countable_type (optional) - filter by countable type
+        #   sort (optional) - sort column: "current_value", "period_key", "created_at"
+        #   direction (optional) - sort direction: "asc", "desc"
+        #   page (optional) - pagination page number
+        #
+        # @return [void]
+        def index
+          scope = RSB::Entitlements::UsageCounter.all
+
+          scope = scope.for_metric(params[:metric]) if params[:metric].present?
+          scope = scope.for_period(params[:period_key]) if params[:period_key].present?
+          scope = scope.where(countable_type: params[:countable_type]) if params[:countable_type].present?
+
+          sort_col = %w[current_value period_key created_at].include?(params[:sort]) ? params[:sort] : 'created_at'
+          sort_dir = params[:direction] == 'asc' ? :asc : :desc
+          scope = scope.order(sort_col => sort_dir)
+
+          @per_page = 25
+          @page = (params[:page] || 1).to_i
+          @total_count = scope.count
+          @usage_counters = scope.offset((@page - 1) * @per_page).limit(@per_page)
+
+          @available_metrics = RSB::Entitlements::UsageCounter.distinct.pluck(:metric).sort
+          @available_types = RSB::Entitlements::UsageCounter.distinct.pluck(:countable_type).sort
+        end
+
+        # Displays a per-metric trend chart using SQL aggregation.
+        #
+        # Params:
+        #   metric (required for chart) - the metric to chart
+        #   countable_type (optional) - filter to specific countable type
+        #   countable_id (optional) - filter to specific countable
+        #
+        # @return [void]
+        def trend
+          @available_metrics = RSB::Entitlements::UsageCounter.distinct.pluck(:metric).sort
+          @metric = params[:metric]
+
+          return unless @metric.present?
+
+          scope = RSB::Entitlements::UsageCounter.for_metric(@metric)
+          scope = scope.where(countable_type: params[:countable_type]) if params[:countable_type].present?
+          scope = scope.where(countable_id: params[:countable_id]) if params[:countable_id].present?
+
+          @trend_data = scope
+                        .group(:period_key)
+                        .order(:period_key)
+                        .sum(:current_value)
+                        .to_a
+                        .last(30)
+                        .to_h
+
+          @max_value = @trend_data.values.max || 0
+        end
+      end
+    end
+  end
+end

data/app/jobs/rsb/entitlements/application_job.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    class ApplicationJob < ActiveJob::Base
+    end
+  end
+end

data/app/jobs/rsb/entitlements/entitlement_expiration_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    class EntitlementExpirationJob < ApplicationJob
+      queue_as :default
+
+      def perform
+        Entitlement.active
+                   .where('expires_at <= ?', Time.current)
+                   .find_each(&:expire!)
+      end
+    end
+  end
+end

data/app/jobs/rsb/entitlements/payment_request_expiration_job.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    # Expires stale payment requests whose expires_at has passed.
+    # Only affects actionable requests (pending, processing).
+    # Sets resolved_by to "system:expiration" and resolved_at to current time.
+    #
+    # Schedule this job to run periodically (e.g., every hour via cron or recurring job).
+    #
+    # @example
+    #   PaymentRequestExpirationJob.perform_later
+    class PaymentRequestExpirationJob < ApplicationJob
+      queue_as :default
+
+      def perform
+        PaymentRequest
+          .actionable
+          .where('expires_at <= ?', Time.current)
+          .where.not(expires_at: nil)
+          .find_each do |request|
+            request.update!(
+              status: 'expired',
+              resolved_by: 'system:expiration',
+              resolved_at: Time.current
+            )
+          end
+      end
+    end
+  end
+end

data/app/models/concerns/rsb/entitlements/entitleable.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    module Entitleable
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :entitlements,
+                 class_name: 'RSB::Entitlements::Entitlement',
+                 as: :entitleable,
+                 dependent: :restrict_with_error
+
+        has_many :usage_counters,
+                 class_name: 'RSB::Entitlements::UsageCounter',
+                 as: :countable,
+                 dependent: :destroy
+
+        has_many :payment_requests,
+                 class_name: 'RSB::Entitlements::PaymentRequest',
+                 as: :requestable,
+                 dependent: :restrict_with_error
+      end
+
+      def entitlement_source
+        self
+      end
+
+      def current_entitlement
+        entitlement_source.entitlements.active.order(created_at: :desc).first
+      end
+
+      def current_plan
+        current_entitlement&.plan
+      end
+
+      def entitled_to?(feature)
+        current_plan&.feature?(feature) || false
+      end
+
+      # Checks if the entitleable is within the usage limit for a metric
+      # in the current period.
+      #
+      # @param metric [String, Symbol] the metric name
+      # @return [Boolean] true if within limit or unlimited, false if at/over limit or no plan
+      def within_limit?(metric)
+        plan = current_plan
+        return false unless plan
+
+        config = plan.limit_config_for(metric)
+        return true unless config # metric not defined = unlimited
+
+        limit_value = config['limit']
+        return true if limit_value.nil? # nil limit = unlimited
+
+        period_key = PeriodKeyCalculator.current_key(config['period'])
+        counter = current_period_counter(metric, period_key, plan)
+        return true unless counter
+
+        counter.current_value < limit_value
+      end
+
+      # Returns the remaining usage quota for a metric in the current period.
+      #
+      # @param metric [String, Symbol] the metric name
+      # @return [Integer, nil] remaining count, or nil if unlimited or no plan
+      def remaining(metric)
+        plan = current_plan
+        return nil unless plan
+
+        config = plan.limit_config_for(metric)
+        return nil unless config
+
+        limit_value = config['limit']
+        return nil if limit_value.nil?
+
+        period_key = PeriodKeyCalculator.current_key(config['period'])
+        counter = current_period_counter(metric, period_key, plan)
+        return limit_value unless counter
+
+        [limit_value - counter.current_value, 0].max
+      end
+
+      # Grants an entitlement for a plan, revoking the current one if any.
+      #
+      # @param plan [RSB::Entitlements::Plan] the plan to grant
+      # @param provider [String, Symbol] the provider key
+      # @param expires_at [Time, nil] optional expiration time
+      # @param metadata [Hash] optional metadata
+      # @return [RSB::Entitlements::Entitlement] the new entitlement
+      def grant_entitlement(plan:, provider:, expires_at: nil, metadata: {})
+        source = entitlement_source
+        current = source.current_entitlement
+        old_plan = current&.plan
+        current&.revoke!(reason: 'upgrade')
+
+        new_entitlement = source.entitlements.create!(
+          plan: plan,
+          status: 'active',
+          provider: provider.to_s,
+          activated_at: Time.current,
+          expires_at: expires_at,
+          metadata: metadata
+        )
+
+        # Handle plan change counter transitions if there was a previous plan
+        if old_plan && old_plan.id != plan.id
+          UsageCounterService.new.handle_plan_change(source, old_plan: old_plan, new_plan: plan)
+        end
+
+        new_entitlement
+      end
+
+      def revoke_entitlement(reason: 'admin')
+        entitlement_source.current_entitlement&.revoke!(reason: reason)
+      end
+
+      # Increments the usage counter for a metric in the current period.
+      #
+      # Automatically finds or creates the counter record for the current period
+      # based on the plan's limit configuration.
+      #
+      # @param metric [String, Symbol] the metric name
+      # @param amount [Integer] the amount to increment (default: 1)
+      # @return [Integer] the new current_value
+      # @raise [RuntimeError] if no current plan or metric not defined in plan
+      def increment_usage(metric, amount = 1)
+        source = entitlement_source
+        plan = source.current_entitlement&.plan
+        raise "No current plan for metric: #{metric}" unless plan
+
+        config = plan.limit_config_for(metric.to_s)
+        raise "No limit defined for metric: #{metric}" unless config
+
+        period_key = PeriodKeyCalculator.current_key(config['period'])
+
+        counter = source.usage_counters.find_or_create_by!(
+          metric: metric.to_s,
+          period_key: period_key,
+          plan_id: plan.id
+        ) { |c| c.limit = config['limit'] }
+
+        counter.increment!(amount)
+      end
+
+      # Returns payment requests in actionable states (pending, processing).
+      #
+      # @return [ActiveRecord::Relation<PaymentRequest>]
+      def pending_payment_requests
+        payment_requests.where(status: %w[pending processing])
+      end
+
+      # Create a payment request and initiate the provider flow.
+      #
+      # @param plan [RSB::Entitlements::Plan] the plan to request
+      # @param provider [Symbol, String] registered provider key
+      # @param amount_cents [Integer, nil] override amount (defaults to plan.price_cents)
+      # @param currency [String, nil] override currency (defaults to plan.currency)
+      # @param metadata [Hash] arbitrary metadata
+      # @return [Hash] provider response ({ instructions: }, { redirect_url: }, or { status: :completed })
+      #   OR { error: :duplicate_request, existing: PaymentRequest } if duplicate
+      # @raise [ArgumentError] if provider is not registered or not enabled
+      def request_payment(plan:, provider:, amount_cents: nil, currency: nil, metadata: {})
+        provider_key = provider.to_sym
+        definition = RSB::Entitlements.providers.find(provider_key)
+
+        raise ArgumentError, "Provider :#{provider_key} is not registered" unless definition
+
+        enabled = RSB::Entitlements.providers.enabled.any? { |d| d.key == provider_key }
+        raise ArgumentError, "Provider :#{provider_key} is disabled" unless enabled
+
+        existing = payment_requests.actionable.find_by(plan: plan)
+        return { error: :duplicate_request, existing: existing } if existing
+
+        request = payment_requests.create!(
+          plan: plan,
+          provider_key: provider_key.to_s,
+          amount_cents: amount_cents || plan.price_cents,
+          currency: currency || plan.currency,
+          metadata: metadata
+        )
+
+        provider_instance = definition.provider_class.new(request)
+        provider_instance.initiate!
+      end
+
+      # Returns historical usage counter records for a metric, most recent first.
+      #
+      # @param metric [String, Symbol] the metric name
+      # @param limit [Integer] maximum number of records to return (default: 30)
+      # @return [ActiveRecord::Relation<UsageCounter>]
+      def usage_history(metric, limit: 30)
+        entitlement_source.usage_counters
+                          .for_metric(metric.to_s)
+                          .order(period_key: :desc)
+                          .limit(limit)
+      end
+
+      private
+
+      def current_period_counter(metric, period_key, plan)
+        entitlement_source.usage_counters
+                          .for_metric(metric.to_s)
+                          .for_period(period_key)
+                          .for_plan(plan)
+                          .last
+      end
+    end
+  end
+end

data/app/models/rsb/entitlements/application_record.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+      self.table_name_prefix = 'rsb_entitlements_'
+    end
+  end
+end