mangadex 5.3.3.1 → 5.3.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdf99fecbef4c256aa1f0b739a7051d68f7f79a864f2525d7a56d5ee6a2cca79
-  data.tar.gz: 7250ded43bef9892e3d13323a1cea91c8f45378df330534f1a4f229575a1ebee
+  metadata.gz: 1d01b0fac553138d7ac86d1313737d86ba5415ee88e2ca6de08787402be7e3fb
+  data.tar.gz: 643923fe081fb046f6feec8ab4ce945a358a2fc9d66681d732a272b9bad2223d
 SHA512:
-  metadata.gz: ef23c65119a28a69e2c060b69361be24e3558cdce80b6bed93e1a0fc7463e7f87bca81b59c770c4fb378d68368c0da1713723523f4fee445d829ac9d4e0a973b
-  data.tar.gz: 58b0f5ee9763465a0801ebfbaf825c0009b12138bd20996ac34d5183c68a16ed6d515c8555e02b669c29cdbcb5e12916bb7adfec4d0769edbc7e793597d97334
+  metadata.gz: a196f878697f4c7f1a65178cee78a6d36b1c23c9466d0b997ee3ece51bbc0497db0fc0a3f6f16361a1d7c7518733afe7357bbc2a5cb785deaabe07d45df1aec5
+  data.tar.gz: b657aa48b952ae4b3136bc52c6e5f96f7d3287ae26d08089a0aaf294313a9662d1dfa2ca35477702b4269ad42af53f2b97e7e9eee575142b0c27b295c789de78

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mangadex (5.3.3.1)
+    mangadex (5.3.3.2)
       activesupport (~> 6.1)
       psych (~> 4.0.1)
       rest-client (~> 2.1)
@@ -82,7 +82,7 @@ GEM
     smart_properties (1.16.3)
     sorbet (0.5.9152)
       sorbet-static (= 0.5.9152)
-    sorbet-runtime (0.5.9161)
+    sorbet-runtime (0.5.9189)
     sorbet-static (0.5.9152-universal-darwin-20)
     sorbet-static (0.5.9152-x86_64-linux)
     tilt (2.0.10)

data/bin/console

@@ -3,13 +3,14 @@
 require "bundler/setup"
 require "mangadex"
 
