1# pleroma announce
  2
  3this is a small quick and dirty tool that intended to be used to post
  4announcements and polls onto bot on pleroma.
  5
  6## prerequisites
  7
  8- python 3
  9
 10- pip
 11
 12- curl (optional, if you can replace it with other tool)
 13
 14- registered pleroma app and authentication token (see next section)
 15
 16## pleroma app registration
 17
 181. create pleroma user and mark it as bot.
 19
 202. create an application for pleroma to get `client_id` and `client_secret`.
 21refer to [pleroma api specification][1] and [mastodon api specification][2].
 22this tool requires `write:statuses` and `read:statuses` scopes, so don't forget
 23to specify them, otherwise it will fail.
 24
 25  ```terminal
 26  curl -X POST \
 27      -F 'client_name={YOUR_APP_NAME}' \
 28      -F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \
 29      -F 'scopes=write:statuses read:statuses' \
 30      https://yourdomain.tld/api/v1/apps
 31  ```
 32  [1]: https://api.pleroma.social/#operation/AppController.create
 33  [2]: https://docs.joinmastodon.org/client/authorized/
 34
 353. with your `client_id` authorize your application with
 36account you are planning to use for posting.
 37
 38  in browser enter:
 39  ```
 40  https://yourdomain.tld/oauth/authorize?client_id={YOUR_CLIENT_ID}
 41  &scope=write:statuses+read:statuses
 42  &redirect_uri=urn:ietf:wg:oauth:2.0:oob
 43  &response_type=code
 44  ```
 45
 46  after entering credentials, you will receive access code which
 47  will be used in the next step.
 48
 494. with obtained access code you have to aquire authentication token for
 50the application.
 51
 52  ```terminal
 53  curl -X POST \
 54      -F 'client_id={YOUR_CLIENT_ID}' \
 55      -F 'client_secret={YOUR_CLIENT_SECRET}' \
 56      -F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \
 57      -F 'grant_type=authorization_code' \
 58      -F 'code={YOUR_AUTHERIZATION_CODE}' \
 59      -F 'scope=write:statuses read:statuses' \
 60      https://yourdomain.tld/oauth/token
 61  ```
 62
 63  you will json response with authentication token, now save it to `.env` file,
 64  see `.env.example`.
 65
 66## usage
 67
 681. git clone the repo
 69
 70  ```terminal
 71  $ git clone https://git.aaoth.xyz/pleroma_announce.git
 72  $ cd pleroma_announce
 73  ```
 74
 752. install required pip packages
 76(though they are likely to be installed already)
 77
 78  ```terminal
 79  $ pip install -r requirements.txt
 80  ```
 81
 823. now you can use the script, see `--help` for options. for example:
 83
 84  ```terminal
 85  $ python plann.py post -d 2022-02-14T14:00+00:00 -p opt1 opt2 -e 3 -m test
 86  ```
 87
 88  this will schedule a status with text `test` and poll with options `opt1` and
 89  `opt2` to 14 feb 2022 14:00 UTC.
 90
 91## todos
 92
 93- add setup.py
 94
 95- figure out versions of pip packages
 96
 97- handle media attachments
 98
 99- add man page
100
101## contacts
102
103[email me][3] or reach me on [fedi][4] if you have found a bug or
104just something weird.
105
106[3]:mailto:aaoth@aaoth.xyz
107[4]:https://pleroma.aaoth.xyz/users/la_ninpre
108
109## licence
110
111this program is licensed under an isc licence, see `LICENCE.txt` for details.