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

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 -> [FormDataPart] -> 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 (the first/only string part)
reqPayload :: Request -> ByteString

-- | The message body (i.e., for multipart/form-data)
multipartPayload :: Request -> [FormDataPart]

-- | 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
data FormDataPart
FormDataPart :: String -> Maybe String -> Content -> [String] -> Maybe String -> FormDataPart
postName :: FormDataPart -> String
contentType :: FormDataPart -> Maybe String
content :: FormDataPart -> Content
extraHeaders :: FormDataPart -> [String]
showName :: FormDataPart -> Maybe String
data Content
ContentFile :: FilePath -> Content
ContentBuffer :: CString -> Long -> Content
ContentString :: String -> Content
convertMultipart :: [FormDataPart] -> [HttpPost]

-- | 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 Method
instance Eq Version
instance Eq FieldList
instance Ord FieldList
instance Eq Content
instance Show Content
instance Eq FormDataPart
instance Show FormDataPart
instance Eq Request
instance Show Request
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)
reason :: Response -> String

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

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


-- | Minimum definition of a user agent required to implement oauth service
--   calls. This should suffice for most applications.
module Network.OAuth.Http.HttpClient
class HttpClient c where runClient_ c r = runClient c r >>= either fail return
runClient :: (HttpClient c, MonadIO m) => c -> Request -> m (Either String Response)
runClient_ :: (HttpClient c, MonadIO m) => c -> Request -> m Response


-- | A type class that is able to perform HTTP requests.
module Network.OAuth.Http.CurlHttpClient
data CurlClient
CurlClient :: CurlClient
OptionsCurlClient :: [CurlOption] -> CurlClient
instance HttpClient CurlClient


-- | 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","ERROR") . oauthParams
--   app       = Application "consumerKey" "consumerSec" OOB
--   response  = runOAuthM (fromApplication app) $ do { signRq2 PLAINTEXT Nothing reqUrl &gt;&gt;= oauthRequest CurlHttpClient
--                                                    ; cliAskAuthorization authUrl
--                                                    ; signRq2 PLAINTEXT Nothing accUrl &gt;&gt;= oauthRequest CurlHttpClient
--                                                    ; signRq2 HMACSHA1 (Just $ Realm "realm") srvUrl &gt;&gt;= serviceRequest CurlHttpClient
--                                                    }
--   </pre>
module Network.OAuth.Consumer
data OAuthMonadT m a

-- | A request that is ready to be performed, i.e., that contains
--   authorization headers.
data OAuthRequest

-- | 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 <a>RSA-SHA1</a> signature method uses the RSASSA-PKCS1-v1_5
--   signature algorithm as defined in [RFC3447], Section 8.2 (also known
--   as PKCS#1), using SHA-1 as the hash function for EMSA-PKCS1-v1_5. To
--   use this method, the client MUST have established client credentials
--   with the server that included its RSA public key (in a manner that is
--   beyond the scope of this specification).
RSASHA1 :: PrivateKey -> SigMethod

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

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

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

-- | Execute the oauth monad using a given error handler
runOAuth :: Monad m => (String -> m a) -> Token -> OAuthMonadT m a -> m a

-- | Execute the oauth monad and returns the value it produced using
--   <a>fail</a> as the error handler.
runOAuthM :: Monad m => Token -> OAuthMonadT m a -> m a

-- | Executes an oauth request which is intended to upgrade/refresh the
--   current token.
oauthRequest :: (HttpClient c, MonadIO m) => c -> OAuthRequest -> OAuthMonadT m Token

-- | Simply create the OAuthRequest but adds no Authorization header.
packRq :: Request -> OAuthRequest

-- | Complete the request with authorization headers.
signRq :: MonadIO m => Token -> SigMethod -> Maybe Realm -> Request -> m OAuthRequest

-- | Complete the request with authorization headers.
signRq2 :: MonadIO m => SigMethod -> Maybe Realm -> Request -> OAuthMonadT m OAuthRequest

-- | Performs a signed request with the available token.
serviceRequest :: (HttpClient c, MonadIO m) => c -> OAuthRequest -> OAuthMonadT 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) -> OAuthMonadT m ()

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

-- | Extracts the token from the OAuthMonadT.
getToken :: Monad m => OAuthMonadT m Token

-- | Alias to the put function.
putToken :: Monad m => Token -> OAuthMonadT 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

-- | Creates a TwoLegg token from an application
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 Show OAuthRequest
instance Eq Nonce
instance Eq Timestamp
instance Ord Timestamp
instance Eq Realm
instance Eq OAuthCallback
instance Eq Application
instance Eq Token
instance Binary Token
instance Binary Application
instance Binary OAuthCallback
instance Show OAuthCallback
instance (Monad m, Functor m) => Functor (OAuthMonadT m)
instance MonadIO m => MonadIO (OAuthMonadT m)
instance MonadTrans OAuthMonadT
instance Monad m => Monad (OAuthMonadT m)