@parity/product-sdk-host 0.10.2 → 0.11.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { JsonRpcProvider } from 'polkadot-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';
+import { Subscription, Transport, CodecType, AllocatableResource as AllocatableResource$1, AllocationOutcome as AllocationOutcome$1, RemotePermission as RemotePermission$1, DevicePermission, HexString } from '@novasamatech/host-api';
 export { HexString, PushNotificationError, 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, notificationManager } from '@novasamatech/host-api-wrapper';
@@ -801,4 +801,229 @@ type PushNotificationInput = Parameters<NotificationManager["push"]>[0];
  */
 declare function getNotificationManager(): Promise<NotificationManager | null>;
 
-export { type AccountsProvider, type AllocatableResource, type AllocatableResourceTag, type AllocationOutcome, type AllocationOutcomeTag, BULLETIN_RPCS, ChainNotSupportedError, 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 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, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, formatHostError, getAccountsProvider, getChatManager, getHostLocalStorage, getHostProvider, getNotificationManager, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isInsideContainer, isInsideContainerSync, matchChatCustomRenderers, requestDevicePermission, requestPermission, requestResourceAllocation };
+/**
+ * Higher-level wrapper for the host's deep-link navigation.
+ *
+ * `hostApi.navigateTo` is reachable via {@link getTruApi}, but consumers have
+ * to wrap the URL in the versioned envelope (`enumValue("v1", ...)`) and
+ * unwrap the neverthrow `ResultAsync` themselves. {@link navigateTo} collapses
+ * that to a throw-on-error Promise that matches the shape of
+ * {@link requestPermission} and {@link deriveEntropy}.
+ *
+ * @module
+ */
+/**
+ * Ask the host to navigate to a URL (deep link or external link).
+ *
+ * Builds the `v1` envelope, calls `hostApi.navigateTo`, and unwraps the
+ * response. The host resolves the destination itself — a `dot`-suffixed
+ * deep link (e.g. `"https://search.dot"`) routes to another app/route inside
+ * the container, an `https://` URL opens externally.
+ *
+ * @param url - The URL to navigate to.
+ * @throws If the host is unavailable, denies the navigation
+ *   (`NavigateToErr::PermissionDenied`), or fails for any other reason
+ *   (`NavigateToErr::Unknown`).
+ *
+ * @example
+ * ```ts
+ * import { navigateTo } from "@parity/product-sdk-host";
+ *
+ * await navigateTo("https://search.dot");
+ * ```
+ */
+declare function navigateTo(url: string): Promise<void>;
+
+/**
+ * Higher-level wrappers for the host's feature-support probe.
+ *
+ * `hostApi.featureSupported` is reachable via {@link getTruApi}, but consumers
+ * have to wrap the feature in the versioned envelope (`enumValue("v1", ...)`)
+ * and unwrap the neverthrow `ResultAsync` themselves. {@link featureSupported}
+ * collapses that to a throw-on-error Promise; {@link isChainSupported} is a
+ * convenience over the only feature variant the host exposes today (`Chain`).
+ *
+ * @module
+ */
+
+/**
+ * A feature the host can be probed for via {@link featureSupported}.
+ *
+ * As of `host-api` v0.8 the only variant is `Chain`, carrying the chain's
+ * `0x`-prefixed genesis hash. Modeled locally (rather than derived from an
+ * upstream codec) because the protocol exposes the feature only inline; new
+ * variants surface here as a widening of the union.
+ */
+type Feature = {
+    tag: "Chain";
+    value: HexString;
+};
+/**
+ * Probe the host for support of a specific feature.
+ *
+ * Builds the `v1` envelope, calls `hostApi.featureSupported`, unwraps the
+ * response, and returns the host's boolean answer.
+ *
+ * @param feature - The feature to probe for.
+ * @returns `true` if the host supports the feature, `false` otherwise.
+ * @throws If the host is unavailable or the probe fails (`GenericError`).
+ *
+ * @example
+ * ```ts
+ * import { featureSupported } from "@parity/product-sdk-host";
+ *
+ * const ok = await featureSupported({ tag: "Chain", value: genesisHash });
+ * ```
+ */
+declare function featureSupported(feature: Feature): Promise<boolean>;
+/**
+ * Convenience probe: is the chain with the given genesis hash supported by the
+ * host? Wraps {@link featureSupported} for the `Chain` feature variant.
+ *
+ * @param genesisHash - The chain's `0x`-prefixed genesis hash.
+ * @returns `true` if the host supports the chain, `false` otherwise.
+ * @throws If the host is unavailable or the probe fails.
+ *
+ * @example
+ * ```ts
+ * import { isChainSupported } from "@parity/product-sdk-host";
+ *
+ * if (!(await isChainSupported(genesisHash))) {
+ *   tellUserChainUnavailable();
+ * }
+ * ```
+ */
+declare function isChainSupported(genesisHash: HexString): Promise<boolean>;
+
+/**
+ * Higher-level wrapper for the host's chain-spec lookups.
+ *
+ * The host exposes three separate chain-spec calls — `chainSpecGenesisHash`,
+ * `chainSpecChainName`, and `chainSpecProperties` — each reachable via
+ * {@link getTruApi} but each requiring its own `enumValue("v1", ...)` wrap
+ * and neverthrow `ResultAsync` unwrap. {@link getChainSpec} fetches all three
+ * in one call and returns a single struct so callers read whichever field
+ * they need, matching the JSON-RPC `chainSpec_v1_*` family they mirror.
+ *
+ * @module
+ */
+
+/**
+ * Chain SS58/token properties as reported by the host's
+ * `chainSpecProperties` call.
+ *
+ * The host returns this as a JSON string (mirroring the substrate
+ * `chainSpec_v1_properties` JSON-RPC, whose payload is an open-ended object).
+ * {@link getChainSpec} parses it into {@link properties} and also surfaces the
+ * untouched JSON as {@link propertiesRaw}. The well-known substrate fields are
+ * typed for convenience; the index signature keeps any chain-specific extras
+ * reachable without `any` at the call site.
+ */
+interface ChainProperties {
+    /** Address prefix used for SS58 encoding (e.g. `0` for Polkadot). */
+    ss58Format?: number;
+    /** Decimal places of the chain's native token(s). */
+    tokenDecimals?: number | number[];
+    /** Ticker symbol(s) of the chain's native token(s). */
+    tokenSymbol?: string | string[];
+    /** Chain-specific extras passed through verbatim from the JSON payload. */
+    [key: string]: unknown;
+}
+/**
+ * Combined chain-spec view returned by {@link getChainSpec}.
+ */
+interface ChainSpec {
+    /** The chain's `0x`-prefixed genesis hash, as reported by the host. */
+    genesisHash: HexString;
+    /** Human-readable chain name (e.g. `"Polkadot"`). */
+    name: string;
+    /**
+     * Parsed chain properties, or `null` if the host's JSON payload couldn't
+     * be parsed. Inspect {@link propertiesRaw} for the original string.
+     */
+    properties: ChainProperties | null;
+    /** The untouched JSON string the host returned for properties. */
+    propertiesRaw: string;
+}
+/**
+ * Fetch a chain's full spec (genesis hash, name, and properties) from the host
+ * in one call.
+ *
+ * Issues the three underlying `chainSpec*` requests concurrently, unwraps each
+ * `v1` envelope, and parses the properties JSON. Note the `genesisHash` in the
+ * result is the value the host echoes back from `chainSpecGenesisHash` for the
+ * looked-up chain — pass the chain's known genesis hash as the lookup key.
+ *
+ * @param genesisHash - The `0x`-prefixed genesis hash identifying the chain.
+ * @returns The combined {@link ChainSpec}, or `null` if the host is
+ *   unavailable (running outside a container).
+ * @throws If any of the underlying host calls fail (`GenericError`).
+ *
+ * @example
+ * ```ts
+ * import { getChainSpec } from "@parity/product-sdk-host";
+ *
+ * const spec = await getChainSpec(genesisHash);
+ * if (spec) {
+ *   console.log(spec.name, spec.properties?.tokenSymbol);
+ * }
+ * ```
+ */
+declare function getChainSpec(genesisHash: HexString): Promise<ChainSpec | null>;
+
+/**
+ * Higher-level wrappers for the host's transaction broadcast lifecycle.
+ *
+ * `hostApi.chainTransactionBroadcast` / `hostApi.chainTransactionStop` are
+ * reachable via {@link getTruApi}, but consumers have to build the versioned
+ * envelope (`enumValue("v1", ...)`) and unwrap the neverthrow `ResultAsync`
+ * themselves. {@link broadcastTransaction} and {@link stopTransaction}
+ * collapse that to throw-on-error Promises, mirroring the JSON-RPC
+ * `transaction_v1_broadcast` / `transaction_v1_stop` pair they wrap.
+ *
+ * @module
+ */
+
+/**
+ * Broadcast a signed transaction to the network via the host.
+ *
+ * Builds the `v1` envelope, calls `hostApi.chainTransactionBroadcast`, and
+ * unwraps the response. The host keeps re-broadcasting until the transaction
+ * is finalized/dropped or {@link stopTransaction} is called with the returned
+ * operation id.
+ *
+ * @param genesisHash - The `0x`-prefixed genesis hash of the target chain.
+ * @param transaction - The `0x`-prefixed SCALE-encoded signed transaction.
+ * @returns The operation id to pass to {@link stopTransaction}, or `null` if
+ *   the host accepted the broadcast without issuing one.
+ * @throws If the host is unavailable or the broadcast fails (`GenericError`).
+ *
+ * @example
+ * ```ts
+ * import { broadcastTransaction, stopTransaction } from "@parity/product-sdk-host";
+ *
+ * const operationId = await broadcastTransaction(genesisHash, signedTx);
+ * // later, to stop re-broadcasting:
+ * if (operationId) await stopTransaction(genesisHash, operationId);
+ * ```
+ */
+declare function broadcastTransaction(genesisHash: HexString, transaction: HexString): Promise<string | null>;
+/**
+ * Stop an in-flight broadcast started by {@link broadcastTransaction}.
+ *
+ * Builds the `v1` envelope, calls `hostApi.chainTransactionStop`, and unwraps
+ * the response.
+ *
+ * @param genesisHash - The `0x`-prefixed genesis hash of the target chain.
+ * @param operationId - The operation id returned by
+ *   {@link broadcastTransaction}.
+ * @throws If the host is unavailable or the stop fails (`GenericError`).
+ *
+ * @example
+ * ```ts
+ * await stopTransaction(genesisHash, operationId);
+ * ```
+ */
+declare function stopTransaction(genesisHash: HexString, operationId: string): Promise<void>;
+
+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 };

