core

type AudioPlayer[T any] struct {
	// contains filtered or unexported fields
}

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

	// FrameRate returns the audio's expected frame rate. Is passed to ffmpeg
	// to convert the audio stream to the correct format before sending.
	FrameRate() int

	// Channels returns the audio's expected number of channels. Is passed to
	// ffmpeg to convert the audio stream to the correct format before sending.
	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 ever exists, 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

	// Leave disconnects the bot from the connected to voice channel, if not
	// connected to a voice channel then returns error.
	Leave() error

	// Say sends audio. Must have connected to a voice channel first, otherwise
	// returns an error. Will only ever have to handle the following states:
	//
	//	- AudioPlay, the default state, keep sending audio
	//	- AudioPause, pause the audio and wait, if AudioPlay is received resume
	//	- AudioStop, stop sending audio and return nil
	Say(buf io.Reader, st <-chan 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 int

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
	// check 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 deleted
	// 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

	// Examples 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 the function that is called to run the command.
	Run(m *Message) (resp any, urr Urr, err error)
}

type CommandType int

type CommandsStatic []CommandStatic

type Event[T any] interface {
	*Message | *RedeemClaim | *StreamOnline | *StreamOffline

	Hooks() *Hooks[T]
}

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

	// Name returns frontend's name formatted in all lowercase.
	Name() string

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

	// Usage returns the passed usage formatted appropriately for the frontend.
	Usage(usage string) any

	// PlaceExact returns the exact scope of the specified ID.
	PlaceExact(id string) (place int64, err error)

	// PlaceLogical returns the logical scope of the specified ID.
	PlaceLogical(id string) (place int64, err error)
}

type Frontenders []Frontender

type Hooks[T any] struct {
	// contains filtered or unexported fields
}

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

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

	// PlaceID 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 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.
	PersonID(s, placeID string) (id string, err error)

	// Person returns 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)

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

	// Ping works the same as Send except the user is also pinged.
	Ping(msg any, urr Urr) (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, urr Urr) (resp *Message, err error)

	// Natural will try to emulate a response as if an actual human had written
	// it. Often the bot uses markers to distinguish its responses (for example,
	// on Twitch it replies with the following format: @person -> <resp>), which
	// are not natural looking. To add to the effect, randomness may be used to
	// only sometimes mention the person.
	Natural(msg any, urr Urr) (resp *Message, err error)

	// QuoteCommand returns the passed cmd quoted appropriately.
	// If frontend-specific formatting doesn't exist, then use single quotes.
	QuoteCommand(cmd string) string
}

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

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

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

	// Mention returns a string that mentions the author.
	// This should ideally ping them in some way.
	Mention() (string, error)

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

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

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

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

	// 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 Place struct {
	Exact   int64
	Logical int64
}

type Placer interface {
	// IDExact returns the exact ID, this should be a unique, static,
	// identifier in that frontend.
	IDExact() string

	// IDLogical returns the logical ID, this should be a unique, static,
	// identifier for the frontend.
	IDLogical() string

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

	// ScopeExact returns the here's exact scope.
	// Returns the exact scope in Teleports if the author is present there.
	// See the interface's doc comment for more information on exact scopes.
	ScopeExact() (place int64, err error)

	// ScopeLogical returns the here's logical scope.
	// Returns the logical scope in Teleports if the author is present there.
	// See the interface's doc comment for more information on logical scopes.
	ScopeLogical() (place int64, err error)
}

type Prefix struct {
	Type   CommandType
	Prefix string
}

type RedeemClaim struct {
	ID       string
	Input    string
	When     time.Time
	Author   Personifier
	Here     Placer
	Frontend Frontender
}

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

type States struct {
	gosafe.Slice[string]
}

type StreamOffline struct {
	When     time.Time
	Here     Placer
	Frontend Frontender
}

type StreamOnline struct {
	When     time.Time
	Here     Placer
	Frontend Frontender
}

type Tx struct {
	Tx *sql.Tx
	// contains filtered or unexported fields
}

type Urr error

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