Web.HZulip

A Wrapper library for the Zulip API. Works on top of a ReaderT monad transformer, holding a ZulipOptions object, which should hold the state and configuration for the API client.

Using the library is made easier through a set of helper functions. This design is more concise and than passing around configuration variables; one could easily bypass it with the use of runZulip, though that isn't recommended.

Example usage: > import Web.HZulip > > main :: IO () > main = withZulipCreds "zulip-api-user" "zulip-api-key" $ do > -- Since we are inside the ZulipM ReaderT monad transformer, we > -- don't need to pass options around. The above function already > -- created an HTTP manager, for connection pooling and wrapped the > -- default configuration options with the Monad: > print =<< getSubscriptions > -- >> ["haskell"] > > -- Sending messages is as easy as: > void $ sendStreamMessage "haskell" -- message stream > "hzulip" -- message topic > "Message from Haskell" -- message content > > -- Listening for events works with a callback based API. More > -- complex patterns for concurrent message handling can be created > -- from it. As long as your zulip user is already subscribed to > -- streams, this is all you have to do: > onNewEvent ["message"] $ msg -> do > liftIO $ putStrLn "Got a new message!" > let usr = messageSender msg > fn = userFullName usr > e = userEmail usr > > sendPrivateMessage [e] $ "Thanks for the message " ++ fn ++ "!!"

Documentation

data Event

Represents zulip events

Constructors

Event

Fields

eventType :: String

eventId :: Int

eventMessage :: Maybe Message

Instances

Eq Event

Ord Event

Show Event

FromJSON Event

data Message

Represents a Zulip Message

Constructors

Message

Fields

messageId :: Int

messageType :: String

messageContent :: String

messageAvatarUrl :: String

messageTimestamp :: Int

messageDisplayRecipient :: Either String [User]

messageSender :: User

messageGravatarHash :: String

messageRecipientId :: Int

messageClient :: String

messageSubjectLinks :: [String]

messageSubject :: String

Instances

Eq Message

Ord Message

Show Message

FromJSON Message

data Queue

Represents some event queue

Constructors

Queue

Fields

queueId :: String

lastEventId :: Int

Instances

Eq Queue

Ord Queue

Show Queue

data User

Represents a zulip user account - for both display_recipient and message_sender representations

Constructors

User

Fields

userId :: Int

userFullName :: String

userEmail :: String

userDomain :: String

userShortName :: String

Instances

Eq User

Ord User

Show User

FromJSON User

data ZulipOptions

Represents a Zulip API client

Constructors

ZulipOptions

Fields

clientEmail :: String

clientApiKey :: String

clientBaseUrl :: String

clientManager :: Manager

Instances

Show ZulipOptions

type EventCallback = Event -> ZulipM ()

The root type for Event callbacks

type MessageCallback = Message -> ZulipM ()

Type for message callbacks

addSubscriptions :: [String] -> ZulipM ()

Add new Stream subscriptions to the client.

defaultBaseUrl :: String

The default zulip API URL

eventTypes :: [String]

The list of all avaiable event types

getEvents :: Queue -> Bool -> ZulipM (Queue, [Event])

Fetches new set of events from a Queue.

getStreams :: ZulipM [String]

Get a list of all the public streams

getStreamSubscribers :: String -> ZulipM [String]

Get all the user emails subscribed to a stream

getSubscriptions :: ZulipM [String]

Get a list of the streams the client is currently subscribed to.

onNewEvent :: [String] -> EventCallback -> ZulipM ()

Registers an event callback for specified events and keeps executing it over events as they come in. Will loop forever

onNewMessage :: MessageCallback -> ZulipM ()

Registers a callback to be executed whenever a message comes in. Will loop forever

registerQueue :: [String] -> Bool -> ZulipM Queue

This registers a new event queue with the zulip API. It's a lower level function, which shouldn't be used unless you know what you're doing. It takes a list of names of the events you want to listen for and whether you'd like for the content to be rendered in HTML format (if you set the last parameter to False it will be kept as typed, in markdown format)

removeSubscriptions :: [String] -> ZulipM ()

Remove one or more Stream subscriptions from the client

runZulip :: ZulipM a -> ZulipOptions -> IO a

Helper to run Actions in the Zulip Monad

sendMessage :: String -> [String] -> String -> String -> ZulipM Int

This wraps `POST https://api.zulip.com/v1/messages` with a nicer root API. Simpler helpers for each specific case of this somewhat overloaded endpoint will also be provided in the future.

It takes the message mtype, mrecipients, msubject and mcontent and returns the created message's id in the ZulipM monad.

sendPrivateMessage :: [String] -> String -> ZulipM Int

Helper for sending private messages. Takes the list of recipients and the message's content.

sendStreamMessage :: String -> String -> String -> ZulipM Int

Helper for sending stream messages. Takes the stream name, the subject and the message.

withZulip :: ZulipOptions -> ZulipM a -> IO a

Flipped version of runZulip

withZulipCreds :: String -> String -> ZulipM a -> IO a

Helper for creating a minimal ZulipOptions object and running an action in the ZulipM monad

zulipOptions :: String -> String -> IO ZulipOptions

Helper for creating a ZulipOptions object with the baseUrl set to defaultBaseUrl