fb-0.14.8: Bindings to Facebook's API.

Safe Haskell | None

Facebook

Contents

- `FacebookT` monad transformer
- Authorization and Authentication
  - Credentials
  - Access token
  - App access token
  - User access token
  - Signed requests
- Facebook's Graph API
  - User
  - Page
  - Actions
  - Checkins
  - Order
- Facebook's Graph API basic functionality
  - Simple types
  - Complex types
  - Pagination
- Real-time update notifications
  - Subscriptions
  - Notifications
- FQL
- Test User API
- Raw access to the Graph API
- Exceptions
- Internal functions

Synopsis

- data FacebookT auth m a
- runFacebookT :: Credentials -> Manager -> FacebookT Auth m a -> m a
- runNoAuthFacebookT :: Manager -> FacebookT NoAuth m a -> m a
- mapFacebookT :: (m a -> n b) -> FacebookT anyAuth m a -> FacebookT anyAuth n b
- beta_runFacebookT :: Credentials -> Manager -> FacebookT Auth m a -> m a
- beta_runNoAuthFacebookT :: Manager -> FacebookT NoAuth m a -> m a
- data Auth
- data NoAuth
- data Credentials = Credentials {
  - appName :: Text
  - appId :: Text
  - appSecret :: Text
  }
- data AccessToken kind where
  - UserAccessToken :: UserId -> AccessTokenData -> UTCTime -> AccessToken UserKind
  - AppAccessToken :: AccessTokenData -> AccessToken AppKind
- type UserAccessToken = AccessToken UserKind
- type AppAccessToken = AccessToken AppKind
- type AccessTokenData = Text
- hasExpired :: (Functor m, MonadIO m) => AccessToken anyKind -> m Bool
- isValid :: (MonadBaseControl IO m, MonadResource m) => AccessToken anyKind -> FacebookT anyAuth m Bool
- data AppKind
- getAppAccessToken :: (MonadResource m, MonadBaseControl IO m) => FacebookT Auth m AppAccessToken
- data UserKind
- type RedirectUrl = Text
- data Permission
- getUserAccessTokenStep1 :: Monad m => RedirectUrl -> [Permission] -> FacebookT Auth m Text
- getUserAccessTokenStep2 :: (MonadBaseControl IO m, MonadResource m) => RedirectUrl -> [Argument] -> FacebookT Auth m UserAccessToken
- getUserLogoutUrl :: Monad m => UserAccessToken -> RedirectUrl -> FacebookT Auth m Text
- extendUserAccessToken :: (MonadBaseControl IO m, MonadResource m) => UserAccessToken -> FacebookT Auth m (Either FacebookException UserAccessToken)
- debugToken :: (MonadBaseControl IO m, MonadResource m) => AppAccessToken -> AccessTokenData -> FacebookT Auth m DebugToken
- data DebugToken = DebugToken {
  - dtAppId :: Maybe Text
  - dtAppName :: Maybe Text
  - dtExpiresAt :: Maybe UTCTime
  - dtIsValid :: Maybe Bool
  - dtIssuedAt :: Maybe UTCTime
  - dtScopes :: Maybe [Permission]
  - dtUserId :: Maybe Id
  - dtAccessToken :: Maybe UserAccessToken
  }
- parseSignedRequest :: (FromJSON a, Monad m) => ByteString -> FacebookT Auth m (Maybe a)
- data User = User {
  - userId :: UserId
  - userName :: Maybe Text
  - userFirstName :: Maybe Text
  - userMiddleName :: Maybe Text
  - userLastName :: Maybe Text
  - userGender :: Maybe Gender
  - userLocale :: Maybe Text
  - userUsername :: Maybe Text
  - userVerified :: Maybe Bool
  - userEmail :: Maybe Text
  - userLocation :: Maybe Place
  }
- type UserId = Id
- data Gender
  - = Male
  - | Female
- getUser :: (MonadResource m, MonadBaseControl IO m) => UserId -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m User
- searchUsers :: (MonadResource m, MonadBaseControl IO m) => Text -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m (Pager User)
- getUserCheckins :: (MonadResource m, MonadBaseControl IO m) => UserId -> [Argument] -> UserAccessToken -> FacebookT anyAuth m (Pager Checkin)
- data Friend = Friend {
  - friendId :: UserId
  - friendName :: Text
  }
