gotosocial/README.md

# gotosocial

A couple of small Python libraries for registering and running bots on a [GoToSocial](https://gotosocial.org/) ActivityPub server.

I wrote these to make it easier for me to port [my bots](https://bots.mikelynch.org) to my bot server, [llull.club](https://llull.club). It's all a bit basic and there are no tests or anything fancy like that.

## Installation

This project is maintained with [uv](https://docs.astral.sh/uv/): install it, check out this repo, cd into the directory and then you can run the registration script with the uv commands below and it should take care of dependencies.

To use the client library you'll have to fiddle around with making it available to whatever Python you're using to run your bots.

Before you can make a bot which posts to your instance you need to register an app and get an access token with the `register` script.

## register

A utility for making it easier to register an app and get an access token for
a GoToSocial account - it's a Python script which automates as much of [the client API instructions](https://docs.gotosocial.org/en/latest/api/authentication/) as possible. There's still some manual stuff required for authenticating.

This process all happens over https so there's no need to run `register` on the server where your instance is actually hosted. You will need to have an ActivityPub account on the instance and be able to log in using its password.

To register an app, you first need to give it an identity on the server - in the examples I've called the server `https://your.server/` and the app `mybot`

    uv run register -u https://your.server/ -n mybot

This will create an app on the server and write out the client id and secret to a file in the current directory called `mybot_app.json`. It will also write a URL to the command line for the next step

The second step is to visit that URL in an incognito browser window. You'll be prompted to authenticate - use the email address and password for the GoToSocial account which you want to post to via the app.

Once you authenticate, you should be taken to a page which has a message like:

    Hi account!
	
	Here's your out-of-band token with scope "write", use it wisely:
	
	ABIGLONGSTRINGOFLETTERSANDNUMBERS

Copy the out-of-band token and do the third step straight away, as the token will expire fairly quickly.

The third step exchanges the above token for a permanent access token, by running the script again in the same directory, passing the OOB token with the -t flag:

    uv run register -u https://your.server/ -n mybot -t ABIGLONGSTRINGOFLETTERSANDNUMBERS

If this is successful, your access token - another, different string of letters and numbers - will be printed to the command prompt. The access token is also written out as a json file with the name `mybot_at.json`.

You should now be able to use the access token to post to your GoToSocial account.

## client

I don't use this version of the client for my own bots - I use it as one
component of [botclient](https://github.com/spikelynch/botclient) which can 
also work against the Mastodon API.

I have tested this version and provided a couple of example scripts - one for
text posts and one for posts with a single image. Note that the GoToSocial 
API allows up to six images - at some point I'll upgrade this to allow
multiple image posts.

The client is a Python class, GoToSocialBot, which needs the URL of your instance
and the access token generated as per the instructions above.

    bot = GoToSocialBot()
    bot.auth({ "base_url": "https://llull.club", "access_token": "..." })
    bot.post("This is an automated post!", { "spoiler_text": "bot post" })
    bot.post_image("myimage.png", "This is an automated image!", { "spoiler_text": "bot post" })

The second argument to post() and third argument to post_imate() is a dict of options which are passed straight through to the API - details available [here](https://docs.gotosocial.org/en/latest/api/swagger/).