usage_credits 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 746f3023cb2533204e1eb089718a09019786f868a76cfa58c61fce459d608985
-  data.tar.gz: cca4bb0ac339d37151f84a2270e7c34f436f6f66cdfbb593e8fbdb57aa7cefcd
+  metadata.gz: '09e65a66af34a0f2bf35a72d59fdd2d9d9799aaeaa1ac8b7628f222f65e5beab'
+  data.tar.gz: 2dc466a29bc36385aeee7c8bbb77833e521c2207e84ac6cf00543253d02af74e
 SHA512:
-  metadata.gz: 539023a63628718b2a44628abb725ab6a1d23f115ca509fbb4cff5284f296cc77e71ae28d0fe0dd84725f415b984757973828214b190da5ba48be0f633778092
-  data.tar.gz: 036544fb6fe39eb762216fef0f9a56cc41c31f0ff5eeb53156a47252a5948b473146b8ead147d5a27e98be652d5cac238f27b503747811064e9f83a2815522e2
+  metadata.gz: c1a6c0fc9dab7e315d67b6071b38d5e00b386bc21830438636405296b32fbabb510f0f31a77d995ea8d03972b939ebcf25aba3baa7f03847a66d2ee55b4a6a62
+  data.tar.gz: fd4c0225c47dfca3903249b9456d428c9012060acb4f8beceb4c577e5673a4f650cdfd0ba74035bae5b253284e8ccb73eeb87a11b815fed4b9626f00968bf84a

data/CHANGELOG.md

@@ -1,5 +1,11 @@
-## [Unreleased]
+## [0.1.1] - 2025-01-14
 
-## [0.1.0] - 2025-01-18
+- Rename `Wallet#subscriptions` to `Wallet.credit_subscriptions` so that it doesn’t override the Pay gem’s own subscriptions association on `User`
+- Add non-postgres fallbacks for PostgreSQL-only operations (namely `@>` to access json attributes)
+- Add optional `expires_at` to `give_credits` so you can expire any batch of credits at any arbitrary date in the future
+- Add Allocation associations to the Wallet model
+- Add demo Rails app to showcase the gem features
+
+## [0.1.0] - 2025-01-12
 
 - Initial release

data/README.md

@@ -123,6 +123,7 @@ That's it! Your app now has a credits system. Let's see how to use it.
 1. Users can get credits by:
   - Purchasing credit packs (e.g., "1000 credits for $49")
   - Having a subscription (e.g., "Pro plan includes 10,000 credits/month")
+  - Arbitrary bonuses at any point (completing signup, referring a friend, etc.)
 
 2. Users spend credits on operations you define:
   - "Sending an email costs 1 credit"
