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


-- | Interface to Google Cloud APIs
--   
--   High-level, extensible interface to Google Cloud APIs.
@package goggles
@version 0.2


-- | <h2><i>Dependencies</i></h2>
--   
--   The examples require the following declarations (which in turn mean
--   that the <tt>req</tt> and <tt>bytestring</tt> libraries are imported
--   by the user's project). You will also need the
--   <tt>OverloadedStrings</tt> language extension :
--   
--   <pre>
--   import qualified Data.ByteString.Lazy as LB
--   import Network.HTTP.Req (responseBody)
--   import Network.Goggles
--   </pre>
--   
--   <h2><i>Examples</i></h2>
--   
--   This first example, <tt>listBucket</tt>, reads content from a cloud
--   storage bucket:
--   
--   <ol>
--   <li>it loads the GCP credentials (username and RSA key),</li>
--   <li>retrieves a token via OAuth2,</li>
--   <li>performs a single call to the Cloud Storage API endpoint that
--   lists the metadata related to the contents of a storage bucket,
--   and</li>
--   <li>returns the raw API data to the user as a lazy ByteString.</li>
--   </ol>
--   
--   <pre>
--   listBucket :: IO LB.ByteString
--   listBucket = do
--     let usr = "...iam.gserviceaccount.com"
--         bucket = "&lt;my-gcs-bucket&gt;"
--         key = "&lt;rsa_key&gt;"
--     pvtkey &lt;- parseRSAPrivateKey key
--     let creds = GCPServiceAccount pvtkey usr Nothing ""
--     hdl &lt;- createHandle creds scopesDefault
--     responseBody &lt;$&gt; evalWebApiIO hdl (listObjects bucket)
--   </pre>
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 :: HasCredentials c => 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

-- | This class
class HasCredentials c where {
    type family Credentials c;
    type family Options c;
    type family TokenContent c;
}
tokenFetch :: HasCredentials 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

-- | 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

-- | 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

module Network.Goggles.Auth