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

module Facebook

-- | <tt>FacebookT auth m a</tt> is this library's monad transformer.
--   Contains information needed to issue commands and queries to Facebook.
--   The phantom type <tt>auth</tt> may be either <a>Auth</a> (you have
--   supplied your <a>Credentials</a>) or <a>NoAuth</a> (you have not
--   supplied any <a>Credentials</a>).
data FacebookT auth m a

-- | Run a computation in the <a>FacebookT</a> monad transformer with your
--   credentials.
runFacebookT :: Credentials -> Manager -> FacebookT Auth m a -> m a

-- | Run a computation in the <a>FacebookT</a> monad without credentials.
runNoAuthFacebookT :: Manager -> FacebookT NoAuth m a -> m a

-- | Same as <a>runFacebookT</a>, but uses Facebook's beta tier (see
--   <a>https://developers.facebook.com/support/beta-tier/</a>).
beta_runFacebookT :: Credentials -> Manager -> FacebookT Auth m a -> m a

-- | Same as <a>runNoAuthFacebookT</a>, but uses Facebook's beta tier (see
--   <a>https://developers.facebook.com/support/beta-tier/</a>).
beta_runNoAuthFacebookT :: Manager -> FacebookT NoAuth m a -> m a

-- | Phantom type stating that you have provided your <a>Credentials</a>
--   and thus have access to the whole API.
data Auth

-- | Phantom type stating that you have <i>not</i> provided your
--   <a>Credentials</a>. This means that you'll be limited about which APIs
--   you'll be able use.
data NoAuth

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

-- | Your application name (e.g. for OpenGraph calls).
appName :: Credentials -> ByteString

-- | Your application ID.
appId :: Credentials -> ByteString

-- | Your application secret key.
appSecret :: Credentials -> ByteString

-- | 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 two kinds of access tokens are distinguished by the phantom type
--   on <a>AccessToken</a>, which can be <a>UserKind</a> or <a>AppKind</a>.
data AccessToken kind
UserAccessToken :: UserId -> AccessTokenData -> UTCTime -> AccessToken UserKind
AppAccessToken :: AccessTokenData -> AccessToken AppKind

-- | Type synonym for <tt><a>AccessToken</a> <a>UserKind</a></tt>.
type UserAccessToken = AccessToken UserKind

-- | Type synonym for <tt><a>AccessToken</a> <a>AppKind</a></tt>.
type AppAccessToken = AccessToken AppKind

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

-- | <tt>True</tt> if the access token has expired, otherwise
--   <tt>False</tt>.
hasExpired :: (Functor m, MonadIO m) => AccessToken anyKind -> 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 :: (MonadBaseControl IO m, MonadResource m) => AccessToken anyKind -> FacebookT anyAuth m Bool

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

-- | Get an app access token from Facebook using your credentials.
getAppAccessToken :: (MonadResource m, MonadBaseControl IO m) => FacebookT Auth m AppAccessToken

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

-- | 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 :: Monad m => RedirectUrl -> [Permission] -> FacebookT Auth m 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>UserAccessToken</a></tt>.
getUserAccessTokenStep2 :: (MonadBaseControl IO m, MonadResource m) => RedirectUrl -> [Argument] -> FacebookT Auth m UserAccessToken

-- | The URL an user should be redirected to in order to log them out of
--   their Facebook session. Facebook will then redirect the user to the
--   provided URL after logging them out. Note that, at the time of this
--   writing, Facebook's policies require you to log the user out of
--   Facebook when they ask to log out of your site.
--   
--   Note also that Facebook may refuse to redirect the user to the
--   provided URL if their user access token is invalid. In order to
--   prevent this bug, we suggest that you use <a>isValid</a> before
--   redirecting the user to the URL provided by <a>getUserLogoutUrl</a>
--   since this function doesn't do any validity checks.
getUserLogoutUrl :: Monad m => UserAccessToken -> RedirectUrl -> FacebookT Auth m Text

