gozulipbot

README

GoZulipBot

gozulipbot is a library to interact with Zulip in Go. It is primarily targeted toward making bots.

Installation

go get github.com/ifo/gozulipbot

Usage

Make sure to add gozulipbot to your imports:

import (
  gzb "github.com/ifo/gozulipbot"
)

Check out the examples directory for more info.

Documentation

Index

• Variables
• type Bot
  • func (b *Bot) GetConfigFromFlags() error
  • func (b *Bot) GetStreamList() (*http.Response, error)
  • func (b *Bot) GetStreams() ([]string, error)
  • func (b *Bot) Init() *Bot
  • func (b *Bot) ListSubscriptions() (*http.Response, error)
  • func (b *Bot) Message(m Message) (*http.Response, error)
  • func (b *Bot) PrivateMessage(m Message) (*http.Response, error)
  • func (b *Bot) RawRegisterEvents(ets []EventType, n Narrow) (*http.Response, error)
  • func (b *Bot) React(e EventMessage, emoji string) (*http.Response, error)
  • func (b *Bot) RealmEmoji() (map[string]*Emoji, error)
  • func (b *Bot) RealmEmojiSet() (map[string]struct{}, error)
  • func (b *Bot) RegisterAll() (*Queue, error)
  • func (b *Bot) RegisterAt() (*Queue, error)
  • func (b *Bot) RegisterEvents(ets []EventType, n Narrow) (*Queue, error)
  • func (b *Bot) RegisterPrivate() (*Queue, error)
  • func (b *Bot) RegisterSubscriptions() (*Queue, error)
  • func (b *Bot) Respond(e EventMessage, response string) (*http.Response, error)
  • func (b *Bot) Subscribe(streams []string) (*http.Response, error)
  • func (b *Bot) Unreact(e EventMessage, emoji string) (*http.Response, error)
  • func (b *Bot) Unsubscribe(streams []string) (*http.Response, error)
• type DisplayRecipient
  • func (d *DisplayRecipient) UnmarshalJSON(b []byte) (err error)
• type Doer
• type Emoji
• type EmojiResponse
• type EventMessage
• type EventType
• type Message
• type Narrow
• type Queue
  • func (q *Queue) EventsCallback(fn func(EventMessage, error)) func()
  • func (q *Queue) EventsChan() (chan EventMessage, func())
  • func (q *Queue) GetEvents() ([]EventMessage, error)
  • func (q *Queue) ParseEventMessages(rawEventResponse []byte) ([]EventMessage, error)
  • func (q *Queue) RawGetEvents() (*http.Response, error)
• type StreamJSON
• type User

Variables

var (
	HeartbeatError    = fmt.Errorf("EventMessage is a heartbeat")
	UnauthorizedError = fmt.Errorf("Request is unauthorized")
	BackoffError      = fmt.Errorf("Too many requests")
	UnknownError      = fmt.Errorf("Error was unknown")
)

Types

type Bot

type Bot struct {
	APIKey  string
	APIURL  string
	Email   string
	Queues  []*Queue
	Streams []string
	Client  Doer
	Backoff time.Duration
	Retries int64
}

func (*Bot) GetConfigFromFlags

func (b *Bot) GetConfigFromFlags() error

func (*Bot) GetStreamList

func (b *Bot) GetStreamList() (*http.Response, error)

GetStreamList gets the raw http response when requesting all public streams.

func (*Bot) GetStreams

func (b *Bot) GetStreams() ([]string, error)

GetStreams returns a list of all public streams

func (*Bot) Init

func (b *Bot) Init() *Bot

Init adds an http client to an existing bot struct.

func (*Bot) ListSubscriptions

func (b *Bot) ListSubscriptions() (*http.Response, error)

func (*Bot) Message

func (b *Bot) Message(m Message) (*http.Response, error)

Message posts a message to Zulip. If any emails have been set on the message, the message will be re-routed to the PrivateMessage function.

func (*Bot) PrivateMessage

func (b *Bot) PrivateMessage(m Message) (*http.Response, error)

PrivateMessage sends a message to the users in the message email slice.

func (*Bot) RawRegisterEvents

func (b *Bot) RawRegisterEvents(ets []EventType, n Narrow) (*http.Response, error)

RawRegisterEvents tells Zulip to include message events in the bots events queue. Passing nil as the slice of EventType will default to receiving Messages

func (*Bot) React

func (b *Bot) React(e EventMessage, emoji string) (*http.Response, error)

React adds an emoji reaction to an EventMessage.

func (*Bot) RealmEmoji

func (b *Bot) RealmEmoji() (map[string]*Emoji, error)

RealmEmoji gets the custom emoji information for the Zulip instance.

func (*Bot) RealmEmojiSet

func (b *Bot) RealmEmojiSet() (map[string]struct{}, error)

RealmEmojiSet makes a set of the names of the custom emoji in the Zulip instance.

func (*Bot) RegisterAll

func (b *Bot) RegisterAll() (*Queue, error)

func (*Bot) RegisterAt

func (b *Bot) RegisterAt() (*Queue, error)

func (*Bot) RegisterEvents

func (b *Bot) RegisterEvents(ets []EventType, n Narrow) (*Queue, error)

RegisterEvents adds a queue to the bot. It includes the EventTypes and Narrow given. If neither is given, it will default to all Messages.

