hkn

README

hkn

A go module for interacting with Hacker News.

Features

A ticked checkbox indicates the feature currently exists in master.

An item refers to either a story, comment, ask, job, poll or poll part

• Get a single item
• Get multiple items
• Get largest item id
• Get top 500 new, top and best stories (or a number >= 0, <= 500)
• Get top 200 ask, show and job stories (or a number >= 0, <= 200)
• Get changed items and profiles
• Get a user
• Get a user's submissions
• Get a user's comments
• Get a user's hidden items
• Get a user's upvoted items
• Get a user's favorited items
• Login a user
• Upvote an item
• Unvote a comment
• Downvote a comment
• Create a story
• Create a poll
• Create a comment
• Flag an item
• Hide an item
• Favorite an item
• Edit an item
• Delete an item
• Search
  • Full text
  • By tag
  • By created at date
  • By points
  • By number of comments
  • By page number
  • Sorted by relevance, then points, then number of comments
  • Sorted by most recent

Usage

First get hkn:

$ go get github.com/lukakerr/hkn

Import into your project:

import "github.com/lukakerr/hkn"

// or

import (
        "github.com/lukakerr/hkn"
)

Methods

Examples of all methods on the client can be found in example/main.go.

First create a client:

client := hkn.NewClient()

Various methods can then be then called on the client:

Get a single item by id

// Returns (Item, error)
item, err := client.GetItem(8869)

Get multiple items by ids

// Returns ([]Item, error)
items, err := client.GetItems([]int{8869, 8908, 8881, 10403, 9125})

Get max item id

// Returns (int, error)
id, err := client.GetMaxItemID()

Get the latest item and profile updates

// Returns (Updates, error)
updates, err := client.GetUpdates()

Get top stories given a number

// Returns ([]int, error)
stories, err := client.GetTopStories(20)

Get new stories given a number

// Returns ([]int, error)
stories, err := client.GetNewStories(20)

Get best stories given a number

// Returns ([]int, error)
stories, err := client.GetBestStories(20)

Get latest ask stories given a number

// Returns ([]int, error)
stories, err := client.GetLatestAskStories(20)

Get latest show stories given a number

// Returns ([]int, error)
stories, err := client.GetLatestShowStories(20)

Get latest job stories given a number

// Returns ([]int, error)
stories, err := client.GetLatestJobStories(20)

Get a user by id

// Returns (User, error)
user, err := client.GetUser("jl")

Login a user with a username and password

// The cookie returned is used for actions that require a user to be logged in
// Returns (*http.Cookie, error)
cookie, err := client.Login("username", "password")

Upvote an item

A cookie is required to upvote, get this from logging in

// Returns (bool, error)
upvoted, err := client.Upvote(8869, cookie)

Unvote a comment

A cookie is required to unvote, get this from logging in

// Returns (bool, error)
unvoted, err := client.Unvote(8869, cookie)

Create a comment

A cookie is required to create a comment, get this from logging in

// Returns (bool, error)
content := "Really cool."
commented, err := client.Comment(8869, content, cookie)

Create a story with a title and URL

A cookie is required to create a story, get this from logging in

// Returns (bool, error)
title := "A title."
URL := "https://a.url.com"
created, err := client.CreateStoryWithURL(title, URL, cookie)

Create a story with a title and text

A cookie is required to create a story, get this from logging in

// Returns (bool, error)
title := "A title."
text := "Some text."
created, err := client.CreateStoryWithText(title, text, cookie)

Running

To run the example locally:

$ go run example/main.go

Testing

$ go test

Documentation

Overview

Package hkn is a go module for interacting with Hacker News.

To get started simply import the package, create a client and call methods on the client:

import (
	"fmt"

	"github.com/lukakerr/hkn"
)

func main() {
	client := hkn.NewClient()

	// For example, to get an item by id
	item, err := client.GetItem(8869)

	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Printf("%+v\n", item)
}

Index

• Variables
• type Client
  • func NewClient() *Client
  • func (c *Client) Comment(id int, content string, cookie *http.Cookie) (bool, error)
  • func (c *Client) CreateStoryWithText(title string, text string, cookie *http.Cookie) (bool, error)
  • func (c *Client) CreateStoryWithURL(title string, url string, cookie *http.Cookie) (bool, error)
  • func (c *Client) GetBestStories(number int) ([]int, error)
  • func (c *Client) GetItem(id int) (Item, error)
  • func (c *Client) GetItems(ids []int) (Items, error)
  • func (c *Client) GetLatestAskStories(number int) ([]int, error)
  • func (c *Client) GetLatestJobStories(number int) ([]int, error)
  • func (c *Client) GetLatestShowStories(number int) ([]int, error)
  • func (c *Client) GetMaxItemID() (int, error)
  • func (c *Client) GetNewStories(number int) ([]int, error)
  • func (c *Client) GetTopStories(number int) ([]int, error)
  • func (c *Client) GetUpdates() (Updates, error)
  • func (c *Client) GetUser(id string) (User, error)
  • func (c *Client) Login(username string, password string) (*http.Cookie, error)
  • func (c *Client) Unvote(id int, cookie *http.Cookie) (bool, error)
  • func (c *Client) Upvote(id int, cookie *http.Cookie) (bool, error)
