-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Advent of Code REST API bindings
--   
--   Haskell bindings for Advent of Code REST API. Please use responsibly!
--   See README.md or <a>Advent</a> module for an introduction and
--   tutorial.
--   
--   Requires libcurl.
@package advent-of-code-api
@version 0.1.2.3


-- | Haskell bindings for Advent of Code 2018 API. Caches and throttles
--   requests automatically.
--   
--   Specify your requests with <a>AoC</a> and <a>AoCOpts</a>, and run them
--   with <a>runAoC</a>.
--   
--   Examples:
--   
--   <pre>
--   -- Fetch prompts for day 5
--   <a>runAoC</a> myOpts $ <a>AoCPrompt</a> (<a>mkDay_</a> 5)
--   
--   -- Fetch input for day 8
--   <a>runAoC</a> myOpts $ <a>AoCInput</a> (<a>mkDay_</a> 8)
--   
--   -- Submit answer "hello" for Day 10, Part 1
--   <a>runAoC</a> myOpts $ <a>AoCSubmit</a> (<a>mkDay_</a> 10) <a>Part1</a> "hello"
--   </pre>
--   
--   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.
--   
--   Note that leaderboard API is not yet supported.
module Advent

-- | An API command. An <tt><a>AoC</a> a</tt> an AoC API request that
--   returns results of type <tt>a</tt>.
--   
--   A lot of these commands take <tt><a>Finite</a> 25</tt>, which
--   represents a day of December up to and including Christmas Day
--   (December 25th). You can convert an integer day (1 - 25) into a
--   <tt><a>Finite</a> 25</tt> representing that day using <a>mkDay</a> or
--   <a>mkDay_</a>.
data AoC :: Type -> Type

-- | Fetch prompts for a given day. Returns a <a>Map</a> of <a>Part</a>s
--   and their associated promps, as HTML.
[AoCPrompt] :: Finite 25 -> AoC (Map Part Text)

-- | Fetch input, as plaintext. Returned verbatim. Be aware that input
--   might contain trailing newlines.
[AoCInput] :: Finite 25 -> AoC Text

-- | Submit a plaintext answer (the <a>String</a>) to a given day and part.
--   Receive a server reponse (as HTML) and a response code
--   <a>SubmitRes</a>.
--   
--   <b>WARNING</b>: Answers are not length-limited. Answers are stripped
--   of leading and trailing whitespace and run through <a>encode</a>
--   before submitting.
[AoCSubmit] :: Finite 25 -> Part -> String -> AoC (Text, SubmitRes)

-- | A given part of a problem. All Advent of Code challenges are
--   two-parts.
--   
--   You can usually get <a>Part1</a> (if it is already released) with a
--   nonsense session key, but <a>Part2</a> always requires a valid session
--   key.
--   
--   Note also that Challenge #25 typically only has a single part.
data Part
Part1 :: Part
Part2 :: Part

-- | 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 <a>AoCPrompt</a>.
--   
--   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.
data AoCOpts
AoCOpts :: String -> Integer -> Maybe FilePath -> Bool -> Int -> [CurlOption] -> AoCOpts

-- | Session key
[_aSessionKey] :: AoCOpts -> String

-- | Year of challenge
[_aYear] :: AoCOpts -> Integer

-- | Cache directory. If <a>Nothing</a> is given, one will be allocated
--   using <a>getTemporaryDirectory</a>.
[_aCache] :: AoCOpts -> Maybe FilePath

-- | Fetch results even if cached. Still subject to throttling. Default is
--   False.
[_aForce] :: AoCOpts -> Bool

-- | Throttle delay, in milliseconds. Minimum is 1000000. Default is
--   3000000 (3 seconds).
[_aThrottle] :: AoCOpts -> Int

-- | (Low-level usage) Extra <a>CurlOption</a> options to feed to the
--   libcurl bindings. Meant for things like proxy options and custom SSL
--   certificates. You should normally not have to add anything here, since
--   the library manages cookies, request methods, etc. for you. Anything
--   other than tweaking low-level network options (like the ones mentioned
--   previously) will likely break everything. Default is <tt>[]</tt>.
[_aCurlOpts] :: AoCOpts -> [CurlOption]

-- | The result of a submission.
data SubmitRes

-- | Correct submission, including global rank (if reported, which usually
--   happens if rank is under 1000)
SubCorrect :: Maybe Integer -> SubmitRes

-- | Incorrect submission. Contains the number of <i>seconds</i> you must
--   wait before trying again. The <a>Maybe</a> contains possible hints
--   given by the server (usually "too low" or "too high").
SubIncorrect :: Int -> Maybe String -> SubmitRes

