Hackfetch

A Promise based Javascript wrapper for the HackerNews API. Hackfetch follows all endpoints for the official HackerNews Firebase API.

Installation

Installation is straightforward and simple.

npm

npm install hackfetch-js

NodeJS

var hnews = require('hackfetch-js');

API Usage

Each response from the HN API is made using the node-fetch module and is returned as a Promise.

Methods

.getTopItems()

Returns an array ids for the top 500 items on HackerNews

Example

hnews.getTopItems().then(function(topItems) {
    console.log(topItems) // [0, 1, 2, ..., 499];
});

.getNewItems()

Returns an array ids for the 500 newest items on HackerNews

Example

hnews.getNewItems().then(function(newItems) {
    console.log(newItems) // [0, 1, 2, ..., 499];
});

.getShowItems()

Returns an array ids for the top 500 showHN items on HackerNews

Example

hnews.getShowItems().then(function(showItems) {
    console.log(showItems) // [0, 1, 2, ..., 499];
});

.getAskItems()

Returns an array ids for the top 500 ask items on HackerNews

Example

hnews.getAskItems().then(function(askItems) {
    console.log(jobsItems) // [0, 1, 2, ..., 499];
});

.getJobItems()

Returns an array ids for the top 500 job items on HackerNews

Example

hnews.getJobItems().then(function(jobsItems) {
    console.log(jobsItems) // [0, 1, 2, ..., 499];
});

.getIdsInCategory(category, numToGet)

Requests an array of ids from one of six categories.

Categories: topstories, newstories, beststories, askstories, showstories, jobstories

@param {String} category required - The category to get items from.

@param {Int} numToGet optional - The number of items you'd like to receive starting from 0 -> Int. This is an optional param if no number is passed then return all results for the chosen category. This function should be relatively quick even when requesting 500 items.

Example

hnews.getIdsInCategory('newstories', 100).then(function(firstOneHundredItems) {
    console.log(firstOneHundredItems); // [0, 1, 2, ..., 99];
});

.getItemById(id)

This is a powerful method which can be used to look up anything found on HackerNews.

Stories, comments, jobs, Ask HNs and even polls are just items. They're identified by their ids, which are unique integers — HN Firebase documentation

@param {Int} id - The id of the item to be requested

All items have some of the following properties, with required properties in bold:

Field | Description ------|------------ id | The item's unique id. deleted | true if the item is deleted. type | The type of item. One of "job", "story", "comment", "poll", or "pollopt". by | The username of the item's author. time | Creation date of the item, in Unix Time. text | The comment, story or poll text. HTML. dead | true if the item is dead. parent | The item's parent. For comments, either another comment or the relevant story. For pollopts, the relevant poll. kids | The ids of the item's comments, in ranked display order. url | The URL of the story. score | The story's score, or the votes for a pollopt. title | The title of the story, poll or job. parts | A list of related pollopts, in display order. descendants | In the case of stories or polls, the total comment count.

Story

{
  "by" : "dhouston",
  "descendants" : 71,
  "id" : 8863,
  "kids" : [ 8952, 9224, 8917, 8884, 8887, 8943, 8869, 8958, 9005, 9671, 8940, 9067, 8908, 9055, 8865, 8881, 8872, 8873, 8955, 10403, 8903, 8928, 9125, 8998, 8901, 8902, 8907, 8894, 8878, 8870, 8980, 8934, 8876 ],
  "score" : 111,
  "time" : 1175714200,
  "title" : "My YC app: Dropbox - Throw away your USB drive",
  "type" : "story",
  "url" : "http://www.getdropbox.com/u/2/screencast.html"
}

Comment

{
  "by" : "norvig",
  "id" : 2921983,
  "kids" : [ 2922097, 2922429, 2924562, 2922709, 2922573, 2922140, 2922141 ],
  "parent" : 2921506,
  "text" : "Aw shucks, guys ... you make me blush with your compliments.<p>Tell you what, Ill make a deal: I'll keep writing if you keep reading. K?",
  "time" : 1314211127,
  "type" : "comment"
}

Example

hnews.getItemById(8863).then(function(item) {
    console.log(item);
    // Item
        {
          "by" : "dhouston",
          "descendants" : 71,
          "id" : 8863,
          "kids" : [ 8952, 9224, 8917]
          "score" : 111,
          "time" : 1175714200,
          "title" : "My YC app: Dropbox - Throw away your USB drive",
          "type" : "story",
          "url" : "http://www.getdropbox.com/u/2/screencast.html"
      }
});

getMaxItem()

The current largest item's id

Example

hnews.getMaxItem().then(function(maxId) {
    console.log(maxId); // 113379847
});

getUpdates()

The item and profile changes

@return Returns two arrays. One for item changes and another for profile changes.

Example

hnews.getUpdates().then(function(updates) {
    console.log(updates);

    // 'items    : [1, 2, 3, ..., 5];
    // 'profiles : ['pg', 'colealanr'];
});

Powering

Hackdot API - A free RESTful API powering data for the iOS client, Hackdot.

Contributing

Please submit a pull request or open an issue if you'd like to add a feature or fix any bugs.

Dependencies

node-fetch - https://www.npmjs.com/package/node-fetch

This is declared as a dependency in package.json and will be automatically installed.

Author

Please feel free to contact me— Cole Alan Roberts via coleroberts.design or @colealan

License

This project is licensed under the MIT License - see the LICENSE.md file for details