@parity/product-sdk-host 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,16 +1,15 @@
1
- import { JsonRpcProvider } from 'polkadot-api';
2
- import * as _novasamatech_host_api from '@novasamatech/host-api';
3
- import { Subscription, Transport, CodecType, AllocatableResource as AllocatableResource$1, AllocationOutcome as AllocationOutcome$1, RemotePermission as RemotePermission$1, DevicePermission, HexString } from '@novasamatech/host-api';
4
- export { HexString, PushNotificationError, assertEnumVariant, enumValue, fromHex, isEnumVariant, resultErr, resultOk, toHex, unwrapResultOrThrow } from '@novasamatech/host-api';
5
- import * as _novasamatech_host_api_wrapper from '@novasamatech/host-api-wrapper';
6
- 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, notificationManager } from '@novasamatech/host-api-wrapper';
1
+ import { JsonRpcProvider, PolkadotSigner } from 'polkadot-api';
2
+ import { Topic, RemoteStatementStoreSubscribeItem, Statement, StatementProof, SignedStatement, HexString, GenericError, TrUApiClient, AllocatableResource, AllocationOutcome, HostGetUserIdError, HostRequestLoginResponse, HostRequestLoginError, ProductAccountId, ProductAccount as ProductAccount$1, HostAccountGetError, HostAccountGetAliasResponse, LegacyAccount, RingLocation, HostAccountCreateProofError, HostAccountConnectionStatusSubscribeItem, HostDevicePermissionRequest, RemotePermission, HostThemeSubscribeItem, ChatBotRegistrationStatus, HostChatCreateRoomRequest, ChatRoomRegistrationStatus, HostChatRegisterBotRequest, ChatMessageContent, ChatRoom, HostChatActionSubscribeItem, HostPaymentBalanceSubscribeItem, PaymentPurseId, Balance, PaymentTopUpSource, HostPaymentStatusSubscribeItem, HostPushNotificationRequest, NotificationId } from '@parity/truapi';
3
+ export { AllocatableResource, AllocationOutcome, ChatMessageContent, ChatRoom, HexString, HostPaymentBalanceSubscribeItem, HostPaymentStatusSubscribeItem, NotificationId, PaymentTopUpSource, ProductAccountId, HostPushNotificationError as PushNotificationError, RemotePermission, RingLocation, SignedStatement, Statement, StatementProof, ThemeName, ThemeVariant, Topic } from '@parity/truapi';
4
+ import { ResultAsync as ResultAsync$1 } from 'neverthrow';
5
+ export { isCorrectEnvironment as isInsideContainerSync } from '@parity/truapi/sandbox';
7
6
 
8
7
  /**
9
8
  * Public types for the host wrappers.
10
9
  *
11
- * These are re-exported from `@novasamatech/host-api-wrapper` (the runtime
12
- * objects the host getters cast to) rather than hand-mirrored, so the
13
- * Parity surface stays in lockstep with the upstream codec types.
10
+ * The statement-store types are re-exported from `@parity/truapi` so the Parity
11
+ * surface stays in lockstep with the in-house protocol codec types. Their fields
12
+ * are `0x`-prefixed hex strings (`HexString`) and their enums are `{ tag }` unions.
14
13
  */
15
14
 
16
15
  /**
@@ -20,59 +19,71 @@ import { hostLocalStorage, createStatementStore, ProductAccountId as ProductAcco
20
19
  * via {@link getHostLocalStorage} when you need raw host storage without the
21
20
  * KV abstraction.
22
21
  *
23
- * Type identical to `hostLocalStorage` from `@novasamatech/host-api-wrapper`.
24
- */
25
- type HostLocalStorage = typeof hostLocalStorage;
22
+ * Backed by `truApi.localStorage.*` (raw `read`/`write`/`clear` over hex bytes);
23
+ * {@link getHostLocalStorage} adapts that into this richer surface. `readString`
24
+ * resolves to `""` for a missing key and `readJSON`/`readBytes` to
25
+ * `null`/`undefined`.
26
+ */
27
+ interface HostLocalStorage {
28
+ /** Read a UTF-8 string value; `""` when the key is absent. */
29
+ readString(key: string): Promise<string>;
30
+ /** Write a UTF-8 string value. */
31
+ writeString(key: string, value: string): Promise<void>;
32
+ /** Read and JSON-parse a value; `null` when the key is absent. */
33
+ readJSON(key: string): Promise<unknown>;
34
+ /** JSON-stringify and write a value. */
35
+ writeJSON(key: string, value: unknown): Promise<void>;
36
+ /** Read raw bytes; `undefined` when the key is absent. */
37
+ readBytes(key: string): Promise<Uint8Array | undefined>;
38
+ /** Write raw bytes. */
39
+ writeBytes(key: string, value: Uint8Array): Promise<void>;
40
+ /** Remove a key. */
41
+ clear(key: string): Promise<void>;
42
+ }
26
43
  /**
27
- * Cryptographic proof attached to a statement before submission, returned by
28
- * {@link HostStatementStore.createProof}. Variants cover the supported
29
- * signature schemes - `Sr25519`, `Ed25519`, `Ecdsa`, and `OnChain` (chain-
30
- * attestation-based proofs).
44
+ * Topic-based subscription filter. The host delivers statements that match
45
+ * either *all* of the listed topics (`matchAll`) or *any* of them (`matchAny`).
31
46
  *
32
- * Inferred from `createStatementStore().createProof`'s return type so codec
33
- * changes surface here as compile errors, not runtime decode failures.
47
+ * This is a field-discriminated form of truapi's `RemoteStatementStoreSubscribeRequest`,
48
+ * which is a tagged union (`{ tag: "MatchAll"; value: Topic[] } | { tag: "MatchAny"; value: Topic[] }`).
49
+ * The transport maps between the two.
34
50
  */
35
- type StatementProof = Awaited<ReturnType<ReturnType<typeof createStatementStore>["createProof"]>>;
36
- /**
37
- * Topic-based subscription filter. The host delivers statements that match
38
- * either *all* of the listed topics (`matchAll`) or *any* of them
39
- * (`matchAny`). Re-exported from `@novasamatech/host-api-wrapper`.
40
- */
41
- type StatementTopicFilter = StatementTopicFilter$1;
42
- /** A single topic value used inside a {@link StatementTopicFilter}. Re-exported from `@novasamatech/host-api-wrapper`. */
43
- type Topic = Topic$1;
44
- /** `[ss58Address, chainPrefix]` tuple identifying a product account at the codec layer. Re-exported from `@novasamatech/host-api-wrapper`. */
45
- type ProductAccountId = ProductAccountId$1;
46
- /** Unsigned statement payload. Re-exported from `@novasamatech/host-api-wrapper`. */
47
- type Statement = Statement$1;
48
- /** Statement bundled with its {@link StatementProof}. Re-exported from `@novasamatech/host-api-wrapper`. */
49
- type SignedStatement = SignedStatement$1;
51
+ type StatementTopicFilter = {
52
+ matchAll: Topic[];
53
+ } | {
54
+ matchAny: Topic[];
55
+ };
50
56
  /**
51
57
  * A page of signed statements delivered by {@link HostStatementStore.subscribe}.
52
58
  *
53
- * Pages arrive sequentially. `isComplete` is `true` on the final page of a
54
- * subscription's initial backfill; subsequent pages contain new statements
55
- * as they appear on chain. `statements` is `SignedStatement[]` (typed,
56
- * not `unknown[]`).
59
+ * truapi's `RemoteStatementStoreSubscribeItem`, re-exported under a friendlier
60
+ * name. Pages arrive sequentially; `isComplete` is `false` while the host
61
+ * streams the historical backfill and `true` once it's done (and on every
62
+ * subsequent live-update page).
57
63
  */
58
- type StatementsPage = StatementsPage$1;
64
+ type StatementsPage = RemoteStatementStoreSubscribeItem;
59
65
  /**
60
- * Subscription handle returned by the host - equivalent to
61
- * `Subscription<void>` from `@novasamatech/host-api`. Exposes
62
- * `unsubscribe()` plus an `onInterrupt` hook that fires if the host
63
- * interrupts the subscription server-side.
66
+ * Subscription handle returned by the host. Exposes `unsubscribe()` plus an
67
+ * `onInterrupt` hook that fires if the host interrupts the subscription
68
+ * server-side; `onInterrupt` returns a function that cancels the hook.
64
69
  */
65
- type HostSubscription = Subscription<void>;
70
+ interface HostSubscription {
71
+ unsubscribe(): void;
72
+ onInterrupt(callback: (reason?: unknown) => void): () => void;
73
+ }
66
74
  /**
67
- * Statement Store handle exposed by the host container. Provides
68
- * `subscribe`, `createProof`, and `submit` operations that go through the
69
- * host's native binary protocol; the `statement-store` package layers a
70
- * higher-level client on top.
71
- *
72
- * Type identical to `createStatementStore()` from
73
- * `@novasamatech/host-api-wrapper`.
74
- */
75
- type HostStatementStore = ReturnType<typeof createStatementStore>;
75
+ * Statement Store handle exposed by the host container, backed by
76
+ * `truApi.statementStore.*`. `subscribe` streams matching statements;
77
+ * `createProofAuthorized` signs a statement with the product's RFC-10 allowance
78
+ * account (the sponsored path — no per-call account id); `submit` publishes a
79
+ * signed statement. The `statement-store` package layers a higher-level client
80
+ * on top.
81
+ */
82
+ interface HostStatementStore {
83
+ subscribe(filter: StatementTopicFilter, callback: (page: StatementsPage) => void): HostSubscription;
84
+ createProofAuthorized(statement: Statement): Promise<StatementProof>;
85
+ submit(signedStatement: SignedStatement): Promise<void>;
86
+ }
76
87
 
77
88
  /**
78
89
  * Thrown by {@link getHostProvider} when the host container is reachable but does
@@ -95,56 +106,42 @@ declare class ChainNotSupportedError extends Error {
95
106
  *
96
107
  * The SDK is designed to run exclusively inside a host container. This function
97
108
  * is primarily useful for early validation or informational purposes.
98
- *
99
- * Uses product-sdk's sandboxProvider as primary detection.
100
- * Falls back to manual signal checks when product-sdk is not installed.
101
109
  */
102
110
  declare function isInsideContainer(): Promise<boolean>;
103
111
  /**
104
112
  * Get the Host API localStorage instance when running inside a container.
105
- * Returns null outside a container or when product-sdk is unavailable.
113
+ * Returns null outside a container or when the host transport is unavailable.
106
114
  */
