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


-- | Authentication backend for Yesod using Facebook.
--   
--   This package allows you to use Yesod's authentication framework with
--   Facebook as your backend. That is, your site's users will log in to
--   your site through Facebook. Your application need to be registered on
--   Facebook.
--   
--   This package works with both the server-side authentication flow
--   (<a>https://developers.facebook.com/docs/authentication/server-side/</a>)
--   via the <a>Yesod.Auth.Facebook.ServerSide</a> module and the
--   client-side authentication
--   (<a>https://developers.facebook.com/docs/authentication/client-side/</a>)
--   via the <a>Yesod.Auth.Facebook.ClientSide</a> module. It's up to you
--   to decide which one to use. The server-side code is older and as such
--   has been through a lot more testing than the client-side code. Also,
--   for now only the server-side code is able to work with other
--   authentication plugins. The client-side code, however, allows you to
--   use some features that are available only to the Facebook JS SDK (such
--   as automatically logging your users in, see
--   <a>https://developers.facebook.com/blog/post/2012/05/08/how-to--improve-the-experience-for-returning-users/</a>).
@package yesod-auth-fb
@version 1.9.1


-- | <tt>yesod-auth</tt> authentication plugin using Facebook's client-side
--   authentication flow. You may see a demo at
--   <a>https://github.com/meteficha/yesod-auth-fb/blob/master/demo/clientside.hs</a>.
--   
--   <i>WARNING:</i> Currently this authentication plugin <i>does not</i>
--   work with other authentication plugins. If you need many different
--   authentication plugins, please try the server-side authentication flow
--   (module <a>Yesod.Auth.Facebook.ServerSide</a>).
--   
--   TODO: Explain how the whole thing fits together.
module Yesod.Auth.Facebook.ClientSide

-- | Yesod authentication plugin using Facebook's client-side
--   authentication flow.
--   
--   You <i>MUST</i> use <a>facebookJSSDK</a> as its documentation states.
authFacebookClientSide :: YesodAuthFbClientSide site => AuthPlugin site

-- | Type class that needs to be implemented in order to use
--   <a>authFacebookClientSide</a>.
--   
--   Minimal complete definition: <a>getFbChannelFile</a>. (We recommend
--   implementing <a>getFbLanguage</a> as well.)
class (YesodAuth site, YesodFacebook site) => YesodAuthFbClientSide site

-- | A route that serves Facebook's channel file in the <i>same</i>
--   <i>subdomain</i> as the current request's subdomain.
--   
--   First of all, we recomment using <a>serveChannelFile</a> to implement
--   the route's handler. For example, if your route is
--   <tt>ChannelFileR</tt>, then you just need:
--   
--   <pre>
--   getChannelFileR :: HandlerT site IO ChooseRep
--   getChannelFileR = serveChannelFile
--   </pre>
--   
--   On most simple cases you may just implement <tt>fbChannelFile</tt> as
--   
--   <pre>
--   getFbChannelFile = return ChannelFileR
--   </pre>
--   
--   However, if your routes span many subdomains, then you must have a
--   channel file for each subdomain, otherwise your site won't work on old
--   Internet Explorer versions (and maybe even on other browsers as well).
--   That's why <a>getFbChannelFile</a> lives inside <a>HandlerT</a>.
getFbChannelFile :: YesodAuthFbClientSide site => HandlerT site IO (Route site)

-- | <i>(Optional)</i> Returns which language we should ask for Facebook's
--   JS SDK. You may use information about the current request to decide
--   upon a language. Defaults to <tt>"en_US"</tt>.
--   
--   If you already use Yesod's I18n capabilities, then there's an easy way
--   of implementing this function. Just create a <tt>FbLanguage</tt>
--   message, for example on your <tt>en.msg</tt> file:
--   
--   <pre>
--   FbLanguage: en_US
--   </pre>
--   
--   and on your <tt>pt.msg</tt> file:
--   
--   <pre>
--   FbLanguage: pt_BR
--   </pre>
--   
--   Then implement <a>getFbLanguage</a> as:
--   
--   <pre>
--   getFbLanguage = ($ MsgFbLanguage) &lt;$&gt; getMessageRender
--   </pre>
--   
--   Although somewhat hacky, this trick works perfectly fine and
--   <i>guarantees</i> that all Facebook messages will be in the same
--   language as the rest of your site (even if Facebook support a language
--   that you don't).
getFbLanguage :: YesodAuthFbClientSide site => HandlerT site IO Text

-- | <i>(Optional)</i> Options that should be given to <tt>FB.init()</tt>.
--   The default implementation is <a>defaultFbInitOpts</a>. If you intend
--   to override this function, we advise you to also call
--   <a>defaultFbInitOpts</a>, e.g.:
--   
--   <pre>
--   getFbInitOpts = do
--     defOpts &lt;- defaultFbInitOpts
--     ...
--     return (defOpts ++ myOpts)
--   </pre>
--   
--   However, if you know what you're doing you're free to override any or
--   all values returned by <a>defaultFbInitOpts</a>.
getFbInitOpts :: YesodAuthFbClientSide site => HandlerT site IO [(Text, Value)]

-- | <i>(Optional)</i> Arbitrary JavaScript that will be called on
--   Facebook's JS SDK's <tt>fbAsyncInit</tt> (i.e. as soon as their SDK is
--   loaded).
fbAsyncInitJs :: YesodAuthFbClientSide site => JavascriptUrl (Route site)

-- | Hamlet that should be spliced <i>right after</i> the
--   <tt><a>body</a></tt> tag in order for Facebook's JS SDK to work. For
--   example:
--   
--   <pre>
--   $doctype 5
--   &lt;html&gt;
--     &lt;head&gt;
--       ...
--     &lt;body&gt;
--       ^{facebookJSSDK AuthR}
--       ...
--   </pre>
--   
--   Facebook's JS SDK may not work correctly if you place it anywhere else
--   on the body. If you absolutely need to do so, avoid any elements
--   placed with <tt>position: relative</tt> or <tt>position:
--   absolute</tt>.
facebookJSSDK :: YesodAuthFbClientSide site => (Route Auth -> Route site) -> WidgetT site IO ()

-- | JavaScript function that should be called in order to login the user.
--   You could splice this into a <tt>onclick</tt> event, for example:
--   
--   <pre>
--   &lt;a href="#" onclick="#{facebookLogin perms}"&gt;
--     Login via Facebook
--   </pre>
--   
--   You should not call this function if the user is already logged in.
--   
--   This is only a helper around Facebook JS SDK's <tt>FB.login()</tt>,
--   you may call that function directly if you prefer.
facebookLogin :: [Permission] -> JavaScriptCall

-- | Route that forces the user to log in. You should avoid using this
--   route whenever possible, using <a>facebookLogin</a> is much better
--   (after all, this module is for client-side authentication). However,
--   you may want to use it at least for <a>authRoute</a>, e.g.:
--   
--   <pre>
--   instance <a>Yesod</a> MyFoundation where
--     ...
--     <a>authRoute</a> _ = Just $ AuthR (facebookForceLoginR [])
--   </pre>
facebookForceLoginR :: [Permission] -> Route Auth

-- | JavaScript function that should be called in order to logout the user.
--   You could splice the result of this widget into a <tt>onclick</tt>
--   event, for example:
--   
--   <pre>
--   &lt;a href="#" onclick="#{facebookLogout}"&gt;
--     Logout
--   </pre>
--   
--   This function used to be just a helper around Facebook JS SDK's
--   <tt>FB.logout()</tt>. However, now it performs a check to see if the
--   user is logged via FB and redirects to <tt>yesod-auth</tt>'s normal
--   <a>LogoutR</a> route if not.
facebookLogout :: JavaScriptCall

-- | A JavaScript function call.
type JavaScriptCall = Text

-- | Facebook's channel file implementation (see
--   <a>https://developers.facebook.com/docs/reference/javascript/</a>).
--   
--   Note that we set an expire time in the far future, so you won't be
--   able to re-use this route again. No common users will see this route,
--   so you may use anything.
serveChannelFile :: HandlerT site IO TypedContent

-- | Default implementation for <a>getFbInitOpts</a>. Defines:
--   
--   <ul>
--   <li><i><tt>appId</tt></i> Using <a>getFbCredentials</a>.</li>
--   <li><i><tt>channelUrl</tt></i> Using <a>getFbChannelFile</a>.</li>
--   <li><i><tt>cookie</tt></i> To <tt>True</tt>. This one is extremely
--   important and this module won't work <i>at all</i> without it.</li>
--   <li><i><tt>status</tt></i> To <tt>True</tt>, since this usually is
--   what you want.</li>
--   </ul>
defaultFbInitOpts :: YesodAuthFbClientSide site => HandlerT site IO [(Text, Value)]

-- | Get the user access token from a <a>Creds</a> created by this backend.
--   This function should be used on <a>getAuthId</a>.
extractCredsAccessToken :: Creds m -> Maybe UserAccessToken

-- | Get the Facebook's user access token from Facebook's cookie. Returns
--   <a>Left</a> if the cookie is not found, is not authentic, is for
--   another app, is corrupted <i>or</i> does not contains the information
--   needed (maybe the user is not logged in). Note that the returned
--   access token may have expired, we recommend using <a>hasExpired</a>
--   and <a>isValid</a>.
--   
--   This <a>getUserAccessTokenFromFbCookie</a> is completely different
--   from the one from the <a>Yesod.Auth.Facebook.ServerSide</a> module.
--   This one does not use only the session, which means that (a) it's
--   somewhat slower because everytime you call this
--   <a>getUserAccessTokenFromFbCookie</a> it needs to reverify the cookie,
--   but (b) it is always up-to-date with the latest cookie that the
--   Facebook JS SDK has given us and (c) avoids duplicating the
--   information from the cookie into the session.
--   
--   Note also that <a>getUserAccessTokenFromFbCookie</a> may return
--   <a>Left</a> even tough the user is properly logged in. When you force
--   authentication via <a>facebookForceLoginR</a> (e.g., via
--   'requireAuth'/'requireAuthId') we use the server-side flow which will
--   not set the cookie until at least the FB JS SDK runs on the
--   user-agent, sets the cookie and another request is sent to our
--   servers.
--   
--   For the reason stated on the previous paragraph, you should not use
--   this function on <a>getAuthId</a>. Instead, you should use
--   <a>extractCredsAccessToken</a>.
getUserAccessTokenFromFbCookie :: YesodAuthFbClientSide site => AuthHandler site (Either String UserAccessToken)

-- | Cookie name with the signed request for the given credentials.
signedRequestCookieName :: Credentials -> Text


-- | <tt>yesod-auth</tt> authentication plugin using Facebook's server-side
--   authentication flow.
module Yesod.Auth.Facebook.ServerSide

-- | Yesod authentication plugin using Facebook.
authFacebook :: (YesodAuth site, YesodFacebook site) => [Permission] -> AuthPlugin site

-- | Route for login using this authentication plugin.
facebookLogin :: AuthRoute

-- | Route for logout using this authentication plugin. This will log your
--   user out of your site <i>and</i> log him out of Facebook since, at the
--   time of writing, Facebook's policies
--   (<a>https://developers.facebook.com/policy/</a>) specified that the
--   user needs to be logged out from Facebook itself as well. If you want
--   to always logout from just your site (and not from Facebook), use
--   <a>LogoutR</a>.
facebookLogout :: AuthRoute

-- | Get the Facebook's user access token from the session. Returns
--   <tt>Nothing</tt> if it's not found (probably because the user is not
--   logged in via <tt>yesod-auth-fb</tt>). Note that the returned access
--   token may have expired, we recommend using <a>hasExpired</a> and
--   <a>isValid</a>.
getUserAccessToken :: MonadHandler m => m (Maybe UserAccessToken)

-- | Set the Facebook's user access token on the user's session. Usually
--   you don't need to call this function, but it may become handy together
--   with <a>extendUserAccessToken</a>.
setUserAccessToken :: MonadHandler m => UserAccessToken -> m ()

-- | Delete Facebook's user access token from the session. <i>Do</i> <i>not
--   use</i> this function unless you know what you're doing.
deleteUserAccessToken :: MonadHandler m => m ()


-- | This is a deprecated module that just re-exports
--   <a>Yesod.Auth.Facebook.ServerSide</a>.

-- | <i>Deprecated: Use Yesod.Auth.Facebook.ServerSide instead (since
--   yesod-auth-fb 1.0.3).</i>
module Yesod.Auth.Facebook
