Advent

Haskell bindings for Advent of Code 2018 API. Caches and throttles requests automatically.

Specify your requests with AoC and AoCOpts, and run them with runAoC.

Examples:

-- Fetch prompts for day 5
runAoC myOpts $ AoCPrompt (mkDay_ 5)

-- Fetch input for day 8
runAoC myOpts $ AoCInput (mkDay_ 8)

-- Submit answer "hello" for Day 10, Part 1
runAoC myOpts $ AoCSubmit (mkDay_ 10) Part1 "hello"

Please use responsibly. All actions are by default rate limited to one per three seconds, but this can be adjusted to a hard-limited cap of one per second.

API

data AoC :: Type -> Type where

An API command. An AoC a an AoC API request that returns results of type a.

A lot of these commands take Day, which represents a day of December up to and including Christmas Day (December 25th). You can convert an integer day (1 - 25) into a Day using mkDay or mkDay_.

Constructors

AoCPrompt :: Day -> AoC (Map Part Text)

Fetch prompts for a given day. Returns a Map of Parts and their associated promps, as HTML.

_Cacheing rules_: Is cached on a per-day basis. An empty session key is given, it will be happy with only having Part 1 cached. If a non-empty session key is given, it will trigger a cache invalidation on every request until both Part 1 and Part 2 are received.

AoCInput :: Day -> AoC Text

Fetch input, as plaintext. Returned verbatim. Be aware that input might contain trailing newlines.

Cacheing rules: Is cached forever, per day per session key.

AoCSubmit :: Day -> Part -> String -> AoC (Text, SubmitRes)

Submit a plaintext answer (the String) to a given day and part. Receive a server reponse (as HTML) and a response code SubmitRes.

WARNING: Answers are not length-limited. Answers are stripped of leading and trailing whitespace and run through encode before submitting.

Cacheing rules: Is never cached.

AoCLeaderboard :: Integer -> AoC Leaderboard

Fetch the leaderboard for a given leaderboard public code (owner member ID). Requires session key.

The public code can be found in the URL of the leaderboard:

https://adventofcode.com/2019/leaderboard/private/view/12345

(the 12345 above)

NOTE: This is the most expensive and taxing possible API call, and makes up the majority of bandwidth to the Advent of Code servers. As a courtesy to all who are participating in Advent of Code, please use this super respectfully, especially in December: if you set up automation for this, please do not use it more than once per day.

Cacheing rules: Is never cached, so please use responsibly (see note above).

Since: 0.2.0.0

AoCDailyLeaderboard :: Day -> AoC DailyLeaderboard

Fetch the daily leaderboard for a given day. Does not require a session key.

Leaderboard API calls tend to be expensive, so please be respectful when using this. If you automate this, please do not fetch any more often than necessary.

Cacheing rules: Will be cached if a full leaderboard is observed.

Since: 0.2.3.0

AoCGlobalLeaderboard :: AoC GlobalLeaderboard

Fetch the global leaderboard. Does not require a session key.

Leaderboard API calls tend to be expensive, so please be respectful when using this. If you automate this, please do not fetch any more often than necessary.

Cacheing rules: Will not cache if an event is ongoing, but will be cached if received after the event is over.

Since: 0.2.3.0

AoCNextDayTime :: AoC NextDayTime

From the calendar, fetch the next release's day and the number of seconds util its release, if there is any at all.

This does an actual request to the AoC servers, and is only accurate to the second; to infer this information (to the millisecond level) from the system clock, you should probably use timeToRelease and aocServerTime instead, which requires no network requests.

Since: 0.2.8.0

Instances

Show (AoC a)

Defined in Advent

Methods

showsPrec :: Int -> AoC a -> ShowS

show :: AoC a -> String

showList :: [AoC a] -> ShowS

data Part

A given part of a problem. All Advent of Code challenges are two-parts.

You can usually get Part1 (if it is already released) with a nonsense session key, but Part2 always requires a valid session key.

Constructors

Part1

Part2

Instances

Bounded Part

Defined in Advent.Types

Methods

minBound :: Part

maxBound :: Part

Enum Part

Defined in Advent.Types

Methods

succ :: Part -> Part

pred :: Part -> Part

toEnum :: Int -> Part

fromEnum :: Part -> Int

