feed

type Feed struct {
	// Name is the name of the feed as defined by the user.
	Name string `json:"name"`

	// Type is the type of the feed. It can be one of the types defined in this
	// file.
	Type string `json:"type"`

	// URL is the URL from which the feed is fetched. If this is empty, the
	// feed is assumed to be a virtual feed managed by the application.
	URL string `json:"url"`

	// Items is a map of items in the feed. The key is the UID of the item.
	Items map[string]*Item `json:"items"`

	// Params is an object with parameters that are specific to the feed type.
	// It is up to the feed type to define what these parameters are, and they
	// are usually used when parsing or refreshing the feed.
	Params any `json:"params"`

	// LastRefreshedAt is the time when the feed was last fetched.
	LastRefreshedAt int64 `json:"updated_at"`

	// LastRefreshError is the last error that occurred when refreshing the
	// feed.
	LastRefreshError string `json:"error"`
}

type FeedParams interface {
	Validate() error
}

type FeedSummary struct {
	// UID is the unique identifier of the feed.
	UID string `json:"uid"`

	// URL is the URL from which the feed is fetched.
	URL string `json:"url"`

	// Name is the name of the feed as defined by the user.
	Name string `json:"name"`

	// Items is a list of items in the feed. It is usually empty, unless
	// explicitly requested.
	Items []*ItemSummary `json:"items,omitempty"`

	// LastUpdated is the time when the feed was last fetched.
	LastUpdated int64 `json:"last_updated"`

	// LastError is the error that occurred when refreshing the feed in the
	// last attempt.
	LastError string `json:"last_error"`

	// ItemCount is the number of items in the feed.
	ItemCount int `json:"item_count"`

	// ReadCount is the number of items in the feed that were marked as read.
	ReadCount int `json:"read_count"`

	// LastItem is the timestamp of the most recent item in the feed.
	LastItem int64 `json:"last_item"`
}

type Item struct {
	RawItem

	// FeedUID is the UID of the feed that this item belongs to. This field is
	// populated by the feed itself.
	FeedUID string `json:"feed_uid"`
	// Timestamp is the time when the item was first seen. This field is
	// populated by the feed itself.
	Timestamp int64 `json:"timestamp"`

	// Read is true if the item was marked as read by the user.
	Read bool `json:"read"`
}

type ItemSummary struct {
	// UID is the unique identifier of the item.
	UID string `json:"uid"`

	// FeedUID is the UID of the feed that this item belongs to.
	FeedUID string `json:"feed_uid"`

	// FeedName is the name of the feed that this item belongs to.
	FeedName string `json:"feed_name"`

	// URL is the URL of the item. It comes directly from the feed and is not
	// sanitized. Do not embed it in the page directly without proper measures.
	URL string `json:"url"`

	// Title is a short title or description of the item. It comes directly
	// from the feed and is not sanitized. Do not embed it in the page directly
	// without proper measures.
	Title string `json:"title"`

	// Timestamp is the time when the item was first seen.
	Timestamp int64 `json:"timestamp"`

	// Authors is a short comma-separated summary of authors of the item. It
	// comes directly from the feed and is not sanitized. Do not embed it in
	// the page directly without proper measures.
	Authors string `json:"authors"`

	// Read is true if the item was marked as read by the user.
	Read bool `json:"read"`

	// Content is the full content of the item, usually a sanitized HTML
	// fragment. It comes directly from the feed and may safely be embedded in
	// the page directly.
	Content string `json:"content,omitempty"`
}

type RawItem struct {
	// URL is the URL of the item.
	URL string `json:"url"`
	// Title is a short title or description of the item.
	Title string `json:"title"`
	// Authors is short summary of authors of the item (usually
	// comma-separated).
	Authors string `json:"authors"`
	// Content is the full content of the item, usually a sanitized HTML
	// fragment.
	Content string `json:"content"`
	// Position is the position of the item in the feed when it was first seen.
	// Assuming two items are first seen at the same time, a lower position
	// typically means a newer item (i.e., that's how blogs are typically laid
	// out).
	Position int `json:"position"`
}