belt-pay 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 673206d18a5fad12255912de6c7833796e147e88e99ce32d70ba48ef727ff9e4
-  data.tar.gz: d5b2171c33ef68447b501183287ab53d209621e859e40a16e2721d0af60a74a2
+  metadata.gz: 614581460579c56502eed359de29c1f36f746c3a8697b6ba3aa073266740649b
+  data.tar.gz: 00d84db5eb7ce1c47f23f666b8eab1511ace5745e2ad18e48e8c9753b2751503
 SHA512:
-  metadata.gz: 475ef6bdadb87b2712145d0e69f3f74c58a7fa07f7a6d2f293e0a34aa19f6a340794feb1d74e76c7d8dd584a1576650c4572670a443b640f7336e2a4e1f16a6a
-  data.tar.gz: e03f179b799302a256b741ff882defab8064909ecef72c25f5ec3043e1c26d76fe2ffde9ae7c1014a6ad76c5d1b25dfe385d9df7ec860404e3a74f6d3c73f87a
+  metadata.gz: 51d01a9a411c28d3e080352bb265553b8de72d24e0166f953248910926b55bd139aa9a7864c7b7ba504a9a8470a12ef013ce1b5153f441c653ef97e847f1e65f
+  data.tar.gz: 4b8e05e523ca9abc3400a3455dfa7fb3b1adc0bd409eef90ed8856878e8938719663d45001ecbb3434e42fa17da07160be33f257acb753c900f9704ac05a7779

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.0.2 — 2026-09-05
+
+- **Plan DSL (convention over configuration).** Declare subscription plans, their
+  prices (per interval), limits, and feature flags once via `Belt::Pay.plans do ... end`,
+  then look them up by symbolic key everywhere. Inspired by how popular Ruby billing
+  gems keep plan definitions in code.
+  - `Belt::Pay::Plan` — a plan's marketing copy, per-interval Stripe prices, named
+    `limit`s (with `:unlimited`), and boolean `feature`s.
+  - `Belt::Pay::PlanRegistry` — `Belt::Pay.plans`, `Belt::Pay.plan(:key)`,
+    `Belt::Pay.plan_for_price(price_id)`.
+  - `Belt::Pay.subscribe` / `Billable#subscribe!` now accept a `plan:` key (resolving
+    the right Stripe price for the `interval:`) in addition to a raw `price_id:`.
+  - `Billable` gains `#plan`, `#on_plan?`, `#plan_allows?(feature)`,
+    `#within_limit?(name, usage)`, and a `pay_plan` attribute.
+
 ## 0.0.1 — 2026-09-01
 
 - Initial release

data/README.md

