@parity/product-sdk-host 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,120 +1,78 @@
-import * as polkadot_api from 'polkadot-api';
 import { JsonRpcProvider } from 'polkadot-api';
-import { CodecType, AllocatableResource as AllocatableResource$1, AllocationOutcome as AllocationOutcome$1 } from '@novasamatech/host-api';
+import * as _novasamatech_host_api from '@novasamatech/host-api';
+import { Subscription, Transport, CodecType, AllocatableResource as AllocatableResource$1, AllocationOutcome as AllocationOutcome$1, RemotePermission as RemotePermission$1, DevicePermission } from '@novasamatech/host-api';
 export { HexString, assertEnumVariant, enumValue, fromHex, isEnumVariant, resultErr, resultOk, toHex, unwrapResultOrThrow } from '@novasamatech/host-api';
+import * as _novasamatech_host_api_wrapper from '@novasamatech/host-api-wrapper';
+import { hostLocalStorage, createStatementStore, ProductAccountId as ProductAccountId$1, SignedStatement as SignedStatement$1, Statement as Statement$1, StatementTopicFilter as StatementTopicFilter$1, StatementsPage as StatementsPage$1, Topic as Topic$1, createAccountsProvider, preimageManager, ThemeMode as ThemeMode$1, createThemeProvider, ChatBotRegistrationResult as ChatBotRegistrationResult$1, ChatCustomMessageRenderer as ChatCustomMessageRenderer$1, ChatCustomMessageRendererParams as ChatCustomMessageRendererParams$1, createProductChatManager, ChatMessageContent as ChatMessageContent$1, ChatReceivedAction as ChatReceivedAction$1, ChatRoom as ChatRoom$1, ChatRoomRegistrationResult as ChatRoomRegistrationResult$1, PaymentBalance as PaymentBalance$1, paymentManager, PaymentStatus as PaymentStatus$1, TopUpSource as TopUpSource$1 } from '@novasamatech/host-api-wrapper';
 
 /**
- * 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>;
-    readJSON<T>(key: string): Promise<T | null>;
-    writeJSON<T>(key: string, value: T): Promise<void>;
-    /**
-     * Clear a specific key from storage.
-     * @param key - The key to clear
-     */
-    clear(key: string): Promise<void>;
-}
+ * Public types for the host wrappers.
+ *
+ * These are re-exported from `@novasamatech/host-api-wrapper` (the runtime
+ * objects the host getters cast to) rather than hand-mirrored, so the
+ * Parity surface stays in lockstep with the upstream codec types.
+ */
+
+/**
+ * Persistent storage exposed by the host container, including string, JSON
+ * and raw byte (`readBytes`/`writeBytes`) accessors. 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.
+ *
+ * Type identical to `hostLocalStorage` from `@novasamatech/host-api-wrapper`.
+ */
+type HostLocalStorage = typeof hostLocalStorage;
 /**
  * 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-
+ * 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: {
-        signature: Uint8Array;
-        signer: Uint8Array;
-    };
-} | {
-    tag: "Ed25519";
-    value: {
-        signature: Uint8Array;
-        signer: Uint8Array;
-    };
-} | {
-    tag: "Ecdsa";
-    value: {
-        signature: Uint8Array;
-        signer: Uint8Array;
-    };
-} | {
-    tag: "OnChain";
-    value: {
-        who: Uint8Array;
-        blockHash: Uint8Array;
-        event: bigint;
-    };
-};
+ * Inferred from `createStatementStore().createProof`'s return type so codec
+ * changes surface here as compile errors, not runtime decode failures.
+ */
+type StatementProof = Awaited<ReturnType<ReturnType<typeof createStatementStore>["createProof"]>>;
 /**
- * Topic-based subscription filter. Mirrors `StatementTopicFilter` from
- * `@novasamatech/product-sdk` — the host delivers statements that match
+ * Topic-based subscription filter. The host delivers statements that match
  * either *all* of the listed topics (`matchAll`) or *any* of them
- * (`matchAny`).
+ * (`matchAny`). Re-exported from `@novasamatech/host-api-wrapper`.
  */
