Megalodon

Megalodon is a Fediverse API client library for NodeJS and browsers. This library allows for interfacing with Mastodon, Pleroma, Friendica, and Firefish servers all with the same interface, providing REST API and streaming methods.

The Rust version is megalodon-rs.

Supports

• Mastodon
• Pleroma
• Friendica
• Firefish
• Akkoma (Unofficial)

Features

• REST API
• Admin API
• WebSocket for streaming
• Promisified methods
• Proxy support
• NodeJS and browser support
• Written in TypeScript

Install

# npm
npm install -S megalodon

# pnpm
pnpm add megalodon

# yarn
yarn add megalodon

Build for browsers

Important: In browsers, you cannot use the proxy.

If you want to build for browser, please use Webpack and set empty value for some libraries which are not supported in NodeJS. Here is example Webpack configuration.

Usage

There are code examples, abd please refer to the documentation about each method.

I explain some typical methods. At first, please get your access token for a fediverse server. If you don't have access token, or you want to register applications and get access token programmably, please refer Authorization section.

Home timeline

import generator, { Entity, Response } from 'megalodon'

const BASE_URL: string = 'https://mastodon.social'
const access_token: string = '...'

const client = generator('mastodon', BASE_URL, access_token)
client.getHomeTimeline()
  .then((res: Response<Array<Entity.Status>>) => {
    console.log(res.data)
  })

Make a post

import generator, { Entity, Response } from 'megalodon'

const BASE_URL: string = 'https://mastodon.social'
const access_token: string = '...'
const post: string = 'test post'

const client = generator('mastodon', BASE_URL, access_token)
client.postStatus(post)
  .then((res: Response<Entity.Status>) => {
    console.log(res.data)
  })

Post media

Please provide a file to the argument.

import generator, { Entity, Response } from 'megalodon'
import fs from 'fs'

const BASE_URL: string = 'https://mastodon.social'
const access_token: string = '...'
const image = fs.readFileSync("test-image.png")

const client = generator('mastodon', BASE_URL, access_token)
client.uploadMedia(image)
  .then((res: Response<Entity.Attachment>) => {
    console.log(res.data)
  })

WebSocket streaming

import generator, { Entity, WebSocketInterface } from 'megalodon'

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

const client = generator('pleroma', BASE_URL, access_token)
const stream: WebSocketInterface = client.userSocket()

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

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

stream.on('notification', (notification: Entity.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)
})

Authorization

You can register applications and/or get access tokens to use this method.

import generator, { OAuth } from 'megalodon'

const BASE_URL: string = 'https://mastodon.social'

let clientId: string
let clientSecret: string

const client = generator('mastodon', BASE_URL)

client.registerApp('Test App')
  .then(appData => {
    clientId = appData.client_id
    clientSecret = appData.client_secret
    console.log('Authorization URL is generated.')
    console.log(appData.url)
  })

Please open Authorization URL in your browser, and authorize this app. In this time, you can get authorization code.

After that, get an access token.

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

client.fetchAccessToken(clientId, clientSecret, code)
  .then((tokenData: OAuth.TokenData) => {
    console.log(tokenData.access_token)
    console.log(tokenData.refresh_token)
  })
  .catch((err: Error) => console.error(err))

Detect each server's software

You have to provide the server's software name (e.g. mastodon, pleroma, firefish) to the generator function. But when you only know the URL and not the software the server runs on, the detector function can detect the server's software.

import { detector } from 'megalodon'

const FIRST_URL = 'https://mastodon.social'
const SECOND_URL = 'https://firefish.social'

const first_server = await detector(MASTODON_URL)
const second_server = await detector(FIREFISH_URL)

console.log(first_server) // mastodon
console.log(second_server) // firefish

License

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