omniauth-shikimori-oauth2 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea04efed2f5b8f6ca5175c9f2ab0620971c6026a42e41c693a4b0744b7414150
-  data.tar.gz: 7bdc09bf37f87db1ad37317b072833dc1831a998a4d70c9080fc40190afd2568
+  metadata.gz: 56f7d6c7b4ddc4c35a41d07e9fe63c33accf8f4f11eb38fc41e8f068726142b9
+  data.tar.gz: dba8911d28f5505e2a408f18ce95eb76a3b7ff90c62ae0307fe7619ea3fc6dbd
 SHA512:
-  metadata.gz: '07392bb0a496168eac6d7c920b681071381feff7e1ebeb4d9d500b344fa48f7aa16bc5e8f47f571c5b4f12d7d3b802e435537f8b2954ac5d192f47f942b8f581'
-  data.tar.gz: 3efdae723a41f72409328e153f12a97a4927da1935b646c3155ae9f1627b02d49ea779b82a1be1ea4534e84fa63d545165042eff6c616a051e1937cdcd0f8890
+  metadata.gz: 77d86be72792de16016414d236bb7d57922c3c26a72313995dd06e5717870102e1e9caceaf0489088f4cf23fa962efbfbf99fd48360d0f045ea742e5358347dc
+  data.tar.gz: 2526ee2574c05330d478b8c351ae217e89a78daa0286ffdf8114f9584a30092ab5bfdf91b5b7f08a0f661755c256f814745806c04d500a36f19042096146311c

data/README.md

