Add notifiers nip

xx.md

@@ -0,0 +1,74 @@
+NIP-46
+======
+
+Notifiers
+---------
+
+A notifier is a nostr application whose job is to monitor the nostr network and notify users of updates via email, push, SMS, DM, etc.
+
+# Notification Subscription
+
+A notification subscription is a `kind 32830` event which specifies how a user would like to be notified, and by whom. It MUST have the following tags, and no others:
+
+- A `d` tag set to an arbitrary string
+- A `p` tag indicating the notifier the subscription is addressed to
+
+All other tags MUST be encrypted to the pubkey indicated by the `p` tag using NIP 44. The following tags are defined:
+
+- `channel` indicates how the user would like to be notified. May be one of `email`, `push`
+- `relay` (one or more) indicates relays where notifications may be discovered
+- `filter` (one or more) indicates a filter matching events that the user wants to be notified about
+- `cadence` (optional) indicates (roughly) how often the user would like to be notified. May be one of `weekly`, `daily`, `immediate`
+- `bunker_url` (optional) with permission to sign `kind 22242` AUTH requests (for access to auth-gated relays)
+- `pause_until` (optional) indicates how long the notifier should wait from the event's `created_at` before sending `immediate` mode notifications.
+
+If channel is set to `push`, the following tags are also required:
+
+- `token` indicates a push notification token
+- `platform` indicates the user's app platform (`ios|android|web`)
+
+If channel is set to `email`, the following tags are also required:
+
+- `email` indicates the user's email address
+
+## Unsubscribing
+
+When a user no longer wants to be notified, they may delete the subscription event by address following [NIP 09](./09.md).
+
+## Pausing while online
+
+When a user becomes active, their client SHOULD automatically update all relevant `kind 32930` events with a current `pause_until` timestamp. This allows the notifier to know the user is online and avoid sending push notifications. When a client knows it's about to go offline, it MAY update the `pause_until` timestamp to the current time.
+
+## Example
+
+Below is an example tag array (the entire event is not shown because the tags are encrypted and placed in `content`).
+
+```jsonc
+[
+  ["channel", "email"],
+  ["cadence", "weekly"],
+  ["bunker_url", "bunker://9ee57420bac3db5f1d7f43e1ed5f8bb6b81bf6df6350eb3377961da229eaab22?relay=wss://r.example.com&secret=9393"],
+  ["pause_until", "1740002930"],
+  ["relay", "wss://relay1.example.com/"],
+  ["relay", "wss://relay2.example.com/"],
+  ["filter", "{\"#p\":[\"c90b4e622a3a5c38aebd5ba3cbb22e4ab5a20056b499f8d2e3d25ff47f589a6b\"]}"],
+  ["filter", "{\"#h\":[\"b3ce4a9f\"]}"],
+  ["email", "email@example.com"]
+]
+```
+
+# Notification Subscription Status
+
+A notifier SHOULD publish a `kind 32831` event which details the status of the user's subscription. A non-existent subscription event indicates that no action has been taken. It MUST have the following tags, and no others:
+
+- An `a` tag set to the address of the `kind 32830` it refers to
+- A `p` tag indicating the notifier the subscription is addressed to
+
+All other tags MUST be encrypted to the pubkey indicated by the `p` tag using NIP 44. The following tags are defined:
+
+- `status` SHOULD be one of `ok`, `payment-required`, `error`
+- `message` SHOULD include human-readable information explaining the status of the subscription
+
+# Discovery
+
+A notifier MAY advertise its services via NIP 89 client listing.