diff --git a/.gitignore b/.gitignore
index 08a04c3..e7f909c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
.dart_tool
.packages
.env
+doc
+.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
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).
+
+[](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<Map> 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/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<void> 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<Map> 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);
+}
diff --git a/lib/gitter_api.dart b/lib/gitter_api.dart
index 26c2a81..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';
@@ -19,15 +22,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/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<SecurityDescriptorType, String> 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<dynamic> 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/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<String, dynamic> 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)';
-}
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<RoomType,String>] 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<String> providers;
+ /// Version
final int v;
+ /// Gavavatar version
final String gv;
+ /// Creates a instance of [User]
const User({
this.id,
this.username,
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<T>].
Future<Result<T>> _jsonRequest<T>(
String path, {
String method = 'GET',
@@ -70,6 +83,7 @@ class V1 extends Version {
}
}
+ /// Sends a request and returns [Stream<StreamEvent>].
Future<Stream<StreamEvent>> _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<V1> {
+ /// 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<V1> {
}
/// List of rooms nested under the specified group.
+ ///
+ /// ### Parameters:
+ ///
+ /// - `groupId`: Id of the group.
+ ///
Future<Result<List>> getRooms(String groupId) {
return _v._jsonRequest<List>('$_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<Result<Map>> 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<V1> {
MessagesResource(V1 v) : super(v, 'chatMessages');
/// List of messages in a room.
/// Returns [List<Map<String,dynamic>>].
///
- /// ### 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<Result<List<dynamic>>> getMessages(
String roomId, {
int skip,
@@ -37,12 +40,20 @@ class MessagesResource extends Resource<V1> {
}
/// 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<Result<Map>> getSingleMessage(String roomId, String messageId) {
return _v._jsonRequest<Map>('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<V1> {
);
}
- /// 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 <a href=\"https://irc.gitter.im/\" rel=\"nofollow\" target=\"_new\" class=\"link\">https://irc.gitter.im/</a> <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<Result<Map>> updateMessage(
- String roomId, String messageId, String text) {
+ String roomId,
+ String messageId,
+ String text,
+ ) {
return _v._jsonRequest<Map>(
'rooms/$roomId/$_path/$messageId',
method: 'PUT',
@@ -104,12 +93,25 @@ class MessagesResource extends Resource<V1> {
/// You can retrieve unread items and
/// mentions using the following endpoint.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ /// - `roomId`: Id of the room.
+ ///
Future<Result<Map>> getUnreadItems(String userId, String roomId) {
return _v._jsonRequest<Map>('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<Result<void>> 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<V1> {
@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<Map<String,dynamic>>].
+ /// ### 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<Result<List<dynamic>>> rooms({String query}) {
return _v._jsonRequest<List<dynamic>>(
_path,
@@ -60,29 +25,33 @@ class RoomsResource extends Resource<V1> {
// 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<Result<Map>> getRoomIdFrom(String uri) {
- return _v
- ._jsonRequest<Map>('$_path', method: 'POST', postData: {'uri': uri});
+ return _v._jsonRequest<Map>(
+ '$_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<Result<void>> joinRoom(String userId, String roomId) {
return _v._jsonRequest(
'user/$userId/$_path',
@@ -91,8 +60,13 @@ class RoomsResource extends Resource<V1> {
);
}
- /// 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<Result<void>> banUserFromRoom(String roomId, String username) {
return _v._jsonRequest(
'$_path/$roomId/bans',
@@ -102,6 +76,7 @@ class RoomsResource extends Resource<V1> {
}
/// Update room details.
+ /// user must be group admin to perform this action.
///
/// ### Parameters
///
@@ -126,7 +101,13 @@ class RoomsResource extends Resource<V1> {
);
}
- ///Delete a room.
+ /// Delete a room.
+ /// user must be group admin to perform this action.
+ ///
+ /// ### Parameters
+ ///
+ /// - `roomId`: Id of the room.
+ ///
Future<Result<Map>> deleteRoom(String roomId) {
return _v._jsonRequest<Map>('$_path/$roomId', method: 'DELETE');
}
@@ -141,29 +122,6 @@ class RoomsResource extends Resource<V1> {
/// - `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<Result<List<dynamic>>> 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<V1> {
StreamApi(V1 v) : super(v, 'rooms');
/// This returns chat message send by users in room.
+ ///
+ /// ### Parameters
+ ///
+ /// - `roomId`: Id of the room.
+ ///
Future<Stream<StreamEvent>> chatMessages(String roomId) async {
return _v._streamRequest('$_path/$roomId/chatMessages');
}
/// This returns room events.
+ ///
+ /// ### Parameters
+ ///
+ /// - `roomId`: Id of the room.
+ ///
Future<Stream<StreamEvent>> 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<V1> {
+ /// Creates a instance of [this].
UserResource(V1 v1) : super(v1, 'user');
- /// Returns a currently signed in user.
+ /// Returns currently signed in user.
Future<Result<Map>> me() {
return _v._jsonRequest<Map>('$_path/me');
}
/// List of Rooms the user is part of.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ ///
Future<Result<List<dynamic>>> getRooms(String userId) {
return _v._jsonRequest<List<dynamic>>('$_path/$userId/rooms');
}
/// Hide the room for the user.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ /// - `roomId`: Id of the room.
+ ///
Future<Result<void>> hideRoom(String userId, String roomId) {
return _v._jsonRequest<void>(
'$_path/$userId/rooms/$roomId',
@@ -24,14 +34,29 @@ class UserResource extends Resource<V1> {
);
}
- /// 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<Result<Map>> getUnreadItems(String userId, String roomId) {
return _v._jsonRequest<Map>(
'$_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<Result<void>> markUnReadItemsAsRead(
String userId,
String roomId,
@@ -44,19 +69,34 @@ class UserResource extends Resource<V1> {
);
}
- /// 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<Result<List<dynamic>>> getOrgs(String userId) {
return _v._jsonRequest<List<dynamic>>('$_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<Result<List<dynamic>>> getRepos(String userId) {
return _v._jsonRequest<List<dynamic>>('$_path/$userId/repos');
}
/// List of Gitter channels nested under the current user.
+ ///
+ /// ### Parameters
+ ///
+ /// - `userId`: Id of the user.
+ ///
Future<Result<List<dynamic>>> getChannels(String userId) {
return _v._jsonRequest<List<dynamic>>(
'$_path/$userId/channels',
diff --git a/pubspec.lock b/pubspec.lock
index 8f14196..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:
@@ -78,6 +85,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 +99,20 @@ 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"
+ dhttpd:
+ dependency: "direct dev"
+ description:
+ name: dhttpd
+ url: "https://pub.dartlang.org"
+ source: hosted
+ version: "3.0.2"
dio:
dependency: "direct main"
description:
@@ -113,6 +141,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 +197,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 +225,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 +429,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..a106bd4 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -12,3 +12,5 @@ dependencies:
dev_dependencies:
test: ^1.15.7
dotenv: ^2.0.0
+ dartdoc: ^0.38.0
+ dhttpd: ^3.0.2