107
115
  declare function getHostLocalStorage(): Promise<HostLocalStorage | null>;
108
116
  /**
109
- * Construct a fresh host-backed `HostLocalStorage` instance with an optional
110
- * custom transport. Use this when you need a non-default transport (e.g.
111
- * for tests); otherwise prefer {@link getHostLocalStorage}, which returns
112
- * the shared singleton.
113
- *
114
- * Mirrors `createLocalStorage` from `@novasamatech/host-api-wrapper`.
117
+ * Construct a host-backed `HostLocalStorage` instance. Retained for API
118
+ * compatibility; with the single cached TruAPI client this is equivalent to
119
+ * {@link getHostLocalStorage}.
115
120
  *
116
- * @param transport - Optional transport; defaults to the sandbox transport.
117
- * @returns A new `HostLocalStorage` instance, or `null` if unavailable.
121
+ * @returns A `HostLocalStorage` instance, or `null` if unavailable.
118
122
  */
119
- declare function createHostLocalStorage(transport?: Transport): Promise<HostLocalStorage | null>;
123
+ declare function createHostLocalStorage(): Promise<HostLocalStorage | null>;
120
124
  /**
121
125
  * Get a PAPI-compatible JSON-RPC provider that routes through the host connection.
122
126
  *
123
- * When running inside a Polkadot container, this wraps the chain connection via the
124
- * host's `createPapiProvider`, enabling shared connections and efficient routing.
125
- * Returns `null` when `@novasamatech/host-api-wrapper` is unavailable or when not
126
- * running inside a container.
127
+ * When running inside a Polkadot container, this builds a `JsonRpcProvider` over
128
+ * `truApi.chain.*` (see {@link module:papi-provider}), enabling shared
129
+ * connections and efficient routing. Returns `null` when not running inside a
130
+ * container.
127
131
  *
128
132
  * @param genesisHash - Genesis hash of the target chain (`0x`-prefixed hex string).
129
133
  * @returns A host-routed `JsonRpcProvider`, or `null` if unavailable.
130
134
  * @throws {ChainNotSupportedError} When inside a container but the host can't serve
131
135
  * the chain — surfaced instead of returning a provider that would hang forever.
132
136
  */
133
- declare function getHostProvider(genesisHash: `0x${string}`): Promise<JsonRpcProvider | null>;
137
+ declare function getHostProvider(genesisHash: HexString): Promise<JsonRpcProvider | null>;
134
138
  /**
135
- * Synchronous container detection fast heuristic check without product-sdk.
139
+ * Get the host statement store when running inside a container, backed by
140
+ * `truApi.statementStore.*`.
136
141
  *
137
- * Checks for iframe, webview marker, and host message port signals.
138
- * Use this when you need a quick sync check (e.g., in hot code paths).
139
- * For full detection including product-sdk, use {@link isInsideContainer} (async).
140
- */
141
- declare function isInsideContainerSync(): boolean;
142
- /**
143
- * Get the host API statement store when running inside a container.
144
- *
145
- * Returns a statement store with `subscribe`, `createProof`, and `submit` methods
146
- * that communicate through the host's native binary protocol — bypassing JSON-RPC
147
- * entirely. Returns `null` when `@novasamatech/host-api-wrapper` is unavailable.
142
+ * Returns a store with `subscribe`, `createProofAuthorized`, and `submit` that
143
+ * communicate through the host's native binary protocol bypassing JSON-RPC
144
+ * entirely. Returns `null` outside a host container.
148
145
  *
149
146
  * @returns The host statement store, or `null` if unavailable.
150
147
  */