enumFrom :: Part -> [Part]

enumFromThen :: Part -> Part -> [Part]

enumFromTo :: Part -> Part -> [Part]

enumFromThenTo :: Part -> Part -> Part -> [Part]

Eq Part

Defined in Advent.Types

Methods

(==) :: Part -> Part -> Bool

(/=) :: Part -> Part -> Bool

Ord Part

Defined in Advent.Types

Methods

compare :: Part -> Part -> Ordering

(<) :: Part -> Part -> Bool

(<=) :: Part -> Part -> Bool

(>) :: Part -> Part -> Bool

(>=) :: Part -> Part -> Bool

max :: Part -> Part -> Part

min :: Part -> Part -> Part

Read Part

Defined in Advent.Types

Methods

readsPrec :: Int -> ReadS Part

readList :: ReadS [Part]

readPrec :: ReadPrec Part

readListPrec :: ReadPrec [Part]

Show Part

Defined in Advent.Types

Methods

showsPrec :: Int -> Part -> ShowS

show :: Part -> String

showList :: [Part] -> ShowS

Generic Part

Defined in Advent.Types

Associated Types

type Rep Part :: Type -> Type

Methods

from :: Part -> Rep Part x

to :: Rep Part x -> Part

ToJSON Part

Since: 0.2.4.2

Defined in Advent.Types

Methods

toJSON :: Part -> Value

toEncoding :: Part -> Encoding

toJSONList :: [Part] -> Value

toEncodingList :: [Part] -> Encoding

ToJSONKey Part

Since: 0.2.4.2

Defined in Advent.Types

Methods

toJSONKey :: ToJSONKeyFunction Part

toJSONKeyList :: ToJSONKeyFunction [Part]

FromJSON Part

Defined in Advent.Types

Methods

parseJSON :: Value -> Parser Part

parseJSONList :: Value -> Parser [Part]

FromJSONKey Part

Defined in Advent.Types

Methods

fromJSONKey :: FromJSONKeyFunction Part

fromJSONKeyList :: FromJSONKeyFunction [Part]

ToHttpApiData Part

Defined in Advent.Types

Methods

toUrlPiece :: Part -> Text

toEncodedUrlPiece :: Part -> Builder

toHeader :: Part -> ByteString

toQueryParam :: Part -> Text

type Rep Part

Defined in Advent.Types

