lists

Documentation

Overview

Package lists provides easy API access to Sourcehut mailing lists.

Index

• Constants
• type Client
  • func NewClient(opts ...Option) (*Client, error)
  • func (c *Client) GetUser(username string) (sourcehut.User, error)
  • func (c *Client) List(username string) (ListIter, error)
  • func (c *Client) ListEmails(username string) (PostIter, error)
  • func (c *Client) ListPosts(username, listname string) (PostIter, error)
  • func (c *Client) Version() (string, error)
• type List
• type ListIter
  • func (i ListIter) List() *List
• type Option
  • func Base(base string) Option
  • func SrhtClient(client sourcehut.Client) Option
• type Post
• type PostIter
  • func (i PostIter) Post() *Post
• type ShortList
• type ShortPost

Examples

• PostIter

Constants

const BaseURL = "https://lists.sr.ht/api/"

BaseURL is the default public Sourcehut mailing lists API URL. It is exported for convenience.

Types

type Client

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

Client handles communication with the mailing lists related methods of the Sourcehut API.

API docs: https://man.sr.ht/lists.sr.ht/api.md

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient returns a new mailing list API client.

func (*Client) GetUser

func (c *Client) GetUser(username string) (sourcehut.User, error)

GetUser returns information about the provided username, or the currently authenticated user if the username is empty.

func (*Client) List

func (c *Client) List(username string) (ListIter, error)

List returns an iterator over all mailing lists owned by the provided username. If an empty username is provided, the authenticated user is used.

func (*Client) ListEmails

func (c *Client) ListEmails(username string) (PostIter, error)

ListEmails returns all emails sent by the provided user.

func (*Client) ListPosts

func (c *Client) ListPosts(username, listname string) (PostIter, error)

ListPosts returns the posts in a mailing list owned by the given username.

func (*Client) Version

func (c *Client) Version() (string, error)

Version returns the version of the API.

API docs: https://man.sr.ht/api-conventions.md#get-apiversion

type List

type List struct {
	ShortList

	Created time.Time `json:"created"`
	Updated time.Time `json:"updated"`
	Desc    string    `json:"description"`
	Perms   struct {
		// TODO: "browse", "reply", and "post" are valid permissions.
		// Make a type for this.
		NonSubscriber []string `json:"nonsubscriber"`
		Subscriber    []string `json:"subscriber"`
		Account       []string `json:"account"`
	} `json:"permissions"`
}

List represents the expanded form of a mailing list.

type ListIter

type ListIter struct {
	*sourcehut.Iter
}

ListIter is used for iterating over a collection of mailing lists.

func (ListIter) List

func (i ListIter) List() *List

List returns the mailing list which the iterator is currently pointing to.

type Option

type Option func(*Client) error

Option is used to configure an API client.

func Base

func Base(base string) Option

Base returns an option that configures the public Sourcehut API URL.

If base does not have a trailing slash, one is added automatically. If unspecified, BaseURL is used.

func SrhtClient

func SrhtClient(client sourcehut.Client) Option

SrhtClient returns an option that configures the client to use the provided sourcehut.Client for API requests. If unspecified, a default sourcehut.Client (with no options of its own) is used.

type Post

type Post struct {
	ShortPost

	Patch        bool   `json:"is_patch"`
	PullRequest  bool   `json:"is_request_pull"`
	Replies      int64  `json:"replies"`
	Participants int64  `json:"participants"`
	Envelope     string `json:"envelope"`
}

Post represents the expanded form of an email message.

type PostIter

type PostIter struct {
	*sourcehut.Iter
}

PostIter is used for iterating over a collection of mailing list posts.

Example

srhtClient := sourcehut.NewClient(sourcehut.Token("<personal access token>"))
listClient, _ := lists.NewClient(lists.SrhtClient(srhtClient))

iter, _ := listClient.ListPosts("~sircmpwn", "sr.ht-dev")
for iter.Next() {
	p := iter.Post()
	log.Printf("Post %d: %q\n", p.ID, p.Subject)
}
if err := iter.Err(); err != nil {
	log.Fatalf("Error fetching posts: %q", err)
}

func (PostIter) Post

func (i PostIter) Post() *Post

Post returns the post which the iterator is currently pointing to.

type ShortList

type ShortList struct {
	Name  string              `json:"name"`
	Owner sourcehut.ShortUser `json:"owner"`
}

ShortList represents the unexpanded form of a mailing list.

type ShortPost

type ShortPost struct {
	ID        int64                `json:"id"`
	Created   time.Time            `json:"created"`
	List      ShortList            `json:"list"`
	MessageID string               `json:"message_id"`
	ParentID  int64                `json:"parent_id"`
	Sender    *sourcehut.ShortUser `json:"sender"`
	Subject   string               `json:"subject"`
	ThreadID  int64                `json:"thread_id"`
}

ShortPost represents the unexpanded form of an email message.