npm package: @kukei/mastodon-api
Description: Mastodon API toot posting library
Author: Szymon Nowicki
Latest version: 1.0.0

# @kukei/mastodon-api

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

Used by [Kukei.eu](https://kukei.eu) and [masto.kukei.eu](https://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

```bash
npm install @kukei/mastodon-api
```

```bash
yarn add @kukei/mastodon-api
```

## Quick Start

```javascript
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

```javascript
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:**

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

**Reply to a status:**

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

**Post in different languages:**

```javascript
// 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:

```javascript
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:

```javascript
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

```bash
npm test
```

### Running Tests with Coverage

```bash
npm run coverage
```

## Contributing

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