ningen

README

ningen

ningen provides abstractions that override Arikawa's existing state to provide behaviors more similar to the official client with more aggressive caching.

Usage

Using ningen is similar to using *state.State, but you'd be handling around *ningen.State instead. Typically, it might look like this:

s, err := state.New(os.Getenv("TOKEN"))
if err != nil {
	return errors.Wrap(err, "failed to create state")
}

n, err := ningen.FromState(s)
if err != nil {
	return errors.Wrap(err, "failed to wrap state")
}

if err := n.Open(); err != nil {
	return errors.Wrap(err, "failed to open connection to Discord")
}

return startApp(n)

Afterwards, *ningen.State can be used as if it is *state.State. The new state will transparently behave more similarly to the official client.

Extras

In addition to wrapping, *ningen.State also adds a few more stores that the client can use:

• n.NoteState keeps track of known user notes, which can be seen on the client by clicking the profile picture of a user.
• n.ReadState allows seeing which channels are not read as well as allowing the client to asynchronously mark a channel as read.
• n.MutedState keeps track of which channels, categories and guilds are muted.
• n.EmojiState keeps track of the user's emojis; it returns the appropriate guild emojis depending on whether or not the user has Nitro.
• n.MemberState provides a way to lazily fetch the right-hand side member list seen in the official client. It also provides an asynchronous guild subscription API for listening to typing events.
  • Sometimes, in large guilds, messages may not be received from the gateway. This might mean that a guild subscription is required.
• n.RelationshipState keeps track of which users are blocked or are friends.

For detailed documentation of each state, see the reference documentation.

Markdown

ningen also provides a built-in Discord Markdown parser using goldmark. For an example on how to implement a custom Markdown renderer that is compatible with ningen, see md/renderer.go.

Documentation

Overview

Package ningen contains a set of helpful functions and packages to aid in making a Discord client.

Index

• type ConnectedEvent
• type DisconnectedEvent
  • func (ev *DisconnectedEvent) IsGraceful() bool
  • func (ev *DisconnectedEvent) IsLoggedOut() bool
• type MessageMentionFlags
  • func (f MessageMentionFlags) Has(other MessageMentionFlags) bool
• type NoPermissionError
  • func (err *NoPermissionError) Error() string
• type State
  • func FromState(s *state.State) *State
  • func New(token string) *State
  • func NewWithIdentifier(id gateway.Identifier) *State
  • func (s *State) AssertPermissions(chID discord.ChannelID, perms discord.Permissions) error
  • func (s *State) ChannelCountUnreads(chID discord.ChannelID) int
  • func (r *State) ChannelIsMuted(chID discord.ChannelID, category bool) bool
  • func (r *State) ChannelIsUnread(chID discord.ChannelID) UnreadIndication
  • func (s *State) Channels(guildID discord.GuildID, allowedTypes []discord.ChannelType) ([]discord.Channel, error)
  • func (r *State) GuildIsUnread(guildID discord.GuildID, types []discord.ChannelType) UnreadIndication
  • func (s *State) HasPermissions(chID discord.ChannelID, perms discord.Permissions) bool
  • func (r *State) LastMessage(chID discord.ChannelID) discord.MessageID
  • func (s *State) MessageMentions(msg *discord.Message) MessageMentionFlags
  • func (s *State) Offline() *State
  • func (s *State) Online() *State
  • func (s *State) Open(ctx context.Context) error
  • func (s *State) PrivateChannels() ([]discord.Channel, error)
  • func (r *State) SetStatus(status discord.Status, custom *gateway.CustomUserStatus, ...) error
  • func (s *State) Status() discord.Status
  • func (r *State) UserIsBlocked(uID discord.UserID) bool
  • func (s *State) WithContext(ctx context.Context) *State
• type UnreadIndication

Types

type ConnectedEvent

type ConnectedEvent struct {
	gateway.Event
}

ConnectedEvent is an event that's sent on Ready or Resumed. The event arrives before all ningen's handlers are called.

type DisconnectedEvent

type DisconnectedEvent struct {
	ws.CloseEvent
}

DisconnectedEvent is an event that's sent when the websocket is disconnected.

func (*DisconnectedEvent) IsGraceful

func (ev *DisconnectedEvent) IsGraceful() bool

IsGraceful returns true if the disconnection is done by the websocket and not by a connection drop.

func (*DisconnectedEvent) IsLoggedOut

func (ev *DisconnectedEvent) IsLoggedOut() bool

IsLoggedOut returns true if the session that Discord gave is now outdated and that the user must login again.

type MessageMentionFlags

type MessageMentionFlags uint8

