# OrangeSite

An Elixir client library for the [Hacker News API](https://github.com/HackerNews/API).

## Installation

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

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

## Usage

### Fetching Items

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

```elixir
# 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

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

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

### Fetching Story Feeds

```elixir
# 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

```elixir
# 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

```elixir
{: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

```elixir
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:

```bash
mix docs
```

Then open `doc/index.html` in your browser.

## License

MIT