Copyright	(c) Will Sewell 2016
License	MIT
Maintainer	[email protected]
Stability	experimental
Safe Haskell	None
Language	Haskell2010

Network.Pusher

Contents

Data types
HTTP Requests
Authentication
Errors
Webhooks

Description

Exposes the functions necessary for interacting with the Pusher Channels HTTP API, as well as functions for generating auth signatures for private and presence channels.

First create a Pusher data structure with your Pusher Channels Credentials, and then call the functions defined in this module to make the HTTP requests.

If any of the requests fail, the return values of the functions will result in a Left PusherError when run.

An example of how you would use these functions:

  let
    credentials = Credentials
      { credentialsAppID     = 123
      , credentialsAppKey    = "wrd12344rcd234"
      , credentialsAppSecret = "124df34d545v"
      , credentialsCluster   = Nothing
      }
  pusher <- getPusher credentials

  triggerRes <-
    trigger pusher [Channel Public "my-channel"] "my-event" "my-data" Nothing

  case triggerRes of
    Left e -> putStrLn $ displayException e
    Right resp -> print resp

  -- import qualified Data.HashMap.Strict as H
  -- import qualified Data.Aeson          as A
  let
    -- A Firebase Cloud Messaging notification payload
    fcmObject = H.fromList [("notification", A.Object $ H.fromList
                                [("title", A.String "a title")
                                ,("body" , A.String "some text")
                                ,("icon" , A.String "logo.png")
                                ]
                            )]
    Just interest = mkInterest "some-interest"

    -- A Pusher Channels notification
    notification = Notification
      { notificationInterest     = interest
      , notificationWebhookURL   = Nothing
      , notificationWebhookLevel = Nothing
      , notificationAPNSPayload  = Nothing
      , notificationGCMPayload   = Nothing
      , notificationFCMPayload   = Just $ FCMPayload fcmObject
      }

  notifyRes <- notify pusher notification

There are simple working examples in the example/ directory.

See https://pusher.com/docs/channels/server_api/http-api for more detail on the HTTP requests.

Synopsis

data Pusher = Pusher {
- pusherHost :: Text
- pusherPath :: Text
- pusherNotifyHost :: Text
- pusherNotifyPath :: Text
- pusherCredentials :: Credentials
- pusherConnectionManager :: Manager
}
data Credentials = Credentials {
- credentialsAppID :: AppID
- credentialsAppKey :: AppKey
- credentialsAppSecret :: AppSecret
- credentialsCluster :: Maybe Cluster
}
newtype Cluster = Cluster {
- clusterName :: Text
}
type AppID = Integer
type AppKey = ByteString
type AppSecret = ByteString
getPusher :: MonadIO m => Credentials -> m Pusher
getPusherWithHost :: MonadIO m => Text -> Text -> Credentials -> m Pusher
getPusherWithConnManager :: Manager -> Maybe Text -> Maybe Text -> Credentials -> Pusher
data Channel = Channel {
- channelType :: ChannelType
- channelName :: ChannelName
}
type ChannelName = Text
data ChannelType
- = Public
- | Private
- | Presence
renderChannel :: Channel -> Text
renderChannelPrefix :: ChannelType -> Text
parseChannel :: Text -> Channel
type Event = Text
type EventData = Text
type SocketID = Text
data Notification = Notification {
- notificationInterest :: Interest
- notificationWebhookURL :: Maybe WebhookURL
- notificationWebhookLevel :: Maybe WebhookLevel
- notificationAPNSPayload :: Maybe APNSPayload
- notificationGCMPayload :: Maybe GCMPayload
- notificationFCMPayload :: Maybe FCMPayload
}
data Interest
mkInterest :: Text -> Maybe Interest
type WebhookURL = Text
data WebhookLevel
- = Info
- | Debug
data APNSPayload = APNSPayload Object
data GCMPayload = GCMPayload Object
data FCMPayload = FCMPayload Object
trigger :: MonadIO m => Pusher -> [Channel] -> Event -> EventData -> Maybe SocketID -> m (Either PusherError ())
channels :: MonadIO m => Pusher -> Maybe ChannelType -> Text -> ChannelsInfoQuery -> m (Either PusherError ChannelsInfo)
channel :: MonadIO m => Pusher -> Channel -> ChannelInfoQuery -> m (Either PusherError FullChannelInfo)
users :: MonadIO m => Pusher -> Channel -> m (Either PusherError Users)
notify :: MonadIO m => Pusher -> Notification -> m (Either PusherError ())
type AuthString = ByteString
type AuthSignature = ByteString
authenticatePresence :: ToJSON a => Credentials -> SocketID -> Channel -> a -> AuthSignature
authenticatePrivate :: Credentials -> SocketID -> Channel -> AuthSignature
data PusherError
- = PusherArgumentError Text
- | PusherNon200ResponseError Text
- | PusherInvalidResponseError Text
parseWebhookPayload :: Pusher -> [(ByteString, ByteString)] -> ByteString -> Maybe WebhookPayload
data WebhookEv
- = ChannelOccupiedEv {
  - onChannel :: Channel
  }
- | ChannelVacatedEv {
  - onChannel :: Channel
  }
- | MemberAddedEv {
  - onChannel :: Channel
  - withUser :: User
  }
- | MemberRemovedEv {
  - onChannel :: Channel
  - withUser :: User
  }
- | ClientEv {
  - onChannel :: Channel
  - clientEvName :: Text
  - clientEvBody :: Maybe Value
  - withSocketId :: SocketID
  - withPossibleUser :: Maybe User
  }
data WebhookPayload = WebhookPayload {
- xPusherKey :: AppKey
- xPusherSignature :: AuthSignature
- webhooks :: Webhooks
}
data Webhooks = Webhooks {
- timeMs :: UTCTime
- webhookEvs :: [WebhookEv]
}
parseAppKeyHdr :: ByteString -> ByteString -> Maybe AppKey
parseAuthSignatureHdr :: ByteString -> ByteString -> Maybe AuthSignature
parseWebhooksBody :: ByteString -> Maybe Webhooks
verifyWebhooksBody :: AppSecret -> AuthSignature -> ByteString -> Bool
parseWebhookPayloadWith :: (AppKey -> Maybe AppSecret) -> [(ByteString, ByteString)] -> ByteString -> Maybe WebhookPayload

Data types

Pusher config type

data Pusher Source #

All the required configuration needed to interact with the API.

Constructors

Pusher
Fields pusherHost :: Text pusherPath :: Text pusherNotifyHost :: Text pusherNotifyPath :: Text pusherCredentials :: Credentials pusherConnectionManager :: Manager

data Credentials Source #

The credentials for the current app.

Constructors

Credentials
Fields credentialsAppID :: AppID credentialsAppKey :: AppKey credentialsAppSecret :: AppSecret credentialsCluster :: Maybe Cluster

Instances

FromJSON Credentials Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser Credentials # parseJSONList :: Value -> Parser [Credentials] #

newtype Cluster Source #

The cluster the current app resides on. Common clusters include: mt1,eu,ap1,ap2.

Constructors

Cluster
Fields clusterName :: Text

Instances

FromJSON Cluster Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser Cluster # parseJSONList :: Value -> Parser [Cluster] #

type AppID = Integer Source #

type AppKey = ByteString Source #

type AppSecret = ByteString Source #

getPusher :: MonadIO m => Credentials -> m Pusher Source #

Use this to get an instance Pusher. This will fill in the host and path automatically.

getPusherWithHost :: MonadIO m => Text -> Text -> Credentials -> m Pusher Source #

Get a Pusher instance that uses a specific API endpoint.

getPusherWithConnManager :: Manager -> Maybe Text -> Maybe Text -> Credentials -> Pusher Source #

Get a Pusher instance with a given connection manager. This can be useful if you want to share a connection with your application code.

Channels

data Channel Source #

The channel name (not including the channel type prefix) and its type.

Constructors

Channel
Fields channelType :: ChannelType channelName :: ChannelName

Instances

Eq Channel Source #
Instance details Defined in Network.Pusher.Data Methods (==) :: Channel -> Channel -> Bool # (/=) :: Channel -> Channel -> Bool #
Show Channel Source #
Instance details Defined in Network.Pusher.Data Methods showsPrec :: Int -> Channel -> ShowS # show :: Channel -> String # showList :: [Channel] -> ShowS #
Generic Channel Source #
Instance details Defined in Network.Pusher.Data Associated Types type Rep Channel :: Type -> Type # Methods from :: Channel -> Rep Channel x # to :: Rep Channel x -> Channel #
Hashable Channel Source #
Instance details Defined in Network.Pusher.Data Methods hashWithSalt :: Int -> Channel -> Int # hash :: Channel -> Int #
FromJSON Channel Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser Channel # parseJSONList :: Value -> Parser [Channel] #
type Rep Channel Source #
Instance details Defined in Network.Pusher.Data type Rep Channel = D1 (MetaData "Channel" "Network.Pusher.Data" "pusher-http-haskell-1.5.1.14-J0BlTt5Ucru8m03xfW3qcM" False) (C1 (MetaCons "Channel" PrefixI True) (S1 (MetaSel (Just "channelType") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ChannelType) :*: S1 (MetaSel (Just "channelName") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ChannelName)))

type ChannelName = Text Source #

data ChannelType Source #

The possible types of channel.

Constructors

Public
Private
Presence

Instances

