package pkgo

const (
	ErrRateLimit = errors.Sentinel("pkgo: hit API rate limits")

	ErrBadRequest    = errors.Sentinel("pkgo: 400 bad request")
	ErrUnauthorized  = errors.Sentinel("pkgo: 401 unauthorized")
	ErrNotFound      = errors.Sentinel("pkgo: 404 not found")
	ErrAlreadyExists = errors.Sentinel("pkgo: 409 resource already exists")
	ErrUnprocessable = errors.Sentinel("pkgo: 422 unprocessable entity")
	ErrUnavailable   = errors.Sentinel("pkgo: 503 service unavailable")
)

Errors returned by Request

const (
	ErrNoToken          = errors.Sentinel("pkgo: no token in session, can't hit endpoints requiring authentication")
	ErrInvalidID        = errors.Sentinel("pkgo: not a 5-character ID")
	ErrInvalidSnowflake = errors.Sentinel("pkgo: not a valid Discord snowflake")
	ErrMsgNotFound      = errors.Sentinel("pkgo: message not found")
	ErrPrivacyInvalid   = errors.Sentinel("pkgo: invalid privacy setting")
)

Errors

Variables ¶

var (
	// BaseURL is the API base url
	BaseURL = "https://api.pluralkit.me/v"
	// Version is the API version
	Version = "1"
)

Types ¶

type Birthday ¶

type Birthday time.Time

Birthday is a member's birthday

func ParseBirthday ¶

func ParseBirthday(in string) (bd Birthday, err error)

ParseBirthday parses a birthday in yyyy-mm-dd or mm-dd format.

func (Birthday) MarshalJSON ¶

func (bd Birthday) MarshalJSON() (b []byte, err error)

MarshalJSON ...

func (Birthday) Time ¶

func (bd Birthday) Time() time.Time

Time returns bd as time.Time

func (*Birthday) UnmarshalJSON ¶

func (bd *Birthday) UnmarshalJSON(v []byte) error

UnmarshalJSON ...

type Color ¶

type Color string

Color holds the color for a member

func (Color) IsValid ¶

func (c Color) IsValid() bool

IsValid returns true if the color is valid for PK

func (Color) ToInt ¶

func (c Color) ToInt() int64

ToInt converts the color to an int64 value

type CreateMemberData ¶

type CreateMemberData struct {
	Name        string `json:"name,omitempty"`
	DisplayName string `json:"display_name,omitempty"`

	Description string   `json:"description,omitempty"`
	Pronouns    string   `json:"pronouns,omitempty"`
	Color       Color    `json:"color,omitempty"`
	Birthday    Birthday `json:"birthday,omitempty"`
	AvatarURL   string   `json:"avatar_url,omitempty"`
	Banner      string   `json:"banner,omitempty"`

	ProxyTags []ProxyTag `json:"proxy_tags,omitempty"`
	KeepProxy bool       `json:"keep_proxy"`

	Visibility         Privacy `json:"visibility,omitempty"`
	NamePrivacy        Privacy `json:"name_privacy,omitempty"`
	DescriptionPrivacy Privacy `json:"description_privacy,omitempty"`
	AvatarPrivacy      Privacy `json:"avatar_privacy,omitempty"`
	BirthdayPrivacy    Privacy `json:"birthday_privacy,omitempty"`
	PronounPrivacy     Privacy `json:"pronoun_privacy,omitempty"`
	MetadataPrivacy    Privacy `json:"metadata_privacy,omitempty"`
}

CreateMemberData is the data for s.CreateMember.

type EditMemberData ¶

type EditMemberData struct {
	Name        string `json:"name,omitempty"`
	DisplayName string `json:"display_name,omitempty"`

	Description string   `json:"description,omitempty"`
	Pronouns    string   `json:"pronouns,omitempty"`
	Color       Color    `json:"color,omitempty"`
	Birthday    Birthday `json:"birthday,omitempty"`
	AvatarURL   string   `json:"avatar_url,omitempty"`
	Banner      string   `json:"banner,omitempty"`

	ProxyTags []ProxyTag `json:"proxy_tags,omitempty"`
	KeepProxy bool       `json:"keep_proxy,omitempty"`

	Visibility         Privacy `json:"visibility,omitempty"`
	NamePrivacy        Privacy `json:"name_privacy,omitempty"`
	DescriptionPrivacy Privacy `json:"description_privacy,omitempty"`
	AvatarPrivacy      Privacy `json:"avatar_privacy,omitempty"`
	BirthdayPrivacy    Privacy `json:"birthday_privacy,omitempty"`
	PronounPrivacy     Privacy `json:"pronoun_privacy,omitempty"`
	MetadataPrivacy    Privacy `json:"metadata_privacy,omitempty"`
}

EditMemberData is the data for s.EditMember.

type EditSystemData ¶

type EditSystemData struct {
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	Tag         string `json:"tag,omitempty"`
	AvatarURL   string `json:"avatar_url,omitempty"`
	Banner      string `json:"banner,omitempty"`
	Color       string `json:"color,omitempty"`
	Timezone    string `json:"tz,omitempty"`

	DescriptionPrivacy  Privacy `json:"description_privacy,omitempty"`
	MemberListPrivacy   Privacy `json:"member_list_privacy,omitempty"`
	FrontPrivacy        Privacy `json:"front_privacy,omitempty"`
	FrontHistoryPrivacy Privacy `json:"front_history_privacy,omitempty"`
}

EditSystemData ...

type Front ¶

type Front struct {
	Timestamp time.Time `json:"timestamp,omitempty"`
	Members   []Member  `json:"members"`
}

Front holds the info for a full switch, as queried from /s/:id/fronters

type InvalidError ¶

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

InvalidError is returned when the data for a PATCH or POST endpoint is invalid.

func (*InvalidError) Error ¶

func (e *InvalidError) Error() string

type Member ¶

type Member struct {
	ID      string    `json:"id"`
	Created time.Time `json:"created"`

	Name        string `json:"name,omitempty"`
	DisplayName string `json:"display_name,omitempty"`

	Description string   `json:"description,omitempty"`
	Pronouns    string   `json:"pronouns,omitempty"`
	Color       Color    `json:"color,omitempty"`
	Birthday    Birthday `json:"birthday,omitempty"`
	AvatarURL   string   `json:"avatar_url,omitempty"`
	Banner      string   `json:"banner,omitempty"`

	ProxyTags []ProxyTag `json:"proxy_tags,omitempty"`
	KeepProxy bool       `json:"keep_proxy"`

	Visibility         Privacy `json:"visibility,omitempty"`
	NamePrivacy        Privacy `json:"name_privacy,omitempty"`
	DescriptionPrivacy Privacy `json:"description_privacy,omitempty"`
	AvatarPrivacy      Privacy `json:"avatar_privacy,omitempty"`
	BirthdayPrivacy    Privacy `json:"birthday_privacy,omitempty"`
	PronounPrivacy     Privacy `json:"pronoun_privacy,omitempty"`
	MetadataPrivacy    Privacy `json:"metadata_privacy,omitempty"`
}

Member holds information for a specific system member. Fields set to private are empty.

func (Member) String ¶

func (m Member) String() string

String returns the member's displayed name--either DisplayName if one is set, otherwise Name.

func (Member) Validate ¶

func (m Member) Validate() error

Validate will validate the member object. If any of the fields have invalid values, it returns an InvalidError.

type Message ¶

type Message struct {
	Timestamp time.Time `json:"timestamp"`

	ID       Snowflake `json:"id"`
	Original Snowflake `json:"original"`
	Sender   Snowflake `json:"sender"`
	Channel  Snowflake `json:"channel"`

	System System `json:"system"`

	Member Member `json:"member"`
}

Message is a proxied message

type Privacy ¶

type Privacy string

Privacy is a system or member privacy field

func (Privacy) MarshalJSON ¶

func (p Privacy) MarshalJSON() (b []byte, err error)

MarshalJSON ...

func (*Privacy) UnmarshalJSON ¶

func (p *Privacy) UnmarshalJSON(v []byte) error

UnmarshalJSON ...

type ProxyTag ¶

type ProxyTag struct {
	Prefix string `json:"prefix,omitempty"`
	Suffix string `json:"suffix,omitempty"`
}

