@parity/product-sdk-host 0.17.0 → 0.18.0

package/dist/index.d.ts

@@ -250,6 +250,29 @@ declare class HostCallFailedError extends HostError {
     readonly payload: HostErrorPayload;
     constructor(label: string, payload: HostErrorPayload);
 }
+/**
+ * A host call could not be processed to completion: the `ResultAsync` the
+ * truapi client returns rejected instead of resolving to an ok/err. The usual
+ * cause is a response the client's SCALE codec can't decode (a
+ * `RangeError: Offset is outside the bounds of the DataView`) because the host
+ * and the `@parity/truapi` version the product is built against disagree on the
+ * wire shape of that call — a protocol-version skew. A host channel that closed
+ * mid-call looks identical from here, so this does not assert the skew; the
+ * real error is preserved on {@link cause}.
+ *
+ * The truapi client catches the decode throw in its message handler and turns
+ * it into a promise rejection, then wraps the call with
+ * `ResultAsync.fromSafePromise`, which installs no rejection handler — so the
+ * rejection escapes the `Result` channel rather than landing on its err side.
+ * Without this boundary that surfaces as a raw `RangeError` with a stack naming
+ * neither the call nor the cause. This names the call, so a bug report has
+ * somewhere to start.
+ */
+declare class HostResponseDecodeError extends HostError {
+    /** The host-API call whose response failed to decode, e.g. `"createRingVRFProof"`. */
+    readonly call: string;
+    constructor(call: string, cause: unknown);
+}
 /** Check whether a value is any {@link HostError}. */
 declare function isHostError(error: unknown): error is HostError;
 
