gitter

README

gitter

Gitter API in Go https://developer.gitter.im

Install

go get github.com/sromku/go-gitter

• Initialize
• Users
• Rooms
• Messages
• Stream
• Faye (Experimental)
• Debug
• App Engine

Initialize

api := gitter.New("YOUR_ACCESS_TOKEN")

Users

• Get current user

  user, err := api.GetUser()
  

Rooms

• Get all rooms

  rooms, err := api.GetRooms()
  

• Get room by id

  room, err := api.GetRoom("roomID")
  

• Get rooms of some user

  rooms, err := api.GetRooms("userID")
  

• Join room

  room, err := api.JoinRoom("roomID", "userID")
  

• Leave room

  room, err := api.LeaveRoom("roomID", "userID")
  

• Get room id

  id, err := api.GetRoomId("room/uri")
  

• Search gitter rooms

  rooms, err := api.SearchRooms("search/string")
  

Messages

• Get messages of room

  messages, err := api.GetMessages("roomID", nil)
  

• Get one message

  message, err := api.GetMessage("roomID", "messageID")
  

• Send message

  err := api.SendMessage("roomID", "free chat text")
  

Stream

Create stream to the room and start listening to incoming messages

stream := api.Stream(room.Id)
go api.Listen(stream)

for {
    event := <-stream.Event
    switch ev := event.Data.(type) {
    case *gitter.MessageReceived:
        fmt.Println(ev.Message.From.Username + ": " + ev.Message.Text)
    case *gitter.GitterConnectionClosed:
        // connection was closed
    }
}

Close stream connection

stream.Close()

Faye (Experimental)

faye := api.Faye(room.ID)
go faye.Listen()

for {
    event := <-faye.Event
    switch ev := event.Data.(type) {
    case *gitter.MessageReceived:
        fmt.Println(ev.Message.From.Username + ": " + ev.Message.Text)
    case *gitter.GitterConnectionClosed: //this one is never called in Faye
        // connection was closed
    }
}

Debug

You can print the internal errors by enabling debug to true

api.SetDebug(true, nil)

You can also define your own io.Writer in case you want to persist the logs somewhere. For example keeping the errors on file

logFile, err := os.Create("gitter.log")
api.SetDebug(true, logFile)

App Engine

Initialize app engine client and continue as usual

c := appengine.NewContext(r)
client := urlfetch.Client(c)

api := gitter.New("YOUR_ACCESS_TOKEN")
api.SetClient(client)

Documentation

Documentation

Overview

Package gitter is a Go client library for the Gitter API.

Author: sromku

Index

• type APIError
  • func (e APIError) Error() string
• type Event
• type Faye
  • func (faye *Faye) Listen()
• type Gitter
  • func New(token string) *Gitter
  • func (gitter *Gitter) Faye(roomID string) *Faye
  • func (gitter *Gitter) GetMessage(roomID, messageID string) (*Message, error)
  • func (gitter *Gitter) GetMessages(roomID string, params *Pagination) ([]Message, error)
  • func (gitter *Gitter) GetRoom(roomID string) (*Room, error)
  • func (gitter *Gitter) GetRoomId(uri string) (string, error)
  • func (gitter *Gitter) GetRooms() ([]Room, error)
  • func (gitter *Gitter) GetUser() (*User, error)
  • func (gitter *Gitter) GetUserRooms(userID string) ([]Room, error)
  • func (gitter *Gitter) GetUsersInRoom(roomID string) ([]User, error)
  • func (gitter *Gitter) JoinRoom(roomID, userID string) (*Room, error)
  • func (gitter *Gitter) LeaveRoom(roomID, userID string) error
  • func (gitter *Gitter) Listen(stream *Stream)
  • func (gitter *Gitter) SearchRooms(room string) ([]Room, error)
  • func (gitter *Gitter) SendMessage(roomID, text string) (*Message, error)
  • func (gitter *Gitter) SetClient(client *http.Client)
  • func (gitter *Gitter) SetDebug(debug bool, logWriter io.Writer)
  • func (gitter *Gitter) Stream(roomID string) *Stream
  • func (gitter *Gitter) UpdateMessage(roomID, msgID, text string) (*Message, error)
