slackmech

README

slackmech

Package slackmech is a package for mechanizing requests to the Slack API. It helps imitate a web session with Slack, to present you with a session API token. This token has different API access, including undocumented behaviors, to allow special features of the Web/Electron UI. This package will also abstract away some of those API calls, making it easier to consume them.

As of now, the features of this project are focused towards a bot for moderating Open Source Slack communities. Things will be added as they are needed to support that effort, or as contributions from others are made.

This package is still under active development.

Compatibility Notice

The behaviors and functions relied on by this package are largely undocumented, and the usage of them fall outside of any compatibility guarantees provided by Slack. While the functionality provided by this package is necessary, it's reasonable to assume it may break unexpectedly in the future.

As such, at the time of writing, it seems unlikely that this package will ever be able to see a 1.0.0 release. However, efforts will be made to retain API compatibility as long as possible. The package will have releases, using git tags, following the Semantic Version v2.0.0 spec.

License

This source code of this package is released under the MIT License. Please see the LICENSE for the full content of the license.

Usage

To be a respectful user of the Slack APIs, be sure to use an *http.Client with a cookiejar set, preferably one that makes use of persistence. In our example, we'll use the standard cookiejar implementation.

Here we'll create a cookiekar, create an HTTP client, create a new slackmech client, log in, and then use the Session Token to create a new API client:

import (
	"log"
	"net/http"
	"net/http/cookiejar"
	"os"

	"github.com/nlopes/slack"
	"github.com/theckman/slackmech"

	"golang.org/x/net/publicsuffix"
)

func main() {
	email := os.Getenv("SLACK_EMAIL")
	password := os.Getenv("SLACK_PASSWORD")
	subdomain := os.Getenv("SLACK_SUBDOMAIN")

	cj, err := cookiejar.New(&cookiejar.Options{PublicSuffixList: publicsuffix.List})
	if err != nil {
		log.Fatal(err)
	}

	// new http client with cookiejar set
	client := &http.Client{
		Jar: cj,
	}

	// don't follow redirects -- needed by slackmech
	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
		return http.ErrUseLastResponse
	}

	// new slackmech client
	sm, err := slackmech.New(client, subdomain)
	if err != nil {
		log.Fatal(err)
	}

	// log in and get a new session
	err = sm.StartSession(email, password)
	if err != nil {
		log.Fatal(err)
	}

	// use the slackmech SessionToken to build a new Slack API client
	// also pass in the HTTP client used to log in to continue using cookies
	api := slack.New(sm.SessionToken(), slack.OptionHTTPClient(client))
}

Documentation

Overview

Package slackmech is a package for mechanizing requests to the Slack API. It helps imitate a web session with Slack, to present you with a session API token. This token has different API access, including undocumented behaviors, to allow special features of the Web/Electron UI. This package will also abstract away some of those API calls, making it easier to consume them.

As of now, the features of this project are focused towards a bot for moderating Open Source Slack communities. Things will be added as they are needed to support that effort, or as contributions from others are made.

This package is still under active development.

The behaviors and functions relied on by this package are largely undocumented, and the usage of them fall outside of any compatibility guarantees provided by Slack. While the functionality provided by this package is necessary, it's reasonable to assume it may break unexpectedly in the future.

As such, at the time of writing, it seems unlikely that this package will ever be able to see a 1.0.0 release. However, efforts will be made to retain API compatibility as long as possible. The package will have releases, using git tags, following the Semantic Version 2.0.0 spec.

Index

• Constants
• type Client
  • func New(c HTTPClient, subdomain string) (*Client, error)
  • func (c *Client) PendingInvites() ([]Invite, string, error)
  • func (c *Client) ResendInvites(crumb string, resendIDs ...int64) (string, error)
  • func (c *Client) RevokeInvites(crumb string, revokeIDs ...int64) (string, error)
  • func (c *Client) SessionToken() string
  • func (c *Client) StartSession(email, password string) error
• type HTTPClient
• type Invite
• type InvitePref
• type InvitePrefs
  • func (i *InvitePrefs) UnmarshalJSON(b []byte) error
• type LoginDetails

Constants

const Version = "0.1.0"

Version is the version of this package.

Types

type Client

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

Client is a client for making mechanized requests to Slack. The actions this client can make are generally unsupported outside of a browser, but they are needed to moderate a Slack community. Also, because we are doing something that is normally done via a browser, Slack is not expecting a high rate of automated calls. Please keep that in mind.

This strut contains a session token that can be used to take API actions as a user. This can also be used with the Slack API library (github.com/nlopes/slack) to communicate with users in real time.

When calling the constructor, you must provide an `*http.Client` with a cookiejar configured. It's recommended you use one with persistence, to avoid your client causing problem for Slack by requiring a log in on each process start.

func New

func New(c HTTPClient, subdomain string) (*Client, error)

New returns a new *Client. After getting the client, you must call StartSession to begin an active session. If your provided client already has active cookies, call ResumeSession().

The HTTPClient being passed in cannot follow redirects automatically, and should instead return the redirect response. This is a requirement for this package, or the ability to obtain a new session will be broken.

For an `*http.Client`, this functionality can be turned on by setting the `CheckRedirect` field and having it return `http.ErrUseLastResponse`.

func (*Client) PendingInvites

func (c *Client) PendingInvites() ([]Invite, string, error)

PendingInvites retrieves the list of currently pending invites.

func (*Client) ResendInvites

func (c *Client) ResendInvites(crumb string, resendIDs ...int64) (string, error)

ResendInvites is a function to resend 1...n invites from Slack. The first argument is the CSRF token (crumb) provided by the PendingInvites() function. If you don't have one, using "" will result in this function retrieving one. You then provide the invitation IDs to resend as the second (variadic) argument. Providing zero IDs to resend is an error.

func (*Client) RevokeInvites

func (c *Client) RevokeInvites(crumb string, revokeIDs ...int64) (string, error)

RevokeInvites is a function to revoke 1...n invites from Slack. The first argument is the CSRF token (crumb) provided by the PendingInvites() function. If you don't have one, using "" will result in this function retrieving one. You then provide the invitation IDs to revoke as the second (variadic) argument. Providing zero IDs to revoke is an error.

func (*Client) SessionToken

func (c *Client) SessionToken() string

SessionToken returns the session token retrieved from logging in. You can use this with the Slack API library (github.com/nlopes/slack).

If you do decide to use the Slack API library, it would be a good idea to use the same HTTP client in there as here, in case the cookie used when logging in is checked.

func (*Client) StartSession

func (c *Client) StartSession(email, password string) error

StartSession starts a new session within the client. This is accomplished by logging in to Slack, as if you were a user on the web application, and pulling the session token out of the bootstrap data for the JavaScript client.

See the internals of this function for a more detailed explanation of how this process works.

type HTTPClient

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

HTTPClient represents the functionality we need from an *http.Client, or similar.

type Invite

type Invite struct {
	ID          int64       `json:"id"`
	Email       string      `json:"email"`
	DateCreate  int64       `json:"date_create"`
	DateResent  int64       `json:"date_resent"`
	Bouncing    bool        `json:"bouncing"`
	InvitePrefs InvitePrefs `json:"invite_prefs"`
}

Invite represents the single invite for a user.

type InvitePref

type InvitePref struct {
	DomainMatch bool   `json:"domain_match"`
	RealName    string `json:"real_name"`
}

InvitePref are the invite preferences as provided by the user.

type InvitePrefs

type InvitePrefs []InvitePref

InvitePrefs is a special type to contain the invite preferences for a user's invite. In some cases Slack returns an Array for this instead of an object, which creates challenges for the default decoder. This type exists to gracefully handle either case.

func (*InvitePrefs) UnmarshalJSON

func (i *InvitePrefs) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type LoginDetails

type LoginDetails struct {
	Crumb       string
	Redir       string
	Signin      string
	HasRemember string
}

LoginDetails is a struct to contain the hidden fields presented by Slack on their login form. Some of these fields are needed for logging in, so this can be used to present them back.