docs: add OAuth2 scope documentation and changelog

- Document all 20 available OAuth2 scopes in README
- Add usage examples for custom scope configuration
- Update CHANGELOG with new features
- Include descriptions for users.email and media.write scopes

Author: HolyGrail

CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+### Added
+- Added `AVAILABLE_SCOPES` constant with all supported X (Twitter) OAuth 2.0 scopes
+- Added `DEFAULT_SCOPE` constant set to "tweet.read users.read"
+- Added default `authorize_params` with scope configuration
+- Added `authorize_params` method to handle scope validation and defaults
+- Added comprehensive documentation for available scopes in README
+
+### Changed
+- Scope parameter is now explicitly handled with defaults and validation
+
 ## [0.1.0] - 2022-01-13
 
 - Initial release

README.md

@@ -33,7 +33,46 @@ $ gem install omniauth-twitter2
 ```ruby
 # config/initializers/omniauth.rb
 Rails.application.config.middleware.use OmniAuth::Builder do
-  provider :twitter2, ENV["TWITTER_CLIENT_ID"], ENV["TWITTER_CLIENT_SECRET"], callback_path: '/auth/twitter2/callback', scope: "tweet.read users.read"
+  provider :twitter2, ENV["TWITTER_CLIENT_ID"], ENV["TWITTER_CLIENT_SECRET"], 
+    callback_path: '/auth/twitter2/callback', 
+    scope: "tweet.read users.read"  # Default scope
+end
+```
+
+### Available Scopes
+
+The following OAuth 2.0 scopes are available for X (Twitter) API v2:
+
+- `tweet.read` - All the Tweets you can view, including Tweets from protected accounts.
+- `tweet.write` - Tweet and Retweet for you.
+- `tweet.moderate.write` - Hide and unhide replies to your Tweets.
+- `users.email` - Email from an authenticated user.
+- `users.read` - Any account you can view, including protected accounts.
+- `follows.read` - People who follow you and people who you follow.
+- `follows.write` - Follow and unfollow people for you.
+- `offline.access` - Stay connected to your account until you revoke access.
+- `space.read` - All the Spaces you can view.
+- `mute.read` - Accounts you've muted.
+- `mute.write` - Mute and unmute accounts for you.
+- `like.read` - Tweets you've liked and likes you can view.
+- `like.write` - Like and un-like Tweets for you.
+- `list.read` - Lists, list members, and list followers of lists you've created or are a member of, including private lists.
+- `list.write` - Create and manage Lists for you.
+- `block.read` - Accounts you've blocked.
+- `block.write` - Block and unblock accounts for you.
+- `bookmark.read` - Get Bookmarked Tweets from an authenticated user.
+- `bookmark.write` - Bookmark and remove Bookmarks from Tweets.
+- `media.write` - Upload media.
+
+Default scope is `"tweet.read users.read"` if not specified.
+
+You can customize the scope like this:
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :twitter2, ENV["TWITTER_CLIENT_ID"], ENV["TWITTER_CLIENT_SECRET"],
+    callback_path: '/auth/twitter2/callback',
+    scope: "tweet.read tweet.write users.read offline.access"
 end
 ```