MessageMentionFlags is the resulting flag of a MessageMentions check. If it's 0, then absolutely no mentions are done, otherwise non-0 is returned.

const (
	// MessageMentions is when a message mentions the user either by tagging
	// that user or a role that the user is in.
	MessageMentions MessageMentionFlags = 1 << iota
	// MessageNotifies is when the message should also send a visible
	// notification.
	MessageNotifies
)

func (MessageMentionFlags) Has

func (f MessageMentionFlags) Has(other MessageMentionFlags) bool

Has returns true if other is in f.

type NoPermissionError

type NoPermissionError struct {
	Has    discord.Permissions
	Wanted discord.Permissions
}

NoPermissionError is returned by AssertPermissions if the user lacks the requested permissions.

func (*NoPermissionError) Error

func (err *NoPermissionError) Error() string

Error implemenets error.

type State

type State struct {
	*state.State
	*handler.Handler

	// Custom Cabinet values.
	MemberStore   *nstore.MemberStore
	PresenceStore *nstore.PresenceStore

	// Custom State values.
	NoteState         *note.State
	ReadState         *read.State
	MutedState        *mute.State
	GuildState        *guild.State
	EmojiState        *emoji.State
	MemberState       *member.State
	RelationshipState *relationship.State
	// contains filtered or unexported fields
}

func FromState

func FromState(s *state.State) *State

FromState wraps a normal state.

func New

func New(token string) *State

New creates a new ningen state from the given token and the default identifier.

func NewWithIdentifier

func NewWithIdentifier(id gateway.Identifier) *State

NewWithIdentifier creates a new ningen state from the given identifier.

func (*State) AssertPermissions

func (s *State) AssertPermissions(chID discord.ChannelID, perms discord.Permissions) error

AssertPermissions asserts that the current user has the given permissions in the given channel. If the assertion fails, a NoPermissionError might be returned.

func (*State) ChannelCountUnreads

func (s *State) ChannelCountUnreads(chID discord.ChannelID) int

ChanneCountUnreads returns the number of unread messages in the channel.

func (*State) ChannelIsMuted

func (r *State) ChannelIsMuted(chID discord.ChannelID, category bool) bool

ChannelIsMuted returns true if the channel with the given ID is muted or if it's in a category that's muted.

func (*State) ChannelIsUnread

func (r *State) ChannelIsUnread(chID discord.ChannelID) UnreadIndication

ChannelIsUnread returns true if the channel with the given ID has unread messages.

func (*State) Channels

func (s *State) Channels(guildID discord.GuildID, allowedTypes []discord.ChannelType) ([]discord.Channel, error)

Channels returns a list of visible channels. Empty categories are automatically filtered out.

func (*State) GuildIsUnread

func (r *State) GuildIsUnread(guildID discord.GuildID, types []discord.ChannelType) UnreadIndication

GuildIsUnread returns true if the guild contains unread channels.

func (*State) HasPermissions

func (s *State) HasPermissions(chID discord.ChannelID, perms discord.Permissions) bool

HasPermissions returns true if AssertPermissions returns a nil error.

func (*State) LastMessage

func (r *State) LastMessage(chID discord.ChannelID) discord.MessageID

LastMessage returns the last message ID in the given channel.

func (*State) MessageMentions

func (s *State) MessageMentions(msg *discord.Message) MessageMentionFlags

MessageMentions returns true if the given message mentions the current user.

func (*State) Offline

func (s *State) Offline() *State

Offline returns an offline version of the state.

func (*State) Online

func (s *State) Online() *State

Online returns an online state. If the state is already online, then it returns itself.

func (*State) Open

func (s *State) Open(ctx context.Context) error

func (*State) PrivateChannels

func (s *State) PrivateChannels() ([]discord.Channel, error)

PrivateChannels returns the sorted list of private channels from the state.

func (*State) SetStatus

func (r *State) SetStatus(status discord.Status, custom *gateway.CustomUserStatus, activities ...discord.Activity) error

SetStatus sets the current user's status and presence.

func (*State) Status

func (s *State) Status() discord.Status

Status returns the user's presence status. Use to check if notifications should be sent.

func (*State) UserIsBlocked

func (r *State) UserIsBlocked(uID discord.UserID) bool

UserIsBlocked returns true if the user with the given ID is blocked by the current user.

func (*State) WithContext

func (s *State) WithContext(ctx context.Context) *State

WithContext returns State with the given context.

type UnreadIndication

type UnreadIndication uint8

UnreadIndication indicates the channel as either unread, mentioned (which implies unread) or neither.

const (
	ChannelRead UnreadIndication = iota
	ChannelUnread
	ChannelMentioned
)