twitch_oauth2 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db75a943539bebe359931ac1b78fd29b6d55add3922c1dd56c3ff457c190ebbd
-  data.tar.gz: d171153225fac0312176a923848b6c9f3be048946e23fbec72f5b7413801665d
+  metadata.gz: 723edb026a4d7f2d80c2689f2b29f97d94eb4089714f0b73fecbc29328fa1ff0
+  data.tar.gz: 95d95090fe825074a893525db1191e1764736fc0f3c431b74837ce59aee8ad7a
 SHA512:
-  metadata.gz: 0d191956b126deec94d160e85af9d147ac1e920db8b5031d68602c6459bb2c172a8025b5205be596d32fb8b1f2040c29f401afb533853ac2f2e813899b36d276
-  data.tar.gz: 75625c8ef174b8115ae4b6fdac56d3fd6e9ab6239854b92619f3e04c978a3ef252bf5255a87ae3685a389f203365739d705a9d588f47f3cb4597c09685b00d38
+  metadata.gz: 4ca9e069fef10a36f1cbe922c52bfdba5a091afc13c8356219361c5475129ccc23e56cdd37f626b4b036bf7134a2b61a218ac6fe7d290520b3d142c6728d820d
+  data.tar.gz: 96543dd82cd0f3eeb646a3e0ae55c21df4d702cc37f6a8d308a62fbe345b5135e6be2865d8a1afe5deff281d0f40235e694f99f90a076c905e68335b277262c2

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.5.0 (2023-07-25)
+
+*   Introduce `Tokens` object.
+    It stores access and refresh tokens, also calls `client` for interactions with them,
+    like refreshing.
+    This approach allows to share this object with the same tokens between different libraries
+    and storing (and refreshing) tokens in (temporary, secret) file.
+*   Add Ruby 3.2 to CI.
+*   Drop Ruby 2.6 support.
+*   Update development dependencies.
+*   Improve CI.
+
 ## 0.4.0 (2022-07-23)
 
 *   Support Ruby 3.

data/README.md

@@ -35,70 +35,97 @@ gem install twitch_oauth2
 
 ## Usage
 
+Since version `0.5.0`, the main object here is `TwitchOAuth2::Tokens` which receives
+and internally uses `client` for necessary requests. This approach allows:
+
+*   get an actual `access_token` with validations, refreshing and other things inside;
+*   share and reuse an instance of this class, for example between API and IRC clients;
+*   initialize 2 instances for user token and application token, but with the same `client` object.
+
 ### Initialization
 
+Client, for requests:
+
 ```ruby
 require 'twitch_oauth2'
 
 client = TwitchOAuth2::Client.new(
   client_id: 'application_client_id',
   client_secret: 'application_client_secret',
-  scopes: %w[user:read:email bits:read] # default is `nil`
   redirect_uri: 'application_redirect_uri' # default is `http://localhost`
 )
 ```
 
-### Check tokens
+Tokens, for their storage and refreshing:
 
 ```ruby
-tokens = previously_saved_tokens
-# => { access_token: 'abcdef', refresh_token: 'ghikjl' }
-# Can be empty.
-
-client.check_tokens **tokens, token_type: :user
+tokens = TwitchOAuth2::Tokens.new(
+  client: client, # initialized above, or can be a `Hash` with values for `Client` initialization
+  # all other arguments are optional
+  access_token: 'somewhere_received_access_token', # default is `nil`
+  refresh_token: 'refresh_token_from_the_same_place', # default is `nil`
+  token_type: :user, # default is `:application`
+  scopes: %w[user:read:email bits:read] # default is `nil`, but it's not so useful
+)
 ```
 
-`:token_type` is optional and is `:application` by default,
-but a number of available API end-points is limited in this case.
+### Check tokens
 
-Also, Application Access Token has no `refresh_token`, but this gem just receive a new one
-if a given one is invalid.
+Please, use `Tokens#valid?` method after initialization, especially for empty initial tokens,
+especially for User Access Token.
 
