rsb-entitlements 0.9.1

data/lib/rsb/entitlements/period_key_calculator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    # Computes period keys for usage tracking from period types.
+    #
+    # Period keys are used to bucket usage records by time period:
+    # - daily: "YYYY-MM-DD" (ISO 8601 date)
+    # - weekly: "YYYY-WNN" (ISO 8601 week number, Monday start)
+    # - monthly: "YYYY-MM"
+    # - nil/empty: "__cumulative__" (lifetime/no reset)
+    #
+    # @example
+    #   PeriodKeyCalculator.current_key("daily")
+    #   # => "2026-02-13"
+    #
+    #   PeriodKeyCalculator.current_key("weekly", Time.new(2026, 2, 13))
+    #   # => "2026-W07"
+    #
+    #   PeriodKeyCalculator.current_key(nil)
+    #   # => "__cumulative__"
+    module PeriodKeyCalculator
+      # Constant for cumulative (non-resetting) period keys.
+      CUMULATIVE_KEY = '__cumulative__'
+
+      # Compute the period key for a given period type and time.
+      #
+      # @param period [String, Symbol, nil] The period type ("daily", "weekly", "monthly", or nil)
+      # @param time [Time, ActiveSupport::TimeWithZone] The time to compute the key for (defaults to Time.current)
+      # @return [String] The period key string
+      #
+      # @example Daily period
+      #   current_key("daily", Time.new(2026, 2, 13, 10, 30, 0))
+      #   # => "2026-02-13"
+      #
+      # @example Weekly period
+      #   current_key("weekly", Time.new(2026, 2, 13, 10, 0, 0))
+      #   # => "2026-W07"
+      #
+      # @example Monthly period
+      #   current_key("monthly", Time.new(2026, 2, 13, 10, 0, 0))
+      #   # => "2026-02"
+      #
+      # @example Cumulative period
+      #   current_key(nil)
+      #   # => "__cumulative__"
+      def self.current_key(period, time = Time.current)
+        case period&.to_s
+        when 'daily'   then time.strftime('%Y-%m-%d')
+        when 'weekly'  then time.strftime('%G-W%V')
+        when 'monthly' then time.strftime('%Y-%m')
+        else CUMULATIVE_KEY
+        end
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/provider_definition.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    # Immutable data object representing a registered payment provider.
+    # Built from a PaymentProvider::Base subclass via .build_from.
+    #
+    # @example
+    #   definition = ProviderDefinition.build_from(MyProvider)
+    #   definition.key            # => :my_provider
+    #   definition.label          # => "My Provider"
+    #   definition.provider_class # => MyProvider
+    ProviderDefinition = Data.define(
+      :key,               # Symbol — unique provider key
+      :label,             # String — human-readable label
+      :provider_class,    # Class — the PaymentProvider::Base subclass
+      :manual_resolution, # Boolean — whether admin must approve/reject
+      :admin_actions,     # Array<Symbol> — actions admin can take
+      :refundable         # Boolean — whether refunds are supported
+    ) do
+      # Build a ProviderDefinition from a PaymentProvider::Base subclass.
+      #
+      # @param klass [Class] a class inheriting from PaymentProvider::Base
+      # @return [ProviderDefinition]
+      # @raise [ArgumentError] if klass does not inherit from Base
+      def self.build_from(klass)
+        unless klass < PaymentProvider::Base
+          raise ArgumentError,
+                "#{klass} must inherit from RSB::Entitlements::PaymentProvider::Base"
+        end
+
+        new(
+          key: klass.provider_key,
+          label: klass.provider_label,
+          provider_class: klass,
+          manual_resolution: klass.manual_resolution?,
+          admin_actions: klass.admin_actions,
+          refundable: klass.refundable?
+        )
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/provider_registry.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    # Registry for payment provider classes. Providers register by passing
+    # their class (which must inherit from PaymentProvider::Base).
+    # The registry validates the class, builds a ProviderDefinition,
+    # and registers the provider's settings schema into RSB::Settings.
+    #
+    # @example
+    #   RSB::Entitlements.providers.register(MyProvider)
+    #   RSB::Entitlements.providers.find(:my_provider)
+    #   RSB::Entitlements.providers.enabled
+    class ProviderRegistry
+      def initialize
+        @definitions = {}
+      end
+
+      # Register a payment provider class.
+      #
+      # @param provider_class [Class] must inherit from PaymentProvider::Base
+      # @return [ProviderDefinition]
+      # @raise [ArgumentError] if class is invalid, key is duplicate, or required settings are missing
+      def register(provider_class)
+        unless provider_class.is_a?(Class) && provider_class < PaymentProvider::Base
+          raise ArgumentError,
+                "#{provider_class} must inherit from RSB::Entitlements::PaymentProvider::Base"
+        end
+
+        key = provider_class.provider_key
+        raise ArgumentError, "Provider key :#{key} is already registered" if @definitions.key?(key)
+
+        # Register provider's settings schema (if declared)
+        register_provider_settings(provider_class)
+
+        # Validate required settings have non-default values
+        validate_required_settings(provider_class)
+
+        # Build and store the definition
+        definition = ProviderDefinition.build_from(provider_class)
+        @definitions[key] = definition
+        definition
+      end
+
+      # Find a provider definition by key.
+      #
+      # @param key [Symbol, String] provider key
+      # @return [ProviderDefinition, nil]
+      def find(key)
+        @definitions[key.to_sym]
+      end
+
+      # All registered provider definitions.
+      #
+      # @return [Array<ProviderDefinition>]
+      def all
+        @definitions.values
+      end
+
+      # All registered provider keys.
+      #
+      # @return [Array<Symbol>]
+      def keys
+        @definitions.keys
+      end
+
+      # Providers where the `entitlements.providers.<key>.enabled` setting is true.
+      #
+      # @return [Array<ProviderDefinition>]
+      def enabled
+        all.reject do |definition|
+          RSB::Settings.get("entitlements.providers.#{definition.key}.enabled") == false
+        end
+      end
+
+      # Array of [label, key] pairs for form dropdowns. Only includes enabled providers.
+      #
+      # @return [Array<Array(String, String)>]
+      def for_select
+        enabled.map { |d| [d.label, d.key.to_s] }
+      end
+
+      private
+
+      # Register the provider's settings schema into RSB::Settings
+      # under the `entitlements` category with compound keys like
+      # `providers.<key>.enabled`.
+      # Adds an `enabled` setting (default: true) unless the provider
+      # defines its own `enabled` setting.
+      def register_provider_settings(provider_class)
+        key = provider_class.provider_key
+        schema_block = provider_class.settings_schema
+        prefix = "providers.#{key}"
+        provider_label = provider_class.provider_label
+
+        schema = RSB::Settings::Schema.new('entitlements')
+
+        # Collect provider's custom settings first to check for enabled override
+        custom_settings = []
+        provider_defines_enabled = false
+
+        if schema_block
+          collector = RSB::Settings::Schema.new('_collector')
+          collector.instance_eval(&schema_block)
+          custom_settings = collector.definitions
+          provider_defines_enabled = custom_settings.any? { |defn| defn.key == :enabled }
+        end
+
+        # Add auto-generated enabled setting only if provider doesn't define it
+        unless provider_defines_enabled
+          schema.setting :"#{prefix}.enabled",
+                         type: :boolean,
+                         default: true,
+                         description: "Enable #{provider_label} provider"
+        end
+
+        # Register all provider's settings with the prefix
+        custom_settings.each do |defn|
+          schema.setting :"#{prefix}.#{defn.key}",
+                         type: defn.type,
+                         default: defn.default,
+                         description: defn.description
+        end
+
+        RSB::Settings.registry.register(schema)
+      end
+
+      # Validate that all required settings have non-default values.
+      def validate_required_settings(provider_class)
+        return if provider_class.required_settings.empty?
+
+        key = provider_class.provider_key
+        missing = provider_class.required_settings.select do |setting_key|
+          value = RSB::Settings.get("entitlements.providers.#{key}.#{setting_key}")
+          value.nil? || value == ''
+        end
+
+        return if missing.empty?
+
+        raise ArgumentError,
+              "Provider :#{key} has required settings that are not configured: #{missing.join(', ')}"
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/settings_schema.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    class SettingsSchema
+      def self.build
+        RSB::Settings::Schema.new('entitlements') do
+          setting :default_currency,
+                  type: :string,
+                  default: 'usd',
+                  group: 'General',
+                  description: 'Default currency code'
+
+          setting :trial_days,
+                  type: :integer,
+                  default: 14,
+                  group: 'General',
+                  description: 'Default trial period in days'
+
+          setting :grace_period_days,
+                  type: :integer,
+                  default: 3,
+                  group: 'General',
+                  description: 'Grace period after entitlement expiry (days)'
+
+          setting :auto_create_counters,
+                  type: :boolean,
+                  default: true,
+                  group: 'General',
+                  description: 'Auto-create usage counters when entitlement is granted'
+
+          setting :on_plan_change_usage,
+                  type: :string,
+                  default: 'continue',
+                  group: 'General',
+                  description: "Behavior on plan change: 'continue' (carry over usage) or 'reset' (fresh counter)"
+
+          setting :payment_request_expiry_hours,
+                  type: :integer,
+                  default: 72,
+                  group: 'General',
+                  description: 'Default expiry for payment requests (hours)'
+        end
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/test_helper.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module RSB
+  module Entitlements
+    module TestHelper
+      extend ActiveSupport::Concern
+
+      included do
+        setup do
+          RSB::Entitlements.reset!
+        end
+
+        teardown do
+          RSB::Entitlements.reset!
+        end
+      end
+
+      def create_test_plan(name: 'Test Plan', slug: nil, **overrides)
+        slug ||= "test-plan-#{SecureRandom.hex(4)}"
+        RSB::Entitlements::Plan.create!({
+          name: name,
+          slug: slug,
+          interval: 'monthly',
+          price_cents: 1000,
+          currency: 'usd',
+          features: {},
+          limits: {},
+          metadata: {},
+          active: true
+        }.merge(overrides))
+      end
+
+      def grant_test_entitlement(entitleable, plan: nil, provider: 'admin')
+        plan ||= create_test_plan
+        entitleable.grant_entitlement(plan: plan, provider: provider)
+      end
+
+      # Register a minimal test provider for use in tests.
+      # Returns the provider class.
+      #
+      # @param key [Symbol] provider key (default: :test)
+      # @param label [String] provider label (default: "Test Provider")
+      # @param manual_resolution [Boolean] (default: false)
+      # @param admin_actions [Array<Symbol>] (default: [])
+      # @param refundable [Boolean] (default: false)
+      # @param initiate_result [Hash] what initiate! returns (default: { status: :completed })
+      # @return [Class] the provider class
+      def register_test_provider(
+        key: :test,
+        label: 'Test Provider',
+        manual_resolution: false,
+        admin_actions: [],
+        refundable: false,
+        initiate_result: { status: :completed }
+      )
+        provider_class = Class.new(RSB::Entitlements::PaymentProvider::Base) do
+          define_singleton_method(:provider_key) { key }
+          define_singleton_method(:provider_label) { label }
+          define_singleton_method(:manual_resolution?) { manual_resolution }
+          define_singleton_method(:admin_actions) { admin_actions }
+          define_singleton_method(:refundable?) { refundable }
+
+          define_method(:initiate!) { initiate_result }
+          define_method(:complete!) { |_params = {}| nil }
+          define_method(:reject!) { |_params = {}| nil }
+        end
+
+        RSB::Entitlements.providers.register(provider_class)
+        provider_class
+      end
+
+      # Create a test payment request.
+      #
+      # @param requestable [ActiveRecord::Base] the polymorphic owner
+      # @param plan [RSB::Entitlements::Plan] the plan
+      # @param provider_key [String] provider key (default: "wire")
+      # @param status [String] status (default: "pending")
+      # @return [RSB::Entitlements::PaymentRequest]
+      def create_test_payment_request(requestable:, plan:, provider_key: 'wire', status: 'pending', **overrides)
+        RSB::Entitlements::PaymentRequest.create!({
+          requestable: requestable,
+          plan: plan,
+          provider_key: provider_key.to_s,
+          status: status,
+          amount_cents: plan.price_cents,
+          currency: plan.currency,
+          provider_data: {},
+          metadata: {}
+        }.merge(overrides))
+      end
+
+      # Create a test usage counter.
+      #
+      # @param countable [ActiveRecord::Base] the polymorphic owner
+      # @param metric [String] metric name
+      # @param plan [RSB::Entitlements::Plan] the plan
+      # @param period_key [String] period key (default: "__cumulative__")
+      # @param current_value [Integer] current usage value (default: 0)
+      # @param limit [Integer, nil] usage limit
+      # @return [RSB::Entitlements::UsageCounter]
+      def create_test_usage_counter(countable:, metric:, plan:, period_key: '__cumulative__', current_value: 0,
+                                    limit: nil)
+        RSB::Entitlements::UsageCounter.create!(
+          countable: countable,
+          metric: metric.to_s,
+          plan: plan,
+          period_key: period_key,
+          current_value: current_value,
+          limit: limit
+        )
+      end
+    end
+  end
+end

