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


-- | Query the GitHub REST API programmatically
--   
--   Query the GitHub REST API programmatically, which can provide a more
--   flexible and clear interface than if all of the endpoints and their
--   types were defined as Haskell values.
@package github-rest
@version 1.2.0


-- | Definitions for handling authentication with the GitHub REST API.
module GitHub.REST.Auth

-- | The token to use to authenticate with GitHub.
data Token

-- | <a>https://developer.github.com/v3/#authentication</a>
AccessToken :: ByteString -> Token

-- | 
--   <a>https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app</a>
BearerToken :: ByteString -> Token
fromToken :: Token -> ByteString

-- | Create a JWT token that expires in 10 minutes.
getJWTToken :: PrivateKey -> AppId -> IO Token
instance GHC.Show.Show GitHub.REST.Auth.Token
instance GHC.Exception.Type.Exception GitHub.REST.Auth.JwtError
instance GHC.Show.Show GitHub.REST.Auth.JwtError


-- | Define the <a>KeyValue</a> helper type.
module GitHub.REST.KeyValue

-- | A type representing a key-value pair.
data KeyValue
[:=] :: (Show v, ToJSON v) => Text -> v -> KeyValue
infixr 1 :=

-- | Convert the given KeyValues into a JSON Object.
kvToValue :: [KeyValue] -> Value

-- | Represent the given KeyValue as a pair of Texts.
kvToText :: KeyValue -> (Text, Text)
instance GHC.Show.Show GitHub.REST.KeyValue.KeyValue
instance Data.Aeson.Types.ToJSON.ToJSON [GitHub.REST.KeyValue.KeyValue]


-- | Define the <a>GHEndpoint</a> helper type for defining a call to a
--   GitHub API endpoint.
module GitHub.REST.Endpoint

-- | A call to a GitHub API endpoint.
data GHEndpoint
GHEndpoint :: StdMethod -> Text -> EndpointVals -> GitHubData -> GHEndpoint
[method] :: GHEndpoint -> StdMethod

-- | The GitHub API endpoint, with colon-prefixed components that will be
--   replaced; e.g. <tt>"/users/:username/repos"</tt>
[endpoint] :: GHEndpoint -> Text

-- | Key-value pairs to replace colon-prefixed components in
--   <a>endpoint</a>; e.g. <tt>[ "username" := ("alice" :: Text) ]</tt>
[endpointVals] :: GHEndpoint -> EndpointVals

-- | Key-value pairs to send in the request body; e.g. <tt>[ "sort" :=
--   ("created" :: Text), "direction" := ("asc" :: Text) ]</tt>
[ghData] :: GHEndpoint -> GitHubData
type EndpointVals = [KeyValue]
type GitHubData = [KeyValue]

-- | Return the endpoint path, populated by the values in
--   <a>endpointVals</a>.
endpointPath :: GHEndpoint -> Text

-- | Render the method of the endpoint.
renderMethod :: GHEndpoint -> Method

module GitHub.REST.PageLinks

-- | Helper type for GitHub pagination.
--   
--   
--   <a>https://developer.github.com/v3/guides/traversing-with-pagination/</a>
data PageLinks
PageLinks :: Maybe Text -> Maybe Text -> Maybe Text -> Maybe Text -> PageLinks
[pageFirst] :: PageLinks -> Maybe Text
[pagePrev] :: PageLinks -> Maybe Text
[pageNext] :: PageLinks -> Maybe Text
[pageLast] :: PageLinks -> Maybe Text
parsePageLinks :: Text -> PageLinks
instance GHC.Show.Show GitHub.REST.PageLinks.PageLinks
instance GHC.Classes.Eq GitHub.REST.PageLinks.PageLinks
instance GHC.Base.Semigroup GitHub.REST.PageLinks.PageLinks
instance GHC.Base.Monoid GitHub.REST.PageLinks.PageLinks


-- | Defines <a>MonadGitHubREST</a> that gives a monad <tt>m</tt> the
--   capability to query the GitHub REST API.
module GitHub.REST.Monad.Class

-- | A type class for monads that can query the GitHub REST API.
--   
--   Example:
--   
--   <pre>
--   -- create the "foo" branch
--   queryGitHub GHEndpoint
--     { method = POST
--     , endpoint = "/repos/:owner/:repo/git/refs"
--     , endpointVals =
--       [ "owner" := "alice"
--       , "repo" := "my-project"
--       ]
--     , ghData =
--       [ "ref" := "refs/heads/foo"
--       , "sha" := "1234567890abcdef"
--       ]
--     }
--   </pre>
--   
--   It's recommended that you create functions for the API endpoints
--   you're using:
--   
--   <pre>
--   deleteBranch branch = queryGitHub GHEndpoint
--     { method = DELETE
--     , endpoint = "/repos/:owner/:repo/git/refs/:ref"
--     , endpointVals =
--       [ "owner" := "alice"
--       , "repo" := "my-project"
--       , "ref" := "heads/" &lt;&gt; branch
--       ]
--     , ghData = []
--     }
--   </pre>
class (Monad m) => MonadGitHubREST m

-- | Query GitHub, returning <tt>(payload, links)</tt> if successful, where
--   <tt>payload</tt> is the response that GitHub sent back and
--   <tt>links</tt> containing any pagination links GitHub may have sent
--   back. If the response could not be decoded as JSON, returns <tt>Left
--   (error message, response from server)</tt>.
--   
--   Errors on network connection failures, if GitHub sent back an error
--   message, or if the response could not be decoded as JSON. Use
--   <tt>githubTry</tt> if you wish to handle GitHub errors.
queryGitHubPage :: (MonadGitHubREST m, FromJSON a) => GHEndpoint -> m (a, PageLinks)

-- | <a>queryGitHubPage</a>, except ignoring pagination links.
queryGitHub :: (MonadGitHubREST m, FromJSON a) => GHEndpoint -> m a

-- | Repeatedly calls <a>queryGitHubPage</a> for each page returned by
--   GitHub and concatenates the results.
queryGitHubAll :: (MonadGitHubREST m, FromJSON a, Monoid a) => GHEndpoint -> m a

-- | <a>queryGitHub</a>, except ignores the result.
queryGitHub_ :: MonadGitHubREST m => GHEndpoint -> m ()
instance GitHub.REST.Monad.Class.MonadGitHubREST m => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.Reader.ReaderT r m)
instance GitHub.REST.Monad.Class.MonadGitHubREST m => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.Except.ExceptT e m)
instance GitHub.REST.Monad.Class.MonadGitHubREST m => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.Identity.IdentityT m)
instance GitHub.REST.Monad.Class.MonadGitHubREST m => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.Maybe.MaybeT m)
instance (GHC.Base.Monoid w, GitHub.REST.Monad.Class.MonadGitHubREST m) => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, GitHub.REST.Monad.Class.MonadGitHubREST m) => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance GitHub.REST.Monad.Class.MonadGitHubREST m => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.State.Lazy.StateT s m)
instance GitHub.REST.Monad.Class.MonadGitHubREST m => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, GitHub.REST.Monad.Class.MonadGitHubREST m) => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, GitHub.REST.Monad.Class.MonadGitHubREST m) => GitHub.REST.Monad.Class.MonadGitHubREST (Control.Monad.Trans.Writer.Strict.WriterT w m)


-- | Defines <a>GitHubT</a> and <a>MonadGitHubREST</a>, a monad transformer
--   and type class that gives a monad <tt>m</tt> the capability to query
--   the GitHub REST API.
module GitHub.REST.Monad

-- | A type class for monads that can query the GitHub REST API.
--   
--   Example:
--   
--   <pre>
--   -- create the "foo" branch
--   queryGitHub GHEndpoint
--     { method = POST
--     , endpoint = "/repos/:owner/:repo/git/refs"
--     , endpointVals =
--       [ "owner" := "alice"
--       , "repo" := "my-project"
--       ]
--     , ghData =
--       [ "ref" := "refs/heads/foo"
--       , "sha" := "1234567890abcdef"
--       ]
--     }
--   </pre>
--   
--   It's recommended that you create functions for the API endpoints
--   you're using:
--   
--   <pre>
--   deleteBranch branch = queryGitHub GHEndpoint
--     { method = DELETE
--     , endpoint = "/repos/:owner/:repo/git/refs/:ref"
--     , endpointVals =
--       [ "owner" := "alice"
--       , "repo" := "my-project"
--       , "ref" := "heads/" &lt;&gt; branch
--       ]
--     , ghData = []
--     }
--   </pre>
class (Monad m) => MonadGitHubREST m

-- | Query GitHub, returning <tt>(payload, links)</tt> if successful, where
--   <tt>payload</tt> is the response that GitHub sent back and
--   <tt>links</tt> containing any pagination links GitHub may have sent
--   back. If the response could not be decoded as JSON, returns <tt>Left
--   (error message, response from server)</tt>.
--   
--   Errors on network connection failures, if GitHub sent back an error
--   message, or if the response could not be decoded as JSON. Use
--   <tt>githubTry</tt> if you wish to handle GitHub errors.
queryGitHubPage :: (MonadGitHubREST m, FromJSON a) => GHEndpoint -> m (a, PageLinks)

-- | <a>queryGitHubPage</a>, except ignoring pagination links.
queryGitHub :: (MonadGitHubREST m, FromJSON a) => GHEndpoint -> m a

-- | Repeatedly calls <a>queryGitHubPage</a> for each page returned by
--   GitHub and concatenates the results.
queryGitHubAll :: (MonadGitHubREST m, FromJSON a, Monoid a) => GHEndpoint -> m a

-- | <a>queryGitHub</a>, except ignores the result.
queryGitHub_ :: MonadGitHubREST m => GHEndpoint -> m ()

-- | Same as <a>queryGitHubPage</a>, except explicitly taking in
--   <a>GitHubManager</a> and running in IO.
--   
--   Useful for implementing <a>MonadGitHubREST</a> outside of
--   <a>GitHubT</a>.
queryGitHubPageIO :: FromJSON a => GitHubManager -> GHEndpoint -> IO (a, PageLinks)
data GitHubManager

-- | Initialize a <a>GitHubManager</a>.
initGitHubManager :: GitHubSettings -> IO GitHubManager
data GitHubSettings
GitHubSettings :: Maybe Token -> ByteString -> ByteString -> GitHubSettings

-- | The token to use to authenticate with the API.
[$sel:token:GitHubSettings] :: GitHubSettings -> Maybe Token

-- | The user agent to use when interacting with the API:
--   <a>https://developer.github.com/v3/#user-agent-required</a>
[$sel:userAgent:GitHubSettings] :: GitHubSettings -> ByteString

-- | The <a>version of the GitHub REST API</a> being used. If left empty,
--   GitHub will assume a default version.
[$sel:apiVersion:GitHubSettings] :: GitHubSettings -> ByteString

-- | A simple monad that can run REST calls.
data GitHubT m a

