@eos3/connect 0.1.0

package/README.md

@@ -0,0 +1,246 @@
+# @eos3/connect
+
+Framework-neutral browser SDK for EOS Passkey Connect.
+
+Use this package inside a Telegram Mini App to create or restore an EOS wallet,
+store the Bot-scoped local payment key in Telegram SecureStorage, unlock it with
+Telegram biometrics, sign paylimit transfers locally, and push them through the
+EOS Passkey API.
+
+## Install
+
+```bash
+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.
+
+## Minimal Setup
+
+```ts
+import {
+  createEosConnect,
+  isEosConnectError,
+  normalizeEosConnectError
+} from '@eos3/connect';
+
+const telegramWebApp = window.Telegram?.WebApp;
+
+const eosConnect = createEosConnect({
+  network: 'testnet',
+  telegramWebApp
+});
+
+eosConnect.subscribe((state) => {
+  console.log('EOS wallet state:', 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.
+
+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.
+
+## Connect a Telegram Wallet
+
+```ts
+const state = await eosConnect.connectTelegram({
+  assetLimits: [
+    {
+      tokenContract: 'core.vaulta',
+      symbol: 'A',
+      precision: 4,
+      perTxLimit: '1',
+      dailyLimit: '10',
+      totalBudget: '100'
+    }
+  ]
+});
+
+if (state.status === 'pending' && state.bindUrl) {
+  // The SDK opens bindUrl by default. Keep this branch for custom UI.
+  console.log('Continue passkey binding:', state.bindUrl);
+}
+```
+
+`connectTelegram()` generates a local EOS K1 payment key, encrypts the private
+key with AES-GCM, stores the encrypted envelope in Telegram SecureStorage, saves
+the unlock key as the Telegram biometric token, and starts the external passkey
+binding flow.
+
+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.
+
+## Check Readiness
+
+```ts
+const capability = await eosConnect.checkWallet();
+
+if (capability.status === 'ready') {
+  console.log('Ready to pay from', capability.account);
+}
+
+if (capability.status === 'needs_local_key') {
+  // The server wallet exists, but this Telegram device does not have the
+  // matching encrypted local payment key. Prompt the user to rebind.
+  await eosConnect.connectTelegram({ replaceWallet: true });
+}
+
+if (capability.status === 'pending' && capability.bindUrl) {
+  telegramWebApp?.openLink?.(capability.bindUrl);
+}
+```
+
+Common capability statuses:
+
+- `unsupported`: missing Telegram initData or secure Telegram APIs.
+- `not_connected`: no wallet exists yet.
+- `pending`: account creation or tgpay binding is not finished.
+- `needs_local_key`: wallet exists, but this device cannot sign quick payments.
+- `ready`: wallet and local payment key match.
+
+## Pay
+
+```ts
+try {
+  const result = await eosConnect.pay({
+    to: 'merchant1111',
+    amount: '1.0000',
+    memo: 'order-123',
+    tokenContract: 'core.vaulta',
+    symbol: 'A'
+  });
+
+  console.log('Pushed transaction:', result.txid);
+} catch (error) {
+  const normalized = normalizeEosConnectError(error);
+  console.error(normalized.code, normalized.message, normalized.retryable);
+}
+```
+
+`pay()` uses these API endpoints:
+
+- `POST /api/tg-wallet/transfer/build`
+- `POST /api/tg-wallet/transfer/push`
+
+The default confirmation sheet can be disabled or replaced:
+
+```ts
+const eosConnect = createEosConnect({
+  network: 'testnet',
+  telegramWebApp,
+  confirmPayment: async (details) => {
+    return window.confirm(`Pay ${details.quantity} to ${details.to}?`);
+  }
+});
+```
+
+For production business actions, prefer project-specific build and push
+endpoints that validate contract, action, authorization, amount, memo, and any
+business parameters before broadcasting.
+
+## Custom Transaction Signing
+
+Use `signEosConnectTransaction()` when your own backend builds a validated
+transaction and expects a signed payload:
+
+```ts
+import { signEosConnectTransaction } from '@eos3/connect';
+
+const signedTransaction = await signEosConnectTransaction(transaction, {
+  telegramWebApp,
+  rpcUrls: ['https://jungle4.cryptolions.io:443']
+});
+
+await fetch('https://wallet.example.com/api/market/push', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({
+    initData: telegramWebApp?.initData,
+    signedTransaction
+  })
+});
+```
+
+## API Summary
+
+- `createEosConnect(options)`: creates the SDK client.
+- `client.getProviders()`: returns wallet provider metadata.
+- `client.getSnapshot()`: returns the current state.
+- `client.subscribe(listener)`: subscribes to state changes.
+- `client.restore()`: loads wallet state from the API.
+- `client.checkWallet()`: checks server wallet plus local key readiness.
+- `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.
+- `client.disconnectLocal()`: clears the local in-memory SDK state.
+
+## Network Presets
+
+```ts
+import { EOS_CONNECT_NETWORKS } from '@eos3/connect';
+
+console.log(EOS_CONNECT_NETWORKS.testnet.rpcUrls);
+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
+  `core.vaulta:A:4`.
+
+Explicit options always win:
+
+```ts
+createEosConnect({
+  network: 'testnet',
+  apiBaseUrl: 'https://my-testnet-wallet.example.com',
+  rpcUrls: ['https://my-jungle-rpc.example.com'],
+  telegramWebApp
+});
+```
+
+## Error Handling
+
+Use `normalizeEosConnectError(error)` at UI boundaries. It maps raw API, EOS RPC,
+Telegram biometric, and contract errors into stable codes:
+
+- `DAILY_LIMIT_EXCEEDED`
+- `PER_TX_LIMIT_EXCEEDED`
+- `TOTAL_BUDGET_EXCEEDED`
+- `INSUFFICIENT_BALANCE`
+- `RAM_INSUFFICIENT`
+- `PAYMENT_PERMISSION_MISSING`
+- `SIGNATURE_REJECTED`
+- `SESSION_EXPIRED`
+- `NETWORK_ERROR`
+- `UNKNOWN_CHAIN_ERROR`
+
+```ts
+catch (error) {
+  const normalized = normalizeEosConnectError(error);
+  if (normalized.retryable) {
+    // Show a retry action.
+  }
+}
+```
+
+## Security Notes
+
+- Never send the local payment private key or biometric unlock token to a server.
+- Never store the private key in `localStorage`, IndexedDB, cookies, or plain
+  Telegram CloudStorage.
+- Treat missing Telegram SecureStorage or BiometricManager as unsupported.
+- Keep `TELEGRAM_BOT_TOKEN`, account creator keys, resource sponsor keys, and
+  contract deployment keys on the backend only.

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+import type { PayLimitAssetConfig, PayLimitPayment, SignedTransferPayload } from '@eos3/shared';
+export type EosConnectProviderId = 'telegram' | 'tokenpocket' | 'anchor';
+export type EosConnectProviderState = 'available' | 'coming_soon' | 'disabled';
+export type EosConnectStatus = 'idle' | 'not_connected' | 'pending' | 'connected' | 'unsupported' | 'error';
+export type EosConnectNetwork = 'testnet' | 'mainnet';
+export type EosConnectWalletCapabilityStatus = 'unsupported' | 'not_connected' | 'pending' | 'ready' | 'needs_local_key';
+export type EosConnectWalletSetupStatus = 'missing_telegram_session' | 'secure_storage_unavailable' | 'pending_tgpay' | 'pay_binding_invalid' | 'ready' | 'not_connected';
+export type EosConnectWalletSetupAction = 'none' | 'create' | 'continue' | 'rebind' | 'transfer';
+export interface EosConnectProvider {
+    id: EosConnectProviderId;
+    name: string;
+    state: EosConnectProviderState;
+    description: string;
+}
+export interface EosConnectTelegramWebApp {
+    initData?: string;
+    platform?: string;
+    version?: string;
+    openLink?(url: string): void;
+    SecureStorage?: {
+        setItem(key: string, value: string, callback?: (error: string | null, isStored?: boolean) => void): void;
+        getItem(key: string, callback: (error: string | null, value?: string | null) => void): void;
+        removeItem?(key: string, callback?: (error: string | null, isRemoved?: boolean) => void): void;
+    };
+    BiometricManager?: {
+        isInited?: boolean;
+        isBiometricAvailable?: boolean;
+        isAccessRequested?: boolean;
+        isAccessGranted?: boolean;
+        isBiometricTokenSaved?: boolean;
+        init(callback?: () => void): void;
+        requestAccess?(params: {
+            reason?: string;
+        }, callback?: (isGranted: boolean) => void): void;
+        authenticate(params: {
+            reason?: string;
+        }, callback: (isAuthenticated: boolean, biometricToken?: string) => void): void;
+        updateBiometricToken(token: string, callback?: (isUpdated: boolean) => void): void;
+        openSettings?(): void;
+    };
+}
+export interface EosConnectState {
+    status: EosConnectStatus;
+    provider: EosConnectProviderId | null;
+    account: string | null;
+    balance: string | null;
+    bindId: string | null;
+    bindUrl: string | null;
+    canUse?: boolean;
+    needsLocalKey?: boolean;
+    expectedPublicKey?: string | null;
+    localPublicKey?: string | null;
+    reused?: boolean;
+    hasWallet?: boolean;
+    error: string | null;
+}
+export interface EosConnectWalletCapability {
+    status: EosConnectWalletCapabilityStatus;
+    hasWallet: boolean;
+    canUse: boolean;
+    needsLocalKey: boolean;
+    account: string | null;
+    balance: string | null;
+    bindId: string | null;
+    bindUrl: string | null;
+    expectedPublicKey: string | null;
+    localPublicKey: string | null;
+    reason: string | null;
+    wallet: EosConnectWalletInfo | null;
+}
+export interface EosConnectWalletSetupEnv {
+    hasTelegramSession?: boolean;
+    canStorePayKey?: boolean;
+}
+export interface EosConnectWalletSetupState {
+    status: EosConnectWalletSetupStatus;
+    action: EosConnectWalletSetupAction;
+    account: string | null;
+    hasWallet: boolean;
+    bindId: string | null;
+    bindUrl: string | null;
+    isRecoverable: boolean;
+    showAction: boolean;
+    reason: string | null;
+}
+export interface EosConnectNetworkConfig {
+    id: EosConnectNetwork;
+    name: string;
+    apiBaseUrl: string;
+    chainId: string;
+    rpcUrls: readonly string[];
+    balanceAsset: EosConnectBalanceAsset;
+}
+export interface EosConnectOptions {
+    network?: EosConnectNetwork;
+    apiBaseUrl?: string;
+    botUsername?: string;
+    deviceLabel?: string;
+    balanceAsset?: EosConnectBalanceAsset;
+    rpcUrls?: string | string[];
+    signTransaction?: EosConnectTransactionSigner;
+    confirmPayment?: EosConnectPaymentConfirmer | false;
+    telegramWebApp?: EosConnectTelegramWebApp | null;
+    openExternal?: (url: string) => void;
+    fetch?: typeof fetch;
+}
+export interface EosConnectConnectOptions {
+    provider: EosConnectProviderId;
+    publicKey?: string;
+    assetLimits?: PayLimitAssetConfig[];
+    replaceWallet?: boolean;
+    openLink?: boolean;
+}
+export interface EosConnectTelegramOptions {
+    assetLimits?: PayLimitAssetConfig[];
+    replaceWallet?: boolean;
+    openLink?: boolean;
+}
+export interface EosConnectClient {
+    getProviders(): EosConnectProvider[];
+    getSnapshot(): EosConnectState;
+    subscribe(listener: (state: EosConnectState) => void): () => void;
+    restore(): Promise<EosConnectState>;
+    checkWallet(): Promise<EosConnectWalletCapability>;
+    connect(options: EosConnectConnectOptions): Promise<EosConnectState>;
+    connectTelegram(options?: EosConnectTelegramOptions): Promise<EosConnectState>;
+    connectTokenPocket(options?: EosConnectTelegramOptions): Promise<EosConnectState>;
+    pay(options: EosConnectPayOptions): Promise<EosConnectPayResult>;
+    disconnectLocal(): EosConnectState;
+}
+export interface EosConnectBalanceAsset {
+    tokenContract: string;
+    symbol: string;
+    precision?: number;
+}
+export interface EosConnectTelegramDeviceDiagnostic {
+    label: string;
+    ok: boolean;
+    detail: string;
+}
+export interface EosConnectTelegramBiometricSettingsResult {
+    opened: boolean;
+    message: string;
+}
+export interface EosConnectPayOptions {
+    to: string;
+    amount: string;
+    memo?: string;
+    tokenContract?: string;
+    symbol?: string;
+}
+export interface EosConnectPayResult {
+    ok: true;
+    txid: string;
+}
+export type EosConnectErrorCode = 'DAILY_LIMIT_EXCEEDED' | 'PER_TX_LIMIT_EXCEEDED' | 'TOTAL_BUDGET_EXCEEDED' | 'INSUFFICIENT_BALANCE' | 'RAM_INSUFFICIENT' | 'PAYMENT_PERMISSION_MISSING' | 'SIGNATURE_REJECTED' | 'SESSION_EXPIRED' | 'NETWORK_ERROR' | 'UNKNOWN_CHAIN_ERROR';
+export declare class EosConnectError extends Error {
+    readonly code: EosConnectErrorCode;
+    readonly rawMessage: string;
+    readonly retryable: boolean;
+    constructor(code: EosConnectErrorCode, message: string, options?: {
+        rawMessage?: string;
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+export declare function isEosConnectError(error: unknown): error is EosConnectError;
+export interface EosConnectPaymentDetails {
+    intentId: string;
+    chainId: string;
+    from: string;
+    to: string;
+    tokenContract: string;
+    quantity: string;
+    memo: string;
+    payments: PayLimitPayment[];
+}
+export type EosConnectSignedTransaction = SignedTransferPayload;
+export type EosConnectPaymentConfirmer = (details: EosConnectPaymentDetails) => boolean | Promise<boolean>;
+export type EosConnectTransactionSigner = (transaction: Record<string, unknown>, context: {
+    telegramWebApp?: EosConnectTelegramWebApp | null;
+    rpcUrls: string[];
+    fetch: typeof fetch;
+}) => Promise<EosConnectSignedTransaction>;
+export interface EosConnectWalletInfo {
+    eosAccount: string | null;
+    balance: string;
+    hasWallet: boolean;
+    status?: string;
+    pendingAccount?: string | null;
+    bindId?: string | null;
+    bindUrl?: string | null;
+    bindingError?: string | null;
+    quickPublicKey?: string | null;
+    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 initEosConnectTelegramBiometricManager(app: EosConnectTelegramWebApp, timeoutMs?: number): Promise<boolean>;
+export declare function openEosConnectTelegramBiometricSettings(app: EosConnectTelegramWebApp): Promise<EosConnectTelegramBiometricSettingsResult>;
+export declare function eosConnectWalletSetupState(wallet: EosConnectWalletInfo, env?: EosConnectWalletSetupEnv): EosConnectWalletSetupState;
+export declare function normalizeEosConnectError(error: unknown): EosConnectError;
+export declare function tokenPocketDappUrl(url: string): string;
+export declare function generateEosConnectPaymentKey(): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+export declare function publicKeyFromEosPrivateKey(privateKey: string): Promise<string>;
+export declare function saveEosConnectPaymentKey(privateKey: string, app?: EosConnectTelegramWebApp | null): Promise<void>;
+export declare function loadEosConnectStoredPublicKey(app?: EosConnectTelegramWebApp | null): Promise<string | null>;
+export declare function loadEosConnectPaymentSigningKey(app?: EosConnectTelegramWebApp | null): Promise<{
+    privateKey: string;
+    publicKey: string;
+    storedPublicKey: string | null;
+}>;
+export declare function removeEosConnectPaymentKey(app?: EosConnectTelegramWebApp | null): Promise<void>;
+export declare function signEosConnectTransaction(transaction: Record<string, unknown>, context: {
+    telegramWebApp?: EosConnectTelegramWebApp | null;
+    rpcUrls: string[];
+    fetch?: typeof fetch;
+}): Promise<EosConnectSignedTransaction>;
+export declare function createEosConnect(options: EosConnectOptions): EosConnectClient;