RFC: Product Session Restore Host API

docs/rfcs/_index.md

@@ -19,5 +19,6 @@ created: 2026-03-13
 | 0010   | [Root account access Host API](0010-get-root-account.md)                 | accepted | @johnthecat   | [#126](https://github.com/paritytech/triangle-js-sdks/pull/126) |
 | 0010   | [W3S Allowance Management](0010-allowance.md)                            | draft    | @valentunn    | —                                                               |
 | 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) |
+| 0015   | [Get User Primary DotNS Name](0015-get-user-id.md)                       | draft    | @valentunn    | [#144](https://github.com/paritytech/triangle-js-sdks/pull/144) |
+| 0016   | [Product Session Restore Host API](0016-product-session-restore.md)      | draft    | @replghost    | —                                                               |
 | 0019   | [Scheduled Push Notifications](0019-scheduled-notifications.md)          | draft    | @johnthecat   |                                                                 |

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

@@ -10,6 +10,7 @@ pub mod payment;
 pub mod permissions;
 pub mod preimage;
 pub mod resource_allocation;
+pub mod session;
 pub mod signing;
 pub mod statement_store;
 pub mod system;
@@ -25,6 +26,7 @@ pub use payment::Payment;
 pub use permissions::Permissions;
 pub use preimage::Preimage;
 pub use resource_allocation::ResourceAllocation;
+pub use session::Session;
 pub use signing::Signing;
 pub use statement_store::StatementStore;
 pub use system::System;
@@ -42,6 +44,7 @@ pub trait TrUApi:
     + Permissions
     + Preimage
     + ResourceAllocation
+    + Session
     + Signing
     + StatementStore
     + System
@@ -62,6 +65,7 @@ impl<T> TrUApi for T where
         + Permissions
         + Preimage
         + ResourceAllocation
+        + Session
         + Signing
         + StatementStore
         + System

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

@@ -0,0 +1,53 @@
+//! Unified [`Session`] trait.
+
+use crate::versioned::session::{
+    HostSessionLifecycleSubscribeError, HostSessionLifecycleSubscribeItem,
+    HostSessionLifecycleSubscribeRequest,
+};
+use crate::wire;
+use crate::{CallContext, CallError, Subscription};
+
+/// Product session lifecycle operations.
+///
+/// Default methods return [`CallError::HostFailure`] with an `unavailable`
+/// reason. Hosts override when they support product session restore.
+pub trait Session: Send + Sync {
+    /// Subscribe to host lifecycle signals so a product can checkpoint semantic
+    /// session state through scoped local storage before suspend, eviction, or
+    /// close.
+    ///
+    /// ```truapi-client-example
+    /// import {
+    ///   type Client,
+    ///   type HostSessionLifecycleSubscribeError,
+    ///   type HostSessionLifecycleSubscribeItem,
+    ///   type Subscription,
+    ///   type SubscriptionError,
+    /// } from "@parity/truapi";
+    ///
+    /// export function watchSessionLifecycle(truapi: Client): Subscription {
+    ///   return truapi.session
+    ///     .sessionLifecycleSubscribe({
+    ///       request: { replayCurrentState: true },
+    ///     })
+    ///     .subscribe({
+    ///       next: (event: HostSessionLifecycleSubscribeItem) =>
+    ///         console.log(event),
+    ///       error: (error: SubscriptionError<HostSessionLifecycleSubscribeError>) =>
+    ///         console.error(error),
+    ///       complete: () => console.log("completed"),
+    ///     });
+    /// }
+    /// ```
+    #[wire(start_id = 162)]
+    async fn lifecycle_subscribe(
+        &self,
+        _cx: &CallContext,
+        _request: HostSessionLifecycleSubscribeRequest,
+    ) -> Result<
+        Subscription<HostSessionLifecycleSubscribeItem>,
+        CallError<HostSessionLifecycleSubscribeError>,
+    > {
+        Err(CallError::unavailable())
+    }
+}

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

@@ -11,6 +11,7 @@ mod payment;
 mod permissions;
 mod preimage;
 mod resource_allocation;
+mod session;
 mod signing;
 mod statement_store;
 mod system;
@@ -28,6 +29,7 @@ pub use payment::*;
 pub use permissions::*;
 pub use preimage::*;
 pub use resource_allocation::*;
+pub use session::*;
 pub use signing::*;
 pub use statement_store::*;
 pub use system::*;

rust/crates/truapi/src/v01/session.rs

@@ -0,0 +1,64 @@
+use parity_scale_codec::{Decode, Encode};
+
+use super::GenericErr;
+
+/// Milliseconds since the Unix epoch.
+pub type TimestampMs = u64;
+
+/// Host-assigned stable identifier for one lifecycle event.
+pub type SessionLifecycleEventId = String;
+
+/// Request to subscribe to host session lifecycle events.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct HostSessionLifecycleSubscribeRequest {
+    /// Ask the host to replay the current lifecycle state when one is active.
+    pub replay_current_state: bool,
+}
+
+/// Lifecycle event emitted by the host before a product transition.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub enum HostSessionLifecycleSubscribeItem {
+    /// The product should checkpoint state before it is suspended.
+    WillSuspend(SessionLifecycleRequest),
+    /// The product should checkpoint state before its WebView may be evicted.
+    WillEvict(SessionLifecycleRequest),
+    /// The product should checkpoint state before it is closed.
+    WillClose(SessionLifecycleRequest),
+}
+
+/// Details for a single lifecycle checkpoint request.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct SessionLifecycleRequest {
+    /// Host-assigned event id for de-duplicating repeated notifications.
+    pub event_id: SessionLifecycleEventId,
+    /// Reason the host is asking the product to checkpoint state.
+    pub reason: SessionLifecycleReason,
+    /// Best-effort deadline for checkpoint completion.
+    pub deadline_ms: Option<TimestampMs>,
+}
+
+/// Reason for a lifecycle checkpoint request.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub enum SessionLifecycleReason {
+    /// User switched away from this product in the host app switcher.
+    AppSwitcher,
+    /// Host application moved to the background.
+    HostBackgrounded,
+    /// Host application is terminating or restarting.
+    HostTerminating,
+    /// Platform memory pressure may evict the product WebView.
+    MemoryPressure,
+    /// User explicitly closed this product.
+    UserClosedProduct,
+    /// Host policy requires a checkpoint.
+    HostPolicy,
+}
+
+/// Error from session lifecycle subscription setup.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub enum HostSessionLifecycleSubscribeError {
+    /// The host does not support product session lifecycle events.
+    Unsupported,
+    /// Catch-all.
+    Unknown(GenericErr),
+}

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

@@ -90,6 +90,7 @@ pub mod payment;
 pub mod permissions;
 pub mod preimage;
 pub mod resource_allocation;
+pub mod session;
 pub mod signing;
 pub mod statement_store;
 pub mod system;

rust/crates/truapi/src/versioned/session.rs

@@ -0,0 +1,9 @@
+//! Versioned wrappers for [`Session`](crate::api::Session) methods.
+
+use crate::v01;
+
+versioned_type! {
+    pub enum HostSessionLifecycleSubscribeRequest { V1 => v01::HostSessionLifecycleSubscribeRequest }
+    pub enum HostSessionLifecycleSubscribeItem { V1 => v01::HostSessionLifecycleSubscribeItem }
+    pub enum HostSessionLifecycleSubscribeError { V1 => v01::HostSessionLifecycleSubscribeError }
+}