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.

Examples are available at the github repository for this project at: https://github.com/yamadapc/hzulip

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 ZulipM = ReaderT ZulipOptions IO

The Monad in which Zulip API actions happen in. This is a ReaderT alias, so it's also a instance of MonadTrans, MonadIO etc.

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.

addAllSubscriptions :: ZulipM [String]

Subscribes the client to all available streams and returns all the stream names

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

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.

sinkZulipMessages :: Sink (String, [String], String, String) ZulipM ()

A sink representation of the zulip messaging API, takes a tuple with the arguments for sendMessage and sends it

sourceZulipEvents

Arguments

:: Int

The size of the event buffer

-> [String]

A list of event types to subscribe to

-> Source ZulipM Event

Creates a conduit Source of zulip events

sourceZulipMessages

Arguments

:: Int

The size of the event buffer

-> Source ZulipM Message

Creates a conduit Source of zulip messages

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

lift :: MonadTrans t => forall m a. Monad m => m a -> t m a

Lift a computation from the argument monad to the constructed monad.

ask :: Monad m => ReaderT r m r

Fetch the value of the environment.