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


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

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

-- | Empty error to serve as a zero element for Monoid.
EmptyError :: APIError a
instance GHC.Show.Show a => GHC.Show.Show (Network.API.Builder.Error.APIError a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Network.API.Builder.Error.APIError a)
instance GHC.Base.Monoid (Network.API.Builder.Error.APIError a)

module Network.API.Builder.Query
class ToQuery a
toQuery :: ToQuery a => Text -> a -> [(Text, Text)]
instance Network.API.Builder.Query.ToQuery GHC.Integer.Type.Integer
instance Network.API.Builder.Query.ToQuery GHC.Types.Bool
instance Network.API.Builder.Query.ToQuery GHC.Types.Int
instance Network.API.Builder.Query.ToQuery Data.Text.Internal.Text
instance Network.API.Builder.Query.ToQuery a => Network.API.Builder.Query.ToQuery (GHC.Base.Maybe a)
instance Network.API.Builder.Query.ToQuery a => Network.API.Builder.Query.ToQuery [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
newtype JSONResponse a
JSONResponse :: a -> JSONResponse a
[unwrapJSON] :: JSONResponse a -> a
instance GHC.Classes.Ord a => GHC.Classes.Ord (Network.API.Builder.Receive.JSONResponse a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Network.API.Builder.Receive.JSONResponse a)
instance GHC.Read.Read a => GHC.Read.Read (Network.API.Builder.Receive.JSONResponse a)
instance GHC.Show.Show a => GHC.Show.Show (Network.API.Builder.Receive.JSONResponse a)
instance Data.Aeson.Types.FromJSON.FromJSON a => Data.Aeson.Types.FromJSON.FromJSON (Network.API.Builder.Receive.JSONResponse a)
instance Data.Aeson.Types.FromJSON.FromJSON a => Network.API.Builder.Receive.Receivable (Network.API.Builder.Receive.JSONResponse a)
instance Network.API.Builder.Receive.Receivable Data.ByteString.Lazy.Internal.ByteString
instance Network.API.Builder.Receive.Receivable (Network.HTTP.Client.Types.Response Data.ByteString.Lazy.Internal.ByteString)
instance Network.API.Builder.Receive.Receivable Data.Aeson.Types.Internal.Value
instance (Network.API.Builder.Receive.Receivable a, Network.API.Builder.Receive.Receivable b) => Network.API.Builder.Receive.Receivable (a, b)
instance (Network.API.Builder.Receive.Receivable a, Network.API.Builder.Receive.Receivable b, Network.API.Builder.Receive.Receivable c) => Network.API.Builder.Receive.Receivable (a, b, c)
instance (Network.API.Builder.Receive.Receivable a, Network.API.Builder.Receive.Receivable b, Network.API.Builder.Receive.Receivable c, Network.API.Builder.Receive.Receivable d) => Network.API.Builder.Receive.Receivable (a, b, c, d)
instance (Network.API.Builder.Receive.Receivable a, Network.API.Builder.Receive.Receivable b, Network.API.Builder.Receive.Receivable c, Network.API.Builder.Receive.Receivable d, Network.API.Builder.Receive.Receivable e) => Network.API.Builder.Receive.Receivable (a, b, c, d, e)
instance Network.API.Builder.Receive.ErrorReceivable Data.ByteString.Lazy.Internal.ByteString
instance Network.API.Builder.Receive.ErrorReceivable ()
instance Network.API.Builder.Receive.ErrorReceivable Data.Aeson.Types.Internal.Value

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 GHC.Classes.Eq Network.API.Builder.Routes.Route
instance GHC.Read.Read Network.API.Builder.Routes.Route
instance GHC.Show.Show Network.API.Builder.Routes.Route

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 GHC.Show.Show Network.API.Builder.Builder.Builder

module Network.API.Builder.Send

-- | Class for types that can be sent with api-builder. Given a
--   <a>Builder</a>, a <a>Route</a>, and an instance of <a>Sendable</a>, we
--   should be able to construct a <a>Request</a> for the API's server. If
--   we can't, <a>send</a> returns <a>Nothing</a> and <tt>APIT</tt>
--   complains about being unable to send the given data.
class Sendable s
send :: Sendable s => Builder -> Route -> s -> Maybe Request
basicSend :: Builder -> Route -> Maybe Request
useToJSON :: ToJSON a => Builder -> Route -> a -> Maybe Request

-- | By default, the '()' instance for <a>Sendable</a> moves the query
--   parameters of the <a>Route</a> into the body of the POST request. Most
--   APIs handle both, but some will complain if they aren't sent in the
--   actual query. If you <a>send</a> <a>PostQuery</a> instead of '()', the
--   query params won't move from the actual query string when constructing
--   the request.
data PostQuery
PostQuery :: PostQuery
instance GHC.Show.Show Network.API.Builder.Send.PostQuery
instance Network.API.Builder.Send.Sendable Network.API.Builder.Send.PostQuery
instance Network.API.Builder.Send.Sendable ()
instance Network.API.Builder.Send.Sendable Data.Aeson.Types.Internal.Value
instance Network.API.Builder.Send.Sendable Data.ByteString.Lazy.Internal.ByteString

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 = ExceptT (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.
liftExcept :: Monad m => ExceptT (APIError e) (ReaderT Manager (StateT Builder (StateT s m))) a -> APIT s e m a

-- | Identical to <a>liftExcept</a>, provided for (almost) compatibility.

-- | <i>Deprecated: Use liftExcept</i>
liftEither :: Monad m => ExceptT (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
stackOverflowSSL :: Builder
answersRoute :: Route
getAnswers :: IO (Either (APIError ()) Questions)
getAnswersSSL :: IO (Either (APIError ()) Questions)
instance GHC.Classes.Eq Network.API.Builder.Examples.StackOverflow.Questions
instance GHC.Show.Show Network.API.Builder.Examples.StackOverflow.Questions
instance GHC.Classes.Eq Network.API.Builder.Examples.StackOverflow.Question
instance GHC.Show.Show Network.API.Builder.Examples.StackOverflow.Question
instance Data.Aeson.Types.FromJSON.FromJSON Network.API.Builder.Examples.StackOverflow.Questions
instance Network.API.Builder.Receive.Receivable Network.API.Builder.Examples.StackOverflow.Questions
instance Data.Aeson.Types.FromJSON.FromJSON Network.API.Builder.Examples.StackOverflow.Question

module Network.API.Builder.Send.Multipart

-- | Send a <a>Multipart</a> request. This can't use the normal <a>send</a>
--   mechanism since it has to do IO to construct its request.
sendMultipart :: MonadIO m => Builder -> Route -> Multipart -> m (Maybe Request)

-- | A type for multipart forms, which uses <a>Part</a>s from
--   <a>MultipartFormData</a>. Construct it and send it with
--   <a>sendMultipart</a> (not <a>send</a>).
data Multipart
Multipart :: [Part] -> Multipart
instance GHC.Show.Show Network.API.Builder.Send.Multipart.Multipart