flamingo

package module
v0.0.0-...-d92fe58 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2016 License: MIT Imports: 2 Imported by: 0

README

godoc reference Build Status codecov License

Flamingo is a very thin and simple platform-agnostic chat bot framework.

You can see a simple example at examples folder.

License

MIT License

Notes

The slack client uses nlopes/slack but right now is using a fork until this pull request is merged.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action 

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{}
}

Action is a message received by the application to notify the user did something.

type ActionHandler 

type ActionHandler func(Bot, Action)

ActionHandler is a function that will handle a certain kind of Action.

type ActionWaitingPolicy 

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
}

ActionWaitingPolicy defines the policy to follow while waiting for actions to arrive.

func IgnorePolicy 

func IgnorePolicy() ActionWaitingPolicy

IgnorePolicy returns an ActionWaitingPolicy that ignores all incoming messages and actions but the one we're looking for.

func ReplyPolicy 

func ReplyPolicy(msg string) ActionWaitingPolicy

ReplyPolicy returns an ActionWaitingPolicy that replies to every message or action received but the on we're looking for.

type AnswerChecker 

type AnswerChecker func(Message) *OutgoingMessage

AnswerChecker is a function that will determine if the provided answer is correct analysing the answer Message. If the function returns nil it is assumed the answer is valid, otherwise it is assumed to be invalid and the question will be repeated with the returned message. Take a look at the AskUntil method of the Bot interface.

type Bot 

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)
}

Bot is the main interface to interact with the user. Either using controllers or action handlers these are all the exposed methods to communicate with the user.

type Button 

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
}

Button is a single button element.

type ButtonType 

type ButtonType byte

ButtonType is the kind of button. Even though there are several types of buttons this is really very platform-specific. 

const (
	// DefaultButton is the default button.
	DefaultButton ButtonType = iota
	// PrimaryButton is a button with an accent color to stand out.
	PrimaryButton
	// DangerButton is a typically red button to indicate a dangerous action.
	DangerButton
)

type Channel 

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{}
}

Channel represents a group, channel, direct message or conversation, all in one, depending on the specific client you are using.

type Client 

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
}

Client is an abstract interface of a platforms-specific client. A client can only run for one platform. If you need to handle more than one platform you will have to start several clients for different platforms.

type ClientType 

type ClientType uint

ClientType tells us what type of client is. 

const (
	// SlackClient is a client for Slack.
	SlackClient ClientType = 1 << iota
)

type Confirmation 

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
}

Confirmation is a confirmation popup to be shown after a button is clicked. Slack-specific at the moment.

type Controller 

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
}

Controller is an object that will handle incoming messages if they can be handled by it.

type Conversation 

type Conversation []OutgoingMessage

Conversation is a collection of OutgoingMessages.

type Field 

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

Field is an element of a FieldGroup.

type FieldGroup 

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
}

FieldGroup is a collection of Fields of a concrete type.

func NewButtonGroup 

func NewButtonGroup(id string, buttons ...Button) FieldGroup

NewButtonGroup creates a FieldGroup with the given buttons.

func NewTextFieldGroup 

func NewTextFieldGroup(fields ...TextField) FieldGroup

NewTextFieldGroup creates a FieldGroup with the given text fields.

type FieldGroupType 

type FieldGroupType byte

FieldGroupType is the type of elements contained in the group. 

const (
	// ButtonGroup is a group of buttons.
	ButtonGroup FieldGroupType = 1 << iota
	// TextFieldGroup is a group of text fields.
	TextFieldGroup
	// ImageGroup is a single image.
	ImageGroup
)

type Form 

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
}

Form is the way to post complex structures with the bot. Forms can have title, text, color, footer, several Fields (buttons, text fields, images, ...), etc.

type Image 

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
}

Image is an image to be posted.

func (Image) ID 

func (f Image) ID() string

ID always returns an empty string since Images have no ID. This method is just implemented to fulfill the FieldGroup interface.

func (Image) Items 

func (f Image) Items() []Field

Items returns a slice with only the image itself, which is both a fieldgroup and a field.

func (Image) Type 

func (f Image) Type() FieldGroupType

Type returns the ImageGroup type.

type IntroHandler 

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
}

IntroHandler is a handler that is triggered whenever someone starts a new conversation or group with the bot.

type Job 

type Job func(Bot, Channel) error

Job is a function that will execute like a cron job after a certain amount of time to perform some kind of task.

type Message 

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{}
}

Message is the data of a message received.

type MessageSender 

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

MessageSender define the properties of the sender of a message.

type OutgoingMessage 

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
}

OutgoingMessage is a message that is going to be sent to the user.

func NewOutgoingMessage 

func NewOutgoingMessage(text string) OutgoingMessage

NewOutgoingMessage creates a simple OutgoingMessage with just text.

type ScheduleTime 

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

ScheduleTime gives the next time to run a job.

func NewDateSchedule 

func NewDateSchedule(hour, minutes, seconds int) ScheduleTime

NewDateSchedule creates a ScheduleTime that runs once a day at a given hour, minutes and seconds.

func NewIntervalSchedule 

func NewIntervalSchedule(every time.Duration) ScheduleTime

NewIntervalSchedule creates a ScheduleTime that runs in intervals of the given duration.

type Storage 

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)
}

Storage is a service to store and retrieve conversations and bots stored.

type StoredBot 

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{}
}

StoredBot is the minimal data snapshot to start a previously running bot instance. It is meant to be stored.

type StoredConversation 

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{}
}

StoredConversation is the minimal data snapshot to start a previously running bot conversation instance. It is meant to be stored.

type TextField 

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
}

TextField is a field which displays a label with its text value.

type User 

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{}
}

User is the representation of an user.

type UserAction 

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

UserAction is the kind of action performed by the user.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.