@eos3/connect 0.1.11 → 0.1.13

package/README.md

@@ -56,6 +56,7 @@ await eosConnect.bootstrapTelegram();
 const quickPay = await eosConnect.checkQuickPay();
 
 if (!quickPay.enabled) {
+  // Requires <eos-connect-modal hidden></eos-connect-modal> from @eos3/connect-ui.
   await eosConnect.enableQuickPay();
 }
 ```
@@ -95,10 +96,10 @@ const eosConnect = createEosConnect({
 
 ## Quick Payment Flow
 
-For app UIs, prefer `checkQuickPay()` and `enableQuickPay()`. They hide
-low-level wallet capability statuses such as `needs_local_key`, open pending
-bind URLs, rebind the current device when the local payment key is missing, and
-can poll until quick payment is enabled:
+For app UIs, use `checkQuickPay()` for readiness and `enableQuickPay()` for the
+button click. `enableQuickPay()` does not start binding directly; it opens the
+SDK-owned `<eos-connect-modal>` from `@eos3/connect-ui` so users always see the
+quick payment setup sheet first:
 
 ```ts
 const quickPay = await eosConnect.checkQuickPay();
@@ -111,15 +112,12 @@ renderQuickPay({
 });
 
 if (!quickPay.enabled) {
-  const next = await eosConnect.enableQuickPay({
-    pollIntervalMs: 1500,
-    timeoutMs: 120_000
-  });
+  const next = await eosConnect.enableQuickPay();
   renderQuickPay(next);
 }
 ```
 
-`enableQuickPay()` performs the common Telegram setup sequence:
+The modal's primary action performs the common Telegram setup sequence:
 
 - loads Telegram's WebApp SDK when needed;
 - initializes `BiometricManager` and checks SecureStorage support;
@@ -127,12 +125,14 @@ if (!quickPay.enabled) {
 - opens an existing `pending` `bindUrl`;
 - calls `connectTelegram({ replaceWallet: true })` when the current device is
   missing the local payment key;
-- polls wallet readiness until `ready`, another terminal state, or timeout.
+- polls wallet readiness until `ready` or another terminal state;
+- pauses background polling when the page is hidden and checks immediately when
+  the Telegram Mini App returns to the foreground.
 
 Advanced UIs can still call `getWalletView()` or `startTelegramWalletFlow()`
-when they need debug-level states and labels. Wallet setup always polls after
-opening the binding page and returns when the wallet is ready, reaches another
-terminal state, or times out.
+inside SDK-owned UI when they need debug-level states and labels. Wallet setup
+always polls after opening the binding page and returns when the wallet is ready
+or reaches another terminal state.
 
 ## Connect a Telegram Wallet
 
@@ -284,8 +284,8 @@ await fetch('https://wallet.example.com/api/market/push', {
 - `checkEosConnectTelegramPayStorage(app)`: initializes Telegram biometrics and returns secure storage diagnostics.
 - `client.connectTelegram(options)`: starts or resumes Telegram binding.
 - `client.connectTokenPocket(options)`: starts TokenPocket binding.
-- `client.startTelegramWalletFlow(options)`: runs the high-level Telegram wallet setup flow.
-- `client.enableQuickPay(options)`: runs the high-level setup flow and returns quick payment readiness.
+- `client.startTelegramWalletFlow(options)`: runs the high-level Telegram wallet setup flow from SDK-owned UI.
+- `client.enableQuickPay()`: opens the SDK-owned `<eos-connect-modal>` and returns current quick payment readiness.
 - `client.pay(options)`: builds, signs, confirms, and pushes a paylimit payment.
 - `client.disconnect()`: removes the local Telegram payment key from
   SecureStorage, clears the biometric token, and resets the SDK state.

package/dist/index.d.ts

@@ -99,7 +99,6 @@ export interface EosConnectTelegramOptions {
 }
 export interface EosConnectWalletFlowOptions extends EosConnectTelegramOptions {
     pollIntervalMs?: number;
-    timeoutMs?: number;
     openExternal?: (url: string) => void;
 }
 export type EosConnectWalletViewStatus = 'setup' | 'pending' | 'ready' | 'unsupported' | 'error';
@@ -140,7 +139,7 @@ export interface EosConnectClient {
     connectTelegram(options?: EosConnectTelegramOptions): Promise<EosConnectState>;
     connectTokenPocket(options?: EosConnectTelegramOptions): Promise<EosConnectState>;
     startTelegramWalletFlow(options?: EosConnectWalletFlowOptions): Promise<EosConnectWalletView>;
-    enableQuickPay(options?: EosConnectWalletFlowOptions): Promise<EosConnectQuickPayStatus>;
+    enableQuickPay(): Promise<EosConnectQuickPayStatus>;
     pay(options: EosConnectPayOptions): Promise<EosConnectPayResult>;
     disconnect(): Promise<EosConnectState>;
 }

package/dist/index.js

@@ -1270,6 +1270,64 @@ function mergeTelegramConnectOptions(defaults, overrides) {
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
+function isVisibleDocument(documentRef) {
+    return !documentRef.visibilityState || documentRef.visibilityState === 'visible';
+}
+function waitForVisibleDocument(documentRef) {
+    if (isVisibleDocument(documentRef)) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const onVisibilityChange = () => {
+            if (!isVisibleDocument(documentRef)) {
+                return;
+            }
+            documentRef.removeEventListener('visibilitychange', onVisibilityChange);
+            resolve();
+        };
+        documentRef.addEventListener('visibilitychange', onVisibilityChange);
+    });
+}
+function waitForNextWalletPoll(ms) {
+    const documentRef = globalThis.document;
+    if (!documentRef?.addEventListener || !documentRef.removeEventListener) {
+        return delay(ms);
+    }
+    if (!isVisibleDocument(documentRef)) {
+        return waitForVisibleDocument(documentRef);
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            documentRef.removeEventListener('visibilitychange', onVisibilityChange);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            if (isVisibleDocument(documentRef)) {
+                finish();
+            }
+        }, Math.max(0, ms));
+        const onVisibilityChange = () => {
+            if (isVisibleDocument(documentRef)) {
+                finish();
+            }
+        };
+        documentRef.addEventListener('visibilitychange', onVisibilityChange);
+    });
+}
+function openEosConnectUiModal() {
+    const modal = globalThis.document?.querySelector?.('eos-connect-modal,eos-connect');
+    if (!modal) {
+        return false;
+    }
+    modal.removeAttribute('hidden');
+    return true;
+}
 function openFlowUrl(url, clientOptions, flowOptions, telegramWebApp) {
     if (flowOptions.openExternal) {
         flowOptions.openExternal(url);
@@ -1565,18 +1623,13 @@ export function createEosConnect(options) {
                         openedView = walletViewFromCapability(pendingWalletCapabilityFromState(next), message);
                     }
                 }
-                const timeoutMs = flowOptions.timeoutMs ?? 120000;
                 const pollIntervalMs = flowOptions.pollIntervalMs ?? 1500;
-                const deadline = Date.now() + Math.max(0, timeoutMs);
                 do {
                     capability = await this.checkWallet();
                     if (capability.status !== 'pending') {
                         return walletViewFromCapability(capability, message);
                     }
-                    if (Date.now() >= deadline) {
-                        return walletViewFromCapability(capability, message);
-                    }
-                    await delay(pollIntervalMs);
+                    await waitForNextWalletPoll(pollIntervalMs);
                 } while (true);
             }
             catch (error) {
@@ -1589,8 +1642,11 @@ export function createEosConnect(options) {
                 return walletViewFromError(normalized, message);
             }
         },
-        async enableQuickPay(flowOptions = {}) {
-            return quickPayFromView(await this.startTelegramWalletFlow(flowOptions));
+        async enableQuickPay() {
+            if (!openEosConnectUiModal()) {
+                throw new Error('EOS Connect UI modal is required to enable quick payment');
+            }
+            return this.checkQuickPay();
         },
         async connectTokenPocket(tokenPocketOptions = {}) {
             const paymentKey = await generateEosConnectPaymentKey();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eos3/connect",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Framework-neutral browser SDK for EOS Passkey Connect in Telegram Mini Apps.",
   "type": "module",
   "license": "UNLICENSED",