@@ -1,20 +1,276 @@
+# Shikikit
+Ruby toolkit for the [Shikimori](https://shikimori.one)
+
 [![CI](https://github.com/iwdt/shikikit/actions/workflows/main.yml/badge.svg)](https://github.com/iwdt/shikikit/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/iwdt/shikikit/graph/badge.svg)](https://codecov.io/gh/iwdt/shikikit)
 
-# Shikikit
-Ruby toolkit for the [Shikimori API](https://shikimori.one)
-
-## TODO:
-- logger
-- #as_app
-- proxy config
-- oauth methods on API
-- optional auto refresh token
-- more information at errors
-- more tests
-- entities for responses
-- contracts for requests (client-side validations)
-- better documentation
-- mutator
-- CI/CD
-- auto version increment on main branch pushing
-- deploy to rubygems
+## Table of Contents
+1. [API Documentation](#api-documentation)
+2. [Omniauth Strategy](#omniauth-shikimori-strategy)
+   1. [Installation](#installation)
+   2. [Configuration](#configuration)
+   3. [Usage](#usage-examples)
+3. [OAuth2](#shikimori-oauth-2)
+   1. [Installation](#installation-1)
+   2. [Configuration](#configuration-1)
+   3. [Usage](#usage)
+4. [API Client](#shikimori-api)
+   1. [Installation](#installation-2)
+   3. [Usage](#usage-1)
+5. [Supported Ruby Versions](#supported-ruby-versions)
+6. [Versioning](#versioning)
+7. [Contributing](/CONTRIBUTING.md)
+8. [Code of conduct](/CODE_OF_CONDUCT.md)
+9. [License](/LICENSE.txt)
+
+## API Documentation
+
+* [Shikimori API](https://www.rubydoc.info/gems/shikimori-api)
+* [Shikimori OAuth2](https://www.rubydoc.info/gems/shikimori-oauth2)
+* [Omniauth Shikimori Strategy](https://www.rubydoc.info/gems/omniauth-shikimori-oauth2)
+
+## Omniauth Shikimori Strategy
+
+Strategy to authenticate with Shikimori via OAuth2 in OmniAuth. To use it, you'll need to sign up for an OAuth2 Application ID and Secret on the [Shikimori OAuth Apps Page](https://shikimori.one/oauth/applications).
+
+Shikimori's official guide to using OAuth2: https://shikimori.one/oauth
+
+[![Gem Version](https://badge.fury.io/rb/omniauth-shikimori-oauth2.svg)](https://rubygems.org/gems/omniauth-shikimori-oauth2)
+
+### Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'omniauth-shikimori-oauth2', '~> 1.0'
+```
+
+Then `bundle install`
+
+### Configuration
+
+You can configure several options, which you pass in to the `provider` method via a `Hash`:
+
+* `app_name`: the name of the registered OAuth application at https://shikimori.one/oauth/applications
+   > **⚠ WARNING!**
+   > This is an important option that must be specified, as otherwise your IP may be banned for further requests to Shikimori.
+
+* `scope`: required list of access permissions you want to request from the user. Available values:
+   - `user_rates` - modify your list of anime and manga.
+   - `messages` - read your personal messages, send personal messages on your behalf.
+   - `comments` - comment on behalf of you.
+   - `topics` - create topics and reviews on your behalf.
+   - `content` - modify the website's database.
+   - `clubs` - join and leave clubs.
+   - `friends` - add and remove people as friends.
+   - `ignores` - add and remove people to ignore.
+
+* `client_options`: optional `Hash` of client options. Available options:
+   - `site` - the OAuth2 provider site host. Default: `https://shikimori.one`
+   - `redirect_uri` - the absolute URI to the Redirection Endpoint for use in authorization grants and token exchange.
+   - `authorize_url` - absolute or relative URL path to the Authorization endpoint. Default: `/oauth/authorize`
+   - `token_url` - absolute or relative URL path to the Token endpoint. Default: `/oauth/token`
+   - `token_method` - HTTP method to use to request token (`:get`, `:post`, `:post_with_query_string`). Default: `:post`
+   - `auth_scheme` - HTTP method to use to authorize request (`:basic_auth` or `:request_body`). Default: `:basic_auth`
+   - `connection_opts` - `Hash` of connection options to pass to initialize `Faraday` with. Default: `{}`
+   - `max_redirects` - maximum number of redirects to follow. Default: `5`
+   - `raise_errors` - whether or not to raise an `OAuth2::Error` on responses with 400+ status codes. Default: `true`
+   - `logger` - which logger to use when `OAUTH_DEBUG` is enabled. Default: `::Logger.new($stdout)`
+
+Here's an example of a possible configuration:
+
+```ruby
+provider :shikimori, ENV['SHIKIMORI_KEY'], ENV['SHIKIMORI_KEY'],
+         scope: %w[user_rates messages comments topics content clubs friends ignores],
+         app_name: 'My awesome site',
+         client_options: {
+            site: 'https://shikimori.org',
+            redirect_url: 'https://my-awesome-site.example/auth/shikimori/callback',
+            logger: Rails.logger
+         }
+```
+
+### Usage examples
+#### Rails usage
+In `config/initializers/omniauth.rb`
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+   provider :shikimori, ENV['SHIKIMORI_KEY'], ENV['SHIKIMORI_KEY'],
+            scope: %w[user_rates comments topics],
+            app_name: ENV['SHIKIMORI_APP_NAME'],
+            client_options: {
+               redirect_url: 'https://my-awesome-site.example/auth/shikimori/callback',
+               logger: Rails.logger
+            }
+end
+```
+
+#### Non-rails usage
+Add middleware to your rack-based application:
+
+```ruby
+use OmniAuth::Builder do
+   provider :shikimori, ENV['SHIKIMORI_KEY'], ENV['SHIKIMORI_SECRET'],
+            scope: %w[user_rates comments topics],
+            app_name: ENV['SHIKIMORI_APP_NAME'],
+            client_options: {
+               redirect_url: 'https://my-awesome-site.example/auth/shikimori/callback'
+            }
+end
+```
+
+## Shikimori OAuth 2
+
+A Ruby wrapper for the [Shikimori's OAuth 2](https://shikimori.one/oauth)
+
+[![Gem Version](https://badge.fury.io/rb/shikimori-oauth2.svg)](https://rubygems.org/gems/shikimori-oauth2)
+
+
+### Installation
+
+Install via Rubygems
+
+```bash
+gem install shikimori-oauth2
+```
+
+... or add to your Gemfile
+
+```ruby
+gem 'shikimori-oauth2', '~> 1.0'
+```
+
+Access the library in Ruby:
+
+```ruby
+require 'shikimori-oauth2'
+```
+
+### Configuration
+
+While `Shikimori::OAuth2::Client` accepts a range of options when creating a new client instance, Shikimori's configuration API allows you to set your configuration options at the module level. This is particularly handy if you're creating a number of client instances based on some shared defaults. Changing options affects new instances only and will not modify existing `Shikimori::OAuth2::Client` instances created with previous options.
+
+Configuring module defaults
+
+Every writable attribute in `Shikimori::OAuth2::Config` can be set in batch:
+
+```ruby
+Shikimori::Oauth2.configure do |c|
+  c.site = 'https://shikimori.one/'
+  c.app_name = 'My awesome site'
+  c.options = {
+   redirect_uri: 'https://my-awesome-site.example/auth/shikimori/callback',
+   authorize_url: '/oauth/authorize',
+   token_url: '/oauth/token',
+   token_method: :post,
+   auth_scheme: :basic_auth,
+   connection_opts: {},
+   max_redirects: 5,
+   raise_errors: true,
+   logger: ::Logger.new($stdout),
+  }
+end
+```
+
+Also available global options from [OAuth2 gem](https://gitlab.com/oauth-xx/oauth2#global-configuration).
+
+### Usage
+
+To get access and refresh tokens, follow this example:
+
+```ruby
+require 'shikimori-oauth2'
+
+client = Shikimori::OAuth2::Client.new('client_id', 'client_secret', app_name: 'Api test')
+client.auth_code.authorize_url(scope: 'user_rates+comments+topics', redirect_uri: 'urn:ietf:wg:oauth:2.0:oob')
+#=> https://shikimori.one/oauth/authorize?client_id=client_id&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&scope=user_rates+comments+topics
+#=> Open this link at browser and copy code
+
+access = client.auth_code.get_token('authorization_code_value', redirect_uri: 'urn:ietf:wg:oauth:2.0:oob')
+
+access.token #=> Access token
+access.refresh_token #=> Refresh token
+access.expires_in #=> 86400
+access.expires_at #=> 1708887613
+```
+
+## Shikimori API
+
+Simple wrapper for the Shikimori API
+
+[![Gem Version](https://badge.fury.io/rb/shikimori-api.svg)](https://rubygems.org/gems/shikimori-api)
+
+### Installation
+
+Install via Rubygems
+
+```bash
+gem install shikimori-api
+```
+
+... or add to your Gemfile
+
+```ruby
+gem 'shikimori-api', '~> 1.0'
+```
+
+Access the library in Ruby:
+
+```ruby
+require 'shikimori-api'
+```
+
+### Usage
+
+API methods are accessible as instance methods of the `Shikimori::API::Client`. Documentation is available at RubyDoc.info:
+* [V1 methods](https://www.rubydoc.info/gems/shikimori-api/Shikimori/API/V1)
+* [V2 methods](https://www.rubydoc.info/gems/shikimori-api/Shikimori/API/V2)
+
+### Examples
+
+Basic example to get 10 random anime titles released in the 90s
+
+```ruby
+client = Shikimori::API::Client.new
+client.v1.animes(limit: 10, order: 'random', season: '199x') # call /api/animes
+```
+
+To provide authentication credentials, you can pass them as arguments during client initialization:
+
+```ruby
+access_token = 'access_token' #=> User's access token
+refresh_token = 'refresh_token' #=> User's refresh token
+oauth_app_name = 'Api Test' #=> OAuth2 application name
+
+client = Shikimori::API::Client.new(app_name: oauth_app_name, access_token: access_token, refresh_token: refresh_token)
+client.v1.whoami
+```
+
+For passing additional query parameters to request use the following syntax:
+
+```ruby
+client.v1.animes(limit: 10, page: 2, another_param: 'Param')
+client.v1.anime_videos(anime_id, first_param: 1, second_param: 2)
+```
+
+... and for request headers use the following syntax:
+
+```ruby
+client.v1.animes(headers: { 'X-Header-Name' => 'My header value' })
+```
+
+## Supported Ruby Versions
+This library aims to support and is tested against the following Ruby implementations:
+* Ruby 3.0
+* Ruby 3.1
+* Ruby 3.2
+* Ruby 3.3
+
+If something doesn't work on one of these Ruby versions, it's a bug.
+
+This library may inadvertently work (or seem to work) on other Ruby implementations, but support will only be provided for the versions listed above.
+
+If you would like this library to support another Ruby version, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.
+
+## Versioning
+This library aims to adhere to [Semantic Versioning 2.0.0](http://semver.org/). Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions. As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision.

data/lib/omniauth/shikimori/version.rb

@@ -3,6 +3,6 @@
 module OmniAuth
   module Shikimori
     # @return [String] Semantic version of library
-    VERSION = '1.0.0'
+    VERSION = '1.0.1'
   end
 end

data/omniauth-shikimori-oauth2.gemspec

@@ -14,11 +14,9 @@ Gem::Specification.new do |spec|
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 3.0'
 
-  spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   spec.metadata['source_code_uri'] = 'https://github.com/iwdt/shikikit'
   spec.metadata['bug_tracker_uri'] = 'https://github.com/iwdt/shikikit/issues'
-  spec.metadata['changelog_uri'] = 'https://github.com/iwdt/shikikit/blob/main/CHANGELOG.md'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir[
@@ -37,5 +35,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'omniauth-oauth2', '~> 1.8'
-  spec.add_dependency 'shikimori-oauth2', '~> 1.0.0'
+  spec.add_dependency 'shikimori-oauth2', '~> 1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-shikimori-oauth2
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Ivan Naumov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-02-22 00:00:00.000000000 Z
+date: 2024-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: omniauth-oauth2
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '1.0'
 description: Strategy to authenticate with Shikimori via OAuth2 in OmniAuth.
 email:
 - ivannaymov@gmail.com
@@ -59,11 +59,9 @@ homepage: https://github.com/iwdt/shikikit
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/iwdt/shikikit
   allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/iwdt/shikikit
   bug_tracker_uri: https://github.com/iwdt/shikikit/issues
-  changelog_uri: https://github.com/iwdt/shikikit/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []