open_router_usage_tracker 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2942349a31ca24bfb080791b3dba9bcb36eaf6fc9709718fe989e65c968ee489
-  data.tar.gz: 57459071b36f2873e5dedf5f4c4d9d98bd1327527edeca2ff9c7bfaff7c14098
+  metadata.gz: f11a0fd8aa29a664ab72f45aa1516974dde22505c9e8f060ca8a051f0558de92
+  data.tar.gz: ad7a682ba71c648dba5dd12d6f47df0cd3ec9fc2590579e8a14bae4e1dd71e5c
 SHA512:
-  metadata.gz: 961ca4017ed1159fb13920d86a07ad4ca78b7bea40f2d105893bdc57653a3deed4164c047b858c0cb5a779419deebd0cdc0a1f0e65d87dab232052b27558f44f
-  data.tar.gz: 3c538fda52c54f226498c6f845d84f7fdd0e42ee78c582062a42fd529d54946ecb10ea470cc2ec7a59a68648358c7d454fbe771661454107f25d21e7a600a436
+  metadata.gz: '002058380aa56c5dfde8490cf908f019da6cb752774f6eef197c4c5746b4b5ce99fa45e76eefc0e596a5c19a5f3eee3ea811b04cbf85fb095a024db8ff08a365'
+  data.tar.gz: 9dc836d59bbda52b9974f98aae37da47eafbbe1581e8f260ef5bbe45de5ccb885148865cf0d787c01aa4ae84a0425d6f043aa8d3801a8e95058113c854c5fa64

data/README.md

@@ -1,8 +1,8 @@
 # OpenRouterUsageTracker
