slack

package
v0.28.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package slack talks to the Slack Web API for the PR notifier: posting, updating, and deleting messages, adding emoji reactions, and composing the blocks of the notification.

Index

Constants

This section is empty.

Variables

View Source
var ErrMessageNotFound = errors.New("slack: message not found")

ErrMessageNotFound reports that the channel/ts pair addresses no message — it was deleted, or the bot cannot see it.

View Source
var ErrUnexpectedMessageShape = errors.New("slack: unexpected message shape")

ErrUnexpectedMessageShape reports a message whose headline could not be rewritten. Rewriting is refused rather than guessed at: a headline we cannot parse would carry its original mentions into the new channel.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	Method string
	Code   string
	// contains filtered or unexported fields
}

APIError represents a non-ok Slack API response. header carries the response headers so a rate-limited call can read Retry-After.

func (*APIError) Error

func (e *APIError) Error() string

type Block

type Block struct {
	Type     string       `json:"type"`
	Text     *TextObject  `json:"text,omitempty"`
	Elements []TextObject `json:"elements,omitempty"`
	Buttons  []Button     `json:"-"`
}

Block is the narrow subset of Block Kit the notifier emits: a "section" (Text set), a "context" line (Elements set), or an "actions" row (Buttons set). Exactly one shape is populated per block. Section and context marshal through the struct tags below; an "actions" block marshals its Buttons as button elements via MarshalJSON.

func (Block) MarshalJSON

func (b Block) MarshalJSON() ([]byte, error)

MarshalJSON keeps section/context blocks byte-for-byte as their struct tags would render, and emits an "actions" block as {"type":"actions","elements": [{"type":"button",...}]} — Block Kit puts buttons under elements, but with a different element shape than a context line, so the two can't share the field.

type Button

type Button struct {
	Text     string
	ActionID string
	Value    string
	Style    string
	URL      string
}

Button is an interactive Block Kit button. Text is rendered into a plain_text object; ActionID identifies the button to the interactions endpoint; Value is the opaque payload it carries back on click; Style is Slack's button style ("primary"/"danger", empty for default). URL, when set, makes Slack open the link in the clicker's browser in addition to delivering the interaction — so the click both records the review and sends the reviewer to the PR page.

type ChannelInfo

type ChannelInfo struct {
	ID         string
	Name       string
	IsMember   bool
	IsArchived bool
}

ChannelInfo is the subset of conversations.info we need for validation.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a thin Slack Web API client covering only the endpoints needed by the notifier. It is safe for concurrent use.

func NewClient

func NewClient(hc *http.Client, token string, opts ...Option) *Client

NewClient builds a Client. The httpClient is used as-is; callers should configure timeouts on it.

func (*Client) AddReaction

func (c *Client) AddReaction(ctx context.Context, channel, ts, name string) error

AddReaction adds a reaction emoji to a message. "already_reacted" is treated as success — it means the reaction we wanted is already there.

func (*Client) AuthTest

func (c *Client) AuthTest(ctx context.Context) (userID string, scopes []string, err error)

AuthTest returns the bot's user_id and the OAuth scopes Slack reports as granted to the token. Scopes are read from the X-OAuth-Scopes response header (comma-separated) and used by validation to verify required scopes are present.

func (*Client) ConversationsInfo

func (c *Client) ConversationsInfo(ctx context.Context, channel string) (ChannelInfo, error)

ConversationsInfo returns metadata about a channel, including whether the bot is a member. The channel argument must be a Slack channel ID.

func (*Client) DeleteMessage

func (c *Client) DeleteMessage(ctx context.Context, channel, ts string) error

DeleteMessage removes an existing message by ts. "message_not_found" is treated as success — somebody removed the message by hand and the outcome we wanted already holds.

func (*Client) GetReactions

func (c *Client) GetReactions(ctx context.Context, channel, ts string) ([]Reaction, error)

GetReactions returns the reactions attached to a message, or an empty slice if none are present.

func (*Client) MessageContent added in v0.25.0

func (c *Client) MessageContent(ctx context.Context, channel, ts string) (RawMessageContent, error)

