shikimori-oauth2 1.0.0 → 1.0.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +274 -18
- data/lib/shikimori/oauth2/version.rb +1 -1
- data/shikimori-oauth2.gemspec +0 -2
- metadata +2 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 61fabe8c9a03a10986a316e7c038192eeb2ba5b5651c573294244316fd830af1
|
4
|
+
data.tar.gz: caae2231a7c712b08b777c728398778b63386190f261ef4978babded080ef1d2
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 82bf94c041021a1ce6b848f101866010b80e5bf4caa2cf3243a12af3561866952ed2dc2f87a8802c40dd8b13f30f8002c0208464d7c9c2c577051bfa06825c68
|
7
|
+
data.tar.gz: 522e16771bf51a4c5d25fdd810a576c4820a047a0a35b246a05d3eeeb60c128d10ef61ef9d072e9cf1c0d85afb94ef9fd0d7e6c409189e3c42885d832b7ea955
|
data/README.md
CHANGED
@@ -1,20 +1,276 @@
|
|
1
|
+
# Shikikit
|
2
|
+
Ruby toolkit for the [Shikimori](https://shikimori.one)
|
3
|
+
|
1
4
|
[![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)
|
2
5
|
|
3
|
-
|
4
|
-
|
5
|
-
|
6
|
-
|
7
|
-
|
8
|
-
|
9
|
-
-
|
10
|
-
-
|
11
|
-
-
|
12
|
-
|
13
|
-
|
14
|
-
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
6
|
+
## Table of Contents
|
7
|
+
1. [API Documentation](#api-documentation)
|
8
|
+
2. [Omniauth Strategy](#omniauth-shikimori-strategy)
|
9
|
+
1. [Installation](#installation)
|
10
|
+
2. [Configuration](#configuration)
|
11
|
+
3. [Usage](#usage-examples)
|
12
|
+
3. [OAuth2](#shikimori-oauth-2)
|
13
|
+
1. [Installation](#installation-1)
|
14
|
+
2. [Configuration](#configuration-1)
|
15
|
+
3. [Usage](#usage)
|
16
|
+
4. [API Client](#shikimori-api)
|
17
|
+
1. [Installation](#installation-2)
|
18
|
+
3. [Usage](#usage-1)
|
19
|
+
5. [Supported Ruby Versions](#supported-ruby-versions)
|
20
|
+
6. [Versioning](#versioning)
|
21
|
+
7. [Contributing](/CONTRIBUTING.md)
|
22
|
+
8. [Code of conduct](/CODE_OF_CONDUCT.md)
|
23
|
+
9. [License](/LICENSE.txt)
|
24
|
+
|
25
|
+
## API Documentation
|
26
|
+
|
27
|
+
* [Shikimori API](https://www.rubydoc.info/gems/shikimori-api)
|
28
|
+
* [Shikimori OAuth2](https://www.rubydoc.info/gems/shikimori-oauth2)
|
29
|
+
* [Omniauth Shikimori Strategy](https://www.rubydoc.info/gems/omniauth-shikimori-oauth2)
|
30
|
+
|
31
|
+
## Omniauth Shikimori Strategy
|
32
|
+
|
33
|
+
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).
|
34
|
+
|
35
|
+
Shikimori's official guide to using OAuth2: https://shikimori.one/oauth
|
36
|
+
|
37
|
+
[![Gem Version](https://badge.fury.io/rb/omniauth-shikimori-oauth2.svg)](https://rubygems.org/gems/omniauth-shikimori-oauth2)
|
38
|
+
|
39
|
+
### Installation
|
40
|
+
|
41
|
+
Add to your `Gemfile`:
|
42
|
+
|
43
|
+
```ruby
|
44
|
+
gem 'omniauth-shikimori-oauth2', '~> 1.0'
|
45
|
+
```
|
46
|
+
|
47
|
+
Then `bundle install`
|
48
|
+
|
49
|
+
### Configuration
|
50
|
+
|
51
|
+
You can configure several options, which you pass in to the `provider` method via a `Hash`:
|
52
|
+
|
53
|
+
* `app_name`: the name of the registered OAuth application at https://shikimori.one/oauth/applications
|
54
|
+
> **⚠ WARNING!**
|
55
|
+
> This is an important option that must be specified, as otherwise your IP may be banned for further requests to Shikimori.
|
56
|
+
|
57
|
+
* `scope`: required list of access permissions you want to request from the user. Available values:
|
58
|
+
- `user_rates` - modify your list of anime and manga.
|
59
|
+
- `messages` - read your personal messages, send personal messages on your behalf.
|
60
|
+
- `comments` - comment on behalf of you.
|
61
|
+
- `topics` - create topics and reviews on your behalf.
|
62
|
+
- `content` - modify the website's database.
|
63
|
+
- `clubs` - join and leave clubs.
|
64
|
+
- `friends` - add and remove people as friends.
|
65
|
+
- `ignores` - add and remove people to ignore.
|
66
|
+
|
67
|
+
* `client_options`: optional `Hash` of client options. Available options:
|
68
|
+
- `site` - the OAuth2 provider site host. Default: `https://shikimori.one`
|
69
|
+
- `redirect_uri` - the absolute URI to the Redirection Endpoint for use in authorization grants and token exchange.
|
70
|
+
- `authorize_url` - absolute or relative URL path to the Authorization endpoint. Default: `/oauth/authorize`
|
71
|
+
- `token_url` - absolute or relative URL path to the Token endpoint. Default: `/oauth/token`
|
72
|
+
- `token_method` - HTTP method to use to request token (`:get`, `:post`, `:post_with_query_string`). Default: `:post`
|
73
|
+
- `auth_scheme` - HTTP method to use to authorize request (`:basic_auth` or `:request_body`). Default: `:basic_auth`
|
74
|
+
- `connection_opts` - `Hash` of connection options to pass to initialize `Faraday` with. Default: `{}`
|
75
|
+
- `max_redirects` - maximum number of redirects to follow. Default: `5`
|
76
|
+
- `raise_errors` - whether or not to raise an `OAuth2::Error` on responses with 400+ status codes. Default: `true`
|
77
|
+
- `logger` - which logger to use when `OAUTH_DEBUG` is enabled. Default: `::Logger.new($stdout)`
|
78
|
+
|
79
|
+
Here's an example of a possible configuration:
|
80
|
+
|
81
|
+
```ruby
|
82
|
+
provider :shikimori, ENV['SHIKIMORI_KEY'], ENV['SHIKIMORI_KEY'],
|
83
|
+
scope: %w[user_rates messages comments topics content clubs friends ignores],
|
84
|
+
app_name: 'My awesome site',
|
85
|
+
client_options: {
|
86
|
+
site: 'https://shikimori.org',
|
87
|
+
redirect_url: 'https://my-awesome-site.example/auth/shikimori/callback',
|
88
|
+
logger: Rails.logger
|
89
|
+
}
|
90
|
+
```
|
91
|
+
|
92
|
+
### Usage examples
|
93
|
+
#### Rails usage
|
94
|
+
In `config/initializers/omniauth.rb`
|
95
|
+
|
96
|
+
```ruby
|
97
|
+
Rails.application.config.middleware.use OmniAuth::Builder do
|
98
|
+
provider :shikimori, ENV['SHIKIMORI_KEY'], ENV['SHIKIMORI_KEY'],
|
99
|
+
scope: %w[user_rates comments topics],
|
100
|
+
app_name: ENV['SHIKIMORI_APP_NAME'],
|
101
|
+
client_options: {
|
102
|
+
redirect_url: 'https://my-awesome-site.example/auth/shikimori/callback',
|
103
|
+
logger: Rails.logger
|
104
|
+
}
|
105
|
+
end
|
106
|
+
```
|
107
|
+
|
108
|
+
#### Non-rails usage
|
109
|
+
Add middleware to your rack-based application:
|
110
|
+
|
111
|
+
```ruby
|
112
|
+
use OmniAuth::Builder do
|
113
|
+
provider :shikimori, ENV['SHIKIMORI_KEY'], ENV['SHIKIMORI_SECRET'],
|
114
|
+
scope: %w[user_rates comments topics],
|
115
|
+
app_name: ENV['SHIKIMORI_APP_NAME'],
|
116
|
+
client_options: {
|
117
|
+
redirect_url: 'https://my-awesome-site.example/auth/shikimori/callback'
|
118
|
+
}
|
119
|
+
end
|
120
|
+
```
|
121
|
+
|
122
|
+
## Shikimori OAuth 2
|
123
|
+
|
124
|
+
A Ruby wrapper for the [Shikimori's OAuth 2](https://shikimori.one/oauth)
|
125
|
+
|
126
|
+
[![Gem Version](https://badge.fury.io/rb/shikimori-oauth2.svg)](https://rubygems.org/gems/shikimori-oauth2)
|
127
|
+
|
128
|
+
|
129
|
+
### Installation
|
130
|
+
|
131
|
+
Install via Rubygems
|
132
|
+
|
133
|
+
```bash
|
134
|
+
gem install shikimori-oauth2
|
135
|
+
```
|
136
|
+
|
137
|
+
... or add to your Gemfile
|
138
|
+
|
139
|
+
```ruby
|
140
|
+
gem 'shikimori-oauth2', '~> 1.0'
|
141
|
+
```
|
142
|
+
|
143
|
+
Access the library in Ruby:
|
144
|
+
|
145
|
+
```ruby
|
146
|
+
require 'shikimori-oauth2'
|
147
|
+
```
|
148
|
+
|
149
|
+
### Configuration
|
150
|
+
|
151
|
+
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.
|
152
|
+
|
153
|
+
Configuring module defaults
|
154
|
+
|
155
|
+
Every writable attribute in `Shikimori::OAuth2::Config` can be set in batch:
|
156
|
+
|
157
|
+
```ruby
|
158
|
+
Shikimori::Oauth2.configure do |c|
|
159
|
+
c.site = 'https://shikimori.one/'
|
160
|
+
c.app_name = 'My awesome site'
|
161
|
+
c.options = {
|
162
|
+
redirect_uri: 'https://my-awesome-site.example/auth/shikimori/callback',
|
163
|
+
authorize_url: '/oauth/authorize',
|
164
|
+
token_url: '/oauth/token',
|
165
|
+
token_method: :post,
|
166
|
+
auth_scheme: :basic_auth,
|
167
|
+
connection_opts: {},
|
168
|
+
max_redirects: 5,
|
169
|
+
raise_errors: true,
|
170
|
+
logger: ::Logger.new($stdout),
|
171
|
+
}
|
172
|
+
end
|
173
|
+
```
|
174
|
+
|
175
|
+
Also available global options from [OAuth2 gem](https://gitlab.com/oauth-xx/oauth2#global-configuration).
|
176
|
+
|
177
|
+
### Usage
|
178
|
+
|
179
|
+
To get access and refresh tokens, follow this example:
|
180
|
+
|
181
|
+
```ruby
|
182
|
+
require 'shikimori-oauth2'
|
183
|
+
|
184
|
+
client = Shikimori::OAuth2::Client.new('client_id', 'client_secret', app_name: 'Api test')
|
185
|
+
client.auth_code.authorize_url(scope: 'user_rates+comments+topics', redirect_uri: 'urn:ietf:wg:oauth:2.0:oob')
|
186
|
+
#=> 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
|
187
|
+
#=> Open this link at browser and copy code
|
188
|
+
|
189
|
+
access = client.auth_code.get_token('authorization_code_value', redirect_uri: 'urn:ietf:wg:oauth:2.0:oob')
|
190
|
+
|
191
|
+
access.token #=> Access token
|
192
|
+
access.refresh_token #=> Refresh token
|
193
|
+
access.expires_in #=> 86400
|
194
|
+
access.expires_at #=> 1708887613
|
195
|
+
```
|
196
|
+
|
197
|
+
## Shikimori API
|
198
|
+
|
199
|
+
Simple wrapper for the Shikimori API
|
200
|
+
|
201
|
+
[![Gem Version](https://badge.fury.io/rb/shikimori-api.svg)](https://rubygems.org/gems/shikimori-api)
|
202
|
+
|
203
|
+
### Installation
|
204
|
+
|
205
|
+
Install via Rubygems
|
206
|
+
|
207
|
+
```bash
|
208
|
+
gem install shikimori-api
|
209
|
+
```
|
210
|
+
|
211
|
+
... or add to your Gemfile
|
212
|
+
|
213
|
+
```ruby
|
214
|
+
gem 'shikimori-api', '~> 1.0'
|
215
|
+
```
|
216
|
+
|
217
|
+
Access the library in Ruby:
|
218
|
+
|
219
|
+
```ruby
|
220
|
+
require 'shikimori-api'
|
221
|
+
```
|
222
|
+
|
223
|
+
### Usage
|
224
|
+
|
225
|
+
API methods are accessible as instance methods of the `Shikimori::API::Client`. Documentation is available at RubyDoc.info:
|
226
|
+
* [V1 methods](https://www.rubydoc.info/gems/shikimori-api/Shikimori/API/V1)
|
227
|
+
* [V2 methods](https://www.rubydoc.info/gems/shikimori-api/Shikimori/API/V2)
|
228
|
+
|
229
|
+
### Examples
|
230
|
+
|
231
|
+
Basic example to get 10 random anime titles released in the 90s
|
232
|
+
|
233
|
+
```ruby
|
234
|
+
client = Shikimori::API::Client.new
|
235
|
+
client.v1.animes(limit: 10, order: 'random', season: '199x') # call /api/animes
|
236
|
+
```
|
237
|
+
|
238
|
+
To provide authentication credentials, you can pass them as arguments during client initialization:
|
239
|
+
|
240
|
+
```ruby
|
241
|
+
access_token = 'access_token' #=> User's access token
|
242
|
+
refresh_token = 'refresh_token' #=> User's refresh token
|
243
|
+
oauth_app_name = 'Api Test' #=> OAuth2 application name
|
244
|
+
|
245
|
+
client = Shikimori::API::Client.new(app_name: oauth_app_name, access_token: access_token, refresh_token: refresh_token)
|
246
|
+
client.v1.whoami
|
247
|
+
```
|
248
|
+
|
249
|
+
For passing additional query parameters to request use the following syntax:
|
250
|
+
|
251
|
+
```ruby
|
252
|
+
client.v1.animes(limit: 10, page: 2, another_param: 'Param')
|
253
|
+
client.v1.anime_videos(anime_id, first_param: 1, second_param: 2)
|
254
|
+
```
|
255
|
+
|
256
|
+
... and for request headers use the following syntax:
|
257
|
+
|
258
|
+
```ruby
|
259
|
+
client.v1.animes(headers: { 'X-Header-Name' => 'My header value' })
|
260
|
+
```
|
261
|
+
|
262
|
+
## Supported Ruby Versions
|
263
|
+
This library aims to support and is tested against the following Ruby implementations:
|
264
|
+
* Ruby 3.0
|
265
|
+
* Ruby 3.1
|
266
|
+
* Ruby 3.2
|
267
|
+
* Ruby 3.3
|
268
|
+
|
269
|
+
If something doesn't work on one of these Ruby versions, it's a bug.
|
270
|
+
|
271
|
+
This library may inadvertently work (or seem to work) on other Ruby implementations, but support will only be provided for the versions listed above.
|
272
|
+
|
273
|
+
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.
|
274
|
+
|
275
|
+
## Versioning
|
276
|
+
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/shikimori-oauth2.gemspec
CHANGED
@@ -14,11 +14,9 @@ Gem::Specification.new do |spec|
|
|
14
14
|
spec.license = 'MIT'
|
15
15
|
spec.required_ruby_version = '>= 3.0'
|
16
16
|
|
17
|
-
spec.metadata['homepage_uri'] = spec.homepage
|
18
17
|
spec.metadata['allowed_push_host'] = 'https://rubygems.org'
|
19
18
|
spec.metadata['source_code_uri'] = 'https://github.com/iwdt/shikikit'
|
20
19
|
spec.metadata['bug_tracker_uri'] = 'https://github.com/iwdt/shikikit/issues'
|
21
|
-
spec.metadata['changelog_uri'] = 'https://github.com/iwdt/shikikit/blob/main/CHANGELOG.md'
|
22
20
|
spec.metadata['rubygems_mfa_required'] = 'true'
|
23
21
|
|
24
22
|
spec.files = Dir[
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: shikimori-oauth2
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.0.
|
4
|
+
version: 1.0.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Ivan Naumov
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2024-02-
|
11
|
+
date: 2024-02-24 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: oauth2
|
@@ -46,11 +46,9 @@ homepage: https://github.com/iwdt/shikikit
|
|
46
46
|
licenses:
|
47
47
|
- MIT
|
48
48
|
metadata:
|
49
|
-
homepage_uri: https://github.com/iwdt/shikikit
|
50
49
|
allowed_push_host: https://rubygems.org
|
51
50
|
source_code_uri: https://github.com/iwdt/shikikit
|
52
51
|
bug_tracker_uri: https://github.com/iwdt/shikikit/issues
|
53
|
-
changelog_uri: https://github.com/iwdt/shikikit/blob/main/CHANGELOG.md
|
54
52
|
rubygems_mfa_required: 'true'
|
55
53
|
post_install_message:
|
56
54
|
rdoc_options: []
|