pkgo

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 28, 2021 License: BSD-3-Clause Imports: 13 Imported by: 3

README

pkgo

Go Reference

pkgo is a simple wrapper around PluralKit's REST API.

Usage

Import the package into your project:

import "github.com/starshine-sys/pkgo"

All API actions are done through a Session struct. This can be authenticated or unauthenticated; for unauthenticated sessions, only public information will be returned.

pk := pkgo.New("authentication token")
// or
pk := pkgo.New("")
Example
sysID := "exmpl"

pk := pkgo.New("")

sys, err := pk.System(sysID)
// ID => exmpl
// Name => PluralKit Example System
// Tag => | PluralKit 🦊
// Created => 2020-01-12 02:00:33.387824 +0000 UTC

front, err := pk.Fronters(sysID)
// Timestamp => 2020-01-12 02:21:44.024493 +0000 UTC
// Members => [Myriad Kit Tester T. Testington]

msg, err := s.Message(859157735644069928)
// ID => 859157735644069928
// Original => 859157734331252777
// Sender => 694563574386786314

pk = pkgo.New("notARealToken")

sys, err = pk.EditSystem(pkgo.EditSystemData{
    Name:        "Testing System",
    Description: "Hi, we're a system! 👋",
    Tag:         "| Testers",
})

Documentation

Index

Constants

This section is empty.

Variables

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

Errors

View Source 
var ErrRateLimit = errors.New("pkgo: hit API rate limits")

ErrRateLimit is returned when the API rate limit is hit

Functions

This section is empty.

Types

type Birthday added in v0.5.0 

type Birthday time.Time

Birthday is a member's birthday

func ParseBirthday added in v0.5.0 

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

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

func (Birthday) MarshalJSON added in v0.5.0 

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

MarshalJSON ...

func (Birthday) Time added in v0.5.0 

func (bd Birthday) Time() time.Time

Time returns bd as time.Time

func (*Birthday) UnmarshalJSON added in v0.5.0 

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 added in v0.5.0 

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"`

	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 added in v0.5.0 

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"`

	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 added in v0.5.0 

type EditSystemData struct {
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	Tag         string `json:"tag,omitempty"`
	AvatarURL   string `json:"avatar_url,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 added in v0.5.0 

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 added in v0.5.0 

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"`

	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 added in v0.5.0 

func (m Member) String() string

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

func (Member) Validate added in v0.5.0 

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 added in v0.5.0 

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

MarshalJSON ...

func (*Privacy) UnmarshalJSON added in v0.5.0 

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 Session 

type Session struct {

	// Timeout is the maximum time this Session will wait for requests.
	Timeout time.Duration
	// contains filtered or unexported fields
}

Session is the PluralKit API session, including a token

func New added in v0.5.0 

func New(token string) *Session

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

func (*Session) Account added in v0.5.0 

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

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

func (*Session) CreateMember added in v0.5.0 

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

CreateMember creates a member. Requires authentication.

func (*Session) DeleteMember added in v1.0.0 

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

DeleteMember deletes a member. Requires authentication.

func (*Session) EditMember added in v0.5.0 

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

EditMember edits a member by ID. Requires authentication.

func (*Session) EditSystem added in v0.5.0 

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

EditSystem edits your system with the provided data.

func (*Session) Fronters added in v0.5.0 

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 added in v0.5.0 

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 added in v0.5.0 

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

Member gets a member by their ID.

func (*Session) Members added in v0.5.0 

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 added in v0.5.0 

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) Switches added in v0.5.0 

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 added in v0.5.0 

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 added in v0.5.0 

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 added in v0.4.0 

type Snowflake uint64

Snowflake is a Discord snowflake

func ParseSnowflake added in v0.4.0 

func ParseSnowflake(str string) (Snowflake, error)

ParseSnowflake parses a snowflake from a string.

func (Snowflake) String added in v0.4.0 

func (s Snowflake) String() string

func (*Snowflake) UnmarshalJSON added in v0.4.0 

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

UnmarshalJSON ...

type StatusError added in v0.5.0 

type StatusError struct {
	Code   int
	Status string
}

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

func (*StatusError) Error added in v0.5.0 

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"`
	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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.