@@ -169,143 +166,195 @@ declare const BULLETIN_RPCS: {
169
166
  declare const DEFAULT_BULLETIN_ENDPOINT: string;
170
167
 
171
168
  /**
172
- * Extract a human-readable message from a host-side error. Hosts wrap
173
- * errors in versioned envelopes (`{ tag: "v1", value: CodecError }`); this
174
- * helper unwraps the envelope and renders the inner error's `name`/`message`
175
- * so callers see the host's actual diagnostic instead of `"[object Object]"`
176
- * (from `String(err)`) or a JSON-stringified envelope.
169
+ * Typed errors carried on the `err` channel of the host public API's
170
+ * {@link Result} returns.
171
+ *
172
+ * The hierarchy mirrors `@parity/product-sdk-signer`'s error classes
173
+ * (`HostUnavailableError` / `HostRejectedError`), so the two layers share one
174
+ * idiom: branch with `instanceof`, and every error is a real `Error` with a
175
+ * stack trace and `cause`. The structured truapi wire error
176
+ * ({@link HostErrorPayload}) rides along as {@link HostCallFailedError.payload}
177
+ * for callers that want fine-grained tag-level handling.
177
178
  *
178
- * Exported for the higher-level wrappers (`requestPermission`,
179
- * `deriveEntropy`, etc.) that build their `throw new Error(...)` messages.
179
+ * This module also owns {@link HostErrorPayload} (the wire-error shape) and
180
+ * {@link formatHostError} (renders a payload to a message) — co-located with the
181
+ * error classes that consume them so the host error model lives in one place.
182
+ *
183
+ * @module
180
184
  */
181
- declare function formatHostError(err: unknown): string;
182
185
 
183
186
  /**
184
- * The TruApi type - provides low-level methods for communicating with the host.
187
+ * The structured error payload `@parity/truapi` surfaces on the `Err` channel of
188
+ * a host call, once unwrapped from the versioned wire envelope. Every host error
189
+ * union is built from these:
190
+ *
191
+ * - the catch-all {@link GenericError} (`{ reason }`),
192
+ * - a unit tagged variant (`{ tag }`), or
193
+ * - a tagged variant carrying a reason (`{ tag, value: { reason } }`).
194
+ *
195
+ * `GenericError` is imported from `@parity/truapi`; the `{ tag }` members are a
196
+ * deliberate widening of truapi's per-domain named variants (the formatter is
197
+ * tag-agnostic). truapi has no umbrella error union to import today — once it
198
+ * exports a canonical tagged-error union from codegen, replace these local
199
+ * members with that import so the type is protocol-sourced rather than
200
+ * hand-widened.
201
+ *
202
+ * This is the *payload* the host public API carries inside a
203
+ * {@link HostCallFailedError} on the `err` channel of its `Result` returns — not
204
+ * the error type consumers branch on.
205
+ */
206
+ type HostErrorPayload = GenericError | {
207
+ tag: string;
208
+ value?: undefined;
209
+ } | {
210
+ tag: string;
211
+ value: {
212
+ reason: string;
213
+ };
214
+ };
215
+ /**
216
+ * Extract a human-readable message from a host-side error.
185
217
  *
186
- * Methods include:
187
- * - `navigateTo(url)` - Navigate to a URL within the host
188
- * - `permission(permissions)` - Request permissions from the host
189
- * - `localStorageRead/Write/Clear` - Host-backed storage
190
- * - `sign(payload)` - Request transaction signing
191
- * - `deriveEntropy(context)` - Derive deterministic entropy
192
- * - `themeSubscribe()` - Subscribe to host theme changes
193
- * - And many more...
218
+ * Renders the {@link HostErrorPayload} shapes `@parity/truapi` surfaces. Accepts
219
+ * `unknown` because it is also the catch-all formatter for thrown adapter-method
220
+ * `Error` messages, so it falls back to `Error`/string/JSON rendering for
221
+ * anything that isn't a recognized host error payload.
194
222
  *
195
- * Type identical to `hostApi` from `@novasamatech/host-api-wrapper` so that
196
- * `truApi.X(...)` calls keep their full inference (return types, method
197
- * names, parameter shapes) instead of decaying to `any`.
223
+ * Used by {@link HostCallFailedError} to render its message, and by the throwing
224
+ * adapter-method helper `unwrapHostResult`.
198
225
  */
199
- type TruApi = typeof _novasamatech_host_api_wrapper.hostApi;
226
+ declare function formatHostError(error: unknown): string;
200
227
  /**
201
- * Get the TruAPI instance for direct low-level access.
202
- *
203
- * Returns the `hostApi` object from `@novasamatech/host-api-wrapper` which provides
204
- * methods for communicating directly with the host container. Returns `null`
205
- * when running outside a container or when the SDK is unavailable.
206
- *
207
- * For most use cases, prefer the higher-level functions like `getHostLocalStorage()`,
208
- * `getHostProvider()`, etc. Use this when you need direct access to host methods
209
- * like `navigateTo()`, `permission()`, or `deriveEntropy()`.
210
- *
211
- * @example
212
- * ```ts
213
- * import { getTruApi, enumValue } from "@parity/product-sdk-host";
214
- *
215
- * const truApi = await getTruApi();
216
- * if (truApi) {
217
- * // Request permission
218
- * const result = await truApi.permission([enumValue("ChainSubmit")]);
228
+ * Base class for all host errors. Use `instanceof HostError` (or {@link isHostError})
229
+ * to catch any host-related failure.
230
+ */
231
+ declare class HostError extends Error {
232
+ constructor(message: string, options?: ErrorOptions);
233
+ }
234
+ /**
235
+ * The host API is not available the app is running outside a Polkadot host
236
+ * container (no injected TruAPI transport). The dominant case during local
237
+ * development. Branch with `instanceof HostUnavailableError` to surface an
238
+ * "open this app in a Polkadot host" message.
239
+ */
240
+ declare class HostUnavailableError extends HostError {
241
+ constructor(message?: string);
242
+ }
243
+ /**
244
+ * A host call reached the container but failed on the `Err` channel. Wraps the
245
+ * structured truapi {@link HostErrorPayload} as {@link payload} (also preserved
246
+ * as `cause`); the message is rendered via {@link formatHostError}.
247
+ */
248
+ declare class HostCallFailedError extends HostError {
249
+ readonly payload: HostErrorPayload;
250
+ constructor(label: string, payload: HostErrorPayload);
251
+ }
252
+ /** Check whether a value is any {@link HostError}. */
253
+ declare function isHostError(error: unknown): error is HostError;
254
+
255
+ /**
256
+ * A lightweight tagged `Result` type for the host public API.
219
257
  *
220
- * // Navigate to a URL
221
- * await truApi.navigateTo("polkadot://settings");
258
+ * Host functions return `Promise<Result<T, HostError>>` rather than throwing, so
259
+ * consumers get typed errors on the `err` channel instead of opaque thrown
260
+ * `Error`s. The shape is intentionally identical to the one
261
+ * `@parity/product-sdk-signer` exposes (`{ ok: true; value } | { ok: false; error }`),
262
+ * so the two layers compose with no adapter — host's `Result` flows straight into
263
+ * the signer's pattern matching.
222
264
  *
223
- * // Subscribe to theme changes
224
- * const sub = truApi.themeSubscribe(undefined, (theme) => {
225
- * console.log("Theme changed:", theme);
226
- * });
227
- * }
228
- * ```
265
+ * NOTE: host owns its own copy because the dependency edge runs `signer → host`,
266
+ * so host cannot import the signer's definition. If a third package ever needs
267
+ * this shape, extract it into a shared `@parity/product-sdk-result` package and
268
+ * have both depend on that instead of duplicating.
229
269
  *
230
- * @returns The TruAPI instance, or `null` if unavailable.
270
+ * @module
231
271
  */
232
- declare function getTruApi(): Promise<TruApi | null>;
272
+ /** A value that is either a success (`ok`) carrying `T`, or a failure (`err`) carrying `E`. */
273
+ type Result<T, E> = {
274
+ ok: true;
275
+ value: T;
276
+ } | {
277
+ ok: false;
278
+ error: E;
279
+ };
280
+ /** Create a successful {@link Result}. */
281
+ declare function ok<T>(value: T): Result<T, never>;
282
+ /** Create a failed {@link Result}. */
283
+ declare function err<E>(error: E): Result<never, E>;
284
+
233
285
  /**
234
- * Get the preimage manager for bulletin chain operations.
286
+ * TruAPI - the protocol for communicating between apps and the Polkadot host container.
235
287
  *
236
- * The preimage manager handles uploading and looking up preimages (arbitrary data)
237
- * on the bulletin chain through the host's optimized path.
288
+ * This module centralizes access to the in-house `@parity/truapi` client,
289
+ * allowing other `@parity/product-sdk-*` packages to import from here rather
290
+ * than depending directly on the protocol package. The client is built and
291
+ * cached by {@link module:transport}; this module adds the accessor plus the
292
+ * two helpers the convenience wrappers fold truapi's `ResultAsync` through —
293
+ * {@link mapHostResult} (returns a `Result`, used by the public operations) and
294
+ * {@link unwrapHostResult} (throws, used by the adapter-object methods).
238
295
  *
239
- * @returns The preimage manager, or `null` if unavailable.
296
+ * @module
297
+ */
298
+
299
+ /** Convert bytes to a `0x`-prefixed lower-case hex string. */
300
+ declare function toHex(bytes: Uint8Array): HexString;
301
+ /** Convert a hex string (with or without `0x`) to bytes. */
302
+ declare function fromHex(hex: string): Uint8Array;
303
+
304
+ /**
305
+ * The TruApi client — namespaced access to every host protocol domain
306
+ * (`permissions`, `entropy`, `signing`, `statementStore`, `system`,
307
+ * `localStorage`, …). Identical to `TrUApiClient` from `@parity/truapi`.
240
308
  *
241
309
  * @example
242
310
  * ```ts
243
- * import { getPreimageManager } from "@parity/product-sdk-host";
244
- *
245
- * const manager = await getPreimageManager();
246
- * if (manager) {
247
- * // Submit a preimage
248
- * const key = await manager.submit(new Uint8Array([1, 2, 3]));
249
- *
250
- * // Look up a preimage
251
- * const sub = manager.lookup(key, (data) => {
252
- * if (data) console.log("Found:", data);
311
+ * const truApi = await getTruApi();
312
+ * if (truApi) {
313
+ * await truApi.permissions.requestRemotePermission({
314
+ * permission: { tag: "ChainSubmit", value: undefined },
253
315
  * });
316
+ * await truApi.system.navigateTo({ url: "polkadot://settings" });
254
317
  * }
255
318
  * ```
256
319
  */
257
- declare function getPreimageManager(): Promise<PreimageManager | null>;
320
+ type TruApi = TrUApiClient;
258
321
  /**
259
- * Preimage manager handle for bulletin chain operations. `lookup` returns a
260
- * `Subscription<void>` (`unsubscribe` + `onInterrupt`); `submit` returns a
261
- * `0x`-prefixed hex preimage key.
322
+ * Get the TruAPI client for direct low-level access to host protocol domains.
262
323
  *
263
- * Type identical to `preimageManager` from `@novasamatech/host-api-wrapper`.
264
- */
265
- type PreimageManager = typeof preimageManager;
266
- /**
267
- * Construct a fresh `PreimageManager` instance with an optional custom
268
- * transport. Use this when you need a non-default transport; otherwise
269
- * prefer {@link getPreimageManager}, which returns the shared singleton.
324
+ * Returns the cached `@parity/truapi` client once the host transport is built
325
+ * and the handshake has run, or `null` when running outside a container.
270
326
  *
271
- * Mirrors `createPreimageManager` from `@novasamatech/host-api-wrapper`.
327
+ * For most use cases, prefer the higher-level functions like
328
+ * {@link requestPermission}, {@link deriveEntropy}, or `getHostLocalStorage()`.
272
329
  *
273
- * @param transport - Optional transport; defaults to the sandbox transport.
274
- * @returns A new `PreimageManager` instance, or `null` if unavailable.
330
+ * @returns The TruAPI client, or `null` if unavailable.
275
331
  */
276
- declare function createHostPreimageManager(transport?: _novasamatech_host_api.Transport): Promise<PreimageManager | null>;
277
- /**
278
- * Get the accounts provider for managing host accounts.
279
- *
280
- * @returns The accounts provider, or `null` if unavailable.
281
- */
282
- declare function getAccountsProvider(): Promise<AccountsProvider | null>;
332
+ declare function getTruApi(): Promise<TruApi | null>;
283
333
  /**
284
- * Resource types requestable via {@link requestResourceAllocation}.
285
- * Derived from the upstream codec so variant renames surface as compile
286
- * errors, not runtime failures.
334
+ * Preimage manager handle for bulletin chain operations, backed by
335
+ * `truApi.preimage.*`. `lookup` opens a {@link HostSubscription} (`unsubscribe`
336
+ * + `onInterrupt`) that delivers the preimage bytes — or `null` until the host
337
+ * finds them; `submit` uploads a preimage and resolves to its `0x`-prefixed hex
338
+ * key.
287
339
  */
288
- type AllocatableResource = CodecType<typeof AllocatableResource$1>;
289
- /** Tag-only view of {@link AllocatableResource} for places that just need the variant name. */
290
- type AllocatableResourceTag = AllocatableResource["tag"];
340
+ interface PreimageManager {
341
+ lookup(key: HexString, callback: (preimage: Uint8Array | null) => void): HostSubscription;
342
+ submit(value: Uint8Array): Promise<HexString>;
343
+ }
291
344
  /**
292
- * Per-resource outcome from {@link requestResourceAllocation}.
293
- * The host strips secret payloads from `Allocated` before returning, so
294
- * `value` is always `undefined` on the product side.
345
+ * Get the preimage manager for bulletin chain operations.
346
+ *
347
+ * @returns The preimage manager, or `null` if unavailable (outside a container).
295
348
  */
296
- type AllocationOutcome = CodecType<typeof AllocationOutcome$1>;
297
- /** Tag-only view of {@link AllocationOutcome} (`"Allocated" | "Rejected" | "NotAvailable"`). */
298
- type AllocationOutcomeTag = AllocationOutcome["tag"];
349
+ declare function getPreimageManager(): Promise<PreimageManager | null>;
299
350
  /**
300
- * Remote permission the dapp can ask the host to grant via
301
- * {@link requestPermission}.
351
+ * Construct a `PreimageManager`. Retained for API compatibility; with the single
352
+ * cached TruAPI client this is equivalent to {@link getPreimageManager}.
302
353
  *
303
- * Derived from the upstream codec so variant renames surface as compile
304
- * errors, not runtime failures.
354
+ * @returns A `PreimageManager` instance, or `null` if unavailable.
305
355
  */
306
- type RemotePermission = CodecType<typeof RemotePermission$1>;
307
- /** Tag-only view of {@link RemotePermission}. */
308
- type RemotePermissionTag = RemotePermission["tag"];
356
+ declare function createHostPreimageManager(): Promise<PreimageManager | null>;
357
+
309
358
  /**
310
359
  * Request the host to pre-allocate one or more resource allowances.
311
360
  *
@@ -313,238 +362,232 @@ type RemotePermissionTag = RemotePermission["tag"];
313
362
  * granted allowance don't re-prompt.
314
363
  *
315
364
  * @param resources - Resources to request.
316
- * @returns Per-resource outcomes in the same order as `resources`.
317
- * @throws If the host is unavailable or the request fails.
365
+ * @returns `ok` with per-resource outcomes in the same order as `resources`, or
366
+ * `err(HostUnavailableError | HostCallFailedError)`.
318
367
  *
319
368
  * @example
320
369
  * ```ts
321
- * const outcomes = await requestResourceAllocation([
370
+ * const r = await requestResourceAllocation([
322
371
  * { tag: "BulletinAllowance", value: undefined },
323
372
  * ]);
324
- * if (outcomes[0].tag === "Allocated") { ... }
373
+ * if (r.ok && r.value[0] === "Allocated") { ... }
325
374
  * ```
326
375
  */
327
- declare function requestResourceAllocation(resources: AllocatableResource[]): Promise<AllocationOutcome[]>;
376
+ declare function requestResourceAllocation(resources: AllocatableResource[]): Promise<Result<AllocationOutcome[], HostError>>;
328
377
  /**
329
- * Have the host sign a Statement using an allowance-bearing account it
330
- * picks internally — RFC-10 §"Statement Store allowance".
331
- *
332
- * The product passes only the Statement payload; the host chooses the
333
- * `//allowance//statement-store//{productId}` account that holds SSS
334
- * allowance and signs with it. Allowance is provisioned implicitly on
335
- * first use if the host hasn't already pre-allocated via
336
- * {@link requestResourceAllocation}; products never see the signing
337
- * account or its key material.
378
+ * Have the host sign a Statement using the product's allowance-bearing account,
379
+ * which it picks internally — RFC-10 §"Statement Store allowance". No per-call
380
+ * account id is needed (this is the sponsored-submission path).
338
381
  *
339
- * Pairs with {@link getStatementStore}'s `submit`: call this to obtain
340
- * a proof, attach it to the Statement, and submit the result.
382
+ * Pairs with {@link getStatementStore}'s `submit`: call this to obtain a proof,
383
+ * attach it to the Statement, and submit the result.
341
384
  *
342
385
  * @param statement - The Statement to be signed.
343
- * @returns The proof to attach before submitting.
344
- * @throws If the host is unavailable or the host-side signing fails.
386
+ * @returns `ok` with the proof to attach before submitting, or
387
+ * `err(HostUnavailableError | HostCallFailedError)`.
388
+ */
389
+ declare function createProofAuthorized(statement: Statement): Promise<Result<StatementProof, HostError>>;
390
+ /**
391
+ * Neverthrow-style ResultAsync returned by product-sdk methods.
345
392
  *
346
- * @example
347
- * ```ts
348
- * import { createProofAuthorized, getStatementStore } from "@parity/product-sdk-host";
349
- *
350
- * const statement = {
351
- * proof: undefined,
352
- * decryptionKey: undefined,
353
- * expiry: undefined,
354
- * channel: undefined,
355
- * topics: [],
356
- * data: payload,
357
- * };
358
- * const proof = await createProofAuthorized(statement);
359
- * const store = await getStatementStore();
360
- * await store?.submit({ ...statement, proof });
361
- * ```
393
+ * Use `.match(onOk, onErr)` to handle success/error cases.
394
+ */
395
+ interface ResultAsync<T, E> {
396
+ match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;
397
+ }
398
+
399
+ /**
400
+ * Host wallet accounts, backed by `truApi.account.*` and `truApi.signing.*`.
401
+ *
402
+ * `getAccountsProvider()` returns the full accounts surface — user identity
403
+ * (`getUserId` / `requestLogin`), the user's existing wallet accounts
404
+ * (`getLegacyAccounts`), app-scoped product accounts (`getProductAccount` /
405
+ * `getProductAccountAlias`), Ring VRF proofs (`createRingVRFProof`), connection
406
+ * status, and PAPI `PolkadotSigner` factories for both product and legacy
407
+ * accounts.
362
408
  *
363
- * @remarks
364
- * RFC-10 introduces this as a new, strictly additive TruAPI call. The
365
- * pre-existing `HostStatementStore.createProof(accountId, statement)`
366
- * surface stays available for products that own a non-allowance signing
367
- * account; this wrapper is the sponsored-submission path.
409
+ * The signer factories build a PAPI `PolkadotSigner` directly over
410
+ * `truApi.signing.createTransaction` (product) /
411
+ * `createTransactionWithLegacyAccount` (legacy) `signTx` derives the
412
+ * metadata-driven `txExtVersion` and maps the signed extensions to the host's
413
+ * wire shape; `signBytes` calls `signing.signRaw(WithLegacyAccount)`. No PJS
414
+ * bridge is involved, so opaque signed extensions (e.g. Paseo Next's `AsPgas`)
415
+ * survive end-to-end.
416
+ *
417
+ * @module
368
418
  */
369
- declare function createProofAuthorized(statement: Statement): Promise<StatementProof>;
419
+
370
420
  /**
371
421
  * One of the user's existing wallet accounts, surfaced through the host and
372
422
  * identified by its public key and an optional name. Contrast with
373
423
  * {@link ProductAccount}, which is also user-controlled but derived by the
374
424
  * host for a specific app rather than picked from the user's existing keys.
425
+ *
426
+ * Derived from `@parity/truapi`'s `LegacyAccount`, with `publicKey` decoded to bytes.
375
427
  */
376
- interface HostAccount {
428
+ type HostAccount = Omit<LegacyAccount, "publicKey"> & {
429
+ /** Raw public key bytes. */
377
430
  publicKey: Uint8Array;
378
- name?: string;
379
- }
431
+ };
380
432
  /**
381
433
  * A product account — an app-scoped derived account managed by the host wallet.
382
434
  *
383
435
  * The host derives a unique keypair for each app (identified by `dotNsIdentifier`)
384
436
  * so apps get their own account that the user controls but is scoped to the app.
437
+ *
438
+ * Combines `@parity/truapi`'s `ProductAccountId` (the `{ dotNsIdentifier,
439
+ * derivationIndex }` lookup key) with the `ProductAccount` payload, with
440
+ * `publicKey` decoded to bytes.
385
441
  */
386
- interface ProductAccount {
387
- /** App identifier (e.g., "mark3t.dot"). */
388
- dotNsIdentifier: string;
389
- /** Derivation index within the app scope. Default: 0 */
390
- derivationIndex: number;
391
- /** Raw public key (32 bytes). */
442
+ type ProductAccount = ProductAccountId & Omit<ProductAccount$1, "publicKey"> & {
443
+ /** Raw public key bytes. */
392
444
  publicKey: Uint8Array;
393
- }
445
+ };
394
446
  /**
395
447
  * A contextual alias obtained from Ring VRF.
396
448
  *
397
449
  * Proves account membership in a ring without revealing which account.
398
- */
399
- interface ContextualAlias {
400
- /** Ring context (32 bytes). */
401
- context: Uint8Array;
402
- /** The Ring VRF alias bytes. */
403
- alias: Uint8Array;
404
- }
405
- /**
406
- * Neverthrow-style ResultAsync returned by product-sdk methods.
407
450
  *
408
- * Use `.match(onOk, onErr)` to handle success/error cases.
451
+ * Derived from `@parity/truapi`'s alias response, with both fields decoded to bytes.
409
452
  */
410
- interface ResultAsync<T, E> {
411
- match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;
453
+ type ContextualAlias = {
454
+ [K in keyof HostAccountGetAliasResponse]: Uint8Array;
455
+ };
456
+ /**
457
+ * Accounts provider handle, backed by `truApi.account.*` / `truApi.signing.*`.
458
+ * Surfaces the user's wallet accounts, app-scoped product accounts, Ring VRF,
459
+ * user identity, connection status, and `PolkadotSigner` factories.
460
+ *
461
+ * Lookup methods return a neverthrow `ResultAsync` (use `.match(ok, err)`);
462
+ * the signer factories return a synchronous PAPI `PolkadotSigner`.
463
+ */
464
+ interface AccountsProvider {
465
+ getUserId(): ResultAsync$1<{
466
+ primaryUsername: string;
467
+ }, HostGetUserIdError>;
468
+ requestLogin(reason?: string): ResultAsync$1<HostRequestLoginResponse, HostRequestLoginError>;
469
+ getProductAccount(dotNsIdentifier: string, derivationIndex?: number): ResultAsync$1<ProductAccount, HostAccountGetError>;
470
+ getProductAccountAlias(dotNsIdentifier: string, derivationIndex?: number): ResultAsync$1<ContextualAlias, HostAccountGetError>;
471
+ getLegacyAccounts(): ResultAsync$1<HostAccount[], HostAccountGetError>;
472
+ createRingVRFProof(dotNsIdentifier: string, derivationIndex: number, location: RingLocation, message: Uint8Array): ResultAsync$1<Uint8Array, HostAccountCreateProofError>;
473
+ /**
474
+ * Build a `PolkadotSigner` for a product account. Signing routes through the
475
+ * host's `createTransaction` path: the host decodes the metadata and forwards
476
+ * the opaque signed-extension bytes, so unknown extensions survive end-to-end.
477
+ */
478
+ getProductAccountSigner(account: ProductAccount): PolkadotSigner;
479
+ /**
480
+ * Build a `PolkadotSigner` for one of the user's existing wallet accounts.
481
+ * `name` is accepted for callsite ergonomics but unused — the signer is
482
+ * derived from `publicKey` alone.
483
+ */
484
+ getLegacyAccountSigner(account: {
485
+ publicKey: Uint8Array;
486
+ name?: string;
487
+ }): PolkadotSigner;
488
+ subscribeAccountConnectionStatus(callback: (status: HostAccountConnectionStatusSubscribeItem) => void): HostSubscription;
412
489
  }
413
490
  /**
414
- * Accounts provider handle from `@novasamatech/host-api-wrapper`. Surfaces the
415
- * full upstream API - host wallet accounts, app-scoped product accounts,
416
- * Ring VRF, user identity (`getUserId`, `requestLogin`), and connection
417
- * status subscription.
491
+ * Get the accounts provider for managing host accounts, backed by
492
+ * `truApi.account.*` / `truApi.signing.*`. Returns `null` when running outside
493
+ * a host container.
418
494
  *
419
- * Type identical to `createAccountsProvider()` from
420
- * `@novasamatech/host-api-wrapper`; methods return neverthrow `ResultAsync`
421
- * values with typed `CodecError` variants in the error channel.
495
+ * @returns The accounts provider, or `null` if unavailable.
422
496
  */
423
- type AccountsProvider = ReturnType<typeof createAccountsProvider>;
497
+ declare function getAccountsProvider(): Promise<AccountsProvider | null>;
424
498
 
425
499
  /**
426
500
  * Higher-level wrappers for the host's single-permission flows.
427
501
  *
428
- * `hostApi.permission` / `hostApi.devicePermission` take a versioned
429
- * envelope (`enumValue("v1", ...)`) and return a neverthrow `ResultAsync`
430
- * of an unwrapped versioned response. Consumers rebuild that wrap/unwrap
431
- * dance every time. {@link requestPermission} and
432
- * {@link requestDevicePermission} collapse it to one-liners that match the
433
- * shape of {@link requestResourceAllocation} (throws on error, returns
434
- * the unwrapped payload on success).
502
+ * `truApi.permissions.requestRemotePermission` / `requestDevicePermission`
503
+ * return a neverthrow `ResultAsync` of a `{ granted }` response.
504
+ * {@link requestPermission} and {@link requestDevicePermission} collapse that
505
+ * to one-liners returning a `Result<boolean, HostError>` — the granted flag on
506
+ * success, a typed {@link HostError} on the `err` channel.
435
507
  *
436
508
  * @module
437
509
  */
438
510
 
439
511
  /**
440
512
  * Device permission the dapp can ask the host to grant via
441
- * {@link requestDevicePermission}.
442
- *
443
- * Derived from the upstream codec so variant renames surface as compile
444
- * errors, not runtime failures.
513
+ * {@link requestDevicePermission}. A string union (`"Camera"`, `"Microphone"`,
514
+ * …) re-exported from `@parity/truapi`.
445
515
  */
446
- type DevicePermissionKind = CodecType<typeof DevicePermission>;
516
+ type DevicePermissionKind = HostDevicePermissionRequest;
447
517
  /**
448
- * Alias of {@link RemotePermission} matching the upstream
449
- * `@novasamatech/host-api-wrapper` name. Use either freely.
518
+ * Legacy alias of {@link RemotePermission}, kept for back-compat with code that
519
+ * used the older name. Use either freely.
450
520
  */
451
521
  type RemotePermissionItem = RemotePermission;
452
522
  /**
453
523
  * Request a single remote permission from the host.
454
524
  *
455
- * Builds the `v1` envelope, calls `hostApi.permission`, unwraps the response,
456
- * and returns the host's boolean granted/denied outcome.
525
+ * Calls `truApi.permissions.requestRemotePermission` and returns the host's
526
+ * boolean granted/denied outcome.
457
527
  *
458
528
  * @param permission - The remote permission to request.
459
- * @returns `true` if the host granted the permission, `false` if denied.
460
- * @throws If the host is unavailable or the request fails.
529
+ * @returns `ok(true)` if the host granted the permission, `ok(false)` if denied,
530
+ * or `err(HostUnavailableError | HostCallFailedError)`.
461
531
  *
462
532
  * @example
463
533
  * ```ts
464
- * const granted = await requestPermission({ tag: "ChainSubmit", value: undefined });
465
- * if (!granted) {
534
+ * const r = await requestPermission({ tag: "ChainSubmit", value: undefined });
535
+ * if (!r.ok || !r.value) {
466
536
  * tellUserToReconnect();
467
537
  * }
468
538
  * ```
469
539
  */
470
- declare function requestPermission(permission: RemotePermission): Promise<boolean>;
540
+ declare function requestPermission(permission: RemotePermission): Promise<Result<boolean, HostError>>;
471
541
  /**
472
542
  * Request a single device permission (camera, microphone, etc.) from the
473
543
  * host.
474
544
  *
475
- * Builds the `v1` envelope, calls `hostApi.devicePermission`, unwraps the
476
- * response, and returns the host's boolean granted/denied outcome.
545
+ * Calls `truApi.permissions.requestDevicePermission` and returns the host's
546
+ * boolean granted/denied outcome.
477
547
  *
478
548
  * @param permission - The device permission to request.
479
- * @returns `true` if the host granted the permission, `false` if denied.
480
- * @throws If the host is unavailable or the request fails.
549
+ * @returns `ok(true)` if the host granted the permission, `ok(false)` if denied,
550
+ * or `err(HostUnavailableError | HostCallFailedError)`.
481
551
  *
482
552
  * @example
483
553
  * ```ts
484
- * const granted = await requestDevicePermission("Camera");
485
- * if (!granted) {
554
+ * const r = await requestDevicePermission("Camera");
555
+ * if (!r.ok || !r.value) {
486
556
  * showCameraDeniedMessage();
487
557
  * }
488
558
  * ```
489
559
  */
490
- declare function requestDevicePermission(permission: DevicePermissionKind): Promise<boolean>;
560
+ declare function requestDevicePermission(permission: DevicePermissionKind): Promise<Result<boolean, HostError>>;
491
561
 
492
562
  /**
493
- * Higher-level wrapper for the host's theme subscription.
494
- *
495
- * `hostApi.themeSubscribe` is reachable via {@link getTruApi}, but consumers
496
- * have to wire the subscription envelope themselves. `getThemeProvider`
497
- * returns the `@novasamatech/host-api-wrapper` theme provider object directly,
498
- * giving callers a `subscribeTheme(cb)` method that resolves to a typed
499
- * {@link ThemeMode} — a `{ name, variant }` struct where `variant` is
500
- * `"Light" | "Dark"` — and yields a `Subscription<void>` handle.
563
+ * Higher-level wrapper for the host's theme subscription, backed by
564
+ * `truApi.theme.subscribe`.
501
565
  *
502
- * @remarks
503
- * As of `host-api(-wrapper)` v0.8 the theme payload is a struct, not a flat
504
- * `"light" | "dark"` string: read {@link ThemeMode.variant} for the
505
- * light/dark value (now capitalized) and {@link ThemeMode.name} for the
506
- * active theme name (`Default`, or `Custom` carrying a string id).
566
+ * `getThemeProvider` returns a handle whose `subscribeTheme(cb)` delivers a
567
+ * typed {@link ThemeMode} a `{ name, variant }` struct where `variant` is
568
+ * `"Light" | "Dark"` and `name` is `{ tag: "Default" }` or
569
+ * `{ tag: "Custom", value }` and yields a {@link HostSubscription}
570
+ * (`unsubscribe` + `onInterrupt`).
507
571
  *
508
572
  * @module
509
573
  */
510
574
 
511
575
  /**
512
- * Host theme provider handle. Exposes `subscribeTheme(callback)` which
513
- * receives a typed {@link ThemeMode} struct on every change and returns a
514
- * `Subscription<void>` (`unsubscribe` + `onInterrupt`).
515
- *
516
- * Type identical to `createThemeProvider()` from
517
- * `@novasamatech/host-api-wrapper`.
576
+ * Host theme value. A `{ name, variant }` struct re-exported from
577
+ * `@parity/truapi`.
518
578
  */
519
- type ThemeProvider = ReturnType<typeof createThemeProvider>;
520
- /**
521
- * Host theme value. Re-exported from `@novasamatech/host-api-wrapper`.
522
- *
523
- * A `{ name, variant }` struct as of v0.8 (previously a flat
524
- * `"light" | "dark"` string).
525
- */
526
- type ThemeMode = ThemeMode$1;
527
- /** Light/dark variant of the active theme: `"Light" | "Dark"`. */
528
- type ThemeVariant = ThemeMode["variant"];
579
+ type ThemeMode = HostThemeSubscribeItem;
580
+
529
581
  /**
530
- * Active theme name: `{ tag: "Default" }`, or `{ tag: "Custom", value }`
531
- * carrying the custom theme's string id.
582
+ * Host theme provider handle. `subscribeTheme(callback)` receives a typed
583
+ * {@link ThemeMode} on every change and returns a {@link HostSubscription}.
532
584
  */
533
- type ThemeName = ThemeMode["name"];
585
+ interface ThemeProvider {
586
+ subscribeTheme(callback: (theme: ThemeMode) => void): HostSubscription;
587
+ }
534
588
  /**
535
- * Get the host theme provider.
536
- *
537
- * Returns the theme-subscription handle exported by
538
- * `@novasamatech/host-api-wrapper`, or `null` if the package is unavailable
539
- * (running outside a host container or the optional peer dep isn't
540
- * installed).
541
- *
542
- * Implementation note: upstream `@novasamatech/host-api-wrapper` exports only
543
- * the `createThemeProvider` factory and no `themeProvider` singleton, so
544
- * this getter constructs a fresh instance on each call (unlike
545
- * {@link getPreimageManager} or {@link getHostLocalStorage}, which return
546
- * upstream singletons). The constructed provider is cheap to allocate; it
547
- * only opens a subscription when `subscribeTheme` is called.
589
+ * Get the host theme provider, backed by `truApi.theme.*`. Returns `null` when
590
+ * running outside a host container.
548
591
  *
549
592
  * @returns The theme provider, or `null` if unavailable.
550
593
  *
@@ -567,14 +610,14 @@ declare function getThemeProvider(): Promise<ThemeProvider | null>;
567
610
  /**
568
611
  * Higher-level wrapper for the host's entropy derivation (RFC-0007).
569
612
  *
570
- * `hostApi.deriveEntropy` is reachable via {@link getTruApi}, but consumers
571
- * have to wrap the value in the versioned envelope (`enumValue("v1", ...)`)
572
- * and unwrap the neverthrow `ResultAsync` themselves. `deriveEntropy`
573
- * collapses that to a throw-on-error Promise that matches the shape of
574
- * {@link requestPermission} and {@link requestResourceAllocation}.
613
+ * `truApi.entropy.derive` takes a hex `context` and returns a hex `entropy`
614
+ * payload wrapped in a neverthrow `ResultAsync`. `deriveEntropy` keeps the
615
+ * ergonomic `Uint8Array Result<Uint8Array, HostError>` signature: it
616
+ * hex-encodes the context on the way in and decodes the entropy on the way out.
575
617
  *
576
618
  * @module
577
619
  */
620
+
578
621
  /**
579
622
  * Derive deterministic entropy from a context key (RFC-0007).
580
623
  *
@@ -583,61 +626,50 @@ declare function getThemeProvider(): Promise<ThemeProvider | null>;
583
626
  * different keys (or different wallets) yield uncorrelated entropy.
584
627
  *
585
628
  * @param key - Context key bytes (typically a SCALE-encoded discriminator).
586
- * @returns The derived entropy bytes.
587
- * @throws If the host is unavailable or the host-side derivation fails.
629
+ * @returns `ok` with the derived entropy bytes, or
630
+ * `err(HostUnavailableError | HostCallFailedError)`.
588
631
  *
589
632
  * @example
590
633
  * ```ts
591
634
  * import { deriveEntropy } from "@parity/product-sdk-host";
592
635
  *
593
- * const seed = await deriveEntropy(new TextEncoder().encode("my-app:seed-v1"));
636
+ * const r = await deriveEntropy(new TextEncoder().encode("my-app:seed-v1"));
637
+ * if (r.ok) { const seed = r.value; }
594
638
  * ```
595
639
  */
596
- declare function deriveEntropy(key: Uint8Array): Promise<Uint8Array>;
640
+ declare function deriveEntropy(key: Uint8Array): Promise<Result<Uint8Array, HostError>>;
597
641
 
598
642
  /**
599
- * Wrapper for the host's chat surface (`host_chat_*` family).
643
+ * Wrapper for the host's chat surface, backed by `truApi.chat.*`.
600
644
  *
601
- * Shipped flat-in-host rather than as `getTruApi().chat.*` (the shape
602
- * sketched in issue #93) because the upstream JS `hostApi` is itself a
603
- * flat object - there is no `.chat` accessor to mirror. A flat
604
- * `getChatManager()` matches the pattern already used by
605
- * {@link getThemeProvider}, {@link getAccountsProvider}, and
606
- * {@link getStatementStore}; if a namespaced view is desirable later, it
607
- * can be layered on top without breaking this surface.
645
+ * `getChatManager()` returns a manager for room/bot registration, message
646
+ * sending, and subscription to the room list and incoming actions.
608
647
  *
609
648
  * @module
610
649
  */
611
650
 
612
- /** Chat message payload variants. Re-exported from `@novasamatech/host-api-wrapper`. */
613
- type ChatMessageContent = ChatMessageContent$1;
614
- /** Action received via {@link ChatManager.subscribeAction}. Re-exported from `@novasamatech/host-api-wrapper`. */
615
- type ChatReceivedAction = ChatReceivedAction$1;
616
- /** Room metadata delivered to {@link ChatManager.subscribeChatList}. Re-exported from `@novasamatech/host-api-wrapper`. */
617
- type ChatRoom = ChatRoom$1;
618
- /** Result of registering a chat room (`"New" | "Exists"`). Re-exported from `@novasamatech/host-api-wrapper`. */
619
- type ChatRoomRegistrationResult = ChatRoomRegistrationResult$1;
620
- /** Result of registering a bot (`"New" | "Exists"`). Re-exported from `@novasamatech/host-api-wrapper`. */
621
- type ChatBotRegistrationResult = ChatBotRegistrationResult$1;
622
- /** Renderer callback for custom message types. Re-exported from `@novasamatech/host-api-wrapper`. */
623
- type ChatCustomMessageRenderer = ChatCustomMessageRenderer$1;
624
- /** Parameters passed to a {@link ChatCustomMessageRenderer}. Re-exported from `@novasamatech/host-api-wrapper`. */
625
- type ChatCustomMessageRendererParams<T = Uint8Array> = ChatCustomMessageRendererParams$1<T>;
626
- /**
627
- * Chat manager handle. Exposes room/bot registration, message sending,
628
- * subscription to room list and incoming actions, and custom-renderer
629
- * registration.
630
- *
631
- * Type identical to `createProductChatManager()` from
632
- * `@novasamatech/host-api-wrapper`.
633
- */
634
- type ChatManager = ReturnType<typeof createProductChatManager>;
635
- /**
636
- * Get the host chat manager.
637
- *
638
- * Returns the chat manager from `@novasamatech/host-api-wrapper`, or `null` if
639
- * the package is unavailable (running outside a host container or the
640
- * optional peer dep isn't installed).
651
+ /** Action received via {@link ChatManager.subscribeAction} (`{ roomId, peer, payload }`). Re-exported from `@parity/truapi`. */
652
+ type ChatReceivedAction = HostChatActionSubscribeItem;
653
+ /** Result of registering a chat room (`"New" | "Exists"`). Re-exported from `@parity/truapi`. */
654
+ type ChatRoomRegistrationResult = ChatRoomRegistrationStatus;
655
+ /** Result of registering a bot (`"New" | "Exists"`). Re-exported from `@parity/truapi`. */
656
+ type ChatBotRegistrationResult = ChatBotRegistrationStatus;
657
+ /**
658
+ * Chat manager handle. Exposes room/bot registration, message sending, and
659
+ * subscription to the room list and incoming actions.
660
+ */
661
+ interface ChatManager {
662
+ registerRoom(request: HostChatCreateRoomRequest): Promise<ChatRoomRegistrationResult>;
663
+ registerBot(request: HostChatRegisterBotRequest): Promise<ChatBotRegistrationResult>;
664
+ sendMessage(roomId: string, payload: ChatMessageContent): Promise<{
665
+ messageId: string;
666
+ }>;
667
+ subscribeChatList(callback: (rooms: ChatRoom[]) => void): HostSubscription;
668
+ subscribeAction(callback: (action: ChatReceivedAction) => void): HostSubscription;
669
+ }
670
+ /**
671
+ * Get the host chat manager, backed by `truApi.chat.*`. Returns `null` when
672
+ * running outside a host container.
641
673
  *
642
674
  * @returns The chat manager, or `null` if unavailable.
643
675
  *
@@ -653,62 +685,38 @@ type ChatManager = ReturnType<typeof createProductChatManager>;
653
685
  * ```
654
686
  */
655
687
  declare function getChatManager(): Promise<ChatManager | null>;
656
- /**
657
- * Dispatch helper that composes multiple custom-message renderers into a
658
- * single {@link ChatCustomMessageRenderer} keyed by `messageType`.
659
- *
660
- * Mirrors `matchChatCustomRenderers` from `@novasamatech/host-api-wrapper`
661
- * inline (the upstream implementation is pure dispatch logic with no
662
- * transport / runtime dependency on Novasama), so callers get the same
663
- * sync signature instead of an async-with-null wrapper.
664
- *
665
- * @param map - Object mapping `messageType` strings to renderers.
666
- * @returns A composed renderer that dispatches to the entry matching
667
- * `params.messageType`, or throws if no renderer is registered.
668
- */
669
- declare function matchChatCustomRenderers(map: Record<string, ChatCustomMessageRenderer>): ChatCustomMessageRenderer;
670
688
 
671
689
  /**
672
- * Wrapper for the host's payment manager (RFC-0006).
673
- *
674
- * Shipped flat-in-host rather than as `getTruApi().payment.*` because the
675
- * upstream JS `hostApi` is itself a flat object - there is no `.payment`
676
- * accessor to mirror. A flat `getPaymentManager()` matches the singleton
677
- * pattern already used by {@link getPreimageManager},
678
- * {@link getHostLocalStorage}, and {@link getAccountsProvider}.
690
+ * Wrapper for the host's payment manager (RFC-0006), backed by
691
+ * `truApi.payment.*`.
679
692
  *
680
- * Returns the shared `paymentManager` singleton from
681
- * `@novasamatech/host-api-wrapper` (not a fresh `createPaymentManager()`
682
- * instance) so callers share one wrapper + hostApi closure across the app.
683
- *
684
- * Distinct from the CoinPayment / merchant-payments surface tracked under
685
- * `@parity/product-sdk-merchant-payments` (RFC-0017). RFC-0006 is the
686
- * user-initiated balance / top-up / payment-request flow; RFC-0017 is the
687
- * merchant-initiated checkout flow.
693
+ * Exposes balance subscription, top-up, payment requests, and payment-status
694
+ * subscription. Distinct from the CoinPayment / merchant-payments surface
695
+ * (RFC-0017): RFC-0006 is the user-initiated balance / top-up / payment-request
696
+ * flow.
688
697
  *
689
698
  * @module
690
699
  */
691
700
 
692
- /** Available balance for the user's payment account. Re-exported from `@novasamatech/host-api-wrapper`. */
693
- type PaymentBalance = PaymentBalance$1;
694
- /** Status of an in-flight payment request. Re-exported from `@novasamatech/host-api-wrapper`. */
695
- type PaymentStatus = PaymentStatus$1;
696
- /** Source for {@link PaymentManager.topUp}. Re-exported from `@novasamatech/host-api-wrapper`. */
697
- type TopUpSource = TopUpSource$1;
698
701
  /**
699
702
  * Payment manager handle. Exposes balance subscription, top-up, payment
700
- * requests, and payment status subscription.
701
- *
702
- * Type identical to `paymentManager` from `@novasamatech/host-api-wrapper`.
703
- */
704
- type PaymentManager = typeof paymentManager;
703
+ * requests, and payment-status subscription.
704
+ *
705
+ * The balance / status / top-up-source shapes are `@parity/truapi`'s
706
+ * `HostPaymentBalanceSubscribeItem`, `HostPaymentStatusSubscribeItem`, and
707
+ * `PaymentTopUpSource` used directly rather than re-aliased.
708
+ */
709
+ interface PaymentManager {
710
+ subscribeBalance(callback: (balance: HostPaymentBalanceSubscribeItem) => void, purse?: PaymentPurseId): HostSubscription;
711
+ topUp(amount: Balance, source: PaymentTopUpSource, into?: PaymentPurseId): Promise<void>;
712
+ requestPayment(amount: Balance, destination: HexString, from?: PaymentPurseId): Promise<{
713
+ id: string;
714
+ }>;
715
+ subscribePaymentStatus(paymentId: string, callback: (status: HostPaymentStatusSubscribeItem) => void): HostSubscription;
716
+ }
705
717
  /**
706
- * Get the host payment manager.
707
- *
708
- * Returns the shared `paymentManager` singleton from
709
- * `@novasamatech/host-api-wrapper`, or `null` if the package is unavailable
710
- * (running outside a host container or the optional peer dep isn't
711
- * installed).
718
+ * Get the host payment manager, backed by `truApi.payment.*`. Returns `null`
719
+ * when running outside a host container.
712
720
  *
713
721
  * @returns The payment manager, or `null` if unavailable.
714
722
  *
@@ -719,9 +727,8 @@ type PaymentManager = typeof paymentManager;
719
727
  * const payments = await getPaymentManager();
720
728
  * if (payments) {
721
729
  * const sub = payments.subscribeBalance((b) => { ... });
722
- * await payments.topUp(1_000_000n, { type: "productAccount", derivationIndex: 0 });
723
- * const destination = new Uint8Array(32);
724
- * const { id } = await payments.requestPayment(500n, destination);
730
+ * await payments.topUp(1_000_000n, { tag: "ProductAccount", value: { derivationIndex: 0 } });
731
+ * const { id } = await payments.requestPayment(500n, "0x…");
725
732
  * sub.unsubscribe();
726
733
  * }
727
734
  * ```
@@ -729,59 +736,41 @@ type PaymentManager = typeof paymentManager;
729
736
  declare function getPaymentManager(): Promise<PaymentManager | null>;
730
737
 
731
738
  /**
732
- * Wrapper for the host's scheduled push-notification surface.
739
+ * Wrapper for the host's scheduled push-notification surface (RFC-0019),
740
+ * backed by `truApi.notifications.*`.
733
741
  *
734
- * Shipped flat-in-host rather than as `getTruApi().notification.*` because
735
- * the upstream JS `hostApi` is itself a flat object - there is no
736
- * `.notification` accessor to mirror. A flat `getNotificationManager()`
737
- * matches the singleton pattern already used by {@link getPaymentManager},
738
- * {@link getPreimageManager}, and {@link getHostLocalStorage}.
739
- *
740
- * Returns the shared `notificationManager` singleton from
741
- * `@novasamatech/host-api-wrapper` (not a fresh `createNotificationManager()`
742
- * instance) so callers share one wrapper + hostApi closure across the app.
743
- *
744
- * {@link PushNotificationError} is re-exported from `@novasamatech/host-api`
745
- * so consumers can branch on `err instanceof
746
- * PushNotificationError.ScheduleLimitReached` (the host's pending-notification
747
- * cap) without importing the novasama packages directly.
742
+ * `getNotificationManager()` returns a handle exposing `push(input)` (resolves
743
+ * to a {@link NotificationId}) and `cancel(id)`, matching the singleton
744
+ * pattern already used by {@link getPaymentManager}, {@link getPreimageManager},
745
+ * and {@link getHostLocalStorage}.
748
746
  *
749
747
  * @module
750
748
  */
751
749
 
752
750
  /**
753
- * Host notification manager handle. Exposes `push(input)` (resolves to a
754
- * {@link NotificationId}) and `cancel(id)`.
755
- *
756
- * Type identical to `notificationManager` from
757
- * `@novasamatech/host-api-wrapper`.
758
- */
759
- type NotificationManager = typeof notificationManager;
760
- /**
761
- * Host-assigned id for a scheduled notification — pass to
762
- * {@link NotificationManager.cancel}. Derived from the manager's `push`
763
- * return type so codec changes surface here as compile errors.
751
+ * Push payload: `text`, an optional `deeplink`, and an optional `scheduledAt`
752
+ * (Unix timestamp in milliseconds; omit for immediate delivery). Re-exported
753
+ * from the truapi wire request type so the shape stays in lockstep with the
754
+ * protocol.
764
755
  */
765
- type NotificationId = Awaited<ReturnType<NotificationManager["push"]>>;
756
+ type PushNotificationInput = HostPushNotificationRequest;
766
757
  /**
767
- * Push payload: `text`, an optional `deeplink`, and an optional
768
- * `scheduledAt` (omit for immediate delivery). Derived from the manager's
769
- * `push` parameter so the shape stays in lockstep with upstream.
758
+ * Host notification manager handle. Exposes `push(input)` (resolves to a
759
+ * {@link NotificationId}) and `cancel(id)`.
770
760
  */
771
- type PushNotificationInput = Parameters<NotificationManager["push"]>[0];
761
+ interface NotificationManager {
762
+ push(input: PushNotificationInput): Promise<NotificationId>;
763
+ cancel(id: NotificationId): Promise<void>;
764
+ }
772
765
  /**
773
- * Get the host notification manager.
774
- *
775
- * Returns the shared `notificationManager` singleton from
776
- * `@novasamatech/host-api-wrapper`, or `null` if the package is unavailable
777
- * (running outside a host container or the optional peer dep isn't
778
- * installed).
766
+ * Get the host notification manager, backed by `truApi.notifications.*`.
767
+ * Returns `null` when running outside a host container.
779
768
  *
780
769
  * @returns The notification manager, or `null` if unavailable.
781
770
  *
782
771
  * @example
783
772
  * ```ts
784
- * import { getNotificationManager, PushNotificationError } from "@parity/product-sdk-host";
773
+ * import { getNotificationManager, type PushNotificationError } from "@parity/product-sdk-host";
785
774
  *
786
775
  * const notifications = await getNotificationManager();
787
776
  * if (notifications) {
@@ -792,7 +781,8 @@ type PushNotificationInput = Parameters<NotificationManager["push"]>[0];
792
781
  * });
793
782
  * // later: await notifications.cancel(id);
794
783
  * } catch (err) {
795
- * if (err instanceof PushNotificationError.ScheduleLimitReached) {
784
+ * const cause = (err as Error).cause as PushNotificationError | undefined;
785
+ * if (cause?.tag === "ScheduleLimitReached") {
796
786
  * // host hit its pending-notification cap — surface to the user
797
787
  * }
798
788
  * }
@@ -804,44 +794,43 @@ declare function getNotificationManager(): Promise<NotificationManager | null>;
804
794
  /**
805
795
  * Higher-level wrapper for the host's deep-link navigation.
806
796
  *
807
- * `hostApi.navigateTo` is reachable via {@link getTruApi}, but consumers have
808
- * to wrap the URL in the versioned envelope (`enumValue("v1", ...)`) and
809
- * unwrap the neverthrow `ResultAsync` themselves. {@link navigateTo} collapses
810
- * that to a throw-on-error Promise that matches the shape of
811
- * {@link requestPermission} and {@link deriveEntropy}.
797
+ * `truApi.system.navigateTo` returns a neverthrow `ResultAsync`; consumers
798
+ * still have to unwrap it themselves. {@link navigateTo} collapses that to a
799
+ * `Result<void, HostError>`-returning Promise.
812
800
  *
813
801
  * @module
814
802
  */
803
+
815
804
  /**
816
805
  * Ask the host to navigate to a URL (deep link or external link).
817
806
  *
818
- * Builds the `v1` envelope, calls `hostApi.navigateTo`, and unwraps the
819
- * response. The host resolves the destination itself — a `dot`-suffixed
820
- * deep link (e.g. `"https://search.dot"`) routes to another app/route inside
821
- * the container, an `https://` URL opens externally.
807
+ * Calls `truApi.system.navigateTo` and unwraps the response. The host resolves
808
+ * the destination itself — a `dot`-suffixed deep link (e.g.
809
+ * `"https://search.dot"`) routes to another app/route inside the container, an
810
+ * `https://` URL opens externally.
822
811
  *
823
812
  * @param url - The URL to navigate to.
824
- * @throws If the host is unavailable, denies the navigation
825
- * (`NavigateToErr::PermissionDenied`), or fails for any other reason
826
- * (`NavigateToErr::Unknown`).
813
+ * @returns `ok` on success, or `err`: {@link HostUnavailableError} if the host
814
+ * is unavailable, or {@link HostCallFailedError} if it denies the navigation
815
+ * (`NavigateToErr::PermissionDenied`) or fails otherwise (`NavigateToErr::Unknown`).
827
816
  *
828
817
  * @example
829
818
  * ```ts
830
819
  * import { navigateTo } from "@parity/product-sdk-host";
831
820
  *
832
- * await navigateTo("https://search.dot");
821
+ * const r = await navigateTo("https://search.dot");
822
+ * if (!r.ok) handle(r.error);
833
823
  * ```
834
824
  */
835
- declare function navigateTo(url: string): Promise<void>;
825
+ declare function navigateTo(url: string): Promise<Result<void, HostError>>;
836
826
 
837
827
  /**
838
828
  * Higher-level wrappers for the host's feature-support probe.
839
829
  *
840
- * `hostApi.featureSupported` is reachable via {@link getTruApi}, but consumers
841
- * have to wrap the feature in the versioned envelope (`enumValue("v1", ...)`)
842
- * and unwrap the neverthrow `ResultAsync` themselves. {@link featureSupported}
843
- * collapses that to a throw-on-error Promise; {@link isChainSupported} is a
844
- * convenience over the only feature variant the host exposes today (`Chain`).
830
+ * `truApi.system.featureSupported` returns a neverthrow `ResultAsync`;
831
+ * {@link featureSupported} collapses that to a `Result` carrying the host's
832
+ * boolean answer. {@link isChainSupported} is a convenience over the only
833
+ * feature variant the host exposes today (`Chain`).
845
834
  *
846
835
  * @module
847
836
  */
@@ -849,10 +838,11 @@ declare function navigateTo(url: string): Promise<void>;
849
838
  /**
850
839
  * A feature the host can be probed for via {@link featureSupported}.
851
840
  *
852
- * As of `host-api` v0.8 the only variant is `Chain`, carrying the chain's
853
- * `0x`-prefixed genesis hash. Modeled locally (rather than derived from an
854
- * upstream codec) because the protocol exposes the feature only inline; new
855
- * variants surface here as a widening of the union.
841
+ * The only variant today is `Chain`, carrying the chain's `0x`-prefixed genesis
842
+ * hash. This is a flattened form of truapi's `HostFeatureSupportedRequest`,
843
+ * which nests the hash as `{ tag: "Chain"; value: { genesisHash } }` — we
844
+ * inline `value` as the `HexString` for ergonomics and re-nest it at the call
845
+ * site. New variants surface here as a widening of the union.
856
846
  */
857
847
  type Feature = {
858
848
  tag: "Chain";
@@ -861,49 +851,51 @@ type Feature = {
861
851
  /**
862
852
  * Probe the host for support of a specific feature.
863
853
  *
864
- * Builds the `v1` envelope, calls `hostApi.featureSupported`, unwraps the
865
- * response, and returns the host's boolean answer.
854
+ * Calls `truApi.system.featureSupported`, unwraps the response, and returns the
855
+ * host's boolean answer.
866
856
  *
867
857
  * @param feature - The feature to probe for.
868
- * @returns `true` if the host supports the feature, `false` otherwise.
869
- * @throws If the host is unavailable or the probe fails (`GenericError`).
858
+ * @returns `ok(true)` if the host supports the feature, `ok(false)` otherwise,
859
+ * or `err(HostUnavailableError | HostCallFailedError)`.
870
860
  *
871
861
  * @example
872
862
  * ```ts
873
863
  * import { featureSupported } from "@parity/product-sdk-host";
874
864
  *
875
- * const ok = await featureSupported({ tag: "Chain", value: genesisHash });
865
+ * const r = await featureSupported({ tag: "Chain", value: genesisHash });
866
+ * if (r.ok && r.value) { ... }
876
867
  * ```
877
868
  */
878
- declare function featureSupported(feature: Feature): Promise<boolean>;
869
+ declare function featureSupported(feature: Feature): Promise<Result<boolean, HostError>>;
879
870
  /**
880
871
  * Convenience probe: is the chain with the given genesis hash supported by the
881
872
  * host? Wraps {@link featureSupported} for the `Chain` feature variant.
882
873
  *
883
874
  * @param genesisHash - The chain's `0x`-prefixed genesis hash.
884
- * @returns `true` if the host supports the chain, `false` otherwise.
885
- * @throws If the host is unavailable or the probe fails.
875
+ * @returns `ok(true)` if the host supports the chain, `ok(false)` otherwise, or
876
+ * `err(HostUnavailableError | HostCallFailedError)`.
886
877
  *
887
878
  * @example
888
879
  * ```ts
889
880
  * import { isChainSupported } from "@parity/product-sdk-host";
890
881
  *
891
- * if (!(await isChainSupported(genesisHash))) {
882
+ * const r = await isChainSupported(genesisHash);
883
+ * if (!r.ok || !r.value) {
892
884
  * tellUserChainUnavailable();
893
885
  * }
894
886
  * ```
895
887
  */
896
- declare function isChainSupported(genesisHash: HexString): Promise<boolean>;
888
+ declare function isChainSupported(genesisHash: HexString): Promise<Result<boolean, HostError>>;
897
889
 
898
890
  /**
899
891
  * Higher-level wrapper for the host's chain-spec lookups.
900
892
  *
901
- * The host exposes three separate chain-spec calls — `chainSpecGenesisHash`,
902
- * `chainSpecChainName`, and `chainSpecProperties` — each reachable via
903
- * {@link getTruApi} but each requiring its own `enumValue("v1", ...)` wrap
904
- * and neverthrow `ResultAsync` unwrap. {@link getChainSpec} fetches all three
905
- * in one call and returns a single struct so callers read whichever field
906
- * they need, matching the JSON-RPC `chainSpec_v1_*` family they mirror.
893
+ * The host exposes three separate chain-spec calls — `chain.getSpecGenesisHash`,
894
+ * `chain.getSpecChainName`, and `chain.getSpecProperties` — each reachable via
895
+ * {@link getTruApi} and each returning a neverthrow `ResultAsync`.
896
+ * {@link getChainSpec} fetches all three in one call and returns a single
897
+ * struct so callers read whichever field they need, matching the JSON-RPC
898
+ * `chainSpec_v1_*` family they mirror.
907
899
  *
908
900
  * @module
909
901
  */
@@ -914,8 +906,8 @@ declare function isChainSupported(genesisHash: HexString): Promise<boolean>;
914
906
  *
915
907
  * The host returns this as a JSON string (mirroring the substrate
916
908
  * `chainSpec_v1_properties` JSON-RPC, whose payload is an open-ended object).
917
- * {@link getChainSpec} parses it into {@link properties} and also surfaces the
918
- * untouched JSON as {@link propertiesRaw}. The well-known substrate fields are
909
+ * {@link getChainSpec} parses it into {@link ChainSpec.properties} and also
910
+ * surfaces the untouched JSON as {@link ChainSpec.propertiesRaw}. The well-known substrate fields are
919
911
  * typed for convenience; the index signature keeps any chain-specific extras
920
912
  * reachable without `any` at the call site.
921
913
  */
@@ -949,37 +941,41 @@ interface ChainSpec {
949
941
  * Fetch a chain's full spec (genesis hash, name, and properties) from the host
950
942
  * in one call.
951
943
  *
952
- * Issues the three underlying `chainSpec*` requests concurrently, unwraps each
953
- * `v1` envelope, and parses the properties JSON. Note the `genesisHash` in the
954
- * result is the value the host echoes back from `chainSpecGenesisHash` for the
944
+ * Issues the three underlying `chain.getSpec*` requests concurrently, unwraps
945
+ * each response, and parses the properties JSON. Note the `genesisHash` in the
946
+ * result is the value the host echoes back from `getSpecGenesisHash` for the
955
947
  * looked-up chain — pass the chain's known genesis hash as the lookup key.
956
948
  *
949
+ * `null` (outside a container) is preserved as an `ok` value — it is an
950
+ * expected state, not a failure — so callers branch on `r.ok && r.value`. A
951
+ * real host-call failure surfaces on the `err` channel.
952
+ *
957
953
  * @param genesisHash - The `0x`-prefixed genesis hash identifying the chain.
958
- * @returns The combined {@link ChainSpec}, or `null` if the host is
959
- * unavailable (running outside a container).
960
- * @throws If any of the underlying host calls fail (`GenericError`).
954
+ * @returns `ok(spec)` with the combined {@link ChainSpec}, `ok(null)` if the
955
+ * host is unavailable (running outside a container), or
956
+ * `err(HostCallFailedError)` if any underlying host call fails.
961
957
  *
962
958
  * @example
963
959
  * ```ts
964
960
  * import { getChainSpec } from "@parity/product-sdk-host";
965
961
  *
966
- * const spec = await getChainSpec(genesisHash);
967
- * if (spec) {
968
- * console.log(spec.name, spec.properties?.tokenSymbol);
962
+ * const r = await getChainSpec(genesisHash);
963
+ * if (r.ok && r.value) {
964
+ * console.log(r.value.name, r.value.properties?.tokenSymbol);
969
965
  * }
970
966
  * ```
971
967
  */
972
- declare function getChainSpec(genesisHash: HexString): Promise<ChainSpec | null>;
968
+ declare function getChainSpec(genesisHash: HexString): Promise<Result<ChainSpec | null, HostError>>;
973
969
 
974
970
  /**
975
971
  * Higher-level wrappers for the host's transaction broadcast lifecycle.
976
972
  *
977
- * `hostApi.chainTransactionBroadcast` / `hostApi.chainTransactionStop` are
978
- * reachable via {@link getTruApi}, but consumers have to build the versioned
979
- * envelope (`enumValue("v1", ...)`) and unwrap the neverthrow `ResultAsync`
980
- * themselves. {@link broadcastTransaction} and {@link stopTransaction}
981
- * collapse that to throw-on-error Promises, mirroring the JSON-RPC
982
- * `transaction_v1_broadcast` / `transaction_v1_stop` pair they wrap.
973
+ * `truApi.chain.broadcastTransaction` / `truApi.chain.stopTransaction` are
974
+ * reachable via {@link getTruApi}, but consumers have to unwrap the neverthrow
975
+ * `ResultAsync` themselves. {@link broadcastTransaction} and
976
+ * {@link stopTransaction} collapse that to `Result`-returning Promises, mirroring
977
+ * the JSON-RPC `transaction_v1_broadcast` / `transaction_v1_stop` pair they
978
+ * wrap.
983
979
  *
984
980
  * @module
985
981
  */
@@ -987,43 +983,41 @@ declare function getChainSpec(genesisHash: HexString): Promise<ChainSpec | null>
987
983
  /**
988
984
  * Broadcast a signed transaction to the network via the host.
989
985
  *
990
- * Builds the `v1` envelope, calls `hostApi.chainTransactionBroadcast`, and
991
- * unwraps the response. The host keeps re-broadcasting until the transaction
992
- * is finalized/dropped or {@link stopTransaction} is called with the returned
993
- * operation id.
986
+ * Calls `truApi.chain.broadcastTransaction` and unwraps the response. The host
987
+ * keeps re-broadcasting until the transaction is finalized/dropped or
988
+ * {@link stopTransaction} is called with the returned operation id.
994
989
  *
995
990
  * @param genesisHash - The `0x`-prefixed genesis hash of the target chain.
996
991
  * @param transaction - The `0x`-prefixed SCALE-encoded signed transaction.
997
- * @returns The operation id to pass to {@link stopTransaction}, or `null` if
998
- * the host accepted the broadcast without issuing one.
999
- * @throws If the host is unavailable or the broadcast fails (`GenericError`).
992
+ * @returns `ok` with the operation id to pass to {@link stopTransaction} (or
993
+ * `null` if the host accepted the broadcast without issuing one), or
994
+ * `err(HostUnavailableError | HostCallFailedError)`.
1000
995
  *
1001
996
  * @example
1002
997
  * ```ts
1003
998
  * import { broadcastTransaction, stopTransaction } from "@parity/product-sdk-host";
1004
999
  *
1005
- * const operationId = await broadcastTransaction(genesisHash, signedTx);
1000
+ * const r = await broadcastTransaction(genesisHash, signedTx);
1006
1001
  * // later, to stop re-broadcasting:
1007
- * if (operationId) await stopTransaction(genesisHash, operationId);
1002
+ * if (r.ok && r.value) await stopTransaction(genesisHash, r.value);
1008
1003
  * ```
1009
1004
  */
1010
- declare function broadcastTransaction(genesisHash: HexString, transaction: HexString): Promise<string | null>;
1005
+ declare function broadcastTransaction(genesisHash: HexString, transaction: HexString): Promise<Result<string | null, HostError>>;
1011
1006
  /**
1012
1007
  * Stop an in-flight broadcast started by {@link broadcastTransaction}.
1013
1008
  *
1014
- * Builds the `v1` envelope, calls `hostApi.chainTransactionStop`, and unwraps
1015
- * the response.
1009
+ * Calls `truApi.chain.stopTransaction` and unwraps the response.
1016
1010
  *
1017
1011
  * @param genesisHash - The `0x`-prefixed genesis hash of the target chain.
1018
1012
  * @param operationId - The operation id returned by
1019
1013
  * {@link broadcastTransaction}.
1020
- * @throws If the host is unavailable or the stop fails (`GenericError`).
1014
+ * @returns `ok` on success, or `err(HostUnavailableError | HostCallFailedError)`.
1021
1015
  *
1022
1016
  * @example
1023
1017
  * ```ts
1024
1018
  * await stopTransaction(genesisHash, operationId);
1025
1019
  * ```
1026
1020
  */
1027
- declare function stopTransaction(genesisHash: HexString, operationId: string): Promise<void>;
1021
+ declare function stopTransaction(genesisHash: HexString, operationId: string): Promise<Result<void, HostError>>;
1028
1022
 
1029
- export { type AccountsProvider, type AllocatableResource, type AllocatableResourceTag, type AllocationOutcome, type AllocationOutcomeTag, BULLETIN_RPCS, ChainNotSupportedError, type ChainProperties, type ChainSpec, type ChatBotRegistrationResult, type ChatCustomMessageRenderer, type ChatCustomMessageRendererParams, type ChatManager, type ChatMessageContent, type ChatReceivedAction, type ChatRoom, type ChatRoomRegistrationResult, type ContextualAlias, DEFAULT_BULLETIN_ENDPOINT, type DevicePermissionKind, type Feature, type HostAccount, type HostLocalStorage, type HostStatementStore, type HostSubscription, type NotificationId, type NotificationManager, type PaymentBalance, type PaymentManager, type PaymentStatus, type PreimageManager, type ProductAccount, type ProductAccountId, type PushNotificationInput, type RemotePermission, type RemotePermissionItem, type RemotePermissionTag, type ResultAsync, type SignedStatement, type Statement, type StatementProof, type StatementTopicFilter, type StatementsPage, type ThemeMode, type ThemeName, type ThemeProvider, type ThemeVariant, type TopUpSource, type Topic, type TruApi, broadcastTransaction, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, featureSupported, formatHostError, getAccountsProvider, getChainSpec, getChatManager, getHostLocalStorage, getHostProvider, getNotificationManager, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isChainSupported, isInsideContainer, isInsideContainerSync, matchChatCustomRenderers, navigateTo, requestDevicePermission, requestPermission, requestResourceAllocation, stopTransaction };
1023
+ export { type AccountsProvider, BULLETIN_RPCS, ChainNotSupportedError, type ChainProperties, type ChainSpec, type ChatBotRegistrationResult, type ChatManager, type ChatReceivedAction, type ChatRoomRegistrationResult, type ContextualAlias, DEFAULT_BULLETIN_ENDPOINT, type DevicePermissionKind, type Feature, type HostAccount, HostCallFailedError, HostError, type HostErrorPayload, type HostLocalStorage, type HostStatementStore, type HostSubscription, HostUnavailableError, type NotificationManager, type PaymentManager, type PreimageManager, type ProductAccount, type PushNotificationInput, type RemotePermissionItem, type Result, type ResultAsync, type StatementTopicFilter, type StatementsPage, type ThemeMode, type ThemeProvider, type TruApi, broadcastTransaction, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, err, featureSupported, formatHostError, fromHex, getAccountsProvider, getChainSpec, getChatManager, getHostLocalStorage, getHostProvider, getNotificationManager, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isChainSupported, isHostError, isInsideContainer, navigateTo, ok, requestDevicePermission, requestPermission, requestResourceAllocation, stopTransaction, toHex };