@parity/product-sdk-host 0.0.0-dev.312.0

package/src/features.ts

@@ -0,0 +1,172 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrappers for the host's feature-support probe.
+ *
+ * `truApi.system.featureSupported` returns a neverthrow `ResultAsync`;
+ * {@link featureSupported} collapses that to a `Result` carrying the host's
+ * boolean answer. {@link isChainSupported} is a convenience over the only
+ * feature variant the host exposes today (`Chain`).
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { type HostError, HostUnavailableError } from "./errors.js";
+import { type Result, err } from "./result.js";
+import { getTruApi, type HexString, mapHostResult } from "./truapi.js";
+
+const log = createLogger("host:features");
+
+/**
+ * A feature the host can be probed for via {@link featureSupported}.
+ *
+ * The only variant today is `Chain`, carrying the chain's `0x`-prefixed genesis
+ * hash. This is a flattened form of truapi's `HostFeatureSupportedRequest`,
+ * which nests the hash as `{ tag: "Chain"; value: { genesisHash } }` — we
+ * inline `value` as the `HexString` for ergonomics and re-nest it at the call
+ * site. New variants surface here as a widening of the union.
+ */
+export type Feature = { tag: "Chain"; value: HexString };
+
+/**
+ * Probe the host for support of a specific feature.
+ *
+ * Calls `truApi.system.featureSupported`, unwraps the response, and returns the
+ * host's boolean answer.
+ *
+ * @param feature - The feature to probe for.
+ * @returns `ok(true)` if the host supports the feature, `ok(false)` otherwise,
+ *   or `err(HostUnavailableError | HostCallFailedError)`.
+ *
+ * @example
+ * ```ts
+ * import { featureSupported } from "@parity/product-sdk-host";
+ *
+ * const r = await featureSupported({ tag: "Chain", value: genesisHash });
+ * if (r.ok && r.value) { ... }
+ * ```
+ */
+export async function featureSupported(feature: Feature): Promise<Result<boolean, HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        return err(new HostUnavailableError("featureSupported: TruAPI unavailable"));
+    }
+    log.debug("featureSupported", { tag: feature.tag });
+
+    return mapHostResult(
+        truApi.system.featureSupported({ tag: feature.tag, value: { genesisHash: feature.value } }),
+        (response) => response.supported,
+        "featureSupported failed",
+    );
+}
+
+/**
+ * Convenience probe: is the chain with the given genesis hash supported by the
+ * host? Wraps {@link featureSupported} for the `Chain` feature variant.
+ *
+ * @param genesisHash - The chain's `0x`-prefixed genesis hash.
+ * @returns `ok(true)` if the host supports the chain, `ok(false)` otherwise, or
+ *   `err(HostUnavailableError | HostCallFailedError)`.
+ *
+ * @example
+ * ```ts
+ * import { isChainSupported } from "@parity/product-sdk-host";
+ *
+ * const r = await isChainSupported(genesisHash);
+ * if (!r.ok || !r.value) {
+ *   tellUserChainUnavailable();
+ * }
+ * ```
+ */
+export async function isChainSupported(
+    genesisHash: HexString,
+): Promise<Result<boolean, HostError>> {
+    return featureSupported({ tag: "Chain", value: genesisHash });
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: { system?: { featureSupported?: (req: unknown) => unknown } } | null,
+        fn: (mod: typeof import("./features.js")) => Promise<T>,
+    ): Promise<T> {
+        vi.resetModules();
+        vi.doMock("./truapi.js", async (importOriginal) => {
+            const original = await importOriginal<typeof import("./truapi.js")>();
+            return {
+                ...original,
+                getTruApi: async () => bridge,
+            };
+        });
+        try {
+            const mod = await import("./features.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    const okBridge = (supported: boolean) => ({
+        system: {
+            featureSupported: vi.fn().mockReturnValue({
+                match: async (onOk: (v: unknown) => unknown) => onOk({ supported }),
+            }),
+        },
+    });
+
+    describe("featureSupported", () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                const result = await mod.featureSupported({ tag: "Chain", value: "0x00" });
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
+            });
+        });
+
+        test("returns ok with the boolean outcome", async () => {
+            await withMockedTruApi(okBridge(true), async (mod) => {
+                expect(await mod.featureSupported({ tag: "Chain", value: "0x00" })).toEqual({
+                    ok: true,
+                    value: true,
+                });
+            });
+        });
+
+        test("wraps host errors in err(HostCallFailedError) with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    system: {
+                        featureSupported: vi.fn().mockReturnValue({
+                            match: async (
+                                _onOk: (v: unknown) => unknown,
+                                onErr: (e: unknown) => unknown,
+                            ) => onErr({ reason: "boom" }),
+                        }),
+                    },
+                },
+                async (mod) => {
+                    const result = await mod.featureSupported({ tag: "Chain", value: "0x00" });
+                    expect(result.ok).toBe(false);
+                    if (!result.ok) {
+                        expect(result.error.name).toBe("HostCallFailedError");
+                        expect(result.error.message).toMatch(/featureSupported failed: boom/);
+                    }
+                },
+            );
+        });
+    });
+
+    describe("isChainSupported", () => {
+        test("delegates to featureSupported with the Chain variant", async () => {
+            await withMockedTruApi(okBridge(false), async (mod) => {
+                expect(await mod.isChainSupported("0x1234")).toEqual({ ok: true, value: false });
+            });
+        });
+    });
+}

