hn

README

== HN

Provides a client library for YCombinator's Hacker News website.

=== Usage

Documentation for the HN client library are provided as GoDocs and can
be viewed by running `go doc -all selesy/hn` (within a module that uses
it) or by visiting https://pkg.go.dev/github.com/selesy/hn.  Examples in this documentation show queries that are the equivalent of those shown in the HN API reference.

=== References

The following links provide the specifications for retriving HN data:

- https://blog.ycombinator.com/hacker-news-api/
- https://github.com/HackerNews/API
- https://firebase.google.com/docs/libraries/

Documentation

Index

• Constants
• type Client
  • func DefaultClient(ctx context.Context) (*Client, error)
  • func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error)
  • func (c Client) Item(ctx context.Context, id int) (Item, error)
  • func (c Client) MaxItem(ctx context.Context) (int, error)
  • func (c Client) NewStories(ctx context.Context) (IDList, error)
  • func (c Client) Update(ctx context.Context, rem Remote) (bool, error)
  • func (c Client) User(ctx context.Context, id string) (User, error)
• type ID
• type IDList
  • func (r IDList) ETag() string
  • func (r IDList) Path() string
  • func (r *IDList) SetETag(etag string)
  • func (r *IDList) SetPath(path string)
  • func (l *IDList) UnmarshalJSON(data []byte) error
• type Item
  • func (r Item) ETag() string
  • func (r Item) Path() string
  • func (r *Item) SetETag(etag string)
  • func (r *Item) SetPath(path string)
  • func (i *Item) UnmarshalJSON(data []byte) error
• type Remote
• type User
  • func (r User) ETag() string
  • func (r User) Path() string
  • func (r *User) SetETag(etag string)
  • func (r *User) SetPath(path string)
  • func (u *User) UnmarshalJSON(data []byte) error

Constants

const (
	HackerNewsAPI = "https://hacker-news.firebaseio.com"

	APIVersion     = "v0"
	ItemPath       = APIVersion + "/item/%d"
	MaxItemPath    = APIVersion + "/maxitem"
	NewStoriesPath = APIVersion + "/newstories"
	UserPath       = APIVersion + "/user/%s"
)

Types

type Client

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

Client provides a consistent interface to the HN API.

func DefaultClient

func DefaultClient(ctx context.Context) (*Client, error)

DefaultClient creates a new HN client with charactistics that are appropriate for most users calling the HN API as follows:

• No authentication is required.
• ETags are used to determine whether an item or user has changed.

func NewClient

func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error)

NewClient creates a new HN client using the provided API options.

func (Client) Item

func (c Client) Item(ctx context.Context, id int) (Item, error)

Item retrieves the news item with the provided id from the HN API.

func (Client) MaxItem

func (c Client) MaxItem(ctx context.Context) (int, error)

MaxItem returns the id of the last item created. The client never caches the maximum item id, nor does it use ETags to avoid retrieving the value from the server.

func (Client) NewStories

func (c Client) NewStories(ctx context.Context) (IDList, error)

NewStories returns a list of item ids for the 500 newest stories.

func (Client) Update

func (c Client) Update(ctx context.Context, rem Remote) (bool, error)

Update retrieves a new version of an HN Item, User or list (passed into the method as rem) if there is one available. If ETags are disabled in the client, the remote object is retrieved from the server again and the boolean returned will alwasy indicated that the item was changed. The default operation of the client is to check the ETags. In this case, the returned boolean will indicate whether a new version of the object has been retrieved.

func (Client) User

func (c Client) User(ctx context.Context, id string) (User, error)

User retrieves the news item with the provided id from the HN API.

type ID

type ID int

type IDList

type IDList struct {
	IDs []ID
	// contains filtered or unexported fields
}

IDList provides a type that can maintain the path to one of the HN lists along with the most recently retrieve ETag and the list of IDs itself.

func (IDList) ETag

func (r IDList) ETag() string

func (IDList) Path

func (r IDList) Path() string

func (*IDList) SetETag

func (r *IDList) SetETag(etag string)

func (*IDList) SetPath

func (r *IDList) SetPath(path string)

func (*IDList) UnmarshalJSON

func (l *IDList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements encoding/json.Unmarshaler for HN id lists.

https://pkg.go.dev/encoding/json#Unmarshaler

type Item

type Item struct {
	ID          int       // The item's unique id.
	Type        string    // The type of item. One of "job", "story", "comment", "poll", or "pollopt".
	By          string    // The username of the item's author.
	Time        time.Time // Creation date of the item, in Unix Time.
	Text        string    // The comment, story or poll text. HTML.
	Parent      int       // The comment's parent: either another comment or the relevant story.
	Poll        int       // The pollopt's associated poll.
	Kids        []int     // The ids of the item's comments, in ranked display order.
	URL         string    // The URL of the story.
	Score       int       // The story's score, or the votes for a pollopt.
	Title       string    // The title of the story, poll or job. HTML.
	Parts       []int     // A list of related pollopts, in display order.
	Descendants int       // In the case of stories or polls, the total comment count.
	Dead        bool      // if the item is dead.
	Deleted     bool      // if the item is deleted.
	// contains filtered or unexported fields
}

Item contains the attributes of an HN item.

See: https://github.com/HackerNews/API#items

func (Item) ETag

func (r Item) ETag() string

func (Item) Path

func (r Item) Path() string

func (*Item) SetETag

func (r *Item) SetETag(etag string)

func (*Item) SetPath

func (r *Item) SetPath(path string)

func (*Item) UnmarshalJSON

func (i *Item) UnmarshalJSON(data []byte) error

UnmarshalJSON implements encoding/json.Unmarshaler for HN items.

https://pkg.go.dev/encoding/json#Unmarshaler

type Remote

type Remote interface {
	Path() string
	SetPath(string)
	ETag() string
	SetETag(string)
}

Remote is an interface that represents a base HN object stored in the Firebase server. Path and ETag accessors and mutators are provided so that the interface's implementation can be embedded without being exported.

type User

type User struct {
	ID        string    // The user's unique username. Case-sensitive. Required.
	Delay     int       // Delay in minutes between a comment's creation and its visibility to other users.
	Created   time.Time // Creation date of the user, in Unix Time.
	Karma     int       // The user's karma.
	About     string    // The user's optional self-description. HTML.
	Submitted []int     // List of the user's stories, polls and comments.
	// contains filtered or unexported fields
}

User contains the attributes of an HN user.

See: https://github.com/HackerNews/API#users

func (User) ETag

func (r User) ETag() string

func (User) Path

func (r User) Path() string

func (*User) SetETag

func (r *User) SetETag(etag string)

func (*User) SetPath

func (r *User) SetPath(path string)

func (*User) UnmarshalJSON

func (u *User) UnmarshalJSON(data []byte) error

UnmarshalJSON implements encoding/json.Unmarshaler for HN users.

https://pkg.go.dev/encoding/json#Unmarshaler