interfaces

type Bot interface {
	Poster

	// GetUsername returns the username of a user in the current network when
	// provided with a user ID.
	//
	// This is mainly useful if the chat network has a notion of user IDs that
	// uniquely identify a user regardless of username changes (i.e. Slack).
	//
	GetUsername(userID string) (string, error)

	// StartTyping will cause the bot to show a typing indicator
	// ("X is typing...") if the network supports it. Otherwise, it will simply
	// ignore it.
	StartTyping(channelID string)

	// GetUsageHandler returns a handler to be used for when no other handlers are
	// matched. This handler usually posts some for of help message.
	GetUsageHandler() Handler

	// Excuse can be used as an error reporter by commands. It posts to the
	// channel a message was received from that an error occurred and logs the
	// error using the application logger.
	Excuse(Message, error)

	// GetGonduit returns an instance of the Conduit client.
	GetGonduit() (*gonduit.Conn, error)

	// GetConfig returns an instance of the configuration object.
	GetConfig() *confer.Config

	// GetModules returns a slice of all the modules loaded by this Bot.
	GetModules() []Module

	// GetHandlers returns the currently active handlers on the connector.
	GetHandlers() []HandlerTuple

	// GetIMHandlers returns the currently active IM handlers on the connector.
	GetIMHandlers() []HandlerTuple
}

type Command interface {
	// GetUsage returns a template of how a command should be invoked in a
	// similar fashion as a CLI utility would.
	GetUsage() string

	// GetDescription returns a short description of what the command does.
	GetDescription() string

	// GetMatchers returns regular expressions that match the command on
	// regular channels.
	GetMatchers() []string

	// GetMentionMatchers returns regular expressions that match the command
	// on regular channels when the bot is mention especifically.
	GetMentionMatchers() []string

	// GetIMMatchers returns regular expressions that match the command on
	// direct messages to the bot.
	GetIMMatchers() []string

	// GetHandler returns the handler function to be executed when the command
	// is matched.
	GetHandler() Handler
}

type Connector interface {
	Poster

	// Boot tells the connector to begin connecting to its network.
	//
	// This method will be called by Phabulous once the server is ready to
	// begin joining networks and all modules have been loaded.
	//
	Boot() error

	// LoadModules provides the connector with a slice of the modules that
	// should be loaded by the connector. The connector should process the
	// modules by creating an internal map of regular expressions and handlers.
	LoadModules(modules []Module)
}

type Handler func(Bot, Message, []string)

type HandlerTuple interface {
	// GetPattern returns the regular expression pattern in the tuple.
	GetPattern() *regexp.Regexp
	// GetHandler returns the Handler in the tuple.
	GetHandler() Handler
}

type Message interface {
	// GetChannel returns the channel or room this message was posted on.
	GetChannel() string
	// GetUserID gets the ID or nickname of the user who created this message.
	GetUserID() string
	// GetContent gets the message content.
	GetContent() string
	// GetProviderName returns the name of the provider this message was
	// delivered by. Examples: slack, irc, etc.
	GetProviderName() string
	// IsIM returns true if the message is a direct message sent to the bot.
	IsIM() bool
	// IsSelf returns true if the message was posted by the bot.
	IsSelf() bool
}

type Module interface {
	// GetName returns the name of the Module.
	GetName() string

	// GetCommands returns all the Commands provided by this Module.
	GetCommands() []Command
}

type Poster interface {
	// Post posts a text message.
	Post(
		channelName string,
		storyText string,
		icon messages.Icon,
		asUser bool,
	)

	// PostImage posts a message with an attached image.
	PostImage(
		channelName string,
		storyText string,
		imageURL string,
		icon messages.Icon,
		asUser bool,
	)

	// PostOnFeed posts a message on the bot's "feed" channel.
	PostOnFeed(storyText string) error
}

type SlackBot interface {
	Bot

	// GetSlack returns an instance of the Slack client for the bot's network.
	GetSlack() *slack.Client
}