Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/h3poteto/megalodon
Fediverse API client library for node.js and browser
https://github.com/h3poteto/megalodon
akkoma client firefish friendica mastodon mastodon-apis pleroma proxy streaming typescript websockets
Last synced: about 2 months ago
JSON representation
Fediverse API client library for node.js and browser
- Host: GitHub
- URL: https://github.com/h3poteto/megalodon
- Owner: h3poteto
- License: mit
- Created: 2018-06-08T01:22:11.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-05-01T18:56:58.000Z (5 months ago)
- Last Synced: 2024-05-02T05:46:16.930Z (5 months ago)
- Topics: akkoma, client, firefish, friendica, mastodon, mastodon-apis, pleroma, proxy, streaming, typescript, websockets
- Language: TypeScript
- Homepage: https://h3poteto.github.io/megalodon/
- Size: 15.2 MB
- Stars: 239
- Watchers: 5
- Forks: 27
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
- Codeowners: CODEOWNERS
Awesome Lists containing this project
- awesome-mastodon-cn - Megalodon\-
- awesome-mastodon - Megalodon - Mastodon API client library for node.js. (Libraries / Français)
README
# Megalodon
[](https://github.com/h3poteto/megalodon/actions?query=branch%3Amaster+workflow%3ATest)
[](https://www.npmjs.com/package/megalodon)
[](https://github.com/h3poteto/megalodon/releases)
[](https://www.npmjs.com/package/megalodon)
[](/LICENSE.txt)
Megalodon is a Fediverse API client library for [NodeJS](https://nodejs.org) and browsers.
This library allows for interfacing with [Mastodon](https://joinmastodon.org), [Pleroma](https://pleroma.social), [Friendica](https://friendi.ca), and [Firefish](https://joinfirefish.org) servers all with the same interface, providing REST API and streaming methods.
The Rust version is [megalodon-rs](https://github.com/h3poteto/megalodon-rs).
## Supports
- [x] Mastodon 
- [x] Pleroma 
- [x] Friendica
- [x] Firefish 
- [x] Gotosocial
- [x] Akkoma (Unofficial)
## Features
- [x] REST API
- [ ] Admin API
- [x] WebSocket for streaming
- [x] Promisified methods
- [x] NodeJS and browser support
- [x] Written in TypeScript
## Install
```sh
# npm
npm install -S megalodon
# pnpm
pnpm add megalodon
# yarn
yarn add megalodon
```
## Usage
There are code [examples](https://github.com/h3poteto/megalodon/tree/master/example), abd please refer to the [documentation](https://h3poteto.github.io/megalodon/) 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](#authorization).
### Home timeline
```ts
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>) => {
console.log(res.data)
})
```
### Make a post
```ts
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) => {
console.log(res.data)
})
```
### Post media
Please provide a file to the argument.
```ts
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) => {
console.log(res.data)
})
```
### WebSocket streaming
```ts
import generator, { Entity } from 'megalodon'
const BASE_URL: string = 'https://pleroma.io'
const access_token: string = '...'
const client = generator('pleroma', BASE_URL, access_token)
client.userStreaming().then(stream => {
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.
```ts
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.
```ts
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.
```ts
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](https://opensource.org/licenses/MIT).