meter_box 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49aa4e6a97cf8056931198070491fada25452f673af872f06a67ec5629084e4f
+  data.tar.gz: 0a343321bb9b806529ea273df1bbc4b9e7e83e21e2ba0cba19e11d50c3bac702
+SHA512:
+  metadata.gz: 96ef328822e774614ddcf2aaff22f3274807a605136b9ab76ca91fc7d88f6295aa9c447263304eb6ff71c18d76f799c20ff09f250320dd59d77d67a1a042c059
+  data.tar.gz: 935d1548499c9bdc67f35a566de41ad9771396a7d6f02dbf65dd88ce64329ff264f6a7d11fd604123ea26a27254ad2cf6a0a7061501dda6f96299a37e1b6d590

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- Append-only event recording with `MeterBox.record`
+- Aggregation queries: `total`, `breakdown`, `over_cap?`, `events_for`
+- Per-meter aggregation types (sum, count, latest, max, min, mean, count_distinct)
+- Typed dimension validation (required, allowed values)
+- Idempotent inserts via `idempotency_key`
+- Polymorphic owner support
+- Thread-safe configuration lifecycle
+- Rails install generator (`rails generate meter_box:install`)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Murray
+
+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,291 @@
+# MeterBox
+
+Append-only, multi-dimensional usage metering for ActiveRecord and PostgreSQL.
+
+MeterBox records usage events against polymorphic owners with typed dimensions, then queries them with time-range filtering and dimension breakdowns. Events are immutable — corrections are new events with negative values.
+
+## Requirements
+
+- Ruby >= 3.2
+- ActiveRecord >= 7.1
+- PostgreSQL (JSONB columns, GIN indexes, partial unique indexes)
+
+## Getting Started
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "meter_box"
+```
+
+Run the install generator:
+
+```bash
+bundle install
+rails generate meter_box:install
+rails db:migrate
+```
+
+This creates:
+- A migration for the `meter_box_events` table
+- An initializer at `config/initializers/meter_box.rb`
+
+> **PostgreSQL 17+**: The generated migration uses `gen_random_uuid()` for primary keys. If your database supports it, you can change this to `uuidv7()` for time-ordered UUIDs.
+
+## Configuration
+
+Declare your meters in the initializer. Each meter has a name (a symbol), an optional aggregation type, and optional dimensions:
+
+```ruby
+# config/initializers/meter_box.rb
+MeterBox.configure do |config|
+  config.meter :signatures,
+    dimensions: {
+      method:        { values: %i[mitid otp], required: true },
+      subaccount_id: { required: false }
+    }
+
+  config.meter :api_calls,
+    aggregation: :count,
+    dimensions: {
+      endpoint: { required: true }
+    }
+
+  config.meter :temperature,
+    aggregation: :latest,
+    dimensions: {
+      sensor: { required: true, values: %i[indoor outdoor] }
+    }
+end
+```
+
+### Aggregation types
+
+The `aggregation:` option controls how `MeterBox.total` and `MeterBox.breakdown` aggregate events. Defaults to `:sum`.
+
+| Type | SQL equivalent | Return type | Empty scope |
+|------|---------------|-------------|-------------|
+| `:sum` | `SUM(value)` | `Numeric` | `0` |
+| `:count` | `COUNT(*)` | `Integer` | `0` |
+| `:max` | `MAX(value)` | `Numeric` | `nil` |
+| `:min` | `MIN(value)` | `Numeric` | `nil` |
+| `:mean` | `AVG(value)` | `BigDecimal` | `nil` |
+| `:latest` | Value from the most recent event | `Numeric` | `nil` |
+| `:count_distinct` | `COUNT(DISTINCT value)` | `Integer` | `0` |
+
+`:latest` orders by `recorded_at DESC`, breaking ties with `created_at DESC`.
+
+**`:count` vs `:sum`**: When every event uses the default `value: 1`, `:count` and `:sum` return the same number. They diverge when events carry varying values — `:sum` adds up the `value` column while `:count` counts rows regardless of value. If you're counting occurrences (API calls, logins), `:sum` with the default value is sufficient. `:count` is useful when events carry a meaningful value (e.g., bytes transferred) but you still want to know how many events occurred.
+
+### Dimension options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `required` | Boolean | `false` | When `true`, `MeterBox.record` raises `MissingDimension` if this key is absent |
+| `values` | Array of symbols | _(none)_ | Constrains allowed values. Omit to allow any value. Symbols and strings are interchangeable |
+
+### Freeze semantics
+
+`MeterBox.configure` freezes the registry after the block returns. Any attempt to register a meter afterwards raises `ConfigurationFrozen`. This ensures meters are defined at boot time and version with your codebase.
+
+## Usage
+
+MeterBox exposes five public methods. All accept keyword arguments.
+
+### `MeterBox.record`
+
+Records a usage event.
+
+```ruby
+MeterBox.record(
+  owner:           account,            # any ActiveRecord model (polymorphic)
+  meter:           :signatures,        # registered meter name
+  value:           1,                  # any Numeric (Integer, Float, BigDecimal), defaults to 1
+  dimensions:      { method: :mitid }, # validated against meter declaration
+  metadata:        { session: "abc" }, # free-form JSONB, never queried
+  idempotency_key: "evt-123",          # optional, prevents duplicate inserts
+  recorded_at:     Time.current        # defaults to now; backfill with past timestamps
+)
+# => MeterBox::Event
+```
+
+**Idempotency**: When an `idempotency_key` is provided, a second call with the same key (scoped to owner + meter) returns the original event without inserting a duplicate or raising an error.
+
+**Corrections**: To correct a previous event, record a new event with a negative `value`. MeterBox never updates or deletes rows.
+
+```ruby
+MeterBox.record(owner: account, meter: :signatures, value: -1,
+                dimensions: { method: :mitid },
+                metadata: { reason: "double-emitted" })
+```
+
+### `MeterBox.total`
+
+Returns the aggregated result for matching events, using the meter's configured aggregation type.
+
+```ruby
+MeterBox.total(
+  owner: account,
+  meter: :signatures,
+  since: Time.utc(2026, 1, 1),         # inclusive, optional
+  until: Time.utc(2026, 2, 1),         # exclusive, optional
+  where: { method: :mitid }            # dimension filter, optional
+)
+# => Numeric or nil (see aggregation types table)
+```
+
+- `since` is **inclusive** (`recorded_at >= since`)
+- `until` is **exclusive** (`recorded_at < until`)
+- Return value depends on aggregation type — `:sum` and `:count` return `0` for empty scopes; `:max`, `:min`, `:mean`, and `:latest` return `nil`
+
+### `MeterBox.breakdown`
+
+Groups aggregated results by one or more dimensions.
+
+```ruby
+MeterBox.breakdown(
+  owner: account,
+  meter: :signatures,
+  by:    :method,                       # symbol or array of symbols
+  since: Time.utc(2026, 1, 1),
+  until: Time.utc(2026, 2, 1)
+)
+# => { { method: "mitid" } => 42, { method: "otp" } => 17 }
+```
+
+Returns an empty hash when no events match. The `by:` keys must be declared dimensions on the meter.
+
+### `MeterBox.over_cap?`
+
+Checks whether the total meets or exceeds a given cap.
+
+```ruby
+MeterBox.over_cap?(
+  owner: account,
+  meter: :signatures,
+  cap:   1000,
+  since: Time.utc(2026, 1, 1),
+  where: { method: :mitid }
+)
+# => true / false
+```
+
+MeterBox does not store cap values — the caller supplies the cap. This keeps plan/billing logic in the host application.
+
+### `MeterBox.events_for`
+
+Returns an `ActiveRecord::Relation` of matching events for drill-down queries.
+
+```ruby
+events = MeterBox.events_for(
+  owner: account,
+  meter: :signatures,
+  since: 1.month.ago,
+  where: { method: :mitid }
+)
+
+events.find_each do |event|
+  puts "#{event.recorded_at}: #{event.value} (#{event.dimensions})"
+end
+```
+
+## Errors
+
+All errors inherit from `MeterBox::Error < StandardError`.
+
+| Error | Raised when |
+|-------|-------------|
+| `ConfigurationFrozen` | Registering a meter after `configure` has run |
+| `UnknownMeter` | Recording or querying with an unregistered meter name |
+| `MissingDimension` | A required dimension is absent on `record` |
+| `UnknownDimension` | An undeclared dimension key is used on `record`, `where:`, or `by:` |
+| `InvalidDimensionValue` | A dimension value is not in the declared `values:` list |
+| `MissingOwner` | `owner` is `nil` or has a `nil` id |
+| `InvalidValue` | `value` is not Numeric, or `metadata` is not a Hash |
+
+## Database Schema
+
+MeterBox uses a single table: `meter_box_events`.
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `id` | UUID | Primary key |
+| `owner_type` | string | Polymorphic type |
+| `owner_id` | string | Stored as string to support any PK type |
+| `meter_name` | string | Registered meter name |
+| `value` | decimal | Signed; supports integers and fractional values; negative for corrections |
+| `dimensions` | JSONB | Validated, aggregation-relevant tags |
+| `metadata` | JSONB | Free-form audit context, never queried |
+| `idempotency_key` | string | Nullable; scoped unique per owner+meter |
+| `recorded_at` | datetime | Business time (can be backfilled) |
+| `created_at` | datetime | Insert time |
+
+Three indexes:
+- **Composite** on `(owner_type, owner_id, meter_name, recorded_at)` for query performance
+- **GIN** on `dimensions` for JSONB queries
+- **Partial unique** on `(owner_type, owner_id, meter_name, idempotency_key)` where `idempotency_key IS NOT NULL`
+
+## MeterBox vs usage_credits
+
+[usage_credits](https://github.com/rameerez/usage_credits) is a credits-based billing system. MeterBox is a metering primitive. They solve different problems and can work together.
+
+| | MeterBox | usage_credits |
+|---|---|---|
+| **Purpose** | Record and query raw usage events | Manage a credits wallet with spending, fulfillment, and billing |
+| **Data model** | Single append-only events table | Multi-table ledger (wallets, transactions, allocations, fulfillments) |
+| **What it tracks** | Dimensioned event counts/sums | Credit balance with FIFO allocation and expiration |
+| **Billing integration** | None — metering only | Stripe/PayPal via the `pay` gem |
+| **Dimensions** | Typed, validated, queryable (`by:`, `where:`) | No built-in dimension system |
+| **Aggregation** | `total`, `breakdown`, time-range filters | Transaction history queries |
+| **Idempotency** | Built-in via `idempotency_key` | Via `pay` gem for charges |
+| **Database** | PostgreSQL (JSONB, GIN indexes) | Any ActiveRecord-supported database |
+| **Corrections** | Negative-value events | Refunds and adjustments |
+| **Scope** | ~300 LOC, zero billing opinions | Full billing stack with subscriptions, packs, webhooks |
+
+**When to use MeterBox**: You need a metering layer that records what happened — how many signatures, API calls, or documents were processed — and you want to query that data with dimensional breakdowns and time ranges. Billing decisions (plans, caps, invoicing) live in your application code.
+
+**When to use usage_credits**: You want a turnkey credits system with wallets, spending, subscriptions, credit packs, and Stripe integration out of the box.
+
+**Using both**: MeterBox records the raw events; your application reads the totals to decide when to deduct credits via usage_credits.
+
+## Testing Your Application
+
+In your test suite, reset the MeterBox configuration in setup/teardown to avoid state leakage:
+
+```ruby
+class MyTest < ActiveSupport::TestCase
+  setup do
+    MeterBox.reset!
+    MeterBox.configure do |config|
+      config.meter :signatures,
+        dimensions: { method: { required: true, values: %i[mitid otp] } }
+    end
+  end
+
+  teardown do
+    MeterBox.reset!
+  end
+end
+```
+
+## Development
+
+Prerequisites: Docker (for PostgreSQL).
+
+```bash
+git clone https://github.com/ianmurrays/meter_box.git
+cd meter_box
+docker compose up -d --wait
+bundle install
+bundle exec rake test
+```
+
+To stop the database:
+
+```bash
+docker compose down
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module MeterBox
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_migration
+        migration_template(
+          "create_meter_box_events.rb.erb",
+          "db/migrate/create_meter_box_events.rb"
+        )
+      end
+
+      def copy_initializer
+        template "meter_box.rb", "config/initializers/meter_box.rb"
+      end
+    end
+  end
+end

