usage_credits 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 710aa384672853be7b8711cffb537ad348761d0f8bf8c9df899565c7917522a8
-  data.tar.gz: de219e55c5442ce44bbdf9bc1843c5bdeaa1e32508e3ee3c193f5baef0b7c259
+  metadata.gz: 10c8b86a5ff03a6d32bc494739245bbf3a829966620931efb6fcea8c72d327bf
+  data.tar.gz: deec62e5e448b924dec3e2896491c3723dbb07f7b90f2945b13d117b64a1c444
 SHA512:
-  metadata.gz: ddd7d4f68a78f5608ded3984b277b6956ed1f849a72061a1816e1456252a164d87b771dd94337d653f28414932e349d31c88168085c1ead78e4083103920f356
-  data.tar.gz: cfaa71674966f0197675a0467cce70d5476b4dd161d838907567e286920590a3051463cb1583baab92e23e852942b6414812df23ed93dc2a421f613f9c853b8f
+  metadata.gz: acef2a23c57df23db5738fbee7d718f15a0883404cd059f6e04e049e2fa00777ab37894b9ccc4abae11bdbe1cf0c5a4374dd682d80ef33ccac44f560399d6e8d
+  data.tar.gz: aee4071cbae93898c31014bac55fc08f2b196f9d4831ab64f749b3a4802d97499dd9a9f73e5cd8cc027bf154a2c6283c62b9d96ce60ebd0543d7ba18435c3ef4

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [1.1.1] - 2026-10-19
+
+### Fixed
+
+- The install and upgrade migrations (and the demo app's) pick `jsonb` for JSON columns on PostgreSQL under either of its adapter names: `PostGIS` (activerecord-postgis-adapter) was getting plain `json`. Same fix as wallets 0.4.3.
+
+## [1.1.0] - 2026-10-18
+
+### Added
+
+- `pricing_plan` in `subscription_plan` blocks: take a plan's Stripe price IDs from the [`pricing_plans`](https://github.com/rameerez/pricing_plans) plan of the same (or a given) key, so prices are declared once and can't drift. Every price of the pricing plan (String or any interval Hash, e.g. `month:`, `year:`, `quarter:`) matches subscriptions. Prices are read lazily, so initializer order doesn't matter; `pricing_plans` remains an optional dependency. Combining `pricing_plan` with `stripe_price`, a missing `pricing_plans` gem, or a missing pricing plan raises the new `UsageCredits::ConfigurationError` (at boot, via `validate_pricing_plan_links!`, and on lookup).
+
+### Fixed
+
+- **No credit grant can vanish through a `return` out of a lock or transaction block, and the suite now proves it.** In 0.5, `Wallet#add_credits` returned from inside `with_lock`, and the plan-change handler and `FulfillmentService#process` returned from inside `transaction`; on Rails 7.0, and on 7.1 without `load_defaults 7.1`, that rolled back what the block had written without an error, while `add_credits` still returned its `Transaction`. An audit of 1.0.1 found none of those exits left (the 1.0 rewrite removed the first and turned the other two into `next`) and no new one in any `transaction`, `with_lock` or wallet command block, and 1.0 requires Rails 7.2.3.1 or newer, which commits a block left by `return`, `break` or `throw`. New tests read back the ledger rows and the cached balance that `add_credits` and `give_credits` write, and document on every supported Rails that such a block commits. Reported by Tal Gruper (@TalGruperFolloze) in #31, with a fix for the 0.5 code in #32.
+
 ## [1.0.1] - 2026-10-18
 
 ### Fixed

data/README.md

@@ -283,6 +283,8 @@ To ensure credits are not subtracted from users during failed operations, you ca
 end
 ```
 
+The credits are deducted right after the block, inside the same database transaction, so leave the block by finishing it or by raising. A `return` or `break` out of the block skips the deduction: the block's own database writes are committed and the operation ends up free.
+
 If you want to spend the credits immediately, you can use the non-block form:
 
 ```ruby
@@ -506,6 +508,33 @@ subscription_plan :basic do
 end
 ```
 
+#### Using `pricing_plans`? Declare your prices once
+
+If you also use [`pricing_plans`](https://github.com/rameerez/pricing_plans), your Stripe prices already live in `config/initializers/pricing_plans.rb`. Don't copy them here: point the subscription plan at its pricing plan instead.
+
+```ruby
+# config/initializers/pricing_plans.rb
+plan :pro do
+  stripe_price month: "price_pro_monthly", year: "price_pro_yearly", quarter: "price_pro_quarterly"
+end
+
+# config/initializers/usage_credits.rb
+subscription_plan :pro do
+  pricing_plan                        # Take the Stripe prices of pricing_plans' :pro plan
+  gives 10_000.credits.every(:month)
+  unused_credits :expire
+end
+```
+
+Every Stripe price of the pricing plan counts, whatever you named its keys (a single `stripe_price "price_x"` works too), so a subscriber on any of them gets their credits. Pass a key when the names differ: `pricing_plan :pro_2026`.
+
+A few things to know:
+
+- **Initializer order doesn't matter.** Prices are read from `pricing_plans` every time a subscription is matched, never copied at boot, so `pricing_plans.rb` can load before or after `usage_credits.rb`.
+- **One source of truth.** A plan that uses `pricing_plan` can't also declare `stripe_price`; that raises `UsageCredits::ConfigurationError`. Keep every price, including legacy ones for grandfathered subscribers, in the pricing plan. `pricing_plans` up to 0.7.x accepts any key for them, but its next version only accepts `id`, `day`, `week`, `month`, `quarter` and `year`, so there a legacy price needs a spare interval key. Plan IDs for other processors (`processor_plan :paddle, ...`) still work alongside it.
+- **Broken links fail loudly.** If `pricing_plans` isn't installed, or has no plan with that key, your app raises `UsageCredits::ConfigurationError` at boot (and on any lookup) instead of silently refilling nothing. A pricing plan with no Stripe price in the current environment only logs a warning at boot, since build steps like `assets:precompile` often run without credentials.
+- `pricing_plans` stays optional: `usage_credits` never requires it. The only thing it reads is `PricingPlans::Registry.plan(key).stripe_price`.
+
 ### Specify a fulfillment period
 
 Next, specify how many credits a user subscribed to this plan gets, and when they get them.

data/lib/generators/usage_credits/templates/create_usage_credits_tables.rb.erb

@@ -125,7 +125,7 @@ class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
   end
 
   def json_column_type
-    return :jsonb if connection.adapter_name.downcase.include?('postgresql')
+    return :jsonb if connection.adapter_name.match?(/postg/i) # PostgreSQL, and PostGIS, which is PostgreSQL under another name
     :json
   end
 

data/lib/generators/usage_credits/templates/upgrade_usage_credits_to_wallets_core.rb.erb

@@ -589,7 +589,7 @@ class UpgradeUsageCreditsToWalletsCore < ActiveRecord::Migration<%= migration_ve
   end
 
   def json_column_type
-    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+    return :jsonb if connection.adapter_name.match?(/postg/i) # PostgreSQL, and PostGIS, which is PostgreSQL under another name
     :json
   end
 

data/lib/usage_credits/configuration.rb

@@ -303,6 +303,24 @@ module UsageCredits
       true
     end
 
+    # Resolve every `pricing_plan` link once all initializers have run, so a
+    # missing gem or plan fails at boot instead of on the first paid webhook.
+    # A linked plan without Stripe prices only warns: build steps like
+    # `assets:precompile` often boot without the credentials that hold them.
+    def validate_pricing_plan_links!
+      @credit_subscription_plans.each_value do |plan|
+        next unless plan.pricing_plan_key
+        next if plan.stripe_price_from_pricing_plan
+
+        Rails.logger.warn(
+          "[UsageCredits] Subscription plan '#{plan.name}' takes its Stripe prices from pricing plan " \
+          "'#{plan.pricing_plan_key}', which has no Stripe price. No Stripe subscription will match it, " \
+          "so Stripe subscribers won't get its credits."
+        )
+      end
+      true
+    end
+
     private
 
     def validate_currency!

data/lib/usage_credits/engine.rb

@@ -23,6 +23,11 @@ module UsageCredits
       end
     end
 
+    # Runs after every initializer, so pricing_plans.rb and usage_credits.rb can load in any order
+    config.after_initialize do
+      UsageCredits.configuration.validate_pricing_plan_links!
+    end
+
     initializer "usage_credits.action_view" do
       ActiveSupport.on_load :action_view do
         require "usage_credits/helpers/credits_helper"

data/lib/usage_credits/models/credit_subscription_plan.rb

@@ -10,7 +10,7 @@ module UsageCredits
   # @see PaySubscriptionExtension for the actual credit fulfillment logic
   class CreditSubscriptionPlan
     attr_reader :name,
-      :processor_plan_ids,
+      :pricing_plan_key,
       :fulfillment_period, :credits_per_period,
       :signup_bonus_credits, :trial_credits,
       :rollover_enabled,
@@ -94,6 +94,49 @@ module UsageCredits
     # Payment Processor Integration
     # =========================================
 
+    # Take this plan's Stripe price IDs from the `pricing_plans` plan with the
+    # given key (this plan's own name by default), so every price is declared
+    # exactly once: in pricing_plans, the single source of truth for pricing.
+    #
+    # Prices are read lazily, every time the plan is matched or asked for its
+    # prices, so it doesn't matter which initializer Rails loads first. The only
+    # contract with pricing_plans is `PricingPlans::Registry.plan(key).stripe_price`.
+    #
+    # @param key [Symbol, String] The pricing_plans plan key
+    # @example Same key
+    #   pricing_plan
+    # @example Different key
+    #   pricing_plan :pro_2026
+    def pricing_plan(key = name)
+      raise ArgumentError, "Pricing plan key can't be blank" if key.blank?
+      @pricing_plan_key = key.to_sym
+      self
+    end
+
+    # Processor-specific plan ID(s), including Stripe prices read from the linked pricing plan
+    # @return [Hash] processor => String or Hash of period => ID
+    def processor_plan_ids
+      return @processor_plan_ids unless pricing_plan_key
+      @processor_plan_ids.merge(stripe: stripe_price_from_pricing_plan).compact
+    end
+
+    # Stripe price ID(s) of the linked pricing plan, in the same shape `stripe_price` returns:
+    # a String for a single price, or a Hash of period => price ID. Blank and non-String
+    # values (e.g. a credential that isn't set in this environment) are skipped.
+    #
+    # @return [String, Hash, nil]
+    # @raise [ConfigurationError] if pricing_plans isn't loaded or has no such plan
+    def stripe_price_from_pricing_plan
+      case (prices = linked_pricing_plan.stripe_price)
+      when String
+        prices.presence
+      when Hash
+        ids = prices.to_h { |period, id| [period.to_sym, id] }.select { |_, id| id.is_a?(String) && id.present? }
+        # pricing_plans stores a single `stripe_price "price_x"` as { id: "price_x" }
+        (ids.keys == [:id]) ? ids[:id] : ids.presence
+      end
+    end
+
     # Set the processor-specific plan ID(s)
     # Accepts either a single ID (String) or multiple period-specific IDs (Hash)
     #
@@ -109,7 +152,7 @@ module UsageCredits
         # Normalize all keys to symbols for consistent lookup
         id = id.transform_keys(&:to_sym)
       end
-      processor_plan_ids[processor.to_sym] = id
+      @processor_plan_ids[processor.to_sym] = id
     end
 
     # Get the plan ID(s) for a specific processor
@@ -244,6 +287,11 @@ module UsageCredits
       raise ArgumentError, "Fulfillment period must be set" if fulfillment_period.nil?
       raise ArgumentError, "Signup bonus credits must be greater than or equal to 0" if signup_bonus_credits.to_i.negative?
       raise ArgumentError, "Trial credits must be greater than or equal to 0" if trial_credits.to_i.negative?
+      if pricing_plan_key && @processor_plan_ids.key?(:stripe)
+        raise ConfigurationError, "Subscription plan :#{name} takes its Stripe prices from pricing plan " \
+          ":#{pricing_plan_key}, so it can't also declare `stripe_price`. Declare every price once, " \
+          "in the pricing plan (legacy prices included), and remove `stripe_price` here."
+      end
       true
     end
 
@@ -293,6 +341,22 @@ module UsageCredits
 
     private
 
+    def linked_pricing_plan
+      unless defined?(::PricingPlans::Registry)
+        raise ConfigurationError, "Subscription plan :#{name} uses `pricing_plan :#{pricing_plan_key}`, " \
+          "but the pricing_plans gem isn't loaded. Add `gem \"pricing_plans\"` to your Gemfile, " \
+          "or declare `stripe_price` in this plan instead."
+      end
+
+      begin
+        ::PricingPlans::Registry.plan(pricing_plan_key) or raise KeyError
+      rescue
+        raise ConfigurationError, "Subscription plan :#{name} uses `pricing_plan :#{pricing_plan_key}`, " \
+          "but pricing_plans has no plan :#{pricing_plan_key}. Define `plan :#{pricing_plan_key}` in " \
+          "config/initializers/pricing_plans.rb, or pass the right key: `pricing_plan :your_plan`."
+      end
+    end
+
     def normalize_whole_number!(amount, name, minimum:)
       amount = amount.to_i if amount.is_a?(UsageCredits::Cost::Fixed)
       value = Wallets::WholeNumber.parse(amount, name: name)

data/lib/usage_credits/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UsageCredits
-  VERSION = "1.0.1"
+  VERSION = "1.1.1"
 end

data/lib/usage_credits.rb

@@ -73,6 +73,7 @@ require "usage_credits/jobs/fulfillment_job"
 module UsageCredits
   # Custom error classes
   class Error < StandardError; end
+  class ConfigurationError < Error; end
   class InsufficientCredits < Error; end
   class InvalidOperation < Error; end
   class InvalidTransfer < Error; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usage_credits
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.1
 platform: ruby
 authors:
 - rameerez