hipchat

package
v0.0.0-...-2c86491 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 26, 2018 License: BSD-3-Clause Imports: 18 Imported by: 0

Documentation

Overview

go-hipchat is a Go client library for accessing the https://developer.atlassian.com/server/hipchat/about-the-hipchat-rest-api/.

go-hipchat requires Go version 1.8 or greater.

Usage:

Construct a new HipChat client, then use the various services on the client to access different parts of the HipChat API. For example:

Some API methods have optional parameters that can be passed. For example:

NOTE: Using the https://godoc.org/context package, one can easily pass cancelation signals and deadlines to various services of the client for handling a request. In case there is no context available, then `context.Background()` can be used as a starting point.

For more sample code snippets, head over to the https://github.com/theodesp/go-hipchat/tree/master/examples directory.

Authentication:

The go-hipchat library does not directly handle authentication. Instead, when creating a new client, pass an `http.Client` that can handle authentication for you. The easiest and recommended way to do this is using the golang.org/x/oauth2 library, but you can always use any other library that provides an `http.Client`. If you have an OAuth2 access token (for example, a https://developer.atlassian.com/server/hipchat/hipchat-rest-api-access-tokens/, you can use it with the oauth2 library using:

Note that when using an authenticated Client, all calls made by the client will include the specified OAuth token. Therefore, authenticated clients should almost never be shared between different users.

See the oauth2 docs for complete instructions on using that library.

Rate Limiting:

Hipchat imposes a rate limit on all API clients. 500 API requests per 5 minutes. Once you exceed the limit, calls will return HTTP status 429.

Learn more about HipChat rate limiting at https://developer.atlassian.com/server/hipchat/hipchat-rest-api-rate-limits.

Response Codes:

https://developer.atlassian.com/server/hipchat/hipchat-rest-api-response-codes

Pagination:

Index

Constants

View Source 
const (
	// Public Room access
	RoomPrivacyPublic = "public"

	// Private Room access
	RoomPrivacyPrivate = "private"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	BaseUrl   *url.URL
	UserAgent string

	Rooms *RoomsService
	// contains filtered or unexported fields
}

A Client communicates with the HipChat API.

func NewClient 

func NewClient(httpClient *http.Client) *Client

NewClient returns a new HipChat API client

func (*Client) Delete 

func (c *Client) Delete(urlStr string) (*http.Request, error)

Convenient shorthand for DELETE requests

func (*Client) Do 

func (c *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*PaginatedResponse, error)

The provided ctx must be non-nil. If it is canceled or times out, ctx.Err() will be returned.

func (*Client) Get 

func (c *Client) Get(urlStr string) (*http.Request, error)

Convenient shorthand for GET requests

func (*Client) NewRequest 

func (c *Client) NewRequest(method, urlStr string, body interface{}) (*http.Request, error)

NewRequest creates an API request. A relative URL can be provided in urlStr, in which case it is resolved relative to the BaseURL of the Client. Relative URLs should always be specified without a preceding slash. If specified, the value pointed to by body is JSON encoded and included as the request body.

func (*Client) NewUploadRequest 

func (c *Client) NewUploadRequest(
	urlStr string,
	reader io.Reader,
	size int64,
	mediaType string,
	body interface{},
	fileName string) (*http.Request, error)

NewUploadRequest creates an upload request.

func (*Client) Post 

func (c *Client) Post(urlStr string, body interface{}) (*http.Request, error)

Convenient shorthand for POST requests

func (*Client) Put 

func (c *Client) Put(urlStr string, body interface{}) (*http.Request, error)

Convenient shorthand for PUT requests

func (*Client) SetApiVersion 

func (c *Client) SetApiVersion(apiVersion string) error

Sets the HipChat API version. This defaults to v2

type ListOptions 

type ListOptions struct {
	// For paginated result sets, StartIndex is the starting index of the request.
	StartIndex int `url:"start-index,omitempty"`

	// For paginated result sets, StartIndex is the maximum number of results to include per page.
	MaxResults int `url:"max-results,omitempty"`
}

ListOptions specifies the optional parameters to various List methods that support pagination.

type PaginatedResponse 

type PaginatedResponse struct {
	*http.Response
	MaxResults int
	StartIndex int
	Links      *PaginationLinks
}

PaginatedResponse is a HipChat API response. This wraps the standard http.Response returned from HipChat and provides convenient access to things like pagination links. 

type PaginationLinks struct {
	Next string
	Prev string
	Self string
}

PaginationLinks consists of a list of links for the current, next and previous pagination results based on the current parameters.

type Room 

type Room struct {
	RoomListItem

	// XMPP/Jabber Id of the room.
	XmppJid string `json:"xmpp_jid"`

	// Time the room was created in ISO 8601 format UTC.
	Created string `json:"created"`

	// Privacy setting
	// Valid values: public, private.
	Privacy string `json:"privacy"`

	// Whether or not guests can access this room.
	IsGuestAccessible bool `json:"is_guest_accessible"`

	// URL to rooms's avatar. 125px on the longest side.
	AvatarUrl string `json:"avatar_url"`

	// Whether the room is visible to delegate admins, may be null to use the group default.
	// May be null.
	DelegateAdminVisibility bool `json:"delegate_admin_visibility"`

	// Current topic.
	Topic string `json:"topic"`

	// URL for guest access, if enabled.
	// May be null.
	GuestAccessUrl string `json:"guest_access_url"`

	Owner *UserListItem `json:"owner,omitempty"`

	// Statistics for this room.
	Statistics *struct {
		Links *struct {
			// The URL to use to retrieve room statistics
			Self string `json:"self"`
		} `json:"links,omitempty"`
	} `json:"statistics,omitempty"`
}

Room represents a HipChat Room

func NewRoom 

func NewRoom(name string) *Room

Creates a new Room Object 

type RoomLinks struct {
	// The URL to use to retrieve the full room information
	Self string `json:"self"`

	// The URL to use to retrieve webhooks registered for this room
	Webhooks string `json:"webhooks"`

	// The URL to use to retrieve members for this room. Only available for private rooms.
	Members string `json:"members,omitempty"`

	//The URL to use to retrieve participants for this room
	Participants string `json:"participants"`
}

type RoomListItem 

type RoomListItem struct {
	// Id of the room.
	Id int64 `json:"id"`

	// Whether or not this room is archived.
	IsArchived bool `json:"is_archived"`

	// Name of the room.
	Name string `json:"name"`

	// Privacy setting. Valid values: public, private.
	Privacy string `json:"privacy"`

	// An etag-like random version string.
	Version string `json:"version"`

	// URLs to retrieve room information
	Links *RoomLinks `json:"links,omitempty"`
}

RoomListItem represents a HipChat Room list item

type RoomMessage 

type RoomMessage struct {
	// The unique identifier of the sent message.
	Id string `json:"id"`

	// The UTC timestamp representing when the message was processed.
	Timestamp string `json:"timestamp"`
}

RoomMessage represents a HipChat Room Message

type RoomParticipantsOptions 

type RoomParticipantsOptions struct {
	// Filter users by status (boolean). Only valid for private rooms.
	//
	// Defaults to 'false'.
	IncludeOffline bool `url:"include-offline,omitempty"`
	ListOptions
}

RoomParticipantsOptions specifies the optional parameters to the RoomService.GetRoomParticipants

type RoomStatistic 

type RoomStatistic struct {
	// The number of messages sent in this room for its entire history.
	MessagesSent int64 `json:"messages_sent"`

	// Time of last activity (sent message) in the room in UNIX time (UTC).
	// May be null in rare cases when the time is unknown.
	LastActive string `json:"last_active"`
}

RoomStatistic represents a HipChat Room Statistic

type RoomsListOptions 

type RoomsListOptions struct {
	// Filter out private rooms
	IncludePrivate bool `url:"include-private,omitempty"`

	// Filter rooms
	IncludeArchived bool `url:"include-archived,omitempty"`
	ListOptions
}

RoomsListOptions specifies the optional parameters to the RoomService.ListRooms

type RoomsService 

type RoomsService service

RoomsService handles communication with the room related methods of the HipChat API.

func (*RoomsService) AddRoomMember 

func (s *RoomsService) AddRoomMember(ctx context.Context, roomIdOrName string, userIdOrName string) (*PaginatedResponse, error)

Adds a member to a private room and sends member's unavailable presence to all room members asynchronously.

Authentication required, with scope admin_room. Accessible by group clients, room clients, users.

func (*RoomsService) CreateRoom 

func (s *RoomsService) CreateRoom(ctx context.Context, room *Room) (*Room, *PaginatedResponse, error)

Creates a new room.

Authentication required, with scope manage_rooms. Accessible by group clients, users.

func (*RoomsService) DeleteRoom 

func (s *RoomsService) DeleteRoom(ctx context.Context, roomIdOrName string) (*PaginatedResponse, error)

Deletes a room and kicks the current participants.

Authentication required, with scope manage_rooms. Accessible by group clients, users.

func (*RoomsService) GetRoom 

func (s *RoomsService) GetRoom(ctx context.Context, roomIdOrName string) (*Room, *PaginatedResponse, error)

Get room details.

Authentication required, with scope view_group or view_room. Accessible by group clients, room clients, users.

func (*RoomsService) GetRoomMembers 

func (s *RoomsService) GetRoomMembers(ctx context.Context, roomIdOrName string, opt *ListOptions) ([]*UserListItem, *PaginatedResponse, error)

Gets all members for this private room.

Authentication required, with scope view_room. Accessible by group clients, room clients, users.

func (*RoomsService) GetRoomParticipants 

func (s *RoomsService) GetRoomParticipants(ctx context.Context, roomIdOrName string, opt *RoomParticipantsOptions) ([]*UserListItem, *PaginatedResponse, error)

Gets all participants in this room.

Authentication required, with scope view_room. Accessible by group clients, room clients, users.

func (*RoomsService) GetRoomStatistics 

func (s *RoomsService) GetRoomStatistics(ctx context.Context, roomIdOrName string) (*RoomStatistic, *PaginatedResponse, error)

Fetch statistics for this room.

Authentication required, with scope view_group or view_room. Accessible by group clients, room clients, users.

func (*RoomsService) InviteUser 

func (s *RoomsService) InviteUser(ctx context.Context, roomIdOrName string, userIdOrName string, reason string) (*PaginatedResponse, error)

Invite a user to a public room.

Authentication required, with scope admin_room. Accessible by users.

func (*RoomsService) ListRooms 

func (s *RoomsService) ListRooms(ctx context.Context, opt *RoomsListOptions) ([]*RoomListItem, *PaginatedResponse, error)

List non-archived rooms for this group.

Authentication required, with scope view_group or view_room. Accessible by group clients, users.

func (*RoomsService) RemoveRoomMember 

func (s *RoomsService) RemoveRoomMember(ctx context.Context, roomIdOrName string, userIdOrName string) (*PaginatedResponse, error)

Removes a member from a private room.

Authentication required, with scope admin_room. Accessible by group clients, room clients, users.

func (*RoomsService) ReplyToRoomMessage 

func (s *RoomsService) ReplyToRoomMessage(ctx context.Context, roomIdOrName string, messageId string, message string) (*PaginatedResponse, error)

Reply to a message in a room.

Authentication required, with scope send_message. Accessible by users.

func (*RoomsService) SendRoomMessage 

func (s *RoomsService) SendRoomMessage(ctx context.Context, roomIdOrName string, message string) (*RoomMessage, *PaginatedResponse, error)

Send a message to a room.

Authentication required, with scope send_message. Accessible by users.

func (*RoomsService) SetRoomTopic 

func (s *RoomsService) SetRoomTopic(ctx context.Context, roomIdOrName string, topic string) (*PaginatedResponse, error)

Set a room's topic. Useful for displaying statistics, important links, server status, you name it!

Authentication required, with scope admin_room. Accessible by group clients, room clients, users.

func (*RoomsService) ShareFile 

func (s *RoomsService) ShareFile(ctx context.Context, roomIdOrName string, file *os.File, message string) (*PaginatedResponse, error)

Share a file with the room.

Format the request as multipart/related with a single part of content-type application/json and a second part containing your file.

func (*RoomsService) ShareLinkWithRoom 

func (s *RoomsService) ShareLinkWithRoom(ctx context.Context, roomIdOrName string, message string, link string) (*PaginatedResponse, error)

Share a link with the room.

Authentication required, with scope send_message. Accessible by users.

func (*RoomsService) UpdateRoom 

func (s *RoomsService) UpdateRoom(ctx context.Context, roomIdOrName string, room *Room) (*PaginatedResponse, error)

Updates a room.

Authentication required, with scope admin_room. Accessible by group clients, users. 

type UserLinks struct {
	// The link to use to retrieve the user information
	Self string `json:"self"`
}

type UserListItem 

type UserListItem struct {
	// The user Id.
	Id int64 `json:"id"`

	// User's @mention name.
	MentionName string `json:"mention_name"`

	// The display user name
	Name string `json:"name"`

	// An etag-like random version string.
	Version string `json:"version"`

	// URLs to retrieve user information
	Links *UserLinks `json:"links,omitempty"`
}

UserListItem represents a HipChat User list item

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.