- getUserFriends :: (MonadResource m, MonadBaseControl IO m) => UserId -> [Argument] -> UserAccessToken -> FacebookT anyAuth m (Pager Friend)
- data Page = Page {
  - pageId :: Id
  - pageName :: Maybe Text
  - pageLink :: Maybe Text
  - pageCategory :: Maybe Text
  - pageIsPublished :: Maybe Bool
  - pageCanPost :: Maybe Bool
  - pageLikes :: Maybe Integer
  - pageLocation :: Maybe Location
  - pagePhone :: Maybe Text
  - pageCheckins :: Maybe Integer
  - pagePicture :: Maybe Text
  - pageWebsite :: Maybe Text
  - pageTalkingAboutCount :: Maybe Integer
  }
- getPage :: (MonadResource m, MonadBaseControl IO m) => Id -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m Page
- searchPages :: (MonadResource m, MonadBaseControl IO m) => Text -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m (Pager Page)
- data Action
- createAction :: (MonadResource m, MonadBaseControl IO m) => Action -> [Argument] -> Maybe AppAccessToken -> UserAccessToken -> FacebookT Auth m Id
- data Checkin = Checkin {
  - checkinId :: Id
  - checkinFrom :: Maybe CheckinFrom
  - checkinPlace :: Maybe Place
  - checkinCreatedTime :: Maybe UTCTime
  - checkinTags :: Maybe (Pager Tag)
  - checkinMessage :: Maybe Text
  }
- data CheckinFrom = CheckinFrom {
  - checkinFromId :: UserId
  - checkinFromName :: Text
  }
- getCheckin :: (MonadResource m, MonadBaseControl IO m) => Id -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m Checkin
- createCheckin :: (MonadResource m, MonadBaseControl IO m) => Id -> GeoCoordinates -> [Argument] -> UserAccessToken -> FacebookT Auth m Id
- data Order = Order {
  - orderId :: OrderId
  - orderFrom :: UserId
  - orderTo :: UserId
  - orderAmount :: Integer
  - orderStatus :: OrderStatus
  - orderApplication :: OrderApplication
  - orderCountry :: Text
  - orderRefundCode :: Maybe Text
  - orderCreatedTime :: ZonedTime
  - orderUpdatedTime :: ZonedTime
  }
