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