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


-- | Bindings to Facebook's API.
--   
--   This package exports bindings to Facebook's APIs (see
--   <a>http://developers.facebook.com/</a>). Does not have any external
--   dependencies and tries to use as little resources (such as memory,
--   sockets and CPU) as possible by using packages such as <tt>aeson</tt>,
--   <tt>attoparsec</tt>, <tt>bytestring</tt>, <tt>conduit</tt>,
--   <tt>http-conduit</tt>, <tt>text</tt> and others.
--   
--   While we would like to have a complete binding to Facebook's API, this
--   package is being developed on demand. If you need something that has
--   not been implemented yet, please send a pull request or file an issue
--   on GitHub (<a>https://github.com/meteficha/fb/issues</a>).
@package fb
@version 0.2

module Facebook

-- | Credentials that you get for your app when you register on Facebook.
data Credentials
Credentials :: Ascii -> Ascii -> Credentials

-- | Your application ID.
clientId :: Credentials -> Ascii

-- | Your application secret key.
clientSecret :: Credentials -> Ascii

-- | An access token. While you can make some API calls without an access
--   token, many require an access token and some will give you more
--   information with an appropriate access token.
--   
--   There are two kinds of access tokens:
--   
--   <ul>
--   <li><i>User access token</i> An access token obtained after an user
--   accepts your application. Let's you access more information about that
--   user and act on their behalf (depending on which permissions you've
--   asked for).</li>
--   <li><i>App access token</i> An access token that allows you to take
--   administrative actions for your application.</li>
--   </ul>
--   
--   These access tokens are distinguished by the phantom type on
--   <a>AccessToken</a>, which can be <a>User</a> or <a>App</a>.
data AccessToken kind
UserAccessToken :: AccessTokenData -> UTCTime -> AccessToken User
AppAccessToken :: AccessTokenData -> AccessToken App

-- | The access token data that is passed to Facebook's API calls.
type AccessTokenData = Ascii

-- | <tt>True</tt> if the access token has expired, otherwise
--   <tt>False</tt>.
hasExpired :: (Functor m, MonadIO m) => AccessToken kind -> m Bool

-- | <tt>True</tt> if the access token is valid. An expired access token is
--   not valid (see <a>hasExpired</a>). However, a non-expired access token
--   may not be valid as well. For example, in the case of an user access
--   token, they may have changed their password, logged out from Facebook
--   or blocked your app.
isValid :: ResourceIO m => AccessToken kind -> Manager -> ResourceT m Bool

-- | Phantom type used mark an <a>AccessToken</a> as an app access token.
data App

-- | Get an app access token from Facebook using your credentials.
getAppAccessToken :: ResourceIO m => Credentials -> Manager -> ResourceT m (AccessToken App)

-- | Phantom type used mark an <a>AccessToken</a> as an user access token.
data User

-- | URL where the user is redirected to after Facebook authenticates the
--   user authorizes your application. This URL should be inside the domain
--   registered for your Facebook application.
type RedirectUrl = Text

-- | A permission that is asked for the user when he authorizes your app.
--   Please refer to Facebook's documentation at
--   <a>https://developers.facebook.com/docs/reference/api/permissions/</a>
--   to see which permissions are available.
--   
--   This is a <tt>newtype</tt> of <a>Text</a> that supports only
--   <a>IsString</a>. This means that to create a <a>Permission</a> you
--   should use the <tt>OverloadedStrings</tt> language extension. For
--   example,
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   perms :: [Permission]
--   perms = ["user_about_me", "email", "offline_access"]
--   </pre>
data Permission

-- | The first step to get an user access token. Returns the Facebook URL
--   you should redirect you user to. Facebook will authenticate the user,
--   authorize your app and then redirect the user back into the provider
--   <a>RedirectUrl</a>.
getUserAccessTokenStep1 :: Credentials -> RedirectUrl -> [Permission] -> Text

-- | The second step to get an user access token. If the user is
--   successfully authenticate and they authorize your application, then
--   they'll be redirected back to the <a>RedirectUrl</a> you've passed to
--   <a>getUserAccessTokenStep1</a>. You should take the request query
--   parameters passed to your <a>RedirectUrl</a> and give to this function
--   that will complete the user authentication flow and give you an
--   <tt><a>AccessToken</a> <a>User</a></tt>.
getUserAccessTokenStep2 :: ResourceIO m => Credentials -> RedirectUrl -> SimpleQuery -> Manager -> ResourceT m (AccessToken User)

-- | Extend the expiration time of an user access token (see
--   <a>https://developers.facebook.com/docs/offline-access-deprecation/</a>).
--   Returns <tt>Left exc</tt> if there is an error while extending, or
--   <tt>Right token</tt> with the new user access token (which could have
--   the same data and expiration time as before, but you can't assume
--   this). Note that expired access tokens can't be extended, only valid
--   tokens.
extendUserAccessToken :: ResourceIO m => Credentials -> AccessToken User -> Manager -> ResourceT m (Either FacebookException (AccessToken User))

-- | An exception that may be thrown by functions on this package. Includes
--   any information provided by Facebook.
data FacebookException

-- | An exception coming from Facebook.
FacebookException :: Text -> Text -> FacebookException
fbeType :: FacebookException -> Text
fbeMessage :: FacebookException -> Text

-- | An exception coming from the <tt>fb</tt> package's code.
FbLibraryException :: Text -> FacebookException
fbeMessage :: FacebookException -> Text