@parity/product-sdk-host 0.4.0 → 0.6.0

package/src/chat.ts

@@ -0,0 +1,126 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Wrapper for the host's chat surface (`host_chat_*` family).
+ *
+ * Shipped flat-in-host rather than as `getTruApi().chat.*` (the shape
+ * sketched in issue #93) because the upstream JS `hostApi` is itself a
+ * flat object - there is no `.chat` accessor to mirror. A flat
+ * `getChatManager()` matches the pattern already used by
+ * {@link getThemeProvider}, {@link getAccountsProvider}, and
+ * {@link getStatementStore}; if a namespaced view is desirable later, it
+ * can be layered on top without breaking this surface.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import type {
+    ChatBotRegistrationResult as NovasamaChatBotRegistrationResult,
+    ChatCustomMessageRenderer as NovasamaChatCustomMessageRenderer,
+    ChatCustomMessageRendererParams as NovasamaChatCustomMessageRendererParams,
+    ChatMessageContent as NovasamaChatMessageContent,
+    ChatReceivedAction as NovasamaChatReceivedAction,
+    ChatRoom as NovasamaChatRoom,
+    ChatRoomRegistrationResult as NovasamaChatRoomRegistrationResult,
+    createProductChatManager,
+} from "@novasamatech/host-api-wrapper";
+
+const log = createLogger("host:chat");
+
+/** Chat message payload variants. Re-exported from `@novasamatech/host-api-wrapper`. */
+export type ChatMessageContent = NovasamaChatMessageContent;
+
+/** Action received via {@link ChatManager.subscribeAction}. Re-exported from `@novasamatech/host-api-wrapper`. */
+export type ChatReceivedAction = NovasamaChatReceivedAction;
+
+/** Room metadata delivered to {@link ChatManager.subscribeChatList}. Re-exported from `@novasamatech/host-api-wrapper`. */
+export type ChatRoom = NovasamaChatRoom;
+
+/** Result of registering a chat room (`"New" | "Exists"`). Re-exported from `@novasamatech/host-api-wrapper`. */
+export type ChatRoomRegistrationResult = NovasamaChatRoomRegistrationResult;
+
+/** Result of registering a bot (`"New" | "Exists"`). Re-exported from `@novasamatech/host-api-wrapper`. */
+export type ChatBotRegistrationResult = NovasamaChatBotRegistrationResult;
+
+/** Renderer callback for custom message types. Re-exported from `@novasamatech/host-api-wrapper`. */
+export type ChatCustomMessageRenderer = NovasamaChatCustomMessageRenderer;
+
+/** Parameters passed to a {@link ChatCustomMessageRenderer}. Re-exported from `@novasamatech/host-api-wrapper`. */
+export type ChatCustomMessageRendererParams<T = Uint8Array> =
+    NovasamaChatCustomMessageRendererParams<T>;
+
+/**
+ * Chat manager handle. Exposes room/bot registration, message sending,
+ * subscription to room list and incoming actions, and custom-renderer
+ * registration.
+ *
+ * Type identical to `createProductChatManager()` from
+ * `@novasamatech/host-api-wrapper`.
+ */
+export type ChatManager = ReturnType<typeof createProductChatManager>;
+
+/**
+ * Get the host chat manager.
+ *
+ * Returns the chat manager from `@novasamatech/host-api-wrapper`, or `null` if
+ * the package is unavailable (running outside a host container or the
+ * optional peer dep isn't installed).
+ *
+ * @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> {
+    try {
+        const sdk = await import("@novasamatech/host-api-wrapper");
+        return sdk.createProductChatManager();
+    } catch (err) {
+        log.debug("getChatManager unavailable", err);
+        return null;
+    }
+}
+
+/**
+ * Dispatch helper that composes multiple custom-message renderers into a
+ * single {@link ChatCustomMessageRenderer} keyed by `messageType`.
+ *
+ * Mirrors `matchChatCustomRenderers` from `@novasamatech/host-api-wrapper`
+ * inline (the upstream implementation is pure dispatch logic with no
+ * transport / runtime dependency on Novasama), so callers get the same
+ * sync signature instead of an async-with-null wrapper.
+ *
+ * @param map - Object mapping `messageType` strings to renderers.
+ * @returns A composed renderer that dispatches to the entry matching
+ *          `params.messageType`, or throws if no renderer is registered.
+ */
+export function matchChatCustomRenderers(
+    map: Record<string, ChatCustomMessageRenderer>,
+): ChatCustomMessageRenderer {
+    return (params, render) => {
+        const renderer = map[params.messageType];
+        if (!renderer) {
+            throw new Error(`Renderer for message type ${params.messageType} is not defined`);
+        }
+        return renderer(params, render);
+    };
+}
+
+if (import.meta.vitest) {
+    const { test, expect } = import.meta.vitest;
+
+    test("getChatManager returns manager when SDK is available", async () => {
+        const chat = await getChatManager();
+        expect(chat === null || typeof chat === "object").toBe(true);
+    });
+}

package/src/container.ts

@@ -1,7 +1,13 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
 import type { JsonRpcProvider } from "polkadot-api";
+import { createLogger } from "@parity/product-sdk-logger";
+import type { Transport } from "@novasamatech/host-api";
 
 import type { HostLocalStorage, HostStatementStore } from "./types.js";
 
+const log = createLogger("host:container");
+
 /**
  * Detect if running inside a Host container (Polkadot Browser / Polkadot Desktop).
  *
@@ -15,7 +21,7 @@ export async function isInsideContainer(): Promise<boolean> {
     if (typeof window === "undefined") return false;
 
     try {
-        const sdk = await import("@novasamatech/product-sdk");
+        const sdk = await import("@novasamatech/host-api-wrapper");
         return sdk.sandboxProvider.isCorrectEnvironment();
     } catch {
         return isInsideContainerSync();
@@ -30,9 +36,35 @@ export async function getHostLocalStorage(): Promise<HostLocalStorage | null> {
     if (!(await isInsideContainer())) return null;
 
     try {
-        const sdk = await import("@novasamatech/product-sdk");
+        const sdk = await import("@novasamatech/host-api-wrapper");
         return sdk.hostLocalStorage as HostLocalStorage;
-    } catch {
+    } catch (err) {
+        log.debug("getHostLocalStorage unavailable", err);
+        return null;
+    }
+}
+
+/**
+ * Construct a fresh host-backed `HostLocalStorage` instance with an optional
+ * custom transport. Use this when you need a non-default transport (e.g.
+ * for tests); otherwise prefer {@link getHostLocalStorage}, which returns
+ * the shared singleton.
+ *
+ * Mirrors `createLocalStorage` from `@novasamatech/host-api-wrapper`.
+ *
+ * @param transport - Optional transport; defaults to the sandbox transport.
+ * @returns A new `HostLocalStorage` instance, or `null` if unavailable.
+ */
+export async function createHostLocalStorage(
+    transport?: Transport,
+): Promise<HostLocalStorage | null> {
+    if (!(await isInsideContainer())) return null;
+
+    try {
+        const sdk = await import("@novasamatech/host-api-wrapper");
+        return sdk.createLocalStorage(transport);
+    } catch (err) {
+        log.debug("createHostLocalStorage unavailable", err);
         return null;
     }
 }
@@ -42,16 +74,17 @@ export async function getHostLocalStorage(): Promise<HostLocalStorage | null> {
  *
  * When running inside a Polkadot container, this wraps the chain connection via the
  * host's `createPapiProvider`, enabling shared connections and efficient routing.
- * Returns `null` when `@novasamatech/product-sdk` is unavailable.
+ * Returns `null` when `@novasamatech/host-api-wrapper` is unavailable.
  *
  * @param genesisHash - Genesis hash of the target chain (`0x`-prefixed hex string).
  * @returns A host-routed `JsonRpcProvider`, or `null` if unavailable.
  */
 export async function getHostProvider(genesisHash: `0x${string}`): Promise<JsonRpcProvider | null> {
     try {
-        const sdk = await import("@novasamatech/product-sdk");
+        const sdk = await import("@novasamatech/host-api-wrapper");
         return sdk.createPapiProvider(genesisHash);
-    } catch {
+    } catch (err) {
+        log.debug("getHostProvider unavailable", err);
         return null;
     }
 }
@@ -90,15 +123,16 @@ export function isInsideContainerSync(): boolean {
  *
  * Returns a statement store with `subscribe`, `createProof`, and `submit` methods
  * that communicate through the host's native binary protocol — bypassing JSON-RPC
- * entirely. Returns `null` when `@novasamatech/product-sdk` is unavailable.
+ * entirely. Returns `null` when `@novasamatech/host-api-wrapper` is unavailable.
  *
  * @returns The host statement store, or `null` if unavailable.
  */
 export async function getStatementStore(): Promise<HostStatementStore | null> {
     try {
-        const sdk = await import("@novasamatech/product-sdk");
+        const sdk = await import("@novasamatech/host-api-wrapper");
         return sdk.createStatementStore() as HostStatementStore;
-    } catch {
+    } catch (err) {
+        log.debug("getStatementStore unavailable", err);
         return null;
     }
 }
@@ -166,6 +200,10 @@ if (import.meta.vitest) {
         expect(await getHostLocalStorage()).toBeNull();
     });
 
+    test("createHostLocalStorage returns null outside container", async () => {
+        expect(await createHostLocalStorage()).toBeNull();
+    });
+
     test("getHostProvider returns null when product-sdk unavailable", async () => {
         const result = await getHostProvider("0xabc");
         expect(result).toBeNull();

package/src/entropy.ts

@@ -0,0 +1,67 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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}.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { enumValue, formatHostError, getTruApi } from "./truapi.js";
+
+const log = createLogger("host:entropy");
+
+/**
+ * Derive deterministic entropy from a context key (RFC-0007).
+ *
+ * The host derives entropy from the user's wallet + the provided context
+ * key. Calling with the same key on the same wallet yields the same bytes;
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { deriveEntropy } from "@parity/product-sdk-host";
+ *
+ * const seed = await deriveEntropy(new TextEncoder().encode("my-app:seed-v1"));
+ * ```
+ */
+export async function deriveEntropy(key: Uint8Array): Promise<Uint8Array> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        throw new Error("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 });
+        },
+    );
+}
+
+if (import.meta.vitest) {
+    const { test, expect } = 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");
+        }
+    });
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+// 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.
  *
