mangadex 5.3.1.3 → 5.3.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05fed5e49341d3e084b2c87611bcb3441058a230f7ccd4485c52959a39eef561
-  data.tar.gz: e094c5d36cf370bb77636c4d181b48f1be2a57346d366ff2e836fef19e159708
+  metadata.gz: 1d01b0fac553138d7ac86d1313737d86ba5415ee88e2ca6de08787402be7e3fb
+  data.tar.gz: 643923fe081fb046f6feec8ab4ce945a358a2fc9d66681d732a272b9bad2223d
 SHA512:
-  metadata.gz: fbd96e94db2956aa5222e84949b58de78aa5880a91fe737001d249d3c357a812335f09ddda3451f46164c9195ae980c36808c1a74b2ceceece7408d8c9359e05
-  data.tar.gz: 1c8f6bf9a0fa198e1794988ff42534806700350cd21b7173e3e73a466ced2f8ccf247d2c96db0faebee2da7fdad1c12309d4d335e22df5d54a5e62cb2808d528
+  metadata.gz: a196f878697f4c7f1a65178cee78a6d36b1c23c9466d0b997ee3ece51bbc0497db0fc0a3f6f16361a1d7c7518733afe7357bbc2a5cb785deaabe07d45df1aec5
+  data.tar.gz: b657aa48b952ae4b3136bc52c6e5f96f7d3287ae26d08089a0aaf294313a9662d1dfa2ca35477702b4269ad42af53f2b97e7e9eee575142b0c27b295c789de78

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mangadex (5.3.1.2)
+    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.9155)
+    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/README.md

@@ -1,4 +1,4 @@
-<a href="https://rubygems.org/gems/mangadex"><img src="https://badgen.net/rubygems/v/mangadex" /></a>
+[![Ruby](https://github.com/thedrummeraki/mangadex/actions/workflows/ruby.yml/badge.svg)](https://github.com/thedrummeraki/mangadex/actions/workflows/ruby.yml)<a href="https://rubygems.org/gems/mangadex"><img src="https://badgen.net/rubygems/v/mangadex" /></a>
 
 # Mangadex
 

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

@@ -7,6 +7,7 @@ module Mangadex
 
       attr_accessor :result, :response, :errors, :data
       attr_accessor :limit, :offset, :total
+      attr_accessor :raw_data
 
       def self.attributes_to_inspect
         %i(result errors limit offset total data)
@@ -40,8 +41,15 @@ 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(*)
+        Hash(raw_data)
       end
 
       private
@@ -60,6 +68,7 @@ module Mangadex
               )
             end
           ),
+          raw_data: data,
         )
       end
 
@@ -75,6 +84,7 @@ module Mangadex
           result: data['result'],
           response: data['response'],
           data: klass.from_data(data['data'] || data),
+          raw_data: data,
         )
       end
 
@@ -97,6 +107,7 @@ module Mangadex
               end
             )
           ),
+          raw_data: data,
         )
       end
     end

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/version_checker.rb

@@ -3,7 +3,7 @@ require "psych"
 
 module Mangadex
   module Api
-    class Version
+    class VersionChecker
       extend T::Sig
 
       sig { returns(T.nilable(String)) }

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"