• type Item
• type Items
• type Updates
• type User

Variables

var (
	// ErrFetching represents an error fetching a resource
	ErrFetching = errors.New("fetching resource failed")

	// ErrEmptyContent represents an error that content provided is empty
	ErrEmptyContent = errors.New("content is empty")

	// ErrEmptyTitle represents an error that a title provided is empty
	ErrEmptyTitle = errors.New("title is empty")

	// ErrInvalidAuth represents an error authenticating
	ErrInvalidAuth = errors.New("invalid username or password")

	// ErrFetchingActionURL represents an error fetching an action URL
	ErrFetchingActionURL = errors.New("fetching action URL failed")

	// ErrInvalidNumber represents an error that a number provided is invalid
	ErrInvalidNumber = errors.New("invalid number")
)

Types

type Client

type Client struct {
	BaseURL string
	WebURL  string
}

Client represents the hkn client

func NewClient

func NewClient() *Client

NewClient creates a new hkn client

func (*Client) Comment

func (c *Client) Comment(id int, content string, cookie *http.Cookie) (bool, error)

Comment creates a comment on an item given an id, content and cookie, and returns whether the comment was successful

func (*Client) CreateStoryWithText

func (c *Client) CreateStoryWithText(title string, text string, cookie *http.Cookie) (bool, error)

CreateStoryWithText creates a story with a mandatory title and optional text body

func (*Client) CreateStoryWithURL

func (c *Client) CreateStoryWithURL(title string, url string, cookie *http.Cookie) (bool, error)

CreateStoryWithURL creates a story with a mandatory title and optional url

func (*Client) GetBestStories

func (c *Client) GetBestStories(number int) ([]int, error)

GetBestStories returns best stories given a number

func (*Client) GetItem

func (c *Client) GetItem(id int) (Item, error)

GetItem returns a single item given an id

func (*Client) GetItems

func (c *Client) GetItems(ids []int) (Items, error)

GetItems returns a slice of items given a number of ids

func (*Client) GetLatestAskStories

func (c *Client) GetLatestAskStories(number int) ([]int, error)

GetLatestAskStories returns latest ask stories given a number

func (*Client) GetLatestJobStories

func (c *Client) GetLatestJobStories(number int) ([]int, error)

GetLatestJobStories returns latest job stories given a number

func (*Client) GetLatestShowStories

func (c *Client) GetLatestShowStories(number int) ([]int, error)

GetLatestShowStories returns latest show stories given a number

func (*Client) GetMaxItemID

func (c *Client) GetMaxItemID() (int, error)

GetMaxItemID returns the most recent item id

func (*Client) GetNewStories

func (c *Client) GetNewStories(number int) ([]int, error)

GetNewStories returns new stories given a number

func (*Client) GetTopStories

func (c *Client) GetTopStories(number int) ([]int, error)

GetTopStories returns top stories given a number

func (*Client) GetUpdates

func (c *Client) GetUpdates() (Updates, error)

GetUpdates returns the latest item and profile updates

func (*Client) GetUser

func (c *Client) GetUser(id string) (User, error)

GetUser returns a user given an id

func (*Client) Login

func (c *Client) Login(username string, password string) (*http.Cookie, error)

Login a user given a username and password and get back an authentication cookie

func (*Client) Unvote

func (c *Client) Unvote(id int, cookie *http.Cookie) (bool, error)

Unvote a comment given an id and cookie and get back whether the unvote was successful

func (*Client) Upvote

func (c *Client) Upvote(id int, cookie *http.Cookie) (bool, error)

Upvote an item given an id and cookie and get back whether the upvote was successful

type Item

type Item struct {
	ID          int    `json:"id"`
	Deleted     bool   `json:"deleted"`
	Type        string `json:"type"`
	By          string `json:"by"`
	Time        int32  `json:"time"`
	Text        string `json:"text"`
	Dead        bool   `json:"dead"`
	Parent      int    `json:"parent"`
	Poll        int    `json:"poll"`
	Kids        []int  `json:"kids"`
	URL         string `json:"url"`
	Score       int    `json:"score"`
	Title       string `json:"title"`
	Parts       []int  `json:"parts"`
	Descendants int    `json:"descendants"`
}

Item represents a Hacker News item

type Items

type Items []Item

Items represents an array of items

type Updates

type Updates struct {
	Items    []int    `json:"items"`
	Profiles []string `json:"profiles"`
}

Updates represents profile and item updates

type User

type User struct {
	ID        string `json:"id"`
	Delay     int    `json:"delay"`
	Created   int32  `json:"created"`
	Karma     int    `json:"karma"`
	About     string `json:"about"`
	Submitted []int  `json:"submitted"`
}

User represents a Hacker News user