Merge #442

442: feat: fixed for the issue (#440) r=myConsciousness a=myConsciousness

# 1. Description

<!-- Provide a description of what this PR is doing.
If you're modifying existing behavior, describe the existing behavior, how this PR is changing it,
and what motivated the change. If this is a breaking change, specify explicitly which APIs have been
changed. -->

## 1.1. Checklist

<!-- Before you create this PR confirm that it meets all requirements listed below by checking the
relevant checkboxes (`[x]`). This will ensure a smooth and quick review process. -->

- [x] The title of my PR starts with a [Conventional Commit] prefix (`fix:`, `feat:`, `docs:` etc).
- [x] I have read the [Contributor Guide] and followed the process outlined for submitting PRs.
- [x] I have updated/added tests for ALL new/updated/fixed functionality.
- [x] I have updated/added relevant documentation in `docs` and added dartdoc comments with `///`.
- [x] I have updated/added relevant examples in `examples`.

## 1.2. Breaking Change

<!-- Does your PR require users to manually update their apps to accommodate your change?

If the PR is a breaking change this should be indicated with suffix "!"  (for example, `feat!:`, `fix!:`). See [Conventional Commit] for details.
-->

- [x] Yes, this is a breaking change.
- [ ] No, this is _not_ a breaking change.

## 1.3. Related Issues

<!-- Provide a list of issues related to this PR from the [issue database].
Indicate which of these issues are resolved or fixed by this PR, i.e. Fixes #xxxx* !-->

<!-- Links -->

[issue database]: https://github.com/twitter-dart/twitter-api-v2/issues
[contributor guide]: https://github.com/twitter-dart/twitter-api-v2/blob/main/CONTRIBUTING.md
[style guide]: https://github.com/twitter-dart/twitter-api-v2/blob/main/STYLEGUIDE.md
[conventional commit]: https://conventionalcommits.org


Co-authored-by: myConsciousness <[email protected]>
Co-authored-by: KATO, Shinya / 加藤 真也 <[email protected]>

CHANGELOG.md

@@ -1,5 +1,64 @@
 # Release Note
 
+## v4.0.0
+
+### New Feature
+
+- Supported the feature for getting the rate limit of each endpoints from response. Now you can get `RateLimit` object from response and it has `limitCount`, `remainingCount` and `resetAt` fields. ([#440](https://github.com/twitter-dart/twitter-api-v2/issues/440))
+
+### Destructive Change
+
+- It was necessary to modify the response structure for endpoints that use `Stream` to include a `RateLimit` object in each endpoint response. The modified methods are following.
+  - `connectVolumeStream`
+  - `connectFilteredStream`
+
+- Also, methods that previously returned the result of processing as a `bool` have been modified to return a `TwitterResponse`. This is to have a `RateLimit` object as above. So, for example, the `createLike` method can also obtain a `RateLimit` object, and the `bool` value of the processing result can be obtained from the TwitterResponse's `data` field.
+
+And now the responses from the modified methods can be used as follows:
+
+```dart
+import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;
+
+Future<void> main() async {
+  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');
+
+  try {
+    final response = await twitter.tweetsService.connectFilteredStream();
+    print(response.rateLimit);
+
+    final stream = response.stream;
+    await for (final event in stream.handleError(print)) {
+      print(event);
+    }
+  } on v2.TwitterException catch (e) {
+    print(e);
+  }
+}
+```
+
+```dart
+import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;
+
+Future<void> main() async {
+  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');
+
+  try {
+    final me = await twitter.usersService.lookupMe();
+    final tweets = await twitter.tweetsService.searchRecent(query: '#ElonMusk');
+
+    final response = await twitter.tweetsService.createLike(
+      userId: me.data.id,
+      tweetId: tweets.data.first.id,
+    );
+
+    print(response.rateLimit);
+    print(response.data); // true or false
+  } on v2.TwitterException catch (e) {
+    print(e);
+  }
+}
+```
+
 ## v3.2.3
 
 - Refactored the internal process for `MediaService`.

README.md

@@ -216,7 +216,7 @@ Future<void> main() async {
 
     // High-performance Volume Stream endpoint is available.
     final volumeStream = await twitter.tweetsService.connectVolumeStream();
-    await for (final response in volumeStream.handleError(print)) {
+    await for (final response in volumeStream.stream.handleError(print)) {
       print(response);
     }
 
@@ -230,7 +230,7 @@ Future<void> main() async {
     );
 
     final filteredStream = await twitter.tweetsService.connectFilteredStream();
-    await for (final response in filteredStream.handleError(print)) {
+    await for (final response in filteredStream.stream.handleError(print)) {
       print(response.data);
       print(response.matchingRules);
     }

example/example.dart

@@ -73,7 +73,7 @@ Future<void> main() async {
 
     // High-performance Volume Stream endpoint is available.
     final volumeStream = await twitter.tweetsService.connectVolumeStream();
-    await for (final response in volumeStream.handleError(print)) {
+    await for (final response in volumeStream.stream.handleError(print)) {
       print(response);
     }
 
@@ -87,7 +87,7 @@ Future<void> main() async {
     );
 
     final filteredStream = await twitter.tweetsService.connectFilteredStream();
-    await for (final response in filteredStream.handleError(print)) {
+    await for (final response in filteredStream.stream.handleError(print)) {
       print(response.data);
       print(response.matchingRules);
     }

i18n/README-BN.md

@@ -174,7 +174,7 @@ Future<void> main() async {
 
     // উচ্চ ক্ষমতা সম্পন্ন ভলিউম স্ট্রীম এন্ডপয়েন্ট পাওয়া যায়।
     final volumeStream = await twitter.tweetsService.connectVolumeStream();
-    await for (final response in volumeStream.handleError(print)) {
+    await for (final response in volumeStream.stream.handleError(print)) {
       print(response);
     }
 
@@ -188,7 +188,7 @@ Future<void> main() async {
     );
 
     final filteredStream = await twitter.tweetsService.connectFilteredStream();
-    await for (final response in filteredStream.handleError(print)) {
+    await for (final response in filteredStream.stream.handleError(print)) {
       print(response.data);
       print(response.matchingRules);
     }

i18n/README-DE.md

@@ -186,7 +186,7 @@ Future<void> main() async {
 
     // Ein hoch-performanter Volume Stream Endpunkt kann wie folgt verwendet werden:
     final volumeStream = await twitter.tweetsService.connectVolumeStream();
-    await for (final response in volumeStream.handleError(print)) {
+    await for (final response in volumeStream.stream.handleError(print)) {
       print(response);
     }
 
@@ -200,7 +200,7 @@ Future<void> main() async {
     );
 
     final filteredStream = await twitter.tweetsService.connectFilteredStream();
-    await for (final response in filteredStream.handleError(print)) {
+    await for (final response in filteredStream.stream.handleError(print)) {
       print(response.data);
       print(response.matchingRules);
     }

i18n/README-ES.md

@@ -184,7 +184,7 @@ Future<void> main() async {
 
     // El punto final de flujo de volumen de alto rendimiento está disponible.
     final volumeStream = await twitter.tweetsService.connectVolumeStream();
-    await for (final response in volumeStream.handleError(print)) {
+    await for (final response in volumeStream.stream.handleError(print)) {
       print(response);
     }
 
@@ -198,7 +198,7 @@ Future<void> main() async {
     );
 
     final filteredStream = await twitter.tweetsService.connectFilteredStream();
-    await for (final response in filteredStream.handleError(print)) {
+    await for (final response in filteredStream.stream.handleError(print)) {
       print(response.data);
       print(response.matchingRules);
     }

i18n/README-FR.md

@@ -173,7 +173,7 @@ Future<void> main() async {
 
     // High-performance Volume Stream endpoint is available.
     final volumeStream = await twitter.tweetsService.connectVolumeStream();
-    await for (final response in volumeStream.handleError(print)) {
+    await for (final response in volumeStream.stream.handleError(print)) {
       print(response);
     }
 
@@ -187,7 +187,7 @@ Future<void> main() async {
     );
 
     final filteredStream = await twitter.tweetsService.connectFilteredStream();
-    await for (final response in filteredStream.handleError(print)) {
+    await for (final response in filteredStream.stream.handleError(print)) {
       print(response.data);
       print(response.matchingRules);
     }

i18n/README-JA.md

@@ -171,7 +171,7 @@ Future<void> main() async {
 
     // 高性能なVolume Streamエンドポイントを利用可能です。
     final volumeStream = await twitter.tweetsService.connectVolumeStream();
-    await for (final response in volumeStream.handleError(print)) {
+    await for (final response in volumeStream.stream.handleError(print)) {
       print(response);
     }
 
@@ -185,7 +185,7 @@ Future<void> main() async {
     );
 
     final filteredStream = await twitter.tweetsService.connectFilteredStream();
-    await for (final response in filteredStream.handleError(print)) {
+    await for (final response in filteredStream.stream.handleError(print)) {
       print(response.data);
       print(response.matchingRules);
     }