usage_credits 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09e65a66af34a0f2bf35a72d59fdd2d9d9799aaeaa1ac8b7628f222f65e5beab'
-  data.tar.gz: 2dc466a29bc36385aeee7c8bbb77833e521c2207e84ac6cf00543253d02af74e
+  metadata.gz: 0fcda02fd1ae61887b8a80d6fbf6c864843d363797d90dbbd66abafe2851ce8b
+  data.tar.gz: 6c1e67ec12f46bf5e33faa7d02ed723dc47926a29948a8140706392d1ffbe024
 SHA512:
-  metadata.gz: c1a6c0fc9dab7e315d67b6071b38d5e00b386bc21830438636405296b32fbabb510f0f31a77d995ea8d03972b939ebcf25aba3baa7f03847a66d2ee55b4a6a62
-  data.tar.gz: fd4c0225c47dfca3903249b9456d428c9012060acb4f8beceb4c577e5673a4f650cdfd0ba74035bae5b253284e8ccb73eeb87a11b815fed4b9626f00968bf84a
+  metadata.gz: cd9d8517d94b2c19d0b141d9b47f4362c65ee1bf9255bff400c2b55c34b14a87903cdd3f58987e92edad8c2116fbfe485f185ddc2e9696782ae912fc7f40402c
+  data.tar.gz: b9498add88988145a75e74abbdf24b086391fd76188d63719a108a97f4b1fa69af86d9ea9c941cdd45ac25a2d1e5319192b14d34361a2ea42058db333f6adb0e

data/.simplecov

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+SimpleCov.start 'rails' do
+  # Coverage directory
+  coverage_dir 'coverage'
+
+  # Enable branch coverage (must be before minimum_coverage)
+  enable_coverage :branch
+
+  # Set minimum coverage threshold to prevent coverage regression
+  # Current coverage: Line 84.38%, Branch 71.9%
+  # Note: Some paths (PostgreSQL JSON operators, error fallbacks) may not be exercised in SQLite tests
+  minimum_coverage line: 75, branch: 60
+
+  # Add custom groups for better organization
+  add_group 'Models', 'lib/usage_credits/models'
+  add_group 'Services', 'lib/usage_credits/services'
+  add_group 'Helpers', 'lib/usage_credits/helpers'
+  add_group 'Jobs', 'lib/usage_credits/jobs'
+  add_group 'Concerns', 'lib/usage_credits/models/concerns'
+  add_group 'DSL', ['lib/usage_credits/operation.rb', 'lib/usage_credits/credit_pack.rb', 'lib/usage_credits/credit_subscription_plan.rb']
+
+  # Filter out files we don't want to track
+  add_filter '/test/'
+  add_filter '/spec/'
+  add_filter '/config/'
+  add_filter '/db/'
+  add_filter '/vendor/'
+  add_filter '/bin/'
+
+  # Track all Ruby files in lib
+  track_files 'lib/**/*.rb'
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+
+  # Use different formatters for CI vs local
+  if ENV['CI']
+    # CI: Use simple formatter for console output
+    formatter SimpleCov::Formatter::SimpleFormatter
+  else
+    # Local: Use HTML formatter for detailed report
+    formatter SimpleCov::Formatter::HTMLFormatter
+  end
+
+  # Merge results from parallel runs
+  merge_timeout 3600
+end