-- | Extend the expiration time of an user access token (see
--   <a>https://developers.facebook.com/docs/offline-access-deprecation/</a>,
--   <a>https://developers.facebook.com/roadmap/offline-access-removal/</a>).
--   Only short-lived user access tokens may extended into long-lived user
--   access tokens, you must get a new short-lived user access token if you
--   need to extend a long-lived one. 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 :: (MonadBaseControl IO m, MonadResource m) => UserAccessToken -> FacebookT Auth m (Either FacebookException UserAccessToken)

-- | Parses a Facebook signed request
--   (<a>https://developers.facebook.com/docs/authentication/signed_request/</a>),
--   verifies its authencity and integrity using the HMAC and decodes its
--   JSON object.
parseSignedRequest :: (FromJSON a, Monad m) => ByteString -> FacebookT Auth m (Maybe a)

-- | A Facebook user profile (see
--   <a>https://developers.facebook.com/docs/reference/api/user/</a>).
--   
--   <i>NOTE:</i> We still don't support all fields supported by Facebook.
--   Please fill an issue if you need access to any other fields.
data User
User :: UserId -> Maybe Text -> Maybe Text -> Maybe Text -> Maybe Text -> Maybe Gender -> Maybe Text -> Maybe Text -> Maybe Bool -> Maybe Text -> Maybe UserLocation -> User
userId :: User -> UserId
userName :: User -> Maybe Text
userFirstName :: User -> Maybe Text
userMiddleName :: User -> Maybe Text
userLastName :: User -> Maybe Text
userGender :: User -> Maybe Gender
userLocale :: User -> Maybe Text
userUsername :: User -> Maybe Text
userVerified :: User -> Maybe Bool
userEmail :: User -> Maybe Text
userLocation :: User -> Maybe UserLocation

-- | A Facebook user id such as <tt>1008905713901</tt>.
type UserId = ByteString

-- | An user's gender.
data Gender
Male :: Gender
Female :: Gender

-- | An user's location.
data UserLocation
UserLocation :: Id -> Text -> UserLocation
userLocationId :: UserLocation -> Id
userLocationName :: UserLocation -> Text

-- | Get an user using his user ID. The user access token is optional, but
--   when provided more information can be returned back by Facebook. The
--   user ID may be <tt>"me"</tt>, in which case you must provide an user
--   access token and information about the token's owner is given.
getUser :: (MonadResource m, MonadBaseControl IO m) => UserId -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m User

-- | Search users by keyword.
searchUsers :: (MonadResource m, MonadBaseControl IO m) => ByteString -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m (SearchResultPage User)

-- | A Facebook page (see
--   <a>https://developers.facebook.com/docs/reference/api/page/</a>).
--   
--   <i>NOTE:</i> Does not yet support all fields. Please file an issue if
--   you need any other fields.
data Page
Page :: ByteString -> Maybe Text -> Maybe ByteString -> Maybe Text -> Maybe Bool -> Maybe Bool -> Maybe Integer -> Maybe UserLocation -> Maybe Text -> Maybe Integer -> Maybe ByteString -> Maybe ByteString -> Maybe Integer -> Page
pageId :: Page -> ByteString
pageName :: Page -> Maybe Text
pageLink :: Page -> Maybe ByteString
pageCategory :: Page -> Maybe Text
pageIsPublished :: Page -> Maybe Bool
pageCanPost :: Page -> Maybe Bool
pageLikes :: Page -> Maybe Integer
pageLocation :: Page -> Maybe UserLocation
pagePhone :: Page -> Maybe Text
pageCheckins :: Page -> Maybe Integer
pagePicture :: Page -> Maybe ByteString
pageWebsite :: Page -> Maybe ByteString
pageTalkingAboutCount :: Page -> Maybe Integer

-- | Get a page using its ID. The user access token is optional.
getPage :: (MonadResource m, MonadBaseControl IO m) => ByteString -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m Page

-- | Search pages by keyword. The user access token is optional.
searchPages :: (MonadResource m, MonadBaseControl IO m) => ByteString -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m (SearchResultPage Page)

-- | Creates an Open Graph action on the user's timeline. Returns the
--   <a>Id</a> of the newly created action. For example:
--   
--   <pre>
--   now &lt;- liftIO getCurrentTime
--   createAction "cook"
--                [ "recipe" #= "http://example.com/cookie.html"
--                , "when"   #= now ]
--                token
--   </pre>
createAction :: (MonadResource m, MonadBaseControl IO m) => Action -> [Argument] -> Maybe AppAccessToken -> UserAccessToken -> FacebookT Auth m Id

-- | An action of your app. Please refer to Facebook's documentation at
--   <a>https://developers.facebook.com/docs/opengraph/keyconcepts/#actions-objects</a>
--   to see how you can create actions.
--   
--   This is a <tt>newtype</tt> of <a>ByteString</a> that supports only
--   <a>IsString</a>. This means that to create an <a>Action</a> you should
--   use the <tt>OverloadedStrings</tt> language extension. For example,
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   foo token = do
--     ...
--     createAction "cook" [...] token
--   </pre>
data Action

-- | Creates a 'check-in' and returns its id. Place and coordinates are
--   both required by Facebook.
createCheckin :: (MonadResource m, MonadBaseControl IO m) => Id -> (Double, Double) -> [Argument] -> UserAccessToken -> FacebookT Auth m Id

-- | Query the Facebook Graph using FQL. You may want to use
--   <a>FQLResult</a> when parsing the returned JSON.
fqlQuery :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Text -> Maybe (AccessToken anyKind) -> FacebookT anyAuth m a

-- | Parses an FQL query result. FQL query results are always of the form
--   
--   <pre>
--   { <a>data</a>: [ret1, ret2, ...] }
--   </pre>
--   
--   This <tt>newtype</tt> unwraps the array from the <tt><a>data</a></tt>
--   field automatically for you, so you may write something like:
--   
--   <pre>
--   FQLResult [...] &lt;- fqlQuery ...
--   </pre>
newtype FQLResult a
FQLResult :: [a] -> FQLResult a

-- | Create an <a>Argument</a> with a <a>SimpleType</a>. See the docs on
--   <a>createAction</a> for an example.
(#=) :: SimpleType a => ByteString -> a -> Argument

-- | Class for data types that may be represented as a Facebook simple
--   type. (see
--   <a>https://developers.facebook.com/docs/opengraph/simpletypes/</a>).
class SimpleType a
encodeFbParam :: SimpleType a => a -> ByteString

-- | Make a raw <tt>GET</tt> request to Facebook's Graph API. Returns a raw
--   JSON <a>Value</a>.
getObject :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => ByteString -> [Argument] -> Maybe (AccessToken anyKind) -> FacebookT anyAuth m a

-- | Make a raw <tt>POST</tt> request to Facebook's Graph API. Returns a
--   raw JSON <a>Value</a>.
postObject :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => ByteString -> [Argument] -> AccessToken anyKind -> FacebookT Auth m a

-- | The identification code of an object.
newtype Id
Id :: ByteString -> Id
idCode :: Id -> ByteString

-- | An argument given to an API call.
type Argument = (ByteString, ByteString)

-- | Make a raw <tt>GET</tt> request to the /search endpoint of Facebook’s
--   Graph API. Returns a raw JSON <a>Value</a>.
searchObjects :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => ByteString -> ByteString -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m (SearchResultPage a)

-- | The result object for searchObjects. The type parameter is expected to
--   be an instance of A.FromJSON, but nothing has been done to assure that
--   Facebook will return the type expected.
data SearchResultPage a
SearchResultPage :: [a] -> Maybe Pager -> SearchResultPage a
searchResults :: SearchResultPage a -> [a]
searchPage :: SearchResultPage a -> Maybe Pager

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

-- | Retrieves the <a>Text</a> back from a <a>Permission</a>. Most of the
--   time you won't need to use this function, but you may need it if
--   you're a library author.
unPermission :: Permission -> Text