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.