xero-kiwi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8461f3c23bcec591acd4a6bb875ff08f4bacf67573ae6e1957ad78a268d4c7bb
-  data.tar.gz: 8167dae0e2922d57099b177a3ee182f3728c28dfc45f6fd0a50ae61a50ea0feb
+  metadata.gz: 775f2c27c6c923aa8ab8c2cbb525d83ab7add7c174315e555428ccd45e520836
+  data.tar.gz: 5d5572e18a023da88435a091636094eae2800442348eaf6e9c19c25b1127e1fd
 SHA512:
-  metadata.gz: 1a55d9c5c9022a6fbf7fcc777d8084775d54e464d87008dfa876f234f792f5ec45a427ea55dfef0adb01ee8f1101ef49999206d64e6b8cec63f0a97fec3564dd
-  data.tar.gz: 95b28e21648463606521aff37c8413e7f6a73fa9f731d30098ef757cb480beaa2f1c3da3f588b1b00ca8cf00784dcd5ec9ca2c7853d129b35ed82ddf6bececaa
+  metadata.gz: f2f8890ad95b9c4c037a4a7d7470b3b32581730960552f6a21c436f3a9209bbf5af3a9ee78467c230c805d5d86de129f4510021098cc4dc2b2c5100e8bc2862c
+  data.tar.gz: 7fd1302cfac5d9e5b2e5a3b0c15a720d9ad08b02d550a65c70e4fb900fa7461ad7be9d3d37c4325aa2d6b2072ac35a6ef5a21b003b63e2cf2561ddf3f4df1e8f

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-15
+
+### Added
+
+- Optional proactive rate-limit throttling via a Redis-backed token bucket, keyed per tenant. Pass `throttle:` to `XeroKiwi::Client.new` to coordinate rate limits across processes (e.g. multiple Sidekiq workers hitting the same Xero tenant). Supports per-minute and per-day limits; per-minute waits are bounded by `max_wait`, per-day exhaustion raises `XeroKiwi::Throttle::DailyLimitExhausted`. Composes with the existing reactive retry layer — neither replaces the other. See `docs/throttling.md`.
+
+### Changed
+
+- `redis` is now a runtime dependency (used only if you opt into throttling).
+
+## [0.1.1] - 2026-04-15
+
+- Add `lib/xero-kiwi.rb` shim so `gem "xero-kiwi"` in a Gemfile auto-requires the gem without needing `require: "xero_kiwi"`.
+
 ## [0.1.0] - 2026-04-15
 
 - Initial release

data/README.md

@@ -1,6 +1,6 @@
 # Xero Kiwi
 