@@ -11,6 +13,7 @@ export {
     isInsideContainer,
     isInsideContainerSync,
     getHostLocalStorage,
+    createHostLocalStorage,
     getHostProvider,
     getStatementStore,
 } from "./container.js";
@@ -18,19 +21,25 @@ 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 - re-exports from @novasamatech/product-sdk and @novasamatech/host-api
+// TruAPI - re-exports from @novasamatech/host-api-wrapper and @novasamatech/host-api
 export {
     getTruApi,
     getPreimageManager,
+    createHostPreimageManager,
     getAccountsProvider,
     requestResourceAllocation,
     createProofAuthorized,
+    formatHostError,
     // Helpers from @novasamatech/host-api
     enumValue,
     isEnumVariant,
@@ -56,8 +65,32 @@ export type {
     AllocationOutcomeTag,
     RemotePermission,
     RemotePermissionTag,
-    Statement,
 } from "./truapi.js";
 
-// Higher-level permission wrapper
-export { requestPermission } from "./permissions.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, matchChatCustomRenderers } from "./chat.js";
+export type {
+    ChatManager,
+    ChatMessageContent,
+    ChatReceivedAction,
+    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";

package/src/payments.ts

@@ -0,0 +1,100 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Wrapper for the host's payment manager (RFC-0006).
+ *
+ * Shipped flat-in-host rather than as `getTruApi().payment.*` because the
+ * upstream JS `hostApi` is itself a flat object - there is no `.payment`
+ * accessor to mirror. A flat `getPaymentManager()` matches the singleton
+ * pattern already used by {@link getPreimageManager},
+ * {@link getHostLocalStorage}, and {@link getAccountsProvider}.
+ *
+ * Returns the shared `paymentManager` singleton from
+ * `@novasamatech/host-api-wrapper` (not a fresh `createPaymentManager()`
+ * instance) so callers share one wrapper + hostApi closure across the app.
+ *
+ * Distinct from the CoinPayment / merchant-payments surface tracked under
+ * `@parity/product-sdk-merchant-payments` (RFC-0017). RFC-0006 is the
+ * user-initiated balance / top-up / payment-request flow; RFC-0017 is the
+ * merchant-initiated checkout flow.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import type {
+    PaymentBalance as NovasamaPaymentBalance,
+    PaymentStatus as NovasamaPaymentStatus,
+    TopUpSource as NovasamaTopUpSource,
+    paymentManager,
+} from "@novasamatech/host-api-wrapper";
+
+const log = createLogger("host:payments");
+
+/** Available balance for the user's payment account. Re-exported from `@novasamatech/host-api-wrapper`. */
+export type PaymentBalance = NovasamaPaymentBalance;
+
+/** Status of an in-flight payment request. Re-exported from `@novasamatech/host-api-wrapper`. */
+export type PaymentStatus = NovasamaPaymentStatus;
+
+/** Source for {@link PaymentManager.topUp}. Re-exported from `@novasamatech/host-api-wrapper`. */
+export type TopUpSource = NovasamaTopUpSource;
+
+/**
+ * Payment manager handle. Exposes balance subscription, top-up, payment
+ * requests, and payment status subscription.
+ *
+ * Type identical to `paymentManager` from `@novasamatech/host-api-wrapper`.
+ */
+export type PaymentManager = typeof paymentManager;
+
+/**
+ * Get the host payment manager.
+ *
+ * Returns the shared `paymentManager` singleton from
+ * `@novasamatech/host-api-wrapper`, or `null` if the package is unavailable
+ * (running outside a host container or the optional peer dep isn't
+ * installed).
+ *
+ * @returns The payment manager, or `null` if unavailable.
+ *
+ * @example
+ * ```ts
+ * import { getPaymentManager } from "@parity/product-sdk-host";
+ *
+ * const payments = await getPaymentManager();
+ * if (payments) {
+ *   const sub = payments.subscribeBalance((b) => { ... });
+ *   await payments.topUp(1_000_000n, { type: "productAccount", derivationIndex: 0 });
+ *   const destination = new Uint8Array(32);
+ *   const { id } = await payments.requestPayment(500n, destination);
+ *   sub.unsubscribe();
+ * }
+ * ```
+ */
+export async function getPaymentManager(): Promise<PaymentManager | null> {
+    try {
+        const sdk = await import("@novasamatech/host-api-wrapper");
+        return sdk.paymentManager;
+    } catch (err) {
+        log.debug("getPaymentManager unavailable", err);
+        return null;
+    }
+}
+
+if (import.meta.vitest) {
+    const { test, expect } = import.meta.vitest;
+
+    test("getPaymentManager returns manager with full RFC-0006 surface when SDK is available", async () => {
+        const payments = await getPaymentManager();
+        if (payments === null) {
+            // Acceptable: SDK couldn't load (e.g. peer dep missing in some envs).
+            return;
+        }
+        expect(typeof payments.subscribeBalance).toBe("function");
+        expect(typeof payments.topUp).toBe("function");
+        expect(typeof payments.requestPayment).toBe("function");
+        expect(typeof payments.subscribePaymentStatus).toBe("function");
+    });
+}

package/src/permissions.ts

@@ -1,22 +1,43 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
 /**
- * Higher-level wrapper for the host's single-permission flow.
+ * Higher-level wrappers for the host's single-permission flows.
  *
- * `hostApi.permission` takes a versioned envelope (`enumValue("v1", ...)`)
- * and returns a neverthrow `ResultAsync` of an unwrapped versioned response.
- * Consumers rebuild that wrap/unwrap dance every time. `requestPermission`
- * collapses it to a one-liner that matches the shape of
- * {@link requestResourceAllocation} (throws on error, returns the unwrapped
- * payload on success).
+ * `hostApi.permission` / `hostApi.devicePermission` take a versioned
+ * envelope (`enumValue("v1", ...)`) and return a neverthrow `ResultAsync`
+ * of an unwrapped versioned response. Consumers rebuild that wrap/unwrap
+ * dance every time. {@link requestPermission} and
+ * {@link requestDevicePermission} collapse it to one-liners that match the
+ * shape of {@link requestResourceAllocation} (throws on error, returns
+ * the unwrapped payload on success).
  *
  * @module
  */
 
 import { createLogger } from "@parity/product-sdk-logger";
 
-import { enumValue, getTruApi, type RemotePermission } from "./truapi.js";
+import type { CodecType } from "@novasamatech/host-api";
+import type { DevicePermission as DevicePermissionCodec } from "@novasamatech/host-api";
+
+import { enumValue, formatHostError, getTruApi, type RemotePermission } from "./truapi.js";
 
 const log = createLogger("host:permissions");
 
+/**
+ * Device permission the dapp can ask the host to grant via
+ * {@link requestDevicePermission}.
+ *
+ * Derived from the upstream codec so variant renames surface as compile
+ * errors, not runtime failures.
+ */
+export type DevicePermissionKind = CodecType<typeof DevicePermissionCodec>;
+
+/**
+ * Alias of {@link RemotePermission} matching the upstream
+ * `@novasamatech/host-api-wrapper` name. Use either freely.
+ */
+export type RemotePermissionItem = RemotePermission;
+
 /**
  * Request a single remote permission from the host.
  *
@@ -45,10 +66,43 @@ export async function requestPermission(permission: RemotePermission): Promise<b
     return await truApi.permission(enumValue("v1", permission)).match(
         (envelope: { tag: "v1"; value: boolean }) => envelope.value,
         (err: unknown) => {
-            throw new Error(
-                `requestPermission failed: ${err instanceof Error ? err.message : String(err)}`,
-                { cause: err },
-            );
+            throw new Error(`requestPermission failed: ${formatHostError(err)}`, { cause: err });
+        },
+    );
+}
+
+/**
+ * Request a single device permission (camera, microphone, etc.) from the
+ * host.
+ *
+ * Builds the `v1` envelope, calls `hostApi.devicePermission`, unwraps the
+ * response, and returns the host's boolean granted/denied outcome.
+ *
+ * @param permission - The device permission to request.
+ * @returns `true` if the host granted the permission, `false` if denied.
+ * @throws If the host is unavailable or the request fails.
+ *
+ * @example
+ * ```ts
+ * const granted = await requestDevicePermission("Camera");
+ * if (!granted) {
+ *   showCameraDeniedMessage();
+ * }
+ * ```
+ */
+export async function requestDevicePermission(permission: DevicePermissionKind): Promise<boolean> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        throw new Error("requestDevicePermission: TruAPI unavailable");
+    }
+    log.debug("requestDevicePermission", { permission });
+
+    return await truApi.devicePermission(enumValue("v1", permission)).match(
+        (envelope: { tag: "v1"; value: boolean }) => envelope.value,
+        (err: unknown) => {
+            throw new Error(`requestDevicePermission failed: ${formatHostError(err)}`, {
+                cause: err,
+            });
         },
     );
 }
@@ -57,14 +111,21 @@ if (import.meta.vitest) {
     const { test, expect, describe, vi } = import.meta.vitest;
 
     async function withMockedTruApi<T>(
-        bridge: { permission?: (req: unknown) => unknown } | null,
+        bridge: {
+            permission?: (req: unknown) => unknown;
+            devicePermission?: (req: unknown) => unknown;
+        } | null,
         fn: (mod: typeof import("./permissions.js")) => Promise<T>,
     ): Promise<T> {
         vi.resetModules();
-        vi.doMock("./truapi.js", () => ({
-            getTruApi: async () => bridge,
-            enumValue: (version: string, value: unknown) => ({ tag: version, value }),
-        }));
+        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("./permissions.js");
             return await fn(mod);
@@ -118,7 +179,54 @@ if (import.meta.vitest) {
                 async (mod) => {
                     await expect(
                         mod.requestPermission({ tag: "ChainSubmit", value: undefined }),
-                    ).rejects.toThrow(/requestPermission failed/);
+                    ).rejects.toThrow(/requestPermission failed: GenericError: boom/);
+                },
+            );
+        });
+    });
+
+    describe("requestDevicePermission", () => {
+        test("throws when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                await expect(mod.requestDevicePermission("Camera")).rejects.toThrow(
+                    /TruAPI unavailable/,
+                );
+            });
+        });
+
+        test("unwraps the v1 boolean outcome", async () => {
+            await withMockedTruApi(
+                {
+                    devicePermission: vi.fn().mockReturnValue({
+                        match: async (onOk: (v: unknown) => unknown) =>
+                            onOk({ tag: "v1", value: true }),
+                    }),
+                },
+                async (mod) => {
+                    const granted = await mod.requestDevicePermission("Camera");
+                    expect(granted).toBe(true);
+                },
+            );
+        });
+
+        test("wraps host errors with a diagnostic message", async () => {
+            await withMockedTruApi(
+                {
+                    devicePermission: 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.requestDevicePermission("Camera")).rejects.toThrow(
+                        /requestDevicePermission failed: GenericError: boom/,
+                    );
                 },
             );
         });