ask-token-usage-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34b1d95794c074506226ba84ddbc01130d7ba026663751741d0c13d497949b55
+  data.tar.gz: 1d6764ef111ded783089f8703182dede3b0dbeadf8b3be5e106179c6f797efc6
+SHA512:
+  metadata.gz: d4f4d4219eb29625d4b962c981da5677216a150c972f27b73fc90eafbb64526e12abb6302883c514e50d039654faf60b26d81127e44fbd044d71c828c3f3ed79
+  data.tar.gz: 9a55d29615156f17d6baef130f7607c20d4cce8d49f843c97bbddeff869f71fc7c14c712b25decfadc4f7ea54e149539a8b66f3ad8e2de470925730461bb046e

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2026-08-19
+
+### Added
+- `has_token_wallet` concern for any ActiveRecord model.
+- `Ask::TokenUsage::TokenWallet` (polymorphic owner + cached balance).
+- `Ask::TokenUsage::TokenTransaction` append-only ledger (immutable).
+- `Ask::TokenUsage::Rails::ActiveRecordStore` implementing the core Store port.
+- `rails g ask_token_usage:install` — migration (`token_wallets`, `token_transactions`) + initializer.
+- `SweepExpiredTokensJob` for expiring past-due grant entries.
+- Automatic store swap via Railtie — no manual wiring required.
+- Standard ask-gem infrastructure: CI, rubocop, overcommit.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# ask-token-usage-rails
+
+ActiveRecord persistence for the [ask-token-usage](https://github.com/ask-rb/ask-token-usage) wallet engine.
+
+Ships an ActiveRecord store adapter, a `has_token_wallet` concern, install generator with migrations, and an expiry sweep job.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "ask-token-usage-rails"
+```
+
+```sh
+bundle install
+rails g ask_token_usage:install
+rails db:migrate
+```
+
+## Usage
+
+```ruby
+class User < ApplicationRecord
+  has_token_wallet
+end
+
+# Grant tokens
+user.grant_tokens!(10_000, reason: :trial, expires_at: 7.days.from_now)
+
+# Spend on an activity (charges only if the block succeeds)
+user.spend_tokens_on!(:chat_message, input: "hi", output: "yo") do
+  LLM.chat(...)
+end
+
+# Check balance
+user.token_balance   # => 9_998
+
+# Use the PORO wallet directly
+wallet = user.ask_token_wallet
+wallet.entries
+wallet.used_since(30.days.ago)
+```
+
+## Scheduled jobs
+
+`SweepExpiredTokensJob` expires grant entries whose `expires_at` has passed.
+
+```yaml
+# config/recurring.yml (Solid Queue)
+ask_token_usage_sweep:
+  class: Ask::TokenUsage::Rails::SweepExpiredTokensJob
+  schedule: "every 1 hour"
+```

data/lib/ask/token_usage/rails/concerns/has_token_wallet.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Ask
+  module TokenUsage
+    module Rails
+      # Include this concern in any ActiveRecord model to give it a token
+      # wallet backed by ask-token-usage-rails.
+      #
+      #   class User < ApplicationRecord
+      #     has_token_wallet
+      #   end
+      #
+      # Adds:
+      #   user.token_balance        # Integer
+      #   user.token_wallet         # Ask::TokenUsage::TokenWallet (lazy-created)
+      #   user.token_transactions   # AR scope for the ledger
+      #   user.grant_tokens!(...)   # convenience
+      #   user.spend_tokens!(...)   # convenience
+      #   user.spend_tokens_on!(...)# convenience (activity name + block)
+      #
+      module HasTokenWallet
+        extend ActiveSupport::Concern
+
+        included do
+          has_one :token_wallet, as: :owner,
+                                 class_name: "Ask::TokenUsage::TokenWallet",
+                                 dependent: :destroy,
+                                 inverse_of: :owner
+
+          has_many :token_transactions, through: :token_wallet
+        end
+
+        def ensure_token_wallet!
+          # Force wallet row creation by probing balance through the AR store
+          Ask::TokenUsage.wallet_for(self).balance
+        end
+
+        def token_balance
+          Ask::TokenUsage.wallet_for(self).balance
+        end
+
+        # Build an Ask::TokenUsage::Wallet PORO backed by this model's
+        # AR wallet — use for one-off operations outside the concern API.
+        def ask_token_wallet
+          Ask::TokenUsage.wallet_for(self)
+        end
+
+        # Grant +amount+ tokens.
+        def grant_tokens!(amount, reason:, expires_at: nil, metadata: {})
+          ask_token_wallet.grant!(amount, reason: reason, expires_at: expires_at, metadata: metadata)
+        end
+
+        # Deduct +amount+ tokens, raising InsufficientTokens on failure.
+        def deduct_tokens!(amount, reason:, metadata: {})
+          ask_token_wallet.deduct!(amount, reason: reason, metadata: metadata)
+        end
+
+        # Deduct +amount+ tokens; returns false instead of raising on
+        # insufficient balance.
+        def try_deduct_tokens!(amount, reason:, metadata: {})
+          deduct_tokens!(amount, reason: reason, metadata: metadata)
+        rescue Ask::TokenUsage::InsufficientTokens
+          false
+        end
+
+        # Spend the estimated cost of +activity+ with +params+, charging
+        # only when the block succeeds.
+        def spend_tokens_on!(activity_name, params = {}, &block)
+          ask_token_wallet.spend!(activity_name, params, &block)
+        end
+
+        # Spend an explicit +amount+ of tokens, charging only on block success.
+        def spend_tokens!(amount, reason:, metadata: {}, &block)
+          ask_token_wallet.deduct!(amount, reason: reason, metadata: metadata, &block)
+        end
+
+        def has_tokens_for?(amount)
+          ask_token_wallet.has?(amount)
+        end
+
+        def token_usage_since(time)
+          ask_token_wallet.used_since(time)
+        end
+      end
+    end
+  end
+end

data/lib/ask/token_usage/rails/jobs/sweep_expired_tokens_job.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Ask
+  module TokenUsage
+    module Rails
+      # Expire grant entries whose +expires_at+ has passed. Scheduled as a
+      # recurring job (Solid Queue cron, Sidekiq Cron, etc.):
+      #
+      #   # config/recurring.yml
+      #   ask_token_usage_sweep:
+      #     class: Ask::TokenUsage::Rails::SweepExpiredTokensJob
+      #     schedule: "every 1 hour"
+      #
+      # For each expired grant, the actual amount removed is capped to the
+      # wallet's current balance (myrr approximation — correct for most
+      # grant-heavy usage patterns; perfect accuracy requires FIFO allocation
+      # which is a future option).
+      #
+      class SweepExpiredTokensJob < ActiveJob::Base
+        queue_as :default
+
+        def perform(now: Time.current)
+          Ask::TokenUsage::TokenTransaction
+            .grants
+            .where("expires_at IS NOT NULL AND expires_at <= ?", now)
+            .where.not(entry_type: "expiry")
+            .where("id NOT IN (SELECT source_transaction_id FROM token_transactions WHERE entry_type = ?)", "expiry")
+            .find_each do |grant|
+              sweep_grant(grant)
+            end
+        end
+
+        private
+
+        def sweep_grant(grant)
+          wallet = grant.token_wallet
+          return unless wallet
+
+          wallet.with_lock do
+            remaining = grant.amount - already_expired_amount(grant)
+            return if remaining <= 0
+
+            actual = [remaining, wallet.balance].min
+            return if actual <= 0
+
+            Ask::TokenUsage::TokenTransaction.create!(
+              token_wallet_id: wallet.id,
+              entry_type: "expiry",
+              amount: -actual,
+              reason: "token_expiry",
+              balance: wallet.balance - actual,
+              metadata: {
+                source_transaction_id: grant.id,
+                expired_amount: remaining,
+                actual_expired: actual
+              },
+              created_at: now
+            )
+
+            wallet.update_column(:balance, wallet.balance - actual)
+          end
+        end
+
+        def already_expired_amount(grant)
+          Ask::TokenUsage::TokenTransaction
+            .where(token_wallet_id: grant.token_wallet_id, entry_type: "expiry")
+            .where("metadata->>'source_transaction_id' = ?", grant.id.to_s)
+            .sum(:amount)
+            .abs
+        end
+      end
+    end
+  end
+end

data/lib/ask/token_usage/rails/models/token_transaction.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module Ask
+  module TokenUsage
+    # Append-only ledger row. Every grant, debit, adjustment, or expiry is
+    # written here as an immutable record. Never updated or deleted.
+    class TokenTransaction < ::ActiveRecord::Base
+      self.table_name = "token_transactions"
+
+      belongs_to :token_wallet, class_name: "Ask::TokenUsage::TokenWallet",
+                                foreign_key: :token_wallet_id,
+                                inverse_of: :token_transactions
+
+      ENTRY_TYPES = %w[grant debit adjustment expiry].freeze
+      validates :entry_type, presence: true, inclusion: { in: ENTRY_TYPES }
+      validates :amount, presence: true, numericality: { only_integer: true }
+      validates :reason, presence: true
+
+      scope :grants, -> { where(entry_type: "grant") }
+      scope :debits, -> { where(entry_type: "debit") }
+      scope :adjustments, -> { where(entry_type: "adjustment") }
+      scope :expiries, -> { where(entry_type: "expiry") }
+      scope :since, ->(time) { where("created_at >= ?", time) }
+      scope :newest_first, -> { order(created_at: :desc) }
+
+      validate :immutable_after_creation, on: :update
+
+      private
+
+      def immutable_after_creation
+        errors.add(:base, "Token transactions are append-only")
+      end
+    end
+  end
+end

data/lib/ask/token_usage/rails/models/token_wallet.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module Ask
+  module TokenUsage
+    # Polymorphic wallet record. One per owner. Holds the cached balance.
+    class TokenWallet < ::ActiveRecord::Base
+      self.table_name = "token_wallets"
+
+      has_many :token_transactions, class_name: "Ask::TokenUsage::TokenTransaction",
+                                   foreign_key: :token_wallet_id,
+                                   dependent: :destroy,
+                                   inverse_of: :token_wallet
+
+      belongs_to :owner, polymorphic: true, optional: true
+
+      validates :balance, numericality: { only_integer: true }
+    end
+  end
+end

data/lib/ask/token_usage/rails/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Ask
+  module TokenUsage
+    module Rails
+      class Railtie < ::Rails::Railtie
+        initializer "ask_token_usage.active_record_store" do
+          require "ask/token_usage/rails/models/token_wallet"
+          require "ask/token_usage/rails/models/token_transaction"
+          require "ask/token_usage/rails/stores/active_record_store"
+          require "ask/token_usage/rails/concerns/has_token_wallet"
+
+          Ask::TokenUsage.configure do |c|
+            c.store = Ask::TokenUsage::Rails::ActiveRecordStore.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/token_usage/rails/stores/active_record_store.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "ask/token_usage/stores/store"
+
+module Ask
+  module TokenUsage
+    module Rails
+      # ActiveRecord-backed wallet store. Each mutation (grant/deduct) does
+      # its own read-write under a single DB call. The wallet row is created
+      # lazily on first access. No outer transaction wrapping — each AR
+      # create/update handles its own atomicity.
+      class ActiveRecordStore < Ask::TokenUsage::Stores::Store
+        def balance(owner)
+          resolve_wallet(owner)&.balance || 0
+        end
+
+        def entries(owner, kind: nil, since: nil)
+          row = resolve_wallet(owner)
+          return [] unless row
+
+          scope = row.token_transactions.order(:created_at)
+          scope = scope.where(entry_type: kind.to_s) if kind
+          scope = scope.where("created_at >= ?", since) if since
+          scope.map { |t| to_entry(t) }
+        end
+
+        # No-op for in-process locking. For production with PostgreSQL,
+        # this could use row-level locks. SQLite uses file-level locks
+        # which are handled by the OS.
+        def with_lock(owner)
+          yield
+        end
+
+        def append(owner, entry)
+          row = find_or_create_wallet!(owner)
+          txn = Ask::TokenUsage::TokenTransaction.create!(
+            token_wallet_id: row.id,
+            entry_type: entry.kind.to_s,
+            amount: entry.amount,
+            reason: entry.reason,
+            metadata: entry.metadata || {},
+            expires_at: entry.expires_at,
+            balance: entry.balance,
+            created_at: entry.created_at
+          )
+          entry.with(id: txn.id)
+        end
+
+        def write_balance(owner, amount)
+          row = find_or_create_wallet!(owner)
+          row.update_column(:balance, amount)
+        end
+
+        private
+
+        def find_or_create_wallet!(owner)
+          owner_type, owner_id = resolve_owner(owner)
+          Ask::TokenUsage::TokenWallet.find_by(owner_type: owner_type, owner_id: owner_id) ||
+            begin
+              Ask::TokenUsage::TokenWallet.create!(owner_type: owner_type, owner_id: owner_id, balance: 0)
+            rescue ActiveRecord::RecordNotUnique
+              Ask::TokenUsage::TokenWallet.find_by!(owner_type: owner_type, owner_id: owner_id)
+            end
+        end
+
+        def resolve_wallet(owner)
+          owner_type, owner_id = resolve_owner(owner)
+          Ask::TokenUsage::TokenWallet.find_by(owner_type: owner_type, owner_id: owner_id)
+        end
+
+        def resolve_owner(owner)
+          if owner.respond_to?(:id) && owner.respond_to?(:class) && owner.class.respond_to?(:polymorphic_name)
+            [owner.class.polymorphic_name, owner.id]
+          else
+            [owner.class.name, owner.respond_to?(:id) ? owner.id : owner.to_s]
+          end
+        end
+
+        def to_entry(txn)
+          Ask::TokenUsage::LedgerEntry.new(
+            id: txn.id,
+            kind: txn.entry_type.to_sym,
+            amount: txn.amount,
+            reason: txn.reason,
+            expires_at: txn.expires_at,
+            metadata: txn.metadata,
+            balance: txn.balance,
+            created_at: txn.created_at
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ask/token_usage/rails/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    module Rails
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/ask-token-usage-rails.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "ask-token-usage"
+require "ask/token_usage/rails/version"
+require "ask/token_usage/rails/railtie"

data/lib/generators/ask_token_usage/install/install_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module AskTokenUsage
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the ask-token-usage migration and initializer"
+
+      def self.next_migration_number(_dir)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def create_migration
+        migration_template "migration.rb", "db/migrate/create_token_wallets.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/ask_token_usage.rb"
+      end
+
+      def show_readme
+        readme "README.md" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/ask_token_usage/install/templates/initializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# ask-token-usage configuration.
+# The railtie auto-wires the ActiveRecord store. Override settings here.
+
+Ask::TokenUsage.configure do |config|
+  # What 1M billing tokens cost (the rate your users pay).
+  # config.price_per_1m = Money.from_amount(100, "USD")  # $100 / 1M
+
+  # Rounding strategy for dynamic token costs: :ceil (default), :floor, :round.
+  # config.rounding = :ceil
+
+  # Allow negative balances? Default: false.
+  # config.negatives = false
+end

data/lib/generators/ask_token_usage/install/templates/migration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class CreateTokenWallets < ActiveRecord::Migration[7.0]
+  def change
+    create_table :token_wallets do |t|
+      t.references :owner, polymorphic: true, null: false
+      t.bigint :balance, null: false, default: 0
+      t.timestamps
+    end
+    add_index :token_wallets, %i[owner_type owner_id], unique: true, name: "idx_token_wallets_owner"
+
+    create_table :token_transactions do |t|
+      t.references :token_wallet, null: false, foreign_key: true
+      t.string :entry_type, null: false
+      t.bigint :amount, null: false
+      t.string :reason, null: false
+      t.jsonb :metadata, null: false, default: {}
+      t.bigint :balance, null: false
+      t.datetime :expires_at
+      t.datetime :created_at, null: false
+    end
+    add_index :token_transactions, %i[token_wallet_id created_at]
+    add_index :token_transactions, :entry_type
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: ask-token-usage-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-token-usage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Adds an ActiveRecord-backed wallet store, has_token_wallet concern, token
+  wallet/transaction models, an install generator with migrations, and an expiry sweep
+  job to any Rails app using ask-token-usage.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-token-usage-rails.rb
+- lib/ask/token_usage/rails/concerns/has_token_wallet.rb
+- lib/ask/token_usage/rails/jobs/sweep_expired_tokens_job.rb
+- lib/ask/token_usage/rails/models/token_transaction.rb
+- lib/ask/token_usage/rails/models/token_wallet.rb
+- lib/ask/token_usage/rails/railtie.rb
+- lib/ask/token_usage/rails/stores/active_record_store.rb
+- lib/ask/token_usage/rails/version.rb
+- lib/generators/ask_token_usage/install/install_generator.rb
+- lib/generators/ask_token_usage/install/templates/initializer.rb
+- lib/generators/ask_token_usage/install/templates/migration.rb
+homepage: https://github.com/ask-rb/ask-token-usage-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-token-usage-rails
+  source_code_uri: https://github.com/ask-rb/ask-token-usage-rails
+  changelog_uri: https://github.com/ask-rb/ask-token-usage-rails/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: ActiveRecord persistence for the ask-token-usage wallet engine
+test_files: []