data/lib/generators/meter_box/install/templates/create_meter_box_events.rb.erb

@@ -0,0 +1,28 @@
+class CreateMeterBoxEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :meter_box_events, id: :uuid, default: -> { "gen_random_uuid()" } do |t|
+      t.string   :owner_type,      null: false
+      t.string   :owner_id,        null: false
+      t.string   :meter_name,      null: false
+      t.decimal  :value,           null: false
+      t.jsonb    :dimensions,      null: false, default: {}
+      t.jsonb    :metadata,        null: false, default: {}
+      t.string   :idempotency_key
+      t.datetime :recorded_at,     null: false
+      t.datetime :created_at,      null: false
+    end
+
+    add_index :meter_box_events,
+              [:owner_type, :owner_id, :meter_name, :recorded_at],
+              name: "idx_mb_events_owner_meter_time"
+
+    add_index :meter_box_events, :dimensions, using: :gin,
+              name: "idx_mb_events_dimensions"
+
+    add_index :meter_box_events,
+              [:owner_type, :owner_id, :meter_name, :idempotency_key],
+              unique: true,
+              where: "idempotency_key IS NOT NULL",
+              name: "idx_mb_events_idempotency"
+  end
+end

data/lib/generators/meter_box/install/templates/meter_box.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+MeterBox.configure do |config|
+  # Declare your meters here. Each meter has a name, optional dimensions,
+  # and an optional aggregation type (defaults to :sum).
+  #
+  # Aggregation types: :sum, :count, :latest, :max, :min, :mean, :count_distinct
+  #
+  # config.meter :api_calls,
+  #   aggregation: :count,
+  #   dimensions: {
+  #     endpoint: { required: true },
+  #     plan:     { values: %i[free pro enterprise] }
+  #   }
+  #
+  # config.meter :storage_bytes,
+  #   aggregation: :latest,
+  #   dimensions: {
+  #     region: { required: true, values: %i[us eu ap] }
+  #   }
+end

