@parity/product-sdk-host 0.1.0

package/dist/index.js

@@ -0,0 +1,219 @@
+// src/container.ts
+async function isInsideContainer() {
+  if (typeof window === "undefined") return false;
+  try {
+    const sdk = await import("@novasamatech/product-sdk");
+    return sdk.sandboxProvider.isCorrectEnvironment();
+  } catch {
+    return isInsideContainerSync();
+  }
+}
+async function getHostLocalStorage() {
+  if (!await isInsideContainer()) return null;
+  try {
+    const sdk = await import("@novasamatech/product-sdk");
+    return sdk.hostLocalStorage;
+  } catch {
+    return null;
+  }
+}
+async function getHostProvider(genesisHash) {
+  try {
+    const sdk = await import("@novasamatech/product-sdk");
+    return sdk.createPapiProvider(genesisHash);
+  } catch {
+    return null;
+  }
+}
+function isInsideContainerSync() {
+  if (typeof window === "undefined") return false;
+  const win = window;
+  try {
+    if (window !== window.top) return true;
+  } catch {
+    return true;
+  }
+  if (win.__HOST_WEBVIEW_MARK__ === true) return true;
+  if (win.__HOST_API_PORT__ != null) return true;
+  return false;
+}
+async function getStatementStore() {
+  try {
+    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 = {
+  paseo: ["wss://paseo-bulletin-rpc.polkadot.io"],
+  polkadot: [],
+  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");
+    cachedTruApi = sdk.hostApi;
+    log.debug("TruAPI loaded");
+    return cachedTruApi;
+  } catch {
+    log.debug("TruAPI unavailable (not in container or SDK not installed)");
+    return null;
+  }
+}
+async function getPreimageManager() {
+  try {
+    const sdk = await import("@novasamatech/product-sdk");
+    return sdk.preimageManager;
+  } catch {
+    return null;
+  }
+}
+async function getAccountsProvider() {
+  try {
+    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
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@parity/product-sdk-host",
+  "version": "0.1.0",
+  "description": "Host container detection and storage access for Polkadot Desktop and Mobile environments",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "polkadot-api": "^1.9.0",
+    "@parity/product-sdk-logger": "0.1.0"
+  },
+  "peerDependencies": {
+    "@novasamatech/product-sdk": ">=0.1.0",
+    "@novasamatech/host-api": ">=0.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@novasamatech/product-sdk": {
+      "optional": true
+    },
+    "@novasamatech/host-api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@novasamatech/product-sdk": "^0.6.17",
+    "@novasamatech/host-api": "^0.7.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "clean": "rm -rf dist"
+  }
+}

package/src/chains.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared chain network configuration — single source of truth for
+ * chain-specific endpoints used by multiple packages.
+ */
+
+/** Bulletin chain RPC endpoints by environment. */
+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). */
+export const DEFAULT_BULLETIN_ENDPOINT: string = BULLETIN_RPCS.paseo[0];
+
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+
+    describe("chains config", () => {
+        test("BULLETIN_RPCS has paseo endpoint", () => {
+            expect(BULLETIN_RPCS.paseo.length).toBeGreaterThan(0);
+            expect(BULLETIN_RPCS.paseo[0]).toMatch(/^wss:\/\//);
+        });
+
+        test("BULLETIN_RPCS polkadot and kusama are empty until live", () => {
+            expect(BULLETIN_RPCS.polkadot).toEqual([]);
+            expect(BULLETIN_RPCS.kusama).toEqual([]);
+        });
+
+        test("DEFAULT_BULLETIN_ENDPOINT matches first paseo endpoint", () => {
+            expect(DEFAULT_BULLETIN_ENDPOINT).toBe(BULLETIN_RPCS.paseo[0]);
+        });
+    });
+}

package/src/container.ts

