@parity/product-sdk-host 0.3.0 → 0.5.0

package/src/chat.ts

@@ -0,0 +1,124 @@
+/**
+ * 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,11 @@
 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 +19,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 +34,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 +72,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 +121,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 +198,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,65 @@
+/**
+ * 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

@@ -11,6 +11,7 @@ export {
     isInsideContainer,
     isInsideContainerSync,
     getHostLocalStorage,
+    createHostLocalStorage,
     getHostProvider,
     getStatementStore,
 } from "./container.js";
@@ -18,18 +19,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,
@@ -50,5 +58,37 @@ export type {
     ContextualAlias,
     ResultAsync,
     AllocatableResource,
+    AllocatableResourceTag,
     AllocationOutcome,
+    AllocationOutcomeTag,
+    RemotePermission,
+    RemotePermissionTag,
 } from "./truapi.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, ThemeProvider } 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,98 @@
+/**
+ * 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");
+    });
+}