ProxyTag is a single proxy tag for a member, in the format <prefix>text<suffix>

func (*ProxyTag) String ¶

func (p *ProxyTag) String() string

String returns a <prefix>text<suffix> formatted version of the proxy tag

type RequestOption ¶

type RequestOption func(*http.Request) error

RequestOption is an optional request option.

func WithBody ¶

func WithBody(r io.Reader) RequestOption

WithBody adds a body to the request.

func WithHeader ¶

func WithHeader(header http.Header) RequestOption

WithHeader adds headers to the request.

func WithJSONBody ¶

func WithJSONBody(v interface{}) RequestOption

WithJSONBody adds a JSON body to the request. Marshaling errors are ignored.

func WithURLValues ¶

func WithURLValues(values url.Values) RequestOption

WithURLValues adds query parameters to the request.

type Session ¶

type Session struct {
	// BaseURL is the API's base url.
	// This is set to the global variables BaseURL + Version when the session is initialized.
	BaseURL string

	Client *http.Client

	// Timeout is the maximum time this Session will wait for requests.
	Timeout time.Duration

	// RequestOptions are applied to every outgoing request.
	RequestOptions []RequestOption
	// contains filtered or unexported fields
}

Session is the PluralKit API session, including a token

func New ¶

func New(token string) *Session

New returns a session with the given token, or no token if the string is empty.

func NewWithLimiter ¶

func NewWithLimiter(token string, limiter *rate.Limiter) *Session

NewWithLimiter returns a session with the given token and rate limiter.

func (*Session) Account ¶

func (s *Session) Account(id Snowflake) (sys *System, err error)

Account gets a system by a Discord snowflake (user ID).

func (*Session) CreateMember ¶

func (s *Session) CreateMember(data CreateMemberData) (m Member, err error)

CreateMember creates a member. Requires authentication.

func (*Session) DeleteMember ¶

func (s *Session) DeleteMember(id string) (err error)

DeleteMember deletes a member. Requires authentication.

func (*Session) EditMember ¶

func (s *Session) EditMember(id string, emd EditMemberData) (*Member, error)

EditMember edits a member by ID. Requires authentication.

func (*Session) EditSystem ¶

func (s *Session) EditSystem(psd EditSystemData) (sys *System, err error)

EditSystem edits your system with the provided data.

func (*Session) Fronters ¶

func (s *Session) Fronters(id string) (f Front, err error)

Fronters gets the current fronters for a system. If the system's fronters are set to private, requires authentication.

func (*Session) Me ¶

func (s *Session) Me(force bool) (sys *System, err error)

Me gets the current token's system. If force is set to true, this will always fetch the system from the API.

func (*Session) Member ¶

func (s *Session) Member(id string) (m Member, err error)

Member gets a member by their ID.

func (*Session) Members ¶

func (s *Session) Members(id string) ([]Member, error)

Members gets all members of a system. If the system's member list is set to private, requires authentication. If the request is not authenticated, only public members will be returned.

func (*Session) Message ¶

func (s *Session) Message(id Snowflake) (m *Message, err error)

Message gets a message by Discord snowflake.

func (*Session) RegisterSwitch ¶

func (s *Session) RegisterSwitch(ids ...string) (err error)

RegisterSwitch registers a switch with the given member IDs. Requires authentication.

func (*Session) Request ¶

func (s *Session) Request(method, endpoint string, opts ...RequestOption) (response []byte, err error)

Request makes a request returning a JSON body.

func (*Session) RequestJSON ¶

func (s *Session) RequestJSON(method, endpoint string, v interface{}, opts ...RequestOption) error

RequestJSON makes a request returning a JSON body.

func (*Session) Switches ¶

func (s *Session) Switches(id string) (switches []Switch, err error)

Switches gets the latest 100 switches for a system. For earlier switches, see SwitchesBefore. If the system's font history is set to private, requires authentication.

func (*Session) SwitchesBefore ¶

func (s *Session) SwitchesBefore(id string, before time.Time) (switches []Switch, err error)

SwitchesBefore gets the 100 switches before the given timestamp. For the latest switches, see Switches. If the system's font history is set to private, requires authentication.

func (*Session) System ¶

