{"id":13546916,"url":"https://github.com/h3poteto/megalodon","last_synced_at":"2026-02-25T12:18:16.547Z","repository":{"id":32546007,"uuid":"136549493","full_name":"h3poteto/megalodon","owner":"h3poteto","description":"Fediverse API client library for node.js and browser","archived":false,"fork":false,"pushed_at":"2025-05-14T05:24:30.000Z","size":19859,"stargazers_count":268,"open_issues_count":31,"forks_count":32,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-14T06:44:47.497Z","etag":null,"topics":["akkoma","client","firefish","friendica","mastodon","mastodon-apis","pleroma","proxy","streaming","typescript","websockets"],"latest_commit_sha":null,"homepage":"https://h3poteto.github.io/megalodon/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/h3poteto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"h3poteto"}},"created_at":"2018-06-08T01:22:11.000Z","updated_at":"2025-05-13T01:13:26.000Z","dependencies_parsed_at":"2023-12-21T16:44:57.603Z","dependency_job_id":"72e81b18-d87d-44c8-b9ac-0e4c26d4e535","html_url":"https://github.com/h3poteto/megalodon","commit_stats":{"total_commits":1491,"total_committers":25,"mean_commits":59.64,"dds":0.5231388329979879,"last_synced_commit":"06590907d800fb1d4e7f92ec51c4ded64f4c01e0"},"previous_names":[],"tags_count":151,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h3poteto%2Fmegalodon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h3poteto%2Fmegalodon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h3poteto%2Fmegalodon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h3poteto%2Fmegalodon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/h3poteto","download_url":"https://codeload.github.com/h3poteto/megalodon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254121943,"owners_count":22018248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["akkoma","client","firefish","friendica","mastodon","mastodon-apis","pleroma","proxy","streaming","typescript","websockets"],"created_at":"2024-08-01T12:00:47.831Z","updated_at":"2026-02-25T12:18:16.534Z","avatar_url":"https://github.com/h3poteto.png","language":"TypeScript","funding_links":["https://github.com/sponsors/h3poteto"],"categories":["TypeScript","Libraries","图书馆"],"sub_categories":["Français","Javascript","法兰西"],"readme":"# Megalodon\n\n[![Test](https://github.com/h3poteto/megalodon/workflows/Test/badge.svg)](https://github.com/h3poteto/megalodon/actions?query=branch%3Amaster+workflow%3ATest)\n[![NPM Version](https://img.shields.io/npm/v/megalodon.svg)](https://www.npmjs.com/package/megalodon)\n[![GitHub release](https://img.shields.io/github/release/h3poteto/megalodon.svg)](https://github.com/h3poteto/megalodon/releases)\n[![npm](https://img.shields.io/npm/dm/megalodon)](https://www.npmjs.com/package/megalodon)\n[![NPM](https://img.shields.io/npm/l/megalodon)](/LICENSE.txt)\n\nMegalodon is a Fediverse API client library for [NodeJS](https://nodejs.org) and browsers.\nThis 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.\n\nThe Rust version is [megalodon-rs](https://github.com/h3poteto/megalodon-rs).\n\n## Supports\n\n- [x] Mastodon \u003cimg src=\"https://cdn.simpleicons.org/mastodon\" alt=\"Mastodon\" width=16 height=16\u003e\n- [x] Pleroma \u003cimg src=\"https://cdn.simpleicons.org/pleroma\" alt=\"Pleroma\" width=16 height=16\u003e\n- [x] Friendica\n- [x] Firefish \u003cimg src=\"https://cdn.simpleicons.org/firefish\" alt=\"Firefish\" width=16 height=16\u003e\n- [x] Gotosocial\n- [x] Pixelfed\n- [x] Akkoma (Unofficial)\n- [x] Sharkey (Unofficial)\n- [x] Hometown (Unofficial)\n- [x] Iceshrimp (Unofficial)\n\n## Features\n\n- [x] REST API\n- [ ] Admin API\n- [x] WebSocket for streaming\n- [x] Promisified methods\n- [x] NodeJS and browser support\n- [x] Written in TypeScript\n\n## Install\n\n```sh\n# npm\nnpm install -S megalodon\n\n# pnpm\npnpm add megalodon\n\n# yarn\nyarn add megalodon\n```\n\n## Usage\n\nThere 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.\n\nI explain some typical methods.\nAt first, please get your access token for a fediverse server.\nIf you don't have access token, or you want to register applications and get access token programmably, please refer [Authorization section](#authorization).\n\n### Home timeline\n\n```ts\nimport generator, { Entity, Response } from 'megalodon'\n\nconst BASE_URL: string = 'https://mastodon.social'\nconst access_token: string = '...'\n\nconst client = generator('mastodon', BASE_URL, access_token)\nclient.getHomeTimeline()\n  .then((res: Response\u003cArray\u003cEntity.Status\u003e\u003e) =\u003e {\n    console.log(res.data)\n  })\n```\n\n### Make a post\n\n```ts\nimport generator, { Entity, Response } from 'megalodon'\n\nconst BASE_URL: string = 'https://mastodon.social'\nconst access_token: string = '...'\nconst post: string = 'test post'\n\nconst client = generator('mastodon', BASE_URL, access_token)\nclient.postStatus(post)\n  .then((res: Response\u003cEntity.Status\u003e) =\u003e {\n    console.log(res.data)\n  })\n```\n\n### Post media\n\nPlease provide a file to the argument.\n\n```ts\nimport generator, { Entity, Response } from 'megalodon'\nimport fs from 'fs'\n\nconst BASE_URL: string = 'https://mastodon.social'\nconst access_token: string = '...'\nconst image = fs.readFileSync(\"test-image.png\")\n\nconst client = generator('mastodon', BASE_URL, access_token)\nclient.uploadMedia(image)\n  .then((res: Response\u003cEntity.Attachment\u003e) =\u003e {\n    console.log(res.data)\n  })\n```\n\n### WebSocket streaming\n\n```ts\nimport generator, { Entity } from 'megalodon'\n\nconst BASE_URL: string = 'https://pleroma.io'\nconst access_token: string = '...'\n\nconst client = generator('pleroma', BASE_URL, access_token)\nclient.userStreaming().then(stream =\u003e {\n  stream.on('connect', () =\u003e {\n    console.log('connect')\n  })\n\n  stream.on('update', (status: Entity.Status) =\u003e {\n    console.log(status)\n  })\n\n  stream.on('notification', (notification: Entity.Notification) =\u003e {\n    console.log(notification)\n  })\n\n  stream.on('delete', (id: number) =\u003e {\n    console.log(id)\n  })\n\n  stream.on('error', (err: Error) =\u003e {\n    console.error(err)\n  })\n\n  stream.on('heartbeat', () =\u003e {\n    console.log('thump.')\n  })\n\n  stream.on('close', () =\u003e {\n    console.log('close')\n  })\n\n  stream.on('parser-error', (err: Error) =\u003e {\n    console.error(err)\n  })\n})\n```\n\n### Authorization\n\nYou can register applications and/or get access tokens to use this method.\n\n```ts\nimport generator, { OAuth } from 'megalodon'\n\nconst BASE_URL: string = 'https://mastodon.social'\n\nlet clientId: string\nlet clientSecret: string\n\nconst client = generator('mastodon', BASE_URL)\n\nclient.registerApp('Test App', {})\n  .then(appData =\u003e {\n    clientId = appData.client_id\n    clientSecret = appData.client_secret\n    console.log('Authorization URL is generated.')\n    console.log(appData.url)\n  })\n```\n\nPlease open `Authorization URL` in your browser, and authorize this app.\nIn this time, you can get authorization code.\n\nAfter that, get an access token.\n\n```ts\nconst code = '...' // Authorization code\n\nclient.fetchAccessToken(clientId, clientSecret, code)\n  .then((tokenData: OAuth.TokenData) =\u003e {\n    console.log(tokenData.access_token)\n    console.log(tokenData.refresh_token)\n  })\n  .catch((err: Error) =\u003e console.error(err))\n```\n\n### Detect each server's software\n\nYou have to provide the server's software name (e.g. `mastodon`, `pleroma`, `firefish`) to the `generator` function.\nBut when you only know the URL and not the software the server runs on, the `detector` function can detect the server's software.\n\n```ts\nimport { detector } from 'megalodon'\n\nconst FIRST_URL = 'https://mastodon.social'\nconst SECOND_URL = 'https://firefish.social'\n\nconst first_server = await detector(MASTODON_URL)\nconst second_server = await detector(FIREFISH_URL)\n\nconsole.log(first_server) // mastodon\nconsole.log(second_server) // firefish\n```\n\n## License\n\nThe software is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh3poteto%2Fmegalodon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fh3poteto%2Fmegalodon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh3poteto%2Fmegalodon/lists"}