rsb-entitlements 0.9.1

data/db/migrate/20260208200003_create_rsb_entitlements_usage_counters.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateRSBEntitlementsUsageCounters < ActiveRecord::Migration[8.0]
+  def change
+    create_table :rsb_entitlements_usage_counters do |t|
+      t.references :countable, polymorphic: true, null: false
+      t.string   :metric,        null: false
+      t.integer  :current_value, null: false, default: 0
+      t.integer  :limit
+      t.string   :period
+      t.datetime :period_start
+      t.datetime :resets_at
+      t.timestamps
+    end
+
+    add_index :rsb_entitlements_usage_counters,
+              %i[countable_type countable_id metric],
+              unique: true,
+              name: 'idx_rsb_usage_counters_unique'
+  end
+end

data/db/migrate/20260208200004_create_rsb_entitlements_payment_requests.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class CreateRSBEntitlementsPaymentRequests < ActiveRecord::Migration[8.0]
+  def change
+    create_table :rsb_entitlements_payment_requests do |t|
+      t.references :requestable, polymorphic: true, null: false
+      t.references :plan, null: false, foreign_key: { to_table: :rsb_entitlements_plans }
+      t.references :entitlement, null: true, foreign_key: { to_table: :rsb_entitlements_entitlements }
+      t.string   :provider_key,  null: false
+      t.string   :status,        null: false, default: 'pending'
+      t.integer  :amount_cents,  null: false, default: 0
+      t.string   :currency,      null: false, default: 'usd'
+      t.string   :provider_ref
+      t.json     :provider_data, default: {}
+      t.text     :admin_note
+      t.string   :resolved_by
+      t.datetime :resolved_at
+      t.datetime :expires_at
+      t.json     :metadata, default: {}
+      t.timestamps
+    end
+
+    add_index :rsb_entitlements_payment_requests,
+              %i[requestable_type requestable_id],
+              name: 'idx_payment_requests_on_requestable'
+    add_index :rsb_entitlements_payment_requests, :status
+    add_index :rsb_entitlements_payment_requests, :provider_key
+    add_index :rsb_entitlements_payment_requests, :expires_at,
+              where: "status IN ('pending', 'processing')",
+              name: 'idx_payment_requests_on_expires_at'
+    add_index :rsb_entitlements_payment_requests,
+              %i[requestable_type requestable_id plan_id],
+              unique: true,
+              where: "status IN ('pending', 'processing')",
+              name: 'idx_payment_requests_actionable_unique'
+  end
+end

data/db/migrate/20260213000001_rework_usage_counters_to_ledger.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+class ReworkUsageCountersToLedger < ActiveRecord::Migration[8.0]
+  def up
+    # 1. Add new columns
+    add_column :rsb_entitlements_usage_counters, :period_key, :string
+    add_reference :rsb_entitlements_usage_counters, :plan,
+                  null: true,
+                  foreign_key: { to_table: :rsb_entitlements_plans }
+
+    # 2. Data migration — set defaults for existing records
+    #    All existing counters become cumulative records.
+    #    Plan is set from the countable's most recent entitlement.
+    execute <<~SQL
+      UPDATE rsb_entitlements_usage_counters
+      SET period_key = '__cumulative__',
+          plan_id = (
+            SELECT e.plan_id
+            FROM rsb_entitlements_entitlements e
+            WHERE e.entitleable_type = rsb_entitlements_usage_counters.countable_type
+              AND e.entitleable_id = rsb_entitlements_usage_counters.countable_id
+            ORDER BY e.created_at DESC
+            LIMIT 1
+          )
+    SQL
+
+    # 3. For any counters that still have NULL plan_id (no entitlement found),
+    #    assign the first plan as a fallback
+    fallback_plan_id = RSB::Entitlements::Plan.first&.id
+    if fallback_plan_id
+      execute <<~SQL
+        UPDATE rsb_entitlements_usage_counters
+        SET plan_id = #{fallback_plan_id}
+        WHERE plan_id IS NULL
+      SQL
+    end
+
+    # 4. Data migration — convert Plan.limits from flat to nested format
+    RSB::Entitlements::Plan.find_each do |plan|
+      next if plan.limits.blank?
+
+      # Skip if already in nested format (first value is a Hash)
+      first_value = plan.limits.values.first
+      next if first_value.is_a?(Hash)
+
+      nested = plan.limits.transform_values do |limit_value|
+        { 'limit' => limit_value, 'period' => nil }
+      end
+      plan.update_column(:limits, nested)
+    end
+
+    # 5. Make columns NOT NULL now that data is migrated
+    change_column_null :rsb_entitlements_usage_counters, :period_key, false
+    change_column_null :rsb_entitlements_usage_counters, :plan_id, false
+
+    # 6. Drop old columns
+    remove_column :rsb_entitlements_usage_counters, :period, :string
+    remove_column :rsb_entitlements_usage_counters, :period_start, :datetime
+    remove_column :rsb_entitlements_usage_counters, :resets_at, :datetime
+
+    # 7. Drop old unique index and create new one
+    remove_index :rsb_entitlements_usage_counters,
+                 name: 'idx_rsb_usage_counters_unique'
+
+    add_index :rsb_entitlements_usage_counters,
+              %i[countable_type countable_id metric period_key plan_id],
+              unique: true,
+              name: 'idx_rsb_usage_counters_unique'
+
+    # 8. Add supporting indexes
+    add_index :rsb_entitlements_usage_counters, :metric,
+              name: 'idx_rsb_usage_counters_on_metric'
+    add_index :rsb_entitlements_usage_counters, :period_key,
+              name: 'idx_rsb_usage_counters_on_period_key'
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration,
+          'Cannot reverse usage counter ledger migration (data migration is lossy)'
+  end
+end