data/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Claude Code, etc) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/Appraisals

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Test against Pay 8.3.x (minimum supported version)
+appraise "pay-8.3" do
+  gem "pay", "~> 8.3.0"
+  gem "stripe", "~> 13.0"
+end
+
+# Test against Pay 9.0.x (current recommended version)
+appraise "pay-9.0" do
+  gem "pay", "~> 9.0.0"
+  gem "stripe", "~> 13.0"
+end
+
+# Test against Pay 10.x (newly supported version)
+appraise "pay-10.0" do
+  gem "pay", "~> 10.0.0"
+  gem "stripe", "~> 15.0"
+end
+
+# Test against Pay 11.x (latest version)
+appraise "pay-11.0" do
+  gem "pay", "~> 11.0"
+  gem "stripe", "~> 18.0"
+end

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.2.0] - 2025-12-29
+
+- Add Claude Code GitHub Workflow by @rameerez in https://github.com/rameerez/usage_credits/pull/14
+- Add test suite by @rameerez in https://github.com/rameerez/usage_credits/pull/15
+- Update Pay gem dependency to support versions 8.3 to 9.x by @rameerez in https://github.com/rameerez/usage_credits/pull/16
+- Update Pay gem dependency to support version 8.3 to < 10.0 by @kaka-ruto in https://github.com/rameerez/usage_credits/pull/10
+- Add Pay version matrix testing with Appraisal by @rameerez in https://github.com/rameerez/usage_credits/pull/17
+- Upgrade Pay dependency to support version 10.x by @rameerez in https://github.com/rameerez/usage_credits/pull/18
+- Upgrade Pay dependency to support version 11.x by @rameerez in https://github.com/rameerez/usage_credits/pull/19
+- Remove payment intent metadata from Subscription checkout session by @cole-robertson in https://github.com/rameerez/usage_credits/pull/2
+- Handle subscription plan changes (upgrades & downgrades) by @rameerez in https://github.com/rameerez/usage_credits/pull/20
+- Add configurable minimum fulfillment period for dev/test flexibility by @rameerez in https://github.com/rameerez/usage_credits/pull/21
+- Add multi-period Stripe price support for subscription plans by @rameerez in https://github.com/rameerez/usage_credits/pull/22
+- Fix a bug where very fast fulfillment periods would cause credits not to expire fast enough by @rameerez in https://github.com/rameerez/usage_credits/pull/23
+- Fix incomplete fulfillment update on subscription plan upgrade by @rameerez in https://github.com/rameerez/usage_credits/pull/24
+
 ## [0.1.1] - 2025-01-14
 
 - Rename `Wallet#subscriptions` to `Wallet.credit_subscriptions` so that it doesn’t override the Pay gem’s own subscriptions association on `User`

data/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/README.md

@@ -1,11 +1,13 @@
 # 💳✨ `usage_credits` - Add usage-based credits to your Rails app 
 
