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

Implements the JS SDK side of paritytech/truapi RFC 0019 (scheduled push
notifications with idempotent cancellation).

BREAKING CHANGE: `host_push_notification` wire format changes — request gains
`scheduled_at: Option<u64>` (ms UTC), response becomes
`Result<NotificationId, PushNotificationError>` with `ScheduleLimitReached`
and `Unknown { reason }` variants. The prior wire format is replaced rather
than versioned alongside; hosts and products must upgrade together.

Protocol changes (v0.8 of host-api-protocol.md):
- `host_push_notification` carries the new `PushNotification` struct
- new `host_push_notification_cancel(NotificationId) -> Result<(), GenericErr>`
- both methods gated by `DevicePermission::Notifications`

SDK changes:
- host-api: `PushNotification`, `NotificationId`, `PushNotificationError`
- host-container: new `handlePushNotificationCancel`; existing
  `handlePushNotification` returns `NotificationId` and rejects with
  `PushNotificationError`
- host-api-wrapper: `createNotificationManager()` exposing
  `.push({ text, deeplink?, scheduledAt? })` and `.cancel(id)`

Host-side persistence, OS-scheduler integration, and the platform-wide
queue cap remain host-application concerns; the SDK only transports
the typed error.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: cuteWarmFrog

__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,72 @@ 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 transport ok for any id without inspecting it (host enforces RFC §5 idempotency)', async () => {
+    const { container, hostApi } = setup();
+
+    container.handleDevicePermission((_, { ok }) => ok(true));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotificationCancel>>((_, { ok }) =>
+      ok(undefined),
+    );
+    container.handlePushNotificationCancel(handler);
+
+    // The SDK does NOT enforce idempotency itself — that's the host's responsibility per RFC §5.
+    // This test only verifies the wire faithfully carries an arbitrary id and the host's Ok response.
+    const result = await hostApi.pushNotificationCancel(enumValue('v1', 99999));
+
+    expect(result.isOk()).toBe(true);
+    expect(handler).toBeCalledWith(99999, { 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(
@@ -484,6 +495,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.

packages/host-api-wrapper/src/index.ts

@@ -38,6 +38,9 @@ export { createThemeProvider } from './theme.js';
 
 export { createLocalStorage, hostLocalStorage } from './localStorage.js';
 
+export type { NotificationId, PushNotificationInput } from './notification.js';
+export { createNotificationManager, notificationManager } from './notification.js';
+
 export { createPreimageManager, preimageManager } from './preimage.js';
 
 export type { PaymentBalance, PaymentStatus, TopUpSource } from './payments.js';

packages/host-api-wrapper/src/notification.ts

@@ -0,0 +1,42 @@
+import { createHostApi, enumValue } from '@novasamatech/host-api';
+
+import { resultToPromise, unwrapVersionedResult } from './helpers.js';
+import { sandboxTransport } from './sandboxTransport.js';
+
+export type NotificationId = number;
+
+export type PushNotificationInput = {
+  text: string;
+  deeplink?: string;
+  /** Unix timestamp in milliseconds (UTC). Omit for immediate delivery. Past values fire immediately. */
+  scheduledAt?: number;
+};
+
+export const createNotificationManager = (transport = sandboxTransport) => {
+  const supportedVersion = 'v1';
+  const hostApi = createHostApi(transport);
+
+  return {
+    push({ text, deeplink, scheduledAt }: PushNotificationInput): Promise<NotificationId> {
+      return resultToPromise(
+        unwrapVersionedResult(
+          supportedVersion,
+          hostApi.pushNotification(
+            enumValue(supportedVersion, {
+              text,
+              deeplink,
+              scheduledAt: scheduledAt === undefined ? undefined : BigInt(scheduledAt),
+            }),
+          ),
+        ),
+      );
+    },
+    cancel(id: NotificationId): Promise<void> {
+      return resultToPromise(
+        unwrapVersionedResult(supportedVersion, hostApi.pushNotificationCancel(enumValue(supportedVersion, id))),
+      );
+    },
+  };
+};
+
+export const notificationManager = createNotificationManager();

packages/host-api/src/hostApi.ts

@@ -12,6 +12,7 @@ import { DeriveEntropyErr } from './protocol/v1/deriveEntropy.js';
 import { HandshakeErr } from './protocol/v1/handshake.js';
 import { StorageErr } from './protocol/v1/localStorage.js';
 import { NavigateToErr } from './protocol/v1/navigation.js';
+import { PushNotificationError } from './protocol/v1/notification.js';
 import { PaymentRequestErr, PaymentTopUpErr } from './protocol/v1/payments.js';
 import { PreimageSubmitErr } from './protocol/v1/preimage.js';
 import { ResourceAllocationErr } from './protocol/v1/resourceAllocation.js';
@@ -103,6 +104,13 @@ export function createHostApi(transport: Transport): HostApi {
 
     pushNotification(payload) {
       return makeRequest(transport.request('host_push_notification', payload), reason => ({
+        tag: payload.tag,
+        value: new PushNotificationError.Unknown({ reason }),
+      }));
+    },
+
+    pushNotificationCancel(payload) {
+      return makeRequest(transport.request('host_push_notification_cancel', payload), reason => ({
         tag: payload.tag,
         value: new GenericError({ reason }),
       }));

packages/host-api/src/index.ts

@@ -87,7 +87,7 @@ export {
 export { StorageErr } from './protocol/v1/localStorage.js';
 export { DevicePermission } from './protocol/v1/devicePermission.js';
 export { RemotePermission } from './protocol/v1/remotePermission.js';
-export { PushNotification } from './protocol/v1/notification.js';
+export { NotificationId, PushNotification, PushNotificationError } from './protocol/v1/notification.js';
 export { NavigateToErr } from './protocol/v1/navigation.js';
 export { PreimageKey, PreimageSubmitErr, PreimageValue } from './protocol/v1/preimage.js';
 export { AllocatableResource, AllocationOutcome, ResourceAllocationErr } from './protocol/v1/resourceAllocation.js';

packages/host-api/src/protocol/impl.ts

@@ -85,7 +85,12 @@ import {
   StorageWriteV1_response,
 } from './v1/localStorage.js';
 import { NavigateToV1_request, NavigateToV1_response } from './v1/navigation.js';
-import { PushNotificationV1_request, PushNotificationV1_response } from './v1/notification.js';
+import {
+  PushNotificationCancelV1_request,
+  PushNotificationCancelV1_response,
+  PushNotificationV1_request,
+  PushNotificationV1_response,
+} from './v1/notification.js';
 import {
   PaymentBalanceSubscribeV1_interrupt,
   PaymentBalanceSubscribeV1_receive,
@@ -204,6 +209,10 @@ export const hostApiProtocol = {
     v1: [PushNotificationV1_request, PushNotificationV1_response],
   }),
 
+  host_push_notification_cancel: versionedRequest({
+    v1: [PushNotificationCancelV1_request, PushNotificationCancelV1_response],
+  }),
+
   host_navigate_to: versionedRequest({
     v1: [NavigateToV1_request, NavigateToV1_response],
   }),