feat(host-api): scheduled push notifications (RFC 0019) (#170)

Co-authored-by: Sergey Zhuravlev <zhuravlev1337@gmail.com>

Author: cuteWarmFrog

.gitignore

@@ -29,3 +29,5 @@ vitest.config.*.timestamp*
 packages/*/dist
 
 storybook-static
+
+docs/superpowers/

CHANGELOG.md

@@ -6,6 +6,9 @@
 - **host-papp:** `UserSession` gains a `createTransaction(payload)` method. The Host can now delegate product-account transaction signing to the paired Polkadot Mobile app via the new `CreateTransactionRequest` / `CreateTransactionResponse` SSO message pair (legacy-account signing stays Host-local).
 - **product-sdk:** new top-level `accounts` singleton (`createAccountsProvider()` with the default sandbox transport) for products that don't need a custom transport.
 - **product-sdk:** export `ProductAccountId` and `LegacyAccount` types.
+- **host-api / product-sdk:** products can now schedule a push notification for a future time, not just send one right away. Pass `scheduledAt` (a UTC timestamp in milliseconds) when calling `notificationManager.push(...)`, and the host will deliver it at that moment. Leave it out to deliver immediately as before.
+- **host-api / product-sdk:** `push(...)` now returns an id you can hold onto, and the new `notificationManager.cancel(id)` lets a product cancel a notification it scheduled earlier — handy for "remind me in an hour" style flows where the user changes their mind.
+- **host-api / product-sdk:** if the host can't accept any more scheduled notifications, the product now gets a clear `ScheduleLimitReached` error instead of a generic failure, so it can tell the user what happened.
 
 ### ⚠️ Breaking Changes
 
@@ -18,6 +21,7 @@
 - **product-sdk:** new runtime dependency `@polkadot-api/substrate-bindings@^0.20.2` (used by `getProductAccountSigner` to decode metadata locally and pick `txExtVersion`).
 
   > No compatibility shim. `host_create_transaction` had no production consumers and `host_create_transaction_with_legacy_account` is only reachable via `product-sdk`, which is bumped in lockstep.
+- **host-api:** the push-notification format changed to support scheduling and cancellation. Hosts and products must upgrade together — older clients won't be able to send notifications to a newer host (or vice versa).
 
 ## 0.7.8 (2026-05-08)
 

__tests__/hostApi/notification.spec.ts

@@ -1,4 +1,4 @@
-import { GenericError, createHostApi, createTransport, enumValue } from '@novasamatech/host-api';
+import { GenericError, PushNotificationError, createHostApi, createTransport, enumValue } from '@novasamatech/host-api';
 import type { ContainerHandlerOf } from '@novasamatech/host-container';
 import { createContainer } from '@novasamatech/host-container';
 
@@ -16,23 +16,23 @@ function setup() {
 }
 
 describe('Host API: PushNotification', () => {
-  it('should deliver a notification and gate on Notifications device permission', async () => {
+  it('should deliver an immediate notification and return a NotificationId', async () => {
     const { container, hostApi } = setup();
-    const payload = { text: 'Hello, world!', deeplink: 'https://example.com/deep' };
+    const payload = { text: 'Hello, world!', deeplink: 'https://example.com/deep', scheduledAt: undefined };
 
     const devicePermissionHandler = vi.fn<ContainerHandlerOf<typeof container.handleDevicePermission>>(
       (_params, { ok }) => ok(true),
     );
     container.handleDevicePermission(devicePermissionHandler);
-    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(undefined));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(42));
     container.handlePushNotification(handler);
 
     const result = await hostApi.pushNotification(enumValue('v1', payload));
 
     result.match(
       ok => {
         expect(ok.tag).toBe('v1');
-        expect(ok.value).toBeUndefined();
+        expect(ok.value).toBe(42);
       },
       () => {
         throw new Error('Expected success');
@@ -47,10 +47,10 @@ describe('Host API: PushNotification', () => {
 
   it('should deliver a notification without a deeplink', async () => {
     const { container, hostApi } = setup();
-    const payload = { text: 'Notification body', deeplink: undefined };
+    const payload = { text: 'Notification body', deeplink: undefined, scheduledAt: undefined };
 
     container.handleDevicePermission((_, { ok }) => ok(true));
-    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(undefined));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(1));
     container.handlePushNotification(handler);
 
     const result = await hostApi.pushNotification(enumValue('v1', payload));
@@ -59,15 +59,27 @@ describe('Host API: PushNotification', () => {
     expect(handler).toBeCalledWith(payload, { ok: expect.any(Function), err: expect.any(Function) });
   });
 
-  it('should propagate handler errors and still gate on Notifications permission', async () => {
+  it('should deliver a scheduled notification carrying scheduledAt as a u64', async () => {
     const { container, hostApi } = setup();
-    const payload = { text: 'will fail', deeplink: undefined };
-    const error = new GenericError({ reason: 'Delivery failed' });
+    const scheduledAt = BigInt(Date.UTC(2027, 0, 1));
+    const payload = { text: 'reminder', deeplink: undefined, scheduledAt };
 
-    const devicePermissionHandler = vi.fn<ContainerHandlerOf<typeof container.handleDevicePermission>>(
-      (_params, { ok }) => ok(true),
-    );
-    container.handleDevicePermission(devicePermissionHandler);
+    container.handleDevicePermission((_, { ok }) => ok(true));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(7));
+    container.handlePushNotification(handler);
+
+    const result = await hostApi.pushNotification(enumValue('v1', payload));
+
+    expect(result.isOk()).toBe(true);
+    expect(handler).toBeCalledWith(payload, { ok: expect.any(Function), err: expect.any(Function) });
+  });
+
+  it('should propagate ScheduleLimitReached', async () => {
+    const { container, hostApi } = setup();
+    const payload = { text: 'full queue', deeplink: undefined, scheduledAt: BigInt(2_000_000_000_000) };
+    const error = new PushNotificationError.ScheduleLimitReached();
+
+    container.handleDevicePermission((_, { ok }) => ok(true));
     container.handlePushNotification((_, { err }) => err(error));
 
     const result = await hostApi.pushNotification(enumValue('v1', payload));
@@ -81,18 +93,35 @@ describe('Host API: PushNotification', () => {
         expect(failure.value).toEqual(error);
       },
     );
+  });
 
-    expect(devicePermissionHandler).toHaveBeenCalledOnce();
-    const [receivedPermissionParams] = devicePermissionHandler.mock.calls[0]!;
-    expect(receivedPermissionParams).toBe('Notifications');
+  it('should propagate Unknown { reason } round-trip', async () => {
+    const { container, hostApi } = setup();
+    const payload = { text: 'boom', deeplink: undefined, scheduledAt: undefined };
+    const error = new PushNotificationError.Unknown({ reason: 'OS rejected' });
+
+    container.handleDevicePermission((_, { ok }) => ok(true));
+    container.handlePushNotification((_, { err }) => err(error));
+
+    const result = await hostApi.pushNotification(enumValue('v1', payload));
+
+    result.match(
+      () => {
+        throw new Error('Expected failure');
+      },
+      failure => {
+        expect(failure.tag).toBe('v1');
+        expect(failure.value).toEqual(error);
+      },
+    );
   });
 
   it('should reject and skip the handler when Notifications permission is denied', async () => {
     const { container, hostApi } = setup();
-    const payload = { text: 'blocked', deeplink: undefined };
+    const payload = { text: 'blocked', deeplink: undefined, scheduledAt: undefined };
 
     container.handleDevicePermission((_, { ok }) => ok(false));
-    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(undefined));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(1));
     container.handlePushNotification(handler);
 
     const result = await hostApi.pushNotification(enumValue('v1', payload));
@@ -104,18 +133,18 @@ describe('Host API: PushNotification', () => {
       },
       failure => {
         expect(failure.tag).toBe('v1');
-        expect(failure.value).toBeInstanceOf(GenericError);
+        expect(failure.value).toBeInstanceOf(PushNotificationError);
       },
     );
     expect(handler).not.toHaveBeenCalled();
   });
 
   it('should reject and skip the handler when the device permission handler errors', async () => {
     const { container, hostApi } = setup();
-    const payload = { text: 'blocked', deeplink: undefined };
+    const payload = { text: 'blocked', deeplink: undefined, scheduledAt: undefined };
 
     container.handleDevicePermission((_, { err }) => err(new GenericError({ reason: 'permission lookup failed' })));
-    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(undefined));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotification>>((_, { ok }) => ok(1));
     container.handlePushNotification(handler);
 
     const result = await hostApi.pushNotification(enumValue('v1', payload));
@@ -124,3 +153,55 @@ describe('Host API: PushNotification', () => {
     expect(handler).not.toHaveBeenCalled();
   });
 });
+
+describe('Host API: PushNotificationCancel', () => {
+  it('should cancel a pending notification by id', async () => {
+    const { container, hostApi } = setup();
+
+    container.handleDevicePermission((_, { ok }) => ok(true));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotificationCancel>>((_, { ok }) =>
+      ok(undefined),
+    );
+    container.handlePushNotificationCancel(handler);
+
+    const result = await hostApi.pushNotificationCancel(enumValue('v1', 42));
+
+    expect(result.isOk()).toBe(true);
+    expect(handler).toBeCalledWith(42, { ok: expect.any(Function), err: expect.any(Function) });
+  });
+
+  it('should propagate GenericError when the host returns one', async () => {
+    const { container, hostApi } = setup();
+    const error = new GenericError({ reason: 'cancel failed' });
+
+    container.handleDevicePermission((_, { ok }) => ok(true));
+    container.handlePushNotificationCancel((_, { err }) => err(error));
+
+    const result = await hostApi.pushNotificationCancel(enumValue('v1', 1));
+
+    result.match(
+      () => {
+        throw new Error('Expected failure');
+      },
+      failure => {
+        expect(failure.tag).toBe('v1');
+        expect(failure.value).toEqual(error);
+      },
+    );
+  });
+
+  it('should reject cancel when Notifications permission is denied', async () => {
+    const { container, hostApi } = setup();
+
+    container.handleDevicePermission((_, { ok }) => ok(false));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotificationCancel>>((_, { ok }) =>
+      ok(undefined),
+    );
+    container.handlePushNotificationCancel(handler);
+
+    const result = await hostApi.pushNotificationCancel(enumValue('v1', 5));
+
+    expect(result.isErr()).toBe(true);
+    expect(handler).not.toHaveBeenCalled();
+  });
+});

docs/design/host-api-protocol.md

@@ -9,6 +9,13 @@ created: 2026-03-13
 
 ## Changelog
 
+### v0.8 - 2026-05-14
+
+- **Breaking change.** Extended `host_push_notification`: request gains `scheduled_at: Option<u64>` (Unix ms UTC) for deferred delivery; response changed from `Result<(), GenericErr>` to `Result<NotificationId, PushNotificationError>` (RFC-0019). The prior wire format is replaced rather than versioned alongside.
+- Added `host_push_notification_cancel(NotificationId) -> Result<(), GenericErr>` for retracting a pending scheduled notification.
+- Both methods are gated by `DevicePermission::Notifications`. No new permission variant.
+- `NotificationId` is opaque per-product; cancellation is idempotent. Persistence, OS-scheduler integration, and the platform-wide queue cap are host-application concerns, not SDK concerns.
+
 ### v0.7 - 2026-04-13
 
 - Renamed all `*_with_non_product_account` methods to `*_with_legacy_account`; renamed `host_get_non_product_accounts` to `host_get_legacy_accounts`; updated glossary term "Non-product account (NPA)" to "Legacy account".
@@ -87,7 +94,11 @@ fn host_feature_supported(
 ) -> Result<bool, GenericErr>;
 
 fn host_push_notification(
-  text: str
+  notification: PushNotification
+) -> Result<NotificationId, PushNotificationError>;
+
+fn host_push_notification_cancel(
+  identifier: NotificationId
 ) -> Result<(), GenericErr>;
 
 fn host_navigate_to(
@@ -482,6 +493,41 @@ fn host_derive_entropy(
 ) -> Result<Entropy, DeriveEntropyErr>;
 ```
 
+#### Push Notifications
+
+Products can request the host to display a notification, either immediately or scheduled for a future wall-clock instant. Both methods are gated by `DevicePermission::Notifications`. See [RFC-0019](https://github.com/paritytech/truapi/blob/main/docs/rfcs/0019-scheduled-notifications.md) for the full motivation and host-side behavioural requirements (persistence, OS-scheduler integration, platform-wide queue cap).
+
+```rust
+type NotificationId = u32;
+
+struct PushNotification {
+  // Notification body text.
+  text: String,
+  // Optional URL to open when the user taps the notification.
+  deeplink: Option<String>,
+  // Optional Unix timestamp in milliseconds (UTC) at which the notification should fire.
+  // `None` fires immediately, preserving prior behaviour. Past timestamps fire immediately.
+  scheduled_at: Option<u64>,
+}
+
+enum PushNotificationError {
+  // The host has reached its platform-wide cap on pending scheduled notifications.
+  // Only returned for scheduled (non-immediate) calls.
+  ScheduleLimitReached,
+  Unknown(GenericErr)
+}
+
+fn host_push_notification(
+  notification: PushNotification
+) -> Result<NotificationId, PushNotificationError>;
+
+fn host_push_notification_cancel(
+  identifier: NotificationId
+) -> Result<(), GenericErr>;
+```
+
+`NotificationId` is opaque and unique per product; the host MUST NOT leak ids across products. An id is returned for every call — immediate or scheduled — for shape uniformity. Cancellation is idempotent: `host_push_notification_cancel` MUST return `Ok(())` regardless of whether the id refers to a pending, already-fired, never-issued, or other-product's notification. This is a breaking change relative to the pre-v0.8 wire format; products and hosts must upgrade together.
+
 #### Device permissions request
 
 Products can request additional device permissions. This check is layered on top of platform permissions (web, iOS, Android) and adds a product-level security gate.