lightning

type Attachment struct {
	// A downloadable https (not http, which will fail) URL pointing to the file.
	URL string `json:"url"`
	// A somewhat user-friendly file name.
	Name string `json:"name"`
	// File size in bytes.
	Size int64 `json:"size"`
	// Mimetype for the file (not always set).
	Type string `json:"type,omitempty"`
	// Description for the file (not always set).
	Description string `json:"description,omitempty"`
}

type BaseMessage struct {
	// Time the event was created (or possibly received).
	Time time.Time `json:"time,omitzero"`
	// Unique identifier for the event.
	EventID string `json:"event_id"`
	// Channel where the event happened.
	ChannelID string `json:"channel_id"`
}

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

type BotReliant interface {
	DoNotUseThisUnlessYouAreAnAPIPluginGetBot(bot *Bot, instanceName string)
}

type ChannelDisabled struct {
	// Read indicates whether you are unable to read from a channel anymore (getting messages).
	Read bool `json:"read"`
	// Write indicates whether you are unable to write to a channel anymore (sending messages).
	Write bool `json:"write"`
}

type ChannelDisabler interface {
	error

	// Disable returns a [*ChannelDisabled] which describes whether you are unable to read/write to a channel.
	Disable() *ChannelDisabled
}

type Command struct {
	// Executor is the function that gets called when a user executes the command.
	Executor func(options *CommandOptions)
	// Name is a unique string identifying the command.
	Name string
	// Description is a string describing the command and its purpose.
	Description string
	// Subcommands is a map of nested commands.
	Subcommands map[string]Command
	// Arguments are input fields which get parsed into [CommandOptions.Arguments] and passed to the Executor.
	Arguments []CommandArgument
}

type CommandArgument struct {
	// Name is a unique string identifying the argument.
	Name string
	// Description is a string describing the argument and its purpose.
	Description string
}

type CommandEvent struct {
	CommandOptions

	// Subcommand the first subcommand used, if any. Should not be used with Options.
	Subcommand string
	// Command is the name of the command called; it is required.
	Command string
	// Options is a variadic list of arguments which have not been parsed and may include a subcommand. Should not be
	// used with Options.
	Options []string
}

type CommandOptions struct {
	BaseMessage

	// Arguments contains parsed [CommandArgument] key-value pairs.
	Arguments map[string]string
	// Author is the user which executed the [Command].
	Author MessageAuthor
	// Bot refers to the [*Bot] instance a [Command] was executed on.
	Bot *Bot
	// Reply creates a new [Message] which replies to the message executing the command.
	Reply func(message *Message, sensitive bool)
	// Prefix is the prefix used when creating the [*Bot] instance the [Command] was executed on.
	Prefix string
}

type EditedMessage struct {
	Message
}

type Embed struct {
	// Author is an optional author on an embed.
	Author *EmbedAuthor `json:"author,omitempty"`
	// Footer is an optional footer on an embed.
	Footer *EmbedFooter `json:"footer,omitempty"`
	// Image is full-width optional [Media] on an embed.
	Image *Media `json:"image,omitempty"`
	// Thumbnail is small optional [Media] on an embed typically in the top-right.
	Thumbnail *Media `json:"thumbnail,omitempty"`
	// Video is full-width optional [Media] on an embed.
	Video *Media `json:"video,omitempty"`
	// Timestamp is an optional RFC3339 formatted time.
	Timestamp string `json:"timestamp,omitempty"`
	// Title is an optional title preceding an embed.
	Title string `json:"title,omitempty"`
	// URL is an optional link for an embed title.
	URL string `json:"url,omitempty"`
	// Description is the main body of an embed.
	Description string `json:"description,omitempty"`
	// Fields are optional additions to an embed.
	Fields []EmbedField `json:"fields,omitempty"`
	// Color is an RGB color value for an embed.
	Color int `json:"color,omitzero"`
}

type EmbedAuthor struct {
	// URL is a link the Name points to.
	URL string `json:"url,omitempty"`
	// IconURL is an https URL pointing to an icon to be shown next to the Name.
	IconURL string `json:"icon_url,omitempty"`
	// Name is a string to be shown above the rest of an [Embed].
	Name string `json:"name,omitempty"`
}

type EmbedField struct {
	// Name is bold text shown above/next to the Value.
	Name string `json:"name,omitempty"`
	// Value is a string show below an [Embed.Description].
	Value string `json:"value,omitempty"`
	// Inline controls whether a field should be shown on a newline.
	Inline bool `json:"inline,omitzero"`
}

type EmbedFooter struct {
	// IconURL is an https URL pointing to an icon to be shown next to the Text.
	IconURL string `json:"icon_url,omitempty"`
	// Text is a string to be shown below the rest of an [Embed].
	Text string `json:"text,omitempty"`
}

type Media struct {
	// URL is a downloadable https url pointing to the image.
	URL string `json:"url"`
	// Height is an optional height for an embed image.
	Height int `json:"height,omitzero"`
	// Width is an optional width for an embed image.
	Width int `json:"width,omitzero"`
}