-#### The first run
+If method returned `false` — direct user to `tokens#authorize_link`.
 
-You can pass nothing to `#check_tokens`, then client will generate new ones.
+For a web-application with N users, you can use `:redirect_uri` argument for `Client`
+initialization as your application callback and redirect them to `#authorize_link`.
 
-If you've specified `:token_type` as `:application` or have not specify it at all (default),
-there will be an Application Access Token (without refresh token).
+For something like a CLI tool you can print instructions for user with received link.
 
-Otherwise, for User Access Token here will be raised a `TwitchOAuth2::Error` with Twitch link
-inside `#metadata[:link]`.
+#### Application Access Token
 
-If you have a web-application with N users, you can redirect them to this link
-and use `redirect_uri` to your application for callbacks.
+It's simpler, has less permissions, and it's the default `:token_type`.
 
-Otherwise, if you have something like CLI tool, you can print instructions with a link for user.
+Application Access Tokens have no `refresh_token` right now and have longer life time,
+so the logic here is simpler: you can pass nothing to `Tokens.new` — the client will generate
+new `access_token`, and regenerate when it's will be outdated.
 
-Then you can use `#token(token_type: :user, code: 'a code from params in redirect uri')`
-and get your `:access_token` and `:refresh_token`.
+#### User Access Token
 
-#### Reusing tokens
+If you need for `:user` token and you have no actual `access_token` or `refresh_token`
+(checkable by `Tokens#valid?`), **you have to direct user** to `tokens#authorize_link`.
 
-Then, if you pass tokens, client will validate them and return themselves
-or refresh and return new ones.
+After successful user login there will be redirect from Twitch to the `:redirect_uri`
+(by default is `localhost`) with the `code` query argument.
+**You have to pass it** to the `Tokens#code=` for `access_token` and `refresh_token` generation,
+they will be available right after it.
 
-### Explicitly refresh tokens
+It's one-time manual operation for User Access Token, further the gem will give you actual tokens
+and refresh them as necessary (right now `refresh_token`, getting after `code`, has no life time).
 
-You can refresh tokens manually:
+Without checking tokens the `TwitchOAuth2::AuthorizeError` will be raised on `#access_token` call,
+and it can interrupt some operations, like API library initialization.
 