• type GitterConnectionClosed
• type Issue
• type Mention
• type Message
• type MessageReceived
• type Pagination
• type Room
• type Stream
  • func (stream *Stream) Close()
• type URL
• type User

Types

type APIError

type APIError struct {
	What string
}

APIError holds data of errors returned from the API.

func (APIError) Error

func (e APIError) Error() string

type Event

type Event struct {
	Data interface{}
}

type Faye

type Faye struct {
	Event chan Event
	// contains filtered or unexported fields
}

func (*Faye) Listen

func (faye *Faye) Listen()

type Gitter

type Gitter struct {
	// contains filtered or unexported fields
}

func New

func New(token string) *Gitter

New initializes the Gitter API client

For example:

api := gitter.New("YOUR_ACCESS_TOKEN")

func (*Gitter) Faye

func (gitter *Gitter) Faye(roomID string) *Faye

func (*Gitter) GetMessage

func (gitter *Gitter) GetMessage(roomID, messageID string) (*Message, error)

GetMessage returns a message in a room.

func (*Gitter) GetMessages

func (gitter *Gitter) GetMessages(roomID string, params *Pagination) ([]Message, error)

GetMessages returns a list of messages in a room. Pagination is optional. You can pass nil or specific pagination params.

func (*Gitter) GetRoom

func (gitter *Gitter) GetRoom(roomID string) (*Room, error)

GetRoom returns a room with the passed id

func (*Gitter) GetRoomId

func (gitter *Gitter) GetRoomId(uri string) (string, error)

GetRoomId returns the room ID of a given URI

func (*Gitter) GetRooms

func (gitter *Gitter) GetRooms() ([]Room, error)

GetRooms returns a list of rooms the current user is in

func (*Gitter) GetUser

func (gitter *Gitter) GetUser() (*User, error)

GetUser returns the current user

func (*Gitter) GetUserRooms

func (gitter *Gitter) GetUserRooms(userID string) ([]Room, error)

GetUserRooms returns a list of Rooms the user is part of

func (*Gitter) GetUsersInRoom

func (gitter *Gitter) GetUsersInRoom(roomID string) ([]User, error)

GetUsersInRoom returns the users in the room with the passed id

func (*Gitter) JoinRoom

func (gitter *Gitter) JoinRoom(roomID, userID string) (*Room, error)

JoinRoom joins a room

func (*Gitter) LeaveRoom

func (gitter *Gitter) LeaveRoom(roomID, userID string) error

LeaveRoom removes a user from the room

func (*Gitter) Listen

func (gitter *Gitter) Listen(stream *Stream)

Implemented to conform with https://developer.gitter.im/docs/streaming-api

func (*Gitter) SearchRooms

func (gitter *Gitter) SearchRooms(room string) ([]Room, error)

SearchRooms queries the Rooms resources of gitter API

func (*Gitter) SendMessage

func (gitter *Gitter) SendMessage(roomID, text string) (*Message, error)

SendMessage sends a message to a room

func (*Gitter) SetClient

func (gitter *Gitter) SetClient(client *http.Client)

SetClient sets a custom http client. Can be useful in App Engine case.

func (*Gitter) SetDebug

func (gitter *Gitter) SetDebug(debug bool, logWriter io.Writer)

SetDebug traces errors if it's set to true.

func (*Gitter) Stream

func (gitter *Gitter) Stream(roomID string) *Stream

Stream initialize stream

func (*Gitter) UpdateMessage

func (gitter *Gitter) UpdateMessage(roomID, msgID, text string) (*Message, error)

UpdateMessage updates a message in a room

type GitterConnectionClosed

type GitterConnectionClosed struct {
}

type Issue

type Issue struct {

	// Issue number
	Number string `json:"number"`
}

