lemmy

README

go-lemmy / lemmy

A pure-Go (CGO=0), dependency-free read client for the Lemmy REST API (/api/v3).

c := lemmy.New("https://lemmy.world")
list, err := c.Posts(context.Background(), lemmy.PostsOptions{Community: "technology", Sort: "Hot", Limit: 20})
for _, p := range list.Posts {
    fmt.Printf("%s — %s (score %d)\n", p.Title, p.Community, p.Score)
}

Optional Login stores a JWT for authenticated reads. Stdlib only; builds for all 64-bit targets.

License

BSD-3-Clause © the go-lemmy/lemmy authors.

Documentation

Overview

Package lemmy is a dependency-free read client for the Lemmy REST API (/api/v3). It targets CGO_ENABLED=0 builds and uses only the Go standard library.

Index

• type Client
  • func New(instance string, opts ...Option) *Client
  • func (c *Client) Login(ctx context.Context, usernameOrEmail, password string) error
  • func (c *Client) Posts(ctx context.Context, opts PostsOptions) (*PostList, error)
  • func (c *Client) SearchCommunities(ctx context.Context, query string, limit int) (*CommunityList, error)
• type Community
• type CommunityList
• type Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithUserAgent(ua string) Option
• type Post
• type PostList
• type PostsOptions

Types

type Client

type Client struct {
	// Instance is the base URL of the Lemmy instance,
	// e.g. https://lemmy.world.
	Instance string
	// HTTPClient is used for all requests. Defaults to http.DefaultClient.
	HTTPClient *http.Client
	// UserAgent is sent with every request.
	UserAgent string
	// contains filtered or unexported fields
}

Client is a read client for a single Lemmy instance.

func New

func New(instance string, opts ...Option) *Client

New returns a Client for the given instance base URL (e.g. https://lemmy.world). Trailing slashes are trimmed.

func (*Client) Login

func (c *Client) Login(ctx context.Context, usernameOrEmail, password string) error

Login POSTs /api/v3/user/login and stores the returned jwt for subsequent requests.

func (*Client) Posts

func (c *Client) Posts(ctx context.Context, opts PostsOptions) (*PostList, error)

Posts GETs /api/v3/post/list with the options as query params.

func (*Client) SearchCommunities

func (c *Client) SearchCommunities(ctx context.Context, query string, limit int) (*CommunityList, error)

SearchCommunities GETs /api/v3/search?type_=Communities for communities matching query — a public read used to discover communities to subscribe to. limit caps the page (0 → 20).

type Community

type Community struct {
	Name        string
	Title       string
	Description string
	Icon        string
	ActorID     string
	Subscribers int
	NSFW        bool
}

Community is one community-search hit: enough to show a discovery row and subscribe. Name is the local handle ("golang"); ActorID is the federated URL ("https://lemmy.world/c/golang") that identifies it across instances.

type CommunityList

type CommunityList struct {
	Communities []Community
}

CommunityList is a page of community-search results.

type Option

type Option func(*Client)

Option configures a Client.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the http.Client used for requests.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header sent with every request.

type Post

type Post struct {
	ID           int
	Title        string
	URL          string
	Body         string
	Permalink    string
	ThumbnailURL string
	Published    time.Time
	NSFW         bool
	Creator      string
	Community    string
	Score        int
	Comments     int
}

Post is a flattened view of a Lemmy post.

type PostList

type PostList struct {
	Posts []Post
}

PostList is a list of posts.

type PostsOptions

type PostsOptions struct {
	Community string // community name; empty = instance-wide
	Sort      string // Active|Hot|New|Top...; default "Hot"
	Type      string // All|Local|Subscribed; default "All"
	Limit     int    // default 20
	Page      int    // 1-based; default 1
}

PostsOptions configures a Posts request.