@@ -0,0 +1,178 @@
+import type { JsonRpcProvider } from "polkadot-api/ws-provider/web";
+
+import type { HostLocalStorage, HostStatementStore } from "./types.js";
+
+/**
+ * Detect if running inside a Host container (Polkadot Browser / Polkadot Desktop).
+ *
+ * The SDK is designed to run exclusively inside a host container. This function
+ * is primarily useful for early validation or informational purposes.
+ *
+ * Uses product-sdk's sandboxProvider as primary detection.
+ * Falls back to manual signal checks when product-sdk is not installed.
+ */
+export async function isInsideContainer(): Promise<boolean> {
+    if (typeof window === "undefined") return false;
+
+    try {
+        const sdk = await import("@novasamatech/product-sdk");
+        return sdk.sandboxProvider.isCorrectEnvironment();
+    } catch {
+        return isInsideContainerSync();
+    }
+}
+
+/**
+ * Get the Host API localStorage instance when running inside a container.
+ * Returns null outside a container or when product-sdk is unavailable.
+ */
+export async function getHostLocalStorage(): Promise<HostLocalStorage | null> {
+    if (!(await isInsideContainer())) return null;
+
+    try {
+        const sdk = await import("@novasamatech/product-sdk");
+        return sdk.hostLocalStorage as HostLocalStorage;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Get a PAPI-compatible JSON-RPC provider that routes through the host connection.
+ *
+ * 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.
+ *
+ * @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");
+        return sdk.createPapiProvider(genesisHash);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Synchronous container detection — fast heuristic check without product-sdk.
+ *
+ * Checks for iframe, webview marker, and host message port signals.
+ * Use this when you need a quick sync check (e.g., in hot code paths).
+ * For full detection including product-sdk, use {@link isInsideContainer} (async).
+ */
+export function isInsideContainerSync(): boolean {
+    if (typeof window === "undefined") return false;
+
+    const win = window as unknown as Record<string, unknown>;
+
+    // Iframe detection (polkadot.com browser)
+    try {
+        if (window !== window.top) return true;
+    } catch {
+        // Cross-origin iframe — likely inside a container
+        return true;
+    }
+
+    // Webview detection (Polkadot Desktop)
+    if (win.__HOST_WEBVIEW_MARK__ === true) return true;
+
+    // Desktop message-passing API
+    if (win.__HOST_API_PORT__ != null) return true;
+
+    return false;
+}
+
+/**
+ * Get the host API statement store when running inside a container.
+ *
+ * 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.
+ *
+ * @returns The host statement store, or `null` if unavailable.
+ */
+export async function getStatementStore(): Promise<HostStatementStore | null> {
+    try {
+        const sdk = await import("@novasamatech/product-sdk");
+        return sdk.createStatementStore() as HostStatementStore;
+    } catch {
+        return null;
+    }
+}
+
+if (import.meta.vitest) {
+    const { test, expect, vi } = import.meta.vitest;
+
+    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: {} }; // top is a different object
+        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();
+    });
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export {
+    isInsideContainer,
+    isInsideContainerSync,
+    getHostLocalStorage,
+    getHostProvider,
+    getStatementStore,
+} from "./container.js";
+export type { HostLocalStorage, HostStatementStore, StatementProof } from "./types.js";
+export { BULLETIN_RPCS, DEFAULT_BULLETIN_ENDPOINT } from "./chains.js";
+
+// TruAPI - re-exports from @novasamatech/product-sdk and @novasamatech/host-api
+export {
+    getTruApi,
+    getPreimageManager,
+    getAccountsProvider,
+    // Helpers from @novasamatech/host-api
+    enumValue,
+    isEnumVariant,
+    assertEnumVariant,
+    unwrapResultOrThrow,
+    resultOk,
+    resultErr,
+    toHex,
+    fromHex,
+} from "./truapi.js";
+export type {
+    TruApi,
+    HexString,
+    PreimageManager,
+    AccountsProvider,
+    HostAccount,
+    ProductAccount,
+    ContextualAlias,
+    ResultAsync,
+} from "./truapi.js";