-[![Gem Version](https://badge.fury.io/rb/usage_credits.svg)](https://badge.fury.io/rb/usage_credits)
+[![Gem Version](https://badge.fury.io/rb/usage_credits.svg?v=0.1)](https://badge.fury.io/rb/usage_credits?v=0.1)
 
 Allow your users to have in-app credits / tokens they can use to perform operations.
 
 ✨ Perfect for SaaS, AI apps, games, and API products that want to implement usage-based pricing.
 
+[ 🟢 [Live interactive demo website](https://usagecredits.com/) ] [ 🎥 [Quick video overview](https://x.com/rameerez/status/1890419563189195260) ]
+
 Refill user credits with Stripe subscriptions, allow your users to top up by purchasing booster credit packs at any time, rollover unused credits to the next billing period, expire credits, implement PAYG (pay-as-you-go) billing, award free credits as bonuses (for referrals, giving feedback, etc.), get a detailed history and audit trail of every transaction for billing / reporting, and more!
 
 All with a simple DSL that reads just like English.
@@ -383,6 +385,31 @@ end
 
 For now, only Stripe subscriptions are supported (contribute to the codebase to help us add more payment processors!)
 
+#### Subscriptions with a monthly + yearly price
+
+For plans that offer multiple billing periods (e.g., monthly and yearly pricing), you can specify multiple Stripe price IDs using a hash:
+
+```ruby
+subscription_plan :pro do
+  # Multi-period pricing: same plan, different billing frequencies
+  stripe_price month: "price_pro_monthly", year: "price_pro_yearly"
+
+  gives 10_000.credits.every(:month)
+  # ...
+end
+```
+
+The gem automatically handles plan matching for webhook events - when Stripe sends subscription events, the plan will be correctly identified regardless of which billing period was selected.
+
+**Note:** Single-price plans (the traditional format) continue to work as before for backward compatibility:
+
+```ruby
+subscription_plan :basic do
+  stripe_price "price_basic_monthly"  # Single price ID (still works)
+  gives 1_000.credits.every(:month)
+end
+```
+
 ### Specify a fulfillment period
 
 Next, specify how many credits a user subscribed to this plan gets, and when they get them.
@@ -413,6 +440,49 @@ subscription_plan :pro do
 end
 ```
 
+### Grace period for credit expiration
+
+When credits expire (i.e., `unused_credits :expire`), there's a configurable **grace period** to ensure smooth transitions between fulfillment cycles. This prevents users from seeing zero credits between the moment old credits expire and new credits are fulfilled.
+
+```ruby
+UsageCredits.configure do |config|
+  # Grace period for credit expiration (default: 5 minutes)
+  # Should match the frequency of your UsageCredits::FulfillmentJob runs
+  config.fulfillment_grace_period = 5.minutes
+end
+```
+
+> [!NOTE]
+> **Automatic grace period capping:** If your fulfillment period is shorter than the grace period (e.g., credits every 15 seconds with a 5-minute grace period), the grace period is **automatically capped** to the fulfillment period. This prevents balance accumulation where credits pile up faster than they expire.
+>
+> For example, with `gives 100.credits.every(15.seconds)` and a 5-minute grace period, the effective grace period will be 15 seconds, not 5 minutes. A warning will be logged during initialization to alert you of this behavior.
+>
+> This is typically only relevant for development/testing with very short fulfillment periods. In production with monthly or daily fulfillment cycles, the default 5-minute grace period works perfectly.
+
+### Upgrades, downgrades, and plan changes
+
+`usage_credits` reacts to plan changes (via the `pay` gem), and we handle automatically credit issuing for upgrades & downgrades:
+
+- **Upgrades**: credits are granted immediately for the new plan. If the new plan expires credits, upgrade credits expire too.
+- **Downgrades**: scheduled for the end of the current period; users keep current benefits until then.
+- **Non-credit plan changes**: moving from credit → non-credit stops fulfillment at period end (no clawback).
+- **Reactivation**: moving back to a credit plan reactivates fulfillment and grants credits (no signup bonus on reactivation).
+- **Pending downgrades**: if a user returns to their current plan before the downgrade takes effect, we cancel the pending change and do **not** grant extra credits.
+- **Credit gaming prevention**: we take measures to protect against user gaming the credit system by repeatedly upgrading/downgrading their subscription.
+
+This happens automatically thanks to our Pay Subscription extension (changes to the `Subscription` model in the `pay` gem trigger `usage_credits` issuing the right credits based on the subscription change)
+
+### What we handle vs. what we don't (brief)
+
+Handled:
+- Subscription create, renew, cancel, upgrade, downgrade, non-credit transitions
+- Pending downgrade application on renewal
+- Credit expiration and rollover
+
+Not handled (yet):
+- Plan changes while **trialing** (we only handle `status == "active"`)
+- Paused subscriptions (see TODO in code)
+
 ## Transaction history & audit trail
 
 Every transaction (whether adding or deducting credits) is logged in the ledger, and automatically tracked with metadata:
@@ -469,6 +539,10 @@ Which will get you:
 
 It's useful if you want to name your credits something else (tokens, virtual currency, tasks, in-app gems, whatever) and you want the name to be consistent.
 
+## Demo Rails app
+
+There's a demo Rails app showcasing the features in the `usage_credits` gem under `test/dummy`. It's currently deployed to `usagecredits.com`. If you want to run it yourself locally, you can just clone this repo, `cd` into the `test/dummy` folder, and then `bundle` and `rails s` to launch it. You can examine the code of the demo app to better understand the gem.
+
 ## Technical notes on architecture and how this gem is built
 
 Building a usage credits system is deceptively complex.
@@ -558,9 +632,7 @@ Real billing systems usually find edge cases when handling things like:
 Please help us by contributing to add tests to cover all critical paths!
 
 ## TODO
-
-- [ ] Write a comprehensive `minitest` test suite that covers all critical paths (both happy paths and weird edge cases)
-- [ ] Handle subscription upgrades and downgrades (upgrade immediately; downgrade at end of billing period? Cover all scenarios allowed by the Stripe Customer Portal?)
+No open TODOs here right now. If you find an edge case, please open an issue or PR.
 
 ## Testing
 
@@ -574,8 +646,7 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/usage_credits. Our code of conduct is: just be nice and make your mom proud of what 
-you do and post online.
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/usage_credits. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
 
 ## License
 

data/gemfiles/pay_10.0.gemfile

@@ -0,0 +1,29 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "mocha"
+gem "simplecov", require: false
+gem "standard"
+gem "vcr"
+gem "webmock"
+gem "braintree", ">= 2.92.0"
+gem "lemonsqueezy", "~> 1.0"
+gem "paddle", "~> 2.6"
+gem "stripe", "~> 15.0"
+gem "prawn"
+gem "receipts"
+gem "sqlite3"
+gem "pg"
+gem "bootsnap", require: false
+gem "puma"
+gem "web-console", group: :development
+gem "importmap-rails"
+gem "sprockets-rails"
+gem "stimulus-rails"
+gem "turbo-rails"
+gem "rdoc", ">= 7.0"
+gem "pay", "~> 10.0.0"
+
+gemspec path: "../"

data/gemfiles/pay_11.0.gemfile

@@ -0,0 +1,29 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "mocha"
+gem "simplecov", require: false
+gem "standard"
+gem "vcr"
+gem "webmock"
+gem "braintree", ">= 2.92.0"
+gem "lemonsqueezy", "~> 1.0"
+gem "paddle", "~> 2.6"
+gem "stripe", "~> 18.0"
+gem "prawn"
+gem "receipts"
+gem "sqlite3"
+gem "pg"
+gem "bootsnap", require: false
+gem "puma"
+gem "web-console", group: :development
+gem "importmap-rails"
+gem "sprockets-rails"
+gem "stimulus-rails"
+gem "turbo-rails"
+gem "rdoc", ">= 7.0"
+gem "pay", "~> 11.0"
+
+gemspec path: "../"

data/gemfiles/pay_8.3.gemfile

@@ -0,0 +1,29 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "mocha"
+gem "simplecov", require: false
+gem "standard"
+gem "vcr"
+gem "webmock"
+gem "braintree", ">= 2.92.0"
+gem "lemonsqueezy", "~> 1.0"
+gem "paddle", "~> 2.6"
+gem "stripe", "~> 13.0"
+gem "prawn"
+gem "receipts"
+gem "sqlite3"
+gem "pg"
+gem "bootsnap", require: false
+gem "puma"
+gem "web-console", group: :development
+gem "importmap-rails"
+gem "sprockets-rails"
+gem "stimulus-rails"
+gem "turbo-rails"
+gem "rdoc", ">= 7.0"
+gem "pay", "~> 8.3.0"
+
+gemspec path: "../"

data/gemfiles/pay_9.0.gemfile

@@ -0,0 +1,29 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "mocha"
+gem "simplecov", require: false
+gem "standard"
+gem "vcr"
+gem "webmock"
+gem "braintree", ">= 2.92.0"
+gem "lemonsqueezy", "~> 1.0"
+gem "paddle", "~> 2.6"
+gem "stripe", "~> 13.0"
+gem "prawn"
+gem "receipts"
+gem "sqlite3"
+gem "pg"
+gem "bootsnap", require: false
+gem "puma"
+gem "web-console", group: :development
+gem "importmap-rails"
+gem "sprockets-rails"
+gem "stimulus-rails"
+gem "turbo-rails"
+gem "rdoc", ">= 7.0"
+gem "pay", "~> 9.0.0"
+
+gemspec path: "../"

data/lib/generators/usage_credits/templates/initializer.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 UsageCredits.configure do |config|
+  #
+  # Minimum fulfillment period for subscription plans (default: 1.day)
+  # In development/test, you can set this to a shorter period for faster testing:
+  #
+  # config.min_fulfillment_period = 2.seconds if Rails.env.development?
+  #
+  #
   #
   # Define your credit-consuming operations below
   #
@@ -55,6 +62,9 @@ UsageCredits.configure do |config|
   #   gives 1000.credits.every(:month)
   #   signup_bonus 100.credits
   #   unused_credits :expire  # Credits reset each month
+  #
+  #   # Single price (backward compatible)
+  #   stripe_price "price_basic_monthly"
   # end
   #
   # subscription_plan :pro do
@@ -62,6 +72,13 @@ UsageCredits.configure do |config|
   #   signup_bonus 1_000.credits
   #   trial_includes 500.credits
   #   unused_credits :expire  # Credits expire at the end of the fulfillment period (use :rollover to roll over to next period)
+  #
+  #   # Multi-period pricing (monthly + yearly)
+  #   stripe_price month: "price_pro_monthly", year: "price_pro_yearly"
+  #
+  #   # When creating checkout sessions with multi-period plans, specify the period:
+  #   # plan.create_checkout_session(user, success_url: "/success", cancel_url: "/cancel", period: :month)
+  #   # plan.create_checkout_session(user, success_url: "/success", cancel_url: "/cancel", period: :year)
   # end
   #
   #
@@ -81,11 +98,22 @@ UsageCredits.configure do |config|
   #
   #
   #
-  # For how long expiring credits from the previous fulfillment cycle will "overlap" the following fulfillment period.
+  # Grace period for credit expiration (default: 5.minutes)
+  #
+  # This is for how long expiring credits from the previous fulfillment cycle will "overlap" the following fulfillment period.
   # During this time, old credits from the previous period will erroneously count as available balance.
   # But if we set this to 0 or nil, user balance will show up as zero some time until the next fulfillment cycle hits.
   # A good default is to match the frequency of your UsageCredits::FulfillmentJob
-  # fulfillment_grace_period = 5.minutes
+  #
+  # config.fulfillment_grace_period = 5.minutes
+  #
+  # NOTE: If your fulfillment period is shorter than the grace period (e.g., credits
+  # every 15 seconds with a 5-minute grace), the grace period is AUTOMATICALLY CAPPED
+  # to the fulfillment period. This prevents balance accumulation where credits pile
+  # up faster than they expire. A warning will be logged during initialization.
+  #
+  # This is typically only relevant for development/testing with very short periods.
+  # In production with monthly/daily fulfillment cycles, the default should work just fine.
   #
   #
   #

data/lib/usage_credits/configuration.rb

@@ -28,7 +28,12 @@ module UsageCredits
 
     attr_reader :credit_formatter
 
-    attr_accessor :fulfillment_grace_period
+    attr_reader :fulfillment_grace_period
+
+    # Minimum allowed fulfillment period for subscription plans.
+    # Defaults to 1.day to prevent accidental 1-second refill loops in production.
+    # Can be set to shorter periods (e.g., 2.seconds) in development/test for faster iteration.
+    attr_reader :min_fulfillment_period
 
     # =========================================
     # Low balance
@@ -56,10 +61,13 @@ module UsageCredits
       # This ensures smooth transition between fulfillment periods.
       # For this amount of time, old, already expired credits will be erroneously counted as available in the user's balance.
       # Keep it short enough that users don't notice they have the last period's credits still available, but
-      # long enough that there's a smooth transition and users never get zero credits in between fullfillment periods
+      # long enough that there's a smooth transition and users never get zero credits in between fulfillment periods
       # A good setting is to match the frequency of your UsageCredits::FulfillmentJob runs
       @fulfillment_grace_period = 5.minutes # If you run your fulfillment job every 5 minutes, this should be enough
 
+      # Minimum fulfillment period - prevents accidental 1-second refill loops in production
+      @min_fulfillment_period = 1.day
+
       @allow_negative_balance = false
       @low_balance_threshold = nil
       @low_balance_callback = nil # Called when user hits low_balance_threshold
@@ -99,13 +107,20 @@ module UsageCredits
       plan = CreditSubscriptionPlan.new(name)
       plan.instance_eval(&block)
       plan.validate!
+
+      # Warn if fulfillment period is shorter than grace period (grace will be auto-capped)
+      warn_if_grace_period_exceeds_fulfillment(plan)
+
       @credit_subscription_plans[name] = plan
     end
 
     # Find a subscription plan by its processor-specific ID
+    # Works with both single-price and multi-period plans
+    # @param processor_id [String] The price ID to search for
+    # @return [CreditSubscriptionPlan, nil] The matching plan or nil
     def find_subscription_plan_by_processor_id(processor_id)
       @credit_subscription_plans.values.find do |plan|
-        plan.processor_plan_ids.values.include?(processor_id)
+        plan.matches_processor_id?(processor_id)
       end
     end
 
@@ -153,6 +168,18 @@ module UsageCredits
       @fulfillment_grace_period = value
     end
 
+    def min_fulfillment_period=(value)
+      unless value.is_a?(ActiveSupport::Duration)
+        raise ArgumentError, "Minimum fulfillment period must be an ActiveSupport::Duration (e.g. 1.day, 2.seconds)"
+      end
+
+      if value < 1.second
+        raise ArgumentError, "Minimum fulfillment period must be at least 1 second"
+      end
+
+      @min_fulfillment_period = value
+    end
+
     # =========================================
     # Callback & Formatter Configuration
     # =========================================
@@ -200,5 +227,25 @@ module UsageCredits
         raise ArgumentError, "Invalid rounding strategy. Must be one of: #{VALID_ROUNDING_STRATEGIES.join(', ')}"
       end
     end
+
+    # Warn developers when grace period exceeds fulfillment period
+    # In this case, the grace period will be automatically capped to the fulfillment period
+    # to prevent balance accumulation (credits piling up because they don't expire fast enough)
+    def warn_if_grace_period_exceeds_fulfillment(plan)
+      return unless plan.fulfillment_period.present?
+      return if plan.rollover_enabled  # Grace period only matters for expiring credits
+
+      fulfillment_duration = plan.parsed_fulfillment_period
+
+      if @fulfillment_grace_period > fulfillment_duration
+        Rails.logger.warn(
+          "[UsageCredits] Subscription plan '#{plan.name}' has a fulfillment period " \
+          "(#{plan.fulfillment_period}) shorter than the configured grace period " \
+          "(#{@fulfillment_grace_period.inspect}). The grace period will be automatically " \
+          "capped to #{fulfillment_duration.inspect} for this plan to prevent balance accumulation. " \
+          "Consider adjusting config.fulfillment_grace_period if this is not intended."
+        )
+      end
+    end
   end
 end

data/lib/usage_credits/helpers/period_parser.rb

@@ -7,6 +7,9 @@ module UsageCredits
 
     # Canonical periods and their aliases
     VALID_PERIODS = {
+      second: [:second, :seconds],        # 1.second
+      minute: [:minute, :minutes],        # 1.minute
+      hour: [:hour, :hours, :hourly],     # 1.hour
       day: [:day, :daily],                # 1.day
       week: [:week, :weekly],             # 1.week
       month: [:month, :monthly],          # 1.month
@@ -14,21 +17,35 @@ module UsageCredits
       year: [:year, :yearly, :annually]   # 1.year
     }.freeze
 
-    MIN_PERIOD = 1.day
+    MIN_PERIOD = 1.day  # Deprecated: Use UsageCredits.configuration.min_fulfillment_period instead
 
     module_function
 
+    # Get the configured minimum fulfillment period
+    def min_fulfillment_period
+      # Use configured value if available, otherwise fall back to default
+      if defined?(UsageCredits) && UsageCredits.respond_to?(:configuration)
+        UsageCredits.configuration.min_fulfillment_period
+      else
+        MIN_PERIOD
+      end
+    end
+
     # Turns things like `:monthly` into `1.month` to always store consistent time periods
     def normalize_period(period)
       return nil unless period
 
       # Handle ActiveSupport::Duration objects directly
       if period.is_a?(ActiveSupport::Duration)
-        raise ArgumentError, "Period must be at least #{MIN_PERIOD.inspect}" if period < MIN_PERIOD
+        min_period = min_fulfillment_period
+        raise ArgumentError, "Period must be at least #{min_period.inspect}" if period < min_period
         period
       else
         # Convert symbols to canonical durations
-        case period
+        duration = case period
+        when *VALID_PERIODS[:second] then 1.second
+        when *VALID_PERIODS[:minute] then 1.minute
+        when *VALID_PERIODS[:hour] then 1.hour
         when *VALID_PERIODS[:day] then 1.day
         when *VALID_PERIODS[:week] then 1.week
         when *VALID_PERIODS[:month] then 1.month
@@ -37,6 +54,10 @@ module UsageCredits
         else
           raise ArgumentError, "Unsupported period: #{period}. Supported periods: #{VALID_PERIODS.values.flatten.inspect}"
         end
+
+        min_period = min_fulfillment_period
+        raise ArgumentError, "Period must be at least #{min_period.inspect}" if duration < min_period
+        duration
       end
     end
 
@@ -57,14 +78,31 @@ module UsageCredits
           raise ArgumentError, "Unsupported period unit: #{unit}. Supported units: #{valid_units.inspect}"
         end
 
-        duration = amount.send(unit)
-        raise ArgumentError, "Period must be at least #{MIN_PERIOD.inspect}" if duration < MIN_PERIOD
+        # Map alias to canonical unit (e.g., :hourly -> :hour, :seconds -> :second)
+        canonical_unit = canonical_unit_for(unit)
+
+        duration = amount.send(canonical_unit)
+        min_period = min_fulfillment_period
+        raise ArgumentError, "Period must be at least #{min_period.inspect}" if duration < min_period
         duration
       else
         raise ArgumentError, "Invalid period format: #{period_str}. Expected format: '1.month', '2 months', etc."
       end
     end
 
+    # Map any alias to its canonical unit method name
+    # @param unit [Symbol] The unit symbol (e.g., :hourly, :seconds, :day)
+    # @return [Symbol] The canonical unit method (e.g., :hour, :second, :day)
+    def canonical_unit_for(unit)
+      # Find which canonical unit this alias belongs to
+      VALID_PERIODS.each do |canonical, aliases|
+        return canonical if aliases.include?(unit)
+      end
+
+      # Fallback to the unit itself if not found (shouldn't happen if validation passed)
+      unit
+    end
+
     # Validates that a period string matches the expected format and units
     def valid_period_format?(period_str)
       parse_period(period_str)

data/lib/usage_credits/models/allocation.rb

@@ -22,6 +22,8 @@ module UsageCredits
     private
 
     def allocation_does_not_exceed_remaining_amount
+      return if amount.blank? || source_transaction.blank?
+
       if source_transaction.remaining_amount < amount
         errors.add(:amount, "exceeds the remaining amount of the source transaction")
       end