-A Ruby wrapper for the [Xero](https://www.xero.com) Accounting API. XeroKiwi handles
+A Ruby wrapper for the [Xero](https://www.xero.com) Accounting API. Xero Kiwi handles
 the unglamorous parts of integrating with Xero — OAuth2, token refresh, rate
 limiting, retries — so the rest of your code can focus on the actual business
 problem.
@@ -33,7 +33,7 @@ gem "xero-kiwi"
 
 Then run `bundle install`.
 
-XeroKiwi requires Ruby 3.4.1 or newer.
+Xero Kiwi requires Ruby 3.4.1 or newer.
 
 ## Quick start
 
@@ -70,14 +70,36 @@ below.
 | [Tokens](docs/tokens.md) | The `XeroKiwi::Token` value object, automatic refresh, revocation, persistence callbacks |
 | [OAuth](docs/oauth.md) | Authorization URL building, code exchange, PKCE, ID token verification, full Rails-style example |
 | [Errors](docs/errors.md) | The error hierarchy, what to catch and when |
-| [Retries and rate limits](docs/retries-and-rate-limits.md) | How XeroKiwi handles 429s and transient failures, customising the retry policy |
+| [Retries and rate limits](docs/retries-and-rate-limits.md) | How Xero Kiwi handles 429s and transient failures, customising the retry policy |
+| [Throttling](docs/throttling.md) | Redis-backed token bucket for proactive rate-limit coordination across multiple workers |
 
 ## Status
 
-XeroKiwi is in early development. The API surface for the features documented above
+Xero Kiwi is in early development. The API surface for the features documented above
 is stable, but expect new resource methods to be added over time. Breaking
 changes will be called out in the [changelog](CHANGELOG.md).
 
+## Development
+
+The gem runs natively via Bundler — nothing is containerised for everyday
+development. A `docker-compose.yml` exists for *external services* the specs
+need, currently just Redis (used by the throttle limiter's Lua-backed specs).
+
+```sh
+bundle install
+docker compose up -d redis   # optional; only needed for :redis-tagged specs
+bundle exec rspec
+```
+
+Without Redis running, specs tagged `:redis` are filtered out automatically
+(see [spec/spec_helper.rb](spec/spec_helper.rb)) so the suite still passes.
+Override the test Redis URL with `TEST_REDIS_URL=...` if you don't want the
+default `redis://127.0.0.1:6379/15`.
+
+```sh
+docker compose down          # when you're done
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/Rakefile

@@ -44,8 +44,8 @@ LLMS_FULL_PATH = "llms-full.txt"
 # expected output.
 def build_llms_full
   out = +""
-  out << "# XeroKiwi — full documentation\n\n"
-  out << "This file is the complete documentation for the XeroKiwi gem (a Ruby wrapper for the Xero Accounting API), assembled into a single document for LLM consumption. It contains the README and every doc in the docs/ folder, in reading order.\n\n"
+  out << "# Xero Kiwi — full documentation\n\n"
+  out << "This file is the complete documentation for the Xero Kiwi gem (a Ruby wrapper for the Xero Accounting API), assembled into a single document for LLM consumption. It contains the README and every doc in the docs/ folder, in reading order.\n\n"
   out << "For the curated index version, see llms.txt in the same directory.\n\n"
   out << "Source: https://github.com/douglasgreyling/xero-kiwi\n\n"
   LLMS_SOURCE_FILES.each { |path| append_file_block(out, path) }

data/docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  redis:
+    image: redis:7-alpine
+    container_name: xero-kiwi-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 2s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  redis-data:

data/docs/accounting/branding-theme.md

@@ -58,7 +58,7 @@ sets.
 ## Date parsing
 
 The `created_date_utc` field uses Xero's .NET JSON timestamp format
-(`/Date(946684800000+0000)/`). XeroKiwi parses both .NET JSON and ISO 8601
+(`/Date(946684800000+0000)/`). Xero Kiwi parses both .NET JSON and ISO 8601
 formats transparently — the attribute is always a UTC `Time` object.
 
 ## Error behaviour

data/docs/accounting/organisation.md

@@ -82,7 +82,7 @@ API. Connections use ISO 8601 strings (e.g. `"2019-07-09T23:40:30.1833130"`),
 but the Accounting API (including Organisation) uses the legacy .NET JSON
 format: `/Date(1574275974000)/`.
 
-XeroKiwi handles both transparently — all `Time` attributes are parsed to UTC
+Xero Kiwi handles both transparently — all `Time` attributes are parsed to UTC
 `Time` objects regardless of which format Xero sends. You don't need to think
 about this unless you're looking at raw cassette data or debugging timestamp
 issues.

data/docs/accounting/user.md

@@ -74,7 +74,7 @@ Two users are `==` if they share the same `user_id`. `#hash` is consistent with
 ## Date parsing
 
 The `updated_date_utc` field uses Xero's .NET JSON timestamp format
-(`/Date(1516230549137+0000)/`). XeroKiwi parses both .NET JSON and ISO 8601
+(`/Date(1516230549137+0000)/`). Xero Kiwi parses both .NET JSON and ISO 8601
 formats transparently — the attribute is always a UTC `Time` object.
 
 ## Error behaviour

data/docs/client.md

@@ -3,7 +3,7 @@
 `XeroKiwi::Client` is the entry point for talking to Xero's accounting API. You
 construct one with credentials and call resource methods on it. The client
 holds the OAuth token state, knows how to refresh it, and translates HTTP
-errors into XeroKiwi exceptions.
+errors into Xero Kiwi exceptions.
 
 ## Constructing a client
 
@@ -97,7 +97,7 @@ skipped: a 401 raises immediately and you handle it in your own code.
 
 ## Custom adapters
 
-XeroKiwi uses Faraday under the hood, so you can swap the HTTP adapter for
+Xero Kiwi uses Faraday under the hood, so you can swap the HTTP adapter for
 testing or for connection pooling:
 
 ```ruby
@@ -123,7 +123,7 @@ test adapter swallows refresh requests too.
 
 ## Customising the retry policy
 
-`retry_options:` is merged into XeroKiwi's defaults, so you only need to specify
+`retry_options:` is merged into Xero Kiwi's defaults, so you only need to specify
 overrides:
 
 ```ruby

data/docs/connections.md

@@ -74,7 +74,7 @@ old_connections - new_connections # diff by id
 
 Xero serialises dates in C# DateTime format and frequently omits the timezone
 marker on values that are documented as UTC (e.g. `"2019-07-09T23:40:30.1833130"`).
-XeroKiwi force-appends a `Z` before parsing so you always get a UTC `Time` back —
+Xero Kiwi force-appends a `Z` before parsing so you always get a UTC `Time` back —
 without this, `Time.parse` would silently fall back to local time and you'd
 get the wrong instant.
 

data/docs/errors.md

@@ -1,6 +1,6 @@
 # Errors
 
-Every failure path in XeroKiwi raises a typed exception. This page walks through
+Every failure path in Xero Kiwi raises a typed exception. This page walks through
 the hierarchy, explains what each class means, and tells you what to catch
 in common situations.
 
@@ -8,7 +8,7 @@ in common situations.
 
 ```
 StandardError
-└─ XeroKiwi::Error                       (root — catch this for "anything XeroKiwi raised")
+└─ XeroKiwi::Error                       (root — catch this for "anything Xero Kiwi raised")
    ├─ XeroKiwi::APIError                 (root for HTTP responses; carries status + body)
    │  ├─ XeroKiwi::AuthenticationError   (401)
    │  │  ├─ XeroKiwi::TokenRefreshError  (refresh round-trip failed)
@@ -22,7 +22,7 @@ StandardError
 
 A few things worth noticing about the shape:
 
-- **Everything XeroKiwi raises** descends from `XeroKiwi::Error`. If you only want
+- **Everything Xero Kiwi raises** descends from `XeroKiwi::Error`. If you only want
   one rescue clause for "the Xero integration broke," catch this.
 - **HTTP responses** descend from `XeroKiwi::APIError`, which carries `status`
   and `body` attributes you can inspect.
@@ -38,7 +38,7 @@ A few things worth noticing about the shape:
 ### `XeroKiwi::Error`
 
 The root class. Inherits from `StandardError`. You almost never raise this
-directly — it exists as a catch-all for code that wants to rescue "any XeroKiwi
+directly — it exists as a catch-all for code that wants to rescue "any Xero Kiwi
 problem" without enumerating every subclass.
 
 ### `XeroKiwi::APIError`
@@ -62,7 +62,7 @@ The access token was rejected. The most common causes:
 - Token has the wrong scopes for this endpoint.
 - The wrong tenant ID was passed in the `Xero-Tenant-Id` header.
 
-If your client has refresh capability, XeroKiwi will already have tried to
+If your client has refresh capability, Xero Kiwi will already have tried to
 refresh and retry exactly once before this raises. Seeing `AuthenticationError`
 on a refresh-capable client means **the second 401 also failed** — refresh
 won't fix it, and you need to either re-authorise or surface the error.
@@ -115,9 +115,9 @@ Inspect `error.body` to surface it.
 
 ### `XeroKiwi::ServerError` (HTTP 5xx)
 
-A 5xx response that wasn't retried. XeroKiwi retries 502/503/504 automatically
+A 5xx response that wasn't retried. Xero Kiwi retries 502/503/504 automatically
 (see [retries and rate limits](retries-and-rate-limits.md)) so by the time
-you see this, the retries are exhausted or the status was 500 (which XeroKiwi
+you see this, the retries are exhausted or the status was 500 (which Xero Kiwi
 deliberately doesn't retry, since 500s are usually persistent bugs in the
 request rather than transient infrastructure issues).
 
@@ -164,7 +164,7 @@ The error message has a brief description of which check failed (e.g.
 
 ## What to catch when
 
-### "Any XeroKiwi failure"
+### "Any Xero Kiwi failure"
 
 ```ruby
 begin
@@ -256,12 +256,12 @@ Order matters — `TokenRefreshError` is more specific than
 
 ## Things the error system deliberately does NOT do
 
-- **No "this error is retryable" predicate.** XeroKiwi already retries the
+- **No "this error is retryable" predicate.** Xero Kiwi already retries the
   cases that *should* be retried at the HTTP level. By the time an exception
   reaches your code, the retries are exhausted and the situation is
   application-level. Adding `error.retryable?` would create a tempting
   foot-gun where callers retry inside their own code, doubling up on the
-  retries XeroKiwi is already doing.
+  retries Xero Kiwi is already doing.
 - **No automatic Sentry / Bugsnag integration.** Errors raise normally;
   configure your own observability layer to catch them at the boundary.
 - **No `error.code` enum.** The HTTP `status` is the enum. Inspecting it

data/docs/getting-started.md

@@ -16,7 +16,7 @@ Before you can talk to Xero from Ruby, you need:
 
 ## Installing the gem
 
-Add XeroKiwi to your `Gemfile`:
+Add Xero Kiwi to your `Gemfile`:
 
 ```ruby
 gem "xero-kiwi"
@@ -30,7 +30,7 @@ bundle install
 
 ## The mental model
 
-XeroKiwi is built around a small set of objects, each with one job:
+Xero Kiwi is built around a small set of objects, each with one job:
 
 | Object | What it does |
 |--------|--------------|

data/docs/oauth.md

@@ -198,7 +198,7 @@ token = oauth.exchange_code(
 
 If you pass a `pkce:` to `authorization_url` but **forget** the
 `code_verifier:` on `exchange_code`, Xero will reject the exchange with
-`invalid_grant` and XeroKiwi will raise `XeroKiwi::OAuth::CodeExchangeError`.
+`invalid_grant` and Xero Kiwi will raise `XeroKiwi::OAuth::CodeExchangeError`.
 
 ## Step 2: handling the callback
 
@@ -489,7 +489,7 @@ end
 
 ## Things OAuth deliberately does NOT do
 
-- **No session storage.** XeroKiwi gives you `generate_state` and
+- **No session storage.** Xero Kiwi gives you `generate_state` and
   `generate_pkce` as helpers but never touches your session/cookies/Redis.
   Where you stash the values is your problem — and that's a feature,
   because every framework is different.

data/docs/retries-and-rate-limits.md

@@ -1,6 +1,6 @@
 # Retries and rate limits
 
-This doc explains how XeroKiwi handles transient failures: rate limiting, server
+This doc explains how Xero Kiwi handles transient failures: rate limiting, server
 errors, and network blips. Most of the time you don't need to know any of
 this — the defaults are sensible. Read on if you need to tune the retry
 policy or you want to understand what's happening when a request mysteriously
@@ -20,9 +20,9 @@ Xero enforces three separate rate limits, all returned with HTTP 429:
 Plus a `Retry-After` header on every 429 telling you how many seconds to
 wait before trying again.
 
-## What XeroKiwi does automatically
+## What Xero Kiwi does automatically
 
-XeroKiwi sets up a `faraday-retry` middleware that handles transient failures
+Xero Kiwi sets up a `faraday-retry` middleware that handles transient failures
 without any code from you. The default retry policy:
 
 | Setting | Default | Why |
@@ -38,13 +38,13 @@ without any code from you. The default retry policy:
 ### Retry-After is honoured
 
 `faraday-retry` automatically respects the `Retry-After` header on 429
-responses. So if Xero says "wait 30 seconds," XeroKiwi waits 30 seconds before
+responses. So if Xero says "wait 30 seconds," Xero Kiwi waits 30 seconds before
 retrying — not the exponential backoff schedule. This is the whole reason
 to use a real retry middleware instead of rolling your own.
 
 ### Which 5xx are retried
 
-XeroKiwi retries `502 Bad Gateway`, `503 Service Unavailable`, and `504 Gateway
+Xero Kiwi retries `502 Bad Gateway`, `503 Service Unavailable`, and `504 Gateway
 Timeout`. These are the canonical "the upstream is having a temporary
 problem" statuses.
 
@@ -66,7 +66,7 @@ The retried request count includes the original attempt, so `max: 4` means
 
 ## Customising the retry policy
 
-Pass `retry_options:` to `XeroKiwi::Client.new`. The hash is merged into XeroKiwi's
+Pass `retry_options:` to `XeroKiwi::Client.new`. The hash is merged into Xero Kiwi's
 defaults, so you only specify what you want to change:
 
 ```ruby
@@ -109,7 +109,7 @@ retry_options: {
 }
 ```
 
-This is what XeroKiwi's own test suite uses to keep specs deterministic and
+This is what Xero Kiwi's own test suite uses to keep specs deterministic and
 fast.
 
 **Adding 500 to the retry list** (against my advice, but sometimes you
@@ -123,7 +123,7 @@ retry_options: {
 
 ### One thing you must NOT remove
 
-XeroKiwi's default `exceptions:` list includes `Faraday::RetriableResponse`,
+Xero Kiwi's default `exceptions:` list includes `Faraday::RetriableResponse`,
 which is the *internal* signal `faraday-retry` uses to flag a status-code
 retry. **It must stay in the list**, or the retry middleware can't catch
 its own retry signal and 429s/503s will never be retried — they'll bubble
@@ -169,7 +169,7 @@ needs to know about `RateLimitError` to know to retry it. That's brittle.
 By putting Retry on the inside, the retry middleware sees raw HTTP envs
 with status 429 and uses its own `retry_statuses` config to decide what to
 do. ResponseHandler only sees the *final* env (after retries are done) and
-maps it to a XeroKiwi exception.
+maps it to a Xero Kiwi exception.
 
 You don't need to think about any of this — it's the gem's job — but if
 you ever subclass the client or insert your own middleware, this is the
@@ -202,7 +202,7 @@ retry/backoff schedules — they won't coordinate.
 
 If you need cross-thread coordination (e.g. "all threads should pause when
 any one of them hits a 429"), build it at the application level using a
-shared semaphore or rate limiter. XeroKiwi doesn't ship one, because the right
+shared semaphore or rate limiter. Xero Kiwi doesn't ship one, because the right
 shape depends entirely on your traffic patterns.
 
 ## Things the retry layer deliberately does NOT do
@@ -212,13 +212,15 @@ shape depends entirely on your traffic patterns.
 - **No retry on 4xx (other than 429).** 4xx means the client did something
   wrong; retrying won't fix it. The exception is 429 (rate limit), which is
   classified as 4xx but is fundamentally a "wait and try again" signal.
-- **No global rate limiter.** XeroKiwi reacts to 429s as they happen but
-  doesn't proactively throttle — it'll happily fire 100 concurrent requests
-  and rely on Xero's 429s to slow things down. If you need proactive
-  throttling, do it at your job-queue level.
+- **No global rate limiter *by default*.** Xero Kiwi reacts to 429s as they
+  happen but doesn't proactively throttle unless you opt in. For multi-worker
+  setups where several processes hit the same tenant, wire up the
+  Redis-backed token bucket described in
+  [throttling.md](throttling.md) — it composes with this retry layer rather
+  than replacing it.
 - **No retry budget across calls.** Each `client.connections` (or any
   other call) gets a fresh `max` retries. There's no concept of "this client
   has had too many retries today and should stop trying."
 - **No automatic Sidekiq integration.** When `RateLimitError` raises, it's
-  up to your job to re-enqueue using the `retry_after` value. XeroKiwi exposes
+  up to your job to re-enqueue using the `retry_after` value. Xero Kiwi exposes
   it; what you do with it is your call.

data/docs/throttling.md

@@ -0,0 +1,183 @@
+# Proactive throttling
+
+Xero Kiwi's retry middleware (see
+[retries-and-rate-limits.md](retries-and-rate-limits.md)) handles 429s *after*
+they happen — it honours `Retry-After` and backs off. That's fine when calls
+are infrequent, but Xero treats *hitting* the rate limit as a misbehaviour
+signal, and multi-worker setups (e.g. several Sidekiq processes syncing the
+same tenant) regularly trip it.
+
+The throttle layer is the other half of the story: block *before* the request
+goes out so you rarely hit 429 in the first place. It's **opt-in** — omit
+the `throttle:` kwarg and behaviour is identical to previous versions.
+
+## When to reach for this
+
+Wire up a limiter if:
+
+- Multiple processes or workers can call Xero for the same tenant concurrently.
+- You see sporadic 429s under normal load (not just traffic spikes).
+- You want predictable pacing rather than "fire everything, react to 429s."
+
+Skip it if you have a single-process, single-worker caller. The retry layer is
+enough.
+
+## Quick start
+
+```ruby
+require "redis"
+
+throttle = XeroKiwi::Throttle::RedisTokenBucket.new(
+  redis:      Redis.new(url: ENV["REDIS_URL"]),
+  per_minute: 55,      # Xero's default is 60. Leave a bit of headroom.
+  per_day:    4_900,   # optional. Xero's default is 5,000.
+  max_wait:   30.0     # cap on how long we'll block for a per-minute token.
+)
+
+client = XeroKiwi::Client.new(
+  access_token: access_token,
+  throttle:     throttle
+)
+
+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.
+
+## How it works
+
+A token bucket per tenant, stored as a Redis hash. Each call to Xero consumes
+a token; tokens refill at `capacity / window` per millisecond. All of the
+read-modify-write runs inside a Lua script, so two workers racing on the same
+bucket can't both spend the same token.
+
+The middleware reads `Xero-Tenant-Id` from the outgoing request and asks the
+limiter for a token before the HTTP call goes out. Untenanted requests
+(`/connections`, OAuth endpoints) bypass the middleware — they have no
+bucket.
+
+The middleware sits *below* the retry middleware in the Faraday stack, which
+means every retry attempt also consumes a token. So a burst of 429s doesn't
+starve other tenants' throughput.
+
+## Composing with the retry middleware
+
+Both layers stay on. They catch different failures:
+
+| Layer | Fires on | Action |
+|-------|----------|--------|
+| Throttle (proactive) | Your own bucket count | Sleep, then retry the acquire |
+| Retry (reactive) | A 429 that still slipped through | Honour `Retry-After` and retry the HTTP call |
+
+You can't just disable the retry layer once the throttle is in place:
+
+- Your bucket only models *your* calls to one tenant. The per-app 10k/min
+  limit is shared with anything else hitting the same Xero credentials.
+- Clock skew between Redis and Xero's own clock means your 60/min window
+  doesn't line up perfectly with theirs.
+- If Redis briefly fails, the limiter fails open (see below) — retry is the
+  safety net.
+
+## Choosing limits
+
+Pick values *below* Xero's defaults:
+
+| Xero limit | Headroom suggestion |
+|------------|---------------------|
+| 60 calls/min per tenant | `per_minute: 50` – `55` |
+| 5,000 calls/day per tenant | `per_day: 4,700` – `4,900` |
+
+The exact number depends on how much you care about the occasional 429 vs.
+maximising throughput. If your job batches run for hours, lean conservative —
+the daily limit resets on Xero's clock, not yours, and the first few
+minutes after "daily reset" can be ambiguous.
+
+## Per-minute vs per-day failure modes
+
+The two buckets fail differently on purpose.
+
+**Per-minute:** the limiter sleeps (up to `max_wait`) and retries. Short waits
+are normal and expected — a worker pausing 2 seconds to let the bucket refill
+is fine. If the wait would exceed `max_wait`, it raises
+`XeroKiwi::Throttle::Timeout`. Treat that as "something upstream is wrong" —
+probably too many concurrent workers for the configured `per_minute`.
+
+**Per-day:** the limiter raises `XeroKiwi::Throttle::DailyLimitExhausted`
+immediately, with a `retry_after` attribute in seconds. Sleeping for hours is
+never the right move in a Sidekiq worker, so the caller has to decide:
+
+```ruby
+begin
+  client.invoices(tenant_id)
+rescue XeroKiwi::Throttle::DailyLimitExhausted => e
+  # Re-enqueue the job for tomorrow. `retry_after` is seconds until the
+  # bucket has at least one token.
+  MyJob.perform_in(e.retry_after, org_id)
+end
+```
+
+This mirrors the `XeroKiwi::RateLimitError` shape that the retry layer raises
+after exhausting retries on a 429, so the handling code is familiar.
+
+## Redis key layout
+
+Buckets live under a namespace (`xero_kiwi:throttle` by default):
+
+```
+xero_kiwi:throttle:<tenant_id>:minute
+xero_kiwi:throttle:<tenant_id>:day
+```
+
+Each key is a Redis hash with `tokens` (float) and `last_refill_ms`. Keys
+carry a `PEXPIRE` of `2 × window` so stale tenants clean themselves up.
+
+Override the namespace with `namespace:` if you're sharing a Redis with other
+rate-limiter traffic:
+
+```ruby
+XeroKiwi::Throttle::RedisTokenBucket.new(
+  redis:      Redis.new,
+  per_minute: 55,
+  namespace:  "myapp:xero"
+)
+```
+
+## What happens if Redis is down
+
+The limiter fails open. If Redis raises (connection refused, timeout), the
+limiter logs a warning via `Kernel.warn` and returns immediately so the
+request still goes out. The retry middleware will still catch any 429s that
+result.
+
+Pass a `logger:` to route warnings somewhere useful:
+
+```ruby
+XeroKiwi::Throttle::RedisTokenBucket.new(
+  redis:      Redis.new,
+  per_minute: 55,
+  logger:     Rails.logger
+)
+```
+
+Fail-open is deliberate: a misbehaving Redis shouldn't stop your app talking
+to Xero. The reactive retry layer still protects you from actually hitting
+the limits.
+
+## Writing a custom limiter
+
+The limiter contract is one method:
+
+```ruby
+class MyLimiter
+  def acquire(tenant_id)
+    # Block until a token is available for this tenant, or raise
+    # XeroKiwi::Throttle::Timeout / DailyLimitExhausted if you want the
+    # same exception shapes.
+  end
+end
+```
+
+Pass any object implementing it as `throttle:`. The built-in
+`XeroKiwi::Throttle::NullLimiter` is a no-op default — it's what runs when
+`throttle:` is omitted.

data/docs/tokens.md

@@ -1,6 +1,6 @@
 # Tokens
 
-This doc covers everything about token *state* in XeroKiwi: the `XeroKiwi::Token`
+This doc covers everything about token *state* in Xero Kiwi: the `XeroKiwi::Token`
 value object, how the client refreshes tokens automatically, the persistence
 callback, manual refresh, revocation, and the gotchas around token rotation.
 
@@ -77,7 +77,7 @@ The `now:` keyword arg lets you inject a fixed time for testing.
 ### Why `expired?` returns false on nil `expires_at`
 
 If you don't know when the token expires (e.g. you loaded a credential from
-storage that was created before you tracked expiry), XeroKiwi treats it as
+storage that was created before you tracked expiry), Xero Kiwi treats it as
 "unknown" and assumes valid. The fallback is reactive — your first 401 will
 trigger a refresh.
 
@@ -163,7 +163,7 @@ token and fail.
 ### Persistence patterns
 
 Different applications store credentials differently. The callback works the
-same in all of them — XeroKiwi just hands you the new token and trusts you to
+same in all of them — Xero Kiwi just hands you the new token and trusts you to
 put it somewhere:
 
 ```ruby
@@ -200,7 +200,7 @@ integrations:
 > and gets `invalid_grant`. From Worker B's perspective, the credential
 > looks dead — but it's not, A just rotated it.
 
-XeroKiwi mitigates this in two ways:
+Xero Kiwi mitigates this in two ways:
 
 1. **Single-process safety.** A `Mutex` around refresh, with a double-check
    inside, prevents multiple threads in the *same process* from racing.
@@ -253,7 +253,7 @@ Use Redis (or Postgres advisory locks, etc.) to take a distributed lock
 keyed by credential ID before refreshing. Slower but more robust than
 Option B.
 
-XeroKiwi doesn't ship any of these — they're application-level decisions that
+Xero Kiwi doesn't ship any of these — they're application-level decisions that
 depend on your infrastructure. But the existence of `client.token.refreshable?`
 and the explicit `XeroKiwi::TokenRefreshError` give you the building blocks.
 
@@ -279,7 +279,7 @@ This:
 
 After revocation, **treat the client as dead.** Subsequent API calls will
 401, and reactive refresh will fail because the refresh token is gone too.
-XeroKiwi doesn't set an internal flag on the client — there's no
+Xero Kiwi doesn't set an internal flag on the client — there's no
 `client.revoked?` predicate — because the right thing for a caller to do
 post-revocation is throw the client away, not keep using it.
 
@@ -307,7 +307,7 @@ Xero accepts both. **But** revoking the access token only kills that one
 access token — the refresh token stays alive and can mint a new one
 immediately. Revoking the refresh token invalidates the entire chain.
 
-XeroKiwi enforces the refresh-token path: `Client#revoke_token!` raises if you
+Xero Kiwi enforces the refresh-token path: `Client#revoke_token!` raises if you
 don't have a refresh token, rather than silently revoking the access token
 (which would do almost nothing useful). This avoids a foot-gun where users
 think they've logged out but the token is still happily working.
@@ -334,6 +334,6 @@ log the full hash.
   full hash, which works for "is this the same token?" but isn't a security
   check. Don't use it for authentication.
 - **No JWT decoding of the access token.** Xero's access tokens are JWTs,
-  but XeroKiwi doesn't peek at their contents. The `id_token` is the OIDC
+  but Xero Kiwi doesn't peek at their contents. The `id_token` is the OIDC
   identity assertion you should care about; see [OAuth](oauth.md#id-token-verification)
   for verifying it.

data/lib/xero-kiwi.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "xero_kiwi"

data/lib/xero_kiwi/client.rb

@@ -62,7 +62,8 @@ module XeroKiwi
       on_token_refresh: nil,
       adapter: nil,
       user_agent: DEFAULT_USER_AGENT,
-      retry_options: {}
+      retry_options: {},
+      throttle: nil
     )
       @token            = Token.new(
         access_token:  access_token,
@@ -75,6 +76,7 @@ module XeroKiwi
       @adapter          = adapter
       @user_agent       = user_agent
       @retry_options    = DEFAULT_RETRY_OPTIONS.merge(retry_options)
+      @throttle         = throttle || Throttle::NullLimiter.new
       @refresh_mutex    = Mutex.new
     end
 
@@ -522,8 +524,10 @@ module XeroKiwi
     #      a XeroKiwi exception, *after* retries have been exhausted.
     #   2. Retry — retries on 429/503 (respecting Retry-After) and on transport
     #      exceptions.
-    #   3. JSON — parses the response body so handlers downstream get a Hash.
-    #   4. Adapter — actually makes the HTTP call.
+    #   3. Throttle — blocks before each attempt until a per-tenant token is
+    #      available. Below Retry so every retry also consumes a token.
+    #   4. JSON — parses the response body so handlers downstream get a Hash.
+    #   5. Adapter — actually makes the HTTP call.
     #
     # Putting ResponseHandler outside Retry is the key trick: it means a 429
     # gets retried by Faraday before we ever raise RateLimitError, and the
@@ -532,6 +536,7 @@ module XeroKiwi
       Faraday.new(url: BASE_URL) do |f|
         f.use ResponseHandler
         f.request :retry, @retry_options
+        f.use Throttle::Middleware, @throttle
         f.response :json, content_type: /\bjson/
         f.adapter(@adapter || Faraday.default_adapter)
 

data/lib/xero_kiwi/throttle/middleware.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module XeroKiwi
+  module Throttle
+    # Faraday request middleware. On every outbound call it reads the
+    # `Xero-Tenant-Id` header and asks the limiter for a token. Requests
+    # without a tenant header (e.g. `/connections`, OAuth endpoints) pass
+    # straight through — they have no tenant bucket to check.
+    #
+    # Placement matters: this sits *below* faraday-retry in the stack, so
+    # every retry attempt also re-enters the limiter and consumes a token.
+    class Middleware < Faraday::Middleware
+      TENANT_HEADER = "Xero-Tenant-Id"
+
+      def initialize(app, limiter)
+        super(app)
+        @limiter = limiter
+      end
+
+      def on_request(env)
+        tenant_id = env.request_headers[TENANT_HEADER]
+        return if tenant_id.nil? || tenant_id.empty?
+
+        @limiter.acquire(tenant_id)
+      end
+    end
+  end
+end

data/lib/xero_kiwi/throttle/null_limiter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module XeroKiwi
+  module Throttle
+    # Default limiter when no `throttle:` is passed to Client.new. Does nothing
+    # — preserves the pre-throttle behaviour where calls go straight out and
+    # the retry middleware reacts to any 429s that come back.
+    #
+    # Also documents the limiter contract: any object implementing
+    # `#acquire(key)` can be passed as `throttle:`.
+    class NullLimiter
+      def acquire(_key)
+        nil
+      end
+    end
+  end
+end

data/lib/xero_kiwi/throttle/redis_token_bucket.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "digest"
+require "redis"
+
+module XeroKiwi
+  module Throttle
+    # Redis-backed token bucket, keyed per tenant. One Ruby instance is shared
+    # across threads and (via Redis) across processes, so N Sidekiq workers
+    # hitting the same Xero tenant cooperatively share a bucket.
+    #
+    # Two buckets per tenant — minute and (optionally) day — modelled as Redis
+    # hashes with `tokens` and `last_refill_ms` fields. All bucket math runs
+    # inside a Lua script so the read-modify-write is atomic server-side; doing
+    # it in Ruby with separate GET/SET calls would race and leak tokens.
+    #
+    #   bucket = XeroKiwi::Throttle::RedisTokenBucket.new(
+    #     redis:      Redis.new,
+    #     per_minute: 55,        # Xero's default is 60; leave headroom.
+    #     per_day:    4_900,     # optional. Xero's default is 5,000.
+    #     max_wait:   30.0       # cap on how long acquire may block.
+    #   )
+    class RedisTokenBucket
+      DEFAULT_NAMESPACE = "xero_kiwi:throttle"
+      MINUTE_MS         = 60_000
+      DAY_MS            = 86_400_000
+      # Extra ms we sleep past a refill-time hint to avoid a busy loop.
+      POLL_MS           = 1_000
+
+      # Lua script. Input ARGV: now_ms, capacities... (minute, day?), window_ms... (minute, day?).
+      # KEYS: bucket hash keys in the same order as capacities.
+      #
+      # Returns: { failed_bucket_index, wait_ms }
+      #   {0, 0} = granted everywhere (decrements committed)
+      #   {i, N} = bucket i (1-indexed) is empty; no decrements committed; wait N ms for it
+      #
+      # Granting is all-or-nothing across buckets: if any bucket is empty we
+      # roll back, so a day-limit failure doesn't burn a minute token.
+      LUA_SCRIPT = <<~LUA
+        local now_ms = tonumber(ARGV[1])
+        local n = #KEYS
+        local new_tokens = {}
+
+        for i = 1, n do
+          local capacity  = tonumber(ARGV[1 + i])
+          local window_ms = tonumber(ARGV[1 + n + i])
+          local refill_per_ms = capacity / window_ms
+
+          local data = redis.call("HMGET", KEYS[i], "tokens", "last_refill_ms")
+          local tokens         = tonumber(data[1]) or capacity
+          local last_refill_ms = tonumber(data[2]) or now_ms
+
+          local elapsed = now_ms - last_refill_ms
+          if elapsed < 0 then elapsed = 0 end
+          tokens = math.min(capacity, tokens + elapsed * refill_per_ms)
+
+          if tokens < 1 then
+            local shortfall = 1 - tokens
+            local wait_ms = math.ceil(shortfall / refill_per_ms)
+            return { i, wait_ms }
+          end
+
+          new_tokens[i] = tokens - 1
+        end
+
+        for i = 1, n do
+          local window_ms = tonumber(ARGV[1 + n + i])
+          redis.call("HSET", KEYS[i], "tokens", new_tokens[i], "last_refill_ms", now_ms)
+          redis.call("PEXPIRE", KEYS[i], window_ms * 2)
+        end
+
+        return { 0, 0 }
+      LUA
+
+      LUA_SHA = Digest::SHA1.hexdigest(LUA_SCRIPT)
+
+      DEFAULT_CLOCK   = -> { (Process.clock_gettime(Process::CLOCK_REALTIME) * 1000).to_i }
+      DEFAULT_SLEEPER = ->(seconds) { Kernel.sleep(seconds) }
+
+      def initialize(redis:, per_minute:, per_day: nil, namespace: DEFAULT_NAMESPACE,
+                     max_wait: 30.0, logger: nil, clock: DEFAULT_CLOCK, sleeper: DEFAULT_SLEEPER)
+        raise ArgumentError, "per_minute must be > 0" unless per_minute.to_i.positive?
+        raise ArgumentError, "per_day must be > 0 when given" if per_day && !per_day.to_i.positive?
+
+        @redis      = redis
+        @per_minute = per_minute.to_i
+        @per_day    = per_day&.to_i
+        @namespace  = namespace
+        @max_wait   = max_wait.to_f
+        @logger     = logger
+        @clock      = clock
+        @sleeper    = sleeper
+      end
+
+      # Blocks until a token is available in every configured bucket. Fails
+      # open on Redis errors (logs and returns) so a dead Redis can't stop
+      # the app — the reactive retry layer still catches any resulting 429s.
+      def acquire(key)
+        raise ArgumentError, "key is required" if key.nil? || key.to_s.empty?
+
+        waited_ms = 0
+
+        loop do
+          failed, wait_ms = evaluate(key)
+          return if failed.zero?
+
+          waited_ms = handle_failure(failed, wait_ms, waited_ms)
+        end
+      rescue Redis::BaseError => e
+        log_redis_failure(e)
+        nil
+      end
+
+      private
+
+      def handle_failure(failed, wait_ms, waited_ms)
+        case failed
+        when 1 then wait_for_minute_bucket(wait_ms, waited_ms)
+        when 2 then raise Throttle::DailyLimitExhausted.new(retry_after: wait_ms / 1000.0)
+        end
+      end
+
+      def wait_for_minute_bucket(wait_ms, waited_ms)
+        if (waited_ms + wait_ms) / 1000.0 > @max_wait
+          raise Throttle::Timeout,
+                "waited #{(waited_ms / 1000.0).round(2)}s for rate-limit token, exceeds max_wait=#{@max_wait}s"
+        end
+
+        @sleeper.call((wait_ms + POLL_MS) / 1000.0)
+        waited_ms + wait_ms + POLL_MS
+      end
+
+      def evaluate(key)
+        keys, capacities, windows = bucket_args(key)
+        argv                      = [@clock.call, *capacities, *windows]
+
+        begin
+          @redis.evalsha(LUA_SHA, keys: keys, argv: argv)
+        rescue Redis::CommandError => e
+          raise unless e.message.include?("NOSCRIPT")
+
+          @redis.eval(LUA_SCRIPT, keys: keys, argv: argv)
+        end
+      end
+
+      def bucket_args(key)
+        keys       = ["#{@namespace}:#{key}:minute"]
+        capacities = [@per_minute]
+        windows    = [MINUTE_MS]
+
+        if @per_day
+          keys       << "#{@namespace}:#{key}:day"
+          capacities << @per_day
+          windows    << DAY_MS
+        end
+
+        [keys, capacities, windows]
+      end
+
+      def log_redis_failure(error)
+        message = "[xero-kiwi] throttle limiter Redis error (failing open): #{error.class}: #{error.message}"
+        if @logger
+          @logger.warn(message)
+        else
+          Kernel.warn(message)
+        end
+      end
+    end
+  end
+end

data/lib/xero_kiwi/throttle.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module XeroKiwi
+  # Proactive rate-limit coordination for multi-process callers hitting the
+  # same Xero tenant. The retry middleware in Client handles reactive 429s;
+  # this module blocks *before* a request goes out so 429s become rare.
+  #
+  # See docs/throttling.md for the full story.
+  module Throttle
+    class Error < XeroKiwi::Error; end
+
+    # Raised when the per-minute bucket is empty and the caller has already
+    # waited longer than the limiter's configured max_wait. The right fix is
+    # usually to slow the caller down or raise headroom; swallowing this
+    # quietly tends to hide the problem.
+    class Timeout < Error; end
+
+    # Raised immediately (no sleep) when the per-day bucket is exhausted. The
+    # wait until reset is typically measured in hours, so blocking the caller
+    # is the wrong move — re-enqueue the job at `retry_after` instead. Shape
+    # mirrors RateLimitError so existing Xero rate-limit handling applies.
+    class DailyLimitExhausted < Error
+      attr_reader :retry_after
+
+      def initialize(retry_after:)
+        @retry_after = retry_after
+        super("Xero daily rate limit exhausted; retry in #{retry_after.round}s")
+      end
+    end
+  end
+end
+
+require_relative "throttle/null_limiter"
+require_relative "throttle/redis_token_bucket"
+require_relative "throttle/middleware"

data/lib/xero_kiwi/version.rb

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

data/lib/xero_kiwi.rb

@@ -22,6 +22,7 @@ require_relative "xero_kiwi/accounting/invoice"
 require_relative "xero_kiwi/accounting/allocation"
 require_relative "xero_kiwi/accounting/user"
 require_relative "xero_kiwi/accounting/branding_theme"
+require_relative "xero_kiwi/throttle"
 require_relative "xero_kiwi/client"
 require_relative "xero_kiwi/identity"
 require_relative "xero_kiwi/token_refresher"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xero-kiwi
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Douglas Greyling
@@ -65,7 +65,21 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
-description: XeroKiwi handles the unglamorous parts of integrating with Xero — OAuth2
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Xero Kiwi handles the unglamorous parts of integrating with Xero — OAuth2
   with PKCE, automatic token refresh, rate-limit-aware retries, and typed value objects
   for accounting resources — so your code can focus on the business problem rather
   than the plumbing.
@@ -80,6 +94,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docker-compose.yml
 - docs/accounting/address.md
 - docs/accounting/branding-theme.md
 - docs/accounting/contact-group.md
@@ -100,7 +115,9 @@ files:
 - docs/getting-started.md
 - docs/oauth.md
 - docs/retries-and-rate-limits.md
+- docs/throttling.md
 - docs/tokens.md
+- lib/xero-kiwi.rb
 - lib/xero_kiwi.rb
 - lib/xero_kiwi/accounting/address.rb
 - lib/xero_kiwi/accounting/allocation.rb
@@ -127,6 +144,10 @@ files:
 - lib/xero_kiwi/oauth.rb
 - lib/xero_kiwi/oauth/id_token.rb
 - lib/xero_kiwi/oauth/pkce.rb
+- lib/xero_kiwi/throttle.rb
+- lib/xero_kiwi/throttle/middleware.rb
+- lib/xero_kiwi/throttle/null_limiter.rb
+- lib/xero_kiwi/throttle/redis_token_bucket.rb
 - lib/xero_kiwi/token.rb
 - lib/xero_kiwi/token_refresher.rb
 - lib/xero_kiwi/version.rb