-[![Gem Version](https://badge.fury.io/rb/open_router_usage_tracker.svg)](https://badge.fury.io/rb/open_router_usage_tracker)
 [![Build Status](https://github.com/mclpio/open_router_usage_tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/mclpio/open_router_usage_tracker/actions)
+[![Gem Version](https://badge.fury.io/rb/open_router_usage_tracker.svg)](https://badge.fury.io/rb/open_router_usage_tracker)
 
-An effortless Rails engine to track API token usage and cost from [OpenRouter.io](https://openrouter.ai/), enabling easy rate-limiting and monitoring for your users.
+An effortless Rails engine to track API token usage and cost from [OpenRouter](https://openrouter.ai/), enabling easy rate-limiting and monitoring for your users.
 
 ## Motivation
 Managing Large Language Model (LLM) API costs is crucial for any application that provides AI features to users. This gem provides simple, out-of-the-box tools to log every OpenRouter API call, associate it with a user, and query their usage over time. This allows you to easily implement spending caps, rate limits, or usage-based billing tiers.
@@ -16,27 +16,32 @@ gem "open_router_usage_tracker"
 
 And then execute:
 ```bash
-$ bundle
+bundle
 ```
 
 Or install it yourself as:
 ```bash
-$ gem install open_router_usage_tracker
+gem install open_router_usage_tracker
 ```
 
 ## Setup
 
-1. **Run the Install Generator**: This will create a migration file in your application to add the open_router_usage_logs table.
+1. **Run the Install Generator**: This will create a migration file in your application to add the `open_router_usage_logs` table.
     ```bash
     bin/rails g open_router_usage_tracker:install
     ```
 
-1. **Run the Database Migration**:
+2. **Run the Summary Table Generator (New in v0.2.0)**: To enable performant daily rate-limiting, generate the migration for the summary table.
+    ```bash
+    bin/rails g open_router_usage_tracker:summary_install
+    ```
+
+3. **Run the Database Migrations**:
     ```bash
     bin/rails db:migrate
     ```
 
-1. **Include the `Trackable` Concern**: To add the usage tracking methods (`usage_in_period`, etc.) to your user model, include the concern. This works with any user-like model (e.g., `User`, `Account`).
+4. **Include the `Trackable` Concern**: To add the usage tracking methods (`usage_in_period`, etc.) to your user model, include the concern. This works with any user-like model (e.g., `User`, `Account`).
     ```ruby
     # app/models/user.rb
     class User < ApplicationRecord
@@ -65,29 +70,56 @@ rescue ActiveRecord::RecordInvalid => e
 end
 ```
 
-### Tracking Usage
-The `Trackable` concern adds powerful querying methods to your user model.
+### Daily Usage Tracking and Rate-Limiting (Recommended)
 
-The main method is `usage_in_period(range)`, which returns a hash containing the total tokens and cost for a given time range.
+For high-performance rate-limiting, the gem provides helpers that query a daily summary table. This avoids slow `SUM` queries on the main log table.
 
-**Example: Implementing a rate limit**
+The primary method is `cost_exceeded?(limit:)`, which provides a near-instantaneous check against a user's daily spending.
 
-Imagine you want to prevent users from using more than 100,000 tokens in a 24-hour period.
+**Example: Implementing a daily cost limit**
+
+Imagine you want to prevent users from spending more than $1.00 per day.
 
 ```ruby
 # somewhere in a controller or before_action
 
-def check_usage_limit
-  usage = current_user.usage_in_last_24_hours
-
-  if usage[:tokens] > 100_000
-    render json: { error: "You have exceeded your daily usage limit." }, status: :too_many_requests
+def enforce_daily_limit
+  # This check is extremely fast as it queries the small summary table.
+  if current_user.cost_exceeded?(limit: 1.00)
+    render json: { error: "You have exceeded your daily spending limit." }, status: :too_many_requests
     return
   end
 end
 ```
 
-The gem also provides `usage_in_last_24_hours` as a convenience method and you can always get all the data using `usage_logs`.
+You can also retrieve the full summary for the current day (UTC):
+
+```ruby
+summary = current_user.usage_today
+# => <OpenRouterUsageTracker::DailySummary id: 1, user_id: 1, day: "2025-06-28", total_tokens: 1500, cost: 0.025, ...>
+
+summary.cost
+# => 0.025
+
+summary.total_tokens
+# => 1500
+```
+
+### Historical Usage Tracking
+
+The `Trackable` concern also adds methods for querying historical usage from the main log table.
+
+The main method is `usage_in_period(range)`, which returns a hash containing the total tokens and cost for a given time range.
+
+**Example: Checking usage for the current month**
+
+```ruby
+range = Time.current.beginning_of_month..Time.current
+usage = current_user.usage_in_period(range)
+# => { tokens: 50000, cost: 1.25 }
+```
+
+**DEPRECATED for rate-limiting**: The `usage_in_last_24_hours` method is still available but is **not recommended** for implementing rate limits due to its performance implications. Use `cost_exceeded?` instead for a more robust and scalable solution.
 
 ## Contributing
 Open an issue first.

data/app/models/concerns/open_router_usage_tracker/trackable.rb

@@ -6,6 +6,20 @@ module OpenRouterUsageTracker
 
     included do
       has_many :usage_logs, as: :user, class_name: "OpenRouterUsageTracker::UsageLog", dependent: :destroy
+      has_many :daily_summaries, as: :user, class_name: "OpenRouterUsageTracker::DailySummary", dependent: :destroy
+    end
+
+    def usage_today
+      daily_summaries.find_by(day: Date.current)
+    end
+
+    def cost_exceeded?(limit:, period: :daily)
+      case period
+      when :daily
+        usage_today&.cost.to_d > limit
+      else
+        raise ArgumentError, "Unsupported period: #{period}"
+      end
     end
 
     # A flexible method to query usage within any time period.

data/app/models/open_router_usage_tracker/daily_summary.rb

@@ -0,0 +1,11 @@
+module OpenRouterUsageTracker
+  class DailySummary < ApplicationRecord
+    self.table_name = "open_router_daily_summaries"
+
+    belongs_to :user, polymorphic: true
+
+    validates :day, presence: true
+    validates :total_tokens, presence: true, numericality: { greater_than_or_equal_to: 0 }
+    validates :cost, presence: true, numericality: { greater_than_or_equal_to: 0 }
+  end
+end

data/lib/generators/open_router_usage_tracker/summary_install/summary_install_generator.rb

@@ -0,0 +1,19 @@
+require "rails/generators/base"
+
+module OpenRouterUsageTracker
+  module Generators
+    class SummaryInstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dir)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def create_migration_file
+        migration_template "migration.rb", "db/migrate/create_open_router_daily_summaries.rb"
+      end
+    end
+  end
+end

data/lib/generators/open_router_usage_tracker/summary_install/templates/migration.rb

@@ -0,0 +1,13 @@
+class CreateOpenRouterDailySummaries < ActiveRecord::Migration[8.0]
+  def change
+    create_table :open_router_daily_summaries do |t|
+      t.references :user, null: false, polymorphic: true
+      t.date :day, null: false
+      t.integer :total_tokens, null: false, default: 0
+      t.decimal :cost, precision: 10, scale: 5, null: false, default: 0.0
+      t.timestamps
+    end
+
+    add_index :open_router_daily_summaries, [ :user_type, :user_id, :day ], unique: true, name: "index_daily_summaries_on_user_and_day"
+  end
+end

data/lib/open_router_usage_tracker/version.rb

@@ -1,3 +1,3 @@
 module OpenRouterUsageTracker
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/open_router_usage_tracker.rb

@@ -7,6 +7,16 @@ module OpenRouterUsageTracker
     attr_writer :configuration
 
     def log(response:, user:)
+      ApplicationRecord.transaction do
+        usage_log = create_usage_log(response, user)
+        update_daily_summary(usage_log)
+        usage_log
+      end
+    end
+
+    private
+
+    def create_usage_log(response, user)
       attributes = {
         model: response["model"],
         prompt_tokens: response.dig("usage", "prompt_tokens"),
@@ -17,8 +27,17 @@ module OpenRouterUsageTracker
         raw_usage_response: response,
         user: user
       }
-
       OpenRouterUsageTracker::UsageLog.create!(attributes)
     end
+
+    def update_daily_summary(usage_log)
+      summary = OpenRouterUsageTracker::DailySummary.find_or_initialize_by(
+        user: usage_log.user,
+        day: Date.current
+      )
+      summary.total_tokens += usage_log.total_tokens
+      summary.cost += usage_log.cost
+      summary.save!
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: open_router_usage_tracker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - MclPio
@@ -23,8 +23,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.0.2
-description: This gem is your rocket launch to managing you web app's LLM usage and
-  rate limiting users with built in methods!
+description: A simple Rails engine to log OpenRouter API usage and provide methods
+  for tracking user consumption over time, enabling easy rate-limiting.
 email:
 - mclpious@gmail.com
 executables: []
@@ -35,9 +35,12 @@ files:
 - README.md
 - Rakefile
 - app/models/concerns/open_router_usage_tracker/trackable.rb
+- app/models/open_router_usage_tracker/daily_summary.rb
 - app/models/open_router_usage_tracker/usage_log.rb
 - lib/generators/open_router_usage_tracker/install/install_generator.rb
 - lib/generators/open_router_usage_tracker/install/templates/migration.rb
+- lib/generators/open_router_usage_tracker/summary_install/summary_install_generator.rb
+- lib/generators/open_router_usage_tracker/summary_install/templates/migration.rb
 - lib/open_router_usage_tracker.rb
 - lib/open_router_usage_tracker/engine.rb
 - lib/open_router_usage_tracker/railtie.rb