data/lib/meter_box/aggregation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MeterBox
+  module Aggregation
+    class << self
+      def apply(scope, aggregation)
+        return scope.order(recorded_at: :desc, created_at: :desc).pick(:value) if aggregation == :latest
+
+        dispatch(scope, aggregation)
+      end
+
+      def apply_grouped(scope, group_sql, aggregation)
+        return latest_per_group(scope, group_sql) if aggregation == :latest
+
+        dispatch(scope.group(Arel.sql(group_sql)), aggregation)
+      end
+
+      private
+
+      def dispatch(scope, aggregation)
+        case aggregation
+        when :sum            then scope.sum(:value)
+        when :count          then scope.count
+        when :max            then scope.maximum(:value)
+        when :min            then scope.minimum(:value)
+        when :mean           then scope.average(:value)
+        when :count_distinct then scope.distinct.count(:value)
+        end
+      end
+
+      def latest_per_group(scope, group_sql)
+        subquery = scope
+          .select(Arel.sql("DISTINCT ON (#{group_sql}) #{group_sql}, value"))
+          .order(Arel.sql("#{group_sql}, recorded_at DESC, created_at DESC"))
+
+        rows = Event.connection.select_rows("SELECT * FROM (#{subquery.to_sql}) AS t")
+
+        rows.each_with_object({}) do |row, h|
+          group_vals = row[0...-1]
+          key = group_vals.length == 1 ? group_vals.first : group_vals
+          h[key] = BigDecimal(row.last)
+        end
+      end
+    end
+  end
+end

