@parity/product-sdk-host 0.10.3 → 0.12.0

package/src/entropy.ts

@@ -3,18 +3,19 @@
 /**
  * Higher-level wrapper for the host's entropy derivation (RFC-0007).
  *
- * `hostApi.deriveEntropy` is reachable via {@link getTruApi}, but consumers
- * have to wrap the value in the versioned envelope (`enumValue("v1", ...)`)
- * and unwrap the neverthrow `ResultAsync` themselves. `deriveEntropy`
- * collapses that to a throw-on-error Promise that matches the shape of
- * {@link requestPermission} and {@link requestResourceAllocation}.
+ * `truApi.entropy.derive` takes a hex `context` and returns a hex `entropy`
+ * payload wrapped in a neverthrow `ResultAsync`. `deriveEntropy` keeps the
+ * ergonomic `Uint8Array → Result<Uint8Array, HostError>` signature: it
+ * hex-encodes the context on the way in and decodes the entropy on the way out.
  *
  * @module
  */
 
 import { createLogger } from "@parity/product-sdk-logger";
 
-import { enumValue, formatHostError, getTruApi } from "./truapi.js";
+import { type HostError, HostUnavailableError } from "./errors.js";
+import { type Result, err } from "./result.js";
+import { fromHex, getTruApi, mapHostResult, toHex } from "./truapi.js";
 
 const log = createLogger("host:entropy");
 
@@ -26,42 +27,79 @@ const log = createLogger("host:entropy");
  * different keys (or different wallets) yield uncorrelated entropy.
  *
  * @param key - Context key bytes (typically a SCALE-encoded discriminator).
- * @returns The derived entropy bytes.
- * @throws If the host is unavailable or the host-side derivation fails.
+ * @returns `ok` with the derived entropy bytes, or
+ *   `err(HostUnavailableError | HostCallFailedError)`.
  *
  * @example
  * ```ts
  * import { deriveEntropy } from "@parity/product-sdk-host";
  *
- * const seed = await deriveEntropy(new TextEncoder().encode("my-app:seed-v1"));
+ * const r = await deriveEntropy(new TextEncoder().encode("my-app:seed-v1"));
+ * if (r.ok) { const seed = r.value; }
  * ```
  */
