core

type Channel struct {
	ID   string
	Name string
}

type Command struct {
	CommandStatic
	CommandRuntime
}

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 {
	// The command's type.
	Type() CommandType

	// Any other 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

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

	// A short description of what the command does.
	Description() string

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

	// A command's parent, this is automatically set during bot startup.
	Parent() CommandStatic

	// The command's sub-commands.
	Children() CommandsStatic

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

	// The 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 Message struct {
	ID       string
	Frontend int
	Raw      string
	User     *User
	Channel  *Channel
	Client   Messenger
	Command  *Command
	// contains filtered or unexported fields
}

type Messenger interface {
	// Checks if the message's author is a bot admin
	BotAdmin() bool

	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

	// Should return true only if a user has basically every permission.
	Admin() bool

	// General rule of thumb is that if they can ban people, they are mods.
	Mod() bool

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

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

	// 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]
}

type User struct {
	ID          string
	Name        string
	DisplayName string
	Mention     string
}