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


-- | A Haskell implementation of OAuth 1.0a protocol.
--   
--   This library implements all PLAINTEXT, HMAC-SHA1 and RSA-SHA1
--   signatures as defined in the specification 1.0. Currently it supports
--   only <i>consumer</i> related functions, but there are plans to add
--   support <i>service providers</i> as well. More on OAuth protocol info
--   at: <a>http://oauth.net/</a>
@package hoauth
@version 0.2.5

module Network.OAuth.Http.Util
splitBy :: (a -> Bool) -> [a] -> [[a]]


-- | Percent encoding <a>http://tools.ietf.org/html/rfc3986#page-12</a>
--   functions, with the exception that all encoding/decoding is in UTF-8.
module Network.OAuth.Http.PercentEncoding
class PercentEncoding a
encode :: (PercentEncoding a) => a -> String
decode :: (PercentEncoding a) => String -> Maybe (a, String)

-- | Decodes a percent encoded string. In case of failure returns a default
--   value, instead of Nothing.
decodeWithDefault :: (PercentEncoding a) => a -> String -> a
instance (PercentEncoding a) => PercentEncoding [a]
instance PercentEncoding Word8
instance PercentEncoding Char


-- | The request currently is only able to represent an HTTP request.
module Network.OAuth.Http.Request
data Request
ReqHttp :: Version -> Bool -> String -> Int -> Method -> FieldList -> [String] -> FieldList -> ByteString -> Request

-- | Protocol version
version :: Request -> Version

-- | Wheter or not to use ssl
ssl :: Request -> Bool

-- | The hostname to connect to
host :: Request -> String

-- | The port to connect to
port :: Request -> Int

-- | The HTTP method of the request.
method :: Request -> Method

-- | Request headers
reqHeaders :: Request -> FieldList

-- | The path split into components
pathComps :: Request -> [String]

-- | The query string, usually set for GET requests
qString :: Request -> FieldList

-- | The message body
reqPayload :: Request -> ByteString

-- | Key-value list.
data FieldList

-- | Supported HTTP versions
data Version
Http10 :: Version
Http11 :: Version

-- | All known HTTP methods
data Method
GET :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
CONNECT :: Method
HEAD :: Method

-- | Creates a FieldList type from a list.
fromList :: [(String, String)] -> FieldList

-- | Creates a FieldList out from a single element.
singleton :: (String, String) -> FieldList

-- | Returns an empty fieldlist.
empty :: FieldList

-- | Transforms a fieldlist into a list type.
toList :: FieldList -> [(String, String)]

-- | Parse a query string.
parseQString :: String -> FieldList

-- | Find keys that satisfy a given predicate.
find :: (String -> Bool) -> FieldList -> [String]

-- | Finds a the value defined in a fieldlist or returns a default value.
--   In the event there are multiple values under the same key the first
--   one is returned.
findWithDefault :: (String, String) -> FieldList -> String

-- | Same as <a>findWithDefault</a> but the match is case-insenstiive.
ifindWithDefault :: (String, String) -> FieldList -> String

-- | Updates all occurrences of a given key with a new value. Does nothing
--   if the values does not exist.
change :: (String, String) -> FieldList -> FieldList

-- | Inserts a new value into a fieldlist.
insert :: (String, String) -> FieldList -> FieldList

-- | Inserts or updates occurrences of a given key.
replace :: (String, String) -> FieldList -> FieldList

-- | Same as <i>replace</i> but work on a list type
replaces :: [(String, String)] -> FieldList -> FieldList

-- | Combines two fieldsets, but prefere items of the first list.
union :: FieldList -> FieldList -> FieldList

-- | Combines two fieldsets keeping duplicates.
unionAll :: FieldList -> FieldList -> FieldList

-- | Show the URL.
showURL :: Request -> String

-- | Show the querty string of the URL.
showQString :: Request -> String

-- | Show the protocol in use (currently either https or http)
showProtocol :: Request -> String

-- | Show the host+port path of the request. May return only the host when
--   (ssl=False &amp;&amp; port==80) or (ssl=True &amp;&amp; port==443).
showAuthority :: Request -> String