-username, password = [
+username, password, email = [
   ENV['MD_USERNAME'],
   ENV['MD_PASSWORD'],
+  ENV['MD_EMAIL'],
 ]
 
-if username && password
-  Mangadex::Auth.login(username, password)
+if (username || email) && password
+  Mangadex::Auth.login(username: username, email: email, password: password)
 end
 
 # You can add fixtures and/or initialization code here to make experimenting

data/docs/authentication.md

@@ -0,0 +1,226 @@
+# 🔒 Authenticating with Mangadex
+
+## Beforehand
+
+Any actions that can be performed on the mangadex site as a non authenticated user will not require a user to be logged
+in. Authentication on Mangadex, as per version
+<a href="https://rubygems.org/gems/mangadex"><img src="https://badgen.net/rubygems/v/mangadex" /></a>
+will need an `Authorization` HTTP header to be present.
+
+You can check details on the Mangadex API here: https://api.mangadex.org/docs.html#section/Authentication
+
+## Authentication & Authorization flow
+
+The authentication flow happens as such:
+
+1. You login with your email or username, and password.
+2. Upon successfully _authenticating_ your account, you will be given a `session` and a `refresh` tokens.
+3. You must use the `session` token to _authorize_ your account to perform certain actions (ie: create resources, etc.)
+4. You must use the `refresh` token to refresh the `session` when expired.
+
+> - The `session` token expires **15 minutes** after been granted.
+> - The `refresh` token refreshes **1 month** after been granted.
+
+## Authentication using `mangadex` gem
+
+Now that the basics of authentication have been covered, let's go over how it's done on with the gem.
+
+### Logging in
+
+It's simple to login, whether with your email address or your email address:
+
+```ruby
+# With your username
+Mangadex::Auth.login(username: username, password: password)
+
+# With your email address
+Mangadex::Auth.login(email: email, password: password)
+```
+
+Upon successful authentication, an instance of `Mangadex::Api::User` will be returned:
+
+```ruby
+user = Mangadex::Auth.login(...)
+
+# The session token, valid for 15 minutes (String).
+user.session
+
+# The refresh token, valid for 1 month (String)
+user.refresh
+
+# The logged in user's ID (String) (formatted as a UUID)
+user.mangadex_user_id
+
+# Time at the which user.session becomes invalid (Time)
+user.session_valid_until
+
+# Miscellaneaous data. When logging in, it's an instance of Mangadex::User
+# (response from the server)
+user.data
+```
+
+```ruby
+# Refreshes the tokens now (Boolean)
+user.refresh!
+
+# Refreshes the tokens if expired, then return user itself (Mangadex::Api::User)
+user.with_valid_session
+
+# Returns if user.session has expired (Boolean)
+user.session_expired?
+```
+
+If there's an error, `Mangadex::Errors::AuthenticationError` will be raised. Here's how to handle that scenario:
+
+```ruby
+def login(email, password)
+  Mangadex::Auth.login(email: email, password: password)
+rescue Mangadex::Errors::AuthenticationError => error
+  response = error.response
+
+  # A list of detailed errors from Mangadex. (Array of
+  # Mangadex::Api::Response::Error)
+  response.errors.each do |error|
+    puts error.id
+    puts error.status
+    puts error.title
+    puts error.detail
+  end
+end
+```
+
+### Authenticating requests
+
+When the user is logged in, all subsequent requests _should_ be authenticated. Here's an example to retrieve a list of manga that the logged in user is _reading_ at the moment:
+
+```ruby
+user = Mangadex::Auth.login(...)
+response = Mangadex::Manga.all_reading_status('reading')
+manga_ids = response['statuses'].keys
+
+reading_now = Mangadex::Manga.list(ids: manga_ids)
+```
+
+If for whatever reason you want to a request not to be authenticated, you can do something like:
+
+```ruby
+Mangadex.context.without_user do
+  # your mangadex request(s) here
+end
+```
+
+When logging in, the user's session information will be persisted in the storage. See below [for more details]().
+
+### Logging out
+
+Logging the user out is very easy:
+
+```ruby
+Mangadex::Auth.logout
+```
+
+Here, the `user`'s session will be revoked on Mangadex. It will try to delete the user's session. `Mangadex::Auth.logout` outside of the `with_user` block will not do anything.
+
+This action also clears the context's user and the storage info associated to this user.
+
+## Persisting the user session: storage stragegies
+
+### What is this?
+
+Using this gem should help you a little bit managing tokens. By default, the gem stores the following information in memory:
+
+- For a particular user ID:
+  - User session
+  - User refresh token
+  - User session expiry date
+
+### Why is this a thing?
+
+Good question. We want to make session management with this gem as easy as possible. The session is used to retrieve a valid logged in user. Here's how it works:
+
+- When the user logs in, the refresh token, the session token (as well as it's expired date) are stored for that user
+- When requesting the tokens for the user, a `Mangadex::Api::User` is created with refreshed tokens (if expired).
+- When logging out, if implemented by you, the users's session details are deleted.
+
+Here's you retrieve a user from your storage at any point:
+
+```ruby
+mangadex_user_id = '...'
+Mangadex::Api::User.from_storage(mangadex_user_id)
+```
+
+It's up to you to decide how you store the user ID. You don't need to worry about saving the storage, the gem takes care of that for you.
+
+### Ok, ok. How can I use my own strategy?
+
+By default, this gem ships with `Mangagex::Storage::Memory` which corresponds to the in-memory storage. This should be fine if you don't care much about persisting the user session at any point.
+
+No assumptions can be made on which storage service you use. That is 100% up to you how the information is stored. Let's say you want to use [redis](https://github.com/redis/redis) for session instead of the default memory storage stragery:
+
+```ruby
+require 'redis'
+
+class BasicRedisStragery < Mangadex::Storage::Basic
+  # Must be implemented
+  def get(mangadex_user_id, key)
+    client.hget(mangadex_user_id, key)
+  end
+
+  # Must be implemented
+  def set(mangadex_user_id, key, value)
+    client.hset(mangadex_user_id, key, value)
+  end
+
+  # Optional - It's a nice-to-have, especially for logging out.
+  def clear(mangadex_user_id)
+    client.del(mangadex_user_id)
+  end
+
+  private
+
+  def client
+    @client ||= Redis.new(url: 'redis://localhost')
+  end
+end
+
+# Let the gem know which strategy needs to be used
+Mangadex.configuration.storage_class = BasicRedisStragery
+```
+
+> On Rails, you can put this inside an initializer. Example: `config/initializers/mangadex.rb`.
+
+The snippet of code is an example of how a storage strategy is implemented. It's important to make sure that neither `get` nor `set` raise exceptions.
+
+> - We recommend using redis if you're developing a web app or a bot where authentication is involed.
+> - You can even use a the filesystem if you're building a CLI (command line interface).
+> - We **do not** recommend using SQL at the moment. This might be hard on your app's performance...
+
+### Can I opt-out?
+
+Of course. Set `Mangadex::Storage::None` as the prefered strategy:
+
+```ruby
+# Either
+Mangadex.configure do |config|
+  config.storage_class = Mangadex::Storage::None
+end
+
+# Or
+Mangadex.configuration.storage_class = Mangadex::Storage::None
+```
+
+## About content ratings
+
+Each manga/chapter has a content rating (`safe`, `suggestive`, `erotica` and `pornographic`). It might be worth filtering certain titles depending on the audiance. By default, Mangadex filters out every `pornographic` entry.
+
+Please note that content rating is not tied to the user at the moment on Mangadex. So it was decided **not** to add this responsiblity on this gem. Instead, the content ratings can be specified on context gem as well, like this:
+
+```ruby
+# Everything but "suggestive" content - this is an example :p
+mangas = Mangadex::Api::Content.allow_content_rating('safe', 'erotica', 'pornographic') do
+  response = Mangadex::Manga.list
+  response.data
+end
+```
+
+The advantage of this approach is that you don't have to set the `content_rating` param yourself everywhere.

data/docs/context.md

@@ -0,0 +1,93 @@
+# Mangadex contexts
+
+There is a concept of concepts in this gem. This is there for you to access certain variables at any point in your app.
+
+## User
+
+```ruby
+Mangadex.context.user # => #<Mangadex::Api::User ...>
+```
+
+This is set to `nil` before logging in.
+
+When logging in, the user is stored in the context so that subsequent requests are set to be authenticated with this user.
+
+```ruby
+Mangadex::Auth.login(...)
+Mangadex.context.user.nil? # => false
+
+custom_lists = Mangadex::CustomList.list
+```
+
+If you're not logged in, `Mangadex::Errors::UnauthorizedError` will be raised for any request that requires you to be logged in and authorized to perform a certain account.
+
+You can set the user in a temporary context:
+
+```ruby
+Mangadex.context.user # => nil
+
+temp_user = Mangadex::Api::User.new(mangadex_user_id: 'blabla')
+Mangadex.context.with_user(temp_user) do
+  Mangadex.context.user # => #<Mangadex::Api::User mangadex_user_id="blabla">
+end
+
+Mangadex.context.user # => nil
+```
+
+More info on authentication [here]().
+
+## Content rating
+
+```ruby
+Mangadex.context.allowed_content_ratings # => [#<Mangadex::ContentRating ...>, ...]
+```
+
+Content ratings are not tied to the user. When set, requests that accept a [`content_rating`](https://api.mangadex.org/docs.html#section/Static-data/Manga-content-rating) parameter, this parameter will be set to `Mangadex.context.allowed_content_ratings` if nothing is specified.
+
+By default, `safe`, `suggestive` and `erotica` are used on Mangadex. But however, if you want to allow all content ratings, you could do something like:
+
+```ruby
+Mangadex.context.allow_content_ratings('safe', 'suggestive', 'erotica', 'pornographic')
+```
+
+Then, a query to fetch manga will make the following request:
+
+```ruby
+Mangadex::Manga.list
+# GET https://api.mangadex.org/manga?contentRating%5B%5D=safe&contentRating%5B%5D=suggestive&contentRating%5B%5D=erotica&contentRating%5B%5D=pornographic
+```
+
+You can also use temporary content ratings:
+
+```ruby
+# old content ratings
+Mangadex.context.allow_content_ratings('safe', 'suggestive', 'erotica', 'pornographic') do
+  # temporary content ratings
+  Mangadex::Manga.list
+end
+
+# back to old content ratings
+```
+
+## Tags
+
+Get the list of possible tags on Mangadex:
+
+```ruby
+Mangadex.context.tags
+```
+
+### API version
+
+Get the current Mangadex's latest API version
+
+```ruby
+Mangadex.context.version
+```
+
+A warning message will be printed if there's a mismatch between Mangadex's API version and the gem version. Example:
+
+| Mangadex's API version | The gem's version | Result  |
+| ---------------------- | ----------------- | ------- |
+| 5.3.3                  | 5.3.3.1           | OK      |
+| 5.3.4                  | 5.3.3.4           | Warning |

data/lib/config.rb

@@ -0,0 +1,50 @@
+# typed: true
+
+module Mangadex
+  class Config
+    extend T::Sig
+
+    # Class used to persist users
+    # Must respond to: :session, :refresh, :mangadex_user_id
+    sig { returns(Class) }
+    attr_accessor :user_class
+
+    # Persisting strategy. See Mangadex::Storage::Base for more details.
+    sig { returns(Class) }
+    attr_accessor :storage_class
+
+    sig { returns(T::Array[ContentRating]) }
+    attr_accessor :default_content_ratings
+
+    sig { void }
+    def initialize
+      @user_class = Api::User
+      @storage_class = Storage::Memory
+      @default_content_ratings = ContentRating.parse(['safe', 'suggestive', 'erotica'])
+    end
+
+    sig { params(klass: Class).void }
+    def user_class=(klass)
+      missing_methods = [:session, :refresh, :mangadex_user_id] - klass.instance_methods
+      if missing_methods.empty?
+        @user_class = klass
+      else
+        raise ArgumentError, 'user_class must respond to :session, :refresh, :mangadex_user_id'
+      end
+    end
+
+    sig { params(content_ratings: T::Array[T.any(String, ContentRating)]).void }
+    def default_content_ratings=(content_ratings)
+      @default_content_ratings = ContentRating.parse(content_ratings)
+    end
+
+    def storage_class=(klass)
+      @storage = nil
+      @storage_class = klass
+    end
+
+    def storage
+      @storage ||= storage_class.new
+    end
+  end
+end

data/lib/errors.rb

@@ -0,0 +1,42 @@
+# typed: true
+
+module Mangadex
+  module Errors
+    # Standard error class for this gem.
+    # 
+    # @author thedrummeraki
+    # @since 0.6.0
+    class StandardError < ::StandardError
+      extend T::Sig
+    end
+
+    class UserNotLoggedIn < StandardError
+      sig { returns(String) }
+      def message
+        "You are not logged in. Use [Mangadex::Auth.login] to log in."
+      end
+    end
+
+    class AuthenticationError < StandardError
+      sig { returns(Mangadex::Api::Response) }
+      attr_accessor :response
+
+      sig { params(response: Mangadex::Api::Response).void }
+      def initialize(response)
+        @response = response
+      end
+
+      sig { returns(String) }
+      def message
+        "Your username or password may not be correct."
+      end
+    end
+
+    class UnauthorizedError < AuthenticationError
+      sig { returns(String) }
+      def message
+        "Oops, you are not authorized to make this call. Make sure you log in with the right account."
+      end
+    end
+  end
+end

data/lib/mangadex/README.md

@@ -3,12 +3,14 @@
 This is documentation for the `Mangadex` module.
 
 ### Directory
+
 #### Sub-modules
 
 - [`Mangadex::Api`](#)
 - [`Mangadex::Internal`](#)
 
 #### Fetchable/Resources
+
 - [`Mangadex::Artist`](#)
 - [`Mangadex::Auth`](#mangadexauth)
 - [`Mangadex::Author`](#)
@@ -25,6 +27,7 @@ This is documentation for the `Mangadex` module.
 - [`Mangadex::User`](#)
 
 #### Other classes
+
 - [`Mangadex::MangadexObject`](#)
 - [`Mangadex::Types`](#)
 - [`Mangadex::Version`](#)
@@ -51,7 +54,7 @@ Mangadex::Auth.login(username, password)
 ```
 
 Login with your username and password. Upon successful login, the user will be available in a context from
-`Mangadex::Api::Context.user`. This variable can be used anywhere in your application. More info [here](#).
+`Mangadex.context.user`. This variable can be used anywhere in your application. More info [here](#).
 
 > - Returns `Mangadex::Api::Response` if request fails.
 > - Returns `true` if user is logged in.
@@ -86,8 +89,9 @@ Mangadex::Auth.refresh_token
 ```
 
 Manually cause a token refresh.
+
 > Please note that simply calling `Mangadex::Api::Content.user` ensures that the token is valid. More info [here](#).
 
 > - Returns `nil` if user is not logged (ie: `Mangadex::Api::Content.user` is `nil`)
 > - Returns `true` if the refresh is successful
-> - Returns `false` if the refresh is [not successful](#).
+> - Returns `false` if the refresh is [not successful](#).

data/lib/mangadex/api/response.rb

@@ -41,8 +41,11 @@ module Mangadex
         end
       end
 
-      def errored?
-        Array(errors).any?
+      def errored?(status=nil)
+        errored = Array(errors).any?
+        return errored if status.nil?
+
+        errors.select { |error| error.status.to_s == status.to_s }.any?
       end
 
       def as_json(*)

data/lib/mangadex/api/user.rb

@@ -7,13 +7,13 @@ module Mangadex
       attr_accessor :mangadex_user_id, :session, :refresh, :session_valid_until
       attr_reader :data
 
-      sig { params(mangadex_user_id: String, session: T.nilable(String), refresh: T.nilable(String), data: T.untyped).void }
-      def initialize(mangadex_user_id, session: nil, refresh: nil, data: nil)
+      sig { params(mangadex_user_id: String, session: T.nilable(String), refresh: T.nilable(String), data: T.untyped, session_valid_until: T.nilable(Time)).void }
+      def initialize(mangadex_user_id:, session: nil, refresh: nil, data: nil, session_valid_until: nil)
         raise ArgumentError, 'Missing mangadex_user_id' if mangadex_user_id.to_s.empty?
 
         @mangadex_user_id = mangadex_user_id
         @session = session
-        @session_valid_until = session ? Time.now + (14 * 60) : nil
+        @session_valid_until = session_valid_until ? session_valid_until : (session ? Time.now + (14 * 60) : nil)
         @refresh = refresh
         @data = data
       end
@@ -24,9 +24,7 @@ module Mangadex
       def refresh!
         return false if refresh.nil?
 
-        response = Mangadex::Api::Context.without_user do
-          Mangadex::Internal::Request.post('/auth/refresh', payload: { token: refresh })
-        end
+        response = Mangadex::Internal::Request.post('/auth/refresh', payload: { token: refresh })
         return false unless response['token']
 
         @session_valid_until = Time.now + (14 * 60)
@@ -36,7 +34,7 @@ module Mangadex
         true
       end
 
-      sig { returns(Mangadex::Api::User) }
+      sig { returns(User) }
       def with_valid_session
         session_expired? && refresh!
         self
@@ -48,6 +46,52 @@ module Mangadex
       def session_expired?
         @session_valid_until.nil? || @session_valid_until <= Time.now
       end
+
+      sig { returns(T::Boolean) }
+      def persist
+        return false unless valid?
+
+        Mangadex.storage.set(mangadex_user_id, 'session', session) if session
+        Mangadex.storage.set(mangadex_user_id, 'refresh', refresh) if refresh
+        if session_valid_until
+          Mangadex.storage.set(mangadex_user_id, 'session_valid_until', session_valid_until.to_s)
+        end
+
+        true
+      end
+
+      sig { returns(T::Boolean) }
+      def valid?
+        !mangadex_user_id.nil? && !mangadex_user_id.strip.empty?
+      end
+
+      sig { params(mangadex_user_id: T.nilable(String)).returns(T.nilable(User)) }
+      def self.from_storage(mangadex_user_id)
+        return if mangadex_user_id.nil?
+
+        session = Mangadex.storage.get(mangadex_user_id, 'session')
+        refresh = Mangadex.storage.get(mangadex_user_id, 'refresh')
+        session_valid_until = Mangadex.storage.get(mangadex_user_id, 'session_valid_until')
+
+        user = if session || refresh || session_valid_until
+          session_valid_until = session_valid_until ? Time.parse(session_valid_until) : nil
+
+          new(
+            mangadex_user_id: mangadex_user_id,
+            session: session,
+            refresh: refresh,
+            session_valid_until: session_valid_until,
+          ).with_valid_session
+        else
+          nil
+        end
+
+        if user
+          Mangadex.context.user = user
+        end
+
+        user
+      end
     end
   end
 end

data/lib/mangadex/api.rb

@@ -1,5 +1,4 @@
 # typed: strict
 require_relative "api/version_checker"
-require_relative "api/context"
 require_relative "api/response"
 require_relative "api/user"

data/lib/mangadex/auth.rb

@@ -3,16 +3,20 @@ module Mangadex
   class Auth
     extend T::Sig
 
-    sig { params(username: String, password: String).returns(T.any(T::Boolean, Mangadex::Api::Response)) }
-    def self.login(username, password)
+    sig { params(username: T.nilable(String), email: T.nilable(String), password: String).returns(T.nilable(Mangadex::Api::User)) }
+    def self.login(username: nil, email: nil, password: nil)
+      args = { password: password }
+      args.merge!(email: email) if email
+      args.merge!(username: username) if username
+
       response = Mangadex::Internal::Request.post(
         '/auth/login',
-        payload: {
-          username: username,
-          password: password,
-        },
+        payload: Mangadex::Internal::Definition.validate(args, {
+          username: { accepts: String },
+          email: { accepts: String },
+          password: { accepts: String, required: true },
+        }),
       )
-      return response if response.is_a?(Mangadex::Api::Response) && response.errored?
 
       session = response.dig('token', 'session')
       refresh = response.dig('token', 'refresh')
@@ -20,13 +24,19 @@ module Mangadex
       mangadex_user = Mangadex::Internal::Request.get('/user/me', headers: { Authorization: session })
 
       user = Mangadex::Api::User.new(
-        mangadex_user.data.id,
+        mangadex_user_id: mangadex_user.data.id,
         session: session,
         refresh: refresh,
         data: mangadex_user.data,
       )
-      Mangadex::Api::Context.user = user
-      !user.session_expired?
+      return if user.session_expired?
+
+      Mangadex.context.user = user
+
+      user.persist
+      user
+    rescue Errors::UnauthorizedError => error
+      raise Errors::AuthenticationError.new(error.response)
     end
 
     sig { returns(Hash) }
@@ -41,20 +51,39 @@ module Mangadex
 
     sig { returns(T.any(T::Boolean, Mangadex::Api::Response)) }
     def self.logout
-      return true if Mangadex::Api::Context.user.nil?
+      return true if Mangadex.context.user.nil?
 
       response = Mangadex::Internal::Request.post(
         '/auth/logout',
       )
       return reponse if response.is_a?(Mangadex::Api::Response) && response.errored?
 
-      Mangadex::Api::Context.user = nil
+      clear_user
+      true
+    rescue Mangadex::Errors::UnauthorizedError
+      clear_user
       true
     end
 
     sig { returns(T::Boolean) }
     def self.refresh_token
-      !(Mangadex::Api::Context.user&.refresh!).nil?
+      !(Mangadex.context.user&.refresh!).nil?
+    end
+
+    private
+
+    sig { void }
+    def self.clear_user
+      return if Mangadex.context.user.nil?
+
+      if Mangadex.context.user.respond_to?(:session=)
+        Mangadex.context.user.session = nil
+      end
+      if Mangadex.context.user.respond_to?(:refresh=)
+        Mangadex.context.user.refresh = nil
+      end
+      Mangadex.storage.clear(Mangadex.context.user.mangadex_user_id)
+      Mangadex.context.user = nil
     end
   end
 end

data/lib/mangadex/internal/context.rb

@@ -0,0 +1,141 @@
+# typed: true
+module Mangadex
+  module Internal
+    class Context
+      extend T::Sig
+
+      sig { returns(T::Array[Mangadex::ContentRating]) }
+      attr_accessor :allowed_content_ratings, :ignore_user
+
+      def initialize
+        @allowed_content_ratings = Mangadex.configuration.default_content_ratings
+      end
+
+      sig { returns(T.nilable(String)) }
+      def version
+        @version ||= Mangadex::Api::VersionChecker.check_mangadex_version
+      end
+
+      sig { returns(T.nilable(Mangadex::Api::User)) }
+      def user
+        @ignore_user ? nil : @user&.with_valid_session
+      rescue Mangadex::Errors::UnauthorizedError
+        warn("A user is present but not authenticated!")
+        nil
+      end
+
+      sig { returns(T::Array[Mangadex::Tag]) }
+      def tags
+        @tags ||= Mangadex::Tag.list.data
+      end
+
+      sig { params(user: T.nilable(T.any(Hash, Mangadex::Api::User, Mangadex::User)), block: T.proc.returns(T.untyped)).returns(T.untyped) }
+      def with_user(user, &block)
+        temp_set_value("user", user) do
+          yield
+        end
+      end
+
+      sig { params(block: T.proc.returns(T.untyped)).returns(T.untyped) }
+      def without_user(&block)
+        temp_set_value("ignore_user", true) do
+          yield
+        end
+      end
+
+      sig { params(user: T.nilable(T.untyped)).void }
+      def user=(user)
+        if user.is_a?(Mangadex::Api::User)
+          @user = user
+        elsif user.is_a?(Mangadex::User)
+          @user = Mangadex::Api::User.new(
+            mangadex_user_id: user.id,
+            data: user,
+          )
+        elsif user.is_a?(Hash)
+          user = Mangadex::Internal::Definition.validate(user, {
+            mangadex_user_id: { accepts: String, required: true },
+            session: { accepts: String },
+            refresh: { accepts: String },
+          })
+
+          @user = Mangadex::Api::User.new(
+            mangadex_user_id: user[:mangadex_user_id],
+            session: user[:session],
+            refresh: user[:refresh],
+          )
+        elsif user_object?(user)
+          @user = Mangadex::Api::User.new(
+            mangadex_user_id: user.mangadex_user_id.to_s,
+            session: user.session,
+            refresh: user.refresh,
+            data: user,
+          )
+        elsif user.nil?
+          @user = nil
+        else
+          raise TypeError, "Invalid user type."
+        end
+      end
+
+      def allow_content_ratings(*content_ratings, &block)
+        content_ratings = Mangadex::ContentRating.parse(Array(content_ratings))
+        if block_given?
+          content_ratings = Mangadex.context.allowed_content_ratings if content_ratings.empty?
+
+          # set temporarily
+          temp_set_value("allowed_content_ratings", content_ratings) do
+            yield
+          end
+        elsif content_ratings.any?
+          # set "permanently"
+          @allowed_content_ratings = content_ratings
+        else
+          # This is to throw an exception prompting to pass a block if there no params.
+          yield
+        end
+      end
+
+      def with_allowed_content_ratings(*other_content_ratings, &block)
+        T.unsafe(self).allow_content_ratings(*(allowed_content_ratings + other_content_ratings)) do
+          yield
+        end
+      end
+
+      # Only recommended for development and debugging only
+      def force_raw_requests(&block)
+        if block_given?
+          temp_set_value("force_raw_requests", true) do
+            yield
+          end
+        else
+          !!@force_raw_requests
+        end
+      end
+
+      private
+
+      def user_object?(user)
+        return false if user.nil?
+
+        missing_methods = [:session, :refresh, :mangadex_user_id] - user.methods
+        return true if missing_methods.empty?
+
+        warn("Potential user object #{user} is missing #{missing_methods}")
+        false
+      end
+
+      def temp_set_value(name, value, &block)
+        setter_method_name = "#{name}="
+
+        current_value = send(name)
+        send(setter_method_name, value)
+        response = yield
+        send(setter_method_name, current_value)
+        response
+      ensure
+        send(setter_method_name, current_value) if current_value
+      end
+    end
+  end
+end

data/lib/mangadex/internal/request.rb

@@ -54,7 +54,7 @@ module Mangadex
         payload_details = request_payload ? "Payload: #{request_payload}" : "{no-payload}"
         puts("[#{self.class.name}] #{method.to_s.upcase} #{request_url} #{payload_details}")
 
-        raise Mangadex::UserNotLoggedIn.new if auth && Mangadex::Api::Context.user.nil?
+        raise Mangadex::Errors::UserNotLoggedIn.new if auth && Mangadex.context.user.nil?
 
         start_time = Time.now
 
@@ -63,11 +63,13 @@ module Mangadex
         elapsed_time = ((end_time - start_time) * 1000).to_i
         puts("[#{self.class.name}] took #{elapsed_time} ms")
         
-        raw_request = raw || Mangadex::Api::Context.force_raw_requests
+        raw_request = raw || Mangadex.context.force_raw_requests
 
         if (body = @response.body)
           raw_request ? try_json(body) : Mangadex::Api::Response.coerce(try_json(body))
         end
+      rescue RestClient::Unauthorized => error
+        raise Errors::UnauthorizedError.new(Mangadex::Api::Response.coerce(try_json(error.response.body)))
       rescue RestClient::Exception => error
         if (body = error.response.body)
           raw_request ? try_json(body) : Mangadex::Api::Response.coerce(JSON.parse(body)) rescue raise error
@@ -90,8 +92,8 @@ module Mangadex
 
       def self.with_content_rating(data)
         content_rating = data.has_key?(:content_rating) ? data[:content_rating] : []
-        Mangadex::Api::Context.allow_content_ratings(*content_rating) do
-          data[:content_rating] = Mangadex::Api::Context.allowed_content_ratings
+        Mangadex.context.allow_content_ratings(*content_rating) do
+          data[:content_rating] = Mangadex.context.allowed_content_ratings
         end
         data
       end
@@ -108,10 +110,10 @@ module Mangadex
       end
 
       def request_headers
-        return headers if Mangadex::Api::Context.user.nil?
+        return headers if Mangadex.context.user.nil?
 
         headers.merge({
-          Authorization: Mangadex::Api::Context.user.with_valid_session.session,
+          Authorization: Mangadex.context.user.with_valid_session.session,
         })
       end
 

data/lib/mangadex/internal.rb

@@ -1,3 +1,4 @@
 # typed: strict
+require_relative "internal/context"
 require_relative "internal/request"
 require_relative "internal/definition"

data/lib/mangadex/manga.rb

@@ -123,14 +123,16 @@ module Mangadex
       )
     end
 
-    sig { params(args: T::Api::Arguments).returns(T::Api::GenericResponse) }
-    def self.all_reading_status(**args)
+    sig { params(status: String).returns(T::Api::GenericResponse) }
+    def self.all_reading_status(status)
+      args = { status: status }
+
       Mangadex::Internal::Request.get(
         '/manga/status',
         Mangadex::Internal::Definition.validate(args, {
           status: {
             accepts: %w(reading on_hold dropped plan_to_read re_reading completed),
-            converts: Mangadex::Internal::Definition.converts(:to_a),
+            converts: :to_s,
           },
         })
       )

data/lib/mangadex/storage/basic.rb

@@ -0,0 +1,18 @@
+module Mangadex
+  module Storage
+    class Basic
+      def get(_scope, _key)
+        raise NotImplementedError
+      end
+
+      def set(_scope, _key, _value)
+        raise NotImplementedError
+      end
+
+      def clear(_scope)
+        warn("Don't know how to clear #{self.class} storage strategy! Skipping...")
+        nil
+      end
+    end
+  end
+end

data/lib/mangadex/storage/memory.rb

@@ -0,0 +1,23 @@
+module Mangadex
+  module Storage
+    class Memory < BasicObject
+      def initialize
+        @storage = {}
+      end
+
+      def get(scope, key)
+        @storage.dig(scope.to_s, key.to_s)
+      end
+
+      def set(scope, key, value)
+        key = key.to_s
+        @storage[scope] = {} unless @storage.has_key?(scope)
+        @storage[scope][key] = value
+      end
+
+      def clear(scope)
+        @storage.delete(scope)
+      end
+    end
+  end
+end

data/lib/mangadex/storage/none.rb

@@ -0,0 +1,9 @@
+module Mangadex
+  module Storage
+    class None < Basic
+      def get(_scope, _key); end
+      def set(_scope, _key, _value); end
+      def clear(_scope); end
+    end
+  end
+end

data/lib/mangadex/storage.rb

@@ -0,0 +1,3 @@
+require_relative "storage/basic"
+require_relative "storage/none"
+require_relative "storage/memory"

data/lib/mangadex/user.rb

@@ -60,7 +60,7 @@ module Mangadex
     def self.follows_user(id)
       Mangadex::Internal::Definition.must(id)
 
-      return if Mangadex::Api::Context.user.nil?
+      return if Mangadex.context.user.nil?
 
       data = Mangadex::Internal::Request.get(
         '/user/follows/user/%{id}' % {id: id},
@@ -90,7 +90,7 @@ module Mangadex
     def self.follows_manga(id)
       Mangadex::Internal::Definition.must(id)
 
-      return if Mangadex::Api::Context.user.nil?
+      return if Mangadex.context.user.nil?
 
       data = Mangadex::Internal::Request.get(
         '/user/follows/manga/%{id}' % {id: id},

data/lib/mangadex/version.rb

@@ -4,7 +4,7 @@ module Mangadex
     MAJOR = "5"
     MINOR = "3"
     TINY = "3"
-    PATCH = "1"
+    PATCH = "2"
 
     STRING = [MAJOR, MINOR, TINY].compact.join('.')
     FULL = [MAJOR, MINOR, TINY, PATCH].compact.join('.')

data/lib/mangadex.rb

@@ -1,4 +1,4 @@
-# typed: strict
+# typed: true
 require 'sorbet-runtime'
 
 require 'active_support'
@@ -14,22 +14,35 @@ require "mangadex/types"
 # API, to interact with Mangadex
 require "mangadex/api"
 
+# Persist strategies
+require "mangadex/storage"
+
+require_relative "config"
+require_relative "errors"
+
 # Namespace for classes and modules for this gem.
 # @since 5.3.0
 
 module Mangadex
-  # Standard error class for this gem.
-  # 
-  # @author thedrummeraki
-  # @since 0.6.0
-  class Error < StandardError
-    extend T::Sig
-  end
+  class << self
+    def configuration
+      @configuration ||= Config.new
+    end
+
+    def context
+      @context ||= Internal::Context.new
+    end
+
+    def configure(&block)
+      yield(configuration)
+    end
+
+    def storage
+      configuration.storage
+    end
 
-  class UserNotLoggedIn < Error
-    sig { returns(String) }
-    def message
-      "You are not logged in. Use [Mangadex::Auth.login] to log in."
+    def api_version
+      context.version
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mangadex
 version: !ruby/object:Gem::Version
-  version: 5.3.3.1
+  version: 5.3.3.2
 platform: ruby
 authors:
 - Akinyele Cafe-Febrissy
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-09-27 00:00:00.000000000 Z
+date: 2021-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: psych
@@ -170,11 +170,14 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/authentication.md
+- docs/context.md
+- lib/config.rb
+- lib/errors.rb
 - lib/extensions.rb
 - lib/mangadex.rb
 - lib/mangadex/README.md
 - lib/mangadex/api.rb
-- lib/mangadex/api/context.rb
 - lib/mangadex/api/response.rb
 - lib/mangadex/api/user.rb
 - lib/mangadex/api/version_checker.rb
@@ -186,6 +189,7 @@ files:
 - lib/mangadex/cover_art.rb
 - lib/mangadex/custom_list.rb
 - lib/mangadex/internal.rb
+- lib/mangadex/internal/context.rb
 - lib/mangadex/internal/definition.rb
 - lib/mangadex/internal/request.rb
 - lib/mangadex/internal/with_attributes.rb
@@ -195,6 +199,10 @@ files:
 - lib/mangadex/report_reason.rb
 - lib/mangadex/scanlation_group.rb
 - lib/mangadex/sorbet.rb
+- lib/mangadex/storage.rb
+- lib/mangadex/storage/basic.rb
+- lib/mangadex/storage/memory.rb
+- lib/mangadex/storage/none.rb
 - lib/mangadex/tag.rb
 - lib/mangadex/types.rb
 - lib/mangadex/upload.rb

data/lib/mangadex/api/context.rb

@@ -1,137 +0,0 @@
-# typed: true
-module Mangadex
-  module Api
-    class Context
-      extend T::Sig
-
-      DEFAULT_MANGADEX_CONTENT_RATING_VALUES = [
-        ContentRating::SAFE,
-        ContentRating::SUGGESTIVE,
-        ContentRating::EROTICA,
-      ].freeze
-
-      @@user = nil
-      @@version = nil
-      @@force_raw_requests = nil
-      @@tags = nil
-      @@allowed_content_ratings = DEFAULT_MANGADEX_CONTENT_RATING_VALUES
-
-      sig { returns(T.nilable(String)) }
-      def self.version
-        return @@version unless @@version.nil?
-
-        @@version = Mangadex::Api::VersionChecker.check_mangadex_version
-      end
-
-      sig { returns(T.nilable(Mangadex::Api::User)) }
-      def self.user
-        @@user&.with_valid_session
-      end
-
-      sig { returns(T::Array[Mangadex::Tag]) }
-      def self.tags
-        return @@tags if @@tags
-
-        @@tags = Mangadex::Tag.list.data
-      end
-
-      sig { returns(T::Array[Mangadex::ContentRating]) }
-      def self.allowed_content_ratings
-        @@allowed_content_ratings.map { |value| ContentRating.new(value) }
-      end
-
-      sig { params(user: T.nilable(T.any(Hash, Mangadex::Api::User, Mangadex::User))).void }
-      def self.user=(user)
-        if user.is_a?(Mangadex::Api::User)
-          @@user = user
-        elsif user.is_a?(Mangadex::User)
-          @@user = Mangadex::Api::User.new(
-            user.id,
-            data: user,
-          )
-        elsif user.is_a?(Hash)
-          user = Mangadex::Internal::Definition.validate(user, {
-            mangadex_user_id: { accepts: String, required: true },
-            session: { accepts: String },
-            refresh: { accepts: String },
-          })
-
-          @@user = Mangadex::Api::User.new(
-            user[:mangadex_user_id],
-            session: user[:session],
-            refresh: user[:refresh],
-          )
-        elsif user.nil?
-          @@user = nil
-        end
-      end
-
-      sig { params(user: T.nilable(T.any(Hash, Mangadex::Api::User, Mangadex::User)), block: T.proc.returns(T.untyped)).returns(T.untyped) }
-      def self.with_user(user, &block)
-        temp_set_value("user", user) do
-          yield
-        end
-      end
-
-      sig { params(block: T.proc.returns(T.untyped)).returns(T.untyped) }
-      def self.without_user(&block)
-        with_user(nil) do
-          yield
-        end
-      end
-
-      def self.force_raw_requests(&block)
-        if block_given?
-          temp_set_value("force_raw_requests", true) do
-            yield
-          end
-        else
-          !!@@force_raw_requests
-        end
-      end
-
-      def self.force_raw_requests=(value)
-        @@force_raw_requests = value
-      end
-
-      def self.allow_content_ratings(*content_ratings, &block)
-        content_ratings = if content_ratings.empty?
-          allowed_content_ratings
-        else
-          Mangadex::ContentRating.parse(content_ratings)
-        end
-        if block_given?
-          # set temporarily
-          temp_set_value("allowed_content_ratings", content_ratings) do
-            yield
-          end
-        elsif content_ratings.any?
-          # set "permanently"
-          @@allowed_content_ratings = content_ratings
-        else
-          # This is to throw an exception prompting to pass a block if there no params.
-          yield
-        end
-      end
-
-      def self.with_allowed_content_ratings(*other_content_ratings, &block)
-        T.unsafe(self).allow_content_ratings(*(allowed_content_ratings + other_content_ratings)) do
-          yield
-        end
-      end
-
-      private
-
-      def self.temp_set_value(name, value, &block)
-        var_name = "@@#{name}"
-        current_value = class_variable_get(var_name)
-        class_variable_set(var_name, value)
-        response = yield
-        class_variable_set(var_name, current_value)
-        response
-      ensure
-        class_variable_set(var_name, current_value) if current_value
-      end
-    end
-  end
-end