core

type AudioSpeaker interface {
	// Enabled returns true if the frontend supports voice chat that the bot can
	// connect to.
	Enabled() bool

	// The audio's expected frame rate.
	FrameRate() int

	// The audio's expected number of channels.
	Channels() int

	// Join the message author's voice channel, if they are not connected to
	// any then returns an error. If in a specific frontend only one voice
	// channel will ever exist then the user doesn't have to be connected to it
	// for the bot to join (for example a discord server with only one voice
	// channel would not apply here as other ones *could* be created at any
	// point).
	Join() error

	// Send audio. Must have connected to a voice channel first, otherwise
	// returns an error.
	Say(buf io.Reader, s *AudioState) error

	// AuthorDeafened returns true if the author that originally made the bot
	// join the voice channel is currently deafened.
	AuthorDeafened() (bool, error)

	// AuthorConnected returns true if the author that originally made the bot
	// join the voice channel is currently connected to that same voice channel.
	AuthorConnected() (bool, error)
}

type AudioState struct {
	gosafe.Value[int]
}

type Author interface {
	// ID returns the author's ID, this should be a unique, static, identifier
	// in that frontend.
	ID() string

	// Name returns the author's username.
	Name() string

	// DisplayName return's the author's display name. If only usernames exist
	// for that frontend then returns the username.
	DisplayName() string

	// Mention return's a string that mention's the author. This should ideally
	// ping them in some way.
	Mention() string

	// BotAdmin returns true if the author is a bot admin. Otherwise returns
	// false.
	BotAdmin() bool

	// Admin checks if the author is considered an admin. Should return true
	// only if the author has basically every permission.
	Admin() bool

	// Mod checks if the author is considered a moderator. General rule of thumb
	// is that if the author can ban people, then they are mods.
	Mod() bool

	// Subcriber checks if the author is considered a subscriber. General rule of
	// is that if they are paying money in some way, then they are subs. If no
	// such thing exists for the specific frontend, then always returns false.
	Subscriber() bool

	// Scope return's the author's scope. If it doesn't exist it will create it
	// and add it to the database.
	Scope() (author int64, err error)
}

type Command struct {
	CommandStatic
	CommandRuntime
}

type CommandCategory string

type CommandRuntime struct {
	// The "path" taken to invoke the command, i.e. which names were used.
	// Includes all the sub-commands e.g. ["prefix", "add"] in order to be able
	// to display accurate help messages.
	Path []string

	// The arguments passed, includes everything that's not part of the
	// command's name.
	Args []string

	// The prefix used when the command was called.
	Prefix string
}

type CommandStatic interface {
	// Type returns the command's type.
	Type() CommandType

	// Permitted will perform checks required for a command to be executed.
	// Returns true if the command is allowed to be executed. Usually used to
	// chcek a user's permissions or to restrict a command to specific
	// frontends.
	Permitted(m *Message) bool

	// Names return a list of all the aliases a command has. The first item in
	// the list is considered the main name and so should be the simplest and
	// most intuitive one for the average person. For example if it's a delete
	// subcommand the first alias should be "delete" instead of "del" or "rm".
	Names() []string

	// Description will return a short description of what the command does.
	Description() string

	// UsageArgs will return the usage arguments. Should follow this format:
	// - <required>
	// - [optional]
	// - (literal-string) or (many | literals)
	UsageArgs() string

	// Category returns the general category the command belongs to. Mainly
	// to make displaying all the commands easier and less overwhelming (as
	// they are split up instead of having them all in a giant list).
	Category() CommandCategory

	// Example returns a list of strings with example usages of the command.
	// Only the arguments passed should be included, not the prefix and the
	// chain of command names.
	Examples() []string

	// Parent returns a command's parent, returns nil if there is no parent.
	Parent() CommandStatic

	// Children returns the command's sub-commands, returns nil if there are no
	// sub-commands.
	Children() CommandsStatic

	// Init is executed during bot startup. Should be used to set things up
	// necessary for the command, for example DB schemas.
	Init() error

	// Run is function that is called to run the command.
	Run(m *Message) (resp any, usrErr error, err error)
}

type CommandType int

type CommandsStatic []CommandStatic

type Flags struct {
	FlagSet *flag.FlagSet
	Msg     *Message
	// contains filtered or unexported fields
}

type FrontendType int

type Frontender interface {
	// Type returns the frontend type ID.
	Type() FrontendType

	// Init is responsible for starting up any frontend specific services and
	// connecting to frontend. When it receives the stop signal then it should
	// disconnect from everything.
	Init(wgInit, wgStop *sync.WaitGroup, stop chan struct{})

	// CreateMessage returns a Message object based on the given arguments.
	// Used to send messages that are not direct replies, e.g. reminders.
	CreateMessage(person, place int64, msgID string) (*Message, error)
}

type Frontenders []Frontender

type Here interface {
	// ID returns the channel's ID, this should be a unique, static, identifier
	// in that frontend.
	ID() string

	// Name return's the channel's name.
	Name() string

	// ScopeExact returns the here's exact scope. See the interface's doc
	// comment for more information on exact scopes.
	ScopeExact() (place int64, err error)

	// ScopeLogical returns the here's logical scope. See the interface's doc
	// comment for more information on logical scopes.
	ScopeLogical() (place int64, err error)
}

type Message struct {
	ID       string
	Raw      string
	Frontend Frontender
	Author   Author
	Here     Here
	Client   Messenger
	Speaker  AudioSpeaker
	Command  *Command
}

type Messenger interface {
	Parse() (*Message, error)

	// Returns the ID of the passed string. The returned ID must be valid.
	// Generally used for verifying an ID's validity and extracting IDs from
	// mentions.
	PlaceID(s string) (id string, err error)
	PersonID(s, placeID string) (id string, err error)

	// Gets the target's scope. If it doesn't exist it will create it and add
	// it to the database.
	Person(id string) (person int64, err error)

	// There exist 2 types of place scopes that are used, the exact place and
	// the logical place. The logical is the area where things are generally
	// expected to work. For example: if a user adds a custom command in a
	// server they would probably expect it to work in the entire server and not
	// just in the specific channel that they added it in. If on the other hand
	// someone adds a custom command in a discord DM message, then no guild
	// exists and thus the channel's scope would have to be used. On the other
	// hand `PlaceExact` returns exactly the scope of the id passed and does not
	// account for context.
	PlaceExact(id string) (place int64, err error)
	PlaceLogical(id string) (place int64, err error)

	Usage(usage string) any

	// Send sends a message to the appropriate scope, resp could be nil
	// depending on the frontend.
	Send(msg any, usrErr error) (resp *Message, err error)

	// Ping works the same as Send except the user is also pinged.
	Ping(msg any, usrErr error) (resp *Message, err error)

	// Write either calls Send or Ping depending on the frontend. This is what
	// should be used in most cases.
	Write(msg any, usrErr error) (resp *Message, err error)
}

type Prefix struct {
	Type   CommandType
	Prefix string
}

type SQLDB struct {
	Lock sync.RWMutex
	DB   *sql.DB
}

type States struct {
	gosafe.Slice[string]
}