package/src/index.ts

@@ -0,0 +1,149 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk-host — Detect and talk to the Polkadot Desktop/Mobile host container.
+ *
+ * Use `isInsideContainer` to branch behavior when running embedded vs. standalone,
+ * and `getHostLocalStorage`, `getHostProvider`, and `getStatementStore` to reach
+ * the storage, signer, and statement-store APIs the host injects.
+ *
+ * @packageDocumentation
+ */
+export {
+    isInsideContainer,
+    isInsideContainerSync,
+    getHostLocalStorage,
+    createHostLocalStorage,
+    getHostProvider,
+    getStatementStore,
+    ChainNotSupportedError,
+} from "./container.js";
+export type {
+    HostLocalStorage,
+    HostStatementStore,
+    HostSubscription,
+    ProductAccountId,
+    SignedStatement,
+    Statement,
+    StatementProof,
+    StatementTopicFilter,
+    StatementsPage,
+    Topic,
+} from "./types.js";
+export { BULLETIN_RPCS, DEFAULT_BULLETIN_ENDPOINT } from "./chains.js";
+
+// TruAPI - @parity/truapi client accessor + convenience wrappers.
+export {
+    getTruApi,
+    getPreimageManager,
+    createHostPreimageManager,
+    requestResourceAllocation,
+    createProofAuthorized,
+    // Hex helpers
+    toHex,
+    fromHex,
+} from "./truapi.js";
+export type {
+    TruApi,
+    HexString,
+    PreimageManager,
+    ResultAsync,
+    AllocatableResource,
+    AllocationOutcome,
+    RemotePermission,
+} from "./truapi.js";
+
+// Worker — this product's background worker, called from its rendered surface.
+export { getWorkerManager, WorkerCallError } from "./worker.js";
+export type { WorkerManager, WorkerErrorTag } from "./worker.js";
+
+// Host chain discovery.
+export { getHostChainInfo } from "./chain-discovery.js";
+export type { HostChainDiscovery, HostChainIdentifier } from "./chain-discovery.js";
+
+// Result type + typed host errors (the throw→Result boundary)
+export { ok, err } from "./result.js";
+export type { Result } from "./result.js";
+export { type SdkError, isSdkError } from "@parity/product-sdk-errors";
+export {
+    HostError,
+    HostUnavailableError,
+    HostCallFailedError,
+    isHostError,
+    formatHostError,
+} from "./errors.js";
+export type { HostErrorPayload } from "./errors.js";
+
+// Accounts — host wallet accounts, product accounts, Ring VRF, and signers.
+export { getAccountsProvider, findRingVrfKeyHandle } from "./accounts.js";
+export type {
+    AccountsProvider,
+    DerivationIndex,
+    HostAccount,
+    ProductAccount,
+    ProductAccountLookup,
+    ContextualAlias,
+    ProductProofContext,
+    RegisteredRingVrfKey,
+    RingLocation,
+    RingVRFProof,
+    RingVrfKeyDisclosure,
+    RingVrfKeyHandle,
+    RingVrfPublicKey,
+    VrfSignature,
+    VrfTranscriptItem,
+} from "./accounts.js";
+
+// Higher-level permission wrappers
+export { requestPermission, requestDevicePermission } from "./permissions.js";
+export type { DevicePermissionKind, RemotePermissionItem } from "./permissions.js";
+
+// Theme provider
+export { getThemeProvider } from "./theme.js";
+export type { ThemeMode, ThemeName, ThemeProvider, ThemeVariant } from "./theme.js";
+
+// Entropy derivation (RFC-0007)
+export { deriveEntropy } from "./entropy.js";
+
+// Chat
+export { getChatManager } from "./chat.js";
+export type {
+    ChatManager,
+    ChatMessageContent,
+    ChatReceivedAction,
+    ChatRoom,
+    ChatRoomRegistrationResult,
+    ChatBotRegistrationResult,
+} from "./chat.js";
+
+// Payments (RFC-0006)
+export { getPaymentManager } from "./payments.js";
+export type { PaymentManager } from "./payments.js";
+export type {
+    HostPaymentBalanceSubscribeItem,
+    HostPaymentStatusSubscribeItem,
+    PaymentTopUpSource,
+} from "@parity/truapi";
+
+// Notifications
+export { getNotificationManager } from "./notifications.js";
+export type {
+    NotificationManager,
+    NotificationId,
+    PushNotificationInput,
+    PushNotificationError,
+} from "./notifications.js";
+
+// Deep-link navigation
+export { navigateTo } from "./navigation.js";
+
+// Feature / chain support probes
+export { featureSupported, isChainSupported } from "./features.js";
+export type { Feature } from "./features.js";
+
+// Chain spec lookups
+export { getChainSpec } from "./chain-spec.js";
+export type { ChainSpec, ChainProperties } from "./chain-spec.js";
+
+// Transaction broadcast lifecycle
+export { broadcastTransaction, stopTransaction } from "./chain-transaction.js";

package/src/navigation.ts

@@ -0,0 +1,128 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrapper for the host's deep-link navigation.
+ *
+ * `truApi.system.navigateTo` returns a neverthrow `ResultAsync`; consumers
+ * still have to unwrap it themselves. {@link navigateTo} collapses that to a
+ * `Result<void, HostError>`-returning Promise.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { type HostError, HostUnavailableError } from "./errors.js";
+import { type Result, err } from "./result.js";
+import { getTruApi, mapHostResult } from "./truapi.js";
+
+const log = createLogger("host:navigation");
+
+/**
+ * Ask the host to navigate to a URL (deep link or external link).
+ *
+ * Calls `truApi.system.navigateTo` and unwraps the response. The host resolves
+ * the destination itself — a `dot`-suffixed deep link (e.g.
+ * `"https://search.dot"`) routes to another app/route inside the container, an
+ * `https://` URL opens externally.
+ *
+ * @param url - The URL to navigate to.
+ * @returns `ok` on success, or `err`: {@link HostUnavailableError} if the host
+ *   is unavailable, or {@link HostCallFailedError} if it denies the navigation
+ *   (`NavigateToErr::PermissionDenied`) or fails otherwise (`NavigateToErr::Unknown`).
+ *
+ * @example
+ * ```ts
+ * import { navigateTo } from "@parity/product-sdk-host";
+ *
+ * const r = await navigateTo("https://search.dot");
+ * if (!r.ok) handle(r.error);
+ * ```
+ */
+export async function navigateTo(url: string): Promise<Result<void, HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        return err(new HostUnavailableError("navigateTo: TruAPI unavailable"));
+    }
+    log.debug("navigateTo", { url });
+
+    return mapHostResult(truApi.system.navigateTo({ url }), () => undefined, "navigateTo failed");
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: { system?: { navigateTo?: (req: unknown) => unknown } } | null,
+        fn: (mod: typeof import("./navigation.js")) => Promise<T>,
+    ): Promise<T> {
+        vi.resetModules();
+        vi.doMock("./truapi.js", async (importOriginal) => {
+            const original = await importOriginal<typeof import("./truapi.js")>();
+            return {
+                ...original,
+                getTruApi: async () => bridge,
+            };
+        });
+        try {
+            const mod = await import("./navigation.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    describe("navigateTo", () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                const result = await mod.navigateTo("https://search.dot");
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
+            });
+        });
+
+        test("returns ok on success", async () => {
+            await withMockedTruApi(
+                {
+                    system: {
+                        navigateTo: vi.fn().mockReturnValue({
+                            match: async (onOk: (v: unknown) => unknown) => onOk(undefined),
+                        }),
+                    },
+                },
+                async (mod) => {
+                    expect(await mod.navigateTo("https://search.dot")).toEqual({
+                        ok: true,
+                        value: undefined,
+                    });
+                },
+            );
+        });
+
+        test("wraps host errors in err(HostCallFailedError) with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    system: {
+                        navigateTo: vi.fn().mockReturnValue({
+                            match: async (
+                                _onOk: (v: unknown) => unknown,
+                                onErr: (e: unknown) => unknown,
+                            ) => onErr({ tag: "PermissionDenied" }),
+                        }),
+                    },
+                },
+                async (mod) => {
+                    const result = await mod.navigateTo("https://search.dot");
+                    expect(result.ok).toBe(false);
+                    if (!result.ok) {
+                        expect(result.error.name).toBe("HostCallFailedError");
+                        expect(result.error.message).toMatch(/navigateTo failed: PermissionDenied/);
+                    }
+                },
+            );
+        });
+    });
+}

