@parity/product-sdk-signer 0.6.4 → 0.8.0

package/dist/index.d.ts

@@ -199,7 +199,18 @@ type OnConnect = (account: SignerAccount, ctx: ConnectContext) => void | Promise
 declare class SignerError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
-/** The Host API is not available (product-sdk not installed or not inside a container). */
+/**
+ * The Host API is not available.
+ *
+ * Common causes:
+ * - The app is loaded outside a Polkadot host container (a regular browser tab
+ *   under `npm run dev`, no iframe, no WebView). This is the dominant case
+ *   during local development.
+ * - The optional `@novasamatech/host-api(-wrapper)` peer is not installed.
+ *
+ * Branch with `instanceof HostUnavailableError` to surface a "open this app
+ * in a Polkadot host, or pick a dev provider" message to the user.
+ */
 declare class HostUnavailableError extends SignerError {
     constructor(message?: string);
 }
@@ -277,8 +288,6 @@ interface HostProviderOptions {
      * `dotNsIdentifier`, skipping the legacy fetch entirely. For apps
      * that sign exclusively with a per-dapp derived account.
      *
-     * `SignerAccount.name` is populated best-effort from
-     * `accounts.getUserId().primaryUsername`; failures leave it null.
      * Signing is pinned to `createTransaction` (see PR #96).
      */
     productAccount?: {
@@ -286,6 +295,20 @@ interface HostProviderOptions {
         dotNsIdentifier: string;
         /** Derivation index within the app scope. Default: 0. */
         derivationIndex?: number;
+        /**
+         * Populate `SignerAccount.name` best-effort from
+         * `accounts.getUserId().primaryUsername`.
+         *
+         * On by default. Set to `false` to skip the fetch: `getUserId`
+         * triggers a host identity-permission prompt, so apps that don't
+         * render the user's name (those with their own display chain, e.g.
+         * registry username → fallback) can opt out and avoid the prompt.
+         * When enabled and the fetch fails (NotConnected, PermissionDenied,
+         * codec drift) the name stays null and connect still succeeds. The
+         * name can also be fetched later on demand via
+         * {@link HostProvider.getUserId}. Default: `true`.
+         */
+        requestName?: boolean;
     };
 }
 /**
@@ -368,13 +391,28 @@ interface ProductSdkModule {
     createAccountsProvider: () => AccountsProvider;
     /** Present from product-sdk ≥ 0.6; used to request TransactionSubmit. */
     hostApi?: HostApiPermissionBridge;
+    /**
+     * `sandboxTransport.isCorrectEnvironment()` returns `false` when the app
+     * is loaded outside a Polkadot host container (e.g. a regular browser
+     * tab). Calling `getLegacyAccounts()` / `getProductAccount()` in that
+     * state surfaces the upstream `Environment is not correct` exception,
+     * so we pre-check during `connect()` and raise a specific
+     * {@link HostUnavailableError} with actionable guidance instead.
+     */
+    sandboxTransport?: {
+        isCorrectEnvironment(): boolean;
+    };
 }
 /**
  * Provider for the Host API (Polkadot Desktop / Android).
  *
- * Dynamically imports `@novasamatech/host-api-wrapper` at runtime so it remains
- * an optional peer dependency. Apps running outside a host container will
- * gracefully get a `HOST_UNAVAILABLE` error.
+ * Dynamically imports `@novasamatech/host-api-wrapper` at runtime. Apps running
+ * outside a host container — e.g. a plain browser tab during `npm run dev` —
+ * resolve to {@link HostUnavailableError} with guidance on what to do (open
+ * the app inside a Polkadot host or pick a non-host provider). The check uses
+ * the wrapper's `sandboxTransport.isCorrectEnvironment()` predicate and runs
+ * before any host RPC call, so the user never sees the upstream
+ * `Environment is not correct` exception leaking through.
  *
  * Supports both non-product accounts (user's external wallets) and product
  * accounts (app-scoped derived accounts managed by the host).
@@ -429,6 +467,22 @@ declare class HostProvider implements SignerProvider {
      * Requires a prior successful `connect()` call.
      */
     getProductAccountAlias(dotNsIdentifier: string, derivationIndex?: number): Promise<Result<ContextualAlias, SignerError>>;
+    /**
+     * Fetch the connected user's primary username from the host.
+     *
+     * Use this to retrieve the name lazily — e.g. on a profile screen that
+     * actually displays it — when `connect()` ran without
+     * `productAccount.requestName` (the default) and so never fetched it.
+     * Like the connect-time fetch this triggers a host identity-permission
+     * prompt; unlike it, the result is returned as a structured `Result` so
+     * callers can react to a `PermissionDenied` / `NotConnected` rejection
+     * explicitly instead of silently falling back to a nameless account.
+     *
+     * Requires a prior successful `connect()` call.
+     */
+    getUserId(): Promise<Result<{
+        primaryUsername: string;
+    }, SignerError>>;
     /**
      * Create a Ring VRF proof for anonymous operations.
      *
@@ -589,6 +643,17 @@ declare class SignerManager {
      * Returns a SIGNING_FAILED error if no account is selected or signing fails.
      */
     signRaw(data: Uint8Array): Promise<Result<Uint8Array, SignerError>>;
+    /**
+     * Fetch the connected user's host identity.
+     *
+     * This uses the Host API identity permission path and is only available
+     * when connected through the host provider. The primary username can be
+     * used by higher-level helpers that need to bind an action to the user's
+     * DotNS / people username.
+     */
+    getUserId(): Promise<Result<{
+        primaryUsername: string;
+    }, SignerError>>;
     /**
      * Get an app-scoped product account from the host.
      *

package/dist/index.js

@@ -348,6 +348,40 @@ var HostProvider = class {
       );
     }
   }
+  /**
+   * Fetch the connected user's primary username from the host.
+   *
+   * Use this to retrieve the name lazily — e.g. on a profile screen that
+   * actually displays it — when `connect()` ran without
+   * `productAccount.requestName` (the default) and so never fetched it.
+   * Like the connect-time fetch this triggers a host identity-permission
+   * prompt; unlike it, the result is returned as a structured `Result` so
+   * callers can react to a `PermissionDenied` / `NotConnected` rejection
+   * explicitly instead of silently falling back to a nameless account.
+   *
+   * Requires a prior successful `connect()` call.
+   */
+  async getUserId() {
+    if (!this.accountsProvider) {
+      return err(new HostUnavailableError("Host provider is not connected"));
+    }
+    try {
+      const result = await this.accountsProvider.getUserId().match(
+        (value) => value,
+        (error) => {
+          throw new Error(`Host rejected user id request: ${formatError(error)}`);
+        }
+      );
+      return ok(result);
+    } catch (cause) {
+      log2.error("failed to get user id", { cause });
+      return err(
+        new HostRejectedError(
+          cause instanceof Error ? cause.message : "Failed to get user id"
+        )
+      );
+    }
+  }
   /**
    * Create a Ring VRF proof for anonymous operations.
    *
@@ -392,6 +426,14 @@ var HostProvider = class {
         )
       );
     }
+    if (sdk.sandboxTransport && !sdk.sandboxTransport.isCorrectEnvironment()) {
+      log2.warn("not inside a host container \u2014 Host API unavailable");
+      return err(
+        new HostUnavailableError(
+          "Host API is not available: not running inside a Polkadot host container. Open this app inside Polkadot Desktop or the Polkadot Mobile WebView, or pick a non-host signer provider (e.g. dev accounts)."
+        )
+      );
+    }
     const provider = sdk.createAccountsProvider();
     this.accountsProvider = provider;
     let signerAccounts;
@@ -399,7 +441,8 @@ var HostProvider = class {
       const accountResult = await this.fetchProductSignerAccount(
         provider,
         this.productAccount.dotNsIdentifier,
-        this.productAccount.derivationIndex ?? 0
+        this.productAccount.derivationIndex ?? 0,
+        this.productAccount.requestName ?? true
       );
       if (!accountResult.ok) return accountResult;
       signerAccounts = [accountResult.value];
@@ -413,6 +456,14 @@ var HostProvider = class {
           }
         );
       } catch (cause) {
+        if (cause instanceof Error && /environment is not correct/i.test(cause.message)) {
+          log2.warn("not inside a host container (detected at getLegacyAccounts)");
+          return err(
+            new HostUnavailableError(
+              "Host API is not available: not running inside a Polkadot host container. Open this app inside Polkadot Desktop or the Polkadot Mobile WebView, or pick a non-host signer provider (e.g. dev accounts)."
+            )
+          );
+        }
         log2.error("failed to get accounts from host", { cause });
         return err(
           new HostRejectedError(
@@ -458,8 +509,9 @@ var HostProvider = class {
     this.statusCleanup = typeof sub === "function" ? sub : () => sub.unsubscribe();
     return ok(signerAccounts);
   }
-  async fetchProductSignerAccount(provider, dotNsIdentifier, derivationIndex) {
+  async fetchProductSignerAccount(provider, dotNsIdentifier, derivationIndex, requestName) {
     const fetchUsername = async () => {
+      if (!requestName) return null;
       try {
         return await provider.getUserId().match(
           (result) => result.primaryUsername,
@@ -723,6 +775,24 @@ var SignerManager = class {
     }
   }
   // ── Host-only: Product Account API ─────────────────────────────
+  /**
+   * Fetch the connected user's host identity.
+   *
+   * This uses the Host API identity permission path and is only available
+   * when connected through the host provider. The primary username can be
+   * used by higher-level helpers that need to bind an action to the user's
+   * DotNS / people username.
+   */
+  async getUserId() {
+    if (this.isDestroyed) return err(new DestroyedError());
+    const host = this.getHostProvider();
+    if (!host) {
+      return err(
+        new HostUnavailableError("User identity requires a host provider connection")
+      );
+    }
+    return host.getUserId();
+  }
   /**
    * Get an app-scoped product account from the host.
    *