fb-0.11.2: Bindings to Facebook's API.

Safe HaskellNone

Facebook

Contents

Synopsis

FacebookT monad transformer

data FacebookT auth m a Source

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

Instances

runFacebookTSource

Arguments

:: Credentials

Your app's credentials.

-> Manager

Connection manager (see withManager).

-> FacebookT Auth m a 
-> m a 

Run a computation in the FacebookT monad transformer with your credentials.

runNoAuthFacebookT :: Manager -> FacebookT NoAuth m a -> m aSource

Run a computation in the FacebookT monad without credentials.

mapFacebookT :: (m a -> n b) -> FacebookT anyAuth m a -> FacebookT anyAuth n bSource

Transform the computation inside a FacebookT.

data Auth Source

Phantom type stating that you have provided your Credentials and thus have access to the whole API.

Instances

data NoAuth Source

Phantom type stating that you have not provided your Credentials. This means that you'll be limited about which APIs you'll be able use.

Instances

Authorization and Authentication

Credentials

data Credentials Source

Credentials that you get for your app when you register on Facebook.

Constructors

Credentials 

Fields

appName :: ByteString

Your application name (e.g. for OpenGraph calls).

appId :: ByteString

Your application ID.

appSecret :: ByteString

Your application secret key.

Access token

data AccessToken kind whereSource

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:

User access token
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).
App access token
An access token that allows you to take administrative actions for your application.

These two kinds of access tokens are distinguished by the phantom type on AccessToken, which can be UserKind or AppKind.

Instances

Typeable1 AccessToken 
Eq (AccessToken kind) 
Ord (AccessToken kind) 
Show (AccessToken kind) 
ToSimpleQuery (AccessToken anyKind) 

type AccessTokenData = ByteStringSource

The access token data that is passed to Facebook's API calls.

hasExpired :: (Functor m, MonadIO m) => AccessToken anyKind -> m BoolSource

True if the access token has expired, otherwise False.

isValid :: (MonadBaseControl IO m, MonadResource m) => AccessToken anyKind -> FacebookT anyAuth m BoolSource

True if the access token is valid. An expired access token is not valid (see hasExpired). 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.

App access token

data AppKind Source

Phantom type used mark an AccessToken as an app access token.

Instances

getAppAccessToken :: (MonadResource m, MonadBaseControl IO m) => FacebookT Auth m AppAccessTokenSource

Get an app access token from Facebook using your credentials.

User access token

data UserKind Source

Phantom type used mark an AccessToken as an user access token.

Instances

type RedirectUrl = TextSource

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.

data Permission Source

A permission that is asked for the user when he authorizes your app. Please refer to Facebook's documentation at https://developers.facebook.com/docs/reference/api/permissions/ to see which permissions are available.

