@4lch4/lib-hn NPM

Lib-HN

This package is a small library for interacting with the official Hacker News (HN) API. Since the API is pretty limited, in terms of features, this library tries to help by providing a different version of the LibHN class, called LibHNExtended, that has a few extra functions for working with the data returned by the API.

Usage

To use the library, simply create an instance of the class you wish to use (LibHN or LibHNExtended) and begin calling the exported functions:

import { LibHN, LibHNExtended } from '@4lch4/lib-hn'

const client = new LibHN()
// const client = new LibHNExtended()

client
  .getListStoryIds('top', 15)
  .then(res => console.log(`Top 15 story ids: ${res.data.join(' - ')}`))
  .catch(err => console.error(err))

Exported Members

Since there isn't much exported by the library, let's go over all of what is available.

Interfaces

HNItemType — The types of items that can be returned by the HN API.
HNStoryList — The types of story lists that are available. Such as topstories, beststories, etc.
IAPIResponse — The type of object returned by the library for a response from the API.
IAppConfig — The optional config for the app, including baseUrl and version.
IHNItem — A standard object returned by the HN API.
IHNUpdate — An object returned by the /v0/updates endpoint & getUpdates() method.
IHNUser — A User object, returned by the /v0/user/{username} endpoint & getUser() method.

Classes

There are two classes that are exported by the package: LibHN and LibHNExtended

LibHN is the basic class that will enable you to interact with the HN API.
LibHNExtended extends the LibHN class and provides some extra methods for handling the data returned by the API.

With the basic info about the classes out of the way, let's discuss the methods provided by each class.

LibHN

getListStoryIds(list: HNStoryList = 'top', count?: number)
- Retrieve the ids for count stories in the given list.
- Leaving count undefined means to return all results.
- For example, if you want all of the stories in the 'best' list, you'd do this: getListStoryIds('best')
- NOTE: This method only returns the ids of the stories, not the content of those stories. If you wish to receive the content as well, use the getListStoryItems method.
- Sample Response:
```
// In total: 500 IDs were retrieved.
[ 32333565, 32331367, 32331781, 32333115, 32333417, 32332385, 32331716, ... ]
```

getListStoryItems(list: HNStoryList = 'top', count?: number)

Retrieve the content for count stories in the given list.
Leaving count undefined means to return all results.
NOTE: This method will make a call to /v0/item/{itemId} for each story in the list. In my tests, the standard response is 500 IDs, meaning 500 calls to /v0/item/{itemId}.
Sample Response (getListStoryItems('top', 3)):

[
  {
    "by": "ColinWright",
    "descendants": 29,
    "id": 32334552,
    "kids": [
      32335109, 32335044, 32335280, 32335400, 32335284, 32334976, 32335008,
      32334689, 32335134, 32334959, 32334812, 32335135, 32335332, 32335309,
      32335268, 32335095
    ],
    "score": 189,
    "time": 1659547590,
    "title": "Strangest Thing Found in a Book",
    "type": "story",
    "url": "https://noctslackv2.wordpress.com/"
  },
  {
    "by": "isolli",
    "descendants": 40,
    "id": 32333565,
    "kids": [
      32334673, 32334566, 32333879, 32334418, 32333698, 32333729, 32334265,
      32334800, 32334427, 32334067
    ],
    "score": 110,
    "time": 1659542882,
    "title": "Why do tree-based models still outperform deep learning on tabular data?",
    "type": "story",
    "url": "https://arxiv.org/abs/2207.08815"
  },
  {
    "by": "triplechill",
    "descendants": 5,
    "id": 32335165,
    "kids": [32335388, 32335320, 32335372, 32335317],
    "score": 13,
    "time": 1659550896,
    "title": "Productivity Porn",
    "type": "story",
    "url": "https://calebschoepp.com/blog/2022/productivity-porn/"
  }
]

getItem(id: number)

Retrieves the content of the item with the given ID.
Children/comments are returned as IDs. If you wish to retrieve the content of the children, use the LibHNExtended class and call the getAllChildren method.
Sample Response (getItem(30222165)):

{
  "by": "zdw",
  "descendants": 566,
  "id": 30222165,
  // In total: 147 "kids" were returned.
  "kids": [ 30222528, 30222543, 30222572, 30222309, 30222548, 30222990, ... ],
  "score": 1607,
  "time": 1644075909,
  "title": "Adobe tricks users into a 12 month contract",
  "type": "story",
  "url": "https://twitter.com/darkpatterns/status/1489901640777973768"
}

getUpdates()

Retrieves the latest updates to items and profiles.
Sample Response (getUpdates()):

{
  // In total: 107 IDs are returned.
  "items": [ 30340345, 30338095, 30341491, 30341490, 30341428, 30341484, 30340305, 30341482, ... ],

  // In total: 29 usernames are returned.
  "profiles": [ "cfcosta", "yabones", "aliabd", "travisgriggs", "version_five", "bobthechef", ... ]
}

getUser(username: string)

Retrieve the content for the user with the given username.
Sample Response (getUser('Alcha')):

{
  "about": "I like making and fixing things that usually involve a keyboard and&#x2F;or a mouse.<p>I go by 4lch4 or Alcha (Al-kuh) on most, if not all, platforms.",
  "created": 1492810088,
  "id": "Alcha",
  "karma": 6,
  "submitted": [29676506, 29676453, 29152977, 27463258, 27455822]
}