@lydianpay/lydianconnect 1.2.1 → 1.4.0

package/dist/index.d.cts

@@ -19,6 +19,22 @@ interface CaipNamespace {
         events: string[];
     };
 }
+/** Input to {@link LydianConnect.openWallet}. */
+interface OpenWalletInput {
+    walletId: string;
+    /**
+     * Pairing URI from the `display_uri` event, to hand the wallet a connection to
+     * approve. Omit to simply foreground the app.
+     */
+    uri?: string;
+    /**
+     * `"scheme"` (default) opens the wallet's custom scheme — reliable, and it
+     * cannot strand the user if the app is missing. `"universal"` opens the https
+     * app-link instead: the retry to offer when the scheme did nothing, but it
+     * navigates away from the page when the app isn't installed.
+     */
+    via?: "scheme" | "universal";
+}
 /**
  * The uniform handle the host app holds after connecting.
  *
@@ -59,11 +75,21 @@ interface ConnectInput {
     signal?: AbortSignal;
 }
 type LydianConnectEvent = 
-/** WalletConnect only — the wc: URI. Deep-linking is fired internally; emitted for QR display. */
+/**
+ * WalletConnect only — the wc: URI.
+ *
+ * `deepLink` is the library telling the host how to prompt: `true` means this
+ * wallet can be opened directly on this device, so render an "Open <wallet>"
+ * button (whose tap is a fresh user gesture — the only reliable way to launch
+ * a wallet app); `false` means render a QR code. The connector also fires the
+ * deep link itself, but mobile browsers suppress a scheme navigation that has
+ * lost its click gesture, so the button is what guarantees a way forward.
+ */
 {
     type: "display_uri";
     walletId: string;
     uri: string;
+    deepLink: boolean;
 } | {
     type: "connect";
     walletId: string;
@@ -103,6 +129,18 @@ declare class LydianConnect {
     constructor(config: LydianConnectConfig);
     init(): Promise<void>;
     connect(input: ConnectInput): Promise<Connection>;
+    /**
+     * Open a wallet app, optionally handing it the pairing URI from `display_uri`.
+     *
+     * Call this from a real click handler. A mobile browser will suppress the same
+     * navigation issued automatically after an async step, which is why the
+     * `display_uri` event reports `deepLink` — that is the library asking the host
+     * for a button to put this behind.
+     *
+     * Returns whether a link was fired. `false` means nothing is known for this
+     * wallet on this device; show the QR code instead.
+     */
+    openWallet(input: OpenWalletInput): boolean;
     restore(): Promise<Connection[]>;
     disconnect(walletId?: string): Promise<void>;
     reset(): Promise<void>;
@@ -110,4 +148,4 @@ declare class LydianConnect {
     on(handler: LydianConnectEventHandler): () => void;
 }
 
-export { type CaipNamespace, type ConnectInput, type Connection, LydianConnect, type LydianConnectConfig, type LydianConnectEvent, type LydianConnectEventHandler };
+export { type CaipNamespace, type ConnectInput, type Connection, LydianConnect, type LydianConnectConfig, type LydianConnectEvent, type LydianConnectEventHandler, type OpenWalletInput };

package/dist/index.d.ts

@@ -19,6 +19,22 @@ interface CaipNamespace {
         events: string[];
     };
 }
+/** Input to {@link LydianConnect.openWallet}. */
+interface OpenWalletInput {
+    walletId: string;
+    /**
+     * Pairing URI from the `display_uri` event, to hand the wallet a connection to
+     * approve. Omit to simply foreground the app.
+     */
+    uri?: string;
+    /**
+     * `"scheme"` (default) opens the wallet's custom scheme — reliable, and it
+     * cannot strand the user if the app is missing. `"universal"` opens the https
+     * app-link instead: the retry to offer when the scheme did nothing, but it
+     * navigates away from the page when the app isn't installed.
+     */
+    via?: "scheme" | "universal";
+}
 /**
  * The uniform handle the host app holds after connecting.
  *
@@ -59,11 +75,21 @@ interface ConnectInput {
     signal?: AbortSignal;
 }
 type LydianConnectEvent = 
-/** WalletConnect only — the wc: URI. Deep-linking is fired internally; emitted for QR display. */
+/**
+ * WalletConnect only — the wc: URI.
+ *
+ * `deepLink` is the library telling the host how to prompt: `true` means this
+ * wallet can be opened directly on this device, so render an "Open <wallet>"
+ * button (whose tap is a fresh user gesture — the only reliable way to launch
+ * a wallet app); `false` means render a QR code. The connector also fires the
+ * deep link itself, but mobile browsers suppress a scheme navigation that has
+ * lost its click gesture, so the button is what guarantees a way forward.
+ */
 {
     type: "display_uri";
     walletId: string;
     uri: string;
+    deepLink: boolean;
 } | {
     type: "connect";
     walletId: string;
@@ -103,6 +129,18 @@ declare class LydianConnect {
     constructor(config: LydianConnectConfig);
     init(): Promise<void>;
     connect(input: ConnectInput): Promise<Connection>;
+    /**
+     * Open a wallet app, optionally handing it the pairing URI from `display_uri`.
+     *
+     * Call this from a real click handler. A mobile browser will suppress the same
+     * navigation issued automatically after an async step, which is why the
+     * `display_uri` event reports `deepLink` — that is the library asking the host
+     * for a button to put this behind.
+     *
+     * Returns whether a link was fired. `false` means nothing is known for this
+     * wallet on this device; show the QR code instead.
+     */
+    openWallet(input: OpenWalletInput): boolean;
     restore(): Promise<Connection[]>;
     disconnect(walletId?: string): Promise<void>;
     reset(): Promise<void>;
@@ -110,4 +148,4 @@ declare class LydianConnect {
     on(handler: LydianConnectEventHandler): () => void;
 }
 
-export { type CaipNamespace, type ConnectInput, type Connection, LydianConnect, type LydianConnectConfig, type LydianConnectEvent, type LydianConnectEventHandler };
+export { type CaipNamespace, type ConnectInput, type Connection, LydianConnect, type LydianConnectConfig, type LydianConnectEvent, type LydianConnectEventHandler, type OpenWalletInput };