-```ruby
-client.refreshed_tokens refresh_token: 'ghikjl'
-```
+The reference for such behavior is [the official Google API gem](https://github.com/googleapis/google-api-ruby-client/blob/39ae3527722a003b389a2f7f5275ab9c6e93bb5e/samples/cli/lib/base_cli.rb`).
+
+Another reference, [`twitch` package for JavaScript](https://d-fischer.github.io/twitch/),
+has refreshing logic, but [requires initial correct tokens from you](https://d-fischer.github.io/twitch-chat-client/docs/examples/basic-bot.html),
+and doesn't care how you'll get them.
+
+
+### Get tokens
+
+The main method is `Tokens#access_token`: it's used in API libraries, in chat libraries, etc.
 
-This is used internally in `#check_tokens`, and can be used separately
-for failed requests to API.
+It has refreshing logic inside for cases when it's outdated.
+But if there is no initial `refresh_token` — be aware and read the documentation below.
 
-And, because Application Access Tokens have no refresh tokens — this method will not work for them.
+There is also `#refresh_token` getter, just for storing it or something else,
+it's more important internally.
+
+#### Reusing tokens
+
+Then, or if you pass tokens to initialization, client will validate them and return themselves
+or refresh and return new ones.
 
 ## Development
 

data/lib/twitch_oauth2/authorize_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TwitchOAuth2
+	## Error for `#authorize_link`
+	class AuthorizeError < Error
+		attr_reader :link
+
+		def initialize(link)
+			@link = link
+			super 'Direct user to `error.link` and assign `code`'
+		end
+	end
+end

data/lib/twitch_oauth2/client.rb

@@ -19,31 +19,27 @@ module TwitchOAuth2
 				parser_options: { symbolize_names: true }
 		end.freeze
 
-		def initialize(
-			client_id:, client_secret:, redirect_uri: 'http://localhost', scopes: nil
-		)
+		attr_reader :client_id
+
+		def initialize(client_id:, client_secret:, redirect_uri: 'http://localhost')
 			@client_id = client_id
 			@client_secret = client_secret
 			@redirect_uri = redirect_uri
-			@scopes = scopes
 		end
 
-		def check_tokens(access_token: nil, refresh_token: nil, token_type: :user)
-			if access_token
-				validate_result = validate access_token: access_token
-
-				if validate_result[:status] == 401
-					return refreshed_tokens(refresh_token: refresh_token) if token_type == :user
-				elsif validate_result[:expires_in].positive?
-					return { access_token: access_token, refresh_token: refresh_token }
-				end
-			end
+		def authorize(scopes:)
+			response = CONNECTION.get(
+				'authorize',
+				client_id: @client_id,
+				redirect_uri: @redirect_uri,
+				scope: Array(scopes).join(' '),
+				response_type: :code
+			)
 
-			flow token_type: token_type
-		end
+			location = response.headers[:location]
+			return location if location
 
-		def refreshed_tokens(refresh_token:)
-			refresh(refresh_token: refresh_token).slice(:access_token, :refresh_token)
+			raise Error, response.body[:message]
 		end
 
 		def token(token_type:, code: nil)
@@ -61,39 +57,6 @@ module TwitchOAuth2
 			raise Error, response.body[:message]
 		end
 
-		private
-
-		def flow(token_type:)
-			if token_type == :user
-				raise Error.new('Use `error.metadata[:link]` for getting new tokens', link: authorize)
-			end
-
-			token(token_type: token_type).slice(:access_token, :refresh_token)
-		end
-
-		def authorize
-			response = CONNECTION.get(
-				'authorize',
-				client_id: @client_id,
-				redirect_uri: @redirect_uri,
-				scope: Array(@scopes).join(' '),
-				response_type: :code
-			)
-
-			location = response.headers[:location]
-			return location if location
-
-			raise Error, response.body[:message]
-		end
-
-		def grant_type_by_token_type(token_type)
-			case token_type
-			when :user then :authorization_code
-			when :application then :client_credentials
-			else raise Error, 'unsupported token type'
-			end
-		end
-
 		def validate(access_token:)
 			response = CONNECTION.get(
 				'validate', {}, { 'Authorization' => "OAuth #{access_token}" }
@@ -115,5 +78,15 @@ module TwitchOAuth2
 
 			raise Error, response.body[:message]
 		end
+
+		private
+
+		def grant_type_by_token_type(token_type)
+			case token_type
+			when :user then :authorization_code
+			when :application then :client_credentials
+			else raise UnsupportedTokenTypeError, token_type
+			end
+		end
 	end
 end

data/lib/twitch_oauth2/error.rb

@@ -3,12 +3,5 @@
 module TwitchOAuth2
 	## Error during Twitch OAuth2 operations
 	class Error < StandardError
-		attr_reader :metadata
-
-		def initialize(message, metadata = {})
-			super message
-
-			@metadata = metadata
-		end
 	end
 end

data/lib/twitch_oauth2/tokens.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'authorize_error'
+
+module TwitchOAuth2
+	## Class for tokens and their refreshing, using provided client
+	class Tokens
+		## `refresh_token` for `on_update`, but it can be better to make getter with logic
+		## like for `access_token`, but there can be troubles:
+		## * right now `refresh_token` is kind of constant, but it can have TTL in the future;
+		## * right now there is no `refresh_token` for `:application` tokens, but it can appears
+		##   in the future.
+		attr_reader :client, :token_type, :refresh_token
+
+		## I don't know how to make it shorter
+		# rubocop:disable Metrics/ParameterLists
+		def initialize(
+			client:, access_token: nil, refresh_token: nil, token_type: :application, scopes: nil,
+			on_update: nil
+		)
+			# rubocop:enable Metrics/ParameterLists
+			@client = client.is_a?(Hash) ? Client.new(**client) : client
+			@access_token = access_token
+			@refresh_token = refresh_token
+			@token_type = token_type
+			@scopes = scopes
+			@on_update = on_update
+
+			@expires_at = nil
+		end
+
+		def valid?
+			if @access_token
+				validate_access_token if @expires_at.nil? || Time.now >= @expires_at
+			else
+				return false if @token_type == :user
+
+				request_new_tokens
+			end
+
+			true
+		end
+
+		def authorize_link
+			@client.authorize(scopes: @scopes)
+		end
+
+		def access_token
+			raise AuthorizeError, authorize_link if !valid? && @token_type == :user
+
+			@access_token
+		end
+
+		def code=(value)
+			assign_tokens @client.token(token_type: @token_type, code: value)
+		end
+
+		private
+
+		def validate_access_token
+			validate_result = @client.validate access_token: @access_token
+
+			if validate_result[:status] == 401
+				refresh_tokens
+			elsif (expires_in = validate_result[:expires_in]).positive?
+				@expires_at = Time.now + expires_in
+			else
+				raise "Unexpected validate result: #{validate_result}"
+			end
+		end
+
+		def refresh_tokens
+			case @token_type
+			when :user
+				assign_tokens @client.refresh(refresh_token: @refresh_token)
+			when :application
+				request_new_tokens
+			else
+				raise UnsupportedTokenTypeError, @token_type
+			end
+		end
+
+		def request_new_tokens
+			assign_tokens @client.token(token_type: @token_type)
+		end
+
+		def assign_tokens(data)
+			@access_token = data[:access_token]
+			@refresh_token = data[:refresh_token]
+			@expires_at = Time.now + data[:expires_in]
+
+			@on_update&.call(self)
+		end
+	end
+end

data/lib/twitch_oauth2/unsupported_token_type_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TwitchOAuth2
+	## Error with `:token_type` recognition
+	class UnsupportedTokenTypeError < Error
+		def initialize(token_type)
+			super "Unsupported token type: `#{token_type}`"
+		end
+	end
+end

data/lib/twitch_oauth2/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TwitchOAuth2
-	VERSION = '0.4.0'
+	VERSION = '0.5.0'
 end

data/lib/twitch_oauth2.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'twitch_oauth2/client'
 require_relative 'twitch_oauth2/error'
+require_relative 'twitch_oauth2/unsupported_token_type_error'
+
+require_relative 'twitch_oauth2/client'
+require_relative 'twitch_oauth2/tokens'
+
 require_relative 'twitch_oauth2/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twitch_oauth2
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Alexander Popov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-23 00:00:00.000000000 Z
+date: 2023-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -38,160 +38,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.0
-- !ruby/object:Gem::Dependency
-  name: pry-byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: gem_toys
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.12.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.12.0
-- !ruby/object:Gem::Dependency
-  name: toys
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.13.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.13.0
-- !ruby/object:Gem::Dependency
-  name: codecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.6.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.6.0
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.21.2
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.21.2
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.32.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.32.0
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 description: |
   Twitch authentication with OAuth 2.
   Result tokens can be used for API libraries, chat libraries
@@ -206,8 +52,11 @@ files:
 - LICENSE.txt
 - README.md
 - lib/twitch_oauth2.rb
+- lib/twitch_oauth2/authorize_error.rb
 - lib/twitch_oauth2/client.rb
 - lib/twitch_oauth2/error.rb
+- lib/twitch_oauth2/tokens.rb
+- lib/twitch_oauth2/unsupported_token_type_error.rb
 - lib/twitch_oauth2/version.rb
 homepage: https://github.com/AlexWayfer/twitch_oauth2
 licenses:
@@ -225,7 +74,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
   - - "<"
     - !ruby/object:Gem::Version
       version: '4'
@@ -235,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.17
 signing_key:
 specification_version: 4
 summary: Twitch authentication with OAuth 2.