-export async function deriveEntropy(key: Uint8Array): Promise<Uint8Array> {
+export async function deriveEntropy(key: Uint8Array): Promise<Result<Uint8Array, HostError>> {
     const truApi = await getTruApi();
     if (!truApi) {
-        throw new Error("deriveEntropy: TruAPI unavailable");
+        return err(new HostUnavailableError("deriveEntropy: TruAPI unavailable"));
     }
     log.debug("deriveEntropy", { keyLen: key.length });
 
-    return await truApi.deriveEntropy(enumValue("v1", key)).match(
-        (envelope: { tag: "v1"; value: Uint8Array }) => envelope.value,
-        (err: unknown) => {
-            throw new Error(`deriveEntropy failed: ${formatHostError(err)}`, { cause: err });
-        },
+    return mapHostResult(
+        truApi.entropy.derive({ context: toHex(key) }),
+        (response) => fromHex(response.entropy),
+        "deriveEntropy failed",
     );
 }
 
 if (import.meta.vitest) {
-    const { test, expect } = import.meta.vitest;
+    const { test, expect, describe, vi } = import.meta.vitest;
 
-    test("deriveEntropy throws when TruAPI is unavailable", async () => {
-        const api = await getTruApi();
-        if (api === null) {
-            await expect(deriveEntropy(new Uint8Array([1, 2, 3]))).rejects.toThrow(
-                /TruAPI unavailable/,
-            );
-        } else {
-            expect(typeof deriveEntropy).toBe("function");
+    function okAsync<T>(value: T) {
+        return { match: async (onOk: (v: T) => unknown) => onOk(value) };
+    }
+
+    async function withMockedTruApi<T>(
+        client: unknown,
+        fn: (mod: typeof import("./entropy.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 () => client };
+        });
+        try {
+            const mod = await import("./entropy.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
         }
+    }
+
+    // Tests live inside `describe` so the re-import in `withMockedTruApi`
+    // (via `vi.resetModules`) doesn't re-register top-level `test()` calls.
+    describe("deriveEntropy", () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                const result = await mod.deriveEntropy(new Uint8Array([1, 2, 3]));
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
+            });
+        });
+
+        test("hex-encodes the context and decodes the entropy bytes", async () => {
+            const derive = vi.fn(() => okAsync({ entropy: "0xc0ffee" }));
+            await withMockedTruApi({ entropy: { derive } }, async (mod) => {
+                const result = await mod.deriveEntropy(new Uint8Array([0xab, 0xcd]));
+                expect(derive).toHaveBeenCalledWith({ context: "0xabcd" });
+                expect(result.ok).toBe(true);
+                if (result.ok) {
+                    expect(Array.from(result.value)).toEqual([0xc0, 0xff, 0xee]);
+                }
+            });
+        });
     });
 }

package/src/errors.ts

@@ -0,0 +1,198 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Typed errors carried on the `err` channel of the host public API's
+ * {@link Result} returns.
+ *
+ * The hierarchy mirrors `@parity/product-sdk-signer`'s error classes
+ * (`HostUnavailableError` / `HostRejectedError`), so the two layers share one
+ * idiom: branch with `instanceof`, and every error is a real `Error` with a
+ * stack trace and `cause`. The structured truapi wire error
+ * ({@link HostErrorPayload}) rides along as {@link HostCallFailedError.payload}
+ * for callers that want fine-grained tag-level handling.
+ *
+ * This module also owns {@link HostErrorPayload} (the wire-error shape) and
+ * {@link formatHostError} (renders a payload to a message) — co-located with the
+ * error classes that consume them so the host error model lives in one place.
+ *
+ * @module
+ */
+import type { GenericError } from "@parity/truapi";
+
+/**
+ * The structured error payload `@parity/truapi` surfaces on the `Err` channel of
+ * a host call, once unwrapped from the versioned wire envelope. Every host error
+ * union is built from these:
+ *
+ * - the catch-all {@link GenericError} (`{ reason }`),
+ * - a unit tagged variant (`{ tag }`), or
+ * - a tagged variant carrying a reason (`{ tag, value: { reason } }`).
+ *
+ * `GenericError` is imported from `@parity/truapi`; the `{ tag }` members are a
+ * deliberate widening of truapi's per-domain named variants (the formatter is
+ * tag-agnostic). truapi has no umbrella error union to import today — once it
+ * exports a canonical tagged-error union from codegen, replace these local
+ * members with that import so the type is protocol-sourced rather than
+ * hand-widened.
+ *
+ * This is the *payload* the host public API carries inside a
+ * {@link HostCallFailedError} on the `err` channel of its `Result` returns — not
+ * the error type consumers branch on.
+ */
+export type HostErrorPayload =
+    | GenericError
+    | { tag: string; value?: undefined }
+    | { tag: string; value: { reason: string } };
+
+/** Narrow an unknown `Err`-channel value to a {@link HostErrorPayload}. */
+function isHostErrorPayload(error: unknown): error is HostErrorPayload {
+    if (error == null || typeof error !== "object") return false;
+    const obj = error as Record<string, unknown>;
+    return typeof obj.reason === "string" || typeof obj.tag === "string";
+}
+
+/**
+ * Extract a human-readable message from a host-side error.
+ *
+ * Renders the {@link HostErrorPayload} shapes `@parity/truapi` surfaces. Accepts
+ * `unknown` because it is also the catch-all formatter for thrown adapter-method
+ * `Error` messages, so it falls back to `Error`/string/JSON rendering for
+ * anything that isn't a recognized host error payload.
+ *
+ * Used by {@link HostCallFailedError} to render its message, and by the throwing
+ * adapter-method helper `unwrapHostResult`.
+ */
+export function formatHostError(error: unknown): string {
+    if (error instanceof Error) return error.message;
+    if (typeof error === "string") return error;
+
+    if (isHostErrorPayload(error)) {
+        if ("tag" in error) {
+            // Tagged variant carrying a reason: { tag, value: { reason } }
+            if (error.value != null && typeof error.value.reason === "string") {
+                return `${error.tag}: ${error.value.reason}`;
+            }
+            // Unit tagged variant, e.g. { tag: "Full" } / { tag: "PermissionDenied" }
+            return error.tag;
+        }
+        // GenericError: { reason }
+        return error.reason;
+    }
+
+    if (error != null && typeof error === "object" && "message" in error) {
+        const message = (error as { message: unknown }).message;
+        if (typeof message === "string") return message;
+    }
+
+    try {
+        return JSON.stringify(error);
+    } catch {
+        return String(error);
+    }
+}
+
+/**
+ * Base class for all host errors. Use `instanceof HostError` (or {@link isHostError})
+ * to catch any host-related failure.
+ */
+export class HostError extends Error {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = "HostError";
+    }
+}
+
+/**
+ * The host API is not available — the app is running outside a Polkadot host
+ * container (no injected TruAPI transport). The dominant case during local
+ * development. Branch with `instanceof HostUnavailableError` to surface an
+ * "open this app in a Polkadot host" message.
+ */
+export class HostUnavailableError extends HostError {
+    constructor(message = "Host API is not available") {
+        super(message);
+        this.name = "HostUnavailableError";
+    }
+}
+
+/**
+ * A host call reached the container but failed on the `Err` channel. Wraps the
+ * structured truapi {@link HostErrorPayload} as {@link payload} (also preserved
+ * as `cause`); the message is rendered via {@link formatHostError}.
+ */
+export class HostCallFailedError extends HostError {
+    readonly payload: HostErrorPayload;
+
+    constructor(label: string, payload: HostErrorPayload) {
+        super(`${label}: ${formatHostError(payload)}`, { cause: payload });
+        this.name = "HostCallFailedError";
+        this.payload = payload;
+    }
+}
+
+/** Check whether a value is any {@link HostError}. */
+export function isHostError(error: unknown): error is HostError {
+    return error instanceof HostError;
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe } = import.meta.vitest;
+
+    describe("host error classes", () => {
+        test("HostError is the base class", () => {
+            const e = new HostUnavailableError();
+            expect(e).toBeInstanceOf(HostError);
+            expect(e).toBeInstanceOf(Error);
+        });
+
+        test("HostUnavailableError default message", () => {
+            const e = new HostUnavailableError();
+            expect(e.name).toBe("HostUnavailableError");
+            expect(e.message).toBe("Host API is not available");
+        });
+
+        test("HostUnavailableError custom message", () => {
+            expect(new HostUnavailableError("nope").message).toBe("nope");
+        });
+
+        test("HostCallFailedError renders payload and preserves it", () => {
+            const payload = { tag: "PermissionDenied", value: { reason: "user said no" } };
+            const e = new HostCallFailedError("requestPermission failed", payload);
+            expect(e).toBeInstanceOf(HostError);
+            expect(e.payload).toBe(payload);
+            expect(e.cause).toBe(payload);
+            expect(e.message).toBe("requestPermission failed: PermissionDenied: user said no");
+        });
+
+        test("HostCallFailedError renders a GenericError payload", () => {
+            const e = new HostCallFailedError("submit failed", { reason: "timeout" });
+            expect(e.message).toBe("submit failed: timeout");
+        });
+
+        test("isHostError narrows host errors only", () => {
+            expect(isHostError(new HostUnavailableError())).toBe(true);
+            expect(isHostError(new HostCallFailedError("x", { reason: "y" }))).toBe(true);
+            expect(isHostError(new Error("plain"))).toBe(false);
+            expect(isHostError("string")).toBe(false);
+        });
+    });
+
+    describe("formatHostError", () => {
+        test("renders the TruAPI error payload shapes", () => {
+            // GenericError: { reason }
+            expect(formatHostError({ reason: "boom" })).toBe("boom");
+            // Tagged variant carrying a reason: { tag, value: { reason } }
+            expect(formatHostError({ tag: "Unknown", value: { reason: "boom" } })).toBe(
+                "Unknown: boom",
+            );
+            // Unit tagged variant: { tag }
+            expect(formatHostError({ tag: "Full" })).toBe("Full");
+        });
+
+        test("falls back for non-host-error input", () => {
+            expect(formatHostError(new Error("plain"))).toBe("plain");
+            expect(formatHostError("string err")).toBe("string err");
+            expect(formatHostError({ message: "loose" })).toBe("loose");
+        });
+    });
+}

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

