Skip to content

Update package doc strings with working URLs #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
evanofslack wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Update package doc strings with working URLs #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
23ee4cf
update doc strings with working URLs
evanofslack Jun 19, 2022
0e38022
update GetStatistics URL
evanofslack Jun 19, 2022
10999b9
update URLs again
Jun 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions rest/channels.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@ type GroupResponse struct {
Group models.Channel `json:"group"`
}

// GetPublicChannels returns all channels that can be seen by the logged in user.
// GetPublicChannels lists all of the channels on the server.
//
// https://rocket.chat/docs/developer-guides/rest-api/channels/list
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/channels-endpoints/list
func (c *Client) GetPublicChannels() (*ChannelsResponse, error) {
response := new(ChannelsResponse)
if err := c.Get("channels.list", nil, response); err != nil {
Expand All @@ -42,9 +42,9 @@ func (c *Client) GetPublicChannels() (*ChannelsResponse, error) {
return response, nil
}

// GetPrivateGroups returns all channels that can be seen by the logged in user.
// GetPrivateGroups lists all of the private groups the calling user has joined.
//
// https://rocket.chat/docs/developer-guides/rest-api/groups/list
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/groups-endpoints/list
func (c *Client) GetPrivateGroups() (*GroupsResponse, error) {
response := new(GroupsResponse)
if err := c.Get("groups.list", nil, response); err != nil {
Expand All @@ -54,9 +54,9 @@ func (c *Client) GetPrivateGroups() (*GroupsResponse, error) {
return response, nil
}

// GetJoinedChannels returns all channels that the user has joined.
// GetJoinedChannels lists all of the channels the calling user has joined.
//
// https://rocket.chat/docs/developer-guides/rest-api/channels/list-joined
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/channels-endpoints/list-joined
func (c *Client) GetJoinedChannels(params url.Values) (*ChannelsResponse, error) {
response := new(ChannelsResponse)
if err := c.Get("channels.list.joined", params, response); err != nil {
Expand All @@ -66,17 +66,18 @@ func (c *Client) GetJoinedChannels(params url.Values) (*ChannelsResponse, error)
return response, nil
}

// LeaveChannel leaves a channel. The id of the channel has to be not nil.
// LeaveChannel causes the callee to be removed from the channel.
// The id of the channel must not be nil.
//
// https://rocket.chat/docs/developer-guides/rest-api/channels/leave
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/channels-endpoints/leave
func (c *Client) LeaveChannel(channel *models.Channel) error {
var body = fmt.Sprintf(`{ "roomId": "%s"}`, channel.ID)
return c.Post("channels.leave", bytes.NewBufferString(body), new(ChannelResponse))
}

// GetChannelInfo get information about a channel. That might be useful to update the usernames.
// GetChannelInfo retrieves the information about the channel.
//
// https://rocket.chat/docs/developer-guides/rest-api/channels/info
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/channels-endpoints/info
func (c *Client) GetChannelInfo(channel *models.Channel) (*models.Channel, error) {
response := new(ChannelResponse)
switch {
Expand All @@ -93,9 +94,9 @@ func (c *Client) GetChannelInfo(channel *models.Channel) (*models.Channel, error
return &response.Channel, nil
}

// GetGroupInfo get information about a group. That might be useful to update the usernames.
// GetGroupInfo retrieves the information about the private group, only if you're part of the group.
//
// https://rocket.chat/docs/developer-guides/rest-api/groups/info
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/groups-endpoints/info
func (c *Client) GetGroupInfo(channel *models.Channel) (*models.Channel, error) {
response := new(GroupResponse)
switch {
Expand Down
6 changes: 3 additions & 3 deletions rest/im.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,13 @@ type DirectMessageResponse struct {
type Room struct {
ID string `json:"_id"`
Rid string `json:"rid"`
Type string `json:"t"`
Type string `json:"t"`
Usernames []string `json:"usernames"`
}

// Creates a DirectMessage
// CreateDirectMessage creates a direct message session with another user.
//
// https://developer.rocket.chat/api/rest-api/methods/im/create
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/im-endpoints/create
func (c *Client) CreateDirectMessage(username string) (*Room, error) {
body := fmt.Sprintf(`{ "username": "%s" }`, username)
resp := new(DirectMessageResponse)
Expand Down
16 changes: 8 additions & 8 deletions rest/information.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ type DirectoryResponse struct {
// GetDirectory a method, that searches by users or channels on all users and channels available on server.
// It supports the Offset, Count, and Sort Query Parameters along with Query and Fields Query Parameters.
//
// https://rocket.chat/docs/developer-guides/rest-api/miscellaneous/directory
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/miscellaneous-endpoints/directory
func (c *Client) GetDirectory(params url.Values) (*models.Directory, error) {
response := new(DirectoryResponse)
if err := c.Get("directory", params, response); err != nil {
Expand All @@ -50,7 +50,7 @@ type SpotlightResponse struct {
// GetSpotlight searches for users or rooms that are visible to the user.
// WARNING: It will only return rooms that user didn’t join yet.
//
// https://rocket.chat/docs/developer-guides/rest-api/miscellaneous/spotlight
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/miscellaneous-endpoints/spotlight
func (c *Client) GetSpotlight(params url.Values) (*models.Spotlight, error) {
response := new(SpotlightResponse)
if err := c.Get("spotlight", params, response); err != nil {
Expand All @@ -65,10 +65,10 @@ type StatisticsResponse struct {
models.StatisticsInfo
}

// GetStatistics
// Statistics about the Rocket.Chat server.
// GetStatistics returns statistics about the Rocket.Chat server.
// Requires view-statistics permission.
//
// https://rocket.chat/docs/developer-guides/rest-api/miscellaneous/statistics
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/stats-endpoints/get-statistics
func (c *Client) GetStatistics() (*models.StatisticsInfo, error) {
response := new(StatisticsResponse)
if err := c.Get("statistics", nil, response); err != nil {
Expand All @@ -83,11 +83,11 @@ type StatisticsListResponse struct {
models.StatisticsList
}

// GetStatisticsList
// Selectable statistics about the Rocket.Chat server.
// GetStatisticsList returns selectable statistics about the Rocket.Chat server.
// It supports the Offset, Count and Sort Query Parameters along with just the Fields and Query Parameters.
// Requires view-statistics permission.
//
// https://rocket.chat/docs/developer-guides/rest-api/miscellaneous/statistics.list
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/miscellaneous-endpoints/statistics-list
func (c *Client) GetStatisticsList(params url.Values) (*models.StatisticsList, error) {
response := new(StatisticsListResponse)
if err := c.Get("statistics.list", params, response); err != nil {
Expand Down
14 changes: 7 additions & 7 deletions rest/messages.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,16 @@ type MessageResponse struct {
// Sends a message to a channel. The name of the channel has to be not nil.
// The message will be html escaped.
//
// https://rocket.chat/docs/developer-guides/rest-api/chat/postmessage
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/chat-endpoints/postmessage
func (c *Client) Send(channel *models.Channel, msg string) error {
body := fmt.Sprintf(`{ "channel": "%s", "text": "%s"}`, channel.Name, html.EscapeString(msg))
return c.Post("chat.postMessage", bytes.NewBufferString(body), new(MessageResponse))
}

// PostMessage send a message to a channel. The channel or roomId has to be not nil.
// The message will be json encode.
// PostMessage sends a message to a channel. The channel or roomId has to be not nil.
// The message will be json encoded.
//
// https://rocket.chat/docs/developer-guides/rest-api/chat/postmessage
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/chat-endpoints/postmessage
func (c *Client) PostMessage(msg *models.PostMessage) (*MessageResponse, error) {
body, err := json.Marshal(msg)
if err != nil {
Expand All @@ -45,10 +45,10 @@ func (c *Client) PostMessage(msg *models.PostMessage) (*MessageResponse, error)
return response, err
}

// Get messages from a channel. The channel id has to be not nil. Optionally a
// count can be specified to limit the size of the returned messages.
// GetMessages retrieves the messages from a channel. The channel id has to be not nil.
// Optionally count and offset can be specified to limit the size and start of the returned messages.
//
// https://rocket.chat/docs/developer-guides/rest-api/channels/history
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/channels-endpoints/history
func (c *Client) GetMessages(channel *models.Channel, page *models.Pagination) ([]models.Message, error) {
params := url.Values{
"roomId": []string{channel.ID},
Expand Down
5 changes: 3 additions & 2 deletions rest/permissions.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package rest
import (
"bytes"
"encoding/json"

"github.com/RocketChat/Rocket.Chat.Go.SDK/models"
)

Expand All @@ -15,9 +16,9 @@ type UpdatePermissionsResponse struct {
Permissions []models.Permission `json:"permissions"`
}

// UpdatePermissions updates permissions
// UpdatePermissions edits permissions on the server.
//
// https://rocket.chat/docs/developer-guides/rest-api/permissions/update/
// https://developer.rocket.chat/reference/api/rest-api/endpoints/core-endpoints/permissions-endpoints/update-permissions
func (c *Client) UpdatePermissions(req *UpdatePermissionsRequest) (*UpdatePermissionsResponse, error) {
body, err := json.Marshal(req)
if err != nil {
Expand Down
86 changes: 50 additions & 36 deletions rest/users.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,18 +28,11 @@ type logonResponse struct {
type CreateUserResponse struct {
Status
User struct {
ID string `json:"_id"`
CreatedAt time.Time `json:"createdAt"`
Services struct {
Password struct {
Bcrypt string `json:"bcrypt"`
} `json:"password"`
} `json:"services"`
Username string `json:"username"`
Emails []struct {
Address string `json:"address"`
Verified bool `json:"verified"`
} `json:"emails"`
ID string `json:"_id"`
CreatedAt time.Time `json:"createdAt"`
Services services `json:"services"`
Username string `json:"username"`
Emails []email `json:"emails"`
Type string `json:"type"`
Status string `json:"status"`
Active bool `json:"active"`
Expand All @@ -50,6 +43,17 @@ type CreateUserResponse struct {
} `json:"user"`
}

type services struct {
Password struct {
Bcrypt string `json:"bcrypt"`
} `json:"password"`
}

type email struct {
Address string `json:"address"`
Verified bool `json:"verified"`
}

type UserStatusResponse struct {
ID string `json:"_id"`
ConnectionStatus string `json:"connectionStatus"`
Expand All @@ -75,9 +79,10 @@ func (s UserStatusResponse) OK() error {
return ResponseErr
}

// Login a user. The Email and the Password are mandatory. The auth token of the user is stored in the Client instance.
// Login authenticates user with email and password.
// The auth token of the user is stored in the Client instance.
//
// https://rocket.chat/docs/developer-guides/rest-api/authentication/login
// https://developer.rocket.chat/reference/api/rest-api/endpoints/other-important-endpoints/authentication-endpoints/login
func (c *Client) Login(credentials *models.UserCredentials) error {
if c.auth != nil {
return nil
Expand All @@ -99,23 +104,10 @@ func (c *Client) Login(credentials *models.UserCredentials) error {
return nil
}

// CreateToken creates an access token for a user
// Logout logs user out.
// Returns the response message of the server.
//
// https://rocket.chat/docs/developer-guides/rest-api/users/createtoken/
func (c *Client) CreateToken(userID, username string) (*models.UserCredentials, error) {
response := new(logonResponse)
data := url.Values{"userId": {userID}, "username": {username}}
if err := c.PostForm("users.createToken", data, response); err != nil {
return nil, err
}
credentials := &models.UserCredentials{}
credentials.ID, credentials.Token = response.Data.UserID, response.Data.Token
return credentials, nil
}

// Logout a user. The function returns the response message of the server.
//
// https://rocket.chat/docs/developer-guides/rest-api/authentication/logout
// https://developer.rocket.chat/reference/api/rest-api/endpoints/team-collaboration-endpoints/users-endpoints/logout-user-endpoint
func (c *Client) Logout() (string, error) {

if c.auth == nil {
Expand All @@ -130,9 +122,26 @@ func (c *Client) Logout() (string, error) {
return response.Data.Message, nil
}

// CreateUser being logged in with a user that has permission to do so.
// CreateToken creates a user authentication token.
// This is the same type of session token a user would get via login and will expire the same way.
// Requires user-generate-access-token permission.
//
// https://developer.rocket.chat/reference/api/rest-api/endpoints/team-collaboration-endpoints/users-endpoints/create-users-token
func (c *Client) CreateToken(userID, username string) (*models.UserCredentials, error) {
response := new(logonResponse)
data := url.Values{"userId": {userID}, "username": {username}}
if err := c.PostForm("users.createToken", data, response); err != nil {
return nil, err
}
credentials := &models.UserCredentials{}
credentials.ID, credentials.Token = response.Data.UserID, response.Data.Token
return credentials, nil
}

// CreateUser creates a new user.
// Requires create-user permission.
//
// https://rocket.chat/docs/developer-guides/rest-api/users/create
// https://developer.rocket.chat/reference/api/rest-api/endpoints/team-collaboration-endpoints/users-endpoints/create-user
func (c *Client) CreateUser(req *models.CreateUserRequest) (*CreateUserResponse, error) {
body, err := json.Marshal(req)
if err != nil {
Expand All @@ -144,9 +153,10 @@ func (c *Client) CreateUser(req *models.CreateUserRequest) (*CreateUserResponse,
return response, err
}

// UpdateUser updates a user's data being logged in with a user that has permission to do so.
// UpdateUser updates a user's data.
// Caller must have permission to do so.
//
// https://rocket.chat/docs/developer-guides/rest-api/users/update/
// https://developer.rocket.chat/reference/api/rest-api/endpoints/team-collaboration-endpoints/users-endpoints/update-user
func (c *Client) UpdateUser(req *models.UpdateUserRequest) (*CreateUserResponse, error) {
body, err := json.Marshal(req)
if err != nil {
Expand All @@ -158,17 +168,21 @@ func (c *Client) UpdateUser(req *models.UpdateUserRequest) (*CreateUserResponse,
return response, err
}

// SetUserAvatar updates a user's avatar being logged in with a user that has permission to do so.
// SetUserAvatar updates a user's avatar.
// Caller must have permission to do so.
// Currently only passing an URL is possible.
//
// https://rocket.chat/docs/developer-guides/rest-api/users/setavatar/
// https://developer.rocket.chat/reference/api/rest-api/endpoints/team-collaboration-endpoints/users-endpoints/set-avatar
func (c *Client) SetUserAvatar(userID, username, avatarURL string) (*Status, error) {
body := fmt.Sprintf(`{ "userId": "%s","username": "%s","avatarUrl":"%s"}`, userID, username, avatarURL)
response := new(Status)
err := c.Post("users.setAvatar", bytes.NewBufferString(body), response)
return response, err
}

// GetUserStatus gets a user's status.
//
// https://developer.rocket.chat/reference/api/rest-api/endpoints/team-collaboration-endpoints/users-endpoints/get-status
func (c *Client) GetUserStatus(username string) (*UserStatusResponse, error) {
params := url.Values{
"username": []string{username},
Expand Down