func (s *Session) System(id string) (sys *System, err error)

System gets a system by its 5-character system ID. Some fields may be empty if unauthenticated and the system has chosen to make those fields private.

type Snowflake ¶

type Snowflake uint64

Snowflake is a Discord snowflake

func ParseSnowflake ¶

func ParseSnowflake(str string) (Snowflake, error)

ParseSnowflake parses a snowflake from a string.

func (Snowflake) String ¶

func (s Snowflake) String() string

func (*Snowflake) UnmarshalJSON ¶

func (s *Snowflake) UnmarshalJSON(v []byte) error

UnmarshalJSON ...

type StatusError ¶

type StatusError struct {
	Code   int
	Status string
}

StatusError is returned when a request returns a non-200 status code

func (*StatusError) Error ¶

func (e *StatusError) Error() string

type Switch ¶

type Switch struct {
	Timestamp time.Time `json:"timestamp,omitempty"`
	Members   []string  `json:"members"`
}

Switch holds the info for a simple switch, as queried from /s/:id/switches

type System ¶

type System struct {
	ID      string    `json:"id"`
	Created time.Time `json:"created"`

	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	Tag         string `json:"tag,omitempty"`
	AvatarURL   string `json:"avatar_url,omitempty"`
	Banner      string `json:"banner,omitempty"`
	Color       string `json:"color,omitempty"`
	Timezone    string `json:"tz,omitempty"`

	DescriptionPrivacy  Privacy `json:"description_privacy,omitempty"`
	MemberListPrivacy   Privacy `json:"member_list_privacy,omitempty"`
	FrontPrivacy        Privacy `json:"front_privacy,omitempty"`
	FrontHistoryPrivacy Privacy `json:"front_history_privacy,omitempty"`
}

System holds all the data for a system

Source Files ¶

api.go api_options.go errors.go limits.go member.go member_api.go member_objects.go message.go session.go snowflake.go switches.go system.go validators.go

Version: v1.2.0 (latest)
Published: Oct 14, 2021
Platform: linux/amd64
Imports: 13 packages
Last checked: 1 second ago –

Tools for package owners.

?	: This menu
/	: Search site
f	: Jump to identifier
g then g	: Go to top of page
g then b	: Go to end of page
G	: Go to end of page
g then i	: Go to index
g then e	: Go to examples

package pkgo

Index ¶

Constants ¶

Variables ¶

Types ¶

type Birthday ¶

func ParseBirthday ¶

func (Birthday) MarshalJSON ¶

func (Birthday) Time ¶

func (*Birthday) UnmarshalJSON ¶

type Color ¶

func (Color) IsValid ¶

func (Color) ToInt ¶

type CreateMemberData ¶

type EditMemberData ¶

type EditSystemData ¶

type Front ¶

type InvalidError ¶

func (*InvalidError) Error ¶

type Member ¶

func (Member) String ¶

func (Member) Validate ¶

type Message ¶

type Privacy ¶

func (Privacy) MarshalJSON ¶

func (*Privacy) UnmarshalJSON ¶

type ProxyTag ¶

func (*ProxyTag) String ¶

type RequestOption ¶

func WithBody ¶

func WithHeader ¶

func WithJSONBody ¶

func WithURLValues ¶

type Session ¶

func New ¶

func NewWithLimiter ¶

func (*Session) Account ¶

func (*Session) CreateMember ¶

func (*Session) DeleteMember ¶

func (*Session) EditMember ¶

func (*Session) EditSystem ¶

func (*Session) Fronters ¶

func (*Session) Me ¶

func (*Session) Member ¶

func (*Session) Members ¶

func (*Session) Message ¶

func (*Session) RegisterSwitch ¶

func (*Session) Request ¶

func (*Session) RequestJSON ¶

func (*Session) Switches ¶

func (*Session) SwitchesBefore ¶

func (*Session) System ¶

type Snowflake ¶

func ParseSnowflake ¶

func (Snowflake) String ¶

func (*Snowflake) UnmarshalJSON ¶

type StatusError ¶

func (*StatusError) Error ¶

type Switch ¶

type System ¶

Source Files ¶

Jump to identifier

Keyboard shortcuts