MessageContent reads a single message by its ts, returning its blocks unparsed so a caller can repost them elsewhere without re-composing. A channel/ts pair that addresses nothing yields ErrMessageNotFound.

func (*Client) PostMessage

func (c *Client) PostMessage(ctx context.Context, channel string, msg Message) (string, error)

PostMessage posts a new message to channel and returns its ts. The Block Kit blocks render in-channel; msg.Fallback is sent as the top-level text Slack uses for the push preview and screen readers.

func (*Client) PostMessageRawBlocks added in v0.25.0

func (c *Client) PostMessageRawBlocks(ctx context.Context, channel string, blocks []json.RawMessage, fallback string) (string, error)

PostMessageRawBlocks posts a new message from pre-rendered blocks and returns its ts. It is PostMessage for blocks that were not built by the Composer — the write counterpart of MessageContent.

func (*Client) PostReply

func (c *Client) PostReply(ctx context.Context, channel, threadTS string, msg Message) (string, error)

PostReply posts a message as a reply in the thread rooted at threadTS and returns its ts. It is PostMessage plus a thread_ts, kept separate so the webhook path stays a plain top-level post.

func (*Client) ReplyCount added in v0.26.0

func (c *Client) ReplyCount(ctx context.Context, channel, ts string) (int, error)

ReplyCount reads how many replies sit in the thread under the message at ts.

func (*Client) UpdateMessage

func (c *Client) UpdateMessage(ctx context.Context, channel, ts string, msg Message) error

UpdateMessage edits an existing message by ts, replacing both its blocks and the top-level text fallback.

func (*Client) UpdateMessageRawBlocks

func (c *Client) UpdateMessageRawBlocks(ctx context.Context, channel, ts string, blocks []json.RawMessage, fallback string) error

UpdateMessageRawBlocks edits a message in place, sending blocks verbatim. Callers pass the message's existing blocks (as echoed back by Slack in the interaction payload) plus any additions, so the original rendering is preserved without re-composing it. fallback is the top-level text.

type Composer

type Composer struct {
	// contains filtered or unexported fields
}

Composer renders Slack-formatted notification messages.

func NewComposer

func NewComposer(newPREmoji string, startReviewButton bool) *Composer

NewComposer returns a Composer that prefixes new-PR messages with the given reaction-style emoji name (without colons). startReviewButton adds the Start review button to new-PR messages; pass it only when the Slack interactions endpoint is served, or the button would lead a click nowhere.

func (*Composer) BotMessage

func (c *Composer) BotMessage(pr PRDetails, mentions []string, bot string, security bool) Message

BotMessage renders the compact notification for a PR opened by a dependency bot. bot is the lowercase bot name ("dependabot" / "renovate"). When security is true it uses the rotating-light advisory template; otherwise the package routine-bump template. It stays deliberately compact — a single section, no context line — so bot bumps read as a one-liner. Mentions follow the same empty-list rule as NewMessage; the PR author is omitted because the bot name carries it.

func (*Composer) NewMessage

func (c *Composer) NewMessage(pr PRDetails, mentions []string, newPREmoji string) Message

NewMessage renders the initial notification for a PR: a headline section with the new-PR emoji, any mentions, and the linked title, plus a muted context line carrying repo, author, and the localized open time, plus the Start review button when the composer was built with it. Mentions stay in the section because Slack only reliably notifies on a mention in a section/ top-level text — a context block renders the mention as gray text but does not ping. When the mentions list is empty the prefix is omitted entirely so the message has no stranded ", ". newPREmoji is the per-repo reaction emoji name (without colons). If empty, falls back to the composer's default emoji.

func (*Composer) ReviewedByMarker

func (c *Composer) ReviewedByMarker(userIDs []string) Block

ReviewedByMarker renders the muted "reviewed by <@U…>, <@U…>" context line appended to a closed/merged PR message, listing everyone who reviewed it. The caller passes a non-empty, deduped list of Slack user IDs.

func (*Composer) ReviewingMarker

func (c *Composer) ReviewingMarker(userID string, since time.Time) Block

ReviewingMarker renders the small context line appended to a PR message when a reviewer starts: ":eye: <@U…> reviewing · since <localized time>". Multiple markers accumulate on a message as more people review the same PR.