-type StatementTopicFilter = {
-    matchAll: Uint8Array[];
-} | {
-    matchAny: Uint8Array[];
-};
+type StatementTopicFilter = StatementTopicFilter$1;
+/** A single topic value used inside a {@link StatementTopicFilter}. Re-exported from `@novasamatech/host-api-wrapper`. */
+type Topic = Topic$1;
+/** `[ss58Address, chainPrefix]` tuple identifying a product account at the codec layer. Re-exported from `@novasamatech/host-api-wrapper`. */
+type ProductAccountId = ProductAccountId$1;
+/** Unsigned statement payload. Re-exported from `@novasamatech/host-api-wrapper`. */
+type Statement = Statement$1;
+/** Statement bundled with its {@link StatementProof}. Re-exported from `@novasamatech/host-api-wrapper`. */
+type SignedStatement = SignedStatement$1;
 /**
  * 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.
+ * as they appear on chain. `statements` is `SignedStatement[]` (typed,
+ * not `unknown[]`).
  */
-interface StatementsPage {
-    statements: unknown[];
-    isComplete: boolean;
-}
-/** Subscription handle returned by the host. */
-interface HostSubscription {
-    unsubscribe: () => void;
-}
+type StatementsPage = StatementsPage$1;
+/**
+ * Subscription handle returned by the host - equivalent to
+ * `Subscription<void>` from `@novasamatech/host-api`. Exposes
+ * `unsubscribe()` plus an `onInterrupt` hook that fires if the host
+ * interrupts the subscription server-side.
+ */
+type HostSubscription = Subscription<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 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(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, 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.
-     */
-    submit(signedStatement: unknown): Promise<void>;
-}
+ * Type identical to `createStatementStore()` from
+ * `@novasamatech/host-api-wrapper`.
+ */
+type HostStatementStore = ReturnType<typeof createStatementStore>;
 
 /**
  * Detect if running inside a Host container (Polkadot Browser / Polkadot Desktop).
@@ -131,12 +89,24 @@ declare function isInsideContainer(): Promise<boolean>;
  * Returns null outside a container or when product-sdk is unavailable.
  */
 declare function getHostLocalStorage(): Promise<HostLocalStorage | null>;
+/**
+ * Construct a fresh host-backed `HostLocalStorage` instance with an optional
+ * custom transport. Use this when you need a non-default transport (e.g.
+ * for tests); otherwise prefer {@link getHostLocalStorage}, which returns
+ * the shared singleton.
+ *
+ * Mirrors `createLocalStorage` from `@novasamatech/host-api-wrapper`.
+ *
+ * @param transport - Optional transport; defaults to the sandbox transport.
+ * @returns A new `HostLocalStorage` instance, or `null` if unavailable.
+ */
+declare function createHostLocalStorage(transport?: Transport): Promise<HostLocalStorage | 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.
+ * Returns `null` when `@novasamatech/host-api-wrapper` is unavailable.
  *
  * @param genesisHash - Genesis hash of the target chain (`0x`-prefixed hex string).
  * @returns A host-routed `JsonRpcProvider`, or `null` if unavailable.
@@ -155,7 +125,7 @@ declare function isInsideContainerSync(): boolean;
  *
  * Returns a statement store with `subscribe`, `createProof`, and `submit` methods
  * that communicate through the host's native binary protocol — bypassing JSON-RPC
- * entirely. Returns `null` when `@novasamatech/product-sdk` is unavailable.
+ * entirely. Returns `null` when `@novasamatech/host-api-wrapper` is unavailable.
  *
  * @returns The host statement store, or `null` if unavailable.
  */
@@ -166,36 +136,51 @@ declare function getStatementStore(): Promise<HostStatementStore | null>;
  * chain-specific endpoints used by multiple packages.
  */
 /**
- * Bulletin Chain RPC endpoints per network environment. `paseo` and `previewnet`
- * are populated today; `polkadot` and `kusama` are reserved for when those
+ * Bulletin Chain RPC endpoints per network environment. `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-next-rpc.polkadot.io"];
-    readonly previewnet: readonly ["wss://previewnet.substrate.dev/bulletin"];
     readonly polkadot: string[];
     readonly kusama: string[];
 };
 /** Default Bulletin Chain endpoint — the first entry under {@link BULLETIN_RPCS}.paseo. */
 declare const DEFAULT_BULLETIN_ENDPOINT: string;
 