data/lib/meter_box/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MeterBox
+  # Mutation methods (meter, freeze!, reset!) require the caller to hold MeterBox's Mutex.
+  # fetch is lock-free — @meters is never mutated after freeze!.
+  class Configuration
+    def initialize
+      reset!
+    end
+
+    def meter(name, dimensions: {}, aggregation: :sum)
+      raise ConfigurationFrozen, "MeterBox configuration is frozen" if @frozen
+      @meters[name.to_sym] = Meter.new(name: name, dimensions: dimensions, aggregation: aggregation)
+    end
+
+    def fetch(name)
+      @meters.fetch(name.to_sym) do
+        raise UnknownMeter, "no meter registered as '#{name}'"
+      end
+    end
+
+    def freeze!
+      @frozen = true
+    end
+
+    def freeze
+      raise NoMethodError, "use MeterBox::Configuration#freeze! to lock the registry"
+    end
+
+    def reset!
+      @meters = {}
+      @frozen = false
+    end
+  end
+end

data/lib/meter_box/configuration_frozen.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class ConfigurationFrozen < Error; end
+end

data/lib/meter_box/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class Error < StandardError; end
+end

data/lib/meter_box/event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class Event < ActiveRecord::Base
+    self.table_name = "meter_box_events"
+
+    belongs_to :owner, polymorphic: true
+  end
+end

