Megalodon

A Mastodon and Pleroma API Client library for node.js and browser. It provides REST API and streaming methods.

Features

• REST API
• Streaming with Server-Sent Event
• Streaming with WebSocket
• Promisified methods
• Proxy support
• Support node.js and browser
• Written in typescript

Install

$ npm install -S megalodon

or

$ yarn add megalodon

Build for browser

Important: In browser, you can not use proxy.

If you want to build for browser, please use Webpack and set empty value for these libraries.

• net
• tls
• dns

  node: {
    net: 'empty',
    tls: 'empty',
    dns: 'empty'
  }

These libraries are for node.js, so can not use in browser.

Here is example Webpack configuration.

Usage

I prepared examples.

Authorization

First, you should register the application.

import Mastodon from 'megalodon'

const SCOPES: string = 'read write follow'
const BASE_URL: string = 'https://friends.nico'

let clientId: string
let clientSecret: string

Mastodon.registerApp('Test App', {
  scopes: SCOPES
}, BASE_URL).then(appData => {
  clientId = appData.clientId
  clientSecret = appData.clientSecret
  console.log('Authorization URL is generated.')
  console.log(appData.url)
})

And, get an access token.

const code = '...' // Authorization code

Mastodon.fetchAccessToken(clientId, clientSecret, code, BASE_URL)
})
  .then((tokenData: Partial<{ accessToken: string }>) => {
    console.log(tokenData.accessToken)
  })
  .catch((err: Error) => console.error(err))

Get timeline

import Mastodon, { Status, Response } from 'megalodon'

const BASE_URL: string = 'https://friends.nico'

const access_token: string = '...'

const client = new Mastodon(
  access_token,
  BASE_URL + '/api/v1'
)

client.get<[Status]>('/timelines/home')
  .then((resp: Response<[Status]>) => {
    console.log(resp.data)
  })

Post toot

import Mastodon, { Status, Response } from 'megalodon'

const BASE_URL: string = 'https://friends.nico'

const access_token: string = '...'

const toot: string = 'test toot'

const client = new Mastodon(
  access_token,
  BASE_URL + '/api/v1'
)

client.post<Status>('/statuses', {
  status: toot
})
  .then((res: Response<Status>) => {
    console.log(res.data)
  })

Post medias

The POST method is wrapper of axios: https://github.com/h3poteto/megalodon/blob/master/src/mastodon.ts#L245-L266

So you can use the same way of axios to post medias.

import Mastodon, { Status, Response } from 'megalodon'
import fs from 'fs'

const BASE_URL: string = 'https://friends.nico'

const access_token: string = '...'

const client = new Mastodon(
  access_token,
  BASE_URL + '/api/v1'
)

const image = fs.readFileSync("test.image")
const formData = new FormData()
formData.append('file', image)

client.post<Attachment>('/media', formData)
  .then((res: Response<Attachment>) => {
    console.log(res.data)
  })

Streaming for Mastodon

This method provides streaming method for Mastodon. If you want to use Pleroma, please use WebSocket.

import Mastodon, { Status, Notification, StreamListener } from 'megalodon'

const BASE_URL: string = 'https://friends.nico'

const access_token: string = '...'

const client = new Mastodon(
  access_token,
  BASE_URL + '/api/v1'
)


const stream: StreamListener = client.stream('/streaming/public')
stream.on('update', (status: Status) => {
  console.log(status)
})

stream.on('notification', (notification: Notification) => {
  console.log(notification)
})

stream.on('delete', (id: number) => {
  console.log(id)
})

stream.on('error', (err: Error) => {
  console.error(err)
})

stream.on('heartbeat', () => {
  console.log('thump.')
})

WebSocket for Pleroma

This method provides streaming method for Pleroma.

import Mastodon, { Status, Notification, WebSocket } from 'megalodon'

const BASE_URL: string = 'wss://pleroma.io'

const access_token: string = '...'

const client = new Mastodon(
  access_token,
  BASE_URL + '/api/v1'
)

const stream: WebSocket = client.socket('/streaming', 'user')
stream.on('connect', () => {
  console.log('connect')
})

stream.on('update', (status: Status) => {
  console.log(status)
})

stream.on('notification', (notification: Notification) => {
  console.log(notification)
})

stream.on('delete', (id: number) => {
  console.log(id)
})

stream.on('error', (err: Error) => {
  console.error(err)
})

stream.on('heartbeat', () => {
  console.log('thump.')
})

stream.on('close', () => {
  console.log('close')
})

stream.on('parser-error', (err: Error) => {
  console.error(err)
})

License

The software is available as open source under the terms of the MIT License.