data/lib/generators/rsb/entitlements/install/install_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    class InstallGenerator < Rails::Generators::Base
+      namespace 'rsb:entitlements:install'
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Install rsb-entitlements: copy migrations.'
+
+      def copy_migrations
+        rake 'rsb_entitlements:install:migrations'
+      end
+
+      def print_post_install
+        say ''
+        say 'rsb-entitlements installed successfully!', :green
+        say ''
+        say 'Next steps:'
+        say '  1. rails db:migrate'
+        say '  2. Include RSB::Entitlements::Entitleable in any model that needs plan-based features.'
+        say ''
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    class Configuration
+      attr_accessor :after_entitlement_changed,
+                    :after_usage_limit_reached,
+                    :after_plan_changed,
+                    :after_payment_request_changed
+
+      def initialize
+        @after_entitlement_changed = nil
+        @after_usage_limit_reached = nil
+        @after_plan_changed = nil
+        @after_payment_request_changed = nil
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/engine.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    class Engine < ::Rails::Engine
+      isolate_namespace RSB::Entitlements
+
+      # FIXME: Move admin integration to separate gem!
+      # Exclude admin controllers from autoloading when rsb-admin is not present.
+      # These controllers inherit from RSB::Admin::AdminController and can only
+      # be loaded when rsb-admin is in the bundle.
+      initializer 'rsb_entitlements.exclude_admin_controllers', before: :set_autoload_paths do
+        unless defined?(RSB::Admin::Engine)
+          Rails.autoloaders.main.ignore(root.join('app', 'controllers', 'rsb', 'entitlements', 'admin'))
+        end
+      end
+
+      # Register settings schema with rsb-settings
+      initializer 'rsb_entitlements.register_settings', after: 'rsb_settings.ready' do
+        RSB::Settings.registry.register(RSB::Entitlements.settings_schema)
+      end
+
+      # Signal readiness — provider extensions hook in after this
+      initializer 'rsb_entitlements.ready' do
+        # Register built-in providers
+        RSB::Entitlements.providers.register(RSB::Entitlements::PaymentProvider::Wire)
+      end
+
+      # Load i18n translations for admin labels
+      initializer 'rsb_entitlements.i18n' do
+        config.i18n.load_path += Dir[RSB::Entitlements::Engine.root.join('config', 'locales', '**', '*.yml')]
+      end
+
+      # Admin integration via lazy on_load hook
+      # Registers Plan and Entitlement resources with explicit columns, filters, and form fields,
+      # plus a UsageCounters page with custom actions for monitoring and resetting counters.
+      initializer 'rsb_entitlements.admin_hooks' do
+        ActiveSupport.on_load(:rsb_admin) do |admin_registry|
+          admin_registry.register_category 'Billing' do
+            resource RSB::Entitlements::Plan,
+                     icon: 'credit-card',
+                     actions: %i[index show new create edit update destroy],
+                     controller: 'rsb/entitlements/admin/plans',
+                     default_sort: { column: :name, direction: :asc } do
+              column :id, link: true
+              column :name, sortable: true
+              column :slug, visible_on: [:show]
+              column :interval, formatter: :badge
+              column :price_cents, label: 'Price', sortable: true
+              column :currency, visible_on: [:show]
+              column :active, formatter: :badge
+              column :features, formatter: :json, visible_on: [:show]
+              column :limits, formatter: :json, visible_on: [:show]
+              column :metadata, formatter: :json, visible_on: [:show]
+              column :created_at, formatter: :datetime, visible_on: [:show]
+
+              filter :active, type: :boolean
+              filter :interval, type: :select, options: %w[monthly yearly one_time]
+
+              form_field :name, type: :text, required: true
+              form_field :slug, type: :text, required: true, hint: 'URL-friendly identifier'
+              form_field :interval, type: :select, options: %w[monthly yearly one_time], required: true
+              form_field :price_cents, type: :number, required: true, label: 'Price (cents)'
+              form_field :currency, type: :text, hint: 'ISO 4217 code (e.g., USD)'
+              form_field :active, type: :checkbox
+              form_field :features, type: :json, hint: 'JSON object of feature flags'
+              form_field :limits, type: :json, hint: 'JSON object of usage limits'
+              form_field :metadata, type: :json, hint: 'Arbitrary metadata'
+            end
+
+            resource RSB::Entitlements::Entitlement,
+                     icon: 'shield',
+                     actions: %i[index show grant revoke activate] do
+              column :id, link: true
+              column :plan_id, label: 'Plan'
+              column :entitleable_type, label: 'Type'
+              column :entitleable_id, label: 'Owner ID'
+              column :status, formatter: :badge
+              column :starts_at, formatter: :datetime, visible_on: [:show]
+              column :ends_at, formatter: :datetime, visible_on: [:show]
+              column :created_at, formatter: :datetime, visible_on: [:show]
+
+              filter :status, type: :select, options: %w[active expired cancelled]
+              filter :entitleable_type, type: :text
+            end
+
+            resource RSB::Entitlements::PaymentRequest,
+                     icon: 'receipt',
+                     actions: %i[index show approve reject refund],
+                     controller: 'rsb/entitlements/admin/payment_requests',
+                     default_sort: { column: :created_at, direction: :desc },
+                     per_page: 20 do
+              column :id, link: true
+              column :requestable_type, label: 'Type'
+              column :requestable_id, label: 'Owner ID'
+              column :plan_id, label: 'Plan'
+              column :provider_key, formatter: :badge
+              column :status, formatter: :badge
+              column :amount_cents, label: 'Amount'
+              column :currency
+              column :created_at, formatter: :datetime, visible_on: %i[index show]
+              column :provider_ref, visible_on: [:show]
+              column :resolved_by, visible_on: [:show]
+              column :resolved_at, formatter: :datetime, visible_on: [:show]
+              column :admin_note, visible_on: [:show]
+              column :expires_at, formatter: :datetime, visible_on: [:show]
+
+              filter :status, type: :select,
+                              options: RSB::Entitlements::PaymentRequest::STATUSES
+              filter :provider_key, type: :select,
+                                    options: -> { RSB::Entitlements.providers.all.map { |d| d.key.to_s } }
+              filter :requestable_type, type: :text
+            end
+
+            page :usage_counters,
+                 label: 'Usage Monitoring',
+                 icon: 'bar-chart',
+                 controller: 'rsb/entitlements/admin/usage_counters',
+                 actions: [
+                   { key: :index, label: 'Overview' },
+                   { key: :trend, label: 'Trend' }
+                 ]
+          end
+        end
+      end
+
+      config.generators do |g|
+        g.test_framework :minitest, fixture: false
+        g.assets false
+        g.helper false
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/payment_provider/base.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    module PaymentProvider
+      # Abstract base class for payment providers.
+      #
+      # Subclasses MUST override these class methods:
+      #   - self.provider_key -> Symbol
+      #   - self.provider_label -> String
+      #
+      # Subclasses MUST override these instance methods:
+      #   - initiate! -> Hash
+      #   - complete!(params) -> void
+      #   - reject!(params) -> void
+      #
+      # Subclasses MAY override:
+      #   - self.manual_resolution? -> Boolean (default: false)
+      #   - self.admin_actions -> Array<Symbol> (default: [])
+      #   - self.refundable? -> Boolean (default: false)
+      #   - self.required_settings -> Array<Symbol> (default: [])
+      #   - refund!(params) -> void (default: raises NotImplementedError)
+      #   - admin_details -> Hash (default: {})
+      #
+      # @example Defining a provider
+      #   class MyProvider < RSB::Entitlements::PaymentProvider::Base
+      #     def self.provider_key = :my_provider
+      #     def self.provider_label = "My Provider"
+      #
+      #     settings_schema do
+      #       setting :api_key, type: :string, default: ""
+      #     end
+      #
+      #     def initiate!
+      #       { redirect_url: "https://..." }
+      #     end
+      #
+      #     def complete!(params = {})
+      #       # finalize payment
+      #     end
+      #
+      #     def reject!(params = {})
+      #       # handle rejection
+      #     end
+      #   end
+      class Base
+        attr_reader :payment_request
+
+        # @param payment_request [RSB::Entitlements::PaymentRequest]
+        def initialize(payment_request)
+          @payment_request = payment_request
+        end
+
+        # --- Class methods (override in subclass) ---
+
+        # @return [Symbol] unique provider key
+        def self.provider_key
+          raise NotImplementedError, "#{name} must implement self.provider_key"
+        end
+
+        # @return [String] human-readable label
+        def self.provider_label
+          raise NotImplementedError, "#{name} must implement self.provider_label"
+        end
+
+        # @return [Boolean] whether admin must manually approve/reject
+        def self.manual_resolution?
+          false
+        end
+
+        # @return [Array<Symbol>] actions admin can take (e.g., [:approve, :reject])
+        def self.admin_actions
+          []
+        end
+
+        # @return [Boolean] whether approved requests can be refunded
+        def self.refundable?
+          false
+        end
+
+        # @return [Array<Symbol>] settings keys that must have non-default values at registration
+        def self.required_settings
+          []
+        end
+
+        # Declare provider-specific settings schema.
+        # The block receives the RSB::Settings::Schema DSL.
+        # An `enabled` setting is auto-added by the registry.
+        #
+        # @example
+        #   settings_schema do
+        #     setting :api_key, type: :string, default: ""
+        #   end
+        def self.settings_schema(&block)
+          if block_given?
+            @settings_schema_block = block
+          else
+            @settings_schema_block
+          end
+        end
+
+        # --- Instance methods (override in subclass) ---
+
+        # Start the payment flow. Called after PaymentRequest creation.
+        #
+        # @return [Hash] one of:
+        #   - { redirect_url: "..." } for redirect-based flows
+        #   - { instructions: "..." } for instruction-based flows
+        #   - { status: :completed } for instant flows
+        def initiate!
+          raise NotImplementedError, "#{self.class.name} must implement #initiate!"
+        end
+
+        # Finalize a successful payment. Called on admin approval or webhook confirmation.
+        #
+        # @param params [Hash] provider-specific completion params
+        # @return [void]
+        def complete!(params = {})
+          raise NotImplementedError, "#{self.class.name} must implement #complete!"
+        end
+
+        # Reject a payment. Called on admin rejection.
+        #
+        # @param params [Hash] provider-specific rejection params
+        # @return [void]
+        def reject!(params = {})
+          raise NotImplementedError, "#{self.class.name} must implement #reject!"
+        end
+
+        # Refund an approved payment. Only called if refundable? is true.
+        #
+        # @param params [Hash] provider-specific refund params
+        # @return [void]
+        # @raise [NotImplementedError] if provider does not support refunds
+        def refund!(params = {})
+          raise NotImplementedError, "#{self.class.name} does not support refunds"
+        end
+
+        # Provider-specific details for the admin show page.
+        #
+        # @return [Hash] { "Label" => "value", ... }
+        def admin_details
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/payment_provider/wire.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    module PaymentProvider
+      # Built-in wire transfer provider. Implements a manual approval flow:
+      # 1. initiate! stores bank details and returns payment instructions
+      # 2. Admin approves/rejects via admin panel
+      # 3. complete! grants the entitlement, reject! marks as rejected
+      #
+      # Settings (under entitlements.providers.wire.*):
+      # - enabled (boolean, default: true)
+      # - instructions (string, default: "") — custom instructions template
+      # - bank_name (string, default: "")
+      # - account_number (string, default: "")
+      # - routing_number (string, default: "")
+      # - auto_expire_hours (integer, default: 72)
+      class Wire < Base
+        def self.provider_key
+          :wire
+        end
+
+        def self.provider_label
+          'Wire Transfer'
+        end
+
+        def self.manual_resolution?
+          true
+        end
+
+        def self.admin_actions
+          %i[approve reject]
+        end
+
+        def self.refundable?
+          false
+        end
+
+        settings_schema do
+          setting :instructions,
+                  type: :string,
+                  default: '',
+                  depends_on: 'entitlements.providers.wire.enabled',
+                  description: 'Custom payment instructions template (supports %<amount>s, %<currency>s, %<bank_name>s, %<account_number>s, %<routing_number>s)'
+
+          setting :bank_name,
+                  type: :string,
+                  default: '',
+                  depends_on: 'entitlements.providers.wire.enabled',
+                  description: 'Bank name for wire transfer details'
+
+          setting :account_number,
+                  type: :string,
+                  default: '',
+                  depends_on: 'entitlements.providers.wire.enabled',
+                  description: 'Account number for wire transfer'
+
+          setting :routing_number,
+                  type: :string,
+                  default: '',
+                  depends_on: 'entitlements.providers.wire.enabled',
+                  description: 'Routing number for wire transfer'
+
+          setting :auto_expire_hours,
+                  type: :integer,
+                  default: 72,
+                  depends_on: 'entitlements.providers.wire.enabled',
+                  description: 'Hours before wire transfer requests auto-expire'
+        end
+
+        # Start the wire transfer flow.
+        # Stores bank details in provider_data, sets expiry, transitions to processing.
+        #
+        # @return [Hash] { instructions: "Please wire $X to..." }
+        def initiate!
+          bank_name = setting('bank_name')
+          account_number = setting('account_number')
+          routing_number = setting('routing_number')
+          auto_expire_hours = setting('auto_expire_hours').to_i
+          custom_instructions = setting('instructions')
+
+          payment_request.update!(
+            status: 'processing',
+            expires_at: auto_expire_hours.hours.from_now,
+            provider_data: {
+              'bank_name' => bank_name,
+              'account_number' => account_number,
+              'routing_number' => routing_number,
+              'instructions_sent_at' => Time.current.iso8601
+            }
+          )
+
+          amount = format_amount(payment_request.amount_cents, payment_request.currency)
+          instructions = build_instructions(
+            custom_instructions,
+            amount: amount,
+            currency: payment_request.currency,
+            bank_name: bank_name,
+            account_number: account_number,
+            routing_number: routing_number
+          )
+
+          { instructions: instructions }
+        end
+
+        # Approve the wire transfer. Grants entitlement to the requestable.
+        #
+        # @param params [Hash] unused
+        # @return [void]
+        def complete!(_params = {})
+          return unless payment_request.actionable?
+
+          entitlement = payment_request.requestable.grant_entitlement(
+            plan: payment_request.plan,
+            provider: payment_request.provider_key,
+            metadata: payment_request.metadata
+          )
+
+          payment_request.update!(
+            status: 'approved',
+            entitlement: entitlement
+          )
+        end
+
+        # Reject the wire transfer. No entitlement changes.
+        #
+        # @param params [Hash] unused
+        # @return [void]
+        def reject!(_params = {})
+          return unless payment_request.actionable?
+
+          payment_request.update!(status: 'rejected')
+        end
+
+        # Provider-specific details for admin show page.
+        #
+        # @return [Hash] { "Bank Name" => "...", ... }
+        def admin_details
+          data = payment_request.provider_data || {}
+          details = {}
+          details['Bank Name'] = data['bank_name'] if data['bank_name'].present?
+          details['Account Number'] = data['account_number'] if data['account_number'].present?
+          details['Routing Number'] = data['routing_number'] if data['routing_number'].present?
+          details['Instructions Sent At'] = data['instructions_sent_at'] if data['instructions_sent_at'].present?
+          details
+        end
+
+        private
+
+        # Read a wire provider setting.
+        #
+        # @param key [String] setting key (without provider prefix)
+        # @return [Object] the setting value
+        def setting(key)
+          RSB::Settings.get("entitlements.providers.wire.#{key}")
+        end
+
+        # Format cents into a human-readable amount string.
+        #
+        # @param cents [Integer]
+        # @param currency [String]
+        # @return [String] e.g., "$99.00"
+        def format_amount(cents, currency)
+          dollars = cents / 100.0
+          symbol = currency.upcase == 'USD' ? '$' : currency.upcase
+          "#{symbol}#{'%.2f' % dollars}"
+        end
+
+        # Build instructions string from template or default.
+        #
+        # @param template [String] custom template (may be blank)
+        # @param kwargs [Hash] substitution variables
+        # @return [String]
+        def build_instructions(template, **kwargs)
+          if template.present?
+            template % kwargs
+          else
+            parts = ["Please wire #{kwargs[:amount]} to"]
+            parts << kwargs[:bank_name] if kwargs[:bank_name].present?
+            parts << "(Account: #{kwargs[:account_number]})" if kwargs[:account_number].present?
+            parts << "(Routing: #{kwargs[:routing_number]})" if kwargs[:routing_number].present?
+            parts.join(' ')
+          end
+        end
+      end
+    end
+  end
+end