@eos3/connect 0.1.12 → 0.2.0

package/README.md

@@ -24,6 +24,7 @@ It does not bundle Telegram's script into the main SDK bundle; call
 ```ts
 import {
   createEosConnect,
+  defineEosConnectElements,
   isEosConnectError,
   normalizeEosConnectError
 } from '@eos3/connect';
@@ -48,6 +49,8 @@ const eosConnect = createEosConnect({
   }
 });
 
+defineEosConnectElements({ client: eosConnect });
+
 eosConnect.subscribe((state) => {
   console.log('EOS wallet state:', state);
 });
@@ -56,6 +59,7 @@ await eosConnect.bootstrapTelegram();
 const quickPay = await eosConnect.checkQuickPay();
 
 if (!quickPay.enabled) {
+  // Requires <eos-connect-modal hidden></eos-connect-modal>.
   await eosConnect.enableQuickPay();
 }
 ```
@@ -95,10 +99,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` so users always see the
+quick payment setup sheet first:
 
 ```ts
 const quickPay = await eosConnect.checkQuickPay();
@@ -111,14 +115,12 @@ renderQuickPay({
 });
 
 if (!quickPay.enabled) {
-  const next = await eosConnect.enableQuickPay({
-    pollIntervalMs: 1500
-  });
+  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;
@@ -131,9 +133,9 @@ if (!quickPay.enabled) {
   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 or reaches another
-terminal state.
+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
 
@@ -285,11 +287,13 @@ 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.
+- `defineEosConnectElements(options)`: registers the built-in quick payment Web Components.
+- `installEosConnectStyles(document)`: injects the built-in quick payment UI stylesheet.
 
 ## Network Presets
 

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import type { PayLimitAssetConfig, PayLimitPayment, SignedTransferPayload } from '@eos3/shared';
+import type { PayLimitAssetConfig, PayLimitPayment, SignedTransferPayload } from './shared/index.js';
 import { type EosConnectTelegramWebApp } from './telegram-web-app.js';
 export { EosConnectError, isEosConnectError, normalizeEosConnectError, type EosConnectErrorCode } from './errors.js';
 export { EOS_CONNECT_TELEGRAM_WEB_APP_SDK_URL, getEosConnectTelegramWebApp, loadEosConnectTelegramWebAppSdk, type EosConnectTelegramWebApp } from './telegram-web-app.js';
+export * from './shared/index.js';
+export * from './ui.js';
 export type EosConnectProviderId = 'telegram' | 'tokenpocket' | 'anchor';
 export type EosConnectProviderState = 'available' | 'coming_soon' | 'disabled';
 export type EosConnectStatus = 'idle' | 'not_connected' | 'pending' | 'connected' | 'unsupported' | 'error';
@@ -139,7 +141,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

@@ -4,6 +4,8 @@ import { getEosConnectTelegramWebApp, loadEosConnectTelegramWebAppSdk } from './
 export { EosConnectError, isEosConnectError, normalizeEosConnectError } from './errors.js';
 import { normalizeEosConnectError } from './errors.js';
 export { EOS_CONNECT_TELEGRAM_WEB_APP_SDK_URL, getEosConnectTelegramWebApp, loadEosConnectTelegramWebAppSdk } from './telegram-web-app.js';
+export * from './shared/index.js';
+export * from './ui.js';
 const defaultWalletSetupEnv = {
     hasTelegramSession: true,
     canStorePayKey: true
@@ -1320,6 +1322,14 @@ function waitForNextWalletPoll(ms) {
         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);
@@ -1634,8 +1644,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/dist/shared/account.d.ts

@@ -0,0 +1,2 @@
+export declare function generateEosAccountName(): string;
+export declare function assertEosAccountName(accountName: string): void;

package/dist/shared/account.js

@@ -0,0 +1,18 @@
+const EOS_ACCOUNT_CHARS = 'abcdefghijklmnopqrstuvwxyz12345';
+export function generateEosAccountName() {
+    const bytes = new Uint8Array(11);
+    globalThis.crypto.getRandomValues(bytes);
+    let suffix = '';
+    for (const byte of bytes) {
+        suffix += EOS_ACCOUNT_CHARS[byte % EOS_ACCOUNT_CHARS.length];
+    }
+    return `u${suffix}`;
+}
+export function assertEosAccountName(accountName) {
+    if (!/^[a-z][a-z1-5.]{0,11}$/.test(accountName)) {
+        throw new Error('Invalid EOS account name');
+    }
+    if (accountName.startsWith('.') || /^[1-5]/.test(accountName)) {
+        throw new Error('EOS account name cannot start with a dot or number');
+    }
+}

package/dist/shared/index.d.ts

@@ -0,0 +1,3 @@
+export * from './account.js';
+export * from './transfer.js';
+export * from './types.js';

package/dist/shared/index.js

@@ -0,0 +1,3 @@
+export * from './account.js';
+export * from './transfer.js';
+export * from './types.js';

package/dist/shared/transfer.d.ts

@@ -0,0 +1,54 @@
+import type { OptionalAssetLimit, PayLimitPayment, TransferSummary } from './types.js';
+export declare function normalizeEosQuantity(amount: string, symbol?: string, precision?: number): string;
+export declare function normalizeOptionalAssetLimit(amount: string | null | undefined, symbol?: string, precision?: number): OptionalAssetLimit;
+export declare function hashTelegramBotId(botId: string): string;
+export declare function deriveBotPermissionName(botId: string, collisionNonce?: number): string;
+export declare function assertTransferSummaryBelongsToUser(summary: TransferSummary, eosAccount: string): void;
+export declare function assertTransferActionBelongsToUser(signedTransaction: {
+    transaction?: {
+        actions?: Array<{
+            account?: string;
+            name?: string;
+            authorization?: Array<{
+                actor?: string;
+                permission?: string;
+            }>;
+            data?: Record<string, unknown> & {
+                from?: string;
+            };
+        }>;
+    };
+}, eosAccount: string, options?: {
+    tokenContract?: string;
+    permission?: 'active' | 'tgpay';
+}): void;
+export declare function assertPayLimitActionBelongsToUser(signedTransaction: {
+    transaction?: {
+        actions?: Array<{
+            account?: string;
+            name?: string;
+            authorization?: Array<{
+                actor?: string;
+                permission?: string;
+            }>;
+            data?: Record<string, unknown> & {
+                from?: string;
+                to?: string;
+                token_contract?: string;
+                quantity?: string;
+                memo?: string;
+                bot_id_hash?: string;
+                permission?: string;
+                payments?: unknown;
+            };
+        }>;
+    };
+}, expected: {
+    payLimitContract: string;
+    eosAccount: string;
+    permission: string;
+    botIdHash: string;
+    payments: PayLimitPayment[];
+    sponsorAccount?: string;
+    sponsorPermission?: string;
+}): void;

package/dist/shared/transfer.js

@@ -0,0 +1,122 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+const EOS_NAME_CHARS = 'abcdefghijklmnopqrstuvwxyz12345';
+function normalizeQuantity(amount, symbol = 'EOS', precision = 4, options = {}) {
+    const trimmed = amount.trim();
+    if (!/^\d+(\.\d+)?$/.test(trimmed)) {
+        throw new Error('Invalid transfer amount');
+    }
+    const [wholePart, decimalPart = ''] = trimmed.split('.');
+    if (decimalPart.length > precision) {
+        throw new Error(`Amount exceeds ${precision} decimal precision`);
+    }
+    const whole = Number(wholePart);
+    const decimal = Number(decimalPart.padEnd(precision, '0') || '0');
+    if (!options.allowZero && whole === 0 && decimal === 0) {
+        throw new Error('Transfer amount must be positive');
+    }
+    return `${wholePart}.${decimalPart.padEnd(precision, '0')} ${symbol}`;
+}
+export function normalizeEosQuantity(amount, symbol = 'EOS', precision = 4) {
+    return normalizeQuantity(amount, symbol, precision);
+}
+export function normalizeOptionalAssetLimit(amount, symbol = 'EOS', precision = 4) {
+    if (amount === null || amount === undefined || amount.trim() === '') {
+        return {
+            hasLimit: false,
+            quantity: normalizeQuantity('0', symbol, precision, { allowZero: true })
+        };
+    }
+    return {
+        hasLimit: true,
+        quantity: normalizeQuantity(amount, symbol, precision, { allowZero: true })
+    };
+}
+export function hashTelegramBotId(botId) {
+    return bytesToHex(sha256(new TextEncoder().encode(botId)));
+}
+export function deriveBotPermissionName(botId, collisionNonce = 0) {
+    const seed = collisionNonce === 0 ? botId : `${botId}:${collisionNonce}`;
+    const hash = sha256(new TextEncoder().encode(seed));
+    let suffix = '';
+    for (let index = 0; suffix.length < 10; index += 1) {
+        suffix += EOS_NAME_CHARS[hash[index % hash.length] % EOS_NAME_CHARS.length];
+    }
+    return `tg${suffix}`;
+}
+export function assertTransferSummaryBelongsToUser(summary, eosAccount) {
+    if (summary.from !== eosAccount) {
+        throw new Error('Signed transaction does not belong to the current wallet');
+    }
+}
+export function assertTransferActionBelongsToUser(signedTransaction, eosAccount, options = {}) {
+    const actions = signedTransaction.transaction?.actions;
+    if (!Array.isArray(actions) || actions.length !== 1) {
+        throw new Error('Signed transaction must contain exactly one action');
+    }
+    const transferAction = actions[0];
+    const tokenContract = options.tokenContract ?? 'eosio.token';
+    const permission = options.permission ?? 'tgpay';
+    if (transferAction.account !== tokenContract || transferAction.name !== 'transfer') {
+        throw new Error('Signed transaction action must be an EOS token transfer');
+    }
+    if (transferAction?.data?.from !== eosAccount) {
+        throw new Error('Signed transaction action does not belong to the current wallet');
+    }
+    const hasWalletActor = transferAction.authorization?.some((auth) => auth.actor === eosAccount);
+    if (!hasWalletActor) {
+        throw new Error('Signed transaction authorization does not belong to the current wallet');
+    }
+    const hasWalletAuthorization = transferAction.authorization?.some((auth) => auth.actor === eosAccount && auth.permission === permission);
+    if (!hasWalletAuthorization) {
+        throw new Error(`Signed transaction authorization must use ${eosAccount}@${permission}`);
+    }
+}
+export function assertPayLimitActionBelongsToUser(signedTransaction, expected) {
+    const actions = signedTransaction.transaction?.actions;
+    if (!Array.isArray(actions) || actions.length !== 2) {
+        throw new Error('Signed transaction must contain exactly sponsor noop and paylimit actions');
+    }
+    const sponsorAction = actions[0];
+    const expectedSponsorAccount = expected.sponsorAccount ?? expected.payLimitContract;
+    const expectedSponsorPermission = expected.sponsorPermission ?? 'paycpu';
+    if (sponsorAction.account !== expected.payLimitContract || sponsorAction.name !== 'noop') {
+        throw new Error('Signed transaction first action must be the paylimit sponsor noop');
+    }
+    const hasSponsorAuthorization = sponsorAction.authorization?.some((auth) => auth.actor === expectedSponsorAccount &&
+        auth.permission === expectedSponsorPermission);
+    if (!hasSponsorAuthorization) {
+        throw new Error(`Signed transaction sponsor action must use ${expectedSponsorAccount}@${expectedSponsorPermission}`);
+    }
+    const action = actions[1];
+    if (action.account !== expected.payLimitContract || action.name !== 'pay') {
+        throw new Error('Signed transaction second action must be a paylimit payment');
+    }
+    const data = action.data;
+    if (!data || data.from !== expected.eosAccount) {
+        throw new Error('Signed paylimit action does not belong to the current wallet');
+    }
+    if (data.bot_id_hash !== expected.botIdHash ||
+        data.permission !== expected.permission) {
+        throw new Error('Signed paylimit action does not match the current Telegram bot permission');
+    }
+    if (!Array.isArray(data.payments) || data.payments.length !== expected.payments.length) {
+        throw new Error('Signed paylimit action payments do not match the requested payment count');
+    }
+    const actualPayments = data.payments;
+    expected.payments.forEach((payment, index) => {
+        const actual = actualPayments[index];
+        if (!actual ||
+            actual.to !== payment.to ||
+            actual.token_contract !== payment.tokenContract ||
+            actual.quantity !== payment.quantity ||
+            actual.memo !== payment.memo) {
+            throw new Error(`Signed paylimit action payment ${index + 1} does not match the request`);
+        }
+    });
+    const hasWalletAuthorization = action.authorization?.some((auth) => auth.actor === expected.eosAccount &&
+        auth.permission === expected.permission);
+    if (!hasWalletAuthorization) {
+        throw new Error(`Signed transaction authorization must use ${expected.eosAccount}@${expected.permission}`);
+    }
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,76 @@
+export type WalletDeviceStatus = 'pending' | 'active' | 'failed' | 'expired' | 'superseded';
+export type BindIntentStatus = 'pending' | 'passkey_created' | 'account_created_waiting_tgpay' | 'account_created' | 'expired' | 'superseded' | 'failed';
+export type TransferStatus = 'pending' | 'pushed' | 'failed';
+export interface PublicUser {
+    id: string;
+    telegramUserId: string | null;
+    telegramUsername: string | null;
+    googleSub?: string | null;
+    email?: string | null;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+    eosAccount: string | null;
+}
+export interface TransferSummary {
+    from: string;
+    to: string;
+    quantity: string;
+    memo: string;
+    permission?: string;
+}
+export interface PayLimitAssetConfig {
+    tokenContract: string;
+    symbol: string;
+    precision: number;
+    perTxLimit?: string | null;
+    dailyLimit?: string | null;
+    totalBudget?: string | null;
+}
+export interface OptionalAssetLimit {
+    hasLimit: boolean;
+    quantity: string;
+}
+export interface PayLimitSummary {
+    from: string;
+    to: string;
+    tokenContract: string;
+    quantity: string;
+    memo: string;
+    botIdHash: string;
+    permission: string;
+}
+export interface PayLimitPayment {
+    to: string;
+    tokenContract: string;
+    quantity: string;
+    memo: string;
+}
+export interface PayLimitBatchSummary {
+    from: string;
+    payments: PayLimitPayment[];
+    botIdHash: string;
+    permission: string;
+}
+export interface BuiltTransfer {
+    transaction: Record<string, unknown>;
+    chainId: string;
+    summary: TransferSummary;
+}
+export interface BuiltPayLimitTransfer {
+    intentId: string;
+    transaction: Record<string, unknown>;
+    chainId: string;
+    summary: PayLimitSummary;
+    payments?: PayLimitPayment[];
+}
+export interface BuiltPayLimitBatchTransfer {
+    intentId: string;
+    transaction: Record<string, unknown>;
+    chainId: string;
+    summary: PayLimitBatchSummary;
+}
+export interface SignedTransferPayload {
+    signatures: string[];
+    serializedTransaction: number[] | string;
+    transaction: Record<string, unknown>;
+}

package/dist/shared/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui.d.ts

@@ -0,0 +1,50 @@
+import type { EosConnectClient, EosConnectNetwork, EosConnectProviderId, EosConnectTelegramOptions, EosConnectTelegramWebApp, EosConnectWalletView } from './index.js';
+export type EosConnectUiTelegramOptions = EosConnectTelegramOptions & {
+    botUsername?: string;
+    openExternal?: (url: string) => void;
+};
+export interface EosConnectUiMessages {
+    enableQuickPayment?: string;
+    quickPaymentEnabled?: string;
+    quickPaymentChecking?: string;
+    quickPaymentCheckingDescription?: string;
+    quickPaymentSuccess?: string;
+    quickPaymentSuccessDescription?: string;
+    quickPaymentSetupDescription?: string;
+    /** @deprecated Use quickPaymentSetupDescription instead. */
+    localKeyMissingDescription?: string;
+    closeEosConnect?: string;
+}
+export interface EosConnectElementsOptions {
+    client?: EosConnectClient;
+    network?: EosConnectNetwork;
+    apiBaseUrl?: string;
+    botUsername?: string;
+    locale?: string;
+    messages?: EosConnectUiMessages;
+    assetLimits?: EosConnectTelegramOptions['assetLimits'];
+    replaceWallet?: boolean;
+    telegramOptions?: EosConnectUiTelegramOptions;
+    openExternal?: (url: string) => void;
+    telegramWebApp?: EosConnectTelegramWebApp | null;
+    injectStyles?: boolean;
+    customElements?: CustomElementRegistry;
+}
+export interface EosConnectUiErrorDetail {
+    error: unknown;
+    provider?: EosConnectProviderId;
+}
+type DocumentLike = Pick<Document, 'createElement' | 'head' | 'querySelector'>;
+export declare function installEosConnectStyles(documentRef?: DocumentLike | undefined): void;
+export type EosConnectUiFlowState = 'idle' | 'checking' | 'success';
+export type EosConnectUiRenderOptions = {
+    locale?: string;
+    messages?: EosConnectUiMessages;
+    telegramWebApp?: EosConnectTelegramWebApp | null;
+    flowState?: EosConnectUiFlowState;
+};
+export declare function renderEosConnectButton(client: EosConnectClient, options?: EosConnectUiRenderOptions): string;
+export declare function renderEosConnectSheet(client: EosConnectClient, options?: EosConnectUiRenderOptions): string;
+export declare function connectEosProvider(client: EosConnectClient, _provider?: EosConnectProviderId, options?: EosConnectUiTelegramOptions): Promise<EosConnectWalletView | void>;
+export declare function defineEosConnectElements({ client, network, apiBaseUrl, botUsername, locale, messages, assetLimits, replaceWallet, telegramOptions, openExternal, telegramWebApp, injectStyles, customElements: registry }: EosConnectElementsOptions): void;
+export {};