diff --git a/README.md b/README.md index 46003b2..e10ee3b 100644 --- a/README.md +++ b/README.md @@ -16,61 +16,99 @@ Python API wrapper for the [Rocket chat API](https://rocket.chat/docs/developer- #### Usage Initialize the client with a username and password or token and user_id. -This user *must* have Admin privs: +Currently no 2FA is supported. from rocketchat.api import RocketChatAPI api = RocketChatAPI(settings={'username': 'someuser', 'password': 'somepassword', - 'domain': 'https://myrockethchatdomain.com'}) + 'domain': 'https://myrocketchatdomain.com'}) # or api = RocketChatAPI(settings={'token': 'sometoken', 'user_id': 'someuserid', - 'domain': 'https://myrockethchatdomain.com'}) + 'domain': 'https://myrocketchatdomain.com'}) ##### Available Calls + +###### Messages / Rooms general functions api.send_message('message', 'room_id') + api.upload_file(room_id='room_id', + file='file', + description='File description', + message='Example message') + + api.upload_remote_file(room_id='room_id', + url='url', + description='File description', + message='Example message') + +###### Users + api.create_user('email', + 'name', + 'password', + 'username', + active=True, + roles=['user'], + join_default_channels=True, + require_password_change=False, + send_welcome_email=False, + verified=False, + customFields=None) + + api.delete_user('user_id') + + api.get_user_id('user_name') + + api.get_users() + + api.get_user_info('user_id') + + api.get_my_info() + +###### Direct Messages + api.create_im_room('username') + + api.close_room('room_id') + + api.open_room('room_id') + + api.get_im_room_history('room_id', oldest=date) + + api.get_im_rooms() + +###### Groups / Private Rooms + api.create_private_room('room_name', + members=[], + read_only=False) + + api.invite_private_room('room_id', 'user_id') + api.get_private_rooms() api.get_private_room_history('room_id', oldest=date) - api.get_public_rooms() - - api.get_room_info('room_id') + api.get_room_id('room_name') api.get_private_room_info('room_id') - api.get_room_history('room_id') + api.set_room_topic('topic', 'room_id') + +###### Channels / Public Rooms + api.get_public_rooms() api.create_public_room('room_name', members=[], read_only=False) - api.delete_public_room('room_id') + api.invite_public_room('room_id', 'user_id') - api.get_my_info() + api.get_room_info('room_id') - api.get_users() + api.get_public_room_id('room_name') - api.get_user_info('user_id') + api.get_room_history('room_id') - api.create_user('email', - 'name', - 'password', - 'username', - active=True, - roles=['user'], - join_default_channels=True, - require_password_change=False, - send_welcome_email=False, - verified=False, - customFields=None) - - api.delete_user('user_id') + api.delete_public_room('room_id') - api.upload_file(room_id='room_id', - file='file', - description='File description', - message='Example message') check /rocketchat/calls/api.py for more. @@ -80,7 +118,6 @@ check /rocketchat/calls/api.py for more. ##### Sending a message -You'll first need to get the _id of the room you want to send a message to. Currently, Rocket -can only send messages to *public* rooms. +You'll first need to get the `_id` of the room you want to send a message to. api.send_message('Your message', room_id) diff --git a/docs/rocketchat.calls.channels.rst b/docs/rocketchat.calls.channels.rst index 4235a51..8447970 100644 --- a/docs/rocketchat.calls.channels.rst +++ b/docs/rocketchat.calls.channels.rst @@ -28,6 +28,14 @@ rocketchat.calls.channels.get\_history module :undoc-members: :show-inheritance: +rocketchat.calls.channels.invite\_public\_room module +--------------------------------------------- + +.. automodule:: rocketchat.calls.channels.invite_public_room + :members: + :undoc-members: + :show-inheritance: + rocketchat.calls.channels.get\_public\_rooms module --------------------------------------------------- @@ -36,6 +44,14 @@ rocketchat.calls.channels.get\_public\_rooms module :undoc-members: :show-inheritance: +rocketchat.calls.channels.get\_public\_room\_id module +------------------------------------------------------ + +.. automodule:: rocketchat.calls.channels.get_public_room_id + :members: + :undoc-members: + :show-inheritance: + rocketchat.calls.channels.get\_room\_info module ------------------------------------------------ diff --git a/docs/rocketchat.calls.groups.rst b/docs/rocketchat.calls.groups.rst index 6023198..cf342ad 100644 --- a/docs/rocketchat.calls.groups.rst +++ b/docs/rocketchat.calls.groups.rst @@ -4,6 +4,14 @@ rocketchat.calls.groups package Submodules ---------- +rocketchat.calls.groups.create\_private\_room module +---------------------------------------------------------- + +.. automodule:: rocketchat.calls.groups.create_private_room + :members: + :undoc-members: + :show-inheritance: + rocketchat.calls.groups.get\_private\_room\_history module ---------------------------------------------------------- @@ -12,6 +20,14 @@ rocketchat.calls.groups.get\_private\_room\_history module :undoc-members: :show-inheritance: +rocketchat.calls.groups.invite\_private\_room module +---------------------------------------------------------- + +.. automodule:: rocketchat.calls.groups.invite_private_room + :members: + :undoc-members: + :show-inheritance: + rocketchat.calls.groups.get\_private\_room\_info module ------------------------------------------------------- @@ -44,6 +60,14 @@ rocketchat.calls.groups.upload\_file module :undoc-members: :show-inheritance: +rocketchat.calls.groups.upload\_remote\_file module +--------------------------------------------------- + +.. automodule:: rocketchat.calls.groups.upload_remote_file + :members: + :undoc-members: + :show-inheritance: + Module contents --------------- diff --git a/docs/rocketchat.calls.im.rst b/docs/rocketchat.calls.im.rst new file mode 100644 index 0000000..b1ded74 --- /dev/null +++ b/docs/rocketchat.calls.im.rst @@ -0,0 +1,54 @@ +rocketchat.calls.im package +=========================== + +Submodules +---------- + +rocketchat.calls.im.close\_room module +-------------------------------------- + +.. automodule:: rocketchat.calls.im.close_room + :members: + :undoc-members: + :show-inheritance: + +rocketchat.calls.im.create\_room module +--------------------------------------- + +.. automodule:: rocketchat.calls.im.create_room + :members: + :undoc-members: + :show-inheritance: + +rocketchat.calls.im.get\_history module +--------------------------------------- + +.. automodule:: rocketchat.calls.im.get_history + :members: + :undoc-members: + :show-inheritance: + +rocketchat.calls.im.get\_rooms module +------------------------------------- + +.. automodule:: rocketchat.calls.im.get_rooms + :members: + :undoc-members: + :show-inheritance: + +rocketchat.calls.im.open\_room module +------------------------------------- + +.. automodule:: rocketchat.calls.im.open_room + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: rocketchat.calls.im + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/rocketchat.calls.users.rst b/docs/rocketchat.calls.users.rst index 9d5a611..cbfcae8 100644 --- a/docs/rocketchat.calls.users.rst +++ b/docs/rocketchat.calls.users.rst @@ -20,6 +20,14 @@ rocketchat.calls.users.delete\_user module :undoc-members: :show-inheritance: +rocketchat.calls.users.get\_user\_id module +------------------------------------------- + +.. automodule:: rocketchat.calls.users.get_user_id + :members: + :undoc-members: + :show-inheritance: + rocketchat.calls.users.get\_user\_info module --------------------------------------------- diff --git a/rocketchat/api.py b/rocketchat/api.py index 6103f87..285efd5 100644 --- a/rocketchat/api.py +++ b/rocketchat/api.py @@ -4,11 +4,16 @@ from rocketchat.calls.channels.get_room_info import GetRoomInfo from rocketchat.calls.groups.get_private_room_info import GetPrivateRoomInfo from rocketchat.calls.groups.get_room_id import GetRoomId +from rocketchat.calls.channels.get_public_room_id import GetPublicRoomId +from rocketchat.calls.users.get_user_id import GetUserId from rocketchat.calls.groups.set_room_topic import SetRoomTopic from rocketchat.calls.channels.get_history import GetRoomHistory from rocketchat.calls.groups.get_private_room_history import GetPrivateRoomHistory +from rocketchat.calls.groups.create_private_room import CreatePrivateRoom from rocketchat.calls.channels.create_public_room import CreatePublicRoom from rocketchat.calls.channels.delete_public_room import DeletePublicRoom +from rocketchat.calls.groups.invite_private_room import InvitePrivateRoom +from rocketchat.calls.channels.invite_public_room import InvitePublicRoom from rocketchat.calls.auth.get_me import GetMe from rocketchat.calls.auth.logout import Logout from rocketchat.calls.users.get_users import GetUsers @@ -16,6 +21,7 @@ from rocketchat.calls.users.create_user import CreateUser from rocketchat.calls.users.delete_user import DeleteUser from rocketchat.calls.groups.upload_file import UploadFile +from rocketchat.calls.groups.upload_remote_file import UploadRemoteFile from rocketchat.calls.im.create_room import CreateImRoom from rocketchat.calls.im.open_room import OpenImRoom from rocketchat.calls.im.close_room import CloseImRoom @@ -63,6 +69,19 @@ def get_private_room_history(self, room_id, oldest=None, **kwargs): **kwargs ) + def create_private_room(self, name, **kwargs): + """ + Create group with given name + :param name: Room name + :param kwargs: + members: The users to add to the channel when it is created. + Optional; Ex.: ["rocket.cat"], Default: [] + read_only: Set if the group is read only or not. + Optional; Ex.: True, Default: False + :return: + """ + return CreatePrivateRoom(settings=self.settings, **kwargs).call(name=name, **kwargs) + def get_public_rooms(self, **kwargs): """ Get a listing of all public rooms with their names and IDs @@ -100,6 +119,25 @@ def upload_file(self, room_id, description, file, message, mime_type='text/plain **kwargs ) + def upload_remote_file(self, room_id, description, url, message, filename='Uploaded File', mime_type='text/plain', **kwargs): + """ + Upload file to room + :param room_id: + :param description: + :param file: + :param kwargs: + :return: + """ + return UploadFile(settings=self.settings, **kwargs).call( + room_id=room_id, + description=description, + url=url, + message=message, + filename=filename, + mime_type=mime_type, + **kwargs + ) + def get_private_room_info(self, room_id, **kwargs): """ Get various information about a specific private group @@ -115,7 +153,7 @@ def get_private_room_info(self, room_id, **kwargs): def get_room_id(self, room_name, **kwargs): """ - Get room ID + Get private room ID :param room_name: :param kwargs: :return: @@ -125,6 +163,30 @@ def get_room_id(self, room_name, **kwargs): **kwargs ) + def get_public_room_id(self, room_name, **kwargs): + """ + Get public room ID + :param room_name: + :param kwargs: + :return: + """ + return GetPublicRoomId(settings=self.settings, **kwargs).call( + room_name=room_name, + **kwargs + ) + + def get_user_id(self, user_name, **kwargs): + """ + Get user ID + :param user_name: + :param kwargs: + :return: + """ + return GetUserId(settings=self.settings, **kwargs).call( + user_name=user_name, + **kwargs + ) + def get_room_history( self, room_id, @@ -174,6 +236,26 @@ def delete_public_room(self, room_id, **kwargs): """ return DeletePublicRoom(settings=self.settings, **kwargs).call(room_id=room_id, **kwargs) + def invite_private_room(self, room_id, user_id, **kwargs): + """ + Invite user to group with given ID + :param room_id: Room ID + :param user_id: User ID + :param kwargs: + :return: + """ + return InvitePrivateRoom(settings=self.settings, **kwargs).call(room_id=room_id, user_id=user_id **kwargs) + + def invite_public_room(self, room_id, user_id, **kwargs): + """ + Invite user to channel with given ID + :param room_id: Room ID + :param user_id: User ID + :param kwargs: + :return: + """ + return InvitePublicRoom(settings=self.settings, **kwargs).call(room_id=room_id, user_id=user_id **kwargs) + def get_my_info(self, **kwargs): return GetMe(settings=self.settings, **kwargs).call(**kwargs) diff --git a/rocketchat/calls/channels/get_public_room_id.py b/rocketchat/calls/channels/get_public_room_id.py new file mode 100644 index 0000000..89c5e02 --- /dev/null +++ b/rocketchat/calls/channels/get_public_room_id.py @@ -0,0 +1,18 @@ +import logging + +from rocketchat.calls.base import RocketChatBase + +logger = logging.getLogger(__name__) + + +class GetPublicRoomId(RocketChatBase): + endpoint = '/api/v1/channels.info' + + def build_endpoint(self, **kwargs): + return '{endpoint}?roomName={room_name}'.format( + endpoint=self.endpoint, + room_name=kwargs.get('room_name') + ) + + def post_response(self, result): + return result['channel']['_id'] diff --git a/rocketchat/calls/channels/invite_public_room.py b/rocketchat/calls/channels/invite_public_room.py new file mode 100644 index 0000000..f100426 --- /dev/null +++ b/rocketchat/calls/channels/invite_public_room.py @@ -0,0 +1,22 @@ +import logging +import json + +from rocketchat.calls.base import PostMixin, RocketChatBase + +logger = logging.getLogger(__name__) + + +class InvitePublicRoom(PostMixin, RocketChatBase): + endpoint = '/api/v1/channels.invite' + + def build_endpoint(self, **kwargs): + return self.endpoint + + def build_payload(self, **kwargs): + return json.dumps({ + 'roomId': kwargs.get('room_id'), + 'userId': kwargs.get('user_id') + }) + + def post_response(self, result): + return result diff --git a/rocketchat/calls/groups/create_private_room.py b/rocketchat/calls/groups/create_private_room.py new file mode 100644 index 0000000..2e4b91b --- /dev/null +++ b/rocketchat/calls/groups/create_private_room.py @@ -0,0 +1,23 @@ +import logging +import json + +from rocketchat.calls.base import PostMixin, RocketChatBase + +logger = logging.getLogger(__name__) + + +class CreatePrivateRoom(PostMixin, RocketChatBase): + endpoint = '/api/v1/groups.create' + + def build_endpoint(self, **kwargs): + return self.endpoint + + def build_payload(self, **kwargs): + return json.dumps({ + 'name': kwargs.get('name'), + 'members': kwargs.get('members', []), + 'readOnly': kwargs.get('read_only', False) + }) + + def post_response(self, result): + return result diff --git a/rocketchat/calls/groups/invite_private_room.py b/rocketchat/calls/groups/invite_private_room.py new file mode 100644 index 0000000..aa6712f --- /dev/null +++ b/rocketchat/calls/groups/invite_private_room.py @@ -0,0 +1,22 @@ +import logging +import json + +from rocketchat.calls.base import PostMixin, RocketChatBase + +logger = logging.getLogger(__name__) + + +class InvitePrivateRoom(PostMixin, RocketChatBase): + endpoint = '/api/v1/groups.invite' + + def build_endpoint(self, **kwargs): + return self.endpoint + + def build_payload(self, **kwargs): + return json.dumps({ + 'roomId': kwargs.get('room_id'), + 'userId': kwargs.get('user_id') + }) + + def post_response(self, result): + return result diff --git a/rocketchat/calls/groups/upload_remote_file.py b/rocketchat/calls/groups/upload_remote_file.py new file mode 100644 index 0000000..c004fb5 --- /dev/null +++ b/rocketchat/calls/groups/upload_remote_file.py @@ -0,0 +1,28 @@ +import logging + +from rocketchat.calls.base import RocketChatBase, PostMixin, logger +import sys +if sys.version_info[0] == 2: + import urllib +else: + import urllib.request as urllib +logger.setLevel(logging.DEBUG) + + +class UploadRemoteFile(PostMixin, RocketChatBase): + endpoint = '/api/v1/rooms.upload' + + def build_endpoint(self, **kwargs): + return '{endpoint}/{room_id}'.format(endpoint=self.endpoint, + room_id=kwargs.get('room_id')) + + def build_files(self, **kwargs): + return {'file': (kwargs.get('filename'), + urllib.urlopen(kwargs.get('url')), + kwargs.get('mime_type'))} + + def build_payload(self, **kwargs): + return {'description': kwargs.get('description'), 'msg': kwargs.get('message')} + + def post_response(self, result): + return result diff --git a/rocketchat/calls/im/close_room.py b/rocketchat/calls/im/close_room.py index fd99986..99a8f8d 100644 --- a/rocketchat/calls/im/close_room.py +++ b/rocketchat/calls/im/close_room.py @@ -6,7 +6,7 @@ class CloseImRoom(PostMixin, RocketChatBase): - endpoint = "/api/v1/im.create" + endpoint = "/api/v1/im.close" def build_endpoint(self, **kwargs): return self.endpoint diff --git a/rocketchat/calls/im/open_room.py b/rocketchat/calls/im/open_room.py index ed4667b..b3f26ef 100644 --- a/rocketchat/calls/im/open_room.py +++ b/rocketchat/calls/im/open_room.py @@ -6,7 +6,7 @@ class OpenImRoom(PostMixin, RocketChatBase): - endpoint = "/api/v1/im.create" + endpoint = "/api/v1/im.open" def build_endpoint(self, **kwargs): return self.endpoint diff --git a/rocketchat/calls/users/get_user_id.py b/rocketchat/calls/users/get_user_id.py new file mode 100644 index 0000000..c182731 --- /dev/null +++ b/rocketchat/calls/users/get_user_id.py @@ -0,0 +1,18 @@ +import logging + +from rocketchat.calls.base import RocketChatBase + +logger = logging.getLogger(__name__) + + +class GetUserId(RocketChatBase): + endpoint = '/api/v1/users.info' + + def build_endpoint(self, **kwargs): + return '{endpoint}?username={user_name}'.format( + endpoint=self.endpoint, + user_name=kwargs.get('user_name') + ) + + def post_response(self, result): + return result['user']['_id']