flamingo

type Action struct {
	// UserAction is the action performed by the user.
	UserAction UserAction
	// User is the user that performed the action.
	User User
	// Channel is the channel in which the action was performed.
	Channel Channel
	// OriginalMessage is the message the action originated from.
	OriginalMessage Message
	// Extra parameters. The contents of this field depend on the
	// specific client you are using. Usually, it is the full
	// data received.
	Extra interface{}
}

type ActionHandler func(Bot, Action)

type ActionWaitingPolicy struct {
	// Reply will send a reply every time an action or message arrives and
	// it's not the one we're waiting for.
	Reply bool
	// Message is the text of the reply message. Only necessary if Reply is true.
	Message string
}

type AnswerChecker func(Message) *OutgoingMessage

type Bot interface {
	// ID returns the ID of the bot.
	ID() string

	// Reply replies a Message with an OutgoingMessage and returns the ID of the
	// reply along with an error, if any.
	Reply(Message, OutgoingMessage) (string, error)

	// Ask sends and OutgoingMessage (typically a question) and returns the ID of
	// the question asked, the Message the user replied and an error, if any.
	Ask(OutgoingMessage) (string, Message, error)

	// Conversation asks a series of questions and waits for answers to these
	// questions by the user. Then returns the IDs of all questions, all replies
	// and an error, if any.
	Conversation(Conversation) ([]string, []Message, error)

	// Say writes an OutgoingMessage and returns the ID of that message along with
	// an error, if any.
	Say(OutgoingMessage) (string, error)

	// Form posts a form and returns the ID of the form and an error, if any.
	Form(Form) (string, error)

	// Image posts an Image and returns the ID of the image message and an error,
	// if any.
	Image(Image) (string, error)

	// UpdateMessage updates the message with the given ID with the replacement
	// text and returns the ID of the new message along with an error, if any.
	UpdateMessage(id string, replacement string) (string, error)

	// UpdateForm updates the message with the given ID and replaces it with the
	// given form. Returns the ID of the new form and an error, if any.
	UpdateForm(id string, form Form) (string, error)

	// WaitForAction will block until an action with the given ID comes. Until
	// then, all the incoming messages or actions will be handled according to
	// the given waiting policy.
	WaitForAction(string, ActionWaitingPolicy) (Action, error)

	// AskUntil posts a question and checks the received message. If the
	// AnswerChecker considers it is correct, it will return. If not, the message
	// returned by the AnswerChecker will be posted and the process will repeat.
	// It returns the ID of the last question posted, the last user message and
	// an error, if any.
	AskUntil(OutgoingMessage, AnswerChecker) (string, Message, error)
}

type Button struct {
	// Text is the visible text of the button.
	Text string
	// Name is the name of the button.
	Name string
	// Value is the value of the button.
	Value string
	// Type is the type of the button.
	Type ButtonType
	// Confirmation defines a confirmation popup to be shown after the button
	// is clicked. This is platform-specific behaviour.
	Confirmation *Confirmation
}

type ButtonType byte

type Channel struct {
	// ID of the channel
	ID string
	// Name if any
	Name string
	// IsDM will be true if is a direct message. That is, between user and bot.
	IsDM bool
	// Users is the list of users in the channel. Some implementations may not
	// provide this.
	Users []User
	// Type is the type of client this channel comes from.
	Type ClientType
	// Extra contains extra data given by the specific client.
	Extra interface{}
}

type Client interface {
	// SetLogOutput will write the logs to the given io.Writer.
	SetLogOutput(io.Writer)

	// AddController adds a new Controller to the Client.
	AddController(Controller)

	// AddActionHandler adds an ActionHandler for the given ID.
	AddActionHandler(string, ActionHandler)

	// AddBot adds a new bot with an ID and a token.
	AddBot(id string, token string)

	// SetIntroHandler sets the IntroHandler for the client.
	SetIntroHandler(IntroHandler)

	// SetStorage sets the storage to be used to store conversations and bots.
	// In this package clients, if the Storage is added *before* calling the
	// Run method bots and conversations will be loaded from there.
	SetStorage(Storage)

	// AddScheduledJob will run the given Job forever after the given
	// duration from the last execution.
	AddScheduledJob(ScheduleTime, Job)

	// Run starts the client.
	Run() error

	// Stop stops the client.
	Stop() error
}

type ClientType uint

