~vpzom/shoved

1f1fa680dfa9bd7d96d57040ec3df4e9c6221f17 — Colin Reeder 11 months ago 39aaf81
Flesh out README
1 files changed, 38 insertions(+), 0 deletions(-)

M README.md
M README.md => README.md +38 -0
@@ 2,3 2,41 @@ shoved
======

*When push comes to shove... it spawns a process.*

`shoved` is a push notification daemon for Linux systems using the
[Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) and the
[Mozilla Push Service](https://mozilla-push-service.readthedocs.io/en/latest/).
These notifications are encrypted by the source and decrypted locally, so the push
service cannot read their content.

## How to Use
This repository includes source code for two executables: `shoved` and `shoved-register`.
`shoved` must be running to receive push notifications and register new handlers.
It is recommended to set this up to automatically start on login, for example in your
desktop environment or as a systemd user service. (a system-wide mode is also supported
but personally I've had trouble getting desktop notifications to show with that setup)

To set up a service for push notifications, you probably want one of these:
- [shoved-matrix](https://git.sr.ht/~vpzom/shoved-matrix) - for notifications from Matrix

If you want to write your own handler, see the following section.

## Handler Interface
To register a new handler, run the `shoved-register` command with the filepath of your
handler executable. If successful, the command will print a JSON object with subscription
information in this structure:

```
{
    "endpoint": "https://updates.push.services.mozilla.com/wpush/v1/SOMETHING_GOES_HERE",
    "keys": {
        "auth": "SomethingGoesHere",
        "p256dh": "SomethingMuchLongerGoesHere"
    }
}
```

These values should then be sent to the service so it can begin sending pushes.

When a push is received, `shoved` will run the specified handler executable and pass
the contents of the received message as stdin.