package/dist/index.js

@@ -296,7 +296,110 @@ async function getNotificationManager() {
     return null;
   }
 }
+var log9 = createLogger("host:navigation");
+async function navigateTo(url) {
+  const truApi = await getTruApi();
+  if (!truApi) {
+    throw new Error("navigateTo: TruAPI unavailable");
+  }
+  log9.debug("navigateTo", { url });
+  await truApi.navigateTo(enumValue("v1", url)).match(
+    (_envelope) => void 0,
+    (err) => {
+      throw new Error(`navigateTo failed: ${formatHostError(err)}`, { cause: err });
+    }
+  );
+}
+var log10 = createLogger("host:features");
+async function featureSupported(feature) {
+  const truApi = await getTruApi();
+  if (!truApi) {
+    throw new Error("featureSupported: TruAPI unavailable");
+  }
+  log10.debug("featureSupported", { tag: feature.tag });
+  return await truApi.featureSupported(enumValue("v1", feature)).match(
+    (envelope) => envelope.value,
+    (err) => {
+      throw new Error(`featureSupported failed: ${formatHostError(err)}`, { cause: err });
+    }
+  );
+}
+async function isChainSupported(genesisHash) {
+  return await featureSupported({ tag: "Chain", value: genesisHash });
+}
+var log11 = createLogger("host:chain-spec");
+async function getChainSpec(genesisHash) {
+  const truApi = await getTruApi();
+  if (!truApi) {
+    log11.debug("getChainSpec: TruAPI unavailable");
+    return null;
+  }
+  log11.debug("getChainSpec", { genesisHash });
+  const [resolvedGenesisHash, name, propertiesRaw] = await Promise.all([
+    truApi.chainSpecGenesisHash(enumValue("v1", genesisHash)).match(
+      (envelope) => envelope.value,
+      (err) => {
+        throw new Error(`getChainSpec (genesisHash) failed: ${formatHostError(err)}`, {
+          cause: err
+        });
+      }
+    ),
+    truApi.chainSpecChainName(enumValue("v1", genesisHash)).match(
+      (envelope) => envelope.value,
+      (err) => {
+        throw new Error(`getChainSpec (chainName) failed: ${formatHostError(err)}`, {
+          cause: err
+        });
+      }
+    ),
+    truApi.chainSpecProperties(enumValue("v1", genesisHash)).match(
+      (envelope) => envelope.value,
+      (err) => {
+        throw new Error(`getChainSpec (properties) failed: ${formatHostError(err)}`, {
+          cause: err
+        });
+      }
+    )
+  ]);
+  let properties;
+  try {
+    properties = JSON.parse(propertiesRaw);
+  } catch (err) {
+    log11.debug("getChainSpec: properties JSON parse failed", err);
+    properties = null;
+  }
+  return { genesisHash: resolvedGenesisHash, name, properties, propertiesRaw };
+}
+var log12 = createLogger("host:chain-transaction");
+async function broadcastTransaction(genesisHash, transaction) {
+  const truApi = await getTruApi();
+  if (!truApi) {
+    throw new Error("broadcastTransaction: TruAPI unavailable");
+  }
+  log12.debug("broadcastTransaction", { genesisHash });
+  return await truApi.chainTransactionBroadcast(enumValue("v1", { genesisHash, transaction })).match(
+    (envelope) => envelope.value,
+    (err) => {
+      throw new Error(`broadcastTransaction failed: ${formatHostError(err)}`, {
+        cause: err
+      });
+    }
+  );
+}
+async function stopTransaction(genesisHash, operationId) {
+  const truApi = await getTruApi();
+  if (!truApi) {
+    throw new Error("stopTransaction: TruAPI unavailable");
+  }
+  log12.debug("stopTransaction", { genesisHash, operationId });
+  await truApi.chainTransactionStop(enumValue("v1", { genesisHash, operationId })).match(
+    (_envelope) => void 0,
+    (err) => {
+      throw new Error(`stopTransaction failed: ${formatHostError(err)}`, { cause: err });
+    }
+  );
+}
 
-export { BULLETIN_RPCS, ChainNotSupportedError, DEFAULT_BULLETIN_ENDPOINT, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, formatHostError, getAccountsProvider, getChatManager, getHostLocalStorage, getHostProvider, getNotificationManager, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isInsideContainer, isInsideContainerSync, matchChatCustomRenderers, requestDevicePermission, requestPermission, requestResourceAllocation };
+export { BULLETIN_RPCS, ChainNotSupportedError, DEFAULT_BULLETIN_ENDPOINT, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map