-- | Show the path component of the URL.
showPath :: Request -> String

-- | Parse a URL and creates an request type.
parseURL :: String -> Maybe Request
instance Eq Request
instance Show Request
instance Eq FieldList
instance Ord FieldList
instance Eq Version
instance Eq Method
instance Binary FieldList
instance Monoid FieldList
instance Show FieldList
instance Show Version
instance Read Version
instance Read Method
instance Show Method


-- | The response of the server for a given <a>Request</a>. Similarly to
--   <a>Request</a>, it is currently only able to represent HTTP responses.
module Network.OAuth.Http.Response
data Response
RspHttp :: Int -> String -> FieldList -> ByteString -> Response

-- | The status code (e.g. 200, 302)
status :: Response -> Int

-- | The message that comes along with the status (e.g. HTTP/1.1 200 OK)
statusLine :: Response -> String

-- | The response headers
rspHeaders :: Response -> FieldList

-- | The body of the message
rspPayload :: Response -> ByteString
instance Show Response


-- | A type class that is able to perform HTTP requests.
module Network.OAuth.Http.HttpClient

-- | The HttpClient type class.
class (Monad m) => HttpClient m
request :: (HttpClient m) => Request -> m Response
unpack :: (HttpClient m) => m a -> IO a

-- | The libcurl backend
newtype CurlM a
CurlM :: IO a -> CurlM a
unCurlM :: CurlM a -> IO a
instance Monad CurlM
instance MonadIO CurlM
instance MonadFix CurlM
instance Functor CurlM
instance HttpClient CurlM


-- | A Haskell library that implements oauth authentication protocol as
--   defined in <a>http://tools.ietf.org/html/draft-hammer-oauth-10</a>.
--   
--   According to the RFC [1]: OAuth provides a method for clients to
--   access server resources on behalf of a resource owner (such as a
--   different client or an end- user). It also provides a process for
--   end-users to authorize third- party access to their server resources
--   without sharing their credentials (typically, a username and password
--   pair), using user- agent redirections.
--   
--   The following code should perform a request using 3 legged oauth,
--   provided the parameters are defined correctly:
--   
--   <pre>
--   reqUrl   = fromJust . parseURL $ "https://service.provider/request_token"
--   accUrl   = fromJust . parseURL $ "https://service.provider/access_token"
--   srvUrl   = fromJust . parseURL $ "http://service/path/to/resource/"
--   authUrl  = ("http://service.provider/authorize?oauth_token="++) . findWithDefault ("oauth_token","") . oauthParams
--   app      = Application "consumerKey" "consumerSec" OOB
--   response = runOAuth $ do ignite app
--                            oauthRequest PLAINTEXT Nothing reqUrl
--                            cliAskAuthorization authUrl
--                            oauthRequest PLAINTEXT Nothing accUrl
--                            serviceRequest HMACSHA1 (Just "realm") srvUrl
--   </pre>
module Network.OAuth.Consumer

-- | The OAuth Token.
data Token

-- | This token is used to perform 2 legged OAuth requests.
TwoLegg :: Application -> FieldList -> Token
application :: Token -> Application
oauthParams :: Token -> FieldList

-- | The service provider has granted you the request token but the user
--   has not yet authorized your application. You need to exchange this
--   token by a proper AccessToken, but this may only happen after user has
--   granted you permission to do so.
ReqToken :: Application -> FieldList -> Token
application :: Token -> Application
oauthParams :: Token -> FieldList

-- | This is a proper 3 legged OAuth. The difference between this and
--   ReqToken is that user has authorized your application and you can
--   perform requests on behalf of that user.
AccessToken :: Application -> FieldList -> Token
application :: Token -> Application
oauthParams :: Token -> FieldList

-- | Identifies the application.
data Application
Application :: String -> String -> OAuthCallback -> Application
consKey :: Application -> String
consSec :: Application -> String
callback :: Application -> OAuthCallback

-- | Callback used in oauth authorization
data OAuthCallback
URL :: String -> OAuthCallback
OOB :: OAuthCallback

