@parity/product-sdk-host 0.10.3 → 0.11.0

package/src/chain-spec.ts

@@ -0,0 +1,230 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrapper for the host's chain-spec lookups.
+ *
+ * The host exposes three separate chain-spec calls — `chainSpecGenesisHash`,
+ * `chainSpecChainName`, and `chainSpecProperties` — each reachable via
+ * {@link getTruApi} but each requiring its own `enumValue("v1", ...)` wrap
+ * and neverthrow `ResultAsync` unwrap. {@link getChainSpec} fetches all three
+ * in one call and returns a single struct so callers read whichever field
+ * they need, matching the JSON-RPC `chainSpec_v1_*` family they mirror.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { enumValue, formatHostError, getTruApi, type HexString } from "./truapi.js";
+
+const log = createLogger("host:chain-spec");
+
+/**
+ * Chain SS58/token properties as reported by the host's
+ * `chainSpecProperties` call.
+ *
+ * The host returns this as a JSON string (mirroring the substrate
+ * `chainSpec_v1_properties` JSON-RPC, whose payload is an open-ended object).
+ * {@link getChainSpec} parses it into {@link properties} and also surfaces the
+ * untouched JSON as {@link propertiesRaw}. The well-known substrate fields are
+ * typed for convenience; the index signature keeps any chain-specific extras
+ * reachable without `any` at the call site.
+ */
+export interface ChainProperties {
+    /** Address prefix used for SS58 encoding (e.g. `0` for Polkadot). */
+    ss58Format?: number;
+    /** Decimal places of the chain's native token(s). */
+    tokenDecimals?: number | number[];
+    /** Ticker symbol(s) of the chain's native token(s). */
+    tokenSymbol?: string | string[];
+    /** Chain-specific extras passed through verbatim from the JSON payload. */
+    [key: string]: unknown;
+}
+
+/**
+ * Combined chain-spec view returned by {@link getChainSpec}.
+ */
+export interface ChainSpec {
+    /** The chain's `0x`-prefixed genesis hash, as reported by the host. */
+    genesisHash: HexString;
+    /** Human-readable chain name (e.g. `"Polkadot"`). */
+    name: string;
+    /**
+     * Parsed chain properties, or `null` if the host's JSON payload couldn't
+     * be parsed. Inspect {@link propertiesRaw} for the original string.
+     */
+    properties: ChainProperties | null;
+    /** The untouched JSON string the host returned for properties. */
+    propertiesRaw: string;
+}
+
+/**
+ * Fetch a chain's full spec (genesis hash, name, and properties) from the host
+ * in one call.
+ *
+ * Issues the three underlying `chainSpec*` requests concurrently, unwraps each
+ * `v1` envelope, and parses the properties JSON. Note the `genesisHash` in the
+ * result is the value the host echoes back from `chainSpecGenesisHash` for the
+ * looked-up chain — pass the chain's known genesis hash as the lookup key.
+ *
+ * @param genesisHash - The `0x`-prefixed genesis hash identifying the chain.
+ * @returns The combined {@link ChainSpec}, or `null` if the host is
+ *   unavailable (running outside a container).
+ * @throws If any of the underlying host calls fail (`GenericError`).
+ *
+ * @example
+ * ```ts
+ * import { getChainSpec } from "@parity/product-sdk-host";
+ *
+ * const spec = await getChainSpec(genesisHash);
+ * if (spec) {
+ *   console.log(spec.name, spec.properties?.tokenSymbol);
+ * }
+ * ```
+ */
+export async function getChainSpec(genesisHash: HexString): Promise<ChainSpec | null> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        log.debug("getChainSpec: TruAPI unavailable");
+        return null;
+    }
+    log.debug("getChainSpec", { genesisHash });
+
+    // `.match()` because the host returns neverthrow ResultAsync values, not Promises.
+    const [resolvedGenesisHash, name, propertiesRaw] = await Promise.all([
+        truApi.chainSpecGenesisHash(enumValue("v1", genesisHash)).match(
+            (envelope: { tag: "v1"; value: HexString }) => envelope.value,
+            (err: unknown) => {
+                throw new Error(`getChainSpec (genesisHash) failed: ${formatHostError(err)}`, {
+                    cause: err,
+                });
+            },
+        ),
+        truApi.chainSpecChainName(enumValue("v1", genesisHash)).match(
+            (envelope: { tag: "v1"; value: string }) => envelope.value,
+            (err: unknown) => {
+                throw new Error(`getChainSpec (chainName) failed: ${formatHostError(err)}`, {
+                    cause: err,
+                });
+            },
+        ),
+        truApi.chainSpecProperties(enumValue("v1", genesisHash)).match(
+            (envelope: { tag: "v1"; value: string }) => envelope.value,
+            (err: unknown) => {
+                throw new Error(`getChainSpec (properties) failed: ${formatHostError(err)}`, {
+                    cause: err,
+                });
+            },
+        ),
+    ]);
+
+    let properties: ChainProperties | null;
+    try {
+        properties = JSON.parse(propertiesRaw) as ChainProperties;
+    } catch (err) {
+        log.debug("getChainSpec: properties JSON parse failed", err);
+        properties = null;
+    }
+
+    return { genesisHash: resolvedGenesisHash, name, properties, propertiesRaw };
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: {
+            chainSpecGenesisHash?: (req: unknown) => unknown;
+            chainSpecChainName?: (req: unknown) => unknown;
+            chainSpecProperties?: (req: unknown) => unknown;
+        } | null,
+        fn: (mod: typeof import("./chain-spec.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,
+                enumValue: (version: string, value: unknown) => ({ tag: version, value }),
+            };
+        });
+        try {
+            const mod = await import("./chain-spec.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    const ok = (value: unknown) => ({
+        match: async (onOk: (v: unknown) => unknown) => onOk({ tag: "v1", value }),
+    });
+
+    describe("getChainSpec", () => {
+        test("returns null when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                expect(await mod.getChainSpec("0x00")).toBeNull();
+            });
+        });
+
+        test("combines the three calls and parses properties JSON", async () => {
+            await withMockedTruApi(
+                {
+                    chainSpecGenesisHash: vi.fn().mockReturnValue(ok("0xabcd")),
+                    chainSpecChainName: vi.fn().mockReturnValue(ok("Polkadot")),
+                    chainSpecProperties: vi
+                        .fn()
+                        .mockReturnValue(
+                            ok('{"ss58Format":0,"tokenDecimals":10,"tokenSymbol":"DOT"}'),
+                        ),
+                },
+                async (mod) => {
+                    const spec = await mod.getChainSpec("0xabcd");
+                    expect(spec).toEqual({
+                        genesisHash: "0xabcd",
+                        name: "Polkadot",
+                        properties: { ss58Format: 0, tokenDecimals: 10, tokenSymbol: "DOT" },
+                        propertiesRaw: '{"ss58Format":0,"tokenDecimals":10,"tokenSymbol":"DOT"}',
+                    });
+                },
+            );
+        });
+
+        test("leaves properties null when the JSON is malformed", async () => {
+            await withMockedTruApi(
+                {
+                    chainSpecGenesisHash: vi.fn().mockReturnValue(ok("0xabcd")),
+                    chainSpecChainName: vi.fn().mockReturnValue(ok("Polkadot")),
+                    chainSpecProperties: vi.fn().mockReturnValue(ok("not json")),
+                },
+                async (mod) => {
+                    const spec = await mod.getChainSpec("0xabcd");
+                    expect(spec?.properties).toBeNull();
+                    expect(spec?.propertiesRaw).toBe("not json");
+                },
+            );
+        });
+
+        test("wraps host errors with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    chainSpecGenesisHash: vi.fn().mockReturnValue({
+                        match: async (
+                            _onOk: (v: unknown) => unknown,
+                            onErr: (e: unknown) => unknown,
+                        ) => onErr({ tag: "v1", value: { name: "GenericError", message: "boom" } }),
+                    }),
+                    chainSpecChainName: vi.fn().mockReturnValue(ok("Polkadot")),
+                    chainSpecProperties: vi.fn().mockReturnValue(ok("{}")),
+                },
+                async (mod) => {
+                    await expect(mod.getChainSpec("0xabcd")).rejects.toThrow(
+                        /getChainSpec \(genesisHash\) failed: GenericError: boom/,
+                    );
+                },
+            );
+        });
+    });
+}

package/src/chain-transaction.ts

@@ -0,0 +1,212 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrappers for the host's transaction broadcast lifecycle.
+ *
+ * `hostApi.chainTransactionBroadcast` / `hostApi.chainTransactionStop` are
+ * reachable via {@link getTruApi}, but consumers have to build the versioned
+ * envelope (`enumValue("v1", ...)`) and unwrap the neverthrow `ResultAsync`
+ * themselves. {@link broadcastTransaction} and {@link stopTransaction}
+ * collapse that to throw-on-error Promises, mirroring the JSON-RPC
+ * `transaction_v1_broadcast` / `transaction_v1_stop` pair they wrap.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { enumValue, formatHostError, getTruApi, type HexString } from "./truapi.js";
+
+const log = createLogger("host:chain-transaction");
+
+/**
+ * Broadcast a signed transaction to the network via the host.
+ *
+ * Builds the `v1` envelope, calls `hostApi.chainTransactionBroadcast`, and
+ * unwraps the response. The host keeps re-broadcasting until the transaction
+ * is finalized/dropped or {@link stopTransaction} is called with the returned
+ * operation id.
+ *
+ * @param genesisHash - The `0x`-prefixed genesis hash of the target chain.
+ * @param transaction - The `0x`-prefixed SCALE-encoded signed transaction.
+ * @returns The operation id to pass to {@link stopTransaction}, or `null` if
+ *   the host accepted the broadcast without issuing one.
+ * @throws If the host is unavailable or the broadcast fails (`GenericError`).
+ *
+ * @example
+ * ```ts
+ * import { broadcastTransaction, stopTransaction } from "@parity/product-sdk-host";
+ *
+ * const operationId = await broadcastTransaction(genesisHash, signedTx);
+ * // later, to stop re-broadcasting:
+ * if (operationId) await stopTransaction(genesisHash, operationId);
+ * ```
+ */
+export async function broadcastTransaction(
+    genesisHash: HexString,
+    transaction: HexString,
+): Promise<string | null> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        throw new Error("broadcastTransaction: TruAPI unavailable");
+    }
+    log.debug("broadcastTransaction", { genesisHash });
+
+    // `.match()` because the host returns a neverthrow ResultAsync, not a Promise.
+    return await truApi
+        .chainTransactionBroadcast(enumValue("v1", { genesisHash, transaction }))
+        .match(
+            (envelope: { tag: "v1"; value: string | null }) => envelope.value,
+            (err: unknown) => {
+                throw new Error(`broadcastTransaction failed: ${formatHostError(err)}`, {
+                    cause: err,
+                });
+            },
+        );
+}
+
+/**
+ * Stop an in-flight broadcast started by {@link broadcastTransaction}.
+ *
+ * Builds the `v1` envelope, calls `hostApi.chainTransactionStop`, and unwraps
+ * the response.
+ *
+ * @param genesisHash - The `0x`-prefixed genesis hash of the target chain.
+ * @param operationId - The operation id returned by
+ *   {@link broadcastTransaction}.
+ * @throws If the host is unavailable or the stop fails (`GenericError`).
+ *
+ * @example
+ * ```ts
+ * await stopTransaction(genesisHash, operationId);
+ * ```
+ */
+export async function stopTransaction(genesisHash: HexString, operationId: string): Promise<void> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        throw new Error("stopTransaction: TruAPI unavailable");
+    }
+    log.debug("stopTransaction", { genesisHash, operationId });
+
+    // `.match()` because the host returns a neverthrow ResultAsync, not a Promise.
+    await truApi.chainTransactionStop(enumValue("v1", { genesisHash, operationId })).match(
+        (_envelope: { tag: "v1"; value: undefined }) => undefined,
+        (err: unknown) => {
+            throw new Error(`stopTransaction failed: ${formatHostError(err)}`, { cause: err });
+        },
+    );
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: {
+            chainTransactionBroadcast?: (req: unknown) => unknown;
+            chainTransactionStop?: (req: unknown) => unknown;
+        } | null,
+        fn: (mod: typeof import("./chain-transaction.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,
+                enumValue: (version: string, value: unknown) => ({ tag: version, value }),
+            };
+        });
+        try {
+            const mod = await import("./chain-transaction.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    const ok = (value: unknown) => ({
+        match: async (onOk: (v: unknown) => unknown) => onOk({ tag: "v1", value }),
+    });
+    const errResult = (name: string, message: string) => ({
+        match: async (_onOk: (v: unknown) => unknown, onErr: (e: unknown) => unknown) =>
+            onErr({ tag: "v1", value: { name, message } }),
+    });
+
+    describe("broadcastTransaction", () => {
+        test("throws when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                await expect(mod.broadcastTransaction("0x00", "0x01")).rejects.toThrow(
+                    /TruAPI unavailable/,
+                );
+            });
+        });
+
+        test("unwraps the operation id", async () => {
+            await withMockedTruApi(
+                { chainTransactionBroadcast: vi.fn().mockReturnValue(ok("op-1")) },
+                async (mod) => {
+                    expect(await mod.broadcastTransaction("0x00", "0x01")).toBe("op-1");
+                },
+            );
+        });
+
+        test("passes through a null operation id", async () => {
+            await withMockedTruApi(
+                { chainTransactionBroadcast: vi.fn().mockReturnValue(ok(null)) },
+                async (mod) => {
+                    expect(await mod.broadcastTransaction("0x00", "0x01")).toBeNull();
+                },
+            );
+        });
+
+        test("wraps host errors with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    chainTransactionBroadcast: vi
+                        .fn()
+                        .mockReturnValue(errResult("GenericError", "boom")),
+                },
+                async (mod) => {
+                    await expect(mod.broadcastTransaction("0x00", "0x01")).rejects.toThrow(
+                        /broadcastTransaction failed: GenericError: boom/,
+                    );
+                },
+            );
+        });
+    });
+
+    describe("stopTransaction", () => {
+        test("throws when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                await expect(mod.stopTransaction("0x00", "op-1")).rejects.toThrow(
+                    /TruAPI unavailable/,
+                );
+            });
+        });
+
+        test("resolves on the v1 success envelope", async () => {
+            await withMockedTruApi(
+                { chainTransactionStop: vi.fn().mockReturnValue(ok(undefined)) },
+                async (mod) => {
+                    await expect(mod.stopTransaction("0x00", "op-1")).resolves.toBeUndefined();
+                },
+            );
+        });
+
+        test("wraps host errors with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    chainTransactionStop: vi
+                        .fn()
+                        .mockReturnValue(errResult("GenericError", "boom")),
+                },
+                async (mod) => {
+                    await expect(mod.stopTransaction("0x00", "op-1")).rejects.toThrow(
+                        /stopTransaction failed: GenericError: boom/,
+                    );
+                },
+            );
+        });
+    });
+}

package/src/features.ts

@@ -0,0 +1,161 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrappers for the host's feature-support probe.
+ *
+ * `hostApi.featureSupported` is reachable via {@link getTruApi}, but consumers
+ * have to wrap the feature in the versioned envelope (`enumValue("v1", ...)`)
+ * and unwrap the neverthrow `ResultAsync` themselves. {@link featureSupported}
+ * collapses that to a throw-on-error Promise; {@link isChainSupported} is a
+ * convenience over the only feature variant the host exposes today (`Chain`).
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { enumValue, formatHostError, getTruApi, type HexString } from "./truapi.js";
+
+const log = createLogger("host:features");
+
+/**
+ * A feature the host can be probed for via {@link featureSupported}.
+ *
+ * As of `host-api` v0.8 the only variant is `Chain`, carrying the chain's
+ * `0x`-prefixed genesis hash. Modeled locally (rather than derived from an
+ * upstream codec) because the protocol exposes the feature only inline; 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.
+ *
+ * Builds the `v1` envelope, calls `hostApi.featureSupported`, unwraps the
+ * response, and returns the host's boolean answer.
+ *
+ * @param feature - The feature to probe for.
+ * @returns `true` if the host supports the feature, `false` otherwise.
+ * @throws If the host is unavailable or the probe fails (`GenericError`).
+ *
+ * @example
+ * ```ts
+ * import { featureSupported } from "@parity/product-sdk-host";
+ *
+ * const ok = await featureSupported({ tag: "Chain", value: genesisHash });
+ * ```
+ */
+export async function featureSupported(feature: Feature): Promise<boolean> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        throw new Error("featureSupported: TruAPI unavailable");
+    }
+    log.debug("featureSupported", { tag: feature.tag });
+
+    // `.match()` because the host returns a neverthrow ResultAsync, not a Promise.
+    return await truApi.featureSupported(enumValue("v1", feature)).match(
+        (envelope: { tag: "v1"; value: boolean }) => envelope.value,
+        (err: unknown) => {
+            throw new Error(`featureSupported failed: ${formatHostError(err)}`, { cause: err });
+        },
+    );
+}
+
+/**
+ * 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 `true` if the host supports the chain, `false` otherwise.
+ * @throws If the host is unavailable or the probe fails.
+ *
+ * @example
+ * ```ts
+ * import { isChainSupported } from "@parity/product-sdk-host";
+ *
+ * if (!(await isChainSupported(genesisHash))) {
+ *   tellUserChainUnavailable();
+ * }
+ * ```
+ */
+export async function isChainSupported(genesisHash: HexString): Promise<boolean> {
+    return await featureSupported({ tag: "Chain", value: genesisHash });
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: { 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,
+                enumValue: (version: string, value: unknown) => ({ tag: version, value }),
+            };
+        });
+        try {
+            const mod = await import("./features.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    const okBridge = (value: boolean) => ({
+        featureSupported: vi.fn().mockReturnValue({
+            match: async (onOk: (v: unknown) => unknown) => onOk({ tag: "v1", value }),
+        }),
+    });
+
+    describe("featureSupported", () => {
+        test("throws when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                await expect(mod.featureSupported({ tag: "Chain", value: "0x00" })).rejects.toThrow(
+                    /TruAPI unavailable/,
+                );
+            });
+        });
+
+        test("unwraps the v1 boolean outcome", async () => {
+            await withMockedTruApi(okBridge(true), async (mod) => {
+                expect(await mod.featureSupported({ tag: "Chain", value: "0x00" })).toBe(true);
+            });
+        });
+
+        test("wraps host errors with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    featureSupported: vi.fn().mockReturnValue({
+                        match: async (
+                            _onOk: (v: unknown) => unknown,
+                            onErr: (e: unknown) => unknown,
+                        ) =>
+                            onErr({
+                                tag: "v1",
+                                value: { name: "GenericError", message: "boom" },
+                            }),
+                    }),
+                },
+                async (mod) => {
+                    await expect(
+                        mod.featureSupported({ tag: "Chain", value: "0x00" }),
+                    ).rejects.toThrow(/featureSupported failed: GenericError: boom/);
+                },
+            );
+        });
+    });
+
+    describe("isChainSupported", () => {
+        test("delegates to featureSupported with the Chain variant", async () => {
+            await withMockedTruApi(okBridge(false), async (mod) => {
+                expect(await mod.isChainSupported("0x1234")).toBe(false);
+            });
+        });
+    });
+}

package/src/index.ts

@@ -103,3 +103,17 @@ export type {
     NotificationId,
     PushNotificationInput,
 } 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";