@@ -495,6 +518,13 @@ type VrfTranscriptItem = {
 type VrfSignature = {
     [K in keyof VrfSignature$1]: Uint8Array;
 };
+/**
+ * A call's declared `Err` channel, plus {@link HostResponseDecodeError}: any
+ * host reply can fail to decode if the host and the product's `@parity/truapi`
+ * client are on different protocol versions, so every decoded call can surface
+ * it in addition to its own typed errors.
+ */
+type WithDecodeError<E> = E | HostResponseDecodeError;
 /**
  * Accounts provider handle, backed by `truApi.account.*` / `truApi.signing.*`.
  * Surfaces the user's wallet accounts, app-scoped product accounts, Ring VRF,
@@ -503,14 +533,17 @@ type VrfSignature = {
  * Lookup methods return a neverthrow `ResultAsync` (use `.match(ok, err)`);
  * the signer factories return a synchronous PAPI `PolkadotSigner`. The `err`
  * channel carries truapi's canonical `CallErrorValue` envelope around the
- * per-call versioned domain error, exactly as the generated client returns it.
+ * per-call versioned domain error, exactly as the generated client returns it,
+ * plus a {@link HostResponseDecodeError} for the case where the host's reply
+ * cannot be decoded at all (a host/client protocol-version skew) — see
+ * {@link WithDecodeError}.
  */
 interface AccountsProvider {
     getUserId(): ResultAsync$1<{
         primaryUsername: string;
-    }, scale.CallErrorValue<VersionedHostGetUserIdError>>;
-    requestLogin(reason?: string): ResultAsync$1<HostRequestLoginResponse, scale.CallErrorValue<VersionedHostRequestLoginError>>;
-    getProductAccount(dotNsIdentifier: string, derivationIndex?: number): ResultAsync$1<ProductAccount, scale.CallErrorValue<VersionedHostAccountGetError>>;
+    }, WithDecodeError<scale.CallErrorValue<VersionedHostGetUserIdError>>>;
+    requestLogin(reason?: string): ResultAsync$1<HostRequestLoginResponse, WithDecodeError<scale.CallErrorValue<VersionedHostRequestLoginError>>>;
+    getProductAccount(dotNsIdentifier: string, derivationIndex?: number): ResultAsync$1<ProductAccount, WithDecodeError<scale.CallErrorValue<VersionedHostAccountGetError>>>;
     /**
      * Register a ring-VRF key owned by the calling product.
      *
@@ -520,17 +553,17 @@ interface AccountsProvider {
      * Registration returns the key's public key. Call {@link listRingVrfKeys}
      * afterward to obtain the opaque handle required by alias and proof calls.
      */
-    registerRingVrfKey(index: number, ring: RingLocation): ResultAsync$1<RingVrfPublicKey, scale.CallErrorValue<VersionedHostAccountRegisterRingVrfKeyError>>;
+    registerRingVrfKey(index: number, ring: RingLocation): ResultAsync$1<RingVrfPublicKey, WithDecodeError<scale.CallErrorValue<VersionedHostAccountRegisterRingVrfKeyError>>>;
     /** List an owner's registered ring-VRF keys. */
-    listRingVrfKeys(owner: string, disclosure?: RingVrfKeyDisclosure): ResultAsync$1<RegisteredRingVrfKey[], scale.CallErrorValue<VersionedHostAccountListRingVrfKeysError>>;
+    listRingVrfKeys(owner: string, disclosure?: RingVrfKeyDisclosure): ResultAsync$1<RegisteredRingVrfKey[], WithDecodeError<scale.CallErrorValue<VersionedHostAccountListRingVrfKeysError>>>;
     /** Derive a contextual alias with an explicitly registered ring-VRF key. */
-    getProductAccountAlias(keyHandle: RingVrfKeyHandle, context: ProductProofContext, location: RingLocation): ResultAsync$1<ContextualAlias, scale.CallErrorValue<VersionedHostAccountGetAliasError>>;
-    getLegacyAccounts(): ResultAsync$1<HostAccount[], scale.CallErrorValue<VersionedHostGetLegacyAccountsError>>;
+    getProductAccountAlias(keyHandle: RingVrfKeyHandle, context: ProductProofContext, location: RingLocation): ResultAsync$1<ContextualAlias, WithDecodeError<scale.CallErrorValue<VersionedHostAccountGetAliasError>>>;
+    getLegacyAccounts(): ResultAsync$1<HostAccount[], WithDecodeError<scale.CallErrorValue<VersionedHostGetLegacyAccountsError>>>;
     /**
      * Generate a Ring VRF proof with an explicitly registered key, binding
      * `message` to the product-scoped `context`.
      */
-    createRingVRFProof(keyHandle: RingVrfKeyHandle, context: ProductProofContext, location: RingLocation, message: Uint8Array): ResultAsync$1<RingVRFProof, scale.CallErrorValue<VersionedHostAccountCreateProofError>>;
+    createRingVRFProof(keyHandle: RingVrfKeyHandle, context: ProductProofContext, location: RingLocation, message: Uint8Array): ResultAsync$1<RingVRFProof, WithDecodeError<scale.CallErrorValue<VersionedHostAccountCreateProofError>>>;
     /**
      * Sign `message` directly with an explicitly registered ring-VRF key.
      *
@@ -538,7 +571,7 @@ interface AccountsProvider {
      * membership; it is the plain signature under the member key, for
      * protocols that carry their own proof.
      */
-    ringVrfSign(keyHandle: RingVrfKeyHandle, message: Uint8Array): ResultAsync$1<Uint8Array, scale.CallErrorValue<VersionedHostAccountRingVrfSignError>>;
+    ringVrfSign(keyHandle: RingVrfKeyHandle, message: Uint8Array): ResultAsync$1<Uint8Array, WithDecodeError<scale.CallErrorValue<VersionedHostAccountRingVrfSignError>>>;
     /**
      * Produce an sr25519 VRF signature from a product account (RFC-0023).
      *
@@ -558,7 +591,7 @@ interface AccountsProvider {
      *
      * Hosts predating the call reject it through the error channel.
      */
-    signVrf(account: ProductAccountLookup, transcriptLabel: Uint8Array, items: VrfTranscriptItem[]): ResultAsync$1<VrfSignature, scale.CallErrorValue<VersionedHostAccountSignVrfError>>;
+    signVrf(account: ProductAccountLookup, transcriptLabel: Uint8Array, items: VrfTranscriptItem[]): ResultAsync$1<VrfSignature, WithDecodeError<scale.CallErrorValue<VersionedHostAccountSignVrfError>>>;
     /**
      * Build a `PolkadotSigner` for a product account. Signing routes through the
      * host's `createTransaction` path: the host decodes the metadata and forwards
@@ -1110,4 +1143,4 @@ declare function broadcastTransaction(genesisHash: HexString, transaction: HexSt
  */
 declare function stopTransaction(genesisHash: HexString, operationId: string): Promise<Result<void, HostError>>;
 
-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 ProductAccountLookup, type PushNotificationInput, type RegisteredRingVrfKey, type RemotePermissionItem, type ResultAsync, type RingVRFProof, type RingVrfKeyHandle, type RingVrfPublicKey, type StatementTopicFilter, type StatementsPage, type ThemeMode, type ThemeProvider, type TruApi, type VrfSignature, type VrfTranscriptItem, broadcastTransaction, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, featureSupported, findRingVrfKeyHandle, formatHostError, fromHex, getAccountsProvider, getChainSpec, getChatManager, getHostLocalStorage, getHostProvider, getNotificationManager, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isChainSupported, isHostError, isInsideContainer, navigateTo, requestDevicePermission, requestPermission, requestResourceAllocation, stopTransaction, toHex };
+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, HostResponseDecodeError, type HostStatementStore, type HostSubscription, HostUnavailableError, type NotificationManager, type PaymentManager, type PreimageManager, type ProductAccount, type ProductAccountLookup, type PushNotificationInput, type RegisteredRingVrfKey, type RemotePermissionItem, type ResultAsync, type RingVRFProof, type RingVrfKeyHandle, type RingVrfPublicKey, type StatementTopicFilter, type StatementsPage, type ThemeMode, type ThemeProvider, type TruApi, type VrfSignature, type VrfTranscriptItem, type WithDecodeError, broadcastTransaction, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, featureSupported, findRingVrfKeyHandle, formatHostError, fromHex, getAccountsProvider, getChainSpec, getChatManager, getHostLocalStorage, getHostProvider, getNotificationManager, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isChainSupported, isHostError, isInsideContainer, navigateTo, requestDevicePermission, requestPermission, requestResourceAllocation, stopTransaction, toHex };