@@ -32,22 +32,14 @@ export type {
 } from "./types.js";
 export { BULLETIN_RPCS, DEFAULT_BULLETIN_ENDPOINT } from "./chains.js";
 
-// TruAPI - re-exports from @novasamatech/host-api-wrapper and @novasamatech/host-api
+// TruAPI - @parity/truapi client accessor + convenience wrappers.
 export {
     getTruApi,
     getPreimageManager,
     createHostPreimageManager,
-    getAccountsProvider,
     requestResourceAllocation,
     createProofAuthorized,
-    formatHostError,
-    // Helpers from @novasamatech/host-api
-    enumValue,
-    isEnumVariant,
-    assertEnumVariant,
-    unwrapResultOrThrow,
-    resultOk,
-    resultErr,
+    // Hex helpers
     toHex,
     fromHex,
 } from "./truapi.js";
@@ -55,19 +47,34 @@ export type {
     TruApi,
     HexString,
     PreimageManager,
-    AccountsProvider,
-    HostAccount,
-    ProductAccount,
-    ContextualAlias,
     ResultAsync,
     AllocatableResource,
-    AllocatableResourceTag,
     AllocationOutcome,
-    AllocationOutcomeTag,
     RemotePermission,
-    RemotePermissionTag,
 } from "./truapi.js";
 
