Push Notification - Event Watcher API

97.md

@@ -0,0 +1,78 @@
+NIP-97
+======
+
+Push Notification Event Watcher API
+-----------------------------------
+
+`draft` `optional`
+
+This NIP defines a common API to register push notification tokens into one or more event watch servers, which constantly query several relays to notify users on new events. 
+
+The goal is to allow users to choose their event watch servers by simply adding an http address to their account. 
+
+## Registration Call
+
+After receiving a `token` from the push system (Google Services, Unified Push, Apple Push Notification), clients should upload a list of signed [NIP-98](98.md) events, one for each account in the device, in a `POST` to `/register` with the following body:
+
+```jsonc
+{
+  "events": [ 
+    {
+      "id": "..",
+      "pubkey": "...",
+      "created_at": ...,
+      "kind": 22242,
+      "tags":[
+        [ "relay","<inbox relay 1>" ],
+        [ "relay","<inbox relay 2>" ],
+        [ "challenge", "<system>:<token>" ]
+      ],
+      "content":"",
+      "sig":"..."
+    }
+  ]
+}
+```
+
+where `system` is `google`, `apple` or `unifiedpush`.
+
+Servers will use the `system` information to select where to send new events from the relays marked as such.
+
+The server returns with an array of 
+
+```jsonc
+  [
+    {
+        "pubkey": "<pubkey>",
+        "result": "<added|replaced|error>",
+        "error": "<message>",
+    }
+  ]
+```
+
+Servers SHOULD accept multiple tokens per pubkey, but may limit the number of them.
+
+Servers SHOULD delete tokens after failure to deliver.
+
+## Sending Events
+
+Servers send new events as stringified JSONs in the user's preferred system. 
+
+The event MUST be [NIP-59 GiftWrapped](59.md) to the receiver. But since it already goes to the destination via the token, no `p`-tag is added to the wrap event. In this way, the chosen system cannot know which key is receiving a notification.
+
+Clients SHOULD decrypt the GiftWrap with all logged-in accounts to find the user this event is for.
+
+## Event Watcher list
+
+An Event Watcher list is a kind 10097 replaceable event meant to select one or more servers the user wants to register for push notifications. Servers are listed as `server` tags:
+
+```json
+{
+  "kind": 10097,
+  "content": "",
+  "tags": [
+    ["server", "https://push.amethyst.social"],
+    ["server", "https://server2.com"],
+  ]
+}
+```