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


-- | Library for easily building REST API wrappers in Haskell
--   
@package api-builder
@version 0.7.0.1

module Network.API.Builder.Query
class ToQuery a
toQuery :: ToQuery a => Text -> a -> [(Text, Text)]
instance ToQuery a => ToQuery [a]
instance ToQuery a => ToQuery (Maybe a)
instance ToQuery Text
instance ToQuery Int
instance ToQuery Bool
instance ToQuery Integer

module Network.API.Builder.Routes

-- | Main type for routes in the API. Used to represent the URL minus the
--   actual endpoint URL as well as the query string and the HTTP method
--   used to communicate with the server.
data Route
Route :: [URLPiece] -> [URLParam] -> Method -> Route
urlPieces :: Route -> [URLPiece]
urlParams :: Route -> [URLParam]
httpMethod :: Route -> Method

-- | Alias for <tt>Text</tt> to store the URL fragments for each
--   <tt>Route</tt>.
type URLPiece = Text

-- | Alias to <tt>(Text, Maybe Text)</tt> used to store each query that
--   gets tacked onto the request.
type URLParam = [(Text, Text)]

-- | Convenience function for building <tt>URLParam</tt>s. Right-hand
--   argument must have a <tt>ToQuery</tt> instance so it can be converted
--   to the appropriate representation in a query string. Query values do
--   not need to be escaped.
--   
--   <pre>
--   &gt;&gt;&gt; "api_type" =. ("json" :: Text)
--   ("api_type", Just "json")
--   </pre>
(=.) :: ToQuery a => Text -> a -> [(Text, Text)]

-- | Converts a Route to a URL. Drops any <tt>Nothing</tt> values from the
--   query, separates the fragments with "/" and tacks them onto the end of
--   the base URL.
routeURL :: Text -> Route -> Text
instance Show Route
instance Read Route
instance Eq Route

module Network.API.Builder.Error

-- | Error type for the <tt>API</tt>, where <tt>a</tt> is the type that
--   should be returned when something goes wrong on the other end - i.e.
--   any error that isn't directly related to this library.
data APIError a

-- | A type that represents any error that happens on the API end. Define
--   your own custom type with a <tt>FromJSON</tt> instance if you want to
--   handle them, or you can use <tt>()</tt> if you just want to ignore
--   them all.
APIError :: a -> APIError a

-- | Something went wrong when we tried to do a HTTP operation.
HTTPError :: HttpException -> APIError a

-- | You're trying to create an invalid URL somewhere - check your
--   <tt>Builder</tt>'s base URL and your <tt>Route</tt>s.
InvalidURLError :: APIError a

-- | Failed when parsing the response, and it wasn't an error on their end.
ParseError :: String -> APIError a
instance Show a => Show (APIError a)
instance Eq a => Eq (APIError a)

module Network.API.Builder.Receive
class Receivable r
receive :: (Receivable r, ErrorReceivable e) => Response ByteString -> Either (APIError e) r
useFromJSON :: (FromJSON a, ErrorReceivable e) => Response ByteString -> Either (APIError e) a
class ErrorReceivable e
receiveError :: ErrorReceivable e => Response ByteString -> Maybe e
useErrorFromJSON :: FromJSON a => Response ByteString -> Maybe a
eitherDecode :: FromJSON a => ByteString -> Either String a
newtype JSONResponse a
JSONResponse :: a -> JSONResponse a
unwrapJSON :: JSONResponse a -> a
instance Show a => Show (JSONResponse a)
instance Read a => Read (JSONResponse a)
instance Eq a => Eq (JSONResponse a)
instance Ord a => Ord (JSONResponse a)
instance FromJSON a => Receivable (JSONResponse a)
instance FromJSON a => FromJSON (JSONResponse a)
instance ErrorReceivable Value
instance ErrorReceivable ()
instance ErrorReceivable ByteString
instance (Receivable a, Receivable b, Receivable c, Receivable d, Receivable e) => Receivable (a, b, c, d, e)
instance (Receivable a, Receivable b, Receivable c, Receivable d) => Receivable (a, b, c, d)
instance (Receivable a, Receivable b, Receivable c) => Receivable (a, b, c)
instance (Receivable a, Receivable b) => Receivable (a, b)
instance Receivable Value
instance Receivable (Response ByteString)
instance Receivable ByteString

module Network.API.Builder.Builder

-- | Builder type for the API. Keeps track of the API's name and base URL,
--   and how to modify Routes and Requests before they're run.
data Builder
Builder :: Text -> Text -> (Route -> Route) -> (Request -> Request) -> Builder
_name :: Builder -> Text
_baseURL :: Builder -> Text
_customizeRoute :: Builder -> Route -> Route
_customizeRequest :: Builder -> Request -> Request

-- | Makes a basic builder, i.e. one that simply has a name and base URL
--   and doesn't fiddle with Routes / Requests.
basicBuilder :: Text -> Text -> Builder
instance Show Builder

module Network.API.Builder.Send
class Sendable s
send :: Sendable s => Builder -> Route -> s -> Maybe Request
instance Sendable ByteString
instance Sendable Value
instance Sendable ()