data/lib/meter_box/invalid_dimension_value.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class InvalidDimensionValue < Error; end
+end

data/lib/meter_box/invalid_value.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class InvalidValue < Error; end
+end

data/lib/meter_box/meter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class Meter
+    AGGREGATIONS = %i[sum count latest max min mean count_distinct].freeze
+
+    attr_reader :name, :dimensions, :aggregation
+
+    def initialize(name:, dimensions:, aggregation: :sum)
+      @name = name.to_sym
+      @dimensions = dimensions.transform_keys(&:to_sym)
+      @aggregation = aggregation.to_sym
+      unless AGGREGATIONS.include?(@aggregation)
+        raise ArgumentError,
+          "unknown aggregation :#{@aggregation} for meter '#{@name}' (allowed: #{AGGREGATIONS.inspect})"
+      end
+    end
+
+    def declared_keys
+      @dimensions.keys
+    end
+
+    def validate_dimensions!(supplied)
+      supplied = supplied.transform_keys(&:to_sym)
+
+      check_required!(supplied)
+      check_unknown_keys!(supplied)
+      check_values!(supplied)
+    end
+
+    private
+
+    def check_required!(supplied)
+      @dimensions.each do |key, opts|
+        next unless opts[:required]
+        next if supplied.key?(key)
+        raise MissingDimension,
+          "missing required dimension '#{key}' for meter '#{name}'"
+      end
+    end
+
+    def check_unknown_keys!(supplied)
+      undeclared = supplied.keys - declared_keys
+      return if undeclared.empty?
+      raise UnknownDimension,
+        "undeclared dimension(s) #{undeclared.inspect} for meter '#{name}'"
+    end
+
+    def check_values!(supplied)
+      supplied.each do |key, value|
+        opts = @dimensions[key]
+        next unless opts && opts[:values]
+        allowed = opts[:values].map(&:to_s)
+        next if allowed.include?(value.to_s)
+        raise InvalidDimensionValue,
+          "value '#{value}' not allowed for dimension '#{key}' on meter '#{name}' (allowed: #{allowed.inspect})"
+      end
+    end
+  end
+end

data/lib/meter_box/missing_dimension.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class MissingDimension < Error; end
+end

data/lib/meter_box/missing_owner.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class MissingOwner < Error; end
+end

