belt-pay 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 673206d18a5fad12255912de6c7833796e147e88e99ce32d70ba48ef727ff9e4
-  data.tar.gz: d5b2171c33ef68447b501183287ab53d209621e859e40a16e2721d0af60a74a2
+  metadata.gz: 6949c31f8f5adaec1e1a6c6d08e36bac5fb3cdac59fd2054a46be18869fa196c
+  data.tar.gz: e07b2808dc053c34235ea4ec6ef183858c43401279a5f3d4b1c92ce7b46d2af1
 SHA512:
-  metadata.gz: 475ef6bdadb87b2712145d0e69f3f74c58a7fa07f7a6d2f293e0a34aa19f6a340794feb1d74e76c7d8dd584a1576650c4572670a443b640f7336e2a4e1f16a6a
-  data.tar.gz: e03f179b799302a256b741ff882defab8064909ecef72c25f5ec3043e1c26d76fe2ffde9ae7c1014a6ad76c5d1b25dfe385d9df7ec860404e3a74f6d3c73f87a
+  metadata.gz: 5ba551d781ba509f1aa8b93f47c84b8d22e6af8727659f7643ec73d6876b58811c7383fd8780c086a1c38dd8eefc3a546efc11297ab9ea2856be0c4a6fcb58ba
+  data.tar.gz: 0e0b3dddaa5d235ba5d10362cc7d9d737ebfbc5f69649620b0adc5d42eb43d92a884560947a47cc53604f2080fd5179106eaab3015d527c6c274b9cd6f3f83b9

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.0.3 — 2026-10-02
+
+- Add Belt-native `pay:setup`, `pay:show`, and `pay:edit` tasks through Belt's
+  gem Rake-task extension mechanism. Select an environment with `BELT_ENV` or standard
+  task-argument syntax such as `belt 'pay:setup[dev]'`.
+- Make `belt pay:setup` the happy path: it prompts without echo for Stripe's API and
+  webhook signing secrets, preserves either existing value when left blank, and writes
+  directly through the AWS SDK.
+- Add `belt pay:show` and `belt pay:edit` for inspecting and securely editing each
+  environment's Stripe JSON secret in AWS Secrets Manager.
+- Detect the Belt app name, AWS profile, and region from the selected environment,
+  with environment-variable and explicit overrides for custom setups.
+- Retain the packaged `belt-pay secrets:*` executable as a backward-compatible alias,
+  pin the AWS Secrets Manager SDK, and include the pinned Rake runtime required for
+  task dispatch in fresh Belt apps.
+
+## 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)
@@ -106,6 +167,54 @@ The Stripe secret should contain:
 }
 ```
 
+### Setting Up and Managing Secrets
+
+Belt Pay hooks into Belt through its standard gem-provided Rake task mechanism. The
+guided happy path uses `BELT_ENV` to select the environment:
+
+```bash
+BELT_ENV=dev belt pay:setup
+```
+
+It prompts without echo for the Stripe secret key and webhook signing secret, then
+writes them directly through the AWS SDK. Leave either prompt blank to preserve its
+existing value, so you can run setup once for the API key and again after Stripe gives
+you the webhook signing secret.
+
+You can also pass the environment with standard Rake task-argument syntax:
+
+```bash
+belt 'pay:setup[dev]'
+```
+
+Rails-like inspection and arbitrary JSON editing remain available for advanced use:
+
+```bash
+BELT_ENV=dev belt pay:show
+EDITOR="code --wait" BELT_ENV=dev belt pay:edit
+# Or: belt 'pay:show[dev]' / belt 'pay:edit[dev]'
+```
+
+`pay:show` prints the complete decrypted JSON to stdout. `pay:edit` opens it with
+`$VISUAL` or `$EDITOR`, validates that the result is a JSON object, and writes a new
+Secrets Manager version only when the content changed. Its temporary file is mode
+`0600` and is removed when the editor closes. All write paths refuse to overwrite a
+secret that changed while the command was open.
+
+The tasks detect the application name from Terraform, the AWS profile from
+`infrastructure/<env>/belt.rb`, and the region from Terraform or AWS environment
+variables. Custom setups can override those values with `APP_NAME`,
+`BELT_PAY_SECRET_NAME`, `AWS_PROFILE`, and `AWS_REGION`:
+
+```bash
+APP_NAME=my_app BELT_ENV=prod AWS_PROFILE=my-prod-profile belt pay:setup
+BELT_PAY_SECRET_NAME=custom-stripe-secret BELT_ENV=prod belt pay:edit
+```
+
+Because `pay:show` intentionally reveals credentials, avoid redirecting its output to
+logs or sharing it in chat. The packaged `belt-pay secrets:*` executable remains as a
+backward-compatible alias, but the Belt-native tasks are the preferred interface.
+
 ## Common Patterns
 
 ### Annual Subscription (Feature Gating)

data/exe/belt-pay

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'belt/pay/cli'
+
+exit Belt::Pay::CLI.start(ARGV)

data/lib/belt/generators/pay_generator.rb

@@ -315,9 +315,11 @@ module Belt
                  # ...
                end
 
-            3. Create your Stripe API keys in Secrets Manager:
-               Secret name: <app_name>-<env>-stripe
-               Keys: stripe_secret_key, stripe_webhook_secret
+            3. Add your Stripe API keys to Secrets Manager:
+               BELT_ENV=<env> belt pay:setup
+
+               Values are prompted without echo. Leave the webhook secret blank
+               until Stripe gives it to you, then run setup again.
 
             4. Deploy:
                belt apply <env>

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/cli.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require 'io/console'
+require 'json'
+require 'optparse'
+require 'shellwords'
+require 'tempfile'
+require 'aws-sdk-secretsmanager'
+
+module Belt
+  module Pay
+    class CLI
+      class Error < StandardError; end
+
+      COMMANDS = %w[secrets:setup secrets:show secrets:edit].freeze
+
+      def self.start(args, input: $stdin, out: $stdout, err: $stderr)
+        new(args, input: input, out: out, err: err).run
+        0
+      rescue Error, OptionParser::ParseError => e
+        err.puts "Error: #{e.message}"
+        err.puts "Run `belt tasks --grep pay` for available Belt Pay commands."
+        1
+      rescue Aws::Errors::ServiceError => e
+        err.puts "AWS error: #{e.message}"
+        1
+      end
+
+      def initialize(args, input:, out:, err:)
+        @args = args.dup
+        @input = input
+        @out = out
+        @err = err
+        @options = {}
+      end
+
+      def run
+        command = @args.shift
+        if command.nil? || %w[help --help -h].include?(command)
+          @out.puts help
+          return
+        end
+
+        raise Error, "unknown command #{command.inspect}" unless COMMANDS.include?(command)
+
+        parse_options!
+        resolve_context!
+
+        case command
+        when 'secrets:setup' then setup
+        when 'secrets:show' then show
+        when 'secrets:edit' then edit
+        end
+      end
+
+      private
+
+      def parse_options!
+        parser.parse!(@args)
+        @environment = @args.shift || ENV['BELT_ENV']
+        raise Error, 'environment is required (for example, dev or prod)' if blank?(@environment)
+        raise Error, "unexpected argument #{@args.first.inspect}" unless @args.empty?
+      end
+
+      def parser
+        OptionParser.new do |opts|
+          opts.banner = 'Usage: belt-pay secrets:setup|secrets:show|secrets:edit ENV [options]'
+
+          opts.on('--app-name NAME', 'Override the detected Belt application name') do |value|
+            @options[:app_name] = value
+          end
+          opts.on('--secret-name NAME', 'Override the Secrets Manager secret name') do |value|
+            @options[:secret_name] = value
+          end
+          opts.on('--profile PROFILE', 'Override the AWS profile') do |value|
+            @options[:profile] = value
+          end
+          opts.on('--region REGION', 'Override the AWS region') do |value|
+            @options[:region] = value
+          end
+          opts.on('-h', '--help', 'Show this help') do
+            @out.puts help
+            exit 0
+          end
+        end
+      end
+
+      def resolve_context!
+        @root = find_project_root
+        env_dir = File.join(@root, 'infrastructure', @environment)
+        raise Error, "environment not found: #{env_dir}" unless Dir.exist?(env_dir)
+
+        @app_name = @options[:app_name] || ENV['APP_NAME'] || detect_app_name(env_dir)
+        raise Error, 'could not determine the application name; pass --app-name or set APP_NAME' if blank?(@app_name)
+
+        @secret_name = @options[:secret_name] || ENV['BELT_PAY_SECRET_NAME'] ||
+                       "#{@app_name}-#{@environment}-stripe"
+        @profile = @options[:profile] || ENV['AWS_PROFILE'] || detect_profile(env_dir)
+        @region = @options[:region] || ENV['AWS_REGION'] || ENV['AWS_DEFAULT_REGION'] || detect_region(env_dir)
+
+        ENV['AWS_PROFILE'] = @profile unless blank?(@profile)
+        @client = Aws::SecretsManager::Client.new(region: @region)
+      end
+
+      def setup
+        response = fetch_secret
+        original = parse_secret(response.secret_string)
+        updated = original.dup
+
+        secret_key = hidden_prompt('Stripe secret key [blank keeps existing]')
+        webhook_secret = hidden_prompt('Stripe webhook signing secret [blank keeps existing]')
+        updated['stripe_secret_key'] = secret_key unless blank?(secret_key)
+        updated['stripe_webhook_secret'] = webhook_secret unless blank?(webhook_secret)
+
+        update_secret(response, original, updated)
+      end
+
+      def show
+        response = fetch_secret
+        @out.puts JSON.pretty_generate(parse_secret(response.secret_string))
+      end
+
+      def edit
+        response = fetch_secret
+        original = parse_secret(response.secret_string)
+        edited = edit_json(original)
+
+        update_secret(response, original, edited)
+      end
+
+      def update_secret(response, original, updated)
+        if updated == original
+          @out.puts "Secret unchanged: #{@secret_name}"
+          return
+        end
+
+        latest = fetch_secret
+        if latest.version_id != response.version_id
+          raise Error, "#{@secret_name} changed while it was open; reopen it and apply your edits again"
+        end
+
+        @client.put_secret_value(
+          secret_id: @secret_name,
+          secret_string: JSON.generate(updated)
+        )
+        @out.puts "Updated secret: #{@secret_name}"
+      end
+
+      def fetch_secret
+        response = @client.get_secret_value(secret_id: @secret_name)
+        raise Error, "#{@secret_name} is binary; belt-pay only supports JSON string secrets" if response.secret_string.nil?
+
+        response
+      end
+
+      def parse_secret(value)
+        parsed = JSON.parse(value)
+        raise Error, "#{@secret_name} must contain a JSON object" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise Error, "#{@secret_name} does not contain valid JSON: #{e.message}"
+      end
+
+      def hidden_prompt(label)
+        @out.print "#{label}: "
+        @out.flush
+        value = if @input.respond_to?(:tty?) && @input.tty? && @input.respond_to?(:noecho)
+                  @input.noecho { @input.gets }
+                else
+                  @input.gets
+                end
+        @out.puts
+        raise Error, 'input ended before both Stripe secrets were read' if value.nil?
+
+        value.chomp
+      end
+
+      def edit_json(secret)
+        editor = ENV['VISUAL'] || ENV['EDITOR']
+        raise Error, 'set $VISUAL or $EDITOR before running secrets:edit' if blank?(editor)
+
+        Tempfile.create(["belt-pay-#{@environment}-", '.json']) do |file|
+          File.chmod(0o600, file.path)
+          file.write("#{JSON.pretty_generate(secret)}\n")
+          file.flush
+
+          success = system(*Shellwords.split(editor), file.path)
+          raise Error, 'editor exited unsuccessfully; secret was not updated' unless success
+
+          file.rewind
+          parse_secret(file.read)
+        end
+      end
+
+      def find_project_root
+        dir = File.expand_path(Dir.pwd)
+        loop do
+          routes = [
+            File.join(dir, 'config', 'routes.rb'),
+            File.join(dir, 'config', 'routes.tf.rb'),
+            File.join(dir, 'infrastructure', 'routes.tf.rb')
+          ]
+          return dir if routes.any? { |path| File.file?(path) }
+
+          parent = File.dirname(dir)
+          break if parent == dir
+
+          dir = parent
+        end
+
+        raise Error, 'could not find a Belt application; run this command inside one'
+      end
+
+      def detect_app_name(env_dir)
+        from_assignment(File.join(env_dir, 'terraform.tfvars'), 'app_name') ||
+          from_variable_default(File.join(env_dir, 'variables.tf'), 'app_name') ||
+          Dir.glob(File.join(@root, 'infrastructure', '*', 'terraform.tfvars')).sort.filter_map do |path|
+            from_assignment(path, 'app_name')
+          end.first ||
+          Dir.glob(File.join(@root, 'infrastructure', '*', 'variables.tf')).sort.filter_map do |path|
+            from_variable_default(path, 'app_name')
+          end.first ||
+          File.basename(@root)
+      end
+
+      def detect_profile(env_dir)
+        path = File.join(env_dir, 'belt.rb')
+        return unless File.file?(path)
+
+        File.read(path)[/config\.aws_profile\s*=\s*['\"]([^'\"]+)['\"]/, 1]
+      end
+
+      def detect_region(env_dir)
+        from_assignment(File.join(env_dir, 'terraform.tfvars'), 'aws_region') ||
+          from_variable_default(File.join(env_dir, 'variables.tf'), 'aws_region') ||
+          'us-east-1'
+      end
+
+      def from_assignment(path, key)
+        return unless File.file?(path)
+
+        File.read(path)[/^\s*#{Regexp.escape(key)}\s*=\s*['\"]([^'\"]+)['\"]/, 1]
+      end
+
+      def from_variable_default(path, key)
+        return unless File.file?(path)
+
+        block = File.read(path)[/variable\s+['\"]#{Regexp.escape(key)}['\"]\s*\{(.*?)\}/m, 1]
+        block&.match(/^\s*default\s*=\s*['\"]([^'\"]+)['\"]/)&.captures&.first
+      end
+
+      def blank?(value)
+        value.nil? || value.strip.empty?
+      end
+
+      def help
+        <<~HELP
+          Manage a Belt application's Stripe secret in AWS Secrets Manager.
+
+          Usage:
+            belt-pay secrets:setup ENV [options]
+            belt-pay secrets:show ENV [options]
+            belt-pay secrets:edit ENV [options]
+
+          Commands:
+            secrets:setup        Prompt without echo for Stripe's secret values
+            secrets:show         Print the decrypted JSON secret
+            secrets:edit         Edit the secret with $VISUAL or $EDITOR
+
+          Options:
+            --app-name NAME      Override the detected application name
+            --secret-name NAME   Override <app>-<environment>-stripe
+            --profile PROFILE    Override the environment's AWS profile
+            --region REGION      Override the detected AWS region
+            -h, --help           Show this help
+
+          Environment:
+            BELT_ENV             Environment when ENV is omitted
+            AWS_PROFILE          AWS profile (overrides infrastructure/ENV/belt.rb)
+            AWS_REGION           AWS region (default: us-east-1)
+            VISUAL, EDITOR       Editor command for secrets:edit
+
+          Examples:
+            belt-pay secrets:setup dev
+            belt-pay secrets:show dev
+            belt-pay secrets:edit prod --profile my-prod-profile
+            BELT_ENV=staging belt-pay secrets:setup
+
+          Security:
+            secrets:setup reads values without echo and sends them directly through the
+            AWS SDK. secrets:show writes the complete secret to stdout. secrets:edit uses
+            a mode-0600 temporary file, validates JSON, and removes the file afterward.
+        HELP
+      end
+    end
+  end
+end

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.3'
   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

data/lib/tasks/pay.rake

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'belt/pay/cli'
+
+run_pay_secret_command = lambda do |command, environment|
+  args = ["secrets:#{command}"]
+  args << environment unless environment.nil? || environment.to_s.strip.empty?
+
+  status = Belt::Pay::CLI.start(args)
+  exit status unless status.zero?
+end
+
+namespace :pay do
+  desc 'Prompt without echo for Stripe secrets (BELT_ENV or pay:setup[env])'
+  task :setup, [:environment] do |_task, args|
+    run_pay_secret_command.call(:setup, args[:environment])
+  end
+
+  desc 'Print the decrypted Stripe secret (BELT_ENV or pay:show[env])'
+  task :show, [:environment] do |_task, args|
+    run_pay_secret_command.call(:show, args[:environment])
+  end
+
+  desc 'Edit the Stripe secret as JSON (BELT_ENV or pay:edit[env])'
+  task :edit, [:environment] do |_task, args|
+    run_pay_secret_command.call(:edit, args[:environment])
+  end
+end

metadata

@@ -1,28 +1,56 @@
 --- !ruby/object:Gem::Specification
 name: belt-pay
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Stowzilla
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-secretsmanager
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.136.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.136.0
 - !ruby/object:Gem::Dependency
   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
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 13.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 13.4.2
 - !ruby/object:Gem::Dependency
   name: stripe
   requirement: !ruby/object:Gem::Requirement
@@ -43,22 +71,27 @@ description: Belt plugin providing payment collection, subscriptions, and billin
 email:
 - andy@stowzilla.com
 - adam@stowzilla.com
-executables: []
+executables:
+- belt-pay
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- exe/belt-pay
 - lib/belt-pay.rb
 - lib/belt/generators/pay_generator.rb
 - lib/belt/pay.rb
 - lib/belt/pay/billable.rb
 - lib/belt/pay/checkout.rb
+- lib/belt/pay/cli.rb
 - lib/belt/pay/configuration.rb
 - 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
@@ -71,6 +104,7 @@ files:
 - lib/belt/pay/transaction.rb
 - lib/belt/pay/version.rb
 - lib/belt/pay/webhook_handler.rb
+- lib/tasks/pay.rake
 homepage: https://github.com/stowzilla/belt-pay
 licenses:
 - MIT