Skip to content
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

docs: Updating Inline Docs and API References #1299

Merged
merged 2 commits into from
Jul 15, 2024
Merged

docs: Updating Inline Docs and API References #1299

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b9f044c
docs: Updating Inline Docs and API References
lorenzoaiello Jul 14, 2024
c6ee26b
Merge branch 'master' into docs/inline-docs-update
lorenzoaiello Jul 15, 2024
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
10 changes: 9 additions & 1 deletion apps.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,15 @@ type EventAuthorization struct {
IsEnterpriseInstall bool `json:"is_enterprise_install"`
}

// ListEventAuthorizations lists authed users and teams for the given event_context.
// You must provide an app-level token to the client using OptionAppLevelToken.
// For more details, see ListEventAuthorizationsContext documentation.
func (api *Client) ListEventAuthorizations(eventContext string) ([]EventAuthorization, error) {
return api.ListEventAuthorizationsContext(context.Background(), eventContext)
}

// ListEventAuthorizationsContext lists authed users and teams for the given event_context. You must provide an app-level token to the client using OptionAppLevelToken. More info: https://api.slack.com/methods/apps.event.authorizations.list
// ListEventAuthorizationsContext lists authed users and teams for the given event_context with a custom context.
// Slack API docs: https://api.slack.com/methods/apps.event.authorizations.list
func (api *Client) ListEventAuthorizationsContext(ctx context.Context, eventContext string) ([]EventAuthorization, error) {
resp := &listEventAuthorizationsResponse{}

Expand All @@ -43,10 +47,14 @@ func (api *Client) ListEventAuthorizationsContext(ctx context.Context, eventCont
return resp.Authorizations, nil
}

// UninstallApp uninstalls your app from a workspace.
// For more details, see UninstallAppContext documentation.
func (api *Client) UninstallApp(clientID, clientSecret string) error {
return api.UninstallAppContext(context.Background(), clientID, clientSecret)
}

// UninstallAppContext uninstalls your app from a workspace with a custom context.
// Slack API docs: https://api.slack.com/methods/apps.uninstall
func (api *Client) UninstallAppContext(ctx context.Context, clientID, clientSecret string) error {
values := url.Values{
"client_id": {clientID},
Expand Down
11 changes: 7 additions & 4 deletions auth.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,14 @@ func (api *Client) authRequest(ctx context.Context, path string, values url.Valu
return response, response.Err()
}

// SendAuthRevoke will send a revocation for our token
// SendAuthRevoke will send a revocation for our token.
// For more details, see SendAuthRevokeContext documentation.
func (api *Client) SendAuthRevoke(token string) (*AuthRevokeResponse, error) {
return api.SendAuthRevokeContext(context.Background(), token)
}

// SendAuthRevokeContext will send a revocation request for our token to api.revoke with context
// SendAuthRevokeContext will send a revocation request for our token to api.revoke with a custom context.
// Slack API docs: https://api.slack.com/methods/auth.revoke
func (api *Client) SendAuthRevokeContext(ctx context.Context, token string) (*AuthRevokeResponse, error) {
if token == "" {
token = api.token
Expand All @@ -50,12 +52,13 @@ type ListTeamsParameters struct {
}

// ListTeams returns all workspaces a token can access.
// More info: https://api.slack.com/methods/admin.teams.list
// For more details, see ListTeamsContext documentation.
func (api *Client) ListTeams(params ListTeamsParameters) ([]Team, string, error) {
return api.ListTeamsContext(context.Background(), params)
}

// ListTeams returns all workspaces a token can access with a custom context.
// ListTeamsContext returns all workspaces a token can access with a custom context.
// Slack API docs: https://api.slack.com/methods/auth.teams.list
func (api *Client) ListTeamsContext(ctx context.Context, params ListTeamsParameters) ([]Team, string, error) {
values := url.Values{
"token": {api.token},
Expand Down
18 changes: 14 additions & 4 deletions bookmarks.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,14 @@ type listBookmarksResponse struct {
SlackResponse
}

// AddBookmark adds a bookmark in a channel
// AddBookmark adds a bookmark in a channel.
// For more details, see AddBookmarkContext documentation.
func (api *Client) AddBookmark(channelID string, params AddBookmarkParameters) (Bookmark, error) {
return api.AddBookmarkContext(context.Background(), channelID, params)
}

// AddBookmarkContext adds a bookmark in a channel with a custom context
// AddBookmarkContext adds a bookmark in a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/bookmarks.add
func (api *Client) AddBookmarkContext(ctx context.Context, channelID string, params AddBookmarkParameters) (Bookmark, error) {
values := url.Values{
"channel_id": {channelID},
Expand Down Expand Up @@ -89,12 +91,14 @@ func (api *Client) AddBookmarkContext(ctx context.Context, channelID string, par
return response.Bookmark, response.Err()
}

// RemoveBookmark removes a bookmark from a channel
// RemoveBookmark removes a bookmark from a channel.
// For more details, see RemoveBookmarkContext documentation.
func (api *Client) RemoveBookmark(channelID, bookmarkID string) error {
return api.RemoveBookmarkContext(context.Background(), channelID, bookmarkID)
}

// RemoveBookmarkContext removes a bookmark from a channel with a custom context
// RemoveBookmarkContext removes a bookmark from a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/bookmarks.remove
func (api *Client) RemoveBookmarkContext(ctx context.Context, channelID, bookmarkID string) error {
values := url.Values{
"channel_id": {channelID},
Expand All @@ -111,11 +115,13 @@ func (api *Client) RemoveBookmarkContext(ctx context.Context, channelID, bookmar
}

// ListBookmarks returns all bookmarks for a channel.
// For more details, see ListBookmarksContext documentation.
func (api *Client) ListBookmarks(channelID string) ([]Bookmark, error) {
return api.ListBookmarksContext(context.Background(), channelID)
}

// ListBookmarksContext returns all bookmarks for a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/bookmarks.edit
func (api *Client) ListBookmarksContext(ctx context.Context, channelID string) ([]Bookmark, error) {
values := url.Values{
"channel_id": {channelID},
Expand All @@ -130,10 +136,14 @@ func (api *Client) ListBookmarksContext(ctx context.Context, channelID string) (
return response.Bookmarks, response.Err()
}

// EditBookmark edits a bookmark in a channel.
// For more details, see EditBookmarkContext documentation.
func (api *Client) EditBookmark(channelID, bookmarkID string, params EditBookmarkParameters) (Bookmark, error) {
return api.EditBookmarkContext(context.Background(), channelID, bookmarkID, params)
}

// EditBookmarkContext edits a bookmark in a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/bookmarks.edit
func (api *Client) EditBookmarkContext(ctx context.Context, channelID, bookmarkID string, params EditBookmarkParameters) (Bookmark, error) {
values := url.Values{
"channel_id": {channelID},
Expand Down
6 changes: 4 additions & 2 deletions bots.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,14 @@ type GetBotInfoParameters struct {
TeamID string
}

// GetBotInfo will retrieve the complete bot information
// GetBotInfo will retrieve the complete bot information.
// For more details, see GetBotInfoContext documentation.
func (api *Client) GetBotInfo(parameters GetBotInfoParameters) (*Bot, error) {
return api.GetBotInfoContext(context.Background(), parameters)
}

// GetBotInfoContext will retrieve the complete bot information using a custom context
// GetBotInfoContext will retrieve the complete bot information using a custom context.
// Slack API docs: https://api.slack.com/methods/bots.info
func (api *Client) GetBotInfoContext(ctx context.Context, parameters GetBotInfoParameters) (*Bot, error) {
values := url.Values{
"token": {api.token},
Expand Down
73 changes: 41 additions & 32 deletions chat.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ type chatResponseFull struct {
SlackResponse
}

// getMessageTimestamp will inspect the `chatResponseFull` to ruturn a timestamp value
// getMessageTimestamp will inspect the `chatResponseFull` to return a timestamp value
// in `chat.postMessage` its under `ts`
// in `chat.postEphemeral` its under `message_ts`
func (c chatResponseFull) getMessageTimestamp() string {
Expand Down Expand Up @@ -88,12 +88,14 @@ func NewPostMessageParameters() PostMessageParameters {
}
}

// DeleteMessage deletes a message in a channel
// DeleteMessage deletes a message in a channel.
// For more details, see DeleteMessageContext documentation.
func (api *Client) DeleteMessage(channel, messageTimestamp string) (string, string, error) {
return api.DeleteMessageContext(context.Background(), channel, messageTimestamp)
}

// DeleteMessageContext deletes a message in a channel with a custom context
// DeleteMessageContext deletes a message in a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.delete
func (api *Client) DeleteMessageContext(ctx context.Context, channel, messageTimestamp string) (string, string, error) {
respChannel, respTimestamp, _, err := api.SendMessageContext(
ctx,
Expand All @@ -106,13 +108,13 @@ func (api *Client) DeleteMessageContext(ctx context.Context, channel, messageTim
// ScheduleMessage sends a message to a channel.
// Message is escaped by default according to https://api.slack.com/docs/formatting
// Use http://davestevens.github.io/slack-message-builder/ to help crafting your message.
// For more details, see ScheduleMessageContext documentation.
func (api *Client) ScheduleMessage(channelID, postAt string, options ...MsgOption) (string, string, error) {
return api.ScheduleMessageContext(context.Background(), channelID, postAt, options...)
}

// ScheduleMessageContext sends a message to a channel with a custom context
//
// For more details, see ScheduleMessage documentation.
// ScheduleMessageContext sends a message to a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.scheduleMessage
func (api *Client) ScheduleMessageContext(ctx context.Context, channelID, postAt string, options ...MsgOption) (string, string, error) {
respChannel, respTimestamp, _, err := api.SendMessageContext(
ctx,
Expand All @@ -126,12 +128,13 @@ func (api *Client) ScheduleMessageContext(ctx context.Context, channelID, postAt
// PostMessage sends a message to a channel.
// Message is escaped by default according to https://api.slack.com/docs/formatting
// Use http://davestevens.github.io/slack-message-builder/ to help crafting your message.
// For more details, see PostMessageContext documentation.
func (api *Client) PostMessage(channelID string, options ...MsgOption) (string, string, error) {
return api.PostMessageContext(context.Background(), channelID, options...)
}

// PostMessageContext sends a message to a channel with a custom context
// For more details, see PostMessage documentation.
// PostMessageContext sends a message to a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.postMessage
func (api *Client) PostMessageContext(ctx context.Context, channelID string, options ...MsgOption) (string, string, error) {
respChannel, respTimestamp, _, err := api.SendMessageContext(
ctx,
Expand All @@ -145,12 +148,13 @@ func (api *Client) PostMessageContext(ctx context.Context, channelID string, opt
// PostEphemeral sends an ephemeral message to a user in a channel.
// Message is escaped by default according to https://api.slack.com/docs/formatting
// Use http://davestevens.github.io/slack-message-builder/ to help crafting your message.
// For more details, see PostEphemeralContext documentation.
func (api *Client) PostEphemeral(channelID, userID string, options ...MsgOption) (string, error) {
return api.PostEphemeralContext(context.Background(), channelID, userID, options...)
}

// PostEphemeralContext sends an ephemeal message to a user in a channel with a custom context
// For more details, see PostEphemeral documentation
// PostEphemeralContext sends an ephemeral message to a user in a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.postEphemeral
func (api *Client) PostEphemeralContext(ctx context.Context, channelID, userID string, options ...MsgOption) (timestamp string, err error) {
_, timestamp, _, err = api.SendMessageContext(
ctx,
Expand All @@ -161,12 +165,14 @@ func (api *Client) PostEphemeralContext(ctx context.Context, channelID, userID s
return timestamp, err
}

// UpdateMessage updates a message in a channel
// UpdateMessage updates a message in a channel.
// For more details, see UpdateMessageContext documentation.
func (api *Client) UpdateMessage(channelID, timestamp string, options ...MsgOption) (string, string, string, error) {
return api.UpdateMessageContext(context.Background(), channelID, timestamp, options...)
}

// UpdateMessageContext updates a message in a channel
// UpdateMessageContext updates a message in a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.update
func (api *Client) UpdateMessageContext(ctx context.Context, channelID, timestamp string, options ...MsgOption) (string, string, string, error) {
return api.SendMessageContext(
ctx,
Expand All @@ -176,38 +182,38 @@ func (api *Client) UpdateMessageContext(ctx context.Context, channelID, timestam
)
}

// UnfurlMessage unfurls a message in a channel
// UnfurlMessage unfurls a message in a channel.
// For more details, see UnfurlMessageContext documentation.
func (api *Client) UnfurlMessage(channelID, timestamp string, unfurls map[string]Attachment, options ...MsgOption) (string, string, string, error) {
return api.UnfurlMessageContext(context.Background(), channelID, timestamp, unfurls, options...)
}

// UnfurlMessageContext unfurls a message in a channel with a custom context
// UnfurlMessageContext unfurls a message in a channel with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.unfurl
func (api *Client) UnfurlMessageContext(ctx context.Context, channelID, timestamp string, unfurls map[string]Attachment, options ...MsgOption) (string, string, string, error) {
return api.SendMessageContext(ctx, channelID, MsgOptionUnfurl(timestamp, unfurls), MsgOptionCompose(options...))
}

// UnfurlMessageWithAuthURL sends an unfurl request containing an
// authentication URL.
// For more details see:
// https://api.slack.com/reference/messaging/link-unfurling#authenticated_unfurls
// UnfurlMessageWithAuthURL sends an unfurl request containing an authentication URL.
// For more details, see UnfurlMessageWithAuthURLContext documentation.
func (api *Client) UnfurlMessageWithAuthURL(channelID, timestamp string, userAuthURL string, options ...MsgOption) (string, string, string, error) {
return api.UnfurlMessageWithAuthURLContext(context.Background(), channelID, timestamp, userAuthURL, options...)
}

// UnfurlMessageWithAuthURLContext sends an unfurl request containing an
// authentication URL.
// For more details see:
// https://api.slack.com/reference/messaging/link-unfurling#authenticated_unfurls
// UnfurlMessageWithAuthURLContext sends an unfurl request containing an authentication URL with a custom context.
// For more details see: https://api.slack.com/reference/messaging/link-unfurling#authenticated_unfurls
func (api *Client) UnfurlMessageWithAuthURLContext(ctx context.Context, channelID, timestamp string, userAuthURL string, options ...MsgOption) (string, string, string, error) {
return api.SendMessageContext(ctx, channelID, MsgOptionUnfurlAuthURL(timestamp, userAuthURL), MsgOptionCompose(options...))
}

// SendMessage more flexible method for configuring messages.
// For more details, see SendMessageContext documentation.
func (api *Client) SendMessage(channel string, options ...MsgOption) (string, string, string, error) {
return api.SendMessageContext(context.Background(), channel, options...)
}

// SendMessageContext more flexible method for configuring messages with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.postMessage
func (api *Client) SendMessageContext(ctx context.Context, channelID string, options ...MsgOption) (_channel string, _timestamp string, _text string, err error) {
var (
req *http.Request
Expand Down Expand Up @@ -771,22 +777,21 @@ func MsgOptionPostMessageParameters(params PostMessageParameters) MsgOption {
}
}

// PermalinkParameters are the parameters required to get a permalink to a
// message. Slack documentation can be found here:
// https://api.slack.com/methods/chat.getPermalink
// PermalinkParameters are the parameters required to get a permalink to a message.
type PermalinkParameters struct {
Channel string
Ts string
}

// GetPermalink returns the permalink for a message. It takes
// PermalinkParameters and returns a string containing the permalink. It
// returns an error if unable to retrieve the permalink.
// GetPermalink returns the permalink for a message. It takes PermalinkParameters and returns a string containing the
// permalink. It returns an error if unable to retrieve the permalink.
// For more details, see GetPermalinkContext documentation.
func (api *Client) GetPermalink(params *PermalinkParameters) (string, error) {
return api.GetPermalinkContext(context.Background(), params)
}

// GetPermalinkContext returns the permalink for a message using a custom context.
// Slack API docs: https://api.slack.com/methods/chat.getPermalink
func (api *Client) GetPermalinkContext(ctx context.Context, params *PermalinkParameters) (string, error) {
values := url.Values{
"channel": {params.Channel},
Expand Down Expand Up @@ -814,12 +819,14 @@ type GetScheduledMessagesParameters struct {
Oldest string
}

// GetScheduledMessages returns the list of scheduled messages based on params
// GetScheduledMessages returns the list of scheduled messages based on params.
// For more details, see GetScheduledMessagesContext documentation.
func (api *Client) GetScheduledMessages(params *GetScheduledMessagesParameters) (channels []ScheduledMessage, nextCursor string, err error) {
return api.GetScheduledMessagesContext(context.Background(), params)
}

// GetScheduledMessagesContext returns the list of scheduled messages in a Slack team with a custom context
// GetScheduledMessagesContext returns the list of scheduled messages based on params with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.getScheduledMessages.list
func (api *Client) GetScheduledMessagesContext(ctx context.Context, params *GetScheduledMessagesParameters) (channels []ScheduledMessage, nextCursor string, err error) {
values := url.Values{
"token": {api.token},
Expand Down Expand Up @@ -862,12 +869,14 @@ type DeleteScheduledMessageParameters struct {
AsUser bool
}

// DeleteScheduledMessage returns the list of scheduled messages based on params
// DeleteScheduledMessage deletes a pending scheduled message.
// For more details, see DeleteScheduledMessageContext documentation.
func (api *Client) DeleteScheduledMessage(params *DeleteScheduledMessageParameters) (bool, error) {
return api.DeleteScheduledMessageContext(context.Background(), params)
}

// DeleteScheduledMessageContext returns the list of scheduled messages in a Slack team with a custom context
// DeleteScheduledMessageContext deletes a pending scheduled message with a custom context.
// Slack API docs: https://api.slack.com/methods/chat.deleteScheduledMessage
func (api *Client) DeleteScheduledMessageContext(ctx context.Context, params *DeleteScheduledMessageParameters) (bool, error) {
values := url.Values{
"token": {api.token},
Expand Down
Loading
Loading