@@ -280,6 +281,28 @@ UsageCredits.configure do |config|
 end
 ```
 
+## Award bonus credits
+
+You might want to award bonus credits to your users for arbitrary actions at any point, like referring a friend, completing signup, or any other reason.
+
+To do that, you can just do:
+
+```ruby
+@user.give_credits(100, reason: "referral")
+```
+
+And the user will get the credits with the proper category in the transaction ledger (so bonus credits get differentiated from purchases / subscriptions for audit trail purposes)
+
+Providing a reason for giving credits is entirely optional (it just helps you if you need to use or analyze the audit trail) – if you don't specify any reason, `:manual_adjustment` is the default reason.
+
+You can also give credits with arbitrary expiration dates:
+```ruby
+@user.give_credits(100, expires_at: 1.month.from_now)
+```
+
+So you can expire any batch of credits at any date in the future.
+
+
 ## Sell credit packs
 
 > [!IMPORTANT]

data/lib/usage_credits/models/concerns/has_wallet.rb

@@ -35,7 +35,7 @@ module UsageCredits
       end
 
       # Returns all active subscriptions as CreditSubscriptionPlan objects
-      def subscriptions
+      def credit_subscriptions
         return [] unless credit_wallet
 
         credit_wallet.fulfillments

data/lib/usage_credits/models/concerns/pay_charge_extension.rb

@@ -17,10 +17,18 @@ module UsageCredits
     end
 
     def succeeded?
-      return true if data["status"] == "succeeded" || data[:status] == "succeeded"
-      # For Stripe charges, a successful charge has amount_captured equal to the charge amount
-      return true if type == "Pay::Stripe::Charge" && data["amount_captured"] == amount
-      false
+      case type
+      when "Pay::Stripe::Charge"
+        status = data["status"] || data[:status]
+        return true if status == "succeeded"
+        return true if data["amount_captured"].to_i == amount.to_i
+      end
+
+      # Are Pay::Charge objects guaranteed to be created only after a successful payment?
+      # Is the existence of a Pay::Charge object in the database a guarantee that the payment went through?
+      # I'm implementing this `succeeded?` method just out of precaution
+      # TODO: Implement for more payment processors? Or just drop this method if it's unnecessary
+      true
     end
 
     def refunded?
@@ -58,9 +66,34 @@ module UsageCredits
       # First check if there's a fulfillment record for this charge
       return true if UsageCredits::Fulfillment.exists?(source: self)
 
-      # Fallback: check transactions directly
-      credit_wallet&.transactions&.where(category: "credit_pack_purchase")
-        .exists?(['metadata @> ?', { purchase_charge_id: id, credits_fulfilled: true }.to_json])
+      # Fallback: check transactions directly:
+
+      # Look up all transactions in the credit wallet for a purchase.
+      transactions = credit_wallet&.transactions&.where(category: "credit_pack_purchase")
+      return false unless transactions.present?
+
+      begin
+        adapter = ActiveRecord::Base.connection.adapter_name.downcase
+        if adapter.include?("postgres")
+          # PostgreSQL supports the @> JSON containment operator.
+          transactions.exists?(['metadata @> ?', { purchase_charge_id: id, credits_fulfilled: true }.to_json])
+        else
+          # For other adapters (e.g. SQLite, MySQL), try using JSON_EXTRACT.
+          transactions.exists?(["json_extract(metadata, '$.purchase_charge_id') = ? AND json_extract(metadata, '$.credits_fulfilled') = ?", id, true])
+        end
+      rescue ActiveRecord::StatementInvalid
+        # If the SQL query fails (for example, if JSON_EXTRACT isn’t supported),
+        # fall back to loading transactions in Ruby and filtering them.
+        transactions.any? do |tx|
+          data =
+            if tx.metadata.is_a?(Hash)
+              tx.metadata
+            else
+              JSON.parse(tx.metadata) rescue {}
+            end
+          data["purchase_charge_id"].to_i == id.to_i && data["credits_fulfilled"].to_s == "true"
+        end
+      end
     end
 
     def fulfill_credit_pack!
@@ -132,8 +165,28 @@ module UsageCredits
 
     def credits_already_refunded?
       # Check if refund was already processed with credits deducted by looking for a refund transaction
-      credit_wallet&.transactions&.where(category: "credit_pack_refund")
-        .exists?(['metadata @> ?', { refunded_purchase_charge_id: id, credits_refunded: true }.to_json])
+      # Look up transactions for a refund.
+      transactions = credit_wallet&.transactions&.where(category: "credit_pack_refund")
+      return false unless transactions.present?
+
+      begin
+        adapter = ActiveRecord::Base.connection.adapter_name.downcase
+        if adapter.include?("postgres")
+          transactions.exists?(['metadata @> ?', { refunded_purchase_charge_id: id, credits_refunded: true }.to_json])
+        else
+          transactions.exists?(["json_extract(metadata, '$.refunded_purchase_charge_id') = ? AND json_extract(metadata, '$.credits_refunded') = ?", id, true])
+        end
+      rescue ActiveRecord::StatementInvalid
+        transactions.any? do |tx|
+          data =
+            if tx.metadata.is_a?(Hash)
+              tx.metadata
+            else
+              JSON.parse(tx.metadata) rescue {}
+            end
+          data["refunded_purchase_charge_id"].to_i == id.to_i && data["credits_refunded"].to_s == "true"
+        end
+      end
     end
 
     def handle_refund!

data/lib/usage_credits/models/transaction.rb

@@ -19,7 +19,8 @@ module UsageCredits
     CATEGORIES = [
       # Bonus credits
       "signup_bonus",                   # Initial signup bonus
-      "referral_bonus",                 # Referral reward
+      "referral_bonus",                 # Referral reward bonus
+      "bonus",                          # Generic bonus
 
       # Subscription-related
       "subscription_credits",           # Generic subscription credits

data/lib/usage_credits/models/wallet.rb

@@ -19,6 +19,9 @@ module UsageCredits
     belongs_to :owner, polymorphic: true
     has_many :transactions, class_name: "UsageCredits::Transaction", dependent: :destroy
     has_many :fulfillments, class_name: "UsageCredits::Fulfillment", dependent: :destroy
+    has_many :outbound_allocations, through: :transactions, source: :outgoing_allocations
+    has_many :inbound_allocations, through: :transactions, source: :incoming_allocations
+    has_many :allocations, ->(wallet) { unscope(:where).where("usage_credits_allocations.transaction_id IN (?) OR usage_credits_allocations.source_transaction_id IN (?)", wallet.transaction_ids, wallet.transaction_ids) }, class_name: "UsageCredits::Allocation", dependent: :destroy
 
     validates :balance, numericality: { greater_than_or_equal_to: 0 }, unless: :allow_negative_balance?
 
@@ -116,23 +119,29 @@ module UsageCredits
       raise e
     end
 
-    # Give credits to the wallet
+    # Give credits to the wallet with optional reason and expiration date
     # @param amount [Integer] Number of credits to give
-    # @param reason [String] Why credits were given (for auditing)
-    def give_credits(amount, reason: nil)
-      raise ArgumentError, "Cannot give negative credits" if amount.negative?
-      raise ArgumentError, "Credit amount must be a whole number" unless amount.integer?
+    # @param reason [String, nil] Optional reason for giving credits (for auditing / trail purposes)
+    # @param expires_at [DateTime, nil] Optional expiration date for the credits
+    def give_credits(amount, reason: nil, expires_at: nil)
+      raise ArgumentError, "Amount is required" if amount.nil?
+      raise ArgumentError, "Cannot give negative credits" if amount.to_i.negative?
+      raise ArgumentError, "Credit amount must be a whole number" unless amount.to_i.integer?
+      raise ArgumentError, "Expiration date must be a valid datetime" if expires_at && !expires_at.respond_to?(:to_datetime)
+      raise ArgumentError, "Expiration date must be in the future" if expires_at && expires_at <= Time.current
 
       category = case reason&.to_s
                 when "signup" then :signup_bonus
                 when "referral" then :referral_bonus
+                when /bonus/i then :bonus
                 else :manual_adjustment
                 end
 
       add_credits(
-        amount,
+        amount.to_i,
         metadata: { reason: reason },
-        category: category
+        category: category,
+        expires_at: expires_at
       )
     end
 

data/lib/usage_credits/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: usage_credits
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - rameerez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-12 00:00:00.000000000 Z
+date: 2025-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails