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


-- | Extensible interface to Web APIs
--   
--   <a>goggles</a> helps with exchanging data with APIs that require
--   authentication. In particular, it handles the details of expiring
--   session tokens, so the user does not have to implement this logic in
--   her program.
@package goggles
@version 0.3

module Network.Goggles.Auth

-- | send a POST request over HTTPS to a given URI that will return a
--   OAuth2Token
requestOAuth2Token :: (MonadHttp m, MonadThrow m) => Url scheme -> [(Text, Text)] -> Option scheme -> m OAuth2Token
data OAuth2Token
OAuth2Token :: Int -> Text -> Maybe Text -> OAuth2Token
[oaTokenExpirySeconds] :: OAuth2Token -> Int
[oaTokenString] :: OAuth2Token -> Text
[oaTokenType] :: OAuth2Token -> Maybe Text
data OAuth2TokenUTC
OAuth2TokenUTC :: UTCTime -> Text -> Maybe Text -> OAuth2TokenUTC
[oauTokenExpiry] :: OAuth2TokenUTC -> UTCTime
[oauTokenString] :: OAuth2TokenUTC -> Text
[oauTokenType] :: OAuth2TokenUTC -> Maybe Text
mkOAuth2TokenUTC :: (MonadIO m, Integral t) => t -> OAuth2Token -> m OAuth2TokenUTC


module Network.Goggles

-- | Create a <a>Handle</a> with an empty token
createHandle :: HasCredentials c => Credentials c -> Options c -> IO (Handle c)

-- | Evaluate a <a>WebApiM</a> action, given a <a>Handle</a>.
--   
--   NB : Assumes all exceptions are handled by <a>throwM</a>
evalWebApiIO :: Handle c -> WebApiM c a -> IO a

-- | Lift an `IO a` action into the <a>WebApiM</a> monad, and catch
--   synchronous exceptions, while rethrowing the asynchronous ones to IO
liftWebApiIO :: IO a -> WebApiM c a

-- | The main type of the library. It can easily be re-used in libraries
--   that interface with more than one cloud API provider because its type
--   parameter <tt>c</tt> lets us be declare distinct behaviours for each.
newtype WebApiM c a
WebApiM :: ReaderT (Handle c) IO a -> WebApiM c a
[runWebApiM] :: WebApiM c a -> ReaderT (Handle c) IO a
class HasCredentials c where {
    type family Credentials c;
}
class HasToken c where {
    type family TokenContent c;
    type family Options c;
}
tokenFetch :: HasToken c => WebApiM c (Token c)

-- | An authentication <a>Token</a> with an expiry date
data Token c
Token :: TokenContent c -> UTCTime -> Token c
[tToken] :: Token c -> TokenContent c
[tTime] :: Token c -> UTCTime

-- | Extract the token content (needed to authenticate subsequent
--   requests). The token will be valid for at least 60 seconds
accessToken :: (HasToken c) => WebApiM c (TokenContent c)
refreshToken :: HasToken c => WebApiM c (Token c)

-- | A <a>Handle</a> contains all information necessary to communicating
--   with a cloud API provider:
--   
--   <ul>
--   <li>Authentication credentials (e.g. username/password)</li>
--   <li>Authentication token (used to authenticate every API call)</li>
--   <li>Options (e.g. GCP authentication scopes)</li>
--   </ul>
data Handle c
Handle :: Credentials c -> TVar (Maybe (Token c)) -> Options c -> Handle c
[credentials] :: Handle c -> Credentials c
[token] :: Handle c -> TVar (Maybe (Token c))
[options] :: Handle c -> Options c

-- | Parse a chunk of text into an RSA private key. For Google Cloud
--   Platform , this is the private key associated with the user's "service
--   account" (for server-to-server API use)
--   
--   <pre>
--   https://console.cloud.google.com/apis/credentials
--   </pre>
--   
--   Note: do <i>not</i> supply the RSA header and footer or any newlines
--   (they will be inserted by this function).
parseRSAPrivateKey :: MonadThrow m => Text -> m PrivateKey
data OAuth2Token
OAuth2Token :: Int -> Text -> Maybe Text -> OAuth2Token
[oaTokenExpirySeconds] :: OAuth2Token -> Int
[oaTokenString] :: OAuth2Token -> Text
[oaTokenType] :: OAuth2Token -> Maybe Text

-- | Authentication key exceptions
data KeyException
NoSecretFound :: !String -> KeyException
NoParsePK :: !String -> KeyException
NoRSAKey :: !String -> KeyException

-- | Errors associated with JWT-encoded token request
data JWTError
BadExpirationTime :: !String -> JWTError
CryptoSignError :: !String -> JWTError

-- | Token exchange exceptions
data TokenExchangeException

-- | Something went wrong with the request, token not found
NotFound :: !String -> TokenExchangeException
APICredentialsNotFound :: !String -> TokenExchangeException

-- | Cloud API exception
data CloudException
UnknownError :: !String -> CloudException
IOError :: !String -> CloudException
TimeoutError :: !String -> CloudException
JsonDecodeError :: !String -> CloudException
XMLDecodeError :: !String -> CloudException
putLbs :: (HasCredentials c, MonadHttp (WebApiM c)) => Url scheme -> Option scheme -> ByteString -> WebApiM c LbsResponse
getLbs :: (HasCredentials c, MonadHttp (WebApiM c)) => Url scheme -> Option scheme -> WebApiM c LbsResponse
urlEncode :: String -> String