data/lib/meter_box/query.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class Query
+    ALLOWED_OPTS = %i[since until where].freeze
+
+    def self.total(owner:, meter:, **opts)
+      validate_opts!(opts)
+      meter_obj = MeterBox.config.fetch(meter)
+      Aggregation.apply(build_scope(owner, meter, opts), meter_obj.aggregation)
+    end
+
+    def self.breakdown(owner:, meter:, by:, **opts)
+      validate_opts!(opts)
+      meter_obj = MeterBox.config.fetch(meter)
+      keys = Array(by).map(&:to_sym)
+      keys.each do |k|
+        unless meter_obj.declared_keys.include?(k)
+          raise UnknownDimension,
+            "dimension '#{k}' not declared on meter '#{meter}'"
+        end
+      end
+
+      scope = build_scope(owner, meter, opts)
+      group_sql = keys.map { |k| "dimensions->>'#{k}'" }.join(", ")
+      raw = Aggregation.apply_grouped(scope, group_sql, meter_obj.aggregation)
+
+      raw.each_with_object({}) do |(row, val), out|
+        values = Array(row)
+        out[keys.zip(values).to_h] = val
+      end
+    end
+
+    def self.over_cap?(owner:, meter:, cap:, **opts)
+      (total(owner: owner, meter: meter, **opts) || 0) >= cap
+    end
+
+    def self.events_for(owner:, meter:, **opts)
+      validate_opts!(opts)
+      build_scope(owner, meter, opts)
+    end
+
+    class << self
+      private
+
+      def validate_opts!(opts)
+        bad = opts.keys - ALLOWED_OPTS
+        raise ArgumentError, "unknown option(s) #{bad.inspect}" unless bad.empty?
+      end
+
+      def build_scope(owner, meter, opts)
+        validate_owner!(owner)
+        meter_obj = MeterBox.config.fetch(meter)
+
+        where = opts.fetch(:where, {})
+        where.each_key do |k|
+          unless meter_obj.declared_keys.include?(k.to_sym)
+            raise UnknownDimension,
+              "dimension '#{k}' not declared on meter '#{meter}'"
+          end
+        end
+
+        scope = Event.where(
+          owner_type: owner.class.name,
+          owner_id:   owner.id.to_s,
+          meter_name: meter.to_s
+        )
+        scope = scope.where("recorded_at >= ?", opts[:since]) if opts[:since]
+        scope = scope.where("recorded_at < ?",  opts[:until]) if opts[:until]
+        where.each do |k, v|
+          scope = scope.where("dimensions ->> ? = ?", k.to_s, v.to_s)
+        end
+        scope
+      end
+
+      def validate_owner!(owner)
+        raise MissingOwner, "owner is required" if owner.nil?
+        unless owner.respond_to?(:id) && !owner.id.nil?
+          raise MissingOwner, "owner must respond to #id with a non-nil value"
+        end
+      end
+    end
+  end
+end

data/lib/meter_box/recorder.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class Recorder
+    def self.call(**kwargs)
+      new.call(**kwargs)
+    end
+
+    def call(owner:, meter:, value: 1, dimensions: {}, metadata: {},
+             idempotency_key: nil, recorded_at: nil)
+      validate_owner!(owner)
+      meter_obj = MeterBox.config.fetch(meter)
+      validate_value!(value)
+      validate_metadata!(metadata)
+      meter_obj.validate_dimensions!(dimensions)
+
+      attrs = {
+        owner_type:      owner.class.name,
+        owner_id:        owner.id.to_s,
+        meter_name:      meter_obj.name.to_s,
+        value:           value,
+        dimensions:      stringify(dimensions),
+        metadata:        stringify_keys(metadata),
+        idempotency_key: idempotency_key,
+        recorded_at:     recorded_at || Time.current
+      }
+
+      insert_with_idempotency(attrs)
+    end
+
+    private
+
+    def validate_owner!(owner)
+      raise MissingOwner, "owner is required" if owner.nil?
+      unless owner.respond_to?(:id) && !owner.id.nil?
+        raise MissingOwner, "owner must respond to #id with a non-nil value"
+      end
+    end
+
+    def validate_value!(value)
+      return if value.is_a?(Numeric)
+      raise InvalidValue, "value must be Numeric (got #{value.class})"
+    end
+
+    def validate_metadata!(metadata)
+      return if metadata.is_a?(Hash)
+      raise InvalidValue, "metadata must be a Hash (got #{metadata.class})"
+    end
+
+    def stringify(dims)
+      dims.each_with_object({}) do |(k, v), h|
+        h[k.to_s] = v.is_a?(Symbol) ? v.to_s : v
+      end
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+
+    def insert_with_idempotency(attrs)
+      Event.create!(attrs)
+    rescue ActiveRecord::RecordNotUnique
+      Event.find_by(
+        owner_type:      attrs[:owner_type],
+        owner_id:        attrs[:owner_id],
+        meter_name:      attrs[:meter_name],
+        idempotency_key: attrs[:idempotency_key]
+      )
+    end
+  end
+end