func (*Composer) ScheduledList added in v0.27.0

func (c *Composer) ScheduledList(mentions []string, prs []PRDetails) Message

ScheduledList renders one channel's list of PRs queued under the scheduled notification strategy: a headline with the mentions and the count, then one line per PR. The list holds many PRs, so it carries no Start review button. Lines past Slack's block cap collapse into a final "…and N more" line.

func (*Composer) StuckDigestList

func (c *Composer) StuckDigestList(prs []StuckPR) Message

StuckDigestList renders the thread reply for a channel's stuck-PR digest: one line per stuck PR, with no headline (mentions and count live on the parent). The caller must pass a non-empty prs slice; an empty channel is skipped upstream.

A busy channel can list more PRs than fit in one Block Kit section (Slack caps section text at 3000 chars), so the lines are packed into successive section blocks, each kept under maxSectionChars.

func (*Composer) StuckDigestParent

func (c *Composer) StuckDigestParent(mentions []string, count int) Message

StuckDigestParent renders the static parent of a channel's stuck-PR digest: a headline carrying the channel's mentions (so the post actually notifies) and the PR count. The PR list itself is posted as a thread reply via StuckDigestList — keeping the channel feed to one quiet line per channel. Mentions follow the same empty-list rule as NewMessage.

func (*Composer) UpdatedMessage

func (c *Composer) UpdatedMessage(pr PRDetails, merged bool, emoji string) Message

UpdatedMessage renders the closed-PR decoration. Block Kit cannot wrap the whole prior message string the way the legacy plain-text format did, so the message is rebuilt from PR details: the title is struck through inside the section, the leading emoji is swapped to the merged/closed reaction emoji, and a [Merged]/[Closed] label is prepended. The context line is preserved.

type Message

type Message struct {
	Blocks   []Block
	Fallback string
}

Message is a composed Slack message: the Block Kit blocks rendered in the channel plus a plain-text Fallback. Slack uses Fallback for the mobile push preview and for screen readers — it does not read interior block text for either — so every Message carries one.

func MovedPointer added in v0.25.0

func MovedPointer(content RawMessageContent, toChannel string) (Message, error)

MovedPointer rewrites the original message into a one-line pointer at the channel its replacement now lives in: the PR link struck through, the destination linked, and nothing else. The context line, review markers and the Start review button are dropped — the button would decorate a message that is no longer the PR's, and the detail now lives in the new channel.

type Option

type Option func(*Client)

Option configures Client construction.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the Slack API base URL — used in tests against an httptest.Server. The URL must NOT have a trailing slash.

type PRDetails

type PRDetails struct {
	Repository string
	Number     int
	Title      string
	URL        string
	Author     string
	// CreatedAt is the PR's open time, rendered as a localized date token in
	// the context line. The zero value omits the "opened …" clause.
	CreatedAt time.Time
}

PRDetails is the subset of PR information the Composer needs to render a notification. It is detached from any HTTP payload type so the composer stays a pure function of its inputs.

type RawMessageContent added in v0.25.0

type RawMessageContent struct {
	Blocks   []json.RawMessage
	Fallback string
}

RawMessageContent is a message as Slack stored it: its Block Kit blocks verbatim, plus the top-level text Slack uses for the push preview.

func MovedMessage added in v0.25.0

func MovedMessage(content RawMessageContent) (RawMessageContent, error)

MovedMessage rewrites a message for reposting in another channel: the headline becomes a mention-free "moved" line built around the original PR link, and every other block (context line, review markers, the Start review button) is carried over verbatim.

type Reaction

type Reaction struct {
	Name  string   `json:"name"`
	Count int      `json:"count"`
	Users []string `json:"users"`
}

Reaction is one entry from reactions.get.

type StuckPR

type StuckPR struct {
	Repository string
	Number     int
	URL        string
	IdleDays   int
}

StuckPR is one entry in a stuck-PR digest: a PR that has seen no activity since before today. The PR title is intentionally absent — the store does not keep it — so the digest links by repository and number.

type TextObject

type TextObject struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

TextObject is a Block Kit text object. Sections/contexts emit mrkdwn; button labels emit plain_text.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL