-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A Haskell Pushover API library
--   
--   This package provides functionality to allow Haskell developers to
--   interact with the Pushover API (https://pushover.net).
@package pushover
@version 0.1.0.0

module Network.Pushover.Response

-- | Describes a response received to a notification request. This follows
--   the specification at
--   <tt><a>https://pushover.net/api#response</a></tt>.
--   
--   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.
data Response
Response :: ResponseStatus -> Text -> Response
[status] :: Response -> ResponseStatus
[request] :: Response -> Text

-- | Describes a Pushover response status.
--   
--   A request is either successful or unsuccessful. This is reflected in
--   this type. Success has no additional data associated with it; failure
--   has a list of errors associated.
data ResponseStatus
Success :: ResponseStatus
Failure :: [RequestError] -> ResponseStatus
type RequestError = Text
instance GHC.Show.Show Network.Pushover.Response.Response
instance GHC.Show.Show Network.Pushover.Response.ResponseStatus
instance Data.Aeson.Types.FromJSON.FromJSON Network.Pushover.Response.Response
instance Data.Aeson.Types.FromJSON.FromJSON Network.Pushover.Response.ResponseStatus


-- | This module provides functions for creating and encoding messages for
--   use within Pushover requests.
--   
--   Pushover messages contain a very limited subset of HTML. Users can
--   insert bold, italic, underlined, and colored text, and URLs within
--   messages. The <a>Message</a> type represents all of these possible
--   formatting options.
--   
--   Constructing a <a>Message</a> is done through the use of the
--   <a>message</a>, <a>bold</a>, <a>italic</a>, <a>underline</a>,
--   <a>color</a>, <a>link</a>, and <a>text</a> functions. The
--   <a>message</a> function takes a list of parts created using the other
--   functions, and concatenates these into a single message. Different
--   types of formatting can be nested within each other by simply calling
--   the functions on the results of other function calls. For example:-
--   
--   <pre>
--   bold 
--     [ italic 
--         [ text "This is bold &amp; italic" 
--         ]
--     , text "This is bold"
--     , underline
--         [ text "This is bold &amp; underlined"
--         ]
--     ]
--   </pre>
--   
--   will create a message with the text values formatted as described.
module Network.Pushover.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.
data Message

-- | Make a message from a list of message parts.
message :: [Message] -> Message

-- | Make a bold message.
bold :: [Message] -> Message

-- | Make an italic message.
italic :: [Message] -> Message

-- | Make an underlined message.
underline :: [Message] -> Message

-- | Make a message with colored text.
--   
--   Accepts three integer arguments for red, green and blue color
--   elements, respectively.
color :: Integer -> Integer -> Integer -> [Message] -> Message

-- | Make a url message.
link :: Url -> [Message] -> Message

-- | Make a textual message.
text :: Text -> Message

-- | Encode a <a>Message</a> into a bytestring.
--   
--   This function is intended to convert a <a>Message</a> into a form
--   useable within a <tt>Request</tt>. It generates a bytestring
--   containing the HTML for the message.
encodeMessage :: Message -> ByteString

-- | Represents an HTML color code.
--   
--   A ColorCode consists of a red, a green and a blue element, each of
--   which must have a value of between 0 and 255. This type cannot enforce
--   this constraint, but see <a>makeColorCode</a> which does.
data ColorCode

-- | Construct a <a>ColorCode</a> value.
--   
--   A <a>ColorCode</a> requires a red, a green and a blue value for
--   construction. This function takes these as arguments and returns a
--   constructed <a>ColorCode</a>.
--   
--   This function checks that each element is within the required 0-255
--   range. Any element which is not is rounded to the nearest extrema (0
--   for negative values; 255 for values larger than that number).
makeColorCode :: Integer -> Integer -> Integer -> ColorCode
type Url = Text
instance GHC.Classes.Eq Network.Pushover.Message.Message
instance GHC.Show.Show Network.Pushover.Message.Message
instance GHC.Classes.Eq Network.Pushover.Message.ColorCode
instance GHC.Show.Show Network.Pushover.Message.ColorCode

module Network.Pushover.Exceptions

-- | Defines possible exceptions which can be thrown from execution
--   commands.
data PushoverException

-- | This exception is thrown when a response is malformed and cannot be
--   decoded.
ResponseDecodeException :: PushoverException

-- | This exception is thrown when a token cannot be constructed because it
--   contains invalid characters.
InvalidTokenCharactersException :: PushoverException

-- | This exception is thrown when a token cannot be constructed because it
--   is an incorrect length.
InvalidTokenLengthException :: PushoverException

-- | This is a generic exception for other errors in Pushover.
PushoverException :: String -> PushoverException

-- | Display a description error message for each <a>PushoverException</a>
--   constructor.
errorMessage :: PushoverException -> String
instance GHC.Show.Show Network.Pushover.Exceptions.PushoverException
instance GHC.Exception.Exception Network.Pushover.Exceptions.PushoverException
instance Control.Monad.Trans.Error.Error Network.Pushover.Exceptions.PushoverException


-- | This module contains functionality and types concerning tokens used to
--   authenticate and direct communications with the Pushover API.
--   
--   The API requires that an API token be sent with every request for
--   authentication purposes, and a user key be sent with every request for
--   the purpose of identifying the recipient of the message. Both types of
--   token/key are of the same format, and the <a>makeToken</a> functions
--   work for constructing both types of token/key.
module Network.Pushover.Token

-- | 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
--   <a>makeToken</a> function is used to construct validated tokens.
data PushoverToken
type APIToken = PushoverToken

-- | User key for the user receiving a notification.
type UserKey = PushoverToken

-- | Construct a <a>PushoverToken</a> value.
--   
--   A <a>PushoverToken</a> 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.
makeToken :: Text -> Either PushoverException PushoverToken

-- | Construct a <a>PushoverToken</a> value.
--   
--   This is similar to the <a>makeToken</a> function, except that it is
--   generalised over the <a>MonadError</a> monad.
makeTokenM :: (Error e, MonadError e m) => Text -> m PushoverToken

-- | Construct a <a>PushoverToken</a> value.
--   
--   This is a version of <a>makeToken</a> in which an invalid token will
--   raise an error. It should generally not be used, with <a>makeToken</a>
--   the preferred means to create a token.
makeTokenOrError :: Text -> PushoverToken

-- | Encode a <a>PushoverToken</a> into a bytestring for sending within an
--   HTTP request.
encodeToken :: PushoverToken -> ByteString
instance GHC.Classes.Eq Network.Pushover.Token.PushoverToken
instance GHC.Show.Show Network.Pushover.Token.PushoverToken
instance Data.Aeson.Types.ToJSON.ToJSON Network.Pushover.Token.PushoverToken
instance Data.Aeson.Types.FromJSON.FromJSON Network.Pushover.Token.PushoverToken


-- | This module exposes types intended to make it easy to incorporate
--   Pushover request functionality within an existing application.
--   
--   The <a>PushoverReader</a> class is designed to make it easy to extend
--   an existing reader environment to include the information required by
--   Pushover in the making of requests.
--   
--   <a>PushoverKeys</a> is a simple type available for immediate use
--   should a developer not yet have a reader environment and wants quickly
--   to use Pushover.
module Network.Pushover.Reader

-- | The <a>PushoverReader</a> 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.
class PushoverReader r
apiToken :: PushoverReader r => r -> APIToken
userKey :: PushoverReader r => r -> UserKey

-- | A basic type for use in storing the pair of keys required for making a
--   request.
data PushoverKeys
PushoverKeys :: APIToken -> UserKey -> PushoverKeys
[_apiToken] :: PushoverKeys -> APIToken
[_userKey] :: PushoverKeys -> UserKey

-- | An unvalidated API token.
type UnvalidatedAPIToken = Text

-- | An unvalidated user key.
type UnvalidatedUserKey = Text

-- | Construct a <a>PushoverKeys</a> value.
--   
--   This attempts to create valid tokens/keys from a pair of unvalidated
--   tokens/keys, returning the result wrapped within a MonadError.
createKeys :: (Error e, MonadError e m) => UnvalidatedAPIToken -> UnvalidatedUserKey -> m PushoverKeys
instance GHC.Show.Show Network.Pushover.Reader.PushoverKeys
instance Network.Pushover.Reader.PushoverReader Network.Pushover.Reader.PushoverKeys

module Network.Pushover.Request

-- | Contains the contents of a Pushover notification request. This follows
--   the API specification at <tt><a>https://pushover.net/api</a></tt>.
data Request
Request :: APIToken -> UserKey -> Message -> [Text] -> Maybe Text -> Maybe URL -> Maybe Priority -> Maybe UTCTime -> Maybe NotificationSound -> Request

-- | The API token provided by your Pushover app's dashboard at
--   <tt><a>https://pushover.net/apps</a></tt>.
[requestToken] :: Request -> APIToken

-- | The user key of the user receiving this notification, found in the
--   Pushover dashboard at <tt><a>https://pushover.net/dashboard</a></tt>.
[requestUserKey] :: Request -> UserKey

-- | The notification message to push to the user.
[requestMessage] :: Request -> Message

-- | An optional list of devices to which to send the notification. If
--   empty, it will be sent to all of the user's devices.
[devices] :: Request -> [Text]

-- | An optional title for the message.
[title] :: Request -> Maybe Text

-- | An optional URL for inclusion with the message.
[url] :: Request -> Maybe URL

-- | The priority of this message. This affects way in which the
--   notification is presented to the receiving user. See <a>Priority</a>
--   for more information.
[priority] :: Request -> Maybe Priority

-- | An optional timestamp for the notification. If no timestamp is
--   provided, the time the request is received by the Pushover API is
--   used.
[timestamp] :: Request -> Maybe UTCTime

-- | The notification sound to use. The default is <a>Pushover</a>, with
--   <a>None</a> provided for a silent notification.
[notificationSound] :: Request -> Maybe NotificationSound

-- | 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.
defaultRequest :: APIToken -> UserKey -> Message -> Request

-- | 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.
data URL
URL :: Text -> Maybe Text -> URL
[urlPath] :: URL -> Text
[urlTitle] :: URL -> Maybe Text

-- | Describes the priority of a particular message.
--   
--   The different priority settings affect the way in which a notification
--   is presented to the user. See
--   <tt><a>https://pushover.net/api#priority</a></tt> for specific
--   details.
data Priority
Lowest :: Priority
Low :: Priority
Normal :: Priority
High :: Priority
Emergency :: Priority

-- | Describes the notification sound for a notification.
data NotificationSound
Pushover :: NotificationSound
Bike :: NotificationSound
Bugle :: NotificationSound
CashRegister :: NotificationSound
Classical :: NotificationSound
Cosmic :: NotificationSound
Falling :: NotificationSound
Gamelan :: NotificationSound
Incoming :: NotificationSound
Intermission :: NotificationSound
Magic :: NotificationSound
Mechanical :: NotificationSound
PianoBar :: NotificationSound
Siren :: NotificationSound
SpaceAlarm :: NotificationSound
TugBoat :: NotificationSound
AlienAlarm :: NotificationSound
Climb :: NotificationSound
Persistent :: NotificationSound
Echo :: NotificationSound
UpDown :: NotificationSound
None :: NotificationSound

-- | Construct an HTTP request out of a Pushover request value.
--   
--   This function is exposed for use by the functions in the
--   <a>Network.Pushover.Execute</a> module. It is unlikely that the user
--   will require to call it directly.
makeHttpRequest :: Request -> IO Request
instance GHC.Classes.Eq Network.Pushover.Request.Request
instance GHC.Show.Show Network.Pushover.Request.Request
instance GHC.Classes.Eq Network.Pushover.Request.NotificationSound
instance GHC.Show.Show Network.Pushover.Request.NotificationSound
instance GHC.Classes.Eq Network.Pushover.Request.Priority
instance GHC.Show.Show Network.Pushover.Request.Priority
instance GHC.Classes.Eq Network.Pushover.Request.URL
instance GHC.Show.Show Network.Pushover.Request.URL


-- | This module exposes a set of functions used for constructing and
--   submitting requests to the Pushover API.
--   
--   Each function has two versions: a monadic version and a non-monadic
--   version. The monadic versions are designed for use within an existing
--   monad transformer stack within an existing application. The
--   non-monadic versions are designed for standalone use.
module Network.Pushover.Execute

-- | Send a request to the Pushover API.
--   
--   Requires a pair of Pushover tokens, together with a <a>Message</a>
--   value. These are used to construct a <a>defaultRequest</a> which is
--   then sent to the API.
sendMessage :: APIToken -> UserKey -> Message -> IO Response

-- | Send a request to the Pushover API.
--   
--   This is similar to <a>sendMessage</a>, except that a constructed
--   <a>Request</a> must be passed instead of the tokens and message.
sendRequest :: Request -> IO Response

-- | Create a standard Pushover request.
--   
--   This is an alias of the <a>defaultRequest</a> function.
createRequest :: APIToken -> UserKey -> Message -> Request

-- | 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 <a>PushoverReader</a> MonadReader
--   instance. These are then used to construct a <a>defaultRequest</a>
--   containing the passed <a>Message</a> value.
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.
--   
--   This is similar to <a>sendMessageM</a>, except that a constructed
--   <a>Request</a> must be passed instead of just the message.
sendRequestM :: (Error e, MonadError e m, MonadIO m) => Request -> m Response

-- | Create a standard Pushover request.
--   
--   This is similar to <a>createRequest</a>, except that token information
--   is read from within the monad stack.
createRequestM :: (MonadReader r m, PushoverReader r) => Message -> m Request

-- | Defines possible exceptions which can be thrown from execution
--   commands.
data PushoverException

-- | This exception is thrown when a response is malformed and cannot be
--   decoded.
ResponseDecodeException :: PushoverException

-- | This exception is thrown when a token cannot be constructed because it
--   contains invalid characters.
InvalidTokenCharactersException :: PushoverException

-- | This exception is thrown when a token cannot be constructed because it
--   is an incorrect length.
InvalidTokenLengthException :: PushoverException

-- | This is a generic exception for other errors in Pushover.
PushoverException :: String -> PushoverException


-- | This library provides functionality for interacting with the Pushover
--   API (<tt><a>https://www.pushover.net</a></tt>) 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 <tt><a>https://pushover.net/api</a></tt>.
--   
--   Requests are defined by the <a>Request</a> type. The
--   <a>defaultRequest</a> 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.
module Network.Pushover

-- | Send a request to the Pushover API.
--   
--   Requires a pair of Pushover tokens, together with a <a>Message</a>
--   value. These are used to construct a <a>defaultRequest</a> which is
--   then sent to the API.
sendMessage :: APIToken -> UserKey -> Message -> IO Response

-- | Send a request to the Pushover API.
--   
--   This is similar to <a>sendMessage</a>, except that a constructed
--   <a>Request</a> must be passed instead of the tokens and message.
sendRequest :: Request -> IO Response

-- | Create a standard Pushover request.
--   
--   This is an alias of the <a>defaultRequest</a> function.
createRequest :: APIToken -> UserKey -> Message -> Request

-- | 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 <a>PushoverReader</a> MonadReader
--   instance. These are then used to construct a <a>defaultRequest</a>
--   containing the passed <a>Message</a> value.
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.
--   
--   This is similar to <a>sendMessageM</a>, except that a constructed
--   <a>Request</a> must be passed instead of just the message.
sendRequestM :: (Error e, MonadError e m, MonadIO m) => Request -> m Response

-- | Create a standard Pushover request.
--   
--   This is similar to <a>createRequest</a>, except that token information
--   is read from within the monad stack.
createRequestM :: (MonadReader r m, PushoverReader r) => Message -> m Request

-- | Contains the contents of a Pushover notification request. This follows
--   the API specification at <tt><a>https://pushover.net/api</a></tt>.
data 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.
defaultRequest :: APIToken -> UserKey -> Message -> Request

-- | 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.
data Message

-- | Make a message from a list of message parts.
message :: [Message] -> Message

-- | Make a bold message.
bold :: [Message] -> Message

-- | Make an italic message.
italic :: [Message] -> Message

-- | Make an underlined message.
underline :: [Message] -> Message

-- | Make a message with colored text.
--   
--   Accepts three integer arguments for red, green and blue color
--   elements, respectively.
color :: Integer -> Integer -> Integer -> [Message] -> Message

-- | Make a url message.
link :: Url -> [Message] -> Message

-- | Make a textual message.
text :: Text -> Message
type APIToken = PushoverToken

-- | User key for the user receiving a notification.
type UserKey = 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
--   <a>makeToken</a> function is used to construct validated tokens.
data PushoverToken

-- | Construct a <a>PushoverToken</a> value.
--   
--   A <a>PushoverToken</a> 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.
makeToken :: Text -> Either PushoverException PushoverToken

-- | 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.
data URL
URL :: Text -> Maybe Text -> URL
[urlPath] :: URL -> Text
[urlTitle] :: URL -> Maybe Text

-- | Describes the priority of a particular message.
--   
--   The different priority settings affect the way in which a notification
--   is presented to the user. See
--   <tt><a>https://pushover.net/api#priority</a></tt> for specific
--   details.
data Priority
Lowest :: Priority
Low :: Priority
Normal :: Priority
High :: Priority
Emergency :: Priority

-- | Describes the notification sound for a notification.
data NotificationSound
Pushover :: NotificationSound
Bike :: NotificationSound
Bugle :: NotificationSound
CashRegister :: NotificationSound
Classical :: NotificationSound
Cosmic :: NotificationSound
Falling :: NotificationSound
Gamelan :: NotificationSound
Incoming :: NotificationSound
Intermission :: NotificationSound
Magic :: NotificationSound
Mechanical :: NotificationSound
PianoBar :: NotificationSound
Siren :: NotificationSound
SpaceAlarm :: NotificationSound
TugBoat :: NotificationSound
AlienAlarm :: NotificationSound
Climb :: NotificationSound
Persistent :: NotificationSound
Echo :: NotificationSound
UpDown :: NotificationSound
None :: NotificationSound

-- | Describes a response received to a notification request. This follows
--   the specification at
--   <tt><a>https://pushover.net/api#response</a></tt>.
--   
--   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.
data Response
Response :: ResponseStatus -> Text -> Response
[status] :: Response -> ResponseStatus
[request] :: Response -> Text

-- | The <a>PushoverReader</a> 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.
class PushoverReader r
apiToken :: PushoverReader r => r -> APIToken
userKey :: PushoverReader r => r -> UserKey

-- | A basic type for use in storing the pair of keys required for making a
--   request.
data PushoverKeys
PushoverKeys :: APIToken -> UserKey -> PushoverKeys
[_apiToken] :: PushoverKeys -> APIToken
[_userKey] :: PushoverKeys -> UserKey

-- | Construct a <a>PushoverKeys</a> value.
--   
--   This attempts to create valid tokens/keys from a pair of unvalidated
--   tokens/keys, returning the result wrapped within a MonadError.
createKeys :: (Error e, MonadError e m) => UnvalidatedAPIToken -> UnvalidatedUserKey -> m PushoverKeys

-- | Defines possible exceptions which can be thrown from execution
--   commands.
data PushoverException

-- | Display a description error message for each <a>PushoverException</a>
--   constructor.
errorMessage :: PushoverException -> String

module Lib
someFunc :: IO ()