data/lib/rsb/entitlements/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative '../../../../lib/rsb/version' unless defined?(RSB::VERSION)
+
+module RSB
+  module Entitlements
+    VERSION = RSB::VERSION
+  end
+end

data/lib/rsb/entitlements.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rsb/settings'
+require 'rsb/entitlements/version'
+require 'rsb/entitlements/engine'
+require 'rsb/entitlements/configuration'
+require 'rsb/entitlements/provider_definition'
+require 'rsb/entitlements/provider_registry'
+require 'rsb/entitlements/payment_provider/base'
+require 'rsb/entitlements/payment_provider/wire'
+require 'rsb/entitlements/settings_schema'
+require 'rsb/entitlements/period_key_calculator'
+
+module RSB
+  module Entitlements
+    class << self
+      def providers
+        @providers ||= ProviderRegistry.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def settings_schema
+        @settings_schema ||= SettingsSchema.build
+      end
+
+      def reset!
+        @providers = ProviderRegistry.new
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: rsb-entitlements
+version: !ruby/object:Gem::Version
+  version: 0.9.1
+platform: ruby
+authors:
+- Aleksandr Marchenko
+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: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rsb-settings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+description: Flexible plan-based feature gating, entitlements, and metered usage tracking.
+  Drop-in Entitleable concern for any model. Extensible provider registry for payment
+  integrations.
+email:
+- alex@marchenko.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/controllers/rsb/entitlements/admin/payment_requests_controller.rb
+- app/controllers/rsb/entitlements/admin/plans_controller.rb
+- app/controllers/rsb/entitlements/admin/usage_counters_controller.rb
+- app/jobs/rsb/entitlements/application_job.rb
+- app/jobs/rsb/entitlements/entitlement_expiration_job.rb
+- app/jobs/rsb/entitlements/payment_request_expiration_job.rb
+- app/models/concerns/rsb/entitlements/entitleable.rb
+- app/models/rsb/entitlements/application_record.rb
+- app/models/rsb/entitlements/entitlement.rb
+- app/models/rsb/entitlements/payment_request.rb
+- app/models/rsb/entitlements/plan.rb
+- app/models/rsb/entitlements/usage_counter.rb
+- app/services/rsb/entitlements/usage_counter_service.rb
+- app/views/rsb/entitlements/admin/payment_requests/index.html.erb
+- app/views/rsb/entitlements/admin/payment_requests/show.html.erb
+- app/views/rsb/entitlements/admin/plans/_form.html.erb
+- app/views/rsb/entitlements/admin/plans/edit.html.erb
+- app/views/rsb/entitlements/admin/plans/index.html.erb
+- app/views/rsb/entitlements/admin/plans/new.html.erb
+- app/views/rsb/entitlements/admin/plans/show.html.erb
+- app/views/rsb/entitlements/admin/usage_counters/index.html.erb
+- app/views/rsb/entitlements/admin/usage_counters/trend.html.erb
+- config/locales/admin.en.yml
+- db/migrate/20260208200001_create_rsb_entitlements_plans.rb
+- db/migrate/20260208200002_create_rsb_entitlements_entitlements.rb
+- db/migrate/20260208200003_create_rsb_entitlements_usage_counters.rb
+- db/migrate/20260208200004_create_rsb_entitlements_payment_requests.rb
+- db/migrate/20260213000001_rework_usage_counters_to_ledger.rb
+- lib/generators/rsb/entitlements/install/install_generator.rb
+- lib/rsb/entitlements.rb
+- lib/rsb/entitlements/configuration.rb
+- lib/rsb/entitlements/engine.rb
+- lib/rsb/entitlements/payment_provider/base.rb
+- lib/rsb/entitlements/payment_provider/wire.rb
+- lib/rsb/entitlements/period_key_calculator.rb
+- lib/rsb/entitlements/provider_definition.rb
+- lib/rsb/entitlements/provider_registry.rb
+- lib/rsb/entitlements/settings_schema.rb
+- lib/rsb/entitlements/test_helper.rb
+- lib/rsb/entitlements/version.rb
+homepage: https://github.com/Rails-SaaS-Builder/rails-saas-builder
+licenses:
+- LGPL-3.0
+metadata:
+  source_code_uri: https://github.com/Rails-SaaS-Builder/rails-saas-builder
+  bug_tracker_uri: https://github.com/Rails-SaaS-Builder/rails-saas-builder/issues
+  changelog_uri: https://github.com/Rails-SaaS-Builder/rails-saas-builder/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Plans, entitlements & usage tracking for Rails SaaS Builder
+test_files: []