func (*Bot) RegisterPrivate

func (b *Bot) RegisterPrivate() (*Queue, error)

func (*Bot) RegisterSubscriptions

func (b *Bot) RegisterSubscriptions() (*Queue, error)

func (*Bot) Respond

func (b *Bot) Respond(e EventMessage, response string) (*http.Response, error)

Respond sends a given message as a response to whatever context from which an EventMessage was received.

func (*Bot) Subscribe

func (b *Bot) Subscribe(streams []string) (*http.Response, error)

Subscribe will set the bot to receive messages from the given streams. If no streams are given, it will subscribe the bot to the streams in the bot struct.

func (*Bot) Unreact

func (b *Bot) Unreact(e EventMessage, emoji string) (*http.Response, error)

Unreact removes an emoji reaction from an EventMessage.

func (*Bot) Unsubscribe

func (b *Bot) Unsubscribe(streams []string) (*http.Response, error)

Unsubscribe will remove the bot from the given streams. If no streams are given, nothing will happen and the function will error.

type DisplayRecipient

type DisplayRecipient struct {
	Users []User `json:"users,omitempty"`
	Topic string `json:"topic,omitempty"`
}

func (*DisplayRecipient) UnmarshalJSON

func (d *DisplayRecipient) UnmarshalJSON(b []byte) (err error)

type Doer

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

type Emoji

type Emoji struct {
	Author     string `json:"author"`
	DisplayURL string `json:"display_url"`
	SourceURL  string `json:"source_url"`
}

type EmojiResponse

type EmojiResponse struct {
	Emoji  map[string]*Emoji `json:"emoji"`
	Msg    string            `json:"msg"`
	Result string            `json:"result"`
}

type EventMessage

type EventMessage struct {
	AvatarURL        string           `json:"avatar_url"`
	Client           string           `json:"client"`
	Content          string           `json:"content"`
	ContentType      string           `json:"content_type"`
	DisplayRecipient DisplayRecipient `json:"display_recipient"`
	GravatarHash     string           `json:"gravatar_hash"`
	ID               int              `json:"id"`
	RecipientID      int              `json:"recipient_id"`
	SenderDomain     string           `json:"sender_domain"`
	SenderEmail      string           `json:"sender_email"`
	SenderFullName   string           `json:"sender_full_name"`
	SenderID         int              `json:"sender_id"`
	SenderShortName  string           `json:"sender_short_name"`
	Subject          string           `json:"subject"`
	SubjectLinks     []interface{}    `json:"subject_links"`
	Timestamp        int              `json:"timestamp"`
	Type             string           `json:"type"`
	Queue            *Queue           `json:"-"`
}

type EventType

type EventType string

const (
	Messages      EventType = "messages"
	Subscriptions EventType = "subscriptions"
	RealmUser     EventType = "realm_user"
	Pointer       EventType = "pointer"
)

type Message

type Message struct {
	Stream  string
	Topic   string
	Emails  []string
	Content string
}

A Message is all of the necessary metadata to post on Zulip. It can be either a public message, where Topic is set, or a private message, where there is at least one element in Emails.

If the length of Emails is not 0, functions will always assume it is a private message.

type Narrow

type Narrow string

const (
	NarrowPrivate Narrow = `[["is", "private"]]`
	NarrowAt      Narrow = `[["is", "mentioned"]]`
)

type Queue

type Queue struct {
	ID           string `json:"queue_id"`
	LastEventID  int    `json:"last_event_id"`
	MaxMessageID int    `json:"max_message_id"`
	Bot          *Bot   `json:"-"`
}

func (*Queue) EventsCallback

func (q *Queue) EventsCallback(fn func(EventMessage, error)) func()

EventsCallback will repeatedly call the provided callback function with the output of continual queue.GetEvents calls. It returns a function which can be called to end the calls.

It will end early if it receives an UnauthorizedError, or an unknown error. Note, it will never return a HeartbeatError.

func (*Queue) EventsChan

func (q *Queue) EventsChan() (chan EventMessage, func())

func (*Queue) GetEvents

func (q *Queue) GetEvents() ([]EventMessage, error)

GetEvents is a blocking call that waits for and parses a list of EventMessages. There will usually only be one EventMessage returned. When a heartbeat is returned, GetEvents will return a HeartbeatError. When an http status code above 400 is returned, one of a BackoffError, UnauthorizedError, or UnknownError will be returned.

func (*Queue) ParseEventMessages

func (q *Queue) ParseEventMessages(rawEventResponse []byte) ([]EventMessage, error)

func (*Queue) RawGetEvents

func (q *Queue) RawGetEvents() (*http.Response, error)

RawGetEvents is a blocking call that receives a response containing a list of events (a.k.a. received messages) since the last message id in the queue.

type StreamJSON

type StreamJSON struct {
	Msg     string `json:"msg"`
	Streams []struct {
		StreamID    int    `json:"stream_id"`
		InviteOnly  bool   `json:"invite_only"`
		Description string `json:"description"`
		Name        string `json:"name"`
	} `json:"streams"`
	Result string `json:"result"`
}

type User

type User struct {
	Domain        string `json:"domain"`
	Email         string `json:"email"`
	FullName      string `json:"full_name"`
	ID            int    `json:"id"`
	IsMirrorDummy bool   `json:"is_mirror_dummy"`
	ShortName     string `json:"short_name"`
}