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

Adds wire support for scheduled notifications and idempotent cancellation,
matching the host-side surface in paritytech/truapi#66 / RFC 0019.

Protocol changes (v0.8 of host-api-protocol.md):
- host_push_notification gains a V2 wire schema (adds scheduled_at: Option<u64>,
  returns Result<NotificationId, PushNotificationError>); V1 retained intact
- new host_push_notification_cancel(NotificationId) -> Result<(), GenericErr>
- both methods gated by DevicePermission::Notifications

SDK changes:
- host-api: V2 codecs, NotificationId, PushNotificationError ErrEnum
- host-container: dual v1/v2 dispatch for host_push_notification sharing a
  single transport registration and the Notifications permission gate;
  new handlePushNotificationV2 + handlePushNotificationCancel; refactored
  handleV1/V2Request to share an implementation via handleVersionedRequest
- host-api-wrapper: new createNotificationManager exposing
  push({ text, deeplink?, scheduledAt? }) and cancel(id), always emitting V2

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';
 
@@ -124,3 +124,176 @@ describe('Host API: PushNotification', () => {
     expect(handler).not.toHaveBeenCalled();
   });
 });
+
+describe('Host API: PushNotification (v2)', () => {
+  it('should deliver an immediate notification and return a NotificationId', async () => {
+    const { container, hostApi } = setup();
+    const payload = { text: 'Hello v2', deeplink: 'https://example.com/x', scheduledAt: undefined };
+
+    container.handleDevicePermission((_, { ok }) => ok(true));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotificationV2>>((_, { ok }) => ok(42));
+    container.handlePushNotificationV2(handler);
+
+    const result = await hostApi.pushNotification(enumValue('v2', payload));
+
+    result.match(
+      ok => {
+        expect(ok.tag).toBe('v2');
+        expect(ok.value).toBe(42);
+      },
+      () => {
+        throw new Error('Expected success');
+      },
+    );
+    expect(handler).toBeCalledWith(payload, { ok: expect.any(Function), err: expect.any(Function) });
+  });
+
+  it('should deliver a scheduled notification carrying scheduledAt as a u64', async () => {
+    const { container, hostApi } = setup();
+    const scheduledAt = BigInt(Date.UTC(2027, 0, 1));
+    const payload = { text: 'reminder', deeplink: undefined, scheduledAt };
+
+    container.handleDevicePermission((_, { ok }) => ok(true));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotificationV2>>((_, { ok }) => ok(7));
+    container.handlePushNotificationV2(handler);
+
+    const result = await hostApi.pushNotification(enumValue('v2', 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.handlePushNotificationV2((_, { err }) => err(error));
+
+    const result = await hostApi.pushNotification(enumValue('v2', payload));
+
+    result.match(
+      () => {
+        throw new Error('Expected failure');
+      },
+      failure => {
+        expect(failure.tag).toBe('v2');
+        expect(failure.value).toEqual(error);
+      },
+    );
+  });
+
+  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.handlePushNotificationV2((_, { err }) => err(error));
+
+    const result = await hostApi.pushNotification(enumValue('v2', payload));
+
+    result.match(
+      () => {
+        throw new Error('Expected failure');
+      },
+      failure => {
+        expect(failure.tag).toBe('v2');
+        expect(failure.value).toEqual(error);
+      },
+    );
+  });
+
+  it('should reject v2 when Notifications permission is denied', async () => {
+    const { container, hostApi } = setup();
+    const payload = { text: 'blocked v2', deeplink: undefined, scheduledAt: undefined };
+
+    container.handleDevicePermission((_, { ok }) => ok(false));
+    const handler = vi.fn<ContainerHandlerOf<typeof container.handlePushNotificationV2>>((_, { ok }) => ok(1));
+    container.handlePushNotificationV2(handler);
+
+    const result = await hostApi.pushNotification(enumValue('v2', payload));
+
+    expect(result.isErr()).toBe(true);
+    result.match(
+      () => {
+        throw new Error('Expected failure');
+      },
+      failure => {
+        expect(failure.tag).toBe('v2');
+        expect(failure.value).toBeInstanceOf(PushNotificationError);
+      },
+    );
+    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,14 @@ created: 2026-03-13
 
 ## Changelog
 
+### v0.8 - 2026-05-13
+
+- Extended `host_push_notification` with optional `scheduled_at: u64` (Unix ms UTC) for deferred delivery; return type changed from `Result<(), GenericErr>` to `Result<NotificationId, PushNotificationError>` (RFC-0019).
+- Added `host_push_notification_cancel(NotificationId) -> Result<(), GenericErr>` for retracting a pending scheduled notification.
+- Wire-format break gated behind a new `PushNotificationV2` payload variant of `host_push_notification`; `PushNotificationV1` (text + deeplink, returning `()`) MUST remain accepted for legacy clients.
+- 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".
@@ -86,8 +94,14 @@ fn host_feature_supported(
   feature: Feature
 ) -> Result<bool, GenericErr>;
 
+// Hosts that advertise v0.8+ MUST accept both PushNotificationV1 (legacy)
+// and PushNotificationV2 (current) wire payloads on this method.
 fn host_push_notification(
-  text: str
+  notification: PushNotificationV2
+) -> Result<NotificationId, PushNotificationError>;
+
+fn host_push_notification_cancel(
+  identifier: NotificationId
 ) -> Result<(), GenericErr>;
 
 fn host_navigate_to(
@@ -484,6 +498,52 @@ 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;
+
+// Legacy wire payload, retained for products that have not yet migrated.
+// Response is Result<(), GenericErr>.
+struct PushNotificationV1 {
+  // Notification body text.
+  text: String,
+  // Optional URL to open when the user taps the notification.
+  deeplink: Option<String>,
+}
+
+// Current wire payload. Response is Result<NotificationId, PushNotificationError>.
+struct PushNotificationV2 {
+  text: String,
+  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(
+  // V1 and V2 payloads are both accepted; response shape follows the input version.
+  notification: PushNotificationV2
+) -> 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.
+
+Hosts that advertise v0.8+ MUST send and accept `PushNotificationV2`; `PushNotificationV1` remains supported indefinitely for products that have not migrated.
+
 #### 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,35 @@
+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 hostApi = createHostApi(transport);
+
+  return {
+    push({ text, deeplink, scheduledAt }: PushNotificationInput): Promise<NotificationId> {
+      const result = hostApi.pushNotification(
+        enumValue('v2', {
+          text,
+          deeplink,
+          scheduledAt: scheduledAt === undefined ? undefined : BigInt(scheduledAt),
+        }),
+      ) as never;
+      return resultToPromise(unwrapVersionedResult('v2', result));
+    },
+    cancel(id: NotificationId): Promise<void> {
+      return resultToPromise(unwrapVersionedResult('v1', hostApi.pushNotificationCancel(enumValue('v1', id))));
+    },
+  };
+};
+
+export const notificationManager = createNotificationManager();

packages/host-api/src/hostApi.ts

@@ -12,6 +12,11 @@ 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,
+  PushNotificationV1_response,
+  PushNotificationV2_response,
+} 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';
@@ -102,7 +107,26 @@ export function createHostApi(transport: Transport): HostApi {
     },
 
     pushNotification(payload) {
-      return makeRequest(transport.request('host_push_notification', payload), reason => ({
+      if (payload.tag === 'v2') {
+        return makeRequest(
+          transport.request('host_push_notification', payload) as Promise<{
+            tag: 'v2';
+            value: CodecType<typeof PushNotificationV2_response>;
+          }>,
+          reason => ({ tag: 'v2' as const, value: new PushNotificationError.Unknown({ reason }) }),
+        ) as ReturnType<HostApi['pushNotification']>;
+      }
+      return makeRequest(
+        transport.request('host_push_notification', payload) as Promise<{
+          tag: 'v1';
+          value: CodecType<typeof PushNotificationV1_response>;
+        }>,
+        reason => ({ tag: 'v1' as const, value: new GenericError({ reason }) }),
+      ) as ReturnType<HostApi['pushNotification']>;
+    },
+
+    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,12 @@ 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,
+  PushNotificationError,
+  PushNotificationV1,
+  PushNotificationV2,
+} 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,14 @@ 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,
+  PushNotificationV2_request,
+  PushNotificationV2_response,
+} from './v1/notification.js';
 import {
   PaymentBalanceSubscribeV1_interrupt,
   PaymentBalanceSubscribeV1_receive,
@@ -202,6 +209,11 @@ export const hostApiProtocol = {
 
   host_push_notification: versionedRequest({
     v1: [PushNotificationV1_request, PushNotificationV1_response],
+    v2: [PushNotificationV2_request, PushNotificationV2_response],
+  }),
+
+  host_push_notification_cancel: versionedRequest({
+    v1: [PushNotificationCancelV1_request, PushNotificationCancelV1_response],
   }),
 
   host_navigate_to: versionedRequest({