type Confirmation struct {
	// Title of the confirm window.
	Title string
	// Text of the confirm window.
	Text string
	// Ok button text of the confirm window.
	Ok string
	// Dismiss button text of the confirm window.
	Dismiss string
}

type Controller interface {
	// CanHandle tells if the controller can handle the message.
	CanHandle(Message) bool

	// Handle performs the actual work, here an instance of Bot is
	// provided along with the Message to be able to communicate with
	// the user.
	Handle(Bot, Message) error
}

type Conversation []OutgoingMessage

type Field interface {
	// contains filtered or unexported methods
}

type FieldGroup interface {
	// ID returns the ID of the group (only valid for ButtonGroup)
	ID() string
	// Items returns all the fields in the group.
	Items() []Field
	// Type returns the type of the group.
	Type() FieldGroupType
}

type FieldGroupType byte

type Form struct {
	// Title is the title of the form.
	Title string
	// Text is the text of the form.
	Text string
	// Combine will force all the form to be in a single message.
	// The behavior of this is actually client-dependant.
	Combine bool
	// Color is the color of the form. This is client-specific.
	Color string
	// Footer is a small text on the footer of the form.
	Footer string
	// Fields is a collection of field groups on the form.
	Fields []FieldGroup
}

type Image struct {
	// URL is the URL of the image.
	URL string
	// Text of the image.
	Text string
	// ThumbnailURL is the URL of the thumbnail to be displayed.
	ThumbnailURL string
}

type IntroHandler interface {
	// HandleIntro performs the actual work, here an instance of Bot
	// is provided along with the Channel to be able to communicate
	// with the users in the channel.
	HandleIntro(Bot, Channel) error
}

type Job func(Bot, Channel) error

type Message struct {
	// ID of the message.
	ID string
	// Type of client this message comes from.
	Type ClientType
	// User that posted the message.
	User User
	// Channel the message was posted in.
	Channel Channel
	// Time of the message.
	Time time.Time
	// Text of the message.
	Text string
	// Extra contains extra data given by the specific content.
	Extra interface{}
}

type MessageSender struct {
	// Username is the name of the user.
	Username string
	// IconURL for the message poster picture.
	IconURL string
}

type OutgoingMessage struct {
	// ChannelID if is different from the channel in which the current handler
	// or controller is executing.
	ChannelID string
	// Text of the message.
	Text string
	// Sender, if provided, changes the username and icon of the message.
	Sender *MessageSender
}

type ScheduleTime interface {
	// Next time right after the given time a job should be run.
	Next(time.Time) time.Time
}

type Storage interface {
	// StoreBot saves the given bot.
	StoreBot(StoredBot) error
	// StoreConversation saves the given conversation.
	StoreConversation(StoredConversation) error
	// LoadBots retrieves all stored bots.
	LoadBots() ([]StoredBot, error)
	// LoadConversations retrieves all stored conversations for a single bot.
	LoadConversations(StoredBot) ([]StoredConversation, error)
	// BotExists checks if the bot is already stored.
	BotExists(StoredBot) (bool, error)
	// ConversationExists checks if the conversation is already stored.
	ConversationExists(StoredConversation) (bool, error)
}

type StoredBot struct {
	// ID is the ID of the bot, an unique identifier.
	ID string
	// Token is the token needed to access the bot API by the client.
	Token string
	// CreatedAt is the time it was first saved.
	CreatedAt time.Time
	// Extra allows clients to store client-specific data needed.
	Extra interface{}
}

type StoredConversation struct {
	// ID is the unique identifier of the conversation or channel.
	ID string
	// BotID is the unique identifier of the bot this conversation belongs to.
	BotID string
	// CreatedAt is the time it was first saved.
	CreatedAt time.Time
	// Extra allows clients to store client-specific data needed.
	Extra interface{}
}

type TextField struct {
	// Title is the label of the field.
	Title string
	// Value is the text value of the field.
	Value string
	// Short is a platform-specific feature. If available, will be rendered as
	// a short field instead of a wide one.
	Short bool
}

type User struct {
	// ID of the user.
	ID string
	// Username is the handle of the user.
	Username string
	// Name is the real name, if any.
	Name string
	// IsBot will be true if the user is a bot.
	IsBot bool
	// Type is the specific client this user comes from.
	Type ClientType
	// Extra contains extra data given by the specific content.
	Extra interface{}
}

type UserAction struct {
	// Name of the action performed.
	Name string
	// Value of the action performed.
	Value string
}