-- | Submission was rejected because an incorrect submission was recently
--   submitted. Contains the number of <i>seconds</i> you must wait before
--   trying again.
SubWait :: Int -> SubmitRes

-- | 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.
SubInvalid :: SubmitRes

-- | Could not parse server response. Contains parse error.
SubUnknown :: String -> SubmitRes

-- | Pretty-print a <a>SubmitRes</a>
showSubmitRes :: SubmitRes -> String

-- | Run an <a>AoC</a> command with a given <a>AoCOpts</a> to produce the
--   result or a list of (lines of) errors.
--   
--   <b>WARNING</b>: Answers are not length-limited. Answers are stripped
--   of leading and trailing whitespace and run through <a>encode</a>
--   before submitting.
runAoC :: AoCOpts -> AoC a -> IO (Either AoCError a)

-- | Sensible defaults for <a>AoCOpts</a> for a given year and session key.
--   
--   Use system temporary directory as cache, and throttle requests to one
--   request per three seconds.
defaultAoCOpts :: Integer -> String -> AoCOpts

-- | A possible (syncronous, logical, pure) error returnable from
--   <a>runAoC</a>. Does not cover any asynchronous or IO errors.
data AoCError

-- | A libcurl error, with response code and response body
AoCCurlError :: CurlCode -> String -> AoCError

-- | Tried to interact with a challenge that has not yet been released.
--   Contains the amount of time until release.
AoCReleaseError :: NominalDiffTime -> AoCError

-- | The throttler limit is full. Either make less requests, or adjust it
--   with <a>setAoCThrottleLimit</a>.
AoCThrottleError :: AoCError

-- | Prompt release time
challengeReleaseTime :: Integer -> Finite 25 -> UTCTime

-- | Get time until release of a given challenge.
timeToRelease :: Integer -> Finite 25 -> IO NominalDiffTime

-- | Check if a challenge has been released yet.
challengeReleased :: Integer -> Finite 25 -> IO Bool

-- | Construct a <tt><a>Finite</a> 25</tt> (the type of a Day) from a day
--   integer (1 - 25). If input is out of range, <a>Nothing</a> is
--   returned. See <a>mkDay_</a> for an unsafe version useful for literals.
--   
--   Inverse of <a>dayInt</a>.
mkDay :: Integer -> Maybe (Finite 25)

-- | Construct a <tt><a>Finite</a> 25</tt> (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 <tt><a>mkDay_</a> 4</tt>
--   
--   Inverse of <a>dayInt</a>.
mkDay_ :: Integer -> Finite 25

-- | Convert a <tt><a>Finite</a> 25</tt> day into a day integer (1 - 25).
--   Inverse of <a>mkDay</a>.
dayInt :: Finite 25 -> Integer

-- | Get the day associated with a given API command.
aocDay :: AoC a -> Finite 25

-- | A character associated with a given part. <a>Part1</a> is associated
--   with <tt>'a'</tt>, and <a>Part2</a> is associated with <tt>'b'</tt>
partChar :: Part -> Char

-- | Convert a <a>Part</a> to an <a>Int</a>.
partInt :: Part -> Int

-- | Set the internal throttler maximum queue capacity. Default is 100.
setAoCThrottleLimit :: Int -> IO ()

-- | Get the internal throttler maximum queue capacity.
getAoCThrottleLimit :: IO Int

-- | Parse <a>Text</a> into a <a>SubmitRes</a>.
parseSubmitRes :: Text -> SubmitRes

-- | Process an HTML webpage into a list of all contents in <a>article</a>s
processHTML :: String -> [Text]
instance GHC.Generics.Generic Advent.AoCOpts
instance GHC.Show.Show Advent.AoCOpts
instance GHC.Generics.Generic Advent.AoCError
instance GHC.Show.Show Advent.AoCError
instance GHC.Generics.Generic Advent.Part
instance GHC.Enum.Bounded Advent.Part
instance GHC.Enum.Enum Advent.Part
instance GHC.Classes.Ord Advent.Part
instance GHC.Classes.Eq Advent.Part
instance GHC.Read.Read Advent.Part
instance GHC.Show.Show Advent.Part
instance GHC.Generics.Generic Advent.SubmitRes
instance GHC.Classes.Ord Advent.SubmitRes
instance GHC.Classes.Eq Advent.SubmitRes
instance GHC.Read.Read Advent.SubmitRes
instance GHC.Show.Show Advent.SubmitRes
instance GHC.Show.Show (Advent.AoC a)
instance GHC.Exception.Type.Exception Advent.AoCError
