OrangeSite

An Elixir client library for the Hacker News API.

Installation

Add orange_site to your list of dependencies in mix.exs:

def deps do
  [
    {:orange_site, "~> 0.1.0"}
  ]
end

Usage

Fetching Items

Items can be stories, comments, jobs, polls, or poll options.

# Fetch a single item
{:ok, item} = OrangeSite.get_item(8863)

# Or use the bang variant
item = OrangeSite.get_item!(8863)

# Fetch multiple items in parallel
items = OrangeSite.get_items([8863, 8864, 8865])

Fetching Users

# Fetch a user by username
{:ok, user} = OrangeSite.get_user("pg")

# Or use the bang variant
user = OrangeSite.get_user!("pg")

Fetching Story Feeds

# Get top stories (returns list of IDs)
{:ok, story_ids} = OrangeSite.get_top_stories()

# Get new stories
{:ok, story_ids} = OrangeSite.get_new_stories()

# Get best stories
{:ok, story_ids} = OrangeSite.get_best_stories()

# Get Ask HN stories
{:ok, story_ids} = OrangeSite.get_ask_stories()

# Get Show HN stories
{:ok, story_ids} = OrangeSite.get_show_stories()

# Get job stories
{:ok, story_ids} = OrangeSite.get_job_stories()

Fetching Stories with Full Data

# Fetch top 10 stories with their full data
{:ok, stories} = OrangeSite.fetch_top_stories(10)

# Or use default limit of 30
{:ok, stories} = OrangeSite.fetch_top_stories()

Getting Maximum Item ID

{:ok, max_id} = OrangeSite.get_max_item()

Data Structures

Item

An item can be a story, comment, job, poll, or pollopt. The OrangeSite.Item struct contains:

• id - The item's unique id
• type - The type: "story", "comment", "job", "poll", or "pollopt"
• by - The username of the item's author
• time - Creation date (Unix timestamp)
• text - The comment, story, or poll text (HTML)
• dead - true if the item is dead
• deleted - true if the item is deleted
• parent - The comment's parent (comment or story id)
• poll - The pollopt's associated poll
• kids - The ids of the item's comments
• url - The URL of the story
• score - The story's score
• title - The title of the story, poll, or job
• parts - A list of related pollopts
• descendants - Total comment count

User

The OrangeSite.User struct contains:

• id - The user's unique username
• created - Creation date (Unix timestamp)
• karma - The user's karma
• about - The user's self-description (HTML)
• submitted - List of the user's stories, polls and comments

Example: Display Top Stories

defmodule TopStories do
  def display(count \\ 10) do
    {:ok, stories} = OrangeSite.fetch_top_stories(count)

    stories
    |> Enum.with_index(1)
    |> Enum.each(fn {story, index} ->
      IO.puts("#{index}. #{story.title}")
      IO.puts("   Score: #{story.score} | By: #{story.by}")
      if story.url, do: IO.puts("   URL: #{story.url}")
      IO.puts("")
    end)
  end
end

# Run it
TopStories.display()

API Reference

For detailed API documentation, run:

mix docs

Then open doc/index.html in your browser.

License

MIT