From 71542510edd64822621609e6542fef6dca8ce054 Mon Sep 17 00:00:00 2001 From: Ratakondala Arun Date: Tue, 29 Dec 2020 22:42:59 +0530 Subject: [PATCH 1/6] added documentation --- .gitignore | 1 + lib/gitter_api.dart | 21 ++++++ lib/src/api_keys.dart | 12 ++- lib/src/v1.dart | 14 ++++ lib/src/v1/groups_resource.dart | 18 +++++ lib/src/v1/messages_resource.dart | 66 +++++++++-------- lib/src/v1/rooms_resource.dart | 118 ++++++++++-------------------- lib/src/v1/stream_api.dart | 18 +++-- lib/src/v1/user_resource.dart | 56 ++++++++++++-- pubspec.lock | 37 +++++++++- pubspec.yaml | 1 + 11 files changed, 234 insertions(+), 128 deletions(-) diff --git a/.gitignore b/.gitignore index 08a04c3..4eabe07 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .dart_tool .packages .env +doc \ No newline at end of file diff --git a/lib/gitter_api.dart b/lib/gitter_api.dart index 26c2a81..80073d5 100644 --- a/lib/gitter_api.dart +++ b/lib/gitter_api.dart @@ -19,15 +19,36 @@ part 'src/v1/rooms_resource.dart'; part 'src/v1/stream_api.dart'; part 'src/v1/user_resource.dart'; +/// Core instance of Gitter API. +/// +/// ### Parameters +/// +/// - `keys`: This takes instance of [ApiKeys] which you can use to serve +/// your access token. +/// +/// Checkout the [gitter docs](https://developer.gitter.im/docs/welcome) class GitterApi { + /// API Host. final host = 'api.gitter.im'; + /// Contains accesstoken. final ApiKeys keys; V1 _v1; + /// Version one of this API. + /// This contains all the resources belongs + /// to version 1 of gitter api. V1 get v1 => _v1; + /// Creates a instance of [this] + /// + /// ## Parameters + /// + /// - `keys`: This takes instance of [ApiKeys] which you can use to serve + /// your access token. + /// + /// Checkout the [gitter docs](https://developer.gitter.im/docs/welcome) GitterApi(this.keys) { _v1 = V1(this); } diff --git a/lib/src/api_keys.dart b/lib/src/api_keys.dart index 4f7be24..2b478c8 100644 --- a/lib/src/api_keys.dart +++ b/lib/src/api_keys.dart @@ -1,8 +1,11 @@ part of gitterapi; +/// class ApiKeys { + /// Authorization token required to connect to Gitter API. final String authToken; + /// Creates a instance of [this]. const ApiKeys(this.authToken); /// Returns a instance of [ApiKeys] @@ -10,7 +13,12 @@ class ApiKeys { /// /// This looksup for `AUTH_TOKEN` env variable. /// - factory ApiKeys.fromEnv() { - return ApiKeys(String.fromEnvironment('AUTH_TOKEN')); + /// ### Parameters: + /// + /// - `tokenVar`: Specifies which env variable to look for token. + /// By default it looks for AUTH_TOKEN. + /// + factory ApiKeys.fromEnv({String tokenVar = 'AUTH_TOKEN'}) { + return ApiKeys(String.fromEnvironment(tokenVar)); } } diff --git a/lib/src/v1.dart b/lib/src/v1.dart index 9b6b200..6facbf6 100644 --- a/lib/src/v1.dart +++ b/lib/src/v1.dart @@ -1,5 +1,6 @@ part of gitterapi; +/// Class of version 1 of gitter API class V1 extends Version { UserResource _userResource; RoomsResource _roomsResource; @@ -7,12 +8,23 @@ class V1 extends Version { GroupsResource _groupsResource; StreamApi _streamApi; + /// Serves methods to access [user-resources](https://developer.gitter.im/docs/user-resource). UserResource get userResource => _userResource; + + /// Serves methods to access [rooms-resources](https://developer.gitter.im/docs/rooms-resource). RoomsResource get roomResource => _roomsResource; + + /// Serves methods to access [messages-resources](https://developer.gitter.im/docs/messages-resource). MessagesResource get messageResource => _messagesResource; + + /// Serves methods to access [groups-resources](https://developer.gitter.im/docs/groups-resource). GroupsResource get groupResource => _groupsResource; + + /// The streaming API allows real-time access to rooms. [streaming-api](https://developer.gitter.im/docs/streaming-api). StreamApi get streamApi => _streamApi; + /// Creates a instance of [this]. + /// V1(GitterApi api) : super(api, 'v1') { _userResource = UserResource(this); _roomsResource = RoomsResource(this); @@ -21,6 +33,7 @@ class V1 extends Version { _streamApi = StreamApi(this); } + /// Sends a json request to server and returns [Result]. Future> _jsonRequest( String path, { String method = 'GET', @@ -70,6 +83,7 @@ class V1 extends Version { } } + /// Sends a request and returns [Stream]. Future> _streamRequest( String path, { String method = 'GET', diff --git a/lib/src/v1/groups_resource.dart b/lib/src/v1/groups_resource.dart index 71f45a3..5de1f7d 100644 --- a/lib/src/v1/groups_resource.dart +++ b/lib/src/v1/groups_resource.dart @@ -1,6 +1,8 @@ part of gitterapi; +/// Contains methods for [Group-Resources](https://developer.gitter.im/docs/groups-resource). class GroupsResource extends Resource { + /// Creates a instance of [this]. GroupsResource(V1 v) : super(v, 'groups'); /// List groups the current user is in. @@ -9,11 +11,27 @@ class GroupsResource extends Resource { } /// List of rooms nested under the specified group. + /// + /// ### Parameters: + /// + /// - `groupId`: Id of the group. + /// Future> getRooms(String groupId) { return _v._jsonRequest('$_path/$groupId/rooms'); } /// Create room nested under the specified group. + /// + /// ### Parameters: + /// + /// - `groupId`: Id of the group. + /// - `name`: Room name.W + /// - `topic`: Room topic/description. + /// - `security`: Describes the backing object we get permissions from. (defaults to 'PUBLIC'). + /// - `type`: null|'ONE_TO_ONE'|'GH_REPO'|'GH_ORG'|'GH_USER'. + /// - `linkPath`: Represents how we find the backing object given the type. + /// - `source`: Tracking info for stats. + /// Future> createRoom( String groupId, { String name, diff --git a/lib/src/v1/messages_resource.dart b/lib/src/v1/messages_resource.dart index 8559dc5..14371e6 100644 --- a/lib/src/v1/messages_resource.dart +++ b/lib/src/v1/messages_resource.dart @@ -1,19 +1,22 @@ part of gitterapi; +/// Creates methods for [Messages-resource](https://developer.gitter.im/docs/messages-resource). class MessagesResource extends Resource { MessagesResource(V1 v) : super(v, 'chatMessages'); /// List of messages in a room. /// Returns [List>]. /// - /// ### All the parameters are optional: + /// ### Parameters /// + /// - `roomId`: Id of the room. /// - `skip`: Skip n messages (constrained to 5000 or less). /// - `beforeId`: Get messages before beforeId. /// - `afterId`: Get messages after afterId. /// - `aroundId`: Get messages around aroundId including this message. /// - `limit`: Maximum number of messages to return (constrained to 100 or less). /// - `q`: Search query. + /// Future>> getMessages( String roomId, { int skip, @@ -37,12 +40,20 @@ class MessagesResource extends Resource { } /// There is also a way to retrieve a single message using its id. + /// + /// ### Parameters: + /// + /// - `roomId`: Id of the room. + /// - `messageId`: Id of the message. + /// Future> getSingleMessage(String roomId, String messageId) { return _v._jsonRequest('rooms/$roomId/$_path/$messageId'); } /// Send a message to a room. /// + /// ### Parameters + /// /// - `text`: Required Body of the message. /// - `status`: Boolean, set to true to indicate that the message is a status update (what /me uses) /// @@ -58,41 +69,19 @@ class MessagesResource extends Resource { ); } - /// Update a message. + /// Update + /// + /// ### Parameters /// + /// - `roomId`: Id of the room. + /// - `messageId`: Id of the message. /// - `text`: Required Body of the message. /// - /// ### Response - /// ``` - /// { - /// "id": "533171eb7bfc1a0000000012", - /// "text": "You should also check https://irc.gitter.im/ <3<3<3", - /// "html": "You should also check https://irc.gitter.im/ <3<3<3", - /// "sent": "2014-03-25T12:09:15.292Z", - /// "editedAt": "2014-03-25T12:13:02.985Z", - /// "fromUser": { - /// "id": "53307734c3599d1de448e192", - /// "username": "malditogeek", - /// "displayName": "Mauro Pompilio", - /// "url": "/malditogeek", - /// "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", - /// "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?" - /// }, - /// "unread": false, - /// "readBy": 0, - /// "urls": [ - /// { - /// "url": "https://irc.gitter.im/" - /// } - /// ], - /// "mentions": [], - /// "issues": [], - /// "meta": {}, - /// "v": 2 - /// } - /// ``` Future> updateMessage( - String roomId, String messageId, String text) { + String roomId, + String messageId, + String text, + ) { return _v._jsonRequest( 'rooms/$roomId/$_path/$messageId', method: 'PUT', @@ -104,12 +93,25 @@ class MessagesResource extends Resource { /// You can retrieve unread items and /// mentions using the following endpoint. + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// - `roomId`: Id of the room. + /// Future> getUnreadItems(String userId, String roomId) { return _v._jsonRequest('user/$userId/rooms/$roomId/unreadItems'); } /// There is an additional endpoint nested under /// rooms that you can use to mark chat messages as read. + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// - `roomId`: Id of the room. + /// - `chatIds`: [List] of messageId's you want to mark as unread. + /// Future> markMessagesAsRead( String userId, String roomId, { diff --git a/lib/src/v1/rooms_resource.dart b/lib/src/v1/rooms_resource.dart index ce9a636..4296c9a 100644 --- a/lib/src/v1/rooms_resource.dart +++ b/lib/src/v1/rooms_resource.dart @@ -1,54 +1,19 @@ part of gitterapi; +/// Creates methods for [Rooms-resource](https://developer.gitter.im/docs/rooms-resource). class RoomsResource extends Resource { @override String get _path => 'rooms'; + /// Creates a instance of [this]. RoomsResource(V1 v) : super(v, 'rooms'); /// List rooms the current user is in. /// - /// Returns [List>]. + /// ### Parameters: + /// + /// - `query`: Query to search for rooms. /// - /// ### Response - /// ``` - /// [ - /// { - /// "id": "53307860c3599d1de448e19d", - /// "name": "Andrew Newdigate", - /// "topic": "", - /// "oneToOne": true, - /// "user": { - /// "id": "53307831c3599d1de448e19a", - /// "username": "suprememoocow", - /// "displayName": "Andrew Newdigate", - /// "url": "/suprememoocow", - /// "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?", - /// "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?" - /// }, - /// "unreadItems": 0, - /// "mentions": 0, - /// "lurk": false, - /// "url": "/suprememoocow", - /// "githubType": "ONETOONE" - /// }, - /// { - /// "id": "5330777dc3599d1de448e194", - /// "name": "gitterHQ", - /// "topic": "Gitter", - /// "uri": "gitterHQ", - /// "oneToOne": false, - /// "userCount": 2, - /// "unreadItems": 0, - /// "mentions": 0, - /// "lastAccessTime": "2014-03-24T18:22:28.105Z", - /// "lurk": false, - /// "url": "/gitterHQ", - /// "githubType": "ORG", - /// "v": 1 - /// }, - /// ] - /// ``` Future>> rooms({String query}) { return _v._jsonRequest>( _path, @@ -60,29 +25,33 @@ class RoomsResource extends Resource { // TODO(@RatakondalaArun): Create a room /// Fetches room id from uri. - /// `uri` must not be null. - /// ### Example: + /// + /// ### Parameters + /// + /// - `uri`: Room Uri must not be null. + /// + /// ### Example /// ``` /// String uri = 'gitterhq/sandbox'; /// // remaining code ...... - ///final room = getRoomIdFrom(uri); - /// ``` - /// ### Result: - /// ``` - /// { - /// "id": "52b42a52ed5ab0b3bf051b93", - /// "name": "gitterHQ/sandbox", - /// //... - /// } + /// final room = getRoomIdFrom(uri); /// ``` /// Future> getRoomIdFrom(String uri) { - return _v - ._jsonRequest('$_path', method: 'POST', postData: {'uri': uri}); + return _v._jsonRequest( + '$_path', + method: 'POST', + postData: {'uri': uri}, + ); } /// Join the room via ID. - /// `userId` and `roomId` must not be null + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// - `roomId`: Id of the room. + /// Future> joinRoom(String userId, String roomId) { return _v._jsonRequest( 'user/$userId/$_path', @@ -91,8 +60,13 @@ class RoomsResource extends Resource { ); } - /// Bans the give user form the room - /// `roomId` and `username` must not be null. + /// Bans the give user form the room. + /// user must be a group admin to perform this action. + /// + /// ### Parameters + /// + /// - `roomId`: Id of the room. + /// - `username`: username. must not be null. Future> banUserFromRoom(String roomId, String username) { return _v._jsonRequest( '$_path/$roomId/bans', @@ -102,6 +76,7 @@ class RoomsResource extends Resource { } /// Update room details. + /// user must be group admin to perform this action. /// /// ### Parameters /// @@ -126,7 +101,13 @@ class RoomsResource extends Resource { ); } - ///Delete a room. + /// Delete a room. + /// user must be group admin to perform this action. + /// + /// ### Parameters + /// + /// - `roomId`: Id of the room. + /// Future> deleteRoom(String roomId) { return _v._jsonRequest('$_path/$roomId', method: 'DELETE'); } @@ -141,29 +122,6 @@ class RoomsResource extends Resource { /// - `skip`: Skip n users. /// - `limit`: maximum number of users to return (default 30). /// - /// ### Response - /// - /// ``` - /// [ - /// { - /// "id": "53307734c3599d1de448e192", - /// "username": "malditogeek", - /// "displayName": "Mauro Pompilio", - /// "url": "/malditogeek", - /// "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", - /// "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?", - /// "role": "admin" - /// }, - /// { - /// "id": "53307831c3599d1de448e19a", - /// "username": "suprememoocow", - /// "displayName": "Andrew Newdigate", - /// "url": "/suprememoocow", - /// "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?", - /// "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?" - /// } - /// ] - /// ``` Future>> getUsers( String roomId, { String query, diff --git a/lib/src/v1/stream_api.dart b/lib/src/v1/stream_api.dart index 6b2c58b..582767d 100644 --- a/lib/src/v1/stream_api.dart +++ b/lib/src/v1/stream_api.dart @@ -1,19 +1,27 @@ part of gitterapi; -/// The JSON stream returns messages as JSON objects -/// that are delimited by newline (\n). Space + newline -/// (\n) are sent as periodic "keep-alive" messages to -/// tell clients and NAT firewalls that the connection -/// is still alive during low message volume periods. +/// The streaming API allows real-time access to rooms. +/// +/// This class methods sends [StreamEvent]s. class StreamApi extends Resource { StreamApi(V1 v) : super(v, 'rooms'); /// This returns chat message send by users in room. + /// + /// ### Parameters + /// + /// - `roomId`: Id of the room. + /// Future> chatMessages(String roomId) async { return _v._streamRequest('$_path/$roomId/chatMessages'); } /// This returns room events. + /// + /// ### Parameters + /// + /// - `roomId`: Id of the room. + /// Future> roomEvents(String roomId) async { return _v._streamRequest('$_path/$roomId/events'); } diff --git a/lib/src/v1/user_resource.dart b/lib/src/v1/user_resource.dart index 51a00e7..a01e78b 100644 --- a/lib/src/v1/user_resource.dart +++ b/lib/src/v1/user_resource.dart @@ -1,22 +1,32 @@ part of gitterapi; -/// This class contains the methods for userresources endpoint of gitter api. -/// -/// [Check out the gitter documentation](https://developer.gitter.im/docs/user-resource) +/// Creates methods for [User-resource](https://developer.gitter.im/docs/user-resource). class UserResource extends Resource { + /// Creates a instance of [this]. UserResource(V1 v1) : super(v1, 'user'); - /// Returns a currently signed in user. + /// Returns currently signed in user. Future> me() { return _v._jsonRequest('$_path/me'); } /// List of Rooms the user is part of. + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// Future>> getRooms(String userId) { return _v._jsonRequest>('$_path/$userId/rooms'); } /// Hide the room for the user. + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// - `roomId`: Id of the room. + /// Future> hideRoom(String userId, String roomId) { return _v._jsonRequest( '$_path/$userId/rooms/$roomId', @@ -24,14 +34,29 @@ class UserResource extends Resource { ); } - /// You can retrieve unread items and mentions using the following method. + /// You can retrieve unread items and mentions + /// using the following method. + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// - `roomId`: Id of the room. + /// Future> getUnreadItems(String userId, String roomId) { return _v._jsonRequest( '$_path/$userId/rooms/$roomId/unreadItems', ); } - /// There is an additional method nested under rooms that you can use to mark chat messages as read. + /// There is an additional method nested under rooms + /// that you can use to mark chat messages as read. + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// - `roomId`: Id of the room. + /// - `chatIds`: [List] of chat ids to marks them as read. + /// Future> markUnReadItemsAsRead( String userId, String roomId, @@ -44,19 +69,34 @@ class UserResource extends Resource { ); } - /// List of the user's GitHub Organisations and their respective Room if available. + /// List of the user's GitHub Organisations and their respective Room if available. + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// Future>> getOrgs(String userId) { return _v._jsonRequest>('$_path/$userId/orgs'); } /// List of the user's GitHub Repositories and their respective Room if available. /// - /// Note: It'll return private repositories if the current user has granted Gitter privileges to access them. + /// *Note: It'll return private repositories if the current user has granted Gitter privileges to access them.* + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// Future>> getRepos(String userId) { return _v._jsonRequest>('$_path/$userId/repos'); } /// List of Gitter channels nested under the current user. + /// + /// ### Parameters + /// + /// - `userId`: Id of the user. + /// Future>> getChannels(String userId) { return _v._jsonRequest>( '$_path/$userId/channels', diff --git a/pubspec.lock b/pubspec.lock index 8f14196..bdb9f59 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -78,6 +78,13 @@ packages: url: "https://pub.dartlang.org" source: hosted version: "2.1.5" + csslib: + dependency: transitive + description: + name: csslib + url: "https://pub.dartlang.org" + source: hosted + version: "0.16.2" dart2_constant: dependency: transitive description: @@ -85,6 +92,13 @@ packages: url: "https://pub.dartlang.org" source: hosted version: "1.0.2+dart2" + dartdoc: + dependency: "direct dev" + description: + name: dartdoc + url: "https://pub.dartlang.org" + source: hosted + version: "0.38.0" dio: dependency: "direct main" description: @@ -113,6 +127,13 @@ packages: url: "https://pub.dartlang.org" source: hosted version: "1.2.0" + html: + dependency: transitive + description: + name: html + url: "https://pub.dartlang.org" + source: hosted + version: "0.14.0+4" http: dependency: transitive description: @@ -162,6 +183,13 @@ packages: url: "https://pub.dartlang.org" source: hosted version: "0.11.4" + markdown: + dependency: transitive + description: + name: markdown + url: "https://pub.dartlang.org" + source: hosted + version: "3.0.0" matcher: dependency: transitive description: @@ -183,6 +211,13 @@ packages: url: "https://pub.dartlang.org" source: hosted version: "0.9.7" + mustache: + dependency: transitive + description: + name: mustache + url: "https://pub.dartlang.org" + source: hosted + version: "1.1.1" node_interop: dependency: transitive description: @@ -380,4 +415,4 @@ packages: source: hosted version: "2.2.1" sdks: - dart: ">=2.9.0 <3.0.0" + dart: ">=2.10.0 <3.0.0" diff --git a/pubspec.yaml b/pubspec.yaml index 34299fe..7d3a735 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -12,3 +12,4 @@ dependencies: dev_dependencies: test: ^1.15.7 dotenv: ^2.0.0 + dartdoc: ^0.38.0 From 6454b66fca6da7931ea0d59e573bcb6a0431c292 Mon Sep 17 00:00:00 2001 From: Ratakondala Arun Date: Tue, 29 Dec 2020 23:54:04 +0530 Subject: [PATCH 2/6] Updated README.md, CHANGELOG.md --- .gitignore | 3 ++- CHANGELOG.md | 3 +++ README.md | 37 ++++++++++++++++++++++++++++++++++++- pubspec.lock | 14 ++++++++++++++ pubspec.yaml | 1 + 5 files changed, 56 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 4eabe07..1928027 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ .dart_tool .packages .env -doc \ No newline at end of file +doc +.markdownlint.yaml \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index e69de29..2cb42fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -0,0 +1,3 @@ +## [0.0.1] + +- Initial Release diff --git a/README.md b/README.md index 80da322..6cedc95 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,38 @@ # Gitter API Dart Warpper -A simple warpper class around Gitter API +A Dart client library for accessing [Gitter API](https://developer.gitter.im/docs/welcome). + +[![Gitter](https://badges.gitter.im/RatakondalaArun/gitterapi.svg)](https://gitter.im/RatakondalaArun/gitterapi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) + +## Getting Started + +1) Add this to your `pubspec.yaml` + + ```text + dependencies: + tmdb_api: recent_version. + ``` + +2) Import the package in your code. + + ```dart + import 'package:gitterapi/gitterapi.dart' + ``` + +3) Create instance of `GitterApi`. + + ```dart + final gitterApi = GitterApi(ApiKeys('ACCESS_TOKEN')); + ``` + +### Example + +Now use that instance to make api requests. + +```dart +final Result result = await gitterApi.v1.userResource.me(); +print(result.data); + +// you can use models from gitterapi/models.dart to parse this data +final User me = User.fromMap(result.data); +``` diff --git a/pubspec.lock b/pubspec.lock index bdb9f59..b542425 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -36,6 +36,13 @@ packages: url: "https://pub.dartlang.org" source: hosted version: "2.0.0" + build_cli_annotations: + dependency: transitive + description: + name: build_cli_annotations + url: "https://pub.dartlang.org" + source: hosted + version: "1.2.0" charcode: dependency: transitive description: @@ -99,6 +106,13 @@ packages: url: "https://pub.dartlang.org" source: hosted version: "0.38.0" + dhttpd: + dependency: "direct dev" + description: + name: dhttpd + url: "https://pub.dartlang.org" + source: hosted + version: "3.0.2" dio: dependency: "direct main" description: diff --git a/pubspec.yaml b/pubspec.yaml index 7d3a735..a106bd4 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -13,3 +13,4 @@ dev_dependencies: test: ^1.15.7 dotenv: ^2.0.0 dartdoc: ^0.38.0 + dhttpd: ^3.0.2 From 583597da073ce458d15b1560735025cb5341d238 Mon Sep 17 00:00:00 2001 From: Ratakondala Arun Date: Tue, 29 Dec 2020 23:54:20 +0530 Subject: [PATCH 3/6] added example.dart --- example/example.dart | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 example/example.dart diff --git a/example/example.dart b/example/example.dart new file mode 100644 index 0000000..9203e4d --- /dev/null +++ b/example/example.dart @@ -0,0 +1,19 @@ +import 'package:gitterapi/gitter_api.dart'; +import 'package:gitterapi/models.dart'; + +Future main() async { + // Create a instance of GitterApi. + // In this case ApiKeys are being grabed from env. + final gitterApi = GitterApi(ApiKeys.fromEnv()); + // Fetches current user. + final Result result = await gitterApi.v1.userResource.me(); + // check if result is success. + if (result.isError) { + print('Some error occured error: ${result.error}'); + return; + } + print(result.data); + // parse User from Map object. + final User me = User.fromMap(result.data); + print(me); +} From 28e36406bf3d5306ab08879ed46bdbe5dd432d4c Mon Sep 17 00:00:00 2001 From: Ratakondala Arun Date: Wed, 30 Dec 2020 11:57:20 +0530 Subject: [PATCH 4/6] removed .todo file --- .gitignore | 3 ++- .todo | 5 ----- 2 files changed, 2 insertions(+), 6 deletions(-) delete mode 100644 .todo diff --git a/.gitignore b/.gitignore index 1928027..e7f909c 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ .packages .env doc -.markdownlint.yaml \ No newline at end of file +.markdownlint.yaml +.todo \ No newline at end of file diff --git a/.todo b/.todo deleted file mode 100644 index 7c33477..0000000 --- a/.todo +++ /dev/null @@ -1,5 +0,0 @@ -- Improve Message class - - [] Add "threadMessageCount" - - [] Add isParent getter - - [] Add isChild getter - - [] Add isEdited getter \ No newline at end of file From 2d60dffeb18876b8056c6ee2fe16ab1a5f9e2ba8 Mon Sep 17 00:00:00 2001 From: Ratakondala Arun Date: Wed, 30 Dec 2020 11:57:49 +0530 Subject: [PATCH 5/6] removed provider.dart file --- lib/models/provider.dart | 32 -------------------------------- 1 file changed, 32 deletions(-) delete mode 100644 lib/models/provider.dart diff --git a/lib/models/provider.dart b/lib/models/provider.dart deleted file mode 100644 index b372cbc..0000000 --- a/lib/models/provider.dart +++ /dev/null @@ -1,32 +0,0 @@ -class Provider { - final String name; - - Provider({ - this.name, - }); - - Map toMap() { - return { - 'name': name, - }; - } - - factory Provider.fromMap(Map map) { - if (map == null) return null; - - return Provider( - name: map['name'], - ); - } - - Provider copyWith({ - String name, - }) { - return Provider( - name: name ?? this.name, - ); - } - - @override - String toString() => 'Provider(name: $name)'; -} From 2430eb09de4bdaf59afa8246603937c049f71a21 Mon Sep 17 00:00:00 2001 From: Ratakondala Arun Date: Wed, 30 Dec 2020 11:58:17 +0530 Subject: [PATCH 6/6] Add Documentation closes #21 --- lib/gitter_api.dart | 3 +++ lib/models.dart | 1 - lib/models/group.dart | 15 +++++++++++-- lib/models/issue.dart | 3 +++ lib/models/mention.dart | 5 +++++ lib/models/message.dart | 6 +++++- lib/models/permission.dart | 5 ++++- lib/models/room.dart | 43 +++++++++++++++----------------------- lib/models/user.dart | 3 +++ 9 files changed, 53 insertions(+), 31 deletions(-) diff --git a/lib/gitter_api.dart b/lib/gitter_api.dart index 80073d5..6fb25f2 100644 --- a/lib/gitter_api.dart +++ b/lib/gitter_api.dart @@ -1,3 +1,6 @@ +/// This library provides a easy way to intract with [Gitter API](https://developer.gitter.im/docs/welcome). +/// +/// This library also provides models to convert responses. library gitterapi; import 'dart:convert'; diff --git a/lib/models.dart b/lib/models.dart index 3f1bfb5..cdad657 100644 --- a/lib/models.dart +++ b/lib/models.dart @@ -3,6 +3,5 @@ export 'models/issue.dart'; export 'models/mention.dart'; export 'models/message.dart'; export 'models/permission.dart'; -export 'models/provider.dart'; export 'models/room.dart'; export 'models/user.dart'; diff --git a/lib/models/group.dart b/lib/models/group.dart index 4be8cf7..5e3321d 100644 --- a/lib/models/group.dart +++ b/lib/models/group.dart @@ -1,3 +1,4 @@ +/// Represents a group. class Group { /// Group ID. final String id; @@ -14,6 +15,7 @@ class Group { /// Base avatar URL (add s parameter to size) final String avatarUrl; + /// Creates a instance of [Group]. const Group({ this.id, this.name, @@ -70,9 +72,10 @@ class SecurityDescriptor { /// [null|'ONE_TO_ONE'|'GH_REPO'|'GH_ORG'|'GH_USER'] final SecurityDescriptorType type; - /// Represents how we find the backing object given the type + /// Represents how we find the backing object given the type. final String linkPath; + /// Creates a instace of [SecurityDescriptor]. const SecurityDescriptor({ this.type, this.linkPath, @@ -107,8 +110,16 @@ class SecurityDescriptor { String toString() => 'SecurityDescriptor(type: $type, linkPath: $linkPath)'; } -enum SecurityDescriptorType { oneToOne, ghRepo, ghOrg, ghUser, glGroup } +/// Security descriptorType. Describes the backing object we get permissions from. +enum SecurityDescriptorType { + oneToOne, + ghRepo, + ghOrg, + ghUser, + glGroup, +} +/// This can be used to convert [SecurityDescriptorType] to [String] and back. extension SecurityDescriptorTypeExtension on SecurityDescriptorType { Map get names { return { diff --git a/lib/models/issue.dart b/lib/models/issue.dart index 13a24ae..d4914fd 100644 --- a/lib/models/issue.dart +++ b/lib/models/issue.dart @@ -1,6 +1,9 @@ +/// Represents a issue. class Issue { + /// Issues number that was mentioned. final String number; + /// Creates a instance of [Issue]. const Issue({ this.number, }); diff --git a/lib/models/mention.dart b/lib/models/mention.dart index 3f3c649..cea3e0b 100644 --- a/lib/models/mention.dart +++ b/lib/models/mention.dart @@ -1,7 +1,12 @@ +/// Represents mention. class Mention { + /// Id of the user that was mentioned. final String userId; + + /// Screen name of the user that was mentioned. final String screenName; + /// Creates a instance of [Mention]. const Mention({ this.userId, this.screenName, diff --git a/lib/models/message.dart b/lib/models/message.dart index b3bd75e..451937b 100644 --- a/lib/models/message.dart +++ b/lib/models/message.dart @@ -2,6 +2,7 @@ import 'issue.dart'; import 'mention.dart'; import 'user.dart'; +/// Represents a Message. class Message { /// ID of the message. final String id; @@ -18,7 +19,7 @@ class Message { /// ISO formatted date of the message if edited. final String editedAt; - /// (User)[user-resource] that sent the message. + /// (User) that sent the message. final User fromUser; /// Boolean that indicates if the current user has read the message. @@ -39,14 +40,17 @@ class Message { /// Metadata. This is currently not used for anything. final List meta; + /// Converts [sent] to [DateTime]. DateTime get sentAs { return sent == null ? null : DateTime.tryParse(sent); } + /// Converts [editedAt] to [DateTime]. DateTime get editedAtAs { return editedAt == null ? null : DateTime.tryParse(editedAt); } + /// Creates a instance of [Message]. const Message({ this.id, this.text, diff --git a/lib/models/permission.dart b/lib/models/permission.dart index cc5410c..83fdbf6 100644 --- a/lib/models/permission.dart +++ b/lib/models/permission.dart @@ -1,9 +1,12 @@ import 'dart:convert'; +/// This class contains user permissions. class Permissions { + /// Returns true if this person is admin. final bool admin; - Permissions({ + /// Creates a instance of [Permissions]. + const Permissions({ this.admin, }); diff --git a/lib/models/room.dart b/lib/models/room.dart index 90f1a48..63cebaf 100644 --- a/lib/models/room.dart +++ b/lib/models/room.dart @@ -1,31 +1,6 @@ import 'permission.dart'; -// { -// "id": "576c4d75c2f0db084a1f99ae", -// "name": "flutter/flutter", -// "topic": "Flutter makes it easy and fast to build beautiful apps for mobile and beyond.\n", -// "avatarUrl": "https://avatars-01.gitter.im/group/iv/4/576c4d75c2f0db084a1f99ad", -// "uri": "flutter/flutter", -// "oneToOne": false, -// "userCount": 12301, -// "unreadItems": 17, -// "mentions": 0, -// "lastAccessTime": "2020-12-16T17:14:05.771Z", -// "lurk": false, -// "url": "/flutter/flutter", -// "githubType": "REPO", -// "security": "PUBLIC", -// "noindex": false, -// "tags": [], -// "permissions": { -// "admin": false -// }, -// "roomMember": true, -// "groupId": "576c4d75c2f0db084a1f99ad", -// "public": true, -// "v": 2 -// }, - +/// Represents a room. class Room { ///Room ID. final String id; @@ -85,6 +60,7 @@ class Room { /// Wheather be indexed by search engines. final bool noindex; + /// Permissions user have in this room. final Permissions permissions; /// Room version. @@ -100,6 +76,7 @@ class Room { ); } + /// Creates a instance of [Room]. const Room({ this.id, this.name, @@ -232,15 +209,29 @@ class Room { } } +/// Type of room. enum RoomType { + /// This room is belonged to organization. org, + + /// This room is belonged to Repository. repo, + + /// This room is a one to one chat( Direct message ). oneToOne, + + /// This is a Organization channel orgChannel, + + /// This is a Repository channel repoChannel, + + /// This is a User channel userChannel, } +/// Extension on [RoomType]. Used to parse [RoomType] to [String] +/// and back. extension RoomTypeExtension on RoomType { /// Returns [Map] with respect to there string. static const names = { diff --git a/lib/models/user.dart b/lib/models/user.dart index c20311b..4acee85 100644 --- a/lib/models/user.dart +++ b/lib/models/user.dart @@ -25,10 +25,13 @@ class User { /// Auth Provider final List providers; + /// Version final int v; + /// Gavavatar version final String gv; + /// Creates a instance of [User] const User({ this.id, this.username,