Eq ChannelType Source #
Instance details Defined in Network.Pusher.Data Methods (==) :: ChannelType -> ChannelType -> Bool # (/=) :: ChannelType -> ChannelType -> Bool #
Show ChannelType Source #
Instance details Defined in Network.Pusher.Data Methods showsPrec :: Int -> ChannelType -> ShowS # show :: ChannelType -> String # showList :: [ChannelType] -> ShowS #
Generic ChannelType Source #
Instance details Defined in Network.Pusher.Data Associated Types type Rep ChannelType :: Type -> Type # Methods from :: ChannelType -> Rep ChannelType x # to :: Rep ChannelType x -> ChannelType #
Hashable ChannelType Source #
Instance details Defined in Network.Pusher.Data Methods hashWithSalt :: Int -> ChannelType -> Int # hash :: ChannelType -> Int #
type Rep ChannelType Source #
Instance details Defined in Network.Pusher.Data type Rep ChannelType = D1 (MetaData "ChannelType" "Network.Pusher.Data" "pusher-http-haskell-1.5.1.14-J0BlTt5Ucru8m03xfW3qcM" False) (C1 (MetaCons "Public" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "Private" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Presence" PrefixI False) (U1 :: Type -> Type)))

renderChannel :: Channel -> Text Source #

renderChannelPrefix :: ChannelType -> Text Source #

parseChannel :: Text -> Channel Source #

Convert string representation, e.g. private-chan into the datatype.

Events

type Event = Text Source #

type EventData = Text Source #

type SocketID = Text Source #

Notifications

data Notification Source #

Constructors

Notification
Fields notificationInterest :: Interest notificationWebhookURL :: Maybe WebhookURL notificationWebhookLevel :: Maybe WebhookLevel notificationAPNSPayload :: Maybe APNSPayload notificationGCMPayload :: Maybe GCMPayload notificationFCMPayload :: Maybe FCMPayload

Instances

Eq Notification Source #
Instance details Defined in Network.Pusher.Data Methods (==) :: Notification -> Notification -> Bool # (/=) :: Notification -> Notification -> Bool #
Show Notification Source #
Instance details Defined in Network.Pusher.Data Methods showsPrec :: Int -> Notification -> ShowS # show :: Notification -> String # showList :: [Notification] -> ShowS #
ToJSON Notification Source #
Instance details Defined in Network.Pusher.Data Methods toJSON :: Notification -> Value # toEncoding :: Notification -> Encoding # toJSONList :: [Notification] -> Value # toEncodingList :: [Notification] -> Encoding #
FromJSON Notification Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser Notification # parseJSONList :: Value -> Parser [Notification] #

data Interest Source #

Up to 164 characters where each character is ASCII upper or lower case, a number or one of _=@,.;

Note: hyphen - is NOT valid as it is reserved for the possibility of marking interest names with prefixes such as private- or presence-.

Instances

Eq Interest Source #
Instance details Defined in Network.Pusher.Data Methods (==) :: Interest -> Interest -> Bool # (/=) :: Interest -> Interest -> Bool #
Show Interest Source #
Instance details Defined in Network.Pusher.Data Methods showsPrec :: Int -> Interest -> ShowS # show :: Interest -> String # showList :: [Interest] -> ShowS #
ToJSON Interest Source #
Instance details Defined in Network.Pusher.Data Methods toJSON :: Interest -> Value # toEncoding :: Interest -> Encoding # toJSONList :: [Interest] -> Value # toEncodingList :: [Interest] -> Encoding #
FromJSON Interest Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser Interest # parseJSONList :: Value -> Parser [Interest] #

mkInterest :: Text -> Maybe Interest Source #

type WebhookURL = Text Source #

URL to which Pusher Channels will send information about sent push notifications.

data WebhookLevel Source #

Level of detail sent to WebhookURL. Defaults to Info.

Constructors

Info	Errors only
Debug	Everything

Instances

Eq WebhookLevel Source #
Instance details Defined in Network.Pusher.Data Methods (==) :: WebhookLevel -> WebhookLevel -> Bool # (/=) :: WebhookLevel -> WebhookLevel -> Bool #
Show WebhookLevel Source #
Instance details Defined in Network.Pusher.Data Methods showsPrec :: Int -> WebhookLevel -> ShowS # show :: WebhookLevel -> String # showList :: [WebhookLevel] -> ShowS #
ToJSON WebhookLevel Source #
Instance details Defined in Network.Pusher.Data Methods toJSON :: WebhookLevel -> Value # toEncoding :: WebhookLevel -> Encoding # toJSONList :: [WebhookLevel] -> Value # toEncodingList :: [WebhookLevel] -> Encoding #
FromJSON WebhookLevel Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser WebhookLevel # parseJSONList :: Value -> Parser [WebhookLevel] #

data APNSPayload Source #

Apple push notification service payload.

Constructors

APNSPayload Object

Instances

Eq APNSPayload Source #
Instance details Defined in Network.Pusher.Data Methods (==) :: APNSPayload -> APNSPayload -> Bool # (/=) :: APNSPayload -> APNSPayload -> Bool #
Show APNSPayload Source #
Instance details Defined in Network.Pusher.Data Methods showsPrec :: Int -> APNSPayload -> ShowS # show :: APNSPayload -> String # showList :: [APNSPayload] -> ShowS #
ToJSON APNSPayload Source #
Instance details Defined in Network.Pusher.Data Methods toJSON :: APNSPayload -> Value # toEncoding :: APNSPayload -> Encoding # toJSONList :: [APNSPayload] -> Value # toEncodingList :: [APNSPayload] -> Encoding #
FromJSON APNSPayload Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser APNSPayload # parseJSONList :: Value -> Parser [APNSPayload] #

data GCMPayload Source #

Google Cloud Messaging payload.

Constructors

GCMPayload Object

Instances

Eq GCMPayload Source #
Instance details Defined in Network.Pusher.Data Methods (==) :: GCMPayload -> GCMPayload -> Bool # (/=) :: GCMPayload -> GCMPayload -> Bool #
Show GCMPayload Source #
Instance details Defined in Network.Pusher.Data Methods showsPrec :: Int -> GCMPayload -> ShowS # show :: GCMPayload -> String # showList :: [GCMPayload] -> ShowS #
ToJSON GCMPayload Source #
Instance details Defined in Network.Pusher.Data Methods toJSON :: GCMPayload -> Value # toEncoding :: GCMPayload -> Encoding # toJSONList :: [GCMPayload] -> Value # toEncodingList :: [GCMPayload] -> Encoding #
FromJSON GCMPayload Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser GCMPayload # parseJSONList :: Value -> Parser [GCMPayload] #

data FCMPayload Source #

Firebase Cloud Messaging payload.

Constructors

FCMPayload Object

Instances

Eq FCMPayload Source #
Instance details Defined in Network.Pusher.Data Methods (==) :: FCMPayload -> FCMPayload -> Bool # (/=) :: FCMPayload -> FCMPayload -> Bool #
Show FCMPayload Source #
Instance details Defined in Network.Pusher.Data Methods showsPrec :: Int -> FCMPayload -> ShowS # show :: FCMPayload -> String # showList :: [FCMPayload] -> ShowS #
ToJSON FCMPayload Source #
Instance details Defined in Network.Pusher.Data Methods toJSON :: FCMPayload -> Value # toEncoding :: FCMPayload -> Encoding # toJSONList :: [FCMPayload] -> Value # toEncodingList :: [FCMPayload] -> Encoding #
FromJSON FCMPayload Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser FCMPayload # parseJSONList :: Value -> Parser [FCMPayload] #

HTTP Requests

Trigger events

trigger Source #

Arguments

:: MonadIO m
=> Pusher
-> [Channel]	The list of channels to trigger to.
-> Event
-> EventData	Often encoded JSON.
-> Maybe SocketID	An optional socket ID of a connection you wish to exclude.
-> m (Either PusherError ())

Trigger an event to one or more channels.

Channel queries

channels Source #

Arguments

:: MonadIO m
=> Pusher
-> Maybe ChannelType	Filter by the type of channel.
-> Text	A channel prefix you wish to filter on.
-> ChannelsInfoQuery	Data you wish to query for, currently just the user count.
-> m (Either PusherError ChannelsInfo)	The returned data.

Query a list of channels for information.

channel Source #

Arguments

:: MonadIO m
=> Pusher
-> Channel
-> ChannelInfoQuery	Can query user count and also subscription count (if enabled).
-> m (Either PusherError FullChannelInfo)

Query for information on a single channel.

users :: MonadIO m => Pusher -> Channel -> m (Either PusherError Users) Source #

Get a list of users in a presence channel.

Push notifications

notify :: MonadIO m => Pusher -> Notification -> m (Either PusherError ()) Source #

Send a push notification.

Authentication

type AuthString = ByteString Source #

The bytestring to sign with the app secret to create a signature from.

type AuthSignature = ByteString Source #

A Pusher auth signature.

authenticatePresence :: ToJSON a => Credentials -> SocketID -> Channel -> a -> AuthSignature Source #

Generate an auth signature of the form "app_key:auth_sig" for a user of a presence channel.

authenticatePrivate :: Credentials -> SocketID -> Channel -> AuthSignature Source #

Generate an auth signature of the form "app_key:auth_sig" for a user of a private channel.

Errors

data PusherError Source #

Constructors

PusherArgumentError Text	Data from the caller is not valid.
PusherNon200ResponseError Text	Received non 200 response code from Pusher.
PusherInvalidResponseError Text	Received unexpected data from Pusher.

Instances

Show PusherError Source #
Instance details Defined in Network.Pusher.Error Methods showsPrec :: Int -> PusherError -> ShowS # show :: PusherError -> String # showList :: [PusherError] -> ShowS #
Exception PusherError Source #
Instance details Defined in Network.Pusher.Error Methods toException :: PusherError -> SomeException # fromException :: SomeException -> Maybe PusherError # displayException :: PusherError -> String #

Webhooks

parseWebhookPayload :: Pusher -> [(ByteString, ByteString)] -> ByteString -> Maybe WebhookPayload Source #

Parse webhooks from a list of HTTP headers and a HTTP body given their AppKey matches the one in our Pusher Channels credentials and the webhook is correctly encrypted by the corresponding AppSecret.

data WebhookEv Source #

A WebhookEv is one of several events Pusher may send to your server in response to events your users may trigger.

Constructors

ChannelOccupiedEv	A channel has become occupied. There is > 1 subscriber.
Fields onChannel :: Channel
ChannelVacatedEv	A channel has become vacated. There are 0 subscribers.
Fields onChannel :: Channel
MemberAddedEv	A new user has subscribed to a presence channel.
Fields onChannel :: Channel withUser :: User
MemberRemovedEv	A user has unsubscribed from a presence channel.
Fields onChannel :: Channel withUser :: User
ClientEv	A client has sent a named client event with some json body. They have a `SocketID` and a `User` if they were in a presence channel.
Fields onChannel :: Channel clientEvName :: Text clientEvBody :: Maybe Value withSocketId :: SocketID withPossibleUser :: Maybe User

Instances

Eq WebhookEv Source #
Instance details Defined in Network.Pusher.Webhook Methods (==) :: WebhookEv -> WebhookEv -> Bool # (/=) :: WebhookEv -> WebhookEv -> Bool #
Show WebhookEv Source #
Instance details Defined in Network.Pusher.Webhook Methods showsPrec :: Int -> WebhookEv -> ShowS # show :: WebhookEv -> String # showList :: [WebhookEv] -> ShowS #
FromJSON WebhookEv Source #
Instance details Defined in Network.Pusher.Webhook Methods parseJSON :: Value -> Parser WebhookEv # parseJSONList :: Value -> Parser [WebhookEv] #

data WebhookPayload Source #

Constructors

WebhookPayload
Fields xPusherKey :: AppKey Authentication header. The oldest active token is used, identified by this key. xPusherSignature :: AuthSignature A HMAC SHA256 formed by signing the payload with the tokens secret. webhooks :: Webhooks

Instances

Eq WebhookPayload Source #
Instance details Defined in Network.Pusher.Webhook Methods (==) :: WebhookPayload -> WebhookPayload -> Bool # (/=) :: WebhookPayload -> WebhookPayload -> Bool #
Show WebhookPayload Source #
Instance details Defined in Network.Pusher.Webhook Methods showsPrec :: Int -> WebhookPayload -> ShowS # show :: WebhookPayload -> String # showList :: [WebhookPayload] -> ShowS #

data Webhooks Source #

A Webhook is received by POST request from Pusher to notify your server of a number of WebhookEvs. Multiple events are received under the same timestamp if batch events is enabled.

Constructors

Webhooks
Fields timeMs :: UTCTime webhookEvs :: [WebhookEv]

Instances

Eq Webhooks Source #
Instance details Defined in Network.Pusher.Webhook Methods (==) :: Webhooks -> Webhooks -> Bool # (/=) :: Webhooks -> Webhooks -> Bool #
Show Webhooks Source #
Instance details Defined in Network.Pusher.Webhook Methods showsPrec :: Int -> Webhooks -> ShowS # show :: Webhooks -> String # showList :: [Webhooks] -> ShowS #
FromJSON Webhooks Source #
Instance details Defined in Network.Pusher.Webhook Methods parseJSON :: Value -> Parser Webhooks # parseJSONList :: Value -> Parser [Webhooks] #

parseAppKeyHdr :: ByteString -> ByteString -> Maybe AppKey Source #

Given a HTTP Header and its associated value, parse an AppKey.

parseAuthSignatureHdr :: ByteString -> ByteString -> Maybe AuthSignature Source #

Given a HTTP Header and its associated value, parse a AuthSignature.

parseWebhooksBody :: ByteString -> Maybe Webhooks Source #

Given a HTTP body, parse the contained webhooks.

verifyWebhooksBody :: AppSecret -> AuthSignature -> ByteString -> Bool Source #

Does a webhook body hash with our secret key to the given signature?

parseWebhookPayloadWith :: (AppKey -> Maybe AppSecret) -> [(ByteString, ByteString)] -> ByteString -> Maybe WebhookPayload Source #

Given a list of http header key:values, a http body and a lookup function for an apps secret, parse and validate a potential webhook payload.