type Rep Part = D1 ('MetaData "Part" "Advent.Types" "advent-of-code-api-0.2.8.0-inplace" 'False) (C1 ('MetaCons "Part1" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Part2" 'PrefixI 'False) (U1 :: Type -> Type))

newtype Day

Describes the day: a number between 1 and 25 inclusive.

Represented by a Finite ranging from 0 to 24 inclusive; you should probably make one using the smart constructor mkDay.

Constructors

Day

Fields

• dayFinite :: Finite 25

Instances

Bounded Day

Defined in Advent.Types

Methods

minBound :: Day

maxBound :: Day

Enum Day

Defined in Advent.Types

Methods

succ :: Day -> Day

pred :: Day -> Day

toEnum :: Int -> Day

fromEnum :: Day -> Int

enumFrom :: Day -> [Day]

enumFromThen :: Day -> Day -> [Day]

enumFromTo :: Day -> Day -> [Day]

enumFromThenTo :: Day -> Day -> Day -> [Day]

Eq Day

Defined in Advent.Types

Methods

(==) :: Day -> Day -> Bool

(/=) :: Day -> Day -> Bool

Ord Day

Defined in Advent.Types

Methods

compare :: Day -> Day -> Ordering

(<) :: Day -> Day -> Bool

(<=) :: Day -> Day -> Bool

(>) :: Day -> Day -> Bool

(>=) :: Day -> Day -> Bool

max :: Day -> Day -> Day

min :: Day -> Day -> Day

Show Day

Defined in Advent.Types

Methods

showsPrec :: Int -> Day -> ShowS

show :: Day -> String

showList :: [Day] -> ShowS

Generic Day

Defined in Advent.Types

Associated Types

type Rep Day :: Type -> Type

Methods

from :: Day -> Rep Day x

to :: Rep Day x -> Day

ToJSON Day

Since: 0.2.4.2

Defined in Advent.Types

Methods

toJSON :: Day -> Value

toEncoding :: Day -> Encoding

toJSONList :: [Day] -> Value

toEncodingList :: [Day] -> Encoding

ToJSONKey Day

Since: 0.2.4.2

Defined in Advent.Types

Methods

toJSONKey :: ToJSONKeyFunction Day

toJSONKeyList :: ToJSONKeyFunction [Day]

FromJSON Day

Defined in Advent.Types

Methods

parseJSON :: Value -> Parser Day

parseJSONList :: Value -> Parser [Day]

FromJSONKey Day

Defined in Advent.Types

Methods

fromJSONKey :: FromJSONKeyFunction Day

fromJSONKeyList :: FromJSONKeyFunction [Day]

ToHttpApiData Day

Defined in Advent.Types

Methods

toUrlPiece :: Day -> Text

toEncodedUrlPiece :: Day -> Builder

toHeader :: Day -> ByteString

toQueryParam :: Day -> Text

type Rep Day

Defined in Advent.Types

type Rep Day = D1 ('MetaData "Day" "Advent.Types" "advent-of-code-api-0.2.8.0-inplace" 'True) (C1 ('MetaCons "Day" 'PrefixI 'True) (S1 ('MetaSel ('Just "dayFinite") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Finite 25))))

data NextDayTime

The next day for a challenge in a given year, and also the number of seconds until the challenge is released.

Since: 0.2.8.0

Constructors

NextDayTime Day Int

NoNextDayTime

Instances

Eq NextDayTime

Defined in Advent.Types

Methods

(==) :: NextDayTime -> NextDayTime -> Bool

(/=) :: NextDayTime -> NextDayTime -> Bool

Ord NextDayTime

Defined in Advent.Types

Methods

compare :: NextDayTime -> NextDayTime -> Ordering

(<) :: NextDayTime -> NextDayTime -> Bool

(<=) :: NextDayTime -> NextDayTime -> Bool

(>) :: NextDayTime -> NextDayTime -> Bool

(>=) :: NextDayTime -> NextDayTime -> Bool

max :: NextDayTime -> NextDayTime -> NextDayTime

min :: NextDayTime -> NextDayTime -> NextDayTime

Show NextDayTime

Defined in Advent.Types

Methods

showsPrec :: Int -> NextDayTime -> ShowS

show :: NextDayTime -> String

showList :: [NextDayTime] -> ShowS

Generic NextDayTime

Defined in Advent.Types

Associated Types

type Rep NextDayTime :: Type -> Type

Methods

from :: NextDayTime -> Rep NextDayTime x

to :: Rep NextDayTime x -> NextDayTime

FromTags "script" NextDayTime

Defined in Advent.API

Methods

fromTags :: p "script" -> [Text] -> Maybe NextDayTime

type Rep NextDayTime

Defined in Advent.Types

type Rep NextDayTime = D1 ('MetaData "NextDayTime" "Advent.Types" "advent-of-code-api-0.2.8.0-inplace" 'False) (C1 ('MetaCons "NextDayTime" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Day) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int)) :+: C1 ('MetaCons "NoNextDayTime" 'PrefixI 'False) (U1 :: Type -> Type))

data AoCOpts

Setings for running an API request.

Session keys are required for all commands, but if you enter a bogus key you should be able to get at least Part 1 from AoCPrompt.

The session key can be found by logging in on a web client and checking the cookies. You can usually check these with in-browser developer tools.

Throttling is hard-limited to a minimum of 1 second between calls. Please be respectful and do not try to bypass this.

Constructors

AoCOpts

Fields

• _aSessionKey :: String

  Session key

• _aYear :: Integer

  Year of challenge

• _aCache :: Maybe FilePath

  Cache directory. If Nothing is given, one will be allocated using getTemporaryDirectory.

• _aForce :: Bool

  Fetch results even if cached. Still subject to throttling. Default is False.

• _aThrottle :: Int

  Throttle delay, in milliseconds. Minimum is 1000000. Default is 3000000 (3 seconds).

Instances

Show AoCOpts

Defined in Advent

Methods

showsPrec :: Int -> AoCOpts -> ShowS

show :: AoCOpts -> String

showList :: [AoCOpts] -> ShowS

Generic AoCOpts

Defined in Advent

Associated Types

type Rep AoCOpts :: Type -> Type

Methods

from :: AoCOpts -> Rep AoCOpts x

to :: Rep AoCOpts x -> AoCOpts

type Rep AoCOpts

Defined in Advent

type Rep AoCOpts = D1 ('MetaData "AoCOpts" "Advent" "advent-of-code-api-0.2.8.0-inplace" 'False) (C1 ('MetaCons "AoCOpts" 'PrefixI 'True) ((S1 ('MetaSel ('Just "_aSessionKey") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Just "_aYear") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Integer)) :*: (S1 ('MetaSel ('Just "_aCache") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe FilePath)) :*: (S1 ('MetaSel ('Just "_aForce") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool) :*: S1 ('MetaSel ('Just "_aThrottle") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int)))))

data SubmitRes

The result of a submission.

Constructors

SubCorrect (Maybe Integer)

Correct submission, including global rank (if reported, which usually happens if rank is under 1000)

SubIncorrect Int (Maybe String)

Incorrect submission. Contains the number of seconds you must wait before trying again. The Maybe contains possible hints given by the server (usually "too low" or "too high").

SubWait Int

Submission was rejected because an incorrect submission was recently submitted. Contains the number of seconds you must wait before trying again.

SubInvalid

Submission was rejected because it was sent to an invalid question or part. Usually happens if you submit to a part you have already answered or have not yet unlocked.

SubUnknown String

Could not parse server response. Contains parse error.

Instances

Eq SubmitRes

Defined in Advent.Types

Methods

(==) :: SubmitRes -> SubmitRes -> Bool

(/=) :: SubmitRes -> SubmitRes -> Bool

Ord SubmitRes

Defined in Advent.Types

Methods

compare :: SubmitRes -> SubmitRes -> Ordering

(<) :: SubmitRes -> SubmitRes -> Bool

(<=) :: SubmitRes -> SubmitRes -> Bool

(>) :: SubmitRes -> SubmitRes -> Bool

(>=) :: SubmitRes -> SubmitRes -> Bool

max :: SubmitRes -> SubmitRes -> SubmitRes

min :: SubmitRes -> SubmitRes -> SubmitRes

Read SubmitRes

Defined in Advent.Types

Methods

readsPrec :: Int -> ReadS SubmitRes

readList :: ReadS [SubmitRes]

readPrec :: ReadPrec SubmitRes

readListPrec :: ReadPrec [SubmitRes]

Show SubmitRes

Defined in Advent.Types

Methods

showsPrec :: Int -> SubmitRes -> ShowS

show :: SubmitRes -> String

showList :: [SubmitRes] -> ShowS

Generic SubmitRes

Defined in Advent.Types

Associated Types

type Rep SubmitRes :: Type -> Type

Methods

from :: SubmitRes -> Rep SubmitRes x

to :: Rep SubmitRes x -> SubmitRes

FromTags "article" SubmitRes

Defined in Advent.API

Methods

fromTags :: p "article" -> [Text] -> Maybe SubmitRes

type Rep SubmitRes

Defined in Advent.Types

type Rep SubmitRes = D1 ('MetaData "SubmitRes" "Advent.Types" "advent-of-code-api-0.2.8.0-inplace" 'False) ((C1 ('MetaCons "SubCorrect" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe Integer))) :+: C1 ('MetaCons "SubIncorrect" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe String)))) :+: (C1 ('MetaCons "SubWait" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int)) :+: (C1 ('MetaCons "SubInvalid" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "SubUnknown" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))))

showSubmitRes :: SubmitRes -> String

Pretty-print a SubmitRes

runAoC :: AoCOpts -> AoC a -> IO (Either AoCError a)

Run an AoC command with a given AoCOpts to produce the result or a list of (lines of) errors.

WARNING: Answers are not length-limited. Answers are stripped of leading and trailing whitespace and run through encode before submitting.

runAoC_ :: AoCOpts -> AoC a -> IO a

A version of runAoC that throws an IO exception (of type AoCError) upon failure, instead of an Either.

Since: 0.2.5.0

defaultAoCOpts :: Integer -> String -> AoCOpts

Sensible defaults for AoCOpts for a given year and session key.

Use system temporary directory as cache, and throttle requests to one request per three seconds.

data AoCError

A possible (syncronous, logical, pure) error returnable from runAoC. Does not cover any asynchronous or IO errors.

Constructors

AoCClientError ClientError

An error in the http request itself

Note that if you are building this with servant-client-core <= 0.16, this will contain ServantError instead of ClientError, which was the previous name of ths type.

AoCReleaseError NominalDiffTime

Tried to interact with a challenge that has not yet been released. Contains the amount of time until release.

AoCThrottleError

The throttler limit is full. Either make less requests, or adjust it with setAoCThrottleLimit.

Instances

Show AoCError

Defined in Advent

Methods

showsPrec :: Int -> AoCError -> ShowS

show :: AoCError -> String

showList :: [AoCError] -> ShowS

Generic AoCError

Defined in Advent

Associated Types

type Rep AoCError :: Type -> Type

Methods

from :: AoCError -> Rep AoCError x

to :: Rep AoCError x -> AoCError

Exception AoCError

Defined in Advent

Methods

toException :: AoCError -> SomeException

fromException :: SomeException -> Maybe AoCError

displayException :: AoCError -> String

type Rep AoCError

Defined in Advent

type Rep AoCError = D1 ('MetaData "AoCError" "Advent" "advent-of-code-api-0.2.8.0-inplace" 'False) (C1 ('MetaCons "AoCClientError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ClientError)) :+: (C1 ('MetaCons "AoCReleaseError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 NominalDiffTime)) :+: C1 ('MetaCons "AoCThrottleError" 'PrefixI 'False) (U1 :: Type -> Type)))

Calendar

challengeReleaseTime

Arguments

:: Integer

year

-> Day

day

-> ZonedTime

Prompt release time.

Changed from UTCTime to ZonedTime in v0.2.7.0. To use as a UTCTime, use zonedTimeToUTC.

timeToRelease

Arguments

:: Integer

year

-> Day

day

-> IO NominalDiffTime

Get time until release of a given challenge.

challengeReleased

Arguments

:: Integer

year

-> Day

day

-> IO Bool

Check if a challenge has been released yet.

Utility

Day

mkDay :: Integer -> Maybe Day

Construct a Day from a day integer (1 - 25). If input is out of range, Nothing is returned. See mkDay_ for an unsafe version useful for literals.

Inverse of dayInt.

mkDay_ :: Integer -> Day

Construct a Finite 25 (the type of a Day) from a day integer (1 - 25). Is undefined if input is out of range. Can be useful for compile-time literals, like mkDay_ 4

Inverse of dayInt.

dayInt :: Day -> Integer

Convert a Finite 25 day into a day integer (1 - 25). Inverse of mkDay.

pattern DayInt :: Day -> Integer

Pattern synonym allowing you to match on an Integer as if it were a Day:

case myInt of
  DayInt d -> ...
  _        -> ...

Will fail if the integer is out of bounds (outside of 1-25)

Since: 0.2.4.0

_DayInt :: (Choice p, Applicative f) => p Day (f Day) -> p Integer (f Integer)

This is a Prism' Integer Day , to treat an Integer as if it were a Day.

Since: 0.2.4.0

aocDay :: AoC a -> Maybe Day

Get the day associated with a given API command, if there is one.

aocServerTime :: IO LocalTime

Utility to get the current time on AoC servers. Basically just gets the current time in Eastern Standard Time. This is only as accurate as your machine's actual time --- it doesn't actually do anything networked.

Since: 0.2.6.0

Part

partChar :: Part -> Char

A character associated with a given part. Part1 is associated with 'a', and Part2 is associated with 'b'

partInt :: Part -> Int

Convert a Part to an Int.

Leaderboard

fullDailyBoard :: DailyLeaderboard -> Bool

Check if a DailyLeaderboard is filled up or not.

Since: 0.2.4.0

Throttler

setAoCThrottleLimit :: Int -> IO ()

Set the internal throttler maximum queue capacity. Default is 100.

getAoCThrottleLimit :: IO Int

Get the internal throttler maximum queue capacity.

Internal

aocReq :: Integer -> AoC a -> ClientM a

ClientM request for a given AoC API call.

aocBase :: BaseUrl

HTTPS base of Advent of Code API.