Notification subscriptions

docs/rfcs/0020-push-notification-subscriptions.md

@@ -0,0 +1,150 @@
+---
+title: "Push Notification Subscriptions"
+type: rfc
+status: draft
+owner: "@pgherveou"
+pr:
+---
+
+# RFC 0020 — Push Notification Subscriptions
+
+## Summary
+
+Adds four TrUAPI methods — `push_add_rules`, `push_remove_rules`, `push_list_rules`, `push_set_rules` — that mirror the rule-management endpoints of the [v2 push backend spec](https://hackmd.io/@1JCaGppGSUqHtJilikYaKw/r16YTVg5Ze). A rule is a `(signer, topic)` pair: the host's push backend delivers a push to the user's device(s) whenever a signed statement matching that pair appears on the Statement Store. The product never sees push tokens.
+
+The method names use `add` / `remove` rather than `subscribe` / `unsubscribe` because the `_subscribe` suffix is reserved for streaming TrUAPI methods (e.g. `statementStore.subscribe`).
+
+## References
+
+- Push notifications, original (v1, peer-to-peer): https://hackmd.io/@1JCaGppGSUqHtJilikYaKw/SyPN2yV6lx
+- Push notifications backend design (v2, backend-mediated): https://hackmd.io/@1JCaGppGSUqHtJilikYaKw/r16YTVg5Ze
+
+This RFC exposes a TrUAPI-shaped surface over the rule-management API defined in the v2 spec.
+
+## Motivation
+
+The push-notifications v2 design assigns delivery to a host-side push backend that tails the Statement Store, verifies signatures, and delivers pushes only for `(signer, topic)` pairs the user has whitelisted. TrUAPI needs a primitive that lets a product manipulate that whitelist.
+
+### Worked example: festival announcements
+
+A conference product publishes festival-wide announcements as signed statements on a well-known topic. When the user taps "notify me about announcements," the subscriber app calls `push_add_rules({ rules: [{ signer: festival_signer, topic: announcements_topic }] })`. From that point on, the user is woken up for new announcements even with the product closed:
+
+```
+Publisher app                                          Subscriber app
+(organizer side)                                       (attendee side)
+        |                                                       ^   |
+        |                                                       |   |
+        |                                                       |   |  (1) pushAddRules({
+        |                                              (6) push |   |        rules: [{
+        |                                               back to |   |          signer: pkPublisher,
+        |                                                caller |   |          topic:  T_announcements
+        |                                                       |   |        }]
+        |                                                       |   |      })
+        |                                                       |   |
+        |                                                       |   v
+        |                  +------------------------------------+---+------+
+        |                  |  Push backend                                 |
+        |                  |  stores rule:                                 |
+        |                  |  (pkPublisher, T_announcements)               |
+        |                  |    -> this subscriber app                     |
+        |                  +-----------------------+-----------------------+
+        |                                          ^
+        |                                          |  (4) tail / match rule
+        |                                          |
+        |                  +-----------------------+-----------------------+
+        |                  | Statement Store                               |
+        |                  +-----------------------+-----------------------+
+        |                                          ^
+        |   (2) compose signed statement           |
+        |--- (3) statementStore.submit(statement) -+
+```
+
+## Detailed Design
+
+### API
+
+Each TrUAPI method mirrors one backend endpoint:
+
+| TrUAPI method       | Backend endpoint                 | Purpose                          |
+| ------------------- | -------------------------------- | -------------------------------- |
+| `push_add_rules`    | `POST   /v1/subscriptions/rules` | add one or more rules            |
+| `push_remove_rules` | `DELETE /v1/subscriptions/rules` | remove one or more rules         |
+| `push_list_rules`   | `GET    /v1/subscriptions`       | snapshot of currently active set |
+| `push_set_rules`    | `PUT    /v1/subscriptions/rules` | atomic replace of the full set   |
+
+```rust
+#[wire(request_id = 134)]
+async fn push_add_rules(
+    &self, cx: &CallContext, request: HostPushAddRulesRequest,
+) -> Result<HostPushAddRulesResponse, CallError<HostPushAddRulesError>>;
+
+#[wire(request_id = 136)]
+async fn push_remove_rules(
+    &self, cx: &CallContext, request: HostPushRemoveRulesRequest,
+) -> Result<HostPushRemoveRulesResponse, CallError<HostPushRemoveRulesError>>;
+
+#[wire(request_id = 138)]
+async fn push_list_rules(
+    &self, cx: &CallContext, request: HostPushListRulesRequest,
+) -> Result<HostPushListRulesResponse, CallError<HostPushListRulesError>>;
+
+#[wire(request_id = 140)]
+async fn push_set_rules(
+    &self, cx: &CallContext, request: HostPushSetRulesRequest,
+) -> Result<HostPushSetRulesResponse, CallError<HostPushSetRulesError>>;
+```
+
+### Types
+
+`Topic` is reused from `v01::statement_store`.
+
+```rust
+pub type StatementSigner = [u8; 32];
+
+/// A single (signer, topic) rule the user wants to be woken up for.
+///
+/// At the host level the effective key is (product, signer, topic): rules
+/// are scoped per calling product, so two products can register the same
+/// (signer, topic) pair independently and never see each other's rules.
+pub struct PushSubscriptionRule {
+    pub signer: StatementSigner,
+    pub topic:  Topic,
+}
+
+pub struct HostPushAddRulesRequest    { pub rules: Vec<PushSubscriptionRule> }
+pub struct HostPushRemoveRulesRequest { pub rules: Vec<PushSubscriptionRule> }
+pub struct HostPushListRulesRequest;
+pub struct HostPushSetRulesRequest    { pub rules: Vec<PushSubscriptionRule> }
+
+pub struct HostPushListRulesResponse {
+    pub rules: Vec<PushSubscriptionRule>,
+}
+
+pub enum HostPushAddRulesError {
+    /// The user has not granted `DevicePermission::Notifications`. The host
+    /// SHOULD prompt for the permission lazily on the first such call from
+    /// a product; if the user dismisses or declines, this variant is
+    /// returned and no rules are stored.
+    PermissionDenied,
+    /// The host could not reach the push backend; no rules were stored.
+    BackendUnavailable,
+    /// Catch-all. `reason`
+    Unknown { reason: String },
+}
+
+pub enum HostPushRemoveRulsError {
+    BackendUnavailable,
+    Unknown { reason: String },
+}
+
+pub enum HostPushListRulesError {
+    BackendUnavailable,
+    Unknown { reason: String },
+}
+
+pub enum HostPushSetRulesError {
+    PermissionDenied,
+    BackendUnavailable,
+    Unknown { reason: String },
+}
+```

docs/rfcs/_index.md

@@ -21,3 +21,4 @@ created: 2026-03-13
 | 0011   | [Simple Group Chat](0011-simple-group-chat.md)                           | draft    | @filvecchiato | [#131](https://github.com/paritytech/triangle-js-sdks/pull/131) |
 | 0015   | [Get User Primary DotNS Name](0015-get-user-id.md)                      | draft    | @valentunn    | [#144](https://github.com/paritytech/triangle-js-sdks/pull/144) |
 | 0019   | [Scheduled Push Notifications](0019-scheduled-notifications.md)          | draft    | @johnthecat   |                                                                 |
+| 0020   | [Push Notification Subscriptions](0020-push-notification-subscriptions.md) | draft  | @pgherveou    |                                                                 |

rust/crates/truapi/src/api/mod.rs

@@ -6,6 +6,7 @@ pub mod chat;
 pub mod entropy;
 pub mod jsonrpc;
 pub mod local_storage;
+pub mod notifications;
 pub mod payment;
 pub mod permissions;
 pub mod preimage;
@@ -21,6 +22,7 @@ pub use chat::Chat;
 pub use entropy::Entropy;
 pub use jsonrpc::JsonRpc;
 pub use local_storage::LocalStorage;
+pub use notifications::Notifications;
 pub use payment::Payment;
 pub use permissions::Permissions;
 pub use preimage::Preimage;
@@ -38,6 +40,7 @@ pub trait TrUApi:
     + Entropy
     + JsonRpc
     + LocalStorage
+    + Notifications
     + Payment
     + Permissions
     + Preimage
@@ -58,6 +61,7 @@ impl<T> TrUApi for T where
         + Entropy
         + JsonRpc
         + LocalStorage
+        + Notifications
         + Payment
         + Permissions
         + Preimage

rust/crates/truapi/src/api/notifications.rs

@@ -0,0 +1,151 @@
+//! Unified [`Notifications`] trait.
+
+use crate::versioned::notifications::{
+    HostPushAddRulesError, HostPushAddRulesRequest, HostPushAddRulesResponse,
+    HostPushListRulesError, HostPushListRulesRequest, HostPushListRulesResponse,
+    HostPushNotificationError, HostPushNotificationRequest, HostPushNotificationResponse,
+    HostPushRemoveRulesError, HostPushRemoveRulesRequest, HostPushRemoveRulesResponse,
+    HostPushSetRulesError, HostPushSetRulesRequest, HostPushSetRulesResponse,
+};
+use crate::wire;
+use crate::{CallContext, CallError};
+
+/// Notification methods: locally-rendered notifications and Statement Store
+/// subscription rules for backend-delivered pushes.
+///
+/// The rule-management methods (`push_add_rules`, `push_remove_rules`,
+/// `push_list_rules`, `push_set_rules`) mirror the rule-management endpoints
+/// of the push-notifications v2 backend design:
+///
+/// - <https://hackmd.io/@1JCaGppGSUqHtJilikYaKw/r16YTVg5Ze> — v2,
+///   backend-mediated
+/// - <https://hackmd.io/@1JCaGppGSUqHtJilikYaKw/SyPN2yV6lx> — v1,
+///   peer-to-peer (historical context)
+pub trait Notifications: Send + Sync {
+    /// Send a notification to the user, rendered immediately by the host.
+    ///
+    /// ```ts
+    /// import { type Client } from "@parity/truapi";
+    ///
+    /// export async function pushNotification(truapi: Client): Promise<void> {
+    ///   const result = await truapi.notifications.pushNotification({
+    ///     text: "Hello!",
+    ///   });
+    ///
+    ///   if (result.isErr()) throw result.error;
+    /// }
+    /// ```
+    #[wire(request_id = 4)]
+    async fn push_notification(
+        &self,
+        cx: &CallContext,
+        request: HostPushNotificationRequest,
+    ) -> Result<HostPushNotificationResponse, CallError<HostPushNotificationError>>;
+
+    /// Register one or more `(signer, topic)` rules so the user is woken up
+    /// by a push when a signed statement matching any registered rule
+    /// appears on the Statement Store. Mirrors
+    /// `POST /v1/subscriptions/rules` from the v2 push backend spec.
+    ///
+    /// ```ts
+    /// import { type Client } from "@parity/truapi";
+    ///
+    /// export async function addAnnouncementsRules(
+    ///   truapi: Client,
+    /// ): Promise<void> {
+    ///   const result = await truapi.notifications.pushAddRules({
+    ///     rules: [
+    ///       {
+    ///         signer: "0x0000000000000000000000000000000000000000000000000000000000000000",
+    ///         topic: "0x00",
+    ///       },
+    ///     ],
+    ///   });
+    ///
+    ///   if (result.isErr()) throw result.error;
+    /// }
+    /// ```
+    #[wire(request_id = 134)]
+    async fn push_add_rules(
+        &self,
+        cx: &CallContext,
+        request: HostPushAddRulesRequest,
+    ) -> Result<HostPushAddRulesResponse, CallError<HostPushAddRulesError>>;
+
+    /// Remove one or more previously registered subscription rules. Mirrors
+    /// `DELETE /v1/subscriptions/rules` from the v2 push backend spec.
+    ///
+    /// ```ts
+    /// import { type Client } from "@parity/truapi";
+    ///
+    /// export async function removeAnnouncementsRules(
+    ///   truapi: Client,
+    /// ): Promise<void> {
+    ///   const result = await truapi.notifications.pushRemoveRules({
+    ///     rules: [
+    ///       {
+    ///         signer: "0x0000000000000000000000000000000000000000000000000000000000000000",
+    ///         topic: "0x00",
+    ///       },
+    ///     ],
+    ///   });
+    ///
+    ///   if (result.isErr()) throw result.error;
+    /// }
+    /// ```
+    #[wire(request_id = 136)]
+    async fn push_remove_rules(
+        &self,
+        cx: &CallContext,
+        request: HostPushRemoveRulesRequest,
+    ) -> Result<HostPushRemoveRulesResponse, CallError<HostPushRemoveRulesError>>;
+
+    /// List the calling product's currently registered subscription rules.
+    /// Useful for reconciling local UI state with what the host believes is
+    /// active (e.g. after logout/login). Mirrors
+    /// `GET /v1/subscriptions` from the v2 push backend spec.
+    ///
+    /// ```ts
+    /// import { type Client } from "@parity/truapi";
+    ///
+    /// export async function listRules(truapi: Client) {
+    ///   const result = await truapi.notifications.pushListRules({});
+    ///   if (result.isErr()) throw result.error;
+    ///   return result.value.rules;
+    /// }
+    /// ```
+    #[wire(request_id = 138)]
+    async fn push_list_rules(
+        &self,
+        cx: &CallContext,
+        request: HostPushListRulesRequest,
+    ) -> Result<HostPushListRulesResponse, CallError<HostPushListRulesError>>;
+
+    /// Atomically replace the calling product's entire rule set with the
+    /// supplied vector. After a successful call, the product's active rules
+    /// are exactly `rules`. Mirrors `PUT /v1/subscriptions/rules` from the
+    /// v2 push backend spec.
+    ///
+    /// ```ts
+    /// import { type Client } from "@parity/truapi";
+    ///
+    /// export async function setRules(truapi: Client): Promise<void> {
+    ///   const result = await truapi.notifications.pushSetRules({
+    ///     rules: [
+    ///       {
+    ///         signer: "0x0000000000000000000000000000000000000000000000000000000000000000",
+    ///         topic: "0x00",
+    ///       },
+    ///     ],
+    ///   });
+    ///
+    ///   if (result.isErr()) throw result.error;
+    /// }
+    /// ```
+    #[wire(request_id = 140)]
+    async fn push_set_rules(
+        &self,
+        cx: &CallContext,
+        request: HostPushSetRulesRequest,
+    ) -> Result<HostPushSetRulesResponse, CallError<HostPushSetRulesError>>;
+}

rust/crates/truapi/src/api/system.rs

@@ -3,14 +3,13 @@
 use crate::versioned::system::{
     HostFeatureSupportedError, HostFeatureSupportedRequest, HostFeatureSupportedResponse,
     HostHandshakeError, HostHandshakeRequest, HostHandshakeResponse, HostNavigateToError,
-    HostNavigateToRequest, HostNavigateToResponse, HostPushNotificationError,
-    HostPushNotificationRequest, HostPushNotificationResponse,
+    HostNavigateToRequest, HostNavigateToResponse,
 };
 use crate::wire;
 use crate::{CallContext, CallError};
 
-/// General-purpose TrUAPI methods for handshake, feature detection,
-/// navigation, and notifications.
+/// General-purpose TrUAPI methods for handshake, feature detection, and
+/// navigation.
 pub trait System: Send + Sync {
     /// Negotiate the wire codec version with the product.
     ///
@@ -63,26 +62,6 @@ pub trait System: Send + Sync {
         request: HostFeatureSupportedRequest,
     ) -> Result<HostFeatureSupportedResponse, CallError<HostFeatureSupportedError>>;
 
-    /// Send a push notification to the user.
-    ///
-    /// ```ts
-    /// import { type Client } from "@parity/truapi";
-    ///
-    /// export async function pushNotification(truapi: Client): Promise<void> {
-    ///   const result = await truapi.system.pushNotification({
-    ///     text: "Hello!",
-    ///   });
-    ///
-    ///   if (result.isErr()) throw result.error;
-    /// }
-    /// ```
-    #[wire(request_id = 4)]
-    async fn push_notification(
-        &self,
-        cx: &CallContext,
-        request: HostPushNotificationRequest,
-    ) -> Result<HostPushNotificationResponse, CallError<HostPushNotificationError>>;
-
     /// Request the host to open a URL.
     ///
     /// ```ts