+/**
+ * Extract a human-readable message from a host-side error. Hosts wrap
+ * errors in versioned envelopes (`{ tag: "v1", value: CodecError }`); this
+ * helper unwraps the envelope and renders the inner error's `name`/`message`
+ * so callers see the host's actual diagnostic instead of `"[object Object]"`
+ * (from `String(err)`) or a JSON-stringified envelope.
+ *
+ * Exported for the higher-level wrappers (`requestPermission`,
+ * `deriveEntropy`, etc.) that build their `throw new Error(...)` messages.
+ */
+declare function formatHostError(err: unknown): string;
+
 /**
  * The TruApi type - provides low-level methods for communicating with the host.
  *
  * Methods include:
- * - `navigateTo(url)` — Navigate to a URL within the host
- * - `permission(permissions)` — Request permissions from the host
- * - `localStorageRead/Write/Clear` — Host-backed storage
- * - `sign(payload)` — Request transaction signing
- * - `deriveEntropy(context)` — Derive deterministic entropy
- * - `themeSubscribe()` — Subscribe to host theme changes
+ * - `navigateTo(url)` - Navigate to a URL within the host
+ * - `permission(permissions)` - Request permissions from the host
+ * - `localStorageRead/Write/Clear` - Host-backed storage
+ * - `sign(payload)` - Request transaction signing
+ * - `deriveEntropy(context)` - Derive deterministic entropy
+ * - `themeSubscribe()` - Subscribe to host theme changes
  * - And many more...
+ *
+ * Type identical to `hostApi` from `@novasamatech/host-api-wrapper` so that
+ * `truApi.X(...)` calls keep their full inference (return types, method
+ * names, parameter shapes) instead of decaying to `any`.
  */
-type TruApi = any;
+type TruApi = typeof _novasamatech_host_api_wrapper.hostApi;
 /**
  * Get the TruAPI instance for direct low-level access.
  *
- * Returns the `hostApi` object from `@novasamatech/product-sdk` which provides
+ * Returns the `hostApi` object from `@novasamatech/host-api-wrapper` which provides
  * methods for communicating directly with the host container. Returns `null`
  * when running outside a container or when the SDK is unavailable.
  *
@@ -251,26 +236,24 @@ declare function getTruApi(): Promise<TruApi | null>;
  */
 declare function getPreimageManager(): Promise<PreimageManager | null>;
 /**
- * Preimage manager interface for bulletin chain operations.
- */
-interface PreimageManager {
-    /**
-     * Submit a preimage to the bulletin chain.
-     * @param data - The data to submit.
-     * @returns The preimage key (hex string).
-     */
-    submit(data: Uint8Array): Promise<string>;
-    /**
-     * Look up a preimage by key.
-     * @param key - The preimage key (hex string).
-     * @param callback - Called with the data when found, or null if not yet available.
-     * @returns Subscription handle with unsubscribe method.
-     */
-    lookup(key: string, callback: (preimage: Uint8Array | null) => void): {
-        unsubscribe: () => void;
-        onInterrupt: (cb: () => void) => () => void;
-    };
-}
+ * Preimage manager handle for bulletin chain operations. `lookup` returns a
+ * `Subscription<void>` (`unsubscribe` + `onInterrupt`); `submit` returns a
+ * `0x`-prefixed hex preimage key.
+ *
+ * Type identical to `preimageManager` from `@novasamatech/host-api-wrapper`.
+ */
+type PreimageManager = typeof preimageManager;
+/**
+ * Construct a fresh `PreimageManager` instance with an optional custom
+ * transport. Use this when you need a non-default transport; otherwise
+ * prefer {@link getPreimageManager}, which returns the shared singleton.
+ *
+ * Mirrors `createPreimageManager` from `@novasamatech/host-api-wrapper`.
+ *
+ * @param transport - Optional transport; defaults to the sandbox transport.
+ * @returns A new `PreimageManager` instance, or `null` if unavailable.
+ */
+declare function createHostPreimageManager(transport?: _novasamatech_host_api.Transport): Promise<PreimageManager | null>;
 /**
  * Get the accounts provider for managing host accounts.
  *
@@ -283,12 +266,26 @@ declare function getAccountsProvider(): Promise<AccountsProvider | null>;
  * errors, not runtime failures.
  */
 type AllocatableResource = CodecType<typeof AllocatableResource$1>;
