plerobuddies/README.md

# Plerobuddies

Yay! **Working examples** say more than a 1000 words:

- [@acvilagers@chat.brainbaking.com](https://chat.brainbaking.com/@acvillagers)
- [@gblegacy@chat.brainbaking.com](https://chat.brainbaking.com/@gblegacy)

![Screenshot from a Pleroma instance](https://raw.githubusercontent.com/wgroeneveld/plerobuddies/master/screenshot.jpg)

## Mastodon/Pleroma Buddies (bots)

Execute through `yarn toot` or `yarn node src/chat.js`. It cycles through all configured "buddies" and toots a message accordingly. Use your favorite `crontab` timestamp to fire off toots automatically. 

If you'd like to let a specific buddy chat - for instance to configure them individually in your crontab - use the argument `buddy`:

`yarn toot --buddy [by-cool-buddy]`

The name should match the `buddy` property in the config file (_not_ the `name` property: that's the buddy directory name).

### Packaged buddies

1. **animalcrossing**: collect data from https://animalcrossing.fandom.com/wiki/ and randomly toot about a villager, including a link to the Fandom page and the birthday. Uses dirty scraping, no rate limit hit yet... 
2. **mobygames**: collect data through the Moby Games API so you'll need an API key: https://www.mobygames.com/info/api - the API is rate-limited at one call per second and 360 per hour. The above working example posts a random Game Boy game with two screenshots collected via the API. It's generic, so just configure `platform` in the config file (10 is GB).

### Creating a new buddy

Create a directory in `src/buddies/` and add it to `config.js` using the same name. Each buddy should have a `buddy.js` with one exposed method called `chat`, which gets executed with a config parameter. Look at the examples for more information. End the file with something like `module.exports = { chat }`.

The function `chat` should create a "toot", with the following structure:

```js
{
    "toot": "hi there buddy!",
    "attach": [ "file1.jpg", "file2.jpg" ],
    "attachDescription": `Screenshots of game x`
}
```

An `attach` and its description are optional. Newlines using `\n` in a toot are allowed. 

### Configuring the buddies

See `config.sample.js`. A config file should expose `buddies` as an array with the following structure:

```js
{
    name: "buddyname", // same as the dir name
    buddy: "my cool buddy", // unique buddy id
    instance: "https://mastodon.social", // where to post to
    oauthToken: "my-token" // the oauth token for that server/user to post the status  with
}
```

Optional config flags can be used in the chat function if desired. 

There's a sanity check implemented: at minimum, each config should have name, buddy, instance, and oauthToken present. 

## How to get an OAuth token from a Masto/Pleroma instance?

I've prepared a few utility functions in `registerApp.js` for you. First, call `await register()`, which prints an URL to go to. Next, fill in the client id, secret, and returned token, after granting the app access to read and write. Then, call `await fetchToken()`. Paste that token in the config file. Done!

Token refreshing is not (yet) implemented. Most tokens are valid for a year or so. Who knows what'll happen by then.