@eos3/connect 0.1.0 → 0.1.2

package/README.md

@@ -15,20 +15,28 @@ npm install @eos3/connect
 
 The SDK expects a browser runtime with `fetch`, Web Crypto, and Telegram WebApp
 APIs when real wallet creation or payment signing is used.
+It does not bundle Telegram's script into the main SDK bundle; call
+`loadEosConnectTelegramWebAppSdk()` or include Telegram's official
+`https://telegram.org/js/telegram-web-app.js` script before wallet flows.
 
 ## Minimal Setup
 
 ```ts
 import {
   createEosConnect,
+  getEosConnectTelegramWebApp,
   isEosConnectError,
+  loadEosConnectTelegramWebAppSdk,
   normalizeEosConnectError
 } from '@eos3/connect';
 
-const telegramWebApp = window.Telegram?.WebApp;
+await loadEosConnectTelegramWebAppSdk().catch(() => undefined);
+const telegramWebApp = getEosConnectTelegramWebApp();
 
 const eosConnect = createEosConnect({
   network: 'testnet',
+  apiBaseUrl: 'https://your-wallet-api.example.com',
+  botUsername: 'your_bot',
   telegramWebApp
 });
 
@@ -39,14 +47,19 @@ eosConnect.subscribe((state) => {
 await eosConnect.checkWallet();
 ```
 
-`network` can be `testnet` or `mainnet`. It selects the default API base URL,
-browser signing RPC failover list, chain id metadata, and balance asset. You can
-still override `apiBaseUrl`, `rpcUrls`, or `balanceAsset` when running your own
-deployment.
+`network` can be `testnet` or `mainnet`. It selects browser signing RPC
+failover list, chain id metadata, and balance asset. The SDK does not include a
+hosted wallet API or a Telegram bot. If `apiBaseUrl` is omitted, requests use
+same-origin paths such as `/api/tg-wallet/me`. `apiBaseUrl` points to the EOS
+Passkey API or to your same-origin proxy for that API; it is not the passkey bind
+page URL.
+When `botUsername` is set, the SDK sends it as `x-telegram-bot-username` so a
+shared backend can choose the correct Telegram bot token for `initData`
+verification.
 
-For now, the testnet preset uses `https://eospasskey.aiexsat.com` as its hosted
-API. The mainnet preset keeps the same hosted API placeholder until a separate
-mainnet endpoint is assigned.
+`connectTelegram()` opens the `bindUrl` returned by the API. The API should
+generate that URL from its `WEB_BASE_URL`, so users leave the Mini App and finish
+passkey authentication on the hosted passkey binding page.
 
 ## Connect a Telegram Wallet
 
@@ -79,6 +92,19 @@ Do not fall back to `localStorage` for the private key. If Telegram
 SecureStorage or BiometricManager is missing, ask the user to open the Mini App
 in a supported Telegram mobile client.
 
+Before showing a real connect action, prefer the async storage check. It calls
+`BiometricManager.init()` before reading Telegram's capability flags:
+
+```ts
+import { checkEosConnectTelegramPayStorage } from '@eos3/connect';
+
+const storage = await checkEosConnectTelegramPayStorage(telegramWebApp);
+
+if (!storage.supported) {
+  console.table(storage.diagnostics);
+}
+```
+
 ## Check Readiness
 
 ```ts
@@ -178,6 +204,7 @@ await fetch('https://wallet.example.com/api/market/push', {
 - `client.subscribe(listener)`: subscribes to state changes.
 - `client.restore()`: loads wallet state from the API.
 - `client.checkWallet()`: checks server wallet plus local key readiness.
+- `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.pay(options)`: builds, signs, confirms, and pushes a paylimit payment.
@@ -194,10 +221,9 @@ console.log(EOS_CONNECT_NETWORKS.mainnet.chainId);
 
 Preset values:
 
-- `testnet`: Jungle4 chain id, Jungle4 RPC failover list, hosted testnet API
-  `https://eospasskey.aiexsat.com`, and default asset `core.vaulta:A:4`.
-- `mainnet`: EOS mainnet chain id, mainnet RPC failover list, hosted API
-  placeholder `https://eospasskey.aiexsat.com`, and default asset
+- `testnet`: Jungle4 chain id, Jungle4 RPC failover list, and default asset
+  `core.vaulta:A:4`.
+- `mainnet`: EOS mainnet chain id, mainnet RPC failover list, and default asset
   `core.vaulta:A:4`.
 
 Explicit options always win:

