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

package/src/chain-transaction.ts

@@ -0,0 +1,241 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrappers for the host's transaction broadcast lifecycle.
+ *
+ * `truApi.chain.broadcastTransaction` / `truApi.chain.stopTransaction` are
+ * reachable via {@link getTruApi}, but consumers have to unwrap the neverthrow
+ * `ResultAsync` themselves. {@link broadcastTransaction} and
+ * {@link stopTransaction} collapse that to `Result`-returning Promises, mirroring
+ * the JSON-RPC `transaction_v1_broadcast` / `transaction_v1_stop` pair they
+ * wrap.
+ *
+ * @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:chain-transaction");
+
+/**
+ * Broadcast a signed transaction to the network via the host.
+ *
+ * Calls `truApi.chain.broadcastTransaction` 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 `ok` with the operation id to pass to {@link stopTransaction} (or
+ *   `null` if the host accepted the broadcast without issuing one), or
+ *   `err(HostUnavailableError | HostCallFailedError)`.
+ *
+ * @example
+ * ```ts
+ * import { broadcastTransaction, stopTransaction } from "@parity/product-sdk-host";
+ *
+ * const r = await broadcastTransaction(genesisHash, signedTx);
+ * // later, to stop re-broadcasting:
+ * if (r.ok && r.value) await stopTransaction(genesisHash, r.value);
+ * ```
+ */
+export async function broadcastTransaction(
+    genesisHash: HexString,
+    transaction: HexString,
+): Promise<Result<string | null, HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        return err(new HostUnavailableError("broadcastTransaction: TruAPI unavailable"));
+    }
+    log.debug("broadcastTransaction", { genesisHash });
+
+    return mapHostResult(
+        truApi.chain.broadcastTransaction({ genesisHash, transaction }),
+        (response) => response.operationId ?? null,
+        "broadcastTransaction failed",
+    );
+}
+
+/**
+ * Stop an in-flight broadcast started by {@link broadcastTransaction}.
+ *
+ * Calls `truApi.chain.stopTransaction` and unwraps the response.
+ *
+ * @param genesisHash - The `0x`-prefixed genesis hash of the target chain.
+ * @param operationId - The operation id returned by
+ *   {@link broadcastTransaction}.
+ * @returns `ok` on success, or `err(HostUnavailableError | HostCallFailedError)`.
+ *
+ * @example
+ * ```ts
+ * await stopTransaction(genesisHash, operationId);
+ * ```
+ */
+export async function stopTransaction(
+    genesisHash: HexString,
+    operationId: string,
+): Promise<Result<void, HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        return err(new HostUnavailableError("stopTransaction: TruAPI unavailable"));
+    }
+    log.debug("stopTransaction", { genesisHash, operationId });
+
+    return mapHostResult(
+        truApi.chain.stopTransaction({ genesisHash, operationId }),
+        () => undefined,
+        "stopTransaction failed",
+    );
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    async function withMockedTruApi<T>(
+        bridge: {
+            chain?: {
+                broadcastTransaction?: (req: unknown) => unknown;
+                stopTransaction?: (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,
+            };
+        });
+        try {
+            const mod = await import("./chain-transaction.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    /** A resolved ResultAsync stub yielding the given response object. */
+    const ok = (response: unknown) => ({
+        match: async (onOk: (v: unknown) => unknown) => onOk(response),
+    });
+    /** A rejected ResultAsync stub yielding a truapi `GenericError` (`{ reason }`). */
+    const errResult = (reason: string) => ({
+        match: async (_onOk: (v: unknown) => unknown, onErr: (e: unknown) => unknown) =>
+            onErr({ reason }),
+    });
+
+    describe("broadcastTransaction", () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                const result = await mod.broadcastTransaction("0x00", "0x01");
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
+            });
+        });
+
+        test("returns ok with the operation id", async () => {
+            await withMockedTruApi(
+                {
+                    chain: {
+                        broadcastTransaction: vi.fn().mockReturnValue(ok({ operationId: "op-1" })),
+                    },
+                },
+                async (mod) => {
+                    expect(await mod.broadcastTransaction("0x00", "0x01")).toEqual({
+                        ok: true,
+                        value: "op-1",
+                    });
+                },
+            );
+        });
+
+        test("passes through a missing operation id as ok(null)", async () => {
+            await withMockedTruApi(
+                {
+                    chain: {
+                        broadcastTransaction: vi.fn().mockReturnValue(ok({})),
+                    },
+                },
+                async (mod) => {
+                    expect(await mod.broadcastTransaction("0x00", "0x01")).toEqual({
+                        ok: true,
+                        value: null,
+                    });
+                },
+            );
+        });
+
+        test("wraps host errors in err(HostCallFailedError) with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    chain: {
+                        broadcastTransaction: vi.fn().mockReturnValue(errResult("boom")),
+                    },
+                },
+                async (mod) => {
+                    const result = await mod.broadcastTransaction("0x00", "0x01");
+                    expect(result.ok).toBe(false);
+                    if (!result.ok) {
+                        expect(result.error.name).toBe("HostCallFailedError");
+                        expect(result.error.message).toMatch(/broadcastTransaction failed: boom/);
+                    }
+                },
+            );
+        });
+    });
+
+    describe("stopTransaction", () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                const result = await mod.stopTransaction("0x00", "op-1");
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
+            });
+        });
+
+        test("returns ok on success", async () => {
+            await withMockedTruApi(
+                {
+                    chain: {
+                        stopTransaction: vi.fn().mockReturnValue(ok(undefined)),
+                    },
+                },
+                async (mod) => {
+                    expect(await mod.stopTransaction("0x00", "op-1")).toEqual({
+                        ok: true,
+                        value: undefined,
+                    });
+                },
+            );
+        });
+
+        test("wraps host errors in err(HostCallFailedError) with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    chain: {
+                        stopTransaction: vi.fn().mockReturnValue(errResult("boom")),
+                    },
+                },
+                async (mod) => {
+                    const result = await mod.stopTransaction("0x00", "op-1");
+                    expect(result.ok).toBe(false);
+                    if (!result.ok) {
+                        expect(result.error.name).toBe("HostCallFailedError");
+                        expect(result.error.message).toMatch(/stopTransaction failed: boom/);
+                    }
+                },
+            );
+        });
+    });
+}

package/src/chains.ts

@@ -0,0 +1,46 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared chain network configuration — single source of truth for
+ * chain-specific endpoints used by multiple packages.
+ */
+
+/**
+ * Bulletin Chain RPC endpoints per network environment. `paseo` (Paseo Next v2)
+ * and `devnet` (public Paseo testnet) are populated today; `polkadot` and
+ * `kusama` are reserved for when those Bulletin deployments go live.
+ */
+export const BULLETIN_RPCS = {
+    paseo: ["wss://paseo-bulletin-next-rpc.polkadot.io"],
+    devnet: ["wss://bulletin-paseo.tservices.es:8443"],
+    polkadot: [] as string[],
+    kusama: [] as string[],
+} as const;
+
+/** Default Bulletin Chain endpoint — the first entry under {@link BULLETIN_RPCS}.paseo. */
+export const DEFAULT_BULLETIN_ENDPOINT: string = BULLETIN_RPCS.paseo[0];
+
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+
+    describe("chains config", () => {
+        test("BULLETIN_RPCS has paseo endpoint", () => {
+            expect(BULLETIN_RPCS.paseo.length).toBeGreaterThan(0);
+            expect(BULLETIN_RPCS.paseo[0]).toMatch(/^wss:\/\//);
+        });
+
+        test("BULLETIN_RPCS has devnet endpoint", () => {
+            expect(BULLETIN_RPCS.devnet.length).toBeGreaterThan(0);
+            expect(BULLETIN_RPCS.devnet[0]).toMatch(/^wss:\/\//);
+        });
+
+        test("BULLETIN_RPCS polkadot and kusama are empty until live", () => {
+            expect(BULLETIN_RPCS.polkadot).toEqual([]);
+            expect(BULLETIN_RPCS.kusama).toEqual([]);
+        });
+
+        test("DEFAULT_BULLETIN_ENDPOINT matches first paseo endpoint", () => {
+            expect(DEFAULT_BULLETIN_ENDPOINT).toBe(BULLETIN_RPCS.paseo[0]);
+        });
+    });
+}

package/src/chat.ts

@@ -0,0 +1,122 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Wrapper for the host's chat surface, backed by `truApi.chat.*`.
+ *
+ * `getChatManager()` returns a manager for room/bot registration, message
+ * sending, and subscription to the room list and incoming actions.
+ *
+ * @module
+ */
+
+import type {
+    ChatBotRegistrationStatus,
+    ChatRoomRegistrationStatus,
+    HostChatActionSubscribeItem,
+    HostChatCreateRoomRequest,
+    HostChatRegisterBotRequest,
+    TrUApiClient,
+} from "@parity/truapi";
+
+import { getClient, subscribeWithInterrupt } from "./transport.js";
+import { unwrapHostResult } from "./truapi.js";
+import type { HostSubscription } from "./types.js";
+
+/** Chat message payload variants and room metadata. Re-exported from `@parity/truapi`. */
+export type { ChatMessageContent, ChatRoom } from "@parity/truapi";
+import type { ChatMessageContent, ChatRoom } from "@parity/truapi";
+
+/** Action received via {@link ChatManager.subscribeAction} (`{ roomId, peer, payload }`). Re-exported from `@parity/truapi`. */
+export type ChatReceivedAction = HostChatActionSubscribeItem;
+
+/** Result of registering a chat room (`"New" | "Exists"`). Re-exported from `@parity/truapi`. */
+export type ChatRoomRegistrationResult = ChatRoomRegistrationStatus;
+
+/** Result of registering a bot (`"New" | "Exists"`). Re-exported from `@parity/truapi`. */
+export type ChatBotRegistrationResult = ChatBotRegistrationStatus;
+
+/**
+ * Chat manager handle. Exposes room/bot registration, message sending, and
+ * subscription to the room list and incoming actions.
+ */
+export interface ChatManager {
+    registerRoom(request: HostChatCreateRoomRequest): Promise<ChatRoomRegistrationResult>;
+    registerBot(request: HostChatRegisterBotRequest): Promise<ChatBotRegistrationResult>;
+    sendMessage(roomId: string, payload: ChatMessageContent): Promise<{ messageId: string }>;
+    subscribeChatList(callback: (rooms: ChatRoom[]) => void): HostSubscription;
+    subscribeAction(callback: (action: ChatReceivedAction) => void): HostSubscription;
+}
+
+/** Build a {@link ChatManager} over a TruAPI client's `chat` domain. */
+function adaptChatManager(client: TrUApiClient): ChatManager {
+    const chat = client.chat;
+    // Cache registration status by id so repeat calls don't re-prompt the host.
+    const roomStatus = new Map<string, ChatRoomRegistrationResult>();
+    const botStatus = new Map<string, ChatBotRegistrationResult>();
+
+    return {
+        async registerRoom(request) {
+            const cached = roomStatus.get(request.roomId);
+            if (cached) return cached;
+            const response = await unwrapHostResult(
+                chat.createRoom(request),
+                "chat registerRoom failed",
+            );
+            roomStatus.set(request.roomId, response.status);
+            return response.status;
+        },
+        async registerBot(request) {
+            const cached = botStatus.get(request.botId);
+            if (cached) return cached;
+            const response = await unwrapHostResult(
+                chat.registerBot(request),
+                "chat registerBot failed",
+            );
+            botStatus.set(request.botId, response.status);
+            return response.status;
+        },
+        async sendMessage(roomId, payload) {
+            const response = await unwrapHostResult(
+                chat.postMessage({ roomId, payload }),
+                "chat sendMessage failed",
+            );
+            return { messageId: response.messageId };
+        },
+        subscribeChatList(callback) {
+            return subscribeWithInterrupt(chat.listSubscribe(), (item) => callback(item.rooms));
+        },
+        subscribeAction(callback) {
+            return subscribeWithInterrupt(chat.actionSubscribe(), callback);
+        },
+    };
+}
+
+/**
+ * Get the host chat manager, backed by `truApi.chat.*`. Returns `null` when
+ * running outside a host container.
+ *
+ * @returns The chat manager, or `null` if unavailable.
+ *
+ * @example
+ * ```ts
+ * import { getChatManager } from "@parity/product-sdk-host";
+ *
+ * const chat = await getChatManager();
+ * if (chat) {
+ *   await chat.registerBot({ botId: "echo", name: "Echo Bot", icon: "" });
+ *   chat.subscribeAction((action) => { ... });
+ * }
+ * ```
+ */
+export async function getChatManager(): Promise<ChatManager | null> {
+    const client = await getClient();
+    return client ? adaptChatManager(client) : null;
+}
+
+if (import.meta.vitest) {
+    const { test, expect } = import.meta.vitest;
+
+    test("getChatManager returns null outside a container", async () => {
+        expect(await getChatManager()).toBeNull();
+    });
+}