@@ -19,6 +19,67 @@ bundle install
 belt generate pay
 ```
 
+## Defining Plans (Convention over Configuration)
+
+Declare your plans once — their prices, limits, and feature flags live in code, not
+scattered across config. Look them up by a symbolic key everywhere else.
+
+```ruby
+# config/initializers/pay.rb (or wherever you boot)
+Belt::Pay.plans do
+  plan :free do
+    name  'Free'
+    description 'For small teams getting started'
+    limit :projects, 1
+    limit :seats,    3
+  end
+
+  plan :pro do
+    name        'Pro'
+    description 'For growing teams'
+    featured                                   # highlight this plan in your UI
+    price 49,  interval: :month, stripe_price: ENV['STRIPE_PRO_MONTH']
+    price 490, interval: :year,  stripe_price: ENV['STRIPE_PRO_YEAR']
+    limit :projects, :unlimited
+    limit :seats,    :unlimited
+    feature :sso, :audit_logs
+  end
+end
+```
+
+Then use the plans:
+
+```ruby
+# Subscribe by plan key — belt-pay resolves the Stripe price for the interval
+customer.subscribe!(plan: :pro, interval: :year)
+
+# Look plans up
+Belt::Pay.plan(:pro).amount(interval: :month)   # => 49.0
+Belt::Pay.plans.paid                             # => [pro, ...]
+Belt::Pay.plans.featured                         # => the :pro plan
+Belt::Pay.plans.to_a                             # => [{ key:, name:, prices:, limits:, ... }] for your frontend
+
+# Gate features and enforce limits
+customer.on_plan?(:pro)                          # => true
+customer.plan_allows?(:sso)                      # => true
+customer.within_limit?(:projects, current_count) # => false once the ceiling is hit
+```
+
+### Plan API
+
+| Method | Description |
+|--------|-------------|
+| `Belt::Pay.plans { ... }` | Declare plans (block) or read the registry |
+| `Belt::Pay.plan(:key)` | Look up one plan (nil if undeclared) |
+| `Belt::Pay.plan_for_price(id)` | Find the plan owning a Stripe price ID |
+| `plan.amount(interval:)` | Price in whole currency units |
+| `plan.amount_cents(interval:)` | Price in cents |
+| `plan.stripe_price_id(interval:)` | Stripe price ID for an interval |
+| `plan.limit(:name)` | Read a limit (Integer, `:unlimited`, or nil) |
+| `plan.allows?(:name, usage)` | Is `usage` under the limit? |
+| `plan.includes_feature?(:name)` | Does the plan unlock a feature? |
+| `plan.to_h` | Serialize for API/frontend |
+
 ## What You Get
 
 ### From the gem (no generation needed)

data/lib/belt/pay/billable.rb

@@ -21,7 +21,7 @@ module Belt
       extend ActiveSupport::Concern
 
       included do
-        attr_accessor :pay_customer_id, :pay_subscription_id, :pay_payment_method_id
+        attr_accessor :pay_customer_id, :pay_subscription_id, :pay_payment_method_id, :pay_plan
       end
 
       # Ensure this customer has a provider customer account.
@@ -45,16 +45,60 @@ module Belt
       end
 
       # Subscribe to a plan.
-      # @param price_id [String] Provider price ID
+      #
+      # Pass either a declared plan key (`plan:`) or a raw `price_id:`.
+      # When a plan key is given, the customer's `pay_plan` is recorded so
+      # limits/features can be checked later without a Stripe round-trip.
+      #
+      # @param plan [Symbol, String, nil] A declared plan key (see Belt::Pay.plans)
+      # @param price_id [String, nil] Provider price ID (overrides plan lookup)
+      # @param interval [Symbol] Billing interval to pick from the plan (default :month)
       # @param metadata [Hash] Additional metadata to store on the subscription
       # @return [Hash] { subscription_id:, status: }
-      def subscribe!(price_id:, metadata: {})
-        result = Belt::Pay.subscribe(self, price_id: price_id, metadata: metadata)
+      def subscribe!(plan: nil, price_id: nil, interval: :month, metadata: {})
+        result = Belt::Pay.subscribe(self, plan: plan, price_id: price_id,
+                                           interval: interval, metadata: metadata)
         self.pay_subscription_id = result[:subscription_id]
+        self.pay_plan = plan.to_s if plan
         save(validate: false)
         result
       end
 
+      # The declared plan this customer is currently on (or nil).
+      # @return [Belt::Pay::Plan, nil]
+      def plan
+        Belt::Pay.plan(pay_plan) if pay_plan
+      end
+
+      # Is this customer on a given plan?
+      # @param plan_key [Symbol, String]
+      # @return [Boolean]
+      def on_plan?(plan_key)
+        pay_plan.to_s == plan_key.to_s
+      end
+
+      # Does this customer's plan allow a named feature?
+      # @param feature_name [Symbol, String]
+      # @return [Boolean]
+      def plan_allows?(feature_name)
+        p = plan
+        return false unless p
+
+        p.includes_feature?(feature_name)
+      end
+
+      # Is the given usage under this customer's plan limit for `limit_name`?
+      # Returns true when there is no plan or the limit is unlimited/undeclared.
+      # @param limit_name [Symbol, String]
+      # @param usage [Integer] Current usage count
+      # @return [Boolean]
+      def within_limit?(limit_name, usage)
+        p = plan
+        return true unless p
+
+        p.allows?(limit_name, usage)
+      end
+
       # Check if customer has an active subscription.
       # @return [Boolean]
       def active_subscription?

data/lib/belt/pay/plan.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Belt
+  module Pay
+    # A single subscription plan definition.
+    #
+    # Plans are declared once (convention over configuration) via `Belt::Pay.plans`
+    # and looked up by their symbolic key. A plan bundles the human-facing marketing
+    # copy (name, description, price), the Stripe price IDs for each billing interval,
+    # and a set of named limits that the rest of your app can gate features on.
+    #
+    # @example
+    #   Belt::Pay.plans do
+    #     plan :free do
+    #       name  'Free'
+    #       price 0
+    #       limit :projects, 1
+    #       limit :seats,    3
+    #     end
+    #
+    #     plan :pro do
+    #       name        'Pro'
+    #       description 'For growing teams'
+    #       price       49, interval: :month, stripe_price: 'price_month_xxx'
+    #       price       490, interval: :year, stripe_price: 'price_year_xxx'
+    #       limit :projects, 25
+    #       limit :seats,    :unlimited
+    #       feature :sso
+    #     end
+    #   end
+    #
+    class Plan
+      # Sentinel used for limits that have no ceiling.
+      UNLIMITED = :unlimited
+
+      attr_reader :key
+
+      def initialize(key)
+        @key         = key.to_sym
+        @name        = key.to_s.capitalize
+        @description = nil
+        @featured    = false
+        @prices      = {} # interval => { amount_cents:, stripe_price: }
+        @limits      = {} # name => Integer | :unlimited
+        @features    = [] # list of symbolic feature flags
+        @metadata    = {}
+      end
+
+      # --- DSL setters (called inside `plan :key do ... end`) ---
+
+      # Human-facing plan name. Reader when called with no args.
+      def name(value = nil)
+        return @name if value.nil?
+
+        @name = value
+      end
+
+      # Marketing description. Reader when called with no args.
+      def description(value = nil)
+        return @description if value.nil?
+
+        @description = value
+      end
+
+      # Mark this plan as the "most popular" / highlighted plan.
+      def featured(value = true)
+        @featured = value
+      end
+
+      # Declare a price for a billing interval.
+      #
+      # @param amount [Numeric] Price in whole currency units (e.g. dollars). Stored as cents.
+      # @param interval [Symbol] :month | :year | :once (default :month)
+      # @param stripe_price [String, nil] The Stripe price ID backing this amount.
+      def price(amount, interval: :month, stripe_price: nil)
+        @prices[interval.to_sym] = {
+          amount_cents: (amount.to_f * 100).round,
+          stripe_price: stripe_price
+        }
+      end
+
+      # Declare a boolean feature this plan unlocks (e.g. :sso, :audit_logs).
+      def feature(*names)
+        @features.concat(names.map(&:to_sym))
+      end
+
+      # Arbitrary free-form metadata carried onto Stripe subscriptions.
+      def metadata(hash = nil)
+        return @metadata if hash.nil?
+
+        @metadata.merge!(hash)
+      end
+
+      # --- Query API (used by the rest of your app) ---
+
+      def featured?
+        @featured
+      end
+
+      # The Stripe price ID for a given interval (defaults to :month, falls back
+      # to the only price if the plan is single-interval).
+      def stripe_price_id(interval: :month)
+        entry = @prices[interval.to_sym] || @prices.values.first
+        entry && entry[:stripe_price]
+      end
+
+      # Price in cents for a given interval.
+      def amount_cents(interval: :month)
+        entry = @prices[interval.to_sym] || @prices.values.first
+        entry ? entry[:amount_cents] : 0
+      end
+
+      # Price in whole currency units (e.g. dollars) for a given interval.
+      def amount(interval: :month)
+        amount_cents(interval: interval) / 100.0
+      end
+
+      # Intervals this plan is priced for.
+      def intervals
+        @prices.keys
+      end
+
+      # Is this a free plan (no paid intervals)?
+      def free?
+        @prices.empty? || @prices.values.all? { |p| p[:amount_cents].zero? }
+      end
+
+      # Declare (2-arg form) or read (1-arg form) a named limit.
+      # Use `:unlimited` for no ceiling.
+      #
+      # @example declare
+      #   limit :projects, 25
+      #   limit :seats, :unlimited
+      # @example read
+      #   plan.limit(:projects) # => 25
+      #
+      # @param name [Symbol] Limit name (e.g. :projects, :seats)
+      # @param value [Integer, Symbol] Ceiling, or :unlimited (setter form only)
+      # @return [Integer, Symbol, nil] The limit when reading; nil if undeclared.
+      def limit(name, *value)
+        if value.empty?
+          @limits[name.to_sym]
+        else
+          v = value.first
+          @limits[name.to_sym] = v == UNLIMITED ? UNLIMITED : Integer(v)
+        end
+      end
+
+      # Is a given usage count allowed under this plan's limit?
+      #
+      # @param name [Symbol] Limit name
+      # @param usage [Integer] Current usage count
+      # @return [Boolean] true if under (or at) the limit, or unlimited/undeclared
+      def allows?(name, usage)
+        ceiling = @limits[name.to_sym]
+        return true if ceiling.nil? || ceiling == UNLIMITED
+
+        usage < ceiling
+      end
+
+      # Does this plan include a boolean feature?
+      def includes_feature?(name)
+        @features.include?(name.to_sym)
+      end
+
+      def limits
+        @limits.dup
+      end
+
+      def features
+        @features.dup
+      end
+
+      # Serialize for API/frontend consumption.
+      def to_h
+        {
+          key: @key.to_s,
+          name: @name,
+          description: @description,
+          featured: @featured,
+          free: free?,
+          prices: @prices.transform_values { |p| p.dup },
+          limits: @limits.transform_values { |v| v == UNLIMITED ? 'unlimited' : v },
+          features: @features.map(&:to_s)
+        }
+      end
+    end
+  end
+end

data/lib/belt/pay/plan_registry.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'plan'
+
+module Belt
+  module Pay
+    # Registry of declared subscription plans.
+    #
+    # Plans are declared once at boot (convention over configuration) and looked
+    # up by their symbolic key everywhere else. This mirrors how popular Ruby
+    # billing gems keep plan definitions in code rather than scattered config.
+    #
+    # @example Declaring plans
+    #   Belt::Pay.plans do
+    #     plan :free do
+    #       name  'Free'
+    #       limit :projects, 1
+    #     end
+    #
+    #     plan :pro do
+    #       name 'Pro'
+    #       featured
+    #       price 49,  interval: :month, stripe_price: ENV['STRIPE_PRO_MONTH']
+    #       price 490, interval: :year,  stripe_price: ENV['STRIPE_PRO_YEAR']
+    #       limit :projects, :unlimited
+    #     end
+    #   end
+    #
+    # @example Looking plans up
+    #   Belt::Pay.plan(:pro)                  # => #<Belt::Pay::Plan key=:pro>
+    #   Belt::Pay.plans.all                   # => [free, pro, ...]
+    #   Belt::Pay.plan_for_price('price_xxx') # => the plan owning that Stripe price
+    #
+    class PlanRegistry
+      def initialize
+        @plans = {}
+      end
+
+      # DSL entry: declare a plan by key with a config block.
+      def plan(key, &block)
+        p = @plans[key.to_sym] || Plan.new(key)
+        p.instance_eval(&block) if block
+        @plans[key.to_sym] = p
+        p
+      end
+
+      # Look up a plan by key. Returns nil if not declared.
+      def find(key)
+        return nil if key.nil?
+
+        @plans[key.to_sym]
+      end
+      alias [] find
+
+      # Look up a plan by key, raising if it isn't declared.
+      def find!(key)
+        find(key) || raise(Error, "Unknown plan: #{key.inspect}. " \
+                                  "Declared plans: #{keys.map(&:inspect).join(', ')}")
+      end
+
+      # Find the plan that owns a given Stripe price ID (across all intervals).
+      def find_by_stripe_price(price_id)
+        return nil if price_id.nil?
+
+        @plans.values.find do |pl|
+          pl.intervals.any? { |i| pl.stripe_price_id(interval: i) == price_id }
+        end
+      end
+
+      # All declared plans, in declaration order.
+      def all
+        @plans.values
+      end
+
+      # All declared plan keys.
+      def keys
+        @plans.keys
+      end
+
+      # Only the paid plans (have at least one non-zero price).
+      def paid
+        @plans.values.reject(&:free?)
+      end
+
+      # The single plan marked `featured` (or nil).
+      def featured
+        @plans.values.find(&:featured?)
+      end
+
+      def empty?
+        @plans.empty?
+      end
+
+      # Serialize every plan for API/frontend consumption.
+      def to_a
+        all.map(&:to_h)
+      end
+
+      # Wipe all plans (useful for tests).
+      def reset!
+        @plans = {}
+      end
+    end
+  end
+end

data/lib/belt/pay/version.rb

@@ -2,6 +2,6 @@
 
 module Belt
   module Pay
-    VERSION = '0.0.1'
+    VERSION = '0.0.2'
   end
 end

data/lib/belt/pay.rb

@@ -2,6 +2,7 @@
 
 require_relative 'pay/version'
 require_relative 'pay/configuration'
+require_relative 'pay/plan_registry'
 require_relative 'pay/transaction'
 require_relative 'pay/billable'
 require_relative 'pay/checkout'
@@ -33,6 +34,40 @@ module Belt
         @configuration = Configuration.new
       end
 
+      # --- Plans (convention-over-configuration subscription plan DSL) ---
+
+      # The plan registry. Pass a block to declare plans, or call with no block
+      # to read the registry.
+      #
+      # @example
+      #   Belt::Pay.plans do
+      #     plan(:pro) { name 'Pro'; price 49, stripe_price: 'price_xxx' }
+      #   end
+      #
+      # @return [Belt::Pay::PlanRegistry]
+      def plans(&block)
+        @plans ||= PlanRegistry.new
+        @plans.instance_eval(&block) if block
+        @plans
+      end
+
+      # Look up a single plan by key. Returns nil if undeclared.
+      # @return [Belt::Pay::Plan, nil]
+      def plan(key)
+        plans.find(key)
+      end
+
+      # Find the declared plan backing a given Stripe price ID.
+      # @return [Belt::Pay::Plan, nil]
+      def plan_for_price(price_id)
+        plans.find_by_stripe_price(price_id)
+      end
+
+      # Reset the plan registry (useful for tests).
+      def reset_plans!
+        @plans = PlanRegistry.new
+      end
+
       # --- Convenience API (provider-agnostic names) ---
 
       # Ensure a payment provider customer exists for this user.
@@ -66,12 +101,21 @@ module Belt
       end
 
       # Subscribe a customer to a plan.
+      #
+      # Pass either a declared plan (`plan:`) — which resolves to the right Stripe
+      # price for the interval — or a raw provider `price_id:`.
+      #
       # @param customer [Object] Your app's user/customer model instance
-      # @param price_id [String] Provider price/plan ID
+      # @param plan [Symbol, String, nil] A declared plan key (see Belt::Pay.plans)
+      # @param price_id [String, nil] Provider price/plan ID (overrides plan lookup)
+      # @param interval [Symbol] Billing interval to pick from the plan (default :month)
       # @param metadata [Hash] Additional metadata
       # @return [Hash] { subscription_id:, status: }
-      def subscribe(customer, price_id:, metadata: {})
-        Subscription.create(customer, price_id: price_id, metadata: metadata)
+      def subscribe(customer, plan: nil, price_id: nil, interval: :month, metadata: {})
+        price_id ||= resolve_plan_price(plan, interval)
+        meta = metadata.dup
+        meta[:plan] ||= plan.to_s if plan
+        Subscription.create(customer, price_id: price_id, metadata: meta)
       end
 
       # Cancel a customer's subscription.
@@ -111,6 +155,17 @@ module Belt
 
       private
 
+      # Resolve a plan key (+ interval) to its Stripe price ID.
+      def resolve_plan_price(plan_key, interval)
+        return nil if plan_key.nil?
+
+        pl = plans.find!(plan_key)
+        price_id = pl.stripe_price_id(interval: interval)
+        raise ConfigurationError, "Plan #{plan_key.inspect} has no Stripe price for interval #{interval.inspect}" unless price_id
+
+        price_id
+      end
+
       def resolve_provider
         case configuration.provider
         when :stripe

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt-pay
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Stowzilla
@@ -13,14 +13,14 @@ dependencies:
   name: belt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.2'
 - !ruby/object:Gem::Dependency
@@ -59,6 +59,8 @@ files:
 - lib/belt/pay/controllers/webhooks_controller.rb
 - lib/belt/pay/customer_provisioner.rb
 - lib/belt/pay/payment_method_attacher.rb
+- lib/belt/pay/plan.rb
+- lib/belt/pay/plan_registry.rb
 - lib/belt/pay/providers/stripe.rb
 - lib/belt/pay/setup_intent_creator.rb
 - lib/belt/pay/subscription.rb