Issue references issue in the message

type Mention

type Mention struct {

	// User's username
	ScreenName string `json:"screenName"`

	// Gitter User ID
	UserID string `json:"userID"`
}

Mention holds data about mentioned user in the message

type Message

type Message struct {

	// ID of the message
	ID string `json:"id"`

	// Original message in plain-text/markdown
	Text string `json:"text"`

	// HTML formatted message
	HTML string `json:"html"`

	// ISO formatted date of the message
	Sent time.Time `json:"sent"`

	// ISO formatted date of the message if edited
	EditedAt time.Time `json:"editedAt"`

	// User that sent the message
	From User `json:"fromUser"`

	// Boolean that indicates if the current user has read the message.
	Unread bool `json:"unread"`

	// Number of users that have read the message
	ReadBy int `json:"readBy"`

	// List of URLs present in the message
	Urls []URL `json:"urls"`

	// List of @Mentions in the message
	Mentions []Mention `json:"mentions"`

	// List of #Issues referenced in the message
	Issues []Issue `json:"issues"`

	// Version
	Version int `json:"v"`
}

type MessageReceived

type MessageReceived struct {
	Message Message
}

type Pagination

type Pagination struct {

	// Skip n messages
	Skip int

	// Get messages before beforeId
	BeforeID string

	// Get messages after afterId
	AfterID string

	// Maximum number of messages to return
	Limit int

	// Search query
	Query string
}

Pagination params

type Room

type Room struct {

	// Room ID
	ID string `json:"id"`

	// Room name
	Name string `json:"name"`

	// Room topic. (default: GitHub repo description)
	Topic string `json:"topic"`

	// Room URI on Gitter
	URI string `json:"uri"`

	// Indicates if the room is a one-to-one chat
	OneToOne bool `json:"oneToOne"`

	// Count of users in the room
	UserCount int `json:"userCount"`

	// Number of unread messages for the current user
	UnreadItems int `json:"unreadItems"`

	// Number of unread mentions for the current user
	Mentions int `json:"mentions"`

	// Last time the current user accessed the room in ISO format
	LastAccessTime time.Time `json:"lastAccessTime"`

	// Indicates if the current user has disabled notifications
	Lurk bool `json:"lurk"`

	// Path to the room on gitter
	URL string `json:"url"`

	// Type of the room
	// - ORG: A room that represents a GitHub Organization.
	// - REPO: A room that represents a GitHub Repository.
	// - ONETOONE: A one-to-one chat.
	// - ORG_CHANNEL: A Gitter channel nested under a GitHub Organization.
	// - REPO_CHANNEL A Gitter channel nested under a GitHub Repository.
	// - USER_CHANNEL A Gitter channel nested under a GitHub User.
	GithubType string `json:"githubType"`

	// Tags that define the room
	Tags []string `json:"tags"`

	RoomMember bool `json:"roomMember"`

	// Room version.
	Version int `json:"v"`
}

A Room in Gitter can represent a GitHub Organization, a GitHub Repository, a Gitter Channel or a One-to-one conversation. In the case of the Organizations and Repositories, the access control policies are inherited from GitHub.

type Stream

type Stream struct {
	Event chan Event
	// contains filtered or unexported fields
}

Stream holds stream data.

func (*Stream) Close

func (stream *Stream) Close()

Close the stream connection and stop receiving streamed data

type URL

type URL struct {

	// URL
	URL string `json:"url"`
}

URL presented in the message

type User

type User struct {

	// Gitter User ID
	ID string `json:"id"`

	// Gitter/GitHub username
	Username string `json:"username"`

	// Gitter/GitHub user real name
	DisplayName string `json:"displayName"`

	// Path to the user on Gitter
	URL string `json:"url"`

	// User avatar URI (small)
	AvatarURLSmall string `json:"avatarUrlSmall"`

	// User avatar URI (medium)
	AvatarURLMedium string `json:"avatarUrlMedium"`
}