@qrlwallet/connect 3.1.1 → 3.2.0

package/README.md

@@ -18,10 +18,12 @@ All communication is end-to-end encrypted with ML-KEM-768 (FIPS 203) key encapsu
 npm install @qrlwallet/connect
 ```
 
+Want a ready-made pairing dialog (QR code, deep link, copy-code fallback) instead of building your own? Add the framework-free [`@qrlwallet/connect-ui`](ui/) web component.
+
 ## Quick start
 
 ```typescript
-import { QRLConnect } from '@qrlwallet/connect';
+import { QRLConnect, attemptWalletRedirect, getAppStoreUrl } from '@qrlwallet/connect';
 
 const qrl = new QRLConnect({
   dappMetadata: {
@@ -34,9 +36,16 @@ const qrl = new QRLConnect({
 const uri = await qrl.getConnectionURI();
 
 // Desktop: render as QR code (use any QR library)
-// Mobile: redirect to open the wallet app
+// Mobile: try to open the wallet app, with a fallback for when it is
+// not installed (a bare `window.location.href = uri` fails at the
+// unknown protocol: silently on Android, blocking alert on iOS)
 if (qrl.isMobile()) {
-  window.location.href = uri;
+  const opened = await attemptWalletRedirect(uri);
+  if (!opened) {
+    // Wallet app not installed (or the user dismissed the chooser):
+    // show your QR / copy-code pairing UI plus an install link.
+    console.log('Get MyQRLWallet:', getAppStoreUrl());
+  }
 } else {
   // render uri as QR code
 }

package/dist/index.d.mts

@@ -777,6 +777,24 @@ declare function isMobileBrowser(): boolean;
  * Falls back to app store URL after timeout.
  */
 declare function getAppStoreUrl(): string;
+/**
+ * Attempt to open a `qrlconnect://` URI in the wallet app and report whether
+ * anything handled it.
+ *
+ * A custom-scheme navigation on a device without the app installed fails
+ * silently on Android and with a blocking alert on iOS Safari, leaving the
+ * page visible either way. When the app IS installed, the OS backgrounds the
+ * browser, firing `visibilitychange`/`pagehide` almost immediately. So:
+ * navigate, then resolve `true` as soon as the page hides, or `false` if it
+ * is still visible after `timeoutMs`. On `false`, show fallback pairing UI
+ * (QR / copy-code) and an install link (`getAppStoreUrl()`).
+ *
+ * Detection is heuristic by nature: a slow device may hide the page late
+ * (harmless, the wallet still opens), and it cannot distinguish "app missing"
+ * from "user dismissed the OS chooser". Treat `false` as "show a fallback",
+ * never as proof the app is absent.
+ */
+declare function attemptWalletRedirect(uri: string, timeoutMs?: number): Promise<boolean>;
 
 declare const DEFAULT_RELAY_URL = "https://qrlwallet.com";
 declare const PROTOCOL_VERSION = 2;
@@ -795,4 +813,4 @@ declare const RESTRICTED_METHODS: Set<string>;
 /** RPC methods that can be auto-proxied without approval */
 declare const UNRESTRICTED_METHODS: Set<string>;
 
-export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };
+export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };

package/dist/index.d.ts

@@ -777,6 +777,24 @@ declare function isMobileBrowser(): boolean;
  * Falls back to app store URL after timeout.
  */
 declare function getAppStoreUrl(): string;
+/**
+ * Attempt to open a `qrlconnect://` URI in the wallet app and report whether
+ * anything handled it.
+ *
+ * A custom-scheme navigation on a device without the app installed fails
+ * silently on Android and with a blocking alert on iOS Safari, leaving the
+ * page visible either way. When the app IS installed, the OS backgrounds the
+ * browser, firing `visibilitychange`/`pagehide` almost immediately. So:
+ * navigate, then resolve `true` as soon as the page hides, or `false` if it
+ * is still visible after `timeoutMs`. On `false`, show fallback pairing UI
+ * (QR / copy-code) and an install link (`getAppStoreUrl()`).
+ *
+ * Detection is heuristic by nature: a slow device may hide the page late
+ * (harmless, the wallet still opens), and it cannot distinguish "app missing"
+ * from "user dismissed the OS chooser". Treat `false` as "show a fallback",
+ * never as proof the app is absent.
+ */
+declare function attemptWalletRedirect(uri: string, timeoutMs?: number): Promise<boolean>;
 
 declare const DEFAULT_RELAY_URL = "https://qrlwallet.com";
 declare const PROTOCOL_VERSION = 2;
@@ -795,4 +813,4 @@ declare const RESTRICTED_METHODS: Set<string>;
 /** RPC methods that can be auto-proxied without approval */
 declare const UNRESTRICTED_METHODS: Set<string>;
 
-export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };
+export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };

package/dist/index.js

@@ -51,6 +51,7 @@ __export(index_exports, {
   SCHEME_VERSION_TYPED: () => SCHEME_VERSION_TYPED,
   SocketClient: () => SocketClient,
   UNRESTRICTED_METHODS: () => UNRESTRICTED_METHODS,
+  attemptWalletRedirect: () => attemptWalletRedirect,
   bytesToHex: () => bytesToHex,
   cidFromString: () => cidFromString,
   cidRandom: () => cidRandom,
@@ -1724,6 +1725,41 @@ function getAppStoreUrl() {
   }
   return "https://apps.apple.com/app/myqrlwallet/id6742219498";
 }
+function attemptWalletRedirect(uri, timeoutMs = 1800) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return Promise.resolve(false);
+  }
+  if (!uri.trim().toLowerCase().startsWith("qrlconnect:")) {
+    return Promise.resolve(false);
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (opened) => {
+      if (settled) return;
+      settled = true;
+      document.removeEventListener("visibilitychange", onVisibility);
+      window.removeEventListener("pagehide", onHide);
+      window.clearTimeout(timer);
+      resolve(opened);
+    };
+    const onVisibility = () => {
+      if (document.visibilityState === "hidden") finish(true);
+    };
+    const onHide = () => {
+      finish(true);
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    window.addEventListener("pagehide", onHide);
+    const timer = window.setTimeout(() => {
+      finish(false);
+    }, timeoutMs);
+    try {
+      window.location.href = uri;
+    } catch {
+      finish(false);
+    }
+  });
+}
 
 // src/QRLConnectProvider.ts
 var QRL_CONNECT_PROVIDER_INFO = {
@@ -2406,6 +2442,7 @@ function verifyTypedData({ signature, publicKey, payload }) {
   SCHEME_VERSION_TYPED,
   SocketClient,
   UNRESTRICTED_METHODS,
+  attemptWalletRedirect,
   bytesToHex,
   cidFromString,
   cidRandom,

package/dist/index.mjs

@@ -1648,6 +1648,41 @@ function getAppStoreUrl() {
   }
   return "https://apps.apple.com/app/myqrlwallet/id6742219498";
 }
+function attemptWalletRedirect(uri, timeoutMs = 1800) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return Promise.resolve(false);
+  }
+  if (!uri.trim().toLowerCase().startsWith("qrlconnect:")) {
+    return Promise.resolve(false);
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (opened) => {
+      if (settled) return;
+      settled = true;
+      document.removeEventListener("visibilitychange", onVisibility);
+      window.removeEventListener("pagehide", onHide);
+      window.clearTimeout(timer);
+      resolve(opened);
+    };
+    const onVisibility = () => {
+      if (document.visibilityState === "hidden") finish(true);
+    };
+    const onHide = () => {
+      finish(true);
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    window.addEventListener("pagehide", onHide);
+    const timer = window.setTimeout(() => {
+      finish(false);
+    }, timeoutMs);
+    try {
+      window.location.href = uri;
+    } catch {
+      finish(false);
+    }
+  });
+}
 
 // src/QRLConnectProvider.ts
 var QRL_CONNECT_PROVIDER_INFO = {
@@ -2329,6 +2364,7 @@ export {
   SCHEME_VERSION_TYPED,
   SocketClient,
   UNRESTRICTED_METHODS,
+  attemptWalletRedirect,
   bytesToHex,
   cidFromString,
   cidRandom,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qrlwallet/connect",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Connect your dApp to QRL Wallet via QR code or deep link",
   "main": "dist/index.js",
   "module": "dist/index.mjs",