@kukei/mastodon-api

A lightweight, no-dependency, limited library for posting statuses to Mastodon.

Used by Kukei.eu and masto.kukei.eu to post updates and threads to Mastodon instances. Will be maintained until I maintain those two.

Features

• Send toots
• Reply to toots (or use as threads poster)

Installation

npm install @kukei/mastodon-api

yarn add @kukei/mastodon-api

Quick Start

import { MastodonApi } from '@kukei/mastodon-api';
// Initialize the client
const mastodon = new MastodonApi({
 token: 'your-mastodon-access-token',
 url: 'https://mastodon.social' // or your Mastodon instance URL
});
// Post a status
const statusId = await mastodon.sendStatus(
 'Hello, Mastodon! 👋',
 'en'
);
console.log(`Status posted with ID: ${statusId}`);

API Reference

new MastodonApi(options)

Creates a new Mastodon API client.

Parameters

• options (Object):
  • token (string, required): Your Mastodon access token
  • url (string, required): The URL of your Mastodon instance (e.g., https://mastodon.social)
  • fetch (function, optional): Custom fetch implementation (defaults to globalThis.fetch)

Example

const mastodon = new MastodonApi({
 token: 'your-access-token',
 url: 'https://mastodon.social'
});

mastodon.sendStatus(text, language, replyTo)

Posts a status to Mastodon.

Parameters

• text (string, required): The content of your status
• language (string, required): The language code (e.g., 'en', 'es', 'fr')
• replyTo (string, optional): The ID of the status you're replying to (default: null)

Returns

• Promise<string>: The ID of the posted status

Examples

Post a simple status:

const statusId = await mastodon.sendStatus(
 'Hello, world!',
 'en'
);

Reply to a status:

const replyId = await mastodon.sendStatus(
 'Great post!',
 'en',
 '109876543210' // ID of the status you're replying to
);

Post in different languages:

// Spanish
await mastodon.sendStatus('¡Hola, mundo!', 'es');
// French
await mastodon.sendStatus('Bonjour le monde!', 'fr');
// Japanese
await mastodon.sendStatus('こんにちは世界!', 'ja');

Idempotency

The library automatically generates an idempotency key based on the status text using MD5 hashing. This prevents duplicate posts if you accidentally send the same request twice. The same text will always generate the same idempotency key.

Error Handling

The library throws an error if the API request fails:

try {
 const statusId = await mastodon.sendStatus('Hello!', 'en');
 console.log('Success:', statusId);
} catch (error) {
 console.error('Failed to post status:', error.message);
}

Advanced Usage

Custom Fetch Implementation

You can provide a custom fetch implementation, which is useful for testing or when using in environments without a built-in fetch:

import fetch from 'node-fetch'; // or any fetch polyfill

const mastodon = new MastodonApi({
 token: 'your-token',
 url: 'https://mastodon.social',
 fetch: fetch
});

Development

Running Tests

npm test

Running Tests with Coverage

npm run coverage

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.