type Mention struct {
	// Name is a user-facing fallback for the thing being mentioned.
	Name string `json:"name"`
	// Text is the content mentioning the user.
	Mention string `json:"mention"`
	// URL is an optional link pointing to the thing mentioned.
	URL string `json:"url,omitempty"`
	// Type is the thing being mentioned.
	Type MentionType `json:"type"`
}

type MentionType int

type Message struct {
	BaseMessage

	// Author is the person or bot who sent a message.
	Author MessageAuthor `json:"author,omitzero"`
	// Content is a Markdown-like string in a message.
	Content string `json:"content,omitempty"`
	// [Attachment]s are downloadable files on a message.
	Attachments []Attachment `json:"attachments,omitempty"`
	// Embeds are Discord-like [Embed]s on a message. Some platforms transform them into text using [Embed.ToMarkdown].
	Embeds []Embed `json:"embeds,omitempty"`
	// RepliedTo contains a list of message IDs to reply to. Some platforms only support using the first reply ID.
	RepliedTo []string `json:"replied_to,omitempty"`
	// Mentions are the specific [Mention]s on a message.
	Mentions []Mention `json:"mentions,omitempty"`
}

type MessageAuthor struct {
	// ID is the user's ID on their originating platform.
	ID string `json:"id"`
	// Username is the user's display name.
	Username string `json:"username"`
	// ProfilePicture is a URL pointing to a downloadable profile picture.
	ProfilePicture string `json:"profile_picture,omitempty"`
	// Color is a six character hex color code (with preceding hashtag) representing a role/profile color.
	Color string `json:"color,omitempty"`
}

type MessageOptions struct {
	// DMUser allows you to send a message to a given user directly, if available on the platform.
	DMUser string `json:"dm_user,omitempty"`
	// ChannelData allows you to send messages with a webhook, or another interface allowing for masquerades or similar.
	ChannelData map[string]string `json:"channel_data,omitempty"`
	// UsernameSuffix allows you to specify an optional suffix for the given username. It exists to make bridging
	// slightly easier by ensuring the suffix is added appropriately.
	UsernameSuffix string `json:"username_suffix,omitempty"`
	// AllowEveryonePings, when set, allows you sending a [Mention] with a type of either [MentionOnline] or
	// [MentionEveryone].
	AllowEveryonePings bool `json:"allow_everyone_pings,omitzero"`
}

type MissingPluginError struct {
	Name string
}

type Plugin interface {
	// IsAdmin allows you to check if a given user has administrator (or similar) privileges within a channel.
	IsAdmin(channel, user string) (bool, error)
	// SetupChannel allows you to create channel data used in [MessageOptions] to send messages with a webhook, or
	// another interface allowing for masquerades or similar.
	SetupChannel(channel string) (map[string]string, error)
	// SendMessage sends the provided [Message] to the channel ID provided with the given [MessageOptions].
	SendMessage(message *Message, opts *MessageOptions) ([]string, error)
	// EditMessage edits the provided [Message] with ids provided by [Plugin.SendMessage] and the options in the
	// provided [MessageOptions].
	EditMessage(message *Message, ids []string, opts *MessageOptions) ([]string, error)
	// DeleteMessage deletes the provided message ids provided by [Plugin.SendMessage] or [Plugin.EditMessage] in a
	// given channel with the provided [MessageOptions].
	DeleteMessage(channel string, ids []string, opts *MessageOptions) error
	// SendTyping allows you to show typing in a channel in a given channel with the provided [MessageOptions].
	SendTyping(channel, user string, opts *MessageOptions) error
	// SetupCommands allows calls to [Bot.AddCommand] to register platform-specific handlers for commands, such as slash
	// commands.
	SetupCommands(command map[string]Command)
	// ListenMessages allows calls to [Bot.AddHandler] to receive message creation events from the platform.
	ListenMessages() <-chan *Message
	// ListenEdits allows calls to [Bot.AddHandler] to receive message edit events from the platform.
	ListenEdits() <-chan *EditedMessage
	// ListenDeletes allows calls to [Bot.AddHandler] to receive message deletion events from the platform.
	ListenDeletes() <-chan *BaseMessage
	// ListenCommands allows commands registered in [Bot.AddCommand] to be executed by platform-specific handlers for
	// commands, such as slash commands.
	ListenCommands() <-chan *CommandEvent
	// ListenTyping allows calls to [Bot.AddHandler] to receive typing events from the platform.
	ListenTyping() <-chan *TypingEvent
}

type PluginConstructor func(config map[string]string, data PluginDataStorage) (Plugin, error)

type PluginDataStorage interface {
	StoreData(data map[string]any) error
	ReadData() (map[string]any, error)
}

type PluginMethodError struct {
	ID     string
	Method string
	// contains filtered or unexported fields
}

type PluginRegisteredError struct {
	Name string
}

type TypingEvent struct {
	// Time the typing started.
	Time time.Time `json:"time,omitzero"`
	// Channel where the event happened.
	ChannelID string `json:"channel_id"`
	// User who is typing.
	UserID string `json:"user_id"`
}