This is a newtype of Text that supports only IsString. This means that to create a Permission you should use the OverloadedStrings language extension. For example,

 {-# LANGUAGE OverloadedStrings #-}

 perms :: [Permission]
 perms = ["user_about_me", "email", "offline_access"]

getUserAccessTokenStep1 :: Monad m => RedirectUrl -> [Permission] -> FacebookT Auth m TextSource

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

getUserAccessTokenStep2Source

Arguments

:: (MonadBaseControl IO m, MonadResource m) 
=> RedirectUrl

Should be exactly the same as in getUserAccessTokenStep1.

-> [Argument]

Query parameters.

-> FacebookT Auth m UserAccessToken 

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 RedirectUrl you've passed to getUserAccessTokenStep1. You should take the request query parameters passed to your RedirectUrl and give to this function that will complete the user authentication flow and give you an UserAccessToken.

getUserLogoutUrlSource

Arguments

:: Monad m 
=> UserAccessToken

The user's access token.

-> RedirectUrl

URL the user should be directed to in your site domain.

-> FacebookT Auth m Text

Logout URL in https://www.facebook.com/ (or on https://www.beta.facebook.com/ when using the beta tier).

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 isValid before redirecting the user to the URL provided by getUserLogoutUrl since this function doesn't do any validity checks.

extendUserAccessToken :: (MonadBaseControl IO m, MonadResource m) => UserAccessToken -> FacebookT Auth m (Either FacebookException UserAccessToken)Source

Extend the expiration time of an user access token (see https://developers.facebook.com/docs/offline-access-deprecation/, https://developers.facebook.com/roadmap/offline-access-removal/). 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 Left exc if there is an error while extending, or Right token 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.

Signed requests

parseSignedRequestSource

Arguments

:: (FromJSON a, Monad m) 
=> ByteString

Encoded Facebook signed request

-> FacebookT Auth m (Maybe a) 

Parses a Facebook signed request (https://developers.facebook.com/docs/authentication/signed_request/), verifies its authencity and integrity using the HMAC and decodes its JSON object.

Facebook's Graph API Objects

User

data User Source

A Facebook user profile (see https://developers.facebook.com/docs/reference/api/user/).

NOTE: We still don't support all fields supported by Facebook. Please fill an issue if you need access to any other fields.

type UserId = ByteStringSource

A Facebook user id such as 1008905713901.

data Gender Source

An user's gender.

Constructors

Male 
Female 

getUserSource

Arguments

:: (MonadResource m, MonadBaseControl IO m) 
=> UserId

User ID or "me".

-> [Argument]

Arguments to be passed to Facebook.

-> Maybe UserAccessToken

Optional user access token.

-> FacebookT anyAuth m User 

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 "me", in which case you must provide an user access token and information about the token's owner is given.

Page

getPageSource

Arguments

:: (MonadResource m, MonadBaseControl IO m) 
=> ByteString

Page ID

-> [Argument]

Arguments to be passed to Facebook

-> Maybe UserAccessToken

Optional user access token

-> FacebookT anyAuth m Page 

Get a page using its ID. The user access token is optional.

searchPagesSource

Arguments

:: (MonadResource m, MonadBaseControl IO m) 
=> ByteString

Keyword to search for

-> [Argument]

Arguments to pass to Facebook

-> Maybe UserAccessToken

Optional user access token

-> FacebookT anyAuth m (SearchResultPage Page) 

Search pages by keyword. The user access token is optional.

Facebook's Open Graph API

Actions

createActionSource

Arguments

:: (MonadResource m, MonadBaseControl IO m) 
=> Action

Action kind to be created.

-> [Argument]

Arguments of the action.

-> Maybe AppAccessToken

Optional app access token (optional with respect to this library, since you can't make this mandatory by changing the settings of your action on Facebook).

-> UserAccessToken

Required user access token.

-> FacebookT Auth m Id 

Creates an Open Graph action on the user's timeline. Returns the Id of the newly created action. For example:

 now <- liftIO getCurrentTime
 createAction "cook"
              [ "recipe" #= "http://example.com/cookie.html"
              , "when"   #= now ]
              token

data Action Source

An action of your app. Please refer to Facebook's documentation at https://developers.facebook.com/docs/opengraph/keyconcepts/#actions-objects to see how you can create actions.

This is a newtype of ByteString that supports only IsString. This means that to create an Action you should use the OverloadedStrings language extension. For example,

 {-# LANGUAGE OverloadedStrings #-}

 foo token = do
   ...
   createAction "cook" [...] token

Instances

Eq Action

Since 0.7.1

Ord Action

Since 0.7.1

Read Action

Since 0.7.1

Show Action 
IsString Action 

Checkins

createCheckinSource

Arguments

:: (MonadResource m, MonadBaseControl IO m) 
=> Id

Place Id

-> (Double, Double)

(Latitude, Longitude)

-> [Argument]

Other arguments of the action.

-> UserAccessToken

Required user access token.

-> FacebookT Auth m Id 

Creates a 'check-in' and returns its id. Place and coordinates are both required by Facebook.

FQL

fqlQuerySource

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) 
=> Text

FQL Query

-> Maybe (AccessToken anyKind)

Optional access token

-> FacebookT anyAuth m a 

Query the Facebook Graph using FQL. You may want to use FQLResult when parsing the returned JSON.

newtype FQLResult a Source

Parses an FQL query result. FQL query results are always of the form

   { data: [ret1, ret2, ...] }

This newtype unwraps the array from the data field automatically for you, so you may write something like:

   FQLResult [...] <- fqlQuery ...

Constructors

FQLResult [a] 

Instances

Eq a => Eq (FQLResult a) 
Ord a => Ord (FQLResult a) 
Read a => Read (FQLResult a) 
Show a => Show (FQLResult a) 
FromJSON a => FromJSON (FQLResult a) 

Helpers

(#=) :: SimpleType a => ByteString -> a -> ArgumentSource

Create an Argument with a SimpleType. See the docs on createAction for an example.

class SimpleType a whereSource

Class for data types that may be represented as a Facebook simple type. (see https://developers.facebook.com/docs/opengraph/simpletypes/).

Instances

SimpleType Bool

Facebook's simple type Boolean.

SimpleType Double

Facebook's simple type Float.

SimpleType Float

Facebook's simple type Float with less precision than supported.

SimpleType Int

Facebook's simple type Integer.

SimpleType Int8

Facebook's simple type Integer.

SimpleType Int16

Facebook's simple type Integer.

SimpleType Int32

Facebook's simple type Integer.

SimpleType Word

Facebook's simple type Integer.

SimpleType Word8

Facebook's simple type Integer.

SimpleType Word16

Facebook's simple type Integer.

SimpleType Word32

Facebook's simple type Integer.

SimpleType Text

Facebook's simple type String.

SimpleType UTCTime

Facebook's simple type DateTime.

SimpleType ByteString

Facebook's simple type String.

SimpleType ZonedTime

Facebook's simple type DateTime.

SimpleType Day

Facebook's simple type DateTime with only the date.

SimpleType Id

An object's Id code.

SimpleType a => SimpleType [a]

A comma-separated list of simple types. This definition doesn't work everywhere, just for a few combinations that Facebook uses (e.g. [Int]). Also, encoding a list of lists is the same as encoding the concatenation of all lists. In other words, this instance is here more for your convenience than to make sure your code is correct.

Real-time update notifications

Subscriptions

modifySubscriptionSource

Arguments

:: (MonadResource m, MonadBaseControl IO m) 
=> RealTimeUpdateObject

Type of objects whose subscription you and to add or modify.

-> [RealTimeUpdateField]

Fields that you are interested in receiving updates.

-> RealTimeUpdateUrl

Your callback URL.

-> RealTimeUpdateToken

A verification token.

-> AppAccessToken

Access token for your app.

-> FacebookT Auth m () 

Add or modify a subscription for real-time updates. If there were no previous subscriptions for the given RealTimeUpdateObject, then a new subscription is created. If there was any previous subscription for the given RealTimeUpdateObject, it's overriden by this one (even if the other subscription had a different callback URL).

listSubscriptions :: (MonadResource m, MonadBaseControl IO m) => AppAccessToken -> FacebookT Auth m [RealTimeUpdateSubscription]Source

List current real-time update subscriptions.

type RealTimeUpdateField = ByteStringSource

A field of a RealTimeUpdateObject that you would like to receive notifications when changed.

type RealTimeUpdateUrl = TextSource

The URL on your server that will receive the real-time updates. Please refer to Facebook's documentation in order to see what this URL needs to implement.

type RealTimeUpdateToken = ByteStringSource

A token that is sent back by Facebook's servers to your server in order to verify that you really were trying to modify your subscription.

Notifications

verifyRealTimeUpdateNotificationsSource

Arguments

:: Monad m 
=> ByteString

X-Hub-Signature HTTP header's value.

-> ByteString

Request body with JSON-encoded notifications.

-> FacebookT Auth m (Maybe ByteString) 

Verifies the input's authenticity (i.e. it comes from Facebook) and integrity by calculating its HMAC-SHA1 (using your application secret as the key) and verifying that it matches the value from the HTTP request's X-Hub-Signature header's value. If it's not valid, Nothing is returned, otherwise Just data is returned where data is the original data.

getRealTimeUpdateNotificationsSource

Arguments

:: (Monad m, FromJSON a) 
=> ByteString

X-Hub-Signature HTTP header's value.

-> ByteString

Request body with JSON-encoded notifications.

-> FacebookT Auth m (Maybe (RealTimeUpdateNotification a)) 

Same as verifyRealTimeUpdateNotifications but also parses the response as JSON. Returns Nothing if either the signature is invalid or the data can't be parsed (use verifyRealTimeUpdateNotifications if you need to distinguish between these two error conditions).

data RealTimeUpdateNotification a Source

When data changes and there's a valid subscription, Facebook will POST to your RealTimeUpdateUrl with a JSON-encoded object containing the notifications. A 'RealTimeUpdateNotification a' represents such object where a is type of the entries (e.g., RealTimeUpdateNotificationUserEntry).

If you have a single RealTimeUpdateUrl for different kinds of notifications, you may parse a RealTimeUpdateNotification Value and then manually parse the Value depending on the value of rtunObject.

We recommend using getRealTimeUpdateNotifications.

Raw access to the Graph API

getObjectSource

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) 
=> ByteString

Path (should begin with a slash /)

-> [Argument]

Arguments to be passed to Facebook

-> Maybe (AccessToken anyKind)

Optional access token

-> FacebookT anyAuth m a 

Make a raw GET request to Facebook's Graph API.

postObjectSource

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) 
=> ByteString

Path (should begin with a slash /)

-> [Argument]

Arguments to be passed to Facebook

-> AccessToken anyKind

Access token

-> FacebookT Auth m a 

Make a raw POST request to Facebook's Graph API.

newtype Id Source

The identification code of an object.

Constructors

Id 

Fields

idCode :: ByteString
 

Instances

Eq Id 
Ord Id 
Read Id 
Show Id 
Typeable Id 
FromJSON Id 
SimpleType Id

An object's Id code.

type Argument = (ByteString, ByteString)Source

An argument given to an API call.

searchObjectsSource

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) 
=> ByteString

A Facebook object type to search for

-> ByteString

The keyword to search for

-> [Argument]

Additional arguments to pass

-> Maybe UserAccessToken

Optional access token

-> FacebookT anyAuth m (SearchResultPage a) 

Make a raw GET request to the /search endpoint of Facebook’s Graph API. Returns a raw JSON Value.

data SearchResultPage a Source

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.

Constructors

SearchResultPage 

Fields

searchResults :: [a]
 
searchPage :: Maybe Pager
 

Exceptions

data FacebookException Source

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

Constructors

FacebookException

An exception coming from Facebook.

Fields

fbeType :: Text
 
fbeMessage :: Text
 
FbLibraryException

An exception coming from the fb package's code.

Fields

fbeMessage :: Text
 

Internal functions

unPermission :: Permission -> TextSource

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