mangadex 5.3.3 → 5.3.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 166fb230b0125992e5168515129718a28f7d545c3c1cb07f9bc81e837ad8c2c7
-  data.tar.gz: cf310df080bb7fdce3df2fd885aa478de4ae050272e58d97ce6fdbe0b60459af
+  metadata.gz: 903ed335a6c351b7b953d9324fc5b49f4e0a1a83668e7f35b9c32a20051a1e4b
+  data.tar.gz: 404efdef00911d0fccffdc5e17425be7d7bed641207f3c5e2fb400cc03d0a7e4
 SHA512:
-  metadata.gz: 4babccf80e64908e70f612d5afb152b00fef108c827cbfc75a273478ee2f1230b6b2366318bab5a3fadb3b2025e0e7a64bed88746c04484d18a9c1a62a241e2a
-  data.tar.gz: aebcdeed93c99b1beb9e4723e8371875c21da6629311270cbf2b6ca5c58c55b0dca39e8a222bcd886180ee7b1059e40853948f90a25553da4dea8f1d261b4f44
+  metadata.gz: 3a16a37051b34693c278657d40b071444344247bab1deac3c9ba568e028fcbe80c04dacc20a85a5a4cc4593a88a6d46fc0b7d31f4b8aa4dcf7116f1a715be0b4
+  data.tar.gz: 5d12be35cfb8241170c19992e4e87d7df2b1496bcbbe6f072bbb61878233013441c1f6c8cc42c94caaf12ce1bb9eb66a3640101258822731ede84ebca79d10d3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mangadex (5.3.2)
+    mangadex (5.3.3.4)
       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.9211)
     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,33 @@ 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 more_results?
+        return unless data.is_a?(Array)
+
+        total > data.count
+      end
+
+      def count
+        data.is_a?(Array) ? data.count : nil
+      end
+
+      def each(&block)
+        if data.is_a?(Array)
+          data.each(&block)
+        else
+          raise ArgumentError, "Expect data to be Array, but got #{data.class}"
+        end
+      end
+
+      def to_a
+        each.to_a
       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/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"

data/lib/mangadex/artist.rb

@@ -2,10 +2,29 @@
 require_relative "author"
 
 module Mangadex
-  class Artist < Author
+  class Artist < MangadexObject
     # Indicates if this is an artist
     #
     # @return [Boolean] whether this is an artist or not.
+    has_attributes \
+      :name,
+      :image_url,
+      :biography,
+      :twitter,
+      :pixiv,
+      :melon_book,
+      :fan_box,
+      :booth,
+      :nico_video,
+      :skeb,
+      :fantia,
+      :tumblr,
+      :youtube,
+      :website,
+      :version,
+      :created_at,
+      :updated_at
+
     def artist?
       true
     end