module Network.API.Builder.Send.Multipart
data Multipart
Multipart :: [Part] -> Multipart
sendMultipart :: MonadIO m => Builder -> Route -> Multipart -> m (Maybe Request)
instance Show Multipart

module Network.API.Builder.API

-- | Main API type. <tt>s</tt> is the API's internal state, <tt>e</tt> is
--   the API's custom error type, and <tt>a</tt> is the result when the API
--   runs. Based on the <tt>APIT</tt> transformer.
type API s e a = APIT s e IO a

-- | Main API transformer type. <tt>s</tt> is the API's internal state,
--   <tt>e</tt> is the API's custom error type, and <tt>a</tt> is the
--   result when the API runs.
type APIT s e m a = EitherT (APIError e) (ReaderT Manager (StateT Builder (StateT s m))) a

-- | Runs an <tt>API</tt> by executing its transformer stack and dumping it
--   all into <tt>IO</tt>. Only returns the actual result.
execAPI :: MonadIO m => Builder -> s -> APIT s e m a -> m (Either (APIError e) a)

-- | Runs an <tt>API</tt> by executing its transformer stack and dumping it
--   all into <tt>IO</tt>. Returns the actual result as well as the final
--   states of the <tt>Builder</tt> and custom state <tt>s</tt>.
runAPI :: MonadIO m => Builder -> Manager -> s -> APIT s e m a -> m (Either (APIError e) a, Builder, s)

-- | Runs a <tt>Route</tt>. Infers the type to convert to from the JSON
--   with the <tt>a</tt> in <tt>API</tt>, and infers the error type from
--   <tt>e</tt>.
runRoute :: (Receivable a, ErrorReceivable e, MonadIO m) => Route -> APIT s e m a
sendRoute :: (MonadIO m, Sendable t, ErrorReceivable e, Receivable r) => t -> Route -> APIT s e m r

-- | Runs a <tt>Route</tt>, but only returns the response and does nothing
--   towards decoding the response.
routeResponse :: (MonadIO m, ErrorReceivable e) => Route -> APIT s e m (Response ByteString)

-- | Try to construct a <tt>Request</tt> from a <tt>Route</tt> (with the
--   help of the <tt>Builder</tt>). Returns <tt>Nothing</tt> if the URL is
--   invalid or there is another error with the <tt>Route</tt>.
routeRequest :: Builder -> Route -> Maybe Request

-- | Lifts an action that works on an <tt>API</tt> to an action that works
--   on an <tt>API</tt>. This function is provided solely for
--   future-proofing in the case that more transformers need to be stacked
--   on top - it's implemented simply as <tt>id</tt> for the moment.
liftEither :: Monad m => EitherT (APIError e) (ReaderT Manager (StateT Builder (StateT s m))) a -> APIT s e m a

-- | Lifts an action that works on a <tt>Manager</tt> to one that works on
--   an <tt>API</tt>.
liftManager :: Monad m => ReaderT Manager (StateT Builder (StateT s m)) a -> APIT s e m a

-- | Lifts an action that operates on a <tt>Builder</tt> to one that works
--   on an <tt>API</tt>. Useful mainly for gaining access to a
--   <tt>Builder</tt> from inside an <tt>API</tt>.
liftBuilder :: Monad m => StateT Builder (StateT s m) a -> APIT s e m a

-- | Lifts an action on an <tt>API</tt>'s state type <tt>s</tt> to one that
--   works on the <tt>API</tt>. Good for messing with the state from inside
--   the <tt>API</tt>.
liftState :: Monad m => StateT s m a -> APIT s e m a

-- | Modify the <tt>name</tt> of the <tt>Builder</tt> from inside an API.
--   Using this is probably not the best idea, it's nice if the
--   <tt>Builder</tt>'s name is stable at least.
name :: Monad m => Text -> APIT s e m ()

-- | Modify the <tt>baseURL</tt> of the <tt>Builder</tt> from inside an
--   API. Can be useful for changing the API's endpoints for certain
--   requests.
baseURL :: Monad m => Text -> APIT s e m ()

-- | Modify every <tt>Route</tt> before it runs. Useful for adding extra
--   params to every query, for example.
customizeRoute :: Monad m => (Route -> Route) -> APIT s e m ()

-- | Modify every <tt>Request</tt> before the API fetches it. Useful for
--   adding headers to every request, for example.
customizeRequest :: Monad m => (Request -> Request) -> APIT s e m ()


-- | Entirely re-exports.
module Network.API.Builder


-- | Defines a basic example of API use - check the readme for more detail
--   or check the tutorial at
--   <a>https://github.com/intolerable/api-builder</a>
module Network.API.Builder.Examples.StackOverflow
data Question
Question :: Text -> Bool -> Int -> [Text] -> Question
title :: Question -> Text
isAnswered :: Question -> Bool
score :: Question -> Int
tags :: Question -> [Text]
newtype Questions
Questions :: [Question] -> Questions
stackOverflow :: Builder
answersRoute :: Route
getAnswers :: IO (Either (APIError ()) Questions)
instance Show Question
instance Eq Question
instance Show Questions
instance Eq Questions
instance Receivable Questions
instance FromJSON Questions
instance FromJSON Question