-- | Available signature methods.
data SigMethod

-- | The <a>PLAINTEXT</a> <i>consumer_key</i> <i>token_secret</i> method
--   does not provide any security protection and SHOULD only be used over
--   a secure channel such as <i>HTTPS</i>. It does not use the Signature
--   Base String.
PLAINTEXT :: SigMethod

-- | The <tt>HMAC_SHA1</tt> <i>consumer_key</i> <i>token_secret</i>
--   signature method uses the <i>HMAC-SHA1</i> signature algorithm as
--   defined in <a>http://tools.ietf.org/html/rfc2104</a> where the
--   Signature Base String is the text and the key is the concatenated
--   values (each first encoded per Parameter Encoding) of the Consumer
--   Secret and Token Secret, separated by an <i>&amp;</i> character (ASCII
--   code 38) even if empty.
HMACSHA1 :: SigMethod

-- | The optional authentication realm. Refer to
--   <a>http://oauth.net/core/1.0/#auth_header_authorization</a> for more
--   information.
type Realm = String

-- | Random string that is unique amongst requests. Refer to
--   <a>http://oauth.net/core/1.0/#nonce</a> for more information.
type Nonce = String

-- | Unix timestamp (seconds since epoch). Refer to
--   <a>http://oauth.net/core/1.0/#nonce</a> for more information.
type Timestamp = String

-- | The OAuth monad.
type OAuthMonad m a = StateT Token m a

-- | Execute the oauth monad and returns the value it produced.
runOAuth :: (MonadIO m, HttpClient m) => OAuthMonad m a -> m a

-- | Executes an oauth request which is intended to upgrade/refresh the
--   current token. Use this combinator to get either a request token or an
--   access token.
oauthRequest :: (MonadIO m, HttpClient m) => SigMethod -> Maybe Realm -> Request -> OAuthMonad m Token

-- | Simply complete the request with the required information to perform
--   the oauth request.
completeRequest :: (MonadIO m) => SigMethod -> Token -> Maybe Realm -> Request -> m Request

-- | Performs a signed request with the available token.
serviceRequest :: (MonadIO m, HttpClient m) => SigMethod -> Maybe Realm -> Request -> OAuthMonad m Response

-- | Probably this is just useful for testing. It asks the user
--   (stdout/stdin) to authorize the application and provide the
--   oauth_verifier.
cliAskAuthorization :: (MonadIO m) => (Token -> String) -> OAuthMonad m ()

-- | Transforms an application into a token.
ignite :: (MonadIO m) => Application -> OAuthMonad m ()

-- | Extracts the token from the OAuthMonad.
getToken :: (Monad m) => OAuthMonad m Token

-- | Alias to the put function.
putToken :: (Monad m) => Token -> OAuthMonad m ()

-- | Returns true if the token is able to perform 2-legged oauth requests.
twoLegged :: Token -> Bool

-- | Tests whether or not the current token is able to perform 3-legged
--   requests.
threeLegged :: Token -> Bool

-- | Signs a request using a given signature method. This expects the
--   request to be a valid request already (for instance, none and
--   timestamp are not set).
signature :: SigMethod -> Token -> Request -> String

-- | Injects the oauth_verifier into the token. Usually this means the user
--   has authorized the app to access his data.
injectOAuthVerifier :: String -> Token -> Token

-- | Transforms an application into a token
fromApplication :: Application -> Token

-- | Receives a response possibly from a service provider and updates the
--   token. As a matter effect, assumes the content-type is
--   application/x-www-form-urlencoded (because some service providers send
--   it as text/plain) and if the status is [200..300) updates the token
--   accordingly.
fromResponse :: Response -> Token -> Either String Token

-- | Computes the authorization header and updates the request.
authorization :: SigMethod -> Maybe Realm -> Nonce -> Timestamp -> Token -> Request -> String
instance Eq Token
instance Eq Application
instance Eq OAuthCallback
instance Binary Token
instance Binary Application
instance Binary OAuthCallback
instance Show OAuthCallback
instance Show SigMethod