package/dist/index.d.ts

@@ -39,6 +39,9 @@ export interface EosConnectTelegramWebApp {
         openSettings?(): void;
     };
 }
+export declare const EOS_CONNECT_TELEGRAM_WEB_APP_SDK_URL = "https://telegram.org/js/telegram-web-app.js";
+export declare function getEosConnectTelegramWebApp(): EosConnectTelegramWebApp | null;
+export declare function loadEosConnectTelegramWebAppSdk(doc?: Document | null | undefined): Promise<void>;
 export interface EosConnectState {
     status: EosConnectStatus;
     provider: EosConnectProviderId | null;
@@ -86,7 +89,6 @@ export interface EosConnectWalletSetupState {
 export interface EosConnectNetworkConfig {
     id: EosConnectNetwork;
     name: string;
-    apiBaseUrl: string;
     chainId: string;
     rpcUrls: readonly string[];
     balanceAsset: EosConnectBalanceAsset;
@@ -107,11 +109,13 @@ export interface EosConnectOptions {
 export interface EosConnectConnectOptions {
     provider: EosConnectProviderId;
     publicKey?: string;
+    botUsername?: string;
     assetLimits?: PayLimitAssetConfig[];
     replaceWallet?: boolean;
     openLink?: boolean;
 }
 export interface EosConnectTelegramOptions {
+    botUsername?: string;
     assetLimits?: PayLimitAssetConfig[];
     replaceWallet?: boolean;
     openLink?: boolean;
@@ -138,6 +142,11 @@ export interface EosConnectTelegramDeviceDiagnostic {
     ok: boolean;
     detail: string;
 }
+export interface EosConnectTelegramPayStorageCheck {
+    supported: boolean;
+    biometricInitialized: boolean;
+    diagnostics: EosConnectTelegramDeviceDiagnostic[];
+}
 export interface EosConnectTelegramBiometricSettingsResult {
     opened: boolean;
     message: string;
@@ -195,10 +204,10 @@ export interface EosConnectWalletInfo {
     botPermission?: string | null;
 }
 export declare const EOS_CONNECT_PRIVATE_KEY_STORAGE = "tg_eos_wallet_pay_key_v1";
-export declare const EOS_CONNECT_DEFAULT_API_BASE_URL = "https://eospasskey.aiexsat.com";
 export declare const EOS_CONNECT_NETWORKS: Record<EosConnectNetwork, EosConnectNetworkConfig>;
 export declare function eosConnectTelegramPayStorageDiagnostics(app: EosConnectTelegramWebApp): EosConnectTelegramDeviceDiagnostic[];
 export declare function supportsEosConnectTelegramPayStorage(app: EosConnectTelegramWebApp): boolean;
+export declare function checkEosConnectTelegramPayStorage(app: EosConnectTelegramWebApp, timeoutMs?: number): Promise<EosConnectTelegramPayStorageCheck>;
 export declare function initEosConnectTelegramBiometricManager(app: EosConnectTelegramWebApp, timeoutMs?: number): Promise<boolean>;
 export declare function openEosConnectTelegramBiometricSettings(app: EosConnectTelegramWebApp): Promise<EosConnectTelegramBiometricSettingsResult>;
 export declare function eosConnectWalletSetupState(wallet: EosConnectWalletInfo, env?: EosConnectWalletSetupEnv): EosConnectWalletSetupState;

package/dist/index.js

@@ -1,4 +1,41 @@
 import { ABI, PrivateKey, Serializer, Transaction } from '@wharfkit/antelope';
+export const EOS_CONNECT_TELEGRAM_WEB_APP_SDK_URL = 'https://telegram.org/js/telegram-web-app.js';
+let telegramWebAppSdkLoadPromise = null;
+export function getEosConnectTelegramWebApp() {
+    const maybeGlobal = globalThis;
+    return maybeGlobal.window?.Telegram?.WebApp ?? maybeGlobal.Telegram?.WebApp ?? null;
+}
+export function loadEosConnectTelegramWebAppSdk(doc = globalThis.document) {
+    if (getEosConnectTelegramWebApp()) {
+        return Promise.resolve();
+    }
+    if (telegramWebAppSdkLoadPromise) {
+        return telegramWebAppSdkLoadPromise;
+    }
+    if (!doc?.head) {
+        return Promise.reject(new Error('Document is not available to load Telegram WebApp SDK'));
+    }
+    telegramWebAppSdkLoadPromise = new Promise((resolve, reject) => {
+        const finish = () => resolve();
+        const fail = () => {
+            telegramWebAppSdkLoadPromise = null;
+            reject(new Error('Failed to load Telegram WebApp SDK'));
+        };
+        const existing = doc.querySelector(`script[src="${EOS_CONNECT_TELEGRAM_WEB_APP_SDK_URL}"]`);
+        if (existing) {
+            existing.addEventListener('load', finish, { once: true });
+            existing.addEventListener('error', fail, { once: true });
+            return;
+        }
+        const script = doc.createElement('script');
+        script.src = EOS_CONNECT_TELEGRAM_WEB_APP_SDK_URL;
+        script.async = true;
+        script.onload = finish;
+        script.onerror = fail;
+        doc.head.appendChild(script);
+    });
+    return telegramWebAppSdkLoadPromise;
+}
 export class EosConnectError extends Error {
     code;
     rawMessage;
@@ -22,12 +59,10 @@ const defaultWalletSetupEnv = {
     canStorePayKey: true
 };
 export const EOS_CONNECT_PRIVATE_KEY_STORAGE = 'tg_eos_wallet_pay_key_v1';
-export const EOS_CONNECT_DEFAULT_API_BASE_URL = 'https://eospasskey.aiexsat.com';
 export const EOS_CONNECT_NETWORKS = {
     testnet: {
         id: 'testnet',
         name: 'Jungle4 Testnet',
-        apiBaseUrl: 'https://eospasskey.aiexsat.com',
         chainId: '73e4385a2708e6d7048834fbc1079f2fabb17b3c125b146af438971e90716c4d',
         rpcUrls: [
             'https://jungle4.cryptolions.io:443',
@@ -46,7 +81,6 @@ export const EOS_CONNECT_NETWORKS = {
     mainnet: {
         id: 'mainnet',
         name: 'EOS Mainnet',
-        apiBaseUrl: 'https://eospasskey.aiexsat.com',
         chainId: 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906',
         rpcUrls: [
             'https://eos.eoseyes.com',
@@ -183,6 +217,21 @@ export function eosConnectTelegramPayStorageDiagnostics(app) {
 export function supportsEosConnectTelegramPayStorage(app) {
     return eosConnectTelegramPayStorageDiagnostics(app).every((item) => item.ok);
 }
+export async function checkEosConnectTelegramPayStorage(app, timeoutMs = 5000) {
+    let biometricInitialized = false;
+    try {
+        biometricInitialized = await initEosConnectTelegramBiometricManager(app, timeoutMs);
+    }
+    catch {
+        biometricInitialized = false;
+    }
+    const diagnostics = eosConnectTelegramPayStorageDiagnostics(app);
+    return {
+        supported: diagnostics.every((item) => item.ok),
+        biometricInitialized,
+        diagnostics
+    };
+}
 export async function initEosConnectTelegramBiometricManager(app, timeoutMs = 5000) {
     const biometric = app.BiometricManager;
     if (typeof biometric?.init !== 'function') {
@@ -316,13 +365,13 @@ export function eosConnectWalletSetupState(wallet, env = defaultWalletSetupEnv)
         reason: wallet.bindingError ?? null
     };
 }
-function openExternalUrl(url, options) {
+function openExternalUrl(url, options, telegramWebApp = options.telegramWebApp) {
     if (options.openExternal) {
         options.openExternal(url);
         return;
     }
-    if (!url.startsWith('tpdapp://') && options.telegramWebApp?.openLink) {
-        options.telegramWebApp.openLink(url);
+    if (!url.startsWith('tpdapp://') && telegramWebApp?.openLink) {
+        telegramWebApp.openLink(url);
         return;
     }
     globalThis.location?.assign(url);
@@ -1149,10 +1198,26 @@ function walletCapabilityToState(capability) {
         localPublicKey: capability.localPublicKey
     };
 }
+function notConnectedWalletCapability(reason = null) {
+    return {
+        status: 'not_connected',
+        hasWallet: false,
+        canUse: false,
+        needsLocalKey: false,
+        account: null,
+        balance: null,
+        bindId: null,
+        bindUrl: null,
+        expectedPublicKey: null,
+        localPublicKey: null,
+        reason,
+        wallet: null
+    };
+}
 export function createEosConnect(options) {
     const fetchImpl = options.fetch ?? fetch;
     const networkConfig = options.network ? EOS_CONNECT_NETWORKS[options.network] : null;
-    const apiBaseUrl = normalizeBaseUrl(options.apiBaseUrl ?? networkConfig?.apiBaseUrl ?? EOS_CONNECT_DEFAULT_API_BASE_URL);
+    const apiBaseUrl = normalizeBaseUrl(options.apiBaseUrl ?? '');
     const balanceAsset = options.balanceAsset ?? networkConfig?.balanceAsset;
     const rpcUrls = parseRpcUrls(options.rpcUrls ?? networkConfig?.rpcUrls);
     const listeners = new Set();
@@ -1162,8 +1227,14 @@ export function createEosConnect(options) {
         listeners.forEach((listener) => listener(state));
         return state;
     }
+    function telegramWebApp() {
+        return options.telegramWebApp === undefined ? getEosConnectTelegramWebApp() : options.telegramWebApp;
+    }
     function initData() {
-        return options.telegramWebApp?.initData ?? '';
+        return telegramWebApp()?.initData ?? '';
+    }
+    function botUsernameHeader() {
+        return options.botUsername ? { 'x-telegram-bot-username': options.botUsername } : {};
     }
     async function request(path, requestOptions) {
         let response;
@@ -1172,6 +1243,7 @@ export function createEosConnect(options) {
                 ...requestOptions,
                 headers: {
                     'content-type': 'application/json',
+                    ...botUsernameHeader(),
                     ...(requestOptions?.headers ?? {})
                 }
             });
@@ -1214,29 +1286,32 @@ export function createEosConnect(options) {
         async checkWallet() {
             if (!initData()) {
                 const capability = {
-                    status: 'unsupported',
-                    hasWallet: false,
-                    canUse: false,
-                    needsLocalKey: false,
-                    account: null,
-                    balance: null,
-                    bindId: null,
-                    bindUrl: null,
-                    expectedPublicKey: null,
-                    localPublicKey: null,
-                    reason: 'Telegram initData is missing',
-                    wallet: null
+                    ...notConnectedWalletCapability('Telegram initData is missing'),
+                    status: 'unsupported'
                 };
                 publish(walletCapabilityToState(capability));
                 return capability;
             }
-            const wallet = await request(`/api/tg-wallet/me${balanceQuery(balanceAsset)}`, {
-                headers: {
-                    'x-telegram-init-data': initData()
+            let wallet;
+            try {
+                wallet = await request(`/api/tg-wallet/me${balanceQuery(balanceAsset)}`, {
+                    headers: {
+                        'x-telegram-init-data': initData()
+                    }
+                });
+            }
+            catch (error) {
+                const normalized = normalizeEosConnectError(error);
+                if (normalized.code === 'SESSION_EXPIRED' &&
+                    normalized.rawMessage.toLowerCase().includes('telegram session not found')) {
+                    const capability = notConnectedWalletCapability();
+                    publish(walletCapabilityToState(capability));
+                    return capability;
                 }
-            });
+                throw normalized;
+            }
             const localPublicKey = wallet.quickPublicKey
-                ? await loadEosConnectStoredPublicKey(options.telegramWebApp)
+                ? await loadEosConnectStoredPublicKey(telegramWebApp())
                 : null;
             const capability = walletCapability(wallet, localPublicKey);
             publish(walletCapabilityToState(capability));
@@ -1266,8 +1341,8 @@ export function createEosConnect(options) {
                     initData: initData(),
                     botPublicKey: connectOptions.provider === 'telegram' ? connectOptions.publicKey : undefined,
                     tgpayPublicKey: connectOptions.provider === 'tokenpocket' ? connectOptions.publicKey : undefined,
-                    botUsername: options.botUsername || undefined,
-                    deviceLabel: options.deviceLabel || telegramDeviceLabel(options.telegramWebApp),
+                    botUsername: connectOptions.botUsername || options.botUsername || undefined,
+                    deviceLabel: options.deviceLabel || telegramDeviceLabel(telegramWebApp()),
                     assetLimits: connectOptions.assetLimits,
                     replaceWallet: connectOptions.provider === 'telegram' ? connectOptions.replaceWallet || undefined : undefined
                 })
@@ -1297,7 +1372,7 @@ export function createEosConnect(options) {
                 error: null
             });
             if (connectOptions.openLink !== false) {
-                openExternalUrl(connectOptions.provider === 'tokenpocket' ? tokenPocketDappUrl(bind.bindUrl) : bind.bindUrl, options);
+                openExternalUrl(connectOptions.provider === 'tokenpocket' ? tokenPocketDappUrl(bind.bindUrl) : bind.bindUrl, options, telegramWebApp());
             }
             return next;
         },
@@ -1306,6 +1381,7 @@ export function createEosConnect(options) {
             const next = await this.connect({
                 provider: 'telegram',
                 publicKey: paymentKey.publicKey,
+                botUsername: telegramOptions.botUsername,
                 assetLimits: telegramOptions.assetLimits,
                 replaceWallet: telegramOptions.replaceWallet,
                 openLink: false
@@ -1317,10 +1393,10 @@ export function createEosConnect(options) {
                 throw new Error('EOS Connect did not return a binding request');
             }
             if (!next.reused) {
-                await saveEosConnectPaymentKey(paymentKey.privateKey, options.telegramWebApp);
+                await saveEosConnectPaymentKey(paymentKey.privateKey, telegramWebApp());
             }
             if (telegramOptions.openLink !== false) {
-                openExternalUrl(next.bindUrl, options);
+                openExternalUrl(next.bindUrl, options, telegramWebApp());
             }
             return next;
         },
@@ -1335,9 +1411,9 @@ export function createEosConnect(options) {
             if (!next.bindUrl || !next.bindId) {
                 throw new Error('EOS Connect did not return a TokenPocket binding request');
             }
-            await saveEosConnectPaymentKey(paymentKey.privateKey, options.telegramWebApp);
+            await saveEosConnectPaymentKey(paymentKey.privateKey, telegramWebApp());
             if (tokenPocketOptions.openLink !== false) {
-                openExternalUrl(tokenPocketDappUrl(next.bindUrl), options);
+                openExternalUrl(tokenPocketDappUrl(next.bindUrl), options, telegramWebApp());
             }
             return next;
         },
@@ -1365,7 +1441,7 @@ export function createEosConnect(options) {
             }
             const signer = options.signTransaction ?? signEosConnectTransaction;
             const signedTransaction = await signer(built.transaction, {
-                telegramWebApp: options.telegramWebApp,
+                telegramWebApp: telegramWebApp(),
                 rpcUrls,
                 fetch: fetchImpl
             });

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@eos3/connect",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Framework-neutral browser SDK for EOS Passkey Connect in Telegram Mini Apps.",
   "type": "module",
   "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HuangLittleOrange/eos3app.git",
+    "directory": "packages/connect"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -26,8 +31,10 @@
     }
   },
   "scripts": {
+    "prebuild": "npm run build -w @eos3/shared",
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
+    "pretypecheck": "npm run build -w @eos3/shared",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {