@parity/product-sdk-host 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,8 +1,13 @@
-import { JsonRpcProvider } from 'polkadot-api/ws-provider/web';
 import * as polkadot_api from 'polkadot-api';
+import { JsonRpcProvider } from 'polkadot-api';
 export { HexString, assertEnumVariant, enumValue, fromHex, isEnumVariant, resultErr, resultOk, toHex, unwrapResultOrThrow } from '@novasamatech/host-api';
 
-/** Subset of product-sdk's hostLocalStorage that the KV store uses. */
+/**
+ * Persistent string and JSON storage exposed by the host container. Most
+ * apps reach it indirectly through the Storage package's `KvStore`; reach for
+ * it directly via {@link getHostLocalStorage} when you need raw host storage
+ * without the KV abstraction.
+ */
 interface HostLocalStorage {
     readString(key: string): Promise<string | null>;
     writeString(key: string, value: string): Promise<void>;
@@ -14,7 +19,14 @@ interface HostLocalStorage {
      */
     clear(key: string): Promise<void>;
 }
-/** Proof types returned from createProof (matches product-sdk SCALE-decoded types). */
+/**
+ * Cryptographic proof attached to a statement before submission, returned by
+ * {@link HostStatementStore.createProof}. Variants cover the supported
+ * signature schemes — `Sr25519`, `Ed25519`, `Ecdsa`, and `OnChain` (chain-
+ * attestation-based proofs).
+ *
+ * Mirrors `@novasamatech/product-sdk@0.7`'s proof shape.
+ */
 type StatementProof = {
     tag: "Sr25519";
     value: {
@@ -28,38 +40,77 @@ type StatementProof = {
         signer: Uint8Array;
     };
 } | {
-    tag: "Secp256k1Ecdsa";
+    tag: "Ecdsa";
     value: {
         signature: Uint8Array;
         signer: Uint8Array;
     };
 } | {
-    tag: "EcdsaRecoverable";
+    tag: "OnChain";
     value: {
-        signature: Uint8Array;
+        who: Uint8Array;
+        blockHash: Uint8Array;
+        event: bigint;
     };
 };
-/** The statement store interface provided by the host API via product-sdk. */
+/**
+ * Topic-based subscription filter. Mirrors `StatementTopicFilter` from
+ * `@novasamatech/product-sdk` — the host delivers statements that match
+ * either *all* of the listed topics (`matchAll`) or *any* of them
+ * (`matchAny`).
+ */
+type StatementTopicFilter = {
+    matchAll: Uint8Array[];
+} | {
+    matchAny: Uint8Array[];
+};
+/**
+ * A page of signed statements delivered by {@link HostStatementStore.subscribe}.
+ *
+ * Pages arrive sequentially. `isComplete` is `true` on the final page of a
+ * subscription's initial backfill; subsequent pages contain new statements
+ * as they appear on chain.
+ */
+interface StatementsPage {
+    statements: unknown[];
+    isComplete: boolean;
+}
+/** Subscription handle returned by the host. */
+interface HostSubscription {
+    unsubscribe: () => void;
+}
+/**
+ * Statement Store handle exposed by the host container. Provides
+ * `subscribe`, `createProof`, and `submit` operations that go through the
+ * host's native binary protocol; the `statement-store` package layers a
+ * higher-level client on top.
+ *
+ * Shape matches `@novasamatech/product-sdk@0.7`'s `createStatementStore()`.
+ */
 interface HostStatementStore {
     /**
-     * Subscribe to statements matching the given topics.
-     * @param topics - Topic filters as Uint8Array[]
-     * @param callback - Called with batches of SignedStatement[]
-     * @returns Subscription object with unsubscribe method
+     * Subscribe to statements matching the given topic filter.
+     *
+     * The callback is invoked once per page of statements. After the initial
+     * backfill completes (signaled by `page.isComplete === true`), subsequent
+     * pages contain new statements as they're produced.
+     *
+     * @param filter   - Topic match filter (`matchAll` or `matchAny`).
+     * @param callback - Called with each `StatementsPage` from the host.
+     * @returns Subscription handle with `unsubscribe`.
      */
-    subscribe(topics: Uint8Array[], callback: (statements: unknown[]) => void): {
-        unsubscribe: () => void;
-    };
+    subscribe(filter: StatementTopicFilter, callback: (page: StatementsPage) => void): HostSubscription;
     /**
      * Create a proof for a statement using the given account.
-     * @param accountId - The account ID tuple [ss58Address, chainPrefix] from product-sdk
-     * @param statement - The unsigned statement
-     * @returns The proof (signature + signer info)
+     *
+     * @param accountId - The account ID tuple `[ss58Address, chainPrefix]` from product-sdk.
+     * @param statement - The unsigned statement.
+     * @returns The proof (signature + signer info, or chain-attestation reference).
      */
     createProof(accountId: [string, number], statement: unknown): Promise<StatementProof>;
     /**
      * Submit a signed statement to the bulletin chain.
-     * @param signedStatement - Statement with attached proof
+     * @param signedStatement - Statement with attached proof.
      */
     submit(signedStatement: unknown): Promise<void>;
 }
@@ -113,13 +164,17 @@ declare function getStatementStore(): Promise<HostStatementStore | null>;
  * Shared chain network configuration — single source of truth for
  * chain-specific endpoints used by multiple packages.
  */
-/** Bulletin chain RPC endpoints by environment. */
+/**
+ * Bulletin Chain RPC endpoints per network environment. Only `paseo` is
+ * populated today; `polkadot` and `kusama` are reserved for when those
+ * Bulletin deployments go live.
+ */
 declare const BULLETIN_RPCS: {
     readonly paseo: readonly ["wss://paseo-bulletin-rpc.polkadot.io"];
     readonly polkadot: string[];
     readonly kusama: string[];
 };
-/** Default bulletin endpoint (first paseo endpoint). */
+/** Default Bulletin Chain endpoint — the first entry under {@link BULLETIN_RPCS}.paseo. */
 declare const DEFAULT_BULLETIN_ENDPOINT: string;
 
 /**
@@ -221,7 +276,10 @@ interface PreimageManager {
  */
 declare function getAccountsProvider(): Promise<AccountsProvider | null>;
 /**
- * Account from the host wallet.
+ * One of the user's existing wallet accounts, surfaced through the host and
+ * identified by its public key and an optional name. Contrast with
+ * {@link ProductAccount}, which is also user-controlled but derived by the
+ * host for a specific app rather than picked from the user's existing keys.
  */
 interface HostAccount {
     publicKey: Uint8Array;
@@ -268,18 +326,22 @@ interface ResultAsync<T, E> {
  */
 interface AccountsProvider {
     /**
-     * Get non-product accounts (user's external wallets connected to the host).
+     * Get legacy accounts (user's external wallets connected to the host).
+     *
+     * Renamed from `getNonProductAccounts` in @novasamatech/product-sdk 0.7.
      *
      * @returns ResultAsync resolving to array of accounts.
      */
-    getNonProductAccounts: () => ResultAsync<HostAccount[], unknown>;
+    getLegacyAccounts: () => ResultAsync<HostAccount[], unknown>;
     /**
-     * Get a signer for a non-product account.
+     * Get a signer for a legacy account.
+     *
+     * Renamed from `getNonProductAccountSigner` in @novasamatech/product-sdk 0.7.
      *
      * @param account - The product account (used for public key lookup).
      * @returns A PolkadotSigner for signing transactions.
      */
-    getNonProductAccountSigner: (account: ProductAccount) => polkadot_api.PolkadotSigner;
+    getLegacyAccountSigner: (account: ProductAccount) => polkadot_api.PolkadotSigner;
     /**
      * Get an app-scoped product account from the host.
      *
@@ -334,4 +396,4 @@ interface AccountsProvider {
     } | (() => void);
 }
 
-export { type AccountsProvider, BULLETIN_RPCS, type ContextualAlias, DEFAULT_BULLETIN_ENDPOINT, type HostAccount, type HostLocalStorage, type HostStatementStore, type PreimageManager, type ProductAccount, type ResultAsync, type StatementProof, type TruApi, getAccountsProvider, getHostLocalStorage, getHostProvider, getPreimageManager, getStatementStore, getTruApi, isInsideContainer, isInsideContainerSync };
+export { type AccountsProvider, BULLETIN_RPCS, type ContextualAlias, DEFAULT_BULLETIN_ENDPOINT, type HostAccount, type HostLocalStorage, type HostStatementStore, type HostSubscription, type PreimageManager, type ProductAccount, type ResultAsync, type StatementProof, type StatementTopicFilter, type StatementsPage, type TruApi, getAccountsProvider, getHostLocalStorage, getHostProvider, getPreimageManager, getStatementStore, getTruApi, isInsideContainer, isInsideContainerSync };

package/dist/index.js

@@ -1,8 +1,11 @@
+import { createLogger } from '@parity/product-sdk-logger';
+export { assertEnumVariant, enumValue, fromHex, isEnumVariant, resultErr, resultOk, toHex, unwrapResultOrThrow } from '@novasamatech/host-api';
+
 // src/container.ts
 async function isInsideContainer() {
   if (typeof window === "undefined") return false;
   try {
-    const sdk = await import("@novasamatech/product-sdk");
+    const sdk = await import('@novasamatech/product-sdk');
     return sdk.sandboxProvider.isCorrectEnvironment();
   } catch {
     return isInsideContainerSync();
@@ -11,7 +14,7 @@ async function isInsideContainer() {
 async function getHostLocalStorage() {
   if (!await isInsideContainer()) return null;
   try {
-    const sdk = await import("@novasamatech/product-sdk");
+    const sdk = await import('@novasamatech/product-sdk');
     return sdk.hostLocalStorage;
   } catch {
     return null;
@@ -19,7 +22,7 @@ async function getHostLocalStorage() {
 }
 async function getHostProvider(genesisHash) {
   try {
-    const sdk = await import("@novasamatech/product-sdk");
+    const sdk = await import('@novasamatech/product-sdk');
     return sdk.createPapiProvider(genesisHash);
   } catch {
     return null;
@@ -39,76 +42,12 @@ function isInsideContainerSync() {
 }
 async function getStatementStore() {
   try {
-    const sdk = await import("@novasamatech/product-sdk");
+    const sdk = await import('@novasamatech/product-sdk');
     return sdk.createStatementStore();
   } catch {
     return null;
   }
 }
-if (void 0) {
-  const { test, expect, vi } = void 0;
-  test("returns false in Node environment (no window)", async () => {
-    expect(await isInsideContainer()).toBe(false);
-  });
-  test("manualDetection returns true for __HOST_WEBVIEW_MARK__", async () => {
-    const fakeWindow = {
-      top: null,
-      __HOST_WEBVIEW_MARK__: true
-    };
-    vi.stubGlobal("window", fakeWindow);
-    const result = await isInsideContainer();
-    expect(result).toBe(true);
-    vi.unstubAllGlobals();
-  });
-  test("manualDetection returns true for __HOST_API_PORT__", async () => {
-    const fakeWindow = {
-      top: null,
-      __HOST_API_PORT__: 12345
-    };
-    vi.stubGlobal("window", fakeWindow);
-    const result = await isInsideContainer();
-    expect(result).toBe(true);
-    vi.unstubAllGlobals();
-  });
-  test("manualDetection returns false when no signals present", async () => {
-    const fakeWindow = { top: null };
-    Object.defineProperty(fakeWindow, "top", { get: () => fakeWindow });
-    vi.stubGlobal("window", fakeWindow);
-    const result = await isInsideContainer();
-    expect(result).toBe(false);
-    vi.unstubAllGlobals();
-  });
-  test("manualDetection returns true for cross-origin iframe", async () => {
-    const fakeWindow = {};
-    Object.defineProperty(fakeWindow, "top", {
-      get: () => {
-        throw new DOMException("cross-origin");
-      }
-    });
-    vi.stubGlobal("window", fakeWindow);
-    const result = await isInsideContainer();
-    expect(result).toBe(true);
-    vi.unstubAllGlobals();
-  });
-  test("manualDetection returns true when window !== window.top (iframe)", async () => {
-    const fakeWindow = { top: {} };
-    vi.stubGlobal("window", fakeWindow);
-    const result = await isInsideContainer();
-    expect(result).toBe(true);
-    vi.unstubAllGlobals();
-  });
-  test("getHostLocalStorage returns null outside container", async () => {
-    expect(await getHostLocalStorage()).toBeNull();
-  });
-  test("getHostProvider returns null when product-sdk unavailable", async () => {
-    const result = await getHostProvider("0xabc");
-    expect(result).toBeNull();
-  });
-  test("getStatementStore returns null when product-sdk unavailable", async () => {
-    const result = await getStatementStore();
-    expect(result).toBeNull();
-  });
-}
 
 // src/chains.ts
 var BULLETIN_RPCS = {
@@ -117,41 +56,12 @@ var BULLETIN_RPCS = {
   kusama: []
 };
 var DEFAULT_BULLETIN_ENDPOINT = BULLETIN_RPCS.paseo[0];
-if (void 0) {
-  const { describe, test, expect } = void 0;
-  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 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]);
-    });
-  });
-}
-
-// src/truapi.ts
-import { createLogger } from "@parity/product-sdk-logger";
-import {
-  enumValue,
-  isEnumVariant,
-  assertEnumVariant,
-  unwrapResultOrThrow,
-  resultOk,
-  resultErr,
-  toHex,
-  fromHex
-} from "@novasamatech/host-api";
 var log = createLogger("host");
 var cachedTruApi = null;
 async function getTruApi() {
   if (cachedTruApi) return cachedTruApi;
   try {
-    const sdk = await import("@novasamatech/product-sdk");
+    const sdk = await import('@novasamatech/product-sdk');
     cachedTruApi = sdk.hostApi;
     log.debug("TruAPI loaded");
     return cachedTruApi;
@@ -162,7 +72,7 @@ async function getTruApi() {
 }
 async function getPreimageManager() {
   try {
-    const sdk = await import("@novasamatech/product-sdk");
+    const sdk = await import('@novasamatech/product-sdk');
     return sdk.preimageManager;
   } catch {
     return null;
@@ -170,50 +80,13 @@ async function getPreimageManager() {
 }
 async function getAccountsProvider() {
   try {
-    const sdk = await import("@novasamatech/product-sdk");
+    const sdk = await import('@novasamatech/product-sdk');
     return sdk.createAccountsProvider();
   } catch {
     return null;
   }
 }
-if (void 0) {
-  const { test, expect } = void 0;
-  test("getTruApi returns TruApi when SDK is available", async () => {
-    cachedTruApi = null;
-    const api = await getTruApi();
-    expect(api === null || typeof api === "object").toBe(true);
-  });
-  test("getPreimageManager returns manager when SDK is available", async () => {
-    const manager = await getPreimageManager();
-    expect(manager === null || typeof manager === "object").toBe(true);
-  });
-  test("getAccountsProvider returns provider when SDK is available", async () => {
-    const provider = await getAccountsProvider();
-    expect(provider === null || typeof provider === "object").toBe(true);
-  });
-  test("enumValue is exported", async () => {
-    const { enumValue: enumValue2 } = await null;
-    expect(typeof enumValue2).toBe("function");
-  });
-}
-export {
-  BULLETIN_RPCS,
-  DEFAULT_BULLETIN_ENDPOINT,
-  assertEnumVariant,
-  enumValue,
-  fromHex,
-  getAccountsProvider,
-  getHostLocalStorage,
-  getHostProvider,
-  getPreimageManager,
-  getStatementStore,
-  getTruApi,
-  isEnumVariant,
-  isInsideContainer,
-  isInsideContainerSync,
-  resultErr,
-  resultOk,
-  toHex,
-  unwrapResultOrThrow
-};
+
+export { BULLETIN_RPCS, DEFAULT_BULLETIN_ENDPOINT, getAccountsProvider, getHostLocalStorage, getHostProvider, getPreimageManager, getStatementStore, getTruApi, isInsideContainer, isInsideContainerSync };
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/container.ts","../src/chains.ts","../src/truapi.ts"],"sourcesContent":["import type { JsonRpcProvider } from \"polkadot-api/ws-provider/web\";\n\nimport type { HostLocalStorage, HostStatementStore } from \"./types.js\";\n\n/**\n * Detect if running inside a Host container (Polkadot Browser / Polkadot Desktop).\n *\n * The SDK is designed to run exclusively inside a host container. This function\n * is primarily useful for early validation or informational purposes.\n *\n * Uses product-sdk's sandboxProvider as primary detection.\n * Falls back to manual signal checks when product-sdk is not installed.\n */\nexport async function isInsideContainer(): Promise<boolean> {\n    if (typeof window === \"undefined\") return false;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.sandboxProvider.isCorrectEnvironment();\n    } catch {\n        return isInsideContainerSync();\n    }\n}\n\n/**\n * Get the Host API localStorage instance when running inside a container.\n * Returns null outside a container or when product-sdk is unavailable.\n */\nexport async function getHostLocalStorage(): Promise<HostLocalStorage | null> {\n    if (!(await isInsideContainer())) return null;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.hostLocalStorage as HostLocalStorage;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Get a PAPI-compatible JSON-RPC provider that routes through the host connection.\n *\n * When running inside a Polkadot container, this wraps the chain connection via the\n * host's `createPapiProvider`, enabling shared connections and efficient routing.\n * Returns `null` when `@novasamatech/product-sdk` is unavailable.\n *\n * @param genesisHash - Genesis hash of the target chain (`0x`-prefixed hex string).\n * @returns A host-routed `JsonRpcProvider`, or `null` if unavailable.\n */\nexport async function getHostProvider(genesisHash: `0x${string}`): Promise<JsonRpcProvider | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createPapiProvider(genesisHash);\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Synchronous container detection — fast heuristic check without product-sdk.\n *\n * Checks for iframe, webview marker, and host message port signals.\n * Use this when you need a quick sync check (e.g., in hot code paths).\n * For full detection including product-sdk, use {@link isInsideContainer} (async).\n */\nexport function isInsideContainerSync(): boolean {\n    if (typeof window === \"undefined\") return false;\n\n    const win = window as unknown as Record<string, unknown>;\n\n    // Iframe detection (polkadot.com browser)\n    try {\n        if (window !== window.top) return true;\n    } catch {\n        // Cross-origin iframe — likely inside a container\n        return true;\n    }\n\n    // Webview detection (Polkadot Desktop)\n    if (win.__HOST_WEBVIEW_MARK__ === true) return true;\n\n    // Desktop message-passing API\n    if (win.__HOST_API_PORT__ != null) return true;\n\n    return false;\n}\n\n/**\n * Get the host API statement store when running inside a container.\n *\n * Returns a statement store with `subscribe`, `createProof`, and `submit` methods\n * that communicate through the host's native binary protocol — bypassing JSON-RPC\n * entirely. Returns `null` when `@novasamatech/product-sdk` is unavailable.\n *\n * @returns The host statement store, or `null` if unavailable.\n */\nexport async function getStatementStore(): Promise<HostStatementStore | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createStatementStore() as HostStatementStore;\n    } catch {\n        return null;\n    }\n}\n\nif (import.meta.vitest) {\n    const { test, expect, vi } = import.meta.vitest;\n\n    test(\"returns false in Node environment (no window)\", async () => {\n        expect(await isInsideContainer()).toBe(false);\n    });\n\n    test(\"manualDetection returns true for __HOST_WEBVIEW_MARK__\", async () => {\n        const fakeWindow = {\n            top: null,\n            __HOST_WEBVIEW_MARK__: true,\n        };\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true for __HOST_API_PORT__\", async () => {\n        const fakeWindow = {\n            top: null,\n            __HOST_API_PORT__: 12345,\n        };\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns false when no signals present\", async () => {\n        const fakeWindow = { top: null };\n        Object.defineProperty(fakeWindow, \"top\", { get: () => fakeWindow });\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(false);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true for cross-origin iframe\", async () => {\n        const fakeWindow = {};\n        Object.defineProperty(fakeWindow, \"top\", {\n            get: () => {\n                throw new DOMException(\"cross-origin\");\n            },\n        });\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true when window !== window.top (iframe)\", async () => {\n        const fakeWindow = { top: {} }; // top is a different object\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"getHostLocalStorage returns null outside container\", async () => {\n        expect(await getHostLocalStorage()).toBeNull();\n    });\n\n    test(\"getHostProvider returns null when product-sdk unavailable\", async () => {\n        const result = await getHostProvider(\"0xabc\");\n        expect(result).toBeNull();\n    });\n\n    test(\"getStatementStore returns null when product-sdk unavailable\", async () => {\n        const result = await getStatementStore();\n        expect(result).toBeNull();\n    });\n}\n","/**\n * Shared chain network configuration — single source of truth for\n * chain-specific endpoints used by multiple packages.\n */\n\n/** Bulletin chain RPC endpoints by environment. */\nexport const BULLETIN_RPCS = {\n    paseo: [\"wss://paseo-bulletin-rpc.polkadot.io\"],\n    polkadot: [] as string[],\n    kusama: [] as string[],\n} as const;\n\n/** Default bulletin endpoint (first paseo endpoint). */\nexport const DEFAULT_BULLETIN_ENDPOINT: string = BULLETIN_RPCS.paseo[0];\n\nif (import.meta.vitest) {\n    const { describe, test, expect } = import.meta.vitest;\n\n    describe(\"chains config\", () => {\n        test(\"BULLETIN_RPCS has paseo endpoint\", () => {\n            expect(BULLETIN_RPCS.paseo.length).toBeGreaterThan(0);\n            expect(BULLETIN_RPCS.paseo[0]).toMatch(/^wss:\\/\\//);\n        });\n\n        test(\"BULLETIN_RPCS polkadot and kusama are empty until live\", () => {\n            expect(BULLETIN_RPCS.polkadot).toEqual([]);\n            expect(BULLETIN_RPCS.kusama).toEqual([]);\n        });\n\n        test(\"DEFAULT_BULLETIN_ENDPOINT matches first paseo endpoint\", () => {\n            expect(DEFAULT_BULLETIN_ENDPOINT).toBe(BULLETIN_RPCS.paseo[0]);\n        });\n    });\n}\n","/**\n * TruAPI - the protocol for communicating between apps and the Polkadot host container.\n *\n * This module centralizes access to @novasamatech/product-sdk and @novasamatech/host-api,\n * allowing other @parity/product-sdk-* packages to import from here rather than depending\n * directly on novasama packages.\n *\n * @module\n */\n\nimport { createLogger } from \"@parity/product-sdk-logger\";\n\nconst log = createLogger(\"host\");\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Helpers from @novasamatech/host-api (re-exported from @novasamatech/scale)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport {\n    /**\n     * Construct an enum variant for TruAPI calls.\n     *\n     * @example\n     * ```ts\n     * import { enumValue, getTruApi } from \"@parity/product-sdk-host\";\n     *\n     * const truApi = await getTruApi();\n     * if (truApi) {\n     *   await truApi.permission([enumValue(\"ChainSubmit\")]);\n     * }\n     * ```\n     */\n    enumValue,\n    /**\n     * Check if a value is a specific enum variant.\n     */\n    isEnumVariant,\n    /**\n     * Assert that a value is a specific enum variant, throwing if not.\n     */\n    assertEnumVariant,\n    /**\n     * Unwrap a Result, throwing on error.\n     */\n    unwrapResultOrThrow,\n    /**\n     * Create an Ok result.\n     */\n    resultOk,\n    /**\n     * Create an Err result.\n     */\n    resultErr,\n    /**\n     * Convert bytes to hex string.\n     */\n    toHex,\n    /**\n     * Convert hex string to bytes.\n     */\n    fromHex,\n} from \"@novasamatech/host-api\";\n\nexport type { HexString } from \"@novasamatech/host-api\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// TruAPI accessor\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The TruApi type - provides low-level methods for communicating with the host.\n *\n * Methods include:\n * - `navigateTo(url)` — Navigate to a URL within the host\n * - `permission(permissions)` — Request permissions from the host\n * - `localStorageRead/Write/Clear` — Host-backed storage\n * - `sign(payload)` — Request transaction signing\n * - `deriveEntropy(context)` — Derive deterministic entropy\n * - `themeSubscribe()` — Subscribe to host theme changes\n * - And many more...\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type TruApi = any;\n\n/** Cached TruApi instance */\nlet cachedTruApi: TruApi | null = null;\n\n/**\n * Get the TruAPI instance for direct low-level access.\n *\n * Returns the `hostApi` object from `@novasamatech/product-sdk` which provides\n * methods for communicating directly with the host container. Returns `null`\n * when running outside a container or when the SDK is unavailable.\n *\n * For most use cases, prefer the higher-level functions like `getHostLocalStorage()`,\n * `getHostProvider()`, etc. Use this when you need direct access to host methods\n * like `navigateTo()`, `permission()`, or `deriveEntropy()`.\n *\n * @example\n * ```ts\n * import { getTruApi, enumValue } from \"@parity/product-sdk-host\";\n *\n * const truApi = await getTruApi();\n * if (truApi) {\n *   // Request permission\n *   const result = await truApi.permission([enumValue(\"ChainSubmit\")]);\n *\n *   // Navigate to a URL\n *   await truApi.navigateTo(\"polkadot://settings\");\n *\n *   // Subscribe to theme changes\n *   const sub = truApi.themeSubscribe(undefined, (theme) => {\n *     console.log(\"Theme changed:\", theme);\n *   });\n * }\n * ```\n *\n * @returns The TruAPI instance, or `null` if unavailable.\n */\nexport async function getTruApi(): Promise<TruApi | null> {\n    if (cachedTruApi) return cachedTruApi;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        cachedTruApi = sdk.hostApi;\n        log.debug(\"TruAPI loaded\");\n        return cachedTruApi;\n    } catch {\n        log.debug(\"TruAPI unavailable (not in container or SDK not installed)\");\n        return null;\n    }\n}\n\n/**\n * Get the preimage manager for bulletin chain operations.\n *\n * The preimage manager handles uploading and looking up preimages (arbitrary data)\n * on the bulletin chain through the host's optimized path.\n *\n * @returns The preimage manager, or `null` if unavailable.\n *\n * @example\n * ```ts\n * import { getPreimageManager } from \"@parity/product-sdk-host\";\n *\n * const manager = await getPreimageManager();\n * if (manager) {\n *   // Submit a preimage\n *   const key = await manager.submit(new Uint8Array([1, 2, 3]));\n *\n *   // Look up a preimage\n *   const sub = manager.lookup(key, (data) => {\n *     if (data) console.log(\"Found:\", data);\n *   });\n * }\n * ```\n */\nexport async function getPreimageManager(): Promise<PreimageManager | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.preimageManager;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Preimage manager interface for bulletin chain operations.\n */\nexport interface PreimageManager {\n    /**\n     * Submit a preimage to the bulletin chain.\n     * @param data - The data to submit.\n     * @returns The preimage key (hex string).\n     */\n    submit(data: Uint8Array): Promise<string>;\n\n    /**\n     * Look up a preimage by key.\n     * @param key - The preimage key (hex string).\n     * @param callback - Called with the data when found, or null if not yet available.\n     * @returns Subscription handle with unsubscribe method.\n     */\n    lookup(\n        key: string,\n        callback: (preimage: Uint8Array | null) => void,\n    ): { unsubscribe: () => void; onInterrupt: (cb: () => void) => () => void };\n}\n\n/**\n * Get the accounts provider for managing host accounts.\n *\n * @returns The accounts provider, or `null` if unavailable.\n */\nexport async function getAccountsProvider(): Promise<AccountsProvider | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createAccountsProvider() as unknown as AccountsProvider;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Account from the host wallet.\n */\nexport interface HostAccount {\n    publicKey: Uint8Array;\n    name?: string;\n}\n\n/**\n * A product account — an app-scoped derived account managed by the host wallet.\n *\n * The host derives a unique keypair for each app (identified by `dotNsIdentifier`)\n * so apps get their own account that the user controls but is scoped to the app.\n */\nexport interface ProductAccount {\n    /** App identifier (e.g., \"mark3t.dot\"). */\n    dotNsIdentifier: string;\n    /** Derivation index within the app scope. Default: 0 */\n    derivationIndex: number;\n    /** Raw public key (32 bytes). */\n    publicKey: Uint8Array;\n}\n\n/**\n * A contextual alias obtained from Ring VRF.\n *\n * Proves account membership in a ring without revealing which account.\n */\nexport interface ContextualAlias {\n    /** Ring context (32 bytes). */\n    context: Uint8Array;\n    /** The Ring VRF alias bytes. */\n    alias: Uint8Array;\n}\n\n/**\n * Neverthrow-style ResultAsync returned by product-sdk methods.\n *\n * Use `.match(onOk, onErr)` to handle success/error cases.\n */\nexport interface ResultAsync<T, E> {\n    match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;\n}\n\n/**\n * Accounts provider interface from @novasamatech/product-sdk.\n *\n * Provides methods for accessing host wallet accounts, product accounts,\n * and Ring VRF operations.\n */\nexport interface AccountsProvider {\n    /**\n     * Get non-product accounts (user's external wallets connected to the host).\n     *\n     * @returns ResultAsync resolving to array of accounts.\n     */\n    getNonProductAccounts: () => ResultAsync<HostAccount[], unknown>;\n\n    /**\n     * Get a signer for a non-product account.\n     *\n     * @param account - The product account (used for public key lookup).\n     * @returns A PolkadotSigner for signing transactions.\n     */\n    getNonProductAccountSigner: (account: ProductAccount) => import(\"polkadot-api\").PolkadotSigner;\n\n    /**\n     * Get an app-scoped product account from the host.\n     *\n     * Product accounts are derived by the host wallet for each app, identified\n     * by `dotNsIdentifier` (e.g., \"mark3t.dot\"). The user controls these accounts\n     * but they are scoped to the requesting app.\n     *\n     * @param dotNsIdentifier - App identifier (e.g., \"mark3t.dot\").\n     * @param derivationIndex - Derivation index within the app scope. Default: 0\n     * @returns ResultAsync resolving to the account.\n     */\n    getProductAccount: (\n        dotNsIdentifier: string,\n        derivationIndex?: number,\n    ) => ResultAsync<HostAccount, unknown>;\n\n    /**\n     * Get a signer for a product account.\n     *\n     * @param account - The product account.\n     * @returns A PolkadotSigner for signing transactions.\n     */\n    getProductAccountSigner: (account: ProductAccount) => import(\"polkadot-api\").PolkadotSigner;\n\n    /**\n     * Get a contextual alias for a product account via Ring VRF.\n     *\n     * Aliases prove account membership in a ring without revealing which\n     * account produced the alias.\n     *\n     * @param dotNsIdentifier - App identifier.\n     * @param derivationIndex - Derivation index. Default: 0\n     * @returns ResultAsync resolving to the contextual alias.\n     */\n    getProductAccountAlias: (\n        dotNsIdentifier: string,\n        derivationIndex?: number,\n    ) => ResultAsync<ContextualAlias, unknown>;\n\n    /**\n     * Create a Ring VRF proof for anonymous operations.\n     *\n     * Proves that the signer is a member of the ring at the given location\n     * without revealing which member.\n     *\n     * @param dotNsIdentifier - App identifier.\n     * @param derivationIndex - Derivation index.\n     * @param location - Ring location on-chain.\n     * @param message - Message to sign.\n     * @returns ResultAsync resolving to the proof bytes.\n     */\n    createRingVRFProof: (\n        dotNsIdentifier: string,\n        derivationIndex: number,\n        location: unknown,\n        message: Uint8Array,\n    ) => ResultAsync<Uint8Array, unknown>;\n\n    /**\n     * Subscribe to account connection status changes.\n     *\n     * @param callback - Called with status string (\"connected\" | \"disconnected\").\n     * @returns Unsubscribe handle.\n     */\n    subscribeAccountConnectionStatus: (\n        callback: (status: string) => void,\n    ) => { unsubscribe: () => void } | (() => void);\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tests\n// ─────────────────────────────────────────────────────────────────────────────\n\nif (import.meta.vitest) {\n    const { test, expect } = import.meta.vitest;\n\n    test(\"getTruApi returns TruApi when SDK is available\", async () => {\n        // Reset cache for test\n        cachedTruApi = null;\n        const api = await getTruApi();\n        // In dev/test mode, product-sdk is installed\n        expect(api === null || typeof api === \"object\").toBe(true);\n    });\n\n    test(\"getPreimageManager returns manager when SDK is available\", async () => {\n        const manager = await getPreimageManager();\n        // In dev/test mode, product-sdk is installed\n        expect(manager === null || typeof manager === \"object\").toBe(true);\n    });\n\n    test(\"getAccountsProvider returns provider when SDK is available\", async () => {\n        // In dev/test mode, product-sdk is installed, so this returns a provider\n        const provider = await getAccountsProvider();\n        // Just verify it returns something (null when SDK unavailable, provider when available)\n        expect(provider === null || typeof provider === \"object\").toBe(true);\n    });\n\n    test(\"enumValue is exported\", async () => {\n        const { enumValue } = await import(\"./truapi.js\");\n        expect(typeof enumValue).toBe(\"function\");\n    });\n}\n"],"mappings":"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","names":["enumValue"]}
+{"version":3,"sources":["../src/container.ts","../src/chains.ts","../src/truapi.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { JsonRpcProvider } from \"polkadot-api\";\n\nimport type { HostLocalStorage, HostStatementStore } from \"./types.js\";\n\n/**\n * Detect if running inside a Host container (Polkadot Browser / Polkadot Desktop).\n *\n * The SDK is designed to run exclusively inside a host container. This function\n * is primarily useful for early validation or informational purposes.\n *\n * Uses product-sdk's sandboxProvider as primary detection.\n * Falls back to manual signal checks when product-sdk is not installed.\n */\nexport async function isInsideContainer(): Promise<boolean> {\n    if (typeof window === \"undefined\") return false;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.sandboxProvider.isCorrectEnvironment();\n    } catch {\n        return isInsideContainerSync();\n    }\n}\n\n/**\n * Get the Host API localStorage instance when running inside a container.\n * Returns null outside a container or when product-sdk is unavailable.\n */\nexport async function getHostLocalStorage(): Promise<HostLocalStorage | null> {\n    if (!(await isInsideContainer())) return null;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.hostLocalStorage as HostLocalStorage;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Get a PAPI-compatible JSON-RPC provider that routes through the host connection.\n *\n * When running inside a Polkadot container, this wraps the chain connection via the\n * host's `createPapiProvider`, enabling shared connections and efficient routing.\n * Returns `null` when `@novasamatech/product-sdk` is unavailable.\n *\n * @param genesisHash - Genesis hash of the target chain (`0x`-prefixed hex string).\n * @returns A host-routed `JsonRpcProvider`, or `null` if unavailable.\n */\nexport async function getHostProvider(genesisHash: `0x${string}`): Promise<JsonRpcProvider | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createPapiProvider(genesisHash);\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Synchronous container detection — fast heuristic check without product-sdk.\n *\n * Checks for iframe, webview marker, and host message port signals.\n * Use this when you need a quick sync check (e.g., in hot code paths).\n * For full detection including product-sdk, use {@link isInsideContainer} (async).\n */\nexport function isInsideContainerSync(): boolean {\n    if (typeof window === \"undefined\") return false;\n\n    const win = window as unknown as Record<string, unknown>;\n\n    // Iframe detection (polkadot.com browser)\n    try {\n        if (window !== window.top) return true;\n    } catch {\n        // Cross-origin iframe — likely inside a container\n        return true;\n    }\n\n    // Webview detection (Polkadot Desktop)\n    if (win.__HOST_WEBVIEW_MARK__ === true) return true;\n\n    // Desktop message-passing API\n    if (win.__HOST_API_PORT__ != null) return true;\n\n    return false;\n}\n\n/**\n * Get the host API statement store when running inside a container.\n *\n * Returns a statement store with `subscribe`, `createProof`, and `submit` methods\n * that communicate through the host's native binary protocol — bypassing JSON-RPC\n * entirely. Returns `null` when `@novasamatech/product-sdk` is unavailable.\n *\n * @returns The host statement store, or `null` if unavailable.\n */\nexport async function getStatementStore(): Promise<HostStatementStore | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createStatementStore() as HostStatementStore;\n    } catch {\n        return null;\n    }\n}\n\nif (import.meta.vitest) {\n    const { test, expect, vi } = import.meta.vitest;\n\n    test(\"returns false in Node environment (no window)\", async () => {\n        expect(await isInsideContainer()).toBe(false);\n    });\n\n    test(\"manualDetection returns true for __HOST_WEBVIEW_MARK__\", async () => {\n        const fakeWindow = {\n            top: null,\n            __HOST_WEBVIEW_MARK__: true,\n        };\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true for __HOST_API_PORT__\", async () => {\n        const fakeWindow = {\n            top: null,\n            __HOST_API_PORT__: 12345,\n        };\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns false when no signals present\", async () => {\n        const fakeWindow = { top: null };\n        Object.defineProperty(fakeWindow, \"top\", { get: () => fakeWindow });\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(false);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true for cross-origin iframe\", async () => {\n        const fakeWindow = {};\n        Object.defineProperty(fakeWindow, \"top\", {\n            get: () => {\n                throw new DOMException(\"cross-origin\");\n            },\n        });\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"manualDetection returns true when window !== window.top (iframe)\", async () => {\n        const fakeWindow = { top: {} }; // top is a different object\n        vi.stubGlobal(\"window\", fakeWindow);\n        const result = await isInsideContainer();\n        expect(result).toBe(true);\n        vi.unstubAllGlobals();\n    });\n\n    test(\"getHostLocalStorage returns null outside container\", async () => {\n        expect(await getHostLocalStorage()).toBeNull();\n    });\n\n    test(\"getHostProvider returns null when product-sdk unavailable\", async () => {\n        const result = await getHostProvider(\"0xabc\");\n        expect(result).toBeNull();\n    });\n\n    test(\"getStatementStore returns null when product-sdk unavailable\", async () => {\n        const result = await getStatementStore();\n        expect(result).toBeNull();\n    });\n}\n","/**\n * Shared chain network configuration — single source of truth for\n * chain-specific endpoints used by multiple packages.\n */\n\n/**\n * Bulletin Chain RPC endpoints per network environment. Only `paseo` is\n * populated today; `polkadot` and `kusama` are reserved for when those\n * Bulletin deployments go live.\n */\nexport const BULLETIN_RPCS = {\n    paseo: [\"wss://paseo-bulletin-rpc.polkadot.io\"],\n    polkadot: [] as string[],\n    kusama: [] as string[],\n} as const;\n\n/** Default Bulletin Chain endpoint — the first entry under {@link BULLETIN_RPCS}.paseo. */\nexport const DEFAULT_BULLETIN_ENDPOINT: string = BULLETIN_RPCS.paseo[0];\n\nif (import.meta.vitest) {\n    const { describe, test, expect } = import.meta.vitest;\n\n    describe(\"chains config\", () => {\n        test(\"BULLETIN_RPCS has paseo endpoint\", () => {\n            expect(BULLETIN_RPCS.paseo.length).toBeGreaterThan(0);\n            expect(BULLETIN_RPCS.paseo[0]).toMatch(/^wss:\\/\\//);\n        });\n\n        test(\"BULLETIN_RPCS polkadot and kusama are empty until live\", () => {\n            expect(BULLETIN_RPCS.polkadot).toEqual([]);\n            expect(BULLETIN_RPCS.kusama).toEqual([]);\n        });\n\n        test(\"DEFAULT_BULLETIN_ENDPOINT matches first paseo endpoint\", () => {\n            expect(DEFAULT_BULLETIN_ENDPOINT).toBe(BULLETIN_RPCS.paseo[0]);\n        });\n    });\n}\n","/**\n * TruAPI - the protocol for communicating between apps and the Polkadot host container.\n *\n * This module centralizes access to @novasamatech/product-sdk and @novasamatech/host-api,\n * allowing other @parity/product-sdk-* packages to import from here rather than depending\n * directly on novasama packages.\n *\n * @module\n */\n\nimport { createLogger } from \"@parity/product-sdk-logger\";\n\nconst log = createLogger(\"host\");\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Helpers from @novasamatech/host-api (re-exported from @novasamatech/scale)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport {\n    /**\n     * Construct an enum variant for TruAPI calls.\n     *\n     * @example\n     * ```ts\n     * import { enumValue, getTruApi } from \"@parity/product-sdk-host\";\n     *\n     * const truApi = await getTruApi();\n     * if (truApi) {\n     *   await truApi.permission([enumValue(\"ChainSubmit\")]);\n     * }\n     * ```\n     */\n    enumValue,\n    /**\n     * Check if a value is a specific enum variant.\n     */\n    isEnumVariant,\n    /**\n     * Assert that a value is a specific enum variant, throwing if not.\n     */\n    assertEnumVariant,\n    /**\n     * Unwrap a Result, throwing on error.\n     */\n    unwrapResultOrThrow,\n    /**\n     * Create an Ok result.\n     */\n    resultOk,\n    /**\n     * Create an Err result.\n     */\n    resultErr,\n    /**\n     * Convert bytes to hex string.\n     */\n    toHex,\n    /**\n     * Convert hex string to bytes.\n     */\n    fromHex,\n} from \"@novasamatech/host-api\";\n\n/** A `0x`-prefixed hex string (the template literal type ``\\`0x${string}\\``) used by the host API surface for raw byte payloads. Re-exported from `@novasamatech/host-api` so consumers bridging between host APIs and SDK code can reach the host-side type without an additional dependency. */\nexport type { HexString } from \"@novasamatech/host-api\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// TruAPI accessor\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The TruApi type - provides low-level methods for communicating with the host.\n *\n * Methods include:\n * - `navigateTo(url)` — Navigate to a URL within the host\n * - `permission(permissions)` — Request permissions from the host\n * - `localStorageRead/Write/Clear` — Host-backed storage\n * - `sign(payload)` — Request transaction signing\n * - `deriveEntropy(context)` — Derive deterministic entropy\n * - `themeSubscribe()` — Subscribe to host theme changes\n * - And many more...\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type TruApi = any;\n\n/** Cached TruApi instance */\nlet cachedTruApi: TruApi | null = null;\n\n/**\n * Get the TruAPI instance for direct low-level access.\n *\n * Returns the `hostApi` object from `@novasamatech/product-sdk` which provides\n * methods for communicating directly with the host container. Returns `null`\n * when running outside a container or when the SDK is unavailable.\n *\n * For most use cases, prefer the higher-level functions like `getHostLocalStorage()`,\n * `getHostProvider()`, etc. Use this when you need direct access to host methods\n * like `navigateTo()`, `permission()`, or `deriveEntropy()`.\n *\n * @example\n * ```ts\n * import { getTruApi, enumValue } from \"@parity/product-sdk-host\";\n *\n * const truApi = await getTruApi();\n * if (truApi) {\n *   // Request permission\n *   const result = await truApi.permission([enumValue(\"ChainSubmit\")]);\n *\n *   // Navigate to a URL\n *   await truApi.navigateTo(\"polkadot://settings\");\n *\n *   // Subscribe to theme changes\n *   const sub = truApi.themeSubscribe(undefined, (theme) => {\n *     console.log(\"Theme changed:\", theme);\n *   });\n * }\n * ```\n *\n * @returns The TruAPI instance, or `null` if unavailable.\n */\nexport async function getTruApi(): Promise<TruApi | null> {\n    if (cachedTruApi) return cachedTruApi;\n\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        cachedTruApi = sdk.hostApi;\n        log.debug(\"TruAPI loaded\");\n        return cachedTruApi;\n    } catch {\n        log.debug(\"TruAPI unavailable (not in container or SDK not installed)\");\n        return null;\n    }\n}\n\n/**\n * Get the preimage manager for bulletin chain operations.\n *\n * The preimage manager handles uploading and looking up preimages (arbitrary data)\n * on the bulletin chain through the host's optimized path.\n *\n * @returns The preimage manager, or `null` if unavailable.\n *\n * @example\n * ```ts\n * import { getPreimageManager } from \"@parity/product-sdk-host\";\n *\n * const manager = await getPreimageManager();\n * if (manager) {\n *   // Submit a preimage\n *   const key = await manager.submit(new Uint8Array([1, 2, 3]));\n *\n *   // Look up a preimage\n *   const sub = manager.lookup(key, (data) => {\n *     if (data) console.log(\"Found:\", data);\n *   });\n * }\n * ```\n */\nexport async function getPreimageManager(): Promise<PreimageManager | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.preimageManager;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Preimage manager interface for bulletin chain operations.\n */\nexport interface PreimageManager {\n    /**\n     * Submit a preimage to the bulletin chain.\n     * @param data - The data to submit.\n     * @returns The preimage key (hex string).\n     */\n    submit(data: Uint8Array): Promise<string>;\n\n    /**\n     * Look up a preimage by key.\n     * @param key - The preimage key (hex string).\n     * @param callback - Called with the data when found, or null if not yet available.\n     * @returns Subscription handle with unsubscribe method.\n     */\n    lookup(\n        key: string,\n        callback: (preimage: Uint8Array | null) => void,\n    ): { unsubscribe: () => void; onInterrupt: (cb: () => void) => () => void };\n}\n\n/**\n * Get the accounts provider for managing host accounts.\n *\n * @returns The accounts provider, or `null` if unavailable.\n */\nexport async function getAccountsProvider(): Promise<AccountsProvider | null> {\n    try {\n        const sdk = await import(\"@novasamatech/product-sdk\");\n        return sdk.createAccountsProvider() as unknown as AccountsProvider;\n    } catch {\n        return null;\n    }\n}\n\n/**\n * One of the user's existing wallet accounts, surfaced through the host and\n * identified by its public key and an optional name. Contrast with\n * {@link ProductAccount}, which is also user-controlled but derived by the\n * host for a specific app rather than picked from the user's existing keys.\n */\nexport interface HostAccount {\n    publicKey: Uint8Array;\n    name?: string;\n}\n\n/**\n * A product account — an app-scoped derived account managed by the host wallet.\n *\n * The host derives a unique keypair for each app (identified by `dotNsIdentifier`)\n * so apps get their own account that the user controls but is scoped to the app.\n */\nexport interface ProductAccount {\n    /** App identifier (e.g., \"mark3t.dot\"). */\n    dotNsIdentifier: string;\n    /** Derivation index within the app scope. Default: 0 */\n    derivationIndex: number;\n    /** Raw public key (32 bytes). */\n    publicKey: Uint8Array;\n}\n\n/**\n * A contextual alias obtained from Ring VRF.\n *\n * Proves account membership in a ring without revealing which account.\n */\nexport interface ContextualAlias {\n    /** Ring context (32 bytes). */\n    context: Uint8Array;\n    /** The Ring VRF alias bytes. */\n    alias: Uint8Array;\n}\n\n/**\n * Neverthrow-style ResultAsync returned by product-sdk methods.\n *\n * Use `.match(onOk, onErr)` to handle success/error cases.\n */\nexport interface ResultAsync<T, E> {\n    match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;\n}\n\n/**\n * Accounts provider interface from @novasamatech/product-sdk.\n *\n * Provides methods for accessing host wallet accounts, product accounts,\n * and Ring VRF operations.\n */\nexport interface AccountsProvider {\n    /**\n     * Get legacy accounts (user's external wallets connected to the host).\n     *\n     * Renamed from `getNonProductAccounts` in @novasamatech/product-sdk 0.7.\n     *\n     * @returns ResultAsync resolving to array of accounts.\n     */\n    getLegacyAccounts: () => ResultAsync<HostAccount[], unknown>;\n\n    /**\n     * Get a signer for a legacy account.\n     *\n     * Renamed from `getNonProductAccountSigner` in @novasamatech/product-sdk 0.7.\n     *\n     * @param account - The product account (used for public key lookup).\n     * @returns A PolkadotSigner for signing transactions.\n     */\n    getLegacyAccountSigner: (account: ProductAccount) => import(\"polkadot-api\").PolkadotSigner;\n\n    /**\n     * Get an app-scoped product account from the host.\n     *\n     * Product accounts are derived by the host wallet for each app, identified\n     * by `dotNsIdentifier` (e.g., \"mark3t.dot\"). The user controls these accounts\n     * but they are scoped to the requesting app.\n     *\n     * @param dotNsIdentifier - App identifier (e.g., \"mark3t.dot\").\n     * @param derivationIndex - Derivation index within the app scope. Default: 0\n     * @returns ResultAsync resolving to the account.\n     */\n    getProductAccount: (\n        dotNsIdentifier: string,\n        derivationIndex?: number,\n    ) => ResultAsync<HostAccount, unknown>;\n\n    /**\n     * Get a signer for a product account.\n     *\n     * @param account - The product account.\n     * @returns A PolkadotSigner for signing transactions.\n     */\n    getProductAccountSigner: (account: ProductAccount) => import(\"polkadot-api\").PolkadotSigner;\n\n    /**\n     * Get a contextual alias for a product account via Ring VRF.\n     *\n     * Aliases prove account membership in a ring without revealing which\n     * account produced the alias.\n     *\n     * @param dotNsIdentifier - App identifier.\n     * @param derivationIndex - Derivation index. Default: 0\n     * @returns ResultAsync resolving to the contextual alias.\n     */\n    getProductAccountAlias: (\n        dotNsIdentifier: string,\n        derivationIndex?: number,\n    ) => ResultAsync<ContextualAlias, unknown>;\n\n    /**\n     * Create a Ring VRF proof for anonymous operations.\n     *\n     * Proves that the signer is a member of the ring at the given location\n     * without revealing which member.\n     *\n     * @param dotNsIdentifier - App identifier.\n     * @param derivationIndex - Derivation index.\n     * @param location - Ring location on-chain.\n     * @param message - Message to sign.\n     * @returns ResultAsync resolving to the proof bytes.\n     */\n    createRingVRFProof: (\n        dotNsIdentifier: string,\n        derivationIndex: number,\n        location: unknown,\n        message: Uint8Array,\n    ) => ResultAsync<Uint8Array, unknown>;\n\n    /**\n     * Subscribe to account connection status changes.\n     *\n     * @param callback - Called with status string (\"connected\" | \"disconnected\").\n     * @returns Unsubscribe handle.\n     */\n    subscribeAccountConnectionStatus: (\n        callback: (status: string) => void,\n    ) => { unsubscribe: () => void } | (() => void);\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tests\n// ─────────────────────────────────────────────────────────────────────────────\n\nif (import.meta.vitest) {\n    const { test, expect } = import.meta.vitest;\n\n    test(\"getTruApi returns TruApi when SDK is available\", async () => {\n        // Reset cache for test\n        cachedTruApi = null;\n        const api = await getTruApi();\n        // In dev/test mode, product-sdk is installed\n        expect(api === null || typeof api === \"object\").toBe(true);\n    });\n\n    test(\"getPreimageManager returns manager when SDK is available\", async () => {\n        const manager = await getPreimageManager();\n        // In dev/test mode, product-sdk is installed\n        expect(manager === null || typeof manager === \"object\").toBe(true);\n    });\n\n    test(\"getAccountsProvider returns provider when SDK is available\", async () => {\n        // In dev/test mode, product-sdk is installed, so this returns a provider\n        const provider = await getAccountsProvider();\n        // Just verify it returns something (null when SDK unavailable, provider when available)\n        expect(provider === null || typeof provider === \"object\").toBe(true);\n    });\n\n    test(\"enumValue is exported\", async () => {\n        const { enumValue } = await import(\"./truapi.js\");\n        expect(typeof enumValue).toBe(\"function\");\n    });\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/product-sdk-host",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Host container detection and storage access for Polkadot Desktop and Mobile environments",
   "type": "module",
   "sideEffects": false,
@@ -18,8 +18,8 @@
     "src"
   ],
   "dependencies": {
-    "polkadot-api": "^1.9.0",
-    "@parity/product-sdk-logger": "0.1.0"
+    "polkadot-api": "^2.1.2",
+    "@parity/product-sdk-logger": "0.1.1"
   },
   "peerDependencies": {
     "@novasamatech/product-sdk": ">=0.1.0",
@@ -34,8 +34,8 @@
     }
   },
   "devDependencies": {
-    "@novasamatech/product-sdk": "^0.6.17",
-    "@novasamatech/host-api": "^0.7.0",
+    "@novasamatech/product-sdk": "^0.7.7",
+    "@novasamatech/host-api": "^0.7.7",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },

package/src/chains.ts

@@ -3,14 +3,18 @@
  * chain-specific endpoints used by multiple packages.
  */
 
-/** Bulletin chain RPC endpoints by environment. */
+/**
+ * Bulletin Chain RPC endpoints per network environment. Only `paseo` is
+ * populated today; `polkadot` and `kusama` are reserved for when those
+ * Bulletin deployments go live.
+ */
 export const BULLETIN_RPCS = {
     paseo: ["wss://paseo-bulletin-rpc.polkadot.io"],
     polkadot: [] as string[],
     kusama: [] as string[],
 } as const;
 
-/** Default bulletin endpoint (first paseo endpoint). */
+/** 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) {

package/src/container.ts

@@ -1,4 +1,4 @@
-import type { JsonRpcProvider } from "polkadot-api/ws-provider/web";
+import type { JsonRpcProvider } from "polkadot-api";
 
 import type { HostLocalStorage, HostStatementStore } from "./types.js";
 

package/src/index.ts

@@ -1,3 +1,12 @@
+/**
+ * @parity/product-sdk-host — Detect and talk to the Polkadot Desktop/Mobile host container.
+ *
+ * Use `isInsideContainer` to branch behavior when running embedded vs. standalone,
+ * and `getHostLocalStorage`, `getHostProvider`, and `getStatementStore` to reach
+ * the storage, signer, and statement-store APIs the host injects.
+ *
+ * @packageDocumentation
+ */
 export {
     isInsideContainer,
     isInsideContainerSync,
@@ -5,7 +14,14 @@ export {
     getHostProvider,
     getStatementStore,
 } from "./container.js";
-export type { HostLocalStorage, HostStatementStore, StatementProof } from "./types.js";
+export type {
+    HostLocalStorage,
+    HostStatementStore,
+    HostSubscription,
+    StatementProof,
+    StatementTopicFilter,
+    StatementsPage,
+} from "./types.js";
 export { BULLETIN_RPCS, DEFAULT_BULLETIN_ENDPOINT } from "./chains.js";
 
 // TruAPI - re-exports from @novasamatech/product-sdk and @novasamatech/host-api

package/src/truapi.ts

@@ -61,6 +61,7 @@ export {
     fromHex,
 } from "@novasamatech/host-api";
 
+/** A `0x`-prefixed hex string (the template literal type ``\`0x${string}\``) used by the host API surface for raw byte payloads. Re-exported from `@novasamatech/host-api` so consumers bridging between host APIs and SDK code can reach the host-side type without an additional dependency. */
 export type { HexString } from "@novasamatech/host-api";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -202,7 +203,10 @@ export async function getAccountsProvider(): Promise<AccountsProvider | null> {
 }
 
 /**
- * Account from the host wallet.
+ * One of the user's existing wallet accounts, surfaced through the host and
+ * identified by its public key and an optional name. Contrast with
+ * {@link ProductAccount}, which is also user-controlled but derived by the
+ * host for a specific app rather than picked from the user's existing keys.
  */
 export interface HostAccount {
     publicKey: Uint8Array;
@@ -253,19 +257,23 @@ export interface ResultAsync<T, E> {
  */
 export interface AccountsProvider {
     /**
-     * Get non-product accounts (user's external wallets connected to the host).
+     * Get legacy accounts (user's external wallets connected to the host).
+     *
+     * Renamed from `getNonProductAccounts` in @novasamatech/product-sdk 0.7.
      *
      * @returns ResultAsync resolving to array of accounts.
      */
-    getNonProductAccounts: () => ResultAsync<HostAccount[], unknown>;
+    getLegacyAccounts: () => ResultAsync<HostAccount[], unknown>;
 
     /**
-     * Get a signer for a non-product account.
+     * Get a signer for a legacy account.
+     *
+     * Renamed from `getNonProductAccountSigner` in @novasamatech/product-sdk 0.7.
      *
      * @param account - The product account (used for public key lookup).
      * @returns A PolkadotSigner for signing transactions.
      */
-    getNonProductAccountSigner: (account: ProductAccount) => import("polkadot-api").PolkadotSigner;
+    getLegacyAccountSigner: (account: ProductAccount) => import("polkadot-api").PolkadotSigner;
 
     /**
      * Get an app-scoped product account from the host.

package/src/types.ts

@@ -1,4 +1,9 @@
-/** Subset of product-sdk's hostLocalStorage that the KV store uses. */
+/**
+ * Persistent string and JSON storage exposed by the host container. Most
+ * apps reach it indirectly through the Storage package's `KvStore`; reach for
+ * it directly via {@link getHostLocalStorage} when you need raw host storage
+ * without the KV abstraction.
+ */
 export interface HostLocalStorage {
     readString(key: string): Promise<string | null>;
     writeString(key: string, value: string): Promise<void>;
@@ -11,37 +16,85 @@ export interface HostLocalStorage {
     clear(key: string): Promise<void>;
 }
 
-/** Proof types returned from createProof (matches product-sdk SCALE-decoded types). */
+/**
+ * Cryptographic proof attached to a statement before submission, returned by
+ * {@link HostStatementStore.createProof}. Variants cover the supported
+ * signature schemes — `Sr25519`, `Ed25519`, `Ecdsa`, and `OnChain` (chain-
+ * attestation-based proofs).
+ *
+ * Mirrors `@novasamatech/product-sdk@0.7`'s proof shape.
+ */
 export type StatementProof =
     | { tag: "Sr25519"; value: { signature: Uint8Array; signer: Uint8Array } }
     | { tag: "Ed25519"; value: { signature: Uint8Array; signer: Uint8Array } }
-    | { tag: "Secp256k1Ecdsa"; value: { signature: Uint8Array; signer: Uint8Array } }
-    | { tag: "EcdsaRecoverable"; value: { signature: Uint8Array } };
+    | { tag: "Ecdsa"; value: { signature: Uint8Array; signer: Uint8Array } }
+    | {
+          tag: "OnChain";
+          value: { who: Uint8Array; blockHash: Uint8Array; event: bigint };
+      };
 
-/** The statement store interface provided by the host API via product-sdk. */
+/**
+ * Topic-based subscription filter. Mirrors `StatementTopicFilter` from
+ * `@novasamatech/product-sdk` — the host delivers statements that match
+ * either *all* of the listed topics (`matchAll`) or *any* of them
+ * (`matchAny`).
+ */
+export type StatementTopicFilter = { matchAll: Uint8Array[] } | { matchAny: Uint8Array[] };
+
+/**
+ * A page of signed statements delivered by {@link HostStatementStore.subscribe}.
+ *
+ * Pages arrive sequentially. `isComplete` is `true` on the final page of a
+ * subscription's initial backfill; subsequent pages contain new statements
+ * as they appear on chain.
+ */
+export interface StatementsPage {
+    statements: unknown[];
+    isComplete: boolean;
+}
+
+/** Subscription handle returned by the host. */
+export interface HostSubscription {
+    unsubscribe: () => void;
+}
+
+/**
+ * Statement Store handle exposed by the host container. Provides
+ * `subscribe`, `createProof`, and `submit` operations that go through the
+ * host's native binary protocol; the `statement-store` package layers a
+ * higher-level client on top.
+ *
+ * Shape matches `@novasamatech/product-sdk@0.7`'s `createStatementStore()`.
+ */
 export interface HostStatementStore {
     /**
-     * Subscribe to statements matching the given topics.
-     * @param topics - Topic filters as Uint8Array[]
-     * @param callback - Called with batches of SignedStatement[]
-     * @returns Subscription object with unsubscribe method
+     * Subscribe to statements matching the given topic filter.
+     *
+     * The callback is invoked once per page of statements. After the initial
+     * backfill completes (signaled by `page.isComplete === true`), subsequent
+     * pages contain new statements as they're produced.
+     *
+     * @param filter   - Topic match filter (`matchAll` or `matchAny`).
+     * @param callback - Called with each `StatementsPage` from the host.
+     * @returns Subscription handle with `unsubscribe`.
      */
     subscribe(
-        topics: Uint8Array[],
-        callback: (statements: unknown[]) => void,
-    ): { unsubscribe: () => void };
+        filter: StatementTopicFilter,
+        callback: (page: StatementsPage) => void,
+    ): HostSubscription;
 
     /**
      * Create a proof for a statement using the given account.
-     * @param accountId - The account ID tuple [ss58Address, chainPrefix] from product-sdk
-     * @param statement - The unsigned statement
-     * @returns The proof (signature + signer info)
+     *
+     * @param accountId - The account ID tuple `[ss58Address, chainPrefix]` from product-sdk.
+     * @param statement - The unsigned statement.
+     * @returns The proof (signature + signer info, or chain-attestation reference).
      */
     createProof(accountId: [string, number], statement: unknown): Promise<StatementProof>;
 
     /**
      * Submit a signed statement to the bulletin chain.
-     * @param signedStatement - Statement with attached proof
+     * @param signedStatement - Statement with attached proof.
      */
     submit(signedStatement: unknown): Promise<void>;
 }