xero-kiwi 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec24e1de644ead6640027a7d62ac1df0eda8677866e2f76f9c4e65c6a36d3750
-  data.tar.gz: a35d014164892fe7aefda15f4c9549d8da82fc292c85f7fcd2e6edb8bdc27458
+  metadata.gz: 353faef8c28dbf7801d5c9e8ebd152e0db172ede1aa69378144ac47cfa603436
+  data.tar.gz: b7decf2d114e9cbfba300c0274d6d9a3604c8d464ce080ac46b4a6df1e23d548
 SHA512:
-  metadata.gz: ab8caf90f556f23e2cd8d324f2995d7c6a32f18f90728463d3b561199ac5d00181b75de84594e96f9526fa1d32c97d6f97038d48f84a2f49dc41c82d87d68338
-  data.tar.gz: '048baedacba51f2cb1aed61e2fb5539cfcb90af075d64f149a305015cf4feb78fc7dd1adee2aec0af178aaf146d732ec28e341228f4dc89f40e38ff8c3be1c22'
+  metadata.gz: ff17d3c14fb35e1d6b3334935cda29c4fba9441ab012692dabc5518bb116a6615007e62a2e3c5c06a9c490f0b56d1fc16f8f42f9ff4b59d389088d68f7b2e3b9
+  data.tar.gz: ed0c6a55bcf9ed6d013f02ad76a3486a8d66f59961b959d85d7ed3e2a9f53c85cf43edb5e6f454f8c5fa556ad73983086105860983ca16c3db23633d39b3e31e

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-20
+
+### Added
+
+- `XeroKiwi.default_throttle` + `XeroKiwi.configure { |c| c.default_throttle = ... }` for configuring one shared throttle limiter at the module level. New `Client` instances pick it up automatically when no `throttle:` kwarg is passed, so a Rails app can wire a single `RedisTokenBucket` in an initializer instead of threading it through every call site. Per-instance `throttle:` still overrides. See `docs/throttling.md`.
+
 ## [0.3.0] - 2026-04-20
 
 ### Added

data/docs/throttling.md

@@ -45,6 +45,34 @@ client.organisation(tenant_id)   # blocks briefly if the bucket is empty
 Same `throttle:` instance across all clients that share a Redis — that's how
 coordination happens.
 
+## Sharing one limiter across every client (Eg. Rails)
+
+Passing `throttle:` to every `Client.new` call gets tedious. Configure a
+module-level default once, and every new client picks it up automatically:
+
+```ruby
+# config/initializers/xero_kiwi.rb
+XeroKiwi.configure do |c|
+  c.default_throttle = XeroKiwi::Throttle::RedisTokenBucket.new(
+    redis:      Redis.new(url: ENV.fetch("REDIS_URL")),
+    per_minute: 55,
+    per_day:    4_900
+  )
+end
+```
+
+From then on:
+
+```ruby
+XeroKiwi::Client.new(access_token: token)             # uses default_throttle
+XeroKiwi::Client.new(access_token: token, throttle: other) # explicit override wins
+XeroKiwi::Client.new(access_token: token, throttle: XeroKiwi::Throttle::NullLimiter.new) # opt out
+```
+
+Precedence is: explicit `throttle:` kwarg → `XeroKiwi.default_throttle` →
+`NullLimiter`. Reset in tests with `XeroKiwi.default_throttle = nil` so global
+state doesn't leak between examples.
+
 ## How it works
 
 A token bucket per tenant, stored as a Redis hash. Each call to Xero consumes

data/lib/xero_kiwi/client.rb

@@ -77,7 +77,7 @@ module XeroKiwi
       @adapter          = adapter
       @user_agent       = user_agent
       @retry_options    = DEFAULT_RETRY_OPTIONS.merge(retry_options)
-      @throttle         = throttle || Throttle::NullLimiter.new
+      @throttle         = throttle || XeroKiwi.default_throttle || Throttle::NullLimiter.new
       @refresh_mutex    = Mutex.new
     end
 

data/lib/xero_kiwi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module XeroKiwi
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/xero_kiwi.rb

@@ -35,4 +35,20 @@ require_relative "xero_kiwi/oauth/pkce"
 require_relative "xero_kiwi/oauth/id_token"
 
 module XeroKiwi
+  class << self
+    # Default throttle limiter applied to every new Client that doesn't pass
+    # its own `throttle:` kwarg. Lets a Rails app wire one shared limiter
+    # (e.g. a RedisTokenBucket) in an initializer without threading it
+    # through every call site. Per-instance `throttle:` still wins.
+    attr_accessor :default_throttle
+  end
+
+  # Yields the module for block-style configuration.
+  #
+  #   XeroKiwi.configure do |c|
+  #     c.default_throttle = XeroKiwi::Throttle::RedisTokenBucket.new(...)
+  #   end
+  def self.configure
+    yield self
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xero-kiwi
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Douglas Greyling