Network.Pushover

This library provides functionality for interacting with the Pushover API (https://www.pushover.net) from within a Haskell codebase.

Pushover exposes a straightforward API for sending notifications to users of the Android and iOS Pushover app. Details of the API can be found at https://pushover.net/api.

Requests are defined by the Request type. The defaultRequest function is provided to allow for the easy creation of simple requests. Each request requires an API token, user token and a message to be passed. All other fields are optional and can be set as required.

Sending a notification

Regular functions

sendMessage :: APIToken -> UserKey -> Message -> IO Response

Send a request to the Pushover API.

Requires a pair of Pushover tokens, together with a Message value. These are used to construct a defaultRequest which is then sent to the API.

sendRequest :: Request -> IO Response

Send a request to the Pushover API.

This is similar to sendMessage, except that a constructed Request must be passed instead of the tokens and message.

createRequest :: APIToken -> UserKey -> Message -> Request

Create a standard Pushover request.

This is an alias of the defaultRequest function.

Monadic functions

sendMessageM :: (Error e, MonadError e m, MonadIO m, MonadReader r m, PushoverReader r) => Message -> m Response

Send a request to the Pushover API.

This function is designed for use within an existing monad transformer stack to make it easy to send Pushover notifications from inside existing software.

The relevant tokens are read from a PushoverReader MonadReader instance. These are then used to construct a defaultRequest containing the passed Message value.

sendRequestM :: (Error e, MonadError e m, MonadIO m) => Request -> m Response

Send a request to the Pushover API.

This function is designed for use within an existing monad transformer stack to make it easy to send Pushover notifications from inside existing software.

This is similar to sendMessageM, except that a constructed Request must be passed instead of just the message.

createRequestM :: (MonadReader r m, PushoverReader r) => Message -> m Request

Create a standard Pushover request.

This is similar to createRequest, except that token information is read from within the monad stack.

Requests

Constructing a request

data Request

Contains the contents of a Pushover notification request. This follows the API specification at https://pushover.net/api.

Instances

Eq Request

Methods

(==) :: Request -> Request -> Bool

(/=) :: Request -> Request -> Bool

Show Request

Methods

showsPrec :: Int -> Request -> ShowS

show :: Request -> String

showList :: [Request] -> ShowS

defaultRequest :: APIToken -> UserKey -> Message -> Request

Construct a default request value.

As a request requires, at a minimum, an API token, a user key and a message, this function requires each of these values as an argument. Other fields can then be initialised using the regular Haskell record syntax.

Constructing a request's message

data Message

Represents a message sent to the Pushover API.

A Pushover message can be constructed with a very small subset of HTML. This type represents the available HTML formatting for a message.

Instances

Eq Message

Methods

(==) :: Message -> Message -> Bool

(/=) :: Message -> Message -> Bool

Show Message

Methods

showsPrec :: Int -> Message -> ShowS

show :: Message -> String

showList :: [Message] -> ShowS

message :: [Message] -> Message

Make a message from a list of message parts.

bold :: [Message] -> Message

Make a bold message.

italic :: [Message] -> Message

Make an italic message.

underline :: [Message] -> Message

Make an underlined message.

color :: Integer -> Integer -> Integer -> [Message] -> Message

Make a message with colored text.

Accepts three integer arguments for red, green and blue color elements, respectively.

link :: Url -> [Message] -> Message

Make a url message.

text :: Text -> Message

Make a textual message.

Authenticating a request

type APIToken = PushoverToken

type UserKey = PushoverToken

User key for the user receiving a notification.

data PushoverToken

Define a type to represent the different types of token or key Pushover requires.

Pushover requires API token and user keys to be send with requests. This is intended to represent these tokens. It is intended that the makeToken function is used to construct validated tokens.

Instances

Eq PushoverToken

Methods

(==) :: PushoverToken -> PushoverToken -> Bool

(/=) :: PushoverToken -> PushoverToken -> Bool

Show PushoverToken

Methods

showsPrec :: Int -> PushoverToken -> ShowS

show :: PushoverToken -> String

showList :: [PushoverToken] -> ShowS

ToJSON PushoverToken

Methods

toJSON :: PushoverToken -> Value

toEncoding :: PushoverToken -> Encoding

toJSONList :: [PushoverToken] -> Value

toEncodingList :: [PushoverToken] -> Encoding

FromJSON PushoverToken

Methods

parseJSON :: Value -> Parser PushoverToken

parseJSONList :: Value -> Parser [PushoverToken]

makeToken :: Text -> Either PushoverException PushoverToken

Construct a PushoverToken value.

A PushoverToken consists of exactly 30 alphanumeric characters (both uppercase and lowercase). The input key text is validated to ensure it is the correct length and contains valid characters.

A descriptive error is returned where validation fails.

Other request fields

data URL

A URL for sending within a notification request.

A Pushover URL is optional within a request; if present, it may optionally contain a title to display instead of the URL itself.

Constructors

URL

Fields

• urlPath :: Text
• urlTitle :: Maybe Text

Instances

Eq URL

Methods

(==) :: URL -> URL -> Bool

(/=) :: URL -> URL -> Bool

Show URL

Methods

showsPrec :: Int -> URL -> ShowS

show :: URL -> String

showList :: [URL] -> ShowS

data Priority

Describes the priority of a particular message.

The different priority settings affect the way in which a notification is presented to the user. See https://pushover.net/api#priority for specific details.

Constructors

Lowest

Low

Normal

High

Emergency

Instances

Eq Priority

Methods

(==) :: Priority -> Priority -> Bool

(/=) :: Priority -> Priority -> Bool

Show Priority

Methods

showsPrec :: Int -> Priority -> ShowS

show :: Priority -> String

showList :: [Priority] -> ShowS

data NotificationSound

Describes the notification sound for a notification.

Constructors

Pushover

Bike

Bugle

CashRegister

Classical

Cosmic

Falling

Gamelan

Incoming

Intermission

Magic

Mechanical

PianoBar

Siren

SpaceAlarm

TugBoat

AlienAlarm

Climb

Persistent

Echo

UpDown

None

Instances

Eq NotificationSound

Methods

(==) :: NotificationSound -> NotificationSound -> Bool

(/=) :: NotificationSound -> NotificationSound -> Bool

Show NotificationSound

Methods

showsPrec :: Int -> NotificationSound -> ShowS

show :: NotificationSound -> String

showList :: [NotificationSound] -> ShowS

Response

data Response

Describes a response received to a notification request. This follows the specification at https://pushover.net/api#response.

A request will either be successful or it will be unsuccessful. Where it is successful, an appropriate status indicator is returned. Where unsuccessful, the response will contain an errors key with a list of errors within the request.

In both cases, a request parameter is returned which uniquely identifies the request leading to the response.

Constructors

Response

Fields

• status :: ResponseStatus
• request :: Text

Instances

Show Response

Methods

showsPrec :: Int -> Response -> ShowS

show :: Response -> String

showList :: [Response] -> ShowS

FromJSON Response

Methods

parseJSON :: Value -> Parser Response

parseJSONList :: Value -> Parser [Response]

Reader

class PushoverReader r where

The PushoverReader class is intended to make it straightforward to incorporate the making of Pushover requests within an existing monad stack.

This class is intended to make it easy to add an API token and user key to an existing reader monad environment.

Minimal complete definition

apiToken, userKey

Methods

apiToken :: r -> APIToken

userKey :: r -> UserKey

Instances

PushoverReader PushoverKeys

Methods

apiToken :: PushoverKeys -> APIToken

userKey :: PushoverKeys -> UserKey

data PushoverKeys

A basic type for use in storing the pair of keys required for making a request.

Constructors

PushoverKeys

Fields

• _apiToken :: APIToken
• _userKey :: UserKey

Instances

Show PushoverKeys

Methods

showsPrec :: Int -> PushoverKeys -> ShowS

show :: PushoverKeys -> String

showList :: [PushoverKeys] -> ShowS

PushoverReader PushoverKeys

Methods

apiToken :: PushoverKeys -> APIToken

userKey :: PushoverKeys -> UserKey

createKeys :: (Error e, MonadError e m) => UnvalidatedAPIToken -> UnvalidatedUserKey -> m PushoverKeys

Construct a PushoverKeys value.

This attempts to create valid tokens/keys from a pair of unvalidated tokens/keys, returning the result wrapped within a MonadError.

Exceptions

data PushoverException

Defines possible exceptions which can be thrown from execution commands.

Instances

Show PushoverException

Methods

showsPrec :: Int -> PushoverException -> ShowS

show :: PushoverException -> String

showList :: [PushoverException] -> ShowS

Exception PushoverException

Methods

toException :: PushoverException -> SomeException

fromException :: SomeException -> Maybe PushoverException

displayException :: PushoverException -> String

Error PushoverException

Methods

noMsg :: PushoverException

strMsg :: String -> PushoverException

errorMessage :: PushoverException -> String

Display a description error message for each PushoverException constructor.