github.com/starshine-sys/pkgo Index | Files

package pkgo

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

Index

Package 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

Constants

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

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

Package pkgo imports 13 packages (graph).

Version v1.1.1 (latest) | Published Aug 15, 2021 | Platform: linux/amd64 | Updated 1 month ago

.
Tools for package owners.