+// Result type + typed host errors (the throw→Result boundary)
+export { ok, err } from "./result.js";
+export type { Result } from "./result.js";
+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 } from "./accounts.js";
+export type {
+    AccountsProvider,
+    HostAccount,
+    ProductAccount,
+    ContextualAlias,
+    RingLocation,
+} from "./accounts.js";
+
 // Higher-level permission wrappers
 export { requestPermission, requestDevicePermission } from "./permissions.js";
 export type { DevicePermissionKind, RemotePermissionItem } from "./permissions.js";
@@ -80,7 +87,7 @@ export type { ThemeMode, ThemeName, ThemeProvider, ThemeVariant } from "./theme.
 export { deriveEntropy } from "./entropy.js";
 
 // Chat
-export { getChatManager, matchChatCustomRenderers } from "./chat.js";
+export { getChatManager } from "./chat.js";
 export type {
     ChatManager,
     ChatMessageContent,
@@ -88,18 +95,36 @@ export type {
     ChatRoom,
     ChatRoomRegistrationResult,
     ChatBotRegistrationResult,
-    ChatCustomMessageRenderer,
-    ChatCustomMessageRendererParams,
 } from "./chat.js";
 
 // Payments (RFC-0006)
 export { getPaymentManager } from "./payments.js";
-export type { PaymentManager, PaymentBalance, PaymentStatus, TopUpSource } from "./payments.js";
+export type { PaymentManager } from "./payments.js";
+export type {
+    HostPaymentBalanceSubscribeItem,
+    HostPaymentStatusSubscribeItem,
+    PaymentTopUpSource,
+} from "@parity/truapi";
 
 // Notifications
-export { getNotificationManager, PushNotificationError } from "./notifications.js";
+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";