+/** Tag-only view of {@link AllocatableResource} for places that just need the variant name. */
+type AllocatableResourceTag = AllocatableResource["tag"];
 /**
  * Per-resource outcome from {@link requestResourceAllocation}.
  * The host strips secret payloads from `Allocated` before returning, so
  * `value` is always `undefined` on the product side.
  */
 type AllocationOutcome = CodecType<typeof AllocationOutcome$1>;
+/** Tag-only view of {@link AllocationOutcome} (`"Allocated" | "Rejected" | "NotAvailable"`). */
+type AllocationOutcomeTag = AllocationOutcome["tag"];
+/**
+ * Remote permission the dapp can ask the host to grant via
+ * {@link requestPermission}.
+ *
+ * Derived from the upstream codec so variant renames surface as compile
+ * errors, not runtime failures.
+ */
+type RemotePermission = CodecType<typeof RemotePermission$1>;
+/** Tag-only view of {@link RemotePermission}. */
+type RemotePermissionTag = RemotePermission["tag"];
 /**
  * Request the host to pre-allocate one or more resource allowances.
  *
@@ -308,6 +305,48 @@ type AllocationOutcome = CodecType<typeof AllocationOutcome$1>;
  * ```
  */
 declare function requestResourceAllocation(resources: AllocatableResource[]): Promise<AllocationOutcome[]>;