package/src/notifications.ts

@@ -0,0 +1,113 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Wrapper for the host's scheduled push-notification surface (RFC-0019),
+ * backed by `truApi.notifications.*`.
+ *
+ * `getNotificationManager()` returns a handle exposing `push(input)` (resolves
+ * to a {@link NotificationId}) and `cancel(id)`, matching the singleton
+ * pattern already used by {@link getPaymentManager}, {@link getPreimageManager},
+ * and {@link getHostLocalStorage}.
+ *
+ * @module
+ */
+
+import type { HostPushNotificationRequest, NotificationId, TrUApiClient } from "@parity/truapi";
+
+import { getClient } from "./transport.js";
+import { unwrapHostResult } from "./truapi.js";
+
+/**
+ * Error variants the host raises when scheduling a push notification.
+ *
+ * A `{ tag }` tagged union re-exported from `@parity/truapi`:
+ * `{ tag: "ScheduleLimitReached" }` (the host-wide pending-notification cap) or
+ * `{ tag: "Unknown"; value: { reason } }`. {@link NotificationManager.push} /
+ * {@link NotificationManager.cancel} reject with an `Error` whose `cause`
+ * carries this value, so branch on it — e.g.
+ * `(err as Error).cause?.tag === "ScheduleLimitReached"`.
+ */
+export type { HostPushNotificationError as PushNotificationError } from "@parity/truapi";
+
+/**
+ * Host-assigned id for a scheduled notification — pass to
+ * {@link NotificationManager.cancel}. Re-exported from `@parity/truapi`.
+ */
+export type { NotificationId };
+
+/**
+ * Push payload: `text`, an optional `deeplink`, and an optional `scheduledAt`
+ * (Unix timestamp in milliseconds; omit for immediate delivery). Re-exported
+ * from the truapi wire request type so the shape stays in lockstep with the
+ * protocol.
+ */
+export type PushNotificationInput = HostPushNotificationRequest;
+
+/**
+ * Host notification manager handle. Exposes `push(input)` (resolves to a
+ * {@link NotificationId}) and `cancel(id)`.
+ */
+export interface NotificationManager {
+    push(input: PushNotificationInput): Promise<NotificationId>;
+    cancel(id: NotificationId): Promise<void>;
+}
+
+/** Build a {@link NotificationManager} over a TruAPI client's `notifications` domain. */
+function adaptNotificationManager(client: TrUApiClient): NotificationManager {
+    const notifications = client.notifications;
+    return {
+        async push(input) {
+            const response = await unwrapHostResult(
+                notifications.sendPushNotification(input),
+                "notification push failed",
+            );
+            return response.id;
+        },
+        async cancel(id) {
+            await unwrapHostResult(
+                notifications.cancelPushNotification({ id }),
+                "notification cancel failed",
+            );
+        },
+    };
+}
+
+/**
+ * Get the host notification manager, backed by `truApi.notifications.*`.
+ * Returns `null` when running outside a host container.
+ *
+ * @returns The notification manager, or `null` if unavailable.
+ *
+ * @example
+ * ```ts
+ * import { getNotificationManager, type PushNotificationError } from "@parity/product-sdk-host";
+ *
+ * const notifications = await getNotificationManager();
+ * if (notifications) {
+ *   try {
+ *     const id = await notifications.push({
+ *       text: "Doors open in 1h",
+ *       scheduledAt: someUnixMs,
+ *     });
+ *     // later: await notifications.cancel(id);
+ *   } catch (err) {
+ *     const cause = (err as Error).cause as PushNotificationError | undefined;
+ *     if (cause?.tag === "ScheduleLimitReached") {
+ *       // host hit its pending-notification cap — surface to the user
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export async function getNotificationManager(): Promise<NotificationManager | null> {
+    const client = await getClient();
+    return client ? adaptNotificationManager(client) : null;
+}
+
+if (import.meta.vitest) {
+    const { test, expect } = import.meta.vitest;
+
+    test("getNotificationManager returns null outside a container", async () => {
+        expect(await getNotificationManager()).toBeNull();
+    });
+}