-- | Run the given <a>GitHubT</a> action with the given token and user
--   agent.
--   
--   The token will be sent with each API request -- see <a>Token</a>. The
--   user agent is also required for each API request -- see
--   <a>https://developer.github.com/v3/#user-agent-required</a>.
runGitHubT :: MonadIO m => GitHubSettings -> GitHubT m a -> m a
instance GHC.Show.Show GitHub.REST.Monad.DecodeError
instance Control.Monad.Trans.Class.MonadTrans GitHub.REST.Monad.GitHubT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (GitHub.REST.Monad.GitHubT m)
instance Control.Monad.Fail.MonadFail m => Control.Monad.Fail.MonadFail (GitHub.REST.Monad.GitHubT m)
instance GHC.Base.Monad m => GHC.Base.Monad (GitHub.REST.Monad.GitHubT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (GitHub.REST.Monad.GitHubT m)
instance GHC.Base.Functor m => GHC.Base.Functor (GitHub.REST.Monad.GitHubT m)
instance Control.Monad.IO.Unlift.MonadUnliftIO m => Control.Monad.IO.Unlift.MonadUnliftIO (GitHub.REST.Monad.GitHubT m)
instance Control.Monad.IO.Class.MonadIO m => GitHub.REST.Monad.Class.MonadGitHubREST (GitHub.REST.Monad.GitHubT m)
instance GHC.Exception.Type.Exception GitHub.REST.Monad.DecodeError


-- | Definitions for querying the GitHub REST API. See README.md for an
--   example.
module GitHub.REST

-- | A type class for monads that can query the GitHub REST API.
--   
--   Example:
--   
--   <pre>
--   -- create the "foo" branch
--   queryGitHub GHEndpoint
--     { method = POST
--     , endpoint = "/repos/:owner/:repo/git/refs"
--     , endpointVals =
--       [ "owner" := "alice"
--       , "repo" := "my-project"
--       ]
--     , ghData =
--       [ "ref" := "refs/heads/foo"
--       , "sha" := "1234567890abcdef"
--       ]
--     }
--   </pre>
--   
--   It's recommended that you create functions for the API endpoints
--   you're using:
--   
--   <pre>
--   deleteBranch branch = queryGitHub GHEndpoint
--     { method = DELETE
--     , endpoint = "/repos/:owner/:repo/git/refs/:ref"
--     , endpointVals =
--       [ "owner" := "alice"
--       , "repo" := "my-project"
--       , "ref" := "heads/" &lt;&gt; branch
--       ]
--     , ghData = []
--     }
--   </pre>
class (Monad m) => MonadGitHubREST m

-- | Query GitHub, returning <tt>(payload, links)</tt> if successful, where
--   <tt>payload</tt> is the response that GitHub sent back and
--   <tt>links</tt> containing any pagination links GitHub may have sent
--   back. If the response could not be decoded as JSON, returns <tt>Left
--   (error message, response from server)</tt>.
--   
--   Errors on network connection failures, if GitHub sent back an error
--   message, or if the response could not be decoded as JSON. Use
--   <tt>githubTry</tt> if you wish to handle GitHub errors.
queryGitHubPage :: (MonadGitHubREST m, FromJSON a) => GHEndpoint -> m (a, PageLinks)

-- | <a>queryGitHubPage</a>, except ignoring pagination links.
queryGitHub :: (MonadGitHubREST m, FromJSON a) => GHEndpoint -> m a

-- | Repeatedly calls <a>queryGitHubPage</a> for each page returned by
--   GitHub and concatenates the results.
queryGitHubAll :: (MonadGitHubREST m, FromJSON a, Monoid a) => GHEndpoint -> m a

-- | <a>queryGitHub</a>, except ignores the result.
queryGitHub_ :: MonadGitHubREST m => GHEndpoint -> m ()

-- | A simple monad that can run REST calls.
data GitHubT m a
data GitHubSettings
GitHubSettings :: Maybe Token -> ByteString -> ByteString -> GitHubSettings

-- | The token to use to authenticate with the API.
[$sel:token:GitHubSettings] :: GitHubSettings -> Maybe Token

-- | The user agent to use when interacting with the API:
--   <a>https://developer.github.com/v3/#user-agent-required</a>
[$sel:userAgent:GitHubSettings] :: GitHubSettings -> ByteString

-- | The <a>version of the GitHub REST API</a> being used. If left empty,
--   GitHub will assume a default version.
[$sel:apiVersion:GitHubSettings] :: GitHubSettings -> ByteString

-- | Run the given <a>GitHubT</a> action with the given token and user
--   agent.
--   
--   The token will be sent with each API request -- see <a>Token</a>. The
--   user agent is also required for each API request -- see
--   <a>https://developer.github.com/v3/#user-agent-required</a>.
runGitHubT :: MonadIO m => GitHubSettings -> GitHubT m a -> m a

-- | The token to use to authenticate with GitHub.
data Token

-- | <a>https://developer.github.com/v3/#authentication</a>
AccessToken :: ByteString -> Token

-- | 
--   <a>https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app</a>
BearerToken :: ByteString -> Token

-- | A call to a GitHub API endpoint.
data GHEndpoint
GHEndpoint :: StdMethod -> Text -> EndpointVals -> GitHubData -> GHEndpoint
[method] :: GHEndpoint -> StdMethod

-- | The GitHub API endpoint, with colon-prefixed components that will be
--   replaced; e.g. <tt>"/users/:username/repos"</tt>
[endpoint] :: GHEndpoint -> Text

-- | Key-value pairs to replace colon-prefixed components in
--   <a>endpoint</a>; e.g. <tt>[ "username" := ("alice" :: Text) ]</tt>
[endpointVals] :: GHEndpoint -> EndpointVals

-- | Key-value pairs to send in the request body; e.g. <tt>[ "sort" :=
--   ("created" :: Text), "direction" := ("asc" :: Text) ]</tt>
[ghData] :: GHEndpoint -> GitHubData
type GitHubData = [KeyValue]
type EndpointVals = [KeyValue]

-- | A type representing a key-value pair.
data KeyValue
[:=] :: (Show v, ToJSON v) => Text -> v -> KeyValue
infixr 1 :=

-- | Handle 422 exceptions thrown by the GitHub REST API.
--   
--   Most client errors are 422, since we should always be sending valid
--   JSON. If an endpoint throws different error codes, use githubTry'.
--   
--   <a>https://developer.github.com/v3/#client-errors</a>
githubTry :: MonadUnliftIO m => m a -> m (Either Value a)

-- | Handle the given exception thrown by the GitHub REST API.
githubTry' :: MonadUnliftIO m => Status -> m a -> m (Either Value a)

-- | Get the given key from the Value, erroring if it doesn't exist.
(.:) :: FromJSON a => Value -> Text -> a

-- | HTTP standard method (as defined by RFC 2616, and PATCH which is
--   defined by RFC 5789).
data () => StdMethod
GET :: StdMethod
POST :: StdMethod
HEAD :: StdMethod
PUT :: StdMethod
DELETE :: StdMethod
TRACE :: StdMethod
CONNECT :: StdMethod
OPTIONS :: StdMethod

PATCH :: StdMethod