+/**
+ * Have the host sign a Statement using an allowance-bearing account it
+ * picks internally — RFC-10 §"Statement Store allowance".
+ *
+ * The product passes only the Statement payload; the host chooses the
+ * `//allowance//statement-store//{productId}` account that holds SSS
+ * allowance and signs with it. Allowance is provisioned implicitly on
+ * first use if the host hasn't already pre-allocated via
+ * {@link requestResourceAllocation}; products never see the signing
+ * account or its key material.
+ *
+ * Pairs with {@link getStatementStore}'s `submit`: call this to obtain
+ * a proof, attach it to the Statement, and submit the result.
+ *
+ * @param statement - The Statement to be signed.
+ * @returns The proof to attach before submitting.
+ * @throws If the host is unavailable or the host-side signing fails.
+ *
+ * @example
+ * ```ts
+ * import { createProofAuthorized, getStatementStore } from "@parity/product-sdk-host";
+ *
+ * const statement = {
+ *     proof: undefined,
+ *     decryptionKey: undefined,
+ *     expiry: undefined,
+ *     channel: undefined,
+ *     topics: [],
+ *     data: payload,
+ * };
+ * const proof = await createProofAuthorized(statement);
+ * const store = await getStatementStore();
+ * await store?.submit({ ...statement, proof });
+ * ```
+ *
+ * @remarks
+ * RFC-10 introduces this as a new, strictly additive TruAPI call. The
+ * pre-existing `HostStatementStore.createProof(accountId, statement)`
+ * surface stays available for products that own a non-allowance signing
+ * account; this wrapper is the sponsored-submission path.
+ */
+declare function createProofAuthorized(statement: Statement): Promise<StatementProof>;
 /**
  * One of the user's existing wallet accounts, surfaced through the host and
  * identified by its public key and an optional name. Contrast with
@@ -352,81 +391,301 @@ interface ResultAsync<T, E> {
     match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;
 }
 /**
- * Accounts provider interface from @novasamatech/product-sdk.
- *
- * Provides methods for accessing host wallet accounts, product accounts,
- * and Ring VRF operations.
- */
-interface AccountsProvider {
-    /**
-     * 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.
-     */
-    getLegacyAccounts: () => ResultAsync<HostAccount[], unknown>;
-    /**
-     * 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.
-     */
-    getLegacyAccountSigner: (account: ProductAccount) => polkadot_api.PolkadotSigner;
-    /**
-     * Get an app-scoped product account from the host.
-     *
-     * Product accounts are derived by the host wallet for each app, identified
-     * by `dotNsIdentifier` (e.g., "mark3t.dot"). The user controls these accounts
-     * but they are scoped to the requesting app.
-     *
-     * @param dotNsIdentifier - App identifier (e.g., "mark3t.dot").
-     * @param derivationIndex - Derivation index within the app scope. Default: 0
-     * @returns ResultAsync resolving to the account.
-     */
-    getProductAccount: (dotNsIdentifier: string, derivationIndex?: number) => ResultAsync<HostAccount, unknown>;
-    /**
-     * Get a signer for a product account.
-     *
-     * @param account - The product account.
-     * @returns A PolkadotSigner for signing transactions.
-     */
-    getProductAccountSigner: (account: ProductAccount) => polkadot_api.PolkadotSigner;
-    /**
-     * Get a contextual alias for a product account via Ring VRF.
-     *
-     * Aliases prove account membership in a ring without revealing which
-     * account produced the alias.
-     *
-     * @param dotNsIdentifier - App identifier.
-     * @param derivationIndex - Derivation index. Default: 0
-     * @returns ResultAsync resolving to the contextual alias.
-     */
-    getProductAccountAlias: (dotNsIdentifier: string, derivationIndex?: number) => ResultAsync<ContextualAlias, unknown>;
-    /**
-     * Create a Ring VRF proof for anonymous operations.
-     *
-     * Proves that the signer is a member of the ring at the given location
-     * without revealing which member.
-     *
-     * @param dotNsIdentifier - App identifier.
-     * @param derivationIndex - Derivation index.
-     * @param location - Ring location on-chain.
-     * @param message - Message to sign.
-     * @returns ResultAsync resolving to the proof bytes.
-     */
-    createRingVRFProof: (dotNsIdentifier: string, derivationIndex: number, location: unknown, message: Uint8Array) => ResultAsync<Uint8Array, unknown>;
-    /**
-     * Subscribe to account connection status changes.
-     *
-     * @param callback - Called with status string ("connected" | "disconnected").
-     * @returns Unsubscribe handle.
-     */
-    subscribeAccountConnectionStatus: (callback: (status: string) => void) => {
-        unsubscribe: () => void;
-    } | (() => void);
-}
+ * Accounts provider handle from `@novasamatech/host-api-wrapper`. Surfaces the
+ * full upstream API - host wallet accounts, app-scoped product accounts,
+ * Ring VRF, user identity (`getUserId`, `requestLogin`), and connection
+ * status subscription.
+ *
+ * Type identical to `createAccountsProvider()` from
+ * `@novasamatech/host-api-wrapper`; methods return neverthrow `ResultAsync`
+ * values with typed `CodecError` variants in the error channel.
+ */
+type AccountsProvider = ReturnType<typeof createAccountsProvider>;
+
+/**
+ * Higher-level wrappers for the host's single-permission flows.
+ *
+ * `hostApi.permission` / `hostApi.devicePermission` take a versioned
+ * envelope (`enumValue("v1", ...)`) and return a neverthrow `ResultAsync`
+ * of an unwrapped versioned response. Consumers rebuild that wrap/unwrap
+ * dance every time. {@link requestPermission} and
+ * {@link requestDevicePermission} collapse it to one-liners that match the
+ * shape of {@link requestResourceAllocation} (throws on error, returns
+ * the unwrapped payload on success).
+ *
+ * @module
+ */
+
+/**
+ * Device permission the dapp can ask the host to grant via
+ * {@link requestDevicePermission}.
+ *
+ * Derived from the upstream codec so variant renames surface as compile
+ * errors, not runtime failures.
+ */
+type DevicePermissionKind = CodecType<typeof DevicePermission>;
+/**
+ * Alias of {@link RemotePermission} matching the upstream
+ * `@novasamatech/host-api-wrapper` name. Use either freely.
+ */
+type RemotePermissionItem = RemotePermission;
+/**
+ * Request a single remote permission from the host.
+ *
+ * Builds the `v1` envelope, calls `hostApi.permission`, unwraps the response,
+ * and returns the host's boolean granted/denied outcome.
+ *
+ * @param permission - The remote permission to request.
+ * @returns `true` if the host granted the permission, `false` if denied.
+ * @throws If the host is unavailable or the request fails.
+ *
+ * @example
+ * ```ts
+ * const granted = await requestPermission({ tag: "ChainSubmit", value: undefined });
+ * if (!granted) {
+ *   tellUserToReconnect();
+ * }
+ * ```
+ */
+declare function requestPermission(permission: RemotePermission): Promise<boolean>;
+/**
+ * Request a single device permission (camera, microphone, etc.) from the
+ * host.
+ *
+ * Builds the `v1` envelope, calls `hostApi.devicePermission`, unwraps the
+ * response, and returns the host's boolean granted/denied outcome.
+ *
+ * @param permission - The device permission to request.
+ * @returns `true` if the host granted the permission, `false` if denied.
+ * @throws If the host is unavailable or the request fails.
+ *
+ * @example
+ * ```ts
+ * const granted = await requestDevicePermission("Camera");
+ * if (!granted) {
+ *   showCameraDeniedMessage();
+ * }
+ * ```
+ */
+declare function requestDevicePermission(permission: DevicePermissionKind): Promise<boolean>;
+
+/**
+ * Higher-level wrapper for the host's theme subscription.
+ *
+ * `hostApi.themeSubscribe` is reachable via {@link getTruApi}, but consumers
+ * have to wire the subscription envelope themselves. `getThemeProvider`
+ * returns the `@novasamatech/host-api-wrapper` theme provider object directly,
+ * giving callers a `subscribeTheme(cb)` method that resolves to a typed
+ * `ThemeMode` ("Light" | "Dark") and yields a `Subscription<void>` handle.
+ *
+ * @module
+ */
+
+/**
+ * Host theme provider handle. Exposes `subscribeTheme(callback)` which
+ * receives a typed `ThemeMode` on every change and returns a
+ * `Subscription<void>` (`unsubscribe` + `onInterrupt`).
+ *
+ * Type identical to `createThemeProvider()` from
+ * `@novasamatech/host-api-wrapper`.
+ */
+type ThemeProvider = ReturnType<typeof createThemeProvider>;
+/** Host theme mode value. Re-exported from `@novasamatech/host-api-wrapper`. */
+type ThemeMode = ThemeMode$1;
+/**
+ * Get the host theme provider.
+ *
+ * Returns the theme-subscription handle exported by
+ * `@novasamatech/host-api-wrapper`, or `null` if the package is unavailable
+ * (running outside a host container or the optional peer dep isn't
+ * installed).
+ *
+ * Implementation note: upstream `@novasamatech/host-api-wrapper` exports only
+ * the `createThemeProvider` factory and no `themeProvider` singleton, so
+ * this getter constructs a fresh instance on each call (unlike
+ * {@link getPreimageManager} or {@link getHostLocalStorage}, which return
+ * upstream singletons). The constructed provider is cheap to allocate; it
+ * only opens a subscription when `subscribeTheme` is called.
+ *
+ * @returns The theme provider, or `null` if unavailable.
+ *
+ * @example
+ * ```ts
+ * import { getThemeProvider } from "@parity/product-sdk-host";
+ *
+ * const provider = await getThemeProvider();
+ * if (provider) {
+ *   const sub = provider.subscribeTheme((mode) => {
+ *     document.documentElement.dataset.theme = mode.toLowerCase();
+ *   });
+ *   // sub.unsubscribe() to stop listening
+ * }
+ * ```
+ */
+declare function getThemeProvider(): Promise<ThemeProvider | null>;
+
+/**
+ * Higher-level wrapper for the host's entropy derivation (RFC-0007).
+ *
+ * `hostApi.deriveEntropy` is reachable via {@link getTruApi}, but consumers
+ * have to wrap the value in the versioned envelope (`enumValue("v1", ...)`)
+ * and unwrap the neverthrow `ResultAsync` themselves. `deriveEntropy`
+ * collapses that to a throw-on-error Promise that matches the shape of
+ * {@link requestPermission} and {@link requestResourceAllocation}.
+ *
+ * @module
+ */
+/**
+ * Derive deterministic entropy from a context key (RFC-0007).
+ *
+ * The host derives entropy from the user's wallet + the provided context
+ * key. Calling with the same key on the same wallet yields the same bytes;
+ * different keys (or different wallets) yield uncorrelated entropy.
+ *
+ * @param key - Context key bytes (typically a SCALE-encoded discriminator).
+ * @returns The derived entropy bytes.
+ * @throws If the host is unavailable or the host-side derivation fails.
+ *
+ * @example
+ * ```ts
+ * import { deriveEntropy } from "@parity/product-sdk-host";
+ *
+ * const seed = await deriveEntropy(new TextEncoder().encode("my-app:seed-v1"));
+ * ```
+ */
+declare function deriveEntropy(key: Uint8Array): Promise<Uint8Array>;
+
+/**
+ * Wrapper for the host's chat surface (`host_chat_*` family).
+ *
+ * Shipped flat-in-host rather than as `getTruApi().chat.*` (the shape
+ * sketched in issue #93) because the upstream JS `hostApi` is itself a
+ * flat object - there is no `.chat` accessor to mirror. A flat
+ * `getChatManager()` matches the pattern already used by
+ * {@link getThemeProvider}, {@link getAccountsProvider}, and
+ * {@link getStatementStore}; if a namespaced view is desirable later, it
+ * can be layered on top without breaking this surface.
+ *
+ * @module
+ */
+
+/** Chat message payload variants. Re-exported from `@novasamatech/host-api-wrapper`. */
+type ChatMessageContent = ChatMessageContent$1;
+/** Action received via {@link ChatManager.subscribeAction}. Re-exported from `@novasamatech/host-api-wrapper`. */
+type ChatReceivedAction = ChatReceivedAction$1;
+/** Room metadata delivered to {@link ChatManager.subscribeChatList}. Re-exported from `@novasamatech/host-api-wrapper`. */
+type ChatRoom = ChatRoom$1;
+/** Result of registering a chat room (`"New" | "Exists"`). Re-exported from `@novasamatech/host-api-wrapper`. */
+type ChatRoomRegistrationResult = ChatRoomRegistrationResult$1;
+/** Result of registering a bot (`"New" | "Exists"`). Re-exported from `@novasamatech/host-api-wrapper`. */
+type ChatBotRegistrationResult = ChatBotRegistrationResult$1;
+/** Renderer callback for custom message types. Re-exported from `@novasamatech/host-api-wrapper`. */
+type ChatCustomMessageRenderer = ChatCustomMessageRenderer$1;
+/** Parameters passed to a {@link ChatCustomMessageRenderer}. Re-exported from `@novasamatech/host-api-wrapper`. */
+type ChatCustomMessageRendererParams<T = Uint8Array> = ChatCustomMessageRendererParams$1<T>;
+/**
+ * Chat manager handle. Exposes room/bot registration, message sending,
+ * subscription to room list and incoming actions, and custom-renderer
+ * registration.
+ *
+ * Type identical to `createProductChatManager()` from
+ * `@novasamatech/host-api-wrapper`.
+ */
+type ChatManager = ReturnType<typeof createProductChatManager>;
+/**
+ * Get the host chat manager.
+ *
+ * Returns the chat manager from `@novasamatech/host-api-wrapper`, or `null` if
+ * the package is unavailable (running outside a host container or the
+ * optional peer dep isn't installed).
+ *
+ * @returns The chat manager, or `null` if unavailable.
+ *
+ * @example
+ * ```ts
+ * import { getChatManager } from "@parity/product-sdk-host";
+ *
+ * const chat = await getChatManager();
+ * if (chat) {
+ *   await chat.registerBot({ botId: "echo", name: "Echo Bot", icon: "" });
+ *   chat.subscribeAction((action) => { ... });
+ * }
+ * ```
+ */
+declare function getChatManager(): Promise<ChatManager | null>;
+/**
+ * Dispatch helper that composes multiple custom-message renderers into a
+ * single {@link ChatCustomMessageRenderer} keyed by `messageType`.
+ *
+ * Mirrors `matchChatCustomRenderers` from `@novasamatech/host-api-wrapper`
+ * inline (the upstream implementation is pure dispatch logic with no
+ * transport / runtime dependency on Novasama), so callers get the same
+ * sync signature instead of an async-with-null wrapper.
+ *
+ * @param map - Object mapping `messageType` strings to renderers.
+ * @returns A composed renderer that dispatches to the entry matching
+ *          `params.messageType`, or throws if no renderer is registered.
+ */
+declare function matchChatCustomRenderers(map: Record<string, ChatCustomMessageRenderer>): ChatCustomMessageRenderer;
+
+/**
+ * Wrapper for the host's payment manager (RFC-0006).
+ *
+ * Shipped flat-in-host rather than as `getTruApi().payment.*` because the
+ * upstream JS `hostApi` is itself a flat object - there is no `.payment`
+ * accessor to mirror. A flat `getPaymentManager()` matches the singleton
+ * pattern already used by {@link getPreimageManager},
+ * {@link getHostLocalStorage}, and {@link getAccountsProvider}.
+ *
+ * Returns the shared `paymentManager` singleton from
+ * `@novasamatech/host-api-wrapper` (not a fresh `createPaymentManager()`
+ * instance) so callers share one wrapper + hostApi closure across the app.
+ *
+ * Distinct from the CoinPayment / merchant-payments surface tracked under
+ * `@parity/product-sdk-merchant-payments` (RFC-0017). RFC-0006 is the
+ * user-initiated balance / top-up / payment-request flow; RFC-0017 is the
+ * merchant-initiated checkout flow.
+ *
+ * @module
+ */
+
+/** Available balance for the user's payment account. Re-exported from `@novasamatech/host-api-wrapper`. */
+type PaymentBalance = PaymentBalance$1;
+/** Status of an in-flight payment request. Re-exported from `@novasamatech/host-api-wrapper`. */
+type PaymentStatus = PaymentStatus$1;
+/** Source for {@link PaymentManager.topUp}. Re-exported from `@novasamatech/host-api-wrapper`. */
+type TopUpSource = TopUpSource$1;
+/**
+ * Payment manager handle. Exposes balance subscription, top-up, payment
+ * requests, and payment status subscription.
+ *
+ * Type identical to `paymentManager` from `@novasamatech/host-api-wrapper`.
+ */
+type PaymentManager = typeof paymentManager;
+/**
+ * Get the host payment manager.
+ *
+ * Returns the shared `paymentManager` singleton from
+ * `@novasamatech/host-api-wrapper`, or `null` if the package is unavailable
+ * (running outside a host container or the optional peer dep isn't
+ * installed).
+ *
+ * @returns The payment manager, or `null` if unavailable.
+ *
+ * @example
+ * ```ts
+ * import { getPaymentManager } from "@parity/product-sdk-host";
+ *
+ * const payments = await getPaymentManager();
+ * if (payments) {
+ *   const sub = payments.subscribeBalance((b) => { ... });
+ *   await payments.topUp(1_000_000n, { type: "productAccount", derivationIndex: 0 });
+ *   const destination = new Uint8Array(32);
+ *   const { id } = await payments.requestPayment(500n, destination);
+ *   sub.unsubscribe();
+ * }
+ * ```
+ */
+declare function getPaymentManager(): Promise<PaymentManager | null>;
 
