client

Documentation

Overview

Package client is a thin HTTP wrapper around the mp2rss Open API.

It handles:

• Bearer auth (Feed Key)
• User-Agent stamping
• 30s timeout with one retry on 429 / 5xx
• decoding {"errorMessage":"..."} error bodies into typed errs.Error

Index

• Constants
• type Article
• type ArticleList
• type Client
  • func New(baseURL, feedKey string) *Client
  • func NewWithHTTP(baseURL, feedKey string, httpClient *http.Client) *Client
  • func (c *Client) BaseURL() string
  • func (c *Client) ListArticles(mpID int64, page, pageSize int) (*ArticleList, error)
  • func (c *Client) ListSubscriptions(q string, page, pageSize int) (*SubscriptionList, error)
  • func (c *Client) ListSubscriptionsFiltered(q, sourceType string, page, pageSize int) (*SubscriptionList, error)
  • func (c *Client) Subscribe(articleURL string) error
  • func (c *Client) Unsubscribe(mpID int64) error
  • func (c *Client) VerifyAuth() error
  • func (c *Client) XListArticles(xUserID string, page, pageSize int) (*XArticleList, error)
  • func (c *Client) XListPosts(xUserID string, page, pageSize int) (*XPostList, error)
• type SubscribeRequest
• type Subscription
• type SubscriptionList
• type XArticle
• type XArticleList
• type XPost
• type XPostList
• type XPostMedia

Constants

const DefaultTimeout = 30 * time.Second

DefaultTimeout is the per-request HTTP timeout.

Types

type Article

type Article struct {
	MpID            int64  `json:"mpId"`
	ArticleID       string `json:"articleId"`
	Title           string `json:"title"`
	Summary         string `json:"summary"`
	CoverImageURL   string `json:"coverImageUrl"`
	OriginalURL     string `json:"originalUrl"`
	ContentMarkdown string `json:"contentMarkdown"`
	PublishedAt     int64  `json:"publishedAt"`
	UpdatedAt       int64  `json:"updatedAt"`
}

Article is one row of /open-api/subscriptions/{mpId}/articles.

type ArticleList

type ArticleList struct {
	Items []Article `json:"items"`
}

ArticleList is the response body of GET /open-api/subscriptions/{mpId}/articles.

type Client

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

Client is an mp2rss Open API client.

func New

func New(baseURL, feedKey string) *Client

New builds a Client. baseURL should NOT have a trailing slash.

func NewWithHTTP

func NewWithHTTP(baseURL, feedKey string, httpClient *http.Client) *Client

NewWithHTTP is the test-friendly constructor accepting a custom *http.Client.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL returns the resolved base URL.

func (*Client) ListArticles

func (c *Client) ListArticles(mpID int64, page, pageSize int) (*ArticleList, error)

ListArticles calls GET /open-api/subscriptions/{mpId}/articles.

func (*Client) ListSubscriptions

func (c *Client) ListSubscriptions(q string, page, pageSize int) (*SubscriptionList, error)

ListSubscriptions calls GET /open-api/subscriptions without a sourceType filter (server default = all). Prefer ListSubscriptionsFiltered when you want to scope to a single source type.

func (*Client) ListSubscriptionsFiltered

func (c *Client) ListSubscriptionsFiltered(q, sourceType string, page, pageSize int) (*SubscriptionList, error)

ListSubscriptionsFiltered calls GET /open-api/subscriptions?sourceType=<...>.

sourceType must be "", "mp", "x" or "all". Empty omits the param entirely.

func (*Client) Subscribe

func (c *Client) Subscribe(articleURL string) error

Subscribe calls POST /open-api/subscriptions.

func (*Client) Unsubscribe

func (c *Client) Unsubscribe(mpID int64) error

Unsubscribe calls DELETE /open-api/subscriptions/{mpId}.

func (*Client) VerifyAuth

func (c *Client) VerifyAuth() error

VerifyAuth pings GET /open-api/subscriptions?pageSize=1 to confirm the Feed Key is valid. Returns an errs.Error with CodeAuth on 401.

func (*Client) XListArticles

func (c *Client) XListArticles(xUserID string, page, pageSize int) (*XArticleList, error)

XListArticles calls GET /open-api/x/:xUserId/articles.

func (*Client) XListPosts

func (c *Client) XListPosts(xUserID string, page, pageSize int) (*XPostList, error)

XListPosts calls GET /open-api/x/:xUserId/posts.

type SubscribeRequest

type SubscribeRequest struct {
	ArticleURL string `json:"articleUrl"`
}

SubscribeRequest is the body of POST /open-api/subscriptions.

type Subscription

type Subscription struct {
	SourceType string `json:"sourceType,omitempty"`

	// MP fields
	MpID            int64  `json:"mpId,omitempty"`
	MpName          string `json:"mpName,omitempty"`
	MpAvatarURL     string `json:"mpAvatarUrl,omitempty"`
	MpLastArticleAt int64  `json:"mpLastArticleAt,omitempty"`

	// X fields
	XUserID      string `json:"xUserId,omitempty"`
	XUsername    string `json:"xUsername,omitempty"`
	XDisplayName string `json:"xDisplayName,omitempty"`
	XAvatarURL   string `json:"xAvatarUrl,omitempty"`
	XVerified    bool   `json:"xVerified,omitempty"`
	XLastItemAt  int64  `json:"xLastItemAt,omitempty"`

	CreatedAt int64 `json:"createdAt,omitempty"`
}

Subscription is one row of GET /open-api/subscriptions.

The endpoint returns a discriminated union keyed by `sourceType`:

• MP items populate the Mp* fields
• X items populate the X* fields

X-specific fields use omitempty so an MP-filtered listing stays clean; MP fields likewise omitempty so X-filtered listing isn't polluted with `mpId:0` noise.

type SubscriptionList

type SubscriptionList struct {
	Items    []Subscription `json:"items"`
	Total    int            `json:"total"`
	Page     int            `json:"page"`
	PageSize int            `json:"pageSize"`
}

SubscriptionList is the response body of GET /open-api/subscriptions.

type XArticle

type XArticle struct {
	URL             string `json:"url"`
	Title           string `json:"title"`
	Description     string `json:"description"`
	ContentMarkdown string `json:"contentMarkdown"`
	CoverURL        string `json:"coverUrl"`
	PublishedAt     int64  `json:"publishedAt"`
}

XArticle is one row of GET /open-api/x/:xUserId/articles.

type XArticleList

type XArticleList struct {
	Items    []XArticle `json:"items"`
	Total    int        `json:"total"`
	Page     int        `json:"page"`
	PageSize int        `json:"pageSize"`
}

XArticleList is the response body of GET /open-api/x/:xUserId/articles.

type XPost

type XPost struct {
	PostID        string         `json:"postId"`
	Content       string         `json:"content"`
	Media         []XPostMedia   `json:"media"`
	RetweetedPost map[string]any `json:"retweetedPost"`
	QuotedPost    map[string]any `json:"quotedPost"`
	ThreadPosts   []any          `json:"threadPosts"`
	PostedAt      int64          `json:"postedAt"`
}

XPost is one row of GET /open-api/x/:xUserId/posts.

type XPostList

type XPostList struct {
	Items    []XPost `json:"items"`
	Total    int     `json:"total"`
	Page     int     `json:"page"`
	PageSize int     `json:"pageSize"`
}

XPostList is the response body of GET /open-api/x/:xUserId/posts.

type XPostMedia

type XPostMedia struct {
	URL  string `json:"url"`
	Type string `json:"type"`
}

XPostMedia is one media attachment on an X post.