nb_api_client 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8a34771eec831f76ebbcab4057adab19e3ed2f0f18a7ea1fefdf4f6cb9c75c8
-  data.tar.gz: d9c17c3d66fe7250dcb06c267530feda1255841509724b6ac061137c1584ff47
+  metadata.gz: fa4a409cda310073f64e30372fd23444e3785ac0a84bf75ec9a328c4ede4ea27
+  data.tar.gz: 5c7eecae6437924564604c56128a7a41a4a152a649cb51b94905becdeec00f20
 SHA512:
-  metadata.gz: e2215188c41fa8820c2b6372cb94e29efabbdd98717b7806b107d8e0e28820daa137118a9de1dfab8e0ee2bb0e5fe4a2a848a9a2a3e56f98cab34a001ce0fff2
-  data.tar.gz: 957fafb9f78368eeff8e0a42e9b01b8e1f5c0cfc8d7112bbcfb2247a62f4fad70632536c290d0f5af147740cccc48dba5165a64a00d430dc06d430cd3d9f7f71
+  metadata.gz: 0732e459c9eddf51483e4718ea6b117a993db84b960bac2a2d2213fa30776fc1f576265e464c5cf9df5d44e7d1eb10ba6d2fef14a99d4edf99bfe274bdee28d9
+  data.tar.gz: 5958277d5e508c9b63f3c126e9ab5305a5f85a8100bc693d07b26f83f09f7639e62071a44e2cc6a2b9a7a2ff3bf29f1ff61e18b804494b8ee01f95ddf66795f5

data/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-07-16
+
+- Added `NbApiClient::OAuthTokenRefresh`, an optional mixin implementing
+  `refresh_oauth_token` for nations backed by an ActiveRecord-style model
+  (`token`/`refresh_token`/`token_expires_at` columns, `#with_lock`/
+  `#update!`). `include` it instead of writing your own; it POSTs to
+  NationBuilder's `/oauth/token` endpoint via HTTParty. Configured via new
+  `config.oauth_client_id`/`config.oauth_client_secret` (default from
+  `NB_CLIENT_ID`/`NB_CLIENT_SECRET` env vars).
+
 ## [1.0.0] - 2026-07-16
 
 - **Breaking:** Removed the `oauth2` gem dependency. `NbApiClient::Request` now

data/README.md

@@ -44,30 +44,17 @@ NbApiClient::Request.call(nation, :post, "/api/v2/signups", {
 | `refresh_oauth_token` | Refreshes the OAuth token in place; returns truthy on success, falsy on failure.                                                                                             |
 | `deauthorize`         | Called after too many consecutive "unauthorized" responses (see `unauthorized_error_threshold` below).                                                                       |
 
-A typical `refresh_oauth_token`, using the [`oauth2`](https://github.com/oauth-xx/oauth2) gem (a separate dependency of your app, not of this gem) and an ActiveRecord model with `token`, `refresh_token`, and `token_expires_at` columns:
+If your model is an ActiveRecord model with `token`, `refresh_token`, and `token_expires_at` columns and supports `#with_lock`/`#update!`, just include the gem's mixin instead of writing `refresh_oauth_token` yourself:
 
 ```ruby
-def refresh_oauth_token
-  with_lock do
-    # Re-check after acquiring the lock in case another process already
-    # refreshed the token while this one was waiting.
-    return true if updated_at > 5.seconds.ago
-
-    client = OAuth2::Client.new(ENV["NB_CLIENT_ID"], ENV["NB_CLIENT_SECRET"], site: "https://#{slug}.nationbuilder.com")
-    old_token = OAuth2::AccessToken.new(client, token, refresh_token: refresh_token)
-    new_token = old_token.refresh!
-
-    update!(token: new_token.token,
-      refresh_token: new_token.refresh_token,
-      token_expires_at: new_token.expires_at)
-  end
-rescue OAuth2::Error => e
-  Rails.logger.error("Failed to refresh OAuth token for #{slug}: #{e.message}")
-  false
+class Nation < ApplicationRecord
+  include NbApiClient::OAuthTokenRefresh
 end
 ```
 
-The `with_lock` (a `SELECT ... FOR UPDATE` row lock) and `updated_at` re-check guard against multiple concurrent requests for the same nation refreshing the token at once.
+It also needs `config.oauth_client_id`/`config.oauth_client_secret` set (below; default from `NB_CLIENT_ID`/`NB_CLIENT_SECRET` env vars). Internally it POSTs to NationBuilder's `/oauth/token` endpoint via HTTParty (no `oauth2` gem dependency), and uses `with_lock` plus an `updated_at` re-check to guard against multiple concurrent requests for the same nation refreshing the token at once.
+
+If your model doesn't fit that shape (different column names, no `with_lock`, non-ActiveRecord storage), write your own `refresh_oauth_token` instead — it just needs to return truthy on success, falsy on failure.
 
 ### Configuration
 
@@ -91,6 +78,11 @@ NbApiClient.configure do |config|
   config.unauthorized_error_threshold = 25
   config.unauthorized_error_window = 5 * 60
 
+  # Only needed if you include NbApiClient::OAuthTokenRefresh. Default from
+  # NB_CLIENT_ID/NB_CLIENT_SECRET env vars.
+  config.oauth_client_id = ENV["NB_CLIENT_ID"]
+  config.oauth_client_secret = ENV["NB_CLIENT_SECRET"]
+
   # Cache store used to count those unauthorized responses, and (below) to
   # back the sliding-window rate limiter. Defaults to Rails.cache; must
   # respond to #increment(key, amount, options), #decrement, and #read.

data/lib/nb_api_client/configuration.rb

@@ -30,6 +30,11 @@ module NbApiClient
     attr_accessor :max_rate_limit_retries
     attr_accessor :max_token_retries
 
+    # Client id/secret used by NbApiClient::OAuthTokenRefresh (only needed if
+    # you include that mixin instead of writing your own refresh_oauth_token).
+    attr_accessor :oauth_client_id
+    attr_accessor :oauth_client_secret
+
     # Sliding-window rate limit: at most `rate_limit` requests per `rate_limit_window_seconds`,
     # enforced across all processes via `cache_store` (above). If `cache_store` is nil,
     # rate limiting is disabled entirely.
@@ -48,6 +53,8 @@ module NbApiClient
       @short_circuit_in_test = true
       @max_rate_limit_retries = 3
       @max_token_retries = 2
+      @oauth_client_id = ENV["NB_CLIENT_ID"]
+      @oauth_client_secret = ENV["NB_CLIENT_SECRET"]
 
       @rate_limit = ENV.fetch("API_RATE_LIMIT", 200).to_i
       @rate_limit_window_seconds = ENV.fetch("API_RATE_WINDOW", 10).to_i

data/lib/nb_api_client/oauth_token_refresh.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module NbApiClient
+  # Optional mixin implementing `refresh_oauth_token` (see README's "nation
+  # interface") for nations backed by an ActiveRecord-style model with
+  # `token`, `refresh_token`, `token_expires_at` columns, and `#with_lock`/
+  # `#update!`. `include NbApiClient::OAuthTokenRefresh` instead of writing
+  # your own refresh_oauth_token; write your own if your model differs
+  # (no `with_lock`, different column names, etc).
+  module OAuthTokenRefresh
+    def refresh_oauth_token
+      with_lock do
+        # Re-check after acquiring the lock in case another process already
+        # refreshed the token while this one was waiting.
+        return true if Time.now - updated_at < 5
+
+        response = HTTParty.post(
+          "https://#{slug}.nationbuilder.com/oauth/token",
+          body: {
+            grant_type: "refresh_token",
+            refresh_token: refresh_token,
+            client_id: NbApiClient.configuration.oauth_client_id,
+            client_secret: NbApiClient.configuration.oauth_client_secret
+          }
+        )
+        return false unless response.success?
+
+        update!(
+          token: response["access_token"],
+          refresh_token: response["refresh_token"],
+          token_expires_at: response["expires_in"] ? Time.now + response["expires_in"].to_i : nil
+        )
+      end
+    rescue => e
+      NbApiClient.configuration.logger&.error("[NbApiClient::OAuthTokenRefresh] Failed to refresh OAuth token for #{slug}: #{e.message}")
+      false
+    end
+  end
+end

data/lib/nb_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NbApiClient
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/nb_api_client.rb

@@ -15,6 +15,7 @@ require_relative "nb_api_client/configuration"
 require_relative "nb_api_client/url_builder"
 require_relative "nb_api_client/rate_limiter"
 require_relative "nb_api_client/request"
+require_relative "nb_api_client/oauth_token_refresh"
 
 module NbApiClient
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nb_api_client
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Alex Flint
@@ -106,6 +106,7 @@ files:
 - README.md
 - lib/nb_api_client.rb
 - lib/nb_api_client/configuration.rb
+- lib/nb_api_client/oauth_token_refresh.rb
 - lib/nb_api_client/rate_limiter.rb
 - lib/nb_api_client/request.rb
 - lib/nb_api_client/url_builder.rb