mastorouter

README

mastorouter

A Mastodon API notification router.

See godocs for documentation: https://godoc.org/github.com/grufwub/mastorouter

Example code:

package main

import (
    "log"

    "github.com/grufwub/mastorouter"
    "github.com/mattn/go-mastodon"
)

func main() {
    // Set client config
    config := &mastodon.Config{
        Server:       "",
        ClientID:     "",
        ClientSecret: "",
        AccessToken:  "",
    }

    // Create new client from config
    client := mastodon.NewClient(config)

    // Create new NotificationRouter from Client
    router := mastorouter.NewNotificationRouter(client)

    // Register mention handler for status content regex
    router.Mention("(@/w)* mention here", func(ctx context.Context, c *mastodon.Client, n *mastodon.Notification) {
        log.Println("specific mention matching regex `(@/w)* mention here`:", n.Status.Content)
    })

    // Register catch-all mention handler
    router.Mention("", func(ctx context.Context, c *mastodon.Client, n *mastodon.Notification) {
        log.Println("mention catch-all:", n.Status.Content)
    })

    // Register favourite handler
    router.Favourite(func(ctx context.Context, c *mastodon.Client, n *mastodon.Notification) {
        log.Println("favourite!")
    })

    // Register reblog handler
    router.Reblog(func(ctx context.Context, c *mastodon.Client, n *mastodon.Notification) {
        log.Println("reblog!")
    })

    // Register follow handler
    router.Follow(func(ctx context.Context, c *mastodon.Client, n *mastodon.Notification) {
        log.Println("follow!")
    })

    // Begin listening with one of:
    // router.Listen()                         -- via stream API /api/v1/streaming/user
    // router.ListenWS()                       -- via websocket /api/v1/streaming
    // router.ListenTicker(rate time.Duration) -- via notifications API on ticker /api/v1/notifications
    //                                            (not recommended)
    log.Println(router.Listen())
}

Todos

• improve mention routing method

• add unit tests

Also grep -RP '// TODO: ' to find others.

Documentation

Index

• Constants
• type Notification
• type NotificationHandler
• type NotificationRouter
  • func NewNotificationRouter(cl *mastodon.Client) *NotificationRouter
  • func (router *NotificationRouter) Favourite(h NotificationHandler)
  • func (router *NotificationRouter) Follow(h NotificationHandler)
  • func (router *NotificationRouter) ListenStream() error
  • func (router *NotificationRouter) ListenStreamWS() error
  • func (router *NotificationRouter) ListenStreamWSWithContext(ctx context.Context) error
  • func (router *NotificationRouter) ListenStreamWithContext(ctx context.Context) error
  • func (router *NotificationRouter) ListenTicker(rate time.Duration) error
  • func (router *NotificationRouter) ListenTickerWithContext(ctx context.Context, rate time.Duration) error
  • func (router *NotificationRouter) Mention(expr string, h NotificationHandler)
  • func (router *NotificationRouter) Reblog(h NotificationHandler)
  • func (router *NotificationRouter) Use(h NotificationHandler)

Constants

const (
	NotificationMention   = "mention"
	NotificationFavourite = "favourite"
	NotificationReblog    = "reblog"
	NotificationFollow    = "follow"
)

Supported Mastodon API notification type constants

Types

type Notification

type Notification struct {
	// StatusContent contains the HTML-tag stripped status content (if it was present)
	StatusContent string

	*mastodon.Notification
}

type NotificationHandler

type NotificationHandler func(context.Context, *mastodon.Client, *Notification)

NotificationHandler is a function passed to NotificationRouter that handles routed notifications

type NotificationRouter

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

NotificationRouter takes a Mastodon Client and provides notification routing

func NewNotificationRouter

func NewNotificationRouter(cl *mastodon.Client) *NotificationRouter

NewNotificationRouter returns a new NotificationRouter based on supplied Client

func (*NotificationRouter) Favourite

func (router *NotificationRouter) Favourite(h NotificationHandler)

Favourite registers a NotificationHandler function for received favourite notifications

func (*NotificationRouter) Follow

func (router *NotificationRouter) Follow(h NotificationHandler)

Follow registers a NotificationHandler function for received follow notifications

func (*NotificationRouter) ListenStream

func (router *NotificationRouter) ListenStream() error

ListenStream listens for new notifications by opening a new user stream event channel: /api/v1/streaming/user. Then filtering specifically for NotificationEvent types. Returned notifications are sent on to appropriate NotificationHandler functions

func (*NotificationRouter) ListenStreamWS

func (router *NotificationRouter) ListenStreamWS() error

ListenStreamWS listens for new notifications by opening a user stream web socket event channel: wss://${instance}/api/v1/streaming. Then filtering specifically for NotificationEvent types. Returned notifications are sent on to appropriate NotificationHandler functions

func (*NotificationRouter) ListenStreamWSWithContext

func (router *NotificationRouter) ListenStreamWSWithContext(ctx context.Context) error

func (*NotificationRouter) ListenStreamWithContext

func (router *NotificationRouter) ListenStreamWithContext(ctx context.Context) error

func (*NotificationRouter) ListenTicker

func (router *NotificationRouter) ListenTicker(rate time.Duration) error

ListenTicker listens for new notifications through repeated API calls to: /api/v1/notifications. Returned notifications are sent on to appropriate NotificationHandler functions

func (*NotificationRouter) ListenTickerWithContext

func (router *NotificationRouter) ListenTickerWithContext(ctx context.Context, rate time.Duration) error

func (*NotificationRouter) Mention

func (router *NotificationRouter) Mention(expr string, h NotificationHandler)

Mention registers a NotificationHandler function for matching mention status content to the supplied regular expression. Empty expression sets the default mention NotificationHandler

func (*NotificationRouter) Reblog

func (router *NotificationRouter) Reblog(h NotificationHandler)

Reblog registers a NotificationHandler function for received reblog notifications

func (*NotificationRouter) Use

func (router *NotificationRouter) Use(h NotificationHandler)

Use adds the supplied NotificationHandler as middleware to be called before any other notification routes are called