- type OrderId = Id
- data OrderApplication
- data OrderStatus
- getOrder :: (MonadResource m, MonadBaseControl IO m) => OrderId -> UserAccessToken -> FacebookT anyAuth m Order
- (#=) :: SimpleType a => ByteString -> a -> Argument
- class SimpleType a where
  - encodeFbParam :: a -> ByteString
- newtype FbUTCTime = FbUTCTime {
  - unFbUTCTime :: UTCTime
  }
- data Place = Place {
  - placeId :: Id
  - placeName :: Maybe Text
  - placeLocation :: Maybe Location
  }
- data Location = Location {
  - locationStreet :: Maybe Text
  - locationCity :: Maybe Text
  - locationState :: Maybe Text
  - locationCountry :: Maybe Text
  - locationZip :: Maybe Text
  - locationCoords :: Maybe GeoCoordinates
  }
- data GeoCoordinates = GeoCoordinates {
  - latitude :: !Double
  - longitude :: !Double
  }
- data Tag = Tag {
  - tagId :: Id
  - tagName :: Text
  }
- data Pager a = Pager {
  - pagerData :: [a]
  - pagerPrevious :: Maybe String
  - pagerNext :: Maybe String
  }
- fetchNextPage :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Pager a -> FacebookT anyAuth m (Maybe (Pager a))
- fetchPreviousPage :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Pager a -> FacebookT anyAuth m (Maybe (Pager a))
- fetchAllNextPages :: (Monad m, MonadResourceBase n, FromJSON a) => Pager a -> FacebookT anyAuth m (Source n a)
- fetchAllPreviousPages :: (Monad m, MonadResourceBase n, FromJSON a) => Pager a -> FacebookT anyAuth m (Source n a)
- modifySubscription :: (MonadResource m, MonadBaseControl IO m) => RealTimeUpdateObject -> [RealTimeUpdateField] -> RealTimeUpdateUrl -> RealTimeUpdateToken -> AppAccessToken -> FacebookT Auth m ()
- listSubscriptions :: (MonadResource m, MonadBaseControl IO m) => AppAccessToken -> FacebookT Auth m [RealTimeUpdateSubscription]
- data RealTimeUpdateObject
  - = UserRTUO
  - | PermissionsRTUO
  - | PageRTUO
  - | ErrorsRTUO
  - | OtherRTUO Text
- type RealTimeUpdateField = ByteString
- type RealTimeUpdateUrl = Text
- type RealTimeUpdateToken = ByteString
- data RealTimeUpdateSubscription = RealTimeUpdateSubscription {
  - rtusObject :: RealTimeUpdateObject
  - rtusCallbackUrl :: RealTimeUpdateUrl
  - rtusFields :: [RealTimeUpdateField]
  - rtusActive :: Bool
  }
- verifyRealTimeUpdateNotifications :: Monad m => ByteString -> ByteString -> FacebookT Auth m (Maybe ByteString)
- getRealTimeUpdateNotifications :: (Monad m, FromJSON a) => ByteString -> ByteString -> FacebookT Auth m (Maybe (RealTimeUpdateNotification a))
- data RealTimeUpdateNotification a = RealTimeUpdateNotification {
  - rtunObject :: RealTimeUpdateObject
  - rtunEntries :: [a]
  }
- data RealTimeUpdateNotificationUserEntry = RealTimeUpdateNotificationUserEntry {
  - rtuneUserId :: Id
  - rtuneChangedFields :: [RealTimeUpdateField]
  - rtuneTime :: Integer
  }
- fqlQuery :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Text -> Maybe (AccessToken anyKind) -> FacebookT anyAuth m (Pager a)
- newtype FQLTime = FQLTime {
  - unFQLTime :: UTCTime
  }
- newtype FQLList a = FQLList {
  - unFQLList :: [a]
  }
- newtype FQLObject a = FQLObject {
  - unFQLObject :: a
  }
- getTestUsers :: (MonadResource m, MonadBaseControl IO m) => AppAccessToken -> FacebookT Auth m (Pager TestUser)
- removeTestUser :: (MonadResource m, MonadBaseControl IO m) => TestUser -> AppAccessToken -> FacebookT Auth m Bool
- createTestUser :: (MonadResource m, MonadBaseControl IO m) => CreateTestUser -> AppAccessToken -> FacebookT Auth m TestUser
- makeFriendConn :: (MonadResource m, MonadBaseControl IO m) => TestUser -> TestUser -> FacebookT Auth m ()
- incompleteTestUserAccessToken :: TestUser -> Maybe UserAccessToken
- data TestUser = TestUser {
  - tuId :: UserId
  - tuAccessToken :: Maybe AccessTokenData
  - tuLoginUrl :: Maybe Text
  - tuEmail :: Maybe Text
  - tuPassword :: Maybe Text
  }
- data CreateTestUser = CreateTestUser {
  - ctuInstalled :: CreateTestUserInstalled
  - ctuName :: Maybe Text
  - ctuLocale :: Maybe Text
  }
- data CreateTestUserInstalled
  - = CreateTestUserNotInstalled
  - | CreateTestUserInstalled {
    - ctuiPermissions :: [Permission]
    }
  - | CreateTestUserFbDefault
- getObject :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Text -> [Argument] -> Maybe (AccessToken anyKind) -> FacebookT anyAuth m a
- postObject :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Text -> [Argument] -> AccessToken anyKind -> FacebookT Auth m a
- deleteObject :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Text -> [Argument] -> AccessToken anyKind -> FacebookT Auth m a
- searchObjects :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Text -> Text -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m (Pager a)
- newtype Id = Id {
  - idCode :: Text
  }
- type Argument = (ByteString, ByteString)
- data FacebookException
  - = FacebookException {
    - fbeType :: Text
    - fbeMessage :: Text
    }
  - | FbLibraryException {
    - fbeMessage :: Text
    }
- unPermission :: Permission -> Text

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

MonadBaseControl b m => MonadBaseControl b (FacebookT auth m) |
MonadBase b m => MonadBase b (FacebookT auth m) |
MonadTrans (FacebookT auth) |
MonadTransControl (FacebookT auth) |
Monad m => Monad (FacebookT auth m) |
Functor m => Functor (FacebookT auth m) |
MonadFix m => MonadFix (FacebookT auth m) |
MonadPlus m => MonadPlus (FacebookT auth m) |
Applicative m => Applicative (FacebookT auth m) |
Alternative m => Alternative (FacebookT auth m) |
MonadThrow m => MonadThrow (FacebookT auth m) |
MonadResource m => MonadResource (FacebookT auth m) |
MonadLogger m => MonadLogger (FacebookT auth m) | Since `fb-0.14.8`.
MonadActive m => MonadActive (FacebookT auth m) |
MonadIO m => MonadIO (FacebookT auth m) |

runFacebookT Source

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

beta_runFacebookT :: Credentials -> Manager -> FacebookT Auth m a -> m aSource

Same as `runFacebookT`, but uses Facebook's beta tier (see https://developers.facebook.com/support/beta-tier/).

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

Same as `runNoAuthFacebookT`, but uses Facebook's beta tier (see https://developers.facebook.com/support/beta-tier/).

data Auth Source

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

Instances

Typeable Auth |

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

Typeable NoAuth |

# Authorization and Authentication

## Credentials

data Credentials Source

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

Constructors

Credentials |

Fields

appName :: Text

  Your application name (e.g. for Open Graph calls).

appId :: Text

  Your application ID.

appSecret :: Text

  Your application secret key.

Instances

Eq Credentials |
Ord Credentials |
Read Credentials |
Show Credentials |
Typeable Credentials |

## Access token

data AccessToken kind where Source

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

Constructors

UserAccessToken :: UserId -> AccessTokenData -> UTCTime -> AccessToken UserKind |
AppAccessToken :: AccessTokenData -> AccessToken AppKind |

Instances

Typeable1 AccessToken |
Eq (AccessToken kind) |
Ord (AccessToken kind) |
Show (AccessToken kind) |

type UserAccessToken = AccessToken UserKind Source

Type synonym for ``AccessToken` `UserKind``.

type AppAccessToken = AccessToken AppKind Source

Type synonym for ``AccessToken` `AppKind``.

type AccessTokenData = Text Source

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

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

`True` if the access token has expired, otherwise `False`.

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

`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

Typeable AppKind |

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

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

Typeable UserKind |

type RedirectUrl = Text Source

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

Instances

Eq Permission |
Ord Permission |
Show Permission |
IsString Permission |
SimpleType Permission | `Permission` is a `newtype` of `Text`

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

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

getUserAccessTokenStep2 Source

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

getUserLogoutUrl Source

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.

debugToken Source

Arguments

:: (MonadBaseControl IO m, MonadResource m) |
=> AppAccessToken | Your app access token.
-> AccessTokenData | The access token you want to debug.
-> FacebookT Auth m DebugToken |

Get detailed information about an access token.

data DebugToken Source

Detailed information about an access token (cf. `debugToken`).

Constructors

DebugToken |

Fields

dtAppId :: Maybe Text
dtAppName :: Maybe Text
dtExpiresAt :: Maybe UTCTime
dtIsValid :: Maybe Bool
dtIssuedAt :: Maybe UTCTime
dtScopes :: Maybe [Permission]
dtUserId :: Maybe Id
dtAccessToken :: Maybe UserAccessToken

Instances

Eq DebugToken |
Ord DebugToken |
Show DebugToken |
Typeable DebugToken |
FromJSON DebugToken | Note: this instance always sets `dtAccessToken` to `Nothing`, but `debugToken` will update this field before returning the final `DebugToken`. This is done because we need the `AccessTokenData`, which is not part of FB's response.

## Signed requests

parseSignedRequest Source

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

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

Constructors

User |

Fields

userId :: UserId
userName :: Maybe Text
userFirstName :: Maybe Text
userMiddleName :: Maybe Text
userLastName :: Maybe Text
userGender :: Maybe Gender
userLocale :: Maybe Text
userUsername :: Maybe Text
userVerified :: Maybe Bool
userEmail :: Maybe Text
userLocation :: Maybe Place

Instances

Eq User |
Ord User |
Read User |
Show User |
Typeable User |
FromJSON User |

type UserId = Id Source

A Facebook user ID such as `1008905713901`.

data Gender Source

An user's gender.

Constructors

Male |
Female |

Instances

Enum Gender |
Eq Gender |
Ord Gender |
Read Gender |
Show Gender |
Typeable Gender |
ToJSON Gender |
FromJSON Gender |

getUser Source

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.

searchUsers :: (MonadResource m, MonadBaseControl IO m) => Text -> [Argument] -> Maybe UserAccessToken -> FacebookT anyAuth m (Pager User)Source

Search users by keyword.

getUserCheckins Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> UserId | User ID or `"me"`.
-> [Argument] | Arguments to be passed to Facebook.
-> UserAccessToken | User access token.
-> FacebookT anyAuth m (Pager Checkin) |

Get a list of check-ins made by a given user.

data Friend Source

A friend connection of a `User`.

Constructors

Friend |

Fields

friendId :: UserId
friendName :: Text

Instances

Eq Friend |
Ord Friend |
Read Friend |
Show Friend |
Typeable Friend |
FromJSON Friend |

getUserFriends Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> UserId | User ID or `"me"`.
-> [Argument] | Arguments to be passed to Facebook.
-> UserAccessToken | User access token.
-> FacebookT anyAuth m (Pager Friend) |

Get the list of friends of the given user.

## Page

data Page Source

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

NOTE: Does not yet support all fields. Please file an issue if you need any other fields.

Constructors

Page |

Fields

pageId :: Id
pageName :: Maybe Text
pageLink :: Maybe Text
pageCategory :: Maybe Text
pageIsPublished :: Maybe Bool
pageCanPost :: Maybe Bool
pageLikes :: Maybe Integer
pageLocation :: Maybe Location
pagePhone :: Maybe Text
pageCheckins :: Maybe Integer
pagePicture :: Maybe Text
pageWebsite :: Maybe Text
pageTalkingAboutCount :: Maybe Integer

Instances

Eq Page |
Ord Page |
Read Page |
Show Page |
Typeable Page |
FromJSON Page |

getPage Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> Id | 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.

searchPages Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> Text | Keyword to search for
-> [Argument] | Arguments to pass to Facebook
-> Maybe UserAccessToken | Optional user access token
-> FacebookT anyAuth m (Pager Page) |

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

## Actions

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

createAction Source

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

## Checkins

data Checkin Source

A Facebook check-in (see https://developers.facebook.com/docs/reference/api/checkin/).

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

Constructors

Checkin |

Fields

checkinId :: Id
checkinFrom :: Maybe CheckinFrom
checkinPlace :: Maybe Place
checkinCreatedTime :: Maybe UTCTime
checkinTags :: Maybe (Pager Tag)
checkinMessage :: Maybe Text

Instances

Eq Checkin |
Ord Checkin |
Read Checkin |
Show Checkin |
Typeable Checkin |
FromJSON Checkin |

data CheckinFrom Source

Information about the user who made the check-in.

Constructors

CheckinFrom |

Fields

checkinFromId :: UserId
checkinFromName :: Text

Instances

Eq CheckinFrom |
Ord CheckinFrom |
Read CheckinFrom |
Show CheckinFrom |
Typeable CheckinFrom |
FromJSON CheckinFrom |

getCheckin Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> Id | Checkin ID.
-> [Argument] | Arguments to be passed to Facebook.
-> Maybe UserAccessToken | Optional user access token.
-> FacebookT anyAuth m Checkin |

Get a checkin from its ID. The user access token is optional, but when provided more information can be returned back by Facebook.

createCheckin Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> Id | Place ID.
-> GeoCoordinates | Coordinates.
-> [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.

## Order

data Order Source

A Facebook `Order` oject.

Constructors

Order |

Fields

orderId :: OrderId
orderFrom :: UserId
orderTo :: UserId
orderAmount :: Integer
orderStatus :: OrderStatus
orderApplication :: OrderApplication
orderCountry :: Text
orderRefundCode :: Maybe Text
orderCreatedTime :: ZonedTime
orderUpdatedTime :: ZonedTime

Instances

Show Order |
Typeable Order |
FromJSON Order |

type OrderId = Id Source

`Order` Id type.

data OrderApplication Source

A trimmed down version of Facebook Application as it is used in `Order`.

Instances

Show OrderApplication |
Typeable OrderApplication |
FromJSON OrderApplication |

data OrderStatus Source

A Facebook `Order` status type.

Instances

Enum OrderStatus |
Eq OrderStatus |
Show OrderStatus |
Typeable OrderStatus |
FromJSON OrderStatus |

getOrder Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> OrderId | Order ID.
-> UserAccessToken | User access token.
-> FacebookT anyAuth m Order |

Get an `Order` using its `OrderId`. The user access token is mandatory.

# Facebook's Graph API basic functionality

## Simple types

(#=) :: SimpleType a => ByteString -> a -> Argument Source

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

class SimpleType a where Source

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

Methods

encodeFbParam :: a -> ByteString Source

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 Int64 | 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 Word64 | Facebook's simple type `Integer`.
SimpleType ByteString | Facebook's simple type `String`.
SimpleType Text | Facebook's simple type `String`.
SimpleType UTCTime | Facebook's simple type `DateTime`.
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 Permission | `Permission` is a `newtype` of `Text`
SimpleType GeoCoordinates |
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.

newtype FbUTCTime Source

`newtype` for `UTCTime` that follows Facebook's conventions of JSON parsing.

- As a string, while `aeson` expects a format of `%FT%T%Q`, Facebook gives time values formatted as `%FT%T%z`.
- As a number, `FbUTCTime` accepts a number of seconds since the Unix epoch.

Constructors

FbUTCTime |

Fields

unFbUTCTime :: UTCTime

Instances

Eq FbUTCTime |
Ord FbUTCTime |
Read FbUTCTime |
Show FbUTCTime |
Typeable FbUTCTime |
FromJSON FbUTCTime |

## Complex types

data Place Source

Information about a place. This is not a Graph Object, instead it's just a field of a Object. (Not to be confused with the `Page` object.)

Constructors

Place |

Fields

placeId :: Id

  `Page` ID.

placeName :: Maybe Text

  `Page` name.

placeLocation :: Maybe Location

Instances

Eq Place |
Ord Place |
Read Place |
Show Place |
Typeable Place |
FromJSON Place |

data Location Source

A geographical location.

Constructors

Location |

Fields

locationStreet :: Maybe Text
locationCity :: Maybe Text
locationState :: Maybe Text
locationCountry :: Maybe Text
locationZip :: Maybe Text
locationCoords :: Maybe GeoCoordinates

Instances

Eq Location |
Ord Location |
Read Location |
Show Location |
Typeable Location |
FromJSON Location |

data GeoCoordinates Source

Geographical coordinates.

Constructors

GeoCoordinates |

Fields

latitude :: !Double
longitude :: !Double

Instances

Eq GeoCoordinates |
Ord GeoCoordinates |
Read GeoCoordinates |
Show GeoCoordinates |
Typeable GeoCoordinates |
FromJSON GeoCoordinates |
SimpleType GeoCoordinates |

data Tag Source

A tag (i.e. "I'll tag you on my post").

Constructors

Tag |

Fields

tagId :: Id

  Who is tagged.

tagName :: Text

  Name of the tagged person.

Instances

Eq Tag |
Ord Tag |
Read Tag |
Show Tag |
Typeable Tag |
FromJSON Tag |

## Pagination

data Pager a Source

Many Graph API results are returned as a JSON object with the following structure:

     {
       "data": [
         ...item 1...,
              :
         ...item n...
       ],
       "paging": {
         "previous": "http:...link to previous page...",
         "next":     "http:...link to next page..."
       }
     }

Only the `"data"` field is required, the others may or may not appear.

A `Pager a` datatype encodes such result where each item has type `a`. You may use functions `fetchNextPage` and `fetchPreviousPage` to navigate through the results.

Constructors

Pager |

Fields

pagerData :: [a]
pagerPrevious :: Maybe String
pagerNext :: Maybe String

Instances

Typeable1 Pager |
Eq a => Eq (Pager a) |
Ord a => Ord (Pager a) |
Read a => Read (Pager a) |
Show a => Show (Pager a) |
FromJSON a => FromJSON (Pager a) |

fetchNextPage :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Pager a -> FacebookT anyAuth m (Maybe (Pager a))Source

Tries to fetch the next page of a `Pager`. Returns `Nothing` whenever the current `Pager` does not have a `pagerNext`.

fetchPreviousPage :: (MonadResource m, MonadBaseControl IO m, FromJSON a) => Pager a -> FacebookT anyAuth m (Maybe (Pager a))Source

Tries to fetch the previous page of a `Pager`. Returns `Nothing` whenever the current `Pager` does not have a `pagerPrevious`.

fetchAllNextPages :: (Monad m, MonadResourceBase n, FromJSON a) => Pager a -> FacebookT anyAuth m (Source n a)Source

Tries to fetch all next pages and returns a `Source` with all results. The `Source` will include the results from this page as well. Previous pages will not be considered. Next pages will be fetched on-demand.

fetchAllPreviousPages :: (Monad m, MonadResourceBase n, FromJSON a) => Pager a -> FacebookT anyAuth m (Source n a)Source

Tries to fetch all previous pages and returns a `Source` with all results. The `Source` will include the results from this page as well. Next pages will not be considered. Previous pages will be fetched on-demand.

# Real-time update notifications

## Subscriptions

modifySubscription Source

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.

data RealTimeUpdateObject Source

The type of objects that a real-time update refers to.

Constructors

UserRTUO |
PermissionsRTUO |
PageRTUO |
ErrorsRTUO |
OtherRTUO Text |

Instances

Eq RealTimeUpdateObject |
Ord RealTimeUpdateObject |
Show RealTimeUpdateObject |
Typeable RealTimeUpdateObject |
ToJSON RealTimeUpdateObject |
FromJSON RealTimeUpdateObject |

type RealTimeUpdateField = ByteString Source

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

type RealTimeUpdateUrl = Text Source

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 = ByteString Source

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.

data RealTimeUpdateSubscription Source

Information returned by Facebook about a real-time update notification subscription.

Constructors

RealTimeUpdateSubscription |

Fields

rtusObject :: RealTimeUpdateObject
rtusCallbackUrl :: RealTimeUpdateUrl
rtusFields :: [RealTimeUpdateField]
rtusActive :: Bool

Instances

Eq RealTimeUpdateSubscription |
Ord RealTimeUpdateSubscription |
Show RealTimeUpdateSubscription |
Typeable RealTimeUpdateSubscription |
FromJSON RealTimeUpdateSubscription |

## Notifications

verifyRealTimeUpdateNotifications Source

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.

getRealTimeUpdateNotifications Source

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

Constructors

RealTimeUpdateNotification |

Fields

rtunObject :: RealTimeUpdateObject
rtunEntries :: [a]

Instances

Typeable1 RealTimeUpdateNotification |
Eq a => Eq (RealTimeUpdateNotification a) |
Ord a => Ord (RealTimeUpdateNotification a) |
Show a => Show (RealTimeUpdateNotification a) |
FromJSON a => FromJSON (RealTimeUpdateNotification a) |

data RealTimeUpdateNotificationUserEntry Source

A notification for the `UserRTUO` object.

Constructors

RealTimeUpdateNotificationUserEntry |

Fields

rtuneUserId :: Id
rtuneChangedFields :: [RealTimeUpdateField]
rtuneTime :: Integer

Instances

Eq RealTimeUpdateNotificationUserEntry |
Ord RealTimeUpdateNotificationUserEntry |
Show RealTimeUpdateNotificationUserEntry |
Typeable RealTimeUpdateNotificationUserEntry |
FromJSON RealTimeUpdateNotificationUserEntry |

# FQL

fqlQuery Source

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) |
=> Text | FQL Query
-> Maybe (AccessToken anyKind) | Optional access token
-> FacebookT anyAuth m (Pager a) |

Query the Facebook Graph using FQL.

newtype FQLTime Source

Deprecated: Deprecated since fb 0.14.7, please use FbUTCTime instead.

`newtype` wrapper around `UTCTime` that is able to parse FQL's time representation as seconds since the Unix epoch.

Constructors

FQLTime | Deprecated: Deprecated since fb 0.14.7, please use FbUTCTime instead.

Fields

unFQLTime :: UTCTime

Instances

Eq FQLTime |
Ord FQLTime |
Show FQLTime |
FromJSON FQLTime |

newtype FQLList a Source

`newtype` wrapper around lists that works around FQL's strange lists.

For example, if you fetch the `tagged_uids` field from `location_post`, you'll find that Facebook's FQL represents an empty list of tagged UIDs as plain JSON array (`[]`). However, it represents a singleton list as an object `{"1234": 1234}` instead of the much more correct `[1234]`.

On the other hand, not all FQL arrays are represented in this bogus manner. Also, some so-called arrays by FQL's documentation are actually objects, see `FQLObject`.

Constructors

FQLList |

Fields

unFQLList :: [a]

Instances

Eq a => Eq (FQLList a) |
Ord a => Ord (FQLList a) |
Show a => Show (FQLList a) |
FromJSON a => FromJSON (FQLList a) |

newtype FQLObject a Source

`newtype` wrapper around any object that works around FQL's strange objects.

For example, if you fetch the `app_data` field from `stream`, you'll find that empty objects are actually represented as empty lists `[]` instead of a proper empty object `{}`. Also note that FQL's documentation says that `app_data` is an array, which it clear is not. See also `FQLList`.

Constructors

FQLObject |

Fields

unFQLObject :: a

Instances

Eq a => Eq (FQLObject a) |
Ord a => Ord (FQLObject a) |
Show a => Show (FQLObject a) |
FromJSON a => FromJSON (FQLObject a) |

# Test User API

getTestUsers Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> AppAccessToken | Access token for your app.
-> FacebookT Auth m (Pager TestUser) |

Get a list of test users.

removeTestUser Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> TestUser | The TestUser to be removed.
-> AppAccessToken | Access token for your app (ignored since fb 0.14.7).
-> FacebookT Auth m Bool |

Remove an existing test user.

createTestUser Source

Arguments

:: (MonadResource m, MonadBaseControl IO m) |
=> CreateTestUser | How the test user should be created.
-> AppAccessToken | Access token for your app.
-> FacebookT Auth m TestUser |

Create a new test user.

makeFriendConn :: (MonadResource m, MonadBaseControl IO m) => TestUser -> TestUser -> FacebookT Auth m ()Source

Make a friend connection between two test users.

This is how Facebook's API work: two calls must be made. The first call has the format: "/userA_id/friends/userB_id" with the access token of user A as query parameter. The second call has the format: "/userB_id/friends/userA_id" with the access token of user B as query parameter. The first call creates a friend request and the second call accepts the friend request.

incompleteTestUserAccessToken :: TestUser -> Maybe UserAccessToken Source

Create an `UserAccessToken` from a `TestUser`. It's incomplete because it will not have the right expiration time.

data TestUser Source

A Facebook test user.

Constructors

TestUser |

Fields

tuId :: UserId
tuAccessToken :: Maybe AccessTokenData
tuLoginUrl :: Maybe Text
tuEmail :: Maybe Text
tuPassword :: Maybe Text

Instances

Eq TestUser |
Ord TestUser |
Read TestUser |
Show TestUser |
Typeable TestUser |
FromJSON TestUser |

data CreateTestUser Source

Data type used to hold information of a new test user. This type also accepts a Data.Default value.

Constructors

CreateTestUser |

Fields

ctuInstalled :: CreateTestUserInstalled
ctuName :: Maybe Text
ctuLocale :: Maybe Text

Instances

Default CreateTestUser | Default instance for `CreateTestUser`.

data CreateTestUserInstalled Source

Specify if the app is to be installed on the new test user. If it is, then you must tell what permissions should be given.

Constructors

CreateTestUserNotInstalled |
CreateTestUserInstalled |

Fields

ctuiPermissions :: [Permission]

CreateTestUserFbDefault | Uses Facebook's default. It seems that this is equivalent to `CreateTestUserInstalled []`, but Facebook's documentation is not clear about it.

Instances

Default CreateTestUserInstalled | Default instance for `CreateTestUserInstalled`.

# Raw access to the Graph API

getObject Source

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) |
=> Text | 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.

postObject Source

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) |
=> Text | 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.

deleteObject Source

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) |
=> Text | Path (should begin with a slash `/`)
-> [Argument] | Arguments to be passed to Facebook
-> AccessToken anyKind | Access token
-> FacebookT Auth m a |

Make a raw `DELETE` request to Facebook's Graph API.

searchObjects Source

Arguments

:: (MonadResource m, MonadBaseControl IO m, FromJSON a) |
=> Text | A Facebook object type to search for
-> Text | The keyword to search for
-> [Argument] | Additional arguments to pass
-> Maybe UserAccessToken | Optional access token
-> FacebookT anyAuth m (Pager a) |

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

newtype Id Source

The identification code of an object.

Constructors

Id |

Fields

idCode :: Text

Instances

Eq Id |
Ord Id |
Read Id |
Show Id |
Typeable Id |
IsString Id |
ToJSON Id |
FromJSON Id |
SimpleType Id | An object's `Id` code.

type Argument = (ByteString, ByteString)Source

An argument given to an API call.

# 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

Instances

Eq FacebookException |
Ord FacebookException |
Read FacebookException |
Show FacebookException |
Typeable FacebookException |
FromJSON FacebookException |
Exception FacebookException |

# Internal functions

unPermission :: Permission -> Text Source

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.