data/lib/meter_box/unknown_dimension.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class UnknownDimension < Error; end
+end

data/lib/meter_box/unknown_meter.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MeterBox
+  class UnknownMeter < Error; end
+end

data/lib/meter_box/version.rb

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

data/lib/meter_box.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative "meter_box/version"
+require_relative "meter_box/error"
+require_relative "meter_box/configuration_frozen"
+require_relative "meter_box/unknown_meter"
+require_relative "meter_box/missing_dimension"
+require_relative "meter_box/unknown_dimension"
+require_relative "meter_box/invalid_dimension_value"
+require_relative "meter_box/missing_owner"
+require_relative "meter_box/invalid_value"
+require_relative "meter_box/meter"
+require_relative "meter_box/configuration"
+require_relative "meter_box/event"
+require_relative "meter_box/recorder"
+require_relative "meter_box/aggregation"
+require_relative "meter_box/query"
+
+module MeterBox
+  @mutex = Mutex.new
+
+  def self.config
+    @config || @mutex.synchronize { @config ||= Configuration.new }
+  end
+
+  def self.configure
+    @mutex.synchronize do
+      yield(@config ||= Configuration.new)
+      @config.freeze!
+    end
+  end
+
+  def self.reset!
+    @mutex.synchronize { @config&.reset! }
+  end
+
+  def self.record(**kwargs)
+    Recorder.call(**kwargs)
+  end
+
+  def self.total(**kwargs)
+    Query.total(**kwargs)
+  end
+
+  def self.breakdown(**kwargs)
+    Query.breakdown(**kwargs)
+  end
+
+  def self.over_cap?(**kwargs)
+    Query.over_cap?(**kwargs)
+  end
+
+  def self.events_for(**kwargs)
+    Query.events_for(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: meter_box
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ian Murray
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  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'
+- !ruby/object:Gem::Dependency
+  name: pg
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: Record and query multi-dimensional usage events against polymorphic owners.
+  Supports typed dimensions, idempotent inserts, time-range aggregation, and dimension
+  breakdowns.
+email:
+- ianmurrays@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/meter_box/install/install_generator.rb
+- lib/generators/meter_box/install/templates/create_meter_box_events.rb.erb
+- lib/generators/meter_box/install/templates/meter_box.rb
+- lib/meter_box.rb
+- lib/meter_box/aggregation.rb
+- lib/meter_box/configuration.rb
+- lib/meter_box/configuration_frozen.rb
+- lib/meter_box/error.rb
+- lib/meter_box/event.rb
+- lib/meter_box/invalid_dimension_value.rb
+- lib/meter_box/invalid_value.rb
+- lib/meter_box/meter.rb
+- lib/meter_box/missing_dimension.rb
+- lib/meter_box/missing_owner.rb
+- lib/meter_box/query.rb
+- lib/meter_box/recorder.rb
+- lib/meter_box/unknown_dimension.rb
+- lib/meter_box/unknown_meter.rb
+- lib/meter_box/version.rb
+homepage: https://github.com/ianmurrays/meter_box
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ianmurrays/meter_box
+  source_code_uri: https://github.com/ianmurrays/meter_box
+  changelog_uri: https://github.com/ianmurrays/meter_box/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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.6
+specification_version: 4
+summary: Append-only, multi-dimensional usage metering for ActiveRecord + PostgreSQL
+test_files: []