hcbv4 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0cb83ef3bb6adbedbad8e6671d7bacea19c0602c8f36672651484a8216e28b6
-  data.tar.gz: e5ea1d71c14fae2aaaad3966b27fb6ad3fcabf87b1871d09410584354e470ef0
+  metadata.gz: 769371ccfa3c68e1fb4e70af29889f49e19319c6c4d7152dea54ce56f462d7d4
+  data.tar.gz: 00d08d8cb7479e1004bc5a3eaacc87faad6ce1708d38f05d06c14066983fe830
 SHA512:
-  metadata.gz: 8409cb00d02bf2fad991c697157bdcaf3bca1f873beac81b1c96adc39b0bf4497f2071cc3a576da59f5696b6df51a4552b2ce112bb4e1c4273985d0324752844
-  data.tar.gz: d6268de4958175d1f6d9307c96fe131f018353c67fdb08701b83fd7b33260db23858e7795994c6afcbdf6195369a854308ca33523c4e01a1acfbee4bc5b9a2fc
+  metadata.gz: 8b2df71c8f293d0988a18fdb97ac180b756e3d06e196e0314275e458255fb79fd9bbb88124544c43b3792e9c2a1345e49a9a9ea42649f1a17a250952a95cfa13
+  data.tar.gz: ed0641418b2cf847ba8396f22ca860373c3cb04d05f6110cda7f7d73348a54d9f3de54704cb7121982ed6772046e46e3f3decb247be19fb463e31b98c821f836

data/README.md

@@ -30,17 +30,43 @@ client = HCBV4::Client.from_credentials(
 )
 ```
 
-the client automatically refreshes expired tokens before each request. after any API call, you can grab the (possibly refreshed) tokens to persist them:
+the client automatically refreshes expired tokens before each request. to persist refreshed tokens, use the `on_token_refresh` callback:
 
 ```ruby
-token = client.oauth_token
-save_to_database(
-  access_token: token.token,
-  refresh_token: token.refresh_token,
-  expires_at: token.expires_at
+client = HCBV4::Client.from_credentials(
+  client_id: ENV["HCB_CLIENT_ID"],
+  client_secret: ENV["HCB_CLIENT_SECRET"],
+  access_token: user.hcb_access_token,
+  refresh_token: user.hcb_refresh_token,
+  expires_at: user.hcb_token_expires_at,
+  on_token_refresh: ->(token) {
+    user.update!(
+      hcb_access_token: token.token,
+      hcb_refresh_token: token.refresh_token,
+      hcb_token_expires_at: token.expires_at
+    )
+  }
 )
 ```
 
+the callback is invoked immediately after a token refresh, before the API request is made. this ensures your stored tokens are always up to date.
+
+### disabling automatic token refresh
+
+if you're managing token refresh yourself, you can disable automatic refresh:
+
+```ruby
+client = HCBV4::Client.from_credentials(
+  client_id: ENV["HCB_CLIENT_ID"],
+  client_secret: ENV["HCB_CLIENT_SECRET"],
+  access_token: "...",
+  refresh_token: "...",
+  auto_token_refresh: false
+)
+```
+
+the `auto_token_refresh` option defaults to `true`.
+
 ### using a pre-built token
 
 if you're managing the `OAuth2::AccessToken` lifecycle yourself:
@@ -482,53 +508,6 @@ tx.update!(memo: "new memo")  # => Error: organization.id is nil
 
 ## recipes
 
-### token persistence
-
-the client automatically refreshes expired tokens. only persist when the token actually changes:
-
-```ruby
-class HCBService
-  def self.with(user, &block)
-    service = new(user)
-    block.call(service.client)
-  ensure
-    service.persist_if_refreshed!
-  end
-
-  def initialize(user)
-    @user = user
-    @original_token = user.hcb_access_token
-  end
-
-  def client
-    @client ||= HCBV4::Client.from_credentials(
-      client_id: ENV["HCB_CLIENT_ID"],
-      client_secret: ENV["HCB_CLIENT_SECRET"],
-      access_token: @user.hcb_access_token,
-      refresh_token: @user.hcb_refresh_token,
-      expires_at: @user.hcb_token_expires_at
-    )
-  end
-
-  def persist_if_refreshed!
-    return unless @client
-    token = @client.oauth_token
-    return if token.token == @original_token
-
-    @user.update!(
-      hcb_access_token: token.token,
-      hcb_refresh_token: token.refresh_token,
-      hcb_token_expires_at: token.expires_at
-    )
-  end
-end
-
-# usage:
-HCBService.with(current_user) do |client|
-  client.organizations
-end
-```
-
 ### keep your ledger pretty
 
 when a card grant is created, it generates a disbursement (transfer) from the org to the grant. you might want to label it:

data/lib/hcbv4/client.rb

@@ -9,20 +9,22 @@ module HCBV4
     DEFAULT_BASE_URL = "https://hcb.hackclub.com"
     API_PATH = "/api/v4"
 
-    attr_reader :oauth_token, :base_url
+    attr_reader :oauth_token, :base_url, :auto_token_refresh, :on_token_refresh
 
-    def initialize(oauth_token:, base_url: DEFAULT_BASE_URL)
+    def initialize(oauth_token:, base_url: DEFAULT_BASE_URL, auto_token_refresh: true, on_token_refresh: nil)
       @oauth_token = oauth_token
       @base_url = base_url
+      @auto_token_refresh = auto_token_refresh
+      @on_token_refresh = on_token_refresh
     end
 
     def self.from_credentials(client_id:, client_secret:, access_token:, refresh_token:, expires_at: nil,
-                              base_url: DEFAULT_BASE_URL)
+                              base_url: DEFAULT_BASE_URL, auto_token_refresh: true, on_token_refresh: nil)
       oauth_client = OAuth2::Client.new(
         client_id,
         client_secret,
         site: base_url,
-        token_url: "/oauth/token"
+        token_url: "/api/v4/oauth/token"
       )
 
       token = OAuth2::AccessToken.new(
@@ -32,7 +34,7 @@ module HCBV4
         expires_at:
       )
 
-      new(oauth_token: token, base_url:)
+      new(oauth_token: token, base_url:, auto_token_refresh:, on_token_refresh:)
     end
 
     # ─────────────────────────────────────────────────────────────────────────
@@ -558,10 +560,12 @@ module HCBV4
     end
 
     def refresh_token_if_needed!
+      return unless auto_token_refresh
       return unless oauth_token.respond_to?(:expired?)
       return unless oauth_token.expired?
 
       @oauth_token = oauth_token.refresh!
+      on_token_refresh&.call(@oauth_token)
     end
 
     def connection

data/lib/hcbv4/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hcbv4
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - 24c02