package/dist/index.js

@@ -6,6 +6,7 @@ import { err, ok } from '@parity/result';
 export { err, ok } from '@parity/result';
 export { isSdkError } from '@parity/product-sdk-errors';
 import { unifyMetadata, decAnyMetadata } from '@polkadot-api/substrate-bindings';
+import { ResultAsync } from 'neverthrow';
 import { AccountId } from 'polkadot-api';
 
 // src/errors.ts
@@ -62,6 +63,18 @@ var HostCallFailedError = class extends HostError {
     this.payload = payload;
   }
 };
+var HostResponseDecodeError = class extends HostError {
+  /** The host-API call whose response failed to decode, e.g. `"createRingVRFProof"`. */
+  call;
+  constructor(call, cause) {
+    super(
+      `Could not process the host's response to ${call}: ${formatHostError(cause)}. The usual cause is a protocol-version skew between the host app and the @parity/truapi version this product is built against; a host channel that closed mid-call looks the same.`,
+      { cause }
+    );
+    this.name = "HostResponseDecodeError";
+    this.call = call;
+  }
+};
 function isHostError(error) {
   return error instanceof HostError;
 }
@@ -486,18 +499,59 @@ function createHostPapiProvider(client, genesisHash) {
 
 // src/truapi.ts
 var log2 = createLogger("host");
+async function matchGuarded(result, label, onOk, onErr, onDecode) {
+  try {
+    return await result.match(
+      (value) => {
+        try {
+          return onOk(value);
+        } catch (thrown) {
+          throw new HandlerThrow(thrown);
+        }
+      },
+      (error) => {
+        try {
+          return onErr(error);
+        } catch (thrown) {
+          throw new HandlerThrow(thrown);
+        }
+      }
+    );
+  } catch (cause) {
+    if (cause instanceof HandlerThrow) throw cause.thrown;
+    return onDecode(
+      cause instanceof HostResponseDecodeError ? cause : new HostResponseDecodeError(label, cause)
+    );
+  }
+}
+var HandlerThrow = class {
+  constructor(thrown) {
+    this.thrown = thrown;
+  }
+  thrown;
+};
 function unwrapHostResult(result, label) {
-  return result.match(
+  return matchGuarded(
+    result,
+    label,
     (value) => value,
     (error) => {
       throw new Error(`${label}: ${formatHostError(error)}`, { cause: error });
+    },
+    // A response the client can't decode would otherwise reject with a raw
+    // `RangeError`; throw it as a typed, named error instead.
+    (decodeError) => {
+      throw decodeError;
     }
   );
 }
 function mapHostResult(result, map, label) {
-  return result.match(
+  return matchGuarded(
+    result,
+    label,
     (value) => ok(map(value)),
-    (error) => err(new HostCallFailedError(label, error))
+    (error) => err(new HostCallFailedError(label, error)),
+    (decodeError) => err(decodeError)
   );
 }
 function toHex(bytes) {
@@ -749,18 +803,25 @@ function sameRingLocation(a, b) {
 function findRingVrfKeyHandle(keys, ring) {
   return keys.find((key) => key.rings.some((candidate) => sameRingLocation(candidate, ring)))?.handle;
 }
-function selectHostTxExtVersion(versions) {
-  if (versions.length === 0) {
+var GENERAL_TX_EXT_VERSION = 5;
+function selectHostTxExtVersion(formatVersions, txExtVersions) {
+  if (formatVersions.length === 0) {
     throw new Error("No extrinsic version found in metadata");
   }
-  if (versions.includes(4)) {
+  if (formatVersions.includes(4)) {
     return 0;
   }
-  return versions.reduce((acc, version) => Math.max(acc, version), 0);
+  if (txExtVersions.includes(GENERAL_TX_EXT_VERSION)) {
+    return GENERAL_TX_EXT_VERSION;
+  }
+  throw new Error(
+    `Runtime offers no V4 extrinsic and no transaction-extension version ${GENERAL_TX_EXT_VERSION} (supported: ${txExtVersions.join(", ") || "none"}); cannot select a txExtVersion the host can assemble.`
+  );
 }
 function deriveTxExtVersion(metadata) {
-  const versions = unifyMetadata(decAnyMetadata(metadata)).extrinsic.version;
-  return selectHostTxExtVersion(versions);
+  const extrinsic = unifyMetadata(decAnyMetadata(metadata)).extrinsic;
+  const txExtVersions = Object.keys(extrinsic.signedExtensions).map(Number);
+  return selectHostTxExtVersion(extrinsic.version, txExtVersions);
 }
 var deps = { deriveTxExtVersion };
 function toHostExtensions(signedExtensions) {
@@ -776,91 +837,127 @@ function toWireProductAccountId({
 }) {
   return { dotNsIdentifier, derivationIndex: { tag: "Index", value: derivationIndex } };
 }
+function guardDecode(call, result) {
+  return ResultAsync.fromPromise(
+    Promise.resolve(result),
+    (cause) => new HostResponseDecodeError(call, cause)
+  ).andThen((inner) => inner);
+}
 function adaptAccountsProvider(client) {
   const account = client.account;
   const signing = client.signing;
   return {
     getUserId() {
-      return account.getUserId().map((response) => ({
-        primaryUsername: response.primaryUsername
-      }));
+      return guardDecode(
+        "getUserId",
+        account.getUserId().map((response) => ({
+          primaryUsername: response.primaryUsername
+        }))
+      );
     },
     requestLogin(reason) {
-      return account.requestLogin({ reason });
+      return guardDecode("requestLogin", account.requestLogin({ reason }));
     },
     getProductAccount(dotNsIdentifier, derivationIndex = 0) {
-      return account.getAccount({
-        productAccountId: toWireProductAccountId({ dotNsIdentifier, derivationIndex })
-      }).map((response) => ({
-        publicKey: fromHex(response.account.publicKey),
-        dotNsIdentifier,
-        derivationIndex
-      }));
+      return guardDecode(
+        "getProductAccount",
+        account.getAccount({
+          productAccountId: toWireProductAccountId({
+            dotNsIdentifier,
+            derivationIndex
+          })
+        }).map((response) => ({
+          publicKey: fromHex(response.account.publicKey),
+          dotNsIdentifier,
+          derivationIndex
+        }))
+      );
     },
     registerRingVrfKey(index, ring) {
-      return account.registerRingVrfKey({ index: { tag: "Index", value: index }, ring }).map(fromHex);
+      return guardDecode(
+        "registerRingVrfKey",
+        account.registerRingVrfKey({ index: { tag: "Index", value: index }, ring }).map(fromHex)
+      );
     },
     listRingVrfKeys(owner, disclosure = "Anonymized") {
-      return account.listRingVrfKeys({ owner, disclosure }).map(
-        (keys) => keys.map((key) => ({
-          ...key,
-          handle: key.handle,
-          publicKey: key.publicKey === void 0 ? void 0 : fromHex(key.publicKey)
-        }))
+      return guardDecode(
+        "listRingVrfKeys",
+        account.listRingVrfKeys({ owner, disclosure }).map(
+          (keys) => keys.map((key) => ({
+            ...key,
+            handle: key.handle,
+            publicKey: key.publicKey === void 0 ? void 0 : fromHex(key.publicKey)
+          }))
+        )
       );
     },
     getProductAccountAlias(keyHandle, context, location) {
-      return account.getAccountAlias({
-        keyHandle,
-        context,
-        ringLocation: location
-      }).map((response) => ({
-        context: fromHex(response.context),
-        alias: fromHex(response.alias)
-      }));
+      return guardDecode(
+        "getProductAccountAlias",
+        account.getAccountAlias({
+          keyHandle,
+          context,
+          ringLocation: location
+        }).map((response) => ({
+          context: fromHex(response.context),
+          alias: fromHex(response.alias)
+        }))
+      );
     },
     getLegacyAccounts() {
-      return account.getLegacyAccounts().map(
-        (response) => response.accounts.map((a) => ({
-          publicKey: fromHex(a.publicKey),
-          name: a.name
-        }))
+      return guardDecode(
+        "getLegacyAccounts",
+        account.getLegacyAccounts().map(
+          (response) => response.accounts.map((a) => ({
+            publicKey: fromHex(a.publicKey),
+            name: a.name
+          }))
+        )
       );
     },
     createRingVRFProof(keyHandle, context, location, message) {
-      return account.createAccountProof({
-        keyHandle,
-        context,
-        ringLocation: location,
-        message: toHex(message)
-      }).map((response) => ({
-        proof: fromHex(response.proof),
-        contextualAlias: {
-          context: fromHex(response.contextualAlias.context),
-          alias: fromHex(response.contextualAlias.alias)
-        },
-        ringIndex: response.ringIndex,
-        ringRevision: response.ringRevision
-      }));
+      return guardDecode(
+        "createRingVRFProof",
+        account.createAccountProof({
+          keyHandle,
+          context,
+          ringLocation: location,
+          message: toHex(message)
+        }).map((response) => ({
+          proof: fromHex(response.proof),
+          contextualAlias: {
+            context: fromHex(response.contextualAlias.context),
+            alias: fromHex(response.contextualAlias.alias)
+          },
+          ringIndex: response.ringIndex,
+          ringRevision: response.ringRevision
+        }))
+      );
     },
     ringVrfSign(keyHandle, message) {
-      return account.ringVrfSign({
-        keyHandle,
-        message: toHex(message)
-      }).map(fromHex);
+      return guardDecode(
+        "ringVrfSign",
+        account.ringVrfSign({
+          keyHandle,
+          message: toHex(message)
+        }).map(fromHex)
+      );
     },
     signVrf(account_, transcriptLabel, items) {
-      return account.signVrf({
-        account: toWireProductAccountId(account_),
-        transcriptLabel: toHex(transcriptLabel),
-        items: items.map(({ label, value }) => ({
-          label: toHex(label),
-          value: toHex(value)
+      return guardDecode(
+        "signVrf",
+        account.signVrf({
+          account: toWireProductAccountId(account_),
+          transcriptLabel: toHex(transcriptLabel),
+          items: items.map(({ label, value }) => ({
+            label: toHex(label),
+            value: toHex(value)
+          }))
+        }).map((response) => ({
+          preOutput: fromHex(response.preOutput),
+          proof: fromHex(response.proof)
         }))
-      }).map((response) => ({
-        preOutput: fromHex(response.preOutput),
-        proof: fromHex(response.proof)
-      }));
+      );
     },
     getProductAccountSigner(account_) {
       const productAccountId = toWireProductAccountId(account_);
@@ -1189,6 +1286,6 @@ async function stopTransaction(genesisHash, operationId) {
   );
 }
 
-export { BULLETIN_RPCS, ChainNotSupportedError, DEFAULT_BULLETIN_ENDPOINT, HostCallFailedError, HostError, HostUnavailableError, broadcastTransaction, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, featureSupported, findRingVrfKeyHandle, formatHostError, fromHex, getAccountsProvider, getChainSpec, getChatManager, getHostChainInfo, getHostLocalStorage, getHostProvider, getNotificationManager, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isChainSupported, isHostError, isInsideContainer, navigateTo, requestDevicePermission, requestPermission, requestResourceAllocation, stopTransaction, toHex };
+export { BULLETIN_RPCS, ChainNotSupportedError, DEFAULT_BULLETIN_ENDPOINT, HostCallFailedError, HostError, HostResponseDecodeError, HostUnavailableError, broadcastTransaction, createHostLocalStorage, createHostPreimageManager, createProofAuthorized, deriveEntropy, featureSupported, findRingVrfKeyHandle, formatHostError, fromHex, getAccountsProvider, getChainSpec, getChatManager, getHostChainInfo, getHostLocalStorage, getHostProvider, getNotificationManager, getPaymentManager, getPreimageManager, getStatementStore, getThemeProvider, getTruApi, isChainSupported, isHostError, isInsideContainer, navigateTo, requestDevicePermission, requestPermission, requestResourceAllocation, stopTransaction, toHex };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map