-export { type AccountsProvider, type AllocatableResource, type AllocationOutcome, 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, requestResourceAllocation };
+export { type AccountsProvider, type AllocatableResource, type AllocatableResourceTag, type AllocationOutcome, type AllocationOutcomeTag, BULLETIN_RPCS, type ChatBotRegistrationResult, type ChatCustomMessageRenderer, type ChatCustomMessageRendererParams, type ChatManager, type ChatMessageContent, type ChatReceivedAction, type ChatRoom, type ChatRoomRegistrationResult, type ContextualAlias, DEFAULT_BULLETIN_ENDPOINT, type DevicePermissionKind, type HostAccount, type HostLocalStorage, type HostStatementStore, type HostSubscription, type PaymentBalance, type PaymentManager, type PaymentStatus, type PreimageManager, type ProductAccount, type ProductAccountId, type RemotePermission, type RemotePermissionItem, type RemotePermissionTag, type ResultAsync, type SignedStatement, type Statement, type StatementProof, type StatementTopicFilter, type StatementsPage, type ThemeMode, type ThemeProvider, type TopUpSource, type Topic, type TruApi, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, formatHostError, getAccountsProvider, getChatManager, getHostLocalStorage, getHostProvider, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isInsideContainer, isInsideContainerSync, matchChatCustomRenderers, requestDevicePermission, requestPermission, requestResourceAllocation };